davinci-resolve-mcp 2.24.1 → 2.26.0

package/CHANGELOG.md

@@ -2,6 +2,161 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.26.0
+
+**Fusion group-settings helpers** — Three new `fusion_comp` actions for
+authoring and patching `GroupOperator` macros without leaving the kernel.
+`group_settings_export` writes a live group to a `.setting` file and returns a
+parsed `published_inputs` summary using a balanced-brace walker so nested
+`UserControls` / `ControlGroup` tables are bounded correctly (the original
+flat-regex parser truncated `InstanceInput` bodies at the first inner `}`).
+`group_settings_splice_inputs` replaces the `Inputs = ordered() { ... }` block
+of one `.setting` with the matching block from another, preserving the source's
+outer structure and inner `Tools`. `group_settings_load` applies a `.setting`
+to a live group with an automatic timestamped backup, wrapped in
+`StartUndo`/`Lock`/`LoadSettings`/`Unlock`/`EndUndo(True)` so Fusion's Ctrl+Z
+reverses the change — verified live via direct BMD API.
+
+**bulk_set_expressions** — Companion to the existing `bulk_set_inputs`. Batch
+attach Fusion expressions across many timeline-item comps in one call. Each op
+requires timeline scope plus `tool_name`, `input_name`, `expression`. Returns
+per-op `success`/`error` rows + `op_count`, matching the bulk-inputs contract.
+Useful for animating many controls at once (`time/30`, etc.) under a single
+chat turn.
+
+**Headless batch-runner CLI** — New
+`davinci-resolve-mcp batch <plan|run|status|list|resume|cancel>` subcommand
+drives `src/utils/media_analysis_jobs` from outside an MCP/chat client so long
+analysis batches can run via cron, CI, or terminal without holding a chat turn
+open. The orchestration loop and durable state stay in the existing jobs
+engine; the CLI only handles argv, progress streaming, and exit codes
+(`0` ok / `2` partial / `3` fatal / `130` Ctrl+C). JSON mode (`--json`)
+emits one record per progress event for log scraping. Closes #42.
+
+**Adapted from PR #40** — Group-settings work originated as a contribution
+from @RaincloudTheDragon; PR #43 retains the keepable parts (parser, exporter,
+splicer, loader, `bulk_set_expressions`) with a balanced-brace fix on the
+parser and an undo+lock wrap on `group_settings_load`. The two AMZ-specific
+templates and the static checklist from #40 were dropped as out-of-scope for a
+general kernel.
+
+## What's New in v2.25.0
+
+**Agentic flow improvements** — A second-pass review against the Claude
+Certified Architect study material drove a sweep of correctness gains. Every
+tool error now returns a structured envelope (`code` / `category` /
+`retryable` / `reason` / `remediation` / `message`); `retryable` defaults are
+locked per category so a host can make a one-shot retry decision without
+inference. Compound-tool descriptions for `media_analysis` and
+`timeline_item_color` adopt XML semantic tags (`<when_to_use>`, `<actions>`,
+`<returns>`) for cheaper per-turn parsing. Repeated failures on the same
+`(scope, action)` pair attach an `escalation` block on the 3rd response —
+halts auto-retry loops with a `suggested_action` for the host. Batch
+manifests now always carry `partial_success`, `completed_clip_ids`, and
+`failed_clip_ids` for safe targeted retry.
+
+**MCP resources surface** — 8 read-only resource URIs the host can poll
+without paying a tool-turn cost: `status://mcp_version`,
+`status://resolve_connection`, `status://current_project`,
+`status://current_timeline`, `status://caps_preset`,
+`analysis://recent_reports`, `capabilities://installed_tools`,
+`capabilities://install_guidance`. Paired tools still work for hosts that
+don't consume resources.
+
+**MCP prompts surface** — 5 slash-command workflow templates:
+`/davinci-resolve:analyze_and_propose_grade`,
+`/davinci-resolve:match_bin_to_hero`,
+`/davinci-resolve:verify_timeline_coverage`,
+`/davinci-resolve:open_and_analyze_selection`,
+`/davinci-resolve:prep_color_handoff`. First-class agentic intent, no
+re-derivation from SKILL.md prose.
+
+**Color-grading evidence base** — `timeline_item_color.grade_evidence_base`
+composes `version_snapshot` + `node_graph` + `color_group` + coverage report
+into a single `evidence_base` summary string; the SKILL guide now teaches
+agents to lead any color recommendation with that line.
+`timeline_item_color.propose_grade` formalizes a recommendation as a
+validated structured plan (returns `plan_id` + `preview_path`; requires
+explicit `execute=true` re-call). `bulk_match_to_hero` drives CDL-delta or
+copy-grade across many targets with a `confirm_token` gate and dry-run
+preview.
+
+**Analysis caps layer** — Token-budget governance for analysis. 7 cap
+dimensions across vision/transcription/job/clip/day scopes, 4 named presets
+(`minimal` / `standard` / `generous` / `unlimited`), pre-call refusal with
+`CAPS_REFUSAL` / `budget_exhausted` / `retryable: false`. New
+`media_analysis` actions: `get_caps`, `set_caps_preset`. Token usage table
+in the analysis DB plus a control-panel widget with gauges + override
+inputs. Wall-clock timeout helper wraps vision/transcription call sites.
+
+**Timeline versioning + analysis↔timeline marriage** — New
+`timeline_versioning` MCP tool: every destructive timeline edit
+auto-archives the current timeline into an Archive bin (compound, captions,
+ripple, gap close, etc.), so versions can be diffed and rolled back. Run
+scoping, schema v4 migrations, concurrency safety, structural snapshots,
+action filtering, strict mode, auto-save preference, media-pool destructive
+coverage, thumbnails. Backed by new modules `timeline_versioning.py`,
+`timeline_brain_db.py`, `brain_edits.py`, `analysis_runs.py`,
+`media_pool_changes.py`, `destructive_hook.py`. Surfaced in the control
+panel's Review → History view.
+
+**Async opt-in for long-running ops** — `analyze_clip` / `analyze_file` /
+`commit_vision` accept `prefer_handle: true`. When set (and the estimated
+runtime exceeds the configured threshold), the response is a fast handoff
+with `job_id` + `status: "queued"`; poll `batch_job_status({job_id})`.
+Default behavior unchanged.
+
+**Aggregated provenance** — `summarize`,
+`review_timeline_markers`, and `grade_evidence_base` now return a
+`provenance` block: `source_reports[]` (clip_id, signature, report_path,
+analyzed_at), `missing_reports[]` (per reason: `no_report` / `stale_report`
+/ `caps_refused`), and inline `[ref:<clip_id>]` citations in the human
+summary text. Multi-clip claims are now traceable.
+
+**Confirm-token gates on destructive batches** — `propose_grade`,
+`bulk_match_to_hero`, and other multi-target writes now require an explicit
+`confirm_token` on first execute (returned on the dry-run), with a
+`pending_user_decision` error if missing.
+
+**Action-help indirection** — `action_help(name=...)` returns the long-form
+guidance for a single action, keeping the top-level tool descriptions
+compact while preserving full per-action documentation.
+
+**Tool-choice hint emission** — Analyze responses include a
+`host_tool_choice_hint` block. Hosts that respect it pass
+`tool_choice={type:"tool", name:"media_analysis"}` on the next API turn,
+hard-locking the agent into the correct next call.
+
+**Update process hardening** — Five improvements layered onto the
+update-check path: active-job lock prevents updates mid-analysis, auto-stash
+strategy preserves uncommitted work across updates, restart-needed marker
+surfaces to the host, channels (`stable` / `beta` / `dev`), pre-update
+breaking-change scan, integrity SHA verification of downloaded artifacts,
+update history table, eager DB migration on update, and rollback to the
+previous build. New `analysis_caps.py` + `update_check.py` revisions.
+
+**Source-safe guardrails** — `destructive_hook.py` + decorator coverage
+tests ensure every destructive surface goes through the auto-archive path
+and never modifies, transcodes, or creates derivatives of source media.
+
+**Test surface** — 30+ new test modules covering error envelopes,
+failure tracking, partial-success manifests, `prefer_handle`, MCP resources,
+MCP prompts, provenance, XML description shape, `action_help`,
+`grade_evidence_base`, `propose_grade`, `bulk_match_to_hero`,
+`confirm_token`, the analysis caps layer, caps integration / events /
+history, timeline versioning, the timeline-brain DB, destructive decorator
+coverage, the destructive hook, update hardening, and update history.
+
+**Validation** — `tests/test_import.py`, `scripts/audit_api_parity.py`,
+`node bin/davinci-resolve-mcp.mjs --version`, `npm pack --dry-run`, and
+`git diff --check` all pass. 375 focused unit tests pass. Live Resolve
+validation covered the D1–F2 surface end-to-end against project CKY /
+Timeline 7 (D1 `retryable`, D2 XML descriptions, D3 partial-success on
+plans + CAPS_REFUSAL manifests, E1 8 MCP resource URIs, E2 escalation on
+3× repeated failure, E3 `prefer_handle` job handoff with
+`batch_job_status` polling, F1 provenance block) — 6/6 PASS on the
+fourteenth-attempt smoke test. No source media was modified.
+
 ## What's New in v2.24.1
 
 **`npx davinci-resolve-mcp` no longer breaks MCP clients when invoked without a

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.24.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.26.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-32%20(329%20full)-blue.svg)](#server-modes)

package/bin/davinci-resolve-mcp.mjs

@@ -41,6 +41,7 @@ Usage:
   davinci-resolve-mcp doctor [install.py options]
   davinci-resolve-mcp server [server.py options]
   davinci-resolve-mcp control-panel [control panel options]
+  davinci-resolve-mcp batch <plan|run|status|list|resume|cancel> [options]
   davinci-resolve-mcp --version
   davinci-resolve-mcp --help
 
@@ -48,6 +49,8 @@ Examples:
   npx davinci-resolve-mcp setup
   npx davinci-resolve-mcp setup --clients cursor,claude-desktop
   npx davinci-resolve-mcp doctor
+  npx davinci-resolve-mcp batch run /path/to/footage --depth standard
+  npx davinci-resolve-mcp batch run /path/to/footage --json > progress.log
 
 Environment:
   DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
@@ -335,6 +338,13 @@ function commandControlPanel(args) {
   run(command, commandArgs, { cwd: root });
 }
 
+function commandBatch(args) {
+  const root = syncManagedInstall(installRoot());
+  const python = venvPython(root) || findSupportedPython();
+  const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.batch_cli", ...args]);
+  run(command, commandArgs, { cwd: root });
+}
+
 function main() {
   const argv = process.argv.slice(2);
   // No args → run the MCP stdio server. Anything printed to stdout would
@@ -366,6 +376,10 @@ function main() {
       commandControlPanel(args);
       return;
     }
+    if (command === "batch") {
+      commandBatch(args);
+      return;
+    }
 
     console.error(`Unknown command: ${command}\n`);
     console.error(usage());

package/docs/SKILL.md

@@ -131,6 +131,11 @@ Code's Read tool handles JPG/PNG natively), produce the JSON, and call
 `pending_host_vision_analysis` — surface that explicitly; do not call the
 analysis complete.
 
+The deferred payload also includes a `host_tool_choice_hint` block. Hosts that
+respect this hint pass it as `tool_choice={type:"tool", name:"media_analysis"}`
+on the next API turn, hard-locking the agent into the correct next call. Hosts
+that don't recognize the field ignore it — the flow is unchanged for them.
+
 ## Local Control Panel
 
 If the user asks to open, launch, or inspect the Resolve MCP control panel, run
@@ -146,6 +151,11 @@ 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.
 
+The **Review tab → History** button opens the timeline-history surface:
+per-timeline version chain, brain-edit deltas, manual archive, and rollback.
+Backed by `timeline_versioning` MCP actions; see that tool's section below for
+the underlying primitives.
+
 ---
 
 ## Editorial Memory And Decision-Making
@@ -159,8 +169,15 @@ 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
+- `media_analysis(action="coverage_report", params={"target": {...}})` — the
+  pre-flight contract. Pure read; never triggers analysis. Returns per-clip
+  state (analyzed / stale / missing / reuse_blocked / superseded_by_relink),
+  layer presence, `source_trust` tier, and a `recommended_action`. The response
+  carries an `evidence_base` summary string — **lead any editorial or color
+  recommendation with that line, before the creative answer.**
+- `media_analysis(action="summarize")` for project-wide rollup of warnings,
+  motion distribution, and signed-report counts.
+- `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")`
@@ -168,15 +185,24 @@ contains useful evidence:
 - `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, host_chat_paths vision (followed
-by commit_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
+Reuse prior analysis unless it is stale, incomplete, missing a modality, or
+flagged `superseded_by_relink` because Resolve's source clip was replaced after
+analysis ran. Coverage_report surfaces all of these in one read. 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, host_chat_paths vision (followed by commit_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.
 
+Source-trust filtering: `coverage_report` accepts `min_source_trust` (one of
+`auto`, `filename`, `low`, `medium`, `high`). Clips below the threshold appear
+in `summary.clips_needs_higher_trust` and are reported with
+`below_min_source_trust=true`. Use `medium` for routine work, `high` for
+shot-matching or look-development passes where confident scene/identity reads
+matter.
+
 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
@@ -217,6 +243,13 @@ Be explicit about the API boundary:
   wheel values, log/HDR palette values, curves, qualifiers, power windows,
   tracking, Color Warper, and detailed ResolveFX/OFX parameter edits.
 
+Before any color recommendation, run
+`media_analysis(action="coverage_report", params={"target": {...},
+"min_source_trust": "medium"})` (use `"high"` for shot-matching or
+look-development passes). Lead the response with the returned `evidence_base`
+line before the grade plan. Coverage_report surfaces relink-superseded clips
+that must be re-analyzed before being graded from prior visual descriptions.
+
 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
@@ -415,12 +448,13 @@ report reuse, persisted analysis execution, host_chat_paths visual review
 metadata/marker writeback, 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`,
-`commit_vision`, `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`.
+`coverage_report`, `analyze_file`, `analyze_clip`, `analyze_bin`,
+`analyze_project`, `detect_sync_events`, `add_sync_event_markers`,
+`publish_clip_metadata`, `commit_vision`, `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.
@@ -434,14 +468,29 @@ 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.
+By default, planning checks the active project's analysis root and bounded
+related project-version roots for existing reports, then marks matching clips
+`skip_execution=true` when those reports already contain the requested
+technical, motion, transcription, and vision layers.
+Resolve clip records also carry the published third-party
+`davinci_resolve_mcp.analysis_report_path` when metadata writeback has run; use
+that provenance as a first-class reuse hint even if the report lives under a
+previous project-version analysis root.
+The planner also maintains an `analysis_registry.json` under the analysis base
+root. This registry indexes report paths by source path, clip id, media id, and
+signature so project renames and versioned Resolve projects can still find prior
+work quickly.
 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.
+when the user explicitly wants to ignore memory; pass
+`search_related_project_roots=false` only for intentionally isolated runs.
+If Resolve metadata shows prior MCP analysis but the planner cannot validate a
+matching report, execution returns `status="reuse_blocked"` instead of silently
+reanalyzing. Treat that as a project-memory integrity warning; restore the
+report or pass `force_refresh=true` only when the user explicitly wants fresh
+analysis.
 Transcription, visual analysis, metadata writeback, and Media Pool marker
 writeback are default-on. Vision uses
 `vision.provider="host_chat_paths"`: analyze actions extract representative
@@ -466,6 +515,10 @@ plus before/after cut-boundary frames as the sampled set. Skipping
 `commit_vision` leaves the run in `pending_host_vision_analysis` — that is a
 failure mode to surface, not a silent downgrade. The local mock providers are
 for tests and do not send frames off-machine.
+
+When creating timelines through `media_pool`, use `if_exists="reuse"` for
+idempotent reruns, `if_exists="version"` for deliberate alternate cuts, and
+`if_exists="fail"` when duplicate names indicate a workflow error.
 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
@@ -497,6 +550,111 @@ only when that mutation is intentional.
 
 ### Timelines
 
+**`timeline_versioning`** — Version-on-mutate, archive, rollback, brain-edit history (C6).
+
+Every destructive timeline op (compound, captions, ripple delete, gap close,
+retime, marker batch, track add/delete, take swaps, color grade, etc.) auto-
+archives the working timeline to the `Archive` bin under an `analysis_run_id`
+before the mutation runs. This tool surfaces and controls that history.
+
+Key actions:
+- `begin_run(label?, initiator?, analysis_run_id?)` — open a multi-step run.
+  Subsequent destructive calls auto-thread this run's ID, so a brain
+  operation that touches 5 clips creates ONE archive + 5 logged edits
+  instead of 5 separate archives.
+- `end_run(analysis_run_id?)` — close the run; aggregates brain_edits into
+  per-metric rollup in `analysis_runs.summary_json`.
+- `list_runs(limit?)` — recent runs newest first with their summaries.
+- `archive_current(reason?, analysis_run_id?)` — manual checkpoint of the
+  current timeline. Idempotent within an `analysis_run_id`. Also captures a
+  structural snapshot (every clip's placement, written to `timeline_clip_usage`)
+  and a thumbnail (when the Color page has a current clip).
+- `list_versions(timeline_name)` — version chain, oldest first. Each row
+  includes `archived_timeline_name`, `created_at`, `analysis_run_id`,
+  `initiator`, `thumbnail_path`, and `drt_export_path` (set when the version
+  was retention-collapsed to disk).
+- `diff_versions(timeline_name, from_version, to_version)` — structural diff
+  between two snapshots: `{added, removed, moved}` lists of clips by
+  media_pool_item_id and timeline position.
+- `get_history(timeline_name?, analysis_run_id?, limit?)` — brain-edit rows
+  with `edit_type`, `target_metric`, `before_value`, `after_value`, `delta`,
+  `rationale`, and `initiator`. Filter by timeline or run; defaults to 50.
+- `media_pool_changes(analysis_run_id?, media_pool_action?, limit?)` —
+  destructive media-pool history (deletes, replaces, relinks) from the
+  `media_pool_changes` table. Separate from brain_edits because the
+  addressable entity is a media_pool_item, not a timeline.
+- `rollback(timeline_name, version, analysis_run_id?)` — archive current first,
+  then duplicate the archived version back as a new `<name>_rolled_back_<HHMMSS>`.
+- `prune(timeline_name, keep_n=10)` — collapse old versions to `.drt` exports
+  under `<project>/_soul/timeline_versions/<slug>/` and remove them from the
+  bin. DB row preserved with `drt_export_path` populated for later rollback.
+- `registry()` — cross-project brain-edits registry that lives at the analysis
+  base root (one level above each project_root). Mirrors `analysis_registry.json`.
+
+**Strict mode** — `timeline.delete_timelines`, `timeline.delete_track`, and
+`timeline.delete_clips(ripple=True)` REFUSE to run when the pre-mutation
+archive can't be created. Pass `strict=true` on any destructive op to opt in.
+This prevents catastrophic ops from proceeding when versioning is broken.
+
+**Action filtering** — `timeline_item.set_property(key='Notes')` and
+`timeline.set_clip_property(key='Notes'|'Comments')` bypass versioning because
+free-text metadata isn't worth archiving. See `NO_ARCHIVE_ON_KEYS` in
+`src/utils/destructive_hook.py` to add more.
+
+**Preferences** — `timeline_versioning_auto_save_after_archive` (default false)
+triggers `project.SaveProject()` after every archive so Resolve crashes don't
+lose history. Configure via the `setup` tool's preferences.
+
+### Analysis Caps
+
+`media_analysis` honors a project-wide caps preset that controls 7 dimensions
+of analysis cost: response payload size, frames per clip, vision tokens per
+clip / per job / per day, wall-clock seconds per call, and the maximum frame
+image dimension before upload. Four named presets, plus per-field overrides.
+
+| Dimension                     | minimal | standard | generous  | unlimited |
+|------------------------------:|--------:|---------:|----------:|----------:|
+| response_chars                | 5,000   | 25,000   | 100,000   | none      |
+| vision_tokens_per_clip        | 5,000   | 25,000   | 100,000   | none      |
+| frames_per_clip               | 4       | 8        | 24        | none      |
+| vision_tokens_per_job         | 50,000  | 250,000  | 1,000,000 | none      |
+| vision_tokens_per_day         | 100,000 | 500,000  | 2,000,000 | none      |
+| wall_clock_seconds_per_call   | 30      | 90       | 300       | none      |
+| max_frame_dim_pixels          | 512     | 768      | 1280      | none      |
+
+Default preset: `standard`. Set via `media_analysis(action="set_caps_preset",
+preset=…, overrides={...})` or the dashboard's **Preferences → Analysis Caps**
+panel. Inspect via `media_analysis(action="get_caps")` which returns the
+effective values + a usage rollup (clip / job / day) with percent-consumed.
+`media_analysis(action="get_usage", scope="day"|"job"|"clip")` returns raw
+counts for one scope. Usage is tracked in
+`<project>/_soul/timeline_brain.sqlite` (`analysis_token_usage` table).
+
+The caps layer:
+- Slices `frame_paths` to `frames_per_clip` before the host LLM sees them.
+- Downscales each sampled frame in place to `max_frame_dim_pixels` (Pillow;
+  degrades silently to original-resolution upload if not installed).
+- Trims the analysis response payload to `response_chars`, dropping the
+  largest list/string fields first and marking the trim under `_trimmed`.
+- Records actual token usage from the host's `commit_vision` payload's
+  optional `usage: {vision_tokens, ...}` block. Hosts that don't report
+  tokens still get `frames_uploaded` recorded.
+
+Wall-clock timeout + cumulative-budget refusal are implemented in
+`src/utils/analysis_caps.py` and ready to hook at additional call sites in
+the analysis pipeline; the initial integration is at frame sampling +
+response construction + commit_vision usage recording.
+
+**Declared edits** — when the brain (or an agent acting deliberately) wants to
+measure an edit, pass `metric`, `direction`, and `rationale` in the params of
+the destructive call. The hook captures `before_value` and `after_value` from
+the live timeline (using the metric vocabulary in `brain_edits.py`) and writes
+them to the `brain_edits` row. Without these, the edit is still logged but with
+null metric — gives history without requiring deliberate intent.
+
+Supported metrics: `duration_seconds`, `avg_performance_score`, `clip_count`,
+`gap_count`, `total_gap_seconds`, `redundancy_score`.
+
 **`timeline`** — Timeline operations: tracks, clips, import/export, generators.
 
 Key actions:
@@ -765,6 +923,18 @@ Key actions:
 - `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`
+- `bulk_set_expressions(ops)` — batch attach expressions across multiple timeline
+  item comps in one call; each op requires timeline scope plus `tool_name`,
+  `input_name`, `expression`
+- `group_settings_export(group_name, path, include_advisory?)` — write a
+  `GroupOperator` to disk and return a parsed published-input summary
+- `group_settings_splice_inputs(source_path, template_path, dest_path?, source_group_name?, template_group_name?)` —
+  replace one `.setting` file's `Inputs = ordered() { ... }` block with the
+  matching block from another, preserving inner tools and outer structure;
+  balanced-brace parser handles nested `UserControls`
+- `group_settings_load(group_name, settings_path, backup_path?, undo_name?)` —
+  apply a `.setting` to a live group with an auto backup and an undo wrap so
+  Ctrl+Z reverses the change
 
 Fusion Composition kernel actions (v2.12.0+) add safer graph inspection and
 mutation wrappers around the raw Fusion API:

package/docs/guides/color-decision-guide.md

@@ -345,6 +345,45 @@ Do not promise node labels or node colors unless the available API path can
 actually write them. Existing labels, LUTs, tools, and cache state can be
 inspected and reported.
 
+## Pre-flight Coverage Check (required)
+
+Before answering any shot-matching, look-development, or per-clip grade question,
+call `timeline_item_color(action="grade_evidence_base", params={...})` against the
+target clip. The action is a pure read — it never mutates and never triggers
+analysis. It composes the version snapshot, node graph, color group, and
+`coverage_report` for the underlying media pool item into a single one-line
+`evidence_base` string. **Lead your response with that line — before any grade
+recommendation.**
+
+For sequence-wide checks (multiple clips, bin, timeline), use
+`media_analysis(action="coverage_report")` as before — the broader pre-flight
+covers all targets in one call.
+
+The response carries an `evidence_base` string and per-clip details: layer
+presence, source-trust tier, staleness reasons, relink supersedure, and a
+`recommended_action`. **Lead your response to the user with the `evidence_base`
+line — before any grade recommendation.**
+
+For color work, source-trust matters more than for editorial. Use the
+`min_source_trust` parameter to gate recommendations:
+
+- `coverage_report(min_source_trust="medium")` for routine corrections.
+- `coverage_report(min_source_trust="high")` for hero shots, look-development
+  passes, and any decision that depends on confident scene/lighting recognition.
+
+Clips below the threshold appear in `summary.clips_needs_higher_trust` and
+should be re-analyzed with an explicit higher `source_trust` before being graded
+from their visual descriptions.
+
+Relink-superseded clips (`superseded_by_relink=true`) must never be reasoned
+about as if the prior analysis still describes the current media. The prior
+report is preserved for reference, but a re-analysis is required before
+shot-matching or look development is grounded.
+
+If existing analysis flags exposure issues, clipped highlights, color cast
+warnings, or scene-of-interest notes, surface those before proposing CDL or
+node-graph changes.
+
 ## Agent Response Rules
 
 When answering a color request, classify the requested operation:
@@ -368,6 +407,7 @@ DCTL, or CDL is equivalent to a full colorist pass.
 
 ## Useful MCP Calls
 
+- `media_analysis(action="coverage_report", params={...})` — pre-flight evidence-base check
 - `resolve_control(action="open_page", params={"page": "color"})`
 - `timeline_item_color(action="grade_boundary_report", params={...})`
 - `timeline_item_color(action="probe_grade_item", params={...})`

package/docs/guides/editorial-decision-guide.md

@@ -38,6 +38,35 @@ the user explicitly needs. A new request for edit advice is not automatically a
 reason to re-run visual analysis if the prior report already has current
 technical data, motion/keyframe evidence, and useful visual descriptions.
 
+## Pre-flight Coverage Check (required)
+
+Before answering any cut, pacing, story-structure, or shot-selection question,
+call `media_analysis(action="coverage_report")` against the target you're about
+to reason about (timeline, bin, selection, or project). The action is a pure
+read — it never triggers analysis.
+
+The response includes an `evidence_base` string (e.g. `"evidence base: 38/40
+clips analyzed (95%), 1 stale, 1 reuse-blocked."`) and a per-clip breakdown
+covering layer presence, source-trust tier, staleness reasons, relink
+supersedure, and a `recommended_action`.
+
+**The response to the user must lead with the `evidence_base` line — before any
+creative recommendation.** This mirrors the `pending_host_vision_analysis`
+honesty pattern: do not silently answer from incomplete evidence. If coverage
+is below the threshold the user's question depends on, surface that gap first
+and offer to fill it (e.g. "3 of the clips on this timeline have no transcript;
+analyzing them first will materially change my cut-point suggestions — run it
+now?").
+
+When the gap is small and the user is okay proceeding, still answer — but mark
+the answer as evidence-thin so they can re-ask once gaps are filled. Do NOT
+auto-trigger analysis to fix gaps unless the user explicitly asks.
+
+Relink-superseded clips (`superseded_by_relink=true`) must never be reasoned
+about as if the prior analysis still describes them. The prior report is
+preserved for reference, but a re-analysis is required before the recommendation
+is grounded.
+
 ## Frame Choice
 
 Find the decisive frame, not just the technically clean frame. Useful cut points

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

@@ -30,10 +30,40 @@ All actions are exposed through `fusion_comp`.
 | `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. |
+| `bulk_set_expressions` | Batch `SetExpression` across scoped timeline-item Fusion comps. Each op needs `tool_name`, `input_name`, `expression`, plus a timeline scope. Wraps each op in `StartUndo`/`EndUndo` + `comp.Lock`. |
+| `group_settings_export` | Save a named `GroupOperator`'s settings to a `.setting` file via `SaveSettings`, returning a parsed published-input summary. |
+| `group_settings_splice_inputs` | Replace the `Inputs = ordered() { ... }` block of `source_path` with the matching block from `template_path` and write `dest_path`. Read-only against Resolve; pure file operation. |
+| `group_settings_load` | Backup the current group state, then `LoadSettings` from a `.setting` file. Wrapped in `StartUndo`/`EndUndo` + `comp.Lock` so Fusion's Ctrl+Z can reverse it. Backup path is returned alongside any error. |
+| `probe_group_published_inputs` | Read live published `Input1..InputN` slots off a `GroupOperator`, optionally cross-referenced with a `.setting` file summary. |
 
 The pre-existing `bulk_set_inputs` action remains the batch path for applying
 input writes across multiple explicitly scoped timeline-item Fusion comps.
 
+### `group_settings_splice_inputs` notes
+
+The Fusion `.setting` format is a Lua-like nested structure: an InstanceInput
+commonly contains `UserControls = ordered() { Custom = { ... } }` tables, so any
+parsing that uses a flat regex will truncate bodies at the first inner `}`. This
+kernel uses balanced-brace scanning end-to-end. Practical implications:
+
+- The action only swaps the published `Inputs = ordered() { ... }` block. The
+  group's outer name, inner `Tools = ordered() { ... }` section, and surrounding
+  structure are preserved byte-for-byte.
+- You must provide the *new* layout as a real `.setting` file (typically
+  exported from a known-good group via `group_settings_export`). The kernel does
+  not ship hardcoded templates.
+- `template_group_name` is optional when the template file contains a single
+  `GroupOperator`; pass it when the template file contains multiple groups and
+  you want a specific one.
+
+### `group_settings_load` Edit-page caveat
+
+`LoadSettings` may update inner tool wiring but not refresh Edit-page
+`InstanceInput` order until the group is selected in Fusion and reloaded via UI.
+This is a Resolve quirk, not a kernel bug. The action always backs up the group
+to a timestamped sibling of `settings_path` first; the backup path is returned
+in success and in error responses.
+
 ## Scope Matrix
 
 | Scope | Probe Support | Mutation Support | Notes |

package/docs/reference/api-coverage.md

@@ -6,7 +6,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **32** compound (default) / **329** granular |
+| MCP Tools | **33** compound (default) / **329** granular |
 | Kernel Actions | **136** guarded MCP workflow actions across 9 compound tools |
 | API Methods Covered | **336/336** (100%) |
 | Methods Live Tested | **331/336** (98.5%) |
@@ -17,7 +17,13 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 ## API Coverage
 
-Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **32 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **329 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
+Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **33 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **329 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
+
+The 33rd compound tool is `timeline_versioning` (C6) — an MCP-level workflow
+tool, not a wrapper around a Resolve API method. It surfaces the
+version-on-mutate hook that auto-archives the working timeline before any
+destructive op, plus rollback and brain-edit history. See [SKILL.md](../SKILL.md)
+for usage.
 
 Workflow helpers can go beyond one-to-one API method coverage while still using
 only public Resolve calls. For example, `media_pool.setup_multicam_timeline`