davinci-resolve-mcp 2.23.0 → 2.24.0

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,123 @@
 
 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.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. 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`.
+
+**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
+top-level dropdown buttons from navigating by themselves. Analysis,
+Diagnostics, Docs, and Preferences open their menus first; selecting a menu item
+is what changes the active view.
+
+**Project dropdown cleanup** — The project context dropdown is back to showing
+only the open/current project context plus a bottom `View All Projects` option.
+The full database browser stays in the Projects view, and the standalone
+Projects navbar button has been removed.
+
+**Validation**: static import checks, API parity audit, focused dashboard unit
+tests, npm CLI smoke tests, package dry-run, and `git diff --check` passed. A
+local dashboard smoke check verified the served HTML on `127.0.0.1:8765`.
+No Resolve scripting behavior changed; live Resolve mutation validation was not
+required.
+
 ## What's New in v2.23.0
 
 **npm installer** — `npx davinci-resolve-mcp setup` is now the primary quick

package/README.md

@@ -1,6 +1,7 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.23.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.24.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)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
@@ -73,7 +74,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 +104,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
 

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

@@ -0,0 +1,238 @@
+# Control Panel Polish — Gameplan
+
+Tracks the round of UI/UX work that started 2026-05-19 after removing Batch
+Jobs / Job Detail from the Analysis menu. The work is sequenced so that the
+visual-design system from Phase 1 gets reused by every later phase, and so that
+schema/server changes land before the UI that consumes them.
+
+Source-of-truth: the user. This doc is a living checklist — strike items as
+they ship, append new ones surfaced during execution.
+
+---
+
+## Findings worth knowing before we start
+
+- **`analysis_summary_style` and `report_format` are dead code today.** Both
+  prefs are validated and threaded through the request envelope
+  (`src/server.py:5695,5696,7364-7369,8709-8710`), but nothing in
+  `src/utils/media_analysis.py` or anywhere downstream branches on them. We can
+  rename the enum values without breaking behavior because there is no behavior
+  to break. The cost: renaming alone won't make summaries *act* different;
+  that's follow-up work.
+
+- **Two transcription settings exist and they don't sync.**
+  `Preferences › Analysis › Transcription default` (`prefTranscriptionDefault`,
+  server-wide, default `"yes"` at `src/server.py:5676`) is the real default.
+  `Preferences › Dashboard Convenience › Transcription` (`prefTranscription`,
+  browser-local checkbox, default off) was the per-run override for the
+  now-deleted batch composer. The browser-local one no longer has a UI
+  consumer; it only feeds the generated MCP prompt in `promptPayload()`
+  (`src/analysis_dashboard.py`).
+
+- **`timed_markers_default` defaults to `"yes"`** (`src/server.py:5673`). The
+  dropdown showing "yes" is not a UI bug — it reflects the actual server
+  default. The user has asked to flip this to `"ask"`.
+
+- **Resolve product/version are not in the boot payload.** `/api/boot` returns
+  capabilities, project info, output roots, but does not call
+  `GetProductName() / GetVersionString() / GetCurrentPage()` on the Resolve
+  handle. `_connect_resolve_read_only()` already returns the handle — easy to
+  extend.
+
+- **Package version source** is `package.json:3` (`"2.23.1"`).
+  `src/utils/update_check.py` already has `check_for_updates()` and writes to
+  `update_state.json`. The plumbing exists; the dashboard just doesn't surface
+  it yet.
+
+- **Browser file-system picker reality check.** `showDirectoryPicker()` exists
+  but is Chromium-only and requires HTTPS or `localhost`. The dashboard runs on
+  `localhost` so it's usable, but we need a graceful fallback for
+  Firefox/Safari users — keep the text input as source of truth.
+
+---
+
+## Phases
+
+### Phase 0 — Server-side flips (small, foundational)
+
+These are tiny but they unblock Phase 1's data and Phase 3's correctness.
+
+- [ ] **Flip `timed_markers_default` to `"ask"`** in
+      `_MEDIA_ANALYSIS_DEFAULT_PREFS` (`src/server.py:5673`). Existing
+      user-saved prefs are untouched; this only affects fresh installs and
+      `Reset Defaults`. Validate by running the dashboard, hitting Reset, and
+      confirming the dropdown lands on "ask".
+- [ ] **Add Resolve identity to `/api/boot`.** Extend the boot route in
+      `src/analysis_dashboard.py` to call `GetProductName()`,
+      `GetVersionString()`, `GetCurrentPage()` against the read-only Resolve
+      handle (use `_connect_resolve_read_only`). Add a `resolve` block to the
+      response. Null-tolerant when Resolve is offline.
+- [ ] **Add `/api/update/status` route.** Wraps
+      `src/utils/update_check.py:check_for_updates` and exposes
+      `{ current, latest, update_available, last_checked, snoozed_until }`.
+      Cache result for at least 5 minutes; never block the dashboard on
+      network.
+
+**Exit criteria:** Boot payload includes `resolve.product`,
+`resolve.version_string`, `resolve.page`. `/api/update/status` returns a
+sensible payload offline (no exceptions). Fresh server prefs file shows
+`timed_markers_default: ask`.
+
+---
+
+### Phase 1 — Status-pill design system + Diagnostics restyle
+
+This is the foundation for every later visual change. We build the components
+once on Diagnostics, then reuse them in Overview rows and (later) the Analyze
+header.
+
+- [ ] **Define status-pill primitives.** Three classes:
+      `pill-ok` (green, var(--accent-success)), `pill-warn` (amber,
+      var(--accent-warning)), `pill-err` (red, var(--accent-error)). A
+      `pill-icon` slot for an inline 12px SVG.
+- [ ] **Define `diagnostic-card`.** Compact card with: header (icon + title
+      + status pill), 2–4 KV rows beneath, optional bottom action row. Reuses
+      the existing `--lab-panel-bg` / `--lab-panel-elevated` tokens.
+- [ ] **Restyle Resolve diagnostics.** Replace the single `info-list` with a
+      grid of cards:
+      - **Connection** card: status pill + product name + version + page
+      - **Project** card: name + clip counts + warnings
+      - **Inventory** card: total / source / hidden / sequences
+- [ ] **Restyle Storage diagnostics** as cards (Analysis root / Index DB /
+      Jobs DB) with pills for "indexed / stale / missing".
+- [ ] **Restyle Tools diagnostics** so each detected tool is a chip with a
+      version line and a status pill — denser than today's `tool-row` layout.
+
+**Exit criteria:** Diagnostics page scans at a glance. Color encodes
+correctness; the eye can find a problem without reading every label.
+
+---
+
+### Phase 2 — Overview rows visual upgrade
+
+Reuses Phase 1 primitives. No new components needed.
+
+- [ ] Convert the four overview metric cards to use the diagnostic-card
+      shell (consistent visual language).
+- [ ] Replace the flat `info-list` below the cards with a status-pill
+      grid: every row gets a leading icon and a pill that reflects health
+      (e.g. *Search index: indexed* in green, *Clip media status: 3 missing*
+      in amber).
+- [ ] Add a tiny meter for "X analyzed of Y source clips" so progress is
+      visible without math.
+
+**Exit criteria:** Overview communicates state without requiring the user to
+read every word. Green/amber/red dominates the scan path.
+
+---
+
+### Phase 3 — Untangle Preferences (the big consolidation)
+
+Touches Analysis, Dashboard Convenience, Storage, and Paths & Workflow.
+
+- [ ] **Delete `Preferences › Dashboard Convenience` as a separate page.**
+      Keep only the fields that still feed live UI:
+      - `prefPollInterval` and `prefAutoPoll` → move to the Analyze page
+        header as inline controls.
+      - `prefDepth`, `prefFrames` → optional; consider moving to Analysis prefs
+        as "Default depth" / "Default sample frames" since they feed the
+        prompt and arguably *are* analysis defaults.
+      - `prefJobName`, `prefRecursive`, `prefTranscription` → delete. Job
+        name can default to "Editorial analysis pass" without a pref.
+        Recursive is no longer surfaced. Transcription is owned by
+        Preferences › Analysis.
+- [ ] **Merge `Preferences › Storage` into `Preferences › Paths & Workflow`.**
+      The Storage page becomes a "Where files live" section at the bottom of
+      Paths & Workflow, rendered as diagnostic cards (reuses Phase 1).
+- [ ] **Add a "Browse..." button** next to `prefPreferredAnalysisRoot` and
+      `prefPreferredGeneratedMediaFolder`. Uses `showDirectoryPicker()` when
+      available; falls back to plain text input. Show a dropdown of recently
+      used project roots sourced from `state.projects.related_project_roots`.
+- [ ] **Rename summary-style enum**: `concise / assistant_editor / qc /
+      producer / full` → `full / concise / creative / technical`. Update:
+      - `_MEDIA_ANALYSIS_DEFAULT_PREFS` (`src/server.py:5695`)
+      - normalizer at `src/server.py:5923`
+      - schema enum at `src/server.py:8709`
+      - error message at `src/server.py:8917`
+      - dashboard `<select>` options (`src/analysis_dashboard.py:2408`)
+      - dashboard help text (`src/analysis_dashboard.py:2788`)
+      - default value: `"concise"` is fine to keep.
+- [ ] **Discuss/add new Analysis prefs.** Open questions for the user:
+      - Default source-trust mode (the conservative-descriptions feature
+        flagged in `feedback_conservative_descriptions.md`). Worth a UI
+        toggle?
+      - Default analysis depth (would replace the Dashboard-Convenience
+        depth).
+      - Default sample frame budget (same).
+
+**Exit criteria:** One Transcription setting, in one place. Paths & Workflow
+shows where files live. Storage page is gone from the menu. Dashboard
+Convenience is gone from the menu. Summary-style dropdown reads
+`full / concise / creative / technical`.
+
+**Follow-up (not blocking this phase):** wire the renamed summary styles into
+actual prompt construction so they produce distinguishable output. Today they
+are stored and forgotten; renaming alone changes nothing downstream.
+
+---
+
+### Phase 4 — Navbar version badge + update flow
+
+- [ ] **Read `package.json` at server start**, expose `version` on the
+      `/api/boot` payload.
+- [ ] **Render version as a navbar badge** next to the wordmark. Style: pill
+      with `--accent-brand-muted` background; chevron when an update is
+      available.
+- [ ] **Poll `/api/update/status` on dashboard boot** and at most once per
+      hour after that. Render a small "Update available → 2.24.0" decoration
+      on the badge when applicable.
+- [ ] **Click on the badge opens a brand-styled modal** (clone of
+      `projectSwitchModal` at `src/analysis_dashboard.py:2556`). Modal shows
+      current → next version, release notes link (if available), and
+      Cancel / Update buttons. **Defer** the actual `pip install -U` /
+      `npm install -g` kickoff — for v1, the modal can offer a "Copy update
+      command" button. Self-updating a running server is a footgun; we'll
+      design that separately.
+
+**Exit criteria:** Users see the current version at all times, get a clear
+indicator when a release is available, and have a one-click path to learn
+how to update.
+
+---
+
+### Phase 5 — Polish pass
+
+Stuff we'll likely find as we work through the above.
+
+- [ ] Audit `setText('promptSourceSummary'/'promptSelectedSummary'/...)` no-op
+      calls left over from the Batch Jobs removal. Either re-attach them to a
+      surface on the Analyze page or delete them.
+- [ ] Verify the post-Batch-Jobs `promptPayload()` still works end-to-end
+      after Dashboard Convenience moves. Run the Analyze page's
+      "Copy Prompt" / "Analyze in Codex" once and confirm the generated
+      prompt is well-formed.
+- [ ] Add a small status-pill legend somewhere on Diagnostics so the
+      green/amber/red language is discoverable.
+
+---
+
+## Out of scope (intentionally)
+
+- Wiring the renamed summary styles into actual prompt construction
+  (separate engineering task — needs prompt-engineering work, not UI work).
+- Self-updating the running MCP server from the dashboard
+  (separate safety design).
+- Touching the V2 Review surface — already shipped in the fourth push.
+- Any change to the Analyze page's clip table — out of scope for this round.
+
+## Open questions
+
+1. **Source-trust default as a pref?** You flagged conservative descriptions
+   in `feedback_conservative_descriptions.md` and it's now a `source_trust`
+   param. Should this surface as a UI default in Preferences › Analysis?
+2. **Depth and Sample Frames — move them or delete them?** They feed the
+   generated MCP prompt but the user can also pass them per-call in chat.
+   Are these worth keeping as UI prefs?
+3. **Brand styling for the update modal.** We have one modal pattern
+   (`projectSwitchModal`). Do you want a distinct visual treatment for
+   update prompts, or keep them visually consistent with project switching?