davinci-resolve-mcp 2.39.0 → 2.41.0

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 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.41.0
+
+DB-canonical clip analysis (C1) — Phase A of the analysis + edit-engine
+program. The per-project SQLite DB is now the source of truth for clip
+analysis; `analysis.json` becomes a derived export written in lockstep.
+
+- **Added** schema v9 to the per-project timeline-brain DB: `clips`,
+  `clip_aliases`, `analysis_reports` (canonical full payload), `shots`,
+  `subjective_fields` + `field_changelog` (per-field provenance),
+  `transcript_segments`, `frames`, and `qc_observations`.
+- **Added** `src/utils/analysis_store.py`: transactional ingest, export with
+  human-correction overlay (human rows always win and survive re-analysis),
+  alias-based clip lookup, shot ids stable under one-second boundary jitter,
+  and a round-trip guard verified against a real sample analysis root.
+- **Added** `media_analysis` actions `db_status` (schema version + row
+  counts) and `db_ingest` (one-shot migration of existing JSON reports and
+  `corrections.json` sidecars into the DB).
+- **Changed** the analysis write path: `execute_plan` and `commit_vision`
+  write DB rows first, then export the JSON. Panel clip/shot endpoints read
+  DB-first with JSON fallback for pre-v9 reports and job-linked report dirs.
+- **Changed** `update_clip_field` / `update_shot_field` / `revert_field` to
+  mirror corrections into the DB as row-level provenance (the
+  `corrections.json` sidecar remains for compatibility).
+- **Fixed** eight V2 actions that were unreachable from MCP dispatch since
+  v2.24.0 (`get_panel_state`, `set_panel_state`, `session_start_context`,
+  `update_shot_field`, `update_clip_field`, `get_field_history`,
+  `revert_field`, `list_corrections`): they were checked inside the
+  project-root dispatch block but missing from its membership set. The
+  control panel proxied to the helpers directly, which masked it.
+- **Fixed** the action-list drift guard to inspect async tool functions
+  (media_analysis had drifted unchecked) and to fail on actions that are
+  unreachable inside membership blocks — the exact class above. Four
+  reachable-but-unadvertised actions (`coverage_report`,
+  `get_resolve_ai_usage`, `get_ai_governance`, `set_ai_governance`) are now
+  listed in the unknown-action error.
+- **Validation**: full offline suite (1066 tests; 12 new), round-trip guard
+  on the real 2026-05-17 sample root, and a live headless pipeline run on
+  synthetic media verifying rows-then-export parity, row-level corrections,
+  and DB-first panel reads.
+
+## What's New in v2.40.0
+
+Control panel UX overhaul + docs refresh, from a full live audit of every
+panel view, with drift guards so neither can silently go stale again.
+
+- **Added** a governance mode toggle (Advisory / Enforce) to the AI Console,
+  with corrected copy (the old text predated v2.39.0 enforce mode), and a
+  Recent-runs list on the AI-ops ledger showing each run's actor.
+- **Added** chat-first onboarding: empty Overview, Review, and Inventory
+  states show plain-language guidance with a copyable suggested prompt
+  instead of zero-walls and MCP action names.
+- **Added** History as a first-class Media menu item, deep-linkable at
+  `#analysis/review/history`; documented the full hash deep-link scheme.
+- **Changed** the top-level "Analysis" menu to "Media" (it collided with the
+  Preferences page of the same name); "Analyze" is now "Inventory". Full
+  vocabulary pass: humanized readiness chips and frame-sampling labels, no
+  internal codenames, file names, or absolute paths in UI copy.
+- **Fixed** the README's linked screenshot rendering broken in the Docs
+  reader: badge parsing no longer claims local linked images, and a new
+  `/api/doc_asset/` route serves repo doc images (path-constrained).
+- **Fixed** poll hygiene: timers pause while the tab is hidden, panel-state
+  polling backs off when unfocused, and unchanged inventory polls return a
+  tiny 200 instead of a 304 that Chrome logged as an aborted request.
+- **Docs**: `docs/guides/control-panel.md` fully rewritten for the current
+  IA with all screenshots regenerated from the live panel
+  (`scripts/regen_panel_screenshots.py`). A new drift-guard test fails the
+  suite — and the publish workflow, which now runs all three static guards
+  on every tag — when the guide drifts from the panel's navigation or
+  screenshots.
+
 ## What's New in v2.39.0
 
 Governance enforce mode and actor identity — the staged Phase 3 of the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.39.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.41.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-33%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -491,8 +491,24 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `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`.
+`cancel_batch_job`, `resume_batch_job`, `review_timeline_markers`,
+`cleanup_artifacts`, `db_status`, `db_ingest`, `get_panel_state`,
+`set_panel_state`, `session_start_context`, `update_clip_field`,
+`update_shot_field`, `get_field_history`, `revert_field`, and
+`list_corrections`.
+
+**DB-canonical analysis store (v2.41.0+).** The per-project SQLite DB
+(`_soul/timeline_brain.sqlite`, schema v9+) is the source of truth for clip
+analysis; `analysis.json` is a derived export written in lockstep. Analysis
+runs write rows first (clips, shots, per-field subjective provenance,
+transcript segments, sampled frames, QC observations) and then export the
+JSON. Human corrections recorded via `update_clip_field` / `update_shot_field`
+live as row-level provenance and always survive re-analysis. Readers
+(panel API, exports) load DB-first and fall back to `analysis.json` for
+reports that predate v9. `db_status` reports schema version + row counts;
+`db_ingest` migrates an existing project's JSON reports (and
+`corrections.json` sidecars) into the DB — run it once on older analysis
+roots.
 The tool never installs
 dependencies and validates that outputs stay under
 `davinci-resolve-mcp-analysis` project roots rather than beside source media.

package/docs/guides/control-panel.md

@@ -1,9 +1,9 @@
 # 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 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, reviewing timeline
+edit history, driving Resolve's local AI operations, 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.
@@ -21,8 +21,29 @@ npx davinci-resolve-mcp control-panel
 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.
+Once running, `resolve_control(action="control_panel_status")` checks the
+pidfile and `resolve_control(action="close_control_panel")` stops it.
+
+## Navigation and deep links
+
+Top-level sections: **Overview**, **Media** (Inventory / Review / History),
+**AI Console**, **Setup** (Resolve / MCP / Storage / Tools / Media Pool
+History), **Docs**, and **Preferences** (Analysis / Caps + Safety / Metadata
+and Markers / Paths and Workflow / MCP Updates). The project selector on the
+right scopes the panel to an analysis context; **View All Projects** opens a
+read-only browser over the Resolve project database with confirm-gated
+loading.
+
+Every view is addressable by URL hash, so links can be bookmarked or pasted
+into chat:
+
+```
+#overview                                  #aiconsole
+#analysis/media                            #analysis/review
+#analysis/review/history                   #analysis/review/clip/<clip_id>
+#analysis/review/clip/<clip_id>/shot/<n>   #analysis/review/clip/<clip_id>/transcript
+#diagnostics/mcp                           #preferences/caps
+```
 
 ## Tour
 
@@ -30,78 +51,125 @@ the pidfile or `resolve_control(action="close_control_panel")` to stop it.
 
 ![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.
+The at-a-glance summary for the active project: Resolve connection state,
+source clip counts, analysis progress, search-index status, and the
+source-media safety posture. When the project has no source clips yet, the
+view shows a get-started card with a suggested chat prompt and a
+**Copy prompt** button — the panel is summoned by conversation, and its empty
+states point back into it.
 
-### Analysis → Analyze
+### Media → Inventory
 
-![Analyze view](../images/control-panel/06-analyze.png)
+![Inventory view](../images/control-panel/06-inventory.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.
+Inventory walks the Resolve Media Pool read-only and filters to source clips so
+timelines, compounds, titles, and generated items stay out of analysis queues.
+Filters cover bin, media type, clip status, and analysis status, with optional
+auto-refresh polling. From here you can select analyzable clips, copy a
+ready-made analysis prompt for your chat session, or launch a supported chat
+client directly.
 
-### Analysis → Review (bin grid)
+### Media → Review
 
 ![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.
+Review is the browser for analyzed clips. The readiness strip summarizes the
+evidence base (analyzed / superseded / vision-pending / warnings) with
+humanized source-trust and analysis-layer chips. Cards show a representative
+thumbnail, duration, shot count, status, and summary one-liner; grid and list
+layouts are available, and full-text search covers clips, summaries, tags, and
+transcripts once the search index is built.
 
 ### 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.
+The clip view shows the full summary, tags, star rating, editorial notes, and
+a contact sheet of every detected shot. From here you can open the clip in
+Resolve, jump to the transcript, or click into any shot.
 
 ### 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.
+Each segment shows its start time, the cleaned sentence, and the original
+machine transcription beneath. Inline edits are preserved across re-analysis,
+and `Re-transcribe with words` re-runs the configured local transcription
+backend (Whisper by default) without re-doing visual analysis.
 
 ### Shot detail with inline correction
 
-![Shot detail with V2 fields and frames](../images/control-panel/05-shot-detail.png)
+![Shot detail with 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.
+The shot view shows the analysis fields for the shot alongside the frames the
+vision pass actually sampled, each labeled with why it was chosen ("Shot
+start", "After cut", "Flash frame", "Motion peak"). Subjective fields are
+editable inline; edits are kept with the clip's analysis and merged on top of
+future re-analysis so human notes survive fresh vision runs. `Open in Resolve`
+jumps straight to the clip in the source viewer with the shot's mark in/out
+set.
 
-### Setup → Resolve diagnostic
+### Media → History
 
-![Setup / Resolve diagnostic](../images/control-panel/07-diagnostics-resolve.png)
+![Timeline history](../images/control-panel/10-history.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.
+The timeline edit history: archived timeline versions and brain edits per
+timeline. Begin/end labeled runs to group related edits, archive the current
+timeline before risky work, and select any timeline to inspect its version
+chain and the edits between versions. Every destructive timeline edit made
+through the MCP archives a version here automatically.
+
+### AI Console
+
+![AI Console with governance](../images/control-panel/09-ai-console.png)
+
+Runs Resolve's local AI operations (audio classification, IntelliSearch, slate
+analysis, transcription, motion deblur, speech generation) on the current
+Media Pool folder or a specific clip. Capability dots show what this Resolve
+build exposes and which AI Extras are required. The **Governance** card sets
+the per-session tier (off / lenient / standard / strict) for the two
+media-creating ops and the governance **mode**: *Advisory* warns in the
+confirm dialog; *Enforce* refuses an over-tier run until you raise the tier,
+relax the mode, or consciously override. Usage gauges track runs, media
+created, and render time against the active tier, and the AI-ops ledger
+(Preferences → Caps + Safety) records every run with the acting instance.
+
+### Setup
+
+![Setup / Resolve diagnostic](../images/control-panel/07-diagnostics-resolve.png)
 
-### Preferences → Analysis
+- **Resolve** — live connection, product/version, active page, project
+  identity, and Media Pool inventory.
+- **MCP** — server identity, detected Resolve scripting paths, transport
+  status (with a start button for the networked mode), and per-client install
+  status with one-click install/repair for every supported harness.
+- **Storage** — the analysis root, search index, and jobs database paths and
+  sizes for the active project.
+- **Tools** — runtime helpers (ffprobe, ffmpeg, Whisper backends, OpenCV)
+  with ready/missing status and copyable install commands.
+- **Media Pool History** — the provenance log for destructive media-pool
+  operations (deletes, replaces, relinks), kept separate from timeline brain
+  edits.
+
+### Preferences
 
 ![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.
+Server-wide defaults for this MCP install (dashboard-only conveniences stay in
+the browser):
+
+- **Analysis** — vision/transcription defaults, slate detection, source-trust
+  grading, depth, frame-sampling mode, summary style, report format.
+- **Caps + Safety** — token and frame budget presets (minimal / standard /
+  generous / unlimited) with live usage gauges, per-clip/job/day caps, the
+  Resolve AI-ops ledger, and destructive-edit safety rails.
+- **Metadata and Markers** — Resolve metadata write-back fields, timed-marker
+  defaults, marker types and colors, overwrite policy.
+- **Paths and Workflow** — preferred analysis root, generated-media folder,
+  post-operation page behavior, and a read-only map of where files live.
+- **MCP Updates** — update policy (prompt / notify / auto / never), release
+  channel (stable / beta / dev), check cadence, apply/rollback with update
+  history.
 
 ## Chat ↔ panel state sharing
 
@@ -115,8 +183,9 @@ active project's analysis root). MCP actions:
 - `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.
+The dashboard polls `/api/panel_state` every 2 seconds while it has focus,
+backs off to roughly every 10 seconds when the window is unfocused, and stops
+polling entirely while the tab is hidden.
 
 ## Open in Resolve
 

package/docs/process/release-process.md

@@ -30,6 +30,11 @@ Every release bump must update all version surfaces:
 - README current stats or latest-release summary when they changed
 - `CHANGELOG.md` latest release entry
 - `docs/SKILL.md` when tool discovery, examples, or behavior changed
+- `docs/guides/control-panel.md` when the control panel UI changed, plus
+  regenerated screenshots: start the panel against a project with analysis
+  data, then run `venv/bin/python scripts/regen_panel_screenshots.py`.
+  The `tests.test_panel_docs_drift` guard fails the suite (and the publish
+  workflow) when the guide drifts from the panel's navigation or screenshots.
 - Git tag, e.g. `v2.4.1`
 - GitHub Release notes
 
@@ -43,12 +48,18 @@ Always run static checks before release:
 ```bash
 venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
+venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version
 npm pack --dry-run
 git diff --check
 ```
 
+The three drift guards (undefined names in `src/`, tool action lists vs
+dispatch, control-panel guide vs panel navigation/screenshots) also run in the
+`Publish npm package` workflow on every `v*` tag, so a stale doc or drifted
+action list fails the publish — fix the drift rather than bypassing the gate.
+
 Run focused unit tests for the changed surface. For recent timeline/marker
 helpers, this usually includes:
 

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.39.0"
+VERSION = "2.41.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.39.0",
+  "version": "2.41.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/regen_panel_screenshots.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Regenerate the control-panel doc screenshots from a live panel.
+
+Drives the panel's hash deep links headlessly and writes 1280x800 captures
+into docs/images/control-panel/. Run whenever the panel UI changes visibly.
+
+Setup:
+  1. venv/bin/pip install playwright  (chromium is fetched on first run if absent)
+  2. Start the panel bound to a project that HAS an analyzed clip, e.g.:
+       venv/bin/python -m src.control_panel --no-open
+     (Bind to a rich analysis context if the live Resolve project is empty.)
+  3. venv/bin/python scripts/regen_panel_screenshots.py [--clip-id <id>] [--port 8765]
+
+The clip id defaults to the first analyzed clip reported by /api/clips.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+import urllib.request
+
+OUT_DIR = pathlib.Path(__file__).resolve().parent.parent / "docs" / "images" / "control-panel"
+
+
+def first_clip_id(base: str) -> str:
+    with urllib.request.urlopen(f"{base}/api/clips", timeout=10) as resp:
+        payload = json.load(resp)
+    clips = payload.get("clips") or []
+    if not clips:
+        sys.exit("No analyzed clips in the panel's project — bind the panel to a project with analysis data first.")
+    return clips[0]["clip_id"]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--clip-id", default=None)
+    args = parser.parse_args()
+    base = f"http://127.0.0.1:{args.port}"
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        sys.exit("playwright not installed: venv/bin/pip install playwright")
+
+    clip = args.clip_id or first_clip_id(base)
+    shots = [
+        ("#overview", "01-overview.png", 3000),
+        ("#analysis/review", "02-review-bin-grid.png", 3500),
+        (f"#analysis/review/clip/{clip}", "03-clip-detail.png", 4000),
+        (f"#analysis/review/clip/{clip}/transcript", "04-transcript.png", 4000),
+        (f"#analysis/review/clip/{clip}/shot/3", "05-shot-detail.png", 4500),
+        ("#analysis/media", "06-inventory.png", 3500),
+        ("#diagnostics/resolve", "07-diagnostics-resolve.png", 3000),
+        ("#preferences/analysis", "08-preferences-analysis.png", 3000),
+        ("#aiconsole", "09-ai-console.png", 3000),
+        ("#analysis/review/history", "10-history.png", 3500),
+    ]
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch()
+        page = browser.new_page(viewport={"width": 1280, "height": 800})
+        for hash_, name, wait in shots:
+            page.goto(f"{base}/{hash_}")
+            page.wait_for_timeout(wait)
+            page.screenshot(path=str(OUT_DIR / name))
+            print("shot:", name)
+        browser.close()
+    print(f"done — {len(shots)} screenshots in {OUT_DIR}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())