@kolbo/mcp 1.91.4 → 1.93.1

package/README.md

@@ -264,7 +264,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `blender_get_command_status` | Read bounded command status/result/error plus absolute `expires_at`; records and idempotency claims expire after 24 hours, and `awaiting_approval` means stop and wait for the user |
 
 **Premiere Pro & After Effects Bridge**
-Requires the Kolbo Studio panel open in Premiere Pro or After Effects with **AI agents** switched on in its header. Every edit is approved by the editor inside the panel; there is no raw ExtendScript tool.
+Requires the Kolbo Studio panel open in Premiere Pro or After Effects with **AI agents** switched on in its header. Every edit is approved by the editor inside the panel; scripts are shown in full before they run.
 
 | Tool | Description |
 |------|-------------|
@@ -275,8 +275,25 @@ Requires the Kolbo Studio panel open in Premiere Pro or After Effects with **AI
 | `adobe_place_on_timeline` | Import and place one Kolbo media item at the playhead of the work sequence / active comp (no time or track control in v1) |
 | `adobe_create_sequence` | Create and open a Premiere Pro sequence matching the open sequence's settings, no dialog (Premiere only) |
 | `adobe_import_captions` | Import a Kolbo-hosted SRT onto the active Premiere sequence (Premiere only) |
+| `adobe_edit_composition` | After Effects: one undo step of structured edits - comps, timed and trimmed Kolbo media, titles with stroke, solids, transforms, keyframes, audio fades, layer deletion |
+| `adobe_run_script` | Approval-gated ExtendScript for real motion graphics (shape layers, trim paths, text animators, effects, expressions, cameras); the editor reviews the exact code |
+| `adobe_capture_frame` | Render a comp/sequence frame to the Kolbo library so the agent can check its work |
 | `adobe_get_command_status` | Read command status/result/error; `awaiting_approval` means stop and wait for the editor |
 
+**DaVinci Resolve Bridge**
+Requires DaVinci Resolve Studio with the Kolbo plugin open (Workspace → Workflow Integrations → Kolbo AI) and **AI agents** switched on in its header. Every edit is approved by the editor inside the plugin; scripts are shown in full before they run.
+
+| Tool | Description |
+|------|-------------|
+| `resolve_list_sessions` | List the caller's DaVinci Resolve windows connected through the Kolbo plugin |
+| `resolve_get_project` | Queue a read-only project inspection: timelines, frame rate, resolution, playhead (no approval) |
+| `resolve_get_timeline` | Queue a read-only inspection of the current timeline: clips per track with start/end, markers, playhead |
+| `resolve_import_media` | Import one Kolbo media id or Kolbo-owned HTTPS URL into the Kolbo.AI Media Pool bin |
+| `resolve_edit_timeline` | Structured edits: new timelines, timed and trimmed Kolbo clips on chosen tracks, transitions, audio fades, Fusion titles, markers, clip deletion |
+| `resolve_run_script` | Approval-gated JavaScript against Resolve's scripting API (colour, Fusion, render jobs); the editor reviews the exact code |
+| `resolve_capture_frame` | Export a timeline frame to the Kolbo library so the agent can check its work |
+| `resolve_get_command_status` | Read command status/result/error; `awaiting_approval` means stop and wait for the editor |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.91.4",
+  "version": "1.93.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@972d2b4, the single source of truth.
+This tree is mirrored from kolbo-code@b066208, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -102,7 +102,9 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Confirm **cost** or validate **resolution / aspect / duration** against model caps | `references/workflows/cost-and-validation.md` |
 | Hit an **auth / MCP / 429** issue | `references/workflows/troubleshooting.md` |
 | Inspect or change a connected **Blender** scene, render, import Kolbo media, or run approved Blender Python | `references/workflows/blender.md` |
-| Inspect or edit an open **Premiere Pro / After Effects** project — timeline, import Kolbo media, place clips, sequences, captions | `references/workflows/adobe.md` |
+| Inspect or edit an open **Premiere Pro / After Effects** project — timeline, Kolbo media, sequences, captions, After Effects edits and titles | `references/workflows/adobe.md` |
+| Build **motion graphics** in After Effects — shape layers, animated text, effects, expressions, logo reveals | `references/workflows/after-effects-motion.md` |
+| Edit, grade or render Kolbo media in **DaVinci Resolve** (Studio 21.1+, Blackmagic's MCP) | `references/workflows/davinci-resolve.md` |
 | Create or edit a saved **Video Editor** timeline, clips, trims, speed or captions | `references/workflows/video-editor.md` |
 
 Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/src/config/systemPrompt.js` — same battle-tuned rules that power Kolbo's web-app help widget. Keep parity (see `packages/opencode/CLAUDE.md` "MCP & Skill Sync Rule").
@@ -160,7 +162,7 @@ Font tools (when exposed by the installed MCP): `list_fonts`, `get_font`, `uploa
 | `create_review_asset` / `add_review_version` / `set_review_status` / `create_review_comment` / `reply_review_comment` / `resolve_review_comment` / `unresolve_review_comment` / `create_review_collection` / `create_review_share_link` / `revoke_review_share_link` / `get_review_storage_usage` (+ list/get/update/delete siblings) | **Kolbo Review** — Frame.io-style client review: asset = media + appended versions (new cut = `add_review_version`, never delete+recreate), timecoded comments per version, approve/request-changes status, guest share links (no Kolbo account; comment-only unless `canSetStatus`). 5GB review storage cap. See `workflows/review-collections.md`. |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 | `blender_list_sessions` / `blender_get_scene` / `blender_search_docs` / `blender_capture_viewport` / `blender_apply_operations` / `blender_import_media` / `blender_render` / `blender_undo` / `blender_file_operation` / `blender_execute_python` / `blender_get_command_status` | Connected Blender control through the Kolbo extension. Every tool crosses into an external desktop host; read `workflows/blender.md` before the first call. |
-| `adobe_list_sessions` / `adobe_get_project` / `adobe_get_timeline` / `adobe_import_media` / `adobe_place_on_timeline` / `adobe_create_sequence` / `adobe_import_captions` / `adobe_get_command_status` | Connected Premiere Pro / After Effects control through the Kolbo panel. Every edit needs the editor's approval in the panel; read `workflows/adobe.md` before the first call. |
+| `adobe_list_sessions` / `adobe_get_project` / `adobe_get_timeline` / `adobe_import_media` / `adobe_place_on_timeline` / `adobe_create_sequence` / `adobe_import_captions` / `adobe_edit_composition` / `adobe_run_script` / `adobe_capture_frame` / `adobe_get_command_status` | Connected Premiere Pro / After Effects control through the Kolbo panel. Every change needs the editor's approval in the panel; read `workflows/adobe.md` before the first call and `workflows/after-effects-motion.md` before any motion-graphics script. |
 
 ## ⚠️ Edit in place — never delete+recreate (HARD RULE — always on)
 

package/skill/references/workflows/adobe.md

@@ -1,41 +1,70 @@
 # Premiere Pro & After Effects Workflow
 
-Use these rules whenever the user wants an agent to inspect or edit an open Premiere Pro or After Effects project through Kolbo. The Kolbo panel inside the Adobe app is a separate desktop authority boundary: a Kolbo account is necessary, but the editor's approval inside the panel is the final gate for every edit.
+Use these rules whenever the user wants an agent to inspect, edit or animate an open Premiere Pro or After Effects project through Kolbo. The Kolbo panel inside the Adobe app is a separate desktop authority boundary: a Kolbo account is necessary, but the editor's approval inside the panel is the final gate for every change.
+
+For motion graphics in After Effects (shape layers, animated text, effects, expressions), also read `references/workflows/after-effects-motion.md` before writing any script.
 
 ## Connect and target safely
 
 1. Call `adobe_list_sessions` before the first Adobe action.
-2. If no session is listed, ask the user to open **Window → Extensions → Kolbo Studio** in Premiere Pro or After Effects, sign in, and click the **AI agents** (robot) button in the panel header until its dot turns green. Do not substitute any other Kolbo tool for the panel relay.
-3. If one session is active, `session_id` may be omitted. If several are active, show each session's `name` (Premiere Pro / After Effects), `adobe_version`, platform and id, and ask which to target. Never guess.
+2. If no session is listed, ask the user to open **Window → Extensions → Kolbo Studio** in Premiere Pro or After Effects and sign in. The **AI agents** switch in the panel header connects automatically when signed in; if its dot is not green, ask them to click it. The panel must be signed into the same Kolbo account as this connector - sessions are private per account.
+3. If one session is active, `session_id` may be omitted. If several are active, show each session's `name` (Premiere Pro / After Effects), `adobe_version` and id, and ask which to target. Never guess.
 4. Keep the chosen `session_id` on every later Adobe call in the task. Re-list after a disconnect or app restart; ids are process-scoped.
 
-There is no MCP logout tool. The editor disconnects from the panel header button.
-
-## Inspect before changing
-
-- Start with `adobe_get_project`, then `adobe_get_timeline` for the active Premiere sequence or After Effects composition. Both are read-only and run without approval.
-- Timeline responses are bounded; pass `max_clips` when you only need the first clips.
+There is no MCP logout tool. The editor turns agents off from the panel header.
 
 ## Command lifecycle and approval
 
 Every Adobe tool except `adobe_list_sessions` and `adobe_get_command_status` returns a **command record**, not the result. Poll `adobe_get_command_status` with its `command_id` until the status is terminal: `succeeded`, `failed`, `denied` or `canceled`.
 
-- `awaiting_approval` is not a polling state. Stop and tell the user to approve or deny the request in the Kolbo panel, then check once more after they answer.
-- `denied` is final. Do not retry the same edit with cosmetic changes; ask the user what they want instead.
-- "Allow for this session" lives only in the panel's memory and ends when the editor disconnects. Never tell the user it persists, and never ask them to enable it for you.
-- Pass a stable `idempotency_key` when a timeout may cause you to retry the same command. A new intent needs a new key.
+- Reads (`adobe_get_project`, `adobe_get_timeline`) run without approval. Everything else waits for **Allow once / Allow for this session / Deny** in the panel.
+- `awaiting_approval` is not a polling state. Tell the user to approve or deny in the Kolbo panel, then check once more after they answer.
+- `denied` is final. Do not retry the same change with cosmetic edits; ask the user what they want instead.
+- "Allow for this session" lives only in the panel's memory and ends on disconnect. Never tell the user it persists and never ask them to enable it for you.
+- Pass a stable `idempotency_key` when a timeout may make you retry the same command. A new intent needs a new key.
+
+## Choosing the right tool
+
+| Goal | Tool |
+|---|---|
+| See the project / active sequence or comp (tracks, clips with start/end, playhead; or comp layers) | `adobe_get_project`, `adobe_get_timeline` |
+| Put a Kolbo clip in the bin, or at the Premiere playhead | `adobe_import_media`, `adobe_place_on_timeline` |
+| New Premiere sequence (no dialog, copies the open sequence's settings) | `adobe_create_sequence` |
+| Captions onto the active Premiere sequence | `transcribe_audio` → `adobe_import_captions` with the `.srt` URL |
+| After Effects edit: comps, timed/trimmed clips, titles, solids, fades, keyframes, music | `adobe_edit_composition` |
+| After Effects motion graphics beyond those operations | `adobe_run_script` (read `after-effects-motion.md`) |
+| Check what it actually looks like | `adobe_capture_frame` → look at the returned `url` |
+
+Prefer `adobe_edit_composition` whenever its operations are enough: it is validated, one undo step, and easier for the editor to approve than code.
+
+## After Effects composition edits (`adobe_edit_composition`)
+
+- One call applies up to 100 operations in order as **one undo step**. It stops at the first failing operation; earlier operations stay applied. Read the error, fix that operation, and continue from there - do not replay the whole batch.
+- Start a new piece with `comp.create` (defaults 1920×1080, 30 fps). Later operations in the same batch target it.
+- Times are **seconds on the composition timeline**. For media: `start_seconds` = where it begins, `trim_start_seconds` = seconds skipped at the head of the source, `duration_seconds` = visible length.
+- Crossfade = overlap two shots by 0.3–1 s and animate the upper shot's opacity 0 → 100 across the overlap. New layers stack on top, so add the later shot after the earlier one.
+- **Name every layer you will address later** and use that exact name in `layer.update` / `layer.animate`. Indexes shift as layers are added (1 = top).
+- `fit: "cover"` fills the frame (default), `"contain"` letterboxes, `"none"` keeps source size. Keyframed `scale` values are absolute percentages, so animate scale on titles and solids, not on fitted media, unless you first read the fitted scale from `adobe_get_timeline`.
+- Titles default to Arial Bold, white, centred. Add `stroke_width` 3–6 (black stroke) whenever text sits over bright or busy footage - white text on a light shot is invisible.
+- Music: add audio with `layer.add_media`, then animate `audio_levels` from 0 dB to about −40 dB over the last 1.5–2 s for a clean fade-out.
+- Solids are sent to the bottom automatically (backgrounds).
+
+## Media rules
+
+- Media accepts exactly one Kolbo `media_id` (preferred) or a Kolbo-owned HTTPS `url`. Third-party hosts, HTTP, private network and guessed URLs are rejected; import third-party files into Kolbo first.
+- Generate first, wait for success, then pass the real media id. Never place a still-running generation.
+- `adobe_place_on_timeline` has no time or track control: it uses the Premiere work sequence playhead or the active After Effects comp. For timed After Effects edits use `adobe_edit_composition`.
+- `adobe_create_sequence` and `adobe_import_captions` are Premiere Pro only; `adobe_edit_composition` is After Effects only. The wrong app fails with `UNSUPPORTED_HOST`.
 
-## Media, sequences and captions
+## Scripts (`adobe_run_script`)
 
-- `adobe_import_media` and `adobe_place_on_timeline` accept exactly one Kolbo `media_id` (preferred) or a Kolbo-owned HTTPS `url`. Third-party hosts, HTTP, private network and guessed URLs are rejected; import third-party files into Kolbo first.
-- To generate then edit: run the Kolbo generation tool, wait for its successful result, then pass the real media id. Never place a still-running generation.
-- `adobe_place_on_timeline` drops the clip into a free track at the playhead of the Premiere work sequence, or into the active After Effects composition. There is no time, track, trim or transition control in v1; do not promise one. Ask the user to position the playhead first when placement matters.
-- `adobe_create_sequence` and `adobe_import_captions` are Premiere Pro only. In After Effects they fail with `UNSUPPORTED_HOST`.
-- For captions, create the SRT with `transcribe_audio`, then pass its Kolbo-hosted `.srt` URL to `adobe_import_captions`.
-- There is no raw ExtendScript tool. If the user asks for an edit outside these commands, say it is not available through agents yet and suggest doing it in the panel or the app.
+- `code` is a **function body**: call `log(...)` for progress and `return` a JSON-serialisable summary. In After Effects the whole script is one undo step.
+- The editor reads the exact code before approving. Keep scripts focused, named and commented; give a plain `purpose`.
+- Scripts have full access to the project and the computer. Never read or write files, call `system.callSystem`, or use the network unless the user explicitly asked for exactly that.
+- On `SCRIPT_ERROR` the message includes the line and the last log lines. Fix the specific problem; do not resend the same script.
 
 ## Completion proof
 
-1. Re-read with `adobe_get_timeline` or `adobe_get_project` after an edit.
-2. Report what changed, which session was targeted, and that the editor approved it.
-3. A command is complete only when `adobe_get_command_status` shows `succeeded`. An accepted enqueue is not proof the edit happened.
+1. Re-read with `adobe_get_timeline` after an edit.
+2. For anything visual - titles, motion graphics, layout, crossfades - call `adobe_capture_frame` at 2–4 representative times and **look at the images** before reporting. Check legibility, contrast, framing and timing.
+3. Report what changed, which session was targeted, and that the editor approved it. A command is complete only when `adobe_get_command_status` shows `succeeded`.

package/skill/references/workflows/after-effects-motion.md

@@ -0,0 +1,193 @@
+# After Effects Motion Graphics
+
+Read this before calling `adobe_run_script` for motion graphics. Connection, approval and completion rules are in `references/workflows/adobe.md`; ordinary cuts, titles and fades belong in `adobe_edit_composition` instead of a script.
+
+Every snippet below was run in After Effects 26.3 through `adobe_run_script`.
+
+## Design before code
+
+Plan the piece as beats before writing anything: what the viewer should notice first, second and last, with times.
+
+- **Timing.** UI and title moves: 0.3–0.6 s. Logo builds and reveals: 1–2 s. Hold readable text for at least 1.5 s plus 0.3 s per word. Leave 0.5 s of breathing room before the end.
+- **Easing.** Nothing real moves at constant speed. Ease into rests (`KeyframeEase` influence 70–90). Use linear only for continuous motion (spins, scrolling, constant drift).
+- **Overlap and offset.** Stagger related elements by 2–4 frames (0.07–0.13 s) instead of moving them together. Let secondary elements settle after the primary one.
+- **Overshoot.** A pop reads as alive when scale goes 0 → 115 → 100 within about 0.6 s. Use it sparingly: one hero element per beat.
+- **Hierarchy.** One dominant element per frame. Size, contrast and motion should all agree on what matters.
+- **Legibility.** Text needs contrast: dark scrim, stroke or shadow over busy footage. Keep text inside title-safe (about 10% margin: x 192–1728, y 108–972 at 1080p).
+- **Restraint.** Two typefaces maximum, a palette of 2–4 colours, and one idea per shot. Remove before adding.
+
+## Build loop
+
+1. `adobe_get_timeline` to see what exists.
+2. Write the script in named sections (background, main element, typography, outro). Name every layer.
+3. `adobe_run_script` with a clear `purpose`. Return a small summary (comp name, layer names).
+4. `adobe_capture_frame` at the key beats (mid-reveal, settled, outro) and look at every image.
+5. Fix in a follow-up script that edits the named layers; do not rebuild everything.
+
+## ExtendScript rules
+
+After Effects scripting is ES3: use `var` and `function`. There is no `let`/`const`, arrow functions, template strings, `Array.prototype.forEach/map/indexOf`, or `Object.keys` - use `for` loops. `JSON` is available. The script body receives `log()` and must `return` its result.
+
+Use property **match names** (`'ADBE Transform Group'`, `'ADBE Position'`), not display names; they work in every UI language.
+
+## Foundation
+
+```js
+var W = 1920, H = 1080, DUR = 6, FPS = 30;
+var comp = app.project.items.addComp('Logo Reveal', W, H, 1, DUR, FPS);
+comp.bgColor = [0.02, 0.02, 0.05];
+comp.motionBlur = true;          // also set layer.motionBlur = true on moving layers
+comp.openInViewer();
+
+function tr(layer, name) { return layer.property('ADBE Transform Group').property(name); }
+// 'ADBE Anchor Point', 'ADBE Position', 'ADBE Scale', 'ADBE Rotate Z', 'ADBE Opacity'
+
+// Keys with ease on every dimension (spatial properties take one ease value).
+function ease(prop, times, values, influence) {
+  for (var i = 0; i < times.length; i++) prop.setValueAtTime(times[i], values[i]);
+  var spatial = prop.propertyValueType === PropertyValueType.TwoD_SPATIAL || prop.propertyValueType === PropertyValueType.ThreeD_SPATIAL;
+  var dims = spatial || !(prop.value instanceof Array) ? 1 : prop.value.length;
+  for (var k = 1; k <= prop.numKeys; k++) {
+    var e = [];
+    for (var d = 0; d < dims; d++) e.push(new KeyframeEase(0, influence || 80));
+    prop.setTemporalEaseAtKey(k, e, e);
+  }
+}
+```
+
+## Backgrounds
+
+```js
+var bg = comp.layers.addSolid([0, 0, 0], 'Background', W, H, 1, DUR);
+var ramp = bg.property('ADBE Effect Parade').addProperty('ADBE Ramp');   // Gradient Ramp
+ramp.property('ADBE Ramp-0001').setValue([W / 2, H * 0.4]);       // start point
+ramp.property('ADBE Ramp-0002').setValue([0.16, 0.13, 0.42, 1]);  // start colour (RGBA)
+ramp.property('ADBE Ramp-0003').setValue([W / 2, H * 1.25]);      // end point
+ramp.property('ADBE Ramp-0004').setValue([0.01, 0.01, 0.03, 1]);  // end colour
+ramp.property('ADBE Ramp-0005').setValue(2);                      // 1 linear, 2 radial
+```
+
+## Shape layers
+
+```js
+var ring = comp.layers.addShape();
+ring.name = 'Ring';
+var group = ring.property('ADBE Root Vectors Group').addProperty('ADBE Vector Group');
+var contents = group.property('ADBE Vectors Group');
+
+contents.addProperty('ADBE Vector Shape - Ellipse').property('ADBE Vector Ellipse Size').setValue([380, 380]);
+// Rounded rectangle instead:
+//   var rect = contents.addProperty('ADBE Vector Shape - Rect');
+//   rect.property('ADBE Vector Rect Size').setValue([900, 500]);
+//   rect.property('ADBE Vector Rect Roundness').setValue(48);
+// Custom path:
+//   var shape = new Shape(); shape.vertices = [[-200, 0], [0, -120], [200, 0]]; shape.closed = false;
+//   contents.addProperty('ADBE Vector Shape - Group').property('ADBE Vector Shape').setValue(shape);
+
+var stroke = contents.addProperty('ADBE Vector Graphic - Stroke');
+stroke.property('ADBE Vector Stroke Color').setValue([0.42, 0.55, 1, 1]);
+stroke.property('ADBE Vector Stroke Width').setValue(16);
+stroke.property('ADBE Vector Stroke Line Cap').setValue(2);            // round caps
+// Solid fill: contents.addProperty('ADBE Vector Graphic - Fill').property('ADBE Vector Fill Color').setValue([1, 1, 1, 1]);
+// Gradient fill: contents.addProperty('ADBE Vector Graphic - G-Fill') with 'ADBE Vector Grad Start Pt' / 'ADBE Vector Grad End Pt'
+
+// Draw-on with Trim Paths (add it after the shape and stroke).
+var trim = contents.addProperty('ADBE Vector Filter - Trim');
+ease(trim.property('ADBE Vector Trim End'), [0.2, 1.5], [0, 100], 85);
+// Endless loader: trim.property('ADBE Vector Trim End').setValue(25); trim.property('ADBE Vector Trim Offset').expression = 'time * 180';
+
+tr(ring, 'ADBE Position').setValue([W / 2, 420]);   // shape contents are centred on the layer position
+ring.motionBlur = true;
+```
+
+Overshoot pop on a second shape: `ease(tr(core, 'ADBE Scale'), [1.2, 1.55, 1.8], [[0, 0], [118, 118], [100, 100]], 70);`
+
+## Typography
+
+```js
+var word = comp.layers.addText('KOLBO');                       // use '\r' for line breaks
+var textProp = word.property('ADBE Text Properties').property('ADBE Text Document');
+var doc = textProp.value;
+doc.resetCharStyle();
+doc.font = 'Arial-BoldMT';          // PostScript name
+doc.fontSize = 190;
+doc.tracking = 180;
+doc.autoLeading = false; doc.leading = 110;                    // multi-line spacing
+doc.fontCapsOption = FontCapsOption.FONT_ALL_CAPS;             // doc.allCaps is read-only
+doc.applyFill = true; doc.fillColor = [1, 1, 1];
+// Outline for busy backgrounds: doc.applyStroke = true; doc.strokeColor = [0, 0, 0]; doc.strokeWidth = 5; doc.strokeOverFill = false;
+doc.justification = ParagraphJustification.CENTER_JUSTIFY;
+textProp.setValue(doc);
+
+// Centre the anchor on the visible text so Position means "centre of the text".
+var box = word.sourceRectAtTime(0, false);
+tr(word, 'ADBE Anchor Point').setValue([box.left + box.width / 2, box.top + box.height / 2]);
+tr(word, 'ADBE Position').setValue([W / 2, 760]);
+```
+
+Per-character reveal with a text animator (characters rise and fade in left to right):
+
+```js
+var animator = word.property('ADBE Text Properties').property('ADBE Text Animators').addProperty('ADBE Text Animator');
+var animProps = animator.property('ADBE Text Animator Properties');
+animProps.addProperty('ADBE Text Position 3D').setValue([0, 140, 0]);   // offset while inside the range
+animProps.addProperty('ADBE Text Opacity').setValue(0);
+// Pop instead of rise: animProps.addProperty('ADBE Text Scale 3D').setValue([0, 0, 100]);
+var selector = animator.property('ADBE Text Selectors').addProperty('ADBE Text Selector');
+// Softer falloff: selector.property('ADBE Text Range Advanced').property('ADBE Text Range Shape').setValue(2); // ramp up
+ease(selector.property('ADBE Text Percent Offset'), [1.6, 2.7], [0, 100], 75);
+word.motionBlur = true;
+```
+
+## Effects
+
+```js
+var fx = layer.property('ADBE Effect Parade');
+var glow = fx.addProperty('ADBE Glo2');                         // Glow
+glow.property('ADBE Glo2-0003').setValue(70);                   // radius
+glow.property('ADBE Glo2-0004').setValue(1.6);                  // intensity
+fx.addProperty('ADBE Gaussian Blur 2').property('ADBE Gaussian Blur 2-0001').setValue(8);  // blurriness
+fx.addProperty('ADBE Drop Shadow').property('ADBE Drop Shadow-0005').setValue(40);         // softness
+fx.addProperty('ADBE Fill').property('ADBE Fill-0002').setValue([1, 0.4, 0.2, 1]);         // colour
+```
+
+## Structure, mattes and 3D
+
+```js
+var ctrl = comp.layers.addNull(); ctrl.name = 'Controller';
+card.parent = ctrl;                                            // move everything together
+
+tr(ctrl, 'ADBE Position').expression = 'wiggle(2, 12)';       // organic drift
+tr(card, 'ADBE Rotate Z').expression = 'loopOut("pingpong")';  // after at least two keys
+tr(ring, 'ADBE Rotate Z').expression = 'time * 24';           // constant spin
+
+var pre = comp.layers.precompose([card.index], 'Card Precomp', true);   // returns the new CompItem
+
+fill.moveAfter(matte);
+fill.setTrackMatte(matte, TrackMatteType.ALPHA);              // reveal fill through the matte's alpha
+
+floor.threeDLayer = true;
+var cam = comp.layers.addCamera('Camera', [W / 2, H / 2]);
+ease(tr(cam, 'ADBE Position'), [0, 5], [[W / 2, H / 2, -2400], [W / 2, H / 2, -1800]], 60);   // slow push-in
+```
+
+## Outro
+
+Fade the group together over the last 0.5–0.7 s, holding the current value first so earlier animation is kept:
+
+```js
+var layers = [ring, core, word, tag];
+for (var i = 0; i < layers.length; i++) {
+  var op = tr(layers[i], 'ADBE Opacity');
+  op.setValueAtTime(DUR - 0.7, op.valueAtTime(DUR - 0.7, false));
+  op.setValueAtTime(DUR, 0);
+}
+return { comp: comp.name, layers: comp.numLayers };
+```
+
+## Checklist before reporting
+
+- Captured frames at mid-reveal, settled state and outro, and looked at them.
+- Text is legible over its background and inside title-safe.
+- Every moving element eases; stagger and overshoot are deliberate, not everywhere.
+- Layers are named and the script returned a summary the user can read.

package/skill/references/workflows/davinci-resolve.md

@@ -0,0 +1,115 @@
+# DaVinci Resolve Workflow
+
+Use this when the user wants Kolbo media edited, graded or rendered in DaVinci Resolve. Kolbo generates and hosts the media; **Blackmagic's own DaVinci Resolve MCP server** drives Resolve. The agent uses both connectors side by side.
+
+Everything below was run against DaVinci Resolve Studio 21.1.0.17 through Blackmagic's server.
+
+## Requirements - check before promising anything
+
+- **DaVinci Resolve Studio 21.1 or later.** The free edition has no MCP server and no external scripting.
+- A **local** agent: Claude Desktop, Claude Code or Codex on the same computer as Resolve. Browser ChatGPT and claude.ai can generate media with Kolbo but cannot reach Resolve.
+- Connect Resolve's server from **File → Setup AI Assistants** in Resolve, and set **Preferences → System → General → External scripting using** to **Local**.
+- Resolve must be running; the server's `launch_resolve` tool can start it.
+
+If the Resolve tools are missing from the conversation, say so and give these steps. Do not try to control Resolve any other way.
+
+## Blackmagic's tools (not Kolbo's)
+
+| Tool | Use |
+|---|---|
+| `get_resolve_status`, `launch_resolve` | Is Resolve running / start it |
+| `get_whats_new` (`since` is required, e.g. `"21.0"`) | Features newer than your training |
+| `search_scripting_api`, `get_scripting_api`, `get_scripting_docs` | Look up exact API signatures before writing a script |
+| `run_script` | Sandboxed Python: Resolve API only, no files, network or processes |
+| `run_script_unsafe` | Python with full system access - required for importing files or downloading media |
+| `generate_lut`, `update_dctl`, `list_luts`, `list_dctls` | Colour transforms |
+
+Scripts get `resolve` and the current `project` pre-injected and return data by assigning `result`.
+
+## Workflow
+
+1. **Generate or find media with Kolbo** (`generate_video`, `generate_music`, `list_media`, …) and wait for success.
+2. **Get the files onto disk.** In Claude Code or Codex, download the Kolbo URLs with the shell. In Claude Desktop, download inside `run_script_unsafe` with `urllib.request`. Only download Kolbo-hosted URLs.
+3. **Protect the user's work.** Call `pm.SaveProject()` first. For anything experimental, build in a new project (`pm.CreateProject(name)`) and reload the original project at the end. Projects opened in 21.1 cannot be opened in 20.x, so never convert a user's project as a side effect.
+4. **Import, cut and finish** with `run_script_unsafe` (see recipe).
+5. **Verify visually.** Set the playhead and call `project.ExportCurrentFrameAsStill(path)` at representative times, then look at the stills before reporting.
+6. Optionally render (`AddRenderJob` / `StartRendering`) and upload the result back to Kolbo with `upload_media` so it lands in the user's library.
+
+## Verified gotchas
+
+- **`MediaPool.ImportMedia` needs plain path strings.** The dict form in the 21.1 stubs (`[{"FilePath": ...}]`) returned `None`. On Windows, backslash paths worked.
+- **File import fails in `run_script`**; use `run_script_unsafe` for anything that touches files.
+- **`Timeline.InsertFusionTitleIntoTimeline("Text+")` is a ripple insert** into every unlocked track: it splits the clips and music under the playhead. With those tracks locked it inserts nothing. For a title over a shot, build it inside that clip's Fusion comp (recipe below).
+- `AppendToTimeline` `startFrame` / `endFrame` are **source frames** at the clip's own frame rate (`GetClipProperty("FPS")`). `recordFrame` is a timeline frame; timelines start at `timeline.GetStartFrame()` (86400 = 01:00:00:00 at 24 fps).
+- New projects default to 24 fps and UHD output.
+
+## Recipe: cut, transition, music fade, title
+
+```python
+pm = resolve.GetProjectManager()
+original = project.GetName()
+pm.SaveProject()
+proj = pm.CreateProject("Kolbo Edit") or pm.LoadProject("Kolbo Edit")
+mp = proj.GetMediaPool()
+
+paths = [r"C:\media\shot1.mp4", r"C:\media\shot2.mp4", r"C:\media\music.mp3"]
+items = {item.GetName(): item for item in mp.ImportMedia(paths)}
+shot1, shot2, music = items["shot1.mp4"], items["shot2.mp4"], items["music.mp3"]
+
+tl = mp.CreateEmptyTimeline("Kolbo Promo")
+proj.SetCurrentTimeline(tl)
+fps = float(proj.GetSetting("timelineFrameRate"))
+start = tl.GetStartFrame()
+
+def src(item, a, b):
+    clip_fps = float(item.GetClipProperty("FPS") or fps)
+    return int(a * clip_fps), int(b * clip_fps) - 1
+
+s1, e1 = src(shot1, 0.5, 6.5)
+s2, e2 = src(shot2, 1.0, 7.0)
+clips = mp.AppendToTimeline([
+    {"mediaPoolItem": shot1, "startFrame": s1, "endFrame": e1, "mediaType": 1, "trackIndex": 1, "recordFrame": start},
+    {"mediaPoolItem": shot2, "startFrame": s2, "endFrame": e2, "mediaType": 1, "trackIndex": 1, "recordFrame": start + int(6 * fps)},
+])
+audio = mp.AppendToTimeline([{"mediaPoolItem": music, "startFrame": 0, "endFrame": int(12 * fps) - 1,
+                              "mediaType": 2, "trackIndex": 1, "recordFrame": start}])
+
+clips[0].AddTransition({"type": "Cross Dissolve", "category": "simple", "position": "end",
+                        "alignment": "center", "duration": int(fps)})
+audio[0].SetFades({"FadeIn": int(0.5 * fps), "FadeOut": int(2 * fps)})
+
+# Title inside shot 1's Fusion comp, fading in and out (Blend keyframes are clip frames).
+comp = clips[0].AddFusionComp()
+media_in, media_out = comp.FindTool("MediaIn1"), comp.FindTool("MediaOut1")
+text = comp.AddTool("TextPlus", -32768, -32768)
+text.SetInput("StyledText", "KOLBO x DAVINCI RESOLVE")
+text.SetInput("Size", 0.085)
+text.SetInput("Font", "Arial")
+text.SetInput("Style", "Bold")
+merge = comp.AddTool("Merge", -32768, -32768)
+merge.ConnectInput("Background", media_in)
+merge.ConnectInput("Foreground", text)
+media_out.ConnectInput("Input", merge)
+merge.AddModifier("Blend", "BezierSpline")
+for value, frame in ((0.0, 6), (1.0, 24), (1.0, 96), (0.0, 120)):
+    merge.SetInput("Blend", value, frame)
+
+pm.SaveProject()
+result = {"project": proj.GetName(), "timeline": tl.GetName(), "original": original}
+```
+
+Then verify, and restore the user's project when you are done:
+
+```python
+tl = project.GetCurrentTimeline()
+tl.SetCurrentTimecode("01:00:02:00")
+ok = project.ExportCurrentFrameAsStill(r"C:\media\check-2s.png")
+resolve.GetProjectManager().SaveProject()
+resolve.GetProjectManager().LoadProject("<original project name>")
+result = {"still": ok}
+```
+
+## Completion proof
+
+- Look at exported stills at the title, the transition and the end before reporting.
+- Report which project and timeline you built, that the original project was saved and restored, and where any render landed.

package/src/index.js

@@ -82,6 +82,7 @@ const { registerAudioStemTools } = require('./tools/audio_stems');
 const { registerAnalyzeTools } = require('./tools/analyze');
 const { registerBlenderTools } = require('./tools/blender');
 const { registerAdobeTools } = require('./tools/adobe');
+const { registerResolveTools } = require('./tools/resolve');
 const { registerApps, attachToolWidgetMeta } = require('./apps');
 const { attachToolAnnotations } = require('./toolAnnotations');
 
@@ -203,6 +204,7 @@ function createServer(opts = {}) {
   registerAudioStemTools(server, client, toolOptions);
   registerBlenderTools(server, client, toolOptions);
   registerAdobeTools(server, client, toolOptions);
+  registerResolveTools(server, client, toolOptions);
 
   // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
   // for text-only hosts — they never fetch them.

package/src/toolAnnotations.js

@@ -36,6 +36,7 @@ const OPEN_WORLD_READ_ONLY = [
   'blender_list_sessions', 'blender_get_scene', 'blender_search_docs',
   'blender_get_command_status',
   'adobe_list_sessions', 'adobe_get_project', 'adobe_get_timeline', 'adobe_get_command_status',
+  'resolve_list_sessions', 'resolve_get_project', 'resolve_get_timeline', 'resolve_get_command_status',
 ];
 
 const PRIVATE_WRITE = [
@@ -105,12 +106,19 @@ const OPEN_WORLD_WRITE = [
   'publish_html_artifact', 'create_review_share_link', 'blender_capture_viewport',
   // Adobe edits add bins, clips, sequences or caption tracks; none delete or overwrite.
   'adobe_import_media', 'adobe_place_on_timeline', 'adobe_create_sequence', 'adobe_import_captions',
+  'adobe_capture_frame',
+  // Resolve imports add Media Pool items; captures add a Kolbo library image.
+  'resolve_import_media', 'resolve_capture_frame',
 ];
 
 const OPEN_WORLD_DESTRUCTIVE = [
   'share_doc', 'revoke_review_share_link',
   'blender_apply_operations', 'blender_import_media', 'blender_render',
   'blender_undo', 'blender_file_operation', 'blender_execute_python',
+  // Can delete layers; approved once per batch in the Kolbo panel.
+  'adobe_edit_composition', 'adobe_run_script',
+  // Can delete timeline clips; approved once per batch in the Kolbo plugin.
+  'resolve_edit_timeline', 'resolve_run_script',
 ];
 
 const CONTRACT_GROUPS = [

package/src/tools/adobe.js

@@ -31,6 +31,114 @@ const mediaUrl = z.string().url().max(4096).optional()
 const mediaKind = z.enum(['video', 'image', 'audio']).optional()
   .describe('Media kind. Inferred from the Kolbo record or file extension when omitted.');
 
+// ─── adobe_edit_composition operation schema (mirrors kolbo-api adobe/schemas.js) ───
+const seconds = (min = 0) => z.number().finite().min(min).max(3600);
+const color = () => z.array(z.number().finite().min(0).max(1)).length(3).describe('[r, g, b], each 0-1');
+const point = () => z.array(z.number().finite().min(-100000).max(100000)).length(2).describe('[x, y] in composition pixels; [0, 0] is top-left');
+const layerRef = z.union([z.number().int().min(1).max(10000), noControls(128)])
+  .describe('Layer name (exact) or 1-based index, 1 = top layer');
+// Titles may span lines; every other control character is refused.
+const TITLE_CONTROL = new RegExp('[\\x00-\\x09\\x0b\\x0c\\x0e-\\x1f]');
+const titleText = z.string().min(1).max(500).refine(
+  (value) => value.trim().length > 0 && !TITLE_CONTROL.test(value),
+  'Text must be 1-500 characters; newlines allowed, no other control characters.',
+);
+
+const compOperation = z.discriminatedUnion('op', [
+  z.object({
+    op: z.literal('comp.create'),
+    name: noControls(128),
+    width: z.number().int().min(16).max(8192).optional().describe('Default 1920'),
+    height: z.number().int().min(16).max(8192).optional().describe('Default 1080'),
+    frame_rate: z.number().finite().min(1).max(120).optional().describe('Default 30'),
+    duration_seconds: seconds(0.1),
+    background_color: color().optional(),
+  }).strict(),
+  z.object({
+    op: z.literal('comp.update'),
+    name: noControls(128).optional(),
+    duration_seconds: seconds(0.1).optional(),
+    background_color: color().optional(),
+  }).strict(),
+  z.object({
+    op: z.literal('layer.add_media'),
+    media_id: mediaId,
+    url: mediaUrl,
+    kind: mediaKind,
+    name: noControls(128).optional().describe('Layer name; defaults to the file name. Name layers you will animate later.'),
+    start_seconds: seconds().optional().describe('Where the layer starts on the comp timeline. Default 0.'),
+    trim_start_seconds: seconds().optional().describe('Seconds skipped at the head of the source clip. Default 0.'),
+    duration_seconds: seconds(0.04).optional().describe('Visible length. Default: rest of the source (stills: rest of the comp).'),
+    fit: z.enum(['cover', 'contain', 'none']).optional().describe('Scale to fill the frame (cover, default), fit inside it, or keep size.'),
+  }).strict(),
+  z.object({
+    op: z.literal('layer.add_text'),
+    text: titleText,
+    name: noControls(128).optional(),
+    start_seconds: seconds().optional(),
+    duration_seconds: seconds(0.04),
+    font: noControls(128).optional().describe('PostScript font name. Default "Arial-BoldMT".'),
+    font_size: z.number().finite().min(4).max(1000).optional().describe('Default 100'),
+    color: color().optional().describe('Default white'),
+    stroke_color: color().optional().describe('Outline colour. Default black when stroke_width is set.'),
+    stroke_width: z.number().finite().min(0).max(100).optional().describe('Outline in pixels. Use 2-6 whenever text sits over bright or busy footage.'),
+    position: point().optional().describe('Centre of the text block. Default: centre of the comp.'),
+  }).strict(),
+  z.object({
+    op: z.literal('layer.add_solid'),
+    color: color(),
+    name: noControls(128).optional(),
+    start_seconds: seconds().optional(),
+    duration_seconds: seconds(0.04).optional(),
+  }).strict(),
+  z.object({
+    op: z.literal('layer.update'),
+    layer: layerRef,
+    new_name: noControls(128).optional(),
+    start_seconds: seconds().optional(),
+    trim_start_seconds: seconds().optional(),
+    duration_seconds: seconds(0.04).optional(),
+    position: point().optional(),
+    scale: z.number().finite().min(0).max(10000).optional().describe('Percent, uniform'),
+    opacity: z.number().finite().min(0).max(100).optional(),
+    rotation: z.number().finite().min(-36000).max(36000).optional().describe('Degrees'),
+    audio_levels: z.number().finite().min(-96).max(24).optional().describe('dB'),
+    enabled: z.boolean().optional(),
+  }).strict(),
+  z.object({
+    op: z.literal('layer.animate'),
+    layer: layerRef,
+    property: z.enum(['opacity', 'scale', 'position', 'rotation', 'audio_levels'])
+      .describe('opacity 0-100, scale percent, rotation degrees, audio_levels dB, position [x, y]'),
+    keyframes: z.array(z.object({
+      time_seconds: seconds().describe('Comp time of this key'),
+      value: z.union([z.number().finite().min(-36000).max(36000), point()]),
+    }).strict()).min(1).max(50),
+    easing: z.enum(['ease', 'linear']).optional().describe('Default ease'),
+  }).strict(),
+  z.object({
+    op: z.literal('layer.delete'),
+    layer: layerRef,
+  }).strict(),
+]);
+const compOperations = z.array(compOperation).min(1).max(100)
+  .superRefine((ops, ctx) => {
+    ops.forEach((operation, opIndex) => {
+      if (operation.op !== 'layer.animate') return;
+      const wantsPoint = operation.property === 'position';
+      operation.keyframes.forEach((key, index) => {
+        if (Array.isArray(key.value) !== wantsPoint) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [opIndex, 'keyframes', index, 'value'],
+            message: wantsPoint ? 'position keyframes need [x, y]' : `${operation.property} keyframes need a number`,
+          });
+        }
+      });
+    });
+  })
+  .refine((ops) => Buffer.byteLength(JSON.stringify(ops), 'utf8') <= 256 * 1024, 'Operations must be at most 256 KiB as JSON.');
+
 function text(value) {
   return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
 }
@@ -162,6 +270,52 @@ function registerAdobeTools(server, client) {
     }
   );
 
+  server.tool(
+    'adobe_edit_composition',
+    'After Effects only. Apply a batch of structured edits to a composition as ONE undo step: create or update a comp, add Kolbo media (trimmed and timed), text titles and solids, change layer timing/transform/opacity/audio, animate with keyframes, or delete layers. Times are in seconds on the composition timeline. Layers are addressed by the exact name you gave them or by 1-based index (1 = top). New layers stack on top; solids go to the bottom. Operations run in order and stop at the first failure (earlier ones stay applied). The editor approves the whole batch once in the Kolbo panel. Read workflows/adobe.md before the first call; verify with adobe_get_timeline afterwards.',
+    {
+      session_id: sessionId,
+      operations: compOperations,
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => {
+      for (const operation of args.operations) {
+        if (operation.op === 'layer.add_media') mediaSource(operation, 'adobe_edit_composition layer.add_media');
+      }
+      return command(client, 'comp.edit', args, { operations: args.operations });
+    }
+  );
+
+  server.tool(
+    'adobe_run_script',
+    'Run ExtendScript inside the connected After Effects (or Premiere Pro) for real motion graphics: shape layers, trim paths, text animators, effects, masks, expressions, cameras, precomps. `code` is a FUNCTION BODY: use log(...) for progress and `return` a JSON-serialisable result. In After Effects the whole script is one undo step. The editor sees the exact code in the Kolbo panel and must approve it. Scripts have full access to the project and the computer, so never read or write files, call system.callSystem, or touch the network unless the user explicitly asked. Read workflows/after-effects-motion.md before writing motion graphics, then verify with adobe_capture_frame.',
+    {
+      session_id: sessionId,
+      code: z.string().min(1).max(64 * 1024).refine(
+        (value) => value.trim().length > 0 && Buffer.byteLength(value, 'utf8') <= 64 * 1024,
+        'Script must be non-empty and at most 64 KiB as UTF-8.',
+      ),
+      purpose: noControls(500).describe('Plain-language reason shown to the editor next to the code.'),
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'script.run', args, { code: args.code, purpose: args.purpose })
+  );
+
+  server.tool(
+    'adobe_capture_frame',
+    'Render one frame of the active After Effects composition (PNG) or Premiere Pro sequence (JPEG) and save it to the Kolbo media library. The result carries the image `url` - look at it to check your motion graphics or edit before telling the user it is done. The editor approves it in the Kolbo panel.',
+    {
+      session_id: sessionId,
+      time_seconds: z.number().finite().min(0).max(3600).optional().describe('Frame time. Default: current playhead / comp time.'),
+      project_id: z.string().min(1).max(128).regex(SAFE_ID).optional().describe('Kolbo project to file the capture in.'),
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'frame.capture', args, {
+      ...(args.time_seconds !== undefined ? { time_seconds: args.time_seconds } : {}),
+      ...(args.project_id ? { project_id: args.project_id } : {}),
+    })
+  );
+
   server.tool(
     'adobe_get_command_status',
     'Read the state, expires_at and bounded result/error of one Adobe command owned by the caller. awaiting_approval is not a polling state: stop and ask the user to approve or deny it in the Kolbo panel.',

package/src/tools/resolve.js

@@ -0,0 +1,249 @@
+'use strict';
+
+const { z } = require('zod');
+const { isTrustedMediaUrl } = require('./blender');
+
+// DaVinci Resolve control through the Kolbo Resolve plugin relay. Same relay
+// contract as Blender and Adobe (/v1/resolve mirrors /v1/adobe): commands are
+// queued on the server, delivered to the open Kolbo plugin in Resolve Studio,
+// approved there by the editor, and executed with Resolve's scripting API.
+
+const SAFE_ID = /^[A-Za-z0-9._:-]+$/;
+
+const noControls = (max) => z.string().min(1).max(max).refine(
+  (value) => value.trim().length > 0 && !/[\x00-\x1f]/.test(value),
+  `Must be non-empty and contain no control characters (max ${max}).`,
+);
+const sessionId = z.string().min(1).max(128).regex(SAFE_ID).optional().describe(
+  'Target Resolve session id from resolve_list_sessions. Omit only when exactly one DaVinci Resolve plugin is connected.'
+);
+const idempotencyKey = z.string()
+  .min(1)
+  .max(128)
+  .regex(SAFE_ID)
+  .optional()
+  .describe('Optional replay-safe key. Reuse it only when retrying the same command.');
+const mediaId = z.string().min(1).max(128).regex(SAFE_ID).optional()
+  .describe('Kolbo media library id (preferred). Provide exactly one of media_id or url.');
+const mediaUrl = z.string().url().max(4096).optional()
+  .describe('Kolbo-owned HTTPS media URL. Third-party hosts are rejected; import them into Kolbo first.');
+const mediaKind = z.enum(['video', 'image', 'audio']).optional()
+  .describe('Media kind. Inferred from the Kolbo record or file extension when omitted.');
+
+// ─── resolve_edit_timeline operation schema (mirrors kolbo-api resolve/schemas.js) ───
+const seconds = (min = 0, max = 4 * 3600) => z.number().finite().min(min).max(max);
+const track = () => z.number().int().min(1).max(50);
+const clipRef = z.union([z.number().int().min(1).max(10000), noControls(128)])
+  .describe('Clip position on the track (1 = leftmost) or exact clip name');
+const TITLE_CONTROL = new RegExp('[\\x00-\\x09\\x0b\\x0c\\x0e-\\x1f]');
+const titleText = z.string().min(1).max(500).refine(
+  (value) => value.trim().length > 0 && !TITLE_CONTROL.test(value),
+  'Text must be 1-500 characters; newlines allowed, no other control characters.',
+);
+const unit = () => z.number().finite().min(0).max(1);
+
+const timelineOperation = z.discriminatedUnion('op', [
+  z.object({
+    op: z.literal('timeline.create'),
+    name: noControls(128).describe('New empty timeline at the project frame rate and resolution; it becomes the current timeline.'),
+  }).strict(),
+  z.object({
+    op: z.literal('clip.append'),
+    media_id: mediaId,
+    url: mediaUrl,
+    kind: mediaKind,
+    name: noControls(128).optional(),
+    track_index: track().optional().describe('Target track (video and/or audio). Missing tracks are added. Default 1.'),
+    record_seconds: seconds().optional().describe('Timeline position in seconds from the timeline start. Default: end of the timeline.'),
+    trim_start_seconds: seconds().optional().describe('Seconds skipped at the head of the source clip. Default 0.'),
+    duration_seconds: seconds(0.04).optional().describe('Length on the timeline. Default: rest of the source (stills: 5 s).'),
+    media_type: z.enum(['video', 'audio', 'both']).optional().describe('Which part of the clip to place. Default both (video files) or audio (audio files).'),
+  }).strict(),
+  z.object({
+    op: z.literal('clip.transition'),
+    track_index: track().describe('Video track'),
+    clip: clipRef,
+    position: z.enum(['start', 'end']).optional().describe('Default end'),
+    duration_seconds: seconds(0.04, 30).optional().describe('Default 1'),
+    transition: z.enum(['Cross Dissolve', 'Dip To Color Dissolve', 'Smooth Cut', 'Additive Dissolve', 'Blur Dissolve']).optional().describe('Default Cross Dissolve'),
+  }).strict(),
+  z.object({
+    op: z.literal('clip.delete'),
+    track_type: z.enum(['video', 'audio']),
+    track_index: track(),
+    clip: clipRef,
+    ripple: z.boolean().optional().describe('Close the gap. Default false.'),
+  }).strict(),
+  z.object({
+    op: z.literal('audio.fade'),
+    track_index: track().describe('Audio track'),
+    clip: clipRef,
+    fade_in_seconds: seconds(0, 600).optional(),
+    fade_out_seconds: seconds(0, 600).optional(),
+  }).strict(),
+  z.object({
+    op: z.literal('title.add'),
+    track_index: track().describe('Video track of the clip the title sits on'),
+    clip: clipRef,
+    text: titleText,
+    font: noControls(128).optional().describe('Font family. Default "Arial".'),
+    size: unit().optional().describe('Text size relative to frame height, 0.01-1. Default 0.08.'),
+    color: z.array(unit()).length(3).optional().describe('[r, g, b], each 0-1. Default white.'),
+    position: z.array(unit()).length(2).optional().describe('[x, y] centre, 0-1; [0.5, 0.5] is the frame centre, y grows upward. Default [0.5, 0.5].'),
+    fade_seconds: seconds(0, 10).optional().describe('Fade in at the clip start and out at its end. Default 0.5.'),
+  }).strict(),
+  z.object({
+    op: z.literal('marker.add'),
+    time_seconds: seconds().describe('Seconds from the timeline start'),
+    color: z.enum(['Blue', 'Cyan', 'Green', 'Yellow', 'Red', 'Pink', 'Purple', 'Fuchsia', 'Rose', 'Lavender', 'Sky', 'Mint', 'Lemon', 'Sand', 'Cocoa', 'Cream']).optional(),
+    name: noControls(128).optional(),
+    note: noControls(1000).optional(),
+    duration_seconds: seconds(0.04).optional(),
+  }).strict(),
+]);
+const timelineOperations = z.array(timelineOperation).min(1).max(100)
+  .superRefine((ops, ctx) => {
+    ops.forEach((operation, index) => {
+      if (operation.op === 'audio.fade' && operation.fade_in_seconds === undefined && operation.fade_out_seconds === undefined) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [index], message: 'audio.fade needs fade_in_seconds or fade_out_seconds' });
+      }
+    });
+  })
+  .refine((ops) => Buffer.byteLength(JSON.stringify(ops), 'utf8') <= 256 * 1024, 'Operations must be at most 256 KiB as JSON.');
+
+function text(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+function envelope(type, args, payload) {
+  return {
+    ...(args.session_id ? { session_id: args.session_id } : {}),
+    command_type: type,
+    payload,
+    ...(args.idempotency_key ? { idempotency_key: args.idempotency_key } : {}),
+  };
+}
+
+function command(client, type, args, payload) {
+  return client.post('/v1/resolve/commands', envelope(type, args, payload)).then(text);
+}
+
+function mediaSource(args, toolName) {
+  if (Boolean(args.media_id) === Boolean(args.url)) {
+    throw new Error(`${toolName} requires exactly one of media_id or url.`);
+  }
+  if (args.url && !isTrustedMediaUrl(args.url)) {
+    throw new Error(`${toolName} accepts only Kolbo-owned HTTPS media URLs. Import third-party files into Kolbo first.`);
+  }
+  return {
+    ...(args.media_id ? { media_id: args.media_id } : { url: args.url }),
+    ...(args.kind ? { kind: args.kind } : {}),
+    ...(args.name ? { name: args.name } : {}),
+  };
+}
+
+function registerResolveTools(server, client) {
+  server.tool(
+    'resolve_list_sessions',
+    'List the caller\'s DaVinci Resolve Studio windows that have the Kolbo plugin connected to AI agents. Call this before the first Resolve command. If none are listed, ask the user to open Workspace → Workflow Integrations → Kolbo AI in Resolve Studio and sign in.',
+    {
+      page: z.number().int().min(1).default(1),
+      page_size: z.number().int().min(1).max(100).default(25),
+    },
+    async ({ page, page_size }) => text(await client.get(`/v1/resolve/sessions?page=${page}&page_size=${page_size}`))
+  );
+
+  server.tool(
+    'resolve_get_project',
+    'Queue a read-only inspection of the open DaVinci Resolve project: name, timelines, current timeline, frame rate, resolution and playhead. No approval is needed. Returns a command record; poll resolve_get_command_status for the result.',
+    {
+      session_id: sessionId,
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'project.get', args, {})
+  );
+
+  server.tool(
+    'resolve_get_timeline',
+    'Queue a read-only inspection of the current DaVinci Resolve timeline: frame rate, duration, playhead, markers and every clip per video/audio track (track, position, name, start_seconds, end_seconds). No approval is needed. The clip list is truncated to max_clips (default 200).',
+    {
+      session_id: sessionId,
+      max_clips: z.number().int().min(1).max(1000).optional(),
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'timeline.get', args, {
+      ...(args.max_clips ? { max_clips: args.max_clips } : {}),
+    })
+  );
+
+  server.tool(
+    'resolve_import_media',
+    'Import one Kolbo media item into the Kolbo.AI bin of the open DaVinci Resolve project\'s Media Pool without touching the timeline. The editor must approve it in the Kolbo plugin. Returns a command record; poll resolve_get_command_status.',
+    {
+      session_id: sessionId,
+      media_id: mediaId,
+      url: mediaUrl,
+      kind: mediaKind,
+      name: noControls(128).optional().describe('File name. Sanitized by the plugin.'),
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'media.import', args, mediaSource(args, 'resolve_import_media'))
+  );
+
+  server.tool(
+    'resolve_edit_timeline',
+    'DaVinci Resolve. Apply a batch of structured timeline edits: create a timeline, place Kolbo media at exact times on chosen tracks with trims, add transitions, fade audio, put animated titles over a clip (built in its Fusion comp), add markers, or delete clips. Times are seconds from the timeline start. Clips are addressed by track plus position (1 = leftmost) or exact name. Operations run in order and stop at the first failure (earlier ones stay applied). The editor approves the whole batch once in the Kolbo plugin. Read workflows/davinci-resolve.md first; verify with resolve_get_timeline and resolve_capture_frame.',
+    {
+      session_id: sessionId,
+      operations: timelineOperations,
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => {
+      for (const operation of args.operations) {
+        if (operation.op === 'clip.append') mediaSource(operation, 'resolve_edit_timeline clip.append');
+      }
+      return command(client, 'timeline.edit', args, { operations: args.operations });
+    }
+  );
+
+  server.tool(
+    'resolve_run_script',
+    'Run JavaScript against DaVinci Resolve\'s scripting API inside the Kolbo plugin, for anything resolve_edit_timeline does not cover (colour, Fusion, render jobs, project settings). `code` is an ASYNC FUNCTION BODY with `resolve`, `project`, `timeline` and `log(...)` in scope; every Resolve API call returns a promise, so `await` it, and `return` a JSON-serialisable result. The editor sees the exact code in the Kolbo plugin and must approve it. Scripts have full access to the project and the computer, so never read or write files or touch the network unless the user explicitly asked.',
+    {
+      session_id: sessionId,
+      code: z.string().min(1).max(64 * 1024).refine(
+        (value) => value.trim().length > 0 && Buffer.byteLength(value, 'utf8') <= 64 * 1024,
+        'Script must be non-empty and at most 64 KiB as UTF-8.',
+      ),
+      purpose: noControls(500).describe('Plain-language reason shown to the editor next to the code.'),
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'script.run', args, { code: args.code, purpose: args.purpose })
+  );
+
+  server.tool(
+    'resolve_capture_frame',
+    'Export one frame of the current DaVinci Resolve timeline and save it to the Kolbo media library. The result carries the image `url` - look at it to check the edit or title before telling the user it is done. Moves the playhead to time_seconds when given. The editor approves it in the Kolbo plugin.',
+    {
+      session_id: sessionId,
+      time_seconds: z.number().finite().min(0).max(4 * 3600).optional().describe('Seconds from the timeline start. Default: current playhead.'),
+      project_id: z.string().min(1).max(128).regex(SAFE_ID).optional().describe('Kolbo project to file the capture in.'),
+      idempotency_key: idempotencyKey,
+    },
+    async (args) => command(client, 'frame.capture', args, {
+      ...(args.time_seconds !== undefined ? { time_seconds: args.time_seconds } : {}),
+      ...(args.project_id ? { project_id: args.project_id } : {}),
+    })
+  );
+
+  server.tool(
+    'resolve_get_command_status',
+    'Read the state, expires_at and bounded result/error of one DaVinci Resolve command owned by the caller. awaiting_approval is not a polling state: stop and ask the user to approve or deny it in the Kolbo plugin.',
+    {
+      command_id: z.string().min(1).max(128).regex(SAFE_ID),
+    },
+    async ({ command_id: id }) => text(await client.get(`/v1/resolve/commands/${encodeURIComponent(id)}`))
+  );
+}
+
+module.exports = { registerResolveTools };