@kolbo/mcp 1.70.1 → 1.70.3

package/skill/scripts/filmmaking/validate_film_package.py

@@ -0,0 +1,435 @@
+#!/usr/bin/env python3
+"""Validate a Kolbo Filmmaker production package using only the Python stdlib."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Iterable
+
+
+VALID_MODES = {
+    "text-to-video",
+    "image-to-video",
+    "reference-to-video",
+    "first-last-frame",
+    "video-to-video",
+}
+VALID_DENSITIES = {"strict", "anchored", "exploratory"}
+
+
+class Report:
+    def __init__(self) -> None:
+        self.items: list[dict[str, str]] = []
+
+    def add(self, level: str, code: str, path: str, message: str) -> None:
+        self.items.append(
+            {"level": level, "code": code, "path": path, "message": message}
+        )
+
+    def error(self, code: str, path: str, message: str) -> None:
+        self.add("error", code, path, message)
+
+    def warn(self, code: str, path: str, message: str) -> None:
+        self.add("warning", code, path, message)
+
+    @property
+    def error_count(self) -> int:
+        return sum(item["level"] == "error" for item in self.items)
+
+    @property
+    def warning_count(self) -> int:
+        return sum(item["level"] == "warning" for item in self.items)
+
+
+def load_json(path: Path, report: Report) -> Any | None:
+    try:
+        return json.loads(path.read_text(encoding="utf-8-sig"))
+    except FileNotFoundError:
+        report.error("missing_file", str(path), "Required file does not exist.")
+    except json.JSONDecodeError as exc:
+        report.error(
+            "invalid_json",
+            str(path),
+            f"JSON parse error at line {exc.lineno}, column {exc.colno}: {exc.msg}",
+        )
+    except OSError as exc:
+        report.error("read_failed", str(path), f"Could not read file: {exc}")
+    return None
+
+
+def require_fields(
+    obj: Any, fields: Iterable[str], path: str, report: Report
+) -> None:
+    if not isinstance(obj, dict):
+        report.error("wrong_type", path, "Expected a JSON object.")
+        return
+    for field in fields:
+        if field not in obj or obj[field] in (None, "", []):
+            report.error("missing_field", f"{path}.{field}", "Required field is empty.")
+
+
+def collect_registry_tags(bible: dict[str, Any]) -> set[str]:
+    tags: set[str] = set()
+
+    def walk(value: Any) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if key in {"tag", "canonical_tag"} and isinstance(child, str):
+                    if child.startswith("@"):
+                        tags.add(child)
+                walk(child)
+        elif isinstance(value, list):
+            for child in value:
+                walk(child)
+
+    for section in ("characters", "locations", "assets"):
+        walk(bible.get(section, []))
+    return tags
+
+
+def json_files(folder: Path) -> list[Path]:
+    return sorted(path for path in folder.glob("*.json") if path.is_file())
+
+
+def validate_bible(bible: Any, path: Path, report: Report) -> tuple[str, set[str]]:
+    require_fields(
+        bible,
+        [
+            "schema_version",
+            "project_id",
+            "title",
+            "story",
+            "characters",
+            "locations",
+            "assets",
+            "audio_policy",
+        ],
+        str(path),
+        report,
+    )
+    if not isinstance(bible, dict):
+        return "", set()
+    project_id = str(bible.get("project_id", ""))
+    tags = collect_registry_tags(bible)
+    if not tags:
+        report.warn(
+            "empty_asset_registry",
+            str(path),
+            "No @ asset tags were found in characters, locations, or assets.",
+        )
+    for section in ("characters", "locations", "assets"):
+        if not isinstance(bible.get(section), list):
+            report.error(
+                "wrong_type", f"{path}.{section}", "Expected this registry to be a list."
+            )
+    return project_id, tags
+
+
+def validate_scene_cards(
+    paths: list[Path], project_id: str, registry_tags: set[str], report: Report
+) -> set[str]:
+    scene_ids: set[str] = set()
+    for path in paths:
+        card = load_json(path, report)
+        if card is None:
+            continue
+        require_fields(
+            card,
+            ["project_id", "scene_id", "slugline", "story_job", "structure"],
+            str(path),
+            report,
+        )
+        if not isinstance(card, dict):
+            continue
+        scene_id = str(card.get("scene_id", ""))
+        if scene_id in scene_ids:
+            report.error("duplicate_scene_id", str(path), f"Duplicate scene_id: {scene_id}")
+        scene_ids.add(scene_id)
+        if project_id and card.get("project_id") != project_id:
+            report.error(
+                "project_mismatch",
+                str(path),
+                f"Scene project_id must be {project_id!r}.",
+            )
+        location_tag = card.get("location_tag")
+        if location_tag and location_tag not in registry_tags:
+            report.error(
+                "unknown_asset_tag",
+                f"{path}.location_tag",
+                f"Tag is absent from production-bible.json: {location_tag}",
+            )
+        structure = card.get("structure")
+        if isinstance(structure, dict):
+            for key in ("goal", "obstacle", "tactic", "reversal", "audience_value_shift"):
+                if not structure.get(key):
+                    report.warn(
+                        "incomplete_scene_engine",
+                        f"{path}.structure.{key}",
+                        "Dramatic structure field is empty.",
+                    )
+    return scene_ids
+
+
+def validate_timed_blocks(
+    blocks: Any, duration: float, path: str, report: Report, label: str
+) -> None:
+    if not isinstance(blocks, list):
+        report.error("wrong_type", path, f"{label} must be a list.")
+        return
+    intervals: list[tuple[float, float, int, dict[str, Any]]] = []
+    for index, block in enumerate(blocks):
+        item_path = f"{path}[{index}]"
+        if not isinstance(block, dict):
+            report.error("wrong_type", item_path, "Timed block must be an object.")
+            continue
+        start = block.get("start_seconds")
+        end = block.get("end_seconds")
+        if not isinstance(start, (int, float)) or not isinstance(end, (int, float)):
+            report.error("invalid_timecode", item_path, "Start and end must be numbers.")
+            continue
+        if start < 0 or end <= start:
+            report.error("invalid_timecode", item_path, "Require 0 <= start < end.")
+        if end > duration:
+            report.error(
+                "timecode_overflow",
+                item_path,
+                f"End {end}s exceeds shot duration {duration}s.",
+            )
+        intervals.append((float(start), float(end), index, block))
+    if label == "Dialogue":
+        ordered = sorted(intervals)
+        for previous, current in zip(ordered, ordered[1:]):
+            if current[0] < previous[1] and not (
+                previous[3].get("allow_overlap") or current[3].get("allow_overlap")
+            ):
+                report.error(
+                    "dialogue_overlap",
+                    path,
+                    f"Dialogue items {previous[2]} and {current[2]} overlap without allow_overlap.",
+                )
+
+
+def validate_shot_cards(
+    paths: list[Path],
+    project_id: str,
+    scene_ids: set[str],
+    registry_tags: set[str],
+    report: Report,
+) -> set[str]:
+    shot_ids: set[str] = set()
+    for path in paths:
+        card = load_json(path, report)
+        if card is None:
+            continue
+        require_fields(
+            card,
+            [
+                "project_id",
+                "scene_id",
+                "shot_id",
+                "editorial_job",
+                "generation_mode",
+                "control_density",
+                "duration_seconds",
+                "active_assets",
+                "first_frame",
+                "final_state",
+            ],
+            str(path),
+            report,
+        )
+        if not isinstance(card, dict):
+            continue
+        shot_id = str(card.get("shot_id", ""))
+        if shot_id in shot_ids:
+            report.error("duplicate_shot_id", str(path), f"Duplicate shot_id: {shot_id}")
+        shot_ids.add(shot_id)
+        if project_id and card.get("project_id") != project_id:
+            report.error(
+                "project_mismatch", str(path), f"Shot project_id must be {project_id!r}."
+            )
+        scene_id = str(card.get("scene_id", ""))
+        if scene_ids and scene_id not in scene_ids:
+            report.error(
+                "unknown_scene_id", str(path), f"No scene card exists for {scene_id!r}."
+            )
+        mode = card.get("generation_mode")
+        if mode not in VALID_MODES:
+            report.error(
+                "invalid_generation_mode",
+                f"{path}.generation_mode",
+                f"Use one of: {', '.join(sorted(VALID_MODES))}.",
+            )
+        density = card.get("control_density")
+        if density not in VALID_DENSITIES:
+            report.error(
+                "invalid_control_density",
+                f"{path}.control_density",
+                f"Use one of: {', '.join(sorted(VALID_DENSITIES))}.",
+            )
+        duration = card.get("duration_seconds")
+        if not isinstance(duration, (int, float)) or duration <= 0:
+            report.error("invalid_duration", f"{path}.duration_seconds", "Use a positive number.")
+            duration_value = 0.0
+        else:
+            duration_value = float(duration)
+        if card.get("model") == "seedance-2.5" and duration_value and not 4 <= duration_value <= 30:
+            report.error(
+                "seedance_duration",
+                f"{path}.duration_seconds",
+                "Seedance 2.5 adapter expects 4-30 seconds per generation.",
+            )
+        assets = card.get("active_assets")
+        if isinstance(assets, list):
+            seen: set[str] = set()
+            for index, asset in enumerate(assets):
+                tag = asset.get("tag") if isinstance(asset, dict) else None
+                if not isinstance(tag, str) or not tag.startswith("@"):
+                    report.error(
+                        "invalid_asset_reference",
+                        f"{path}.active_assets[{index}]",
+                        "Every active asset needs a @tag.",
+                    )
+                    continue
+                if tag in seen:
+                    report.warn(
+                        "duplicate_asset_reference",
+                        f"{path}.active_assets[{index}]",
+                        f"Asset is listed more than once: {tag}",
+                    )
+                seen.add(tag)
+                if tag not in registry_tags:
+                    report.error(
+                        "unknown_asset_tag",
+                        f"{path}.active_assets[{index}]",
+                        f"Tag is absent from production-bible.json: {tag}",
+                    )
+        else:
+            report.error("wrong_type", f"{path}.active_assets", "Expected a list.")
+        if "action_timing" in card and duration_value:
+            validate_timed_blocks(
+                card["action_timing"], duration_value, f"{path}.action_timing", report, "Action"
+            )
+        dialogue = card.get("dialogue", [])
+        if dialogue and duration_value:
+            validate_timed_blocks(
+                dialogue, duration_value, f"{path}.dialogue", report, "Dialogue"
+            )
+    return shot_ids
+
+
+def validate_continuity(
+    path: Path, project_id: str, shot_ids: set[str], report: Report
+) -> None:
+    if not path.exists():
+        report.warn(
+            "missing_continuity_ledger",
+            str(path),
+            "Add continuity-ledger.json before generating a multi-shot sequence.",
+        )
+        return
+    ledger = load_json(path, report)
+    if ledger is None:
+        return
+    require_fields(ledger, ["project_id", "entries"], str(path), report)
+    if not isinstance(ledger, dict):
+        return
+    if project_id and ledger.get("project_id") != project_id:
+        report.error(
+            "project_mismatch", str(path), f"Ledger project_id must be {project_id!r}."
+        )
+    entries = ledger.get("entries")
+    if not isinstance(entries, list):
+        report.error("wrong_type", f"{path}.entries", "Expected a list.")
+        return
+    ledger_ids: set[str] = set()
+    for index, entry in enumerate(entries):
+        item_path = f"{path}.entries[{index}]"
+        require_fields(entry, ["shot_id", "entering", "leaving", "handoff_proof"], item_path, report)
+        if not isinstance(entry, dict):
+            continue
+        shot_id = str(entry.get("shot_id", ""))
+        if shot_id in ledger_ids:
+            report.error("duplicate_ledger_entry", item_path, f"Duplicate shot_id: {shot_id}")
+        ledger_ids.add(shot_id)
+        if shot_ids and shot_id not in shot_ids:
+            report.error("unknown_shot_id", item_path, f"No shot card exists for {shot_id!r}.")
+    missing = shot_ids - ledger_ids
+    for shot_id in sorted(missing):
+        report.warn(
+            "missing_ledger_entry",
+            str(path),
+            f"Shot has no explicit entering/leaving handoff: {shot_id}",
+        )
+
+
+def render_text(report: Report, package: Path, counts: dict[str, int]) -> str:
+    lines = [f"Kolbo Filmmaker package: {package}"]
+    lines.append(
+        "Validated "
+        + ", ".join(f"{value} {key}" for key, value in counts.items())
+        + "."
+    )
+    for item in report.items:
+        lines.append(
+            f"[{item['level'].upper()}] {item['code']} - {item['path']}: {item['message']}"
+        )
+    lines.append(f"Result: {report.error_count} error(s), {report.warning_count} warning(s).")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("package", type=Path, help="Production package folder")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    args = parser.parse_args()
+
+    package = args.package.resolve()
+    report = Report()
+    if not package.is_dir():
+        report.error("missing_package", str(package), "Package folder does not exist.")
+        counts = {"scene card(s)": 0, "shot card(s)": 0, "registered tag(s)": 0}
+    else:
+        bible_path = package / "production-bible.json"
+        bible = load_json(bible_path, report)
+        project_id, tags = validate_bible(bible, bible_path, report) if bible is not None else ("", set())
+        scene_paths = json_files(package / "scene-cards")
+        shot_paths = json_files(package / "shot-cards")
+        if not scene_paths:
+            report.warn("no_scene_cards", str(package / "scene-cards"), "No scene cards found.")
+        if not shot_paths:
+            report.warn("no_shot_cards", str(package / "shot-cards"), "No shot cards found.")
+        scene_ids = validate_scene_cards(scene_paths, project_id, tags, report)
+        shot_ids = validate_shot_cards(shot_paths, project_id, scene_ids, tags, report)
+        validate_continuity(package / "continuity-ledger.json", project_id, shot_ids, report)
+        counts = {
+            "scene card(s)": len(scene_paths),
+            "shot card(s)": len(shot_paths),
+            "registered tag(s)": len(tags),
+        }
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "package": str(package),
+                    "valid": report.error_count == 0,
+                    "counts": counts,
+                    "errors": report.error_count,
+                    "warnings": report.warning_count,
+                    "items": report.items,
+                },
+                indent=2,
+                ensure_ascii=False,
+            )
+        )
+    else:
+        print(render_text(report, package, counts))
+    return 1 if report.error_count else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apps/index.js

@@ -321,6 +321,26 @@ function pickForType(candidates, types) {
   return pool.reduce((a, b) => (b.id.length < a.id.length ? b : a)).id;
 }
 
+// Strip modality tokens so a t2v id and its i2v sibling share one family key
+// (grok-imagine-text-to-video ↔ grok-imagine-image-to-video; kling …/text-to-video
+// ↔ …/image-to-video). Version tokens stay (1.5 ≠ 1.0).
+function fam(s) {
+  return normId(s).replace(
+    /texttovideo|imagetovideo|imgtovideo|texttoimage|imagetoimage|imageediting|imageedit|referencetovideo|videotovideo|videoedit|editvideo|firstlastframe|firstlast/g,
+    '',
+  );
+}
+
+function sibling(models, hit, types) {
+  if (!hit || !types.length) return hit;
+  const row = models.find((i) => i.id === hit);
+  if (row && row.types.some((t) => types.includes(t))) return hit;
+  const key = fam(hit);
+  const sibs = models.filter((i) => fam(i.id) === key && i.types.some((t) => types.includes(t)));
+  if (!sibs.length) return hit;
+  return sibs.reduce((a, b) => (b.id.length < a.id.length ? b : a)).id;
+}
+
 /**
  * Lenient model-identifier resolution for LLM-supplied model args.
  * Users say "z-image"; the real identifier is "z-image/turbo" — the backend
@@ -334,6 +354,9 @@ function pickForType(candidates, types) {
  * without it, "Kling 2.6 Pro" from generate_video_from_image resolved to
  * kling-video/v2.6/pro/text-to-video (2026-08-10), so the image-to-video
  * pipeline submitted the TEXT-to-video endpoint and billed against it.
+ * An explicit t2v identifier on an i2v tool remaps to the unique same-family
+ * sibling (grok-imagine-text-to-video → grok-imagine-image-to-video). No
+ * sibling → the id is passed through unchanged (MiniMax H3).
  *
  * Still unresolved: throw with the near misses named. The API answers a bad
  * identifier with a bare INVALID_*_MODEL and no hint, which on 2026-08-09 sent
@@ -362,13 +385,13 @@ async function canonicalModelId(client, input, type) {
   const dashed = key.replace(/\s+/g, '-');
 
   // 1. exact name / identifier hit
-  const exact = pickForType(models.filter((i) => [i.id, i.name].some(
+  const exact = sibling(models, pickForType(models.filter((i) => [i.id, i.name].some(
     (k) => k && (k.toLowerCase() === key || k.toLowerCase() === dashed)
-  )), types);
+  )), types), types);
   if (exact) return exact;
 
   // 2. separator-insensitive exact ("flux-2-flash" → "flux-2/flash")
-  const loose = pickForType(models.filter((i) => normId(i.id) === want || normId(i.name) === want), types);
+  const loose = sibling(models, pickForType(models.filter((i) => normId(i.id) === want || normId(i.name) === want), types), types);
   if (loose) return loose;
 
   // 3. unique prefix ("z-image" → "z-image/turbo") — the modality filter runs

package/src/index.js

@@ -76,8 +76,8 @@ const { registerReviewTools } = require('./tools/review');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
-const { registerApps, attachToolWidgetMeta } = require('./apps');
-const { attachToolAnnotations } = require('./toolAnnotations');
+const { registerApps, attachToolWidgetMeta } = require('./apps');
+const { attachToolAnnotations } = require('./toolAnnotations');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -126,9 +126,9 @@ function createServer(opts = {}) {
       '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
       '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly; all Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
-      '9. MODEL SELECTION — ROUTE BY THE STRENGTHS SUMMARY, NEVER BY THE BADGE OR THE PRICE TAG: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). To choose: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost. That summary IS the routing instruction: match it against what the user actually asked for (subject, style, motion, length, quality bar, speed), then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
-      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
-      '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'
+      '9. MODEL SELECTION — NAMED MODEL WINS, THEN STRENGTHS SUMMARY: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). If the user named a model this turn OR earlier in the conversation (including a compaction "Locked choices" / summary), that name is a FAMILY LOCK: pass it (or its display name) on every follow-up, including when the tool changes (text-to-video → image-to-video). Identifier resolution remaps a t2v id to the family\'s i2v sibling automatically. NEVER substitute a different brand because it is cheaper, faster, or "best balance" (Grok Imagine named → do not fire Seedance). If the named family has no variant for this modality, ASK — do not silently switch. Cheapest-summary routing applies ONLY when no model was named on this task: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost — then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
+      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
+      '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'
     ].join('\n')
   });
   const progress = require('./progress');
@@ -173,12 +173,12 @@ function createServer(opts = {}) {
   // transport. Without it, a remote-connector model reads "absolute local path",
   // sees no filesystem, and tells the user Kolbo cannot accept their file —
   // the single most-reported failure, despite the upload tools existing.
-  attachFileInputHints(server, toolOptions);
-  // OpenAI public-app review requires every exposed tool to declare the three
-  // safety hints explicitly. The exact contract also fails closed when a tool
-  // is added or removed without a classification.
-  attachToolAnnotations(server);
-  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
+  attachFileInputHints(server, toolOptions);
+  // OpenAI public-app review requires every exposed tool to declare the three
+  // safety hints explicitly. The exact contract also fails closed when a tool
+  // is added or removed without a classification.
+  attachToolAnnotations(server);
+  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
   // claude.ai prepares the widget iframe from tools/list, not from the result.
   attachToolWidgetMeta(server);
 

package/src/install.js

@@ -16,6 +16,8 @@ const path = require('path');
 const os = require('os');
 
 const KOLBO_ENTRY = { command: 'npx', args: ['-y', '@kolbo/mcp@latest'] };
+const MANAGED_FILE = '.kolbo-managed.json';
+const PACKAGE_VERSION = require('../package.json').version;
 
 function targets() {
   const home = os.homedir();
@@ -78,6 +80,7 @@ function skillTargets() {
   return [
     { name: 'Claude Code skill', root: path.join(home, '.claude'), dir: path.join(home, '.claude', 'skills', 'kolbo') },
     { name: 'Agents skill (Cursor/Codex)', root: path.join(home, '.agents'), dir: path.join(home, '.agents', 'skills', 'kolbo') },
+    { name: 'Kolbo Code skill', root: path.join(home, '.kolbo'), dir: path.join(home, '.kolbo', 'skills', 'kolbo') },
   ];
 }
 
@@ -85,15 +88,45 @@ function installSkill(t) {
   const src = path.join(__dirname, '..', 'skill');
   if (!fs.existsSync(src)) return { ...t, status: 'skill not bundled' };
   if (!fs.existsSync(t.root)) return { ...t, status: 'not found' };
+  const tmp = `${t.dir}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
   try {
-    fs.mkdirSync(t.dir, { recursive: true });
-    fs.cpSync(src, t.dir, { recursive: true });
+    // Replace the generated tree so source deletions propagate too. A simple
+    // recursive copy leaves obsolete references behind indefinitely.
+    fs.rmSync(tmp, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(t.dir), { recursive: true });
+    fs.cpSync(src, tmp, { recursive: true });
+    fs.writeFileSync(path.join(tmp, MANAGED_FILE), JSON.stringify({
+      source: '@kolbo/mcp',
+      skill: 'kolbo',
+      version: fs.readFileSync(path.join(src, 'VERSION'), 'utf8').trim(),
+      packageVersion: PACKAGE_VERSION,
+    }, null, 2) + '\n');
+    fs.rmSync(t.dir, { recursive: true, force: true });
+    fs.renameSync(tmp, t.dir);
     return { ...t, status: 'installed' };
   } catch (e) {
+    fs.rmSync(tmp, { recursive: true, force: true });
     return { ...t, status: `failed — ${e.message}` };
   }
 }
 
+// Local MCP launches refresh only installs created by Kolbo. A manually
+// authored `kolbo` skill without the marker is never overwritten.
+function refreshManagedSkills() {
+  return skillTargets().map((t) => {
+    const marker = path.join(t.dir, MANAGED_FILE);
+    if (!fs.existsSync(marker)) return { ...t, status: 'unmanaged' };
+    try {
+      const installed = JSON.parse(fs.readFileSync(marker, 'utf8'));
+      const skillVersion = fs.readFileSync(path.join(__dirname, '..', 'skill', 'VERSION'), 'utf8').trim();
+      if (installed.packageVersion === PACKAGE_VERSION && installed.version === skillVersion) {
+        return { ...t, status: 'current' };
+      }
+    } catch (_) {}
+    return installSkill(t);
+  });
+}
+
 // Versions before this fix wrote the Claude Code entry into
 // ~/.claude/settings.json, where Claude Code silently ignores it. Anyone who ran
 // those is left with a dead entry that makes it look configured. Detect and say
@@ -156,4 +189,30 @@ async function run() {
   return 0;
 }
 
-module.exports = { run };
+async function runSkillOnly() {
+  const out = (s = '') => process.stdout.write(s + '\n');
+  const skills = skillTargets().map(installSkill);
+  const ready = skills.filter((s) => s.status === 'installed');
+
+  out();
+  out('  Kolbo Skill — standalone install');
+  out('  ────────────────────────────────');
+  for (const s of skills) {
+    out(`  ${s.status === 'installed' ? '✓' : '·'} ${s.name}: ${s.status}`);
+  }
+  out();
+
+  if (ready.length === 0) {
+    out('  No supported skill directory found (.claude or .agents).');
+    out('  Install or open a compatible agent, then run this command again.');
+    out();
+    return 0;
+  }
+
+  out('  Done — the Kolbo Skill is installed.');
+  out('  MCP settings were not changed. Restart your agent to load the skill.');
+  out();
+  return 0;
+}
+
+module.exports = { run, runSkillOnly, refreshManagedSkills, MANAGED_FILE };

package/src/tools/generate.js

@@ -438,7 +438,7 @@ function registerGenerateTools(server, client, options = {}) {
     {
       prompt: z.string().optional().describe('Text description of the video to generate. Required unless `prompts` is provided.'),
       prompts: promptsField('videos'),
-      model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "seedance-2" (versatile) or "veo3" (Veo 3.1, cinematic + native audio); the Kling family (call list_models for exact ids like kling-video/v3/pro/text-to-video) is strongest for motion. Call list_models type="text_to_video" to see all options + check supported_durations / supported_aspect_ratios, and choose per the user\'s intent.'),
+      model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). If the user already named a model/family (this turn or earlier), pass that name — do not substitute a cheaper default. Only when no model was named: "seedance-2" (versatile) or "veo3" (cinematic + native audio) are reasonable auto-picks; Kling is strongest for motion (list_models type="text_to_video" for exact ids). Call list_models for supported_durations / supported_aspect_ratios.'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
       duration: z.number().optional().describe('Duration in seconds. Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration` (whichever the model exposes). Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
@@ -520,7 +520,7 @@ function registerGenerateTools(server, client, options = {}) {
       })).max(MAX_BATCH_PROMPTS).optional().describe(
         `BATCH MODE — several DIFFERENT stills (2–${MAX_BATCH_PROMPTS}) animated concurrently in ONE call and rendered together in ONE combined widget. Unlike the \`prompts\` array on generate_image / generate_video, each entry pairs its OWN \`image_url\` with its OWN motion \`prompt\` — the image is what varies, and that is the point. **Hard cap: ${MAX_BATCH_PROMPTS} items per call — more than that is REJECTED with an error (never silently truncated), so split a longer sequence across several calls of at most ${MAX_BATCH_PROMPTS}.** Whenever the user wants several stills animated (a shot sequence, a storyboard, an animatic), ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All items share the same model / duration / resolution / aspect_ratio / sound_enabled / project_id / session_id. When set, \`image_url\` and \`prompt\` are ignored.`
       ),
-      model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "seedance-2" (versatile) or "veo3" (Veo 3.1, cinematic + native audio); the Kling family (call list_models for exact ids like kling-video/v3/pro/image-to-video) is strongest for motion. Call list_models type="img_to_video" to see all options and choose per the user\'s intent.'),
+      model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). If the user already named a model/family (this turn or earlier), pass that name — a text-to-video id remaps to the family\'s image-to-video sibling. Do not substitute a cheaper default (named Grok Imagine → not Seedance). Only when no model was named: "seedance-2" or "veo3" are reasonable auto-picks; Kling is strongest for motion (list_models type="img_to_video" for exact ids).'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
       duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the motion prompt. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),