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(skill): establish coarse-fine reference rooms

kashorind999ad8fffae
diff --git a/skills/hypit/references/creation/brief.md b/skills/hypit/references/creation/brief.md
new file mode 100644
index 00000000..685598a4
--- /dev/null
+++ b/skills/hypit/references/creation/brief.md
@@ -0,0 +1,77 @@
+# Brief and Treatment
+
+Read this whenever a target video is being defined, whether it begins from a reference, a loose idea,
+an existing project, or a requested revision.
+
+## Brief preserves user authority
+
+`BRIEF.md` records what the user wants and what only the user can authoritatively supply. It can be as
+short as one sentence when that sentence is sufficient:
+
+> Faithfully recreate this reference, but replace the presenter with the cat in `assets/miso.jpg` and
+> the product with Hypit.
+
+Add only facts that matter to the work, such as:
+
+- the intended outcome, audience, platform, deliverable, or business purpose;
+- the claim, product truth, offer, CTA, language, and facts that must remain accurate;
+- references and what the user wants inherited from each;
+- requested replacements, additions, removals, or style changes;
+- private identity assets and exact brand material;
+- hard duration, format, budget, or delivery constraints;
+- choices the user explicitly reserves for themselves.
+
+Quote or closely preserve the user's wording where reinterpretation could change the request. Do not
+expand an example video's Hook into a format rule or mix implementation choices into the Brief.
+
+In a faithful adaptation, unmentioned relationships normally inherit from the reference: structure,
+the role of each layer, the promise/payoff relationship, and the visual or audio systems that make the
+piece work. This is a starting interpretation, not pixel copying. Ask the user only when the available
+facts leave materially different goals, private facts, meaningful value choices, deliverables, or
+spending authority unresolved. Routine casting, art direction, shot choice, Caption treatment,
+component design, prompts, and implementation belong to the Agent.
+
+## Treatment is the director's answer
+
+`TREATMENT.md` turns the Brief, relevant reference understanding, and current creative judgment into
+one complete creative design for the new work. It can cover:
+
+- the creative premise and viewer experience;
+- story movement, Hook, reveal, payoff, and CTA;
+- target pacing and the jobs of major passages;
+- character, performance, camera, locations, and visual world;
+- A-roll, B-roll, Caption, Typography, MG, Effect, and Audio systems that the target actually needs;
+- how requested transformations propagate through those systems;
+- which generated or supplied media will act as identity and continuity anchors;
+- open creative questions that genuinely prevent the design from becoming specific.
+
+Write in director language. The Treatment may say that a ranking portrait accumulates into a board or
+that a second podcast angle reverses the eye line while preserving the shared counter and light. It
+does not need package names, element attributes, provider selection, Build order, or Result ids. Those
+belong to production files.
+
+Reference Analysis says why the old piece works; Treatment says what the new piece will be. Original
+work reaches Treatment from the Brief, relevant examples, and the Agent's judgment rather than from
+one dominant reference. These are different sources of creative evidence.
+
+## Keep one formal Script
+
+The spoken wording becomes authoritative only in the Author Source's `<script>`. During drafting, copy
+may live in `drafts/`; once adopted, move it into Source and stop maintaining a second full transcript
+in Brief or Treatment. Brief can preserve mandatory claims or exact user-supplied phrases. Treatment
+can describe what each passage must accomplish. Source owns the actual words, roles, Cue breaks,
+Selections, and Moments.
+
+## Revise the owner of the changed fact
+
+- A changed user goal, claim, constraint, or requested substitution changes the Brief.
+- A changed story, shot logic, visual system, performance, or creative approach changes the Treatment.
+- A prompt refinement, component geometry correction, Candidate choice, or timing-expression fix that
+ preserves the same design changes Source, Recipe, Run, a project package, or generation input—not
+ the Treatment.
+- New evidence about the reference changes its Analysis or Timeline; it may then cause the director to
+ reconsider Treatment.
+
+Studio and built Results participate in this loop. If the work looks wrong because the design itself
+was wrong, revise Treatment. If the design is sound and its implementation is wrong, repair the
+production. Brief changes only when the user's truth changes.
diff --git a/skills/hypit/references/creation/project-files.md b/skills/hypit/references/creation/project-files.md
new file mode 100644
index 00000000..f8d948df
--- /dev/null
+++ b/skills/hypit/references/creation/project-files.md
@@ -0,0 +1,95 @@
+# Project files
+
+Read this when starting, resuming, or reorganizing a video project. The layout below is a working
+convention, not syntax: Hypit resolves ordinary paths and does not assign meaning to these directory
+names.
+
+## Keep reference truth and target truth separate
+
+A reference archive says what an existing piece does. A production says what the new piece should do
+and contains the files that make it. One reference can inform several productions, and one production
+can draw from several references; ordinary relative links express those relationships without a
+central project index.
+
+```text
+project/
+├── references/
+│ └── <reference>/
+│ ├── source.*
+│ ├── ANALYSIS.md
+│ ├── TIMELINE.md
+│ ├── transcript.json
+│ ├── evidence/
+│ ├── PROGRESS.md # only while understanding is in progress
+│ └── drafts/ # optional observation experiments
+├── productions/
+│ └── <target>/
+│ ├── BRIEF.md
+│ ├── TREATMENT.md
+│ ├── PROGRESS.md
+│ ├── authors/
+│ ├── recipes/
+│ ├── runs/
+│ ├── assets/
+│ └── drafts/
+├── assets/ # inputs shared by several targets
+├── packages/ # project Author Packages shared by targets
+├── hypit.runtime.json
+└── package.json
+```
+
+A target may have several Author Sources, Recipe Sources, and Runs. Re-running one Run creates another
+Build, not another target. Keep files for one target together so their relationship is readable from
+the filesystem rather than inferred from matching names elsewhere in the project.
+
+For example, one understood reference can support two distinct target works without being copied:
+
+```text
+references/darby/
+productions/darby-hypit/
+productions/darby-hypit-short/
+```
+
+Each production links to `../../references/darby/` from its own Brief or Treatment and keeps its own
+Sources and Runs.
+
+The CLI finds the project from the nearest `package.json`; Source and Run files may live in any
+subdirectory inside it. Shared assets and packages can stay at project root. Target-specific assets
+stay with that target. A reference file that is also intentionally used in the new film can be
+referenced in place; its documentary role does not require a duplicate.
+
+## Give each document one job
+
+- `ANALYSIS.md` is the current whole-piece understanding of a reference: form, story, recurring
+ systems, relationships, function, and why the work holds together.
+- `TIMELINE.md` says what happens when in the reference, including concurrent picture, speech,
+ Caption, Typography, MG, Effect, and Audio behavior.
+- `transcript.json` is word-level speech evidence. It is evidence, not the director's interpretation.
+- `evidence/` contains only media worth reopening, with ordinary human-readable names.
+- `BRIEF.md` preserves the user's goal, facts, constraints, and requested changes.
+- `TREATMENT.md` is the director's current answer to the Brief: the intended new piece in complete
+ creative terms, before implementation details.
+- `authors/`, `recipes/`, and `runs/` are the exact production implementation.
+- `PROGRESS.md` is a short photograph of the work now: the live question, next useful action, real
+ blockers, and reusable Results. Established conclusions belong in their owning document instead.
+
+Rewrite these files when the current truth changes. They are not logs. `PROGRESS.md` may exist beside
+a reference or a production because either kind of work can span conversations; it does not mark a
+stage and can disappear when there is nothing useful to hand over.
+
+## Drafts and Results are different things
+
+`drafts/` holds unpublished authoring material that is not part of the current Source: trial copy,
+temporary designs, or media deliberately exported for further work. A Build output remains in that
+Build's Result even if a later Run does not use it. The absence of a later reference already says it
+was not adopted; it does not need to be copied into `drafts/`.
+
+When an output is deliberately exported into the project, place it according to its new role. It may
+become an `asset`, a `draft`, or direct input to another production.
+
+## Resume from present facts
+
+After interruption or context compaction, read the current Brief, Treatment, reference archive,
+Source, Recipe, Run, and the short `PROGRESS.md` that applies. Then inspect the project's actual Build
+Results and Runtime status. Continue from usable outputs already present; loss of conversation context
+is not a reason to submit the same paid work again.
diff --git a/skills/hypit/references/creation/reference-video.md b/skills/hypit/references/creation/reference-video.md
new file mode 100644
index 00000000..1b29a558
--- /dev/null
+++ b/skills/hypit/references/creation/reference-video.md
@@ -0,0 +1,113 @@
+# Understanding a reference video
+
+Read this when a video or link is evidence for what the new work should preserve, adapt, or learn
+from.
+
+## Direct the investigation
+
+The Agent is the mind and director. Use visual observation as eyes, transcription and alignment as
+ears, and local media commands to prepare a closer view. The tools report evidence; the Agent connects
+events across time, resolves contradictions, explains why they matter, and decides what to inspect
+next.
+
+Begin by watching the whole piece and reading its word-level transcript. Form a provisional account
+of:
+
+- the Hook, story movement, payoff, and intended viewer response;
+- who speaks, whether speech is on camera or voice-over, and the roles of A-roll and B-roll;
+- the persistent and recurring Caption, Typography, MG, Effect, and Audio systems;
+- changes, accumulations, replacements, reveals, cover relationships, and callbacks;
+- the few relationships that make the piece recognizably itself.
+
+Then spend detail attention where an answer can change the production. A ranking board that already
+contains players while a new portrait appears nearby raises a structural question: whether the new
+portrait enters, replaces, or accumulates on the board. That matters before the exact direction of an
+incidental slide. Coarse understanding tells you what deserves a close look; close evidence is allowed
+to overturn the coarse understanding.
+
+## Choose evidence for the question
+
+Use `hypit transcribe` for speech and word time. Use `hypit observe` when motion, sound, sequence, or
+whole-piece visual context matters. The local `hypit media` family prepares views without interpreting
+them:
+
+- `probe` reports media facts;
+- `cut` isolates a short temporal question;
+- `frames` exposes exact moments or small details;
+- `tile` and `tiles` show change across a span with visible time labels;
+- `boundaries` offers possible visual-change locations for navigation;
+- `fetch` turns a supported link into a local source file.
+
+No evidence form is a substitute for every other one. A still cannot establish movement or sound. A
+single representative frame cannot establish entry, exit, replacement, or persistence. A long video
+pass can lose small text and rapid order. A tile shows sampled order but may miss what happens between
+cells. When motion direction or a transition is important, inspect a short clip or denser adjacent
+frames. When text or geometry is important, inspect full-resolution frames. Keep an unsupported claim
+unknown instead of completing the prose by imagination.
+
+Visual reports can be wrong even when fluently written, especially about changes over time, small UI,
+rapid cuts, and which neighboring shot owns a detail. Compare the report with the transcript and the
+actual media. Ask one narrower question over one relevant span when the answer would change the work.
+Platform watermarks and player chrome are viewing context unless the video itself demonstrates that
+the author designed them.
+
+For Caption systems, sample every meaningfully different configuration: speakers with different
+colors or positions, normal and emphasized states, different regions, or different motion. Repeated
+uses of one configuration do not need separate style investigations. A fixed quota of frames cannot
+prove that all configurations were seen.
+
+## Write two complementary reference documents
+
+`ANALYSIS.md` carries the whole-piece model. Write what kind of work it is, its story and pacing, what
+each layer contributes, which systems persist or recur, how distant moments relate, and why the piece
+works. Distinguish visible or audible facts from the Agent's reading in ordinary prose.
+
+`TIMELINE.md` carries locatable behavior. Organize it with loose second-level sections named by an
+original-media time range and a human-readable content phase:
+
+```md
+## 6.07–8.27 · Pain-point list accelerates
+
+Speech: the list reaches “videos / voiceovers / ads / scripts”. WhisperX places each word in this
+span.
+
+Picture: each item uses a new B-roll shot. Tile 003 shows the cuts clustered around the spoken list.
+
+Caption: a marker-style word appears with each listed item; the lower spoken Caption is absent here.
+
+Reading: the one-item/one-picture rhythm makes the workload feel excessive.
+```
+
+These sections are navigation, not mutually exclusive rows. They may overlap, leave an unresolved
+gap, or contain smaller timed notes where density warrants it. Within a section, describe every layer
+that is actually active together. A title, music bed, Caption style, or MG object may continue across
+several sections; say that it continues rather than pretending the document boundary reset it.
+
+Use open production vocabulary—A-roll, B-roll, Speech, Voice-over, Silence, Caption, Typography,
+Text Track, MG, UI, Effect, Audio—and introduce a clearer term when a work needs one. Caption is the
+spoken display system: words, Cues, speaker or role, activation, placement, and style. Typography is
+independent visual writing such as a title, label, step, or poster text. UI and MG may contain text of
+their own. Classify by function instead of collapsing everything visible into a generic text track.
+
+Every observation sentence should identify its material in natural language: “tile 004 shows…”, “the
+0:12.4 frame shows…”, “the 0:12–0:14 clip shows…”, or “the WhisperX transcript gives…”. Several
+materials may support one conclusion. When a fact remains unsettled, name the question that would
+change the work.
+
+## Preserve time without turning it into target code
+
+Reference time establishes order, overlap, duration, and relation to spoken words. Record both the
+original seconds and the meaningful relation: a picture illustrates the word `videos`, a reveal lands
+after a pause, a Caption Cue spans a phrase, or an effect continues through a cut. Word-level evidence
+is essential because it lets the director identify what an event means. Read `script-and-time.md` when
+turning those observed relationships into the target's Script identities and timing.
+
+## Keep the archive complete and revisable
+
+“Complete” means another Agent can recover every important element, when and how it appears, which
+system it belongs to, what it relates to, what role it plays, and why those relationships matter. It
+rests on accurate temporal and stylistic evidence without becoming a frame-by-frame transcription.
+
+Store only evidence worth reopening. Update Analysis and Timeline in place when new evidence changes
+the account. Put the current unresolved question and next useful observation in the reference's
+`PROGRESS.md`. Understanding the reference does not create the user's Brief.
diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.md
new file mode 100644
index 00000000..0788ce8f
--- /dev/null
+++ b/skills/hypit/references/creation/script-and-time.md
@@ -0,0 +1,97 @@
+# Script and semantic time
+
+Read this when writing the target's words, balancing delivery across generated Takes, or attaching
+pictures, Captions, MG, Effects, and Audio to what is said. For exact grammar and component attributes,
+use the selected Distribution's Script, Timing, and Track documentation and the owning package READMEs.
+
+## Script is the target's sole verbal authority
+
+`<script>` contains the words the target video will say. It contains no reference timecodes, media,
+styling, prompts, or provider decisions. Brief may preserve required claims and Treatment may describe
+the purpose of a passage, but the adopted wording appears in Source only once.
+
+Use Script's distinct authoring concepts for distinct jobs:
+
+- a **Segment** is a named structural passage whose accepted media can become one SemanticTake;
+- a **Role Cue** says who speaks a turn without creating a character or choosing a voice;
+- **Dual Text** gives one authored unit separate display and pronunciation text;
+- `||` places an authored **Caption Cue Break** between complete Alignment Units;
+- a **Selection** names a semantic range;
+- a **Moment** names a semantic point.
+
+```svml
+<script id="story">
+ <hook>
+ <HOST> I made @proof this tiny product || work overnight @/proof.
+ </hook>
+</script>
+```
+
+Here `||` authors two reading Cues while `proof` remains one semantic range that other layers can use.
+
+Choose Segment boundaries from speech and production continuity, not from every picture cut. One
+continuous narration can carry many B-roll changes through Selections. When the actual speaking Take
+must change, when a speaker or delivery boundary is intentional, or when a model limit requires a
+seam, make the seam deliberate and place it where the performance can sustain it.
+
+## Author Caption rhythm, not a word-count rule
+
+Caption Cues express how the viewer should read the displayed speech. Break them at natural phrase,
+emphasis, speaker, layout, and motion boundaries. A large display or rapid word-by-word system may
+need very small Cues; a restrained lower Caption may hold a longer phrase. Inspect the actual style and
+canvas.
+
+Keep `||` between complete Alignment Units; it cannot split Dual Text. Script emits one
+`CaptionDocument` containing display words, alignment units, attributes, and authored Cue breaks but
+no seconds or frames. Caption packages later join that document to actual semantic timing. Independent
+titles, labels, steps, and poster text normally belong to Typography, Text Track, UI, or MG rather than
+being forced into spoken Caption Cues.
+
+## Measure before choosing durations
+
+Generated Takes require a literal `duration`, so measure the adopted wording before choosing that
+number. `hypit measure` counts a Segment's pronunciation units and reports how many seconds they need
+at an author-chosen pace or numeric rate:
+
+```bash
+hypit measure path/to/source.svml --segment opening --language en --pace normal
+hypit measure path/to/source.svml --segment proof --language en --pace normal
+```
+
+Its immediate use is to give each request a sensible media length. Its deeper use is to keep related
+Takes inside one performance: measure them with the same delivery policy and compare the results, so
+their pronunciation units receive compatible amounts of time. A denser Segment needs more time at
+the same pace; a Segment forced into a short model window may need a faster intended delivery, tighter
+copy, or a deliberate split. Use the desired pauses, action, edit, model range, and rounding to choose
+the final literals. If the wording or delivery changes, measure the affected Segments again.
+
+Measurement balances the intended speaking density and sizes generation; it supplies no timeline
+anchors. Once a Take is accepted, normalize it, align its actual speech to its Script Segment, and
+assemble the resulting SemanticTakes into the SemanticTrack. The literal duration answers how much
+media to request. The aligned words answer where Caption, B-roll, MG, and Effects belong in that actual
+media. Alignment measures real word positions inside that media envelope; it does not reproduce an
+estimated distribution of words.
+
+## Bind meaning to Script identities
+
+For a picture, Caption treatment, MG state, sound, or effect that belongs to spoken meaning, author a
+Selection or Moment and let the consuming Track project it through the SemanticTrack. Use explicit
+seconds for genuinely clock-based or speechless design.
+
+Selections may overlap or cross. Default markers are already exact: `@videos videos @/videos` opens
+at the word's start and closes at that same word's end. Script also offers explicit left/right affinity
+when the design intentionally includes an adjacent gap or structural boundary. Read the selected
+Distribution's `docs/quickstart/script.md` for the current marker spellings.
+
+Reference archives keep original seconds and explain which original words or content events an item
+serves. The target Source names the intended relation against the target Script. After the target's
+actual audio is aligned, the SemanticTrack supplies its frames. Do not copy a reference timestamp into
+the target or preserve an incidental lead/lag unless that offset itself is part of the design.
+
+## Let the creation and production loops meet honestly
+
+Timing seen in Studio or a real Result may expose one of several different problems. A wrong Cue or
+semantic anchor changes Script. A sound performance that changes the intended rhythm may change the
+duration choice or Treatment. A correct Selection rendered badly changes the component or Recipe. An
+unusable generated Take changes its prompt, reference, Candidate, or shot design. Put each correction
+where its fact is owned.
diff --git a/skills/hypit/references/creation/transformations.md b/skills/hypit/references/creation/transformations.md
new file mode 100644
index 00000000..8ce358a8
--- /dev/null
+++ b/skills/hypit/references/creation/transformations.md
@@ -0,0 +1,89 @@
+# Transforming a reference into a target
+
+Read this when a request changes, combines, shortens, restyles, or extends reference material. Several
+transformations usually apply at once, and unfamiliar work can introduce a new one in plain language.
+
+## Preserve the role, then recreate the form
+
+Before replacing an object, understand the role it plays in the work. A presenter may also appear as
+an avatar, a voice, a B-roll subject, a phone image, and the identity inside an MG system. A product
+may be a prop, a screen, a demonstration, a claim, and the final CTA. Transform the role across every
+real manifestation; do not stop after changing its most obvious pixels.
+
+The target need not copy a form that no longer fits. Preserve the purpose of an action, composition,
+or callback while directing a form that makes sense for the new body, product, platform, and viewer.
+A cat can perform confidence through a planted pose, gaze, tail, or framing without literally copying
+a human hand gesture. A product with no screen can demonstrate the same benefit through a different
+piece of evidence.
+
+Useful transformation lenses include:
+
+- **subject or identity** — who carries the narrative role and everywhere that identity appears;
+- **product or brand** — product truth, use, props, UI, logos, colors, proof, offer, and CTA;
+- **Script, language, or CTA** — meaning, speech rhythm, on-screen wording, demonstrations, and the
+ timing relationships that follow the new words;
+- **platform, duration, or aspect** — which story functions survive, compress, expand, or need a new
+ composition;
+- **visual or tonal style** — art direction across generated shots, Caption, Typography, MG, Effect,
+ and Audio, without erasing the reference's useful structure;
+- **adding or removing a system** — redistribute the job formerly done by that system rather than
+ leaving a narrative hole;
+- **multiple references** — state which function comes from each reference and resolve conflicts in
+ Treatment instead of blending every surface detail.
+
+These lenses are prompts for thought, not fields to complete. Follow the relationships the actual work
+contains.
+
+## Example: replace the presenter with a supplied cat
+
+Suppose the user supplies a video, `assets/miso.jpg`, and says, “replace the person with this cat.”
+
+The reference archive records the original work without the cat. The Brief records the faithful
+adaptation and the cat image as the user's private identity authority. The Agent identifies what the
+presenter does throughout the piece: speaking A-roll, lifestyle B-roll, voice, Caption ownership,
+avatar, product interaction, screen image, or MG state. Treatment decides how the cat performs those
+same functions and which systems actually need to change.
+
+The cat image can directly condition the first real A-roll camera image. Once accepted, that camera
+image is both usable artwork and a strong visual precedent for other real angles and Takes. It is
+enough to start; the next shots can grow from it together with any product or Logo authority they
+need.
+
+If “real pet behaving naturally” and “fully anthropomorphic host” would produce materially different
+works and the supplied evidence does not favor either, ask once. Otherwise the commissioned Agent
+makes the routine directing choice and validates it by looking at the generated work.
+
+## Treat generation as ordinary production
+
+Think of the image model as a broadly informed painter, the video model as a broadly informed camera
+crew and performer, and audio generation as a broadly informed sound team. “Real” is an aesthetic
+direction—iPhone capture, natural light, documentary movement, room tone—not a claim about where the
+asset came from. The normal task is to create the target media.
+
+External references become essential when public world knowledge cannot determine exact identity:
+the user, a private or obscure product, a proprietary interface, an exact Logo or data display. An
+accepted generated image, Take, or sound can then become authority for later work.
+
+Prefer reference-conditioned video generation when identity, art direction, composition, or product
+continuity matters. The input guides the shot without having to appear as its literal first or last
+frame. Use keyframe-constrained generation when the endpoint image itself is part of the designed
+continuous change. Use text-only generation when the shot benefits from variation and needs no exact
+visual anchor. These are control meanings; package and Provider support remains owned by their public
+documentation.
+
+## Keep media dependencies shallow and useful
+
+Generate actual work: the main A-roll camera image, the reverse angle, a B-roll image, a product close
+up, or a component slot. The first accepted presenter image will often already be the main A-roll
+camera image. Another A-roll view can be generated from it by describing the new camera relationship,
+eye line, recurring objects, light, and what naturally changes when the camera faces the other way.
+The shared world lives in the relationship between useful shots, not in an abstract scene plate.
+
+An independent identity asset or location image is useful when the work itself needs it independently.
+Otherwise, avoid chains of intermediate pictures that exist only to feed the next generation. For a
+single shot split by a model's duration limit, reuse the same accepted visual authorities for each
+part unless the cut itself is designed around a literal boundary frame.
+
+Studio and real Results close the decision loop. Adopt a generated item by using it in a later Run,
+Source, or request. If it fails the intended role, change the prompt, reference relation, shot design,
+or Treatment according to what is actually wrong.
diff --git a/skills/hypit/references/credentials.md b/skills/hypit/references/credentials.md
index 3448e942..dc8e31f4 100644
--- a/skills/hypit/references/credentials.md
+++ b/skills/hypit/references/credentials.md
@@ -12,7 +12,7 @@ variables used by the selected Runtime Profile:
| `GOOGLE_CLOUD_PROJECT` | Google Vertex project with Vertex AI enabled |
| `GOOGLE_APPLICATION_CREDENTIALS_JSON` | Vertex credential JSON contents, not a path |
| HypiHub OAuth login | HypiHub default paid provider for generation and Gemini VLM; run `hypit auth login hypihub.default --runtime hypit.runtime.json` and sign in at [hypit.ai](https://hypit.ai) |
-| `MIMO_API_KEY` | Xiaomi MiMo VoiceDesign only when the user explicitly selects the official Provider |
+| `MIMO_API_KEY` | Xiaomi MiMo Voice Design or Voice Clone when the user explicitly selects the official Provider |
Before any paid Build, report the selected Provider and credential source for every paid capability in
the Runtime Profile. Say the variable/store and endpoint (for example, `@hypit/provider-kie` using
diff --git a/skills/hypit/references/environment/local-tools.md b/skills/hypit/references/environment/local-tools.md
new file mode 100644
index 00000000..7eac452b
--- /dev/null
+++ b/skills/hypit/references/environment/local-tools.md
@@ -0,0 +1,128 @@
+# Local tools and Managed Programs
+
+Read this when the selected Profile uses local media, HyperFrames, WhisperX, OpenCV, or another local
+Endpoint and its executable or Managed Program is unavailable.
+
+## Diagnose the selected local capability
+
+Begin with the current project and Profile:
+
+```bash
+hypit paths
+hypit runtime status
+hypit runtime logs
+hypit programs status
+hypit doctor
+```
+
+The Skill also ships a small host probe:
+
+```bash
+node <skill-root>/scripts/check-environment.mjs
+```
+
+Read the failing Endpoint's message and package README before changing the machine. The Profile says
+which local implementation was selected; another project's working service is not evidence that this
+Profile selects it.
+
+## Supply host executables at machine scope
+
+The installed Hypit Distribution requires its supported Node.js version. Local media processing needs
+both `ffmpeg` and `ffprobe` on `PATH`, or explicit compatible paths accepted by its Provider. Local
+Python Programs use `uv` to create their locked environments in Hypit's machine Program Home.
+
+Use the host's ordinary package manager, then verify the executables in a new shell:
+
+```bash
+# macOS
+brew install ffmpeg uv
+ffmpeg -version
+ffprobe -version
+uv --version
+```
+
+```powershell
+# Windows
+winget install --id Gyan.FFmpeg.Shared -e
+winget install --id astral-sh.uv -e
+ffmpeg -version
+ffprobe -version
+uv --version
+```
+
+On Linux, use the distribution package manager or the current official installation method for the
+same executables. Keep these machine tools outside the video project. `hypit paths` reports the shared
+Program and npm package homes used by selected Runtime adapters.
+
+## Let the selected Endpoint own its Program
+
+An Endpoint may contribute one Managed Program: for example, a warm WhisperX service or the browser
+needed by local HyperFrames. Its Provider owns the prepare command, start command, probe, expected
+identity, and configuration. The Runtime operates those declarations:
+
+```bash
+hypit runtime up
+hypit programs status
+```
+
+`runtime up` prepares selected adapter dependencies, brings declared Programs to their expected local
+state, and starts the Worker. The narrower commands operate only the Programs:
+
+```bash
+hypit programs up
+hypit programs status
+hypit programs down
+```
+
+`runtime down` stops the Worker while leaving separately managed Programs available. This lets a later
+Build reuse an already warm local model. Use `programs down` when those helpers themselves should stop.
+
+Ordinary projects use these declarations instead of running a service's internal `uv sync` or Python
+entry point by hand. Contributor/operator commands in a service README are for diagnosing that
+packaged service, not for creating a second project-local installation.
+
+## Select local WhisperX explicitly
+
+Local and hosted WhisperX implement the same alignment capability. Add the local Provider to the
+Profile:
+
+```json
+{
+ "endpoints": {
+ "whisperx.local": {
+ "use": "@hypit/provider-whisperx-local"
+ }
+ },
+ "bindings": {
+ "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"
+ }
+}
+```
+
+The binding is needed when another selected Endpoint, such as HypiHub, also offers alignment. The
+Provider README owns optional model, device, compute, batch-size, timeout, and concurrency settings.
+Its loopback service accepts canonical speech evidence and returns measured alignment; it does not
+interpret Script, Caption Cues, or Semantic Segments.
+
+Run `hypit runtime up` after selecting it. The first preparation may install Python and download model
+weights, while later projects reuse the machine Program. Success means the configured service identity
+answers its health probe; `hypit doctor` then checks the selected Endpoint as part of the full Profile.
+
+If local installation is incompatible with the machine, blocked by the network, or making no useful
+progress within the user's available time, report the exact evidence and offer another Provider for
+the same capability. Repeated installation attempts are not a substitute for a working ear.
+
+## Repair from the narrowest evidence
+
+- A missing executable belongs to host installation and `PATH`.
+- A package dependency named by an adapter can be prepared by `runtime up`; a separately reported
+ exact optional npm dependency uses `hypit packages install <package@version>`.
+- A down or mismatched Managed Program belongs to its Provider configuration, Program status, and
+ service log.
+- A healthy local Program with a rejected request belongs to the Provider's support or request error,
+ not to reinstallation.
+- A remote authentication, account, quota, or model-catalogue error belongs to the remote Endpoint and
+ `profile.md`, even when the Worker happens to run locally.
+
+After changing the Distribution or an already loaded project package, read `../production/builds.md`
+before restarting the Worker so active work is preserved.
diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.md
new file mode 100644
index 00000000..848b3f3b
--- /dev/null
+++ b/skills/hypit/references/environment/profile.md
@@ -0,0 +1,179 @@
+# Runtime Profile and capabilities
+
+Read this when a project needs an execution environment, a credential, another Provider, or an
+explanation of what the current machine can actually do.
+
+## Start from the work's capabilities
+
+The environment is sufficient relative to the work, not as a global state. Read the Brief,
+Treatment, Source, and Run that matter, then identify the capabilities they need. A typical generated
+reconstruction may need:
+
+- visual observation through a selected `@hypit/gemini` Endpoint;
+- word transcription and alignment through a selected `@hypit/whisperx` Endpoint;
+- the exact image, video, voice, or audio models authored in Source;
+- media inspection, normalization, extraction, audio assembly, and muxing;
+- HyperFrames visual rendering;
+- the project's selected Build Result repository.
+
+Different work can need a smaller or larger set. Existing material with deterministic Caption, MG,
+and editing does not acquire an image model merely because another production used one. A reference
+reconstruction that depends on unobserved motion, speech timing, or new generated shots does need the
+corresponding eyes, ears, and production capabilities.
+
+## Keep the owners separate
+
+| Owner | What it decides |
+| --- | --- |
+| Author and Run Sources | what the work is and which public Outputs this execution requires |
+| Runtime Profile | which environmental packages, Endpoint instances, credentials, and bindings are selected |
+| Provider Endpoint | how one capability is supported, diagnosed, invoked, and priced |
+| Credential Store | how one explicitly named secret is resolved |
+| Managed Program | how a selected local Endpoint's long-lived helper is prepared and probed |
+| Project Result repository | where finished Build Results and their public Outputs live |
+
+Changing an Endpoint does not change the Author Source. Result storage is selected separately in
+`hypit.results.json`; it is not a Runtime Profile field. Workspace and project-package resolution are
+also independent of the Profile.
+
+The Profile itself contains only environmental choices:
+
+- `credentials` selects Credential Store adapters;
+- `endpoints` names Provider adapter instances and their configuration;
+- `bindings` chooses an Endpoint when several selected instances offer the same capability;
+- an optional shared `pool` says that several instances consume one real account, deployment, or
+ compute quota.
+
+Read each selected Provider README for its accepted configuration and capability support. Installing
+a package only makes it available; a Profile entry selects it.
+
+## Begin with the Distribution starter
+
+From the project directory:
+
+```bash
+hypit runtime init
+hypit paths
+```
+
+`runtime init` writes and selects an editable starter `hypit.runtime.json`. It does not install a
+package, contact a service, request a credential, or start a Worker, and it preserves an existing
+Profile. Use `hypit runtime use <profile>` to select an intentional existing Profile for this project.
+
+The current official video Distribution starts with:
+
+- `hypihub.default` for remote generation, Gemini observation, and WhisperX alignment;
+- `media.local` for local media processing;
+- `hyperframes.local` for local visual rendering.
+
+This is a useful first configuration, not an Author-language rule. A project may select BYOK
+Providers, local WhisperX, remote rendering, or another supported deployment without changing its
+Source. Exact models remain author choices and are demanded only when the selected Run reaches them.
+
+Runtime selection is project-local. Commands read that project's `.hypit/runtime` pointer and do not
+choose a Profile from a familiar filename or from another project above it.
+
+## Choose the practical capability path with the user
+
+Inspect the selected Profile, configured credentials, and current Endpoint diagnoses before asking
+the user to set up anything. Keep a working choice. When a required capability is missing, explain
+the consequence in the language of the work and present only the choices that materially differ in
+cost, privacy, setup time, or control.
+
+- Use a supported BYOK Provider when the user already has that account and wants to use it.
+- For speech alignment, offer local WhisperX when the machine and the user's available setup time
+ make it practical. Explain that its first preparation may install a runtime and download model
+ weights; `local-tools.md` owns the bounded setup and repair guidance.
+- Offer HypiHub as the official hosted route when the user prefers one hosted account or does not
+ have the corresponding BYOK or local capability. Authentication and available quota still need to
+ be established for the selected account.
+- Image, video, voice, and audio production each require an actual selected Endpoint for the exact
+ authored model. An observation Endpoint does not imply a generation Endpoint, and vice versa.
+
+HypiHub is a convenient selected Provider, not an automatic fallback. Moving from BYOK or local
+execution to HypiHub changes the Profile or its binding explicitly; it never happens because another
+Endpoint failed. Ask for a user decision only when the alternatives have a meaningful consequence,
+not merely because several equivalent implementations exist.
+
+## Put secrets behind credential references
+
+A Profile names a Credential Store and key; the secret stays in that store. The writable OS store
+uses macOS Keychain or Windows Credential Locker. The environment store reads one explicitly named
+environment variable and is read-only.
+
+Inspect one Endpoint's credential slots without revealing their values:
+
+```bash
+hypit auth status hypihub.default
+```
+
+When the Endpoint declares an acquisition flow or the selected store accepts interactive input, use:
+
+```bash
+hypit auth login hypihub.default
+```
+
+OAuth may open the Provider's browser flow. Another Endpoint may securely prompt for its exact secret
+or accept `--from <secret-file>`. An Endpoint backed by the read-only environment store is configured
+in the Worker process environment instead.
+
+Keep secrets out of Author Sources, Runs, Runtime Profile JSON, project documentation, command
+arguments, commits, and conversation text. Ask the user to complete a Provider browser flow or secure
+terminal prompt rather than paste a key into chat. Report the Store, key name, Endpoint, and whether
+it is configured; never report the stored value.
+
+A stored credential proves only that a value is available. It does not prove that the account is
+current, has quota, can reach a model, or is accepted by the remote service.
+
+## Ask each command for the fact it owns
+
+| Command | What it can establish |
+| --- | --- |
+| `hypit paths` | resolved project, selected Profile, and physical host/runtime locations |
+| `hypit auth status <endpoint>` | whether that Endpoint's declared credential slots are configured |
+| `hypit doctor` | an active, read-only audit of the selected or supplied Profile and Result repository |
+| `hypit plan <run> --runtime <profile>` | the exact external Needs of one Run and cheap readiness of that demanded slice |
+| `hypit runtime status` | Worker, active Build, and selected Managed Program state |
+
+With no Profile selected or supplied, `doctor` checks the project Result repository alone. With a
+Profile, it may authenticate and ask a remote Endpoint for its bounded capability catalogue. It
+submits no generation request. A successful login followed by a failing doctor is useful evidence:
+report the Provider's current explanation rather than treating credential storage as proof of
+reachability.
+
+`plan` knows the chosen Target and Candidates, so it identifies the capabilities this Run will demand
+and applies the selected Endpoint's normal request-support check. Its preflight checks configuration,
+credential presence, packages, executables, and relevant Managed Programs without actively probing a
+remote service. Read `../production/builds.md` for planning, spending authority, and submission.
+
+## Be honest about the available production
+
+When a capability is absent, explain the creative consequence and offer the choices that actually
+exist:
+
+- select a supported Provider using the user's own account;
+- use the official HypiHub Endpoint when the user has chosen and authenticated it;
+- use a local implementation such as WhisperX when the machine can support it;
+- reshape the production around accepted existing media and deterministic components;
+- stop before promising a reconstruction that needs unavailable observation or generation.
+
+With no generation account, a project can still arrange supplied media, Script, Caption, MG, audio,
+and HyperFrames output. Without reliable visual observation, the Agent can inspect prepared frames and
+tiles but has weaker evidence about complete motion and long-range sequence. Without alignment,
+semantic attachment to real spoken words is unavailable. State those differences in the language of
+the requested work.
+
+When an installed Provider does not support the user's service or local deployment, say so and offer
+integration as a separate framework or deployment task. A new protocol normally needs a Provider;
+genuinely new author-facing request semantics also need a Model Package. Keep SVML unaware of the
+service and leave the package implementation to the Hypit repository's framework documentation.
+
+## Prepare the selected environment
+
+After selecting or changing a Profile, `hypit runtime up` prepares the selected adapters' machine npm
+dependencies, prepares and starts their declared local Managed Programs, validates the Runtime, and
+starts its Worker. It does not log into or start remote services. `hypit doctor` is the active check
+for those remote Endpoints.
+
+Use `local-tools.md` when a selected local binary or Managed Program needs installation or repair.
+Read `../production/builds.md` for how submission uses the prepared environment and Worker.
diff --git a/skills/hypit/references/playbooks/craft/persona-and-audio.md b/skills/hypit/references/playbooks/craft/persona-and-audio.md
deleted file mode 100644
index 098c03b8..00000000
--- a/skills/hypit/references/playbooks/craft/persona-and-audio.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Persona and audio craft
-
-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.
-- Choose it once. One accepted sample per person feeds every line they say and every take they appear
- in, as `generated-dependencies.md` requires; choosing again per take produces a second voice.
-- 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.
-- Use `mimo:VoiceDesign` with a written voice description. Generate the sample once per person.
-- That sample is a reference on every take the person appears in, and the take speaks the Segment.
- `generated-dependencies.md` holds the rule and what it costs: one generation carries the speech and
- the picture, so the Segment's length and its picture's length are one number.
-- 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.
-
-## The take's own length is the Segment's length
-
-- The speaking take generates the speech, so a Segment is exactly as long as the take that speaks it.
- There is no second duration to reconcile.
-- Use `hypit measure` only to size a generation before it is ordered, and write the result as the
- literal duration. Final caption and semantic timing comes from each accepted normalized Take
- through `whisperx:SemanticTake`.
-- One continuous voiceover may cover several independently selected visual inserts. Do not cut the
- Script merely because the picture cuts — the inserts are Selections inside the Segment.
-- Preserve Script Segment order when assembling `speech:Take` children.
-
-## Choose one path for speech audio
-
-- Normalize the speaking take, create its `whisperx:SemanticTake`, then put that value in
- `speech:Track` as a `speech:Take`. The take carries the speech and the picture together, so that one
- value is both the Segment's timing and the picture over it.
-- Do not place the same narration on both Speech Track and an Audio Track. That duplicates speech in
- the final mix and creates competing time authority.
-
-## Put non-speech 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" semantic={speech.semantic}>
- <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 Track's audio projection and every selected Audio Track to `film:Film`.
-- A Media Track carries picture alone unless the source was normalized with `audio="default"`.
-- 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/skills/hypit/references/playbooks/craft/sound-mix.md b/skills/hypit/references/playbooks/craft/sound-mix.md
new file mode 100644
index 00000000..8c60cf63
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/sound-mix.md
@@ -0,0 +1,71 @@
+# Sound and mix
+
+Read this when speech, music, ambience, and sound effects must work together across a passage or the
+complete Film. Voice identity and the source of spoken performance belong to
+`voice-and-performance.md`.
+
+## Give each layer a dramatic job
+
+Treat the soundtrack as a composition of independently authored contributions:
+
+- **speech** carries words, performance, and intelligibility;
+- **music** carries continuous pace, mood, tension, release, and structural change;
+- **ambience** gives places and edits a believable acoustic world;
+- **sound effects** answer discrete visible or editorial events.
+
+The Treatment and reference Timeline can describe what each layer contributes and where its role
+changes. The Source expresses the chosen relationships with ordinary audio Resources and Tracks.
+An audio library, generated sound, recorded material, or an earlier accepted Output can all supply a
+layer; choose from the work's need rather than treating origin as an audible category.
+
+## Let speech organize the available space
+
+In a work with dialogue or narration, every required word should remain effortless to understand on
+ordinary phone and laptop speakers. Shape music, effects, and ambience around consonants, names,
+numbers, claims, punchlines, and the CTA. A louder layer is not automatically more exciting if it
+makes the argument disappear.
+
+Use level changes, fades, arrangement gaps, frequency balance, or ducking when the music should yield
+to speech. Let an intentional pause, reveal, or montage earn a fuller musical moment. When a passage
+has no speech, the other layers can occupy more space without implying that every silence needs to be
+filled.
+
+Normalize each selected source into media the program can place, then author its audible level and
+span. Normalization prepares a source; it does not decide the creative balance or master the complete
+Film. Keep speech, music, ambience, and effect families independently inspectable until their
+relationship is understood.
+
+## Attach sound to meaning
+
+Continuous music usually follows a structural passage or the whole program. Ambience follows the
+world and may bridge picture cuts that remain in one place. A sound effect follows the perceived
+event that gives it meaning: contact, arrival, state change, reveal, transition, or completion.
+
+Use Script Selections and Moments when the sound belongs to spoken meaning. Use clock time when the
+event is genuinely independent of speech. The final accepted speech alignment locates semantic
+events in real media; a measured reading duration is not a substitute for it.
+
+Repeated visual states can share a coherent sound vocabulary. Variation is useful when the dramatic
+function changes, not merely because another asset is available. `sfx.md` owns the finer judgment of
+individual effect choice and timing.
+
+## Preserve continuity through edits
+
+Picture cuts do not necessarily imply acoustic cuts. Room tone can continue across coverage, music
+can bind a montage, and a speaking Take can remain audible while B-roll or MG changes the picture.
+Conversely, a change of place, speaker perspective, narrative state, or designed silence may deserve
+an audible transition even when the picture changes gently.
+
+Listen at boundaries for clipped words, missing breaths, doubled speech, abrupt room changes, music
+that restarts accidentally, and effect tails cut by the next shot. Fades and overlaps should express
+the intended handoff rather than hide an unexplained discontinuity.
+
+## Review the complete listening experience
+
+First establish that each important source is the right performance or sound. Then hear speech with
+the surrounding layers, the densest passage, every structural transition, and the opening and close.
+Finally listen to the complete Film without stopping on both headphones and ordinary speakers.
+
+Judge cumulative pace and fatigue as well as isolated clarity. Repair the owning layer: performance
+problems in the speech source, semantic placement in Source, event design in the effect, arrangement
+and balance in the mix, and clipping or encoding in the relevant media or final output.
diff --git a/skills/hypit/references/playbooks/craft/voice-and-performance.md b/skills/hypit/references/playbooks/craft/voice-and-performance.md
new file mode 100644
index 00000000..5427fa76
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/voice-and-performance.md
@@ -0,0 +1,100 @@
+# Voice and performance
+
+Read this when deciding who performs spoken material, how a recurring person keeps one voice, or
+whether an off-screen passage continues an A-roll performance or uses independent speech.
+
+## Begin with who carries the expression
+
+Most presenter-led short videos get their speech from an A-roll performance. The generated Take
+carries the words, mouth movement, gesture, gaze, delivery, and picture together. An accepted camera
+image establishes the person in a useful shot, an accepted Voice Reference establishes how they
+sound, and the video direction tells the performer what to say and do.
+
+A-roll is a role in the work, not a rectangle or stack position. The same performance remains A-roll
+when its picture is cropped, keyed, moved into a corner, placed above a board, or temporarily covered
+by B-roll or MG. The viewer may stop seeing the speaker while continuing to hear the same performance.
+Changing the visible projection does not by itself create a new speech source.
+
+Read the whole work or passage before choosing the source of speech. A recurring presenter, podcast
+speaker, interview participant, or host normally continues to carry their own lines through visual
+coverage. A passage built as narration from the outset may instead use independent speech while
+hands, screens, products, montage, B-roll, Typography, or MG carry the picture.
+
+## Give a recurring person one accepted voice
+
+A **Voice Reference** is an ordinary accepted audio Resource that establishes a person's vocal
+identity. Reusing that Resource wherever the same person performs is what carries the relationship
+through the production.
+
+When the user supplies the exact private voice they want, prepare a clean representative excerpt as
+the Voice Reference. Otherwise direct Voice Design from the person's role, energy, age range,
+language, accent, vocal texture, pace, and delivery. Voice Design acts as a broadly capable casting
+and voice-design partner; a public character type or an imagined voice can be designed directly.
+
+About five seconds of clear, natural speech is usually enough to establish a useful reference while
+remaining easy to reuse across models. Choose words that exercise the delivery the work needs. Keep
+the sample free of other speakers, music, clipping, heavy room echo, and long silence. The selected
+model's documentation owns any exact count, duration, or format limits for its references.
+
+Direct the voice from the intended character and performance. Appearance alone is not acoustic
+evidence, but the Agent can choose a voice that supports the person's role, personality, setting, and
+the work's tone. Once accepted, reuse that same Resource wherever the same person must sound like
+themselves.
+
+## Let one reference support different performances
+
+The useful dependency is shallow:
+
+```text
+Voice Design or supplied audio
+ ↓
+ accepted Voice Reference
+ ↙ ↘
+A-roll performance independent speech
+```
+
+An A-roll-capable video model receives the reference while generating the person's visible speaking
+Take. Voice Clone receives the same reference when the work genuinely needs that person to speak as
+an independent audio source. These are two uses of one ordinary Resource, not two voice identities.
+
+A work may combine them. A host can perform the main A-roll and later narrate a passage that has no
+underlying on-camera performance; using the same Voice Reference makes both sound like the same
+person. Another passage covered by B-roll may still be audio from the A-roll Take beneath it. Decide
+from the passage's expressive construction, not from whether the face happens to be visible at that
+instant.
+
+## Treat narration as a sound-picture relationship
+
+Narration means the audience hears speech while the speaker is not the primary visible action. That
+description does not reveal how the speech was produced.
+
+- In an A-roll-led passage, coverage changes the picture while the accepted speaking Take remains the
+ performance and timing authority.
+- In a narration-led passage, accepted independent speech supplies the performance while the picture
+ is designed separately around it.
+- In a mixed work, each passage can use the relationship that serves it, while recurring people keep
+ their accepted Voice References.
+
+Use `formats/narration-led-demo.md` when independent narration actually organizes a work or
+substantial passage. Use the relevant presenter, interview, podcast, or call Format when people
+perform their lines on camera, even if other layers cover them for part of the edit.
+
+## Give real performance real semantic time
+
+`../../creation/script-and-time.md` owns measurement, literal duration, and alignment. Once the
+accepted performance has semantic time, its dependent layers follow the delivery that really
+happened. Repair a weak performance at its direction, wording, reference, or generation according to
+the visible and audible problem.
+
+## Review the person, not just the waveform
+
+Judge whether the voice and visible performance express the same character: pronunciation, pace,
+cadence, emotion, mouth movement, gesture, gaze, and interaction with the scene. Across recurring
+Takes, listen for identity drift and room discontinuity while allowing intentional changes in energy
+or delivery.
+
+Review covered passages with their picture and with the underlying speech source made clear. A clean
+mix cannot rescue the wrong performer, and a good voice sample cannot rescue an unconvincing Take.
+Use `sound-mix.md` for music, effects, ambience, gain, and the completed mix. Use
+`generated-dependencies.md` for the broader question of which accepted media should directly
+condition another generation.
diff --git a/skills/hypit/references/playbooks/formats/asmr.md b/skills/hypit/references/playbooks/formats/asmr.md
index 75515e50..197a0c07 100644
--- a/skills/hypit/references/playbooks/formats/asmr.md
+++ b/skills/hypit/references/playbooks/formats/asmr.md
@@ -46,6 +46,6 @@ the visible event, including headphones and ordinary speakers. Pin accepted firs
and audio Records with `.svrun` `build-record` and `satisfy`.
Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`, `../craft/b-roll.md`,
-`../craft/persona-and-audio.md`, and `../craft/sfx.md`.
+`../craft/voice-and-performance.md`, and `../craft/sfx.md`.
That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/formats/mass-tarot.md b/skills/hypit/references/playbooks/formats/mass-tarot.md
deleted file mode 100644
index 3304a090..00000000
--- a/skills/hypit/references/playbooks/formats/mass-tarot.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# Mass-tarot pick-a-card format
-
-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.
-- Take the voice sample once with `mimo:VoiceDesign`. The reading is spoken by a
- take, and that take is the base under the whole Segment — the cards and the spread cover it, and
- the speech and the picture stay one generation. `../craft/generated-dependencies.md` says why.
- Cut the Segment to fit one generation.
-
-```svml
-<program:Clock id="clock" frame-rate="30"/>
-<seedance:ReferenceVideo id="narration-take" model="mini" prompt={reading-prompt}
- duration={reading-duration.duration} generate-audio="true">
- <seedance:Reference image={reader.image}/>
- <seedance:Reference audio={reading-voice.audio}/>
-</seedance:ReferenceVideo>
-<pipeline:Normalize id="narration-media" source={narration-take.video}
- video="primary-moving" audio="default" span-authority="video" clock={clock}/>
-<whisperx:SemanticTake id="narration-semantic" narrative={story}
- segment={story.segment.reading} media={narration-media.media}/>
-<speech:Track id="speech"
- visual-frame={full-frame} visual-appearance={recipes.speech.visual} visual-z="0">
- <speech:Take source={narration-semantic.take}/>
-</speech:Track>
-```
-
- Peer Media Tracks provide every card/table visual while `{speech.audio}` carries narration.
-- A visible host may instead use `speaker-v1` speaking Semantic Takes assembled through the same Track.
-
-## 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`.
-
-That list is complete, and the always-read craft in `../index.md` applies regardless of format.
-
-- The base is meant to stay hidden, so the covering Selections tile the Segment.
- `../craft/generated-dependencies.md` states that rule and holds the marker table.
diff --git a/skills/hypit/references/playbooks/formats/mixcut.md b/skills/hypit/references/playbooks/formats/mixcut.md
index 939bfc77..577de298 100644
--- a/skills/hypit/references/playbooks/formats/mixcut.md
+++ b/skills/hypit/references/playbooks/formats/mixcut.md
@@ -60,6 +60,6 @@ image, clip, audio source, and the SemanticTrack with `.svrun` `build-record` an
only failed beats.
Read `../craft/image-prompt-style.md`, `../craft/b-roll.md`, `../craft/overlays.md`,
-`../craft/persona-and-audio.md`, and `../craft/sfx.md`.
+`../craft/voice-and-performance.md`, and `../craft/sfx.md`.
That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/formats/narration-led-demo.md b/skills/hypit/references/playbooks/formats/narration-led-demo.md
new file mode 100644
index 00000000..c7e75bed
--- /dev/null
+++ b/skills/hypit/references/playbooks/formats/narration-led-demo.md
@@ -0,0 +1,86 @@
+# Narration-led work
+
+Read this when independent spoken narration carries a work or substantial passage while products,
+hands, screens, demonstrations, B-roll, Typography, or MG carry the picture.
+
+## Recognize the organizing relationship
+
+A narration-led passage is organized by an accepted independent speech performance. Its pictures
+are designed around that performance rather than being temporary coverage over a speaking A-roll
+Take. Common forms include desk demonstrations, screen tutorials, product walkthroughs, visual
+essays, montage narration, and MG explainers.
+
+The decisive question is not whether a face is currently visible. A presenter-led work may cover its
+A-roll with B-roll for several seconds and still be A-roll-led. A narration-led passage begins with a
+speech performance that does not depend on an underlying on-camera delivery. A mixed work can move
+between these relationships when the story does.
+
+State that relationship in Treatment. It determines how performance, picture coverage, visual
+proof, and later review should be understood.
+
+## Direct one spoken spine and many visual answers
+
+Write the adopted narration in Script and use its Selections and Moments to name the meanings that
+need visual response. One continuous passage can carry many picture changes. A new product angle,
+screen state, action, example, or graphic reveal is usually a new visual answer inside the same
+spoken performance, not a reason to break the performance itself.
+
+Choose pictures by what they contribute:
+
+- a **context shot** establishes who, where, or what is being demonstrated;
+- a **proof shot** makes a claim visible through use, state, result, or comparison;
+- **B-roll** supplies a concrete action, object, situation, or emotional counterpoint;
+- **screen media** shows an interface or state whose literal details matter;
+- **MG and Typography** explain structure, accumulation, transformation, or a concept that a camera
+ image alone cannot communicate clearly.
+
+These roles can overlap in time. A device frame may persist while screen content changes, Caption
+follows the narration, a label remains visible, and a sound answers a UI event. Author each relation
+according to what persists and what changes rather than flattening the whole passage into a sequence
+of isolated cards.
+
+## Build visual evidence, not noun illustration
+
+Let each picture advance the argument. A claim about speed benefits from a visible fast action or a
+shortened process; a product claim benefits from the product being used or its result being shown;
+an explanation benefits from a graphic relationship the viewer can understand at a glance. Merely
+showing a generic image of every noun in the narration produces activity without proof.
+
+Generated images and videos are ordinary production media. Direct the image model as a broadly
+informed painter and the video model as a broadly informed camera crew. Use exact private product,
+brand, person, data, or interface references when public knowledge cannot establish them. Let the
+Treatment and accepted references determine each prompt; use the selected model package's vocabulary
+and README for its exact inputs and limits.
+
+## Keep the narrator one person across the work
+
+Use `../craft/voice-and-performance.md` to establish the narrator's accepted Voice Reference and
+generate independent speech from it. If the same person also appears in A-roll elsewhere, the same
+Voice Reference can condition both the visible performance and independent narration. The work then
+changes sound-picture relationship without changing who is speaking.
+
+`../../creation/script-and-time.md` owns measurement and alignment. One accepted narration
+performance can carry many picture changes; their semantic relations follow that performance without
+forcing new speech seams.
+
+## Give the complete canvas and soundtrack continuity
+
+Every intended span needs a deliberate picture: a continuing shot, another B-roll item, a persistent
+component, a handoff, or an authored background. Inspect the visible Film to verify that no inherited
+or empty edge appears between those decisions. Music, ambience, and effects can bind visual cuts or
+mark structural changes while the narration stays clear; `../craft/sound-mix.md` owns that
+relationship.
+
+Caption remains spoken text. Steps, labels, figures, headings, CTA copy, and interface writing have
+their own Typography, Text, screen, or MG roles unless they are also meant to be read as narration.
+
+## Review whether the pictures earn the narration
+
+Watch the passage first as an argument: does every visual change clarify, prove, pace, or intensify
+what is being said? Then inspect exact product and screen truth, hand and device geometry, Caption
+timing, persistent component states, visual handoffs, and audio continuity.
+
+Listen once without the picture to judge the speech performance, then watch without relying on the
+words to judge whether the visual sequence has its own intelligible progression. Finally review the
+complete Film. Repair weak narration at its performance source, weak proof in the shot or component
+design, wrong timing at the authored semantic relation, and weak balance in the mix.
diff --git a/skills/hypit/references/playbooks/formats/scenario-call.md b/skills/hypit/references/playbooks/formats/scenario-call.md
index 0202aa21..1a6868e0 100644
--- a/skills/hypit/references/playbooks/formats/scenario-call.md
+++ b/skills/hypit/references/playbooks/formats/scenario-call.md
@@ -38,6 +38,6 @@ live listener reaction, UI stability, and generated text. Pin every accepted lay
`.svrun` `build-record` and `satisfy`.
Read `../craft/seedance-directing.md`, `../craft/captions.md`, `../craft/overlays.md`, and
-`../craft/persona-and-audio.md`.
+`../craft/voice-and-performance.md`.
That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/formats/street-interview.md b/skills/hypit/references/playbooks/formats/street-interview.md
index e227a305..d4773a14 100644
--- a/skills/hypit/references/playbooks/formats/street-interview.md
+++ b/skills/hypit/references/playbooks/formats/street-interview.md
@@ -51,7 +51,7 @@ Review speaker/voice assignment, lip-sync, microphone position, listener silence
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/persona-and-audio.md`, `../craft/captions.md`,
+Read `../craft/seedance-directing.md`, `../craft/voice-and-performance.md`, `../craft/captions.md`,
and `../craft/b-roll.md`.
That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/formats/talking-head.md b/skills/hypit/references/playbooks/formats/talking-head.md
index 0a99237e..1460d08c 100644
--- a/skills/hypit/references/playbooks/formats/talking-head.md
+++ b/skills/hypit/references/playbooks/formats/talking-head.md
@@ -55,7 +55,7 @@ Use supplied UI media whenever exact interface content matters. Keep explanatory
- 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/persona-and-audio.md`, `../craft/captions.md`, `../craft/b-roll.md`, and
+`../craft/voice-and-performance.md`, `../craft/captions.md`, `../craft/b-roll.md`, and
`../craft/overlays.md`.
That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/formats/two-person-podcast.md b/skills/hypit/references/playbooks/formats/two-person-podcast.md
index b10c0a4b..57281251 100644
--- a/skills/hypit/references/playbooks/formats/two-person-podcast.md
+++ b/skills/hypit/references/playbooks/formats/two-person-podcast.md
@@ -51,7 +51,7 @@ lighting. Then review every take for voice assignment, exact words, lip-sync, re
camera selection, and identity. Pin accepted views and takes through `.svrun` `build-record` and
`satisfy`.
-Read `../craft/seedance-directing.md`, `../craft/persona-and-audio.md`, `../craft/captions.md`,
+Read `../craft/seedance-directing.md`, `../craft/voice-and-performance.md`, `../craft/captions.md`,
and `../craft/b-roll.md`.
That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md b/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md
deleted file mode 100644
index 625b6ac4..00000000
--- a/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Voiceover desk-demo format
-
-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. Take the voice sample once with `mimo:VoiceDesign`.
-3. The narration is spoken by a take, and that take is the base. It is under the whole Segment and
- the B-roll covers it; the viewer sees the desk only where nothing is over it, and the speech and
- the picture are one generation either way — `../craft/generated-dependencies.md` says why that
- matters. Cut the Segment to fit one generation.
-
-```svml
-<program:Clock id="clock" frame-rate="30"/>
-<seedance:ReferenceVideo id="narration-take" model="mini" prompt={narration-prompt}
- duration={narration-duration.duration} generate-audio="true">
- <seedance:Reference image={desk.image}/>
- <seedance:Reference audio={narration-voice.audio}/>
-</seedance:ReferenceVideo>
-<pipeline:Normalize id="narration-media" source={narration-take.video}
- video="primary-moving" audio="default" span-authority="video" clock={clock}/>
-<whisperx:SemanticTake id="narration-semantic" narrative={story}
- segment={story.segment.narration} media={narration-media.media}/>
-<speech:Track id="speech"
- visual-frame={full-frame} visual-appearance={recipes.speech.visual} visual-z="0">
- <speech:Take source={narration-semantic.take}/>
-</speech:Track>
-```
-
-4. Pass `{speech.semantic}` to every Media/Typography/Caption/Audio Track and add
- `{speech.audio}` 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.
- The base is meant to stay hidden, so the covering Selections tile the Segment —
- `../craft/generated-dependencies.md` states that rule and holds the marker table. 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/seedance-directing.md`,
-`../craft/persona-and-audio.md`, `../craft/captions.md`, and `../craft/sfx.md`.
-
-That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/skills/hypit/references/playbooks/index.md b/skills/hypit/references/playbooks/index.md
index c35906fd..3ad67b7e 100644
--- a/skills/hypit/references/playbooks/index.md
+++ b/skills/hypit/references/playbooks/index.md
@@ -1,106 +1,46 @@
-# Hypit production playbooks
+# Production playbooks
-Use these playbooks to author production decisions directly in `.svml`, `.svs`, and `.svrun`
-sources. Each playbook names the SVML components, timing model, review questions, and reuse behavior
-needed for that craft or format.
+Read this when the current work needs format or craft knowledge beyond the Creation and Production
+references. Playbooks help the Agent direct a work; the Source and Run remain the author's.
-## Required load order
+## Combine two scales
-1. Always read `craft/frame-coverage.md`, `craft/visual-continuity.md`,
- `craft/graphic-compositions.md`, and `craft/generated-dependencies.md`. Each route file names the
- step that reads them.
-2. Read `craft/seedance-directing.md` whenever the Author Source invokes Seedance.
-3. Read the selected format file and only the additional craft files **its own footer** names.
- That footer is the complete list; this index does not repeat it, and a footer that is wrong is
- fixed in the footer.
-4. Read the installed `packages/<name>/README.md` for every package whose elements you write, and the relevant
- authoritative Quickstart page for the model behind them.
+A **format** describes a recurring whole-work relationship: who carries the argument, how attention
+moves, and what kind of reveal or payoff holds the piece together. A **craft** addresses one local
+directing problem that can appear in many formats: Caption, B-roll, continuity, image generation,
+sound, or graphic composition.
-No document a whole job needs may be reachable only through a conditional file. Craft and format
-files are selected per job; a spine is walked by every job on its route, so anything every job needs
-is named by `../original-authoring/route.md` or `../reconstruction/route.md` rather than by a craft
-file that some jobs never open.
+Use the reference Analysis and Timeline, the target Brief and Treatment, and the visible Source to
+choose what is relevant now. One work may draw from several formats and several crafts. A new or
+hybrid form may need craft pages without matching any format page.
-## Shared SVML contract
+The pages below own stable cross-work directing knowledge. When none fits the current question, use
+the project's Analysis, Timeline, Brief, Treatment, Source, and visible Results directly. A work does
+not need a matching playbook before it can be understood or made.
-- Put narrative truth in one `script` with Segments, Role Cues, Selections, and Moments.
-- Use `copy:Value`/`copy:Render` from `@hypit/text@1` for prompts and reusable copy.
-- Use `typo:Style`/`typo:Track` from `@hypit/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 from normalized `whisperx:SemanticTake` values with `speech:Track`, then add
- peer Caption, Media, Typography, Ranking, Deck, Comment, Screen, and Audio Tracks.
-- Use `speech:Track` for ordered speech-bearing Semantic Takes. A program with no spoken words still
- has a SemanticTrack, because it is the frame domain every `start`/`end` window resolves into: keep
- the `whisperx:SemanticTake` and `speech:Track` declarations, which are what declares the
- `<track>.semantic` output, and satisfy that output in `.svrun` with a `build-record` Candidate from
- a Build that already produced one. Keep `<track>.visual` and `<track>.audio` out of the Film and the
- alignment goes unreached — `hypit plan` lists it under `Declared but not reached`. Time every Item
- and Clip with `start`/`end`, and omit the Caption components.
-- Assemble peer Tracks with `film:Film`, render with `render:Video`, and demand outputs through a
- `.svrun` Target.
-- Stage expensive work with narrow `.svrun` Targets. Explicitly reuse an accepted Record through
- `build-record` plus `satisfy`; Hypit 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; `../vocabulary.md` says why, and how to
- find out what exists.
+## Craft
-## Prompt policy
+| Read | When the current question concerns |
+| --- | --- |
+| [Voice and performance](craft/voice-and-performance.md) | who performs speech, recurring voice identity, A-roll under coverage, or genuinely independent narration |
+| [Sound and mix](craft/sound-mix.md) | the relationship among speech, music, ambience, effects, loudness, ducking, and continuity |
-- Write VLM instructions and image/video generation prompts in English. Keep original-language
- dialogue, transcript, pronunciation, and quoted copy verbatim.
-- Every photographic `gpt:Image` prompt begins with the invariant reality contract in
- `craft/image-prompt-style.md`, including when ordered `gpt:Reference` children are present;
- references constrain the shot but never replace that prefix.
-- Spend descriptive detail on the subject's identity and silhouette first. Keep the background to one
- short continuity sentence unless a setting detail is required for the story or camera geometry.
-- Keep dimensions out of prompt prose. Put aspect ratio and resolution on `gpt:Image`; do not mention
- values such as `1:1`, `16:9`, `square image`, `2K`, or `4K` in the prompt.
-- Do not use real-person names as visual shorthand. Spell out the subject's visible appearance and
- wardrobe so the image model can render the intended identity without a named-person reference.
-- 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.
+Read every craft whose question genuinely appears in the work, including questions discovered after
+a Studio preview or completed Result. Repeated use of the same craft does not require rereading it
+unless the decision has changed.
-## Craft
+## Formats
-- `craft/visual-continuity.md` — identity, shot groups, reverse-view geometry, and prop invariants.
-- `craft/graphic-compositions.md` — what counts as a base picture, full-screen graphic compositions,
- and where missing material comes from.
-- `craft/frame-coverage.md` — what is on screen at every instant, and the edges nobody chose.
-- `craft/generated-dependencies.md` — what one generation owes another: the location, the split picture,
- the voice, the first frame, and the take too short to generate.
-- `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.
+| Read | When the work's shape includes |
+| --- | --- |
+| [Narration-led work](formats/narration-led-demo.md) | independent narration organizing products, hands, screens, demonstrations, montage, or MG |
-## Formats
+A format page is useful when its relationships illuminate this work. It is not a category the
+project must declare, and its examples do not limit what the work may combine or invent.
-| Format | Choose it when the request is |
-|---|---|
-| `formats/talking-head.md` | one presenter speaking to camera — an explainer, an opinion piece, a piece to camera |
-| `formats/street-interview.md` | a vox pop, passers-by being asked something, an interview on location |
-| `formats/two-person-podcast.md` | a conversation between two people — a podcast clip, an interview at a table |
-| `formats/scenario-call.md` | a video call or screen share, two live tiles, an active speaker that changes |
-| `formats/ranking-listicle.md` | a top-N, a countdown, a tier list, "best X", any ordered set revealed in turn |
-| `formats/mass-tarot.md` | a pick-a-card reading, a pick-a-pile, a several-option reveal |
-| `formats/voiceover-desk-demo.md` | a voiceover over a product, a desk demo, a screen or hands walkthrough |
-| `formats/mixcut.md` | a montage or music-led cut — short shots carrying the argument, nobody to camera |
-| `formats/asmr.md` | close texture and sound, a satisfying micro-film, one physical action per shot |
+## Continue at the owner
-Each format file's own footer is the single authority for the additional craft that format needs.
-This table routes; it does not require. **An inventory may carry descriptions, and may not carry
-requirements.** A stale description misroutes and the first line of the file it opens corrects it; a
-stale requirement is silently unmet and nothing corrects it.
+Once a playbook identifies the needed role or relationship, use `hypit vocabulary <package>` and the
+owning package README for exact Surfaces, ports, fields, and model options. Creation references own
+the work's understanding and intention; Production references own Source, Run, preview, Build, and
+Result behavior. Project files own the facts and decisions of the current work.
diff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.md
new file mode 100644
index 00000000..ba9ad666
--- /dev/null
+++ b/skills/hypit/references/production/authoring.md
@@ -0,0 +1,119 @@
+# Authoring a production
+
+Read this when turning the current Treatment into Author Sources, Recipes, Runs, project components,
+and Builds, or when revising an existing production.
+
+## Turn the Treatment into relationships
+
+Begin with the work the Treatment describes, not with a package inventory. Identify:
+
+- the Script passages and speaking roles;
+- the A-roll and B-roll Takes that carry those passages;
+- the Caption, Typography, MG, Effect, and Audio systems that act with them;
+- the semantic relations that should follow words, phrases, pauses, or content events;
+- the genuinely clock-based events;
+- the final Film or other deliverables.
+
+Author those relationships explicitly. Script Selections and Moments carry meaning through produced
+speech into real time. Track and Film elements arrange the resulting picture and sound. One Source
+carries the whole creative program; its cuts are relationships inside that program.
+
+When observation has already produced useful authored data—such as a per-frame region sequence for
+placing Caption above a moving head—keep that data in Source or Recipe and pass it through the
+component's declared input. It is part of the chosen production design, just like a Frame or Style.
+
+## Give each production surface one job
+
+- An **Author Source** (`.svml`) owns the target Script, media requests, components, Tracks, Film, and
+ public Outputs. It imports the vocabulary it uses and may import other Author or Recipe Sources.
+- A **Recipe Source** (`.svs`) owns reusable authored values such as a visual Style or request
+ configuration. It remains explicit input to the Source that uses it.
+- A **Run Source** (`.svrun`) binds one Author entry, names the public Outputs this execution requires,
+ and selects any file, earlier Result, or Fragment Candidates used for it.
+- A project **Author Package** under `packages/` owns a visual or semantic role that deserves its own
+ vocabulary and implementation.
+
+A project may have several of each. Different Runs against the same Author Source are useful when
+their demanded Outputs or Candidate selections genuinely differ, not because production is divided
+into mandatory approval stages. Repeating one Run creates another Build; it does not create another
+production.
+
+Read the selected Distribution documentation and the owning package README for exact grammar. Use
+`hypit vocabulary <package>` or a focused tag or visual query to inspect the public Surfaces before
+writing them. Source imports select author vocabulary; they grant no Runtime or credential authority.
+
+## Use Runs for execution choices
+
+A Target marks where this Run asks the graph to become real. For ordinary commissioned production,
+the demanded Output is usually the finished video and the Build can produce the media dependencies
+on its route without image-by-image or Take-by-Take approval. A public image, Take, audio item, or
+other intermediate Output is also a normal Target when the user requested that deliverable or the
+work genuinely needs it independently now.
+
+Every public Author Output that completes on the demanded route is stored in that Build Result and
+can be inspected or reused later. Derived public Outputs such as a SemanticTake therefore remain
+available when a downstream Target caused them to complete, without becoming separate production
+checkpoints.
+
+The Author Graph supplies primary Candidates. A Run may explicitly select another compatible
+Candidate for a Logical Output:
+
+- `<file>` admits project media as a zero-input Candidate;
+- `<build-record>` names one public Output from one earlier Build Result;
+- a Run Fragment may provide one or more Candidates, including the generic image, video, and silence
+ stand-ins from `@hypit/stand-in`;
+- `<satisfy>` selects one declared Candidate for one Logical Output.
+
+Candidate selection is an implementation decision for this Run. Core checks nominal Type
+compatibility and plans the combined Author and Run graphs. It replaces the displaced upstream route
+while preserving any upstream Outputs that the selected Candidate itself consumes.
+
+Stand-ins carry the dimensions, duration, and clock required by downstream composition. The Run
+chooses them in the same way as every other Candidate.
+
+## Reuse produced work explicitly
+
+The exact address of an earlier public Output is its Build id plus Output name:
+
+```svml
+<build-record id="opening-take"
+ build="bld_20260902T110000001Z_0000000001" output="opening-take.video"/>
+<satisfy output="opening-take.video" candidate="opening-take"/>
+```
+
+If the current Logical Output was renamed, the two names may differ: `build-record output` remains
+the old Result's public name, while `satisfy output` names the current graph position. Hypit does not
+infer that two names carry the same creative meaning.
+
+Use `hypit builds`, `hypit inspect <build-id>`, and `hypit history <output-name>` to find a produced
+Output, then write that exact choice into the Run. A failed Build may still contain completed public
+Outputs worth using. A later Build that forwards an earlier Output does not copy its bytes.
+
+The current Build's generated media normally continues downstream as the material for the commissioned
+work. Reusing it explicitly lets Caption, MG, Effects, composition, and final encoding change without
+submitting the same paid media requests again. A SemanticTake remains meaningful only for the Script
+Segment and produced speech it aligns; changed wording needs timing from the changed speech.
+
+## Revise the fact at its owner
+
+Before editing an existing production, read its Brief, Treatment, Source, Recipes, Run, current
+Results, and relevant diff. Preserve unrelated work.
+
+- Revise Treatment when the creative design changed.
+- Revise Script when words, Cue breaks, Selections, or Moments changed.
+- Revise Source or Recipe when composition, parameters, or authored timing relations changed.
+- Revise the Run when the demanded deliverable or selected Candidate changed.
+- Revise a project package when its reusable visual role or rendering behavior is wrong.
+- Revise a media request when the desired shot or the user's requested media has changed.
+
+Generated Result bytes are evidence and reusable inputs, not editable Source. A change that still
+uses existing media should keep selecting it. A change that intentionally requests new paid media
+should first make the additional request visible in `hypit plan` and then follow the user's spending
+authority.
+
+## Use each view for what it can establish
+
+`hypit check` establishes Source and graph legality. `hypit plan <run>` shows the selected target
+route and external requests without submitting them. Studio opens that same Run for visual authoring.
+Only `hypit build <run>` submits work and creates a fresh Build Result. None of those facts alone says
+that the video is creatively successful; review the visible work as described in `review.md`.
diff --git a/skills/hypit/references/production/builds.md b/skills/hypit/references/production/builds.md
new file mode 100644
index 00000000..7dd2c24e
--- /dev/null
+++ b/skills/hypit/references/production/builds.md
@@ -0,0 +1,148 @@
+# Planning, Builds, and Results
+
+Read this when inspecting the work selected by a Run, obtaining spending authority, submitting a
+Build, following active work, or retrieving completed public Outputs.
+
+## Plan the selected Run
+
+`authoring.md` owns the meaning of Target, Candidate, and Satisfaction. This page begins after the Run
+has expressed that execution intention.
+
+```bash
+hypit check path/to/build.svrun
+hypit plan path/to/build.svrun
+```
+
+`check` validates the self-described Sources and graph without executing them. `plan` freezes the
+demanded subgraph after applying the Run's Candidate selections and lists every external Need that
+would be sent. Planning starts no external work.
+
+With a selected Runtime Profile, the plan also names the Endpoint behind each request, applies that
+Endpoint's request-support rules, checks cheap readiness for the demanded capabilities, and shows the
+Provider's declared price page or that its price source is unknown. Hypit does not copy changing rate
+tables or manufacture a total. Use the linked Provider source together with the plan's real request
+counts and authored parameters when a cost judgment is needed.
+
+Before new paid work, tell the user which requests and Provider Endpoints the plan selected and link
+their price sources. Existing explicit authorization for that described work is sufficient; otherwise
+obtain authorization before `build`. A later plan that materially changes the paid requests needs a
+new decision.
+
+## Submit one durable Build
+
+```bash
+hypit build path/to/build.svrun --title first-cut --follow
+```
+
+Every invocation creates a fresh time-ordered Build id and one independent Result, even when the Run
+did not change. The optional title is a human-facing Result label; it does not replace the Build id or
+alter Source identity.
+
+Build performs a cheap preflight and submits only when the selected deployment slice is ready. It
+does not install packages or start a missing Managed Program. When the environment has already been
+prepared and only the Worker is stopped, Build ensures that Worker becomes available. When
+preparation is missing, use `hypit runtime up` as described in `../environment/profile.md` and submit
+again after it succeeds.
+
+The Worker owns execution after durable submission. `--follow` only observes it; closing or
+interrupting that terminal detaches the observer and leaves the Build running. Reattach with:
+
+```bash
+hypit status <build-id> --watch
+```
+
+A plain `status` reads one current snapshot. `--max-wait-ms` bounds how long a caller watches; it
+does not bound or cancel the Build itself.
+
+## Observe shared work and capacity
+
+```bash
+hypit activity
+hypit runtime status
+```
+
+`activity` shows active Builds and shared Provider capacity. The Worker may advance many unrelated
+Builds together. Capacity belongs to the exact Endpoint instances, real shared pools, and any narrower
+model limits declared by those Endpoints. Builds share only those actual resources, so unrelated work
+can advance together.
+
+Immediate work releases its capacity when it returns. An asynchronous Provider operation keeps its
+claim while that same accepted operation is being polled to completion. A Worker restart continues
+stored Provider operations rather than submitting their paid request again.
+
+## Separate active work from Result outcome
+
+Runtime activity describes what is happening now. The finished Result records one outcome:
+`complete`, `failed`, or `cancelled`. These are different facts. `status` reads both sources and may
+therefore show, for example, a decided failure whose completed public Outputs are still being written
+to its Result.
+
+A failed or cancelled Build can retain useful public Outputs completed before its outcome. Inspect
+them normally. Cancellation withdraws work that has not begun and asks an Endpoint once to cancel an
+already submitted operation when it supports that; accepted completed output is retained.
+
+If Result storage or cleanup fails after execution has decided its outcome, `status` reports operator
+attention and the exact action:
+
+```bash
+hypit result finish <build-id>
+```
+
+That command writes from already accepted execution facts and working Resources. It does not invoke a
+Producer, resubmit generation, or choose another Candidate. Use it only for the Result write named by
+`status`. `hypit result discard <build-id>` applies only to an incomplete submission that never became
+active and has no Result to finish.
+
+Cancel active work explicitly:
+
+```bash
+hypit cancel <build-id> --reason "superseded by the corrected Run"
+```
+
+Stopping a Worker is different from cancellation. `runtime down` pauses advancement of all active
+Builds in that project Runtime; their durable facts remain available for the next Worker.
+
+## Browse and export project Results
+
+```bash
+hypit builds
+hypit inspect <build-id>
+hypit history <public-output-name>
+hypit get <build-id> --output <public-output-name> --to <destination>
+```
+
+`builds` lists finished project Results newest first. `inspect` shows one Result and its exact public
+Output names. `history` finds one named Output across Results; it does not select one for the current
+Run. `get` exports one named Output to one explicit destination:
+
+- a Scalar becomes a JSON file;
+- a Resource becomes one streamed file;
+- a Composite becomes a directory containing `value.json` and its referenced Resources.
+
+The destination remains a user-facing export. The original Result stays in the project's selected
+repository. The default filesystem repository lives under the project; `hypit.results.json` may
+select another adapter such as S3 without changing these commands or the Run.
+
+Give useful Results presentation metadata when it helps people and Studio find them:
+
+```bash
+hypit result edit <build-id> --title "podcast take · coral captions" \
+ --note "speaker timing and framing for the current production" \
+ --highlight podcast-take.video
+```
+
+The title, note, and highlights live in that Result manifest. They do not rename its public Outputs
+or create a project-wide history index. Reuse still names the exact Build id and Output through the
+Run mechanism in `authoring.md`.
+
+## Reload changed execution code deliberately
+
+A running Worker keeps the Runtime Profile, inherited environment, Distribution code, and package
+implementations it has already loaded. Before restarting it for a changed Profile, environment-backed
+credential, Distribution, or loaded project package, inspect `hypit activity` and preserve active
+work. Stop an idle Worker with `hypit runtime down`; the next prepared Build can start a fresh one.
+
+Credentials resolved from a writable external store may be visible without a process restart, while
+environment variables are inherited when the Worker process starts. Let the Credential Store and
+current Provider error determine which case applies instead of treating every authentication failure
+as a restart problem.
diff --git a/skills/hypit/references/production/review.md b/skills/hypit/references/production/review.md
new file mode 100644
index 00000000..cd05cebd
--- /dev/null
+++ b/skills/hypit/references/production/review.md
@@ -0,0 +1,112 @@
+# Reviewing the production
+
+Read this when opening Studio, judging an encoded Result, comparing a reconstruction with its
+reference, or deciding where a visible problem should be repaired.
+
+## Review the work the Run actually selects
+
+Open Studio with the ordinary Run intended for the work. That Run binds the Author Source, Targets,
+files, earlier Results, and stand-in Candidates, so Studio and a Build see the same authored graph.
+A separate review Run is useful when its Candidate selection is intentionally different.
+
+Studio renders the selected display closure with deterministic Producers and the exact capabilities
+that the Runtime Provider declares safe for transient authoring. It submits no Build and no paid
+generation. When a selected route still needs external generation, use an existing file or Build
+Output, or explicitly select a stand-in when only shape and time are under review.
+
+A stand-in can establish layout, duration, cuts, and downstream wiring. Its visible marking reminds
+the reviewer that it cannot establish subject identity, performance, shot composition, texture,
+continuity, or the interaction between real media and graphics.
+
+## Separate legality from judgment
+
+`hypit check` can establish that the Source and graph are legal. Studio can establish what the
+configured composition displays. A completed Build can establish what the selected Endpoints actually
+produced. Creative review asks a different question: does this visible and audible work perform the
+Treatment and the useful relationships learned from the reference?
+
+Look at the complete vertical film as well as the components inside it. A component that looks
+attractive in isolation may still cover a face, compete with a Hook, arrive on the wrong word, or
+break the piece's rhythm.
+
+## Choose evidence that exists
+
+The useful frame or interval is not known merely because a component has been authored. It becomes
+known from something visible or time-locatable: an authored Segment or clock relation, the Studio
+playhead, an encoded Result, or timing produced elsewhere in the graph. Until then, its exact
+location remains an open question.
+
+Use whichever view can answer the current question:
+
+- An Agent with browser interaction can open Studio, seek and play the ordinary Run, look at the
+ current frame, and discover where a layout or motion deserves closer inspection. This is usually
+ the cheapest way to work on Caption, MG, Effects, and composition, with stand-ins when external
+ media does not yet exist.
+- Once a numeric interval is known, a range render can inspect the corresponding frames of the same
+ HyperFrames program. The range may come from the playhead, authored clock time, or an existing
+ Result; HyperFrames does not need to know whether language helped the Agent locate it.
+- On an encoded Result, focused media operations such as frames, cut, and tile can expose exact
+ pixels, adjacent frames, or a short passage without turning those observations into project state.
+- Watch the whole deliverable when the question concerns Hook clarity, story movement, pace, payoff,
+ CTA, performance, continuity, or whether A-roll, B-roll, Caption, MG, Effects, and Audio cooperate.
+
+These views are complementary tools, not review stages. A component name alone does not prove that a
+particular state is stable or that a change occurs at a guessed time; Studio or actual media supplies
+that evidence.
+
+Inspect the visible and audible relationships that could change the work:
+
+- **picture and performance** — identity, camera relationship, action, eye line, continuity, useful
+ detail, and whether the shot serves its passage;
+- **semantic timing** — cuts, Caption Cues, MG states, Effects, and sounds occur on the intended word,
+ phrase, pause, or clock event;
+- **Caption** — every meaningfully different speaker, position, color, emphasis, Cue shape, and motion
+ configuration remains readable, belongs to the speech, and preserves the intended face and action;
+- **Typography and UI** — independent writing has the correct hierarchy, content, persistence, and
+ relationship to the picture;
+- **audio** — speech is intelligible, speaker and voice are right, music and effects support the beat,
+ and transitions sound continuous;
+- **composition** — each element has enough room and the full frame preserves the intended visual
+ hierarchy.
+
+For geometry, read three nested relationships: Canvas, outer Frame or background, and inner content.
+Check containment and capacity at each boundary, then judge optical alignment. Intentional crop,
+bleed, overlap, and asymmetric balance are part of the design when they help the work; measurements
+describe what happened and the picture decides whether it succeeds.
+
+Repeated appearances of one observed visual configuration can share a judgment. A visibly changed
+speaker, placement, Style, content shape, behavior, or surrounding composition supplies different
+evidence.
+
+## Compare a reconstruction by function
+
+Use the reference Analysis and Timeline as a question map. Compare the spans that reveal an important
+relationship: an accumulation on a board, a switch from A-roll to B-roll, a Caption system changing
+speaker, an MG reveal, or a payoff returning to the Hook. A short clip or dense adjacent frames can
+establish motion and order; a full-resolution frame can establish text and geometry.
+
+The target may intentionally change person, product, brand, language, or visual world. Compare
+whether the transformed element performs the same useful role, not whether its pixels match. When the
+target's Treatment deliberately changes the role too, the Treatment is the authority.
+
+Fresh visual attention is useful when familiarity hides an obvious problem. Another observer can be
+asked a neutral, bounded question about the actual media, while the commissioned Agent remains
+responsible for combining that evidence with the Brief, Treatment, and graph.
+
+## Repair the owning fact
+
+| What the review reveals | Where the correction belongs |
+| --- | --- |
+| The intended story, shot logic, or visual system is wrong | `TREATMENT.md` |
+| Words, speakers, Cue breaks, Selections, or Moments are wrong | the Author Source's Script |
+| Composition, authored parameters, or semantic/clock relation is wrong | Author Source or Recipe |
+| The wrong file, earlier Output, or stand-in is selected | Run Source |
+| A reusable visual role cannot express or render its intended design | the project Author Package |
+| Word timing does not describe the produced speech | the Take's transcription or alignment evidence |
+
+Use the smallest correction that changes the failed fact and preserve existing work around it. Review
+again when that correction produces new visible or audible evidence. A request for different paid
+media is a new production decision whose additional calls must be visible in `hypit plan`; it is not
+an automatic consequence of routine review. Build completion is operational success; the production
+closes when the Agent has watched the actual deliverable and can explain why it satisfies the Brief
+and Treatment.
diff --git a/skills/hypit/references/production/vocabulary.md b/skills/hypit/references/production/vocabulary.md
new file mode 100644
index 00000000..c723aa40
--- /dev/null
+++ b/skills/hypit/references/production/vocabulary.md
@@ -0,0 +1,77 @@
+# Choosing and extending author vocabulary
+
+Read this when deciding which installed Surface should express a Treatment role, or whether the
+production needs a new project Author Package.
+
+## Search from the role
+
+Name what the element must do in the work before choosing its implementation. Useful questions are:
+
+- What does the viewer perceive, and why is it present?
+- Is it Caption, independent Typography, A-roll, B-roll, MG, UI, Effect, Audio, or a new role?
+- What does it consume and publish?
+- Does it follow a Script Selection, a Moment, an explicit time span, or another component state?
+- What changes over time, and what stays visually persistent?
+- Which content belongs to this production, and which behavior should be reusable?
+
+Then inspect only plausible vocabulary:
+
+```bash
+hypit vocabulary @hypit/caption-fine
+hypit vocabulary @hypit/media-pipeline --tag StillVideo
+hypit vocabulary --visual text
+```
+
+The command reports installed package declarations, Surface attributes, children, ports, examples,
+and designed previews. The package README owns exact syntax and behavior. Read implementation files
+only when authoring a new package or diagnosing an implementation defect.
+
+## Judge fit by behavior, not resemblance
+
+An installed Surface fits when its semantic role, inputs and outputs, temporal behavior, composition
+ownership, and visual range match the intended work. Parameter differences such as words, colors,
+spacing, or ordinary media inputs belong to authored configuration when the Surface already exposes
+them.
+
+A catalogue preview is a quick recognition aid. The configured Source in Studio is the evidence for
+how the component behaves in this production. A poster that happens to resemble the reference cannot
+establish fit, and a differently styled poster does not disqualify a component whose public design
+range expresses the required role.
+
+Record the creative role in Treatment and express the implementation choice through Source imports
+and elements. Those two places contain the useful reason and the exact choice.
+
+## Create a project component as normal production work
+
+When the work introduces a new visual role, structure, state change, interaction, or crafted behavior,
+create a project Author Package under the project's `packages/`. This is a normal part of making a
+video. It does not require changing Hypit Core, the CLI, or an installed official component.
+
+Keep the boundary useful:
+
+- the package owns reusable mechanics, authored value shapes, rendering behavior, its own chrome and
+ defaults, and the public vocabulary that explains them;
+- Source and Recipe own this video's words, people, assets, timing, and chosen configuration;
+- Runtime Profiles own external execution and credentials;
+- Provider packages own privileged capabilities rather than visual composition.
+
+Start from `examples/minimal-author-package/packages/example-component/` for the current package
+shape. A close installed sibling can supply a bounded implementation pattern after its public
+vocabulary is understood. The new package still owns its own Module identity, Types, Surfaces,
+Fragments, Producers, activation descriptor, and README.
+
+Every Surface that a future author should recognize needs concise vocabulary: what it means, what it
+looks like, its attributes and ports, and a small valid example. Give a visual Surface a designed
+poster that communicates its role at a glance. The poster is package documentation, while Studio
+renders the actual configured work.
+
+## Let ordinary package management own distribution
+
+The project's package manager installs and versions components. Hypit loads only packages selected
+by Source or Run imports and resolves project packages from the project first. It does not scan the
+dependency tree for possible components.
+
+Keep a new component project-local while it serves this work. If its owner later wants to use it
+across projects, publish it as an ordinary versioned npm or private-registry package and pin it in the
+consumer project's `package.json` and lockfile. Sharing changes where the same package is installed;
+it does not change the component model or require a Hypit-specific registry.
diff --git a/skills/hypit/references/runtime.md b/skills/hypit/references/runtime.md
index e6d2e013..ccd9d51f 100644
--- a/skills/hypit/references/runtime.md
+++ b/skills/hypit/references/runtime.md
@@ -54,7 +54,7 @@ gateway, so a typical profile looks like this:
`defaultConcurrency` is the total HypiHub pool shared by its model capabilities. Tune it to the
quota behind the key; image/video capabilities keep exact-model lanes while Gemini requests share
one conservative lane. Bind every paid capability HypiHub supports to this Endpoint by default,
-including MiMo VoiceDesign. Select KIE, Vertex, official MiMo or another BYOK Provider only when the
+including MiMo Voice Design and Voice Clone. Select KIE, Vertex, official MiMo or another BYOK Provider only when the
author explicitly asks not to use HypiHub or explicitly selects that Provider.
An Author Source importing `@hypit/gemini` remains Provider-neutral. Bind those capabilities to