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.

Add Narratage production playbook skill

rponea06d00f1dcc2
diff --git a/.agent/skills/narratage/SKILL.md b/.agent/skills/narratage/SKILL.md
new file mode 100644
index 00000000..ed34b9e1
--- /dev/null
+++ b/.agent/skills/narratage/SKILL.md
@@ -0,0 +1,31 @@
+---
+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.
+---
+
+# Narratage
+
+Use this entrypoint for work in the `svml` repository. Keep `.svml` Author Source, `.svrun` Run
+Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.
+
+## Route the task
+
+- Environment/setup or API keys → read `references/environment.md` and `references/credentials.md`.
+- SVML authoring → read `references/quickstart.md`, then the linked authoritative page under
+ `docs/quickstart/`.
+- Production craft or format choice → read `references/playbooks/index.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.
+- Execution → `check` first, `plan` before paid work, then `build`; inspect and retrieve durable
+ outputs afterward.
+
+## Required loop
+
+```bash
+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 .
+```
+
+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/.agent/skills/narratage/agents/openai.yaml b/.agent/skills/narratage/agents/openai.yaml
new file mode 100644
index 00000000..80697cf9
--- /dev/null
+++ b/.agent/skills/narratage/agents/openai.yaml
@@ -0,0 +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."
diff --git a/.agent/skills/narratage/references/credentials.md b/.agent/skills/narratage/references/credentials.md
new file mode 100644
index 00000000..7c963ad4
--- /dev/null
+++ b/.agent/skills/narratage/references/credentials.md
@@ -0,0 +1,30 @@
+# API keys and credentials
+
+`check` and `plan` do not need live keys. Before paid/external `build`, configure only variables used
+by the selected Runtime Profile:
+
+| Variable | Provider/use |
+|---|---|
+| `KIE_API_KEY` | KIE generation: Seedance, GPT Image, and other selected KIE models |
+| `GOOGLE_CLOUD_PROJECT` | Google Vertex project with Vertex AI enabled |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON` | Vertex credential JSON contents, not a path |
+| `MIMO_API_KEY` | Xiaomi MiMo TTS only when explicitly selected |
+
+macOS/Linux session example:
+
+```bash
+read -r -s KIE_API_KEY; export KIE_API_KEY
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_APPLICATION_CREDENTIALS_JSON="$(<"$HOME/.config/narratage/google-service-account.json")"
+```
+
+Windows PowerShell session example:
+
+```powershell
+$env:KIE_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>`.
diff --git a/.agent/skills/narratage/references/environment.md b/.agent/skills/narratage/references/environment.md
new file mode 100644
index 00000000..48d89708
--- /dev/null
+++ b/.agent/skills/narratage/references/environment.md
@@ -0,0 +1,28 @@
+# Cross-platform environment
+
+Requirements: Node.js 22+, pnpm 10.33.x via Corepack, Python 3.10–3.13 only for local
+WhisperX/OpenCV, `uv` for locked Python environments, and `ffmpeg`/`ffprobe` for local media.
+
+macOS/Linux or Windows PowerShell:
+
+```text
+corepack enable
+corepack prepare [email protected] --activate
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test
+```
+
+For managed local services:
+
+```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
+pnpm narratage services up svml.runtime.json
+pnpm narratage doctor svml.runtime.json
+```
+
+The repository owns skill discovery: `.agent/skills` is canonical, with repository-root
+`.codex/skills` and `.claude/skills` links. This is checkout layout, not a skill setup operation.
diff --git a/.agent/skills/narratage/references/playbooks/craft/b-roll.md b/.agent/skills/narratage/references/playbooks/craft/b-roll.md
new file mode 100644
index 00000000..b85aa472
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/b-roll.md
@@ -0,0 +1,16 @@
+# B-roll craft
+
+- 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 Typography/Media Tracks. Keep product labels and
+ UI text physically attached to the product or screen.
diff --git a/.agent/skills/narratage/references/playbooks/craft/captions.md b/.agent/skills/narratage/references/playbooks/craft/captions.md
new file mode 100644
index 00000000..e7543794
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/captions.md
@@ -0,0 +1,11 @@
+# Caption craft
+
+- Use one Caption Program/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. A 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.
diff --git a/.agent/skills/narratage/references/playbooks/craft/image-prompt-style.md b/.agent/skills/narratage/references/playbooks/craft/image-prompt-style.md
new file mode 100644
index 00000000..dd82522c
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/image-prompt-style.md
@@ -0,0 +1,18 @@
+# Image 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.
+
+## Four-part structure
+
+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.
+
+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.
diff --git a/.agent/skills/narratage/references/playbooks/craft/overlays.md b/.agent/skills/narratage/references/playbooks/craft/overlays.md
new file mode 100644
index 00000000..73090e85
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/overlays.md
@@ -0,0 +1,15 @@
+# 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 inputs and
+ Typography Track 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 spoken-phrase timing using a literal contiguous transcript substring; do not anchor to the
+ final sentence. Without speech, use a scene-relative fraction/manual window, never source-video
+ absolute seconds.
+- Report unsupported effects with a reason. Build an approximation only when the gap stays attached
+ to the authored element; never silently downgrade.
diff --git a/.agent/skills/narratage/references/playbooks/craft/persona-and-audio.md b/.agent/skills/narratage/references/playbooks/craft/persona-and-audio.md
new file mode 100644
index 00000000..afc7a596
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/persona-and-audio.md
@@ -0,0 +1,11 @@
+# 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 contributions. Dialogue wins the mix.
diff --git a/.agent/skills/narratage/references/playbooks/craft/pip-overlay.md b/.agent/skills/narratage/references/playbooks/craft/pip-overlay.md
new file mode 100644
index 00000000..14b3b7b8
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/pip-overlay.md
@@ -0,0 +1,12 @@
+# Picture-in-picture overlay craft
+
+- Decide whether PIP is real photographed video, supplied recording, or a composited subject with
+ transparency. Use the matching explicit Media Track input; 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.
diff --git a/.agent/skills/narratage/references/playbooks/craft/production-gates.md b/.agent/skills/narratage/references/playbooks/craft/production-gates.md
new file mode 100644
index 00000000..32162214
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/production-gates.md
@@ -0,0 +1,18 @@
+# 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 captions, typography, and media overlays on the real base program for safe zones, occlusion,
+ phrase anchors, 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.
diff --git a/.agent/skills/narratage/references/playbooks/craft/screen-demo.md b/.agent/skills/narratage/references/playbooks/craft/screen-demo.md
new file mode 100644
index 00000000..e0f2f442
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/screen-demo.md
@@ -0,0 +1,10 @@
+# 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 Typography 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.
diff --git a/.agent/skills/narratage/references/playbooks/craft/seedance-directing.md b/.agent/skills/narratage/references/playbooks/craft/seedance-directing.md
new file mode 100644
index 00000000..fae62f1b
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/seedance-directing.md
@@ -0,0 +1,14 @@
+# Seedance directing
+
+The motion prompt is an increment over an authored reference frame.
+
+- 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.
+- End every generated-video prompt with the English no-overlay sentence in `reference-vlm.md`.
diff --git a/.agent/skills/narratage/references/playbooks/craft/sfx.md b/.agent/skills/narratage/references/playbooks/craft/sfx.md
new file mode 100644
index 00000000..07041877
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/sfx.md
@@ -0,0 +1,11 @@
+# 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.
+- 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. Check headphones and phone speakers, and listen to
+ the entire program for density rather than approving isolated loops.
diff --git a/.agent/skills/narratage/references/playbooks/craft/visual-continuity.md b/.agent/skills/narratage/references/playbooks/craft/visual-continuity.md
new file mode 100644
index 00000000..45d3d1fe
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/craft/visual-continuity.md
@@ -0,0 +1,15 @@
+# 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.
diff --git a/.agent/skills/narratage/references/playbooks/formats/asmr.md b/.agent/skills/narratage/references/playbooks/formats/asmr.md
new file mode 100644
index 00000000..2a1074e1
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/asmr.md
@@ -0,0 +1,14 @@
+# ASMR format
+
+Evidence level: thin.
+
+- 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 tracks
+ 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.
diff --git a/.agent/skills/narratage/references/playbooks/formats/mass-tarot.md b/.agent/skills/narratage/references/playbooks/formats/mass-tarot.md
new file mode 100644
index 00000000..cfd8d437
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/mass-tarot.md
@@ -0,0 +1,15 @@
+# Mass-tarot pick-a-card format
+
+Evidence level: thin.
+
+- 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; author narration and all editorial text separately. Numbers,
+ questions, and interpretation lines belong in Typography/Caption Tracks 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 operator before production; do not fabricate certainty.
diff --git a/.agent/skills/narratage/references/playbooks/formats/mixcut.md b/.agent/skills/narratage/references/playbooks/formats/mixcut.md
new file mode 100644
index 00000000..2b8f719c
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/mixcut.md
@@ -0,0 +1,11 @@
+# Silent visual mixcut format
+
+- 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 concatenate deliberately.
+- Without speech, use fixed scene-relative windows for titles, benefits, and CTA. Lock effective
+ duration before laying out overlays; changing a clip duration requires updating all windows.
+- 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 Typography Track for editorial copy.
diff --git a/.agent/skills/narratage/references/playbooks/formats/ranking-listicle.md b/.agent/skills/narratage/references/playbooks/formats/ranking-listicle.md
new file mode 100644
index 00000000..159d1f12
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/ranking-listicle.md
@@ -0,0 +1,13 @@
+# Ranking-listicle format
+
+Evidence level: partial.
+
+- Use one ranking/deck presentation system 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.
diff --git a/.agent/skills/narratage/references/playbooks/formats/scenario-call.md b/.agent/skills/narratage/references/playbooks/formats/scenario-call.md
new file mode 100644
index 00000000..475475f8
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/scenario-call.md
@@ -0,0 +1,14 @@
+# Scenario-call format
+
+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/Track. Put call labels, notifications, and editorial copy in explicit
+ Typography/Media Tracks; Seedance must not generate them.
+- Validate layout, speaker/voice assignment, reaction timing, and continuity with provider-free/mock
+ media before a paid call generation.
diff --git a/.agent/skills/narratage/references/playbooks/formats/street-interview.md b/.agent/skills/narratage/references/playbooks/formats/street-interview.md
new file mode 100644
index 00000000..7c8844e0
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/street-interview.md
@@ -0,0 +1,13 @@
+# Street-interview format
+
+- 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.
+- 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 when captions are wanted. Overlay phrase anchors must be literal transcript
+ substrings and should not target the final sentence.
diff --git a/.agent/skills/narratage/references/playbooks/formats/talking-head.md b/.agent/skills/narratage/references/playbooks/formats/talking-head.md
new file mode 100644
index 00000000..f728fcc8
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/talking-head.md
@@ -0,0 +1,12 @@
+# 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 `seedance:ReferenceVideo` for face/image/audio references; use `seedance:TextVideo` without an
+ identity reference. Keep dialogue and action as separate text inputs.
+- Build one Speech Spine and one WhisperX Alignment. Add one Caption Track only when requested; add
+ B-roll through Media Track and editorial titles through Typography Track.
+- Review A-roll and B-roll independently, then validate the joined Film. Reuse accepted shots
+ explicitly in a later Run Source.
diff --git a/.agent/skills/narratage/references/playbooks/formats/two-person-podcast.md b/.agent/skills/narratage/references/playbooks/formats/two-person-podcast.md
new file mode 100644
index 00000000..29aba399
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/two-person-podcast.md
@@ -0,0 +1,12 @@
+# Two-person podcast format
+
+- 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.
+- 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 Track, and Typography/Media Tracks 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.
diff --git a/.agent/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md b/.agent/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md
new file mode 100644
index 00000000..efa9d107
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/formats/voiceover-desk-demo.md
@@ -0,0 +1,11 @@
+# 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 visuals. Because the base is
+ silent, do not rely on speech phrase anchors or captions unless a separately measured speech base
+ exists; use program/full/manual windows.
+- Treat UI, labels, receipts, and website text as provided physical screen content. Add editorial
+ explanations as Typography Track, never floating generator text.
diff --git a/.agent/skills/narratage/references/playbooks/index.md b/.agent/skills/narratage/references/playbooks/index.md
new file mode 100644
index 00000000..646cb116
--- /dev/null
+++ b/.agent/skills/narratage/references/playbooks/index.md
@@ -0,0 +1,49 @@
+# Narratage production playbooks
+
+Portable production patterns extracted from `twinit/playbooks` and rewritten for Narratage. These
+files describe what to author and inspect, not twinit canvas nodes or JSON contracts.
+
+## Decision path
+
+1. Identify the format: talking head, street interview, two-person podcast, voiceover desk demo, or
+ silent mixcut.
+2. 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. Map the result to Script, Seedance, Speech Spine, SemanticMap, peer Tracks, Film, and Run Source.
+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, Typography, or Media Tracks.
+
+## 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.
+
+## 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`
diff --git a/.agent/skills/narratage/references/quickstart.md b/.agent/skills/narratage/references/quickstart.md
new file mode 100644
index 00000000..e697eacc
--- /dev/null
+++ b/.agent/skills/narratage/references/quickstart.md
@@ -0,0 +1,20 @@
+# Quickstart map
+
+The repository docs are authoritative:
+
+| Need | Read |
+|---|---|
+| Script semantics | `docs/quickstart/script.md` |
+| SVS Recipes | `docs/quickstart/styles.md` |
+| Media and Seedance | `docs/quickstart/generation.md` |
+| Speech Spine and SemanticMap | `docs/quickstart/timing.md` |
+| Caption, Media, Typography Tracks | `docs/quickstart/tracks.md` |
+| Film and rendering | `docs/quickstart/composition.md` |
+| Run Source and Runtime | `docs/quickstart/run.md` |
+
+Canonical path:
+
+`Script → Estimate/Seedance → Speech Spine → WhisperX SemanticMap → peer Caption/Media/Text/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`.
diff --git a/.agent/skills/narratage/references/reference-vlm.md b/.agent/skills/narratage/references/reference-vlm.md
new file mode 100644
index 00000000..9f3ba1cf
--- /dev/null
+++ b/.agent/skills/narratage/references/reference-vlm.md
@@ -0,0 +1,22 @@
+# 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 all VLM instructions and generated image/video prompts in English. Preserve original language
+ only for verbatim dialogue/transcript/sample lines.
+- Analyze active video clips, not stills alone. Split on RGB content distance, keep clips at or below
+ 15 seconds, and share one reference across continuous parts.
+- Keep photographed base and editorial overlays complementary. Treat exact UI/screenshots/charts as
+ provided media; generated live-action PIP/B-roll may be real generated media.
+- Anchor recurring people/products/locations at the clearest shot and reuse references topologically.
+- Listen to audio for voice design. Transcribe speech, not burned-in captions.
+- Map transcript to Script; generated media to Seedance; supplied assets to Media; timing to Speech
+ Spine/WhisperX; overlays to Caption/Media/Typography; then Film/Render and a final-video Run Target.
+
+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.`
+
+Every generated motion prompt ends with:
+
+`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/.agent/skills/narratage/scripts/check-credentials.mjs b/.agent/skills/narratage/scripts/check-credentials.mjs
new file mode 100755
index 00000000..b7309ec5
--- /dev/null
+++ b/.agent/skills/narratage/scripts/check-credentials.mjs
@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import process from "node:process";
+const names = process.argv.slice(2);
+if (names.length === 0) { console.error("Usage: node check-credentials.mjs NAME [...NAME]"); process.exitCode = 2; }
+for (const name of names) console.log(`${name}\t${process.env[name]?.trim() ? "set" : "missing"}`);
diff --git a/.agent/skills/narratage/scripts/check-environment.mjs b/.agent/skills/narratage/scripts/check-environment.mjs
new file mode 100755
index 00000000..c72c5f4d
--- /dev/null
+++ b/.agent/skills/narratage/scripts/check-environment.mjs
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+for (const command of ["node", "pnpm", "corepack", "ffmpeg", "ffprobe", "uv"]) {
+ try {
+ const version = execFileSync(command, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().split(/\r?\n/, 1)[0];
+ console.log(`${command}\tok\t${version}`);
+ } catch { console.log(`${command}\tmissing`); }
+}
+console.log(`platform\t${process.platform}\t${process.arch}`);