davinci-resolve-mcp 2.57.5 → 2.58.0

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/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.57.5"
+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.5",
+  "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"
+  }
+}

package/resolve-advanced/server/black-balance.mjs

@@ -0,0 +1,92 @@
+/**
+ * black_balance (P1d) — neutralize a SHADOW cast specifically. Where white_balance_match
+ * balances a mid/highlight neutral patch, this operates on the p1 shadow point ONLY: it aligns
+ * each channel's black point to a common target (the lowest channel black), removing a colour
+ * cast in the shadows WITHOUT lifting or crushing them (gain=1, offset-only).
+ *
+ * Emits an offset-only affine (reuse generateAssertedAffineDRX). Skips a clip whose shadows are
+ * already neutral (nothing to do — skip-not-fake). LOCAL & deterministic; no Resolve.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { generateAssertedAffineDRX } from './contrast-normalize.mjs';
+import { provenanceLabel, gist } from './node-provenance.mjs';
+
+const require = createRequire(import.meta.url);
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("black-balance needs the optional dep 'sharp'. Install: npm i sharp");
+  }
+}
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const idx = clamp(Math.round((p / 100) * (sorted.length - 1)), 0, sorted.length - 1);
+  return sorted[idx];
+}
+
+/** Per-channel black point (p1, 0..1). Returns {r,g,b} or null. */
+export async function measureBlackPoint(pngPath, opts = {}) {
+  const sharp = loadSharp();
+  const lowP = opts.lowPct ?? 1,
+    maxSide = opts.maxSide ?? 480;
+  let data, ch;
+  try {
+    const out = await sharp(pngPath).resize(maxSide, maxSide, { fit: 'inside', kernel: 'nearest' }).raw().toBuffer({ resolveWithObject: true });
+    data = out.data;
+    ch = out.info.channels;
+  } catch {
+    return null;
+  }
+  const R = [],
+    G = [],
+    B = [];
+  for (let i = 0; i < data.length; i += ch) {
+    R.push(data[i]);
+    G.push(data[i + 1]);
+    B.push(data[i + 2]);
+  }
+  if (!R.length) return null;
+  R.sort((a, b) => a - b);
+  G.sort((a, b) => a - b);
+  B.sort((a, b) => a - b);
+  return { r: percentile(R, lowP) / 255, g: percentile(G, lowP) / 255, b: percentile(B, lowP) / 255 };
+}
+
+/**
+ * @param {Array<{id, png, group?}>} clips
+ * @param {{outDir, castThreshold?:number, clampOffset?:[number,number]}} opts
+ */
+export async function computeBlackBalance(clips, opts = {}) {
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  fs.mkdirSync(opts.outDir, { recursive: true });
+  const castThreshold = opts.castThreshold ?? 0.004; // ~1/255 — below this the shadows are already neutral
+  const [olo, ohi] = opts.clampOffset || [-0.2, 0.2];
+
+  const grades = [];
+  const warnings = [];
+  const skipped = [];
+  const report = {};
+  for (const c of clips) {
+    const bp = await measureBlackPoint(c.png, opts);
+    if (!bp) {
+      skipped.push({ id: c.id, reason: 'unreadable frame' });
+      continue;
+    }
+    const target = Math.min(bp.r, bp.g, bp.b); // align to the lowest black — pull casts DOWN, don't lift
+    const spread = Math.max(bp.r, bp.g, bp.b) - target;
+    if (spread < castThreshold) {
+      skipped.push({ id: c.id, reason: 'shadows already neutral', castSpread: +spread.toFixed(4) });
+      continue;
+    }
+    const gain = { r: 1, g: 1, b: 1 };
+    const offset = { r: clamp(target - bp.r, olo, ohi), g: clamp(target - bp.g, olo, ohi), b: clamp(target - bp.b, olo, ohi) };
+    const drxPath = `${opts.outDir}/${c.id}_blackbal.drx`;
+    await generateAssertedAffineDRX(gain, offset, provenanceLabel('black_balance', { source: 'shadow-neutral', gist: gist('offset', offset) }), drxPath, warnings);
+    grades.push({ id: c.id, offset, castSpreadPct: +(100 * spread).toFixed(2), drxPath });
+    report[c.id] = { castSpreadPct: +(100 * spread).toFixed(2) };
+  }
+  return { grades, report, warnings, skipped };
+}