davinci-resolve-mcp 2.23.0

package/docs/kernels/extension-authoring-kernel.md

@@ -0,0 +1,101 @@
+# Extension Authoring Kernel
+
+The Extension Authoring kernel turns the existing `fuse_plugin`, `dctl`, and
+`script_plugin` tools into a lifecycle-aware boundary layer for generated
+Resolve extensions.
+
+Kernel actions are exposed through `script_plugin` as the cross-extension
+orchestrator. The raw authoring tools remain available for direct file
+operations.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with only
+MCP-marked `_mcp_` Fuse, DCTL, ACES DCTL, and Resolve-page script files. Final
+release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 14 |
+| `partially_supported` | 1 |
+| `unsupported` | 1 |
+| `not_applicable` | 0 |
+| `version_or_page_dependent` | 0 |
+| `error` | 0 |
+
+The unsupported result is intentional: safe install rejects provided source that
+does not include the expected MCP marker.
+
+## Added Actions
+
+All kernel actions are exposed through `script_plugin`.
+
+| Action | Purpose |
+| --- | --- |
+| `extension_capabilities` | Report Fuse, DCTL, script paths, template kinds, MCP markers, lifecycle rules, and safety guards. |
+| `probe_fuse_lifecycle` | Generate, validate, optionally install/read/list/remove a Fuse template. |
+| `probe_dctl_lifecycle` | Generate, validate, optionally install/read/list/remove a LUT or ACES DCTL template. |
+| `probe_script_lifecycle` | Generate, validate, optionally install/read/list/execute/remove a Resolve-page script. |
+| `safe_install_extension` | Install Fuse, DCTL, or script source/templates with `_mcp_` name and marker guards. |
+| `safe_remove_extension` | Remove Fuse, DCTL, or script files only when the file is MCP-marked by default. |
+| `refresh_or_restart_required` | Classify whether an extension needs LUT refresh, menu refresh, UI reload, or Resolve restart. |
+| `extension_boundary_report` | Return lifecycle classifications, template validation matrix, and dry-run probes. |
+
+## Lifecycle Map
+
+| Surface | Install Target | Live Pickup | Restart |
+| --- | --- | --- | --- |
+| Fuse | Fusion Fuses directory | Existing Fuses can be UI-reloaded from Inspector; MCP cannot trigger it. | Required for new Fuse registration. |
+| Regular DCTL | LUT directory | `project_settings.refresh_luts` picks it up. | Not required for LUT-category DCTLs. |
+| ACES IDT/ODT DCTL | ACES Transforms IDT/ODT | Not picked up by LUT refresh. | Required. |
+| Resolve-page script | Fusion/Scripts category directory | Workspace Scripts menu refreshes when opened. | Not required. |
+| Inline Python script | Temp file subprocess | Captured synchronously. | Not required. |
+| Inline Lua script | Temp Lua file via `fusion.RunScript` | Captured through Fusion app data bridge. | Not required. |
+
+## Supported Findings
+
+- Fuse template generation, validation, install, read, MCP-managed list, and
+  safe marker-enforced remove worked.
+- Regular LUT DCTL template generation, validation, install into `LUT/MCP`,
+  read, list, `project_settings.refresh_luts`, and safe remove worked.
+- ACES IDT DCTL template generation, install into `ACES Transforms/IDT/MCP`,
+  read, list, and safe remove worked. It remains restart-required before Resolve
+  can use the transform.
+- Python Resolve-page script template generation, install, read, list, execute,
+  stdout/stderr capture, and safe remove worked.
+- `script_plugin.run_inline` worked for Python with stdout capture.
+- `script_plugin.run_inline` worked for Lua with stdout and return-value capture.
+- The template matrix generated and validated every Fuse, DCTL, and script
+  template kind.
+- Safe install rejected unmarked provided source by default.
+
+## Boundaries
+
+- Installed Lua script execution through `fusion.RunScript(path)` returned
+  `success=False` in the release probe, even though install/read/list/remove
+  worked and inline Lua execution worked. Use `run_inline(language="lua")` when
+  captured output/return values matter.
+- New Fuses still require a Resolve restart to appear as registered Fusion
+  tools. The MCP can install/remove files but cannot force Fusion to register a
+  new Fuse in-process.
+- ACES IDT/ODT DCTLs are scanned at Resolve startup. `RefreshLUTList` is only
+  appropriate for LUT-category DCTLs.
+- Template validation is structural/parser-level. It does not prove a Fuse
+  renders correctly after restart or that every DCTL compiles on every GPU
+  backend.
+- Safe remove refuses to delete unmarked extension files unless
+  `require_marker=False` is explicitly passed.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+python3.11 tests/live_extension_authoring_validation.py --output-dir /tmp/extension-authoring-probe
+```
+
+The harness creates a disposable `_mcp_` project, installs and removes a
+generated Fuse, regular DCTL, ACES DCTL, Python script, and Lua script, probes
+inline Python/Lua execution, writes JSON and Markdown reports, deletes the
+project, and removes its temp work directory.
+
+Use `--keep-open` only when you intentionally want to inspect the disposable
+project by hand.

package/docs/kernels/fusion-composition-kernel.md

@@ -0,0 +1,91 @@
+# Fusion Composition Kernel
+
+The Fusion Composition kernel expands `fusion_comp` into a safer graph
+inspection, tool creation, input write, connection, and boundary-report layer
+for timeline item Fusion comps and active Fusion page comps.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with a
+disposable `_mcp_fusion_composition_probe_*` project and generated synthetic
+video media. Final release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 18 |
+| `partially_supported` | 0 |
+| `unsupported` | 0 |
+| `version_or_page_dependent` | 0 |
+| `not_applicable` | 0 |
+| `error` | 0 |
+
+## Added Actions
+
+All actions are exposed through `fusion_comp`.
+
+| Action | Purpose |
+| --- | --- |
+| `fusion_graph_capabilities` | Return current comp summary, common tool IDs, supported graph operations, and known boundaries. |
+| `probe_fusion_comp` | Snapshot composition attrs, tool count, and tool summaries, optionally including input/output ports. |
+| `probe_fusion_tool` | Inspect one tool by name, including attrs and optional input/output metadata. |
+| `safe_add_tool` | Validate a tool type, add it with optional naming, and return a normalized tool summary; supports dry run. |
+| `safe_set_inputs` | Batch write inputs on one tool with optional readback classification. |
+| `safe_connect_tools` | Validate source/target tools before connecting a source output to a target input. |
+| `fusion_boundary_report` | Return graph capabilities plus a composition snapshot for the selected comp scope. |
+
+The pre-existing `bulk_set_inputs` action remains the batch path for applying
+input writes across multiple explicitly scoped timeline-item Fusion comps.
+
+## Scope Matrix
+
+| Scope | Probe Support | Mutation Support | Notes |
+| --- | --- | --- | --- |
+| Timeline item Fusion comp | Supported | Tool add, input writes, connections, frame range, comp export | Primary safe automation target. Pass `timeline_item`, `clip_id`, or `timeline_item_id`. |
+| Active Fusion page comp | Supported when a current comp exists | Raw and safe graph helpers work against the active page comp | Page state matters; omit timeline scope only when that is intentional. |
+| Bulk timeline item comps | Supported | `bulk_set_inputs` requires explicit timeline scope per op | Avoids accidentally mutating the active page comp. |
+| Comp import/export | Supported through `timeline_item_fusion` | Export succeeded to a temp `.setting` file in the live probe | Import should use temp or explicitly approved paths. |
+
+## Supported Findings
+
+- Timeline item Fusion comp creation, count, and name listing worked on the
+  generated synthetic clip.
+- `fusion_graph_capabilities` and `fusion_boundary_report` produced stable
+  graph summaries without requiring Fusion page focus.
+- `safe_add_tool` successfully added `Background`, `TextPlus`, `Merge`,
+  `Transform`, and `Blur` tools to a timeline item comp.
+- `safe_set_inputs` wrote and read back text and background color inputs.
+- `probe_fusion_tool` returned normalized attrs plus input/output metadata for
+  the generated `TextPlus` tool.
+- `safe_connect_tools` connected the generated text tool to `MediaOut1`.
+- `bulk_set_inputs` wrote multiple scoped input changes in one request.
+- `set_frame_range` and timeline item comp export succeeded against the
+  disposable timeline item comp.
+
+## Boundaries
+
+- Tool availability varies by Resolve/Fusion build. The kernel reports common
+  tool IDs but does not pretend every Fusion tool is installed everywhere.
+- Fusion inputs are heterogeneous. Some are readable after writes, some coerce
+  values, and some can be effectively write-only depending on the tool.
+- Active Fusion page comps and timeline item comps are different scopes. The
+  safe helpers support both, but bulk mutation requires timeline scope.
+- `fusion_comp.render` is still exposed as the raw API path, but the live kernel
+  probe does not force a render because renderability depends on graph shape,
+  MediaOut state, and page/build behavior.
+- The public API exposes tool attrs and ports, not a semantic model of every
+  effect parameter. Higher-level wrappers should probe before assuming a
+  control exists.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+python3.11 tests/live_fusion_composition_validation.py --output-dir /tmp/fusion-composition-probe
+```
+
+The harness creates a disposable project, generates synthetic video media,
+builds a timeline item Fusion comp, probes tool creation, input writes, graph
+inspection, connections, bulk writes, frame range, comp export, and boundary
+reporting, then deletes the project and removes generated media.
+
+Use `--keep-open` only when you intentionally want to inspect the disposable
+project by hand.

package/docs/kernels/media-pool-ingest-kernel.md

@@ -0,0 +1,147 @@
+# Media Pool / Ingest Kernel
+
+The Media Pool / Ingest kernel expands the raw Resolve Media Storage,
+Media Pool, Folder, MediaPoolItem, and MediaPoolItem marker wrappers into a
+safer agent-facing layer for import, organization, metadata, annotation, and
+link-boundary work.
+
+Source media integrity remains the first rule: these helpers do not transcode,
+render, proxy-generate, overwrite, or mutate source files. They validate paths
+before calling Resolve, and the live harness uses generated synthetic media in
+disposable `_mcp_...` projects only.
+
+## New Compound Actions
+
+All actions are under `media_pool(action=...)`.
+
+| Action | Status | Purpose |
+| --- | --- | --- |
+| `ingest_capabilities` | Supported | Maintained support/partial/unsupported map for ingest workflows. |
+| `probe_media_pool` | Supported | Read-only Media Pool, folder, selected clip, and method availability snapshot. |
+| `probe_ingest_item` | Supported | Read-only metadata/property/annotation/audio snapshot for clip IDs or selected clips. |
+| `safe_import_media` | Supported | Validates existing paths, optionally targets a Media Pool folder, supports dry-run, then calls `ImportMedia(paths)`. |
+| `safe_import_sequence` | Supported | Validates printf-style sequence patterns and frame ranges before calling `ImportMedia([{clipInfo}])`. |
+| `safe_import_folder` | Supported dry-run | Validates folder paths before `ImportFolderFromFile`; dry-run is recommended unless importing Resolve folder exports intentionally. |
+| `setup_multicam_timeline` | Supported setup helper | Creates a stacked multicam prep timeline from Media Pool clips, with one angle per video track and optional matching audio tracks. |
+| `organize_clips` | Supported | Moves clips to an existing or optionally created Media Pool folder. |
+| `copy_metadata` | Supported | Copies Resolve metadata and optional third-party metadata from one clip to target clips. |
+| `normalize_metadata` | Supported | Bulk-writes explicit metadata and third-party metadata to clip IDs or selected clips. |
+| `probe_clip_properties` | Supported | Read-only full and known-key clip property snapshots. |
+| `metadata_field_inventory` | Supported | Read-only metadata, clip-property, and inferred Metadata-panel group inventory for selected or explicit clips. |
+| `safe_relink` | Supported | Validates clip IDs and target directory before `RelinkClips`; supports dry-run. |
+| `safe_unlink` | Supported | Validates clip IDs before `UnlinkClips`; supports dry-run. |
+| `link_proxy_checked` | Supported | Validates clip ID and proxy file path before `LinkProxyMedia`. |
+| `link_full_resolution_checked` | Supported on Resolve 20+ | Version-guards and validates path before `LinkFullResolutionMedia`. |
+| `set_clip_marks` | Supported | Bulk `SetMarkInOut` for clip IDs or selected clips. |
+| `clear_clip_marks` | Supported | Bulk `ClearMarkInOut` for clip IDs or selected clips. |
+| `copy_clip_annotations` | Supported | Copies clip color, flags, and media-pool item markers from one clip to targets. |
+| `media_pool_boundary_report` | Supported | Combines capabilities, Media Pool probe, and optional item probes. |
+
+## Multicam Setup Helper
+
+`setup_multicam_timeline` is intentionally documented as a helper tool rather
+than API coverage. It prepares the timeline structure Resolve's multicam UI can
+consume, while leaving native conversion to Resolve.
+
+Supported planning inputs:
+
+- `clip_ids`: simple one-angle-per-clip setup.
+- `angles`: explicit rows with `clip_id`, `angle_name`, source range, track
+  index, audio track index, source timecode, record frame, or record offset.
+- `sync_mode`: `stack_start`, `source_timecode`, or `record_frame`.
+- `include_audio`: append audio-only rows for each angle.
+- `dry_run`: return the planned append rows without creating a timeline.
+
+After the helper creates the setup timeline, verify sync in Resolve, duplicate
+the timeline if it should remain recoverable, then use the Media Pool context
+menu command "Convert Compound Clips (Timelines) to Multicam Clips." See
+`docs/guides/multicam-setup-guide.md` for examples and the Resolve 20 manual
+reference.
+
+For 2-pop or slate-clap assisted sync, run
+`media_analysis(action="detect_sync_events")` first and pass its suggested
+`record_offset` values into `setup_multicam_timeline(sync_mode="record_frame")`.
+If the detected sync points should become Resolve markers, ask the user first;
+the guarded write step is `media_analysis(action="add_sync_event_markers",
+params={"confirm": true, ...})`.
+
+## Supported Boundaries
+
+- Media Storage browsing: volumes, subfolders, and file listing.
+- Media import through simple paths and image sequence clipInfos.
+- Safe import helpers with path validation and dry-run support.
+- Media Pool organization: folder creation, current folder switching, selected
+  clip get/set, and clip moves.
+- Multicam setup timelines: source-safe placement of existing Media Pool clips
+  on per-angle tracks via `AppendToTimeline([{clipInfo}])`, with stack-start,
+  manual record-frame, or source-timecode planning.
+- Metadata: scalar and dict metadata writes, third-party metadata writes,
+  metadata copy, explicit normalization, and field inventory for mapping
+  analysis writeback targets to Resolve metadata/clip-property surfaces.
+- Clip property probing: full snapshot plus known keys such as `File Path`,
+  `Type`, `FPS`, `Duration`, `Resolution`, `Codec`, and audio fields.
+- Media Pool item annotations: markers, custom marker data, flags, clip color,
+  and mark in/out.
+- Link boundaries: relink/unlink dry-runs, proxy linking, and Resolve 20+
+  full-resolution media linking, with generated media used for live validation.
+- Export metadata to a caller-provided path.
+
+## Partial Or Version-Dependent Areas
+
+- Clip property writes are still key/media/build dependent. The kernel probes
+  properties read-only; raw `media_pool_item.set_clip_property` remains
+  available for explicit writes.
+- Proxy and full-resolution linking may accept paths without deep media
+  compatibility validation. Use checked helpers for path validation, and verify
+  editorial intent before changing real project links.
+- Audio transcription depends on Studio features, installed language
+  components, media type, and Resolve state; it remains exposed on existing
+  `folder` and `media_pool_item` actions, not folded into the ingest live pass.
+- Image sequence import depends on a valid printf-style pattern and Resolve's
+  still/sequence interpretation.
+- `ImportFolderFromFile` is a Resolve folder/project interchange operation, not
+  a general filesystem import. The safe helper validates the folder and supports
+  dry-run to prevent accidental misuse.
+
+## Unsupported Or Intentionally Guarded
+
+- Non-media files are not imported. The final live probe classified a generated
+  `.txt` fixture as `unsupported` because Resolve returned zero imported items
+  without raising an API error.
+- The kernel does not create proxies, transcodes, renders, or derivatives of
+  source media.
+- Destructive replacement APIs (`ReplaceClip`, `ReplaceClipPreserveSubClip`)
+  remain raw explicit clip actions and are not used by the kernel probe.
+- Resolve does not guarantee a stable writable metadata schema across versions
+  or locales.
+- Native multicam clip creation, angle switching, and multicam flattening are
+  not exposed by the public Resolve scripting API. The setup helper prepares a
+  timeline that can be converted to a native multicam clip in Resolve's UI. See
+  the installed DaVinci Resolve 20 Manual, Edit > Chapter 42, "Multicam
+  Editing," for the current UI workflow.
+
+## Live Evidence
+
+Final validation ran on May 9, 2026 with DaVinci Resolve Studio 20.3.2.9 and
+Python 3.11.14.
+
+```
+python3.11 tests/live_media_pool_ingest_validation.py \
+  --output-dir /private/tmp/media-pool-ingest-probe-20260509-release
+```
+
+Result:
+
+- `supported`: 56
+- `unsupported`: 1
+- `partially_supported`: 0
+- `version_or_page_dependent`: 0
+- `write_only_unverifiable`: 0
+- `read_only`: 0
+- `not_applicable`: 0
+- `error`: 0
+
+The live harness created and deleted a disposable project named
+`_mcp_media_pool_ingest_probe_1778341105`, generated synthetic video/audio/still
+fixtures, wrote JSON and Markdown reports, and removed the generated media
+directory after the report was written.

package/docs/kernels/project-lifecycle-kernel.md

@@ -0,0 +1,120 @@
+# Project / Database / Archive Kernel
+
+The Project / Database / Archive kernel expands `project_manager` into a guarded
+project lifecycle, settings, database, preset, and archive boundary layer.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with disposable
+`_mcp_project_lifecycle_*` projects only. The probe created an empty timeline,
+saved the disposable project, exported/imported through a temp DRP, exercised
+project folders, layout presets, page switching, database dry-runs, settings
+snapshot/write/restore, and archive guards. Final release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 35 |
+| `partially_supported` | 5 |
+| `unsupported` | 1 |
+| `not_applicable` | 1 |
+| `version_or_page_dependent` | 0 |
+| `error` | 0 |
+
+The unsupported result is intentional: archive calls that request source media,
+render cache, or proxy media are rejected by default unless explicitly opted in.
+
+## Added Actions
+
+All kernel actions are exposed through `project_manager`.
+
+| Action | Purpose |
+| --- | --- |
+| `project_capabilities` | Report ProjectManager, Project, layout preset, render preset, and safety-guard availability. |
+| `probe_project_lifecycle` | Snapshot current project, current folder, project list, folder list, and ProjectManager methods. |
+| `probe_project_settings` | Read candidate project settings and optionally dry-run/write-restore candidates. |
+| `safe_project_create` | Create disposable `_mcp_` projects with optional temp media-location guard. |
+| `safe_project_export` | Export disposable projects to temp DRP paths; stills/LUTs are off by default. |
+| `safe_project_import` | Import temp DRP projects under disposable `_mcp_` names. |
+| `safe_project_archive` | Archive disposable projects with media/cache/proxy flags forced false by default. |
+| `safe_project_restore` | Restore temp project archives or DRPs under disposable `_mcp_` names. |
+| `safe_project_delete` | Delete disposable projects, with explicit `close_current=True` required for the open project. |
+| `safe_set_project_settings` | Validate, write, read back, and restore project settings. |
+| `project_settings_snapshot` | Snapshot project settings, presets, timeline count, current timeline, render presets, and color groups. |
+| `database_capabilities` | Read current database, database list, and switch safety constraints. |
+| `safe_set_current_database` | Dry-run database switches by default because switching closes open projects. |
+| `preset_lifecycle_probe` | Report project, render, quick-export, Fairlight, layout, render-preset, and burn-in preset surfaces. |
+| `project_boundary_report` | Return the full lifecycle, settings, database, preset, and cloud boundary report. |
+
+`project_manager_folders` also now normalizes both documented string folder
+returns and newer folder-object returns.
+
+## Supported Findings
+
+- Disposable project creation, current-project readback, save, and delete worked.
+- Empty timeline creation inside the disposable project worked and gave the
+  project enough structure for DRP export.
+- DRP export and `ImportProject` under a new `_mcp_` name worked.
+- Project folder list/create/open/current/goto-parent/delete worked.
+- Full project settings snapshots worked, including project presets, render
+  presets, quick-export presets, timeline count, current timeline, and color
+  groups.
+- Same-value write/readback/restore worked for `timelineResolutionWidth`.
+- Database current/list probing worked, and guarded database switching correctly
+  dry-ran by default.
+- Layout preset save/update/load/export/import/delete worked with `_mcp_`
+  temp names.
+- All Resolve pages opened successfully through `resolve_control.open_page`.
+- Keyframe mode readback worked.
+- The combined boundary report worked and includes cloud methods as
+  shape-only, infrastructure-dependent capabilities.
+
+## Boundaries
+
+- `ProjectManager.RestoreProject` returned false when pointed at the exported
+  DRP. `ImportProject` is the supported path for temp DRP round-trips in this
+  probe.
+- `ProjectManager.ArchiveProject` returned false for both a `.dra` path and a
+  folder-style path, even with `src_media=False`, `render_cache=False`, and
+  `proxy_media=False`.
+- Archive calls with source media, render cache, or proxy media are blocked by
+  default. This protects source media integrity and avoids large cache/proxy
+  copies.
+- `Resolve.SetKeyframeMode` returned false when setting the current keyframe
+  mode back to itself, though `GetKeyframeMode` worked.
+- `Resolve.ExportRenderPreset` returned false for the first listed render
+  preset in the release probe. Render/quick-export preset listing still worked.
+- `Project.GetRenderSettings` was not present on the live Project object, so
+  render settings remain covered by the Render / Deliver kernel's existing
+  guarded actions.
+- Cloud project create/load/import/restore methods are exposed by the API, but
+  default validation treats them as shape-only because they require Resolve
+  cloud infrastructure and media-location settings.
+
+## Safety Rules
+
+- Safe project create/import/restore/delete actions require names beginning with
+  `_mcp_` unless `allow_non_mcp_name=True`.
+- Safe export/import/archive/restore paths must be under the system temp
+  directory unless `require_temp_path=False`.
+- Safe project delete refuses to delete the currently open project unless
+  `close_current=True`.
+- Safe database switching is a dry-run unless both `allow_switch=True` and
+  `dry_run=False` are provided.
+- Safe archive defaults all media/cache/proxy flags to false and rejects any
+  true flag unless `allow_media_archive=True`.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+python3.11 tests/live_project_lifecycle_validation.py --output-dir /tmp/project-lifecycle-probe
+```
+
+The harness creates disposable `_mcp_` projects, creates an empty timeline,
+saves the project, probes DRP export/import, archive/restore boundaries,
+project folder lifecycle, project settings write/restore, database dry-runs,
+layout preset lifecycle, page switching, keyframe mode, preset listings, writes
+JSON and Markdown reports, deletes disposable projects and layout presets, and
+removes temp work files.
+
+Use `--keep-open` only when you intentionally want to inspect the disposable
+projects by hand.

package/docs/kernels/render-deliver-kernel.md

@@ -0,0 +1,92 @@
+# Render / Deliver Kernel
+
+The Render / Deliver kernel adds a safer planning and validation layer over
+Resolve's render queue, render settings, format/codec discovery, presets, and
+Quick Export APIs.
+
+Live probes use disposable `_mcp_...` projects, generated synthetic media, and
+temporary output directories only. They may render derivatives of generated
+fixtures, but never render, transcode, proxy, or overwrite user source media.
+
+## New Compound Actions
+
+All actions are under `render(action=...)`.
+
+| Action | Status | Purpose |
+| --- | --- | --- |
+| `render_capabilities` | Supported | Reports render method availability, formats, presets, quick-export presets, setting keys, and safety guards. |
+| `probe_render_matrix` | Supported | Builds a format/codec/resolution compatibility matrix. |
+| `probe_render_settings` | Supported with readback boundary | Captures current format/codec, mode, jobs, render state, and settings when Resolve exposes settings readback. |
+| `validate_render_settings` | Supported | Validates supported setting keys, value types, frame ranges, and optional temp-target requirements. |
+| `safe_set_render_settings` | Supported | Validates settings before `SetRenderSettings`, reports post-set readback/coercion when available, and supports dry-run. |
+| `prepare_render_job` | Supported | Validates target directory/settings, optionally sets format/codec, applies settings, and adds a render job without starting it. |
+| `render_job_lifecycle_probe` | Supported | Adds a job, reads status, and deletes the job to validate queue lifecycle safely. |
+| `quick_export_capabilities` | Supported | Lists Quick Export presets and enforced safety guards. |
+| `safe_quick_export` | Supported dry-run | Validates temp target, forces `EnableUpload=False`, and requires `allow_render=True` before actual Quick Export execution. |
+| `export_render_boundary_report` | Supported | Combines capabilities, settings snapshot, format matrix, and Quick Export capabilities. |
+
+## Supported Boundaries
+
+- Format discovery through `GetRenderFormats`.
+- Codec discovery for every returned format through `GetRenderCodecs`.
+- Resolution discovery for every format/codec pair through
+  `GetRenderResolutions`.
+- Current format/codec set and readback.
+- Current render mode get/set.
+- Render preset list, save, and delete for temporary MCP-named presets.
+- Render setting validation for documented `SetRenderSettings` keys.
+- Safe render job preparation into a temp target directory.
+- Job queue lifecycle: add, status, delete.
+- Actual synthetic render start/completion for a two-second generated timeline.
+- Quick Export preset discovery and guarded dry-run planning.
+
+## Version Or Page Dependent Boundaries
+
+- `GetRenderSettings` is documented, but in the final Resolve Studio 20.3.2.9
+  live probe the project attribute was not callable. The kernel treats settings
+  readback as version/page dependent and still validates and applies settings
+  through `SetRenderSettings`.
+- Render format and codec availability is machine, OS, license, and plugin
+  dependent. The final live probe found 23 formats and 99 format/codec pairs.
+- Some settings may be accepted but not readable for coercion checks on builds
+  where `GetRenderSettings` is unavailable.
+- Quick Export actual execution is intentionally gated behind
+  `allow_render=True`, because it starts rendering immediately and can involve
+  upload-capable presets. The safe helper always forces `EnableUpload=False`.
+
+## Unsupported Or Guarded
+
+- Render lifecycle helpers require temp output directories by default. Passing
+  real delivery paths requires explicit lower-level actions or disabling the
+  temp guard.
+- Upload-enabled Quick Export is not allowed through `safe_quick_export`.
+- Import/export of render and burn-in preset files remains exposed through the
+  existing `render_presets` tool, but the live kernel probe does not fabricate
+  arbitrary preset files.
+
+## Live Evidence
+
+Final validation ran on May 9, 2026 with DaVinci Resolve Studio 20.3.2.9 and
+Python 3.11.14.
+
+```
+python3.11 tests/live_render_deliver_validation.py \
+  --output-dir /private/tmp/render-deliver-probe-20260509-release
+```
+
+Result:
+
+- `supported`: 23
+- `version_or_page_dependent`: 1
+- `unsupported`: 0
+- `partially_supported`: 0
+- `write_only_unverifiable`: 0
+- `read_only`: 0
+- `not_applicable`: 0
+- `error`: 0
+
+The live harness created and deleted a disposable project named
+`_mcp_render_deliver_probe_1778342107`, generated synthetic media, probed 23
+formats and 99 format/codec pairs, rendered one tiny synthetic output, wrote
+JSON and Markdown reports, and removed the generated media and render output
+directories after the report was written.

package/docs/kernels/review-annotation-kernel.md

@@ -0,0 +1,110 @@
+# Review Annotation Kernel
+
+The Review Annotation kernel expands `timeline_markers` into a scope-aware
+annotation layer for timeline markers, timeline item markers, media pool item
+markers, flags, clip colors, and read-only review reports.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with a
+disposable `_mcp_review_annotation_probe_*` project and generated synthetic
+video/audio media. Final release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 44 |
+| `unsupported` | 1 |
+| `partially_supported` | 0 |
+| `version_or_page_dependent` | 0 |
+| `error` | 0 |
+
+The single `unsupported` result is the expected invalid marker color boundary
+for `color="Invisible"`.
+
+## Added Actions
+
+All actions are exposed through `timeline_markers`.
+
+| Action | Purpose |
+| --- | --- |
+| `annotation_capabilities` | Return supported scopes, colors, aliases, and known boundaries. |
+| `probe_annotations` | Snapshot markers, flags, clip color, ids, and names for one scope or the current timeline context. |
+| `normalize_marker_payload` | Normalize frame aliases, timecode, color, name/label, note/comment, duration, and custom data aliases. |
+| `copy_annotations` | Copy markers between annotation scopes, optionally carrying flags and clip color. |
+| `move_annotations` | Copy markers, then clear source markers when the source exposes marker deletion. |
+| `sync_marker_custom_data` | Update marker custom data for timeline, timeline item, or media pool item scope. |
+| `clear_annotations_by_scope` | Clear markers by color/custom data and optionally clear flags and clip color. |
+| `export_review_report` | Return a read-only annotation report with optional capability metadata. |
+| `annotation_boundary_report` | Return capabilities plus a live annotation snapshot. |
+
+## Scope Matrix
+
+| Scope | Markers | Custom Data | Flags | Clip Color | Frame Space |
+| --- | --- | --- | --- | --- | --- |
+| `timeline` | Supported | Supported | Not exposed | Not exposed | Timeline frame id or timeline timecode. |
+| `timeline_item` | Supported | Supported | Supported | Supported | Timeline item marker frames. |
+| `media_pool_item` | Supported | Supported | Supported | Supported | Source/media pool item frames. |
+
+## Marker Payloads
+
+The kernel accepts these frame inputs:
+
+- `frame`
+- `frame_id`
+- `frameId`
+- `frame_num`
+- `frameNum`
+- `timecode`
+- `tc`
+
+The kernel accepts `custom_data` and `customData`, plus `label` as an alias for
+`name` and `comment` as an alias for `note`.
+
+Validated marker colors:
+
+`Blue`, `Cyan`, `Green`, `Yellow`, `Red`, `Pink`, `Purple`, `Fuchsia`, `Rose`,
+`Lavender`, `Sky`, `Mint`, `Lemon`, `Sand`, `Cocoa`, `Cream`.
+
+## Supported Findings
+
+- Timeline marker add/get/update/custom-data readback works with frame,
+  `frame_id`, `frameId`, explicit timecode, and current-playhead insertion.
+- All documented marker colors were accepted in the live Resolve build.
+- Timeline item markers support marker copy and custom data updates.
+- Timeline item flags and clip color support add/read/set/clear.
+- Media pool item markers, flags, and clip color support add/set/read/clear
+  through the existing MCP wrappers and the new copy/move kernel helpers.
+- `copy_annotations` successfully copied 21 timeline markers to a timeline
+  item in the live probe.
+- `move_annotations` successfully copied a media pool item marker to the
+  timeline and cleared the source marker.
+- `clear_annotations_by_scope` supports Resolve's `"All"` color sentinel for
+  marker cleanup on timeline and timeline item scopes.
+- `export_review_report` and `annotation_boundary_report` are read-only
+  summaries over current annotation state.
+
+## Boundaries
+
+- Timeline, timeline item, and media pool item frame spaces are not equivalent.
+  `copy_annotations` uses direct frame numbers; callers must map frames when
+  moving between source, item-local, and timeline coordinate systems.
+- Current-playhead marker insertion depends on a current timeline and readable
+  current timecode.
+- `probe_annotations` only includes timeline item and media pool item scopes
+  when Resolve can resolve a current video item at the playhead.
+- Flags and clip colors are review metadata, but they are not marker records.
+  They are copied only when both source and target expose compatible methods.
+- Invalid marker colors are rejected before calling Resolve.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+python3.11 tests/live_review_annotation_validation.py --output-dir /tmp/review-annotation-probe
+```
+
+The harness creates a disposable project, generates a short synthetic video
+with audio, imports it, creates a timeline, probes annotation operations, writes
+JSON and Markdown reports, deletes the project, and removes generated media.
+
+Use `--keep-open` only when you intentionally want to inspect the disposable
+project by hand.