davinci-resolve-mcp 2.57.4 → 2.58.0

package/docs/kernels/fusion-composition-kernel.md

@@ -104,6 +104,23 @@ in success and in error responses.
   effect parameter. Higher-level wrappers should probe before assuming a
   control exists.
 
+## Advanced (offline) server — declarative `.comp` authoring
+
+The actions above build a Fusion comp on a timeline item in a *running* Resolve.
+The companion advanced server (`davinci-resolve-advanced`, see
+`resolve-advanced/README.md`) authors Fusion compositions **offline, no Resolve
+running**, via the `fusion` tool:
+
+- `generate` / `generate_from_template` — write a `.comp` from a declarative spec
+  or a named template (`list_templates`).
+- `to_api_calls` — compile a spec into the ordered tool-creation / input /
+  connection calls the live server then replays.
+
+Rule of thumb: author and verify the comp offline, then apply it live with
+`fusion_comp` `safe_add_tool` → `safe_set_inputs` → `safe_connect_tools` (the
+`to_api_calls` output maps directly onto those). See the `resolve-fusion` skill
+(`.claude/skills/fusion.md`) and the `/fusion_workflow` prompt.
+
 ## Live Probe
 
 Run the live boundary probe with:

package/docs/kernels/media-pool-ingest-kernel.md

@@ -120,6 +120,26 @@ params={"confirm": true, ...})`.
   the installed DaVinci Resolve 20 Manual, Edit > Chapter 42, "Multicam
   Editing," for the current UI workflow.
 
+## Advanced (offline) server — media front-end / ingest verification
+
+The actions above import and organize media in a *running* Resolve. The companion
+advanced server (`davinci-resolve-advanced`, see `resolve-advanced/README.md`)
+handles the front-end / assistant-editor ingest layer **offline, no Resolve
+running**, via the `media` tool (needs ffmpeg + ffprobe on PATH for the probing
+actions):
+
+- `ingest_verify` — hash seal / verify / dupes-by-hash (chain-of-custody).
+- `media_inventory` — fps / codec / colorspace / TC + card-gap report.
+- `sync` — picture↔sound TC alignment + drift / MOS detection.
+- `relink_manifest`, `rename_plan` (**refuses camera originals**) /
+  `reel_normalize`, `turnover_package`, `project_hygiene`.
+
+Rule of thumb: verify and inventory the card offline *before* importing, then
+import/organize live. `media` also serves the delivery side (see the
+`resolve-delivery` skill). See the `resolve-media-pool` skill
+(`.claude/skills/media-pool.md`) and the `/media_pool_workflow` prompt. Never
+rename or derive camera originals without explicit approval.
+
 ## Live Evidence
 
 Final validation ran on May 9, 2026 with DaVinci Resolve Studio 20.3.2.9 and

package/docs/kernels/render-deliver-kernel.md

@@ -64,6 +64,38 @@ All actions are under `render(action=...)`.
   existing `render_presets` tool, but the live kernel probe does not fabricate
   arbitrary preset files.
 
+## Advanced (offline) server — deliverable QC, media front-end, provenance
+
+The live actions above plan and drive renders in a *running* Resolve. The
+companion advanced server (`davinci-resolve-advanced`, see
+`resolve-advanced/README.md`) QCs the **finished render** and manages media/
+provenance with **no Resolve running**. It is report-only —
+**`gate: review`, never auto-pass-clear.**
+
+- **`deliverable`** — `deliverable_qc` (ffprobe a render vs its spec → pass/fail
+  **per field**), `loudness_qc` (ebur128 LUFS/true-peak/LRA),
+  `reframe_blanking_check`, `conform_completeness` (every intended shot present),
+  `re_delivery_diff`, `render_manifest` (build/reconcile), `expand_deliverable`
+  (texted/textless/stems/slate/leader entities).
+- **`media`** (front-end / AE) — `ingest_verify` (hash seal/verify/dupes),
+  `media_inventory` (fps/codec/colorspace/TC + card gaps), `sync` (picture↔sound
+  TC + drift/MOS), `relink_manifest`, `rename_plan` (**refuses camera
+  originals**) / `reel_normalize`, `turnover_package`, `project_hygiene`.
+- **`provenance`** (audit) — `grade_provenance` ("why is this graded this way"),
+  `gallery_lineage`, `cdl_export` / `cdl_diff` (round-trip asserted),
+  `revision_tracking`, `episode_report`.
+
+Rules an agent must know:
+
+- QC tools **refuse rather than fabricate** — a "refused" result means missing
+  file, wrong spec, or a metric it cannot honestly compute.
+- Deliverable gates never auto-clear; surface the per-field verdict to a human.
+- **Deps.** `deliverable`/`media` QC needs **ffmpeg + ffprobe on PATH** (GPL, not
+  bundled) — call the advanced `capabilities` tool for status + install hints.
+
+See the `resolve-delivery` skill (`.claude/skills/delivery.md`) for the
+craft ↔ live ↔ offline routing.
+
 ## Live Evidence
 
 Final validation ran on May 9, 2026 with DaVinci Resolve Studio 20.3.2.9 and

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -84,6 +84,45 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
 - Export and import helpers require temp paths by default because they write
   interchange artifacts.
 
+## Advanced (offline) server — the conform QC engine
+
+The live actions above operate on a *running* Resolve. The companion advanced
+server (`davinci-resolve-advanced`, see `resolve-advanced/README.md`) does the
+finishing-grade conform work with **no Resolve running**, against `.drt`/`.drp`
+files and the project DB.
+
+- **`conform`** — offline conform/relink QC with **frame-oracle math, not
+  filename matching** (it catches a clip relinked to the wrong-but-similarly-named
+  source). Also: reverse/retimed subclip DB repair (reversed `source_start` =
+  `masterFrames − 1 − endoffset`, live-validated), sequence lineage store + diff +
+  rollback (hashed snapshots), and per-cut frame QC (oracle-frame vs
+  reference-render, scale-corrected, red/yellow/cyan verdicts).
+- **`color_trace`** — cross-project clip matching → a trace plan for carrying
+  grades across a re-conform (pairs with the color kernel's `drx grade_transfer`).
+- **`offline_ref`** — offline-reference clips have **no scripting API** but live
+  inside `.drp`/`.drt` as `<OfflineClip>` entries; patch them here.
+- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML; **AAF = honest refuse**),
+  `turnover_changelist` (moved/retimed/replaced/new/gone with timing guards),
+  `conform_manifest`, `marker_roundtrip`.
+- **`drt` / `project_db`** — timeline file authoring and DB patching.
+
+Gotchas the live path shares:
+
+- **XML import via the scripting API goes _offline_** (missing-media/generators
+  abort). Use `import_timeline_checked` with media **sanitize** (FCP7/FCPXML) so
+  the API imports with links intact, then exact-path relink. Restart a running MCP
+  server to pick up the sanitize fix.
+- **`.drt` version.** For DaVinci Resolve 19.1.3, set `DbPrjVer` 17 → 16 when
+  authoring a `.drt`.
+- **`project_db` patches** require the project **CLOSED** plus
+  `iConfirmProjectClosed:true`; writes auto-back-up and read-back verify. Resolve
+  caches open projects — **fully quit and relaunch** after patching.
+- **Deps.** `better-sqlite3` gates lineage/reverse/DB; `sharp`/ffmpeg gate frame
+  compare — call the advanced `capabilities` tool.
+
+See the `resolve-conform` skill (`.claude/skills/conform.md`) for the
+craft ↔ live ↔ offline routing.
+
 ## Live Probe
 
 Run the live boundary probe with:

package/docs/kernels/timeline-edit-kernel.md

@@ -180,6 +180,23 @@ Some behavior depends on Resolve's current page or bridge state:
   if Resolve loses current timeline state, the harness records the bridge
   condition separately.
 
+## Advanced (offline) server — editorial interchange + changelist
+
+The kernel above restructures a *running* timeline. The companion advanced server
+(`davinci-resolve-advanced`, see `resolve-advanced/README.md`) authors/diffs
+timelines and reasons over editorial interchange with **no Resolve running**:
+
+- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML; **AAF = honest refuse**),
+  `turnover_changelist` (moved/retimed/replaced/new/gone between two cuts, with
+  timing silent-lie guards), `conform_manifest`, `marker_roundtrip`.
+- **`drt`** — `.drt` timeline file authoring + structural diff.
+
+Use these to answer "what changed between v3 and v4" or to hand a conform an
+accurate change list without opening either timeline. For conforming/relinking
+that change list, see the Timeline Conform / Interchange kernel and the
+`resolve-conform` skill; for the edit ↔ offline routing, see the `resolve-edit`
+skill (`.claude/skills/timeline-edit.md`).
+
 ## Development Guardrails
 
 - Use disposable projects and synthetic media for live validation.

package/docs/process/release-process.md

@@ -35,11 +35,15 @@ Every release bump must update all version surfaces:
   `venv/bin/python scripts/gen_api_limitations.py`. The
   `tests.test_api_limitations_doc` drift guard fails the suite if it is stale.
 - `docs/SKILL.md` when tool discovery, examples, or behavior changed
-- `docs/guides/control-panel.md` when the control panel UI changed, plus
+- `docs/guides/control-panel.md` — check EVERY release, not only when the
+  panel "changed": panel surfaces grow transitively (new tools, new docs pages,
+  new diagnostics cards), so review the guide for accuracy and update it plus
   regenerated screenshots: start the panel against a project with analysis
   data, then run `venv/bin/python scripts/regen_panel_screenshots.py`.
   The `tests.test_panel_docs_drift` guard fails the suite (and the publish
-  workflow) when the guide drifts from the panel's navigation or screenshots.
+  workflow) when the guide drifts from the panel's navigation or screenshots —
+  but the guard checks presence, not prose accuracy; the human pass is the
+  accuracy check.
 - Git tag, e.g. `v2.4.1`
 - GitHub Release notes
 
@@ -54,17 +58,35 @@ Always run static checks before release:
 venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
-venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift
+node scripts/agent-rules/generate.mjs --check
+venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version
 npm pack --dry-run
 git diff --check
 ```
 
-The three drift guards (undefined names in `src/`, tool action lists vs
-dispatch, control-panel guide vs panel navigation/screenshots) also run in the
-`Publish npm package` workflow on every `v*` tag, so a stale doc or drifted
-action list fails the publish — fix the drift rather than bypassing the gate.
+The drift guards (undefined names in `src/`, tool action lists vs dispatch,
+control-panel guide vs panel navigation/screenshots, api-limitations vs the
+api_truth ledger, and **tool counts across the docs vs reality** —
+`test_doc_tool_counts`) also run in the `Publish npm package` workflow on every
+`v*` tag, so a stale doc or drifted action list fails the publish — fix the drift
+rather than bypassing the gate.
+
+`test_doc_tool_counts` statically counts the compound (`src/server.py`), granular
+(`src/granular/`), and Node advanced (`resolve-advanced/server/index.mjs`) tools and
+asserts the numbers quoted in README, `resolve-advanced/README.md`, `docs/contributing.md`,
+`docs/SKILL.md`, `docs/reference/api-coverage.md`, and `.github/copilot-instructions.md`
+still match. When you add/remove a tool, update those docs to the counts the test prints.
+
+The cross-platform agent rule files (`.cursor/rules/*`, `.github/instructions/*`,
+`.windsurf/rules/*`, `.cursorrules`, `.windsurfrules`, the `AGENTS.md` domain-routing
+block, and `.github/copilot-instructions.md`) are **generated** by
+`scripts/agent-rules/generate.mjs`, which parses those same counts from their
+canonical docs. After a count or tool-routing change, run
+`node scripts/agent-rules/generate.mjs` and commit the result;
+`test_agent_rules_drift` fails the suite (and publish) if the committed files are
+stale. See `scripts/agent-rules/README.md`.
 
 Run focused unit tests for the changed surface. For recent timeline/marker
 helpers, this usually includes:

package/docs/reference/api-coverage.md

@@ -17,7 +17,7 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 ## API Coverage
 
-Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **33 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
+Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
 
 The 33rd compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 14 missing capabilities, 10 bugs / unreliable behaviors.
+**Totals:** 18 missing capabilities, 11 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -141,6 +141,34 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Create Smart/Power Bins in the Resolve UI; only regular bins are scriptable.
 - **Tags:** missing-method, media-pool, bins
 
+### Per-subtitle text content and timing editing
+
+- **Object:** `TimelineItem (subtitle track)`
+- **Behavior:** TimelineItem on a subtitle track exposes only 21 standard transform/composite properties (Pan, Tilt, ZoomX, Opacity, Crop, etc.). There are no methods to get or set subtitle text (GetText/SetText), start time, end time, or duration for individual subtitle items. Subtitles created via CreateSubtitlesFromAudio or imported via the Resolve UI cannot have their content or timing read or modified programmatically. Verified via dir() and GetProperty() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No workaround exists — subtitle text and timing are completely inaccessible from the scripting API. Must be edited in the Resolve UI.
+- **Tags:** missing-method, subtitle, text, timing
+
+### Subtitle track styling and presets
+
+- **Object:** `TimelineItem / Timeline / Project`
+- **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. TimelineItem.GetProperty() on subtitle items returns only transform/composite keys. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No workaround exists — subtitle styling is UI-only. Burn-in overlays via Fusion titles are a visual alternative but do not produce proper subtitle tracks.
+- **Tags:** missing-method, subtitle, style, preset
+
+### Speech recognition engine selection and SRT import
+
+- **Object:** `Timeline`
+- **Behavior:** Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) always uses the built-in Resolve speech recognition engine. There is no API parameter to select an alternative provider (e.g. whisper-cli, Google Speech, AWS Transcribe). The language selection via resolve.AUTO_CAPTION_LANGUAGE_* is the only customization; the engine itself cannot be changed. Furthermore, there is no API method to import an SRT file into a subtitle track programmatically — File -> Import -> Subtitle is UI-only.
+- **Workaround / current handling:** No workaround exists for provider selection or SRT import. External transcripts must be converted to SRT and imported through the Resolve UI.
+- **Tags:** missing-method, subtitle, transcription, speech-recognition, asr
+
+### Media Pool folder rename
+
+- **Object:** `MediaPool`
+- **Behavior:** MediaPool exposes AddSubFolder(name), DeleteSubFolders([names]), and MoveFolders([names], targetFolder) but no RenameSubFolder(oldName, newName) method. Folders can be created, deleted, and moved, but their names cannot be changed through the API. Verified via dir() on Resolve 21.0.0.
+- **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
+- **Tags:** missing-method, media-pool, folder
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return
@@ -220,3 +248,12 @@ values, or automation-hostile modal prompts.
 - **Behavior:** The Python bridge returns a callable for ANY attribute name, so hasattr(obj, 'TotallyMadeUpMethod') is always True and getattr never raises. This makes capability detection by hasattr impossible — verified on 21.0.0 (hasattr reported SetStart, Razor, AddNode, GenerateProxy, AddSmartBin etc. as present though none exist). Only dir() lists the real methods.
 - **Workaround / current handling:** Never probe method existence with hasattr/getattr; test membership against dir(obj) instead. Calling a fabricated method typically returns None/False with no error.
 - **Tags:** bridge, introspection, silent-failure
+
+### MediaPoolItem.SetClipProperty('Reel Name', ...)
+
+- **Object:** `MediaPoolItem`
+- **Signature:** `(propertyName, propertyValue) -> bool`
+- **Behavior:** Setting the 'Reel Name' clip property returns True but the value is silently dropped on read-back when the project is configured to derive reel names automatically (General Options > 'Assist using reel names from the:' set to source clip file / embedding / filename pattern). The same True-but-unpersisted behavior occurs via SetMetadata('Reel Name', ...). Other clip properties on the same clip (e.g. 'Comments') write and persist normally, so this is field-specific, not a bridge/permission failure. Verified on Resolve 21.0.0; reported as issue #77.
+- **Workaround / current handling:** After writing 'Reel Name', read it back with GetClipProperty('Reel Name') and refuse to report success on mismatch; surface the project-setting gate to the caller (server._verify_clip_property_writeback).
+- **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
+- **Tags:** unreliable-return, silent-failure, metadata, reel-name

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.57.4"
+VERSION = "2.58.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -666,14 +666,37 @@ def write_client_config(client, python_path, server_path, api_path, lib_path, dr
     return True, str(config_path)
 
 
+def build_advanced_entry(server_path):
+    """Build the config entry for the optional 'davinci-resolve-advanced' server.
+
+    This is the Node, beyond-the-scripting-API sibling (file/.drp/.drt/.drx
+    authoring + conform + editorial, no live Resolve required). It ships in the
+    same package as a second bin. Opt-in: include it only if you want the
+    file-level tools alongside the live server.
+    """
+    project_dir = Path(server_path).resolve().parents[1]  # .../src/server.py -> repo root
+    advanced_bin = project_dir / "bin" / "davinci-resolve-advanced-mcp.mjs"
+    return {"command": "node", "args": [str(advanced_bin)]}
+
+
 def generate_manual_config(python_path, server_path, api_path, lib_path):
     """Generate config snippets for manual setup."""
     entry = build_server_entry(python_path, server_path, api_path, lib_path)
     zed_entry = build_zed_entry(python_path, server_path, api_path, lib_path)
     opencode_entry = build_opencode_entry(python_path, server_path, api_path, lib_path)
-
-    standard = json.dumps({"mcpServers": {"davinci-resolve": entry}}, indent=2)
-    vscode_fmt = json.dumps({"servers": {"davinci-resolve": entry}}, indent=2)
+    advanced = build_advanced_entry(server_path)
+
+    # Standard snippet includes BOTH servers: the live Python server and the
+    # optional Node 'advanced' server (file-level, no Resolve). Drop the
+    # advanced entry if you only want live control.
+    standard = json.dumps({"mcpServers": {
+        "davinci-resolve": entry,
+        "davinci-resolve-advanced": advanced,
+    }}, indent=2)
+    vscode_fmt = json.dumps({"servers": {
+        "davinci-resolve": entry,
+        "davinci-resolve-advanced": advanced,
+    }}, indent=2)
     zed_fmt = json.dumps({"context_servers": {"davinci-resolve": zed_entry}}, indent=2)
     opencode_fmt = json.dumps({"mcp": {"davinci-resolve": opencode_entry}}, indent=2)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.57.4",
+  "version": "2.58.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",
@@ -14,11 +14,32 @@
   },
   "type": "module",
   "bin": {
-    "davinci-resolve-mcp": "./bin/davinci-resolve-mcp.mjs"
+    "davinci-resolve-mcp": "./bin/davinci-resolve-mcp.mjs",
+    "davinci-resolve-advanced-mcp": "./bin/davinci-resolve-advanced-mcp.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "adm-zip": "^0.5.16",
+    "fast-xml-parser": "^5.7.3",
+    "fzstd": "^0.1.1",
+    "jszip": "^3.10.1",
+    "uuid": "^9.0.0",
+    "zod": "^3.25.76",
+    "zstd-codec": "^0.1.5"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "js-yaml": "^4.1.0",
+    "pg": "^8.11.0",
+    "sharp": "^0.33.0"
   },
   "files": [
     "bin/",
     "src/**/*.py",
+    "resolve-advanced/server/**/*.mjs",
+    "resolve-advanced/vendor/**",
+    "resolve-advanced/package.json",
+    "resolve-advanced/README.md",
     "docs/**/*.md",
     "docs/reference/resolve_scripting_api.txt",
     "examples/**/*.md",

package/resolve-advanced/README.md

@@ -0,0 +1,194 @@
+# davinci-resolve-advanced-mcp
+
+The **beyond-the-API** half of `davinci-resolve-mcp`: a Node MCP server that authors and edits
+DaVinci Resolve **files** (`.drp` / `.drt` / `.drx`) and applies DB/XML-level changes (Fairlight
+routing, offline-reference, conform, color-group grade read) — **with no DaVinci Resolve running.**
+
+It ships as a second `bin` inside the `davinci-resolve-mcp` npm package (one install, two servers):
+
+```
+bin/davinci-resolve-mcp.mjs           → Python, live, sanctioned scripting API (drives Resolve)
+bin/davinci-resolve-advanced-mcp.mjs  → Node, beyond-API file/DB authoring (no Resolve required)   [this]
+```
+
+Runs cloud or local — the file tools never touch Resolve.
+
+## Two ways to use it
+
+- **As an MCP server** (the bin above) — point any MCP client at it.
+- **As a library** — `import` the engine directly. The package exposes a public API surface
+  (`server/lib.mjs`, wired via `package.json` `main`/`exports`), grouped as **codec** (offline
+  `.drp/.drt/.drx`), **grading** (deterministic compute cores), **pipeline** (the DB-as-truth
+  foundation), **tools** (the MCP tool handlers), and **mcp** (the stdio server entry). The MCP
+  server is a thin shell over these same exports.
+
+## Usage
+
+**As a library — a grading core.** You extract display-referred frames per clip (ffmpeg, your
+call); the engine computes the grade offline and writes an apply-ready `.drx`. Applying it in
+Resolve (via the scripting API) is the caller's job.
+
+```js
+import { computeSkinMatch } from 'davinci-resolve-advanced-mcp';
+
+const { grades, report, warnings } = await computeSkinMatch(
+  [
+    { id: 'B_0008', png: '/frames/B_0008.png', group: 'Guest' },
+    { id: 'C_0016', png: '/frames/C_0016.png', group: 'Guest' },
+  ],
+  { outDir: '/out/skin' },
+);
+// grades[].drxPath → apply in Resolve; warnings flag over-corrections; low-skin clips are skipped, not faked.
+```
+
+**The DB-as-truth pipeline** (via the `pipeline` tool handler — same API the MCP server exposes).
+Compile YAML specs into the canonical DB, plan a run, execute a deterministic stage (you supply the
+tool inputs), then read decoded state back and check drift:
+
+```js
+import { pipelineTool } from 'davinci-resolve-advanced-mcp';
+const call = (action, args) => pipelineTool.handler({ action, args });
+
+const dbPath = '/proj/project.db';
+const now = new Date().toISOString(); // the tool takes an explicit timestamp
+
+await call('compile', { dbPath, now, yamlDir: '/proj/specs' }); // YAML → resolved entity tree
+const { runId, stages } = await call('plan', { dbPath, episodeSlug: 'e012', now });
+
+// Deterministic stages run now (you pass the tool args); Resolve-apply stages return an action plan.
+await call('execute_stage', {
+  dbPath, runId, stageIndex: 0, now,
+  toolArgs: { tool: 'gamut_legal', args: { clips: [{ id: 'f', png: '/frames/f.png' }] } },
+});
+
+// Pull decoded actual state up and flag intent↔actual drift.
+await call('readback', {
+  dbPath, entitySlug: 'e012.group.Host', now,
+  facts: { 'look.lut': 'Kodak_5219' }, pushFields: [{ field: 'look.lut' }],
+});
+```
+
+## Tools (18)
+
+`drp` · `drt` · `drx` · `offline_ref` · `conform` · `color_trace` · `fusion` · `audio` ·
+`audio_plan` · `fairlight` · `project_db` · `project_read` · `pipeline` · `capabilities` ·
+`deliverable` · `media` · `editorial` · `provenance`
+
+Each dispatches on an `action`. Highlights:
+
+- **`drx`** — per-clip grade (`.drx`) codec: `parse`, `generate`, `generate_from_request`,
+  `export_cdl`, `merge`, plus the **grading/QC catalog** below.
+- **`drp` / `drt`** — project / timeline file authoring + editing + grade injection + structural diff.
+- **`conform`** — offline conform/relink QC engine (frame-oracle math, not filename matching),
+  reverse-clip DB repair, sequence lineage store + diff, per-cut frame QC.
+- **`color_trace`** — cross-project clip matching → a trace plan for carrying grades across a re-conform.
+- **`project_read` / `project_db`** — read/patch the Resolve project DB (SQLite or Postgres).
+- **`pipeline`** — the DB-as-truth pipeline foundation (see below).
+- **`deliverable`** — deliverable QC / compliance: `deliverable_qc` (ffprobe a render vs its spec →
+  pass/fail per field), `loudness_qc` (ebur128 LUFS/true-peak/LRA), `reframe_blanking_check`,
+  `conform_completeness`, `re_delivery_diff`, `render_manifest` (build/reconcile), `expand_deliverable`
+  (texted/textless/stems/slate/leader entities). Report-only (`gate: review` — never auto-pass-clear).
+- **`media`** — media front-end / AE: `ingest_verify` (hash seal/verify/dupes-by-hash), `media_inventory`
+  (fps/codec/colorspace/TC + card gaps), `sync` (TC picture↔sound + drift/MOS), `relink_manifest`,
+  `rename_plan` (refuses camera originals) / `reel_normalize`, `turnover_package`, `project_hygiene`.
+- **`editorial`** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML; AAF = honest refuse),
+  `turnover_changelist` (moved/retimed/replaced/new/gone + timing silent-lie guards), `conform_manifest`,
+  `marker_roundtrip`.
+- **`provenance`** — provenance / audit: `gallery_lineage`, `grade_provenance` ("why is this graded this
+  way"), `cdl_export` (+ `cdl_diff`, round-trip asserted), `revision_tracking`, `episode_report`.
+
+### Grading / QC catalog (`drx` actions — all local, deterministic, no Resolve)
+
+Frame-stats → arithmetic → `.drx` grade. Frame extraction and grade **apply** are the caller's job;
+these compute the grade offline. Each carries guards that refuse to fabricate a match rather than emit
+a silent no-op.
+
+| Action | What |
+|---|---|
+| `level_clips` | within-camera exposure/WB drift → a group hero (whole-frame mean) |
+| `skin_match` | cross-camera skin-tone cohesion (skin-gated mean; throws on log/wrong-space frames) |
+| `shot_match` | b-roll cohesion — gray-world `neutralize` or `hero` match (per-channel median) |
+| `white_balance_match` | WB from a known-neutral patch (gray card) — accurate, not gray-world guess |
+| `contrast_normalize` | match black/white points to a hero (affine gain+offset) |
+| `match_to_reference` | affine mean-std transfer toward an approved still (skin-line gated, luma-preserve) |
+| `saturation_match` | skin/overall saturation cohesion toward a hero |
+| `black_balance` | neutralize a shadow colour cast (p1 black point, offset-only) |
+| `cdl_io` | import ASC CDL (`.cc`/`.ccc`/`.cdl`) → `.drx` |
+| `grade_transfer` | lossless Body copy — a `.drp` group / `.drx` look → an apply-ready `.drx` |
+| `relayout` | programmatic "Cleanup Node Graph" (the UI command has no API) — rewrite node x/y to Resolve's clean row, grade byte-preserved. Live recipe: grab → `relayout` → reset grade → apply (same-structure applies keep the old layout). Bulk whole-project sweep: `project_db` `relayout_node_graphs` |
+| `author_look` / `carry_look` | version an approved season/host look + plan carrying it across episodes |
+| `lut_apply` | attach a named `.cube` LUT to a node (Body-LUT write path, round-trip asserted) |
+| `scope_read` | frame readouts: parade balance, vectorscope skin-line, black-balance, %clip/%crush + intent signals |
+| `intent_tags` | derive L1 shot-intent tags (low_key, monochromatic, motivated_warm) to exclude from neutralize |
+| `verify_grade` | intended vs applied `.drx` → landed/drifted/missing/unverifiable |
+| `extract_frames` | ffmpeg display-referred frame extraction (hard log-refuse) |
+| `gamut_legal` | broadcast-legal + hard-clip QC (measurement only, no grade emitted) |
+
+### Pipeline foundation (`pipeline` tool — DB-as-truth)
+
+A canonical local **SQLite project DB** is the source of truth; **YAML authoring compiles into it**
+(4-layer inheritance: type → series → episode → deliverable, with validation); a **runner** reads the
+resolved `pipeline:` and executes stages with gates + provenance; **readback** records decoded actual
+state and flags intent↔actual **drift**. Deterministic stages run in Node; Resolve-apply stages emit an
+action plan for the live agent (Node can't drive Resolve). Actions: `compile`, `list_entities`,
+`get_entity`, `ancestry`, `catalog`, `plan`, `execute_stage`, `approve_gate`, `mark_applied`,
+`readback`, `get_run`, `list_runs`, `provenance`, `drift`.
+
+## Layout
+- `vendor/` — vendored, MIT copies of the format libraries (CommonJS):
+  - `drp-format/` — `.drp` project authoring/editing + grade injection + structural diff
+  - `drt-format/` — `.drt` timeline authoring (delegates to drp-format)
+  - `drx-codec/` — per-clip DRX grade parse/generate, CDL export, node-tree/curves/qualifier/window codecs
+  - `drx-parameters/` — calibrated parameter ranges/ids consumed by drx-codec
+  - `conform-qc/` — the offline conform/relink QC engine
+- `server/` — the MCP server, tools, grading cores, and the DB-as-truth pipeline foundation
+- `test/` — offline unit suite (`npm test`); `.prettierrc.json` — formatting config
+- `package.json` — manifest; intentionally CommonJS (no `"type": "module"`) so the vendored libs load
+  under the repo's `type: module` root.
+
+## Requirements & optional features
+
+The **core is pure-JS / MIT with zero required native modules or bundled binaries** — `drp`, `drt`,
+`drx` (incl. the grading catalog needs `sharp`, see below), `offline_ref`, `fusion`, `audio_plan`,
+`conform` (core), `color_trace`, `project_read`, `capabilities` all work out of the box, cloud or local.
+
+A few features need something the **user installs themselves** (call the `capabilities` tool for live
+status + install hints):
+
+| Feature | Needs | Why not bundled / Install |
+|---|---|---|
+| `audio` (split/trim/convert), conform frame ops | **ffmpeg + ffprobe on PATH** | FFmpeg binaries are **GPL** — bundling them would taint this MIT package. `brew install ffmpeg` / `apt install ffmpeg` / `choco install ffmpeg`. |
+| grading/QC catalog, `conform.verify` (frame compare) | `sharp` (optional) | native module; `npm i sharp` |
+| `pipeline` (project DB), `fairlight` live-DB path, conform lineage/reverse | `better-sqlite3` (optional) | native module; `npm i better-sqlite3`. (The `.drp`-zip Fairlight path needs none.) |
+| YAML authoring (`pipeline compile` from a YAML dir) | `js-yaml` (optional) | pure JS; `npm i js-yaml` |
+
+Missing features fail with a clear, actionable message rather than crashing; the server logs a one-line
+"needs setup" summary to stderr at startup.
+
+## Provenance & license
+Vendored libraries are clean offline format-interop and deterministic compute code: no secrets, no
+external service coupling, no network calls, no LLM dependency. Where a feature can take a second
+opinion from an AI (the conform engine's advisory `VisionValidator`), it does so only through a
+host-injected adapter — the engine ships the interface and a deterministic fake, never a concrete
+LLM client. Licensed **MIT** under this repo's root `LICENSE` (Copyright DaVinci Resolve MCP
+Contributors and Bradford Operations LLC).
+
+> The bundled `vendor/drp-format/templates/media-clip-h264.drp` uses a neutral synthetic source
+> (`/Media/sample.mp4`) — scrubbed of any personal path / third-party clip reference.
+
+DRX write paths were calibrated live against DaVinci Resolve 19 Studio (2026-07): primaries use one
+unified `space: 'ui' | 'drx'` value-space flag (panel units by default), and the structural writes —
+power windows (circle/linear/gradient + polygon/curve vertex shapes), HSL/RGB/luma qualifiers, HDR
+zones, ColorSlice globals, blur/key/motion-effects palettes, sat/lum-axis HSL curves, and hue-axis
+HSL curves (single- **and** multi-band, via a canonical bezier-cage emitter that replicates Resolve's
+own serialization; edge-on-band-slot geometry passes through raw) — are panel-readback-verified.
+OFX/ResolveFX plugin params are read AND write verified (params are self-describing
+on the wire; writes render-confirmed live — see the ResolveFX registry for the full
+plugin universe, measured ranges, and per-plugin enum vocabularies). HDR zone
+DEFINITIONS (custom Max Range/falloff), Motion Effects scales, and the tracker-data
+blob are decoded and (where applicable) write-verified. Still experimental to write:
+Color Warper on Resolve 19 (the pin-list wire format is R21's). Per-control status
+lives in `vendor/drx-parameters/CALIBRATION-STATUS.md` — capabilities are flagged
+honestly, not overclaimed.
+The grading catalog and pipeline foundation are unit-tested offline; their Resolve **apply** is the
+caller's job and is validated live separately.

package/resolve-advanced/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "davinci-resolve-advanced-mcp",
+  "version": "0.0.0-dev",
+  "private": true,
+  "license": "MIT",
+  "description": "Beyond-the-API DaVinci Resolve MCP — offline .drp/.drt/.drx authoring/editing. Sibling Node server to the Python davinci-resolve-mcp. Dev-local package.json; deps promote to the repo root at packaging.",
+  "comment_commonjs": "Intentionally NO \"type\": \"module\" — the vendored libs are CommonJS (require()). The repo root is type:module, so this nested manifest scopes resolve-advanced/**/*.js back to CommonJS.",
+  "comment_exports": "Public library surface so a downstream consumer can import the codec/grading/pipeline API, not just spawn the MCP bin. `.` = the lib barrel; `./mcp` = the stdio server entry. Still private:true — publish name/registry + un-privating are a parked decision.",
+  "main": "./server/lib.mjs",
+  "exports": {
+    ".": "./server/lib.mjs",
+    "./mcp": "./server/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "server/**/*.mjs",
+    "vendor/**",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "adm-zip": "^0.5.16",
+    "fast-xml-parser": "^5.7.3",
+    "fzstd": "^0.1.1",
+    "jszip": "^3.10.1",
+    "uuid": "^9.0.0",
+    "zod": "^3.25.76",
+    "zstd-codec": "^0.1.5"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.10.0",
+    "js-yaml": "^4.3.0",
+    "pg": "^8.22.0",
+    "sharp": "^0.33.0"
+  },
+  "peerDependenciesMeta": {
+    "_comment": "audio (split/trim/convert) + conform frame ops need system ffmpeg/ffprobe on PATH (NOT bundled — FFmpeg binaries are GPL; this package stays MIT). Install ffmpeg yourself: brew install ffmpeg."
+  },
+  "scripts": {
+    "test": "node --test vendor/drp-format/__tests__/ vendor/drt-format/__tests__/ vendor/drx-codec/__tests__/ test/",
+    "test:libs": "node --test vendor/drp-format/__tests__/ vendor/drt-format/__tests__/ vendor/drx-codec/__tests__/",
+    "test:server": "node --test test/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "prettier": "^3.9.4"
+  }
+}