davinci-resolve-mcp 2.23.1 → 2.24.1

package/AGENTS.md

@@ -9,12 +9,35 @@ kernel-action counts, release notes, or long reference tables here.
 Never modify, transcode, convert, proxy, relink, replace, or create derivatives
 of source media unless the user explicitly asks for that exact operation.
 
-Analysis workflows may read source media, but outputs must go to sidecar files,
-session scratch space, or the configured `davinci-resolve-mcp-analysis` project
-root. Preserve the chain from camera original to final delivery.
+Analysis workflows may read source media, but file outputs must go to sidecar
+files, session scratch space, or the configured
+`davinci-resolve-mcp-analysis` project root. Resolve-target analysis should run
+visual analysis, transcription, metadata writeback, and Media Pool marker
+writeback by default unless the user opts out; those writes are Resolve project
+database changes, not source-media changes. Preserve the chain from camera
+original to final delivery.
 
 See `docs/guides/media-analysis-guide.md` for the full source-safe workflow.
 
+## Media Analysis Defaults Are Mandatory
+
+Do not translate source-safe into underpowered, read-only, no-writeback analysis.
+When the user asks to analyze Resolve media, run the requested analysis directly
+with visual analysis, transcription, persisted artifacts, metadata writeback, and
+Media Pool marker writeback enabled by default. Do not add
+`include_visuals=false`, `include_transcription=false`,
+`publish_metadata=false`, `timed_markers=no`, `session_only=true`, or
+`dry_run=true` unless the user explicitly asks for that opt-out, the target is a
+raw file path that cannot receive Resolve project writeback. Vision uses
+`host_chat_paths` by default — analyze actions return a deferred payload with
+absolute `frame_paths` and a JSON schema; the host chat must read those frames
+as local images, produce JSON per the schema, and call
+`media_analysis(action="commit_vision", params={clip_id, visual, vision_token})`
+to merge the result and trigger metadata + Media Pool clip-marker writeback.
+Not completing `commit_vision` leaves the analysis in
+`pending_host_vision_analysis` — that is a failure mode, not a success. Users
+must explicitly opt out with `include_visuals=false` for a technical-only run.
+
 ## Frame-Referenced Color Work
 
 Before applying a grade, look, shot match, LUT, CDL, DRX, or copied grade to an

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 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.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
+`vision.provider="host_chat_paths"` by default. The analyze response is a
+deferred payload with absolute `frame_paths`, a per-shot `shot_table`, and a
+JSON schema; the host chat reads each frame as a local image, produces JSON per
+the schema, and calls `media_analysis(action="commit_vision", params={clip_id,
+visual, vision_token})` to finalize. `commit_vision` merges the visual report,
+rebuilds Media Pool clip markers, publishes metadata to Resolve, and preserves
+human corrections via `corrections.json`. Skipping the commit leaves the run in
+`pending_host_vision_analysis` — surfaced explicitly rather than silently
+downgraded. The legacy `chat_context`/`mcp_sampling` providers still resolve to
+the same host-chat path.
+
+**Trust-by-default analysis defaults** — `analyze_media` defaults to
+`include_transcription=true`, `persist=true`, `publish_metadata=true`, and
+`timed_markers="ask"` so source-safe no longer means underpowered. Agents that
+need a technical-only or read-only run must explicitly pass
+`include_visuals=false`, `include_transcription=false`, `publish_metadata=false`,
+`timed_markers="no"`, `session_only=true`, or `dry_run=true`. The
+`analyze_media` prompt and SKILL.md spell out the anti-regression rule.
+
+**Control panel: Review surface (Phase B)** — The local browser control panel
+gains a Review tab backed by new endpoints: `/api/clips`, `/api/clips/<id>`,
+`/api/clips/<id>/shots`, `/api/clips/<id>/shots/<index>`,
+`/api/clips/<id>/frames/<n>`, `/api/clips/<id>/transcript`,
+`/api/clips/<id>/corrections`, `/api/clips/combined`, `/api/clips/export`,
+`/api/panel_state`, `/api/update/status`, `/api/update/apply`, and
+`/api/resolve/open_clip`. The UI ships a bin grid with thumbnails, a clip
+detail with shot strip, a shot detail with grouped V2 fields + frame grid,
+inline correction editors per subjective field, transcript correction +
+regeneration, an Open-in-Resolve bridge, and 2-second chat ↔ panel state
+polling.
+
+**Control panel MCP actions** — `resolve_control.open_control_panel`,
+`control_panel_status`, and `close_control_panel` manage the local panel
+subprocess via a pidfile. `save_state` / `restore_state` snapshot and restore
+Resolve playhead + selection state. `get_panel_state`, `set_panel_state`, and
+`session_start_context` share panel focus between chat and the UI through
+`panel_state.json`.
+
+**Correction tools** — New `media_analysis` actions for editing analysis
+without re-running it: `update_shot_field`, `update_clip_field`,
+`get_field_history`, `revert_field`, `list_corrections`. Writes land in
+`{clip_dir}/corrections.json` with append-only changelog + provenance
+(mirrors the V2 DB schema). `commit_vision` merges corrections on top of the
+fresh visual report so human edits survive re-analysis.
+
+**Media Pool item open-in-viewer** — `media_pool_item.open_in_viewer` selects
+a clip on the Media page and loads it into the source viewer, optionally
+setting mark in/out and bringing Resolve to the foreground via OS-level
+window activation. Useful for chat → Resolve hand-off.
+
+**Source-trust prompt grading** — `source_trust` parameter
+(`auto`/`filename`/`low`/`medium`/`high`) on analyze actions tunes the vision
+prompt to hedge identity/intent/value for archival or thin-evidence clips.
+
+**Analysis memory layer** — New `src/utils/analysis_memory.py` introduces
+per-project memory + heartbeat + bin summary + soul scaffolding under the
+analysis root. `regenerate_bin_summary_from_manifest` aggregates per-clip
+fields (primary use, select potential, style, energy arc, top tags/locations)
+into a bin briefing. Auto-initialized on analyze.
+
+**Control-panel polish** — Diagnostics + Overview restyled with a status-pill
+design system, navbar dropdowns fixed so top-level buttons no longer navigate
+on their own, Preferences consolidated (Dashboard Convenience + Storage pages
+removed), summary-style enum renamed to `full`/`concise`/`creative`/
+`technical` with backwards compat, navbar version badge + update modal,
+source-trust dropdown wired through.
+
+**Server-side bug fixes** — `commit_vision` auto-publish now reflects per-row
+status correctly (no silent-lie pending), compact analyze responses by default
+(`verbose: true` for the full manifest), `resolve_output_root` skips slug
+append when the configured base already terminates in the slug, frame sampler
+reserves per-shot budget so shot starts aren't starved by flash candidates,
+and machine markers are no longer written to Resolve (V2 architecture).
+
+**Path hardening for GUI launches** — `media_analysis` now augments `PATH`
+with the standard tool dirs (`/opt/homebrew/bin`, `/usr/local/bin`, etc.) so
+ffprobe/ffmpeg resolve even when the MCP server is launched by a GUI app
+(Claude.app, Dock/Spotlight) that inherits launchd's bare PATH.
+
+**Documentation** — `AGENTS.md` adds the "Media Analysis Defaults Are
+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.
+
+**Validation**: static import checks, API parity audit, focused
+media-analysis + marker/range/v232/v233 unit tests, npm CLI smoke,
+`npm pack --dry-run`, and `git diff --check` all passed. No source media was
+modified. Resolve scripting behavior is additive (new actions; existing
+actions unchanged); live Resolve validation covered the control-panel +
+open_in_viewer + commit_vision auto-publish + corrections-merge paths during
+the V2 push sessions logged in MEMORY.md.
+
 ## What's New in v2.23.1
 
 **Control panel navigation fixes** — The local browser control panel now keeps

package/README.md

@@ -1,6 +1,7 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.23.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.24.1-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)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
@@ -10,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
@@ -73,7 +78,7 @@ The compound server is recommended unless you specifically need the granular one
 |------|-----------------------------------|
 | App and project control | Launch/reconnect, page switching, project CRUD, project folders, databases, cloud project wrappers, settings, presets, archives |
 | Media pool and ingest | Safe import, image sequences, multicam prep timelines, bin organization, metadata normalization, metadata field inventory, marks, annotations, relink/proxy/full-resolution guards |
-| Media analysis | Source-safe file/clip/bin/project analysis, 2-pop/slate-clap sync-event detection, confirmed Resolve metadata publishing, session-only defaults, existing-report reuse, chat-context visual analysis by default in `analyze_media` with opt-out, optional transcription |
+| Media analysis | Source-safe file/clip/bin/project analysis, 2-pop/slate-clap sync-event detection, default Resolve metadata and Media Pool marker writeback, persisted analysis artifacts, existing-report reuse, host_chat_paths visual analysis (finalized per clip with `commit_vision`, works with any vision-capable MCP client) with opt-out, transcription with opt-out |
 | Timeline editing and conform | Track/item probing, title text key scans/writes, copy/move/duplicate helpers, range operations, gaps/overlaps, source ranges, checked interchange exports/imports |
 | Review annotations | Timeline/item/clip markers, custom data, flags, clip color, copy/move/sync cleanup, review reports, marker thumbnail review |
 | Color and grading | Node graph probing, CDL validation, grade copy, DRX/LUT helpers, versions, Gallery stills, color groups |
@@ -103,7 +108,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 For method-by-method status, see [API Coverage and Test Results](docs/reference/api-coverage.md). For current workflow support, see [Kernel Action Coverage](docs/kernels/README.md).
 
-`analyze_media` uses in-chat visual analysis by default when the MCP client supports sampling/image messages. Pass `include_visuals=false` for technical-only or privacy-sensitive runs. If in-chat vision is unavailable, analysis continues with local technical/motion evidence and reports the skipped visual layer. `media_analysis.publish_clip_metadata` can publish confirmed analysis summaries, comments, keywords, people, and high-confidence slate fields back to Resolve clip metadata while preserving existing human-entered fields by default.
+`analyze_media` executes directly by default, persists inspectable reports/artifacts under the analysis root, requests host-chat visual analysis via the `host_chat_paths` protocol (analyze returns absolute frame paths + a JSON schema; the host chat reads each frame as an image and calls `media_analysis(action="commit_vision", ...)` to finalize), runs transcription through the configured local backend, and writes analysis summaries plus source-time Media Pool clip markers back to the Resolve project. Pass `include_visuals=false`, `include_transcription=false`, `publish_metadata=false`, `timed_markers=no`, or `dry_run=true` only when you want to opt out of those default behaviors. Skipping `commit_vision` leaves the run in `pending_host_vision_analysis` — surfaced as a failure mode, not silently downgraded.
 
 ## Documentation
 
@@ -113,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

@@ -108,11 +108,28 @@ tool accepts an `action` string and an optional `params` object.
 
 The compound server also registers MCP prompts. Use `davinci_resolve_workflow`
 as the compact operating brief, and use `analyze_media` as a slash-command style
-entry point for read-only project, selected-clip, bin, or file analysis. The
-Analyze Media prompt defaults to chat-context visual analysis when the MCP
-client supports sampling/image messages, while allowing `include_visuals=false`
-for technical-only or privacy-sensitive runs. It also encodes session-only
-defaults, optional transcription, and finished-video editorial guardrails.
+entry point for source-safe project, selected-clip, bin, file, or sequence
+analysis. The Analyze Media prompt executes directly by default, persists
+inspectable reports/artifacts under the project analysis root, requests
+`host_chat_paths` visual analysis (frames are extracted to disk and the host
+chat finalizes each clip via `media_analysis(action="commit_vision", ...)`),
+runs local transcription through the configured backend, and writes metadata
+plus source-time Media Pool markers back to the Resolve project unless the
+user opts out.
+
+Anti-regression rule: do not silently downgrade media analysis. Source-safe
+means source media stays untouched; it does not mean no visuals, no transcript,
+no persisted report, no metadata writeback, or no Media Pool markers. Do not
+add `include_visuals=false`, `include_transcription=false`,
+`publish_metadata=false`, `timed_markers=no`, `session_only=true`, or
+`dry_run=true` unless the user explicitly asks for that opt-out, the target is a
+raw file path that cannot receive Resolve project writeback. The host_chat_paths
+vision protocol is: `analyze_*` returns a deferred payload with absolute
+`frame_paths` and a JSON schema; you must read those frames as images (Claude
+Code's Read tool handles JPG/PNG natively), produce the JSON, and call
+`commit_vision` for each clip. Skipping `commit_vision` leaves the run in
+`pending_host_vision_analysis` — surface that explicitly; do not call the
+analysis complete.
 
 ## Local Control Panel
 
@@ -154,9 +171,9 @@ contains useful evidence:
 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, chat-context 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
+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.
 
@@ -393,26 +410,28 @@ Key actions: `add(frame, color, name, note, duration)`, `get_all`, `delete_by_co
 **`media_analysis`** — Project-scoped media intelligence and guarded metadata publishing.
 
 Media Analysis and editorial-assist actions (v2.17.0+) add source-safe planning,
-report reuse, session-only execution, chat-context visual review, and
-timeline-level editorial helpers.
+report reuse, persisted analysis execution, host_chat_paths visual review
+(finalized per clip via `commit_vision`), transcription, default Resolve
+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`,
-`summarize`, `get_report`, `build_index`, `index_status`, `query_index`,
-`start_batch_job`, `run_batch_job_slice`, `batch_job_status`,
+`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.
-Executed file/clip analysis defaults to session-only: scratch artifacts are
-removed after structured reports are returned to the MCP response. `persist=true`
-keeps reports under the project analysis root, and `keep_artifacts=true`
-preserves a session scratch run for inspection. Persisted analysis refreshes the
-local SQLite search index automatically unless `auto_build_index=false` is set;
-`build_index` remains the manual rebuild action for existing reports. `quick`
-uses ffprobe metadata; `standard` adds ffmpeg read-through checks,
+Executed Resolve-target analysis defaults to running, persisting inspectable
+artifacts, and publishing metadata plus Media Pool clip markers. Use
+`dry_run=true`, `publish_metadata=false`, `timed_markers=no`, or
+`session_only=true` with `keep_artifacts=false` to disable those defaults for a
+run. Persisted analysis refreshes the local SQLite search index automatically unless
+`auto_build_index=false` is set; `build_index` remains the manual rebuild action
+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
@@ -423,31 +442,47 @@ 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.
-Transcription requires explicit opt-in. The `analyze_media` prompt opts into
-visual analysis by default and uses `vision.provider="chat_context"` when the
-MCP client supports sampling; pass `include_visuals=false` to opt out. For
-direct `media_analysis` tool calls, set `vision.enabled=true` explicitly when
-visual interpretation is needed. Standard/deep runs prioritize first/last usable
-frames plus before/after cut-boundary frames; those sampled frames are sent to
-the current chat/sampling model and the response is stored in the default
-structured JSON shape. If chat-context vision is unavailable, continue with
-technical/motion analysis and ask whether the user wants setup steps or a
-no-visual run. The local mock providers are for tests and do not send frames
-off-machine.
+Transcription, visual analysis, metadata writeback, and Media Pool marker
+writeback are default-on. Vision uses
+`vision.provider="host_chat_paths"`: analyze actions extract representative
+frames to disk under the project analysis root and return a deferred payload
+containing absolute `frame_paths`, a `shot_table` mapping each detected shot
+range to its in-shot `frame_indices`, the JSON schema, and a `commit_action`.
+The host chat must read those frames as local images, produce JSON per the
+schema (including one `shot_descriptions` entry per `shot_index` in the
+`shot_table`, grounded only in the frames listed for that shot), and call
+`media_analysis(action="commit_vision", params={clip_id, visual,
+vision_token})` per clip to merge the visual report, rebuild Media Pool clip
+markers, and publish vision-dependent metadata to Resolve. Each Resolve shot
+marker inherits its description from `shot_descriptions[shot_index]`; missing
+entries fall back to an in-range `analysis_keyframe` and finally to a
+clip-summary-tagged fallback — never to a neighbour shot's description. The manifest exposes
+`vision_pending=True` and `pending_action` so callers know what is incomplete.
+Pass `include_visuals=false`, `include_transcription=false`,
+`publish_metadata=false`, or `timed_markers=no` to opt out. Agents must not add
+those opt-out flags preemptively; use them only when requested or when a target
+boundary requires it. Standard/deep runs prioritize first/last usable frames
+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.
 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
 per-file `record_offset` suggestions, and never installs FFmpeg automatically.
-It also returns marker suggestions; only call `add_sync_event_markers` after the
-user explicitly approves marker writes, and pass `confirm=true`.
+It also returns marker suggestions; `add_sync_event_markers` remains an explicit
+marker-write action for standalone sync detections.
 Use `publish_clip_metadata` when the user wants analysis to become searchable
 inside Resolve. It analyzes or reuses reports, proposes field-specific merges
 for `Description`, `Comments`, `Keywords`, `People`, and optional slate-derived
-fields, stores provenance in third-party metadata, defaults to `dry_run=true`,
-and writes Resolve metadata only when called with `confirm=true`.
+fields, stores provenance in third-party metadata, and writes metadata plus
+source-time markers by default for executed Resolve-target analysis. Disable a
+write run with `dry_run=true`, `publish_metadata=false`, or `timed_markers=no`.
 `review_timeline_markers` creates a labeled
-Resolve-rendered marker contact sheet plus JSON sidecar, and can request
-chat-context vision for marker/frame mismatch review.
+Resolve-rendered marker contact sheet plus JSON sidecar; with
+`vision.enabled=true` it returns a host_chat_paths review payload (image_path +
+prompt) so the host chat can read the sheet and answer inline — no commit step
+required for marker review.
 
 Before calling `analyze_*`, prefer `summarize` and `get_report` to discover
 existing reports for the active project. If reports exist, use them as the

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).

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

@@ -97,10 +97,10 @@ verify it against a Resolve-rendered frame:
 - Keep marker notes concrete enough that another editor can act on them.
 
 Use contact sheets for orientation and review. `analyze_media` defaults to
-chat-context vision for visual/editorial analysis when the MCP client supports
-sampling; pass `include_visuals=false` for a no-visual run. Use direct assistant
-inspection when the user provides or requests specific still/contact-sheet
-review.
+host_chat_paths vision: analyze actions return frame_paths and a schema, and the
+host chat finalizes per-clip visual analysis via `commit_vision`. Pass
+`include_visuals=false` for a no-visual run. Use direct assistant inspection
+when the user provides or requests specific still/contact-sheet review.
 
 ## Edit Variant Safety