davinci-resolve-mcp 2.57.4 → 2.58.0

package/AGENTS.md

@@ -112,3 +112,23 @@ for Resolve scripting; 3.13/3.14 are accepted and verified on Resolve Studio
   live-validation guidance in `docs/process/release-process.md`.
 - For docs changes, keep the README concise and move durable detail into
   dedicated files under `docs/`.
+
+<!-- BEGIN GENERATED: domain-routing -->
+<!-- GENERATED by scripts/agent-rules/generate.mjs — edit that, not this file. -->
+## Domain Routing
+
+Per-domain routers pair the live tools with their offline (advanced-server)
+counterparts. Every domain is available on demand in ANY MCP client as a slash
+prompt (`/color_grade_workflow`, `/timeline_edit_workflow`, `/conform_workflow`,
+`/delivery_workflow`, `/analyze_media`) and, in Claude Code, as a `.claude/skills/`
+skill. Full per-action depth lives in `docs/kernels/`.
+
+- **Color / Grade** (`/color_grade_workflow`, skill `resolve-color`) — grading, correcting, shot matching, developing looks, or applying/modifying LUTs, CDLs, DRX grades, or copied grades. Live: timeline_item_color. Offline: drx. Depth: docs/kernels/color-grade-kernel.md + docs/guides/color-decision-guide.md.
+- **Timeline Edit** (`/timeline_edit_workflow`, skill `resolve-edit`) — cutting, trimming, pacing, duplicating/moving clips, copying ranges, building variants, tightening a cut, or generating an editorial changelist. Live: timeline. Offline: editorial. Depth: docs/kernels/timeline-edit-kernel.md + docs/guides/editorial-decision-guide.md.
+- **Conform / Interchange** (`/conform_workflow`, skill `resolve-conform`) — importing/relinking editorial, checking a conform against a reference, repairing reversed/retimed subclips, tracing grades across a re-conform, or QCing a conformed timeline. Live: timeline. Offline: conform. Depth: docs/kernels/timeline-conform-interchange-kernel.md.
+- **Delivery / Deliverable QC** (`/delivery_workflow`, skill `resolve-delivery`) — preparing render jobs, validating render settings, QCing a finished render vs spec, building render manifests, expanding texted/textless/stems deliverables, verifying media ingest, or producing a provenance/episode report. Live: render. Offline: deliverable. Depth: docs/kernels/render-deliver-kernel.md.
+- **Fusion Composition** (`/fusion_workflow`, skill `resolve-fusion`) — building or editing Fusion comps — titles, motion graphics, VFX, merges, masks, trackers. Live: fusion_comp. Offline: fusion. Depth: docs/kernels/fusion-composition-kernel.md.
+- **Audio / Fairlight** (`/audio_workflow`, skill `resolve-audio`) — setting audio properties, syncing audio, isolating voice, generating subtitles, planning Fairlight tracks/buses, checking loudness, routing buses, or splitting/trimming/converting audio. Live: timeline. Offline: audio_plan. Depth: docs/kernels/audio-fairlight-kernel.md.
+- **Media Pool / Ingest** (`/media_pool_workflow`, skill `resolve-media-pool`) — importing media, building multicam timelines, organizing/relinking clips, normalizing metadata, or verifying/inventorying a card before ingest. Live: media_pool. Offline: media. Depth: docs/kernels/media-pool-ingest-kernel.md + docs/guides/multicam-setup-guide.md.
+- **Media Analysis** (`/analyze_media`, skill `resolve-media-analysis`) — reading or analyzing source media (technical, visual, or transcription) to inform Resolve actions. Live: media_analysis. Offline: media. Depth: docs/kernels/README.md + docs/guides/media-analysis-guide.md.
+<!-- END GENERATED: domain-routing -->

package/CHANGELOG.md

@@ -2,6 +2,201 @@
 
 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.58.0
+
+Major expansion of the optional **advanced** Node server (`davinci-resolve-advanced-mcp`,
+bundled in the same package) — the beyond-the-API sibling that edits Resolve files
+(`.drp`/`.drt`/`.drx`) offline. It grows from 14 to **18 tools** and adds a deterministic,
+offline grading/QC/finishing catalog. All new capability is offline, deterministic, and
+carries silent-lie guards (it refuses to fabricate a result). None of it touches the live
+Python server or its tool counts.
+
+### Added
+
+- **Grading catalog** (`drx` actions): `scope_read` (frame readouts — RGB parade, vectorscope
+  skin-line, black-balance, %clip/%crush + shot-intent signals), `intent_tags`, `verify_grade`
+  (intended vs applied → landed/drifted/missing/unverifiable), `extract_frames` (display-referred,
+  hard log-refuse), `match_to_reference`, `saturation_match`, `black_balance`, `tone_curve_transfer`
+  (luma CDF matching), `skin_match` v2 (luma-preserving skin-line metric), `author_look` / `carry_look`
+  (season-look authoring), and `lut_apply` — a reverse-engineered Body-LUT write path that attaches a
+  named `.cube` to a grade node with a round-trip assert.
+- **`deliverable` tool** — deliverable QC/compliance: `deliverable_qc` (ffprobe vs spec, pass/fail per
+  field), `loudness_qc` (EBU R128), `reframe_blanking_check`, `render_manifest` (checksum/reconcile),
+  `conform_completeness`, `re_delivery_diff`, `expand_deliverable` (texted/textless/stems entities).
+- **`media` tool** — media front-end / AE: `ingest_verify` (hash seal/verify/dupes), `media_inventory`,
+  `sync` (TC), `relink_manifest`, `rename_plan` / `reel_normalize` (refuses camera originals),
+  `turnover_package`, `project_hygiene`.
+- **`editorial` tool** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML), `turnover_changelist`
+  with timing silent-lie guards, `conform_manifest`, `marker_roundtrip`.
+- **`provenance` tool** — provenance/audit: `gallery_lineage`, `grade_provenance`, `cdl_export` (+diff),
+  `revision_tracking`, `episode_report`.
+- **Node-labeling / provenance** on every auto-emitted grade node (`AUTO:<tool> v<n> → <source>`),
+  a **runner→apply contract** (stage → live-server action mapping), and runner **stage-resume**.
+  The pipeline records per-episode decoded facts, drift, and provenance (`readback`) — the
+  substrate the maintainers' managed application mines for cross-episode insights (see the
+  README's Bradford Post Assistant note).
+- **DRX value-space calibration (Phase 1)** — one unified `space: 'ui' | 'drx'` flag on `drx`
+  `generate`/`merge`: `'ui'` (the default) takes Resolve panel numbers for every primary
+  (lift ×2, gamma ×4, gain 1:1, offset panel-delta ÷25, saturation 0–100 ÷50 — factors
+  calibrated by live panel readback against Resolve 19 Studio); `'drx'` takes raw internal
+  floats losslessly. 28 scalar/wheel/affine controls confirmed aligned. Factor reference in
+  `resolve-advanced/vendor/drx-parameters/DRX-VALUE-SCALING.md`; coverage ledger in
+  `CALIBRATION-STATUS.md` alongside it.
+- **DRX structural write fidelity (Phase 2)** — the structural write paths (windows,
+  qualifiers, HDR zones, HSL curves, ColorSlice, Color Warper) were audited against live
+  Resolve and rebuilt where broken; items marked live-verified below were confirmed by
+  applying a generated `.drx` and reading the Resolve panel:
+  - **Power windows** — true live-calibrated transform scales (rotate −UI°/180, size
+    1+(UI−50)×0.08, aspect (50−UI)/50, pan/tilt ×4096, softness ×16) replace placeholder
+    conventions the registry's old ranges clamped to garbage; linear softness masks and
+    gradient params now route to their real corrector blocks. Live-verified exact.
+  - **HDR zones** — multi-zone grades now write every zone into the single
+    `ZONE_ADJUSTMENTS` param (previously only the last zone survived the encode).
+    Live-verified with two zones exact.
+  - **Qualifiers** — HSL ranges live-verified exact; RGB and luma modes newly reachable via
+    `rgbQualifier` / `lumaQualifier` (mode flags corrected to their real varint wire form;
+    the Qualifier palette switches modes correctly). RGB live-verified exact.
+  - **ColorSlice** — new write path for the six global controls (identity scale, Hue stored
+    negated). Live-verified exact.
+  - **HSL curves** — sat/lum-axis curves write correctly with per-curve meta
+    (`hslCurveMeta`); hue-axis curves are a strict bezier control cage, and a canonical
+    emitter (`canonicalizeHueAxisPoints`) reproduces Resolve's own serialization —
+    live-verified single- AND multi-band at multiple positions and values. Known-bad
+    geometry (a bump edge landing exactly on a band slot) passes through raw instead
+    and now surfaces a `warnings` array on the `generate`/`merge` result ("renders
+    FLAT"). Because a malformed wrapped cage can crash Resolve 19 outright, caller-built
+    pre-wrapped point lists (x outside [0,1]) are **refused** unless
+    `allowWrappedHueCage:true` (the verbatim re-encode escape hatch). `generate` and
+    `merge` share the same `space:'ui'` default, and every bundled matcher emitter pins
+    `space` explicitly.
+  - **Polygon/curve window shapes** — new ct6 vertex-ring write path; geometry renders and
+    masks exactly as one window row.
+  - **Color Warper** — new pin-list write path matching the Resolve 21 wire format;
+    round-trips exactly but Resolve 19 ignores it (version-gated — pending an R21 verify).
+
+### Fixed
+
+- `drx` `parse` now reads back custom curves / HSL curves / qualifiers / power windows through the tool
+  (the augmentation passed the node params object instead of the flat corrector parameters).
+- **Two long-standing DRX "known bugs" resolved as not encoder bugs** (live panel readback):
+  `hueRotate` stores `(UI−50)/50` (input 60 → panel Hue 60.00), and `contrastHighRange` is
+  stored `1−UI` **by Resolve itself** (input 0.70 → panel ↑Rng 0.700; low range is 1:1).
+  Both now round-trip in `space:'drx'` via normalizer compensation; the old bug-locking test
+  was replaced with correct assertions.
+- Vestigial `satVsSat` registry ranges removed — they silently clamped real gradient-window
+  writes (the 0x08F000xx ids belong to the gradient window; the real Sat-vs-Sat curve is an
+  HSL spline).
+- **Blur / Key / Motion Effects palettes decoded AND writable** (the last unswept native
+  palettes): the registry's legacy "Curves corrector (Type 18)" grouping was measured
+  wrong — those ids are the Key palette (ct9, identity scales) and the Motion Effects
+  palette (a newly identified corrector type 15). Blur-palette radius/H-V ratio store as
+  (UI−0.5)×2 (two-point fit). New `gradeParams.blur` / `key` / `motionEffects` write
+  paths, panel-readback-verified (Frames varint = frames×2 confirmed); all named in the
+  registry and locked by a new fixture + calibration/write tests; the sweep grade decodes
+  with zero unknown_ params.
+- **3D-qualifier selection volume blob decoded** (the last offline-reachable opaque blob):
+  a packed header + float32 sample point cloud — the keyer's chroma-plane stroke path,
+  now lifted as `qualifier3d` with a per-sample decode locked by test.
+- **Programmatic "Cleanup Node Graph"** — Resolve's node-layout tidy is UI-only (no
+  scripting API); a before/after Project.db diff proved it rewrites only the per-node
+  x/y position varints in the graded version Body, and direct injection of rewritten
+  positions was live-verified to render with the grade intact. Two productized paths:
+  - `drx` `relayout` — rewrites node positions in a `.drx` to Resolve's own clean-row
+    layout (or explicit `positions`), byte-preserving everything else (labels, keyframes,
+    OFX). Live single-clip recipe (verified on a production clip): grab still → `relayout`
+    → `reset_all_grades` → `ApplyGradeFromDRX`. The reset is required — a same-structure
+    apply silently keeps the existing node layout (new `api_truth` entry).
+  - `project_db` `relayout_node_graphs` — whole-project sweep over every graded version
+    row (closed project, dry-run, auto-backup, per-row read-back verify, undecodable rows
+    skipped and reported, already-clean rows left untouched). Resolve caches open projects
+    in memory, so the patch is only visible after a full quit + relaunch — the result
+    says so explicitly.
+
+### Documentation
+
+- Advanced-server section + tool table updated to 18 tools; `resolve-advanced/README.md` catalog expanded.
+- **Control panel learns about the advanced server** (read-only): Setup → **Advanced**
+  (live capability card — pure-JS core + ffmpeg/sharp/better-sqlite3 status with install
+  hints), Setup → **Conform QC** (lineage-sidecar browser: snapshots, diff-vs-previous,
+  per-cut frame-QC verdicts with tallies), and Docs → **Advanced Server** (the full
+  18-tool catalog rendered in-panel). Backed by a deliberate read-only Node bridge
+  (`resolve-advanced/scripts/panel-bridge.mjs` — capabilities + lineage
+  list/show/diff/verdicts only; ingest/QC/patches stay with the MCP tools) and two new
+  panel endpoints (`/api/advanced/capabilities`, `/api/advanced/lineage`). Degrades
+  gracefully when Node.js is absent.
+- `docs/SKILL.md` gains an advanced-server operating section (value-space rules, hue-axis
+  guard/warnings, relayout recipes, closed-project DB-patch + quit/relaunch discipline) plus
+  DRX-apply gotchas and a session-start MCP-update note (surface `update_decision` once;
+  applying updates stays with `install.py` / the control panel).
+- New DRX calibration docs: `CALIBRATION-STATUS.md` (per-control coverage ledger — what is
+  confirmed, how it was verified, and what remains experimental) and a corrected
+  `DRX-VALUE-SCALING.md` (offset ÷25, saturation ÷50, contrast 1:1, affine hue/contrast-range
+  mappings).
+
+### Validation
+
+- Full offline Node suite green (671 tests / 650 pass, legacy live harnesses skip cleanly) +
+  doc-count drift guard. DRX write paths live-verified against DaVinci Resolve 19.1.3 Studio
+  by panel readback (windows, qualifiers, HDR zones, ColorSlice, HSL curves); Color Warper
+  write is R21-format and pends an R21 verify. Resolve-behavior validation for the offline
+  QC/finishing tools remains gated on real footage (they compute/plan; apply stays in the
+  live server) — no live Python-server behavior changed in this release.
+
+### Cross-platform agent guidance
+
+Also in this release: per-domain agent routing between the live Python server and the
+offline advanced server, available in every IDE — not just Claude Code. No tool counts
+change (compound 34 / granular 341 / advanced 18).
+
+- **7 per-domain MCP prompts** (`color_grade_workflow`, `timeline_edit_workflow`,
+  `conform_workflow`, `delivery_workflow`, `fusion_workflow`, `audio_workflow`,
+  `media_pool_workflow`) — slash commands in *every* MCP client, each routing a task
+  across its live tools and its offline advanced-server counterpart (compute offline,
+  apply live).
+- **9 Claude Code skills** (`.claude/skills/`): a `resolve-mcp` index plus eight domain
+  routers (color, edit, conform, delivery, fusion, audio, media-pool, media-analysis).
+  Thin bridges to the kernels; all 18 advanced tools are routed.
+- **Generated cross-platform rule files** from a single manifest
+  (`scripts/agent-rules/generate.mjs`): `.cursor/rules/*`, `.github/instructions/*` +
+  `.github/copilot-instructions.md`, `.windsurf/rules/*`, `.clinerules`, `.roo/rules/*`,
+  `.continue/rules/*`, and an `AGENTS.md` domain-routing block. Tool/action counts are
+  parsed from their canonical docs so they cannot drift; a stale generated file fails
+  `tests/test_agent_rules_drift.py`.
+- Every kernel with an offline counterpart gained an "Advanced (offline) server" section.
+  Fixed stale tool counts / doc paths that had drifted in `.github/copilot-instructions.md`,
+  `.clinerules`, `.cursorrules`, and `.windsurfrules`.
+
+## What's New in v2.57.5
+
+Fixes a silent data-loss bug on Reel Name writes (issue #77) and bundles the
+community-contributed API-limitation entries from PR #76 (issue #75).
+
+- **Fixed** (#77) `set_clip_property` / `set_metadata` reporting `success: true`
+  when writing the `Reel Name` clip property even though Resolve silently
+  dropped the value. Resolve gates `Reel Name` behind the project setting
+  *General Options > Assist using reel names from the:* — when that derives reel
+  names automatically, scripted writes are ignored but still return `True`. On a
+  batch ingest this meant hundreds of clips believed to have reel names assigned
+  when none actually stuck. The server now reads the value back after writing
+  known-unreliable keys and refuses to report success on mismatch, surfacing the
+  project-setting gate as a `hint`. Wired into `set_clip_property`,
+  `set_metadata` (both forms), and the bulk `normalize_metadata` path. Adds an
+  `api_truth` bug entry (report now lists 18 missing + 11 bugs) and 10 unit
+  tests.
+- **Added** (PR #76, thanks @swayll) four `submit: missing` API-limitation
+  entries verified on Resolve 21.0.0: per-subtitle text/timing editing, subtitle
+  track styling/presets, speech-recognition engine selection + SRT import, and
+  Media Pool folder rename. These document the API ceiling behind the subtitle
+  feature request in #75 — direct subtitle text editing and SRT round-trip are
+  not exposed by the Blackmagic scripting API.
+
+### Validation
+
+- Offline: full unit suite green; new `tests/test_reel_name_writeback.py` (10
+  tests) plus the api_truth/limitations drift guards. Live Resolve validation of
+  the Reel Name read-back is recommended but not performed here — forcing the
+  gate would require writing reel names into a live project's media metadata.
+
 ## What's New in v2.57.4
 
 Live mutating verification of the catalogued API gaps.
@@ -1684,8 +1879,8 @@ coverage, the destructive hook, update hardening, and update history.
 **Validation** — `tests/test_import.py`, `scripts/audit_api_parity.py`,
 `node bin/davinci-resolve-mcp.mjs --version`, `npm pack --dry-run`, and
 `git diff --check` all pass. 375 focused unit tests pass. Live Resolve
-validation covered the D1–F2 surface end-to-end against project CKY /
-Timeline 7 (D1 `retryable`, D2 XML descriptions, D3 partial-success on
+validation covered the D1–F2 surface end-to-end against a live production
+project / Timeline 7 (D1 `retryable`, D2 XML descriptions, D3 partial-success on
 plans + CAPS_REFUSAL manifests, E1 8 MCP resource URIs, E2 escalation on
 3× repeated failure, E3 `prefer_handle` job handoff with
 `batch_job_status` polling, F1 provenance block) — 6/6 PASS on the

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025-2026 DaVinci Resolve MCP Contributors
+Copyright (c) 2025-2026 DaVinci Resolve MCP Contributors and Bradford Operations LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.57.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.58.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-34%20(341%20full)-blue.svg)](#server-modes)
@@ -54,6 +54,78 @@ The command starts a localhost server and opens the control panel in your browse
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
+### Advanced server — beyond the scripting API (optional, Node)
+
+The same package ships a second, optional MCP server: **`davinci-resolve-advanced-mcp`** (bin
+`bin/davinci-resolve-advanced-mcp.mjs`). Where the Python server drives a *live* Resolve over the
+sanctioned scripting API, the advanced server does what the API **can't** — it reads and edits Resolve
+**files** (`.drp` / `.drt` / `.drx`) and applies DB/XML-level changes **with no Resolve running**, so it
+runs cloud *or* local. 18 tools: `drp`, `drt`, `drx` (per-clip grade codec **plus a deterministic,
+offline grading/QC catalog** — within-camera + cross-camera skin (v2 skin-line metric) + b-roll +
+neutral-patch WB matching, match-to-reference, saturation/black-balance, contrast-normalize, ASC CDL
+import, lossless grade-transfer + season-look authoring, named-LUT attach, scope reads + intent tags,
+verify-grade, display-referred frame extraction, broadcast-legal QC), `offline_ref`,
+`conform` (frame-oracle conform/relink QC + lineage), `color_trace` (carry grades across a re-conform),
+`fusion`, `audio_plan`, `fairlight` (bus routing), `audio`, `project_read`, `project_db`, `pipeline`
+(a **DB-as-truth pipeline**: compile YAML project specs into a canonical SQLite DB, then run stages with
+gates, provenance, and intent↔actual drift detection), `capabilities`, `deliverable` (deliverable QC /
+compliance), `media` (media front-end / AE ingest), `editorial` (editorial integrity / changelist),
+`provenance` (provenance / audit / episode report). It can also be consumed **as a
+library** (importable engine API), not just spawned as a server.
+
+DRX grade writes are **live-calibrated against Resolve Studio**: grade params take Resolve's
+on-screen panel units by default (`space: 'ui' | 'drx'`), and the structural writes (power windows,
+qualifiers, HDR zones, HSL curves, ColorSlice, blur/key/motion-effects) are panel-readback-verified —
+per-control status in `resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md`. It also closes
+a UI-only gap: **programmatic "Cleanup Node Graph"** (`drx` `relayout` for one clip, `project_db`
+`relayout_node_graphs` for a whole project) — node layout tidied, grade content byte-preserved.
+
+Add it alongside the live server (both ship in one `npm install`):
+
+```json
+{
+  "mcpServers": {
+    "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
+    "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
+  }
+}
+```
+
+`install.py` prints both entries. The core is pure-JS/MIT with no required native modules; a few features
+need user-installed tools (ffmpeg for `audio`, `sharp`/`better-sqlite3` for some paths) — call the
+`capabilities` tool for live status and install hints.
+
+### Bradford Post Assistant — managed application (closed beta)
+
+The maintainers also build **Bradford Post Assistant**, a desktop application on top of this
+open foundation. Where the MCP servers give an agent hands, Post Assistant is the working
+copilot around them — an on-device AI assistant for post-production where client material
+never leaves the workstation:
+
+- **A post-production copilot** — a desktop app that sits alongside DaVinci Resolve and
+  watches the session live (timeline, grades, and frames — not just API calls), with an
+  embedded AI assistant and agent runtime, local media analysis (transcription, frame
+  analysis, editorial intelligence), and in-app conform QC.
+- **Memory** — persistent, encrypted on-device assistant memory plus cross-episode learning
+  mined from your pipeline's decoded facts (season-look drift, per-camera correction priors,
+  hero-frame libraries, conform path-map reuse), with accumulation managed for you and a
+  reviewed-insight workflow.
+- **Self-contained by design** — Post Assistant wires everything itself: this MCP for
+  Resolve control, the Bradford API for its extended services, and your choice of LLM
+  provider. Nothing to configure by hand, no separate clients to manage, and the app keeps
+  itself (and its bundled MCP) current with signed auto-updates.
+- **An extended professional toolset** — grade surgery on live projects, 22+ adaptive grade
+  families, a curated looks library, delivery-spec validation, editorial pacing/cleanup
+  analysis, natural-language color direction, and Fusion composition authoring — delivered
+  through the managed Bradford API.
+- **Production workflows** — the raw tools composed into finished, real-world flows
+  (turnover → conform → QC → delivery, season-look carry, episode reporting) with the
+  guardrails and approvals a client-facing shop expects.
+
+It is currently in **closed beta** — you can request access at
+[bradfordoperations.com/software/post-assistant](https://www.bradfordoperations.com/software/post-assistant).
+The open-source servers are complete and fully functional on their own.
+
 ## What You Can Do
 
 ```text

package/bin/davinci-resolve-advanced-mcp.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * davinci-resolve-advanced-mcp — entry point.
+ *
+ * The Node, beyond-the-API sibling bin to davinci-resolve-mcp. Authors/edits
+ * DaVinci Resolve files (.drp/.drt/.drx) offline — no Resolve, cloud or local.
+ *
+ * Boots the stdio MCP server in resolve-advanced/server. (During dev the
+ * vendored libs + deps live under resolve-advanced/; Phase 4 promotes deps to
+ * the repo root for the published package.)
+ */
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverEntry = path.resolve(__dirname, '..', 'resolve-advanced', 'server', 'index.mjs');
+
+const { startServer } = await import(serverEntry);
+await startServer();

package/docs/README.md

@@ -41,6 +41,25 @@ ignored scratch folders such as `docs/_scratch/`.
 - [Project Lifecycle](kernels/project-lifecycle-kernel.md)
 - [Extension Authoring](kernels/extension-authoring-kernel.md)
 
+## Claude Code Skills
+
+Per-domain skills in `.claude/skills/` route craft ↔ live tools ↔ offline
+advanced tools automatically when an agent works in that domain. They are thin
+bridges — the authoritative depth stays in the kernels and guides above.
+
+- `resolve-mcp` (`.claude/skills/resolve.md`) — orientation/index: the map to the domain skills below (self-trigger; not an auto-loader)
+- `resolve-color` (`.claude/skills/color-grade.md`) — grading, looks, shot match, LUT/CDL/DRX
+- `resolve-edit` (`.claude/skills/timeline-edit.md`) — cutting, ranges, variants, changelist
+- `resolve-conform` (`.claude/skills/conform.md`) — conform, relink, finishing QC, grade tracing
+- `resolve-delivery` (`.claude/skills/delivery.md`) — render, deliverable QC, media/provenance
+- `resolve-fusion` (`.claude/skills/fusion.md`) — Fusion comps (titles, motion graphics, VFX)
+- `resolve-audio` (`.claude/skills/audio.md`) — audio/Fairlight tracks, buses, loudness, sync
+- `resolve-media-pool` (`.claude/skills/media-pool.md`) — media pool ingest, organize, multicam
+- `resolve-media-analysis` (`.claude/skills/media-analysis.md`) — source-safe media intelligence
+
+The offline half of every one is the advanced server; see
+[Advanced Server](../resolve-advanced/README.md).
+
 ## Authoring References
 
 - [Fuse + DCTL Authoring](authoring/fuse-dctl-authoring.md)

package/docs/SKILL.md

@@ -17,6 +17,16 @@ DaVinci Resolve must be running with **Preferences > General > "External scripti
 using"** set to **Local**. The server auto-launches Resolve if it is not running,
 but that first connection can take up to 60 seconds.
 
+**Session-start update note.** The first `resolve_control(action="get_version")`
+of a session returns an `mcp` block with the cached update check
+(`mcp.update` + `mcp.update_decision`). If `update_decision.action` is
+`"notify"` or `"prompt"`, tell the user ONCE that a newer MCP release is
+available (version + one-line pointer). Do not repeat it, do not auto-apply,
+and do not treat it as an error — updates are applied by the user via
+`python install.py` or the control panel's Settings page. If the user asks to
+check on demand, use `resolve_control(action="mcp_update_status",
+params={"force_check": true})`.
+
 Workflow Integration plugins/scripts are a separate Resolve-hosted UI mechanism.
 They are not required for this MCP server, but `docs/integrations/workflow-integrations.md`
 summarizes when they are useful for optional in-Resolve panels, UIManager
@@ -103,12 +113,55 @@ before mutating Resolve state.
 
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
-| Compound (default) | `src/server.py` | 32 tools | Most workflows — keeps context lean |
+| Compound (default) | `src/server.py` | 34 tools | Most workflows — keeps context lean |
 | Granular (full) | `src/server.py --full` | 341 tools | Power users needing one tool per API method |
 
 This skill document covers the **compound server** (the default). Each compound
 tool accepts an `action` string and an optional `params` object.
 
+### The advanced server (`davinci-resolve-advanced-mcp`)
+
+The same package ships an optional third surface: an offline Node server (18
+tools, typically registered as `davinci-resolve-advanced`) that edits Resolve
+**files** (`.drp`/`.drt`/`.drx`) and patches the project DB — no running Resolve
+required. Rule of thumb: drive a *live session* with the Python server; compute
+grades, QC, conform math, and file-level edits with the advanced server, then
+apply results through the live server. Full catalog: `resolve-advanced/README.md`.
+
+Operating rules an agent must know:
+
+- **Grade value space.** `drx` `generate`/`merge` default to `space:'ui'` —
+  params are Resolve PANEL units (lift/gamma/gain/offset panel numbers,
+  saturation 0–100 neutral 50). Pass `space:'drx'` only for raw internal floats
+  (e.g. re-encoding decoded values). Decoded values are ground truth only for
+  the calibrated native set — check the `valueFidelity` marker on `parse`
+  results; per-control status is `resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md`.
+- **Hue-axis curves.** Naive `[0,1]` point lists are canonicalized into the
+  verified bezier cage automatically. Pre-wrapped lists (x outside `[0,1]`) are
+  REFUSED unless `allowWrappedHueCage:true` (malformed cages can crash Resolve
+  19). If a `generate`/`merge` result carries a `warnings` array, the curve was
+  passed through raw and will render FLAT — tell the user, don't ship it silently.
+- **Node-graph relayout** (programmatic "Cleanup Node Graph"; the UI command
+  has no API). Single clip, live: `gallery_stills.grab_and_export` → advanced
+  `drx(action="relayout")` → `graph.reset_all_grades` → `safe_apply_drx` with
+  EXPLICIT item indices (the reset is required — a same-structure apply keeps
+  the old layout). Whole project, offline: `project_db(action="relayout_node_graphs")`.
+- **project_db patches** require the project CLOSED in Resolve plus
+  `iConfirmProjectClosed:true`; every write auto-backs-up and read-back
+  verifies. Resolve caches open projects in memory: after patching, fully QUIT
+  and relaunch Resolve or the patch will not be visible.
+- **Guards are load-bearing.** Advanced tools refuse rather than fabricate
+  (silent-lie guards): a thrown "refused" error usually means wrong input space,
+  log-encoded frames, or missing media — read the message before retrying.
+  Optional native deps (`better-sqlite3`, `sharp`, ffmpeg) gate some actions;
+  call the advanced `capabilities` tool for live status and install hints.
+
+Per-domain depth for both servers lives in the kernels (`docs/kernels/`), each of
+which carries an "Advanced (offline) server" section where an offline counterpart
+exists. Claude Code skills in `.claude/skills/` (`resolve-color`, `resolve-edit`,
+`resolve-conform`, `resolve-delivery`, `resolve-media-analysis`) route
+craft ↔ live ↔ offline automatically when working in that domain.
+
 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 source-safe project, selected-clip, bin, file, or sequence
@@ -1157,6 +1210,14 @@ Key actions: `get_num_nodes(source?)`, `set_lut(node_index, lut_path, source?)`,
 `1`=source timecode aligned, `2`=start frames aligned,
 `reset_all_grades(source?)`
 
+DRX-apply gotchas (also apply to `timeline_item_color.safe_apply_drx`): ALWAYS pass
+`track_type`/`track_index`/`item_index` explicitly — the default target is video track 1
+item 0, NOT the current clip — and grab a still/`.drx` backup first (`safe_apply_drx` does
+not snapshot). When the applied `.drx` has the same node structure/ids as the target's
+current graph, Resolve keeps the existing node-editor layout (positions in the `.drx` are
+silently ignored); to re-layout a graph programmatically, reset the grade first, then
+apply (see the advanced server's `drx` `relayout` and `api_truth`).
+
 **`color_group`** — Manage color groups.
 
 Key actions: `list`, `get_name(group_name)`, `set_name(group_name, new_name)`,

package/docs/contributing.md

@@ -63,7 +63,7 @@ This MCP server controls DaVinci Resolve via its Scripting API. Some tools perfo
 davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
-│   ├── server.py                # Compound MCP server — 32 tools (default)
+│   ├── server.py                # Compound MCP server — 34 tools (default)
 │   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 341 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers

package/docs/guides/control-panel.md

@@ -184,6 +184,15 @@ created, and render time against the active tier, and the AI-ops ledger
   sizes for the active project.
 - **Tools** — runtime helpers (ffprobe, ffmpeg, Whisper backends, OpenCV)
   with ready/missing status and copyable install commands.
+- **Advanced** — live capability status for the optional offline Node server
+  (`davinci-resolve-advanced-mcp`): the pure-JS core plus each user-installed
+  helper (ffmpeg, sharp, better-sqlite3) with what it enables and how to
+  install it. The full tool catalog is available under Docs → Advanced Server.
+- **Conform QC** — read-only browser for a conform lineage sidecar: point at
+  the `.db` the advanced server's `conform` tool writes to inspect snapshots,
+  diff a snapshot against its predecessor, and review per-cut frame-QC
+  verdicts (MATCH / OFFSET / WRONG / REF_OFFLINE / UNREADABLE) with tallies.
+  Ingest and QC runs stay with the MCP tools; the panel never writes.
 - **Media Pool History** — the provenance log for destructive media-pool
   operations (deletes, replaces, relinks), kept separate from timeline brain
   edits.

package/docs/kernels/README.md

@@ -21,6 +21,27 @@ Current kernel coverage: **136 actions** across **9 compound MCP tools**.
 | Project lifecycle | `project_manager` | `project_capabilities`, `probe_project_lifecycle`, `probe_project_settings`, `safe_project_create`, `safe_project_export`, `safe_project_import`, `safe_project_archive`, `safe_project_restore`, `safe_project_delete`, `safe_set_project_settings`, `project_settings_snapshot`, `database_capabilities`, `safe_set_current_database`, `preset_lifecycle_probe`, `project_boundary_report` |
 | Extension authoring | `script_plugin` | `extension_capabilities`, `probe_fuse_lifecycle`, `probe_dctl_lifecycle`, `probe_script_lifecycle`, `safe_install_extension`, `safe_remove_extension`, `refresh_or_restart_required`, `extension_boundary_report` |
 
+## Advanced (offline) server
+
+The kernels above wrap the **live** Python server (`davinci-resolve`), which
+drives a running Resolve. A companion **advanced** server
+(`davinci-resolve-advanced`, 18 tools — see `resolve-advanced/README.md`) does
+the beyond-API, **no-Resolve-running** half: it authors/edits `.drp`/`.drt`/`.drx`
+files, patches the project DB, and computes grades, conform QC, and deliverable
+QC offline. The rule of thumb is *compute offline, apply live*. Kernels that have
+an offline counterpart carry an "Advanced (offline) server" section linking the
+two:
+
+- Color / Grade → `drx` grading/QC catalog + relayout
+- Timeline Conform / Interchange → `conform`, `color_trace`, `offline_ref`, `editorial`
+- Render / Deliver → `deliverable`, `media`, `provenance`
+- Timeline Edit → `editorial` (interchange + changelist), `drt`
+
+Per-domain Claude Code skills route craft ↔ live ↔ offline automatically and live
+in `.claude/skills/`: `resolve-color`, `resolve-edit`, `resolve-conform`,
+`resolve-delivery` (plus `resolve-media-analysis`). `docs/SKILL.md` is the
+top-level brief for both servers.
+
 Helper-tool details that need more than an action list live in guides. See
 [Multicam Setup Helper Guide](../guides/multicam-setup-guide.md) for the
 `media_pool.setup_multicam_timeline` helper/API boundary and Resolve UI

package/docs/kernels/audio-fairlight-kernel.md

@@ -68,6 +68,28 @@ All kernel actions are exposed through `timeline`.
 - The public API does not expose full Fairlight mix automation curves or plugin
   parameter graphs.
 
+## Advanced (offline) server — Fairlight planning + bus routing
+
+The actions above drive audio on a *running* Resolve. The companion advanced
+server (`davinci-resolve-advanced`, see `resolve-advanced/README.md`) plans and
+patches audio **offline, no Resolve running**:
+
+- **`audio_plan`** (pure Node) — `list_templates`, `select_template`,
+  `track_plan`, `analyze_coverage`, `check_loudness` (against R128/ATSC/streaming
+  targets). Plan the Fairlight track/bus layout before building it live.
+- **`fairlight`** — Fairlight **bus routing**, which has *no scripting API*: it
+  patches the `FLStudioModelBA` blob directly. `read_buses_from_blob` (offline
+  codec); `read_buses_from_db`, `expand_buses`, `export_template` /
+  `import_template`, `backup`, `restore` (DB path — needs optional
+  `better-sqlite3`; project CLOSED + quit/relaunch, like other DB patches).
+- **`audio`** — offline ffmpeg ops: `split` (silence/TC/intervals), `trim`,
+  `convert` (needs ffmpeg on PATH — GPL, not bundled). Align/loudness-measure are
+  not yet vendored.
+
+Rule of thumb: plan/measure offline, apply mix/track changes live; use
+`fairlight` for bus work the scripting API can't reach. See the `resolve-audio`
+skill (`.claude/skills/audio.md`) and the `/audio_workflow` prompt.
+
 ## Live Probe
 
 Run the live boundary probe with:

package/docs/kernels/color-grade-kernel.md

@@ -86,6 +86,57 @@ All actions are exposed through `timeline_item_color`.
   as callable methods but are not forced in the boundary report because they can
   be asynchronous, page dependent, and expensive.
 
+## Advanced (offline) server — the grading / QC catalog
+
+The live actions above drive a *running* Resolve. The companion advanced server
+(`davinci-resolve-advanced`, see `resolve-advanced/README.md`) *computes* grades
+offline from extracted frames and reads/writes `.drx`/`.drp` grades with **no
+Resolve running**. It emits an apply-ready `.drx`; **applying it is this kernel's
+job** (`safe_apply_drx`). Node never drives Resolve.
+
+`drx` grading/QC actions (frame-stats → arithmetic → `.drx`, all local,
+deterministic, guarded — they refuse to fabricate a match rather than emit a
+silent no-op):
+
+| Action | Use when |
+| --- | --- |
+| `match_to_reference` | Match a clip toward an approved still (affine mean/std, skin-line gated, luma-preserving). |
+| `level_clips` | Level within-camera exposure/WB drift to a group hero. |
+| `skin_match` | Cross-camera skin-tone cohesion (skin-gated; throws on log/wrong-space frames). |
+| `shot_match` | B-roll cohesion (gray-world neutralize or hero match). |
+| `white_balance_match` | WB from a known-neutral patch / gray card. |
+| `contrast_normalize` | Match black/white points to a hero (affine gain+offset). |
+| `saturation_match` / `black_balance` | Saturation cohesion / neutralize a shadow cast. |
+| `cdl_io` | Import ASC CDL (`.cc`/`.ccc`/`.cdl`) → `.drx`. |
+| `grade_transfer` | Lossless Body copy — a `.drp` group / `.drx` look → apply-ready `.drx`. |
+| `lut_apply` | Attach a named `.cube` LUT to a node (round-trip asserted). |
+| `author_look` / `carry_look` | Version and carry an approved season/host look. |
+| `scope_read` / `intent_tags` / `gamut_legal` | Read frames: parade/vectorscope/clip%, shot-intent tags, broadcast-legal QC. |
+| `verify_grade` | Intended vs applied `.drx` → landed/drifted/missing/unverifiable. |
+
+Cross-server rules an agent must know:
+
+- **Value space.** `drx` `generate`/`merge` default to `space:'ui'` (Resolve
+  panel units; saturation 0–100, neutral 50). Pass `space:'drx'` only for raw
+  internal floats. Fidelity is ground-truth only for the calibrated set — check
+  the `valueFidelity` marker
+  (`resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md`).
+- **Hue-axis curves.** Naive `[0,1]` point lists auto-canonicalize into the
+  verified bezier cage; a `warnings` array in the result means the curve went
+  through raw and will render **FLAT** — surface it, don't ship silently.
+- **Apply targeting.** `safe_apply_drx` defaults to video track 1 / item 0 —
+  always pass `track_type`/`track_index`/`item_index` explicitly, and grab a
+  still/`.drx` backup first (`safe_apply_drx` does not snapshot).
+- **Relayout ("Cleanup Node Graph," no UI API).** Single clip, live: grab still →
+  `drx(action="relayout")` → `graph.reset_all_grades` → `safe_apply_drx` with
+  explicit indices (a same-structure apply keeps the OLD layout — the reset is
+  required). Whole project, offline: `project_db(action="relayout_node_graphs")`.
+- **Deps.** The grading catalog needs `sharp`; call the advanced `capabilities`
+  tool for live status and install hints.
+
+See the `resolve-color` skill (`.claude/skills/color-grade.md`) for the
+craft ↔ live ↔ offline routing and the frame-first rule.
+
 ## Live Probe
 
 Run the live boundary probe with: