@kolbo/mcp 1.70.1 → 1.70.3

package/README.md

@@ -51,7 +51,7 @@ Or add the config by hand — this block is identical for every MCP client and c
 
 | Client | Where the config goes |
 |--------|----------------------|
-| **Claude Code** | `.claude/settings.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
+| **Claude Code** | `~/.claude.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
 | **Claude Desktop** | `claude_desktop_config.json` |
 | **Cursor** | `.cursor/mcp.json` |
 | **Kolbo Code** | configured automatically on `kolbo auth login` |
@@ -67,15 +67,15 @@ No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** un
 The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:
 
 ```bash
-# Claude Code (also writes the MCP config for you, so you can skip Step 2 above)
-claude plugin marketplace add Zoharvan12/kolbo-skills
-claude plugin install kolbo@kolbo-skills
+# Claude Code plugin (canonical skill + MCP configuration)
+claude plugin marketplace add Zoharvan12/kolbo-claude-plugin
+claude plugin install kolbo@kolbo
 
-# Cursor / Codex / any agent (cross-agent installer)
-npx skills add Zoharvan12/kolbo-skills
+# Skill only — installs the bundled official skill without changing MCP settings
+npx -y @kolbo/mcp@latest skill
 ```
 
-The skill content is the same canonical routing logic that ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
+The skill-only command installs the canonical single `kolbo` skill and does not change MCP configuration. The Claude Code plugin and `npx -y @kolbo/mcp install` routes configure MCP as well. Official installer-created skill folders are marked as Kolbo-managed and refresh automatically when the MCP server starts on a newer package; unmarked or hand-authored folders are never overwritten. The canonical skill ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
 
 ### Use it
 

package/bin/kolbo-mcp.js

@@ -1,15 +1,24 @@
 #!/usr/bin/env node
 
-// `npx @kolbo/mcp install` → one-command keyless setup (configures the user's
-// agent). Anything else → run the MCP stdio server (the default).
-if (process.argv[2] === 'install') {
-  require('../src/install.js')
-    .run()
+// Installer commands are additive aliases on the same public package:
+//   `npx @kolbo/mcp install`       → MCP configuration + bundled skill
+//   `npx @kolbo/mcp skill`         → bundled skill only
+//   `npx @kolbo/mcp install-skill` → readable alias for skill-only
+// Anything else runs the MCP stdio server (the default).
+const command = process.argv[2];
+if (command === 'install' || command === 'skill' || command === 'install-skill') {
+  const installer = require('../src/install.js');
+  const run = command === 'install' ? installer.run : installer.runSkillOnly;
+  run()
     .then((code) => process.exit(code || 0))
     .catch((err) => {
       console.error('Kolbo install failed:', err && err.message ? err.message : err);
       process.exit(1);
     });
 } else {
+  // Keep official managed skill installs on the exact tree bundled with the
+  // MCP package selected by `@latest`. Unmanaged/user-authored skills are left
+  // alone. This is silent because stdout belongs to the MCP JSON transport.
+  require('../src/install.js').refreshManagedSkills();
   require('../src/index.js');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.70.1",
+  "version": "1.70.3",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -9,8 +9,9 @@
   "scripts": {
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
+    "check-skill-bundle": "node scripts/check-skill-bundle.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-submission-contract.js && node scripts/check-install.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-skill-bundle.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-submission-contract.js && node scripts/check-install.js",
     "check-model-catalog": "node scripts/check-model-catalog.js",
     "check-widget-fields": "node scripts/check-widget-fields.js",
     "check-widget-render": "node scripts/check-widget-render.js",

package/skill/GENERATED.md

@@ -1,8 +1,7 @@
 # AUTO-GENERATED — do not edit
 
-This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@3a7950b.
+This tree is mirrored from kolbo-code@0fbb0ce, the single source of truth.
+Canonical source: packages/opencode/skills/kolbo/
+Distribution: .github/workflows/sync-skill-to-plugin.yml
 
-It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
-To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;
-this workflow re-mirrors the whole tree here. Hand-edits here are overwritten.
+Both 'npx -y @kolbo/mcp@latest skill' and the combined 'install' command deploy it.

package/skill/SKILL.md

@@ -1,21 +1,14 @@
 ---
-version: 0.7.5
+version: 0.8.1
 name: kolbo
 description: |
-  Generate, edit, or analyze creative media via the Kolbo AI MCP server:
-  images (GPT Image, Nano Banana, Flux), video (Seedance, Veo, Kling, Hailuo),
-  music (Suno), TTS (ElevenLabs), 3D, transcription, Visual DNA (character
-  consistency), Marketing Studio (UGC + DTC ads + product photoshoot +
-  marketplace cards), Creative Director (multi-scene batches), HTML artifact
-  publishing (presentations, landing pages, dashboards), AI Docs (project
-  documents you author and share).
-
-  Use when the user wants to generate, create, make, edit, animate, or
-  transcribe media: images, video, music, voice/TTS, sound effects, 3D models,
-  UGC or TV-spot ads, product / lifestyle / hero shots, Amazon or marketplace
-  listings, presentations, landing pages, or dashboards;
-  to reuse a character or brand (Visual DNA, brand kits); or to save a written
-  plan / brief / script / research into a Kolbo project (AI Docs).
+  Generate, edit, analyze, and direct creative media through Kolbo AI: images,
+  video (Seedance, Veo, Kling, Hailuo), music, speech, sound, 3D, transcription,
+  Visual DNA, Creative Director batches, marketing assets, HTML artifacts, and
+  AI Docs. Use for sophisticated AI filmmaking as well as individual media:
+  scripts, production bibles, recurring characters and locations, acting,
+  dialogue, music performance, blocking, physics, multi-shot continuity,
+  connected scenes, prompt audits, and feature-length production planning.
 
   NOT for: video editing / FFmpeg (use video-production), motion graphics
   (use remotion-best-practices), code editing, or general chat.
@@ -64,8 +57,9 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 
 | If the user wants to… | Read first |
 |---|---|
-| Generate a **Seedance 2** video | `references/models/seedance.md` |
-| Generate a **Seedance 2.5** video | `references/models/seedance25.md` (also load `seedance.md` for the locked intro + craft layer) |
+| Direct, develop, audit, or continue a **film / episode / connected scene / complex performance** with continuity, acting, dialogue, music, blocking, or physics | `references/workflows/filmmaking.md` |
+| Generate a **Seedance 2.5** video | `references/models/seedance25.md`; also load `references/workflows/filmmaking.md` for narrative, performance, or cross-shot continuity |
+| Generate a **Seedance 2 / 2.0** video | `references/models/seedance.md` |
 | Generate a **GPT Image 2** image | `references/models/gpt-image.md` |
 | Generate a **Nano Banana / Gemini** image | `references/models/nano-banana.md` |
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
@@ -166,7 +160,6 @@ A user-named tool — in any language — overrides every other rule. Recognized
    - User named one → use it. Model identifiers resolve leniently — shorthand like `"z-image"` or `"nano banana 2"` auto-resolves to the exact identifier, so don't over-engineer exact-id lookups (`list_models` is still authoritative for constraints, caps, and pricing).
    - Auto-select → only from "Auto-selectable" section (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
    - Never auto-select from "Named-only" section.
-   - **Photoreal photo edits** (object removal, keep one person / remove the crowd, inpainting, "edit this photo") → `generate_image_edit` with **Nano Banana 2** or **GPT Image 2** only. Do not auto-pick Flux 2 / Flux Klein — those are generate-from-scratch / style, named-only for editing.
 4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
 5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` instantly — the card updates on its own; you only need `get_generation_status` when a follow-up step needs the output URLs.
 6. **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. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.

package/skill/VERSION

@@ -1 +1 @@
-0.7.5
+0.8.1

package/skill/assets/filmmaking/continuity-ledger.template.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0",
+  "project_id": "EXAMPLE",
+  "sequence_id": "EXAMPLE_SEQ001",
+  "global_locks": {
+    "screen_direction": "Movement toward the north platform is screen-left to screen-right.",
+    "time_and_light": "Continuous pre-dawn; blue ambient light slowly increases.",
+    "weather": "Heavy rain continues without interruption.",
+    "base_ambience": "Rain, current, distant station alarms."
+  },
+  "entries": [
+    {
+      "shot_id": "EXAMPLE_SC001_SH001",
+      "entering": {
+        "character_state": "Mara base state; dry above knees; no hand injury.",
+        "prop_state": "Medicine case sealed in left hand.",
+        "positions": "Mara at south entrance, platform ahead frame right."
+      },
+      "leaving": {
+        "character_state": "Mara waist-down soaked, stopped mid-concourse.",
+        "prop_state": "Medicine case sealed in left hand.",
+        "positions": "Mara body aimed right, looking left toward kiosk."
+      },
+      "handoff_proof": "Final selected frame must preserve body direction, gaze, hand ownership, and case seal."
+    }
+  ]
+}

package/skill/assets/filmmaking/generation-log.template.csv

@@ -0,0 +1,2 @@
+project_id,scene_id,shot_id,prompt_version,attempt,model,generation_mode,control_density,change_owner,change_summary,expected_proof,result_uri,verdict,selected_take,qc_notes,timestamp_utc
+EXAMPLE,EXAMPLE_SC001,EXAMPLE_SC001_SH001,p001,1,seedance-2.5,reference-to-video,anchored,baseline,initial compiled prompt,"geography readable; Mara ends looking left; case remains sealed",,pending,false,,

package/skill/assets/filmmaking/production-bible.template.json

@@ -0,0 +1,97 @@
+{
+  "schema_version": "1.0",
+  "project_id": "EXAMPLE",
+  "title": "Example Film",
+  "format": {
+    "type": "short",
+    "runtime_target_minutes": 3,
+    "primary_aspect_ratio": "16:9",
+    "delivery_fps": 24
+  },
+  "story": {
+    "logline": "A courier must cross a flooded city before the last evacuation train leaves.",
+    "story_goal": "Deliver the medicine and escape before dawn.",
+    "genre": [
+      "survival drama"
+    ],
+    "tone": [
+      "intimate",
+      "urgent",
+      "grounded"
+    ]
+  },
+  "world_rules": [
+    "Water obeys realistic mass, drag, and buoyancy.",
+    "Technology is contemporary and visibly weathered."
+  ],
+  "visual_worlds": [
+    {
+      "id": "world_flooded_dawn",
+      "palette": "cool blue-grey with warm emergency-light accents",
+      "texture": "wet concrete, rain, practical haze",
+      "capture_language": "large-format naturalism, restrained handheld"
+    }
+  ],
+  "characters": [
+    {
+      "id": "char_mara",
+      "canonical_tag": "@char_EXAMPLE_mara_base_v1",
+      "identity_anchors": [
+        "short black curls",
+        "scar through left eyebrow",
+        "yellow rain shell"
+      ],
+      "performance_profile": "Contained urgency; she masks fear by solving practical problems.",
+      "voice_lock": "Low mezzo, clipped phrasing under stress, never theatrical.",
+      "states": [
+        {
+          "id": "mara_soaked",
+          "tag": "@char_EXAMPLE_mara_soaked_v1",
+          "changes": [
+            "rain shell soaked and darker",
+            "small cut on right palm"
+          ]
+        }
+      ]
+    }
+  ],
+  "locations": [
+    {
+      "id": "loc_station_concourse",
+      "canonical_tag": "@loc_EXAMPLE_station_concourse_v1",
+      "geography": "Entrance south, ticket hall center, platforms north, service stairs east.",
+      "light_lock": "Pre-dawn blue through broken roof; amber emergency fixtures.",
+      "states": []
+    }
+  ],
+  "assets": [
+    {
+      "id": "prop_medicine_case",
+      "tag": "@prop_EXAMPLE_medicine_case_v1",
+      "type": "hero_prop",
+      "continuity_lock": "Silver hard case, black handle, red medical seal intact until scene 08."
+    }
+  ],
+  "audio_policy": {
+    "dialogue": "Generate performance dialogue in-shot when model capability is verified.",
+    "music": "Use post-score by default; native source music only when it drives visible timing.",
+    "ambience": "Rain, distant alarms, water movement, structural creaks.",
+    "subtitle_policy": "No generated subtitles or on-screen text."
+  },
+  "model_adapters": {
+    "default": "seedance-2.5",
+    "verified_at": "2026-08-15",
+    "notes": "Re-verify live limits before a costly production batch."
+  },
+  "naming_policy": {
+    "shot_id_pattern": "EXAMPLE_SC###_SH###",
+    "asset_tag_pattern": "@type_PROJECT_subject_state_v#",
+    "prompt_version_pattern": "p###"
+  },
+  "approval": {
+    "story_locked": false,
+    "visual_world_locked": false,
+    "character_assets_locked": false,
+    "production_ready": false
+  }
+}

package/skill/assets/filmmaking/scene-card.template.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "1.0",
+  "project_id": "EXAMPLE",
+  "scene_id": "EXAMPLE_SC001",
+  "title": "The Last Platform",
+  "slugline": "INT. FLOODED STATION CONCOURSE - PRE-DAWN",
+  "story_job": "Force Mara to choose between speed and helping a stranded child.",
+  "structure": {
+    "goal": "Reach the north platform before the evacuation train departs.",
+    "obstacle": "Floodwater blocks the direct route and a child is trapped on a kiosk.",
+    "tactic": "Use a floating bench as a bridge while pulling the child across.",
+    "reversal": "The medicine case slips into the current.",
+    "audience_value_shift": "Efficient escape becomes a costly moral commitment."
+  },
+  "shared_event": "Mara rescues the child and loses control of the medicine case.",
+  "acting_direction": {
+    "mara": "Keep the child calm while privately calculating whether the rescue will cost both lives."
+  },
+  "location_tag": "@loc_EXAMPLE_station_concourse_v1",
+  "entering_state": {
+    "mara": "Dry above the knees; right palm uninjured; medicine case sealed in left hand.",
+    "environment": "Water waist-high at the center aisle, flowing east to west."
+  },
+  "geography": {
+    "screen_direction": "Mara advances screen-left to screen-right toward the north platform.",
+    "axis": "Primary axis runs south entrance to north platforms.",
+    "fixed_landmarks": [
+      "kiosk on west wall",
+      "service stairs on east wall"
+    ]
+  },
+  "audio_bed": "Rain on broken roof, waist-deep current, distant departure alarm.",
+  "coverage_plan": [
+    "wide geography master",
+    "Mara-child performance two-shot",
+    "case-loss action insert",
+    "reaction close-up"
+  ],
+  "unresolved_questions": []
+}

package/skill/assets/filmmaking/shot-card.template.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": "1.0",
+  "project_id": "EXAMPLE",
+  "scene_id": "EXAMPLE_SC001",
+  "shot_id": "EXAMPLE_SC001_SH001",
+  "editorial_job": "Establish the flooded geography and Mara's route to the platform.",
+  "dramatic_beat": "Mara sees the stranded child but initially keeps moving.",
+  "model": "seedance-2.5",
+  "generation_mode": "reference-to-video",
+  "control_density": "anchored",
+  "duration_seconds": 8,
+  "aspect_ratio": "16:9",
+  "active_assets": [
+    {
+      "tag": "@char_EXAMPLE_mara_base_v1",
+      "role": "Mara",
+      "state": "base"
+    },
+    {
+      "tag": "@loc_EXAMPLE_station_concourse_v1",
+      "role": "station concourse",
+      "state": "flooded pre-dawn"
+    },
+    {
+      "tag": "@prop_EXAMPLE_medicine_case_v1",
+      "role": "medicine case",
+      "state": "sealed"
+    }
+  ],
+  "first_frame": "Wide at waist height. Mara enters frame left, medicine case in her left hand; north platform signs sit deep frame right.",
+  "blocking": "Mara pushes left-to-right through waist-high water. She notices the child off-screen west, checks the platform clock, and takes one more step before stopping.",
+  "camera": {
+    "framing": "wide moving master",
+    "movement": "slow lateral tracking move matching Mara",
+    "lens_language": "natural wide perspective, rectilinear",
+    "camera_side": "east side of the south-north axis"
+  },
+  "eyelines": {
+    "mara": "first toward platform frame right, then sharply off-screen left toward the child"
+  },
+  "action_timing": [
+    {
+      "start_seconds": 0,
+      "end_seconds": 4,
+      "beat": "Mara advances toward the platform."
+    },
+    {
+      "start_seconds": 4,
+      "end_seconds": 8,
+      "beat": "She hears the child, looks left, hesitates, and stops."
+    }
+  ],
+  "acting_tasks": {
+    "mara": "Reach the train without acknowledging the plea; when it becomes impossible to ignore, hide the cost of stopping."
+  },
+  "dialogue": [],
+  "audio_lane": {
+    "dialogue": "none",
+    "source_music": "none",
+    "ambience": "rain, moving floodwater, distant departure alarm",
+    "post_music": "optional restrained pulse added in edit"
+  },
+  "physics": "Water resistance slows each step and pushes fabric westward. The medicine case has visible weight and remains above water.",
+  "lighting": "Pre-dawn blue roof light with warm amber practicals; wet reflections remain physically motivated.",
+  "final_state": "Mara is stationary mid-concourse, body aimed right but eyes and head turned left; case still sealed in left hand.",
+  "edit": {
+    "in": "Hard cut from exterior rain.",
+    "out": "Cut on Mara's look toward the child."
+  },
+  "prompt_version": "p001",
+  "status": "draft"
+}

package/skill/references/filmmaking/acting-direction.md

@@ -0,0 +1,131 @@
+# Acting Direction
+
+Direct behavior under pressure. Give performers playable work; let emotion emerge as a consequence.
+
+## Order of work
+
+### 1. Read the complete dramatic unit
+
+Read the whole exchange and its ending before directing a line. The ending often reveals what the event actually was.
+
+### 2. Name one shared event/direction
+
+Find the unspoken process all present characters inhabit, including silent listeners. The physical activity—packing, driving, cleaning, waiting, fighting—is the terrain through which the event moves, not necessarily the event itself.
+
+### 3. Give each character different fuel
+
+For every present character, define:
+
+- **Motive:** why this person pushes the shared direction.
+- **Goal:** what this person wants from a specific partner now.
+- **Obstacle/stakes:** what resists and what one crack costs.
+- **Tactic:** what the person actively does to the partner to get it.
+- **Physical channel/business:** what the body/hands are doing while pursuing it.
+- **Listener task:** what the person checks, measures, decides, hides, or waits for while not speaking.
+
+Use action verbs: convince, expose, disarm, charm, shame, protect, test, provoke, recruit, delay, conceal, reassure.
+
+### 4. Change tactics at beats
+
+When a tactic fails or new information lands, change the action. Make the beat change filmable through timing, posture, distance, speech rhythm, interrupted business, or gaze target.
+
+### 5. Preserve two truths
+
+For important close performance, hold a contradiction: helps while resenting it, jokes while begging, threatens while seeking approval, stays calm while testing whether escape is possible. Avoid a single clean emotion.
+
+## Acting task block
+
+Use a compact form for strict prompts:
+
+```text
+ACTING TASK — <character>
+Shared direction: <unspoken scene vector>
+Motive / goal / obstacle: <fuel, fight, pressure>
+Tactic: <playable action toward partner>
+Physical channel: <business and body rhythm>
+Moment to moment: <dialogue/beat → tactic and listener check>
+```
+
+Do not paste theory into the prompt. Convert it into actions the model can show.
+
+## Eyes and listening
+
+Treat the eyes as purposeful work, not decoration:
+
+- check whether a point landed;
+- search both eyes for trust;
+- compare words with hands or exits;
+- steal a look and return before discovery;
+- let the eyes reach the new target just before the head;
+- react before the partner finishes when comprehension arrives mid-line.
+
+Use natural blink/gaze continuity as a minimal AI safety layer. Do not try to create acting by choreographing endless eyebrow, mouth, and blink commands. Task first; micro-life second.
+
+Never solve dead eyes only with catchlights. Lighting can reveal eyes but cannot give them intention.
+
+## Physical life
+
+Define what matters for the shot:
+
+- center of gravity and body weight;
+- tempo and economy;
+- breath consistent with exertion and pressure;
+- openness/closure and status behavior;
+- proxemic distance and motivated changes;
+- physical business and the moment it stops.
+
+The interrupted-action beat is strong punctuation: hands stop because something became an event.
+
+## Character master profile
+
+Create one durable performance profile for recurring characters:
+
+- body as biography;
+- core behavioral engine;
+- voice identity;
+- signature habit with trigger;
+- stress/concealment behavior;
+- default mask and exact crack condition;
+- gait/movement grammar;
+- chosen stillness versus fidget behavior;
+- one softening target when dramatically useful.
+
+Keep wardrobe, camera, grade, and scene-specific blocking outside the master profile.
+
+Adapt the profile per scene. Transform impossible behaviors rather than deleting their energy: pacing may become wrist-flicks or micro-sway when seated.
+
+## Voice identity
+
+Keep vocal identity stable across shots:
+
+```text
+age register + origin/accent + pitch/timbre + pace + habitual delivery + pressure behavior
+```
+
+Change the scene's tactic and intensity without casually rewriting the voice identity. Name phonetic markers only when needed and when the production has permission to use the voice/likeness.
+
+## Dialogue performance
+
+- Give exact words to one speaker.
+- Separate voice identity from scene delivery.
+- Give listeners active tasks.
+- Preserve breath and emotional carry across cuts.
+- Let pauses contain assessment, decision, or refusal; remove empty pauses.
+- Keep reaction timing connected to the partner's line, not delayed by default.
+- In tight close-ups, reduce external behavior and let intention, breath, and eyes carry the beat.
+
+## Audit failures
+
+Flag:
+
+- emotion labels without playable action;
+- one tactic across the whole scene;
+- waiting-for-cue faces;
+- synchronized ensemble reactions;
+- gesture illustrating the spoken word;
+- free tears/rage without pressure or trigger;
+- dead pauses;
+- emotional reset between beats/shots;
+- voice identity drift;
+- facial choreography that fights the acting task;
+- silent characters with no listener task.

package/skill/references/filmmaking/asset-preproduction.md

@@ -0,0 +1,97 @@
+# Asset Pre-production
+
+Build stable inputs before expensive continuity work.
+
+## Asset contract
+
+Treat an asset as:
+
+```text
+canonical tag + immutable state + approved descriptor + reference media + provenance + stress-test status
+```
+
+The descriptor and media have different jobs. Media carries appearance. Text declares role, state, critical anchors, scale, ownership, and constraints the model might drop.
+
+For Kolbo Visual DNA, treat `dnaType` and the saved analyzed description/system prompt as authoritative asset data. Compile by role:
+
+- `character` → identity, physical state, wardrobe, performance, speaking voice, and singing voice;
+- `environment` / `scene` → location volume, landmarks, geography, materials, light, atmosphere, and available coverage;
+- `product` → recurring prop/product identity, scale, material, ownership, interaction state, and damage/version;
+- `style` → visual register only.
+
+Never flatten every DNA into CAST or infer role only from its images. Exact tags remain immutable.
+
+## Character assets
+
+Create a canonical identity source and separate state variants.
+
+For a reference sheet, capture at minimum:
+
+- a high-information close portrait;
+- full-body front and back or equivalent coverage;
+- neutral readable light and background;
+- empty hands unless an object is permanently inseparable;
+- optional smile/mouth state for speaking characters;
+- stable skin, hair, proportions, marks, and silhouette.
+
+Avoid baking a scene-specific grade, rim light, camera gimmick, or prop into the base identity asset. Create new state assets for wardrobe, wetness, wounds, dirt, age phase, transformation, gravity orientation, or action-critical pose.
+
+## Location assets
+
+Create plates that communicate volume, material, landmarks, and one coherent light logic.
+
+- Prefer a three-quarter view for spatial readability.
+- Include visible anchors used for blocking.
+- Separate day/night/weather/light states.
+- Create reverse/background plates for dialogue-heavy locations.
+- Keep people and movable action props out unless they are permanent environmental facts.
+- Record which qualities a location reference controls: geography, materials, atmosphere, light, palette, or optics.
+
+Do not let a location reference silently control the shot's framing unless explicitly intended.
+
+## Props, vehicles, creatures, and crowds
+
+Define action-critical states separately: open/closed, intact/broken, clean/bloody, hidden/revealed, front/back interior, loaded/unloaded, wings folded/open.
+
+Record scale with visible comparisons. For crowds, decide whether one crowd asset plus selected lead extras is more stable than many individual references.
+
+## Impossible-shot preparation
+
+Move difficult truth into the input when prose repeatedly fails:
+
+- rotate/invert the character state for shifted gravity;
+- build a first/last frame;
+- create a staging/layout reference;
+- use a depth map for volume;
+- use a motion reference for complex choreography;
+- create a purpose-built prop or creature state;
+- generate a new location angle rather than asking the video model to invent it.
+
+This is not cheating; it is production design.
+
+## Surgical image revision
+
+Preserve the original and change one thing:
+
+```text
+CHANGE: the single intended difference.
+PRESERVE: identity, composition, camera, wardrobe, props, lighting, shadows, palette, texture, and every unaffected element.
+```
+
+Never run an approved identity source repeatedly through full-frame transformation when a masked/local edit can preserve it. Version every approved variant.
+
+## Stress testing
+
+Test assets in the conditions that matter:
+
+- multiple shot sizes and actions;
+- real target locations and lighting;
+- dialogue, laughter, distress, and unusual poses;
+- alongside recurring co-stars and props;
+- across the intended model/mode.
+
+If the same failure survives prompt fixes, rebuild the asset or state. A beautiful sheet that fails motion is not production-ready.
+
+## Approval gate
+
+Do not begin continuity-heavy production until the required cast, locations, props, states, voices, and world rules are named, versioned, and sufficiently stress-tested. For exploratory tests, label temporary assets and prevent them from becoming canonical accidentally.