davinci-resolve-mcp 2.24.0 → 2.25.0

package/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 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.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
+subcommand.** The npm bootstrapper previously defaulted to `--help`, which wrote
+usage text to stdout and exited 0. MCP stdio clients (Hermes Agent, Claude
+Desktop, Cursor, etc.) read that as malformed JSON-RPC, retried three times,
+then dropped the connection. `bin/davinci-resolve-mcp.mjs` now defaults to the
+`server` subcommand when no arguments are supplied. Explicit `--help`, `-h`,
+`help`, `--version`, and `-v` continue to print to stdout as before, and
+existing configs that already pass `server` explicitly are unaffected. Reported
+in [#41](https://github.com/samuelgursky/davinci-resolve-mcp/issues/41).
+
 ## What's New in v2.24.0
 
 **Host-chat vision protocol (V2)** — `analyze_*` actions now use
@@ -88,10 +217,7 @@ ffprobe/ffmpeg resolve even when the MCP server is launched by a GUI app
 Mandatory" section. `docs/SKILL.md` rewrites the `analyze_media` prompt
 guidance for the host-chat-paths protocol and adds the anti-regression rule.
 `docs/guides/media-analysis-guide.md` covers the deferred vision payload and
-commit step. New design docs under `docs/design/`:
-`v2-control-panel-design.md`, `v2-db-schema.sql`,
-`v2-implementation-gameplan.md`, `v2-shot-schema-spec.md`,
-`control-panel-polish-gameplan.md`.
+commit step.
 
 **Validation**: static import checks, API parity audit, focused
 media-analysis + marker/range/v232/v233 unit tests, npm CLI smoke,

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.24.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.25.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)
@@ -11,6 +11,10 @@
 
 A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
 
+[![Local control panel](docs/images/control-panel/01-overview.png)](docs/guides/control-panel.md)
+
+A local browser control panel ships with the server for inspecting Resolve state, running source-safe analysis, drilling into analyzed clips and shots, and editing analysis output inline. See the [Control Panel Guide](docs/guides/control-panel.md) for the full tour.
+
 ## Quick Start
 
 ```bash
@@ -114,6 +118,7 @@ For method-by-method status, see [API Coverage and Test Results](docs/reference/
 | [API Coverage and Test Results](docs/reference/api-coverage.md) | Key stats, API coverage table, live-test status, full method reference |
 | [Kernel Action Coverage](docs/kernels/README.md) | Current guarded workflow action map |
 | [AI Skill Reference](docs/SKILL.md) | Operational context for AI assistants using the compound server |
+| [Control Panel Guide](docs/guides/control-panel.md) | Local browser panel tour: Overview, Review (bin/clip/shot), Analyze, Setup, Preferences |
 | [Media Analysis Guide](docs/guides/media-analysis-guide.md) | Source-safe FFprobe, FFmpeg, Whisper, sidecar, and analysis-root workflows |
 | [Multicam Setup Helper Guide](docs/guides/multicam-setup-guide.md) | Stacked timeline prep, helper/API boundary, and Resolve UI conversion steps |
 | [Editorial Decision Guide](docs/guides/editorial-decision-guide.md) | Project-owned editorial craft guidance for analysis and timeline decisions |

package/bin/davinci-resolve-mcp.mjs

@@ -336,7 +336,10 @@ function commandControlPanel(args) {
 }
 
 function main() {
-  const [command = "--help", ...args] = process.argv.slice(2);
+  const argv = process.argv.slice(2);
+  // No args → run the MCP stdio server. Anything printed to stdout would
+  // otherwise be parsed as JSON-RPC by MCP clients and break the connection.
+  const [command = "server", ...args] = argv;
 
   try {
     if (command === "--help" || command === "-h" || command === "help") {

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:

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/control-panel.md

@@ -0,0 +1,128 @@
+# Local Control Panel
+
+The DaVinci Resolve MCP ships with a local, single-user browser control panel for
+inspecting Resolve state, running source-safe media analysis, drilling into
+analyzed clips and shots, fixing analysis output inline, and managing
+preferences.
+
+The panel is a local HTTP server (default `http://127.0.0.1:8765`). It does not
+expose a network listener beyond loopback and does not modify source media.
+
+## Launching the panel
+
+```bash
+# From source
+venv/bin/python -m src.control_panel
+
+# From the npm package
+npx davinci-resolve-mcp control-panel
+
+# From a chat client via MCP
+resolve_control(action="open_control_panel")
+```
+
+Once running, you can `resolve_control(action="control_panel_status")` to check
+the pidfile or `resolve_control(action="close_control_panel")` to stop it.
+
+## Tour
+
+### Overview
+
+![Control panel overview](../images/control-panel/01-overview.png)
+
+The Overview tab is the at-a-glance summary for the active project: Resolve
+connection state, source clip counts, analysis progress, search index size,
+and the source-media safety status.
+
+### Analysis → Analyze
+
+![Analyze view](../images/control-panel/06-analyze.png)
+
+The Analyze view inventories the Resolve media pool read-only and lets you
+queue source-safe analysis jobs. Filters cover bin, media type, clip status,
+and analysis status. Resolve media stays read-only; analysis outputs land under
+the configured analysis root.
+
+### Analysis → Review (bin grid)
+
+![Review bin grid](../images/control-panel/02-review-bin-grid.png)
+
+The Review surface is the browser for analyzed clips. Each card shows a
+representative thumbnail, summary one-liner, primary use, shot count, and tags.
+Click into a card to drill down.
+
+### Clip detail
+
+![Clip detail with shot strip](../images/control-panel/03-clip-detail.png)
+
+The clip view shows the full summary, tags, editorial notes, and a strip of
+every detected shot with thumbnails. From here you can open the clip in
+Resolve, jump to the transcript, or click into any shot for the full V2 field
+breakdown.
+
+### Transcript
+
+![Transcript view with word-level timing](../images/control-panel/04-transcript.png)
+
+The transcript view is reachable from the clip detail (top-right `Transcript`
+button). Each segment shows its start timecode, the cleaned sentence, and the
+word-level transcription beneath. The segment filter narrows by text; clicking
+a segment can jump the Resolve playhead to that source time. `Re-transcribe
+with words` re-runs the configured local transcription backend (Whisper by
+default) without re-doing visual analysis, and `corrections.json` captures
+inline edits so they survive future re-runs.
+
+### Shot detail with inline correction
+
+![Shot detail with V2 fields and frames](../images/control-panel/05-shot-detail.png)
+
+The shot view shows every V2 schema field (shot size, framing, camera height,
+motion direction, lens character, lighting, composition notes, and more)
+alongside the frames the vision pass actually saw. Each subjective field is
+editable inline — edits land in `corrections.json` with an append-only
+changelog and are merged on top of the next re-analysis so human notes survive
+fresh vision runs. `Open in Resolve` bounces you straight to the clip in the
+source viewer with the shot's mark in/out set.
+
+### Setup → Resolve diagnostic
+
+![Setup / Resolve diagnostic](../images/control-panel/07-diagnostics-resolve.png)
+
+The Resolve diagnostic page reports the live connection, product/version,
+active page, project identity, and media pool inventory. Useful when chat
+sessions need to confirm Resolve is reachable before issuing scripted
+operations.
+
+### Preferences → Analysis
+
+![Preferences / Analysis defaults](../images/control-panel/08-preferences-analysis.png)
+
+Server-wide analysis defaults: vision on/off, transcription default, slate
+detection, source-trust grading (`auto` / `filename` / `low` / `medium` /
+`high`), default analysis depth, default sample frame count, persistence
+behavior, summary style, and report format. These are the defaults the
+`analyze_media` prompt uses when not overridden per call.
+
+## Chat ↔ panel state sharing
+
+The panel and chat share focus state through `panel_state.json` (under the
+active project's analysis root). MCP actions:
+
+- `media_analysis(action="get_panel_state")` — read current focus (project,
+  clip, shot)
+- `media_analysis(action="set_panel_state", params={...})` — set focus from
+  chat
+- `media_analysis(action="session_start_context")` — bootstrap a chat session
+  with the panel's current focus
+
+The dashboard polls `/api/panel_state` every 2 seconds, so changes from chat
+appear in the UI without a refresh.
+
+## Open in Resolve
+
+The shot view and clip view both have an Open-in-Resolve action. Under the
+hood this calls `media_pool_item(action="open_in_viewer", params={clip_id,
+mark_in, mark_out})`, which selects the clip on the Media page, loads it into
+the source viewer, sets mark in/out, and brings Resolve to the foreground via
+an OS-level window activation (AppleScript on macOS, PowerShell `AppActivate`
+on Windows, wmctrl/xdotool on Linux).