@kolbo/mcp 1.70.0 → 1.70.2

package/skill/references/filmmaking/audio-dialogue-music.md

@@ -0,0 +1,111 @@
+# Audio, Dialogue, and Music
+
+Choose one primary audio lane, then state how the remaining sound layers interact.
+
+## Audio ownership
+
+For every audible element, record:
+
+- source: native generation, supplied audio, off-screen actor, environment, or post;
+- owner: which mouth/body/object produces it;
+- timing and duration;
+- priority in the mix;
+- whether it continues across the edit.
+
+Never leave spoken or sung words ownerless.
+
+## Dialogue lane
+
+Use exact quoted text. Separate:
+
+1. **Voice identity** — stable register, timbre, accent, pace, habitual delivery.
+2. **Scene delivery** — tactic, volume, pressure, timing, breath, interruption.
+3. **Listener behavior** — active task and reaction timing.
+
+Specify when mouths remain closed if the model tends to invent speech. Allow nonverbal sound only when requested.
+
+Fit dialogue to the available duration. Include a clean tail when the editor needs a seam. Preserve the previous line's emotional/audio tail only when it helps the next reaction; do not import irrelevant visual subjects from prior audio.
+
+## Exact-song lip-sync lane
+
+Use when a supplied waveform is authoritative.
+
+Declare:
+
+- the audio/video reference contains the performance track;
+- the exact performer whose mouth owns it;
+- the lyric fragment in the block;
+- source waveform wins if text and clipped edges disagree;
+- breath gaps and section boundaries;
+- non-performers' mouth behavior;
+- whether returned generation audio is retained or replaced in post.
+
+Example contract:
+
+```text
+<audio tag> is the authoritative performance waveform.
+<performer> shapes every audible syllable frame-accurately.
+Lyrics: "..."
+At clipped boundaries, follow the waveform rather than completing the written line.
+Other mouths react and sing only if explicitly assigned; they never inherit these words.
+```
+
+Cut long songs into edit-aware sections at breaths or musical seams. Do not cut mid-phoneme unless unavoidable.
+
+## Native music-performance lane
+
+Use when the selected model can produce synchronized music/vocals and the user wants generation-native sound.
+
+Specify:
+
+- performers and vocal ownership;
+- lyric or semantic requirement;
+- tempo/beat landmarks and choreography hits;
+- music style in observable arrangement terms;
+- where vocals trade, overlap, or unify;
+- SFX/ambience relationship;
+- whether imperfect live energy or polished studio precision is desired.
+
+Do not default to “music belongs in post” when the creative ask explicitly depends on native synchronized music.
+
+## Dance and ensemble performance
+
+Define formation, choreography class, beat accents, leader changes, and what counts as synchronized versus individualized. Keep reaction/face rhythms distinct even when bodies hit choreography in unison.
+
+For moving vehicles or complex environments, protect balance, handholds, wind, hair/wardrobe response, and occupant positions.
+
+## Ambience/SFX-only lane
+
+Use when edit flexibility or dramatic silence matters. Define a continuous environmental bed and timed events. “No score” must not suppress dialogue or requested effects.
+
+Use silence as a placed event with duration and dramatic purpose, not an empty unspecified gap.
+
+## Post-production music lane
+
+Track the score brief outside the generation prompt:
+
+- thematic motif and emotional arc;
+- tempo, meter, instrumentation, entry/exit points;
+- dialogue ducking and impact sync;
+- continuous ambience that glues generated shots;
+- licensing/ownership status.
+
+Generate clean picture audio consistent with the edit plan.
+
+## Voice and likeness rights
+
+Do not imitate or deploy a real person's voice/likeness without confirmed authorization. Store provenance/permission with the asset. Describe fictional character performance rather than relying on an actor name.
+
+## Audit failures
+
+Flag:
+
+- multiple mouths owning one line unintentionally;
+- dialogue repeated in both action and audio in conflicting forms;
+- lyrics inconsistent with the source waveform;
+- invented ad-libs or sound from off-screen events meant to remain silent;
+- native music requested but globally prohibited;
+- “no music” interpreted as “no audio”;
+- voice identity rewritten across shots;
+- dialogue/choreography that cannot fit the duration;
+- no clean audio seam for the intended edit.

package/skill/references/filmmaking/blocking-continuity.md

@@ -0,0 +1,125 @@
+# Blocking, Geography, and Continuity
+
+Use this pack for multiple subjects, dialogue, recurring locations, cross-shot continuity, or any result where characters flip, teleport, swap, duplicate, or lose props.
+
+## Build the map before the shot
+
+Record stable scene geography independently of camera prose:
+
+- landmark names and screen/world relationships;
+- entrances, exits, furniture, hazards, levels, and movement paths;
+- key light direction;
+- one side of the 180-degree line for coverage;
+- character starting marks and recurring prop homes.
+
+Tie people to visible landmarks. Prefer “at the stage edge, one stride from the exit door” over an unsupported abstract coordinate. Use measurable distances only when they genuinely help the target model.
+
+## First-frame contract
+
+State exactly what frame one contains when occupancy matters:
+
+- active character count;
+- screen position and depth layer;
+- body facing and eyeline;
+- contact with landmarks/props;
+- camera side and shot size;
+- motion already in progress or deliberate stillness.
+
+Do not automatically add an empty establishing beat. Use a short master/positioning image only when it serves continuity or editorial intent.
+
+## Position grammar
+
+For each important subject specify as needed:
+
+- screen-left/center/right;
+- foreground/midground/background;
+- facing direction and torso orientation;
+- gaze target;
+- relation/contact to landmark;
+- movement direction/path;
+- hand/prop state;
+- permitted moment of relocation.
+
+Body direction and eye direction are separate facts.
+
+## Internal cuts
+
+At every cut preserve or deliberately change:
+
+- camera side and screen direction;
+- subject marks, facing, eyelines, and posture;
+- wardrobe, hair, wounds, dirt, wetness;
+- prop owner, hand, orientation, damage;
+- environmental debris, smoke, fire, water, practical lights;
+- emotional pressure and breath;
+- audio tail and mouth state.
+
+Begin the new shot on a physically possible continuation or explicit temporal/spatial reset. Do not use “continues from before” as the only instruction.
+
+## Across generations
+
+Record the approved final state of shot N and compile it into shot N+1. Use the continuity ledger rather than reinterpreting the previous prompt.
+
+Default to the full approved prior video plus explicit final-state prose. The video owns motion cadence, performance, ambience, temporal carry, and the actual landing state. Do not automatically extract or attach its last frame merely because the next shot is connected.
+
+Add a last-frame or staging still only when exact opening geometry is essential, or after a video-only attempt failed on blocking, axis, eyeline, prop-hand state, or composition. When both references are used, keep their authority non-overlapping: the prior video owns temporal behavior; the still owns only the new shot's opening crop, pose, facing, positions, and geometry.
+
+Continuity can intentionally break for ellipsis, montage, dream logic, or a revealed camera-side change, but name the transition in the edit plan.
+
+## Staging/layout references
+
+Use a staging reference when prose cannot reliably hold multi-character geometry.
+
+### Diagram construction
+
+- Build a front-view composition map from the intended camera side, not a top-down floor plan unless the model has proven it can use one.
+- Use thin muted outlines or another low-style-mass representation.
+- Keep one distinct color per figure/path.
+- Preserve crop, pose, facing, scale, and anchoring furniture.
+- Avoid rendered names/letters if they may bleed into the video.
+- Version every retake from the real source frame, not from a progressively degraded diagram.
+
+### Connector
+
+In the video prompt, bind diagram identities textually:
+
+```text
+<staging tag> controls position, pose, facing, and path only.
+BLUE figure = <character tag> at <mark> facing <target>.
+Visual identity, wardrobe, materials, light, and grade come from character/location references.
+```
+
+Attach strong identity/location references before the staging reference when attachment order affects the model.
+
+### Anti-bleed discipline
+
+Do not describe the diagram's graphic aesthetics inside the final video prompt. State positively where the final picture's style and identity come from.
+
+## Depth and trajectory helpers
+
+Use a depth map when the difficult problem is volume, scale, or occlusion. Use trajectory paths when the problem is a thrown object, bullet, creature, vehicle, camera path, or character cross. Define start, path, end, trigger beat, and owner.
+
+## Count and scale laws
+
+For critical counts or scale, write:
+
+- the intended count/measure;
+- visible proof in the frame;
+- relationship to a known person/object;
+- what state must not multiply during motion.
+
+Avoid contradictory repeated bans. One clear law near the protected action plus a concise final restatement is usually stronger.
+
+## Audit failures
+
+Flag:
+
+- “left of him” without a stable camera/world anchor;
+- changing map facts between shots;
+- camera crossing the line without showing it;
+- gaze directions that do not meet;
+- prop teleportation or hand swap;
+- asset state reset after a cut;
+- diagram controlling style rather than geometry;
+- overly free camera instruction in a strict geography shot;
+- active references that are not visible or required.

package/skill/references/filmmaking/cinematography.md

@@ -0,0 +1,101 @@
+# Cinematography
+
+Translate creative intent into visible camera behavior. Use model-readable outcomes rather than relying only on equipment names.
+
+## Decide content before lens
+
+Match the optical class to what the frame must communicate:
+
+| Content | Useful FOV region | Observable result |
+|---|---:|---|
+| Immersive environment/body-near-camera | 84°–107° | strong depth expansion, environment readable, camera physically close |
+| Natural grounded observation | 47°–63° | human perspective, readable space, modest separation |
+| Portrait/dialogue isolation | 18°–29° | stable face, compressed background, focused attention |
+| Distant surveillance/sports/wildlife | 8°–12° | extreme compression, distance, foreground occlusion, atmosphere |
+| Fisheye/extreme subjective world | 135°–180° | explicit distortion and environmental immersion; higher failure risk |
+
+Use discrete anchors when the model responds to them. Reinforce extreme optics with physical camera distance, foreground behavior, depth, and visible outcome.
+
+## One content class per beat
+
+Do not ask one uninterrupted lens beat to be a macro detail, intimate portrait, and vast geographic panorama simultaneously. Use a cut, motivated camera transition, or looser exploratory instruction.
+
+## Shot design
+
+For each shot or segment establish:
+
+- shot size and subject priority;
+- camera height, side, and physical distance;
+- operator movement and motivation;
+- focus target and transition;
+- lens/FOV character;
+- negative space and depth layers;
+- how the shot begins and ends editorially.
+
+Write camera and subject motion separately.
+
+## Operator behavior
+
+Prefer physical language:
+
+- locked at eye height;
+- shoulder-mounted with weight and organic corrections;
+- low tracking beside the vehicle;
+- cranes as the reveal expands;
+- camera stays put as subjects pass;
+- orbits only while preserving a named axis/center.
+
+Do not confuse travel speed with shake intensity. Preserve explicitly requested restless handheld instead of softening it into subtle drift.
+
+## Single take versus controlled cuts
+
+Use a single take when geography, performance, or physical flow benefits from continuity and the action is feasible.
+
+Use controlled cuts when content class changes, two simultaneous reactions need coverage, a detail requires an insert, time compresses, or the editorial rhythm is the idea.
+
+Do not describe “one continuous take” and then request multiple disconnected framings unless a physically plausible camera path connects them.
+
+## Controlled creative freedom
+
+In anchored/exploratory work, name the dimensions the model may vary:
+
+```text
+Keep identity, geography, action order, scale, and final state fixed.
+Vary camera path and shot size within smooth motivated coverage.
+```
+
+Avoid “free camera” when strict eyelines, exact prop contact, or a single-take topology would be endangered.
+
+## Optical signatures
+
+Describe signatures through outcomes:
+
+- anamorphic: oval/cat-eye bokeh, horizontal defocus character, contained source glows, edge behavior, breathing;
+- spherical: round bokeh, natural geometry, more uniform focus falloff;
+- vintage: lower contrast, imperfect edge response, gentle aberration, texture;
+- clean modern: controlled highlights, crisp detail, restrained artifacts.
+
+Do not stack incompatible signatures. If a location asset already carries the optical look, keep the video prompt lighter and protect it from drift.
+
+## Style and palette
+
+Treat style as a production bible decision. Express palette through materials, sources, and compositional role, not an arbitrary color list. Place style after identity, geography, action, optics, and light so it cannot overwrite them.
+
+Translate a named filmmaker/cinematographer reference into observable characteristics when necessary. Do not depend on the name alone.
+
+## Edit grammar
+
+Name cut type only when it matters: hard, match, smash, insert, reverse, whip. Allocate enough pre/post action for the intended edit. Record the final state and the visual or audio hook into the next shot.
+
+## Audit failures
+
+Flag:
+
+- optics incompatible with content;
+- extreme FOV without supporting visual evidence;
+- compound camera moves competing in one time slice;
+- camera freedom contradicting blocking;
+- unjustified lens drift across internal cuts;
+- stylistic camera language overriding acting or story;
+- impossible travel across the requested duration;
+- a first/last frame that does not support the desired camera move.

package/skill/references/filmmaking/physics-action.md

@@ -0,0 +1,93 @@
+# Physics and Action
+
+Design action as cause, contact, mass, and consequence.
+
+## Feasibility pass
+
+Before prompting, simulate the shot mentally:
+
+1. Where is every body/object at frame one?
+2. What force starts each movement?
+3. What path, distance, duration, and contact are required?
+4. What carries inertia or delay?
+5. What changes state?
+6. What is the final stable arrangement?
+
+If the movement cannot happen physically or editorially in the allotted time, simplify or split it.
+
+## Physical vocabulary
+
+Specify only relevant properties:
+
+- gravity, mass, inertia, friction, weight transfer, balance;
+- contact point, pressure, collision, follow-through;
+- acceleration/deceleration and motion vector;
+- cloth/hair/feather delay and wind coupling;
+- liquid viscosity, splash origin, wake, residue;
+- particle direction, density, accumulation, heat shimmer;
+- hinge resistance, suspension, vehicle roll, creature wing loading;
+- prop weight, grip, wrist/shoulder response.
+
+Keep subject physics, camera physics, and environment physics mutually compatible.
+
+## States, transitions, and action density
+
+For difficult action, begin on a strong executable state: already mid-swing, already inverted, already running, already in contact. Put the approach in another shot when it competes with the main event.
+
+Use explicit transitions only when the model/mode and duration can carry them. A sequence of clear states with causal bridges is usually more reliable than a long chain of preparatory actions.
+
+## Impossible shots
+
+Change the input before overprompting:
+
+- bake orientation or damage into a new state asset;
+- supply start/end frames;
+- add a layout or depth reference;
+- use motion reference for choreography;
+- split approach, impact, and aftermath;
+- grant camera freedom while locking physics anchors;
+- design several anchored coverage variations and edit the strongest pieces.
+
+## Scale
+
+Protect scale with three signals:
+
+1. real-world measurement or ratio;
+2. visible frame occupation;
+3. comparison with a known body/object.
+
+Repeat the proof only where scale may reset after a cut.
+
+## Vehicles and creatures
+
+Define:
+
+- mass and support/contact points;
+- propulsion and response delay;
+- direction and speed class;
+- rider/passenger balance and attachment;
+- moving environment and camera relationship;
+- state of wings, wheels, suspension, harness, doors, or limbs;
+- safe/required clearance from surfaces.
+
+For water contact, specify which exact body/object touches, where the rest remains, and the resulting spray/wake origin.
+
+## Transformations and destruction
+
+Name material progression, origin, direction, conservation of mass, debris behavior, and what remains recognizable. Separate a transformation into causal beats rather than adjective escalation.
+
+## Failure threshold
+
+Track attempts. After repeated variants fail for the same reason, stop wording iteration and change the production design. Common rescues:
+
+- one action instead of three;
+- one subject instead of a crowd;
+- a tighter corner instead of a whole room;
+- a new asset state;
+- a different camera angle;
+- a cut at the hard transition;
+- another model or generation mode.
+
+## Audit failures
+
+Flag floating mass, frictionless feet, teleporting props, duplicated objects, impossible reach/contact, wings or wheels in contradictory states, water reacting to the wrong body, action without causal force, camera motion that erases the physical read, and time windows overloaded with incompatible actions.

package/skill/references/filmmaking/production-bible.md

@@ -0,0 +1,108 @@
+# Production Bible and Continuity State
+
+Use durable project state for any recurring cast, world, location, prop, voice, visual register, or multi-shot production.
+
+## Sources of truth
+
+Maintain these layers:
+
+1. **Production bible** — project-wide creative and technical truth.
+2. **Asset registry** — every approved character, state, location, prop, vehicle, creature, audio, diagram, and motion reference.
+3. **Scene card** — dramatic event, geography, active states, coverage plan, and scene-level constants.
+4. **Shot card** — one generation's exact inputs, intent, timing, final state, and edit relationship.
+5. **Continuity ledger** — state entering and leaving each approved shot.
+6. **Generation log** — prompt version, one change, result, verdict, and selected take.
+
+Use the JSON/CSV templates in `assets/` as starting artifacts. Keep project-owned files outside this skill folder.
+
+## Production bible
+
+Capture only facts that should survive many scenes:
+
+- project ID, title, format, runtime target, genre, tone, logline, story goal;
+- period and world laws, including forbidden anachronisms;
+- visual worlds/registers, palette logic, light laws, texture, capture grammar;
+- character IDs, immutable identity anchors, performance engine, voice identity, state variants;
+- location IDs, material/geography anchors, light direction, time/weather variants, available angles;
+- prop/vehicle/creature IDs, scale, material, states, ownership, action limitations;
+- audio policy, score policy, language/accent rules, subtitle policy;
+- default model adapters and verified capability snapshot;
+- naming/version policy and approval gates.
+
+Do not store shot-specific improvisation as global truth.
+
+## Asset identity and states
+
+Treat identity and state separately.
+
+- Identity answers: who/what is this across the project?
+- State answers: what exact version appears now—wardrobe, wetness, wound, dirt, damage, age phase, prop configuration, upside-down orientation?
+
+Create a new immutable state asset when a meaningful visible condition changes. Never overload one tag with mutually exclusive states. Preserve prior approved states.
+
+Prefer a stable naming pattern:
+
+```text
+@char_<PROJECT>_<name>_<state>_vN
+@loc_<PROJECT>_<name>_<time-weather>_sN_vN
+@prop_<PROJECT>_<name>_<state>_sN_vN
+@vehicle_<PROJECT>_<name>_<view-state>_vN
+@staging_<PROJECT>_<scene-shot>_vN
+@audio_<PROJECT>_<character-or-track>_<section>_vN
+```
+
+Use only legal identifiers supported by the destination platform. One asset has one canonical active tag.
+
+## Scene card
+
+Record:
+
+- structural goal, open jeopardy, event/reversal/value shift;
+- shared acting direction and each character's motive/task;
+- location variant, map, landmarks, camera side, 180-degree axis, light law;
+- entering character/prop/environment states;
+- planned coverage and edit arc;
+- scene-level audio bed and score intention;
+- unresolved assets or risks.
+
+## Shot card
+
+Record:
+
+- shot ID and scene ID;
+- editorial job and dramatic beat;
+- generation family/mode, model, duration, aspect, control density;
+- active assets and exact state tags;
+- first frame, blocking, camera side, eyelines, action/timing;
+- acting tasks, dialogue/audio ownership;
+- physics and light constraints;
+- final frame/state and intended cut relationship;
+- prompt path/version, output candidates, approval/QC state.
+
+A shot card is the compiler input. The model prompt is a derived artifact, not the source of production truth.
+
+## Continuity ledger
+
+Track explicit entering and leaving values for:
+
+- character position, facing, eyeline, posture, breath, emotional pressure;
+- wardrobe, hair, dirt, wetness, blood, injury, transformation;
+- prop owner, hand, orientation, open/closed/loaded/broken state;
+- vehicle/creature position, motion vector, damage, occupants;
+- location time, weather, light direction, practical states, debris;
+- camera side, screen direction, lens family, motion state;
+- last spoken line, mouth state, ambience, score/SFX tail.
+
+Update only from an approved take or deliberate story change. Do not let an accidental generation artifact become canon without explicit approval.
+
+## Version and change discipline
+
+- Never overwrite an approved asset state or prompt version.
+- Change one causal variable per diagnostic iteration whenever possible.
+- Record the observed result, not only “failed.”
+- Preserve the selected take and the exact prompt/model/settings that created it.
+- After repeated identical failures, reclassify the problem as asset, shot design, capability, or model mismatch.
+
+## Compilation rule
+
+Compile the current shot from the bible, asset registry, scene card, shot card, and incoming continuity state. Include only active facts. Re-anchor all details the model cannot infer from attached inputs; omit lore the shot cannot show or hear.

package/skill/references/filmmaking/prompt-contracts.md

@@ -0,0 +1,140 @@
+# Prompt Contracts
+
+Compile from approved project/shot state. Keep explanatory notes outside the generation prompt.
+
+## Strict shot contract
+
+Use for dialogue, continuity, complex blocking, exact synchronization, or failure recovery.
+
+```text
+SCENE CONTEXT
+<dramatic event, exact active count, duration, editorial job>
+
+ACTIVE REFERENCES
+<tag: role, state, action-critical anchors, reference authority>
+
+LOCATION MAP
+<landmarks, marks, axis, light direction>
+
+FIRST FRAME AND SPATIAL BLOCKING
+<frame-one positions, facing, eyelines, contact, prop/hand state>
+
+FORMAT MODE
+<single take or exact cuts, duration, speed, aspect if adapter requires>
+
+OPTICS
+<content-matched FOV/signature, focus plan>
+
+CAMERA
+<operator position/movement and motivation>
+
+ACTION TIMING / SHOTS
+<light executable beats with explicit state bridges>
+
+PHYSICS
+<only relevant mass/contact/material laws>
+
+LIGHTING
+<source, direction, exposure priority, continuity>
+
+ACTING TASKS
+<shared direction and playable tactic/listening behavior>
+
+DIALOGUE
+<speaker, exact text, timing, silence/mouth ownership>
+
+AUDIO / MUSIC
+<lane, source, ownership, ambience/SFX/score relationship>
+
+STYLE
+<project register; do not override identity or geography>
+
+POSITIVE LOCKS
+<short restatement of failure-critical facts>
+```
+
+Omit empty sections. Do not duplicate all reference descriptions again in final locks.
+
+## Anchored spectacle contract
+
+Use when the model should discover coverage inside fixed truth:
+
+```text
+GOAL / SIGNATURE MOMENT
+ACTIVE REFERENCES AND STATES
+WORLD / GEOGRAPHY ANCHORS
+START STATE
+MANDATORY BEAT ORDER
+PHYSICS / SCALE LAWS
+FINAL STATE
+CAMERA FREEDOM: <dimensions allowed to vary>
+AUDIO LANE
+FAILURE-CRITICAL LOCKS
+```
+
+State what is fixed and what is free. Avoid locking one camera path while simultaneously asking for bold variation.
+
+## Exploratory coverage contract
+
+Use for b-roll, montage, music inserts, or alternative coverage:
+
+```text
+EDITORIAL PURPOSE
+IDENTITY / WORLD CONSTANTS
+PERFORMANCE OR ACTION LANGUAGE
+VISUAL / AUDIO REGISTER
+ALLOWED VARIATIONS
+EXCLUSIONS ONLY WHEN FAILURE-CRITICAL
+```
+
+Request separate variations rather than contradictory camera moves inside one take.
+
+## Dialogue contract
+
+Include:
+
+- current shared event;
+- each speaker's tactic;
+- listener task;
+- exact line ownership and time;
+- voice identity plus scene delivery;
+- breath/reaction tail;
+- eyeline and mouth state;
+- ambience behavior under speech.
+
+One short line per clip is often reliable, but do not impose that as a universal model law. Use actual duration/capability and the user's editorial plan.
+
+## Exact-song contract
+
+Include:
+
+- authoritative source audio tag;
+- performers and non-performers;
+- lyric fragment and waveform-wins rule;
+- choreography/beat hits;
+- breath seam and final pose/state;
+- returned-audio/post-audio policy.
+
+## Workbench patch contract
+
+Return:
+
+```text
+ROOT CAUSE
+<one causal owner>
+
+PATCH
+<only changed section or exact diff>
+
+PRESERVE
+<sections/lines that remain unchanged>
+
+EXPECTED PROOF
+<visible/audible outcome that confirms the fix>
+```
+
+Do not rewrite the whole prompt when one block owns the failure.
+
+## Prompt-card routing
+
+When the caller supports Kolbo prompt cards, tag the final fenced block with the generation mode selected from inputs. Keep all internal shots of one generation inside one card. Keep multiple separate generations as separate cards only when the user requested multiple outputs or the adapter requires a split.