davinci-resolve-mcp 2.23.0

package/docs/SKILL.md

@@ -0,0 +1,1145 @@
+# DaVinci Resolve MCP Server — AI Skill Reference
+
+This document gives AI assistants the context needed to use the DaVinci Resolve
+MCP server effectively. It covers the tool landscape, page prerequisites,
+common workflow patterns, error recovery, and known gotchas.
+
+---
+
+## What This Server Does
+
+The DaVinci Resolve MCP server bridges AI assistants to DaVinci Resolve Studio
+via its official Scripting API. You can control every aspect of a post-production
+session — projects, timelines, clips, color grading, Fusion compositions, audio,
+render queues, and more — through natural language.
+
+DaVinci Resolve must be running with **Preferences > General > "External scripting
+using"** set to **Local**. The server auto-launches Resolve if it is not running,
+but that first connection can take up to 60 seconds.
+
+Workflow Integration plugins/scripts are a separate Resolve-hosted UI mechanism.
+They are not required for this MCP server, but `docs/integrations/workflow-integrations.md`
+summarizes when they are useful for optional in-Resolve panels, UIManager
+scripts, and render callback companions.
+
+OpenFX plugins are native C++ image-effect plugins, not an MCP control surface.
+Use `docs/notes/openfx-notes.md` when diagnosing `insert_ofx_generator` failures or
+discussing optional OFX plugin development.
+
+LUT files are directly relevant to Color-page graph actions. Use
+`docs/notes/lut-notes.md` when diagnosing `graph.set_lut` failures, validating `.cube`
+files, or explaining `project_settings.refresh_luts`.
+
+Fusion templates are relevant to Edit/Cut page insertion actions. Use
+`docs/notes/fusion-template-notes.md` when diagnosing `insert_fusion_generator` or
+`insert_fusion_title` failures, template paths, `.setting` files, or `.drfx`
+bundles.
+
+DCTL files are programmable color transforms/effects adjacent to LUT and OpenFX
+workflows. Use `docs/notes/dctl-notes.md` when diagnosing `.dctl`/`.dctle` discovery,
+ResolveFX DCTL plugin behavior, ACES DCTL IDT/ODT setup, or DCTL-as-LUT usage.
+
+Codec plugins are native IO encode plugins that extend Deliver-page render
+formats/codecs. Use `docs/notes/codec-plugin-notes.md` when diagnosing missing custom
+render formats/codecs, `.dvcp.bundle` packaging, or IOPlugins install paths.
+
+The `fuse_plugin`, `dctl`, and `script_plugin` compound tools (v2.5.0+) write
+Fuse plugin source, DCTL files, and Lua/Python scripts into Resolve's install
+directories. They are *authoring* tools — every other tool in this server wraps
+Resolve's scripting API, while these three emit and install plugin/script
+source. Status: lifecycle-verified in DaVinci Resolve Studio 20.3.2.9 for
+MCP-marked install/read/list/remove, regular DCTL `refresh_luts`, ACES/Fuse
+restart-required classification, Python installed-script execution, and
+Python/Lua `run_inline`. Use `docs/kernels/extension-authoring-kernel.md` for the
+kernel boundary map, `docs/authoring/fuse-dctl-authoring.md` for the Fuse + DCTL coverage
+matrix, and `docs/authoring/script-plugin-authoring.md` for the script DSL spec and the
+conversational-execution model.
+
+Extension Authoring kernel actions (v2.16.0+) are exposed through
+`script_plugin`:
+
+- `extension_capabilities`
+- `probe_fuse_lifecycle(name?, kind?, install?, cleanup?)`
+- `probe_dctl_lifecycle(name?, kind?, category?, install?, refresh_luts?, cleanup?)`
+- `probe_script_lifecycle(name?, language?, category?, install?, execute?, cleanup?)`
+- `safe_install_extension(extension_type, name, source?|kind?, dry_run?)`
+- `safe_remove_extension(extension_type, name, dry_run?)`
+- `refresh_or_restart_required(extension_type, category?)`
+- `extension_boundary_report(include_template_matrix?)`
+
+Key behavioral notes for `script_plugin`:
+- `run_inline(source, language)` runs ad-hoc Lua/Python in Resolve and returns
+  stdout + result — use this for one-off conversational queries against the
+  Resolve API instead of building+installing a script.
+- `language` accepts `lua`, `py`, or the human-facing aliases `python` and
+  `python3`.
+- `execute(name, category, language)` runs an installed script; Python stdout
+  and stderr are captured, while installed Lua execution can return false from
+  the Python bridge even when install/read/list/remove worked.
+- Lua scripts: `fusion.Execute()` from the Python bridge is a no-op in
+  Resolve 20.x — `_run_inline_lua` works around this with `RunScript` against
+  a temp file plus completion-sentinel polling on `app:SetData/GetData`.
+- Fuse install path on macOS is `…/DaVinci Resolve/Fusion/Fuses/` (NOT
+  `Support/Fusion/Fuses/` as the SDK doc lists). The MCP path helpers handle
+  this; if you're staging files manually, use the path the implementation
+  emits.
+- Resolve picks up new scripts without a restart; new Fuses need a restart
+  to register; new DCTLs need `project_settings(action='refresh_luts')`
+  (regular LUT category) or a restart (ACES IDT/ODT category).
+
+Tool metadata (v2.17.1+) includes MCP `ToolAnnotations` for read-only,
+destructive, idempotent, and external-resource hints. Treat compound tool
+annotations as conservative because a single compound tool may expose both probe
+and mutation actions behind its `action` parameter. Continue to prefer
+`safe_*`, `dry_run`, `probe_*`, `capabilities`, and `boundary_report` actions
+before mutating Resolve state.
+
+---
+
+## Two Server Modes
+
+| Mode | Entry point | Tool count | Use when |
+|---|---|---|---|
+| Compound (default) | `src/server.py` | 32 tools | Most workflows — keeps context lean |
+| Granular (full) | `src/server.py --full` | 329 tools | Power users needing one tool per API method |
+
+This skill document covers the **compound server** (the default). Each compound
+tool accepts an `action` string and an optional `params` object.
+
+The compound server also registers MCP prompts. Use `davinci_resolve_workflow`
+as the compact operating brief, and use `analyze_media` as a slash-command style
+entry point for read-only project, selected-clip, bin, or file analysis. The
+Analyze Media prompt defaults to chat-context visual analysis when the MCP
+client supports sampling/image messages, while allowing `include_visuals=false`
+for technical-only or privacy-sensitive runs. It also encodes session-only
+defaults, optional transcription, and finished-video editorial guardrails.
+
+## Local Control Panel
+
+If the user asks to open, launch, or inspect the Resolve MCP control panel, run
+this from the repository root:
+
+```bash
+venv/bin/python -m src.control_panel
+```
+
+The command starts the local control panel and opens the default browser. Use
+`--no-open` when running in a headless context, then give the user the printed
+localhost URL. The panel is local and single-user; it is an operational surface
+for server status, Resolve clips, source-safe analysis jobs, preferences, and
+diagnostics as those sections are added.
+
+---
+
+## Editorial Memory And Decision-Making
+
+When the user asks for cutting, pacing, story shape, suspense, comedy timing, or
+tonal reframing, operate like an editor, not just a metadata scanner. Use
+`docs/guides/editorial-decision-guide.md` as the project-owned craft reference. The
+short version: emotion and story come first, then clarity, rhythm, eye trace,
+screen geography, continuity, and coverage variety.
+
+Before analyzing or rebuilding anything, check whether the active project already
+contains useful evidence:
+
+- `media_analysis(action="summarize")`
+- `media_analysis(action="get_report")` when a manifest or report path is known
+- `timeline(action="list")`
+- `timeline(action="get_current")`
+- `timeline(action="probe_timeline_structure")`
+- `timeline(action="source_range_report")`
+- `timeline_markers(action="get_all")`
+- `media_analysis(action="review_timeline_markers")` when marker imagery matters
+
+Reuse prior analysis unless it is stale, incomplete, or missing the modality the
+user is asking for. For example, do not re-run visual analysis just because the
+edit task is new if a current report already has keyframes, motion variance, and
+usable visual descriptions. Add transcription, chat-context vision, marker
+review, or source range checks only when that missing evidence changes the
+decision. Use `force_refresh=true` only when the user asks for a fresh read or
+when cache signatures show the source, prompt, depth, or requested modality has
+changed.
+
+For finished-video editorial work, scene detection and motion variance are
+guardrails, not story. Use them to avoid black frames, flash frames, corrupt
+ranges, and accidental cut points. Let transcript, sound events, complete
+thoughts, reactions, and decisive visual frames drive the actual edit.
+
+After creating or modifying a timeline variant, do a second pass before calling
+the work done:
+
+- `timeline(action="detect_gaps_overlaps")`
+- `timeline(action="source_range_report")`
+- `timeline_markers(action="get_thumbnail_image")` at important markers and cuts
+- Compare each marker name against the Resolve-rendered frame; revise the marker
+  or edit if the image contradicts the plan.
+
+Do not depend on personal, external, or workstation-specific editorial context.
+For this project, keep the editorial craft reference self-contained in
+`docs/guides/editorial-decision-guide.md` and keep this `SKILL.md` focused on
+operational use of the MCP.
+
+---
+
+## Color Memory And Decision-Making
+
+When the user asks for color correction, shot matching, look development, LUTs,
+DCTLs, DRX grades, Gallery stills, or color-group workflows, use
+`docs/guides/color-decision-guide.md` as the project-owned color reference.
+
+Be explicit about the API boundary:
+
+- Directly creatable/control surfaces: CDL values on an existing node, grade
+  versions, color-group assignment, LUT assignment on existing nodes, node
+  enable/cache state, LUT/DCTL assets, Gallery still import/export, and grade
+  copy/export helpers.
+- Opaque full-grade surfaces: copied grades, imported/exported `.drx` stills,
+  and manually built Resolve node graphs. These can carry full grades, but the
+  MCP applies or copies them as packages.
+- Not directly creatable from structured params: new node trees, Lift/Gamma/Gain
+  wheel values, log/HDR palette values, curves, qualifiers, power windows,
+  tracking, Color Warper, and detailed ResolveFX/OFX parameter edits.
+
+For safe color work, start with `timeline_item_color(action="grade_boundary_report")`,
+`timeline_item_color(action="grade_version_snapshot")`,
+`timeline_item_color(action="probe_node_graph")`, and a Resolve-rendered frame
+reference for the target shot or shots. Use thumbnails, contact sheets, Gallery
+stills, marker frames, or existing visual analysis reports before writing a
+grade, and cite the inspected frames in the response. When the API can safely
+provide them, compare matched untreated/bypass, current, and after frames at the
+same timecodes, then restore the previous active version or node-enabled state
+after any temporary bypass capture. Treat untreated frames as diagnostic
+evidence, not as permission to discard an existing creative grade.
+
+Prefer `safe_set_cdl` for small reversible primary corrections. Use DRX/stills
+or grade copy only when the user accepts whole-grade replacement/transfer
+semantics. Use DCTL/LUT authoring only for reusable mathematical transforms, not
+as a substitute for hand-built windows, qualifiers, or tracked secondaries. Do
+not apply blind/global grades unless the user explicitly asks for that. When the
+user asks to build on or adjust an existing grade, preserve the current
+grade/version as the starting point, create or switch to a recoverable
+adjustment version, and apply only incremental changes through supported
+controls. Do not reset grades, replace graphs, or apply DRX/copy-grade
+whole-grade artifacts unless replacement or transfer semantics are explicitly
+accepted. Distinguish Resolve's default one-node graph from an existing creative
+grade; only describe a creative grade when active tools, LUTs, or other grade
+state are present.
+
+For sequence-wide looks, prefer a duplicated timeline, batch creation of
+reference/current/look versions across all target clips, and one bulk Resolve
+script for repeated version, group, or CDL operations. Use color groups for shared
+scene-level intent only when they fit the work: group pre-clip for shared
+normalization, clip versions for shot-specific matching, and group post-clip for
+the creative look. Sampling can guide a first pass, but final handoff should
+state the reviewed scope; short sequences should be checked shot by shot.
+
+---
+
+## Page Context Requirements
+
+DaVinci Resolve is a page-based application. Certain operations only work on
+specific pages. Always confirm or switch pages before calling page-sensitive tools.
+
+| Operation category | Required page | How to switch |
+|---|---|---|
+| Color grading, node graphs, CDL | Color | `resolve_control(action="open_page", params={"page": "color"})` |
+| Gallery stills export, `grab_and_export` | Color, Gallery panel open | `resolve_control` + open Gallery panel in Workspace menu |
+| Fusion compositions (page comp) | Fusion | `resolve_control(action="open_page", params={"page": "fusion"})` |
+| Timeline editing, track operations | Edit or Cut | `resolve_control(action="open_page", params={"page": "edit"})` |
+| Fairlight audio | Fairlight | `resolve_control(action="open_page", params={"page": "fairlight"})` |
+| Render / deliver | Deliver | `resolve_control(action="open_page", params={"page": "deliver"})` |
+| Media import, storage browsing | Media | `resolve_control(action="open_page", params={"page": "media"})` |
+
+When a tool returns an unexpected `False` or an error about context, check whether
+you are on the correct page first.
+
+---
+
+## Tool Map
+
+### App Control
+
+**`resolve_control`** — App-level operations.
+
+Key actions:
+- `launch` — connect to or start Resolve; call this first if any tool returns a
+  "Not connected" error
+- `get_version` — returns `{product, version, version_string}`
+- `get_page` / `open_page(page)` — read or switch the active page
+- `get_keyframe_mode` / `set_keyframe_mode(mode)`
+- `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight
+  preset names
+- `quit` — terminates Resolve (destructive; confirm with user first)
+
+**`layout_presets`** — Save, load, export, import, delete UI layout presets.
+
+**`render_presets`** — Import and export render and burn-in presets.
+
+---
+
+### Project Management
+
+**`project_manager`** — CRUD on projects.
+
+Key actions: `list`, `get_current`, `create(name, media_location_path?)`,
+`load(name)`, `save`, `close`,
+`delete(name)`, `import_project(path)`, `export_project(name, path)`, `archive`,
+`restore`
+
+Project / Database / Archive kernel actions (v2.15.0+) add guarded project
+lifecycle, settings, database, preset, and archive boundary helpers:
+
+- `project_capabilities`
+- `probe_project_lifecycle`
+- `probe_project_settings(keys?, try_write?, dry_run?)`
+- `safe_project_create(name, media_location_path?, dry_run?)`
+- `safe_project_export(name, path, with_stills_and_luts?, dry_run?)`
+- `safe_project_import(path, name, dry_run?)`
+- `safe_project_archive(name, path, src_media=false, render_cache=false, proxy_media=false, dry_run?)`
+- `safe_project_restore(path, name, dry_run?)`
+- `safe_project_delete(name, close_current?, dry_run?)`
+- `safe_set_project_settings(settings, restore?, dry_run?)`
+- `project_settings_snapshot(name?)`
+- `database_capabilities`
+- `safe_set_current_database(db_info, dry_run?, allow_switch?)`
+- `preset_lifecycle_probe`
+- `project_boundary_report`
+
+Safe project actions require `_mcp_` names and temp paths by default. Database
+switching dry-runs by default because Resolve closes open projects when
+switching databases. Archive source media/cache/proxy flags are rejected unless
+explicitly opted in.
+
+**`project_manager_folders`** — Navigate project folders.
+
+Key actions: `list`, `get_current`, `create(name)`, `open(name)`, `goto_root`,
+`goto_parent`
+
+**`project_manager_database`** — Switch databases.
+
+Key actions: `get_current`, `list`, `set_current(db_info)`
+
+**`project_manager_cloud`** — Cloud projects (requires Resolve cloud
+infrastructure; most users will not have this).
+
+**`project_settings`** — Project metadata, settings, color groups, and misc
+operations on the open project.
+
+Key actions: `get_name`, `set_name(name)`, `get_setting(name?)`,
+`set_setting(name, value)`, `get_color_groups`, `add_color_group(name)`,
+`delete_color_group(name)`, `export_frame_as_still(path)`,
+`load_burnin_preset(name)`, `insert_audio(media_path, ...)`,
+`apply_fairlight_preset(preset_name)`
+
+---
+
+### Media
+
+**`media_storage`** — Browse mounted volumes and import files.
+
+Key actions: `get_volumes`, `get_subfolders(path)`, `get_files(path)`,
+`import_to_pool(items)` — `items` is a list of file path strings
+
+**`media_pool`** — Full Media Pool management.
+
+Key actions: `get_root_folder`, `get_current_folder`, `set_current_folder(path)`,
+`add_subfolder(name)`, `create_timeline(name)`, `import_timeline(path, options?)`,
+`import_media(paths)`, `delete_clips(clip_ids)`, `move_clips(clip_ids, target_path)`,
+`setup_multicam_timeline(name, clip_ids|angles, sync_mode?, include_audio?, dry_run?)`,
+`get_selected`, `set_selected(clip_id)`, `export_metadata(path, clip_ids?)`
+
+Media Pool / Ingest kernel actions (v2.8.0+) add safer agent-facing workflows:
+`ingest_capabilities`, `probe_media_pool`, `probe_ingest_item`,
+`safe_import_media`, `safe_import_sequence`, `safe_import_folder`,
+`organize_clips`, `copy_metadata`, `normalize_metadata`,
+`probe_clip_properties`, `metadata_field_inventory`, `safe_relink`,
+`safe_unlink`, `link_proxy_checked`, `link_full_resolution_checked`,
+`set_clip_marks`, `clear_clip_marks`, `copy_clip_annotations`,
+`setup_multicam_timeline`, and
+`media_pool_boundary_report`. See
+`docs/kernels/media-pool-ingest-kernel.md` for the live-tested support map.
+
+`setup_multicam_timeline` is a helper, not a native multicam API wrapper. It
+creates a source-safe stacked prep timeline with one angle per video track,
+optional matching audio tracks, and `stack_start`, `source_timecode`, or
+explicit `record_frame` placement. Native multicam clip creation, angle
+switching, and flattening remain Resolve UI workflows; see
+`docs/guides/multicam-setup-guide.md`.
+
+Note: `folder path` arguments use slash notation like `"Master/SubFolder"`.
+`"Master"` or `"/"` refers to the root folder.
+
+**`folder`** — Operations on a specific Media Pool folder.
+
+Key actions: `get_clips(path?)`, `get_subfolders(path?)`, `export(path?, export_path)`,
+`transcribe_audio(path?)`, `clear_transcription(path?)`
+
+**`media_pool_item`** — Read/write clip metadata and properties. All actions
+require a `clip_id` (the UUID returned by `GetUniqueId()`).
+
+Key actions: `get_name`, `get_metadata(key?)`, `set_metadata(key, value)`,
+`get_clip_property(key?)`, `set_clip_property(key, value)`, `get_clip_color`,
+`set_clip_color(color)`, `link_proxy(proxy_path)`, `replace_clip(path)`,
+`set_name(name)`, `link_full_resolution_media(path)`,
+`replace_clip_preserve_sub_clip(path)`, `monitor_growing_file`,
+`transcribe_audio`, `get_audio_mapping`, `get_mark_in_out`, `set_mark_in_out`
+
+**`media_pool_item_markers`** — Markers and flags on clips in the Media Pool.
+All actions require a `clip_id`.
+
+Key actions: `add(frame, color, name, note, duration)`, `get_all`, `delete_by_color(color)`,
+`delete_at_frame(frame)`, `add_flag(color)`, `get_flags`, `set_name(name)`
+
+**`media_analysis`** — Project-scoped media intelligence and guarded metadata publishing.
+
+Media Analysis and editorial-assist actions (v2.17.0+) add source-safe planning,
+report reuse, session-only execution, chat-context visual review, and
+timeline-level editorial helpers.
+
+Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
+`analyze_file`, `analyze_clip`, `analyze_bin`, `analyze_project`,
+`detect_sync_events`, `add_sync_event_markers`, `publish_clip_metadata`,
+`summarize`, `get_report`, `build_index`, `index_status`, `query_index`,
+`start_batch_job`, `run_batch_job_slice`, `batch_job_status`,
+`list_batch_jobs`, `cancel_batch_job`, `resume_batch_job`,
+`review_timeline_markers`, and `cleanup_artifacts`.
+The tool never installs
+dependencies and validates that outputs stay under
+`davinci-resolve-mcp-analysis` project roots rather than beside source media.
+Executed file/clip analysis defaults to session-only: scratch artifacts are
+removed after structured reports are returned to the MCP response. `persist=true`
+keeps reports under the project analysis root, and `keep_artifacts=true`
+preserves a session scratch run for inspection. Persisted analysis refreshes the
+local SQLite search index automatically unless `auto_build_index=false` is set;
+`build_index` remains the manual rebuild action for existing reports. `quick`
+uses ffprobe metadata; `standard` adds ffmpeg read-through checks,
+cut-boundary analysis from full-stream scene detection, flash-frame candidates,
+motion/variance scoring, analysis keyframes, and sidecar reports.
+By default, planning checks the active project's analysis root for existing
+reports and marks matching clips `skip_execution=true` when those reports already
+contain the requested technical, motion, transcription, and vision layers.
+Reports include cache signatures with source stat, depth, frame budget, prompt
+hash, and requested modalities. Use `force_refresh=true` for a fresh read,
+`max_report_age_days` for freshness limits, and `reuse_policy="fresh"` when
+unsigned older reports should not be reused. Pass `reuse_existing=false` only
+when the user explicitly wants to ignore memory.
+Transcription requires explicit opt-in. The `analyze_media` prompt opts into
+visual analysis by default and uses `vision.provider="chat_context"` when the
+MCP client supports sampling; pass `include_visuals=false` to opt out. For
+direct `media_analysis` tool calls, set `vision.enabled=true` explicitly when
+visual interpretation is needed. Standard/deep runs prioritize first/last usable
+frames plus before/after cut-boundary frames; those sampled frames are sent to
+the current chat/sampling model and the response is stored in the default
+structured JSON shape. If chat-context vision is unavailable, continue with
+technical/motion analysis and ask whether the user wants setup steps or a
+no-visual run. The local mock providers are for tests and do not send frames
+off-machine.
+Use `detect_sync_events` before multicam setup, deliverable QC, or single-camera
+sync review when the user needs likely 2-pop or slate-clap locations. It reads
+source audio through FFmpeg/FFprobe only, returns advisory frames/timecodes and
+per-file `record_offset` suggestions, and never installs FFmpeg automatically.
+It also returns marker suggestions; only call `add_sync_event_markers` after the
+user explicitly approves marker writes, and pass `confirm=true`.
+Use `publish_clip_metadata` when the user wants analysis to become searchable
+inside Resolve. It analyzes or reuses reports, proposes field-specific merges
+for `Description`, `Comments`, `Keywords`, `People`, and optional slate-derived
+fields, stores provenance in third-party metadata, defaults to `dry_run=true`,
+and writes Resolve metadata only when called with `confirm=true`.
+`review_timeline_markers` creates a labeled
+Resolve-rendered marker contact sheet plus JSON sidecar, and can request
+chat-context vision for marker/frame mismatch review.
+
+Before calling `analyze_*`, prefer `summarize` and `get_report` to discover
+existing reports for the active project. If reports exist, use them as the
+working memory for edit decisions and only request fresh analysis when a missing
+layer changes the decision. If a user is
+making story or audio-spine decisions and transcription is available but disabled,
+tell them that transcript analysis may materially improve the edit instead of
+silently skipping it. Resolve-native transcription changes project state; use it
+only when that mutation is intentional.
+
+---
+
+### Timelines
+
+**`timeline`** — Timeline operations: tracks, clips, import/export, generators.
+
+Key actions:
+- `list` — all timelines in the project
+- `get_current` — current timeline info
+- `set_current(index)` — switch timeline by 1-based index
+- `get_track_count(track_type)` — track_type: `"video"`, `"audio"`, `"subtitle"`
+- `add_track(track_type, sub_type?)` / `delete_track(track_type, index)`
+- `get_items(track_type, index)` — items on a track
+- `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`
+- `duplicate_clips(clip_ids?, selected?, target_track_index?, track_offset?, placement?, record_frame?, record_frame_offset?, copy_properties?, include_linked?)` —
+  duplicate existing video timeline items by re-appending the same Media Pool
+  item with the same source trim; `selected=True` uses Resolve's selected/current
+  item when available, `placement` supports `"same_time"`, `"offset"`,
+  `"at_playhead"`, `"track_above"`, `"after_source"`, and `"next_gap"`, and
+  `include_linked=True` duplicates linked audio and restores link state.
+  `copy_properties` can copy `transform`, `crop`, `composite`, `audio`,
+  `retime`, `dynamic_zoom`, `scaling`, `stabilization`, `clip_color`,
+  `markers`, `flags`, `enabled`, `cache`, `voice_isolation`, `fusion`,
+  `grades`, `takes`, and `keyframes`; `transitions` is accepted but reported
+  unsupported because Resolve's public scripting API does not expose transition
+  cloning. `copy_keyframes=True` adds the `keyframes` group.
+- `copy_clips(...)` / `move_clips(...)` — same safe append path; `move_clips`
+  deletes successfully duplicated source items afterward
+- `copy_range` / `duplicate_range` — copy exact video/audio source segments
+  from `start_frame`/`end_frame` or mark in/out to `record_frame`
+- `overwrite_range` — delete whole destination overlaps, then copy the exact
+  range segment
+- `lift_range` — delete whole items in a range; partial overlaps require
+  `allow_partial_item_delete=True` because Resolve does not expose a safe
+  partial lift primitive here
+- `story_spine_report` — read markers, source ranges, and audio/video structure
+  into an editor-facing beat report
+- `create_variant_from_ranges(name, ranges, markers?, cdl?, dry_run?)` — create
+  a guarded timeline variant from declarative source ranges, optional markers,
+  transforms, and CDL
+- `bulk_set_item_properties(ops, dry_run?, readback?)` — apply transforms,
+  crop/composite/audio/property groups to many timeline items in one call
+- `apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?)` — apply a
+  normalized CDL and/or copy a source grade to multiple video items
+- `thumbnail_contact_sheet` / `marker_thumbnail_review` — sample Resolve-rendered
+  thumbnails under the project analysis root for visual verification
+- `edit_kernel_capabilities` — report supported, partially supported, and
+  unsupported timeline edit kernel behavior
+- `probe_edit_kernel_item(clip_ids? selected? timeline_item?)` — read-only
+  capability/property probe for timeline items, including available item
+  methods, `GetProperty()` values, known property keys, keyframe counts, and
+  linked item summaries
+- `title_property_scan(clip_id|timeline_item_id|timeline_item)` — inspect
+  undocumented Edit-page title/generator `TimelineItem.GetProperty()` keys
+- `set_title_text(clip_id|..., text, property_key?, as_styled_xml?, try_plain_first?, try_heuristic_keys?, readback?)`
+  / `bulk_set_title_text(ops, ...)` — update title text via explicit or scanned
+  keys when the current Resolve build accepts the `SetProperty()` write
+- `export(path, type, subtype?)` — type: `"AAF"`, `"EDL"`, `"FCPXML"`, `"DRT"`, etc.
+- `insert_generator(name)`, `insert_title(name)`, `insert_fusion_title(name)`
+- `get_mark_in_out`, `set_mark_in_out(mark_in, mark_out, type?)`
+- `duplicate(name?)` — duplicate the current timeline
+- `get_voice_isolation_state(track_index)` / `set_voice_isolation_state`
+- `extract_source_frame_ranges(handles?, gap_max?, skip_extensions?)` — return
+  inclusive source frame ranges for current-timeline video clips, with fixed
+  handles or gap-only auto handles when `handles=0`
+
+Timeline Conform / Interchange kernel actions (v2.13.0+) add live-tested
+structure, interchange, comparison, missing-media, and relink-planning helpers:
+
+- `conform_capabilities`
+- `probe_timeline_structure(track_types?, include_markers?, include_clip_properties?)`
+- `detect_gaps_overlaps(track_types?, min_gap?)`
+- `source_range_report(handles?, merge?)`
+- `export_timeline_checked(path, format?|type?, subtype?, require_temp_path?, dry_run?)`
+- `import_timeline_checked(path, options?, timeline_name?, import_source_clips?, require_temp_path?, dry_run?)`
+- `compare_timelines(right_timeline_id?|right_timeline_index?|left_snapshot?, right_snapshot?)`
+- `probe_interchange_roundtrip(format?, output_dir?, cleanup_imported?)`
+- `detect_missing_media`
+- `build_relink_plan(search_roots)`
+- `conform_boundary_report`
+
+Audio / Fairlight kernel actions (v2.14.0+) add live-tested audio state,
+mapping, voice-isolation, sync, transcription, subtitle, and Fairlight boundary
+helpers:
+
+- `audio_capabilities`
+- `probe_audio_track(track_index?)`
+- `probe_audio_item(track_type?, track_index?, item_index?)`
+- `safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?)`
+- `audio_mix_capability_report(...)`
+- `voice_isolation_capabilities(track_index?, track_type?, item_index?)`
+- `audio_mapping_report(clip_ids?)`
+- `safe_auto_sync_audio(clip_ids|selected, settings?, dry_run?)`
+- `transcription_capabilities(clip_ids?|selected?)`
+- `subtitle_generation_probe(settings?, allow_generate?)`
+- `fairlight_boundary_report`
+
+**`timeline_markers`** — Markers and playhead on the current timeline.
+
+Key actions: `add(frame|frame_id|timecode?, color?, name?, note?, duration?)`, `get_all`,
+`get_current_timecode`, `set_current_timecode(timecode)`,
+`get_current_video_item`, `get_thumbnail`, `get_thumbnail_image`
+
+Review Annotation kernel actions (v2.10.0+) add a unified review layer across
+timeline, timeline item, and media pool item scopes: `annotation_capabilities`,
+`probe_annotations`, `normalize_marker_payload`, `copy_annotations`,
+`move_annotations`, `sync_marker_custom_data`, `clear_annotations_by_scope`,
+`export_review_report`, and `annotation_boundary_report`. See
+`docs/kernels/review-annotation-kernel.md` for the live-tested scope and boundary map.
+
+For `add`, omit `frame`/`timecode` to create the marker at the current playhead.
+The compound tool accepts `frame`, `frame_id`, and `frameId` aliases.
+
+Note: `get_thumbnail` returns raw pixel data from `GetCurrentClipThumbnailImage()`.
+The dictionary includes `data` (raw bytes as a Python bytes-like object),
+`format`, `width`, `height`, `noOfComponents`, and `depth`. This reflects the
+current frame as rendered by Resolve — including any color grading or effects
+applied — which is different from reading the source file directly.
+
+Use `get_thumbnail_image` when the MCP client can display image content directly.
+It converts the same Resolve thumbnail payload to PNG bytes without writing a
+file to disk.
+
+**`timeline_ai`** — AI/ML analysis on the current timeline.
+
+Key actions: `create_subtitles(settings?)`, `detect_scene_cuts`,
+`grab_still`, `grab_all_stills(source?)`, `analyze_dolby_vision`
+
+---
+
+### Timeline Items
+
+Timeline items are identified by `track_type`, `track_index`, and `item_index`
+(all default to `"video"`, `1`, `0` respectively — the first clip on the first
+video track). Always retrieve item IDs via `timeline.get_items` before operating
+on specific items.
+
+**`timeline_item`** — Properties, transform, speed, audio, keyframes.
+
+Key actions:
+- `get_property(key?)` / `set_property(key, value)` — raw property access
+- `get_name` / `set_name(name)`
+- `get_duration`, `get_start`, `get_end`
+- `get_retime` / `set_retime(process?, motion_estimation?)`
+  - process: `"nearest"`, `"frame_blend"`, `"optical_flow"` (or 0–3)
+  - motion_estimation: integer 0–6
+- `get_transform` / `set_transform(Pan?, Tilt?, ZoomX?, ZoomY?, RotationAngle?, ...)`
+- `get_crop` / `set_crop(CropLeft?, CropRight?, CropTop?, CropBottom?, ...)`
+- `get_composite` / `set_composite(Opacity?, CompositeMode?)`
+- `get_audio` / `set_audio(Volume?, Pan?, AudioSyncOffset?)`
+- `get_voice_isolation_state` / `set_voice_isolation_state(state)` — Resolve
+  20.1+; audio timeline items only
+- `get_keyframes(property)`, `add_keyframe(property, frame, value)`,
+  `modify_keyframe`, `delete_keyframe`, `set_keyframe_interpolation`
+  - interpolation values: `"Linear"`, `"Bezier"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`
+- `get_unique_id` — use this to get the ID for other tool calls
+- `get_media_pool_item` — get the source clip from the Media Pool
+
+**`timeline_item_markers`** — Markers, flags, clip color on timeline items.
+
+**`timeline_item_fusion`** — Fusion comp management on timeline items.
+
+Key actions: `add_comp`, `get_comp_count`, `get_comp_names`, `export_comp(path, index)`,
+`import_comp(path)`, `delete_comp(name)`, `load_comp(name)`, `rename_comp`,
+`get_cache_enabled`, `set_cache(value)` — value: `"Auto"`, `"On"`, `"Off"`
+
+**`timeline_item_color`** — Color grading on timeline items. Requires Color page
+for most operations.
+
+Key actions:
+- `set_cdl(cdl)` — cdl: `{NodeIndex, Slope, Offset, Power, Saturation}`
+  - Slope/Offset/Power can be arrays `[R, G, B]` or strings like `"1.0 1.0 1.0"`
+- `add_version(name, type?)`, `load_version(name, type?)`, `get_version_names(type?)`
+  - type: `0` = local, `1` = remote
+- `assign_color_group(group_name)`, `remove_from_color_group`
+- `export_lut(type, path)`
+- `reset_all_node_colors` — Resolve 20.2+; resets node colors for the active
+  clip version
+- `stabilize`, `smart_reframe`
+- `create_magic_mask(mode)` — mode: `"F"` forward, `"B"` backward, `"BI"` bidirectional
+  (requires DaVinci Neural Engine and Color page)
+
+Color / Grade kernel actions (v2.11.0+) add safer grade inspection and
+boundary helpers: `grade_capabilities`, `probe_grade_item`,
+`probe_node_graph`, `safe_set_cdl`, `safe_copy_grade`, `safe_apply_drx`,
+`safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`,
+`color_group_capabilities`, `gallery_capabilities`, and
+`grade_boundary_report`. See `docs/kernels/color-grade-kernel.md` for the live-tested
+support map, and `docs/guides/color-decision-guide.md` for the practical distinction
+between direct API color controls and opaque full-grade artifacts.
+
+**`timeline_item_takes`** — Take management.
+
+Key actions: `add(clip_id, start_frame?, end_frame?)`, `get_count`,
+`get_selected_index`, `select(index)`, `delete(index)`, `finalize`
+
+---
+
+### Gallery
+
+**`gallery`** — Gallery album management.
+
+Key actions: `get_still_albums`, `get_current_album`, `set_current_album(album_index)`,
+`create_still_album`, `create_power_grade_album`
+
+**`gallery_stills`** — Manage stills within an album. Requires Color page.
+
+Key actions:
+- `get_stills(album_index?)` — returns count
+- `get_label(still_index)` / `set_label(still_index, label)`
+- `import_stills(paths)` — paths to `.drx` files
+- `export_stills(folder_path, prefix?, format?, album_index?)`
+  - formats: `dpx`, `cin`, `tif`, `jpg`, `png`, `ppm`, `bmp`, `xpm`, `drx`
+- `grab_and_export(folder_path, prefix?, format?, album_index?, cleanup?)` —
+  grabs a still from the current frame and exports it in one atomic call.
+  Returns `{files, format, folder, cleaned_up}` where each file entry includes
+  `data_base64` for image files and `data` (text) for `.drx` grade files.
+  `cleanup` defaults to `true` — files are deleted from disk after being inlined.
+  Requires Color page with Gallery panel visible.
+- `delete_stills(still_indices)`
+
+---
+
+### Node Graphs
+
+**`graph`** — Node graph operations on timeline, timeline item, or color group.
+
+The `source` parameter controls which graph you target:
+- `"timeline"` (default) — the timeline node graph
+- `"item"` — a specific timeline item (needs `track_type`, `track_index`, `item_index`)
+- `"color_group_pre"` / `"color_group_post"` — group pre/post graphs (needs `group_name`)
+
+Key actions: `get_num_nodes(source?)`, `set_lut(node_index, lut_path, source?)`,
+`get_lut(node_index, source?)`, `get_node_label(node_index, source?)`,
+`set_node_enabled(node_index, enabled, source?)`,
+`apply_grade_from_drx(path, grade_mode?, source?)` — grade_mode: `0`=no keyframes,
+`1`=source timecode aligned, `2`=start frames aligned,
+`reset_all_grades(source?)`
+
+**`color_group`** — Manage color groups.
+
+Key actions: `list`, `get_name(group_name)`, `set_name(group_name, new_name)`,
+`get_clips(group_name)`, `get_pre_clip_graph(group_name)`,
+`get_post_clip_graph(group_name)`
+
+---
+
+### Fusion
+
+**`fusion_comp`** — Fusion composition node graph operations.
+
+Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, or
+`timeline_item={track_type, track_index, item_index}`) or from the active Fusion
+page comp (omit timeline scope).
+
+Key actions:
+- `add_tool(tool_type, x?, y?, name?)` — common types: `Merge`, `Background`,
+  `TextPlus`, `Transform`, `Blur`, `ColorCorrector`, `RectangleMask`,
+  `EllipseMask`, `Tracker`, `MediaIn`, `MediaOut`, `Glow`, `DeltaKeyer`,
+  `UltraKeyer`, `FilmGrain`, `CornerPositioner`
+- `delete_tool(tool_name)`, `get_tool_list(type?)`, `find_tool(name)`
+- `connect(target_tool, input_name, source_tool, output_name?)`
+- `disconnect(tool_name, input_name)`
+- `set_input(tool_name, input_name, value, time?)` /
+  `get_input(tool_name, input_name, time?)`
+- `get_inputs(tool_name)` / `get_outputs(tool_name)`
+- `set_attrs(tool_name, attrs)` / `get_attrs(tool_name)`
+- `add_keyframe(tool_name, input_name, time, value)`
+- `get_comp_info`, `set_frame_range(start, end)`, `render`
+- `start_undo(name?)` / `end_undo(keep?)`
+- `bulk_set_inputs(ops)` — batch set inputs across multiple timeline item comps in
+  one call; each op requires timeline scope plus `tool_name`, `input_name`, `value`
+
+Fusion Composition kernel actions (v2.12.0+) add safer graph inspection and
+mutation wrappers around the raw Fusion API:
+
+- `fusion_graph_capabilities`
+- `probe_fusion_comp(include_io?, max_tools?)`
+- `probe_fusion_tool(tool_name, include_io?)`
+- `safe_add_tool(tool_type, name?, dry_run?)`
+- `safe_set_inputs(tool_name, inputs, readback?)`
+- `safe_connect_tools(target_tool, input_name, source_tool, dry_run?)`
+- `fusion_boundary_report(include_io?)`
+
+---
+
+### Render
+
+**`render`** — Render pipeline: jobs, presets, formats, codecs.
+
+Key actions: `add_job`, `list_jobs`, `delete_job(job_id)`, `delete_all_jobs`,
+`start(job_ids?, interactive?)`, `stop`, `is_rendering`, `get_formats`,
+`get_codecs(format)`, `set_format_and_codec(format, codec)`,
+`get_resolutions(format, codec)`, `set_settings(settings)`,
+`list_presets`, `load_preset(name)`, `save_preset(name)`,
+`quick_export_presets`, `quick_export(preset, params?)`
+
+Render / Deliver kernel actions (v2.9.0+) add planning and safety layers:
+`render_capabilities`, `probe_render_matrix`, `probe_render_settings`,
+`validate_render_settings`, `safe_set_render_settings`,
+`prepare_render_job`, `render_job_lifecycle_probe`,
+`quick_export_capabilities`, `safe_quick_export`, and
+`export_render_boundary_report`. See `docs/kernels/render-deliver-kernel.md` for the
+live-tested format/codec, settings, job, and Quick Export boundary map.
+
+---
+
+## Common Workflows
+
+### 1. Connect and verify
+
+```
+resolve_control(action="launch")
+resolve_control(action="get_version")
+resolve_control(action="mcp_update_status")
+setup(action="get_defaults")
+resolve_control(action="get_page")
+```
+
+Always call `launch` first in a new session. It is safe to call when Resolve is
+already running.
+
+Use `setup(action="schema")`, `setup(action="get_defaults")`, and
+`setup(action="set_defaults")` when the user wants durable conversation
+defaults for media analysis, metadata publishing, timed markers, report style,
+or MCP update behavior. Setup defaults may shape future tool parameters, but
+confirmed Resolve project writes still require the relevant action's explicit
+confirmation flag.
+
+### 2. Open a project and navigate timelines
+
+```
+project_manager(action="list")
+project_manager(action="load", params={"name": "My Film"})
+timeline(action="list")
+timeline(action="set_current", params={"index": 2})
+timeline(action="get_current")
+```
+
+### 3. Add clips to Media Pool and build a timeline
+
+```
+media_storage(action="get_volumes")
+media_storage(action="import_to_pool", params={"items": ["/path/to/clip.mp4"]})
+media_pool(action="get_current_folder")
+media_pool(action="create_timeline", params={"name": "Assembly"})
+media_pool(action="get_selected")
+media_pool(action="append_to_timeline", params={"clip_ids": ["<uuid>", ...]})
+media_pool(action="safe_import_sequence", params={
+  "pattern": "/path/to/frames/shot_%04d.dpx",
+  "start_index": 1001,
+  "end_index": 1048,
+  "target_folder": "Master/Plates"
+})
+media_pool(action="media_pool_boundary_report", params={"selected": True, "depth": 2})
+# Positioned append (MediaPool.AppendToTimeline([{clipInfo}, ...])) — e.g. rebuild a subtitle row after delete_clips
+media_pool(action="append_to_timeline", params={"clip_infos": [
+  {"clip_id": "<uuid>", "start_frame": 0, "end_frame": 100, "record_frame": 1200, "track_index": 4}
+]})
+```
+
+### 4. Inspect and annotate timeline items
+
+```
+timeline(action="get_items", params={"track_type": "video", "index": 1})
+timeline(action="duplicate_clips", params={
+  "clip_ids": ["<timeline-item-uuid>"], "target_track_index": 2, "record_frame_offset": 120
+})
+timeline(action="duplicate_clips", params={
+  "selected": True,
+  "placement": "track_above",
+  "include_linked": True,
+  "copy_properties": ["transform", "crop", "composite", "audio", "dynamic_zoom", "scaling", "stabilization", "clip_color", "markers", "enabled"],
+  "copy_keyframes": True
+})
+timeline(action="probe_edit_kernel_item", params={"selected": True})
+timeline(action="copy_range", params={
+  "start_frame": 110, "end_frame": 130, "record_frame": 900,
+  "track_types": ["video", "audio"], "target_track_index": 2
+})
+timeline_item(action="get_name", params={"track_type": "video", "track_index": 1, "item_index": 0})
+timeline_item(action="get_property", params={"track_type": "video", "track_index": 1, "item_index": 0})
+timeline_markers(action="add", params={"color": "Blue", "note": "Review this"})
+timeline_item_markers(action="add", params={"frame": 100, "color": "Blue", "name": "Review", "note": "Check this", "duration": 1, "track_type": "video", "track_index": 1, "item_index": 0})
+```
+
+For an exhaustive live boundary map of the timeline edit kernel, run:
+
+```
+python3.11 tests/live_duplicate_clips_validation.py --output-dir /tmp/timeline-kernel-probe
+```
+
+The live harness first validates duplicate/range edit behavior, then runs the
+exhaustive probe. It creates disposable projects with synthetic media, emits
+JSON and Markdown reports, and classifies each API surface as `supported`,
+`partially_supported`, `read_only`, `write_only_unverifiable`,
+`version_or_page_dependent`, `unsupported`, `not_applicable`, or `error`.
+See `docs/kernels/timeline-edit-kernel.md` for the maintained support map and current
+Resolve API limitations.
+
+For the Media Pool / Ingest boundary map, run:
+
+```
+python3.11 tests/live_media_pool_ingest_validation.py --output-dir /tmp/media-pool-ingest-probe
+```
+
+The harness creates a disposable project, generates synthetic video/audio/still
+and image-sequence fixtures, probes safe import/metadata/annotation/link
+helpers, writes JSON and Markdown reports, deletes the project, and removes the
+generated media directory. See `docs/kernels/media-pool-ingest-kernel.md`.
+
+For the Review Annotation boundary map, run:
+
+```
+python3.11 tests/live_review_annotation_validation.py --output-dir /tmp/review-annotation-probe
+```
+
+The harness creates a disposable project, generates synthetic video/audio media,
+probes timeline, timeline item, and media pool item marker/flag/color/report
+behavior, writes JSON and Markdown reports, deletes the project, and removes the
+generated media directory. See `docs/kernels/review-annotation-kernel.md`.
+
+### 5. Color grading
+
+```
+resolve_control(action="open_page", params={"page": "color"})
+timeline_item_color(action="set_cdl", params={"cdl": {"NodeIndex": 1, "Slope": [1.1, 1.0, 0.9], "Offset": [0.0, 0.0, 0.0], "Power": [1.0, 1.0, 1.0], "Saturation": 1.0}, "track_type": "video", "track_index": 1, "item_index": 0})
+timeline_item_color(action="add_version", params={"name": "Grade v2", "track_type": "video", "track_index": 1, "item_index": 0})
+timeline_item_color(action="grade_boundary_report", params={"track_type": "video", "track_index": 1, "item_index": 0})
+timeline_item_color(action="safe_export_lut", params={"type": "33ptcube", "path": "/tmp/look.cube", "track_type": "video", "track_index": 1, "item_index": 0})
+```
+
+For the Color / Grade boundary map, run:
+
+```
+python3.11 tests/live_color_grade_validation.py --output-dir /tmp/color-grade-probe
+```
+
+The harness creates a disposable project, generates synthetic color-bar media,
+probes grade, node graph, version, copy, LUT, Gallery, and color-group
+behavior, writes JSON and Markdown reports, deletes the project, and removes
+generated media and exported probe files. See `docs/kernels/color-grade-kernel.md`.
+
+### 6. Grab a still and read the grade data
+
+```
+resolve_control(action="open_page", params={"page": "color"})
+gallery_stills(action="grab_and_export", params={"folder_path": "/tmp/stills", "format": "jpg"})
+```
+
+The response includes `files[].data_base64` (the image as base64) and
+`files[].data` for the companion `.drx` grade file (plain text XML). The
+image reflects the color-graded frame as Resolve sees it, not the raw source.
+
+### 7. Export the timeline
+
+```
+timeline(action="export", params={"path": "/tmp/export.edl", "type": "EDL", "subtype": "CMX3600"})
+timeline(action="export", params={"path": "/tmp/export.fcpxml", "type": "FCPXML"})
+timeline(action="export_timeline_checked", params={"path": "/tmp/export.drt", "format": "drt"})
+timeline(action="detect_gaps_overlaps")
+timeline(action="conform_boundary_report", params={"handles": 8})
+```
+
+For the Timeline Conform / Interchange boundary map, run:
+
+```
+python3.11 tests/live_timeline_conform_validation.py --output-dir /tmp/timeline-conform-probe
+```
+
+The harness creates a disposable project, generates synthetic media, builds a
+gapped timeline, probes structure, source ranges, gap/overlap detection,
+interchange export/import/round-trip behavior, synthetic missing-media relink
+planning, writes reports, deletes the project, and removes generated media.
+See `docs/kernels/timeline-conform-interchange-kernel.md`.
+
+For the Audio / Fairlight boundary map, run:
+
+```
+python3.11 tests/live_audio_fairlight_validation.py --output-dir /tmp/audio-fairlight-probe
+```
+
+The harness creates a disposable project, generates synthetic video and audio
+media, probes track/item audio state, mappings, voice isolation, property
+writes, auto-sync, transcription, subtitle generation, Fairlight preset listing,
+audio insertion, writes reports, deletes the project, and removes generated
+media. See `docs/kernels/audio-fairlight-kernel.md`.
+
+### 8. Add and start a render job
+
+```
+render(action="get_formats")
+render(action="probe_render_matrix")
+render(action="set_format_and_codec", params={"format": "QuickTime", "codec": "H.265 Master"})
+render(action="validate_render_settings", params={"settings": {"TargetDir": "/tmp/renders", "CustomName": "review", "SelectAllFrames": true}, "require_temp_target": true})
+render(action="prepare_render_job", params={"target_dir": "/tmp/renders", "settings": {"CustomName": "review", "SelectAllFrames": true}})
+render(action="add_job")
+render(action="list_jobs")
+render(action="start")
+render(action="is_rendering")
+```
+
+For the Render / Deliver boundary map, run:
+
+```
+python3.11 tests/live_render_deliver_validation.py --output-dir /tmp/render-deliver-probe
+```
+
+The harness creates a disposable project, generates a synthetic timeline, probes
+format/codec/resolution compatibility, validates settings, runs a tiny temp
+render job, writes reports, deletes the project, and removes generated media and
+render outputs.
+
+### 9. Apply a Fusion effect to a timeline item
+
+```
+timeline_item_fusion(action="add_comp", params={"track_type": "video", "track_index": 1, "item_index": 0})
+fusion_comp(action="add_tool", params={"tool_type": "Glow", "timeline_item": {"track_type": "video", "track_index": 1, "item_index": 0}})
+fusion_comp(action="set_input", params={"tool_name": "Glow1", "input_name": "Gain", "value": 0.8, "timeline_item": {"track_type": "video", "track_index": 1, "item_index": 0}})
+fusion_comp(action="fusion_boundary_report", params={"timeline_item": {"track_type": "video", "track_index": 1, "item_index": 0}})
+```
+
+For the Fusion Composition boundary map, run:
+
+```
+python3.11 tests/live_fusion_composition_validation.py --output-dir /tmp/fusion-composition-probe
+```
+
+The harness creates a disposable project, generates synthetic video media,
+probes timeline item comp creation, safe tool creation, input writes, graph
+inspection, connections, bulk writes, frame range, and comp export, writes
+reports, deletes the project, and removes generated media. See
+`docs/kernels/fusion-composition-kernel.md`.
+
+---
+
+## Error Handling and Recovery
+
+| Error message | Cause | Fix |
+|---|---|---|
+| `"Not connected to DaVinci Resolve"` | Resolve is not running or scripting is disabled | Call `resolve_control(action="launch")`, wait, retry |
+| `"No project open"` | No project is currently loaded | Call `project_manager(action="load", params={"name": "..."})` |
+| `"No current timeline"` | Project has no timeline set as current | Call `timeline(action="set_current", params={"index": 1})` |
+| `"No item at index N"` | `item_index` out of range for the track | Call `timeline(action="get_items", ...)` first to find valid indices |
+| `"Clip not found"` | Stale or wrong `clip_id` | Re-fetch IDs via `media_pool(action="get_selected")` or `folder(action="get_clips")` |
+| `"Gallery not available"` | Not on Color page | `resolve_control(action="open_page", params={"page": "color"})` |
+| `"GrabStill failed"` | Not on Color page or no clip under playhead | Switch to Color page, move playhead over a clip |
+| `"ExportStills failed"` | Gallery panel not open in UI | Instruct user to open Workspace > Gallery |
+| `"Tool '...' not found"` | Wrong tool name in Fusion comp | Use `fusion_comp(action="get_tool_list")` to list available tools |
+| `"Color group '...' not found"` | Group name mismatch | Use `color_group(action="list")` first |
+
+When a tool returns `{"success": False}` without an error key, the underlying
+Resolve API returned `False`. This usually means a precondition was not met
+(wrong page, wrong state, context missing). Check the API reference in
+`docs/reference/resolve_scripting_api.txt` for the specific method.
+
+---
+
+## Known Gotchas
+
+**Resolve API object lifetimes** — Objects like timelines, clips, and color groups
+returned by the API are live references that can become stale if the project state
+changes (e.g., the user deletes a timeline). Always re-fetch IDs after any
+destructive action.
+
+**`SetName` on the active timeline** — `timeline(action="set_name")` returns
+`False` if you try to rename the currently active timeline. Switch to a different
+timeline first, rename, then switch back.
+
+**`DeleteProject`** — Returns `False` if the project is currently open. Close it
+first.
+
+**CDL value format** — `set_cdl` accepts Slope/Offset/Power as arrays `[R, G, B]`,
+tuples, or space-separated strings like `"1.0 1.0 1.0"`. All forms are normalized
+internally.
+
+**`GetNodeGraph(0)`** — Passing `0` as `layer_index` to `GetNodeGraph` on a
+timeline item returns `False` in Resolve. Use `get_node_graph` without a
+`layer_index` to get the default graph.
+
+**Gallery export requires the Gallery panel visible** — `ExportStills` only works
+if the Gallery panel is open in the Resolve UI on the Color page. Instruct the
+user to open it via Workspace menu if export fails.
+
+**Python version** — Resolve's scripting library works best with Python 3.10–3.12.
+Python 3.13+ may cause `scriptapp("Resolve")` to return `None` due to ABI
+incompatibilities.
+
+**Resolve version guards** — Resolve 20-specific actions return a clear
+`requires DaVinci Resolve 20.x+` error when called against older builds. Resolve
+19.1.3 remains the compatibility baseline; Resolve 20 additions were live-tested
+on Resolve Studio 20.3.2.
+
+**Source media integrity** — Do not transcode, convert, create proxies, or write
+derivatives of source media unless the user explicitly asks. Analysis and tests
+should write sidecars or synthetic fixtures, never modify camera originals.
+
+**Windows multi-Python setups** — On Windows with multiple Python installations,
+Resolve 20.3 may crash on import unless `PYTHONHOME` is set to the interpreter
+used to build the venv. The installer handles this automatically; manual configs
+may need it added.
+
+**`item_index` is 0-based** — When specifying `item_index` in params, `0` is the
+first item on the track, not `1`.
+
+**`track_index` is 1-based** — Track indices start at `1`, not `0`.
+
+**Fusion comp scope** — `fusion_comp` actions without a timeline scope target the
+active composition on the Fusion page. If you intend to operate on a specific
+clip's comp, always pass `clip_id`, `timeline_item_id`, or `timeline_item`.
+
+---
+
+## Seeing What Resolve Sees (Visual Context)
+
+The server provides two mechanisms to inspect a frame as Resolve has processed it,
+including color grading, effects, and compositing — not just the raw source file.
+
+**`timeline_markers(action="get_thumbnail")`** — Returns raw thumbnail data at
+the current playhead position. The response is a dictionary with keys `data`,
+`format`, `width`, `height`, `noOfComponents`, and `depth`.
+
+**`timeline_markers(action="get_thumbnail_image")`** — Converts the same current
+frame thumbnail to PNG bytes and returns MCP image content without writing a file.
+
+**`gallery_stills(action="grab_and_export", params={...})`** — Grabs a still from
+the current frame on the Color page and returns the image encoded as base64 in the
+response (`files[].data_base64`). This is the most reliable way to get a
+color-graded frame preview as a standard image format (jpg, tif, dpx, etc.)
+that can be passed directly to a vision-capable AI model. Requires the Color page
+with Gallery panel visible.
+
+To use `grab_and_export` for visual inspection:
+
+```
+resolve_control(action="open_page", params={"page": "color"})
+gallery_stills(action="grab_and_export", params={
+  "folder_path": "/tmp/resolve-preview",
+  "format": "jpg",
+  "cleanup": true
+})
+```
+
+The response `files[0].data_base64` is a standard JPEG, base64-encoded. Feed it
+to a vision model to describe what Resolve is displaying — including all grading
+and effects applied to the source.
+
+---
+
+## Clip ID Reference Pattern
+
+Many tools require a `clip_id` (the UUID of a Media Pool clip) or a timeline item
+identified by `track_type + track_index + item_index`. Use this pattern to resolve
+both:
+
+```
+# List clips in the Media Pool
+folder(action="get_clips")
+# -> returns [{name, id}, ...]  — use id as clip_id
+
+# List items on a timeline track
+timeline(action="get_items", params={"track_type": "video", "index": 1})
+# -> returns [{name, id, start, end, duration}, ...]
+# Use track_type="video", track_index=1, item_index=<position in this list>
+# Or use id to look up later via timeline_item(action="get_unique_id", ...)
+```
+
+---
+
+## API Coverage
+
+All 336 non-deprecated methods of the DaVinci Resolve Scripting API are covered.
+331 methods have been live-tested across Resolve 19.1.3 Studio and Resolve
+20.3.2 Studio. Five methods require infrastructure not available in typical
+setups:
+
+| Method | Requires |
+|---|---|
+| `ProjectManager.CreateCloudProject` | Resolve cloud infrastructure |
+| `ProjectManager.LoadCloudProject` | Resolve cloud infrastructure |
+| `ProjectManager.ImportCloudProject` | Resolve cloud infrastructure |
+| `ProjectManager.RestoreCloudProject` | Resolve cloud infrastructure |
+| `Timeline.AnalyzeDolbyVision` | HDR / Dolby Vision content |
+
+The full API reference is in `docs/reference/resolve_scripting_api.txt`.