@kolbo/mcp 1.93.4 → 1.93.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.93.4",
+  "version": "1.93.6",
   "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@54e9713, the single source of truth.
+This tree is mirrored from kolbo-code@d10586e, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -339,7 +339,7 @@ Four surfaces show the same job. Use this map — never invent a fifth:
 
 **🛑 NEVER re-fire a generation you already called.** Aborted / timed-out / `submitted` calls still process server-side. Finish with `get_generation_status` (`wait=true`) — never a second `generate_*`.
 
-**🛑 After `submitted` / `_timed_out` — END THE TURN (credit guard).** Do **not** keep thinking, writing skills, editing files, or planning "next steps" while a generation is still running — that burns the user's coding/chat credits for nothing. Either **stop immediately** after telling the user it's generating in Library / the card above (preferred when you do not need the output URLs yet), OR — if the **next** required step needs those URLs — call `get_generation_status` **once** with `wait=true` as the **only** follow-up, no parallel Write/Edit/Think while it waits.
+**After `submitted` / `_timed_out` — avoid idle work (credit guard).** For a multi-output request, first submit all independent authorized items within the supported concurrency limit. Do not end the task after submitting only the first item or batch. If more requested items are waiting for capacity or output dependencies, use one batched `get_generation_status` call with `wait=true`, then submit the next ready batch. Once every requested item is submitted and no further work needs its output, tell the user it is generating in Library / the cards and end the turn. Submitted is not completed. Do not perform unrelated thinking, file edits, or speculative extra generations while waiting.
 
 **Checking status — NEVER poll in a loop.** `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop: check ALL in-flight ids in ONE call, never one by one, never without `wait`. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
 
@@ -390,8 +390,8 @@ After the user approves a bucket, write its `session_id` + plan name into `.kolb
 ## Rate Limiting & Batch Generation
 
 - `generate_image`: 30/min. All other generation tools: 10/min per type. 300/min global. `upload_media`: 300/min, no credit cost.
-- **Batch ≤10 items**: output ALL tool calls in one response — they run concurrently.
-- **Bulk >10 items**: real-world ceilings — `generate_image` 8–10 in-flight, image-edit 5–8, video tools 3–5, `generate_video_from_video` 3, music/speech/sound 5–8. Fire one batch → wait → fire next. Keep pending ids in the current run; persist only the user-approved winners in `.kolbo/production.md`.
+- **Independent outputs:** emit ready generation calls together. This applies to videos as well as images. Eight requested videos must not become eight sequential waits when parallel submission is supported.
+- **Every batch size:** respect current tool/provider concurrency limits and rate-limit responses. If no more specific limit is available, use the existing conservative batch guidance: images 8, image edits 5, videos 3, video-to-video 3, music/speech/sound 5. Submit each batch concurrently, wait for capacity with a batched status call, then submit the remaining items. Keep pending IDs in the current run; persist only user-approved winners in `.kolbo/production.md`. Never restart submitted jobs to fill a batch.
 
 ## ⚠️ Multi-output? Default to `generate_creative_director` (CRITICAL)
 

package/skill/references/models/gpt-image.md

@@ -4,7 +4,7 @@
 
 # GPT Image 2 / 2.5 — Prompt Rules
 
-Load this file when the user wants a **GPT Image 2 or GPT Image 2.5** image (OpenAI). The live family is `gpt-image-2`, `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` — all three are the ONLY Kolbo image models that can output a native transparent background. (`gpt-image/1.5-text-to-image` is the older row and cannot.) For other image models see `models/nano-banana.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
+Load this file when the user wants a **GPT Image 2 or GPT Image 2.5** image (OpenAI). Discover current variants and native transparency support from list_models; never assume exclusivity or support from this reference. For other image models see `models/nano-banana.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
 
 **Kolbo MCP routing:** call `generate_image` (text-to-image) or `generate_image_edit` (edits with `source_images`). Pass the exact identifier the user named (`gpt-image-2`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-flare`); otherwise consult `list_models({ type: "text_to_img" })`. On `generate_image_edit` the same families appear as their `/edit` rows under `list_models({ type: "image_editing" })`.
 
@@ -26,23 +26,20 @@ Load this file when the user wants a **GPT Image 2 or GPT Image 2.5** image (Ope
 - **People, pose, action**: describe scale, body framing, gaze, object interactions ("full body visible, feet included", "looking down at the open book, not at the camera", "hands naturally gripping the handlebar").
 - **Complex scene, an edit that must not drift, or a reusable template**: use the block schema, the reference contract (`identity_lock` + an explicit `preserve` list) and named slots from `workflows/prompt-structure.md`.
 - **Constraints — what changes vs what stays**: state exclusions and invariants explicitly. For edits use **"change only X" + "keep everything else the same"**, and re-state the preserve list on every iteration to prevent drift. Common invariants: identity, geometry, layout, brand elements, camera angle, saturation, contrast, labels, surrounding objects. Always include "no watermark, no extra text, no logos/trademarks" unless the brief specifies otherwise.
-- **Text in images**: put literal text in **quotes** or **ALL CAPS**, specify typography (font style, size, color, placement). For tricky words / brand names, spell letter-by-letter. Recommend quality **high** when text is small, dense, or multi-font.
+- **Text in images**: put literal text in **quotes** or **ALL CAPS**, specify typography (font style, size, color, placement). For tricky words / brand names, spell letter-by-letter. Use the current catalog quality guidance for small, dense or multi-font text.
 - **Multi-image inputs**: reference each input by number with a short description ("Image 1: product photo… Image 2: style reference…") and describe the interaction ("apply Image 2's style to Image 1", "place the dog from Image 2 next to the woman in Image 1"). Use `@image1` / `@image2` tags — see `workflows/visual-dna.md`.
 - **Iterate, don't overload**: prefer a clean base prompt + single-change follow-ups ("make lighting warmer", "remove the extra tree", "restore the original background") over one giant prompt.
 
-## Latency vs Fidelity (recommend `quality` param)
+## Quality selection
 
-- **low**: only when the user prioritizes minimum cost or latency; medium remains the ordinary GPT Image 2.5 default.
-- **medium**: default best price/quality for ordinary generations, edits and exploration.
-- **high**: final assets, small/dense text, multi-font layouts, close-up portraits, identity-sensitive edits, infographics, diagrams, posters, UI with labels, scientific visuals, slides with charts/footnotes.
-- **xhigh/max** (GPT Image 2.5 only, when listed): exceptional dense text or difficult multilingual/Hebrew typography after medium/high are insufficient. Do not auto-run retries or raise spending without authorization.
+Read the selected model's current catalog summary, supported qualities and default_quality before recommending a tier. The catalog owns price/quality tradeoffs and exceptional higher-tier use cases. Honor explicit user settings and spending authorization; examples below are craft illustrations, not default settings.
 
 ## Use Cases (text → image)
 
 ### Infographics, diagrams, scientific visuals, slides/charts
 - Treat as artifact spec, not illustration request. Name exact deliverable. Define hierarchy. Provide real text/data verbatim in quotes.
 - Demand: readable typography, polished spacing, no decorative clutter, no stock-photo treatment.
-- Recommend: `quality: "high"`, landscape `aspect_ratio` for deck/slide outputs.
+- Recommend a supported quality from the current catalog and an aspect ratio matching the requested deck/slide output.
 
 ### Photorealism
 - Prompt as if a real photo is being captured in the moment. Use photography language (lens, lighting, framing). Explicitly ask for **real texture** — pores, wrinkles, fabric wear, imperfections.
@@ -50,7 +47,7 @@ Load this file when the user wants a **GPT Image 2 or GPT Image 2.5** image (Ope
 
 ### Logos
 - Brand personality + use case + clean, original mark + strong silhouette + balanced negative space + scales from small to large. Flat design, minimal strokes, no gradients unless essential. Plain background, generous padding, centered. "Original, non-infringing".
-- Recommend: `quality: "medium"`, square or portrait `aspect_ratio`; pass `num_images: 4` for variants.
+- Recommend quality from the selected catalog row and an aspect ratio matching the brief; request variants only within the authorized count and budget.
 
 ### Ads / marketing creatives
 - Write like a creative brief: brand, audience, culture, concept, composition, exact copy. Let the model make taste decisions inside boundaries.

package/skill/references/models/nano-banana.md

@@ -13,11 +13,8 @@ Load this file when the user wants a **Nano Banana 2 (Gemini 3.1 Flash Image)**
 - **Resolution and aspect ratio are MCP-tool params.** **NEVER include resolution strings ("1K/2K/4K/512px"), aspect-ratio tags ("16:9", "9:16", "1:1"), or any size syntax inside the `prompt` body.** Pass them as separate `aspect_ratio` / `resolution` params.
 - Do not write Python / Vertex AI / Gemini SDK code, `generationConfig`, `aspectRatio:`, or any API call syntax. The user is generating through Kolbo's MCP tools.
 
-## Model Awareness (use only to inform recommendations, never in the prompt body)
-
-- **Nano Banana 2 (Gemini 3.1 Flash Image)**: fast, 512px / 1K / 2K / 4K, very wide aspect range incl. 1:4, 4:1, 1:8, 8:1, 21:9, supports real-time web-search grounding. Default for most use cases.
-- **Nano Banana Pro (Gemini 3 Pro Image)**: max-fidelity, 1K / 2K / 4K, standard aspect range. Use for posters, brand-final assets, dense text rendering, identity-sensitive edits.
-- Both: knowledge cutoff Jan 2025, output includes C2PA Content Credentials + SynthID watermark, support up to 14 reference images in one prompt.
+## Model Awareness
+Read the current catalog for the requested family's variants, strengths, quality, resolutions, grounding and reference limits. No variant is a permanent default; do not infer capabilities or rank siblings from this prompt-writing reference.
 
 ## Best Practices (apply to EVERY prompt)
 
@@ -52,7 +49,7 @@ Instead of describing a fictional scene, instruct the model to retrieve real-wor
 **Formula**: `[Source/Search request] + [Analytical task] + [Visual translation]`
 Example shape: `Search for the current weather and date in San Francisco. Analytically, use this data to modify the scene (e.g., if raining, make it look grey and rainy). Visualize this in a miniature city-in-a-cup concept embedded within a realistic, modern smartphone UI.`
 - Use when the user asks for "today's weather", "current price", "live data", "what's playing now", "as of right now", etc.
-- Recommend Nano Banana 2 (Flash) for this — Pro doesn't add value here.
+- Select a current catalog variant that explicitly supports the requested grounding workflow.
 
 ### 5. Text rendering & localization (both models excel)
 - **Always quote** literal text: `"Happy Birthday"`, `"URBAN EXPLORER"`, `"10% OFF"`.
@@ -60,7 +57,7 @@ Example shape: `Search for the current weather and date in San Francisco. Analyt
 - **Multilingual**: write the prompt in English and specify the target language for the in-image text ("Then render the same text in Korean and Arabic").
 - **Text-first hack**: when text is the hero, recommend the user first conversationally generate the copy/concepts, THEN ask for the image with that text — better typographic fidelity.
 - Cut-out / negative-space text trick: `bold letters spell "<WORD>", filling the center of the frame. The text acts as a cut-out window. A photograph of <scene> is visible ONLY inside the letterforms.`
-- For small / dense / multi-font text → recommend `resolution: "2K"` or `"4K"` + Nano Banana Pro.
+- For small / dense / multi-font text, select the variant and quality using current catalog strengths and supported settings.
 
 ## Prompt Like a Creative Director (the upgrade layer)
 

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/cost-and-validation.md

@@ -104,7 +104,7 @@ Normal cost formula: `final_cost = credit × output_seconds × resolution_multip
    - Only fire after they reply.
 2. **No explicit video output resolution**: choose the cheapest supported tier using current catalog pricing and pass it explicitly. This applies to drafts, normal work and final delivery alike. Do not default to 720p/1080p when a cheaper supported tier exists. Fixed-resolution models use their native output.
 3. **Creative intent is not spending authorization**: "finish fully", "cinematic", "professional", "final", "production", "hero" and "don't ask me" do not authorize higher resolution, upscaling or a second high-resolution generation. A budget is a ceiling, not a target. Reference-video resolution and export resolution do not authorize matching generation resolution.
-4. Preserve explicit user-selected settings. Otherwise proceed economically without a resolution approval loop. Inspect missing pricing/capabilities before dispatch. Upgrade only when the user explicitly selects a higher output tier or authorizes the resolution increase; never treat silence as approval. Image quality follows the image-model guidance (GPT Image 2.5 medium by default), not a generic final-work maximum.
+4. Preserve explicit user-selected settings. Otherwise proceed economically without a resolution approval loop. Inspect missing pricing/capabilities before dispatch. Upgrade only when the user explicitly selects a higher output tier or authorizes the resolution increase; never treat silence as approval. Image quality follows the selected model's live catalog summary and default_quality, not a hardcoded family preference or generic final-work maximum.
 5. **Sound on a video model with `sound_credit_multiplier > 1`** → if user didn't ask for sound, leave it off. If user said "with sound" / "with music", enable it.
 
 ## Defaults When Nothing Is Specified

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

@@ -0,0 +1,163 @@
+# DaVinci Resolve Workflow
+
+Use this when the user wants Kolbo media edited, cut, titled, graded or rendered in DaVinci Resolve. There are two ways to reach Resolve; pick by what is connected.
+
+| Path | Works from | Use it for |
+|---|---|---|
+| **Kolbo Resolve plugin** (`resolve_*` tools, this server) | Any agent, including ChatGPT and claude.ai | Reading the project, importing Kolbo media, building timeline edits, titles, frame checks - every change approved by the editor |
+| **Blackmagic's DaVinci Resolve MCP** (their own server) | Local agents only (Claude Desktop, Claude Code, Codex) | Deep scripting, colour, LUTs/DCTLs, rendering |
+
+Both need **DaVinci Resolve Studio**; the free edition has no plugins and no external scripting. If `resolve_list_sessions` returns a session, prefer the Kolbo plugin.
+
+## Kolbo Resolve plugin
+
+Everything in this section was run end to end through Kolbo MCP against DaVinci Resolve Studio 21.1.
+
+### Connect and target safely
+
+1. Call `resolve_list_sessions` before the first Resolve action.
+2. If no session is listed, ask the user to open **Workspace → Workflow Integrations → Kolbo AI** in Resolve Studio and sign in with the same Kolbo account as this connector. **AI agents** in the plugin header connects automatically; if its dot is not green, ask them to click it.
+3. One session: `session_id` may be omitted. Several: show each and ask. Keep the chosen `session_id` on every later call; re-list after Resolve or the plugin restarts.
+
+Every tool except `resolve_list_sessions` and `resolve_get_command_status` returns a command record. Poll `resolve_get_command_status` until `succeeded`, `failed`, `denied` or `canceled`. Reads run without approval; everything else waits for **Allow once / Allow for this session / Deny** in the plugin window. `awaiting_approval` is not a polling state: tell the user to approve in the Kolbo AI window (it may be behind Resolve), then check again. `denied` is final.
+
+### Tools
+
+| Goal | Tool |
+|---|---|
+| Project name, timelines, frame rate, resolution, playhead | `resolve_get_project` |
+| Clips on every track (position, start/end seconds), markers | `resolve_get_timeline` |
+| Kolbo media into the Media Pool only | `resolve_import_media` |
+| Build or change an edit | `resolve_edit_timeline` |
+| Anything else in Resolve's scripting API | `resolve_run_script` |
+| See the result | `resolve_capture_frame` → look at the returned `url` |
+
+### Timeline edits (`resolve_edit_timeline`)
+
+- Up to 100 operations run in order and stop at the first failure; earlier operations stay applied. Fix the failing one and continue - do not replay the batch.
+- Start new work with `timeline.create` so the user's existing timelines stay untouched. It uses the project's frame rate and resolution.
+- Times are seconds from the timeline start. `clip.append`: `record_seconds` = where it lands (default: end of that track), `trim_start_seconds` = seconds skipped at the head of the source, `duration_seconds` = length on the timeline (stills default to 5 s). media_type "video" keeps a clip's audio off the timeline; audio files always go to audio tracks. Missing tracks are added.
+- Clips are addressed by track plus position (1 = leftmost media clip on that track; transitions do not count) or exact clip name. Clip names are file names, and a file imported again gets a short prefix, so prefer positions. Positions change after inserts and deletes - re-read with `resolve_get_timeline` when unsure.
+- `clip.transition` needs handles: trim the head of the next shot (`trim_start_seconds` ≥ half the transition) or the transition will be refused.
+- `audio.fade` is for clips on audio tracks. `title.add` builds the title inside that clip's Fusion comp (`position` [0.5, 0.5] = centre, y grows upward) with a fade in and out; keep it inside title-safe (x and y between 0.1 and 0.9).
+- `clip.delete` is destructive; only delete what the user asked for.
+- The Kolbo AI window must stay open while you work; it can sit behind Resolve.
+
+### Scripts (`resolve_run_script`)
+
+- `code` is an **async JavaScript function body** with `resolve`, `project`, `timeline` and `log(...)` in scope. Every Resolve call returns a promise - `await` each one - and `return` a JSON-serialisable result.
+- The editor reads the exact code before approving. Give a plain `purpose`. Never touch files, the network or other projects unless the user asked for exactly that.
+
+## Blackmagic's DaVinci Resolve MCP
+
+Verified against DaVinci Resolve Studio 21.1.0.17.
+
+### 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 cannot reach this server; use the Kolbo Resolve plugin from there.
+- 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 neither the Kolbo plugin session nor Blackmagic's tools are available, say so and give the setup steps for the path that fits the user. 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/skill/references/workflows/personal-fonts.md

@@ -42,7 +42,7 @@ it — nothing installs the font — so these are the levers that decide how clo
 
 - **Model choice is the biggest one.** GPT Image 2 reproduced the uploaded letterforms
   clearly better than GPT Image 2.5 Sunburst / Flare, which drift toward a default bold
-  Hebrew. Recommend GPT Image 2 whenever the typeface matters.
+  Hebrew in that test. This is historical evidence, not a standing recommendation: choose from current catalog typography strengths and supported font inputs.
 - **Quality does not compensate.** 2K + `high` on GPT Image 2 beat both 2.5 rows at
   `max`. Do not sell a higher tier as a fix for typography.
 - **Weight words in the prompt beat the specimen.** "bold", "medium weight", "very large