venice-video-harness 2.13.0 → 2.14.0

package/{.claude → .agents}/agents/cut-qa.md

@@ -126,8 +126,8 @@ Next: applying 3 fixes -> re-render -> iteration 2.
 
 ## See Also
 
-- `.claude/skills/video-editing/SKILL.md` — the pipeline this agent plugs into
-- `.claude/skills/burn-in-subtitles/SKILL.md` — caption derivation the agent may trigger re-runs of
+- `.agents/skills/video-editing/SKILL.md` — the pipeline this agent plugs into
+- `.agents/skills/burn-in-subtitles/SKILL.md` — caption derivation the agent may trigger re-runs of
 - `scripts/timeline-view.ts` — the composite tool this agent uses
 - `src/editing/types.ts` → `CutQaFinding`, `CutQaReport`
 - `AGENTS.md` anti-patterns #5, #7, #10, rule 26

package/{.claude → .agents}/agents/ffmpeg-overlay.md

@@ -103,6 +103,6 @@ On unsuitable overlay (e.g. `logo-bug` spec), return:
 ## See Also
 
 - [`scripts/render-overlay.ts`](../../scripts/render-overlay.ts) — the consumer of these specs
-- `.claude/agents/overlay-designer.md` — parent agent
-- `.claude/agents/remotion-overlay.md` — sibling for animated overlays
-- `.claude/skills/burn-in-subtitles/SKILL.md` — drawtext escaping gotchas learned in production
+- `.agents/agents/overlay-designer.md` — parent agent
+- `.agents/agents/remotion-overlay.md` — sibling for animated overlays
+- `.agents/skills/burn-in-subtitles/SKILL.md` — drawtext escaping gotchas learned in production

package/{.claude → .agents}/agents/overlay-designer.md

@@ -111,8 +111,8 @@ Return to the calling agent:
 
 ## See Also
 
-- [`.claude/agents/remotion-overlay.md`](remotion-overlay.md) — animated overlay worker
-- [`.claude/agents/ffmpeg-overlay.md`](ffmpeg-overlay.md) — static overlay worker
+- [`.agents/agents/remotion-overlay.md`](remotion-overlay.md) — animated overlay worker
+- [`.agents/agents/ffmpeg-overlay.md`](ffmpeg-overlay.md) — static overlay worker
 - [`scripts/render-overlay.ts`](../../scripts/render-overlay.ts) — the compositing tool
 - [`src/editing/overlays.ts`](../../src/editing/overlays.ts) — manifest type definitions
 - AGENTS.md rules 17, anti-pattern #9, anti-pattern #11

package/{.claude → .agents}/agents/prompt-engineer.md

@@ -7,7 +7,7 @@ Before filling any template below, decide what the shot is *doing* — the turn,
 - Decorated (avoid): `epic cinematic close-up of a woman reading a letter, emotional, beautiful lighting`
 - Directed (do this): `Medium close-up, eye-level; she lowers the letter and her hands go still as a slow push-in arrives; soft window light keeps her face plain; near-silence with one chair scrape — the realization lands in the stilled hands, not a word.`
 
-If the **Seedance 2.0 Skill OS** is installed (see this repo's README "Directing layer"; typical path `.claude/skills/seedance-20/`), load its `directing-engine` for the full derivation method and worked genre examples, `seedance-antislop` + `vocab/*` to strip empty boosters, and `retake-protocol` when a take is close but not right. The templates below are the *container*; the directing engine decides what goes in them.
+If the **Seedance 2.0 Skill OS** is installed (see this repo's README "Directing layer"; typical path `.agents/skills/seedance-20/`), load its `directing-engine` for the full derivation method and worked genre examples, `seedance-antislop` + `vocab/*` to strip empty boosters, and `retake-protocol` when a take is close but not right. The templates below are the *container*; the directing engine decides what goes in them.
 
 **Division of labor with the harness:** identity is locked by R2V references + the Seedance → Wan keyframe pass, and durations/model routing are decided at generation time. So direct **intention/camera/light/blocking/performance/sound**; let the pipeline own identity, duration, and routing.
 

package/{.claude → .agents}/agents/remotion-overlay.md

@@ -97,8 +97,7 @@ On failure, return `{ "id": "...", "error": "<message>" }` — the parent decide
 
 ## See Also
 
-- `~/.claude/skills/remotion/SKILL.md` — Remotion best practices
-- `~/.claude/skills/remotion-best-practices/SKILL.md` — deeper patterns
-- `.claude/agents/overlay-designer.md` — parent agent
-- `.claude/agents/ffmpeg-overlay.md` — sibling worker for static overlays
+- `remotion` / `remotion-best-practices` skills, if installed in your runner's global skills dir (e.g. `~/.claude/skills/`, `~/.hermes/skills/`) — Remotion best practices and deeper patterns
+- `.agents/agents/overlay-designer.md` — parent agent
+- `.agents/agents/ffmpeg-overlay.md` — sibling worker for static overlays
 - AGENTS.md rules 17, anti-patterns #9, #11

package/{.claude → .agents}/commands/edit-footage.md

@@ -139,7 +139,7 @@ session.iterations.push(report);
 saveSession(session, 'output/<project>/edit/session.json');
 ```
 
-Then invoke `.claude/agents/cut-qa.md` with the report. The agent proposes fixes, you apply them to the EDL, and re-render.
+Then invoke `.agents/agents/cut-qa.md` with the report. The agent proposes fixes, you apply them to the EDL, and re-render.
 
 **Max 3 iterations.** If the 3rd iteration still has `fail`-severity findings, stop and surface to the user with:
 
@@ -152,7 +152,7 @@ Then invoke `.claude/agents/cut-qa.md` with the report. The agent proposes fixes
 Always ask "Burn in subtitles? (yes / no)" before running the captioning step, per the [burn-in-subtitles skill](../skills/burn-in-subtitles/SKILL.md). If yes:
 
 ```bash
-npx tsx .claude/skills/burn-in-subtitles/scripts/derive-captions.ts \
+npx tsx .agents/skills/burn-in-subtitles/scripts/derive-captions.ts \
   --vo output/<project>/edit/final-edit.mp4 \
   --vo-text-file scripts/<project>/config.ts \
   --vo-delay 0
@@ -189,8 +189,8 @@ Report back to the user with:
 
 ## See Also
 
-- [`.claude/skills/video-editing/SKILL.md`](../skills/video-editing/SKILL.md) — the full philosophy and rules
-- [`.claude/skills/burn-in-subtitles/SKILL.md`](../skills/burn-in-subtitles/SKILL.md) — caption derivation
-- [`.claude/agents/cut-qa.md`](../agents/cut-qa.md) — the QA agent invoked in step 5
+- [`.agents/skills/video-editing/SKILL.md`](../skills/video-editing/SKILL.md) — the full philosophy and rules
+- [`.agents/skills/burn-in-subtitles/SKILL.md`](../skills/burn-in-subtitles/SKILL.md) — caption derivation
+- [`.agents/agents/cut-qa.md`](../agents/cut-qa.md) — the QA agent invoked in step 5
 - [`src/editing/types.ts`](../../src/editing/types.ts) — EDL, Take, Session type definitions
 - `AGENTS.md` rule 26 — VO truncation cause and cure

package/{.claude → .agents}/commands/generate-trailer.md

@@ -18,7 +18,7 @@ Analyze the screenplay and generate a curated trailer -- selecting the most comp
 1. Load `project.json` and read all scene data
 2. Analyze the dramatic arc: world, inciting incident, protagonist journey, central tension
 3. Identify the most visually striking and emotionally resonant moments
-4. Follow the trailer-curator agent's methodology (see `.claude/agents/trailer-curator.md`)
+4. Follow the trailer-curator agent's methodology (see `.agents/agents/trailer-curator.md`)
 
 ### Phase 2: Shot List Curation
 1. Select 10-15 shots (1m) or 25-40 shots (3m) from across the screenplay

package/{.claude → .agents}/skills/burn-in-subtitles/SKILL.md

@@ -105,7 +105,7 @@ Threshold guidance:
 This skill ships a TypeScript helper that does the silence detection AND prints a drop-in `CAPTIONS` array:
 
 ```bash
-npx tsx .claude/skills/burn-in-subtitles/scripts/derive-captions.ts \
+npx tsx .agents/skills/burn-in-subtitles/scripts/derive-captions.ts \
   --vo output/<project>/audio/vo.mp3 \
   --vo-text-file scripts/<project>/config.ts \
   --vo-delay 1.5 \
@@ -272,13 +272,13 @@ Even with silence-detect-derived timings, verify by extracting a frame at each p
 | Render VO | `npx tsx scripts/<project>/04-audio.ts --only=vo --force` |
 | Measure VO | `ffprobe -v error -show_entries format=duration ...` |
 | Detect phrase boundaries | `ffmpeg -af "silencedetect=noise=-30dB:d=0.18"` |
-| Generate CAPTIONS array | `npx tsx .claude/skills/burn-in-subtitles/scripts/derive-captions.ts ...` |
+| Generate CAPTIONS array | `npx tsx .agents/skills/burn-in-subtitles/scripts/derive-captions.ts ...` |
 | Paste into config.ts | manual |
 | Re-assemble trailer | `npx tsx scripts/<project>/05-assemble.ts --force` |
 | Verify spot frames | `ffmpeg -ss <caption.start> -i trailer-final.mp4 -frames:v 1` |
 
 ## See Also
 
-- `.claude/skills/venice-api/SKILL.md` — Venice TTS endpoints and voice catalog
-- `.claude/skills/venice-video-model-routing/SKILL.md` — model selection for the underlying video
+- `.agents/skills/venice-api/SKILL.md` — Venice TTS endpoints and voice catalog
+- `.agents/skills/venice-video-model-routing/SKILL.md` — model selection for the underlying video
 - `AGENTS.md` § "Learned Anti-Patterns" — broader harness lessons

package/{.claude → .agents}/skills/burn-in-subtitles/scripts/derive-captions.ts

@@ -9,7 +9,7 @@
  * time.
  *
  * Usage:
- *   npx tsx .claude/skills/burn-in-subtitles/scripts/derive-captions.ts \
+ *   npx tsx .agents/skills/burn-in-subtitles/scripts/derive-captions.ts \
  *     --vo output/<project>/audio/vo.mp3 \
  *     --vo-text-file scripts/<project>/config.ts \
  *     --vo-delay 1.5 \
@@ -339,7 +339,7 @@ function formatCaptionsArray(captions: Caption[]): string {
   });
   return [
     "/**",
-    " * Caption rows (auto-derived by .claude/skills/burn-in-subtitles/scripts/derive-captions.ts).",
+    " * Caption rows (auto-derived by .agents/skills/burn-in-subtitles/scripts/derive-captions.ts).",
     " * Re-derive whenever the VO file changes — never hand-edit timings.",
     " */",
     "export const CAPTIONS: Array<{ text: string; start: number; end: number }> = [",

package/{.claude → .agents}/skills/shot-composition/SKILL.md

@@ -7,7 +7,7 @@ Plan cinematic shot lists for screenplay scenes, determining shot types, camera
 
 Shot type, angle, movement, and lens are *consequences*, not starting points. Before you pick from the tables below, name what the beat is **doing** (a reveal, a goodbye, a power flip, a lie) and its **one intention**. A reveal is not framed, lit, blocked, or moved like a goodbye — derive the coverage from the intention instead of defaulting to "coverage that looks cinematic." Hold one directorial voice across the scene.
 
-When the **Seedance 2.0 Skill OS** is installed (`.claude/skills/seedance-20/`), load `directing-engine` for the derivation method, and use `retake-protocol` (triage the verdict, change one variable, keep an attempt budget) and `continuation-handoff` (direct the next beat from accepted footage, not the original plan) when iterating. See this repo's README "Directing layer."
+When the **Seedance 2.0 Skill OS** is installed (`.agents/skills/seedance-20/`), load `directing-engine` for the derivation method, and use `retake-protocol` (triage the verdict, change one variable, keep an attempt budget) and `continuation-handoff` (direct the next beat from accepted footage, not the original plan) when iterating. See this repo's README "Directing layer."
 
 ## Shot Types
 | Type | Use Case | Lens |

package/{.claude → .agents}/skills/venice-agent-guide/SKILL.md

@@ -40,6 +40,6 @@ in the other.
 
 ## Where the full knowledge lives
 - `AGENTS.md` — 49 rules and 28 production anti-patterns, shipped in the package.
-- `.claude/skills/` — `venice-api`, `venice-video-model-routing`, `character-consistency`, `shot-composition`, `burn-in-subtitles`, `video-editing`, and more.
-- `.claude/commands/` — 20 step-by-step playbooks; `.claude/agents/` — 10 sub-agent roles.
+- `.agents/skills/` — `venice-api`, `venice-video-model-routing`, `character-consistency`, `shot-composition`, `burn-in-subtitles`, `video-editing`, and more.
+- `.agents/commands/` — 20 step-by-step playbooks; `.agents/agents/` — 10 sub-agent roles.
 - Read the relevant playbook before running a workflow. Validate model capabilities against `src/venice/models.ts` before an API call.

package/{.claude → .agents}/skills/venice-video-model-routing/README.md

@@ -1,6 +1,6 @@
 # Venice Video Model Routing for Character Consistency
 
-A Claude Code agent skill that combines Venice AI media generation tools with intelligent model routing for character consistency. Includes executable Python scripts for image generation, video generation, image editing, and upscaling, plus decision trees for choosing the right model, reference images, frame sources, and prompt format for every shot.
+An agent skill (usable by any coding agent — Claude Code, Cursor, Hermes, OpenClaw, and others) that combines Venice AI media generation tools with intelligent model routing for character consistency. Includes executable Python scripts for image generation, video generation, image editing, and upscaling, plus decision trees for choosing the right model, reference images, frame sources, and prompt format for every shot.
 
 Based on the [venice-ai-media](https://github.com/openclaw/skills/tree/main/skills/nhannah/venice-ai-media) skill by [@nhannah](https://github.com/nhannah) for generation execution, extended with production-tested model routing logic for multi-shot character consistency.
 
@@ -87,13 +87,13 @@ Previous last frame (continuity priority):
 Clone into your project's skills directory:
 
 ```bash
-git clone https://github.com/jordanurbs/venice-video-model-routing.git your-project/.claude/skills/venice-video-model-routing/
+git clone https://github.com/jordanurbs/venice-video-model-routing.git your-project/.agents/skills/venice-video-model-routing/
 ```
 
 Or copy manually:
 
 ```bash
-cp -r venice-video-model-routing/ your-project/.claude/skills/venice-video-model-routing/
+cp -r venice-video-model-routing/ your-project/.agents/skills/venice-video-model-routing/
 ```
 
 ## Skill Structure

package/{.claude → .agents}/skills/video-editing/SKILL.md

@@ -133,7 +133,7 @@ Archive-first per workspace rule `.cursor/rules/shot-asset-safety.mdc`: if `fina
 
 ### Step 5 — Self-Eval via cut-qa
 
-After the render, spawn the `cut-qa` agent (see `.claude/agents/cut-qa.md`). It checks:
+After the render, spawn the `cut-qa` agent (see `.agents/agents/cut-qa.md`). It checks:
 
 | Check | Trigger |
 |-------|---------|
@@ -222,9 +222,9 @@ Fix: ALWAYS propose-then-confirm. The render is cheap; regenerating a 20-minute
 
 ## See Also
 
-- `.claude/skills/burn-in-subtitles/SKILL.md` — downstream captioning
-- `.claude/skills/venice-video-model-routing/SKILL.md` — generation side for insert shots
-- `.claude/agents/cut-qa.md` — post-render QA agent
-- `.claude/commands/edit-footage.md` — end-to-end playbook
+- `.agents/skills/burn-in-subtitles/SKILL.md` — downstream captioning
+- `.agents/skills/venice-video-model-routing/SKILL.md` — generation side for insert shots
+- `.agents/agents/cut-qa.md` — post-render QA agent
+- `.agents/commands/edit-footage.md` — end-to-end playbook
 - `src/editing/types.ts` — EDL, Take, EditSession type definitions
 - `.cursor/rules/shot-asset-safety.mdc` — archive-first rule

package/AGENTS.md

@@ -10,7 +10,7 @@ The shared `VENICE_API_KEY` lives in `.env` and is sourced by many scripts: do n
 
 1. Helps an agent plan and execute consistency-first Venice video workflows
 2. Supports recurring characters, locked visual systems, and reference-driven generation
-3. Provides reusable orchestration through `AGENTS.md` plus the playbooks, sub-agent definitions, and skills in `.claude/` (a directory name kept for compatibility — the contents are agent-neutral markdown)
+3. Provides reusable orchestration through `AGENTS.md` plus the playbooks, sub-agent definitions, and skills in `.agents/` (provider-neutral markdown — usable by any coding agent, renamed from `.claude/` in 2.14.0)
 4. Includes a comprehensive model registry covering 50+ Venice video, image, audio, and music models
 5. Includes a working narrative reference implementation in `src/mini-drama/`
 6. Preserves generated media by archiving instead of destructively replacing
@@ -34,8 +34,8 @@ This harness is not limited to any single video format. It supports:
 The intended interface is:
 - Natural-language requests to the agent
 - Orchestration rules in `AGENTS.md`
-- Workflow playbooks in `.claude/commands/`
-- Reusable Venice knowledge in `.claude/skills/`
+- Workflow playbooks in `.agents/commands/`
+- Reusable Venice knowledge in `.agents/skills/`
 - Underlying TypeScript and script execution in `src/` and `scripts/`
 
 The CLI and scripts are the execution layer underneath the harness, not the primary user interface.
@@ -288,10 +288,10 @@ Inspired by [browser-use/video-use](https://github.com/browser-use/video-use), t
 
 ### Key Files
 
-- `.claude/skills/video-editing/SKILL.md` — full philosophy, EDL format, anti-patterns
-- `.claude/commands/edit-footage.md` — end-to-end playbook
-- `.claude/agents/cut-qa.md` — post-render quality gate
-- `.claude/agents/overlay-designer.md` — branded motion-graphics planner
+- `.agents/skills/video-editing/SKILL.md` — full philosophy, EDL format, anti-patterns
+- `.agents/commands/edit-footage.md` — end-to-end playbook
+- `.agents/agents/cut-qa.md` — post-render quality gate
+- `.agents/agents/overlay-designer.md` — branded motion-graphics planner
 - `src/editing/` — type definitions, packer, aligner, EDL renderer, self-eval
 - `scripts/transcribe-sources.ts` — transcription CLI
 - `scripts/timeline-view.ts` — filmstrip + waveform + word-labels composite
@@ -390,9 +390,9 @@ Use `POST /video/quote` (via `quoteVideo()`) to estimate costs before committing
 22. **Seedance excels at physics-aware prompting.** Describe forces, not just actions — "tires smoke as car drifts 90 degrees" rather than "car turns." Friction, weight, material interactions, and contact physics produce better results with Seedance's physics-aware training.
 23. **3+ character shots auto-fallback to Kling O3 R2V.** When the default R2V model is Seedance (flat refs, max 4 images), shots with 3+ characters automatically fall back to Kling O3 R2V which supports structured `elements` for better per-character identity separation.
 24. **Seedance accepts face-bearing input images from ANY image family (2026-07).** Venice removed the old restriction that Seedance 2.0 only accepted face-bearing images produced by `seedream-v5-lite` / `seedream-v5-lite-edit`. There is no longer any seedream requirement: generate character portraits, character panels, and references with the global default `nano-banana-2` (or any family you prefer) and feed them straight to Seedance. The provenance-driven pre-flight gate is now a no-op (`ensureSeedanceCompatibility` always proceeds) and `seedanceCompatibility` is no longer auto-set. Provenance sidecars are still written as metadata but nothing gates on them. (Historical context: anti-pattern 13.) The Seedance face **consent** attestation (409 `needs_consent`) is unrelated and still handled at queue time.
-25. **Always ask before burning in subtitles.** Before assembling the final video on any project that includes a VO track, ask the user "Burn in subtitles? (yes / no)" — burn-in is a permanent baked-into-pixels decision and is not always wanted. If yes, follow `.claude/skills/burn-in-subtitles/SKILL.md`: never hand-estimate caption timings, always derive them from `ffmpeg silencedetect` on the rendered VO via `.claude/skills/burn-in-subtitles/scripts/derive-captions.ts`, and use single `...` ellipses only in TTS VO_TEXT (doubled `......` cause Kokoro/ElevenLabs to silently truncate the audio).
+25. **Always ask before burning in subtitles.** Before assembling the final video on any project that includes a VO track, ask the user "Burn in subtitles? (yes / no)" — burn-in is a permanent baked-into-pixels decision and is not always wanted. If yes, follow `.agents/skills/burn-in-subtitles/SKILL.md`: never hand-estimate caption timings, always derive them from `ffmpeg silencedetect` on the rendered VO via `.agents/skills/burn-in-subtitles/scripts/derive-captions.ts`, and use single `...` ellipses only in TTS VO_TEXT (doubled `......` cause Kokoro/ElevenLabs to silently truncate the audio).
 26. **Never use doubled ellipses in TTS VO scripts.** Kokoro and ElevenLabs handle single `...` reliably as breath gaps. Doubled `......` cause silent truncation — the audio file ends mid-script with no error, and you only catch it when downstream captions reference dropped text. Use commas + single `...` for combined rhythm, or break across multiple TTS calls and concat with ffmpeg `apad`.
-27. **Editing pipeline is text-first.** When the task is to cut / trim / re-order existing media (not synthesize new shots), always transcribe sources first via `scripts/transcribe-sources.ts` and reason over `takes_packed.md`. Call `scripts/timeline-view.ts` ONLY at explicit decision points — never frame-dump to browse the footage. See `.claude/skills/video-editing/SKILL.md`.
+27. **Editing pipeline is text-first.** When the task is to cut / trim / re-order existing media (not synthesize new shots), always transcribe sources first via `scripts/transcribe-sources.ts` and reason over `takes_packed.md`. Call `scripts/timeline-view.ts` ONLY at explicit decision points — never frame-dump to browse the footage. See `.agents/skills/video-editing/SKILL.md`.
 28. **Never render an EDL without user confirmation of the cut strategy.** Post a summary (sources, duration, trim rules, transitions) and wait for "yes" before calling `renderEdl()`. The render is cheap; a throwaway 15-minute render because intent was guessed is not. Mirrors video-use design principle 3.
 29. **Always run cut-qa after every assembly / edit render.** The `cut-qa` agent runs programmatic checks (aspect, visual jump, VO truncation, **dialogue/VO overlap** — assert no two spoken clips play simultaneously, see rule 35, lighting, audio pop, subtitle overlap) at cut boundaries. Max 3 fix iterations before surfacing to the user. Applies to BOTH the generation-pipeline assembler and the editing-pipeline render.
 30. **Overlays are a post-process, never baked into the EDL render.** Lower-thirds, title cards, chapter markers, and logo-bugs live in an `OverlayManifest` rendered via `scripts/render-overlay.ts` on top of `final-edit.mp4`. Changing overlay wording must not require re-rendering the cut.
@@ -403,7 +403,7 @@ Use `POST /video/quote` (via `quoteVideo()`) to estimate costs before committing
 35. **Schedule dialogue/VO with a global no-overlap scheduler driven by MEASURED clip durations — never by the script's planned shot lengths.** At assembly time, two audio clips may never play at once unless they are intentionally layered (e.g. a music bed vs a line). Build the schedule against the actual `ffprobe` duration of each rendered/normalized segment, not the `duration` field in the script (the rendered clip is almost always shorter or longer than its planned slot). Algorithm: walk shots in timeline order keeping a single `nextFreeSec` cursor; place each line at `max(shotStart + lead, nextFreeSec + gap)`; set `nextFreeSec = placedStart + audioDur`; use one cursor for ALL spoken lines regardless of speaker (narrator AND character) — a per-speaker cursor is the classic bug (see anti-pattern 19). Keep a small `gap` (≈0.2-0.3s) between consecutive lines. SFX and the music bed are exempt because they are meant to underlay. After mixing, verify with the cut-qa overlap check.
 36. **Author VO so each line fits its shot, and when it can't, extend the picture — never let audio bleed into the next shot.** A line of TTS runs ≈2.3-2.7 words/sec plus ~0.4s lead-in; budget `shotSeconds × 2.4` words and write to it. If a finished line is longer than its shot's video, the assembler must (a) extend that shot by freezing/holding its last frame to cover the audio (`ffmpeg tpad=stop_mode=clone:stop_duration=...`), or (b) the line must be shortened/split — it must NOT spill onto the next shot. Long narrator lines over short establishing shots are the usual offender; either tighten the narration or hold the frame. This is the authoring complement to the scheduler in rule 35.
 37. **Re-anchor every separately-rendered shot to the SAME locked references and restate the character's invariant traits in every prompt.** Identity, scale, palette, and wardrobe drift across independently generated shots even when the story is continuous. For each shot pass the identical canonical `reference_image_urls` (not a frame grabbed from a different shot), and repeat the character's fixed traits inline every time (markings, hair color, costume, and **relative size** — e.g. "as tall as the boy"). Size is a trait the model forgets most: if a character's scale changed in-story (grew/shrank), encode a `sizeState` per shot and state it explicitly. Prefer Seedance native multi-shot (rule 21) for consecutive beats precisely because identity/scale/lighting hold within one generation; across separate renders, the per-prompt trait restatement is what holds them together. Verify drift on a contact sheet of first-frames before assembling (see anti-pattern 20).
-38. **Direct the scene, don't decorate it.** Before writing any shot's `description` or `delivery` — in `workshop-episode`, `insert-shot`, or a manual `script.json` edit — decide what the beat is DOING (the turn, POV, power, subtext) and name ONE intention, then derive camera/light/blocking/performance/sound from it. Do not stack "cinematic / epic / beautiful / masterpiece / 4k" adjectives; they give the model nothing to serve. Hold one directorial voice across the episode. This is baked into the `workshop-episode` system prompt (`src/mini-drama/cli.ts`) so both the CLI and the venice-video-mcp `episode.workshop` inherit it. Direct **intention/camera/light/blocking/performance/sound only** — identity is locked downstream (rules 9, 19, 32), so never hand-write full physical character descriptions or reference-image tags into `description`. When a take is close-but-wrong, fix ONE variable at a time; when continuing, direct from the accepted footage's real ending, not the original plan. The optional **Seedance 2.0 Skill OS** (install into `.claude/skills/seedance-20/`; see README "Directing layer") supplies the full `directing-engine`, `retake-protocol`, `continuation-handoff`, `seedance-copyright`, and `seedance-antislop` behind this rule; ignore its non-Venice surface/API references.
+38. **Direct the scene, don't decorate it.** Before writing any shot's `description` or `delivery` — in `workshop-episode`, `insert-shot`, or a manual `script.json` edit — decide what the beat is DOING (the turn, POV, power, subtext) and name ONE intention, then derive camera/light/blocking/performance/sound from it. Do not stack "cinematic / epic / beautiful / masterpiece / 4k" adjectives; they give the model nothing to serve. Hold one directorial voice across the episode. This is baked into the `workshop-episode` system prompt (`src/mini-drama/cli.ts`) so both the CLI and the venice-video-mcp `episode.workshop` inherit it. Direct **intention/camera/light/blocking/performance/sound only** — identity is locked downstream (rules 9, 19, 32), so never hand-write full physical character descriptions or reference-image tags into `description`. When a take is close-but-wrong, fix ONE variable at a time; when continuing, direct from the accepted footage's real ending, not the original plan. The optional **Seedance 2.0 Skill OS** (install into `.agents/skills/seedance-20/`; see README "Directing layer") supplies the full `directing-engine`, `retake-protocol`, `continuation-handoff`, `seedance-copyright`, and `seedance-antislop` behind this rule; ignore its non-Venice surface/API references.
 39. **Every AI pass writes a recipe sidecar; finishing passes must append to it.** Each generated/edited asset gets `shot-NNN.recipe.json` (via `appendRecipePass()` in `src/venice/recipe.ts`) — an append-only log where every entry is a replayable Venice call: kind (`generate` / `multi-edit` / `video-generate` / `mechanical`), role (`content` / `identity` / `look` / `mechanical`), model, prompt, negative, seed, cfg, and reference-image paths (stable on-disk paths, never data: URIs). The harness writes it automatically for character refs, storyboard passes 1–3, the seedance launder pass, keyframe extraction, and video renders. **Finishing convention:** shots are finished with AI model calls, not local pixel edits — any post-harness polish/fix pass (agent, MCP, one-off script) must go through `appendRecipePass()` too, which also updates the provenance sidecar in the same write so the Seedance gate stays honest. Roles make finishing safe: `look` passes can be redone freely; `identity` passes (character refine, R2V anchors, seeds, `@Image` mappings) must not be disturbed by a look polish; redoing a `content` pass invalidates everything after it. To regenerate a shot that matches the episode, replay its recipe (same STYLE string, seed, cfg, refs, style anchor — the `.style-anchor.png` in each scene dir is intentionally kept on disk) instead of hand-prompting. The pass-1 `--debug` prompt dump is superseded by this; the recipe is always written.
 40. **Dialogue shots on reference-audio-capable models carry a per-character voice-donor clip (`reference_audio_urls`, bound in-prompt as @AudioN).** When a shot routes to a reference-audio model (Seedance 2.0 R2V family, HappyHorse 1.1 R2V) and the speaker is a visible non-narrator character, the harness attaches that character's voice reference so the native model dialogue keeps the same timbre/accent/pacing across shots. The clip lives at `characters/<slug>/voice-reference.mp3` — generated on demand via `seed-audio-1-0` from the character's `voiceDescription` (or supplied by the operator). The generator auto-creates a missing clip inline before rendering (mirroring the inline dialogue-TTS pattern) and persists `voiceReferencePath` to `character.json`. Wire-in rules: Venice REQUIRES ≥1 reference image alongside reference audio (audio-only is rejected), each clip is 2-15s with an aggregate ≤15s across ≤3 clips (out-of-budget clips dropped + warned), and the @AudioN index in the prompt MUST match the push order into `reference_audio_urls`. The prompt binds it as "Use @Audio1 only for voice identity — timbre, accent, pacing; regenerate clean studio dialogue" so the model doesn't copy any junk-tail noise. Opt-outs: `generate-videos --no-voice-reference`, or series-wide `videoDefaults.voiceReferenceForDialogue: false`. Explicit clips: `generate-voice-reference` / `lock-character --voice-reference <file>` (CLI), `character { action: "generate_voice_reference" }` / `character { action: "lock", voiceReference }` (MCP). Wan 2.7 lip-sync shots do NOT take reference audio — they get `audio_url` instead (rule 32).
 41. **Locations are first-class entities with generated reference images, folded into panels and video like character refs.** A `Location` (name, slug, description, lightingNotes, seed) carries 3 faceless reference angles (`wide` / `medium` / `detail`, generated with `nano-banana-pro`, provenance `hasFace:false`) under `locations/<slug>/`. Tag any shot with `location: <slug>`. Effects: (a) **storyboard Pass 1** injects the location's locked `description` + `lightingNotes` into the panel prompt (serves anti-pattern 7) and adds the wide/medium ref as an environment anchor (closer shot types prefer `medium.png`); (b) **Pass 2 refine** prefers the location ref as the environment/style anchor (characters first, location takes the last free slot); (c) **video**: Kling O3 R2V shots auto-populate `scene_image_urls` from the location (hand-set `sceneImagePaths` override wins); Seedance / HappyHorse (no `scene_image_urls`) get location angles via the reference slot planner (`reference-slots.ts`) — up to ALL THREE angles (wide → medium → detail, closer shot types lead with medium) land in `reference_image_urls` with per-angle `@ImageN` role clauses ("a second angle of the same location"), within the 9-image budget. Create locations with `add-location` / `generate-location-references` (CLI) or the `location` MCP tool (`add` / `generate_references` / `list`). `workshop-episode` also emits a `locations[]` array, tags every shot with a slug, and auto-generates any missing refs right after saving the draft (cost logged). Reuse existing slugs across episodes instead of redefining a place.
@@ -420,7 +420,7 @@ Use `POST /video/quote` (via `quoteVideo()`) to estimate costs before committing
 
 47. **Ask a model for JSON through `client.chatJson()`, never by parsing `post()` yourself.** Reasoning models are now the default, and three things break naive parsing: fences appear inconsistently; some models emit *almost* valid JSON (GLM 5.2 drops a closing brace roughly one attempt in three); and a model with no vision answers an image prompt with an empty string or an opaque 400 rather than a useful error. `chatJson` strips fences, retries once quoting the parse error back to the model, and names the no-vision case explicitly. Related: `describeApiError()` reads all three Venice error shapes — `{error:"..."}`, `{error:{message}}`, and `{issues:[{message}]}` — because reading only `error.message` discarded both the "Did you mean: …" model-not-found hint and the "Image content is not supported by this model" validation message, leaving operators with a bare HTTP status. Reasoning also costs tokens from `max_tokens`, so a budget sized for a plain model can return empty content.
 
-48. **The CLI is self-describing — discover state and order from it, do not guess.** `venice-video agent-guide [--json]` prints the core operating rules (this section in miniature) and ships inside the binary, so it is available even on a bare global install with no `AGENTS.md`. `venice-video pipeline [--json]` prints the ordered stages, their gates, and the command that advances each; it mirrors `classifyEpisode` in `src/session/status.ts` (rule 45 — change both together). `venice-video status -p <project> [--json]` reports where a project stands and the next command. `--json` is supported on `status`, `pipeline`, `agent-guide`, `doctor`, and `queue` (and globally as `venice-video --json <command>`); it prints exactly one JSON object on stdout, and the human text rendering is unchanged. Exit codes are honest — `status` with no project exits non-zero — and ordinary errors are a clean `error:` line, not a stack trace (`VENICE_VIDEO_DEBUG=1` for the stack). The condensed guide is kept in `src/agent/guide.ts` and duplicated as an installable skill at `.claude/skills/venice-agent-guide/`; when a non-negotiable here changes, change those two as well.
+48. **The CLI is self-describing — discover state and order from it, do not guess.** `venice-video agent-guide [--json]` prints the core operating rules (this section in miniature) and ships inside the binary, so it is available even on a bare global install with no `AGENTS.md`. `venice-video pipeline [--json]` prints the ordered stages, their gates, and the command that advances each; it mirrors `classifyEpisode` in `src/session/status.ts` (rule 45 — change both together). `venice-video status -p <project> [--json]` reports where a project stands and the next command. `--json` is supported on `status`, `pipeline`, `agent-guide`, `doctor`, and `queue` (and globally as `venice-video --json <command>`); it prints exactly one JSON object on stdout, and the human text rendering is unchanged. Exit codes are honest — `status` with no project exits non-zero — and ordinary errors are a clean `error:` line, not a stack trace (`VENICE_VIDEO_DEBUG=1` for the stack). The condensed guide is kept in `src/agent/guide.ts` and duplicated as an installable skill at `.agents/skills/venice-agent-guide/`; when a non-negotiable here changes, change those two as well.
 
 49. **Spatial consistency is authored, not inferred — every prompt states placement relative to locked anchors (2026-08-05).** Visual consistency (identity, wardrobe, palette) is handled by the reference stack, but *spatial* consistency — who stands where, which side of frame, facing which way, relative to which landmark — drifts unless it is stated the same way in every generation. The harness now carries geometry as first-class data: (a) **`Location.spatialAnchors`** is the locked geography of a place — 3-5 named landmarks and their fixed relative positions ("bar counter along the back wall; entrance door opposite it; neon window left of the door as seen from the counter"). It is baked into the location reference angles at generation time, injected as "Fixed layout (never rearrange): …" into every panel and video prompt for shots tagged with the location, and is sticky on merge — an existing anchor set is never overwritten by a later script part. (b) **`ShotScript.blocking`** is the shot's authored geometry — 1-2 sentences placing each character/object relative to the named anchors, the frame (screen left/right, foreground/background), and their facing/eyeline. The workshop and script LLM prompts require it for every character shot, with continuity rules: characters keep their screen side and relative positions across consecutive shots unless a movement is written into the action; screen direction and eyelines are preserved (180-degree rule); close-ups still name what is behind/beside the subject. It is injected verbatim (with @ImageN/@ElementN name substitution) into the panel prompt (`BLOCKING: …`), the video prompt (`Blocking: …`), the multi-shot per-beat blocks (both the Seedance native lane and the legacy Kling format), and it seeds the beat's storyboard blocking-plate description. (c) The video prompt's plate clause now forbids mirroring/swapping ("each character stays on the same side of the scene… do not mirror, swap, or rearrange who stands where"), and plateless location shots get a geography-hold clause anchored to the location's first `@ImageN` slot. (d) **QA reads geometry**: `qa-storyboard` evaluates a fourth SPATIAL CONTINUITY dimension against the shot's stated blocking and the location's landmarks, and attaches the nearest prior panel from the same location so side-swaps, mirrored geography, and moved landmarks are caught against real coverage — a spatial flip that breaks the scene is FLAG-CRITICAL. (e) `workshop-episode` warns when character shots are missing `blocking` or locations are missing `spatialAnchors`; `insert-shot` inherits the anchor shot's location and blocking (same-scene splices keep the established geography) and takes `--location` / `--blocking` overrides; `add-location` takes `--spatial-anchors`. The failure mode this kills: characters teleporting across the room, swapping frame sides between coverage, and set geography silently mirroring between shots that read as the same scene (see anti-patterns 20 and 26).
 
@@ -519,29 +519,29 @@ Issues discovered during production and their fixes. The agent should internaliz
 **Symptom:** Agent asked to "edit this footage" started frame-dumping random PNGs from the timeline to decide where to cut, burning tokens without producing a coherent strategy.
 **Root cause:** Frame-dump-first is the wrong substrate for cut decisions. 30 minutes of footage at 24fps = 43,200 frames × ~1,500 tokens = 64M tokens of noise. The LLM cannot hold that context and fabricates its way through the edit.
 **Fix:** Always transcribe first via `scripts/transcribe-sources.ts`, read the resulting `takes_packed.md` (~12KB), and only call `scripts/timeline-view.ts` at explicit decision points (comparing retakes, resolving an ambiguous pause, verifying a mouth-close before a cut). Inspired by browser-use/video-use.
-**Rule:** The text transcript is the primary editing surface. Pixels are consulted on demand only. See `.claude/skills/video-editing/SKILL.md`.
+**Rule:** The text transcript is the primary editing surface. Pixels are consulted on demand only. See `.agents/skills/video-editing/SKILL.md`.
 **Files:** `src/editing/packer.ts`, `scripts/transcribe-sources.ts`, `scripts/timeline-view.ts`
 
 ### 15. Skipping "Propose Strategy, Wait For Confirmation" Causes Throwaway Renders
 **Symptom:** Agent started rendering an EDL before the user had approved the cut strategy. User then asked for a completely different structure, wasting a 15-minute render.
 **Root cause:** The render is cheap to launch and expensive to throw away. Without an explicit pre-render confirmation step, intent is inferred and frequently wrong.
-**Fix:** `.claude/commands/edit-footage.md` step 3 and `.claude/skills/video-editing/SKILL.md` design principle 3 both mandate: post a summary (sources, duration estimate, trim rules, transitions) and wait for "yes / revise / cancel" BEFORE running `renderEdl()`.
+**Fix:** `.agents/commands/edit-footage.md` step 3 and `.agents/skills/video-editing/SKILL.md` design principle 3 both mandate: post a summary (sources, duration estimate, trim rules, transitions) and wait for "yes / revise / cancel" BEFORE running `renderEdl()`.
 **Rule:** Never render without confirmation. The render is cheap; the redo is not. Video-use design principle 3 is non-negotiable.
-**Files:** `.claude/commands/edit-footage.md`, `.claude/skills/video-editing/SKILL.md`
+**Files:** `.agents/commands/edit-footage.md`, `.agents/skills/video-editing/SKILL.md`
 
 ### 16. Auto-Trimming "..." Dead Air From Kokoro VOs Breaks Intended Pacing
 **Symptom:** Filler-word detector was configured to trim all silence gaps ≥ 0.45s. This removed the intentional breath beats rendered by Kokoro for `...` in `VO_TEXT`, producing a rushed, rhythm-less VO.
 **Root cause:** `...` in a Kokoro TTS script renders as an intentional ~0.6s breath gap. It's a creative beat, not dead air.
 **Fix:** `DEFAULT_FILLER_UNIGRAMS` in `src/editing/silence.ts` explicitly excludes `...` and the filler-word detector never touches gaps that were triggered by `...` in aligned mode. Always require user confirmation before a filler trim lands — `you know` and `i mean` can also be content-bearing for certain speakers.
-**Rule:** Never auto-trim silence gaps that originated from a script's `...`. Never land filler-word trims without user confirmation. See `.claude/skills/video-editing/SKILL.md` anti-pattern E2.
-**Files:** `src/editing/silence.ts`, `.claude/skills/burn-in-subtitles/SKILL.md` rules 1-2
+**Rule:** Never auto-trim silence gaps that originated from a script's `...`. Never land filler-word trims without user confirmation. See `.agents/skills/video-editing/SKILL.md` anti-pattern E2.
+**Files:** `src/editing/silence.ts`, `.agents/skills/burn-in-subtitles/SKILL.md` rules 1-2
 
 ### 17. Rendering Overlays As Part Of The EDL Pass
 **Symptom:** Agent baked lower-thirds and title cards into the EDL render, then had to throw away the render when the user wanted to change the overlay wording.
 **Root cause:** Overlays are a post-process, not an edit decision. They belong in a separate compositing pass on top of the delivered cut.
 **Fix:** Overlay designs live in `OverlayManifest` (`src/editing/overlays.ts`), are rendered via `scripts/render-overlay.ts` on top of `final-edit.mp4`, and produce `delivered.mp4`. The EDL render never touches overlays.
 **Rule:** EDL handles cut decisions. Overlays are applied separately. `overlay-designer` agent only runs AFTER the EDL cut is approved.
-**Files:** `src/editing/overlays.ts`, `scripts/render-overlay.ts`, `.claude/agents/overlay-designer.md`
+**Files:** `src/editing/overlays.ts`, `scripts/render-overlay.ts`, `.agents/agents/overlay-designer.md`
 
 ### 18. Not Archiving Prior Renders Before A New Edit
 **Symptom:** A "quick fix" re-render overwrote a 15-minute `final-edit.mp4` before the user had a chance to compare against the prior version.

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 2.14.0 — 2026-08-05
+
+### Changed
+
+- **Provider-neutral workspace: `.claude/` → `.agents/`, `CLAUDE.md` symlink
+  removed.** The knowledge pack (20 command playbooks, 10 sub-agent roles,
+  9 skills, hooks-config) now lives at `.agents/` — a neutral name any coding
+  agent (Cursor, Claude Code, Hermes, OpenClaw, Codex, opencode) can read
+  without implying a provider. Every reference was rewritten: `package.json`
+  `files[]`, `src/agent/guide.ts` (the `agent-guide` text shipped inside the
+  binary), source-comment cross-references, `AGENTS.md`, `README.md`, and all
+  intra-pack links (`hooks-config.json`, skills, commands, agents). The
+  `CLAUDE.md → AGENTS.md` symlink is gone — `AGENTS.md` is the single
+  orchestration hub. Claude Code's own `settings.local.json` was untracked
+  (provider-local state, now git-ignored along with any `.claude/` a specific
+  runner drops in a checkout).
+- **What deliberately still says `.claude`:** external tools' own read paths.
+  Claude Code and Cursor consume skills from `~/.claude/skills/` /
+  `<workspace>/.claude/skills/` — that is their convention, not this repo's
+  layout — so the `venice-video-mcp-install-skills` docs still name those
+  targets, and the optional Seedance Skill OS install still lands wherever
+  the runner reads. Historical CHANGELOG entries are unchanged (they describe
+  the tree as it was). No code behavior changes; docs, packaging, and the
+  embedded agent-guide text only.
+
+## 2.13.1 — 2026-08-05
+
+### Changed
+
+- **README: Video Model Routing catches up with the 2.13.0 multi-shot default.**
+  The routing table gained a "Multi-shot units" row naming
+  `seedance-2-0-enhanced-reference-to-video` as the default lane (`Lens switch.`
+  separators, pure reference mode from the full slot plan) with
+  `kling-o3-pro-image-to-video` demoted to an explicit
+  `videoDefaults.multiShotModel` override, and the "carry these" rule 3 now
+  notes the planner applies Seedance native multi-shot by default. Docs only.
+
 ## 2.13.0 — 2026-08-05
 
 ### Changed

package/README.md

@@ -25,7 +25,7 @@ Most Venice integrations are thin wrappers around API calls. This package is the
 - **Direct Venice API client** with retries, rate limiting, deprecation warnings, and async media polling
 - **Persistent project state** for characters, locations, episodes, references, recipes, and provenance
 - **Comprehensive model registry** covering Venice video, image, audio, and music models
-- **Optional agent orchestration** in `AGENTS.md` and `.claude/` for users who want natural-language operation
+- **Optional agent orchestration** in `AGENTS.md` and `.agents/` for users who want natural-language operation
 
 ## Driving this from an agent
 
@@ -40,9 +40,9 @@ knowledge reaches you, which is the single largest predictor of output quality.
 
 | Surface | How it runs | What you get | Use when |
 |---|---|---|---|
-| **Repo-resident agent** | Agent's cwd is a clone of this repo | Everything: `AGENTS.md` (49 rules, 28 anti-patterns), `.claude/commands/`, `.claude/agents/`, `.claude/skills/`, `.cursor/rules/` | Authoring and iteration — the best results by a wide margin |
+| **Repo-resident agent** | Agent's cwd is a clone of this repo | Everything: `AGENTS.md` (49 rules, 28 anti-patterns), `.agents/commands/`, `.agents/agents/`, `.agents/skills/`, `.cursor/rules/` | Authoring and iteration — the best results by a wide margin |
 | **MCP** | `venice-video-mcp` (on npm) shells out to this CLI | 7 action-discriminated tools, structured JSON responses, progress notifications, plus 4 companion skills carrying the pipeline order | Any agent that supports MCP — Hermes, OpenClaw, Cursor, Claude — with no clone required |
-| **Bare global CLI** | `npm install -g`, shell tool, `--help` | The compiled CLI, this README, `AGENTS.md`, `.claude/skills/`, and the self-describing commands below (`agent-guide`, `pipeline`) | When your runner has a shell but no MCP — start with `venice-video agent-guide` |
+| **Bare global CLI** | `npm install -g`, shell tool, `--help` | The compiled CLI, this README, `AGENTS.md`, `.agents/skills/`, and the self-describing commands below (`agent-guide`, `pipeline`) | When your runner has a shell but no MCP — start with `venice-video agent-guide` |
 
 ### Quick start for Hermes and OpenClaw (no clone, no absolute paths)
 
@@ -58,7 +58,7 @@ requires cloning a repo or hand-writing a path.
 > points the agent at the operating rules — run it once and re-set-up cleanly.
 
 ```bash
-# 1. Install both globally. The harness ships AGENTS.md + .claude/skills/;
+# 1. Install both globally. The harness ships AGENTS.md + .agents/skills/;
 #    the MCP ships its 7 tools and 4 companion skills.
 npm install -g venice-video-harness venice-video-mcp --foreground-scripts
 
@@ -93,15 +93,16 @@ verified here; the shapes above are what to adapt. `venice-video-mcp-install-ski
 
 **The bare-CLI trap, and how to check whether you are in it.** Through version
 **2.9.0** the npm package published only `dist`, `README.md`, `CHANGELOG.md`,
-`LICENSE`, and `scripts/postinstall.mjs`. `AGENTS.md` and `.claude/` were left
+`LICENSE`, and `scripts/postinstall.mjs`. `AGENTS.md` and `.agents/` were left
 out, so an agent working from a global install of those versions had no access to
 the anti-patterns, the model-routing rules, or the pipeline playbooks. It saw a
 flat list of 40-plus commands with no ordering information and no indication of
 which stages were gated. That is the most common reason agent-driven runs produce
 poor output, and it is a knowledge problem rather than a capability problem.
 
-From **2.10.0** onward the package ships `AGENTS.md`, `.claude/commands/`,
-`.claude/agents/`, and `.claude/skills/`. Check what your install actually has:
+From **2.10.0** onward the package ships `AGENTS.md` plus the knowledge pack
+(`commands/`, `agents/`, `skills/` — under `.claude/` through 2.13.x, under the
+provider-neutral `.agents/` from 2.14.0). Check what your install actually has:
 
 ```bash
 ls "$(npm root -g)/venice-video-harness/AGENTS.md"
@@ -114,7 +115,7 @@ package and must do one of the following first:
 1. **Upgrade**, then read the shipped `AGENTS.md`.
 2. **Register the MCP server** (see below). It carries the pipeline order in its
    companion skills and returns JSON instead of prose.
-3. **Clone this repo** and work inside it, so `AGENTS.md` and `.claude/` load
+3. **Clone this repo** and work inside it, so `AGENTS.md` and `.agents/` load
    from the working tree.
 4. **Read `AGENTS.md` from GitHub** and hold its rules in context for the session.
 
@@ -137,7 +138,7 @@ venice-video status -p <dir> --json   # where a project stands and the exact com
 anything, then reach for the full rules and playbooks when you need depth. The
 same core rules are installable as a skill for runners that pull skills from
 GitHub: `hermes skills install jordanurbs/venice-video-harness/venice-agent-guide`
-(and any of the other `.claude/skills/` by name).
+(and any of the other `.agents/skills/` by name).
 
 ### Running the harness in a separate runtime (containers, remote backends)
 
@@ -270,9 +271,10 @@ gate flowchart), `venice-mcp-cookbook` (one worked example per action),
 `venice-mcp-directing` (shot-prompt quality), and `venice-mcp-troubleshooting`
 (every known failure mode). Without them the MCP tools are thin per-command
 wrappers and you will reconstruct the pipeline by trial and error. Claude Code and
-Cursor read `.claude/skills/`; Hermes reads `~/.hermes/skills/`, so `--target
-hermes` installs a `venice` category there. OpenClaw's skills path is not verified
-yet — pass `--dir` once you know it.
+Cursor read `.claude/skills/` (their convention — the installer symlinks there);
+Hermes reads `~/.hermes/skills/`, so `--target hermes` installs a `venice`
+category there. Any other runner: pass `--dir` with its skills path. This repo's
+own knowledge pack lives provider-neutrally in `.agents/`.
 
 ### Preflight: run these three checks first
 
@@ -433,6 +435,8 @@ Anti-Patterns" (28 entries). If you can only carry a few, carry these:
 3. **Prefer Seedance native multi-shot for any 2–3 beat scene.** One generation
    with `Lens switch.` separators holds identity, environment, and lighting
    across the beats and costs roughly 3× less than three separate renders.
+   (Since 2026-08-05 the planner does this by default: multi-shot units render
+   on Seedance R2V Enhanced with the full reference slot plan.)
 4. **Front-load style.** Aesthetic descriptions go at the start of a prompt, not
    the end, or style drifts across angles.
 5. **Keep Seedance prompts under 60 words**, using Subject, Action, Camera,
@@ -457,7 +461,7 @@ Anti-Patterns" (28 entries). If you can only carry a few, carry these:
 12. **Validate model capabilities before sending** `elements`,
     `reference_image_urls`, `scene_image_urls`, `end_image_url`, or `audio_url`.
     The registry is `src/venice/models.ts` in a clone; from a global install use
-    `.claude/skills/venice-video-model-routing/SKILL.md` or the model tables
+    `.agents/skills/venice-video-model-routing/SKILL.md` or the model tables
     below.
 13. **Ask before burning in subtitles**, and derive caption timings from
     `ffmpeg silencedetect` on the rendered voiceover rather than estimating them.
@@ -577,7 +581,7 @@ retries automatically, so the choice costs latency rather than a failed command.
 
 ```
 AGENTS.md                        Agent orchestration hub
-.claude/
+.agents/
   commands/                      19 workflow playbooks (see below)
   agents/                        6 specialized agent roles (see below)
   skills/                        6 Venice and workflow knowledge packs (see below)
@@ -897,7 +901,7 @@ npm run test:legacy
 npm run dev -- <command>
 ```
 
-The repository still includes agent orchestration in `AGENTS.md` and `.claude/`.
+The repository still includes agent orchestration in `AGENTS.md` and `.agents/`.
 Those layers can operate the same execution engine, but the installed
 `venice-video` command does not depend on them.
 
@@ -944,6 +948,7 @@ Every shot renders in **pure reference mode** — no start image — from an ord
 | **Character shots (up to ~6 characters)** | `seedance-2-0-enhanced-reference-to-video` | Default R2V — up to 9 `reference_image_urls` with `@Image` tags (chars + blocking plate + location angles), 1080p, up to 15s, native stereo audio |
 | **Character shots (budget overflow)** | `kling-o3-standard-reference-to-video` | Auto-fallback — structured `elements` for multi-character identity |
 | **Establishing / mood / action** | `seedance-2-0-enhanced-reference-to-video` | Anchors to location reference angles via `@Image` tags |
+| **Multi-shot units (2+ grouped beats)** | `seedance-2-0-enhanced-reference-to-video` | Default since 2026-08-05 — ONE native multi-shot generation with `Lens switch.` separators, pure reference mode from the full slot plan. The old default `kling-o3-pro-image-to-video` (no reference support at all) is an explicit `videoDefaults.multiShotModel` override only |
 
 These defaults are overridable per-project via `series.json` → `videoDefaults`. To target a non-Seedance family (e.g. for accounts that lack Seedance access, or projects that need a different look), set `videoDefaults` to `kling-o3-standard-reference-to-video` (character consistency) and `veo3.1-fast-image-to-video` (atmosphere). Image models default to `nano-banana-2` / `nano-banana-2-edit` for all panels regardless of video family.
 
@@ -1127,7 +1132,7 @@ npx tsx scripts/render-overlay.ts \
   --manifest output/<project>/overlays/manifest.json
 ```
 
-See [`.claude/skills/video-editing/SKILL.md`](.claude/skills/video-editing/SKILL.md) for the full philosophy, EDL format, and editing-specific anti-patterns.
+See [`.agents/skills/video-editing/SKILL.md`](.agents/skills/video-editing/SKILL.md) for the full philosophy, EDL format, and editing-specific anti-patterns.
 
 ## Timeline Export (NLE round-trip)
 
@@ -1172,7 +1177,7 @@ Bug reports are how we'll catch the gaps — the test fixture confirms structure
 
 ## Commands, Agents, and Skills
 
-### Workflow Commands (`.claude/commands/`)
+### Workflow Commands (`.agents/commands/`)
 
 | Command | Purpose |
 |---------|---------|
@@ -1200,7 +1205,7 @@ Bug reports are how we'll catch the gaps — the test fixture confirms structure
 | `ingest-screenplay` | Ingest Fountain/PDF screenplay |
 | `edit-footage` | Text-first editing pipeline for existing media (cuts, trims, re-orders) |
 
-### Specialized Agents (`.claude/agents/`)
+### Specialized Agents (`.agents/agents/`)
 
 | Agent | Role |
 |-------|------|
@@ -1215,7 +1220,7 @@ Bug reports are how we'll catch the gaps — the test fixture confirms structure
 | `remotion-overlay` | Renders one animated overlay as transparent ProRes / WebM |
 | `ffmpeg-overlay` | Emits drawtext specs for static overlays |
 
-### Production Skills (`.claude/skills/`)
+### Production Skills (`.agents/skills/`)
 
 | Skill | Purpose |
 |-------|---------|
@@ -1234,14 +1239,14 @@ The harness is the *production crew* — it locks identity, routes models, QA's
 This principle is already baked into the harness where it matters:
 
 - The **workshop system prompt** (`src/mini-drama/cli.ts`) carries a "DIRECT THE SCENE, DON'T DECORATE IT" block, so both the CLI and the `venice-video-mcp` `episode.workshop` produce directed scripts.
-- `.claude/agents/prompt-engineer.md`, `.claude/skills/shot-composition/SKILL.md`, and `.claude/commands/workshop-episode.md` open with the same directing preface for Claude-Code-in-repo sessions.
+- `.agents/agents/prompt-engineer.md`, `.agents/skills/shot-composition/SKILL.md`, and `.agents/commands/workshop-episode.md` open with the same directing preface for agent-in-repo sessions.
 - The `buildVideoPrompt` builders document the principle so future prompt logic stays directed.
 
 Install Seedance OS to unlock its full `directing-engine`, genre library, `retake-protocol`, `continuation-handoff`, `seedance-copyright`, `seedance-antislop`, and multilingual `vocab/*`:
 
 ```bash
 # Clone the repo (its root is shaped as the seedance-20 skill) into the skills dir:
-git clone https://github.com/emily2040/seedance-2.0 .claude/skills/seedance-20
+git clone https://github.com/emily2040/seedance-2.0 .agents/skills/seedance-20
 ```
 
 **Division of labor to respect:** the harness owns identity (R2V refs + Seedance → Wan keyframe pass), durations (the pre-flight gate + 15s default), and model routing. So use Seedance OS for **intention/camera/light/blocking/performance/sound** only — do not hand-write identity locks, `[Image1]` reference tags, or surface-specific durations into prompts. Skip Seedance OS's `api-status.md` / `surface-prompt-profiles.md` / `api-workflow.md` / `model-name-map.md` (those describe non-Venice surfaces). The `venice-video-mcp` repo's `venice-mcp-directing` skill is the matching bridge for MCP-driven work.

package/dist/agent/guide.js

@@ -63,8 +63,8 @@ export const AGENT_GUIDE = [
         title: 'Where the full knowledge lives',
         points: [
             'AGENTS.md — 49 rules and 28 production anti-patterns, shipped in the package.',
-            '.claude/skills/ — venice-api, venice-video-model-routing, character-consistency, shot-composition, burn-in-subtitles, video-editing, and more.',
-            '.claude/commands/ — 20 step-by-step playbooks; .claude/agents/ — 10 sub-agent roles.',
+            '.agents/skills/ — venice-api, venice-video-model-routing, character-consistency, shot-composition, burn-in-subtitles, video-editing, and more.',
+            '.agents/commands/ — 20 step-by-step playbooks; .agents/agents/ — 10 sub-agent roles.',
             'Read the relevant playbook before running a workflow. Validate model capabilities against src/venice/models.ts before an API call.',
         ],
     },
@@ -75,7 +75,7 @@ export function guideAsJson() {
 export function formatGuide() {
     const lines = [];
     lines.push('Venice Video Harness — core rules for driving this CLI from an agent');
-    lines.push('Full rules: AGENTS.md · Playbooks: .claude/commands/ · Knowledge: .claude/skills/');
+    lines.push('Full rules: AGENTS.md · Playbooks: .agents/commands/ · Knowledge: .agents/skills/');
     lines.push('');
     for (const section of AGENT_GUIDE) {
         lines.push(`## ${section.title}`);

package/dist/editing/self-eval.d.ts

@@ -1,7 +1,7 @@
 /**
  * Self-evaluation driver for the editing pipeline.
  *
- * The cut-qa agent (`.claude/agents/cut-qa.md`) is the intelligent layer;
+ * The cut-qa agent (`.agents/agents/cut-qa.md`) is the intelligent layer;
  * this module is the mechanical layer that:
  *   1. Enumerates cut boundaries from an EDL
  *   2. Runs each boundary through the six programmatic checks

package/dist/editing/self-eval.js

@@ -1,7 +1,7 @@
 /**
  * Self-evaluation driver for the editing pipeline.
  *
- * The cut-qa agent (`.claude/agents/cut-qa.md`) is the intelligent layer;
+ * The cut-qa agent (`.agents/agents/cut-qa.md`) is the intelligent layer;
  * this module is the mechanical layer that:
  *   1. Enumerates cut boundaries from an EDL
  *   2. Runs each boundary through the six programmatic checks

package/dist/editing/silence.d.ts

@@ -2,7 +2,7 @@
  * Silence-gap and filler-word detection.
  *
  * Built on the same `ffmpeg silencedetect` pattern used by
- * `.claude/skills/burn-in-subtitles/scripts/derive-captions.ts`. Reused here
+ * `.agents/skills/burn-in-subtitles/scripts/derive-captions.ts`. Reused here
  * rather than duplicated.
  *
  * Filler words are identified from word-level transcripts (not audio), so

package/dist/editing/silence.js

@@ -2,7 +2,7 @@
  * Silence-gap and filler-word detection.
  *
  * Built on the same `ffmpeg silencedetect` pattern used by
- * `.claude/skills/burn-in-subtitles/scripts/derive-captions.ts`. Reused here
+ * `.agents/skills/burn-in-subtitles/scripts/derive-captions.ts`. Reused here
  * rather than duplicated.
  *
  * Filler words are identified from word-level transcripts (not audio), so

package/dist/mini-drama/prompt-builder.d.ts

@@ -99,7 +99,7 @@ export declare function buildImagePrompt(shot: ShotScript, series: SeriesState):
 /**
  * Build a video-generation prompt for a shot.
  *
- * Directing principle (see .claude/agents/prompt-engineer.md and the README
+ * Directing principle (see .agents/agents/prompt-engineer.md and the README
  * "Directing layer"): this assembles the prose that DIRECTS the shot -- one
  * intention expressed through camera, light, blocking, performance, and sound
  * -- not a pile of "cinematic" adjectives. It intentionally leans on the

package/dist/mini-drama/prompt-builder.js

@@ -268,7 +268,7 @@ function summarizeCharacterForMultiShot(char, wardrobeOverride, elementSlot) {
 /**
  * Build a video-generation prompt for a shot.
  *
- * Directing principle (see .claude/agents/prompt-engineer.md and the README
+ * Directing principle (see .agents/agents/prompt-engineer.md and the README
  * "Directing layer"): this assembles the prose that DIRECTS the shot -- one
  * intention expressed through camera, light, blocking, performance, and sound
  * -- not a pile of "cinematic" adjectives. It intentionally leans on the

package/dist/storyboard/prompt-builder.d.ts

@@ -99,7 +99,7 @@ export declare function buildPrompt(shot: Shot, scene: Scene, aesthetic: Aesthet
  * movement, subject + action, setting, style, and audio cues. Only the
  * aesthetic register relevant to the current scene is included.
  *
- * Directing principle (see .claude/agents/prompt-engineer.md and the README
+ * Directing principle (see .agents/agents/prompt-engineer.md and the README
  * "Directing layer"): the prose should DIRECT the shot -- one intention
  * expressed through camera/light/blocking/performance/sound -- rather than
  * stack "cinematic" adjectives. Camera, angle, and movement come from the

package/dist/storyboard/prompt-builder.js

@@ -497,7 +497,7 @@ function extractRegister(fullText, sceneNumber) {
  * movement, subject + action, setting, style, and audio cues. Only the
  * aesthetic register relevant to the current scene is included.
  *
- * Directing principle (see .claude/agents/prompt-engineer.md and the README
+ * Directing principle (see .agents/agents/prompt-engineer.md and the README
  * "Directing layer"): the prose should DIRECT the shot -- one intention
  * expressed through camera/light/blocking/performance/sound -- rather than
  * stack "cinematic" adjectives. Camera, angle, and movement come from the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "venice-video-harness",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Standalone consistency-first video production CLI powered by the Venice API",
   "homepage": "https://github.com/jordanurbs/venice-video-harness",
   "repository": {
@@ -72,9 +72,9 @@
     "LICENSE",
     "AGENTS.md",
     "HERMES-AGENT-SETUP.md",
-    ".claude/commands",
-    ".claude/agents",
-    ".claude/skills",
+    ".agents/commands",
+    ".agents/agents",
+    ".agents/skills",
     "scripts/postinstall.mjs"
   ],
   "engines": {