@hybridlabor-api/aos 4.3.0 → 4.4.0

package/mcps/davinci-resolve-mcp/docs/authoring/fuse-dctl-authoring.md

@@ -1,242 +0,0 @@
-# Fuse and DCTL Authoring Tools (Experimental)
-
-The `fuse_plugin` and `dctl` compound tools (introduced in v2.5.0) generate and
-install Fusion Fuse plugins and DCTL color-transform files. They are the first
-*authoring* tools in this MCP — every other tool wraps Resolve's scripting API,
-while these two write source files into Resolve's plugin/LUT directories.
-
-**Status: lifecycle-tested, runtime rendering still experimental.** The v2.16.0
-Extension Authoring kernel live-tested template generation, validation,
-install/read/list/remove, LUT refresh for regular DCTLs, and restart-required
-classification for Fuse and ACES DCTL surfaces. It does not prove every Fuse
-renders correctly after a restart or that every DCTL compiles on every GPU
-backend. Community feedback on runtime behavior is still welcome — please open
-an issue with the template kind, your Resolve version and platform, and any
-console output from Resolve's Workspace → Console.
-
-## What's covered
-
-### `fuse_plugin` — Fusion Fuse plugins
-
-Fuses are Lua plugins (or GLSL view-LUT shaders) that Fusion loads at startup.
-A new Fuse requires a Resolve restart to register; existing Fuses can be
-edited and reloaded from the Inspector's Edit/Reload buttons without a
-restart. The MCP cannot trigger reload — that's a UI-only action.
-
-Actions: `path`, `list`, `install`, `remove`, `read`, `validate`, `template`,
-`list_templates`.
-
-**18 template kinds**, grouped by purpose:
-
-| Group           | Kind                  | Type           | Lang        | Risk  |
-|-----------------|-----------------------|----------------|-------------|-------|
-| Color           | `color_matrix`        | `CT_Tool`      | Lua         | Low   |
-|                 | `per_pixel`           | `CT_Tool`      | Lua         | Low   |
-|                 | `channel_op`          | `CT_Tool`      | Lua         | Low   |
-| Geometric       | `transform`           | `CT_Tool`      | Lua         | Low   |
-|                 | `spatial_warp`        | `CT_Tool`      | Lua         | Med   |
-| Text & shapes   | `text_overlay`        | `CT_Tool`      | Lua         | Med   |
-|                 | `shape_generator`     | `CT_Tool`      | Lua         | Med   |
-| Source/temporal | `source_generator`    | `CT_Tool` (source) | Lua    | Med   |
-|                 | `time_displace`       | `CT_Tool`      | Lua         | Low   |
-| Filters         | `builtin_blur`        | `CT_Tool`      | Lua         | Low   |
-|                 | `builtin_resize`      | `CT_Tool`      | Lua         | Low   |
-|                 | `variable_blur`       | `CT_Tool`      | Lua (SAT)   | Med   |
-| Modifiers       | `modifier`            | `CT_Modifier`  | Lua         | High  |
-|                 | `point_modifier`      | `CT_Modifier`  | Lua         | High  |
-| Display/shaders | `view_lut`            | `CT_ViewLUTPlugin` | Lua + GLSL | Med |
-|                 | `dctl_kernel`         | `CT_Tool`      | Lua + DCTL  | High  |
-| Reference       | `controls_demo`       | `CT_Tool`      | Lua         | Low   |
-|                 | `notifychanged_demo`  | `CT_Tool`      | Lua         | Low   |
-
-Risk levels reflect how confident we are the template is correct based on the
-SDK reference and parser-level checks:
-
-- **Low** — directly mirrors a documented SDK example, simple Lua, no aux paths.
-- **Medium** — uses several documented APIs together (Shape system, sampling,
-  source-tool registration, GLSL parameter passing). Each API is documented
-  but the combination has more surface area to misalign on.
-- **High** — `CT_Modifier` is barely covered in the SDK; `dctl_kernel` exercises
-  GPU-compute integration (`DVIPComputeNode`, parameter blocks, samplers) that
-  isn't reachable by static checks.
-
-Install location:
-
-| Platform | Path |
-|---|---|
-| macOS   | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Support/Fusion/Fuses` |
-| Windows | `%PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Fuses` |
-| Linux   | `~/.local/share/DaVinciResolve/Fusion/Fuses` |
-
-### `dctl` — DCTL color-transform files
-
-Regular DCTLs live under Resolve's LUT directory and appear as LUT-style entries
-in the LUT browser, the Clip/Node LUT picker, and the ResolveFX DCTL plugin.
-After install, call `project_settings(action='refresh_luts')` to make Resolve
-discover the new file.
-
-ACES DCTLs (IDT/ODT) install to a separate ACES Transforms directory and are
-scanned **only at Resolve startup**. Install requires a Resolve restart.
-
-Actions: `path`, `list`, `install`, `remove`, `read`, `validate`, `template`,
-`list_templates`.
-
-**8 template kinds**:
-
-| Kind                | Entry point                | Category       | Notes                          |
-|---------------------|----------------------------|----------------|--------------------------------|
-| `transform`         | `__DEVICE__ float3 transform()` | `lut`     | Per-pixel, no alpha            |
-| `transform_alpha`   | `__DEVICE__ float4 transform()` | `lut`     | Resolve 19.1+; alpha mode tag  |
-| `transition`        | `__DEVICE__ float4 transition()` | `lut`    | Reads `TRANSITION_PROGRESS`    |
-| `matrix`            | `__DEVICE__ float3 transform()` | `lut`     | 3x3 color matrix as constants  |
-| `kernel`            | `__DEVICE__ float3 transform()` | `lut`     | Bare TODO stub                 |
-| `lut_apply`         | `__DEVICE__ float3 transform()` | `lut`     | Wraps an external `.cube` LUT  |
-| `aces_idt`          | `__DEVICE__ float3 transform()` | `aces_idt` | ACES Input Device Transform   |
-| `aces_odt`          | `__DEVICE__ float3 transform()` | `aces_odt` | ACES Output Device Transform  |
-
-The `template` action returns `suggested_category` so callers know which install
-path to use:
-
-```python
-gen = dctl('template', {'kind': 'aces_idt', 'name': 'MyIDT'})
-dctl('install', {'name': 'MyIDT', 'source': gen['source'],
-                 'category': gen['suggested_category']})
-```
-
-Install locations:
-
-| Category | macOS | Windows | Linux |
-|---|---|---|---|
-| `lut`      | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/LUT` | `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\LUT` | `~/.local/share/DaVinciResolve/LUT` |
-| `aces_idt` | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/ACES Transforms/IDT` | `%APPDATA%\…\ACES Transforms\IDT` | `~/.local/share/DaVinciResolve/ACES Transforms/IDT` |
-| `aces_odt` | …`/ACES Transforms/ODT` | …`\ACES Transforms\ODT` | …`/ACES Transforms/ODT` |
-
-Subdir support is available within any category for organization (e.g.
-`subdir='MCP'` puts a generated DCTL under `LUT/MCP/`).
-
-See `docs/notes/dctl-notes.md` for the full DCTL language reference, custom UI
-parameter syntax (`DCTLUI_SLIDER_FLOAT`, `DCTLUI_COLOR_PICKER`, etc.), and
-ACES parametric V1/V2 details.
-
-## What's been tested vs. what hasn't
-
-**Tested:**
-- All 18 Fuse templates pass `luac -p` (Lua 5.5) with default *and* varied
-  options
-- All 8 DCTL templates produce a valid entry-point signature
-- Filesystem round-trip (install → list → read → remove) for both tools across
-  all install categories (LUT, ACES IDT, ACES ODT)
-- Live v2.16.0 lifecycle probe confirmed generated Fuse install/read/list/remove,
-  regular DCTL install/read/list/refresh/remove, and ACES IDT
-  install/read/list/remove on Resolve Studio 20.3.2.9
-- `list_templates` enumeration for both tools
-- Path-traversal and name-regex rejection paths
-- Subdir handling with traversal guards (no `..`, no hidden dirs)
-- `view_lut` parameter types: `float`, `vec2`, `vec3_rgb`, `vec4_rgba`
-
-**Still not fully proven:**
-- Restarting Resolve and confirming every generated Fuse appears in the Fusion
-  tool list
-- Confirming every template renders correctly at runtime (e.g. does
-  `color_matrix` brightness actually shift values? does `text_overlay` draw
-  glyphs? does `point_modifier` drive a Merge Center input?)
-- The Modifier templates — `CT_Modifier` is barely covered in the Fuse SDK
-- The `dctl_kernel` Fuse — `DVIPComputeNode` runtime, sampler setup,
-  parameter struct memory layout
-- GLSL `view_lut` shader compilation (we only check braces and the
-  `ShadePixel` substring; `glslangValidator` would be needed for full GLSL
-  parsing)
-- Every DCTL template compiling on every Resolve GPU backend (Metal/CUDA/OpenCL
-  each have edge cases)
-- `variable_blur` SAT-based pattern — `UseSAT()`/`SampleAreaW()`/`RecycleSAT()`
-  are documented but unverified in this combination
-- `source_generator` `CT_SourceTool` registration — the `REG_Source_*Ctrls`
-  attributes mirror the SDK example but the global `Width`/`Height`/`Scale`/
-  `XAspect`/`YAspect` variables we reference are inferred, not documented
-- `controls_demo` and `notifychanged_demo` — Inspector layout and dynamic
-  show/hide behavior
-
-## Reporting feedback
-
-If a template fails to load, render incorrectly, or produces a Resolve
-console error, please open an issue at
-<https://github.com/samuelgursky/davinci-resolve-mcp/issues> with:
-
-- Template kind (e.g. `text_overlay`, `dctl_kernel`)
-- DaVinci Resolve version and platform
-- The exact MCP call you made (action, name, options)
-- Any console output from Workspace → Console (for Fuses) or the build-error
-  dialog (for DCTLs)
-- Whether the bug reproduces with default options or only with custom ones
-
-A short manual-smoke-test recipe for the highest-risk templates lives at the
-end of this document.
-
-## Manual smoke test
-
-For maintainers who want to live-test before merging template changes.
-
-```bash
-# Install the highest-risk Fuses
-venv/bin/python <<'EOF'
-import sys
-sys.modules['DaVinciResolveScript'] = type(sys)('DaVinciResolveScript')
-from src.server import fuse_plugin
-for kind in ('text_overlay', 'dctl_kernel', 'point_modifier', 'variable_blur'):
-    name = 'McpSmoke' + kind.replace('_', '').title()
-    src = fuse_plugin('template', {'kind': kind, 'name': name})['source']
-    print(fuse_plugin('install', {'name': name, 'source': src, 'overwrite': True}))
-EOF
-
-# Quit and relaunch Resolve, then in the Fusion page:
-#   Effects Library → Tools → Fuses → MCP → McpSmokeTextoverlay
-#   Effects Library → Tools → Fuses → MCP → McpSmokeDctlkernel
-#   Effects Library → Tools → Fuses → MCP → McpSmokeVariableblur
-# Drop each onto a node graph between MediaIn1 and MediaOut1.
-# For McpSmokePointmodifier: right-click any Point input (e.g. Merge Center)
-# in any tool → Modify with → MCP → McpSmokePointmodifier.
-# Verify Inspector controls work and the image responds.
-```
-
-For the DCTL side:
-
-```bash
-venv/bin/python <<'EOF'
-import sys
-sys.modules['DaVinciResolveScript'] = type(sys)('DaVinciResolveScript')
-from src.server import dctl
-# Regular DCTL — refresh-luts to pick up
-gen = dctl('template', {'kind': 'lut_apply', 'name': 'McpSmokeLut'})
-dctl('install', {'name': 'McpSmokeLut', 'source': gen['source'],
-                 'subdir': 'MCP', 'overwrite': True})
-# ACES IDT — restart Resolve to pick up
-gen = dctl('template', {'kind': 'aces_idt', 'name': 'McpSmokeIdt'})
-dctl('install', {'name': 'McpSmokeIdt', 'source': gen['source'],
-                 'category': gen['suggested_category'], 'overwrite': True})
-EOF
-# Then: project_settings(action='refresh_luts') in your MCP client for the
-# regular one; restart Resolve for the ACES IDT.
-```
-
-Cleanup:
-
-```bash
-venv/bin/python -c "
-import sys
-sys.modules['DaVinciResolveScript'] = type(sys)('DaVinciResolveScript')
-from src.server import fuse_plugin, dctl
-for n in ('McpSmokeTextoverlay', 'McpSmokeDctlkernel',
-          'McpSmokePointmodifier', 'McpSmokeVariableblur'):
-    print(fuse_plugin('remove', {'name': n}))
-print(dctl('remove', {'name': 'McpSmokeLut', 'subdir': 'MCP'}))
-print(dctl('remove', {'name': 'McpSmokeIdt', 'category': 'aces_idt'}))
-"
-```
-
-## Source media integrity
-
-These tools write into Resolve's plugin and LUT directories. They do not
-touch source media. Effects authored with these tools modify Resolve's
-grade/render pipeline, not the original camera files. Do not bake template
-effects into source media, create rendered derivatives, or export/reimport
-processed media unless the user explicitly asks for that workflow.

package/mcps/davinci-resolve-mcp/docs/authoring/script-plugin-authoring.md

@@ -1,195 +0,0 @@
-# Script Plugin Authoring & Conversational Resolve Scripting
-
-The `script_plugin` compound tool (introduced in v2.5.0) generates, installs,
-and **executes** Resolve-page Lua/Python scripts. It closes the conversational
-loop: an LLM with access to the MCP can describe a workflow, generate the
-script, install it as a Resolve menu item, and execute it — all in one turn —
-with the script's stdout streamed back into the conversation.
-
-Unlike `fuse_plugin` (which authors Fusion image-processing tools) and `dctl`
-(which authors color-page shaders), `script_plugin` targets the
-**Workspace → Scripts** menu — the user-facing surface for general Resolve
-automation.
-
-## When to use what
-
-| Goal | Use |
-|---|---|
-| One-off conversational query against Resolve | `script_plugin('run_inline', ...)` |
-| Custom workflow you want as a permanent menu item | `script_plugin('install', ...)` then `('execute', ...)` |
-| Image-processing node for the Fusion page | `fuse_plugin` |
-| Color-page programmable transform | `dctl` |
-| Anything the existing 28 wrapped Resolve API tools already cover | The wrapped tool — no scripting needed |
-
-## Two template kinds
-
-### `scaffold`
-Minimal stub. Connects to Resolve, gets `resolve` / `project` / `mp` /
-`timeline` handles, defines an empty `main()`. For when the LLM wants to
-write everything from scratch.
-
-### `media_rules`
-The rules-and-variables DSL. Generates a self-contained script with three
-top sections (VARIABLES, ENGINE GLOBALS, RULES) followed by an embedded
-~300-line engine that interprets the rules. The LLM (or user) edits the
-RULES table; the engine handles execution.
-
-**Rules** are dicts with shape:
-```lua
-{
-    name    = "rule description",
-    target  = "media_pool_clips",  -- scope
-    extract = {                     -- pull values from each item
-        { source = "file_path", pattern = "DATE_PATTERN",
-          into = {"yr", "mo", "dy"} },
-    },
-    apply = {                       -- side effects driven by the captures
-        { type = "set_metadata", field = "Shoot Date",
-          value = "{yr}-{mo}-{dy}" },
-    },
-    condition = function(vars) return ... end,  -- optional
-    enabled = true,                              -- optional
-    stop_on_match = false,                       -- optional
-}
-```
-
-## DSL coverage
-
-### Sources (where data comes from)
-`file_path`, `filename`, `dirname`, `parent_dir`, `grandparent_dir`,
-`file_extension`, `path_segment:N`, `clip_property:<Field>`,
-`metadata:<Field>`, `embedded_metadata:<Field>`, `camera_metadata:<Field>`,
-`previous_capture:<rule_id>`, `static_value`, `bin_name`, `media_pool_path`,
-`clip_duration`, `clip_resolution`, `frame_rate`, `codec`, `audio_channels`,
-`audio_format`, `start_tc`, `end_tc`, `creation_time`, `modification_time`,
-`external_data:<column>` (loaded from CSV/JSON).
-
-### Actions (what to do)
-`set_metadata`, `set_clip_property`, `rename_clip`, `move_to_bin`,
-`set_clip_color`, `flag_clip`, `add_keyword`, `add_marker`, `apply_lut`,
-`set_in_out`, `tag_for_review`, `notify` / `print`.
-
-### Targets (scope)
-`media_pool_clips`, `current_bin_clips`, `bin_path:<path>`,
-`selected_clips`, `timeline_items`, `selected_timeline_items`,
-`unmatched_clips`, `clips_matching:<predicate>`, `timeline_items_in_track:N`.
-
-### Transforms (variable pipes)
-Plain substitution `{var}`, plus pipes: `upper`, `lower`, `title`, `slug`,
-`pad(n, char)`, `lookup(table_name)`, `add(n)`, `sub(n)`, `mul(n)`, `div(n)`,
-`date(format)`. Chainable: `{var | upper | slug}`.
-
-### Engine globals
-`DRY_RUN`, `LOG_LEVEL`, `LIMIT_TO_FIRST_N`, `EXTERNAL_DATA`,
-`BACKUP_BEFORE_RUN`.
-
-### External data (the killer feature)
-`EXTERNAL_DATA = { csv = "/path/to/sheet.csv", match_on = {...} }` lets
-rules reference any column in a spreadsheet via `external_data:<column>`.
-Match strategies: `exact`, `regex`, `fuzzy` (Levenshtein nearest match —
-useful for filename variations).
-
-Real-world example: a script supervisor's CSV with Filename, Scene, Take,
-Camera, Lens columns. Single rule maps each clip to its row and populates
-all metadata fields plus organizes into Scene bins. Six lines of RULES.
-
-## Conversational execution: `run_inline` and `execute`
-
-The two actions that close the loop:
-
-### `run_inline(source, language, timeout?)`
-Run an ad-hoc Lua or Python snippet inside Resolve, get stdout + return
-value back. No file persistence.
-
-**Python**: writes source to a temp file with `resolve`/`project`/`mp`/
-`timeline` pre-bound, runs as subprocess, captures stdout/stderr.
-
-**Lua**: wraps source so `print()` is intercepted into a buffer, runs via
-`fusion.RunScript()`, polls a completion sentinel, reads stdout + return
-value back via `app:SetData()`/`fusion.GetData()`. (Note: `fusion.Execute()`
-from the Python bridge is a no-op in Resolve 20.x — `RunScript()` against a
-file is the only working path. The implementation handles this.)
-
-Example:
-```python
-script_plugin('run_inline', {
-    'source': '''
-print(f"Project: {project.GetName()}")
-print(f"Bins: {len(mp.GetRootFolder().GetSubFolderList() or [])}")
-''',
-    'language': 'py',
-})
-# → {success: True, stdout: "Project: My Show\nBins: 12\n", exit_code: 0}
-```
-
-### `execute(name, category, language, args?, timeout?)`
-Run an installed script. Same return shape as `run_inline`.
-
-**Python**: subprocess captures full stdout/stderr.
-**Lua**: `fusion.RunScript()`; print() output goes to Resolve Console
-(can't capture). For Lua scripts that need to return data, have them write
-to `app:SetData()` and the caller reads via the existing `fusion_comp`
-tooling.
-
-## Install paths
-
-Resolve scans these subdirs for the **Workspace → Scripts → \<category\>** menu:
-
-| Platform | Root |
-|---|---|
-| macOS | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/<category>/` |
-| Windows | `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Scripts\<category>\` |
-| Linux | `~/.local/share/DaVinciResolve/Fusion/Scripts/<category>/` |
-
-Categories: `Edit`, `Color`, `Deliver`, `Comp`, `Tool`, `Utility`, `Views`.
-`Utility` shows up everywhere; the others only on the matching page.
-
-Resolve picks up new scripts **without a restart** — the menu refreshes each
-time it's opened.
-
-## Languages
-
-Both Lua and Python are first-class. Lua is Fusion-native; Python is more
-familiar for data-heavy workflows. The same RULES table syntax works in both
-(Lua tables vs. Python dicts).
-
-## Live verification
-
-Verified on DaVinci Resolve Studio 20.3.2.9, macOS:
-
-- ✅ Scripts appear in Workspace → Scripts → \<category\> after install (no restart needed)
-- ⚠️ Installed Lua script execution via `fusion.RunScript(path)` can return
-  `False` from the Python bridge even when install/read/list/remove work. Use
-  `run_inline(language="lua")` when captured output or return values matter.
-- ✅ Python scripts execute via subprocess with full stdout/stderr capture
-- ✅ `run_inline` Lua: stdout captured (with tabs), return value captured, errors trapped with line numbers
-- ✅ `run_inline` Python: full Resolve API access, project + media-pool + timeline pre-bound
-- ✅ Both engines (Lua and Python) compile without errors
-- ✅ DSL coverage tests confirm every documented source/action/target/transform/strategy is present in both engines
-
-## Implementation notes (for maintainers)
-
-Two non-obvious behaviors of Resolve's Lua bridge surfaced during live
-testing and are encoded in the implementation:
-
-1. **`fusion.Execute(luaSource)` is a no-op** when called from the Python
-   `DaVinciResolveScript` bridge in Resolve 20.x. It returns `None` and has
-   no observable side effects. Don't use it. Use `fusion.RunScript(filepath)`
-   against a temp file instead.
-
-2. **`fusion.RunScript()` is asynchronous.** It returns before the script
-   finishes. Reading `fusion.GetData()` immediately gives stale values. The
-   implementation polls a completion-sentinel slot (`__mcp_done__`) until
-   the wrapped Lua sets it to `"1"`, then reads results.
-
-These constraints are unique to the Lua side; Python's subprocess approach
-is straightforwardly synchronous.
-
-## Source media integrity
-
-These tools generate workflows that READ Resolve's media-pool and timeline
-state and WRITE metadata, bin organization, markers, and similar
-non-destructive properties. The DSL's actions do not modify source files
-on disk. If you build a custom action that exports media, transcodes, or
-otherwise creates derivatives, that's outside the engine's defaults — be
-explicit when authoring such rules.

package/mcps/davinci-resolve-mcp/docs/authoring/setting-files/README.md

@@ -1,152 +0,0 @@
-# Authoring DaVinci Resolve Custom Effects (`.setting` files)
-
-Guide and reference for hand-authoring DaVinci Resolve effects, transitions,
-titles, generators, and Fusion macros as `.setting` files — the serialized
-Fusion-composition format Resolve indexes from its Templates directory. No
-plugin SDK, no compile step. Start from a [template](templates/) and consult the
-[reference docs](#reference-docs) for the format and the hard-won gotchas.
-
-Use this when a task touches building a new effect, packaging a Fusion comp as a
-reusable template, making a title or transition preset, editing
-`InstanceInput`/`UserControls`, or the `.setting` file format, thumbnail
-conventions, or the Fusion Templates install directory.
-
-## What a `.setting` file actually is
-
-A `.setting` file is a **Fusion composition serialized as a Lua table**. It is NOT a custom binary format — it's a readable, hand-editable text file. When Resolve loads it, Fusion instantiates every node described in the file; when the user drops the template onto a clip, Fusion wires the clip into the node graph using the `MainInput*` hooks declared at the top of the file.
-
-Everything you need to build a custom Resolve effect lives in that single text file plus a handful of PNG thumbnails that sit next to it. No plugin SDK, no code signing, no compile step.
-
-## The Five Categories You Can Ship
-
-There are five roles a `.setting` file can play. Each hooks into a different part of the Resolve UI and has different wiring requirements:
-
-| Role | Location (user install) | MainInputs | MainOutputs | Typical top-level node |
-|------|-------------------------|-----------|-------------|------------------------|
-| **Edit Effect** (clip filter) | `Templates/Edit/Effects/` | `MainInput1` → source clip | `MainOutput1` → result | GroupOperator |
-| **Edit Transition** | `Templates/Edit/Transitions/` | `MainInput1` (Background) + `MainInput2` (Foreground) | `MainOutput1` | GroupOperator |
-| **Edit Title** | `Templates/Edit/Titles/` | *(none — generates)* | `MainOutput1` | GroupOperator wrapping TextPlus |
-| **Edit Generator** | `Templates/Edit/Generators/` | *(none — generates)* | `MainOutput1` | GroupOperator or raw node |
-| **Fusion Macro** (Tools / Backgrounds / Generators / Particles / Shaders / Styled Text / Motion Graphics / Lens Flares / How To) | `Templates/Fusion/<subfolder>/` | Optional — whatever makes sense for that node type | Optional | GroupOperator OR raw tool(s) |
-
-**Fusion/Looks is different — it is NOT a `.setting` file.** Looks are `.alut3` files (plain-text 3D LUTs with an `F5LT3` header). They apply via the Color page, not Fusion. Don't confuse them with the composition-based categories.
-
-## Install Paths
-
-User-installed templates go here (create any missing subfolders):
-
-- **Windows**: `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Templates\<role>\<category>\`
-- **macOS (user)**: `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Templates/<role>/<category>/`
-- **macOS (system-wide)**: `/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Templates/<role>/<category>/`
-
-`<role>` is literally `Edit` or `Fusion`. `<category>` mirrors the folders you see in the effects library (`Effects`, `Transitions`, `Titles`, `Generators`, `Tools`, `Backgrounds`, etc.). Restart Resolve after dropping new files in; they get indexed at launch.
-
-**The `<category>` subfolder is not optional.** A file at `Templates/Edit/MyEffect.setting` (loose in `Edit/`, no category folder) is invisible to the Edit page — it falls through to the Fusion-page library instead, which silently indexes anything under `Templates/`. Always write the full path including the category: `Templates/Edit/Effects/MyEffect.setting`. Same rule applies to Fusion macros (`Fusion/Tools/`, not loose in `Fusion/`). See gotcha 18.
-
-## Anatomy of a `.setting` File
-
-The outermost structure is always a table containing a `Tools` list and (optionally) an `ActiveTool` pointer:
-
-```lua
-{
-    Tools = ordered() {
-        MyEffect = GroupOperator {
-            Inputs = ordered() { ... exposed controls ... },
-            Outputs = { MainOutput1 = InstanceOutput { ... } },
-            Tools = ordered() { ... the internal node graph ... }
-        }
-    },
-    ActiveTool = "MyEffect"
-}
-```
-
-- `ordered() { ... }` preserves the order of keys (regular `{}` tables do not). Use it anywhere the order matters — the `Inputs` list drives the display order of controls in the inspector.
-- `MyEffect` is the internal tool ID. It must be a valid identifier (letters/digits/underscore) and match `ActiveTool`.
-- The **outer** `Tools` list is the top level of the composition; the **inner** `Tools` list inside the GroupOperator is the macro's internal graph.
-
-Inside the GroupOperator you have three sections:
-
-1. **`Inputs = ordered() { ... }`** — the controls the user sees in the inspector. Each entry is an `InstanceInput` that re-exposes one parameter of one internal node. `MainInput1` / `MainInput2` are reserved for clip wiring.
-2. **`Outputs = { ... }`** — what the rest of the pipeline sees. `MainOutput1` is the pixel output Resolve reads.
-3. **`Tools = ordered() { ... }`** — the actual internal nodes (Blur, Merge, Background, ofx.*, TextPlus, etc.) with their parameters and connections between each other via `SourceOp` / `Source`.
-
-## Wiring Rules That Matter
-
-- **`SourceOp = "NodeName"`, `Source = "OutputName"`** is how you connect nodes. The referenced node must exist in the same `Tools` list. Outputs are typed — image tools use `"Output"`, mask tools use `"Mask"`, value nodes use `"Value"`, text outputs `"Result"`.
-- **`MainInput1`'s `Source` must be the node input Resolve should feed the clip into.** On effects, that's typically `"Input"` on the first node. On transitions, `MainInput1` and `MainInput2` both point at a `Merge` or `Dissolve` node's `Background` / `Foreground`.
-- **Transition progress is automatic** — don't try to wire a "progress" parameter. The idiom is: drive your transition with a `Dissolve` node whose `Mix` is sourced from an `AnimCurves = LUTLookup` using `Curve = FuID { "Easing" }`. Fusion evaluates that curve across the clip length and you get a free 0→1 ramp shaped by the easing you chose.
-- **Titles use `KeyStretcher`** to make their internal animation stretch to fit the clip length. Wrap your animated `TextPlus` output with a `KeyStretcher` and output that from `MainOutput1`.
-- **Generators / Backgrounds have no MainInput** — they're pure sources. Just expose the interesting params and point `MainOutput1` at the terminal node.
-
-## Exposing Controls
-
-Every user-visible control in the inspector is an `InstanceInput` that re-publishes an input of one of your internal nodes. Pattern:
-
-```lua
-Intensity = InstanceInput {
-    SourceOp = "PrismBlur1",       -- the internal node
-    Source   = "AberrationStrength", -- its parameter
-    Name     = "Aberration",       -- label in the inspector (optional — defaults to Source)
-    Default  = 0.4,                -- initial value
-    MinScale = 0,                  -- soft slider minimum
-    MaxScale = 1,                  -- soft slider maximum
-    Page     = "Controls",         -- which inspector tab this sits on
-    ControlGroup = 4,              -- group with other inputs sharing this number (colors, etc.)
-    Width    = 0.5,                -- horizontal width fraction (0-1) for side-by-side layouts
-},
-```
-
-See `references/controls.md` for the complete control-attribute catalog, how `ControlGroup` collapses R/G/B/A into a single color picker, and how to add **new** controls (buttons, checkboxes, labels) that aren't tied to an existing node input using `UserControls`.
-
-## Thumbnails
-
-Each `.setting` ships with a bundle of PNG thumbnails named after the `.setting` file. Thumbnail shape depends on the category:
-
-| Category | Files you need |
-|----------|---------------|
-| Edit/Effects, Generators, Fusion/Tools, Backgrounds, Generators, Particles, Shaders, Lens Flares, Motion Graphics, How To, Styled Text | `Name.large.png` (128×128), `Name.large@2x.png` (256×256), `Name.small.png` (30×30), `Name.small@2x.png`, plus `.small.active/hover/push` button-state variants |
-| Edit/Transitions | `Name.small.*` suite (30×30) + `Name.wide.png` (52×29) + `@2x` versions |
-| Edit/Titles | `Name.wide.png` (52×29) + `Name.wide@2x.png` (104×58) — no `.large` or `.small` |
-
-Resolve will render a missing thumbnail from a generic placeholder (`_default.png` exists as a fallback in some stock folders). You can ship with only `.large.png` + `@2x` for a quick-and-dirty effect; the inspector degrades gracefully. See `references/thumbnails.md` for the exhaustive list.
-
-## The Five-Minute Recipe
-
-1. **Decide the role.** Effect / Transition / Title / Generator / Fusion macro. This sets your MainInputs, template file, and install path.
-2. **Prototype the node graph in Fusion first.** Open Resolve → Fusion page → build your composition → select your nodes → right-click → **Macro → Create Macro…**. Save it. That gives you a working `.setting` file with the outer structure correct. 99% of real-world authoring starts from a working Fusion comp, not from a blank text editor.
-3. **Open the resulting `.setting` file** in a text editor and rename / reorder / prune the `Inputs` list until the inspector shows only the controls you want, in the order you want.
-4. **Set `Default`, `MinScale`, `MaxScale`, `Name`, `Page`, `ControlGroup`, `Width`** on each `InstanceInput` to tune presentation.
-5. **Drop it into the correct Templates subfolder**, add thumbnails alongside, restart Resolve, and test from the Effects Library.
-
-Templates for each category live in `templates/`. Copy one and modify.
-
-## When NOT to Use This Skill
-
-- **OFX plugins.** Those are compiled C++ shared libraries — completely separate system, not `.setting` files.
-- **Color grade LUTs.** `.cube` / `.3dl` / `.alut3` files go in the LUT directory and apply from the Color page. Don't confuse `Fusion/Looks/*.alut3` with custom effects.
-- **Project-wide scripting.** If you want to *drive* Resolve (build timelines, apply grades, queue renders), use this server's MCP tools (see [docs/SKILL.md](../../SKILL.md)) — not a custom template.
-
-## Reference Docs
-
-| File | What's in it |
-|------|-------------|
-| `references/format.md` | Full `.setting` Lua-table syntax: `ordered()`, `Input`, `FuID`, `BezierSpline`, `LUTLookup`, `GroupOperator`, `InstanceOutput`, `CustomData`, `UserControls` shape |
-| `references/controls.md` | Every `InstanceInput` attribute + `UserControls` control types (SliderControl, ButtonControl, CheckboxControl, LabelControl, MultiButtonControl) with examples |
-| `references/category-patterns.md` | Side-by-side minimal skeletons for Effect vs Transition vs Title vs Generator vs Fusion macro — shows what's different about each |
-| `references/thumbnails.md` | Exact filename grid, dimensions, which files are required vs optional per category |
-| `references/gotchas.md` | Hard-won rules: transition progress curves, `KeyStretcher` on titles, what breaks when you rename `ActiveTool`, SourceOp name collisions, the difference between `Inputs = {}` (unordered) and `Inputs = ordered() {}` |
-| `templates/MCP Test Blur.setting` | Minimal clip-filter effect — one Blur exposed as "Strength" (Edit / Effects) |
-| `templates/MCP Test Vignette.setting` | Ellipse-mask vignette darkening the edges — exercises mask-feeding + Merge.Blend (Edit / Effects) |
-| `templates/MCP Test Color Tint.setting` | Tint via colored Background → Merge, with `ControlGroup` collapsing R/G/B/A into a single color picker (Edit / Effects) |
-| `templates/MCP Test Wipe.setting` | Gradient-map luma wipe transition with an easing curve (Edit / Transitions) |
-| `templates/MCP Test Iris.setting` | Circular iris transition using an EllipseMask as the Dissolve.Map (Edit / Transitions) |
-| `templates/MCP Test Cross Dissolve.setting` | Dead-simplest transition — `DFTDissolve` with no Map, just a Mix ramp (Edit / Transitions) |
-| `templates/MCP Test Title.setting` | Minimal TextPlus title with Color/Size/Position controls (Edit / Titles) |
-| `templates/MCP Test Lower Third.setting` | TextPlus + RectangleMask-bordered Background composite — exercises multi-node title composition (Edit / Titles) |
-| `templates/MCP Test Fade Title.setting` | TextPlus with animated alpha via a `BezierSpline`, stretched by `KeyStretcher` (Edit / Titles) |
-| `templates/MCP Test Noise.setting` | FastNoise generator with Detail/Contrast/Scale/Speed controls (Edit / Generators) |
-| `templates/MCP Test Solid Color.setting` | Solid-color Background with `ControlGroup` color picker (Edit / Generators) |
-| `templates/MCP Test Gradient.setting` | Linear gradient Background with exposed Start/End points and Gradient colors widget (Edit / Generators) |
-| `templates/MCP Test Glow.setting` | Minimal Fusion-page tool with MainInput + one control (Fusion / Tools) |
-
-**Start from a template.** Copying `templates/MCP Test Blur.setting` and renaming it is ~10x faster than writing one from scratch and the result will always be well-formed. The filenames match what shows up in Resolve's Effects Library, so renaming the copy is all you need to do to change the display name.