davinci-resolve-mcp 2.71.1 → 2.72.1

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 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.72.1
+
+Documentation only. The API coverage page stated its method counts in four
+places and they disagreed; the cause turned out to be structural rather than
+clerical.
+
+### The Resolve 21 surface was never counted
+
+None of the Resolve 21 methods appeared in the Complete API Reference tables —
+the tables the `API Methods Covered` denominator counts — although the server
+has wrapped, released and live-tested them since v2.28.1. So `337/337 (100%)`
+described a surface that excluded nine methods across four classes, and the
+`336 → 337` bump for `ResetIntellisearchAnalysis` added one to a count whose
+table did not list it.
+
+Thirteen rows added, one per method per object class, since a wrapper on
+`Folder` and one on `MediaPoolItem` can fail independently. Signatures taken
+from the bundled 21.0.2 scripting reference. `TranscribeAudio` was already
+listed — its Resolve 21 change is the optional `useSpeakerDetection` argument,
+accepted but producing identical transcripts either way — so those rows are
+annotated rather than duplicated.
+
+Every summary figure is now derived from the tables: **349 covered, 338 live
+tested, 11 untested**.
+
+### The counting convention is now written down
+
+Two of the three disagreements came from it being implicit:
+
+- A method that could not be executed is **not** counted as a pass. The old
+  "Resolve 21 delta 8/9" counted Extras-blocked methods as passes, contradicting
+  the prose directly above it and overstating coverage exactly where the risk is
+  highest.
+- The phase table counts **methods, not assertions**, which is why its Total
+  equals Methods Live Tested. That ambiguity is what made two figures look
+  independently wrong.
+
+`tests/test_api_coverage_arithmetic.py` derives all four figures from the
+reference tables and fails if any disagrees, so the tables stay the single
+source. It was checked against both drift shapes: a hand-edited summary figure,
+and a row removed from a table.
+
+## What's New in v2.72.0
+
+Resolve 21's AI methods report a missing Extras pack as an error *string*, not
+the documented bool — and a non-empty string is truthy. Live-validated against
+Studio 21.0.2.4 by @AghisSs in #107.
+
+### The trap
+
+The methods do not agree on how they refuse. With only AI Motion Deblur
+installed:
+
+| Method | Return when the pack is absent |
+|---|---|
+| `AnalyzeForSlate` | `False` |
+| `AnalyzeForIntellisearch` | `"Required package 'AI Intellisearch - Faster' is not installed."` |
+| `GenerateSpeech` | `"Required Package, 'AI Speech Generator' is not Installed."` |
+
+So `bool(result)` reported **success for analysis that never ran** across eight
+call sites, and `generate_speech` let the string past its guard into
+`.GetName()`, raising `AttributeError: 'str' object has no attribute 'GetName'`.
+
+`_ai_result` / `_ai_result_payload` now treat any string as a failure and
+surface its text as the error. That message is the only machine-readable signal
+that a pack is missing, since nothing in the scripting API enumerates installed
+Extras.
+
+`remove_motion_blur` is routed through the same helper. It needs the AI Motion
+Deblur Extra like its siblings and reproduced *both* failures — the
+`AttributeError` on the clip path, and a silent `success: true` with
+`created: []` in the confirm-gated folder path that renders new media. Both were
+live-tested with the Extra installed, so the absent-pack return was never
+observable.
+
+### Also
+
+- `project_settings("reset_intellisearch_analysis")` — documented in the 21.0.2
+  scripting README and present in `dir(project)`, but absent from the copy the
+  repo bundled, so it was never wrapped.
+- A live validation harness for the Resolve 21 delta, source-safe: synthetic
+  media in a temp dir, disposable project, teardown that restores the
+  originally-open project.
+- `api_truth` entries for the string-return bug, the undiscoverable Extras gap,
+  and `AnalyzeForSlate`'s documented `resolve.MARKER_*` constants, which do not
+  exist on the handle at all.
+- The `hasattr` attribute-fabrication entry is scoped as **unresolved**. The
+  21.0.2.4 control probe used an invented name, while the 21.0.0 evidence it
+  overturns used real method names borrowed from other object types — so it does
+  not refute the original record. `_has_method` is what every `_requires_method`
+  version gate is built on, and a gate that silently passes is the failure this
+  ledger exists to prevent.
+
 ## What's New in v2.71.1
 
 `Timeline.DeleteClips` can lie about whether it worked. #111 recorded four

package/README.md

@@ -1,11 +1,11 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.71.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.72.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)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
-[![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
+[![Tested](https://img.shields.io/badge/Live%20Tested-96.8%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -252,10 +252,10 @@ The default server is a local stdio process launched by your MCP client; it does
 | MCP Tools | **34** compound / **341** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
-| API Methods Covered | **336/336** (100%) |
-| Methods Live Tested | **331/336** (98.5%) |
-| Live Test Pass Rate | **331/331** (100%) |
-| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio |
+| API Methods Covered | **349/349** (100%) |
+| Methods Live Tested | **338/349** (96.8%) |
+| Live Test Pass Rate | **338/338** (100%) |
+| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio |
 
 For method-by-method status, see [API Coverage and Test Results](docs/reference/api-coverage.md). For current workflow support, see [Kernel Action Coverage](docs/kernels/README.md).
 
@@ -289,7 +289,7 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
   preference has no effect — use the [in-app bridge](#free-edition-in-app-bridge)
   instead.
 
-Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+.
+Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+. They are live-tested on Studio 21.0.2.4 — see the [Resolve 21 delta](docs/reference/api-coverage.md#resolve-21-delta-detail). Note that `AnalyzeForIntellisearch`, `AnalyzeForSlate` and `GenerateSpeech` each require a separately-downloaded AI Extras pack, and Resolve reports a missing pack inconsistently (some return `False`, others an error string), so these actions report `success: false` with the Resolve-supplied reason rather than guessing.
 
 ## Development
 

package/docs/contributing.md

@@ -67,7 +67,8 @@ davinci-resolve-mcp/
 │   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 341 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
-├── tests/                       # 5-phase live API test suite + Resolve 20 delta (331/331 pass)
+├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):
+│                                # 5-phase live API suite + Resolve 20/21 deltas
 ├── docs/
 │   ├── README.md                 # Documentation index
 │   ├── SKILL.md                  # AI assistant operating reference

package/docs/reference/api-coverage.md

@@ -6,20 +6,20 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **33** compound (default) / **341** granular |
+| MCP Tools | **34** compound (default) / **341** granular |
 | Kernel Actions | **136** guarded MCP workflow actions across 9 compound tools |
-| API Methods Covered | **336/336** (100%) |
-| Methods Live Tested | **331/336** (98.5%) |
-| Live Test Pass Rate | **331/331** (100%) |
+| API Methods Covered | **349/349** (100%) |
+| Methods Live Tested | **338/349** (96.8%) |
+| Live Test Pass Rate | **338/338** (100%) |
 | API Object Classes | 13 |
-| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio |
-| Compatibility Note | Resolve 19.1.3 remains the compatibility baseline; Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2; Resolve 21 beta APIs are intentionally deferred until stable |
+| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio |
+| Compatibility Note | Resolve 19.1.3 remains the compatibility baseline; Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2; Resolve 21.0 additions are version-guarded and live-tested on 21.0.2 (see the Resolve 21 delta row below — five wrappers need AI Extras packs and stay untested without one, and one is deliberately not executed) |
 
 ## API Coverage
 
 Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
 
-The 33rd compound tool is `timeline_versioning` (C6) — an MCP-level workflow
+The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the
 version-on-mutate hook that auto-archives the working timeline before any
 destructive op, plus rollback and brain-edit history. See [SKILL.md](../SKILL.md)
@@ -81,7 +81,24 @@ guard, so it never goes stale.
 
 ## Test Results
 
-Baseline testing was performed against **DaVinci Resolve 19.1.3 Studio** on macOS with live API calls (no mocks). Resolve 20 additions were revalidated live against **DaVinci Resolve 20.3.2 Studio**.
+Baseline testing was performed against **DaVinci Resolve 19.1.3 Studio** on macOS with live API calls (no mocks). Resolve 20 additions were revalidated live against **DaVinci Resolve 20.3.2 Studio**, Resolve 21 additions against **Studio 21.0.2.4**.
+
+**Counting convention.** Every figure on this page is derived from the rows of
+the [Complete API Reference](#complete-api-reference) tables — that table is the
+source, these summaries are downstream of it:
+
+- **API Methods Covered** = the number of rows. One row per method per object
+  class, so `PerformAudioClassification` on both `Folder` and `MediaPoolItem`
+  counts twice, because they are two wrappers that can fail independently.
+- **Methods Live Tested** = rows marked ✅ or ⚠️ — the call was made against a
+  live Resolve and the result observed.
+- **Untested** = rows marked ☁️ or 🔬. A method that could not be executed is
+  never counted as a pass: a missing Extras pack tells you nothing about the
+  wrapper, so counting it as tested would overstate coverage in exactly the
+  place the risk is highest.
+- **The phase table below counts methods, not test cases**, which is why its
+  Total equals Methods Live Tested rather than the number of assertions run.
+
 
 | Phase | Tests | Pass Rate | Scope |
 |-------|-------|-----------|-------|
@@ -91,9 +108,32 @@ Baseline testing was performed against **DaVinci Resolve 19.1.3 Studio** on macO
 | Phase 4 | 10/10 | 100% | AI/ML methods, Fusion clips, stereo, gallery stills |
 | Phase 5 | 6/6 | 100% | Scene cuts, subtitles from audio, graph node cache/tools/enable |
 | Resolve 20 delta | 12/12 | 100% | Resolve 20.0-20.2.2 scripting additions live-tested on 20.3.2 |
-| **Total** | **331/331** | **100%** | **98.5% of current API methods tested live** |
+| Resolve 21 delta | 7/7 | 100% | Resolve 21.0 additions that could be executed, live-tested on Studio 21.0.2.4 (`tests/live_resolve21_validation.py`). The other 6 need an AI Extras pack or are unsafe to run — counted as untested, not as passes |
+| **Total** | **338/338** | **100%** | **96.8% of the 349 covered methods tested live** |
+
+#### Resolve 21 delta detail
+
+Run on Studio 21.0.2.4, macOS/Apple Silicon, with **only the AI Motion Deblur
+Extra installed**. Three of these methods require an Extras pack that was
+absent, so their result says nothing about the wrapper — that is why they are
+marked 🔬 rather than ⚠️.
+
+| Method | Result | Evidence |
+|--------|--------|----------|
+| `MediaPoolItem/Folder.PerformAudioClassification` | ✅ | Returned True; `Category` clip property went `""` → `Dialogue` |
+| `MediaPoolItem/Folder.ClearAudioClassification` | ✅ | Returned True; `Category` reset to `Uncategorized` (not `""`) |
+| `MediaPoolItem/Folder.TranscribeAudio(useSpeakerDetection)` | ⚠️ | Parameter accepted; `True` and `False` produced identical transcripts on a two-voice clip |
+| `MediaPoolItem/Folder.RemoveMotionBlur` | ✅ | Returned a MediaPoolItem; source media path unchanged |
+| `Project.ResetIntellisearchAnalysis` | ✅ | Returned True — new in the 21.0.2 scripting doc, previously unwrapped |
+| `MediaPoolItem/Folder.AnalyzeForIntellisearch` | 🔬 | Requires AI IntelliSearch; returned an error **string**, not False — see api-limitations |
+| `MediaPoolItem/Folder.AnalyzeForSlate` | 🔬 | Requires AI Slate ID; returned False. Documented `resolve.MARKER_*` constants do not exist on the handle |
+| `Project.GenerateSpeech` | 🔬 | Requires AI Speech Generator; returned an error **string**, not a MediaPoolItem |
+| `Resolve.DisableBackgroundTasksForCurrentResolveSession` | 🔬 | Present in `dir()`; **not executed** — session-wide, returns None, and has no `Enable...` counterpart, so there is no undo short of restarting Resolve |
+
+### Untested Methods (11 of 349)
 
-### Untested Methods (5 of 336)
+Every ☁️ and 🔬 row from the reference tables, listed here so the count is
+checkable rather than asserted.
 
 | Method | Reason | Help Wanted |
 |--------|--------|-------------|
@@ -102,6 +142,18 @@ Baseline testing was performed against **DaVinci Resolve 19.1.3 Studio** on macO
 | `PM.ImportCloudProject` | Requires DaVinci Resolve cloud infrastructure | Yes |
 | `PM.RestoreCloudProject` | Requires DaVinci Resolve cloud infrastructure | Yes |
 | `TL.AnalyzeDolbyVision` | Requires HDR/Dolby Vision content | Yes |
+| `Folder.AnalyzeForIntellisearch` | Requires the AI IntelliSearch Extra | Yes |
+| `MPI.AnalyzeForIntellisearch` | Requires the AI IntelliSearch Extra | Yes |
+| `Folder.AnalyzeForSlate` | Requires the AI Slate ID Extra | Yes |
+| `MPI.AnalyzeForSlate` | Requires the AI Slate ID Extra | Yes |
+| `Project.GenerateSpeech` | Requires the AI Speech Generator Extra | Yes |
+| `Resolve.DisableBackgroundTasksForCurrentResolveSession` | Deliberately not executed: session-wide, returns `None`, and has no `Enable...` counterpart, so there is no undo short of restarting Resolve | No |
+
+The five AI Extras rows are untested for want of a downloadable pack, not because
+the wrappers are suspect — a report from anyone who has the packs installed would
+close them. The last one is a decision rather than a gap: it is reachable, and
+running it during a validation sweep would disable background tasks for every
+project open in that Resolve instance.
 
 ---
 
@@ -141,6 +193,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 20 | `GetKeyframeMode()` | ✅ | Returns keyframe mode |
 | 21 | `SetKeyframeMode(keyframeMode)` | ⚠️ | API accepts; mode must match valid enum |
 | 22 | `GetFairlightPresets()` | ✅ | Resolve 20.3.2 live test returns preset map |
+| 23 | `DisableBackgroundTasksForCurrentResolveSession()` | 🔬 | Resolve 21.0. Present in `dir()`; **not executed** — session-wide, returns `None`, no `Enable...` counterpart, so no undo short of restarting Resolve |
 
 ### ProjectManager
 
@@ -219,6 +272,8 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 41 | `AddColorGroup(groupName)` | ✅ | Returns ColorGroup object |
 | 42 | `DeleteColorGroup(colorGroup)` | ✅ | Deletes color group |
 | 43 | `ApplyFairlightPresetToCurrentTimeline(presetName)` | ⚠️ | Resolve 20.3.2 live test accepts call; returns `False` without a named preset |
+| 44 | `GenerateSpeech({speechGenerationSettings}, timecode)` | 🔬 | Resolve 21.0. Requires the AI Speech Generator Extra; without it returns an error **string**, not a MediaPoolItem |
+| 45 | `ResetIntellisearchAnalysis()` | ✅ | Resolve 21.0.2 live test returns `True` |
 
 ### MediaStorage
 
@@ -274,8 +329,13 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 4 | `GetIsFolderStale()` | ✅ | Returns `False` |
 | 5 | `GetUniqueId()` | ✅ | Returns UUID string |
 | 6 | `Export(filePath)` | ✅ | Exports DRB file |
-| 7 | `TranscribeAudio()` | ✅ | Starts audio transcription |
+| 7 | `TranscribeAudio({useSpeakerDetection})` | ✅ | Starts audio transcription. Resolve 21.0 added the optional `useSpeakerDetection` argument: it is accepted, but `True` and `False` produced identical transcripts on a deliberately two-voice clip (21.0.2.4) — the method passes, the parameter has no observable effect |
 | 8 | `ClearTranscription()` | ✅ | Clears transcription |
+| 9 | `PerformAudioClassification()` | ✅ | Resolve 21.0.2 live test returns `True`; `Category` clip property goes `""` → `Dialogue` |
+| 10 | `ClearAudioClassification()` | ✅ | Resolve 21.0.2 live test returns `True`; `Category` resets to `Uncategorized`, not `""` |
+| 11 | `AnalyzeForIntellisearch(identifyFaces, isBetterMode)` | 🔬 | Resolve 21.0. Requires the AI IntelliSearch Extra; without it returns an error **string**, not `False` |
+| 12 | `AnalyzeForSlate(markerColor)` | 🔬 | Resolve 21.0. Requires the AI Slate ID Extra. Documented `resolve.MARKER_*` constants do not exist on the handle |
+| 13 | `RemoveMotionBlur({deblurOption})` | ✅ | Resolve 21.0.2 live test returns original→new pairs; source media unchanged. Requires the AI Motion Deblur Extra |
 
 ### MediaPoolItem
 
@@ -307,7 +367,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 24 | `UnlinkProxyMedia()` | ✅ | Unlinks proxy media |
 | 25 | `ReplaceClip(filePath)` | ✅ | Replaces clip source |
 | 26 | `GetUniqueId()` | ✅ | Returns UUID string |
-| 27 | `TranscribeAudio()` | ✅ | Starts audio transcription |
+| 27 | `TranscribeAudio({useSpeakerDetection})` | ✅ | Starts audio transcription. Resolve 21.0 added the optional `useSpeakerDetection` argument: it is accepted, but `True` and `False` produced identical transcripts on a deliberately two-voice clip (21.0.2.4) — the method passes, the parameter has no observable effect |
 | 28 | `ClearTranscription()` | ✅ | Clears transcription |
 | 29 | `GetAudioMapping()` | ✅ | Returns JSON audio mapping |
 | 30 | `GetMarkInOut()` | ✅ | Returns mark in/out dict |
@@ -317,6 +377,11 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 | 34 | `LinkFullResolutionMedia(filePath)` | ⚠️ | Resolve 20.3.2 live test accepts call; full-res relink returns `False` without a matching proxy/full-res fixture |
 | 35 | `ReplaceClipPreserveSubClip(filePath)` | ✅ | Resolve 20.3.2 live test replaces clip while preserving subclip metadata |
 | 36 | `MonitorGrowingFile()` | ✅ | Resolve 20.3.2 live test enables growing-file monitoring |
+| 37 | `PerformAudioClassification()` | ✅ | Resolve 21.0.2 live test returns `True`; `Category` clip property goes `""` → `Dialogue` |
+| 38 | `ClearAudioClassification()` | ✅ | Resolve 21.0.2 live test returns `True`; `Category` resets to `Uncategorized`, not `""` |
+| 39 | `AnalyzeForIntellisearch(identifyFaces, isBetterMode)` | 🔬 | Resolve 21.0. Requires the AI IntelliSearch Extra; without it returns an error **string**, not `False` |
+| 40 | `AnalyzeForSlate(markerColor)` | 🔬 | Resolve 21.0. Requires the AI Slate ID Extra. Documented `resolve.MARKER_*` constants do not exist on the handle |
+| 41 | `RemoveMotionBlur({deblurOption})` | ✅ | Resolve 21.0.2 live test returns the new MediaPoolItem; source media path unchanged. Requires the AI Motion Deblur Extra |
 
 ### Timeline
 

package/docs/reference/api-limitations.md

@@ -10,9 +10,9 @@ 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
+**Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 23 missing capabilities, 22 bugs / unreliable behaviors.
+**Totals:** 25 missing capabilities, 24 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -192,6 +192,21 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
 - **Tags:** missing-method, media-pool, folder
 
+### Installed AI Extras packs are not discoverable from scripting
+
+- **Object:** `Resolve`
+- **Behavior:** AnalyzeForIntellisearch, AnalyzeForSlate, GenerateSpeech and RemoveMotionBlur each require a separately-downloaded Extras pack, but nothing in the scripting API reports which packs are installed. A caller cannot distinguish 'the Extra is missing' from 'the analysis ran and found nothing' ahead of time; on 21.0.2.4 two of the four leak the reason only as free text in the return value, and AnalyzeForSlate's bare False carries no reason at all.
+- **Workaround / current handling:** Until an API exists, treat a string return as the reason and read the pack names out of the Extras directory (Blackmagic Design/DaVinci Resolve/Extras/*/log.dpl1) for diagnostics only — that path is undocumented and may change.
+- **Tags:** ai, extras, introspection, resolve-21
+
+### Resolve.DisableBackgroundTasksForCurrentResolveSession
+
+- **Object:** `Resolve`
+- **Signature:** `() -> None`
+- **Behavior:** Returns None, so a caller cannot tell whether it took effect, and there is no Enable... counterpart anywhere in the shipped 21.0.2 scripting README — the only documented way back is restarting Resolve. The scope is the whole session, so a script disables background tasks for every project open in that instance, not just its own. Present in dir(resolve) on Studio 21.0.2.4; deliberately not executed during validation for exactly that reason.
+- **Workaround / current handling:** Treat as irreversible within a session. server returns _ok() unconditionally because there is nothing to check.
+- **Tags:** resolve-21, unreliable-return, irreversible, session-wide
+
 ### MediaPool.ImportMedia (current-folder destination only)
 
 - **Object:** `MediaPool`
@@ -322,10 +337,26 @@ values, or automation-hostile modal prompts.
 ### 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.
+- **Behavior:** UNRESOLVED — the two measurements do not test the same thing. On 21.0.0 the bridge was recorded as returning a callable for ANY attribute name, making capability detection by hasattr impossible; the evidence was REAL API method names borrowed from other object types (SetStart, Razor, AddNode, GenerateProxy, AddSmartBin reported present on objects that do not have them). A 21.0.2.4 control probe of the invented name 'TotallyMadeUpMethod_xyz123' returned getattr-callable False on all eight object types, matching dir() in every case. That does NOT refute the 21.0.0 record: if the bridge resolves any name known to the RemoteObject method table rather than literally any string, an invented name is correctly rejected on both builds and the probe never exercised the failing case. Re-running the probe with those five real names is what would settle it; until then, assume fabrication is possible.
+- **Workaround / current handling:** Use dir(obj) membership for capability probes. It is correct on every build measured, and it is the only form not affected by whichever way this resolves. server._has_method uses hasattr/getattr and so may over-report on builds where fabrication is live — that is the case _requires_method gates guard, so it matters most exactly where it is least tested. Calling a fabricated method typically returns None/False with no error.
 - **Tags:** bridge, introspection, silent-failure
 
+### Resolve 21 AI methods (AnalyzeForIntellisearch, GenerateSpeech, AnalyzeForSlate) — inconsistent failure return type
+
+- **Object:** `MediaPoolItem / Folder / Project`
+- **Signature:** `-> Bool (documented)`
+- **Behavior:** When the required Extras pack is not installed, these methods do not agree on how they say so, and the documented Bool is not what you get. Verified live on Studio 21.0.2.4 with only AI Motion Deblur installed: AnalyzeForSlate returned False, but AnalyzeForIntellisearch returned the STRING "Required package 'AI Intellisearch - Faster' is not installed." and GenerateSpeech returned the STRING "Required Package, 'AI Speech Generator' is not Installed.". A non-empty string is truthy in Python, so bool(result) reports SUCCESS for a call that definitively did not run, and treating GenerateSpeech's return as a MediaPoolItem raises AttributeError: 'str' object has no attribute 'GetName'.
+- **Workaround / current handling:** Never bool() an AI-method return directly. Route it through server._ai_result / _ai_result_payload, which treat any string as a failure and surface its text as the error — the message is the only machine-readable signal that an Extras pack is missing, since there is no scripting API to enumerate installed Extras.
+- **Tags:** ai, extras, unreliable-return, silent-failure, resolve-21
+
+### Folder.AnalyzeForSlate / MediaPoolItem.AnalyzeForSlate markerColor
+
+- **Object:** `MediaPoolItem / Folder`
+- **Signature:** `(markerColor) -> Bool`
+- **Behavior:** The shipped 21.0.2 scripting README says markerColor must be one of the resolve.MARKER_* constants (resolve.MARKER_BLUE etc.). Those constants do not exist: on Studio 21.0.2.4, [c for c in dir(resolve) if c.startswith('MARKER_')] is empty. There is therefore no documented-correct way to call this method. The plain colour string the server passes is the only option available, and it returns False here — though with AI Slate ID absent, a string-rejection bug cannot be distinguished from the missing pack on this machine.
+- **Workaround / current handling:** Keep passing the plain colour name (server._MARKER_COLORS) — the documented constants are unavailable. Re-test on a machine with the AI Slate ID Extra installed before concluding the string form is rejected.
+- **Tags:** ai, extras, missing-constant, documentation, resolve-21
+
 ### MediaPoolItem.SetClipProperty('Reel Name', ...)
 
 - **Object:** `MediaPoolItem`

package/docs/reference/resolve_scripting_api.txt

@@ -1,4 +1,4 @@
-Last Updated: 5 May 2026
+Last Updated: 26 May 2026
 -------------------------
 In this package, you will find a brief introduction to the Scripting API for DaVinci Resolve Studio. Apart from this README.txt file, this package contains folders containing the basic import
 modules for scripting access (DaVinciResolve.py) and some representative examples.
@@ -86,8 +86,8 @@ Resolve
   Fusion()                                        --> Fusion             # Returns the Fusion object. Starting point for Fusion scripts.
   GetMediaStorage()                               --> MediaStorage       # Returns the media storage object to query and act on media locations.
   GetProjectManager()                             --> ProjectManager     # Returns the project manager object for currently open database.
-  OpenPage(pageName)                              --> Bool               # Switches to indicated page in DaVinci Resolve. Input can be one of ("media", "cut", "edit", "fusion", "color", "fairlight", "deliver").
-  GetCurrentPage()                                --> String             # Returns the page currently displayed in the main window. Returned value can be one of ("media", "cut", "edit", "fusion", "color", "fairlight", "deliver", None).
+  OpenPage(pageName)                              --> Bool               # Switches to indicated page in DaVinci Resolve. Input can be one of ("media", "photo", "cut", "edit", "fusion", "color", "fairlight", "deliver").
+  GetCurrentPage()                                --> String             # Returns the page currently displayed in the main window. Returned value can be one of ("media", "photo", "cut", "edit", "fusion", "color", "fairlight", "deliver", None).
   GetProductName()                                --> string             # Returns product name.
   GetVersion()                                    --> [version fields]   # Returns list of product version fields in [major, minor, patch, build, suffix] format.
   GetVersionString()                              --> string             # Returns product version in "major.minor.patch[suffix].build" format.
@@ -174,13 +174,13 @@ Project
   SaveAsNewRenderPreset(presetName)               --> Bool               # Creates new render preset by given name if presetName(string) is unique.
   DeleteRenderPreset(presetName)                  --> Bool               # Delete render preset by provided name.
   SetRenderSettings({settings})                   --> Bool               # Sets given settings for rendering. Settings is a dict, with support for the keys:
-                                                                         # Refer to "Looking up render settings" section for information for supported settings
+                                                                         # Refer to section "Looking up render settings" for information on supported settings
   GetRenderJobStatus(jobId)                       --> {status info}      # Returns a dict with job status and completion percentage of the job by given jobId (string).
   GetQuickExportRenderPresets()                   --> [preset_name..]    # Returns a list of Quick Export render presets by name
   RenderWithQuickExport(preset_name, {param_dict})--> {status info}      # Starts a quick export render for the current active timeline. preset_name from GetQuickExportRenderPresets list. param_dict supports render settings keys "TargetDir", "CustomName", "VideoQuality", and "EnableUpload".
                                                                          # "EnableUpload" key enables direct upload for supported web presets.
                                                                          # Returns a dict with job status and time taken to render, or an error string if render has failed or not attempted
-                                                                         # Refer to "Looking up Render Settings" section for information on the above supported settings
+                                                                         # Refer to section "Looking up Render Settings" for information on the above supported settings
   GetSetting(settingName)                         --> string             # Returns value of project setting (indicated by settingName, string). Check the section below for more information.
   SetSetting(settingName, settingValue)           --> Bool               # Sets the project setting (indicated by settingName, string) to the value (settingValue, string). Check the section below for more information.
   GetRenderFormats()                              --> {render formats..} # Returns a dict (format -> file extension) of available render formats.
@@ -200,7 +200,11 @@ Project
   AddColorGroup(groupName)                        --> ColorGroup         # Creates a new ColorGroup. groupName must be a unique string.
   DeleteColorGroup(colorGroup)                    --> Bool               # Deletes the given color group and sets clips to ungrouped.
   ApplyFairlightPresetToCurrentTimeline(name)     --> Bool               # Apply Fairlight Preset of given name to the current timeline, returns True if successful, False otherwise.
+  ResetIntellisearchAnalysis()                    --> Bool               # Clears Intellisearch analysis data. Returns True if successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GenerateSpeech({speechGenerationSettings}, timecode) --> MediaPoolItem # Generates an audio MediaPoolItem based on the given speechGenerationSettings and adds it to the timeline at the stated timecode if "AddToTimeline" is True. Returns the newly generated MediaPoolItem.
+                                                                         # Refer to section "Speech Generation Settings" for information on supported settings
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 MediaStorage
   GetMountedVolumeList()                          --> [paths...]         # Returns list of folder paths corresponding to mounted volumes displayed in Resolve’s Media Storage.
@@ -253,6 +257,7 @@ MediaPool
   GetUniqueId()                                   --> string             # Returns a unique ID for the media pool
   CreateStereoClip(LeftMediaPoolItem,
                    RightMediaPoolItem)            --> MediaPoolItem      # Takes in two existing media pool items and creates a new 3D stereoscopic media pool entry replacing the input media in the media pool.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   AutoSyncAudio([MediaPoolItems], {audioSyncSettings}) --> Bool          # Syncs audio for specified [MediaPoolItems] (list). The list must contain a minimum of two MediaPoolItems - at least one video and one audio clip.
                                                                          # Returns True if successful. Refer to 'Audio Sync Settings' section for details.
   GetSelectedClips()                              --> [MediaPoolItems]   # Returns the current selected MediaPoolItems
@@ -266,12 +271,22 @@ Folder
   GetUniqueId()                                   --> string             # Returns a unique ID for the media pool folder
   Export(filePath)                                --> bool               # Returns true if export of DRB folder to filePath is successful, false otherwise
   TranscribeAudio(useSpeakerDetection=None)       --> Bool               # Transcribes audio of the MediaPoolItems within the folder and nested folders. Returns True if successful; False otherwise
+                                                                         # Accepts an optional boolean argument to use speaker detection when transcribing. If no argument is specified, use the project's setting.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearTranscription()                            --> Bool               # Clears audio transcription of the MediaPoolItems within the folder and nested folders. Returns True if successful; False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   PerformAudioClassification()                    --> Bool               # Analyzes and classifies the audio of the MediaPoolItems within the folder and nested folders into categories and subcategories.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearAudioClassification()                      --> Bool               # Clears audio classification of the MediaPoolItems within the folder and nested folders.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   RemoveMotionBlur({deblurOption})                --> [[MediaPoolItem, MediaPoolItem]...]   # Applies motion deblur on MediaPoolItems in the folder. Returns a list of pairs mapping original to newly created MediaPoolItems.
+                                                                         # Refer to section "Motion Deblur Settings" for information on supported settings
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   AnalyzeForIntellisearch(identifyFaces, isBetterMode) --> Bool          # Performs Intellisearch analysis on all MediaPoolItems in the folder. identifyFaces specifies whether to identify faces; isBetterMode specifies whether to use Better mode. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   AnalyzeForSlate(markerColor)                    --> Bool               # Performs Slate analysis on all MediaPoolItems in the folder using the current settings and specified markerColor. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Analyze Slate Settings" for information on markerColor
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 MediaPoolItem
   GetName()                                       --> string             # Returns the clip name.
@@ -312,18 +327,28 @@ MediaPoolItem
   ReplaceClipPreserveSubClip(filePath)            --> Bool               # Replaces the underlying asset and metadata of a video or audio clip with the specified absolute clip path, preserving original sub clip extents.
   GetUniqueId()                                   --> string             # Returns a unique ID for the media pool item
   TranscribeAudio(useSpeakerDetection=None)       --> Bool               # Transcribes audio of the MediaPoolItem. Returns True if successful; False otherwise
+                                                                         # Accepts an optional boolean argument to use speaker detection when transcribing. If no argument is specified, use the project's setting.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearTranscription()                            --> Bool               # Clears audio transcription of the MediaPoolItem. Returns True if successful; False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   PerformAudioClassification()                    --> Bool               # Analyzes and classifies the audio of a MediaPoolItem into categories and subcategories.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearAudioClassification()                      --> Bool               # Clears audio classification of the MediaPoolItem.
-  RemoveMotionBlur({deblurOption})                --> MediaPoolItem      # Applies motion deblur on the MediaPoolItem. Returns the newly created MediaPoolItem.
-  AnalyzeForIntellisearch(identifyFaces, isBetterMode) --> Bool          # Performs Intellisearch analysis on the MediaPoolItem. identifyFaces specifies whether to identify faces; isBetterMode specifies whether to use Better mode. Returns True if required packages are installed and analysis is successful.
-  AnalyzeForSlate(markerColor)                    --> Bool               # Performs Slate analysis on the MediaPoolItem using the current settings and specified markerColor. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetAudioMapping()                               --> json formatted string # Returns a string with MediaPoolItem's audio mapping information. Check 'Audio Mapping' section below for more information.
   GetMarkInOut()                                  --> {mark}             # Returns dict of in/out marks set (keys omitted if not set), example:
                                                                          # {'video': {'in': 0, 'out': 134}, 'audio': {'in': 0, 'out': 134}}
   SetMarkInOut(in, out, type="all")               --> Bool               # Sets mark in/out of type "video", "audio" or "all" (default).
   ClearMarkInOut(type="all")                      --> Bool               # Clears mark in/out of type "video", "audio" or "all" (default).
   MonitorGrowingFile()                            --> Bool               # Monitor a file as long as it keeps growing (stops if the file does not grow for some time).
+  RemoveMotionBlur({deblurOption})                --> MediaPoolItem      # Applies motion deblur on the MediaPoolItem. Returns the newly created MediaPoolItem.
+                                                                         # Refer to section "Motion Deblur Settings" for information on supported settings.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
+  AnalyzeForIntellisearch(identifyFaces, isBetterMode) --> Bool          # Performs Intellisearch analysis on the MediaPoolItem. identifyFaces specifies whether to identify faces; isBetterMode specifies whether to use Better mode. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
+  AnalyzeForSlate(markerColor)                    --> Bool               # Performs Slate analysis on the MediaPoolItem using the current settings and specified markerColor. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Analyze Slate Settings" for information on markerColor
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 Timeline
   GetName()                                       --> string             # Returns the timeline name.
@@ -407,12 +432,15 @@ Timeline
   CreateSubtitlesFromAudio({autoCaptionSettings}) --> Bool               # Creates subtitles from audio for the timeline.
                                                                          # Takes in optional dictionary {autoCaptionSettings}. Check 'Auto Caption Settings' subsection below for more information.
                                                                          # Returns True on success, False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   DetectSceneCuts()                               --> Bool               # Detects and makes scene cuts along the timeline. Returns True if successful, False otherwise.
   ConvertTimelineToStereo()                       --> Bool               # Converts timeline to stereo. Returns True if successful; False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetNodeGraph()                                  --> Graph              # Returns the timeline's node graph object.
   AnalyzeDolbyVision([timelineItems]=[],          --> Bool               # Analyzes Dolby Vision on clips present on the timeline. Returns True if analysis start is successful; False otherwise.
                      analysisType=NONE)                                  # if [timelineItems] is empty, analysis performed on all items. Else, analysis performed on [timelineItems] only.
                                                                          # set analysisType to resolve.DLB_BLEND_SHOTS for blend setting
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetMediaPoolItem()                              --> MediaPoolItem      # Returns the media pool item corresponding to the timeline
   GetMarkInOut()                                  --> {mark}             # Returns dict of in/out marks set (keys omitted if not set), example:
                                                                          # {'video': {'in': 0, 'out': 134}, 'audio': {'in': 0, 'out': 134}}
@@ -420,6 +448,7 @@ Timeline
   ClearMarkInOut(type="all")                      --> Bool               # Clears mark in/out of type "video", "audio" or "all" (default).
   GetVoiceIsolationState(trackIndex)              --> {VoiceIsolationState} # Returns the Voice Isolation State as a dict {isEnabled, amount}, of the given track index
   SetVoiceIsolationState(trackIndex, {VoiceIsolationState}) --> Bool     # Sets Voice Isolation state of audio track with given trackIndex (int) to the given VoiceIsolationState of {isEnabled (bool), amount (int)}. amount is in range of [0, 100] and 1 <= trackIndex <= GetTrackCount("audio"). Returns True if successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 TimelineItem
   GetName()                                       --> string             # Returns the item name.
@@ -438,7 +467,7 @@ TimelineItem
   GetSourceStartFrame()                           --> int                # Returns the start frame position of the media pool clip in the timeline clip.
   GetSourceStartTime()                            --> float              # Returns the start time position of the media pool clip in the timeline clip.
   SetProperty(propertyKey, propertyValue)         --> Bool               # Sets the value of property "propertyKey" to value "propertyValue"
-                                                                         # Refer to "Looking up Timeline item properties" for more information
+                                                                         # Refer to section "Looking up Timeline item properties" for more information
   GetProperty(propertyKey)                        --> int/[key:value]    # returns the value of the specified key
                                                                          # if no key is specified, the method returns a dictionary(python) or table(lua) for all supported keys
   AddMarker(frameId, color, name, note, duration, --> Bool               # Creates a new marker at given frameId position and with given marker information. 'customData' is optional and helps to attach user specific data to the marker.
@@ -471,8 +500,11 @@ TimelineItem
   GetVersionNameList(versionType)                 --> [names...]         # Returns a list of all color versions for the given versionType (0 - local, 1 - remote).
   GetMediaPoolItem()                              --> MediaPoolItem      # Returns the media pool item corresponding to the timeline item if one exists.
   GetStereoConvergenceValues()                    --> {keyframes...}     # Returns a dict (offset -> value) of keyframe offsets and respective convergence values.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetStereoLeftFloatingWindowParams()             --> {keyframes...}     # For the LEFT eye -> returns a dict (offset -> dict) of keyframe offsets and respective floating window params. Value at particular offset includes the left, right, top and bottom floating window values.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetStereoRightFloatingWindowParams()            --> {keyframes...}     # For the RIGHT eye -> returns a dict (offset -> dict) of keyframe offsets and respective floating window params. Value at particular offset includes the left, right, top and bottom floating window values.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   SetCDL([CDL map])                               --> Bool               # Keys of map are: "NodeIndex", "Slope", "Offset", "Power", "Saturation", where 1 <= NodeIndex <= total number of nodes.
                                                                          # Example python code - SetCDL({"NodeIndex" : "1", "Slope" : "0.5 0.4 0.2", "Offset" : "0.4 0.3 0.2", "Power" : "0.6 0.7 0.8", "Saturation" : "0.65"})
   AddTake(mediaPoolItem, startFrame, endFrame)    --> Bool               # Adds mediaPoolItem as a new take. Initializes a take selector for the timeline item if needed. By default, the full clip extents is added. startFrame (int) and endFrame (int) are optional arguments used to specify the extents.
@@ -489,9 +521,12 @@ TimelineItem
   GetUniqueId()                                   --> string             # Returns a unique ID for the timeline item
   LoadBurnInPreset(presetName)                    --> Bool               # Loads user defined data burn in preset for clip when supplied presetName (string). Returns true if successful.
   CreateMagicMask(mode)                           --> Bool               # Returns True if magic mask was created successfully, False otherwise. mode can "F" (forward), "B" (backward), or "BI" (bidirection)
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   RegenerateMagicMask()                           --> Bool               # Returns True if magic mask was regenerated successfully, False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   Stabilize()                                     --> Bool               # Returns True if stabilization was successful, False otherwise
   SmartReframe()                                  --> Bool               # Performs Smart Reframe. Returns True if successful, False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetNodeGraph(layerIdx)                          --> Graph              # Returns the clip's node graph object at layerIdx (int, optional). Returns the first layer if layerIdx is skipped. 1 <= layerIdx <= project.GetSetting("nodeStackLayers").
   GetColorGroup()                                 --> ColorGroup         # Returns the clip's color group if one exists.
   AssignToColorGroup(ColorGroup)                  --> Bool               # Returns True if TiItem to successfully assigned to given ColorGroup. ColorGroup must be an existing group in the current project.
@@ -510,6 +545,7 @@ TimelineItem
   SetFusionOutputCache(cache_value)               --> Bool               # Sets caching to auto, enabled or disabled. Equivalent to clip context menu action 'Render Cache Fusion Output'.
   GetVoiceIsolationState()                        --> {VoiceIsolationState} # Returns the Voice Isolation State as a dict {isEnabled, amount}, of the timelineItem
   SetVoiceIsolationState({VoiceIsolationState})   --> Bool               # Sets Voice Isolation state of the timelineItem to the given VoiceIsolationState of {isEnabled (bool), amount (int)}. amount is in range of [0, 100]. Returns True if successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ResetAllNodeColors()                            --> Bool               # Reset node color for all nodes in the active version of the clip. Returns True if successful.
 
 Gallery
@@ -538,7 +574,7 @@ Graph
                                                                          # The lutPath can be an absolute path, or a relative path (based off custom LUT paths or the master LUT path).
                                                                          # The operation is successful for valid lut paths that Resolve has already discovered (see Project.RefreshLUTList).
   GetLUT(nodeIndex)                               --> String             # Gets relative LUT path based on the node index provided, 1 <= nodeIndex <= total number of nodes.
-  SetNodeCacheMode(nodeIndex, cache_value)        --> Bool               # Sets the cache mode type on the node mapping the node index provided. Refer to "Cache Mode" section below to find the possible values of cache_value.
+  SetNodeCacheMode(nodeIndex, cache_value)        --> Bool               # Sets the cache mode type on the node mapping the node index provided. Refer to section "Cache Mode" below to find the possible values of cache_value.
   GetNodeCacheMode(nodeIndex)                     --> cache_value        # Returns the cache mode type on the node mapping the node index provided.
   GetNodeLabel(nodeIndex)                         --> string             # Returns the label of the node at nodeIndex.
   GetToolsInNode(nodeIndex)                       --> [toolsList]        # Returns toolsList (list of strings) of the tools used in the node indicated by given nodeIndex (int).
@@ -960,6 +996,39 @@ as a single argument.
 
 Getting the values for the keys that uses constants will return the number which is in the constant
 
+Studio and AI Scripting APIs
+----------------------------
+The DaVinci Resolve scripting APIs cover a common superset of functions for both the Free and Studio versions of the application.
+
+API calls can return with a False status (or an appropriate error status) when:
+* the function references a Studio function from the free DaVinci Resolve version.
+* the minimum system requirements of the function are not satisfied. To check if your system is capable, invoke the function from the GUI and check for error dialogs.
+* the requisite Extras have not been downloaded.
+
+The following functions require one or more Extras downloads:
+* AnalyzeForIntellisearch(identifyFaces, isBetterMode=False) requires AI IntelliSearch - Faster.
+* AnalyzeForIntellisearch(identifyFaces, isBetterMode=True) requires AI IntelliSearch - Better.
+* AnalyzeForSlate(markerColor) requires AI Slate ID.
+* Transcription workflows with extended language models. Languages from built in models will be used as a fallback if unavailable.
+* GenerateSpeech({speechGenerationSettings}, timecode) requires AI Speech Generator.
+
+For a successful API call, the required package will need to be installed before script invocation. Go to the DaVinci Resolve Studio application menu, open the Extras Download Manager and install the required package.
+
+Motion Deblur Settings
+-----------------------------------
+This section covers the supported settings for the method RemoveMotionBlur({deblurOption})
+
+The deblurOption setting is a dictionary containing the following keys:
+    - "FileName": string
+    - "Format": string (example: "mov", "mp4").
+    - "Codec": string (example: "H264", "ProRes422")
+    - "EncodingProfile": string (example: "Main10"). Can only be set for H.264 and H.265.
+    - "UseExtremeMode": bool
+    - "UseMarkInMarkOut": bool
+    - "RenderAtSourceRes": bool
+    - "UseMoreGpuMemory": bool
+    - "Encoder" : string (Native or MainConcept). Can only be set for H.265
+
 ExportLUT notes
 ---------------
 The following section covers additional notes for TimelineItem.ExportLUT(exportType, path).
@@ -970,6 +1039,43 @@ Supported values for 'exportType' (enum) are:
     - resolve.EXPORT_LUT_65PTCUBE
     - resolve.EXPORT_LUT_PANASONICVLUT
 
+Analyze Slate Settings
+-----------------------------------
+This section covers the supported settings for the method AnalyzeForSlate(markerColor)
+  markerColor can be one of the following constants:
+    - resolve.MARKER_BLUE
+    - resolve.MARKER_CYAN
+    - resolve.MARKER_GREEN
+    - resolve.MARKER_YELLOW
+    - resolve.MARKER_RED
+    - resolve.MARKER_PINK
+    - resolve.MARKER_PURPLE
+    - resolve.MARKER_FUCHSIA
+    - resolve.MARKER_ROSE
+    - resolve.MARKER_LAVENDER
+    - resolve.MARKER_SKY
+    - resolve.MARKER_MINT
+    - resolve.MARKER_LEMON
+    - resolve.MARKER_SAND
+    - resolve.MARKER_COCOA
+    - resolve.MARKER_CREAM
+
+Speech Generation Settings
+-----------------------------------
+This section covers the supported settings for the method GenerateSpeech({speechGenerationSettings}, timecode)
+
+The speechGenerationSettings is a dictionary containing the following keys:
+    - "TextInput": string # Max 350 chars
+    - "VoiceModel": string (example: "Female 1", "Male 1", "Custom Voice").
+    - "CustomVoiceFile": string "Full Path of Voice File"
+    - "Speed": int
+    - "Variation": int
+    - "Pitch": int
+    - "GenerationID": int
+    - "Filename" : string
+    - "AddToTimeline" : bool
+    - "AudioTrack": int
+
 Deprecated Resolve API Functions
 --------------------------------
 The following API functions are deprecated.

package/install.py

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

package/src/granular/common.py

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

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.71.1"
+VERSION = "2.72.1"
 
 import base64
 import os
@@ -1784,6 +1784,36 @@ def _requires_method(obj, method_name, min_version):
         return None
     return _err(f"{method_name} requires DaVinci Resolve {min_version}+")
 
+def _ai_result(returned):
+    """Normalize a Resolve 21 AI-method return into (ok, message).
+
+    The AI methods do not agree on how they report a missing Extras pack, and
+    one of the two shapes is a trap. Verified live on Studio 21.0.2.4 with only
+    AI Motion Deblur installed:
+
+      - `AnalyzeForSlate`  -> False
+      - `AnalyzeForIntellisearch` -> "Required package 'AI Intellisearch -
+        Faster' is not installed."
+      - `GenerateSpeech`   -> "Required Package, 'AI Speech Generator' is not
+        Installed."
+
+    A non-empty string is truthy, so `bool(returned)` reports success for a call
+    that definitively did not run, and treating the return as a MediaPoolItem
+    raises AttributeError. Route every AI return through here instead: a string
+    is always a failure, and its text is the reason worth surfacing.
+    """
+    if isinstance(returned, str):
+        return False, returned.strip() or None
+    return bool(returned), None
+
+def _ai_result_payload(returned):
+    """`{"success": ...}` plus the Resolve-supplied reason when there is one."""
+    ok, message = _ai_result(returned)
+    payload = {"success": ok}
+    if message:
+        payload["error"] = message
+    return payload
+
 def _is_truncated(text):
     """True if a transcription preview was cut off.
 
@@ -15459,6 +15489,7 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
       delete_color_group(name) -> {success}
       apply_fairlight_preset(preset_name) -> {success}
       generate_speech(speech_generation_settings, timecode?) -> {success, new, new_id}  — Resolve 21+, AI Speech Generator; creates new audio media (confirm-gated)
+      reset_intellisearch_analysis() -> {success}  — Resolve 21+; clears the project's IntelliSearch analysis data
     """
     p = _params(params)
     _, proj, err = _check()
@@ -15557,16 +15588,29 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
             return blocked
         with _ai_ledger_timed("generate_speech") as _rec:
             new_item = proj.GenerateSpeech(settings, timecode)
-            _rec.success = bool(new_item)
-            if new_item:
+            # GenerateSpeech returns an error STRING when the AI Speech Generator
+            # Extra is absent (verified on Studio 21.0.2.4), not a MediaPoolItem.
+            # A bare truthiness test lets that string through to .GetName() and
+            # raises AttributeError, so normalize before touching the result.
+            ok, message = _ai_result(new_item)
+            _rec.success = ok
+            if ok:
                 path, nbytes = _clip_file_size(new_item)
                 _rec.output_path = path
                 _rec.output_bytes = nbytes
-        if not new_item:
-            return {"success": False}
+        if not ok:
+            return {"success": False, "error": message} if message else {"success": False}
         return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId(),
                 "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
-    return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","project_summary","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech"])
+    elif action == "reset_intellisearch_analysis":
+        missing = _requires_method(proj, "ResetIntellisearchAnalysis", "21.0")
+        if missing:
+            return missing
+        with _ai_ledger_timed("reset_intellisearch_analysis") as _rec:
+            result = _ai_result_payload(proj.ResetIntellisearchAnalysis())
+            _rec.success = result["success"]
+        return result
+    return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","project_summary","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech","reset_intellisearch_analysis"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -17006,17 +17050,17 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if missing:
             return missing
         with _ai_ledger_timed("perform_audio_classification") as _rec:
-            ok = bool(f.PerformAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.PerformAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "clear_audio_classification":
         missing = _requires_method(f, "ClearAudioClassification", "21.0")
         if missing:
             return missing
         with _ai_ledger_timed("clear_audio_classification") as _rec:
-            ok = bool(f.ClearAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.ClearAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_intellisearch":
         missing = _requires_method(f, "AnalyzeForIntellisearch", "21.0")
         if missing:
@@ -17024,9 +17068,9 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         identify_faces = bool(_first_param(p, "identify_faces", "identifyFaces", default=False))
         is_better_mode = bool(_first_param(p, "is_better_mode", "isBetterMode", default=False))
         with _ai_ledger_timed("analyze_for_intellisearch") as _rec:
-            ok = bool(f.AnalyzeForIntellisearch(identify_faces, is_better_mode))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.AnalyzeForIntellisearch(identify_faces, is_better_mode))
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_slate":
         missing = _requires_method(f, "AnalyzeForSlate", "21.0")
         if missing:
@@ -17035,9 +17079,9 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if marker_color not in _MARKER_COLORS:
             return _err(f"Invalid marker_color {marker_color!r}. Valid colors: {', '.join(_MARKER_COLORS)}")
         with _ai_ledger_timed("analyze_for_slate") as _rec:
-            ok = bool(f.AnalyzeForSlate(marker_color))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.AnalyzeForSlate(marker_color))
+            _rec.success = result["success"]
+        return result
     elif action == "remove_motion_blur":
         missing = _requires_method(f, "RemoveMotionBlur", "21.0")
         if missing:
@@ -17062,11 +17106,18 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if blocked:
             return blocked
         with _ai_ledger_timed("remove_motion_blur") as _rec:
+            # RemoveMotionBlur needs the AI Motion Deblur Extra, so it belongs to
+            # the same family as the methods above: absent the pack, the return
+            # can be an error STRING rather than the documented list. Iterating a
+            # string yields characters, the pair-unpack raises, `except Exception`
+            # swallows it, and the action reported success:true with created:[]
+            # — a silent lie in the confirm-gated path that renders new media.
             result = f.RemoveMotionBlur(deblur)
-            _rec.success = bool(result)
+            ok, message = _ai_result(result)
+            _rec.success = ok
             created = []
             total_bytes = 0
-            for pair in (result or []):
+            for pair in (result or []) if ok else []:
                 try:
                     orig, new = pair
                     path, nbytes = _clip_file_size(new)
@@ -17080,7 +17131,10 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
             if created:
                 _rec.output_path = created[0].get("output_path")
                 _rec.output_bytes = total_bytes or None
-        return {"success": bool(result), "created": created}
+        payload = {"success": ok, "created": created}
+        if message:
+            payload["error"] = message
+        return payload
     return _unknown(action, ["get_clips","get_name","get_subfolders","is_stale","get_unique_id","export","transcribe_audio","clear_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur"])
 
 
@@ -17404,17 +17458,17 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if missing:
             return missing
         with _ai_ledger_timed("perform_audio_classification", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.PerformAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.PerformAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "clear_audio_classification":
         missing = _requires_method(clip, "ClearAudioClassification", "21.0")
         if missing:
             return missing
         with _ai_ledger_timed("clear_audio_classification", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.ClearAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.ClearAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_intellisearch":
         missing = _requires_method(clip, "AnalyzeForIntellisearch", "21.0")
         if missing:
@@ -17422,9 +17476,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         identify_faces = bool(_first_param(p, "identify_faces", "identifyFaces", default=False))
         is_better_mode = bool(_first_param(p, "is_better_mode", "isBetterMode", default=False))
         with _ai_ledger_timed("analyze_for_intellisearch", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.AnalyzeForIntellisearch(identify_faces, is_better_mode))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.AnalyzeForIntellisearch(identify_faces, is_better_mode))
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_slate":
         missing = _requires_method(clip, "AnalyzeForSlate", "21.0")
         if missing:
@@ -17433,9 +17487,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if marker_color not in _MARKER_COLORS:
             return _err(f"Invalid marker_color {marker_color!r}. Valid colors: {', '.join(_MARKER_COLORS)}")
         with _ai_ledger_timed("analyze_for_slate", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.AnalyzeForSlate(marker_color))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.AnalyzeForSlate(marker_color))
+            _rec.success = result["success"]
+        return result
     elif action == "remove_motion_blur":
         missing = _requires_method(clip, "RemoveMotionBlur", "21.0")
         if missing:
@@ -17460,14 +17514,19 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if blocked:
             return blocked
         with _ai_ledger_timed("remove_motion_blur", clip_id=p.get("clip_id")) as _rec:
+            # Same shape as generate_speech: a MediaPoolItem return, and an error
+            # STRING when the AI Motion Deblur Extra is absent. `_clip_file_size`
+            # swallows its own AttributeError, so the string survived to
+            # `.GetName()` and raised there instead.
             new_clip = clip.RemoveMotionBlur(deblur)
-            _rec.success = bool(new_clip)
-            if new_clip:
+            ok, message = _ai_result(new_clip)
+            _rec.success = ok
+            if ok:
                 path, nbytes = _clip_file_size(new_clip)
                 _rec.output_path = path
                 _rec.output_bytes = nbytes
-        if not new_clip:
-            return {"success": False}
+        if not ok:
+            return {"success": False, "error": message} if message else {"success": False}
         return {"success": True, "new": new_clip.GetName(), "new_id": new_clip.GetUniqueId(),
                 "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
     elif action == "get_audio_mapping":

package/src/utils/api_truth.py

@@ -26,7 +26,7 @@ When you add or change a ``submit``-tagged entry, regenerate the report
 """
 from typing import Any, Dict, List, Optional
 
-VERIFIED_ON = "DaVinci Resolve Studio 21.0.0"
+VERIFIED_ON = "DaVinci Resolve Studio 21.0.2"
 
 # Each entry: symbol, object, reality, recommended, tags. `signature` optional.
 API_TRUTH: List[Dict[str, Any]] = [
@@ -717,18 +717,143 @@ API_TRUTH: List[Dict[str, Any]] = [
     {
         "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.",
+        "reality": "UNRESOLVED — the two measurements do not test the same thing. "
+                   "On 21.0.0 the bridge was recorded as returning a callable for "
+                   "ANY attribute name, making capability detection by hasattr "
+                   "impossible; the evidence was REAL API method names borrowed from "
+                   "other object types (SetStart, Razor, AddNode, GenerateProxy, "
+                   "AddSmartBin reported present on objects that do not have them). "
+                   "A 21.0.2.4 control probe of the invented name "
+                   "'TotallyMadeUpMethod_xyz123' returned getattr-callable False on "
+                   "all eight object types, matching dir() in every case. That does "
+                   "NOT refute the 21.0.0 record: if the bridge resolves any name "
+                   "known to the RemoteObject method table rather than literally any "
+                   "string, an invented name is correctly rejected on both builds and "
+                   "the probe never exercised the failing case. Re-running the probe "
+                   "with those five real names is what would settle it; until then, "
+                   "assume fabrication is possible.",
+        "recommended": "Use dir(obj) membership for capability probes. It is correct "
+                       "on every build measured, and it is the only form not affected "
+                       "by whichever way this resolves. server._has_method uses "
+                       "hasattr/getattr and so may over-report on builds where "
+                       "fabrication is live — that is the case _requires_method gates "
+                       "guard, so it matters most exactly where it is least tested. "
+                       "Calling a fabricated method typically returns None/False with "
+                       "no error.",
         "tags": ["bridge", "introspection", "silent-failure"],
         "submit": "bug",
     },
+    {
+        "symbol": "Resolve 21 AI methods (AnalyzeForIntellisearch, GenerateSpeech, "
+                  "AnalyzeForSlate) — inconsistent failure return type",
+        "object": "MediaPoolItem / Folder / Project",
+        "signature": "-> Bool (documented)",
+        "reality": "When the required Extras pack is not installed, these methods do "
+                   "not agree on how they say so, and the documented Bool is not what "
+                   "you get. Verified live on Studio 21.0.2.4 with only AI Motion "
+                   "Deblur installed: AnalyzeForSlate returned False, but "
+                   "AnalyzeForIntellisearch returned the STRING \"Required package 'AI "
+                   "Intellisearch - Faster' is not installed.\" and GenerateSpeech "
+                   "returned the STRING \"Required Package, 'AI Speech Generator' is "
+                   "not Installed.\". A non-empty string is truthy in Python, so "
+                   "bool(result) reports SUCCESS for a call that definitively did not "
+                   "run, and treating GenerateSpeech's return as a MediaPoolItem "
+                   "raises AttributeError: 'str' object has no attribute 'GetName'.",
+        "recommended": "Never bool() an AI-method return directly. Route it through "
+                       "server._ai_result / _ai_result_payload, which treat any string "
+                       "as a failure and surface its text as the error — the message is "
+                       "the only machine-readable signal that an Extras pack is "
+                       "missing, since there is no scripting API to enumerate "
+                       "installed Extras.",
+        "tags": ["ai", "extras", "unreliable-return", "silent-failure", "resolve-21"],
+        "submit": "bug",
+        "mitigation": ["_ai_result", "_ai_result_payload"],
+    },
+    {
+        "symbol": "Installed AI Extras packs are not discoverable from scripting",
+        "object": "Resolve",
+        "reality": "AnalyzeForIntellisearch, AnalyzeForSlate, GenerateSpeech and "
+                   "RemoveMotionBlur each require a separately-downloaded Extras pack, "
+                   "but nothing in the scripting API reports which packs are installed. "
+                   "A caller cannot distinguish 'the Extra is missing' from 'the "
+                   "analysis ran and found nothing' ahead of time; on 21.0.2.4 two of "
+                   "the four leak the reason only as free text in the return value, and "
+                   "AnalyzeForSlate's bare False carries no reason at all.",
+        "recommended": "Until an API exists, treat a string return as the reason and "
+                       "read the pack names out of the Extras directory "
+                       "(Blackmagic Design/DaVinci Resolve/Extras/*/log.dpl1) for "
+                       "diagnostics only — that path is undocumented and may change.",
+        "tags": ["ai", "extras", "introspection", "resolve-21"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Folder.AnalyzeForSlate / MediaPoolItem.AnalyzeForSlate markerColor",
+        "object": "MediaPoolItem / Folder",
+        "signature": "(markerColor) -> Bool",
+        "reality": "The shipped 21.0.2 scripting README says markerColor must be one of "
+                   "the resolve.MARKER_* constants (resolve.MARKER_BLUE etc.). Those "
+                   "constants do not exist: on Studio 21.0.2.4, "
+                   "[c for c in dir(resolve) if c.startswith('MARKER_')] is empty. "
+                   "There is therefore no documented-correct way to call this method. "
+                   "The plain colour string the server passes is the only option "
+                   "available, and it returns False here — though with AI Slate ID "
+                   "absent, a string-rejection bug cannot be distinguished from the "
+                   "missing pack on this machine.",
+        "recommended": "Keep passing the plain colour name (server._MARKER_COLORS) — "
+                       "the documented constants are unavailable. Re-test on a machine "
+                       "with the AI Slate ID Extra installed before concluding the "
+                       "string form is rejected.",
+        # Deliberately NOT tagged `enum`: that tag denotes the issue-#70 class,
+        # where plain strings are rejected and a resolver must translate them
+        # into live enum constants. Here the documented constants do not exist
+        # on the handle at all, so there is nothing to resolve — the defect is
+        # in the documentation, not in a missing resolver.
+        "tags": ["ai", "extras", "missing-constant", "documentation", "resolve-21"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "Project.ResetIntellisearchAnalysis",
+        "object": "Project",
+        "signature": "() -> Bool",
+        "reality": "Documented in the scripting README shipped with Resolve 21.0.2 "
+                   "(dated 26 May 2026) but absent from the 5 May 2026 copy the repo "
+                   "bundled, so it was missing from the coverage tables. Present in "
+                   "dir(project) and returns True on Studio 21.0.2.4.",
+        "recommended": "Exposed as project_settings('reset_intellisearch_analysis').",
+        "tags": ["resolve-21", "documentation"],
+    },
+    {
+        "symbol": "Resolve.DisableBackgroundTasksForCurrentResolveSession",
+        "object": "Resolve",
+        "signature": "() -> None",
+        "reality": "Returns None, so a caller cannot tell whether it took effect, and "
+                   "there is no Enable... counterpart anywhere in the shipped 21.0.2 "
+                   "scripting README — the only documented way back is restarting "
+                   "Resolve. The scope is the whole session, so a script disables "
+                   "background tasks for every project open in that instance, not just "
+                   "its own. Present in dir(resolve) on Studio 21.0.2.4; deliberately "
+                   "not executed during validation for exactly that reason.",
+        "recommended": "Treat as irreversible within a session. server returns _ok() "
+                       "unconditionally because there is nothing to check.",
+        "tags": ["resolve-21", "unreliable-return", "irreversible", "session-wide"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "MediaPoolItem.PerformAudioClassification / ClearAudioClassification",
+        "object": "MediaPoolItem / Folder",
+        "signature": "() -> Bool",
+        "reality": "Both work without any Extras pack and the effect is observable, "
+                   "which is unusual for this family. Verified on Studio 21.0.2.4 "
+                   "against a synthetic speech clip: PerformAudioClassification "
+                   "returned True and set the clip property 'Category' from '' to "
+                   "'Dialogue' (also surfacing Category/Subcategory in GetMetadata); "
+                   "ClearAudioClassification returned True and reset 'Category' to "
+                   "'Uncategorized' — note the cleared state is 'Uncategorized', NOT "
+                   "the original empty string.",
+        "recommended": "Read back GetClipProperty('Category'); treat both '' and "
+                       "'Uncategorized' as unclassified.",
+        "tags": ["ai", "audio", "resolve-21", "readback"],
+    },
     {
         "symbol": "subprocess inheriting stdin under the MCP stdio server",
         "object": "(server runtime)",