davinci-resolve-mcp 2.23.0

package/docs/guides/multicam-setup-guide.md

@@ -0,0 +1,138 @@
+# Multicam Setup Helper Guide
+
+The multicam setup helper prepares source-safe Resolve timelines for multicam
+workflows. It is a workflow helper, not a native multicam API wrapper: DaVinci
+Resolve's public scripting API does not expose creating native multicam clips,
+switching multicam angles, or flattening multicam edits.
+
+The current Resolve UI workflow is documented in the installed DaVinci Resolve
+20 Manual, Edit > Chapter 42, "Multicam Editing." In Resolve, native multicam
+creation and "Convert Compound Clips (Timelines) to Multicam Clips" are Media
+Pool context-menu operations.
+
+## What The Helper Does
+
+`media_pool(action="setup_multicam_timeline")` creates a new prep timeline that
+references existing Media Pool clips:
+
+- One camera angle per video track.
+- Optional matching audio tracks.
+- Track names from angle names or clip names.
+- Exact `AppendToTimeline([{clipInfo}])` placement with source ranges and
+  record frames.
+- Dry-run planning before touching Resolve project state.
+
+The helper never modifies, transcodes, proxies, renders, relinks, replaces, or
+creates derivatives of source media.
+
+## What It Does Not Do
+
+- It does not create a native multicam clip.
+- It does not run Resolve's "Create Multicam Clip Using Selected Clips" dialog.
+- It does not switch angles in an edited multicam clip.
+- It does not flatten multicam clips.
+- It does not perform waveform/audio correlation internally. Use
+  `media_analysis(action="detect_sync_events")` as a separate read-only analysis
+  layer when 2-pops or slate claps should feed this helper.
+
+## Sync Modes
+
+`stack_start`
+: Places every angle at the same record frame. Use this when clips are already
+  trimmed to the same sync point or you want a simple visual stack.
+
+`source_timecode`
+: Reads each angle's `source_timecode` parameter or Resolve clip Start TC
+  metadata and computes offsets from `timeline_start_timecode`. Use this for
+  jam-synced cameras or externally prepared timecode metadata.
+
+`record_frame`
+: Uses explicit per-angle `record_frame` values. Use this for manual sync,
+  external alignment tools, or future FFmpeg/ffprobe audio-analysis results.
+
+## Minimal Example
+
+```json
+{
+  "action": "setup_multicam_timeline",
+  "params": {
+    "name": "Interview Multicam Prep",
+    "clip_ids": ["clip-a-id", "clip-b-id"],
+    "sync_mode": "stack_start",
+    "include_audio": true,
+    "dry_run": true
+  }
+}
+```
+
+Run the same call with `dry_run=false` or omit `dry_run` to create the timeline.
+
+## Timecode Example
+
+```json
+{
+  "action": "setup_multicam_timeline",
+  "params": {
+    "name": "Concert Multicam Prep",
+    "sync_mode": "source_timecode",
+    "timeline_start_timecode": "01:00:00:00",
+    "start_timecode": "01:00:00:00",
+    "include_audio": true,
+    "angles": [
+      {
+        "clip_id": "cam-a-id",
+        "angle_name": "Camera A",
+        "source_timecode": "01:00:03:12"
+      },
+      {
+        "clip_id": "cam-b-id",
+        "angle_name": "Camera B",
+        "source_timecode": "01:00:06:04"
+      }
+    ]
+  }
+}
+```
+
+The helper also accepts `start_frame`, `end_frame`, `duration_frames`,
+`record_offset`, `track_index`, and `audio_track_index` per angle for more
+explicit control.
+
+## After The Timeline Is Created
+
+1. Open the setup timeline and verify sync by scrubbing visible action, slate,
+   clap, or reference audio.
+2. Duplicate the setup timeline if you want a preserved editable source, because
+   Resolve's conversion to multicam is one-way.
+3. In the Media Pool, right-click the setup timeline.
+4. Choose "Convert Compound Clips (Timelines) to Multicam Clips."
+5. Edit the created native multicam clip into the working timeline.
+6. Use Resolve's Multicam viewer, keyboard shortcuts, angle switching, and
+   optional flattening tools for the edit.
+
+## Agent Workflow
+
+When asked to prepare multicam:
+
+1. Gather clip IDs with `media_pool(action="probe_media_pool")` or
+   `media_pool(action="get_selected")`.
+2. Prefer a `dry_run` call first.
+3. Explain which sync mode is being used and what evidence supports it.
+4. Create the setup timeline only after the plan is coherent.
+5. Report the resulting timeline name/id and remind the user that native
+   conversion is a Resolve UI step.
+
+For audio-derived alignment, first run a separate source-safe analysis pass
+against source paths with `media_analysis(action="detect_sync_events")`. Use
+the returned `alignment.suggestions[].suggested_record_offset_frames` values as
+per-angle `record_offset` values, then call this helper with
+`sync_mode="record_frame"`.
+
+If sync markers would help the user verify the setup, show the returned marker
+suggestions and ask first. Only after approval, call
+`media_analysis(action="add_sync_event_markers", params={"confirm": true, ...})`
+to write Media Pool item markers.
+
+Do not install FFmpeg automatically. If `ffmpeg` or `ffprobe` is missing, report
+that the optional audio-analysis layer is unavailable and suggest installing
+FFmpeg before retrying that feature.

package/docs/install.md

@@ -0,0 +1,198 @@
+# Installation and Configuration
+
+This guide covers Resolve requirements, the universal installer, supported MCP clients, server modes, and manual configuration.
+
+## Requirements
+
+- **DaVinci Resolve Studio** 18.5+ (macOS, Windows, or Linux) — the free edition does not support external scripting
+- **Python 3.10–3.12** recommended (3.13+ may have ABI incompatibilities with Resolve's scripting library)
+- DaVinci Resolve running with **Preferences > General > "External scripting using"** set to **Local**
+
+Validated live coverage is based on **DaVinci Resolve 19.1.3 Studio** for the original API surface, plus **DaVinci Resolve 20.3.2 Studio** for the Resolve 20.0-20.2.2 scripting additions. Resolve 21 beta APIs are intentionally deferred until a stable release.
+
+## Quick Start
+
+```bash
+# Make sure DaVinci Resolve Studio is running, then:
+npx davinci-resolve-mcp setup
+```
+
+The npm launcher installs a managed copy in your user application-data directory
+and then runs the universal Python installer from there. MCP client configs point
+directly at the managed Python virtual environment and `src/server.py`, so Node
+is not required after setup.
+
+For source installs:
+
+```bash
+git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
+cd davinci-resolve-mcp
+
+python install.py
+```
+
+The universal installer auto-detects your platform, finds your DaVinci Resolve installation, creates a virtual environment, and configures your MCP client — all in one step.
+
+The installer and MCP server perform a best-effort update check against the latest GitHub release. The server check runs in the background, is throttled to once every 24 hours, and never installs code automatically. Set `DAVINCI_RESOLVE_MCP_UPDATE_CHECK=0` to disable it, or `DAVINCI_RESOLVE_MCP_UPDATE_INTERVAL_HOURS` to adjust the interval.
+
+### Supported MCP Clients
+
+The installer can automatically configure any of these clients:
+
+| Client | Config Written To |
+|--------|-------------------|
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Claude Code | `.mcp.json` (project root) |
+| Cursor | `~/.cursor/mcp.json` |
+| VS Code (Copilot) | `.vscode/mcp.json` (workspace) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline | VS Code global storage |
+| Roo Code | VS Code global storage |
+| Zed | `~/.config/zed/settings.json` |
+| Continue | `~/.continue/config.json` |
+| JetBrains IDEs | Manual (Settings > Tools > AI Assistant > MCP) |
+
+You can configure multiple clients at once, or use `--clients manual` to get copy-paste config snippets.
+
+### Installer Options
+
+```bash
+npx davinci-resolve-mcp setup                 # Interactive npm setup
+npx davinci-resolve-mcp setup --clients all   # Configure all clients
+npx davinci-resolve-mcp doctor                # Dry-run environment/config check
+npx davinci-resolve-mcp server                # Launch the managed MCP server
+npx davinci-resolve-mcp control-panel         # Launch the local control panel
+
+python install.py                              # Interactive mode
+python install.py --clients all                # Configure all clients
+python install.py --clients cursor,claude-desktop  # Specific clients
+python install.py --clients manual             # Just print the config
+python install.py --dry-run --clients all      # Preview without writing
+python install.py --no-venv --clients cursor   # Skip venv creation
+```
+
+### Server Modes
+
+The MCP server comes in two modes:
+
+| Mode | File | Tools | Best For |
+|------|------|-------|----------|
+| **Compound** (default) | `src/server.py` | 32 | Most users — fast, clean, low context usage |
+| **Full** | `src/resolve_mcp_server.py` | 329 | Power users who want one tool per API method |
+
+The compound server's `timeline_item` tool includes dedicated actions for common workflows:
+
+| Category | Actions | Parameters |
+|----------|---------|------------|
+| **Retime** | `get_retime`, `set_retime` | process (nearest, frame_blend, optical_flow), motion_estimation (0-6) |
+| **Transform** | `get_transform`, `set_transform` | Pan, Tilt, ZoomX/Y, RotationAngle, AnchorPointX/Y, Pitch, Yaw, FlipX/Y |
+| **Crop** | `get_crop`, `set_crop` | CropLeft, CropRight, CropTop, CropBottom, CropSoftness, CropRetain |
+| **Composite** | `get_composite`, `set_composite` | Opacity, CompositeMode |
+| **Audio** | `get_audio`, `set_audio` | Volume, Pan, AudioSyncOffset |
+| **Keyframes** | `get_keyframes`, `add_keyframe`, `modify_keyframe`, `delete_keyframe`, `set_keyframe_interpolation` | property, frame, value, interpolation (Linear, Bezier, EaseIn, EaseOut, EaseInOut) |
+
+The installer uses the compound server by default. To use the full server:
+```bash
+python src/server.py --full    # Launch full 329-tool server
+# Or point your MCP config directly at src/resolve_mcp_server.py
+```
+
+### Local Control Panel
+
+The repository includes a local, single-user control panel for server status,
+Resolve clip visibility, source-safe media-analysis jobs, and the searchable
+analysis index. Persisted analysis jobs refresh the index automatically after
+successful slices; the manual Build Index action is for rebuilding from existing
+reports.
+
+From the repository root:
+
+```bash
+venv/bin/python -m src.control_panel
+```
+
+This opens the browser by default. Use `--no-open` to run only the localhost
+server, or `--port` to choose a different port:
+
+```bash
+venv/bin/python -m src.control_panel --no-open --port 8766
+```
+
+You can also ask an AI coding agent: **"Open the Resolve MCP control panel for
+this repo."** The agent should launch the command above and open the local URL.
+
+### Manual Configuration
+
+If you prefer to set things up yourself, add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "davinci-resolve": {
+      "command": "/path/to/venv/bin/python",
+      "args": ["/path/to/davinci-resolve-mcp/src/server.py"],
+      "env": {
+        "RESOLVE_SCRIPT_API": "/path/to/DaVinci Resolve/Developer/Scripting",
+        "RESOLVE_SCRIPT_LIB": "/path/to/fusionscript.so-or-dll",
+        "PYTHONPATH": "/path/to/DaVinci Resolve/Developer/Scripting/Modules"
+      }
+    }
+  }
+}
+```
+
+On Windows, installer-generated configs also include `PYTHONHOME`. That scopes Resolve's Python binding to the selected interpreter and avoids the Resolve 20.3 multi-Python crash reported in [Issue #26](https://github.com/samuelgursky/davinci-resolve-mcp/issues/26).
+
+When the compound server is running, `resolve_control(action="get_version")`
+includes the local MCP version, the last update-check status, and the current
+update decision under the `mcp` key. `resolve_control(action="mcp_update_status",
+params={"force_check": true})` performs an explicit foreground check.
+
+### MCP Update Policy
+
+The server keeps update checks non-interactive so MCP stdio startup remains safe
+for every client. The installer is the human-facing prompt surface: when a newer
+GitHub release is available, interactive installs can update now, continue,
+snooze for 24 hours, ignore that release, enable safe auto-update, or disable
+checks for the checkout.
+
+Safe auto-update only runs for clean git checkouts with a configured upstream,
+and applies `git fetch --tags --prune` followed by `git pull --ff-only`. If the
+checkout has local changes, no upstream, or a non-fast-forward update, the
+installer continues with the current build.
+
+Installer flags:
+
+```bash
+python install.py --update-now
+python install.py --update-policy prompt
+python install.py --update-policy auto
+python install.py --update-policy notify
+python install.py --update-policy never
+python install.py --clear-update-preferences
+```
+
+The same local defaults are available from chat through
+`setup(action="get_defaults")` and `setup(action="set_defaults")`. For example,
+`{"defaults":{"updates":{"mode":"notify"}}}` changes the MCP update policy
+without rerunning the installer. `updates.check_interval_hours` and
+`updates.snooze_hours` can also be set from the same setup tool; environment
+variables still take precedence when present.
+
+Environment controls:
+
+```bash
+DAVINCI_RESOLVE_MCP_UPDATE_CHECK=0
+DAVINCI_RESOLVE_MCP_UPDATE_MODE=prompt|auto|notify|never
+DAVINCI_RESOLVE_MCP_UPDATE_INTERVAL_HOURS=24
+DAVINCI_RESOLVE_MCP_UPDATE_SNOOZE_HOURS=24
+DAVINCI_RESOLVE_MCP_UPDATE_STATE=/path/to/update-check.json
+```
+
+Platform-specific paths:
+
+| Platform | API Path | Library Path |
+|----------|----------|-------------|
+| macOS | `/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting` | `fusionscript.so` in DaVinci Resolve.app |
+| Windows | `C:\ProgramData\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting` | `fusionscript.dll` in Resolve install dir |
+| Linux | `/opt/resolve/Developer/Scripting` | `/opt/resolve/libs/Fusion/fusionscript.so` |

package/docs/integrations/workflow-integrations.md

@@ -0,0 +1,120 @@
+# DaVinci Resolve Workflow Integration Notes
+
+Blackmagic ships a separate Workflow Integrations developer package alongside the
+Python/Lua scripting docs. This MCP server does not need a Workflow Integration
+plugin to run; it talks to Resolve through the standard Python scripting API.
+The Workflow Integration package is still useful context when building an
+optional Resolve-hosted panel or script UI around the MCP.
+
+## What Workflow Integrations Are
+
+Workflow Integration plugins are Electron apps loaded by DaVinci Resolve Studio
+under `Workspace > Workflow Integrations`. Resolve scans a platform-specific
+plugin root on startup, reads each plugin's `manifest.xml`, and launches the
+plugin's configured JavaScript entry point.
+
+Plugin roots:
+
+| Platform | Workflow Integration plugin root |
+|---|---|
+| macOS | `/Library/Application Support/Blackmagic Design/DaVinci Resolve/Workflow Integration Plugins/` |
+| Windows | `%PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\Support\Workflow Integration Plugins\` |
+
+Resolve-hosted Python/Lua Workflow Integration scripts are also supported. Those
+scripts use the same Resolve scripting API as this MCP server and can create
+small UIManager windows inside Resolve. Plugins are supported on macOS and
+Windows; scripts are supported on macOS, Windows, and Linux.
+
+## Current Blackmagic Notes Worth Preserving
+
+- Resolve 19.0.2 and newer use an Electron runtime with process sandboxing and
+  context isolation enabled by default. New plugins should use a preload script,
+  `contextBridge`, and `ipcMain` rather than renderer-side Node access.
+- Resolve 20.1 updated Workflow Integrations to Electron 36.3.2 and added
+  promise-based JavaScript APIs: `InitializePromise()` and
+  `GetResolvePromise()`.
+- Plugin authors should keep `WorkflowIntegration.node` current by copying the
+  version bundled with the installed Resolve developer package.
+- JavaScript Resolve access is plugin-hosted only; Blackmagic notes that there
+  is no console-based JavaScript API support.
+- `WorkflowIntegration.SetAPITimeout(seconds)` exists for plugin calls that
+  should fail instead of blocking indefinitely. `0` disables the timeout.
+- `WorkflowIntegration.CleanUp()` should be called when the plugin app quits.
+
+## WorkflowIntegration Module Surface
+
+The Electron-side native module exposes:
+
+| Function | Purpose |
+|---|---|
+| `GetInfo()` | Returns module metadata, including module version. |
+| `Initialize(pluginId)` | Initializes the native bridge for the manifest plugin ID. |
+| `InitializePromise(pluginId)` | Promise-returning initialize variant. |
+| `GetResolve()` | Returns the Resolve scripting root object. |
+| `GetResolvePromise()` | Returns a promise Resolve object; subsequent API calls return promises. |
+| `RegisterCallback(name, fn)` | Registers a supported callback. |
+| `DeregisterCallback(name)` | Removes a registered callback. |
+| `CleanUp()` | Releases the Workflow Integration bridge on plugin quit. |
+| `SetAPITimeout(seconds)` | Sets a blocking API timeout for plugin calls. |
+
+Supported callback names:
+
+- `RenderStart`
+- `RenderStop`
+- `ResolveQuit`
+
+These callbacks are not exposed through the standard Python scripting API used
+by this MCP server. If the MCP ever needs event-style render notifications, the
+clean design is an optional Workflow Integration companion that forwards these
+callbacks to the MCP process over a local HTTP/WebSocket bridge. The core MCP
+server should continue to use polling actions such as `render.list_jobs`,
+`render.get_job_status`, and `render.is_rendering`.
+
+## UIManager Script Notes
+
+Workflow Integration Python scripts launched by Resolve are automatically given
+`resolve` and `project` variables. UI windows are built with:
+
+```python
+ui = fusion.UIManager()
+dispatcher = bmd.UIDispatcher(ui)
+```
+
+The useful primitives for small Resolve-hosted panels are:
+
+- `dispatcher.AddWindow(props, children)` and `dispatcher.AddDialog(...)`
+- `win.Show()` followed by `dispatcher.RunLoop()`
+- `dispatcher.ExitLoop()` in the window close handler
+- `win.Find(id)`, `win.GetItems()`, and `ui.FindWindow(id)` for element lookup
+- event handlers via `win.On[element_id].Clicked = handler`
+
+Common UI elements include `Label`, `Button`, `CheckBox`, `ComboBox`, `SpinBox`,
+`Slider`, `LineEdit`, `TextEdit`, `ColorPicker`, `TabBar`, `Tree`, and
+`TreeItem`. Layout is usually composed with `ui.VGroup`, `ui.HGroup`, `ui.VGap`,
+and `ui.HGap`.
+
+## Good Additions For This Repo
+
+The Workflow Integration docs suggest a few possible additions, but none should
+be treated as required for the MCP server itself:
+
+1. Add an optional `examples/workflow-integration-panel/` Electron panel that
+   demonstrates a Resolve-hosted UI talking to a local MCP-adjacent endpoint.
+   Do not vendor `WorkflowIntegration.node`; document that users copy it from
+   their installed Resolve developer package.
+2. Add an optional Python UIManager script example for launching a few common
+   MCP-assisted workflows from inside Resolve.
+3. Add a render callback companion only if we need push-style `RenderStart`,
+   `RenderStop`, or `ResolveQuit` events. Keep the main MCP render tools
+   polling-based and dependency-free.
+4. Extend the installer only after there is a real companion plugin/script to
+   install into the Workflow Integration root. The current MCP client installer
+   should stay focused on MCP client configuration.
+
+## Source Media Integrity Caveat
+
+Blackmagic's sample Workflow Integration Python script includes proxy-linking
+examples. This repo's policy is stricter: never create, link, transcode, or
+otherwise introduce proxy/derivative source media unless the user explicitly
+asks for that workflow. Workflow Integration examples should preserve that rule
+and keep analysis outputs in sidecar files or analysis directories.

package/docs/kernels/README.md

@@ -0,0 +1,28 @@
+# Kernel Action Coverage
+
+Kernel actions are MCP workflow actions layered on top of the public DaVinci
+Resolve Scripting API. They are tracked separately from API method coverage:
+API coverage answers "can MCP reach every Blackmagic method?", while kernel
+coverage answers "which higher-level, guarded agent workflows are available?".
+
+Current kernel coverage: **136 actions** across **9 compound MCP tools**.
+
+| Kernel | MCP Tool | Actions |
+|--------|----------|---------|
+| Media analysis | `media_analysis` | `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`, `review_timeline_markers`, `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`, `cleanup_artifacts` |
+| Timeline edit | `timeline` | `duplicate_clips`, `copy_clips`, `move_clips`, `copy_range`, `duplicate_range`, `overwrite_range`, `lift_range`, `story_spine_report`, `create_variant_from_ranges`, `bulk_set_item_properties`, `apply_look_to_items`, `thumbnail_contact_sheet`, `marker_thumbnail_review`, `edit_kernel_capabilities`, `probe_edit_kernel_item`, `title_property_scan`, `set_title_text`, `bulk_set_title_text` |
+| Media Pool / ingest | `media_pool` | `ingest_capabilities`, `setup_multicam_timeline`, `probe_ingest_item`, `probe_media_pool`, `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`, `media_pool_boundary_report` |
+| Render / Deliver | `render` | `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`, `export_render_boundary_report` |
+| Review annotations | `timeline_markers` | `annotation_capabilities`, `probe_annotations`, `normalize_marker_payload`, `copy_annotations`, `move_annotations`, `sync_marker_custom_data`, `clear_annotations_by_scope`, `export_review_report`, `annotation_boundary_report` |
+| Color / Grade | `timeline_item_color` | `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`, `grade_boundary_report` |
+| Fusion composition | `fusion_comp` | `fusion_graph_capabilities`, `probe_fusion_comp`, `probe_fusion_tool`, `safe_add_tool`, `safe_set_inputs`, `safe_connect_tools`, `fusion_boundary_report` |
+| Conform / interchange | `timeline` | `conform_capabilities`, `probe_timeline_structure`, `detect_gaps_overlaps`, `source_range_report`, `export_timeline_checked`, `import_timeline_checked`, `compare_timelines`, `probe_interchange_roundtrip`, `detect_missing_media`, `build_relink_plan`, `conform_boundary_report` |
+| Audio / Fairlight | `timeline` | `audio_capabilities`, `probe_audio_item`, `probe_audio_track`, `safe_set_audio_properties`, `audio_mix_capability_report`, `voice_isolation_capabilities`, `audio_mapping_report`, `safe_auto_sync_audio`, `transcription_capabilities`, `subtitle_generation_probe`, `fairlight_boundary_report` |
+| Project lifecycle | `project_manager` | `project_capabilities`, `probe_project_lifecycle`, `probe_project_settings`, `safe_project_create`, `safe_project_export`, `safe_project_import`, `safe_project_archive`, `safe_project_restore`, `safe_project_delete`, `safe_set_project_settings`, `project_settings_snapshot`, `database_capabilities`, `safe_set_current_database`, `preset_lifecycle_probe`, `project_boundary_report` |
+| Extension authoring | `script_plugin` | `extension_capabilities`, `probe_fuse_lifecycle`, `probe_dctl_lifecycle`, `probe_script_lifecycle`, `safe_install_extension`, `safe_remove_extension`, `refresh_or_restart_required`, `extension_boundary_report` |
+
+Helper-tool details that need more than an action list live in guides. See
+[Multicam Setup Helper Guide](../guides/multicam-setup-guide.md) for the
+`media_pool.setup_multicam_timeline` helper/API boundary and Resolve UI
+conversion steps, and [Media Analysis Guide](../guides/media-analysis-guide.md)
+for source-safe 2-pop/slate-clap detection.

package/docs/kernels/audio-fairlight-kernel.md

@@ -0,0 +1,86 @@
+# Audio / Fairlight Kernel
+
+The Audio / Fairlight kernel expands `timeline` into a safer audio-state,
+mapping, voice isolation, auto-sync, transcription, subtitle, and Fairlight
+boundary layer.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with a
+disposable `_mcp_audio_fairlight_probe_*` project and generated synthetic video
+plus audio-only media. Final release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 13 |
+| `partially_supported` | 3 |
+| `unsupported` | 0 |
+| `version_or_page_dependent` | 0 |
+| `not_applicable` | 0 |
+| `error` | 0 |
+
+The partially supported results were generated-item `Volume` property writes,
+`AutoSyncAudio` execution, and `InsertAudioToCurrentTrackAtPlayhead`; all
+returned false in the release probe while their guarded planning/probe layers
+worked.
+
+## Added Actions
+
+All kernel actions are exposed through `timeline`.
+
+| Action | Purpose |
+| --- | --- |
+| `audio_capabilities` | Return track, item, media pool, timeline AI, Fairlight, and known boundary support. |
+| `probe_audio_track` | Snapshot audio track subtype, name, lock/enable state, and track voice isolation state. |
+| `probe_audio_item` | Snapshot audio item properties, source audio mapping, voice isolation, and method availability. |
+| `safe_set_audio_properties` | Validate audio property keys, write with readback, and restore original values by default. |
+| `voice_isolation_capabilities` | Report track-level and item-level voice isolation availability and state. |
+| `audio_mapping_report` | Report timeline item source audio mappings and MediaPoolItem audio mappings. |
+| `safe_auto_sync_audio` | Validate clip selection and normalize Resolve audio-sync constants; dry-run by default. |
+| `transcription_capabilities` | Report clip and folder transcription method availability without mutating by default. |
+| `subtitle_generation_probe` | Dry-run subtitle generation by default; requires `allow_generate=True` to call Resolve. |
+| `fairlight_boundary_report` | Return capabilities, track/item probes, mappings, transcription state, presets, and project methods. |
+
+## Supported Findings
+
+- Audio track subtype, name, lock, enable, and voice isolation state probing
+  worked.
+- Audio item source audio mapping and MediaPoolItem audio mapping readback
+  worked on generated media.
+- Guarded audio property dry-run worked.
+- Voice isolation capability reporting worked for track and item scopes.
+- Auto-sync dry-run produced a normalized Resolve-constant settings payload.
+- MediaPoolItem transcription and clear-transcription both returned true on the
+  generated video clip.
+- Subtitle generation from the generated timeline returned true.
+- Fairlight preset listing and the full boundary report worked.
+
+## Boundaries
+
+- Timeline item audio properties may be readable as `None` and can reject writes
+  for some generated item types. The release probe saw `Volume` write and
+  restore return false.
+- `AutoSyncAudio` depends on media content and Resolve's sync engine. The
+  guarded call normalized waveform/channel settings but Resolve returned false
+  for the generated video/audio pair.
+- `InsertAudioToCurrentTrackAtPlayhead` can return false depending on current
+  track, page, and insertion state even with a valid generated audio path.
+- Transcription and subtitle APIs can be asynchronous, language-component
+  dependent, and license/build dependent even when they return true quickly.
+- The public API does not expose full Fairlight mix automation curves or plugin
+  parameter graphs.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+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-only media, probes track/item audio state, source/audio mappings,
+voice-isolation state, guarded property writes, auto-sync, transcription,
+subtitle generation, Fairlight preset listing, audio insertion, 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.

package/docs/kernels/color-grade-kernel.md

@@ -0,0 +1,103 @@
+# Color / Grade Kernel
+
+The Color / Grade kernel expands `timeline_item_color` into a safer grade
+inspection, versioning, copy, LUT, DRX, Gallery, and color-group boundary layer.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with a
+disposable `_mcp_color_grade_probe_*` project and generated synthetic color-bar
+media. Final release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 25 |
+| `version_or_page_dependent` | 2 |
+| `not_applicable` | 1 |
+| `partially_supported` | 0 |
+| `unsupported` | 0 |
+| `error` | 0 |
+
+The version/page-dependent results were Gallery still export and
+`ExportCurrentFrameAsStill(.drx)` in this Resolve/UI state. `safe_apply_drx`
+was marked `not_applicable` because the probe could not produce a DRX file
+through the public API in that run.
+
+## Added Actions
+
+All actions are exposed through `timeline_item_color`.
+
+| Action | Purpose |
+| --- | --- |
+| `grade_capabilities` | Return callable item methods, graph sources, LUT export types, version modes, guards, and known boundaries. |
+| `probe_grade_item` | Snapshot grade versions, item graph, color group, cache states, ids, names, and callable methods. |
+| `probe_node_graph` | Inspect item, timeline, pre-clip group, or post-clip group graph availability and node metadata. |
+| `safe_set_cdl` | Validate and normalize CDL payloads before calling `SetCDL`; supports dry run. |
+| `safe_copy_grade` | Resolve target timeline item IDs before calling `CopyGrades`; supports dry run. |
+| `safe_apply_drx` | Validate DRX file existence and temp-path guard before calling `ApplyGradeFromDRX`. |
+| `safe_export_lut` | Resolve LUT export type aliases and require temp output paths by default. |
+| `grade_version_snapshot` | Read current, local, and remote grade version names. |
+| `grade_version_restore` | Safely load a named local/remote version after verifying it exists. |
+| `color_group_capabilities` | Report color groups and pre/post graph availability. |
+| `gallery_capabilities` | Report Gallery availability, albums, and callable Gallery methods. |
+| `grade_boundary_report` | Return capabilities, current item snapshot, color groups, Gallery, and timeline graph summary. |
+
+## Scope Matrix
+
+| Scope | Probe Support | Mutation Support | Notes |
+| --- | --- | --- | --- |
+| Timeline item graph | Supported | CDL, LUT export, grade copy, DRX apply when file exists | Primary grade entry point. |
+| Timeline graph | Supported | Raw `graph` tool can mutate | Live probe found zero timeline nodes by default. |
+| Color group pre-clip graph | Supported | Raw `graph` tool can mutate | Requires existing `group_name`. |
+| Color group post-clip graph | Supported | Raw `graph` tool can mutate | Requires existing `group_name`. |
+| Gallery albums/stills | Partially environment dependent | Album create and list supported; still export may require UI panel state | Public API can return false if Gallery export is not ready. |
+
+## Supported Findings
+
+- `SetCDL` worked after payload validation and Resolve-specific string
+  normalization.
+- Item graph and timeline graph objects were available; item graph exposed one
+  node in the synthetic clip.
+- Node graph metadata probes worked for node count, LUT, cache mode, label, and
+  tools-in-node where Resolve returned data.
+- Local grade version add, rename, load, restore, and delete worked when the
+  version to delete was not currently loaded.
+- `CopyGrades` worked from the first synthetic timeline item to the second.
+- `ExportLUT` produced a 33-point `.cube` file under the generated temp probe
+  directory.
+- Color group create, assign, capability probe, pre/post graph probe, remove,
+  and delete worked.
+- Gallery capability and album list/create calls worked.
+
+## Boundaries
+
+- Node graph internals are intentionally limited by Resolve's public API. The
+  kernel can inspect high-level node count and a few node attributes, but not
+  every grading control inside a node.
+- `ApplyGradeFromDRX` replaces the target graph. There is no append mode in the
+  public API.
+- `safe_apply_drx` requires an existing DRX path. The live release probe could
+  not produce one because both Gallery still export and
+  `ExportCurrentFrameAsStill(.drx)` were unavailable in the current UI/build
+  state.
+- Gallery still export may require the Color page Gallery panel to be open and
+  ready. The public API returned false in the release probe even after the page
+  was active.
+- LUT export writes files, so `safe_export_lut` requires temp paths by default.
+- Stabilize, Smart Reframe, Magic Mask, and Magic Mask regeneration are exposed
+  as callable methods but are not forced in the boundary report because they can
+  be asynchronous, page dependent, and expensive.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+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,
+builds a two-item timeline, probes grade/node/version/copy/LUT/group/Gallery
+surfaces, writes JSON and Markdown reports, deletes the project, and removes
+generated media and exported probe files.
+
+Use `--keep-open` only when you intentionally want to inspect the disposable
+project by hand.