Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: complete Narratage skill and Quickstart

rpone45e93ac66b82
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.md
index 56ca2e91..02cc79d0 100644
--- a/.agents/skills/narratage/SKILL.md
+++ b/.agents/skills/narratage/SKILL.md
@@ -1,6 +1,6 @@
---
name: narratage
-description: Author, check, plan, build, inspect, and retrieve Narratage/SVML video graphs; configure the cross-platform Node/pnpm/Python runtime; reverse-engineer reference video directly into .svml/.svs/.svrun sources; and apply production playbooks for prompts, continuity, captions, B-roll, overlays, audio, and common video formats. Use for this svml repository, its quickstart, SVML authoring, runtime profiles, VLM reference reconstruction, or video craft decisions. Never use a JSON storyboard as the VLM-to-SVML intermediate.
+description: Author, check, plan, build, inspect, and retrieve Narratage/SVML video sources; configure the cross-platform Node/pnpm/Python runtime and API keys; reconstruct reference video directly as .svml/.svs/.svrun sources; and apply native SVML production playbooks for prompts, continuity, captions, B-roll, overlays, audio, and common video formats. Use for this svml repository, its quickstart, SVML authoring, runtime profiles, reference-video reconstruction, or video craft decisions.
---
# Narratage
@@ -15,10 +15,11 @@ Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.
`docs/quickstart/`.
- Seedance prompt assembly → read `references/seedance-kits.md`; reuse an official vendored Kit and
SVS Recipe before writing format scaffolding by hand.
-- Production craft or format choice → read `references/playbooks/index.md` and
- `references/playbooks/svml-mapping.md`, then only the relevant craft/format file.
-- Reference-video reverse engineering → read `references/reference-vlm.md`; have VLM emit
- `main.svml`, optional `studio.svs`, and `build.svrun` directly, never a JSON storyboard.
+- Production craft or format choice → read `references/playbooks/index.md`,
+ `references/playbooks/craft/production-gates.md`, and
+ `references/playbooks/craft/visual-continuity.md`, then the relevant craft/format file.
+- Reference-video reconstruction → read `references/reference-vlm.md`; emit `main.svml`, optional
+ `studio.svs`, and `build.svrun` directly.
- Execution, Runtime control, Build inspection, or output retrieval → read
`references/runtime.md`; diagnose and start the durable Runtime, `check` Author Source, `plan`
before paid work, then submit, inspect, and retrieve the Build.
@@ -28,10 +29,10 @@ Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.
```bash
node --run narratage -- doctor path/to/svml.runtime.json
node --run narratage -- runtime up path/to/svml.runtime.json
-node --run narratage -- check path/to/main.svml --package-lock path/to/svml.packages.lock --root .
-node --run narratage -- plan path/to/build.svrun --package-lock path/to/svml.packages.lock --root .
+node --run narratage -- check path/to/main.svml --runtime path/to/svml.runtime.json --root .
+node --run narratage -- plan path/to/build.svrun --runtime path/to/svml.runtime.json --root .
node --run narratage -- build path/to/build.svrun --runtime path/to/svml.runtime.json \
- --package-lock path/to/svml.packages.lock --root . --build-id my-build-001 --follow
+ --root . --build-id my-build-001 --follow
node --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.json
node --run narratage -- get my-build-001 --runtime path/to/svml.runtime.json \
--name final.video --to path/to/output/final.mp4
@@ -41,5 +42,9 @@ Treat `--follow` as an observer: stopping it does not stop the durable Build. Us
only to stop the Worker and Runtime-owned programs; it does not cancel Builds or remote Provider
work.
+Pin and reuse every accepted generated image or take in the next `.svrun` with `build-record` plus
+`satisfy`. Set the consuming Target to accept the declared fidelity, then review the frozen plan
+before paid downstream work.
+
Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of commits.
The repository's docs remain the syntax authority.
diff --git a/.agents/skills/narratage/agents/openai.yaml b/.agents/skills/narratage/agents/openai.yaml
index 80697cf9..c71f5959 100644
--- a/.agents/skills/narratage/agents/openai.yaml
+++ b/.agents/skills/narratage/agents/openai.yaml
@@ -1,4 +1,4 @@
interface:
display_name: "Narratage"
short_description: "Build SVML videos with production playbooks"
- default_prompt: "Use $narratage to author, validate, or refine a Narratage video graph and its production craft."
+ default_prompt: "Use $narratage to author, validate, or refine native SVML video sources and production craft."
diff --git a/.agents/skills/narratage/references/credentials.md b/.agents/skills/narratage/references/credentials.md
index 7c963ad4..a86b956e 100644
--- a/.agents/skills/narratage/references/credentials.md
+++ b/.agents/skills/narratage/references/credentials.md
@@ -13,7 +13,10 @@ by the selected Runtime Profile:
macOS/Linux session example:
```bash
-read -r -s KIE_API_KEY; export KIE_API_KEY
+read -r -s KIE_API_KEY
+export KIE_API_KEY
+read -r -s MIMO_API_KEY
+export MIMO_API_KEY
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_APPLICATION_CREDENTIALS_JSON="$(<"$HOME/.config/narratage/google-service-account.json")"
```
@@ -22,9 +25,12 @@ Windows PowerShell session example:
```powershell
$env:KIE_API_KEY = "your-key"
+$env:MIMO_API_KEY = "your-key"
$env:GOOGLE_CLOUD_PROJECT = "your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS_JSON = Get-Content -Raw "$HOME\.config\narratage\google-service-account.json"
```
Keep keys outside Author/Run/Runtime source and committed files. Verify presence without printing
-values with `scripts/check-credentials.mjs`, then run `pnpm narratage doctor <profile>`.
+values with, for example,
+`node .agents/skills/narratage/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY`, then run
+`node --run narratage -- doctor <profile>`.
diff --git a/.agents/skills/narratage/references/environment.md b/.agents/skills/narratage/references/environment.md
index 72c056c1..591f6f88 100644
--- a/.agents/skills/narratage/references/environment.md
+++ b/.agents/skills/narratage/references/environment.md
@@ -5,6 +5,19 @@ WhisperX/OpenCV, `uv` for locked Python environments, and `ffmpeg`/`ffprobe` for
macOS/Linux or Windows PowerShell:
+```text
+node .agents/skills/narratage/scripts/check-environment.mjs
+```
+
+If the probe reports `corepack missing` (some newer Node.js distributions do not bundle it), install
+a compatible release from either shell:
+
+```text
+npm install --global [email protected]
+```
+
+Then install and validate the workspace:
+
```text
corepack enable
corepack prepare [email protected] --activate
diff --git a/.agents/skills/narratage/references/playbooks/craft/b-roll.md b/.agents/skills/narratage/references/playbooks/craft/b-roll.md
index abf9da9e..e758e0ec 100644
--- a/.agents/skills/narratage/references/playbooks/craft/b-roll.md
+++ b/.agents/skills/narratage/references/playbooks/craft/b-roll.md
@@ -1,19 +1,94 @@
# B-roll craft
-- Use the vendored `broll-v1` Kit with `text:Render`. Put `material-mode`, `story-shape`,
- `edit-language`, `camera-language`, and `motion-intensity` in an SVS Recipe; connect only the
- shot-specific micro-story through the required `story` slot.
-- Choose the narrative scene before writing prompts. A useful product arc is **problem → failed
- effort → product/mechanism → payoff**, but use the number of beats the story needs.
-- Design each shot as a paired package: the image prompt establishes every visible fact; the video
- prompt adds only motion over those facts. Audit every noun and relationship in the video prompt
- against its image prompt.
-- Adjacent shots must carry different information. Change location, camera relation, action, prop
- relation, or emotional state; do not make cosmetic crops.
-- B-roll is silent. Put narration, music, and effects on explicit audio components.
-- Clamp generated shots to 4–15 seconds. Longer material becomes continuous parts sharing one image.
-- For software demos, use complementary context and proof images: person/device relationship first,
- then a device-screen shot from a physically possible reverse viewpoint. Use real supplied UI when
- exact fidelity matters.
-- Put changing text, labels, arrows, and cards in `text:Track`/`media-track:Track`. Keep product labels and
- UI text physically attached to the product or screen.
+B-roll is authored visual evidence, context, or emotional progression outside the primary speaking
+take. Every insert must earn its place in the story and remain independent from editorial text and
+program audio.
+
+## Choose the story beats first
+
+- Write the shot list before writing prompts. Give every shot one clear job: establish context, show
+ a problem, demonstrate failed effort, reveal a mechanism, provide proof, or deliver a payoff.
+- A useful product arc is **problem → failed effort → mechanism/product → payoff**, but the number of
+ beats follows the actual story rather than a fixed template.
+- Adjacent shots must contribute different information. Change the location, camera relationship,
+ action, prop relationship, evidence, or emotional state; a cosmetic crop is not a new shot.
+- Decide whether each beat needs generated motion, a supplied image, a supplied video, or an authored
+ graphic before choosing components.
+
+## Author generated B-roll in SVML
+
+1. Put the reference-frame prompt in an English `copy:Value` and generate the image with an explicit
+ image Surface such as `gpt:Image`.
+2. Pass the image through the image gate in `production-gates.md` before using it as a video reference.
+3. Vendor `broll-v1.svs`, choose the stable material/story/edit/camera/motion axes in an SVS Recipe,
+ and put only the shot-specific micro-story in an English `copy:Value`.
+4. Render the Kit with `copy:Render` and connect the story through `copy:Set`.
+5. Generate through `seedance:ReferenceVideo` with `generate-audio="false"` and explicit ordered
+ references.
+6. Place accepted shots with `media-track:Track` and `media-track:Item` or `media-track:Sequence`.
+
+```svml
+<copy:Value id="demo-story">
+ The hand places the device on the desk, wakes the screen, and pauses as the result becomes visible.
+</copy:Value>
+
+<copy:Render id="demo-prompt"
+ template={broll-kit.broll-v1} recipe={studio.broll.screen-demo}>
+ <copy:Set name="story" text={demo-story}/>
+</copy:Render>
+
+<seedance:ReferenceVideo id="demo-motion" model="mini"
+ prompt={demo-prompt} duration="6" resolution="720p"
+ aspect-ratio="9:16" generate-audio="false">
+ <seedance:Reference image={demo-frame.image}/>
+</seedance:ReferenceVideo>
+```
+
+Use the model limits and prompt rules in `seedance-directing.md`. Generated B-roll supplies pictures
+only; narration, music, and effects remain explicit audio contributions.
+
+## Design the image and motion prompt as one package
+
+- The image prompt establishes every visible fact: subject, identity, location, wardrobe, props,
+ object count, camera geometry, emotion, and initial physical state.
+- The video story adds only motion over those established facts. Audit every person, object,
+ relationship, and emotional starting point in the video text against the accepted image.
+- Direct one or two readable events with macro action and small facial/postural feedback. Do not add
+ a new room, person, outfit, prop, or unexplained camera angle during the shot.
+- Give every manipulated object a plausible starting contact and short motion envelope. Preserve its
+ count, shape, label, and distinctive physical features throughout the take.
+- When a document, device screen, receipt, or product label must stay unchanged, use a continuous-shot
+ edit language and a reference-locked camera treatment.
+
+## Place B-roll by authored meaning
+
+- Mark the intended spoken range as a Script `Selection`, then use `during={story.selection.NAME}` on
+ the Media Item and pass `{timing.map}` to the Track.
+- For a point event, declare a Script `Moment` and use `at={story.moment.NAME}` with an explicit `for`.
+- For silent programs or intentionally absolute edits, use `during="program"` or explicit `start` and
+ `end` expressions in the shared ProgramSpace.
+- For a non-contiguous Selection, choose `occurrences="each"` only when the same insert should appear
+ at every occurrence; otherwise author separate Items.
+- Create J-cuts and L-cuts in the Script boundaries: let narration establish a few words before the
+ B-roll opens, and let speech continue before or after the picture returns. Do not make every visual
+ cut start and end exactly with a complete spoken sentence.
+
+## Protect screens, text, and reverse views
+
+- Keep physical UI and product text attached to the screen, label, document, or sign. Put editorial
+ titles, arrows, comparisons, and cards on `typo:Track` or `media-track:Track`.
+- When exact UI or brand artwork matters, use the supplied asset as authored media rather than asking
+ a generator to recreate it.
+- A person-facing view and its device-facing reverse view must pass the hard geometry gate in
+ `visual-continuity.md`: opposing camera positions require different background sectors and different
+ dominant landmark sets. The same main background is an automatic rejection.
+- Follow `screen-demo.md` for context/proof pairs and physically possible screen orientation.
+
+## Accept and reuse shots
+
+- Review each generated image before its video, then review each video before Track assembly.
+- Reject identity drift, same-background reverse views, impossible contact, duplicated props,
+ unstable screen content, unwanted text, broken end frames, or motion that does not start from the
+ accepted reference.
+- Pin accepted image and video outputs in the next `.svrun` with `build-record` and `satisfy`, so
+ only failed shots are regenerated.
diff --git a/.agents/skills/narratage/references/playbooks/craft/captions.md b/.agents/skills/narratage/references/playbooks/craft/captions.md
index a0db4408..e3514eb9 100644
--- a/.agents/skills/narratage/references/playbooks/craft/captions.md
+++ b/.agents/skills/narratage/references/playbooks/craft/captions.md
@@ -1,11 +1,86 @@
# Caption craft
-- Use one `caption:Program` and one `caption-fine:Track` for the program. Route speakers and styles through role/word rules,
- not duplicate caption tracks.
-- Keep the spoken Script authoritative. Transcribe real audio; do not copy burned-in reference
- subtitles. Preserve original-language speech and translate separately when needed.
-- Use the WhisperX SemanticMap for timing. `caption-gemini:Planner` may group whole display Atoms but cannot rewrite
- text, invent timing, or split an indivisible Dual Text Atom.
-- Keep captions in a safe region, avoid faces/product/UI, and use a stable-size Recipe when uniform
- readability matters. Hide words with an explicit visibility rule, not by deleting source text.
-- If a format intentionally has no captions, omit caption components entirely.
+Captions are one program-wide interpretation of the authoritative Script, measured against the real
+speech program. Do not create separate caption systems for speakers, regions, or styles.
+
+## Author one caption pipeline
+
+Use one pipeline for the program:
+
+```text
+exact font → caption-fine:Style → caption:Program → caption-ai:Planner
+ +
+ whisperx:Alignment map
+ ↓
+ caption-fine:Track
+```
+
+```svml
+<fonts:Stack id="caption-font" family="inter" weight="700"
+ style="normal" emoji="color"/>
+<caption-fine:Style id="primary-caption"
+ recipe={studio.caption.primary} font={caption-font}/>
+
+<caption:Program id="caption-program" display={story.caption}
+ default={primary-caption}>
+ <caption:Use role="HOST" style={host-caption}/>
+ <caption:Use words={story.caption.selection.product}
+ style={product-caption}/>
+ <caption:Mute words={story.caption.selection.private}/>
+</caption:Program>
+
+<caption-ai:Planner id="caption-plan" display={story.caption}
+ program={caption-program} model="gemini-2.5-flash"/>
+
+<caption-fine:Track id="captions" display={story.caption}
+ correspondence={story.caption.correspondence}
+ map={timing.map} space={speech.space}
+ program={caption-program} plan={caption-plan.plan}/>
+```
+
+Add `{captions.track}` to `film:Film` as one peer Visual Track. If the format intentionally has no
+captions, omit the Caption components entirely.
+
+## Keep the Script authoritative
+
+- Preserve the exact Script display text. Do not copy burned-in reference subtitles or rewrite the
+ spoken source to match an existing visual caption.
+- Use Dual Text when display and pronunciation differ. A Dual Text Atom is indivisible for timing and
+ planning; do not expect the Planner to split it internally.
+- Use `caption:Use role` for speaker-wide style and `caption:Use words` for a Script Selection's
+ caption-word projection. Ordered rules replace the complete Style, with the last matching rule
+ winning.
+- Use `caption:Mute` to hide complete display Atoms without deleting Script words, changing speech,
+ or regrouping Cues.
+- Preserve original-language dialogue. Translation or alternate-language delivery is a separate
+ authored Script decision, not a caption-planner rewrite.
+
+## Separate planning from timing
+
+- `caption-ai:Planner` receives immutable display Atoms and resolved Style runs. It may place Cue cuts
+ only between complete Atoms and attach fields declared by the Style family.
+- The Planner does not see audio, rewrite text, select Styles, or invent timestamps.
+- `whisperx:Alignment` measures the accepted `speech:Spine` audio and produces the SemanticMap used by
+ `caption-fine:Track`.
+- Recheck alignment whenever the speech audio changes. A Style-only change does not prove that a
+ prior visual review is still valid.
+
+## Design for readability
+
+- Define one explicit default Style covering every word, then use only the overrides the story needs.
+- Keep caption placement inside a safe region and clear of faces, products, device screens, buttons,
+ and essential evidence.
+- Use consistent font bytes, width, size, line height, Cue bounds, and padding when stable readability
+ matters. Avoid decorative motion or active scaling that makes consecutive Cues appear unrelated.
+- Short spoken phrases remain complete even when they cannot satisfy a preferred minimum word count.
+ Never remove words merely to force a visual layout target.
+- Treat captions and editorial overlays as separate Tracks with deliberate stack orders and spatial
+ regions so they do not compete for the same area.
+
+## Review the actual program
+
+- Review the full delivery with real speech timing, not only a still frame or a structural plan.
+- Verify every word, Role Style, muted Atom, Cue boundary, timing window, line wrap, safe zone, and
+ overlap with Media/Text Tracks.
+- Listen while reviewing: a visually plausible Caption Track still fails if it leads or trails the
+ actual spoken word.
diff --git a/.agents/skills/narratage/references/playbooks/craft/image-prompt-style.md b/.agents/skills/narratage/references/playbooks/craft/image-prompt-style.md
index dd82522c..30fc2f7a 100644
--- a/.agents/skills/narratage/references/playbooks/craft/image-prompt-style.md
+++ b/.agents/skills/narratage/references/playbooks/craft/image-prompt-style.md
@@ -1,18 +1,51 @@
-# Image prompt craft
+# Image generation and prompt craft
-Use English prompts for GPT Image and Seedance reference frames. Describe the final desired image,
-not a list of edits to a source image.
+## Author images in SVML
-## Four-part structure
+- Put each prompt in a `copy:Value` from `@narratage/text@1`.
+- Generate with an explicit image Surface such as `gpt:Image`, `nano:Image`, `nano:ProImage`,
+ `seedream:TextImage`, or `seedream:ReferenceImage`. Use the exact package README for its ports.
+- Connect every identity, product, scene, or UI reference as a visible Artifact edge. For GPT Image,
+ use ordered `gpt:Reference` children and consume `{shot.image}` downstream.
+- Set aspect ratio and resolution on the model Surface. Do not put pixels, resolution, or aspect-ratio
+ tokens into prompt prose.
-1. **Reality contract:** realistic iPhone video-frame photograph; natural, non-glossy, clear
- background, realistic skin texture, natural light, no visual artifacts.
-2. **Subject/story:** person, product, location, wardrobe, action, emotion, and physical objects.
-3. **Camera/reference relationship:** shot size, camera ownership/placement, spatial direction, and
- explicit identity/product reference reuse.
-4. **Texture close:** repeat a short reality contract if needed for a stable ending.
+## Write every generation prompt in English
-Do not put resolution, pixels, or aspect ratio in prose; use model parameters. Do not use conditional
-language or mutually exclusive states; split different states into separate prompts. When using a
-reference, state what it represents and what remains consistent. Use absolute spatial instructions
-instead of “mirror”. The first identity anchor should show a clear complete face with both eyes visible.
+Use four ordered parts:
+
+1. **Reality contract:** name the capture medium and texture, such as a realistic phone-video frame,
+ natural light, visible background detail, realistic skin/material texture, and unpolished motion-frame
+ character.
+2. **Visible story:** state the exact person/product, wardrobe, location, action, emotion, objects,
+ object count, and initial physical state that must be visible.
+3. **Camera geometry:** state shot size, camera owner/placement, height, direction, lens relationship,
+ reflection logic, and which requested objects must fit inside the frame.
+4. **Reference contract:** assign each reference a role and state which identity, product geometry,
+ room, or UI fact remains stable.
+
+Describe the final image directly. Do not write an edit-operation checklist, conditional branches,
+or long negative inventories containing unwanted concrete objects. Split mutually exclusive states
+into separate prompts.
+
+## Keep people and cameras physically possible
+
+- Make the first generated identity anchor a clear complete face with both eyes visible. Vary face
+ direction naturally only after that anchor exists.
+- Respect hand occupancy. A person holding a phone or product cannot simultaneously have both hands
+ free; assign only physically necessary tasks and avoid arbitrary left/right choreography.
+- For a selfie, specify one real camera topology: an arm-held front camera, a mirror/reflective-surface
+ shot with explainable reflection geometry, or a fixed low/front camera. If another person or a
+ third-party camera owns the shot, do not call it a selfie.
+- Make shot size agree with the story. Do not place essential feet, table-under actions, or lower-body
+ props outside a close or waist-up frame.
+- For reverse views, define both background sectors before writing prompts and apply the hard rule in
+ `visual-continuity.md`.
+- Make before/after states visibly distinguishable through the authored condition, posture, setting,
+ styling, or evidence while preserving the intended recurring identity and product facts.
+
+## Accept images before reuse
+
+Run the image gate in `production-gates.md`. When image viewing is available, inspect the actual
+output and reject identity drift, impossible anatomy/camera geometry, duplicate props, wrong text,
+same-background reverse views, watermarks, and unusable overlay clearance before downstream use.
diff --git a/.agents/skills/narratage/references/playbooks/craft/overlays.md b/.agents/skills/narratage/references/playbooks/craft/overlays.md
index 2da1fb6f..ca44d367 100644
--- a/.agents/skills/narratage/references/playbooks/craft/overlays.md
+++ b/.agents/skills/narratage/references/playbooks/craft/overlays.md
@@ -1,17 +1,67 @@
# Overlay craft
-- Base and overlays are complementary. Base prompts ignore captions, stickers, arrows, cards, UI,
- logos, and transition graphics; overlay analysis ignores the photographed base.
-- Preserve every distinct changing or scrolling text segment. Put editable text in `text:Value`
- inputs and `text:Track`/`text:Area` content, not hard-coded generated segments.
-- Infer alignment across frames: left, center, or right anchoring is a continuity decision. Keep text
- inside safe zones and away from faces, products, and key UI.
-- Classify non-text layers by source: `real` photographed PIP/B-roll may be generated; `provided`
- screenshots, UI, charts, finished graphics, logos, and alpha stickers require supplied media.
-- Prefer semantic timing through a Script `Selection` or `Moment` resolved by the WhisperX
- `SemanticMap`: use `during={story.selection.<id>}` for a range or `at={story.moment.<id>}` with
- an explicit `for` duration for a point. Without speech timing, use `during="program"` or explicit
- author-time `start`/`end` values in the shared `ProgramSpace`; never infer a window from a source
- video's original timestamps.
-- Report unsupported effects with a reason. Build an approximation only when the gap stays attached
- to the authored element; never silently downgrade.
+An overlay should add information the photographed or generated base does not already communicate.
+Keep every overlay as an explicit peer Track with its own content, placement, timing, appearance, and
+stack order.
+
+## Give every overlay one job
+
+- Use an overlay to name, emphasize, compare, direct attention, or add necessary context. Remove any
+ layer whose only function is decoration.
+- Keep copy short enough to read in one scan. Put explanations in speech or captions rather than a
+ second paragraph inside a badge or lower third.
+- Present related title, label, icon, and card elements as one clear hierarchy on the same story beat.
+- Use a small stable visual vocabulary. Color, size, border, paint, and motion should express hierarchy,
+ not random variation.
+- Keep base-generation prompts free of editorial captions, arrows, cards, floating logos, and UI
+ callouts. Author those elements separately.
+
+## Choose the native overlay surface
+
+Use `typo:Track` for editable typography:
+
+- declare exact font bytes with `fonts:Stack` or `media:Font`;
+- compile appearance with `typo:Style` and an SVS Recipe;
+- choose `typo:Point`, `typo:Area`, or `typo:Path` according to the intended geometry;
+- put reusable plain copy in `copy:Value` and connect it through `content={copy}`.
+
+Use `media-track:Track` for images, generated/supplied video, prepared media, or an already-authored
+compositable surface:
+
+- place every Item in an explicit `space:Frame`;
+- select one source form: `image` with `extent`, `video`, `media`, or `surface`;
+- keep fitting, clipping, frame paint, border, shadow, and lifecycle motion in SVS Recipes;
+- use ordered Layers for a deliberate composite and `media-track:Sequence` for changing visual states.
+
+Changing or scrolling content must remain explicit. Author distinct timed Text/Media Items or a
+Sequence for each state; do not bake several states into one generated image.
+
+## Bind overlays to story time
+
+- Use `during={story.selection.NAME}` for a semantic range and pass `{timing.map}` to the Track.
+- Use `at={story.moment.NAME}` with an explicit `for` duration for a point event.
+- Use `during="program"` for persistent overlays and explicit `start`/`end` expressions for deliberate
+ author-time placement.
+- Use `occurrences="each"` only when one authored item should repeat at every non-contiguous Selection
+ occurrence.
+- Let an overlay appear when the information is actually spoken or visible, and leave enough time to
+ read it. Do not place important copy only in the final instant of a shot.
+
+## Preserve source truth
+
+- Use supplied screenshots, charts, finished graphics, logos, and alpha artwork as media when their
+ exact appearance matters.
+- Keep editable text as Text, not rasterized generator output.
+- Preserve alignment across related frames. Left, center, or right anchoring is a continuity decision,
+ not an incidental per-frame choice.
+- Keep overlays clear of captions, faces, product labels, key UI, gestures, and the base shot's main
+ evidence. Resolve collisions by moving or simplifying the overlay before reducing readability.
+
+## Review overlays in motion
+
+- Watch the full sequence to evaluate entry timing, reading time, hierarchy, transition rhythm, and
+ exit timing; a still image cannot validate these properties.
+- Check every overlay both with captions present and with the surrounding Media Tracks visible.
+- When the screen feels crowded, remove information before accelerating animations or shrinking type.
+- Verify the final `film:Film` stack order. Higher recipe `stack-order` values render above lower ones,
+ so accidental ordering can hide otherwise correct content.
diff --git a/.agents/skills/narratage/references/playbooks/craft/persona-and-audio.md b/.agents/skills/narratage/references/playbooks/craft/persona-and-audio.md
index 5d3584d9..6aaccf4e 100644
--- a/.agents/skills/narratage/references/playbooks/craft/persona-and-audio.md
+++ b/.agents/skills/narratage/references/playbooks/craft/persona-and-audio.md
@@ -1,12 +1,80 @@
# Persona and audio craft
-- Establish identity from a clear visual anchor and voice from real audio. Do not infer voice from
- appearance alone.
-- Keep one stable persona per recurring speaker: face, age range, vocal texture, delivery, accent,
- pace, and emotional register. Preserve the original-language sample line verbatim.
-- Keep reference audio short and clean; trim silence and unrelated voices. Respect provider/model
- reference-duration limits and inspect duration before planning.
-- Choose the voice before finalizing shot timing when TTS is the sole source. One continuous voiceover
- can cover independently selected visual cuts; do not split TTS merely to mirror each shot.
-- Keep speech, music, and effects as separate explicit `audio:Track` contributions made of
- `audio:Clip` items. Dialogue wins the mix.
+Treat visual identity, voice identity, spoken truth, music, and effects as separate authored facts.
+Connect only the references a component actually needs.
+
+## Establish authoritative identity
+
+- Choose one clear visual anchor for each recurring person and product. Declare supplied anchors with
+ `media:Image`, or reuse an accepted generated image Record through the Run Source.
+- Choose voice from real supplied audio, an explicit preset, a written voice design, or an explicit
+ clone sample. Never infer a person's voice, accent, age, or delivery from appearance alone.
+- Keep one persona contract across recurring takes: face, apparent age range, hair, wardrobe logic,
+ vocal texture, accent, pace, delivery, and emotional register.
+- Preserve quoted sample dialogue verbatim in its original language. All generation instructions and
+ voice-design descriptions are written in English.
+- Trim reference audio to a clean, representative passage without unrelated speakers, long silence,
+ music, clipping, echo, or abrupt edits.
+
+## Author faces and voices explicitly
+
+- Use `gpt:Image` with ordered `gpt:Reference` children when a new character/scene image must preserve
+ supplied identity or product facts. Pass every generated image through `production-gates.md`.
+- Use `mimo:Preset` for a selected built-in voice, `mimo:VoiceDesign` for an English voice description,
+ or `mimo:VoiceClone` with one explicit `sample` Artifact.
+- Feed exact Script speech text through each MiMo component's `speech={story.segment.NAME.speech}`
+ edge. Voice instructions affect delivery; they do not replace or rewrite Script words.
+- For Seedance speaking formats, render the matching Kit and connect image/audio references to
+ `seedance:ReferenceVideo` in the exact order defined by `seedance-directing.md`.
+- Do not add a face or voice reference to a shot that does not need that identity. Extra references
+ increase ambiguity and can contaminate the intended subject.
+
+## Plan voice before picture duration
+
+- When TTS is the sole narration source, choose the voice and generate or measure the real speech
+ before locking visual cut lengths.
+- Use `estimate:Speech` only for deterministic pre-generation planning. Final caption and semantic
+ timing comes from accepted audio through `speech:Spine` and `whisperx:Alignment`.
+- One continuous voiceover may cover several independently selected visual shots. Do not split TTS
+ merely because the picture cuts.
+- For dialogue generated inside speaking Seedance takes, preserve Script Segment order when assembling
+ `speech:Take` children.
+
+## Choose one path for speech audio
+
+- Put speech-bearing generated or supplied audio in `speech:Spine` as an audio `speech:Take` when it
+ is the program's authoritative narration. This produces ProgramSpace and speech audio for
+ `whisperx:Alignment` without inventing a visual clip.
+- Do not place the same narration on both Speech Spine and an Audio Track. That duplicates speech in
+ the final mix and creates competing time authority.
+
+## Put non-spine audio on Tracks
+
+Generated or supplied audio is a Blob until it is explicitly normalized. Prepare an audio-only source
+as `SynchronizedMedia`, then place it with `audio:Track`:
+
+```svml
+<media:Audio id="music-source" src="./assets/music.wav"/>
+<pipeline:Normalize id="music-media" source={music-source}
+ video="none" audio="default" span-authority="audio" frame-rate="30"/>
+
+<audio:Track id="music-track" space={speech.space}>
+ <audio:Clip source={music-media.media} during="program"
+ playback="once" gain="0.18" fade-in="6f" fade-out="12f"/>
+</audio:Track>
+```
+
+- Keep primary speech, music, ambience, and effects as independently inspectable contributions. Add
+ Speech Spine's audio Track and every selected Audio Track to `film:Film`.
+- Raw Media Track video is visual-only unless `audio="include"` is explicitly authored.
+- Dialogue wins the mix. Use explicit gain and fades; do not assume automatic ducking, loudness
+ normalization, or mastering.
+
+## Review and reuse
+
+- Listen for identity consistency, pronunciation, cadence, clipping, room mismatch, synthetic tails,
+ cross-talk, and words that no longer match the Script.
+- Review dialogue alone, then with music, then with effects on both headphones and ordinary speakers.
+- Do not approve caption timing from silent or placeholder audio.
+- Pin accepted face, voice, and take Records in later `.svrun` files with `build-record` and
+ `satisfy`; regenerate only the failed contribution.
diff --git a/.agents/skills/narratage/references/playbooks/craft/pip-overlay.md b/.agents/skills/narratage/references/playbooks/craft/pip-overlay.md
index fdeeb4c6..03047723 100644
--- a/.agents/skills/narratage/references/playbooks/craft/pip-overlay.md
+++ b/.agents/skills/narratage/references/playbooks/craft/pip-overlay.md
@@ -1,13 +1,62 @@
-# Picture-in-picture overlay craft
-
-- Decide whether PIP is real photographed video, supplied recording, or a composited subject with
- transparency. Use `media-track:Item` with `video`, `media`, or `surface`; do not call every non-text
- layer a sticker.
-- Establish a stable placement Frame, crop, border/paint, and stack order. Keep the PIP clear of
- captions, faces, product labels, and the base shot's main evidence.
-- A talking reaction PIP must remain visually alive but silent unless its audio is explicitly included.
- If it speaks, author its audio and timing as a real track rather than relying on implied lip movement.
-- Use a source with alpha when the subject must float without a rectangular background. Inspect edges,
- hair, motion blur, and color spill against the actual base before accepting it.
-- Time entry/exit to a perceptible story event or spoken phrase. A PIP that persists across shots must
- preserve identity, scale, placement, and styling unless a deliberate transition is authored.
+# Picture-in-picture craft
+
+Use picture-in-picture only when the base evidence must remain dominant while a presenter, reaction,
+secondary feed, or supporting image stays visible.
+
+## Choose the source form
+
+- Use a normal rectangular `media-track:Item video={...}` for a live reaction, presenter feed, screen
+ recording, or secondary camera.
+- Use `remove:Background` when a still portrait must become a transparent cutout. Place the resulting
+ image with `image={cutout.image}` plus an explicit `space:Extent`.
+- Use `compose:Image` with ordered `compose:Layer` children when the PIP should be frozen into one
+ deterministic still before it enters the timeline.
+- Use `surface={...}` only when the upstream component already produces an authored compositable
+ surface. Keep the source form explicit rather than guessing from a generic Artifact.
+
+```svml
+<remove:Background id="presenter-cutout" source={presenter.image}/>
+<space:Extent id="presenter-extent" width="1200" height="1600"/>
+<space:Frame id="presenter-pip" within={vertical}
+ left="64%" top="52%" right="4%" bottom="8%"/>
+
+<media-track:Track id="presenter-overlay" space={speech.space} canvas={vertical}>
+ <media-track:Item image={presenter-cutout.image} extent={presenter-extent}
+ frame={presenter-pip} during="program"
+ appearance={studio.media.pip} motion={studio.motion.pip}/>
+</media-track:Track>
+```
+
+## Lock placement and appearance
+
+- Define one stable Frame, fit, crop, border/paint treatment, stack order, and safe margin for a
+ persistent PIP. Preserve them across shots unless a deliberate transition changes the layout.
+- Keep the PIP clear of captions, faces, product labels, key UI, action buttons, and the base shot's
+ main evidence.
+- Match source light direction, color temperature, contrast, and apparent camera quality to the base
+ closely enough that the composite reads as intentional.
+- For transparent cutouts, inspect the actual edges against the final base: hair, fingers, motion
+ blur, holes, residual background, halos, and color spill.
+- Scale tall portraits against both width and resulting height. A narrow cutout can still consume most
+ of a vertical frame.
+
+## Keep speech and motion truthful
+
+- A reaction PIP may remain visually alive through breathing, eye movement, and expression while
+ silent. Do not imply that it speaks unless its real audio is explicitly authored.
+- For a video Item, add `audio="include"` only when that source should contribute sound; otherwise keep
+ it visual-only and put the intended audio on a separate Track.
+- Only the active Script speaker moves their mouth in a dialogue format. A listener PIP reacts without
+ invented words.
+- Preserve the same identity, wardrobe, crop, scale, and placement when a PIP persists across edits.
+
+## Time and review the PIP
+
+- Enter or exit on a perceptible story event, Script Selection, or Moment. Use semantic timing when a
+ measured speech map exists and explicit ProgramSpace timing otherwise.
+- Give the audience enough time to recognize both the base evidence and the PIP; avoid rapid toggling
+ that makes neither readable.
+- Review edge quality first, then placement on every relevant base shot, then entry/exit motion, audio
+ inclusion, caption collision, and final stack order.
+- Pin an accepted cutout or PIP source through `.svrun` `build-record` and `satisfy` instead of
+ regenerating it with unrelated downstream changes.
diff --git a/.agents/skills/narratage/references/playbooks/craft/production-gates.md b/.agents/skills/narratage/references/playbooks/craft/production-gates.md
index ac11f7a2..f8f91645 100644
--- a/.agents/skills/narratage/references/playbooks/craft/production-gates.md
+++ b/.agents/skills/narratage/references/playbooks/craft/production-gates.md
@@ -1,18 +1,83 @@
# Production gates
-- Freeze Script meaning, target language, format, aspect ratio, duration, and supplied assets before
- writing generation prompts.
-- Build the shot list from story beats first. Every shot needs a job: hook, evidence, mechanism,
- payoff, transition, or CTA.
-- Confirm keys, Runtime Profile, package locks, media limits, and model/resolution choices. Run
- `check` and `plan` before any paid Operation.
-- Review reference images before video generation: reject identity drift, malformed hands, watermarks,
- unwanted text, and impossible camera relationships.
-- Review each video shot independently: motion starts from the reference, stays in 4–15 seconds,
- preserves props/wardrobe/space, and contains no generated overlays.
-- Review `caption-fine:Track`, `text:Track`, and `media-track:Track` on the real base program for
- safe zones, occlusion, semantic timing, and stacking.
-- Use mock/provider-free inputs to validate topology and timing. Do not mock the only audio source
- when acceptance depends on real speech or TTS.
-- Regenerate only failed shots and reuse accepted Artifacts explicitly in a later Run Source; there
- is no implicit cache.
+Use staged Run Sources so unreviewed expensive outputs cannot silently feed later Operations.
+
+## Gate 0: freeze author intent
+
+- Freeze Script meaning, target language, aspect ratio, delivery duration, format, supplied assets,
+ and factual claims before writing prompts.
+- Give every planned shot one job: hook, context, evidence, mechanism, reaction, payoff, transition,
+ or CTA. Delete shots with no distinct job.
+- Confirm credentials, Runtime Profile, package locks, model limits, resolution, and permissions.
+ Run `doctor`, `check`, and `plan` before the first paid Build.
+
+## Gate 1: build and review reference images
+
+1. Create a narrow `.svrun` target-set that demands only the generated reference-image outputs.
+2. Submit that Build, then use `inspect` and `get` to retrieve every candidate image.
+3. If the Agent can view images, open the actual full-resolution outputs and review every image
+ itself. Do not approve from prompts, metadata, filenames, or thumbnails alone.
+4. Reject and regenerate any failed image. Do not connect a failed image to Seedance, Media Track,
+ image composition, or another downstream generator.
+5. Pin accepted image Records with `.svrun` `build-record` and connect them to the next Build with
+ `satisfy`. Changing the target-set alone does not select those Records.
+
+Apply this checklist to every image:
+
+- identity: correct recurring person/product/location, complete face when required, no drift;
+- anatomy: plausible hands, fingers, limbs, pose, gaze, and object contact;
+- geometry: camera ownership, viewpoint, reflections, screen orientation, and visible objects are
+ physically possible;
+- reverse views: opposing camera positions show different background sectors and landmarks; the
+ same or near-identical main background is an automatic failure;
+- continuity: wardrobe, lighting, props, object count, handed tasks, and spatial relationships match
+ the shot group;
+- text: required physical labels/UI are accurate enough for the use; no invented subtitles,
+ watermarks, floating words, or accidental logos;
+- composition: requested framing, aspect, safe zones, and overlay clearance are present;
+- quality: no broken edges, duplicated objects, severe blur, malformed texture, or generation debris.
+
+If the Agent cannot view images, skip visual inspection and do not claim that the images passed
+visual QA.
+
+## Gate 2: generate and review video takes
+
+- Demand only the takes whose reference images have passed Gate 1.
+- Keep Seedance duration inside the declared 4–15 second range; invalid values fail validation rather
+ than being silently clamped.
+- Review each take before assembly: verify the first-frame identity, reference continuity, lip-sync
+ when applicable, physical motion, stable props/text, intended camera/edit language, and absence of
+ generated editorial overlays.
+- Regenerate only failed takes. Pin accepted image/take Records explicitly in the next Build.
+
+## Gate 3: measure and author Tracks
+
+- Build `speech:Spine` only from accepted speech-bearing video or audio Takes, then run one
+ `whisperx:Alignment` for the authored Narrative.
+- Review Caption, Media, Typography, Ranking, Deck, Comment, Screen, and Audio Tracks against the
+ real ProgramSpace and SemanticMap. Check timing, safe zones, occlusion, stacking, audio clarity,
+ and whether each Track contributes unique information.
+- Treat `check` and `plan` as structural proofs only. They do not prove visual quality, real speech
+ alignment, Provider output quality, or factual correctness.
+
+## Gate 4: delivery Build
+
+- Demand `final.video` only after the upstream gates pass.
+- Inspect the durable Build and retrieve the final Artifact with `get`.
+- Watch and listen to the complete delivery, including the first and last second. Verify dialogue,
+ captions, overlays, transitions, audio density, claims, and CTA as one program.
+- Preserve accepted Records for deliberate future reuse; never assume a rerun will reuse them.
+
+Use explicit Run Source authoring for every accepted reuse:
+
+```svml
+<target-set id="delivery">
+ <target output="final.video" accepts="substitute"/>
+</target-set>
+<build-record id="accepted-take" build="reviewed-build-001"
+ output="opening-take.video"/>
+<satisfy output="opening-take.video" candidate="accepted-take"
+ fidelity="substitute"/>
+```
+
+Substitute fidelity propagates downstream. The demanded final Target must explicitly accept it.
diff --git a/.agents/skills/narratage/references/playbooks/craft/screen-demo.md b/.agents/skills/narratage/references/playbooks/craft/screen-demo.md
index 0def97ab..ac744687 100644
--- a/.agents/skills/narratage/references/playbooks/craft/screen-demo.md
+++ b/.agents/skills/narratage/references/playbooks/craft/screen-demo.md
@@ -1,10 +1,62 @@
# Screen-demo craft
-- Decide whether the screen is the base subject or an overlay. A full-screen recording/screenshot is
- provided media; a floating card over live action is an overlay. Do not regenerate exact UI.
-- Pair context and proof: show the person/device relationship, then show the actual UI from the user's
- position. Keep device orientation, screen content, and room geometry consistent.
-- Keep UI text attached to the screen. Use `text:Track` only for editorial callouts outside the
- UI. Use continuous motion when a document, receipt, or screen must remain unchanged.
-- Ask for the real screenshot, recording, or alpha asset when fidelity matters. Mark the missing asset
- and gap instead of hallucinating a similar interface.
+A screen demo must make the person/device relationship physically possible and preserve the real
+product interface as evidence.
+
+## Choose the presentation form
+
+- Use a full-screen screenshot or recording when the interface itself is the primary evidence.
+- Use a framed `media-track:Item` when the screen is an overlay over live action.
+- Use a context/proof pair when the story needs both the user and the interface: first establish the
+ person/device relationship, then show the screen from the user's physically possible position.
+- Keep editorial explanations outside the UI on `typo:Track`. Keep the product's own labels, buttons,
+ values, and navigation physically attached to the supplied screen asset.
+
+## Enforce hard reverse-view geometry
+
+Define both views before generating either one:
+
+- name camera position A for the person-facing view and camera position B for the device-facing view;
+- name the background sector and dominant landmarks visible from each position;
+- require position B to show the opposite sector with a different landmark set;
+- require the two views to show different background sectors and different landmark sets;
+- reject and regenerate if both views show the same main wall, window, furniture arrangement, or a
+ mirrored/cropped version of the same background.
+
+For example, a person-facing classroom view may show chairs behind the user, while the device-facing
+reverse view shows the lectern and blackboard behind the laptop. Writing only “the same classroom”
+for both views is insufficient. Apply the complete gate in `visual-continuity.md`.
+
+## Keep the interface on the correct surface
+
+- A readable laptop UI can appear only on the screen facing the camera. Never place interface content
+ on the laptop lid, back, keyboard, or another physically impossible plane.
+- Use a real supplied screenshot or captured screen whenever exact wording, data, layout, logo, or
+ interaction state matters. Do not ask an image or video generator to guarantee exact UI text.
+- When generating a contextual device image, connect the real UI screenshot as an explicit image
+ reference, describe its role in the English prompt, and pass the result through the image gate.
+- Preserve device orientation, bezel, screen plane, user eye line, room geometry, and the interface
+ state across the context/proof pair.
+
+## Direct generated screen motion
+
+- Use the vendored `broll-v1` Kit with a Recipe selecting `material-mode: screen-demo`.
+- Prefer `edit-language: continuous-shot` when the screen, receipt, document, or values must remain
+ unchanged throughout the take.
+- Prefer `camera-language: reference-locked` for proof and stable UI, or `product-macro` for a motivated
+ close detail. Avoid unnecessary reframing that makes the interface unreadable.
+- Put only the physical interaction and small camera/action change in the English `story` slot.
+- Generate with `seedance:ReferenceVideo generate-audio="false"`; narration and effects remain on
+ explicit Audio Tracks.
+
+## Assemble and inspect
+
+- Place screenshots, recordings, and generated demonstrations with `media-track:Track`; define an
+ explicit Frame, appearance Recipe, motion Recipe, timing window, and stack order.
+- Use `during={story.selection.NAME}` for a spoken demonstration range, a Moment plus `for` for an
+ event, or explicit ProgramSpace timing for a silent demo.
+- Inspect legibility at delivery size, not only full-resolution source size. Reject changed text,
+ unreadable controls, moire, impossible perspective, screen reflections that hide evidence,
+ same-background reverse views, or a hand interaction that does not match the UI state.
+- Pin accepted screenshots, contextual frames, and generated demo takes in later Builds with
+ `.svrun` `build-record` and `satisfy`.
diff --git a/.agents/skills/narratage/references/playbooks/craft/seedance-directing.md b/.agents/skills/narratage/references/playbooks/craft/seedance-directing.md
index 566d6f02..91d2ba45 100644
--- a/.agents/skills/narratage/references/playbooks/craft/seedance-directing.md
+++ b/.agents/skills/narratage/references/playbooks/craft/seedance-directing.md
@@ -1,25 +1,58 @@
# Seedance directing
-Separate the reusable format contract from per-take dialogue, action, story, or direction.
-
-- Select an official vendored Seedance Kit before composing prompt prose: `speaker-v1` for talking
- heads, `broll-v1` for silent visual stories, `podcast-v1`, `call-v1`,
- `street-interview-v1`, `motion-reference-v1`, or `camera-reference-v1`.
-- Render the Kit with `text:Render`; keep stable policy in an SVS Recipe and connect only dynamic
- `dialogue`, `action`, `story`, or `direction` slots through `text:Set`. Do not duplicate the Kit's
- reference, role, voice, camera, microphone, or hygiene blocks in a hand-written prompt.
-- Vendor the selected `.svs` into the video project's `./kits/` directory. Do not import it from a
- separate Narratage checkout.
-
-- Write one or two readable events, not frame-by-frame choreography: macro action plus micro eye,
- brow, smile, concern, or breath feedback.
-- Start from the reference pose, objects, emotion, camera, and space. Do not introduce a new person,
- prop, room, wardrobe, or angle.
-- Give physical motion envelopes: objects start in the hand or on the surface, travel a short distance,
- move slowly and naturally, never fly, bounce, teleport, detach, or multiply.
-- Tie speech actions to actual Script order. Quote only words present in the Script; otherwise use
- semantic phases such as opening, turn, and verdict.
-- Keep the face visible and hands away from it unless contact is required.
-- For a prompt with no matching Kit, end it with the English no-overlay sentence in
- `reference-vlm.md`. Official Kits already own their format-specific hygiene block; do not append a
- duplicate.
+## Build the prompt inputs
+
+1. Vendor one matching Kit into the project's `./kits/` directory.
+2. Import generic Text as `copy` and the vendored Kit under its own alias.
+3. Put stable creative choices in a named SVS Recipe.
+4. Render the Kit with `copy:Render`; connect only dynamic `dialogue`, `action`, `story`, or
+ `direction` slots through `copy:Set`.
+5. Feed the rendered Text to one explicit Seedance Surface and keep every reference edge visible.
+
+Write every user-authored image/video generation instruction in English. Verbatim dialogue may retain
+the Script's authored language; do not translate or paraphrase quoted Script lines inside prompts.
+
+Choose the Kit by meaning:
+
+| Use | Kit | Expected ordered references |
+|---|---|---|
+| one speaking person | `speaker-v1` | image 1 = person/scene; audio 1 = voice when used |
+| silent B-roll | `broll-v1` | one or more authored images |
+| two-person podcast | `podcast-v1` | images 1/2 = final A/B views; audio 1/2 = A/B voices |
+| video call | `call-v1` | images 1/2 = reversed call layouts; audio 1/2 = A/B voices |
+| street interview | `street-interview-v1` | image 1 = complete scene; audio 1/2 = interviewer/guest |
+| body-motion transfer | `motion-reference-v1` | image 1 = subject; video 1 = motion reference |
+| camera-language transfer | `camera-reference-v1` | image 1 = subject; video 1 = camera reference |
+
+Use `seedance:TextVideo` for prompt-only generation, `seedance:FrameVideo` for first/optional-last
+frame control, and `seedance:ReferenceVideo` for image/video/audio references. Do not duplicate the
+Kit's fixed reference, role, voice, microphone, camera, or text-hygiene blocks in freeform prose.
+Set `generate-audio="false"` for silent B-roll and set it deliberately for speaking formats rather
+than relying on an unstated assumption.
+
+## Respect model contracts
+
+- Use model values `standard`, `fast`, or `mini`. `fast` and `mini` support only 480p/720p;
+ `standard` also supports 1080p/4k.
+- Keep duration at an integer from 4 through 15 seconds. Invalid values fail closed.
+- Respect the ReferenceVideo caps: at most 9 images, 3 videos, 3 audio clips, and 12 total files.
+ Reference audio requires at least one visual reference.
+- Use `estimate:Speech` for speech-driven duration planning; it estimates pronunciation length but
+ does not create measured timing.
+
+## Direct the shot
+
+- Write one or two readable events: a macro action plus small eye, brow, breath, smile, concern, or
+ posture feedback. Do not choreograph frame-by-frame poses.
+- Start from the reference pose, objects, emotion, camera, and room. Add only motion that follows from
+ visible facts already established by the image.
+- Give objects a physical motion envelope: known starting support/contact, short believable travel,
+ and stable count/shape. Avoid teleporting, flying, multiplying, or detaching props.
+- Tie speech actions to Script order. Quote only exact Script words; otherwise refer to semantic beats
+ such as opening, reversal, evidence, and verdict.
+- Keep faces readable and hands away from the face unless contact is the authored action.
+- Keep editorial subtitles, titles, cards, stickers, and floating text out of Seedance. Preserve only
+ physical labels/UI already attached to referenced objects.
+
+Review every reference image through `production-gates.md` before calling Seedance, then review the
+resulting take before adding it to Speech Spine or Media Track.
diff --git a/.agents/skills/narratage/references/playbooks/craft/sfx.md b/.agents/skills/narratage/references/playbooks/craft/sfx.md
index fa6dda9b..4efff62b 100644
--- a/.agents/skills/narratage/references/playbooks/craft/sfx.md
+++ b/.agents/skills/narratage/references/playbooks/craft/sfx.md
@@ -1,12 +1,60 @@
# Sound-effects craft
-- Add a sound only for a perceptible event: motion landing, UI state change, reveal, or transition.
- No event means no effect.
-- One sound has one job. Do not stack impact, whoosh, click, and ambience on the same beat.
-- Dialogue wins. Keep effects short/light enough not to mask consonants, numbers, names, or conclusions.
+Sound effects support discrete visible or editorial events. They do not replace music, ambience, or
+clear dialogue.
+
+## Give each sound one purpose
+
+- Add a sound only when the audience can perceive the corresponding event: contact, landing, UI state
+ change, reveal, transition, or completion.
+- One sound should perform one job. Do not stack impact, whoosh, click, and ambience on the same beat
+ unless the story explicitly requires a layered event.
- Trigger at the audience-perceived event, not automatically at every shot boundary.
-- Keep a consistent sound vocabulary for repeated cards/UI/actions. Music owns continuous emotion;
- SFX owns discrete events.
-- Review dialogue alone, then music, then effects. Author each contribution as an `audio:Clip` inside
- an `audio:Track`; check headphones and phone speakers, and listen to
- the entire program for density rather than approving isolated loops.
+- Keep one consistent sound vocabulary for repeated UI states, cards, reveals, and actions.
+- Let music carry continuous emotion; use SFX for discrete events and ambience for environmental
+ continuity.
+
+## Author SFX in SVML
+
+Declare the source, normalize it to audio-only `SynchronizedMedia`, and place it with an `audio:Clip`:
+
+```svml
+<media:Audio id="reveal-source" src="./assets/reveal.wav"/>
+<pipeline:Normalize id="reveal-media" source={reveal-source}
+ video="none" audio="default" span-authority="audio" frame-rate="30"/>
+
+<audio:Track id="effects" space={speech.space}>
+ <audio:Clip source={reveal-media.media}
+ at={story.moment.reveal} for="600ms" map={timing.map}
+ playback="once" gain="0.45" fade-in="0f" fade-out="3f"/>
+</audio:Track>
+```
+
+- Use `during={story.selection.NAME}` for a range, a Script Moment plus `for` for a point event, or
+ explicit `start`/`end` timing in ProgramSpace.
+- Use `playback="once"` for a discrete effect, loop only for a genuinely repeating texture, and
+ bounded pitch-preserving stretch only when the occupancy must fill an authored range.
+- Use explicit trim, gain, fade-in, and fade-out. The Audio Track preserves source level and does not
+ add automatic loudness normalization or ducking.
+- For a sound owned by a Media Item or Sequence transition, use `media-track:Sound` with an explicit
+ enter, exit, or named Handoff trigger.
+
+## Protect dialogue
+
+- Dialogue remains the most important audio. Keep effects short and light enough not to mask
+ consonants, numbers, names, product terms, or conclusions.
+- Avoid strong transients on the same instant as a critical word. Move, shorten, or reduce the effect
+ rather than sacrificing speech clarity.
+- Leave breathing space between repeated events. A dense series of identical effects usually means
+ the visual rhythm or sound plan needs simplification.
+
+## Review the complete mix
+
+1. Listen to dialogue alone.
+2. Add music and confirm every word remains clear.
+3. Add effects one family at a time.
+4. Listen on headphones and ordinary phone/laptop speakers.
+5. Play the entire program from start to finish and judge cumulative density, not isolated loops.
+
+Verify each trigger against the visible event and check the first/last second for clipped tails or
+effects that outlive the picture.
diff --git a/.agents/skills/narratage/references/playbooks/craft/visual-continuity.md b/.agents/skills/narratage/references/playbooks/craft/visual-continuity.md
index 45d3d1fe..4d916733 100644
--- a/.agents/skills/narratage/references/playbooks/craft/visual-continuity.md
+++ b/.agents/skills/narratage/references/playbooks/craft/visual-continuity.md
@@ -1,15 +1,45 @@
# Visual continuity
-- Pick one clearest identity anchor for each recurring person, product, and real location. Reuse it
- in later generated frames instead of redrawing identity from prose.
-- A continuous shot group shares one reference frame. Split for duration or a genuine edit; parts
- preserve camera, space, wardrobe, props, and action continuity.
-- Define reverse views explicitly. A face-facing selfie and a device-screen shot from that person's
- position cannot use the same background direction; the screen view is the opposite side of the room.
-- Keep camera motion small unless the story requires a clear move. Do not introduce a new location,
- camera, or wardrobe inside a locked-reference shot.
-- Lock distinctive props in both image and motion prompts. State stable physical invariants and remove
- unnecessary asymmetric props if the model repeatedly duplicates them.
-- Only the active speaker talks. A listener remains visibly alive with breathing, eye movement, and
- reaction but no invented dialogue.
-- Keep visible text physically attached to its product, screen, document, or authored overlay Track.
+## Encode continuity in SVML
+
+- Declare recurring anchors as explicit `media:Image`/`media:Audio` assets or accepted generated
+ outputs. Reuse the same Artifact edges; do not redraw identity from prose for every take.
+- Keep one authoritative reference set and one stable Recipe for a continuous shot group. Split a
+ group only for a genuine edit or the 15-second Seedance ceiling; preserve camera, room, wardrobe,
+ light, props, action state, and reference order across its parts.
+- Put each stable physical fact in both the reference image and the relevant prompt contract. Prefer
+ simple, symmetric props when a distinctive feature repeatedly duplicates or mutates.
+
+## Enforce shot/reverse-shot geometry
+
+Treat reverse-view geometry as a hard acceptance rule, not a stylistic suggestion.
+
+1. Name camera positions A and B, their facing directions, and the background sector/landmarks that
+ each position must see before generating either image.
+2. For opposing positions, require different main background sectors and different dominant
+ landmarks. The room, people, lighting logic, and key props remain continuous, but the background
+ behind the subject must not be the same or a cosmetic crop of the same wall.
+ The two views must show different background sectors and different landmark sets.
+ In short: opposing views must show different backgrounds.
+3. Reject both images if they show the same main background, the same landmark arrangement, or a
+ mirrored duplicate. Regenerate before either image enters downstream generation.
+
+Use explicit English geometry such as:
+
+`Camera A faces the subject with the window wall behind them. Camera B is the opposite reverse view from the subject's position, with the counter and blackboard wall behind the device. The two views show different sides of the same room.`
+
+For a person-facing/device-facing pair, the person-facing image shows what is behind the person;
+the device-facing reverse image shows what is behind the device. Writing only “cafe interior” or
+“office interior” for both views is a continuity failure.
+
+## Review each accepted group
+
+- Compare identity, face angle, eye line, wardrobe, lighting direction, room layout, camera height,
+ lens feel, prop count, handed tasks, and action state across every image/take in the group.
+- Keep camera movement within the selected Kit Recipe. Do not introduce a new room, camera, outfit,
+ or unexplained object inside a reference-locked take.
+- Let only the active Script Role speak. Keep listeners visibly alive through breath, gaze, and
+ reaction without invented dialogue.
+- Keep supplied physical text attached to its product, screen, document, or sign; put editorial text
+ on explicit Tracks.
+- Apply the image gate in `production-gates.md` before connecting any generated frame downstream.
diff --git a/.agents/skills/narratage/references/playbooks/formats/asmr.md b/.agents/skills/narratage/references/playbooks/formats/asmr.md
index d2331027..adc4198c 100644
--- a/.agents/skills/narratage/references/playbooks/formats/asmr.md
+++ b/.agents/skills/narratage/references/playbooks/formats/asmr.md
@@ -1,17 +1,47 @@
# ASMR format
-Evidence level: thin.
-
-- Use the vendored `broll-v1` Kit. Select a practical material mode, a single readable story shape,
- reference-locked camera language, and micro/readable motion in the Recipe; connect the exact
- physical action through the `story` slot.
-- Use close, simple, predictable physical actions: cutting, pouring, wiping, pressing, folding, or
- rubbing. Keep motion micro/readable, not energetic or impact-heavy.
-- Keep the shot continuous and camera close/locked. Rapid cuts or large camera moves break the
- sound-image continuity.
-- Generated visuals remain silent. Author texture sound, ambience, and music as explicit
- `audio:Track`/`audio:Clip` contributions aligned to the visible event.
-- Choose references with strong material texture and clean geometry. Review looping, contact points,
- duplicated tools, and end-frame artifacts before adding sound.
-- Use a higher-quality generation model when fine surface detail is the point; verify the requested
- resolution is actually supported rather than assuming an upscale.
+Use close material detail, one readable physical action per shot, and deliberately synchronized
+texture sound to create a calm, satisfying micro-film.
+
+## Author the visual
+
+1. Establish one accepted first frame with clear material texture, exact tool/object count, visible
+ contact points, and a physically possible starting state.
+2. Vendor `broll-v1.svs`. Use `product-beauty` or `practical-real`, `single-moment` or
+ `process-demo`, `continuous-shot`, `product-macro` or `reference-locked`, and `micro` or
+ `readable` motion.
+3. Put only the visible action in the English `story` slot: cut, pour, wipe, press, fold, rub, peel,
+ place, or another small event that can complete naturally in one take.
+4. Use `seedance:FrameVideo` for one controlling first frame or `seedance:ReferenceVideo` for
+ multiple ordered material references. Set `generate-audio="false"`.
+5. Keep raw Seedance duration at an integer 4–15 seconds. Use explicit media Trim/Retime only after
+ reviewing the generated take.
+
+Avoid rapid edits, large camera moves, busy backgrounds, multiple simultaneous actions, or motion
+that hides the contact point. Use `standard` for 1080p/4k detail; `fast` and `mini` are limited to
+480p/720p.
+
+## Author the sound
+
+- Use supplied or generated texture sound, ambience, and optional music as explicit sources.
+- Normalize every Blob with `pipeline:Normalize`, then place it through `audio:Track` and
+ `audio:Clip` on the delivery ProgramSpace.
+- Align impacts and texture changes to the audience-perceived contact event with explicit timing.
+- Use one sound for one function. Do not cover a delicate material sound with unnecessary impacts,
+ whooshes, or dense music.
+- Set trim, playback, gain, fade-in, and fade-out explicitly. Do not assume automatic looping,
+ ducking, or loudness normalization.
+
+For a speech-free ASMR edit, omit WhisperX and Caption components. Select a verified ProgramSpace
+Record in `.svrun` with `build-record` and `satisfy`, then author explicit windows against that
+ProgramSpace. The selected Record is the delivery time contract.
+
+## Review and reuse
+
+Inspect the actual take for material detail, tool/object count, hand geometry, contact, motion speed,
+label stability, duplicated objects, camera drift, and broken tail frames. Then review sound against
+the visible event, including headphones and ordinary speakers. Pin accepted first frames, takes,
+and audio Records with `.svrun` `build-record` and `satisfy`.
+
+Read `../craft/b-roll.md`, `../craft/sfx.md`, `../craft/persona-and-audio.md`, and
+`../craft/production-gates.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/mass-tarot.md b/.agents/skills/narratage/references/playbooks/formats/mass-tarot.md
index aac69e23..e745a40c 100644
--- a/.agents/skills/narratage/references/playbooks/formats/mass-tarot.md
+++ b/.agents/skills/narratage/references/playbooks/formats/mass-tarot.md
@@ -1,18 +1,61 @@
# Mass-tarot pick-a-card format
-Evidence level: thin.
-
-- Use the vendored `broll-v1` Kit for card/table motion. Keep shared material, story shape, camera,
- edit, and motion policy in a Recipe; connect each reveal action through the `story` slot.
-- Preserve the four-part structure: question → three face-down cards → pick 1/2/3 prompt → individual
- reveals and interpretations.
-- Frame interpretation as reflection, not guaranteed fortune-telling. Offer themes/directions, not
- exact dates, flat verdicts, or promised outcomes. Personality questions describe traits, not a
- predicted person's physical appearance.
-- Generate silent card/table motion with `seedance:ReferenceVideo`; author narration and all editorial
- text separately. Numbers, questions, and interpretation lines belong in `text:Track` or the
- `caption:Program` + `caption-fine:Track` pair unless physically printed
- on supplied card art.
-- Use real supplied card faces when exact symbolism matters. Keep card order and identity stable from
- selection through reveal.
-- Validate every claim and visual cue with the project reviewer before production; do not fabricate certainty.
+Build a four-stage reading: question → exactly three face-down cards → pick 1/2/3 prompt →
+ordered reveals and interpretations.
+
+## Author the narration and program time
+
+- Write one authoritative Script with Selections/Moments for the question, choice window, each reveal,
+ and the close.
+- Use one continuous narration take whenever the reading is voiceover-led. Generate it with
+ `mimo:Preset`, `mimo:VoiceDesign`, or `mimo:VoiceClone`, then use an audio-only Speech Take:
+
+```svml
+<speech:Spine id="speech" frame-rate="30"
+ visual-frame={full-frame} visual-appearance={studio.speech.visual} visual-z="0">
+ <speech:Take audio={narration.audio} segment={story.segment.reading}/>
+</speech:Spine>
+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+```
+
+ Peer Media Tracks provide every card/table visual while `{speech.audioTrack}` carries narration.
+- A visible host may instead use `speaker-v1` speaking takes assembled through the same Spine.
+
+## Author the card visuals
+
+1. Establish one accepted table scene with exactly three face-down cards, stable card positions,
+ lighting, hands, cloth, and surrounding objects.
+2. Use supplied card-face art whenever exact symbolism or card identity matters.
+3. Vendor `broll-v1.svs`. Use `product-beauty` or `practical-real`, a `single-moment` or
+ `process-demo` story shape, `continuous-shot`, a locked/macro camera, and micro/readable motion.
+4. Generate silent card actions with `seedance:FrameVideo` for exact first-frame control or
+ `seedance:ReferenceVideo` for multiple visual references; set `generate-audio="false"`.
+5. Place the accepted question/table/reveal shots with `media-track:Item` or
+ `media-track:Sequence` using the
+ Script's measured Selections and Moments.
+
+Keep card count, order, back design, face identity, hand ownership, and reveal direction stable.
+Reject a fourth card, duplicated card, changed artwork, impossible hand contact, or a reveal that no
+longer matches its interpretation.
+
+## Separate spoken and editorial text
+
+- Use the exact-font Caption pipeline only for spoken narration or host dialogue.
+- Put the question title, `PICK 1 / 2 / 3`, card numbers, short interpretation highlights, and CTA on
+ `typo:Track` unless they are physically printed on supplied card art.
+- Give the choice window enough time for the viewer to decide before the first reveal.
+
+## Keep claims responsible
+
+Frame the reading as reflection and possible direction, not guaranteed fortune-telling. Do not
+promise exact outcomes or dates. For questions about a future person, describe themes or traits
+rather than predicting physical appearance.
+
+## Review and reuse
+
+Review the complete four-stage order, exact card count and identity, narration/reveal timing, text
+legibility, claims, and final CTA. Pin accepted table images, card shots, narration, and host takes
+through `.svrun` `build-record` and `satisfy`.
+
+Read `../craft/b-roll.md`, `../craft/captions.md`, `../craft/overlays.md`, and
+`../craft/persona-and-audio.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/mixcut.md b/.agents/skills/narratage/references/playbooks/formats/mixcut.md
index 8ae27fab..a807fb71 100644
--- a/.agents/skills/narratage/references/playbooks/formats/mixcut.md
+++ b/.agents/skills/narratage/references/playbooks/formats/mixcut.md
@@ -1,15 +1,60 @@
-# Silent visual mixcut format
-
-- Render each generated beat through the vendored `broll-v1` Kit. Reuse an SVS Recipe for the shared
- material/edit/camera language and vary only the beat-specific `story` Text when appropriate.
-- Each beat is a reference frame plus a silent generated motion clip. Keep clips 4–15 seconds, use
- distinct roles (hook, rhythm, detail/effect, conversion/payoff), and assemble ordered
- `media-track:Item` inputs deliberately.
-- Without speech, use explicit `start`/`end` values in the shared `ProgramSpace` for titles, benefits,
- and CTA. Lock effective duration before laying out overlays; changing a clip duration requires
- updating those authored times.
-- Make the first three seconds immediately engaging. Music or voiceover is the only audio source when
- generated clips are silent; truncate deliberately rather than letting a long track drift.
-- Keep at most one or two text groups on screen at once. Product claims must match verified facts and
- the visible frame. Alpha graphics retain transparency and point to the intended CTA.
-- Omit caption components when there is no spoken base; use `text:Track` for editorial copy.
+# Visual mixcut format
+
+Use several short, visually distinct shots to create a music- or voice-led product/story montage.
+The pictures carry the argument; captions are optional and normally omitted when there is no speech.
+
+## Lock the beat structure
+
+Give each shot a distinct role, for example:
+
+1. hook: an immediately readable benefit, contrast, or visual question;
+2. rhythm: a larger but controlled action that establishes momentum;
+3. detail/proof: a stable close view of texture, mechanism, or result;
+4. conversion/payoff: product, outcome, CTA, or a final memorable image.
+
+Adjacent shots must differ in location, camera relationship, action, evidence, or emotional state.
+A crop of the same image is not a new beat.
+
+## Author the SVML shots
+
+1. Generate or supply the exact first frame for each beat and pass every generated image through the
+ image review gate.
+2. Vendor `broll-v1.svs`; select one coherent material/edit language while varying the beat-specific
+ English `story` slot.
+3. Prefer `seedance:FrameVideo` when the first frame is the controlling fact. Use
+ `seedance:ReferenceVideo` when the shot needs multiple ordered references. Set
+ `generate-audio="false"`.
+4. Add only motion that follows from the accepted first frame. Do not introduce a new person, room,
+ product, camera side, or label inside the motion prompt.
+5. Use explicit `pipeline:Transform` Trim/Retime operations when the accepted source needs a precise
+ effective length. Place final clips as ordered full-frame `media-track:Item` inputs.
+
+## Author timing, text, and sound
+
+- Lock the delivery ProgramSpace before laying out Items. For a voice-led cut, an audio-only
+ `speech:Take` supplies program time and semantic anchors. For a music-only cut, select a verified
+ ProgramSpace Record in `.svrun` with `build-record` and `satisfy`, then author explicit
+ `start`/`end` windows. Do not treat music as speech evidence.
+- Omit Caption components when there is no spoken Script. Use `typo:Track` for title, benefit, and CTA
+ copy.
+- Keep no more than one or two text groups on screen at once. Align text handoffs to the final trimmed
+ clip boundaries, and update them whenever a clip length changes.
+- Normalize BGM or voiceover before placing it on an Audio Track. Make the musical idea or spoken hook
+ audible within the first three seconds. Use explicit gain and fades.
+
+## Preserve product truth
+
+- Use supplied product art, labels, UI, screenshots, and alpha graphics when exact appearance matters.
+- Product and ingredient claims must match verified source material and the visible shot.
+- Keep labels facing a readable direction and inspect the product frame at pause-level detail.
+- Alpha stickers and arrows must retain transparency and point to the intended CTA or evidence.
+
+## Review and reuse
+
+Review first frames, motion continuity, object/label stability, effective clip lengths, text handoffs,
+audio start/end, claim accuracy, and the first/last second of the complete Film. Pin every accepted
+image, clip, audio source, and ProgramSpace with `.svrun` `build-record` and `satisfy`; regenerate
+only failed beats.
+
+Read `../craft/image-prompt-style.md`, `../craft/b-roll.md`, `../craft/overlays.md`, and
+`../craft/persona-and-audio.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/ranking-listicle.md b/.agents/skills/narratage/references/playbooks/formats/ranking-listicle.md
index 65b73f63..034014a9 100644
--- a/.agents/skills/narratage/references/playbooks/formats/ranking-listicle.md
+++ b/.agents/skills/narratage/references/playbooks/formats/ranking-listicle.md
@@ -1,14 +1,48 @@
# Ranking-listicle format
-Evidence level: partial.
-
-- Use one official `ranking` variant (`TierBoard`, `Column`, `TopThree`, or `TypewriterList`) or one
- `deck:DepthStack` for all items; change layout/style through its Recipe or
- component configuration rather than duplicating competing tracks.
-- Every item has a stable identity, label/icon, rank/tier, and narrow semantic evidence window. A
- non-contiguous Selection does not implicitly clone an item; author repeated appearances explicitly.
-- Write each spoken item as setup → concrete evidence/cost → punchline. Higher-value entries should
- earn stronger evidence and a more decisive close, not merely a different color.
-- Keep editable labels, scores, icons, and headings as graph inputs/assets. Verify item order, timing,
- visual hierarchy, and evidence before render.
-- Claims must be supportable. Do not invent comparative facts, performance numbers, or user votes.
+Use one progressive Ranking component to reveal a stable ordered set while speech and evidence
+explain why every item belongs where it is placed.
+
+## Author the Script schedule
+
+- Write one outer Script Selection covering the complete ranking window.
+- Declare one repeated Script Moment for item reveals and one terminal Moment for the completed board.
+- The outer Selection must resolve exactly once. The terminal Moment must resolve exactly once.
+- Repeat the same reveal Moment id once per item. Ranking applies strict `each` semantics; the
+ occurrence count must equal the number of authored items, and trigger frames must increase.
+- Give every item a stable id, order, label, icon/image, rank or tier, and one evidence beat.
+
+## Author the SVML program
+
+1. Build the speech program with accepted speaking or audio-only `speech:Take` inputs, then run
+ `whisperx:Alignment` so the Selection and Moments resolve against real audio.
+2. Declare exact font bytes and the variant's package-owned Style.
+3. Choose exactly one primary component: `ranking:TierBoard`, `ranking:Column`,
+ `ranking:TopThree`, or `ranking:TypewriterList`.
+4. Connect `map={timing.map}`, `space={speech.space}`, the outer `during` Selection, repeated
+ `triggers` Moment, terminal Moment, explicit frame, Style, and the complete ordered item list.
+5. Add the component's `.visual` output to `film:Film`; add its optional `.audio` output only when
+ authored sound is present.
+6. Put screenshots, demonstrations, or proof clips on a separate `media-track:Track`. Use
+ `deck:DepthStack` only as an intentional evidence treatment, not as a second ranking system.
+7. Add the full Caption pipeline when spoken words should be captioned, then render and target the
+ delivery through `.svrun`.
+
+## Write and design the list
+
+- Use setup → concrete evidence or cost → punchline for each spoken item.
+- Give higher-ranked entries stronger proof and a more decisive close, not merely a brighter color.
+- Keep row/tier vocabulary stable. Do not change layout grammar, label style, or icon logic halfway
+ through the list.
+- Keep claims verifiable. Do not invent performance numbers, votes, comparisons, or product facts.
+- Separate ranking copy from captions: item labels belong to the Ranking component; spoken dialogue
+ belongs to Script and Caption; supporting proof belongs to Media Track.
+
+## Review and reuse
+
+Review resolved trigger count/order, terminal timing, item identity, rank/tier, labels, icon assets,
+evidence alignment, safe zones, stack order, and optional sounds. Pin accepted generated evidence
+media through `.svrun` before the final ranking Build.
+
+Read `../craft/captions.md`, `../craft/overlays.md`, `../craft/b-roll.md`, and
+`../craft/production-gates.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/scenario-call.md b/.agents/skills/narratage/references/playbooks/formats/scenario-call.md
index 4ca51caa..7f571eba 100644
--- a/.agents/skills/narratage/references/playbooks/formats/scenario-call.md
+++ b/.agents/skills/narratage/references/playbooks/formats/scenario-call.md
@@ -1,19 +1,41 @@
# Scenario-call format
-Use the vendored data-only `call-v1` Kit; it is a reusable Text Template, not a new execution node.
-Render it with `text:Render` plus an SVS Recipe, then feed one `seedance:ReferenceVideo` with the two
-final reversed call-layout images and two ordered voice references. Use supplied media and
-`media-track:Track` only when the call must be assembled from independent real feeds.
-
-Evidence level: thin.
-
-- Prepare two final call-layout references: A main with B inset, and B main with A inset. Their main/
- inset geometry, rooms, wardrobe, and identities must be mutually consistent reverse states.
-- Author explicit A/B Script cues and two clean voice references. Only the active speaker moves their
- mouth; the listener remains alive in either main or inset view.
-- Keep both video feeds active. Do not let the inset become a frozen portrait unless that is explicitly
- the story state.
-- Use at most one `caption:Program` + `caption-fine:Track`. Put call labels, notifications, and
- editorial copy in explicit `text:Track`/`media-track:Track`; Seedance must not generate them.
-- Validate layout, speaker/voice assignment, reaction timing, and continuity with provider-free/mock
- media before a paid call generation.
+Use two final video-call states: A in the main tile with B inset, and B in the main tile with A
+inset. Both tiles remain live while the active speaker changes.
+
+## Author the SVML program
+
+1. Write explicit A/B Script turns and prepare two clean voice references in that order.
+2. Prepare two accepted call-layout images. Image 1 is A-main/B-inset; image 2 is B-main/A-inset.
+ Preserve both identities, local rooms, wardrobe, webcam perspective, borders, controls, crop, and
+ tile geometry.
+3. Vendor `call-v1.svs`. Select `framing`, `edit-language`, `pacing`, `performance`, `reaction`, and
+ `gesture` in an SVS Recipe.
+4. Render each Segment with `copy:Render`; connect Script dialogue and optional English action
+ direction through `copy:Set`.
+5. Generate each take with `seedance:ReferenceVideo generate-audio="true"`, the two layout images,
+ and the two ordered voice references.
+6. Assemble takes with `speech:Spine`, create one `whisperx:Alignment`, then add the exact-font Caption
+ chain, Typography, Media, and Audio Tracks.
+7. Assemble in `film:Film`, render with `render:Video`, and stage review/delivery in `.svrun`.
+
+## Preserve call-state truth
+
+- Main and inset geometry must exchange roles exactly; the layout may not drift between states.
+- A's local background remains A's background whether A is main or inset. The same rule applies to B.
+ These are two live feeds changing layout, not two physical cameras reversing inside one room.
+- Only the active speaker moves their mouth. The listener remains live through gaze, breath, posture,
+ and silent reaction; do not freeze the inset into a portrait.
+- Keep interface controls, borders, labels, and notification states supplied by the accepted layout
+ media. Seedance should preserve them, not invent new messages, captions, or badges.
+- Use `typo:Track` for editorial labels or explanations that sit outside the physical call UI.
+
+## Review and reuse
+
+Review the two layout references side by side for exact main/inset exchange, participant/background
+identity, crop, controls, and aspect ratio. Review each take for speaker/voice assignment, lip-sync,
+live listener reaction, UI stability, and generated text. Pin every accepted layout and take with
+`.svrun` `build-record` and `satisfy`.
+
+Read `../craft/seedance-directing.md`, `../craft/captions.md`, `../craft/overlays.md`, and
+`../craft/persona-and-audio.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/street-interview.md b/.agents/skills/narratage/references/playbooks/formats/street-interview.md
index 68df6bde..8fc3ca02 100644
--- a/.agents/skills/narratage/references/playbooks/formats/street-interview.md
+++ b/.agents/skills/narratage/references/playbooks/formats/street-interview.md
@@ -1,22 +1,57 @@
# Street-interview format
-Use the vendored data-only `street-interview-v1` Kit; it is a reusable Text Template, not a new
-execution node. Render it with `text:Render` plus an SVS Recipe, then feed the result to one
-`seedance:ReferenceVideo` with one complete-scene image and two ordered voice references. Use a
-shared `speech:Spine` for take assembly and `media-track:Track` only for separate editorial overlays.
-
-- Establish one shared scene reference showing interviewer, guest, microphone, distance, and street
- context. Establish two short clean voice references and a Script with explicit speaker cues.
-- Use `A:` for the interviewer/first audio reference and `B:` for the guest/second audio reference.
- Connect dialogue and optional take-specific action through the Kit slots instead of rebuilding its
- role, microphone, scene, and no-overlay prompt blocks.
-- Keep one locked or softly handheld two-person view. Drift may be slight, but do not cut to a new
- angle or reconstruct the room. The active speaker is identified by mouth and microphone; the listener
- remains visibly alive and silent.
-- Add about one second of silent surprise before the first authored line in the opening shot. This is
- performance only; never add words to the Script.
-- Define reverse-view backgrounds explicitly for reaction/device shots. Keep distinctive props stable
- across the reference image and motion prompt.
-- Use one `caption:Program` + `caption-fine:Track` when captions are wanted. Put editorial overlays
- on a Script `Selection`/`Moment` resolved through the WhisperX `SemanticMap`; do not recreate the
- old phrase-query or source-timestamp locator model.
+Use one complete two-person street scene, two explicit Script Roles, and a microphone handoff to
+make the active speaker readable without changing the location or camera topology.
+
+## Author the SVML program
+
+1. Write Script turns with explicit interviewer and guest Role Cues. Render the Kit dialogue so the
+ interviewer is `A:` and the guest is `B:`.
+2. Prepare one accepted final scene image containing both people, their full spatial relationship,
+ the microphone, wardrobe, street context, camera height, and lens feel.
+3. Prepare two clean voice references in the same order: audio 1 for A, audio 2 for B.
+4. Vendor `street-interview-v1.svs`. Select `framing`, `edit-language`, `pacing`, `performance`,
+ `reaction`, and `gesture` in an SVS Recipe.
+5. For each Script Segment, use `copy:Render` with dialogue plus an optional English action slot,
+ then call `seedance:ReferenceVideo generate-audio="true"` with the scene image and both voices.
+6. Assemble the accepted Segment takes with `speech:Spine`, align the complete Script with
+ `whisperx:Alignment`, then add Caption, Media, Typography, and Audio Tracks as needed.
+7. Assemble peer Tracks in `film:Film`, render with `render:Video`, and demand review or delivery
+ outputs through named `.svrun` target-sets.
+
+## Preserve the street-interview grammar
+
+- Keep one locked or softly handheld two-person perspective. Small operator drift is natural; a new
+ camera side, reconstructed street, or unrelated reaction angle is not.
+- Only the active Role moves their mouth. The listener remains alive through eye focus, breath,
+ posture, nods, and an appropriate silent reaction.
+- A always holds the same microphone. On A lines it remains near A; on B lines A extends it toward B
+ through a believable wrist/arm movement. The microphone must not duplicate or switch hands
+ without an authored action.
+- Let each answer complete one natural idea. Compact handoffs are useful, but intelligibility wins
+ over speed.
+- In the opening take, include about one second of silent surprise before the first authored line;
+ budget it inside the generated duration and do not add unauthored words.
+
+## Add proof and editorial layers
+
+- Place B-roll and proof media with `media-track:Item` during Script Selections. Let the spoken setup
+ begin before the picture enters and let the next spoken beat begin before the picture exits when a
+ J-cut/L-cut improves continuity.
+- Use the complete Caption chain with one program-wide Planner. Use `typo:Track` for titles, names,
+ questions, or CTA copy.
+- Keep exact signs, product labels, and device UI as supplied physical media. Do not ask Seedance to
+ add editorial cards or captions.
+
+The primary shared street shot does not need a reverse angle. If a device-facing or proof angle is
+added, its opposing camera position must show a different background sector and landmark set from
+the person-facing image.
+
+## Review and reuse
+
+Review speaker/voice assignment, lip-sync, microphone position, listener silence, identities,
+street continuity, reaction timing, text hygiene, and caption placement. Pin accepted scene images
+and takes with `.svrun` `build-record` and `satisfy` before downstream assembly.
+
+Read `../craft/seedance-directing.md`, `../craft/visual-continuity.md`, `../craft/b-roll.md`, and
+`../craft/captions.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/talking-head.md b/.agents/skills/narratage/references/playbooks/formats/talking-head.md
index e6419f2a..c5d348be 100644
--- a/.agents/skills/narratage/references/playbooks/formats/talking-head.md
+++ b/.agents/skills/narratage/references/playbooks/formats/talking-head.md
@@ -1,15 +1,58 @@
# Talking-head format
-- Put a strong hook in the first Script Segment. Divide the script into semantic beats, usually 3–4
- segments, each planned for 4–15 seconds with an 8–12 second target.
-- Keep one visual identity across A-roll: same face reference, room, wardrobe, and lighting. Use
- B-roll for changes, not to drift the presenter base.
-- Use the vendored `speaker-v1` Kit with `text:Render`; select composition, camera, edit,
- performance, and gesture through an SVS Recipe, then connect dialogue/action as Text edges.
-- Use `seedance:ReferenceVideo` for face/image/audio references; use `seedance:TextVideo` without an
- identity reference. Keep dialogue and action as separate `text:Value` inputs.
-- Build one `speech:Spine` and one `whisperx:Alignment`. Add `caption:Program` +
- `caption-fine:Track` only when requested; add B-roll through `media-track:Track` and editorial
- titles through `text:Track`.
-- Review A-roll and B-roll independently, then validate the joined Film. Reuse accepted shots
- explicitly in a later Run Source.
+Use one recurring presenter identity for a sequence of direct-to-camera speech takes, then add
+captions, B-roll, and editorial typography as peer Tracks.
+
+## Author the SVML program
+
+1. Write one Script with a strong opening Segment and 2–3 following Segments for context, evidence,
+ mechanism, payoff, or CTA. Keep each generated speaking take within 4–15 seconds; 8–12 seconds is
+ a useful target when the delivery remains natural.
+2. Run `estimate:Speech` for each Segment before generation.
+3. Vendor `speaker-v1.svs`. Put stable `composition-stability`, `camera-motion`, `edit-rhythm`,
+ `performance`, and `gesture` choices in an SVS Recipe.
+4. Render each take prompt with `copy:Render`; connect the Segment dialogue and one short English
+ action direction through `copy:Set`.
+5. Generate each take with `seedance:ReferenceVideo generate-audio="true"`, one accepted full
+ presenter/scene image, and the intended voice reference. Keep reference order identical across
+ the shot group.
+6. Assemble accepted takes in Script order with `speech:Spine`, then create one
+ `whisperx:Alignment` for the complete program.
+7. Add the exact-font Caption chain when captions are wanted: `caption-fine:Style` →
+ `caption:Program` → `caption-ai:Planner` → `caption-fine:Track`.
+8. Add B-roll through `media-track:Track`, editorial copy through `typo:Track`, then assemble with
+ `film:Film` and render with `render:Video`.
+
+## Direct the presenter
+
+- Keep face, apparent age, hair, wardrobe, room, light direction, lens feel, and framing envelope
+ stable across A-roll.
+- Put spoken words only in the Script-derived dialogue slot. Put visible performance in the action
+ slot: gaze changes, brows, nods, compact gestures, posture, breath, or one motivated object action.
+- Let each Segment finish one thought. Do not fragment a sentence merely to manufacture more cuts.
+- Keep hands inside the established frame and away from the face unless contact is the authored
+ action. Preserve every prop's count, support, label, and starting position.
+- Use B-roll for a genuine change of place, proof, mechanism, or emotional state. Do not make the
+ presenter identity drift to create variety.
+
+## Handle screens and reverse views
+
+When the presenter-facing shot is paired with a device-facing proof shot, define both camera
+positions before generating either image. The two opposing views must show different background
+sectors and different dominant landmark sets. Reusing the same wall, window, or furniture group is
+an automatic rejection. Preserve the same room, presenter, device, lighting logic, and eye line.
+
+Use supplied UI media whenever exact interface content matters. Keep explanatory text on
+`typo:Track`, not inside the generated shot.
+
+## Review and reuse
+
+- Review the full-resolution presenter image before any speaking take.
+- Review every A-roll take for identity, lip-sync, exact words, voice assignment, stable background,
+ hands, props, and generated text.
+- Review B-roll independently, then review the joined Film for pacing, semantic timing, caption
+ collisions, and audio clarity.
+- Pin every accepted image and take in the next Build with `.svrun` `build-record` and `satisfy`.
+
+Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`, `../craft/captions.md`,
+`../craft/b-roll.md`, and `../craft/overlays.md` for the corresponding gates.
diff --git a/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md b/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md
index 1cb6bd39..8be6f35b 100644
--- a/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md
+++ b/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md
@@ -1,21 +1,55 @@
# Two-person podcast format
-Use the vendored data-only `podcast-v1` Kit; it is a reusable Text Template, not a new execution
-node. Render it with `text:Render` plus an SVS Recipe, then feed the result to
-`seedance:ReferenceVideo` with two final camera-position images and two ordered voice references.
-Use ordered `speech:Take` inputs and peer Tracks for assembly.
-
-- Prepare two final camera-position reference images, not isolated portraits. They establish room,
- lighting, clothing, seating, and mutually consistent reverse views.
-- Prefix every Script line with an explicit speaker cue. Only the active speaker talks; the other host
- remains present with breathing, listening, and reaction.
-- Use `A:`/`B:` dialogue and connect optional take-specific action through the Kit. Keep framing,
- edit language, pacing, performance, reaction, and gesture in the Recipe rather than rewriting the
- prompt scaffold.
-- Choose rhythm deliberately: follow the speaker for measured dialogue or cut to a meaningful listener
- reaction. Framing changes are crops/pushes inside locked A/B views, never invented cameras/locations.
-- Use one `speech:Spine`, at most one `caption:Program` + `caption-fine:Track`, and `text:Track`/
- `media-track:Track` for titles/evidence.
- Keep dialogue/action prompts separate and in English.
-- Shape skeptical reviews asymmetrically: short challenge, longer grounded answer, mechanism/evidence,
- and a payoff that returns to the opening hook.
+Use two final camera-view references and intentional speaker/reaction cuts to build a coherent
+two-person conversation.
+
+## Lock the two-view geometry first
+
+Draw the room and name camera positions A and B before generating either view.
+
+- View A and View B belong to the same room, but they must show different background sectors and
+ different dominant landmark sets.
+- The two backgrounds must never be identical, near-identical, horizontally mirrored, or the same
+ wall with only the person changed.
+- Preserve seating, eye lines, table edge, microphones, shared props, light direction, lens feel,
+ and left/right relationship across the pair.
+- Reject and regenerate both images when the geometry cannot explain how the two cameras occupy the
+ room.
+
+## Author the SVML program
+
+1. Write Script turns with explicit A/B Role Cues. Use Dual Text for exact display/pronunciation
+ differences while preserving the intended visible spelling.
+2. Prepare the accepted final A-view and B-view images plus ordered A/B voice references.
+3. Vendor `podcast-v1.svs`. Select `framing`, `edit-language`, `pacing`, `performance`, `reaction`,
+ and `gesture` in an SVS Recipe.
+4. Render each Segment with `copy:Render`, Script dialogue, and an optional English action direction.
+5. Generate each take with `seedance:ReferenceVideo generate-audio="true"`, both final views, and
+ both voice references in the Kit's declared order.
+6. Assemble accepted takes through `speech:Spine`, run `whisperx:Alignment`, then add exact-font
+ Captions, evidence Media, Typography, and optional Audio Tracks.
+7. Assemble with `film:Film`, render with `render:Video`, and use `.svrun` target-sets for staged
+ review and delivery.
+
+## Direct turns and cuts
+
+- Let each speaker finish a natural thought. Short challenges may lead into longer grounded answers;
+ do not create rapid alternation by splitting one sentence into fragments.
+- Use the Recipe's speaker-following or reaction-cut pattern. Do not write camera cuts, new angles,
+ zooms, or location changes into the action slot.
+- Camera stability and performer intensity are independent: a host may lean, laugh, gesture, or
+ change posture while the two established camera views remain fixed.
+- Only the current speaker moves their mouth. A listener cutaway stays silent but visually alive.
+- A skeptical format works well as bold claim → short challenge → mechanism/evidence → grounded
+ payoff that returns to the hook. A phone CTA is optional and appears only when the Script requires it.
+
+## Review and reuse
+
+Review the two reference images side by side before video generation. Reject same-background reverse
+views, broken eye lines, contradictory seating, duplicated microphones, prop drift, or impossible
+lighting. Then review every take for voice assignment, exact words, lip-sync, reaction timing,
+camera selection, and identity. Pin accepted views and takes through `.svrun` `build-record` and
+`satisfy`.
+
+Read `../craft/visual-continuity.md`, `../craft/seedance-directing.md`, `../craft/captions.md`, and
+`../craft/persona-and-audio.md`.
diff --git a/.agents/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md b/.agents/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md
index f4a5b475..6e45d091 100644
--- a/.agents/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md
+++ b/.agents/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md
@@ -1,12 +1,54 @@
# Voiceover desk-demo format
-- Produce one continuous TTS/audio source for the narration. Plan its actual duration before selecting
- visual shot lengths; do not split TTS merely to mirror visual cuts.
-- Keep every B-roll clip silent. Visual cuts follow visible screen/product changes, not sentence
- boundaries; one sentence may cross several shots.
-- Place voiceover as an explicit `audio:Track` over independent `media-track:Track` visuals. Because
- the base is silent, bind clips with `during="program"` or explicit `start`/`end` in the shared
- `ProgramSpace`; use a `Selection`/`Moment` only when a measured speech base and `SemanticMap`
- exist. Do not use phrase-query, `full`, or manual-locator semantics from another authoring system.
-- Treat UI, labels, receipts, and website text as provided physical screen content. Add editorial
- explanations as `text:Track`, never floating generator text.
+Use one continuous voiceover as the timing authority while independent silent visual shots follow
+screen, product, hand, or proof changes.
+
+## Author the SVML program
+
+1. Write one narration Script Segment with Selections/Moments for every visual proof beat.
+2. Generate one continuous narration Blob with `mimo:Preset`, `mimo:VoiceDesign`, or
+ `mimo:VoiceClone`. Do not split TTS to match picture cuts.
+3. Put the audio directly into an audio-only Speech Take:
+
+```svml
+<speech:Spine id="speech" frame-rate="30"
+ visual-frame={full-frame} visual-appearance={studio.speech.visual} visual-z="0">
+ <speech:Take audio={narration.audio} segment={story.segment.narration}/>
+</speech:Spine>
+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+```
+
+4. Use `{speech.space}` for every Media/Typography/Caption/Audio Track and add
+ `{speech.audioTrack}` directly to `film:Film`.
+5. Build each visual beat from supplied media or the vendored `broll-v1` Kit. Generated desk/screen
+ shots use `seedance:FrameVideo` or `seedance:ReferenceVideo` with `generate-audio="false"`.
+6. Place visuals by the measured Script Selections/Moments. One sentence may span several visual
+ cuts, and one visual may cover only part of a sentence.
+7. Add editorial explanation with `typo:Track`; add the complete Caption chain only when narration
+ captions are wanted. Normalize only additional BGM/SFX before placing them on `audio:Track`.
+
+## Preserve UI and physical geometry
+
+- Use supplied screenshots or recordings whenever exact interface wording, values, charts, buttons,
+ or state changes matter.
+- Keep product UI physically attached to the screen. Do not place interface content on the laptop
+ lid, keyboard, or an impossible plane.
+- A person-facing context shot and a device-facing proof shot are opposing camera positions. Their
+ views must show different backgrounds: different room sectors and different dominant landmark
+ sets. The same background is an automatic rejection.
+- The two views must show different background sectors and different landmark sets.
+- Preserve device model, orientation, bezel, screen plane, user eye line, room, lighting logic, and
+ hand contact across the pair.
+
+## Pace and review
+
+- Generate or measure the actual narration before locking shot lengths.
+- Let visual cuts follow visible changes, not punctuation or sentence boundaries.
+- Review the full-resolution reference images first, then silent visual takes, then narration alone,
+ then the complete Film with captions, typography, music, and effects.
+- Reject unreadable UI, changed text, same-background reverse views, impossible hands, voice drift,
+ clipped narration, or visual proof that arrives before its setup.
+- Pin accepted narration and visuals through `.svrun` `build-record` and `satisfy`.
+
+Read `../craft/screen-demo.md`, `../craft/b-roll.md`, `../craft/persona-and-audio.md`, and
+`../craft/visual-continuity.md`.
diff --git a/.agents/skills/narratage/references/playbooks/index.md b/.agents/skills/narratage/references/playbooks/index.md
index c345200d..73e42011 100644
--- a/.agents/skills/narratage/references/playbooks/index.md
+++ b/.agents/skills/narratage/references/playbooks/index.md
@@ -1,54 +1,72 @@
# Narratage production playbooks
-Portable production patterns for Narratage. These files describe what to author and inspect, not
-private renderer internals or an analysis-data contract.
-
-## Decision path
-
-1. Identify the format: talking head, street interview, two-person podcast, voiceover desk demo, or
- silent mixcut. Treat format files as editorial recipes; Narratage does not provide a native
- generation surface for every format.
-2. Choose an official Seedance Kit when one matches, then apply universal gates:
- `production-gates`, `visual-continuity`, and `seedance-directing`.
-3. Add focused craft: `image-prompt-style`, `b-roll`, `overlays`, `captions`, `persona-and-audio`,
- or `screen-demo`.
-4. Read `svml-mapping.md`, then map the result to actual Narratage surfaces: Script, Seedance `TextVideo`/`FrameVideo`/
- `ReferenceVideo`, Speech Spine, SemanticMap, peer Tracks, Film, and Run Source. If a format needs
- a capability not present in the package surface, use supplied media or supported primitives and
- record the gap.
-5. Run provider-free `check`/`plan`; only then release paid generation.
-
-## Universal prompt policy
-
-- Write all VLM instructions and all image/video generation prompts in English.
-- Preserve the original language only for verbatim dialogue, transcript text, and quoted sample lines.
-- Describe desired states directly. Do not mention mutually exclusive alternatives or objects that
- should not appear; generation models can materialize them.
-- Never ask Seedance to render subtitles, captions, floating labels, stickers, or UI overlays. Author
- those as `caption-fine:Track`, `text:Track`, or `media-track:Track`.
+Use these playbooks to author production decisions directly in `.svml`, `.svs`, and `.svrun`
+sources. Each playbook names the SVML components, timing model, review gates, and reuse behavior
+needed for that craft or format.
+
+## Required load order
+
+1. Always read `craft/production-gates.md` and `craft/visual-continuity.md`.
+2. Read `craft/seedance-directing.md` whenever the Author Source invokes Seedance.
+3. Read the selected format file and only the additional craft files it names.
+4. Read the relevant authoritative Quickstart or package README before writing unfamiliar syntax.
+
+## Shared SVML contract
+
+- Put narrative truth in one `script` with Segments, Role Cues, Selections, and Moments.
+- Use `copy:Value`/`copy:Render` from `@narratage/text@1` for prompts and reusable copy.
+- Use `typo:Style`/`typo:Track` from `@narratage/typography-track@1` for editorial text.
+ Never use the same import alias for generic Text and typography.
+- Vendor the selected Seedance Kit into the project, choose stable axes in an SVS Recipe, and keep
+ dynamic dialogue/action/story in explicit Text edges.
+- Keep model invocation explicit with `seedance:TextVideo`, `seedance:FrameVideo`, or
+ `seedance:ReferenceVideo`; keep every media reference, duration, model, resolution, and aspect
+ ratio visible in the Author Source.
+- Build speech-led programs with `speech:Spine`, measure them with `whisperx:Alignment`, then add
+ peer Caption, Media, Typography, Ranking, Deck, Comment, Screen, and Audio Tracks.
+- Use `speech:Spine` for speech-bearing video or audio Takes. For speech-free formats, select a
+ verified ProgramSpace Record in `.svrun`, author explicit timing, and omit WhisperX/Caption work.
+- Assemble peer Tracks with `film:Film`, render with `render:Video`, and demand outputs through a
+ `.svrun` Target.
+- Stage expensive work with narrow target-sets. Pin and reuse an accepted Record through
+ `build-record` plus `satisfy`; Narratage has no implicit cache.
+- Use only elements and attributes documented by the current Quickstart or package README. Never
+ invent a component or attribute to fill in missing syntax.
+
+## Prompt policy
+
+- Write VLM instructions and image/video generation prompts in English. Keep original-language
+ dialogue, transcript, pronunciation, and quoted copy verbatim.
+- Describe the desired visible state directly. Omit unwanted concrete objects instead of naming
+ them inside negations or hypotheticals that a model may materialize.
+- Keep editorial captions, titles, stickers, cards, and callouts out of generation prompts. Author
+ them as explicit Tracks. Preserve text that is physically attached to a supplied product, screen,
+ document, or sign.
## Craft
-- `craft/image-prompt-style.md` — realistic reference-frame construction.
-- `craft/seedance-directing.md` — action prompts and physical motion envelopes.
-- `craft/visual-continuity.md` — identity, reverse views, props, and shot continuity.
-- `craft/b-roll.md` — story-first inserts and supplied/generated media decisions.
-- `craft/screen-demo.md` — UI and device demonstrations.
-- `craft/overlays.md` — text, stickers, PIP, timing, and gaps.
-- `craft/captions.md` — one caption program and measured timing.
-- `craft/persona-and-audio.md` — identity and voice references.
-- `craft/pip-overlay.md` — composited picture-in-picture.
-- `craft/sfx.md` — event-based sound effects.
-- `craft/production-gates.md` — free validation, review, and paid gates.
+- `craft/production-gates.md` — staged Targets, image review, paid generation, and explicit reuse.
+- `craft/visual-continuity.md` — identity, shot groups, reverse-view geometry, and prop invariants.
+- `craft/image-prompt-style.md` — English reference-image prompts and camera geometry.
+- `craft/seedance-directing.md` — Kit selection, Recipe axes, references, and motion direction.
+- `craft/b-roll.md` — story-led silent inserts and semantic placement.
+- `craft/screen-demo.md` — physically possible device/UI views and exact supplied UI.
+- `craft/captions.md` — complete Caption pipeline and review rules.
+- `craft/overlays.md` — Typography, Media, Comment, and Screen Tracks.
+- `craft/pip-overlay.md` — framed video, alpha cutouts, and picture-in-picture timing.
+- `craft/persona-and-audio.md` — identity, voice, TTS, normalization, and mix separation.
+- `craft/sfx.md` — event-led sound design on explicit Audio Tracks.
## Formats
-- `formats/talking-head.md`
-- `formats/street-interview.md`
-- `formats/two-person-podcast.md`
-- `formats/voiceover-desk-demo.md`
-- `formats/mixcut.md`
-- `formats/ranking-listicle.md`
-- `formats/scenario-call.md`
-- `formats/asmr.md`
-- `formats/mass-tarot.md`
+| Format | Additional craft to read |
+|---|---|
+| `formats/talking-head.md` | `seedance-directing`, `persona-and-audio`, `captions`, `b-roll`, `overlays` |
+| `formats/street-interview.md` | `seedance-directing`, `persona-and-audio`, `captions`, `b-roll` |
+| `formats/two-person-podcast.md` | `seedance-directing`, `persona-and-audio`, `captions`, `b-roll` |
+| `formats/scenario-call.md` | `seedance-directing`, `persona-and-audio`, `captions`, `overlays` |
+| `formats/ranking-listicle.md` | `captions`, `overlays`, `sfx` |
+| `formats/mass-tarot.md` | `b-roll`, `overlays`, `persona-and-audio`, `captions` |
+| `formats/voiceover-desk-demo.md` | `persona-and-audio`, `b-roll`, `screen-demo`, `captions`, `sfx` |
+| `formats/mixcut.md` | `image-prompt-style`, `b-roll`, `overlays`, `sfx` |
+| `formats/asmr.md` | `image-prompt-style`, `seedance-directing`, `persona-and-audio`, `sfx` |
diff --git a/.agents/skills/narratage/references/playbooks/svml-mapping.md b/.agents/skills/narratage/references/playbooks/svml-mapping.md
deleted file mode 100644
index 101395d7..00000000
--- a/.agents/skills/narratage/references/playbooks/svml-mapping.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Narratage surface mapping
-
-Use this map when translating an editorial playbook into SVML. These are current package surfaces,
-not aliases for the old canvas/JSON workflow.
-
-| Editorial need | Narratage author surface |
-|---|---|
-| Story and dialogue | `Script`, `Segment`, `Role Cue`, `Selection`, `Moment` |
-| Prompt or reusable copy | `text:Value` and `text:Render` (backed by Text Templates) |
-| Reusable Seedance prompt contract | vendored `speaker-v1`, `broll-v1`, `podcast-v1`, `call-v1`, `street-interview-v1`, `motion-reference-v1`, or `camera-reference-v1` Kit + SVS Recipe |
-| Generated image | `gpt:Image`, `nano:Image`/`nano:ProImage`, or `seedream:TextImage`/`ReferenceImage` |
-| Text-to-video | `seedance:TextVideo` |
-| First-frame-to-video | `seedance:FrameVideo` |
-| Reference-image/audio-to-video | `seedance:ReferenceVideo` |
-| Ordered speech-video assembly | `speech:Spine` with `speech:Take` children |
-| Measured speech timing | `whisperx:Alignment` → `{timing.map}` |
-| Caption policy | `caption:Program` |
-| Caption planning/rendering | `caption-ai:Planner` + `caption-fine:Track` |
-| B-roll, PIP, supplied media | `media-track:Track` + `media-track:Item` |
-| Editorial titles/callouts | `text:Track` + `text:Area`/`text:Point`/`text:Path` |
-| Music, voiceover, SFX | `audio:Track` + `audio:Clip` |
-| Ranking/listicle visuals | an official `ranking:Column`/`TierBoard`/`TopThree`/`TypewriterList` or `deck:DepthStack` surface |
-| Final composition | `film:Film` + `film:Track` |
-| Video output | `render:Video` |
-| Reusable run/build definition | `.svrun` Run Source, `Target`, and Runtime Profile |
-
-## Timing rule
-
-Use `during="program"` or explicit `start`/`end` for absolute author-time placement. When speech
-timing is available, use `during={story.selection.<id>}` for a range or `at={story.moment.<id>}`
-with the component's duration attribute (for example `for="2s"`). A Selection/Moment is semantic
-and is resolved through `{timing.map}`; it is not a literal transcript query or a source-video
-timestamp.
-
-## Translation rule
-
-Editorial concepts map to the nearest supported package surface. Do not invent a native component
-for a format that Narratage does not ship: use supplied media plus peer Tracks, or record the gap.
-Do not add a storyboard JSON layer or a conversion script between VLM analysis and `.svml`.
diff --git a/.agents/skills/narratage/references/quickstart.md b/.agents/skills/narratage/references/quickstart.md
index 81508761..c17047a1 100644
--- a/.agents/skills/narratage/references/quickstart.md
+++ b/.agents/skills/narratage/references/quickstart.md
@@ -15,11 +15,18 @@ The repository docs are authoritative:
Canonical path:
-`Script → estimate:Speech/text → Seedance or supplied media → Speech Spine → WhisperX SemanticMap → peer Caption/Media/Text/Audio Tracks → Film → render:Video`.
+`Script → estimate:Speech/text → Seedance or supplied media → Speech Spine → WhisperX SemanticMap → peer Caption/Media/Typography/Audio Tracks → Film → render:Video`.
Use explicit imports, exact fonts, Canvas/Frames, ProgramSpace, package locks, Targets, and Runtime
authority. There is no implicit cache; reuse is explicit with `build-record` + `satisfy`.
+Use `speech:Take video={...}` for a speech-bearing A/V take and `speech:Take audio={...}` for
+voiceover. An audio Take creates program time and speech audio while peer Media Tracks provide the
+visuals.
+
+For a speech-free program, select a verified ProgramSpace Record through `.svrun` `build-record`
+and `satisfy`, use explicit Track windows, and omit WhisperX and Caption components.
+
For execution, preserve the full lifecycle: diagnose the Profile, start or reuse the durable
Runtime, inspect the frozen plan, submit a named Build, inspect its accepted Records, retrieve
Artifacts, and declare any reuse explicitly in a new Run Source.
diff --git a/.agents/skills/narratage/references/reference-vlm.md b/.agents/skills/narratage/references/reference-vlm.md
index 9b12cc1d..06a1350c 100644
--- a/.agents/skills/narratage/references/reference-vlm.md
+++ b/.agents/skills/narratage/references/reference-vlm.md
@@ -1,7 +1,6 @@
# Reference video VLM to SVML
-Write `main.svml`, optional `studio.svs`, and `build.svrun` directly. Do not persist storyboard/
-overlay JSON or introduce a JSON-to-SVML conversion step.
+Write `main.svml`, optional `studio.svs`, and `build.svrun` directly.
- Write all VLM instructions and generated image/video prompts in English. Preserve original language
only for verbatim dialogue/transcript/sample lines.
@@ -14,14 +13,20 @@ overlay JSON or introduce a JSON-to-SVML conversion step.
- Before hand-writing a Seedance prompt, select an official vendored Kit when the format matches:
`speaker-v1`, `broll-v1`, `podcast-v1`, `call-v1`, `street-interview-v1`,
`motion-reference-v1`, or `camera-reference-v1`. Supply only Recipe axes and dynamic slots.
-- Map transcript to Script; generated media to `seedance:TextVideo`/`FrameVideo`/`ReferenceVideo`;
- supplied assets to `media:Image`/`media:Audio` or `media-track:Item`; timing to `speech:Spine` and
- `whisperx:Alignment`; overlays to `caption:Program` + `caption-fine:Track`, `media-track:Track`,
- and `text:Track`; then `film:Film`/`render:Video` and a final-video Run Target.
+- Author the transcript as Script; keep reusable prompt copy in `copy:Value`/`copy:Render`; generate
+ media with `seedance:TextVideo`, `seedance:FrameVideo`, or `seedance:ReferenceVideo`; declare
+ supplied assets with `media:Image`/`media:Audio` or place them with `media-track:Item`; establish
+ timing with `speech:Spine` and `whisperx:Alignment`; build captions with an exact font,
+ `caption-fine:Style`, `caption:Program`, `caption-ai:Planner`, and `caption-fine:Track`; put
+ editorial text on `typo:Track`; then assemble with `film:Film`, render with `render:Video`, and
+ demand the desired outputs in `build.svrun`.
+- Route every generated reference image through `playbooks/craft/production-gates.md`. Pin and reuse
+ each accepted image or take in the next Build with `.svrun` `build-record` and `satisfy`.
-Generated image prompt structure: English realistic-iPhone reality contract, detailed subject/story,
-camera/reference relationship, then `Natural lighting, detailed realistic skin texture, and no visual artifacts.`
+Generated image prompt structure: an English reality contract matching the observed capture medium,
+the exact visible subject/story, camera geometry, and the role of every reference. Keep lighting,
+skin/material texture, focus, and photographic finish consistent with the reference format.
-Every generated motion prompt ends with:
+When no official Kit applies, include this hygiene block in a freeform motion prompt:
`Do not add subtitles or any on-screen text. Do not add stickers, labels, captions, floating words, or other graphic overlays. Preserve text that is physically printed on the product, device, or screen as part of the filmed content.`
diff --git a/.agents/skills/narratage/references/runtime.md b/.agents/skills/narratage/references/runtime.md
index 3bbf298b..c7372148 100644
--- a/.agents/skills/narratage/references/runtime.md
+++ b/.agents/skills/narratage/references/runtime.md
@@ -6,22 +6,21 @@ Build, retrieval, and reuse syntax. Use this file as the operational checklist.
## Execute the lifecycle
```bash
-pnpm narratage doctor path/to/svml.runtime.json
-pnpm narratage runtime up path/to/svml.runtime.json
-pnpm narratage runtime status path/to/svml.runtime.json
+node --run narratage -- doctor path/to/svml.runtime.json
+node --run narratage -- runtime up path/to/svml.runtime.json
+node --run narratage -- runtime status path/to/svml.runtime.json
-pnpm narratage check path/to/main.svml \
- --package-lock path/to/svml.packages.lock --root .
-pnpm narratage plan path/to/build.svrun \
- --package-lock path/to/svml.packages.lock --root .
+node --run narratage -- check path/to/main.svml \
+ --runtime path/to/svml.runtime.json --root .
+node --run narratage -- plan path/to/build.svrun \
+ --runtime path/to/svml.runtime.json --root .
-pnpm narratage build path/to/build.svrun \
+node --run narratage -- build path/to/build.svrun \
--runtime path/to/svml.runtime.json \
- --package-lock path/to/svml.packages.lock \
--root . --build-id my-build-001 --follow
-pnpm narratage inspect my-build-001 --runtime path/to/svml.runtime.json
-pnpm narratage get my-build-001 \
+node --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.json
+node --run narratage -- get my-build-001 \
--runtime path/to/svml.runtime.json \
--name final.video --to path/to/output/final.mp4
```
@@ -40,7 +39,7 @@ durable Builds and does not cancel remote Provider work.
terminal does not stop the Build.
- `inspect` reads durable Build state and accepted Records. `get` copies an archived Artifact to the
requested destination.
-- There is no implicit cache. Reuse Records only through a new `.svrun` containing `build-record`
+- There is no implicit cache. Pin and reuse Records through a new `.svrun` containing `build-record`
and `satisfy`, with the target accepting the resulting fidelity.
## Keep project and package boundaries distinct
diff --git a/.agents/skills/narratage/references/seedance-kits.md b/.agents/skills/narratage/references/seedance-kits.md
index 8d767dac..3b517c00 100644
--- a/.agents/skills/narratage/references/seedance-kits.md
+++ b/.agents/skills/narratage/references/seedance-kits.md
@@ -1,7 +1,8 @@
# Seedance Prompt Kits
-Narratage ships seven data-only English Text Templates under `packages/seedance-kits/kits/`. They
-assemble recurring prompt contracts without adding execution nodes or hiding media/model choices.
+Narratage ships seven English Text Templates under `packages/seedance-kits/kits/`. Each Kit owns the
+repeatable prompt contract; the project Recipe selects its stable directing axes, and explicit Text
+slots carry shot-specific dialogue or action.
| Format | Kit | Required dynamic slots | Ordered references |
|---|---|---|---|
@@ -18,9 +19,19 @@ assemble recurring prompt contracts without adding execution nodes or hiding med
1. Read `packages/seedance-kits/README.md` and the selected Kit file for exact axes and defaults.
2. Copy only that `.svs` file into the video project's `./kits/` directory; import the vendored copy.
3. Put stable axis choices in `studio.svs` as a named Recipe.
-4. Use `text:Render` with the Kit Template and Recipe. Connect dynamic slots with `text:Set`.
+4. Import `@narratage/text@1` as `copy`. Use `copy:Render` with the Kit Template and Recipe, then
+ connect dynamic slots with `copy:Set`.
5. Feed the rendered Text to the appropriate low-level Seedance Surface. Keep duration, resolution,
- model, and every image/audio/video reference explicit on the graph.
+ model, and every image/audio/video reference explicit in the Author Source.
-Do not hand-write or duplicate a Kit's fixed reference, role, voice, microphone, camera, or hygiene
-blocks. Write a freeform English prompt only when none of the seven Kit contracts matches.
+Select these Recipe axes instead of rewriting their prompt blocks:
+
+| Kit | Stable Recipe axes |
+|---|---|
+| `speaker-v1` | `composition-stability`, `camera-motion`, `edit-rhythm`, `performance`, `gesture` |
+| `broll-v1` | `material-mode`, `story-shape`, `edit-language`, `camera-language`, `motion-intensity` |
+| `podcast-v1` / `call-v1` | `framing`, `edit-language`, `pacing`, `performance`, `reaction`, `gesture` |
+| `street-interview-v1` | `framing`, `edit-language`, `pacing`, `performance`, `reaction`, `gesture` |
+
+Use a freeform English prompt only when none of the seven Kit contracts matches. Keep dialogue in
+its authored language when it must be spoken verbatim.
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 00000000..2b7a412b
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/.codex/skills b/.codex/skills
new file mode 120000
index 00000000..2b7a412b
--- /dev/null
+++ b/.codex/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 31527f1d..4b3361ea 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,9 +8,11 @@ coverage/
*.temp
*.lock.editing
-# Local editor and agent state is never part of the distribution.
-.claude/
-.codex/
+# Ignore local editor state while distributing repository skill-discovery links.
+.claude/*
+!.claude/skills
+.codex/*
+!.codex/skills
.agents/*
!.agents/skills/
!.agents/skills/**
diff --git a/docs/quickstart.md b/docs/quickstart.md
index cdf40587..f1c311e3 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -5,6 +5,28 @@ description: Set up Narratage and compile your first video graph.
# Quickstart
+## Choose your path
+
+**Use the Narratage skill.** Install the complete
+[`narratage` skill folder](https://github.com/cashdiffusion/svml/tree/main/.agents/skills/narratage)
+with your agent's standard skill installer, or send that link to the agent and ask it to install and
+use the skill. If you already cloned the repository, point the installer at
+`.agents/skills/narratage`; install the whole folder, not only `SKILL.md`.
+
+```text
+Install and use the narratage skill from this repository. Set up my environment, ask for only the
+API keys required by my Runtime Profile, and guide me through authoring and building my first SVML
+video.
+```
+
+Codex and Claude sessions opened in this checkout can discover the canonical skill through the
+checked-in `.codex/skills` and `.claude/skills` links. If a Windows checkout does not preserve
+symlinks, give the agent `.agents/skills/narratage` directly. Once the skill is active, the agent
+loads the relevant Quickstart pages for you, so you do not need to read the rest of this guide
+manually.
+
+**Continue manually.** Start with [Install](#install), then follow the seven guides in order.
+
The name **Narratage** comes from a 1933 *New York Times* review of the film *The Power and the
Glory*. The critic coined the word to describe a then-new cinematic technique:
**Narration + Montage** — a narrator's voice carries the story forward while the screen assembles
@@ -18,16 +40,36 @@ been published to npm yet.
## Install
-Requires Node.js 22+ and pnpm for installing/testing this source workspace. The ordinary CLI
-examples use Node's built-in script runner so each command does not launch pnpm again.
+The source workspace requires Node.js 22+ and pnpm 10.33.x through Corepack. These commands are the
+same in macOS/Linux shells and Windows PowerShell. The ordinary CLI examples use Node's built-in
+script runner so each command does not launch pnpm again.
+
+Some newer Node.js distributions do not bundle Corepack. If `corepack --version` is unavailable,
+install a compatible release first from either shell:
+
+```text
+npm install --global [email protected]
+```
```bash
corepack enable
+corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm check
pnpm test
```
+Local media work also requires `ffmpeg` and `ffprobe` on `PATH`. Python is optional: install Python
+3.10–3.13 and [`uv`](https://docs.astral.sh/uv/) only when the Runtime Profile selects local
+WhisperX or OpenCV. Prepare the locked environments from either shell with:
+
+```text
+uv python install 3.13
+uv sync --project services/whisperx --frozen
+uv sync --project services/image-opencv --frozen
+uv run --project services/whisperx --frozen svml-whisperx-prepare
+```
+
Inside the source checkout, commands use `node --run narratage -- ...`. A project outside this
repository uses `/path/to/svml/narratage ...` plus `--package-root /path/to/svml`; the checked-in
launcher starts the same CLI directly without pnpm, and all project state stays under that external
@@ -70,6 +112,6 @@ before spending money.
| [SVS Stylesheets](./quickstart/styles.md) | CSS-like Recipes for film, caption, B-roll, text, speech and fonts |
| [Media & Generation](./quickstart/generation.md) | media:Image, media:Audio, estimate:Speech, Text Templates, Seedance |
| [Timing & Assembly](./quickstart/timing.md) | speech:Spine, whisperx:Alignment, ProgramSpace, SemanticMap |
-| [Caption, Media & Text](./quickstart/tracks.md) | caption-fine:Style/Track, caption:Program, Planner, Media Track and Text |
+| [Caption, Media, Text & Audio](./quickstart/tracks.md) | Caption, Media, Typography and Audio Track authoring |
| [Film & Rendering](./quickstart/composition.md) | film:Film, render:Video, full pipeline walkthrough |
| [Run Source & Builds](./quickstart/run.md) | .svrun syntax, targets, reuse, runtime profile, build workflow |
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
index ffd6db70..06876b2a 100644
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@ -205,15 +205,25 @@ Copy only the selected Kit `.svs` files into the video project's `./kits/` direc
vendored project copy so the Kit bytes remain inside the Source Closure; do not reach back into a
Narratage repository checkout from project source.
+Read the
+[`@narratage/seedance-kits` guide](https://github.com/cashdiffusion/svml/blob/main/packages/seedance-kits/README.md)
+and the [selected Kit source](https://github.com/cashdiffusion/svml/tree/main/packages/seedance-kits/kits)
+before authoring. Use an official Kit whenever its format matches. Keep generation instructions and
+dynamic prompt slots in English; preserve the authored language only for dialogue that must be
+spoken verbatim. Write a freeform English prompt only when none of the seven Kits applies.
+
```svml
<import as="text" from="@narratage/text@1"/>
<import as="seedance" from="@narratage/seedance@1"/>
<import as="broll-kit" source="./kits/broll-v1.svs"/>
+<text:Value id="product-story">
+ Show the product opening, the primary feature activating, and the finished result in one readable sequence.
+</text:Value>
<text:Render id="demo-prompt"
template={broll-kit.broll-v1}
recipe={studio.broll.product-demo}>
- <text:Set name="story" text={copy.product-demo}/>
+ <text:Set name="story" text={product-story}/>
</text:Render>
<seedance:ReferenceVideo id="demo" model="mini"
@@ -231,11 +241,20 @@ The project Recipe selects axes such as `material-mode`, `story-shape` and `came
`text:Render` reads only properties declared by the template; an explicit `text:Param` overrides a
Recipe value. Dynamic story/dialogue/action/extra content remains a `Text` edge through `Set`.
-Available templates are `speaker-v1`, `broll-v1`, `podcast-v1`, `call-v1`, `street-interview-v1`,
-`motion-reference-v1` and `camera-reference-v1`. Podcast and Call expect two ordered image
-references plus two ordered audio references; Street Interview expects one scene image plus two
-ordered voices; the two reference-transfer templates expect one subject image and one reference
-video. Those shapes are visible in `seedance:ReferenceVideo`, not hidden in Kit execution code.
+Choose the Kit by format, then provide its declared dynamic slots and ordered references:
+
+| Format | Kit | Dynamic slots | Ordered references |
+|---|---|---|---|
+| Talking head | `speaker-v1` | `dialogue`; optional `action` | image 1 = speaker/scene; audio 1 = voice |
+| Silent B-roll | `broll-v1` | `story` | one or more authored images |
+| Two-person podcast | `podcast-v1` | `dialogue`; optional `action` | images 1/2 = A/B views; audio 1/2 = A/B voices |
+| Video call | `call-v1` | `dialogue`; optional `action` | images 1/2 = reversed call layouts; audio 1/2 = A/B voices |
+| Street interview | `street-interview-v1` | `dialogue`; optional `action` | image 1 = complete scene; audio 1/2 = interviewer/guest |
+| Motion transfer | `motion-reference-v1` | optional `direction` | image 1 = subject; video 1 = motion reference |
+| Camera transfer | `camera-reference-v1` | optional `direction` | image 1 = subject; video 1 = camera reference |
+
+These shapes remain visible in `seedance:ReferenceVideo`; Kit rendering does not hide media count or
+order.
## Street-interview prompt assembly
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index c4dfa13e..13ed657e 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -85,6 +85,10 @@ The `targets` attribute on `<svrun>` selects which set is active.
Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — you declare
historical Records as zero-input Candidates and connect them through Satisfaction edges.
+As soon as a generated image or take is accepted, pin it in the next `.svrun` with `build-record`
+and `satisfy`, let the consuming Target accept the declared fidelity, and inspect the frozen plan
+before starting paid downstream work.
+
```svml
<?svml using="@narratage/run-markup@1"?>
@@ -186,6 +190,10 @@ that consume substitute inputs produce substitute results.
The Runtime Profile (`svml.runtime.json`) tells the system **where** to run each type of work:
+Declarative `svml.runtime.json` is the standard form. Advanced trusted embedding may instead use
+`svml.runtime.ts`; both are passed to `--runtime` and assemble the same explicit roles. See the
+complete [Runtime Profile guide](../guide/runtime-profile.md).
+
```json
{
"format": "svml.runtime-config@1",
@@ -291,8 +299,46 @@ require permissions not listed here.
and one exact capability Route resource. Optional `resources` overrides use those opaque resource
ids; they never select a model or Provider.
+## Configure selected credentials
+
+`check` and `plan` do not make live Provider requests and do not need API keys. Before `doctor` or a
+paid/external `build`, configure only the environment variables referenced by the selected Runtime
+Profile:
+
+| Variable | Provider/use |
+|---|---|
+| `KIE_API_KEY` | KIE models, including Seedance and GPT Image |
+| `GOOGLE_CLOUD_PROJECT` | Google Cloud project with Vertex AI enabled |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON` | Complete Vertex credential JSON contents, not a file path |
+| `MIMO_API_KEY` | Xiaomi MiMo TTS, only when that Endpoint is selected |
+
+Run only the lines for the Endpoints in your Profile. In macOS/Linux shells:
+
+```bash
+read -r -s KIE_API_KEY
+export KIE_API_KEY
+read -r -s MIMO_API_KEY
+export MIMO_API_KEY
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_APPLICATION_CREDENTIALS_JSON="$(<"$HOME/.config/narratage/google-service-account.json")"
+```
+
+In Windows PowerShell:
+
+```powershell
+$env:KIE_API_KEY = "your-key"
+$env:MIMO_API_KEY = "your-key"
+$env:GOOGLE_CLOUD_PROJECT = "your-project-id"
+$env:GOOGLE_APPLICATION_CREDENTIALS_JSON = Get-Content -Raw "$HOME\.config\narratage\google-service-account.json"
+```
+
+Keep credentials out of Author Source, Run Source, Runtime Profile source, and committed files.
+`doctor` validates required credential presence without printing secret values.
+
## Build workflow
+Keep credentials, generated media, Runtime state/databases, and logs out of commits.
+
### 0. Install
```bash
@@ -378,7 +424,23 @@ node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json
Doctor validates both locks, every selected Runtime role, Endpoint configuration, credential
presence and bounded environment probes. It never starts the Worker or performs a paid request.
-### 2. Inspect the plan
+### 2. Start or reuse the Runtime
+
+```bash
+node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime status examples/talking-head-aroll/svml.runtime.json
+```
+
+`runtime up` owns the detached durable Worker and every external program declared by the Profile.
+The narrower `services up|status|down` commands manage only those external programs and do not own
+the Worker lifecycle.
+
+### 3. Check source and inspect the plan
+
+```bash
+node --run narratage -- check examples/talking-head-aroll/main.svml \
+ --runtime examples/talking-head-aroll/svml.runtime.json --root .
+```
```bash
node --run narratage -- plan examples/talking-head-aroll/build.svrun \
@@ -388,7 +450,7 @@ node --run narratage -- plan examples/talking-head-aroll/build.svrun \
Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the
Scheduler would issue.
-### 3. Submit the Build
+### 4. Submit the Build
```bash
node --run narratage -- build examples/talking-head-aroll/build.svrun \
@@ -418,7 +480,15 @@ failed or cancelled Build remains terminal and is only reported. Use a new expli
unchanged prompt intentionally needs another stochastic take. Reusing an explicit id for different
compiled intent is rejected with both repair choices.
-### 4. Retrieve results
+### 5. Inspect and retrieve results
+
+```bash
+node --run narratage -- inspect my-film-001 \
+ --runtime examples/talking-head-aroll/svml.runtime.json
+```
+
+`inspect` reports durable Build state, demanded outputs, and accepted Records. Retrieve the selected
+archived Artifact only after those facts are correct:
```bash
node --run narratage -- get my-film-001 \
@@ -435,7 +505,7 @@ exporting a large MP4 does not buffer the complete file in CLI memory.
The terminal Build result prints the exact `get --name …` command for every targeted source alias;
there is no need to inspect opaque Record ids just to export `final.video`.
-### 5. Reuse in a new Build
+### 6. Reuse in a new Build
Create a new `.svrun` file that references the completed Build's Records (see [Reusing results](#reusing-results)
above), then submit it:
@@ -445,3 +515,14 @@ node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun
--runtime examples/talking-head-aroll/svml.runtime.json \
--root . --build-id my-film-reuse-001 --follow
```
+
+### 7. Diagnose or stop the local Runtime
+
+```bash
+node --run narratage -- runtime logs examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime down examples/talking-head-aroll/svml.runtime.json
+```
+
+`runtime down` stops the Worker from claiming more leases and stops Runtime-owned programs. It does
+not cancel durable Builds or remote Provider work. Start the same Profile again to resume local
+execution.
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
index c4a971bb..5b156994 100644
--- a/docs/quickstart/timing.md
+++ b/docs/quickstart/timing.md
@@ -68,6 +68,15 @@ all three values unless it overrides them. An audio Take cannot declare visual o
is playing, `speech.visual` simply has no Present, so the Film background or peer Tracks remain
visible.
+For voiceover timing, use an audio Take and supply the visuals through peer Media Tracks:
+
+```svml
+<speech:Spine id="speech" frame-rate="30"
+ visual-frame={speech-frame} visual-appearance={studio.speech.visual} visual-z="0">
+ <speech:Take audio={narration.audio} segment={story.segment.narration}/>
+</speech:Spine>
+```
+
The fit Recipe is ordinary compile-time SVS data, for example:
```svs
@@ -135,6 +144,14 @@ ProgramSpace owns:
Every component that operates in the time domain takes a `space` attribute pointing to
`{speech.space}`.
+### Speech-free programs
+
+A speech-free film still needs an explicit, verified ProgramSpace. Select a previously accepted
+ProgramSpace Record in the Run Source with `build-record` and `satisfy`, then connect that named
+logical output to Tracks and Film. Use `during="program"` or explicit `start`/`end` windows. Without
+speech there is no measured SemanticMap, so omit WhisperX and Caption components and do not use
+Selection/Moment timing. See [Reusing results](./run.md#reusing-results) for Run Source syntax.
+
## SemanticMap
The SemanticMap is the typed bridge between Script text and physical time. When you write
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index afb753e8..39164a23 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -1,17 +1,17 @@
---
-title: Caption, Media & Typography
-description: Visual track components — captions, media overlays and typography overlays.
+title: Caption, Media, Typography & Audio
+description: Peer track components — captions, media, typography and authored audio.
---
-# Caption, Media & Typography
+# Caption, Media, Typography & Audio
-> **Pre-release note:** Caption Fine, Media Track and Typography Track execute their declared author Surfaces.
+> **Pre-release note:** Caption Fine, Media Track, Typography Track and Audio Track execute their declared author Surfaces.
> Their author APIs may still evolve; the shared terminal Track/Visual IR waist is frozen inside the
> repository but has not been published as an npm ABI.
Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat
-(no nesting), and their z-order is determined by the `stack-order` property in SVS. This page
-covers three official visual Track packages: captions, media, and typography overlays.
+(no nesting), and visual z-order is determined by the `stack-order` property in SVS. This page
+covers Caption, Media, Typography and Audio Track authoring.
## Caption system
@@ -211,6 +211,43 @@ or specially selected media, whose output then connects through `media=`.
**Outputs:** `{product-broll.visual}` and, only when explicitly authored, `{product-broll.audio}`.
+## Audio tracks
+
+`@narratage/audio-track` places explicitly prepared audio on the same ProgramSpace as the visual
+Tracks. A `Clip` consumes `SynchronizedMedia`; normalize a declared or generated audio Blob first,
+then choose its exact program window and occupancy:
+
+```svml
+<import as="media" from="@narratage/media@1"/>
+<import as="pipeline" from="@narratage/media-pipeline@1"/>
+<import as="audio" from="@narratage/audio-track@1"/>
+
+<media:Audio id="music" src="./assets/music.wav"/>
+<pipeline:Normalize id="music-media" source={music}
+ video="none" audio="default" span-authority="audio" frame-rate="30"/>
+
+<audio:Track id="music-bed" space={speech.space}>
+ <audio:Clip source={music-media.media} during="program"
+ playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+</audio:Track>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `Track.id` | yes | Stable Audio Track identity |
+| `Track.space` | yes | ProgramSpace that defines the exact sample and frame domain |
+| `Clip.source` | yes | Explicitly selected and normalized `SynchronizedMedia` |
+| `during`, `at`/`for`, or `start`/`end` | exactly one form | Whole-program, Selection, Moment, or explicit window |
+| `map` | for Selection/Moment | SemanticMap used to resolve semantic timing |
+| `playback` | no | `once`, `once-end`, `loop`, `loop-end`, or bounded `stretch` |
+| `occurrences` | no | `one` or `each` when a semantic source has multiple occurrences |
+| `trim-start`, `trim-end` | no | Exact source trim |
+| `gain`, `fade-in`, `fade-out` | no | Explicit per-clip mix values |
+
+The package performs no automatic extraction, normalization, ducking, or bus routing. Multiple
+Clips in one Track and multiple peer Audio Tracks remain independent inputs to Film. The output is
+`{music-bed.track}`, an ordinary `AudioTrack`.
+
## Text overlays
Static or timed text displayed on screen — titles, callouts, lower thirds.
@@ -292,15 +329,18 @@ placement, timing, style and motion. Use inline `P`/`Span`/`Break` when the auth
## Combination example
-All three track types together in one source file:
+All four track families together in one source file:
```svml
<import as="caption" from="@narratage/caption@1"/>
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
<import as="fonts" from="@narratage/fonts-open@1"/>
+<import as="media" from="@narratage/media@1"/>
+<import as="pipeline" from="@narratage/media-pipeline@1"/>
<import as="media-track" from="@narratage/media-track@1"/>
<import as="text" from="@narratage/typography-track@1"/>
+<import as="audio" from="@narratage/audio-track@1"/>
<import as="space" from="@narratage/spatial@1"/>
<!-- Captions: primary style for all text -->
@@ -334,13 +374,23 @@ All three track types together in one source file:
</text:Area>
</text:Track>
-<!-- All three tracks feed into Film -->
+<!-- Audio: normalize one declared source, then place it for the complete program -->
+<media:Audio id="music" src="./assets/music.wav"/>
+<pipeline:Normalize id="music-media" source={music}
+ video="none" audio="default" span-authority="audio" frame-rate="30"/>
+<audio:Track id="music-bed" space={speech.space}>
+ <audio:Clip source={music-media.media} during="program"
+ playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+</audio:Track>
+
+<!-- All peer tracks feed into Film -->
<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={cards.visual}/>
<film:Track source={captions.track}/>
<film:Track source={titles.track}/>
+ <film:Track source={music-bed.track}/>
</film:Film>
```
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index e2166ad5..2c83423e 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -5,6 +5,25 @@ description: 搭建 Narratage 并编译你的第一张视频图。
# Quickstart
+## 选择开始方式
+
+**使用 Narratage skill。** 通过 Agent 自带的 skill 安装器安装完整的
+[`narratage` skill 文件夹](https://github.com/cashdiffusion/svml/tree/main/.agents/skills/narratage),
+也可以把这个链接发给 Agent,让它安装并使用该 skill。已经克隆仓库时,直接让安装器读取
+`.agents/skills/narratage`;需要安装整个文件夹,而不是只复制 `SKILL.md`。
+
+```text
+安装并使用这个仓库里的 narratage skill。配置我的环境,只向我索取当前 Runtime Profile
+实际需要的 API key,然后带我完成第一支 SVML 视频的创作与 Build。
+```
+
+在本仓库内打开的 Codex 与 Claude 会通过已提交的 `.codex/skills`、`.claude/skills` 链接发现
+这份 canonical skill。如果 Windows checkout 没有保留软链接,直接把
+`.agents/skills/narratage` 交给 Agent。skill 生效后,Agent 会按需读取对应的 Quickstart 页面,
+你无需再手动通读后文。
+
+**手动开始。** 从[安装](#安装)继续,然后按顺序阅读七篇指南。
+
**Narratage** 这个名字来自 1933 年《*New York Times*》对电影《*The Power and the
Glory*》的一篇影评。那位影评人造出这个词,用来描述当时的一种新兴电影手法:
**Narration + Montage** —— 旁白的声音推动故事前进,同时画面组接出与之呼应的蒙太奇。
@@ -15,15 +34,35 @@ Glory*》的一篇影评。那位影评人造出这个词,用来描述当时
## 安装
-需要 Node.js 22+ 与 pnpm。
+源码工作区需要 Node.js 22+,并通过 Corepack 使用 pnpm 10.33.x。以下命令在 macOS/Linux
+Shell 与 Windows PowerShell 中相同:
+
+部分较新的 Node.js 发行版不再自带 Corepack。如果 `corepack --version` 不可用,先在任一
+Shell 中安装兼容版本:
+
+```text
+npm install --global [email protected]
+```
```bash
corepack enable
+corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm check
pnpm test
```
+本地媒体处理还要求 `ffmpeg` 与 `ffprobe` 位于 `PATH`。Python 是可选依赖:只有 Runtime
+Profile 选择本地 WhisperX 或 OpenCV 时,才需要 Python 3.10–3.13 与
+[`uv`](https://docs.astral.sh/uv/)。在任一 Shell 中按锁定环境准备:
+
+```text
+uv python install 3.13
+uv sync --project services/whisperx --frozen
+uv sync --project services/image-opencv --frozen
+uv run --project services/whisperx --frozen svml-whisperx-prepare
+```
+
在源码仓库内可使用 `node --run narratage -- ...`。仓库外的视频项目直接执行
`/path/to/svml/narratage ... --package-root /path/to/svml`;这个轻量入口不再启动 pnpm,源码、
SQLite、Artifact 和输出仍全部留在外部项目的 Runtime Profile root 下。
@@ -64,6 +103,6 @@ node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
| [SVS 样式表](./quickstart/styles.md) | CSS 风格的 Recipe:film、caption、B-roll、text、speech、字体 |
| [媒体与生成](./quickstart/generation.md) | media:Image、media:Audio、estimate:Speech、Text Template、Seedance |
| [时序与装配](./quickstart/timing.md) | speech:Spine、whisperx:Alignment、ProgramSpace、SemanticMap |
-| [字幕、Media 与文字](./quickstart/tracks.md) | caption-fine:Style/Track、caption:Program、Planner、Media Track 与 Text |
+| [字幕、Media、文字与音频](./quickstart/tracks.md) | Caption、Media、Typography 与 Audio Track 作者语法 |
| [Film 与渲染](./quickstart/composition.md) | film:Film、render:Video、完整流水线演练 |
| [Run Source 与 Build](./quickstart/run.md) | .svrun 语法、targets、复用、runtime profile、build 工作流 |
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
index 1dc8adb3..513a06b6 100644
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@ -192,15 +192,24 @@ Endpoint,不会改变作者图。
只把项目实际选择的 Kit `.svs` 文件复制进视频项目的 `./kits/` 目录,并导入这份项目内
副本,使 Kit 字节保持在 Source Closure 内;项目源码不要反向引用 Narratage 仓库 checkout。
+创作前阅读
+[`@narratage/seedance-kits` 指南](https://github.com/cashdiffusion/svml/blob/main/packages/seedance-kits/README.md)
+和[所选 Kit 源文件](https://github.com/cashdiffusion/svml/tree/main/packages/seedance-kits/kits)。格式匹配时
+优先使用官方 Kit。生成指令与动态 prompt slot 必须使用英语;只有需要逐字说出的对白保留作者
+原语言。七个 Kit 都不适用时,才编写自由格式的英语 prompt。
+
```svml
<import as="text" from="@narratage/text@1"/>
<import as="seedance" from="@narratage/seedance@1"/>
<import as="broll-kit" source="./kits/broll-v1.svs"/>
+<text:Value id="product-story">
+ Show the product opening, the primary feature activating, and the finished result in one readable sequence.
+</text:Value>
<text:Render id="demo-prompt"
template={broll-kit.broll-v1}
recipe={studio.broll.product-demo}>
- <text:Set name="story" text={copy.product-demo}/>
+ <text:Set name="story" text={product-story}/>
</text:Render>
<seedance:ReferenceVideo id="demo" model="mini"
@@ -211,10 +220,20 @@ Endpoint,不会改变作者图。
</seedance:ReferenceVideo>
```
-项目 Recipe 选择模板声明的轴;显式 `text:Param` 可以覆盖 Recipe。动态 story、dialogue、
-action 和 extra 仍经由 `text:Set` 作为图边进入。现有模板包括 `speaker-v1`、`broll-v1`、`podcast-v1`、
-`call-v1`、`street-interview-v1`、`motion-reference-v1`、`camera-reference-v1`。
-媒体数量与顺序仍清楚地写在 `seedance:ReferenceVideo` 里,不藏进 Kit 代码。
+项目 Recipe 选择模板声明的轴;显式 `text:Param` 可以覆盖 Recipe。按格式选择 Kit,再提供它
+声明的动态 slot 与有序参考:
+
+| 格式 | Kit | 动态 slot | 有序参考 |
+|---|---|---|---|
+| 单人口播 | `speaker-v1` | `dialogue`;可选 `action` | image 1 = 人物/场景;audio 1 = 声音 |
+| 无声 B-roll | `broll-v1` | `story` | 一张或多张作者声明图片 |
+| 双人 Podcast | `podcast-v1` | `dialogue`;可选 `action` | image 1/2 = A/B 视角;audio 1/2 = A/B 声音 |
+| 视频通话 | `call-v1` | `dialogue`;可选 `action` | image 1/2 = 相反通话布局;audio 1/2 = A/B 声音 |
+| 街访 | `street-interview-v1` | `dialogue`;可选 `action` | image 1 = 完整场景;audio 1/2 = 采访者/受访者 |
+| 动作迁移 | `motion-reference-v1` | 可选 `direction` | image 1 = 主体;video 1 = 动作参考 |
+| 运镜迁移 | `camera-reference-v1` | 可选 `direction` | image 1 = 主体;video 1 = 运镜参考 |
+
+这些形状仍然清楚地写在 `seedance:ReferenceVideo` 中;Kit 渲染不会隐藏媒体数量与顺序。
## 街访 Prompt 组装
@@ -260,7 +279,7 @@ dialogue/action 由普通 Text 模块组装,结果再像其他生成任务一
<import as="speaker-kit" source="./kits/speaker-v1.svs"/>
<text:Value id="hook-action">
- 先紧迫地直视镜头,最后一句收住声音。
+ Begin with urgent direct eye contact, then let the final admission land more quietly.
</text:Value>
<text:Render id="hook-prompt"
@@ -301,8 +320,8 @@ dialogue/action 由普通 Text 模块组装,结果再像其他生成任务一
source={story.segment.hook.speech} policy={studio.speech.normal}/>
<estimate:Speech id="meeting-duration"
source={story.segment.meeting.speech} policy={studio.speech.normal}/>
-<text:Value id="hook-action">紧迫开场,最后一句放轻。</text:Value>
-<text:Value id="meeting-action">示意产品,然后回到镜头。</text:Value>
+<text:Value id="hook-action">Start urgently, then become quieter.</text:Value>
+<text:Value id="meeting-action">Indicate the product, then return to the lens.</text:Value>
<text:Render id="hook-prompt" template={speaker-kit.speaker-v1} recipe={studio.speaker.host}>
<text:Set name="dialogue" text={story.segment.hook.dialogue}/>
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index adff3956..db9f74aa 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -79,6 +79,9 @@ Run Source(`.svrun`)声明**要构建什么**——需要哪些输出、接
Narratage 没有隐式缓存。复用结果是显式的运行图编写——你将历史 Record 声明为零输入 Candidate,并通过 Satisfaction 边将它们连接起来。
+生成图片或 Take 一经验收,就在下一份 `.svrun` 中用 `build-record` 与 `satisfy` 固定它;
+消费它的 Target 要接受所声明的 fidelity,并在启动付费下游工作前检查冻结 plan。
+
```svml
<?svml using="@narratage/run-markup@1"?>
@@ -174,6 +177,10 @@ Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-0
Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类型的工作:
+声明式 `svml.runtime.json` 是标准形式。高级可信嵌入也可以使用 `svml.runtime.ts`;两种形式
+都通过 `--runtime` 传入,并装配同样显式的角色。完整说明见
+[Runtime Profile 指南](../guide/runtime-profile.md)。
+
```json
{
"format": "svml.runtime-config@1",
@@ -277,17 +284,55 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类
`maxConcurrency` 限制总的并行 Operation 数。Provider 会贡献一个 Authority 资源和一个精确
Capability Route 资源,二者由 Store 原子获取;可选的 `resources` 只按不透明资源 id 覆盖容量。
+## 配置所选凭据
+
+`check` 与 `plan` 不会请求在线 Provider,因此不需要 API key。在运行 `doctor` 或付费/外部
+`build` 之前,只配置当前 Runtime Profile 实际引用的环境变量:
+
+| 变量 | Provider / 用途 |
+|---|---|
+| `KIE_API_KEY` | KIE 模型,包括 Seedance 与 GPT Image |
+| `GOOGLE_CLOUD_PROJECT` | 已启用 Vertex AI 的 Google Cloud project |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON` | 完整的 Vertex 凭据 JSON 内容,而不是文件路径 |
+| `MIMO_API_KEY` | Xiaomi MiMo TTS;只有选择该 Endpoint 时才需要 |
+
+只执行 Profile 中所选 Endpoint 对应的行。在 macOS/Linux Shell 中:
+
+```bash
+read -r -s KIE_API_KEY
+export KIE_API_KEY
+read -r -s MIMO_API_KEY
+export MIMO_API_KEY
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_APPLICATION_CREDENTIALS_JSON="$(<"$HOME/.config/narratage/google-service-account.json")"
+```
+
+在 Windows PowerShell 中:
+
+```powershell
+$env:KIE_API_KEY = "your-key"
+$env:MIMO_API_KEY = "your-key"
+$env:GOOGLE_CLOUD_PROJECT = "your-project-id"
+$env:GOOGLE_APPLICATION_CREDENTIALS_JSON = Get-Content -Raw "$HOME\.config\narratage\google-service-account.json"
+```
+
+不要把凭据写进 Author Source、Run Source、Runtime Profile 源文件或提交内容。`doctor` 会验证
+所需凭据是否存在,但不会打印秘密值。
+
## Build 工作流
+不要提交凭据、生成媒体、Runtime 状态/数据库或日志。
+
### 0. 安装
```bash
pnpm install
```
-这条命令在安装 Node 依赖的同时,也会准备好本地 Build 所需的 Python 服务(WhisperX、OpenCV)。
-如果 `uv` 不在 PATH 中,Python 步骤会跳过并给出提示——需要本地对齐或图像处理时请先安装
-[uv](https://docs.astral.sh/uv/)。
+这条命令只安装 JavaScript 工作区,不会下载 Python 模型,也不会准备仓库内的所有 Provider。
+`runtime up` / `services up` 会读取所选 Runtime Profile,只准备其中 Endpoint 声明的外部程序。
+只有 Profile 选择 WhisperX、OpenCV 等本地 Python 服务时,才需要先安装
+[`uv`](https://docs.astral.sh/uv/);具体锁定环境命令见 Quickstart 首页的[安装](../quickstart.md#安装)。
`narratage runtime up` 管理后台 Worker 和外部程序;`build` 会确保 Runtime 已运行,但不拥有
Worker。
@@ -357,7 +402,22 @@ node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json
Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;
它不启动 Worker,也不发付费请求。
-### 2. 检查计划
+### 2. 启动或复用 Runtime
+
+```bash
+node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime status examples/talking-head-aroll/svml.runtime.json
+```
+
+`runtime up` 负责后台耐久 Worker,以及 Profile 声明的全部外部程序。范围更窄的
+`services up|status|down` 只管理这些外部程序,不负责 Worker 生命周期。
+
+### 3. 检查 Source 与计划
+
+```bash
+node --run narratage -- check examples/talking-head-aroll/main.svml \
+ --runtime examples/talking-head-aroll/svml.runtime.json --root .
+```
```bash
node --run narratage -- plan examples/talking-head-aroll/build.svrun \
@@ -366,7 +426,7 @@ node --run narratage -- plan examples/talking-head-aroll/build.svrun \
在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs。
-### 3. 提交 Build
+### 4. 提交 Build
```bash
node --run narratage -- build examples/talking-head-aroll/build.svrun \
@@ -392,7 +452,15 @@ node --run narratage -- build examples/talking-head-aroll/build.svrun \
继续;已完成、失败或取消的 Build 保持终态,只返回状态。相同 prompt 明确需要另一份随机结果时,
使用新的显式 id。把已有显式 id 用到另一份编译意图上会被拒绝,并同时提示“换 id”或“恢复原 Source”。
-### 4. 获取结果
+### 5. 检查并获取结果
+
+```bash
+node --run narratage -- inspect my-film-001 \
+ --runtime examples/talking-head-aroll/svml.runtime.json
+```
+
+`inspect` 会显示耐久 Build 状态、所需输出与已接受的 Record。确认这些事实正确后,再获取所选
+归档 Artifact:
```bash
node --run narratage -- get my-film-001 \
@@ -407,7 +475,7 @@ Record。Blob Artifact 会从所选 Store 流式读取,逐步校验长度与 S
Build 的最终输出会为每个目标别名打印精确的 `get --name …` 命令,不必为了导出
`final.video` 去查不透明的 Record id。
-### 5. 在新 Build 中复用
+### 6. 在新 Build 中复用
创建一个引用已完成 Build 的 Record 的新 `.svrun` 文件(参见上文[复用结果](#复用结果)),然后提交:
@@ -416,3 +484,13 @@ node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun
--runtime examples/talking-head-aroll/svml.runtime.json \
--build-id my-film-reuse-001 --follow
```
+
+### 7. 诊断或停止本地 Runtime
+
+```bash
+node --run narratage -- runtime logs examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime down examples/talking-head-aroll/svml.runtime.json
+```
+
+`runtime down` 会让 Worker 停止领取新 lease,并停止 Runtime 管理的程序;它不会取消耐久
+Build 或远程 Provider 工作。再次启动同一 Profile 即可恢复本地执行。
diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.md
index b1a93d98..6486f433 100644
--- a/docs/zh/quickstart/timing.md
+++ b/docs/zh/quickstart/timing.md
@@ -60,7 +60,18 @@ Surface 会把这句易读声明展开为普通 Media Pipeline Operation:检
视觉 Take 默认继承 Spine 上显式写出的三个视觉值,也可以逐段覆盖。纯音频 Take 禁止写
视觉覆盖;它播放时 `speech.visual` 就没有 Present,Film 背景或平级 Track 会自然露出,
-系统不会伪造黑场。fit Recipe 只是普通编译期 SVS 数据,例如:
+系统不会伪造黑场。
+
+旁白时序使用 audio Take,画面则由对等 Media Track 提供:
+
+```svml
+<speech:Spine id="speech" frame-rate="30"
+ visual-frame={speech-frame} visual-appearance={studio.speech.visual} visual-z="0">
+ <speech:Take audio={narration.audio} segment={story.segment.narration}/>
+</speech:Spine>
+```
+
+fit Recipe 只是普通编译期 SVS 数据,例如:
```svs
speech.visual { fit: cover; }
@@ -121,6 +132,14 @@ ProgramSpace 包含:
每个在时间域中运行的组件都通过 `space` 属性指向 `{speech.space}`。
+### 无语音节目
+
+无语音影片仍然需要一份显式且已验证的 ProgramSpace。在 Run Source 中用 `build-record` 与
+`satisfy` 选择一份此前已接受的 ProgramSpace Record,再把该具名逻辑输出连接给 Track 与
+Film。Track 使用 `during="program"` 或显式 `start`/`end` 窗口。没有语音就没有实测
+SemanticMap,因此省略 WhisperX 与 Caption 组件,也不要使用 Selection/Moment 时序。Run
+Source 语法见[复用结果](./run.md#复用结果)。
+
## SemanticMap
SemanticMap 是连接 Script 文本与物理时间的类型化桥梁。当你在 Media Item 上写 `during={story.selection.demo}` 时,组件会使用 SemanticMap 查找该 Selection 覆盖的精确帧范围。没有 SemanticMap,Selection 和 Moment 就没有物理意义。
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index d771ea06..f3f55f4d 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -1,15 +1,17 @@
---
-title: 字幕、Media 与 Typography
-description: 视觉 Track 组件——字幕、媒体叠加层和排版叠加层。
+title: 字幕、Media、Typography 与 Audio
+description: 对等 Track 组件——字幕、媒体、排版与作者声明的音频。
---
-# 字幕、Media 与 Typography
+# 字幕、Media、Typography 与 Audio
-> **发布前说明:** Caption Fine、Media Track 与 Typography Track 都执行各自声明的作者 Surface。
+> **发布前说明:** Caption Fine、Media Track、Typography Track 与 Audio Track 都执行各自声明的作者 Surface。
> 它们的作者 API 仍可演进;共享终端 Track/Visual IR 窄腰已在仓库内冻结,但尚未作为
> npm ABI 发布。
-每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套),其 z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍三个官方视觉 Track 包:字幕、Media 和 Typography 叠加层。
+每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套);视觉层的
+z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍 Caption、Media、Typography 与 Audio
+Track 的作者语法。
## 字幕系统
@@ -178,6 +180,41 @@ Operation。需要共享或特殊选流时仍可显式写 `<pipeline:Normalize>`
**输出:**`{product-broll.visual}`;只有作者显式选择了源音频或 SFX 时才会出现
`{product-broll.audio}`。
+## Audio Track
+
+`@narratage/audio-track` 把显式准备好的音频放进与视觉 Track 相同的 ProgramSpace。`Clip`
+消费 `SynchronizedMedia`;先规范化已声明或生成的音频 Blob,再选择精确节目窗口与占用方式:
+
+```svml
+<import as="media" from="@narratage/media@1"/>
+<import as="pipeline" from="@narratage/media-pipeline@1"/>
+<import as="audio" from="@narratage/audio-track@1"/>
+
+<media:Audio id="music" src="./assets/music.wav"/>
+<pipeline:Normalize id="music-media" source={music}
+ video="none" audio="default" span-authority="audio" frame-rate="30"/>
+
+<audio:Track id="music-bed" space={speech.space}>
+ <audio:Clip source={music-media.media} during="program"
+ playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+</audio:Track>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `Track.id` | 是 | 稳定的 Audio Track 身份 |
+| `Track.space` | 是 | 定义精确采样域与帧域的 ProgramSpace |
+| `Clip.source` | 是 | 显式选流并规范化后的 `SynchronizedMedia` |
+| `during`、`at`/`for` 或 `start`/`end` | 三种形式选一 | 全节目、Selection、Moment 或显式窗口 |
+| `map` | Selection/Moment 必填 | 用于解析语义时间的 SemanticMap |
+| `playback` | 否 | `once`、`once-end`、`loop`、`loop-end` 或有界 `stretch` |
+| `occurrences` | 否 | 语义来源有多次出现时选择 `one` 或 `each` |
+| `trim-start`、`trim-end` | 否 | 精确源裁切 |
+| `gain`、`fade-in`、`fade-out` | 否 | 显式的单 Clip 混音值 |
+
+该包不会自动提取、规范化、duck 或分配 bus。同一 Track 内的多个 Clip 与多个对等 Audio
+Track 都会作为独立输入进入 Film。输出 `{music-bed.track}` 是普通 `AudioTrack`。
+
## 文字叠加层
在屏幕上显示的静态或定时文字——标题、标注、下方三分之一字幕条。
@@ -258,15 +295,18 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。
## 组合示例
-三种 Track 类型在一个源文件中协同使用:
+四类 Track 在一个源文件中协同使用:
```svml
<import as="caption" from="@narratage/caption@1"/>
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
<import as="fonts" from="@narratage/fonts-open@1"/>
+<import as="media" from="@narratage/media@1"/>
+<import as="pipeline" from="@narratage/media-pipeline@1"/>
<import as="media-track" from="@narratage/media-track@1"/>
<import as="text" from="@narratage/typography-track@1"/>
+<import as="audio" from="@narratage/audio-track@1"/>
<import as="space" from="@narratage/spatial@1"/>
<!-- Captions: primary style for all text -->
@@ -300,13 +340,23 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。
</text:Area>
</text:Track>
-<!-- All three tracks feed into Film -->
+<!-- Audio:先规范化一份已声明素材,再把它放满整个节目 -->
+<media:Audio id="music" src="./assets/music.wav"/>
+<pipeline:Normalize id="music-media" source={music}
+ video="none" audio="default" span-authority="audio" frame-rate="30"/>
+<audio:Track id="music-bed" space={speech.space}>
+ <audio:Clip source={music-media.media} during="program"
+ playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+</audio:Track>
+
+<!-- 所有对等 Track 都进入 Film -->
<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={cards.visual}/>
<film:Track source={captions.track}/>
<film:Track source={titles.track}/>
+ <film:Track source={music-bed.track}/>
</film:Film>
```