davinci-resolve-mcp 2.23.0

package/AGENTS.md

@@ -0,0 +1,85 @@
+# DaVinci Resolve MCP Server — Agent Instructions
+
+This is the canonical short operating brief for AI coding agents working in this
+repository. Keep it durable: do not duplicate version numbers, tool counts,
+kernel-action counts, release notes, or long reference tables here.
+
+## Non-Negotiable Source Media Safety
+
+Never modify, transcode, convert, proxy, relink, replace, or create derivatives
+of source media unless the user explicitly asks for that exact operation.
+
+Analysis workflows may read source media, but outputs must go to sidecar files,
+session scratch space, or the configured `davinci-resolve-mcp-analysis` project
+root. Preserve the chain from camera original to final delivery.
+
+See `docs/guides/media-analysis-guide.md` for the full source-safe workflow.
+
+## Frame-Referenced Color Work
+
+Before applying a grade, look, shot match, LUT, CDL, DRX, or copied grade to an
+existing Resolve timeline, inspect representative Resolve-rendered frames for
+the target shot or shots. Use thumbnails, contact sheets, Gallery stills, marker
+frames, or visual analysis reports written only to scratch/analysis locations.
+When the API can safely provide them, compare matched untreated/bypass, current,
+and after frames at the same timecodes; restore the previous active version or
+node-enabled state after any temporary bypass capture.
+
+Do not grade only from clip metadata, graph availability, or a requested style
+label unless the user explicitly asks for a blind/global pass. Preserve or create
+a recoverable grade version, and report which frame references informed the
+change. Do not describe Resolve's default one-node graph as an existing creative
+grade unless active grade tools, LUTs, or other grade state are present.
+
+When the user asks to build on or adjust an existing grade, treat the current
+grade as creative work to preserve. Inspect the active grade version and node
+graph first, create or switch to a recoverable adjustment version, and make
+incremental changes only through supported controls. Do not reset grades, replace
+graphs, or apply whole-grade artifacts unless the user explicitly asks for that
+semantics.
+
+## Source Of Truth
+
+- Public overview, current stats, and docs map: `README.md`
+- Historical release notes: `CHANGELOG.md`
+- AI assistant operating reference: `docs/SKILL.md`
+- Release checklist and validation rules: `docs/process/release-process.md`
+- Kernel workflow support maps: `docs/kernels/`
+- API coverage and live-test status: `docs/reference/api-coverage.md`
+- Bundled Resolve API text: `docs/reference/resolve_scripting_api.txt`
+
+## Key Paths
+
+- Compound server: `src/server.py`
+- Granular server entrypoint: `src/resolve_mcp_server.py`
+- Local control panel launcher: `src/control_panel.py`
+- Granular implementation: `src/granular/`
+- Utilities: `src/utils/`
+- Installer: `install.py`
+- Tests: `tests/`
+- Examples: `examples/`
+
+## Common Commands
+
+```bash
+python src/server.py
+python src/server.py --full
+venv/bin/python -m src.control_panel
+python install.py
+venv/bin/python tests/test_import.py
+venv/bin/python scripts/audit_api_parity.py
+```
+
+Python 3.10-3.12 is recommended for Resolve scripting compatibility.
+
+## Development Notes
+
+- Prefer the compound server unless a task specifically needs granular tools.
+- Use existing action-dispatch patterns and helper functions before adding new
+  abstractions.
+- All Resolve-facing temp or export paths should use the repo's safe path
+  helpers; do not invent ad hoc temp paths for files Resolve writes.
+- For changes touching Resolve behavior, update focused tests and follow the
+  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/`.