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): rebuild video direction knowledge around real work

kashorindc006ae0c07c
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.md
index e2b47647..70265dac 100644
--- a/skills/hypit/SKILL.md
+++ b/skills/hypit/SKILL.md
@@ -12,6 +12,12 @@ and ears; image, video, and audio models are your crew; Author Packages are your
is your editing room; the Runtime is the production facility. Keep your understanding revisable as
evidence and Results arrive, and communicate in terms of the work.
+Most work Hypit is asked to clone is creator-led, phone-captured short-form UGC: spoken expression is
+carried by one or more A-roll performances while B-roll, Caption and MG reshape what the viewer sees.
+Use this as a practical prior when evidence is incomplete, not as a definition of valid work. When the
+reference or Brief establishes independently narrated, speechless, animated or another kind of work,
+direct that form on its own terms.
+
## Two loops, one director
Understanding a reference is a loop between coarse and fine: the whole-piece reading tells your eyes
@@ -25,17 +31,30 @@ design itself changes. Brief changes when the user's goal or constraints change.
Create project components as normal production work. Let the authorized media requests complete and
continue downstream; refine deterministic Caption, MG, Effects, and composition through Studio and
-rendering, reusing produced media through Run Candidates. Additional paid generation requires a new
-explicit decision, whether the request changes or is deliberately repeated. Environment, creation,
-and production are rooms you enter whenever the current question leads there.
+rendering, reusing produced media through Run Candidates. Environment, creation, and production are
+rooms you enter whenever the current question leads there.
-## What never changes
+## Standing responsibilities
- **Money.** Before paid work, including observation and transcription, explain the actual requests,
selected Endpoints, Provider price sources, and estimated cost or what remains unknown. For a Build,
use `hypit plan` with the selected Runtime Profile. Proceed under existing authorization that covers
- the work and cost; obtain it when missing. Additional requests or a materially changed paid plan
- need a new decision.
+ the work and cost; obtain it when missing. Additional generation, including a repeated attempt,
+ needs an explicit decision covered by that authority. A request to rebuild or fix downstream work
+ does not by itself authorize regenerating unchanged media. Keep the selected Provider and account.
+ Changing either requires the user's explicit choice after its capability, price and account effects are
+ clear. Authentication, quota, rate or service failure calls for diagnosis rather than making that choice;
+ HypiHub follows the same rule as every other Provider.
+- **Existing work.** When revising or retrying, preserve usable produced media through explicit Run
+ Candidates and retain unrelated selections. Inspect project Results, including useful Outputs from
+ failed Builds; an absent exported file does not mean the Output was never produced. A new Build
+ does not automatically reuse an earlier one. Before submission, check that `plan` contains only
+ the new media requests the current work actually needs. Correct accidental generation before spending.
+- **Execution.** A Build is one execution attempt. When a watching terminal closes or times out,
+ Runtime status establishes whether that Build is still running; stopping `--follow` only detaches
+ the observer. After execution fails, preserve available Outputs in a new Run and submit a new Build.
+ [Builds](references/production/builds.md#continue-after-a-failed-attempt) explains failed Provider
+ submissions, including a timeout with no task receipt.
- **Secrets.** The Runtime Profile selects Credential Stores and references; Endpoints declare their
credential slots and acquisition flows. Manage credentials through `hypit auth` and the selected
store's supported setup. Report configuration status while secret values remain in the store.
@@ -51,6 +70,9 @@ and production are rooms you enter whenever the current question leads there.
casting, art direction, shots, performance, Caption, components, prompts, and implementation. Ask
when a decision requires user authority that the Brief, references, existing preferences, or
spending approval do not provide. Otherwise decide and continue.
+- **Project ownership.** Preserve unrelated Source, Recipe, Run, assets, and project-package work.
+ Make production changes at their owning source; keep Result media intact. New reusable behavior
+ belongs in a project component, without patching the installed Distribution for one video.
- **Done means watched.** Watch the actual deliverable and judge it against the Brief, Treatment,
and relevant reference relationships. Also judge the work's clarity, performance, rhythm, visual
and sonic coherence, and suitability for publishing. Deliver the work with the important choices
@@ -60,8 +82,9 @@ and production are rooms you enter whenever the current question leads there.
| When the question is about | Read |
| --- | --- |
+| how Source, media, Tracks, execution and Results connect | `references/production/system.md` |
| the `hypit` command is unavailable, or installing or updating the executable Distribution | `references/environment/distribution.md` |
-| what this machine can do, a credential, or choosing a Provider | `references/environment/profile.md` |
+| what this machine can do, credentials, Model/Provider/Endpoint choices or shared capacity | `references/environment/profile.md` |
| a local binary, WhisperX, or a Managed Program that will not come up | `references/environment/local-tools.md` |
| understanding a reference video or link | `references/creation/reference-video.md` |
| defining the target: what the user asked for, and what the new piece will be | `references/creation/brief.md` |
@@ -69,11 +92,23 @@ and production are rooms you enter whenever the current question leads there.
| the words, Cues, durations, and semantic time | `references/creation/script-and-time.md` |
| how the project is laid out, or picking work back up | `references/creation/project-files.md` |
| writing Sources, Recipes, and Runs, reusing produced work, adding a component | `references/production/authoring.md` |
+| imports, output references, literal values or Recipe rules | `references/production/source-syntax.md` |
+| Run syntax, Targets, Candidates, Run Fragments or substitute media for a preview | `references/production/runs.md` |
+| admitting media, normalization, SemanticTakes, still clips, trims or extraction | `references/production/media.md` |
+| Canvas, Frames, aspect, fitting, cropping or coordinate relationships | `references/production/spatial.md` |
+| font resources, multilingual text, Emoji, titles or rich Typography | `references/production/fonts-and-text.md` |
| which installed Surface to use, or whether to write a project component | `references/production/vocabulary.md` |
-| `plan`, `build`, following work, Results and exports | `references/production/builds.md` |
-| looking at Studio or a finished Result and deciding what to fix | `references/production/review.md` |
-| the shape of a format, or one craft problem: Caption, B-roll, voice, sound, graphics | `references/playbooks/index.md` |
+| sharing a project component or Prompt Kit across projects | `references/production/component-sharing.md` |
+| composing performance, Media, Audio, Caption, Text, MG and Effect Tracks | `references/production/tracks.md` |
+| writing a project Track with new layout, semantic events or persistent state | `references/production/track-authoring.md` |
+| drawing a component's elements, animation, resources or prepared surfaces | `references/production/component-visuals.md` |
+| writing a Caption family with new word relationships, scheduling or layout | `references/production/caption-authoring.md` |
+| `plan`, `build`, a retry or interrupted submission, following work, Results and exports | `references/production/builds.md` |
+| opening Studio, understanding its views and edits, or adding a component Companion | `references/production/studio.md` |
+| Film assembly, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` |
+| judging the preview or finished Result and deciding what to fix | `references/production/review.md` |
+| the shape of a format, or one craft problem: image direction, Caption, B-roll, voice, sound, graphics | `references/playbooks/index.md` |
Several rows can apply at once; read what the work actually asks for, and return to a room whenever a
-preview or Result raises its question again. The owning package README supplies exact syntax,
-Surfaces, and model limits.
+preview or Result raises its question again. These references explain production use; installed
+package vocabulary and package-local documentation supply exact attributes, APIs and model limits.
diff --git a/skills/hypit/references/creation/project-files.md b/skills/hypit/references/creation/project-files.md
index f8d948df..33239f37 100644
--- a/skills/hypit/references/creation/project-files.md
+++ b/skills/hypit/references/creation/project-files.md
@@ -4,6 +4,37 @@ Read this when starting, resuming, or reorganizing a video project. The layout b
convention, not syntax: Hypit resolves ordinary paths and does not assign meaning to these directory
names.
+## Establish the project boundary
+
+Run commands from the video project's root. A small `package.json` makes that root explicit and
+can later hold the project's component dependencies:
+
+```json
+{
+ "name": "workshop-video",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module"
+}
+```
+
+The CLI uses the nearest `package.json` above the command's working directory, or that directory
+itself when none exists. Passing a Source or Runtime path does not select a different project.
+Sources can live below the root, with file and Source imports relative to the declaring file.
+
+| Boundary | When to set it explicitly |
+| --- | --- |
+| `--workspace <directory>` | Choose the Source containment root when running from another directory |
+| `--asset-root <directory>` | Admit assets stored elsewhere while keeping Source imports in their workspace |
+| `--package-root <directory>` | Resolve project packages from another installation location |
+
+For example, `hypit check authors/main.svml --asset-root /path/to/shared-media` admits intentionally
+referenced shared media. Keep the same relevant boundaries for subsequent commands. An ordinary
+project uses its own package installation; reserved `@hypit/*` packages come from the selected
+Distribution. [Distribution](../environment/distribution.md) explains locating that executable,
+and [component vocabulary](../production/vocabulary.md#let-ordinary-package-management-own-distribution)
+explains installing project packages.
+
## 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
@@ -45,15 +76,15 @@ 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/
+references/viral-ad/
+productions/product-version/
+productions/short-version/
```
-Each production links to `../../references/darby/` from its own Brief or Treatment and keeps its own
+Each production links to `../../references/viral-ad/` 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
+The CLI finds the project from the command's working directory as described above; 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.
@@ -71,7 +102,10 @@ referenced in place; its documentary role does not require a duplicate.
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.
+ blockers, active Build ids and reusable Results. When handing work over, retain the relevant Run
+ and Runtime Profile, exact Build id and public Output names needed to continue. Run Candidates own
+ the actual reuse choices; the note points to them. 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
@@ -93,3 +127,9 @@ After interruption or context compaction, read the current Brief, Treatment, ref
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.
+
+A command interruption or missing reply can leave the Worker running. [Builds](../production/builds.md)
+explains how to identify active work and continue through a new Run after a failed attempt, including
+a Provider submission timeout with no receipt.
+Completed Outputs remain in Results without being exported as files. Keep or add their Run Candidates
+when revising downstream work; neither the notes nor an unchanged output name selects them automatically.
diff --git a/skills/hypit/references/creation/reference-video.md b/skills/hypit/references/creation/reference-video.md
index 1b29a558..164e4d74 100644
--- a/skills/hypit/references/creation/reference-video.md
+++ b/skills/hypit/references/creation/reference-video.md
@@ -10,11 +10,13 @@ ears, and local media commands to prepare a closer view. The tools report eviden
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:
+Begin by watching the whole piece. Spoken language carries most work Hypit is asked to clone, so obtain
+and read its word-level transcript and use it as the normal time spine. If the piece is genuinely
+speechless, establish that spine from its actions, visual changes, music, effects and silence. 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;
+- how speech or silence carries the piece, who speaks when present, 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.
@@ -89,18 +91,21 @@ spoken display system: words, Cues, speaker or role, activation, placement, and
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.
+Name the material for an important observed fact when its provenance will help another Agent trust,
+reopen or correct it: “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. Ordinary connected
+description need not repeat the citation in every sentence. 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.
+after a pause, a Caption Cue spans a phrase, or an effect continues through a cut. In the usual spoken
+work, word-level evidence lets the director identify what an event means and later bind it to Script.
+A genuinely speechless work locates meaning through action, visual change, music, effects and silence
+instead. Read `script-and-time.md` when turning those observed relationships into the target's Script
+identities and timing.
## Keep the archive complete and revisable
diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.md
index 0788ce8f..4a88963a 100644
--- a/skills/hypit/references/creation/script-and-time.md
+++ b/skills/hypit/references/creation/script-and-time.md
@@ -1,13 +1,20 @@
# 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.
+Read this when structuring Script, balancing spoken delivery across generated Takes, or attaching
+pictures, Captions, MG, Effects, and Audio to what is said. It also explains how a passage with no
+spoken words receives semantic boundaries. The installed `@hypit/script` vocabulary
+and package README supply exact marker spellings and parsing details.
+
+[Source syntax](../production/source-syntax.md) covers the surrounding imports, references, Recipes
+and Runs; [Tracks](../production/tracks.md) covers the consumers of Script meaning.
+[Media preparation](../production/media.md) explains connecting actual footage to a Segment, and
+[Runs](../production/runs.md) explains choosing estimated timing for a layout study.
## 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
+visual Style parameters, prompts, or provider decisions. Semantic word attributes such as
+`useful{emphasis}` can identify a word's role for a Caption family. 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:
@@ -29,10 +36,25 @@ Use Script's distinct authoring concepts for distinct jobs:
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.
+Script also represents passages without speech:
+
+```svml
+<script id="story">
+ <empty></empty>
+</script>
+```
+
+`empty` is an ordinary Segment name; a name such as `product-detail` can express the passage's role.
+No words does not mean no semantics: the Segment retains its identity and start/end anchors. Its
+associated normalized media determines the duration, and its SemanticTake has an empty word array.
+The same SemanticTrack and Track timing vocabulary apply to a wordless passage or an entire
+speech-free piece. The empty tag itself declares neither a zero-length interval nor a duration.
+
+Choose Segment boundaries from natural production passages and delivery length, not from every
+picture cut. One Segment and Take can carry several speaking turns, camera cuts or a split-screen
+conversation. One continuous narration can carry many B-roll changes through Selections. Edited UGC
+can deliberately use several Takes driven by the same character-and-scene image; a natural cut is
+often part of its appeal. A Role change or `||` does not require another generation.
## Author Caption rhythm, not a word-count rule
@@ -49,7 +71,7 @@ being forced into spoken Caption Cues.
## Measure before choosing durations
-Generated Takes require a literal `duration`, so measure the adopted wording before choosing that
+For generated speaking Takes that require a literal `duration`, 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:
@@ -72,6 +94,9 @@ media to request. The aligned words answer where Caption, B-roll, MG, and Effect
media. Alignment measures real word positions inside that media envelope; it does not reproduce an
estimated distribution of words.
+For a wordless Segment, choose the requested duration from the action, music or visual rhythm.
+Speech-rate measurement has no role there; the resulting media still determines its Segment span.
+
## Bind meaning to Script identities
For a picture, Caption treatment, MG state, sound, or effect that belongs to spoken meaning, author a
@@ -80,8 +105,9 @@ 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.
+when the design intentionally includes an adjacent gap or structural boundary. The `@hypit/script`
+package README owns the marker spellings. For adjacent B-roll that should not reveal the underlying
+picture, use the shared-boundary examples in [B-roll craft](../playbooks/craft/b-roll.md).
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
diff --git a/skills/hypit/references/environment/local-tools.md b/skills/hypit/references/environment/local-tools.md
index 7eac452b..b21a060d 100644
--- a/skills/hypit/references/environment/local-tools.md
+++ b/skills/hypit/references/environment/local-tools.md
@@ -15,12 +15,6 @@ 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.
diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.md
index 848b3f3b..35bf851f 100644
--- a/skills/hypit/references/environment/profile.md
+++ b/skills/hypit/references/environment/profile.md
@@ -3,6 +3,9 @@
Read this when a project needs an execution environment, a credential, another Provider, or an
explanation of what the current machine can actually do.
+[System relationships](../production/system.md) explains how authored work reaches these facilities;
+[rendering](../production/rendering.md) explains picture, audio and frame-range requests.
+
## Start from the work's capabilities
The environment is sufficient relative to the work, not as a global state. Read the Brief,
@@ -47,6 +50,80 @@ The Profile itself contains only environmental choices:
Read each selected Provider README for its accepted configuration and capability support. Installing
a package only makes it available; a Profile entry selects it.
+## Connect Model, capability, Need and Endpoint
+
+These names describe different facts about the same work:
+
+| Term | Meaning in production |
+| --- | --- |
+| Model Package | Owns the authored request and result semantics, including the exact model choice and supported input form. It does not choose an account or service URL. |
+| Capability | The versioned operation an implementation must support. Generation, rendering, media processing and alignment all have capabilities. |
+| Need | One concrete external request produced by the selected graph, with its capability and actual inputs. One Build can produce many Needs. |
+| Provider Package | Implements capabilities through a vendor API or local process, including credentials, invocation, polling, resource transfer, capacity and diagnostics. |
+| Endpoint | One configured instance of that Provider, using a particular account or deployment. Several instances may use the same Provider package. |
+| Binding | The Profile's explicit choice among Endpoints offering the same capability. |
+| Runtime Worker | Advances submitted Builds, reserves shared capacity for their Needs and follows submitted external operations. |
+
+For example, an authored video request determines what to generate. The Run can satisfy its output
+with an existing Result so that generation is no longer demanded. If it remains demanded, the Model
+produces a Need; the Profile resolves its capability to one Endpoint; the Provider maps that request
+to the chosen service. The same author semantics can therefore work through BYOK or HypiHub when
+both implement the exact capability, without putting those account choices into SVML.
+
+A binding key is the complete `name@version#capability`, not a guessed vendor model label. For
+example, this Profile fragment selects local alignment when multiple Endpoints offer it:
+
+```json
+"bindings": {
+ "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"
+}
+```
+
+That Endpoint must actually be declared and support the capability. A single eligible Endpoint
+needs no binding; multiple unbound choices are an error. Use the Model and Provider READMEs and
+`plan` to establish actual support rather than inferring compatibility from similar model names.
+
+## Set capacity at the resource it describes
+
+The Runtime Worker and HyperFrames `workers` are different things. The Worker schedules many Builds;
+HyperFrames workers are independent Chrome processes within one active render Need. There is no
+per-Build worker count or extra Build-wide concurrency limit to coordinate all models.
+
+| Control | What it limits |
+| --- | --- |
+| Endpoint total concurrency, commonly `config.defaultConcurrency` | Simultaneous requests across Builds using that resource |
+| A Provider's exact-model limit, where supported | A narrower quota within its total capacity; read that Provider's accepted configuration |
+| Endpoint `pool` | Shared resource identity for instances using the same real account, deployment or compute budget |
+| Endpoint action limits, where supported | Concurrent `submit`, `poll` or `collect` calls and starts admitted within a time period; these are distinct from remote tasks in progress |
+| HyperFrames `config.workers` | Chrome processes requested by one render; this is work size |
+| HyperFrames `config.browserCapacity` | Chrome slots shared by render Needs; each reserves its actual worker count alongside one request slot |
+
+For example, two local render Endpoint instances using 4 and 2 workers can share a pool with
+request capacity 2 and browser capacity 6. Both fit together. With browser capacity 4, one waits;
+a single request larger than the configured browser capacity is a configuration error. These are
+illustrative budgets, not universal machine recommendations. Increasing workers can increase memory,
+decode and I/O pressure; inspect actual progress before attributing every delay to capacity contention.
+The selected frame range belongs to the render request, while worker policy belongs to the Endpoint.
+
+Configure these choices in the Runtime Profile's Endpoint entries, using each Provider's documented
+fields. All instances sharing a resource must agree on its limit; use different pools for genuinely
+independent resources. Kie and HypiHub use the same capacity-reservation mechanism, but separate
+accounts do not share a pool merely because they offer the same model.
+
+Capacity reservations coordinate Builds sharing the same Runtime Execution Store. They are not a
+cross-machine account quota service. An accepted asynchronous Operation retains its task-capacity claim
+while it is pending, including between polls and across a Worker restart. Each short `submit`, `poll` or
+`collect` call can separately consume action concurrency and rate; the call releases its concurrency when
+it ends while a rate budget continues for its declared period. If an Endpoint action fails, that Operation
+and Build attempt fail and their local capacity claims are released; any receipt, last remote status and
+error remain evidence. Disconnecting a CLI observer does not change any of these facts. Studio's permitted
+transient work has session-local concurrency and does not consume durable Build capacity claims.
+
+Read the installed `@hypit/runtime-local` README for the shared model and the selected
+`@hypit/provider-hyperframes-local`, `@hypit/provider-kie` or `@hypit/provider-hypihub` README for
+accepted settings. Use `hypit activity` to inspect actual claims. After changing a Profile, follow
+[Worker reload guidance](../production/builds.md#reload-changed-execution-code-deliberately).
+
## Begin with the Distribution starter
From the project directory:
@@ -84,15 +161,16 @@ cost, privacy, setup time, or control.
- 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
+- Offer HypiHub as the official hosted option 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,
+execution to HypiHub changes the Profile or its binding explicitly; an authentication error, exhausted
+quota, rate limit or service failure never authorizes that switch or a different billing account.
+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
diff --git a/skills/hypit/references/playbooks/craft/b-roll.md b/skills/hypit/references/playbooks/craft/b-roll.md
index 463aa920..b71a48ba 100644
--- a/skills/hypit/references/playbooks/craft/b-roll.md
+++ b/skills/hypit/references/playbooks/craft/b-roll.md
@@ -1,122 +1,119 @@
+# B-roll and semantic coverage
+
+B-roll adds evidence, association, humor or another view over the passage that carries the speech.
+It can be a photograph, an illustration, a screenshot, generated motion or existing footage.
+Choose the material for what the viewer needs to understand, not from a rule that every noun needs
+its own video generation. Keep the speaking performance's sound when covering its picture.
+
+## Let people live inside B-roll
+
+B-roll is defined by what the picture contributes, not by whether a person appears in it. Creator-led
+social video commonly covers a speaking performance with the same person's life: working, studying,
+driving, exercising, travelling, using a product or reacting inside another situation. These shots can
+make the work feel inhabited and socially credible while remaining B-roll.
+
+A person visible while words are heard is not by itself evidence that the pictured clip produced those
+words. Read the whole passage: the picture may be a silent lifestyle action covering audio from the
+underlying A-roll, or it may be another visible speaking performance whose own delivery carries the
+line. Preserve those as separate sound and picture relationships. [Voice and performance](voice-and-performance.md)
+owns the choice of speech source.
+
+## Decide how closely the pictures follow the words
+
+**Exact correspondence** is useful when the reference or explanation depends on a particular image
+being present for a particular claim. Give each scene a Selection and its own media input. A short
+window can play just the needed beginning or authored source trim of a longer generated clip.
+The selected model's minimum generation length does not set a minimum display length.
+
+**A montage over a thought** is useful when several scenes collectively communicate a habit, history
+or attitude. The podcast example supplies three lifestyle images to one short B-roll request,
+directs the scene order, and places the result over one broader Selection. Each noun need not land
+on a cut for the idea to read. This trades precise correspondence for a compact, lively sequence;
+it is not a substitute when reconstruction requires the original's exact correspondence.
+
+The B-roll Kit's `story` Text directs scene order and a few meaningful actions. Select compatible
+edit choices for that story. A multi-scene montage with cuts should not also ask for one uninterrupted
+shot; if each scene should be continuous internally, say that explicitly. Keep motion understated
+when posture, context and a small action already communicate the event.
+
+## Distinguish generated length, source sampling and display window
+
+A Selection determines where an Item is active in the program. Its Recipe determines which source
+frames it samples there. They are separate decisions. `@hypit/media-track` owns exact playback and
+trim syntax; moving inputs are explicitly normalized before entering the Track.
+
+For the natural moving coverage discussed here, prefer one native-speed pass: `playback: once-start`.
+Give a montage enough room to finish when all its scenes matter. A Selection slightly longer than
+the actual clip is fine when returning to the underlying picture at the clip's end is intended.
+A shorter Selection deliberately cuts the clip off. Do not fill the extra time with a frozen tail,
+repetition or automatic retiming merely to occupy every frame of that Selection.
+
+- `once-start` plays from the beginning at native speed. A shorter window cuts the source off; a
+ longer window outlasts the material and can reveal what lies beneath.
+- `stretch` retimes the selected source range across the whole window. A shorter window compresses
+ all scenes; a longer one slows them. Very brief scenes may read as a flash even if sampled.
+- `hold-start` plays once, then freezes the last frame if the Window is longer. This frozen tail is
+ usually distracting in natural lifestyle coverage. Hold, loop and stretch belong to an explicitly
+ intended freeze, repetition or retiming effect, rather than the default treatment of these clips.
+- A durationless still has no playback or source trim. Its Item's window determines its presence;
+ authored spatial motion can move it without pretending it is generated video.
+
+For example, take a five-second montage whose last scene starts at 3.5 seconds. If a window lasts
+three seconds, `once-start` never reaches that scene. A 5.2-second Window permits the entire clip to
+play at native speed, including the last scene's 1.5 seconds. For the remaining 0.2 seconds the clip
+no longer covers the picture beneath; it does not hold its last frame. These numbers illustrate
+the relationship, not a required montage duration or a fixed amount of extra room.
+
+## Let picture and speech hand over at different moments
+
+A montage can stay up after its subject finishes speaking. In the podcast example, the partner
+starts responding while the last lifestyle picture is still visible, and their camera returns
+later. This incoming voice before its picture forms a J-cut relationship and gives the montage room.
+The B-roll does not need to contain that speech: the speaking Track's audio already continues beneath.
+
+Choose the endpoint by the thought, reaction and visual reading time. Extending coverage across a
+Role turn is legal; a Selection can also cross a Segment boundary. Avoid cutting the final scene
+short just to make the visual endpoint coincide with the original speaker's last word.
+
+## Join adjacent coverage on the same boundary
+
+For separate clips that should cover a passage without briefly exposing the A-roll, both sides of
+each shared boundary must select the same instant. Default markers close on the previous word's end
+and open on the next word's start, leaving their intervening pause uncovered.
+
+```text
+@coffee my coffee @/coffee ~@smoothie my smoothie @/smoothie
+```
+
+Here both sides meet at the end of “coffee”; the smoothie picture owns the pause. Alternatively:
-# B-roll craft
-
-B-roll is authored visual evidence, context, or emotional progression outside the primary speaking
-take. Every insert must earn its place in the story and remain independent from editorial text and
-program audio.
-
-## Full-screen B-roll of the same speaker
-
-A reference may cover the whole frame with the same speaker in a second location while their voice
-continues: the picture cuts away to the person whose voice is heard, shown silent in another setting.
-This is B-roll, and the base stays the primary take. `../../reconstruction/continuity.md` owns the rule — the picture that
-shows the speaker saying the words is the base, whoever else fills the frame. Author the second
-location exactly like any other B-roll: vendor `broll-v1.svs`, one shot per beat, placed over the
-Script Selection with `during=`.
-
-The speaking kit's scene contract governs the base take, and applies only to it.
-`street-interview-v1`'s "SINGLE-SCENE CONTRACT" keeps both people in the same street scene; a covering
-cutaway in a classroom, an office or a product room is a separate picture and a separate kit. B-roll
-carries its own `duration` on the generation, so the speech take's length does not bound it.
-
-## See it before you generate it
-
-Where a cutaway lands, how long it holds, and whether its Frame sits in the right part of the
-picture are all decided by the Source, not by the footage. Hypit Studio answers all three without a
-generation, provided the Run satisfies the material it places: cut points come from the aligned
-`SemanticTrack`, so where a cutaway falls against the speech is measured rather than guessed.
-
-Satisfy the B-roll outputs in the Run Source with whatever footage you already have before expecting
-to see the placement: an Item whose material no Candidate supplies makes the whole Run unopenable.
-
-Do this after placing a Selection and before paying for a generation. Startup and arguments are in
-`docs/quickstart/preview.md`; for how to see placed items against their real frames, read
-`../../preview.md` and start Studio.
-
-## Choose the story beats first
-
-- Write the shot list before writing prompts. Give every shot one clear job: establish context, show
- a problem, demonstrate failed effort, reveal a mechanism, provide proof, or deliver a payoff.
-- A useful product arc is **problem → failed effort → mechanism/product → payoff**, but the number of
- beats follows the actual story rather than a fixed template.
-- Adjacent shots must contribute different information. Change the location, camera relationship,
- action, prop relationship, evidence, or emotional state; a cosmetic crop is not a new shot.
-- Decide whether each beat needs generated motion, a supplied image, a supplied video, or an authored
- graphic before choosing components.
-
-## Author generated B-roll in SVML
-
-1. Put the reference-frame prompt in an English `copy:Value` and generate the image with an explicit
- image Surface such as `gpt:Image`.
-2. Vendor `broll-v1.svs`, choose the stable material/story/edit/camera/motion axes in an SVS Recipe,
- and put only the shot-specific micro-story in an English `copy:Value`.
-3. Render the Kit with `copy:Render` and connect the story through `copy:Set`.
-4. Generate through `seedance:ReferenceVideo` with `generate-audio="false"` and explicit ordered
- references.
-5. Place shots with `media-track:Track` and `media-track:Item` or `media-track:Sequence`.
-
-```svml
-<copy:Value id="demo-story">
- The hand places the device on the desk, wakes the screen, and pauses as the result becomes visible.
-</copy:Value>
-
-<copy:Render id="demo-prompt"
- template={broll-kit.broll-v1} recipe={recipes.broll.screen-demo}>
- <copy:Set name="story" text={demo-story}/>
-</copy:Render>
-
-<seedance:ReferenceVideo id="demo-motion" model="mini"
- prompt={demo-prompt} duration="6" resolution="720p"
- aspect-ratio="9:16" generate-audio="false">
- <seedance:Reference image={demo-frame.image}/>
-</seedance:ReferenceVideo>
+```text
+@coffee my coffee @/coffee~ @smoothie my smoothie @/smoothie
```
-Use the model limits and prompt rules in `seedance-directing.md`. Generated B-roll supplies pictures
-only; narration, music, and effects remain explicit audio contributions.
-
-## Design the image and motion prompt as one package
-
-- The image prompt establishes every visible fact: subject, identity, location, wardrobe, props,
- object count, camera geometry, emotion, and initial physical state.
-- The video story adds only motion over those established facts. Audit every person, object,
- relationship, and emotional starting point in the video text against the accepted image.
-- Direct one or two readable events with macro action and small facial/postural feedback. Do not add
- a new room, person, outfit, prop, or unexplained camera angle during the shot.
-- Give every manipulated object a plausible starting contact and short motion envelope. Preserve its
- count, shape, label, and distinctive physical features throughout the take.
-- When a document, device screen, receipt, or product label must stay unchanged, use a continuous-shot
- edit language and a reference-locked camera treatment.
-
-## Place B-roll by authored meaning
-
-- Mark the intended spoken range as a Script `Selection`, pass `semantic={speech.semantic}` to the
- Track, then use `during={story.selection.NAME}` on the Media Item.
-- For a point event, declare a Script `Moment` and use `at={story.moment.NAME}` with an explicit `for`.
-- For intentionally absolute edits, use `during="program"` or explicit `start` and `end` expressions
- in the shared SemanticTrack frame domain.
-- A Selection is one contiguous range. Author separate named Selections and Media Items when the same
- insert should appear again later.
-- Create J-cuts and L-cuts in the Script boundaries: let narration establish a few words before the
- B-roll opens, and let speech continue before or after the picture returns. Do not make every visual
- cut start and end exactly with a complete spoken sentence.
-
-## Protect screens, text, and reverse views
-
-- Keep physical UI and product text attached to the screen, label, document, or sign. Put editorial
- titles, arrows, comparisons, and cards on `typo:Track` or `media-track:Track`.
-- When exact UI or brand artwork matters, use the supplied asset as authored media rather than asking
- a generator to recreate it.
-- A person-facing view and its device-facing reverse view must satisfy the explicit geometry rules in
- `visual-continuity.md`: opposing camera positions require different background sectors and different
- dominant landmark sets. The same main background is an automatic rejection.
-- Follow `screen-demo.md` for context/proof pairs and physically possible screen orientation.
-
-## Accept and reuse shots
-
-- Review each generated image before its video, then review each video before Track assembly.
-- Reject identity drift, same-background reverse views, impossible contact, duplicated props,
- unstable screen content, unwanted text, broken end frames, or motion that does not start from the
- accepted reference.
-- Pin accepted image and video outputs in the next `.svrun` with `build-record` and `satisfy`, so
- only failed shots are regenerated.
+Both sides now meet at the start of the next “my”; the coffee picture owns the pause. Keep both
+sides left-affine or both right-affine at each join. `||` may also sit between those phrases, but it
+only authors Caption grouping and cannot close a visual gap. The `@hypit/script` README owns the
+complete marker grammar.
+
+These joins handle internal pauses. If coverage must also include lead-in or trailing silence,
+choose outer boundaries that cover those edges through the Track's actual timing vocabulary.
+Inspect media exhaustion, fades and component visibility too: touching windows alone cannot make
+an exhausted or transparent visual cover the frame. See [Frame coverage](frame-coverage.md).
+
+## When the pictures carry the whole passage
+
+The same media tools can form a music-led montage or a tactile process film with no underlying
+speaking picture. Then the images are the main sequence rather than coverage. Choose cuts from the
+visual argument, musical phrase or physical action; a fixed hook/detail/CTA shot count is not a
+requirement. Adjacent images should earn their change through a new view, information, attitude or
+rhythm. A closer crop can be a meaningful beat when it reveals something the wider shot did not.
+
+For quiet material or ASMR-like work, the contact point, texture, action and sound can carry attention.
+Keep the decisive action visible and let small changes finish; camera movement and extra cuts should
+serve that sensation. Synchronized generated sound, recorded sound or separately authored sound can
+each be appropriate. [Sound and mix](sound-mix.md) covers their relationship.
+
+When a work is genuinely speech-free, its visual, musical and action relationships still need
+authored semantic boundaries. [Media preparation](../../production/media.md#wordless-passages-use-media-boundaries)
+owns how actual media supplies them.
diff --git a/skills/hypit/references/playbooks/craft/caption-tracking.md b/skills/hypit/references/playbooks/craft/caption-tracking.md
new file mode 100644
index 00000000..448b0f95
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/caption-tracking.md
@@ -0,0 +1,94 @@
+# Caption above a moving head
+
+Use this when following a person's head adds character or keeps Caption clear of the image. The
+street-interview example uses external face measurements, authored head regions and Fine's existing
+placement input. The detector measures evidence; the author decides the Caption design.
+
+## Produce the footage that will actually be measured
+
+Build the speaking media and an ordinary composition first, using fixed Caption if useful. Keep the
+Run's exact media and SemanticTake outputs available for reuse. A final-video Target can produce
+those dependencies.
+
+Measure footage whose timing and framing match the next composition. An existing rendered result
+can work when its graphics do not obstruct detection. A clean picture pass is useful when they do;
+it can reuse the same normalized Takes and layout. If measuring individual Takes instead, use their
+actual edited lengths and project their local frame positions into the final program. Do not measure
+an original raw file and silently assume its timestamps survive later trim, speed or crop changes.
+
+## Obtain useful boxes outside Build
+
+The worked method used Google Video Intelligence. Its face feature can return bounding boxes when
+`FACE_DETECTION` is requested with `includeBoundingBoxes` enabled; facial attributes are unnecessary
+for this placement task. Use the installed tool or the provider's
+[face-detection example](https://docs.cloud.google.com/video-intelligence/docs/samples/video-detect-faces)
+for actual invocation and existing authorization for any paid request. Another suitable detector or
+manual measurement can supply the same authored data.
+
+GVI's timestamped boxes are observations, not Script Roles or ready-to-use Hypit head tracks. Its
+[response schema](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1/AnnotateVideoResponse#TimestampedObject)
+expresses `timeOffset` relative to the input video and the rectangle as `normalizedBoundingBox`.
+Use all relevant observations, not just the first box printed by a sample program.
+
+Associate each visible person with the intended Role by inspecting the footage. A detection id is
+not a global person identity, and a cut can create another track for the same guest. In a shared
+shot, selecting the largest face alone can attach the guest's Caption to the interviewer.
+
+## Author one head region per final program frame
+
+Transform the useful observations into ordinary project data, with these decisions explicit:
+
+- **Clock:** resample onto the actual ProgramSpace frame rate. For concatenated normalized Takes,
+ the local-to-global offset is the sum of preceding Takes' actual frame counts, not their requested
+ generation durations. Final-video measurements are already on the global timeline.
+- **Geometry:** convert detector edges to `[x, y, width, height]` using width `right - left` and height
+ `bottom - top`. If measurement used another resolution, crop, inset or split-screen panel, map the
+ box through that actual placement before normalizing it to the final Canvas.
+- **Head extent:** expand the face region to include the relevant hair, hat and desired clearance.
+ For face `(x,y,w,h)`, authored padding fractions can produce
+ `(x - pL*w, y - pT*h, w*(1+pL+pR), h*(1+pT+pB))`. Choose those fractions from the visible head;
+ there is no universal face-to-head multiplier. Keep the resulting region valid inside the Canvas.
+- **Missing observations:** make any interpolation or smoothing an explicit external preparation
+ choice within a continuous shot and the same person. Inspect it, stop at cuts and occlusion, and
+ write `null` when no usable region exists. Fine does not invent a missing box.
+
+The final array has exactly one box or `null` per program frame, including frames where the Role is
+absent. Caption already follows the Role's spoken Cues; the region track supplies position, not a
+second speech detector. Additional visibility choices, such as hiding that Role's Caption under
+B-roll, can be authored with null regions or the appropriate Caption selection behavior.
+
+For example, this is a three-frame data-shape illustration, not a ready timeline for a real video:
+
+```svs
+heads.default {
+ frame-count: 3;
+ tracks: [
+ {"id":"GUEST","regions":[[0.12,0.09,0.20,0.26],null,[0.13,0.10,0.20,0.26]]}
+ ];
+}
+```
+
+Keep the actual array in a project Recipe such as `tracking.svs`. A small project script can make
+these transformations reproducible when needed, taking explicit media, clock and geometry inputs.
+
+## Connect the measured placement and render again
+
+```svml
+<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
+<caption-fine:Track id="captions" document={story.caption}
+ semantic={speech.semantic} program={caption-program} regions={heads}/>
+```
+
+The RegionTimeline's ids match Script Roles. Fine places a single-Role Cue at that region's top
+center; `anchor-x: center` and `anchor-y: bottom` put the Cue above it. The Style still owns its width,
+font and motion. A named Role track with `null` hides its Cue on that frame; a Role with no region
+track uses its ordinary Style position. This allows tracked guest Caption and fixed interviewer
+Caption together. The `@hypit/spatial` and `@hypit/caption-fine` READMEs own the exact data behavior.
+
+Select the existing media and alignment outputs in the Run as described in
+[production authoring](../../production/authoring.md#reuse-produced-work-explicitly), then inspect
+`hypit plan` before rebuilding. A Caption placement change should reuse the paid Takes. Review
+representative frames, camera cuts and the moving result for jitter, wrong-person jumps, hair/hat
+clearance, top-edge clipping and collisions with icons. Local frame-range rendering makes these
+iterations cheap. If media timing or placement changes, update the affected measurements rather
+than reusing stale coordinates.
diff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.md
index c90f8c70..4d8e854d 100644
--- a/skills/hypit/references/playbooks/craft/captions.md
+++ b/skills/hypit/references/playbooks/craft/captions.md
@@ -1,189 +1,72 @@
# Caption craft
-Captions are one program-wide interpretation of the authoritative Script, measured against the real
-speech program. Do not create separate caption systems for speakers, regions, or styles.
-
-## What is a caption is decided by the words, not by the styling
-
-**Text that arrives with speech and reads exactly what is being said is a caption.** That is the
-whole test, and it is checkable rather than a judgement: the words match the transcript verbatim, and
-they appear as those words are spoken. A reference video's word-level transcript is prepared for
-exactly this comparison.
-
-Nothing about how it is drawn changes the answer. A caption may be set in two typefaces, sit on a
-coloured slab, arrive a word at a time, be enormous, be decorative, or open the video — and it is
-still a caption. Handsome styling is the commonest reason this gets misfiled, and it is not a reason
-at all.
-
-So it is authored with the caption vocabulary, driven by the Script and the alignment map. Never
-reproduce it as `typo:` or `text:` with the words typed in by hand. That looks equivalent on the
-first frame and is not: hand-typed words no longer follow the Script, so re-recording the line leaves
-them stale, they are unreachable by anything that reasons about captions, and the identity that makes
-them checkable is gone.
-
-When the caption vocabulary cannot express the appearance, that is a vocabulary gap and it is
-declared as one. Write a new project-local caption package that fills the same roles the installed
-caption packages fill — Style, Program, planning and alignment — and drive it from the same Script
-and map. `../../local-author-package.md` says where those roles are stated and when a package's own
-source is worth opening. Reaching for a typography Track because it already draws the shape is the
-mistake this section exists to prevent.
-
-Text that is *not* a caption keeps its own vocabulary: a title nobody says, a lower third, a label on
-a product, an editorial line that paraphrases rather than transcribes. The distinction is whether the
-words are the spoken words.
-
-## Author one caption pipeline
-
-Use one deterministic pipeline for the program:
-
-```text
-exact font → caption-fine:Style → caption:Program
- +
- speech.semantic
- ↓
- caption-fine:Track
-```
+Caption displays the speech as it is being delivered. Its verbal identity and contemporaneous
+relationship to that speech matter more than its size, decoration or placement. A striking animated
+word can be Caption; a title held long after the phrase to label a section can be Typography even
+when those words were also spoken. Their role in the work decides the distinction.
-```svml
-<fonts:Stack id="caption-font" family="inter" weight="700"
- style="normal" emoji="color"/>
-<caption-fine:Style id="primary-caption"
- recipe={recipes.caption.primary} font={caption-font}/>
+Script's Dual Text permits intentional display/pronunciation differences: “2012” and “twenty twelve”
+remain one authored verbal unit. Caption does not require literal equality to a raw transcript.
+Independent titles, lower thirds, labels and editorial paraphrases belong to their own Text or MG role.
-<caption:Program id="caption-program" document={story.caption} narrative={story}
- default={primary-caption}>
- <caption:Use role="HOST" style={host-caption}/>
- <caption:Use selection={story.selection.product}
- style={product-caption}/>
- <caption:Mute selection={story.selection.private}/>
-</caption:Program>
+For implementation of a new visual family, read
+[Caption authoring](../../production/caption-authoring.md). That guide keeps the common text/timing
+chain and shows where the new family owns scheduling and rendering.
-<caption-fine:Track id="captions" document={story.caption}
- semantic={speech.semantic}
- program={caption-program}/>
-```
+## Keep wording and timing in their owners
-Add `{captions.track}` to `film:Film` as one peer Visual Track. If the format intentionally has no
-captions, omit the Caption components entirely.
+Script owns display words, speaking Roles, Dual Text units, attributes and `||` Cue Breaks. Its
+CaptionDocument contains no seconds or frames. Caption joins that truth to the actual SemanticTrack;
+a visual family then presents the timed units. Reuse those units rather than retyping spoken words
+into independent Typography merely because it can draw the desired shape.
-## Moving captions consume finished numeric regions
+Use the produced performance's normalized and aligned audio. A change to that audio, its speed or
+its cuts can change word timing and requires corresponding alignment. A visual-only restyle can
+reuse the same semantic and media outputs through the Run.
-When a caption follows a speaker, measure the face or head before the Build and write the useful
-normalized boxes into an SVS `RegionTimeline`. Intersect that track with the Role's speaking spans:
-the Role has `[x, y, width, height]` only on Frames where that person is speaking and `null` elsewhere.
-Then pass the authored timeline directly to Fine:
+## Start with the Fine family's real expressive range
-```svs
-heads.default {
- frame-count: 3;
- tracks: [
- {"id":"WIFE","regions":[[0.12,0.09,0.20,0.26],null,[0.13,0.10,0.20,0.26]]}
- ];
-}
-```
+The UGC, podcast and interview examples use `@hypit/caption-fine`. Fine supports exact fonts,
+placement and anchors, wrapping, Cue boxes, active-word treatment, lead/tail and motion through
+explicit Style Recipes. Role overrides can distinguish podcast hosts; a tracked head can supply a
+moving placement point without changing the verbal pipeline.
```svml
-<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
+<caption:Program id="caption-program" document={story.caption} narrative={story}
+ default={primary-caption}>
+ <caption:Use role="GUEST" style={guest-caption}/>
+</caption:Program>
<caption-fine:Track id="captions" document={story.caption}
- semantic={speech.semantic} program={caption-program} regions={heads}/>
+ semantic={speech.semantic} program={caption-program}/>
```
-The numbers are authoring evidence, regardless of which observation tool measured them. Adjusting a
-box upward or outward is an ordinary pre-Build data transformation. Do not add face detection,
-tracking, identity association or box expansion to the production graph; Caption should receive the
-final placement evidence rather than rediscovering the face while paid work is running.
-
-## A Fine Caption Recipe writes eleven keys or it throws
+This excerpt assumes the imported Surfaces, fonts and Styles already declared in the Source.
+Use the owning package README and `hypit vocabulary @hypit/caption-fine` for current Recipe fields.
+Keep one coherent interpretation of the Script across speakers and styles; different colors do not
+require unrelated transcripts or separately invented timing.
-`caption-fine:Style` requires `align`, `background`, `fill`, `line-height`, `padding`, `radius`,
-`size`, `stack-order`, `width`, `x` and `y`. None of them has a fallback: a Recipe missing one is
-refused when the Style decodes, before anything draws.
+Fine's uniform-flow layout is a particular family. When the work needs new structural relationships
+within a Cue, create a project Caption family consuming the common Caption data and semantic timing.
+A new layout is normal component authorship. [Track authoring](../../production/track-authoring.md)
+explains the boundary.
-The three that get left out are the box keys — `background`, `padding` and `radius` — because a
-design that wants no Cue box reads as having nothing to say about them. Write them anyway: an
-invisible box is `background="#00000000"` with `padding` and `radius` at `0`, which is a value, not
-an omission.
+## Design reading rhythm with the picture
-**`padding` is a string; `radius` and `size` are numbers.** `padding: 0` is refused with *Fine Caption
-Recipe padding must be a string* while `radius: 0` beside it is correct, and the same holds for
-`active-box-padding`. The reason is that padding admits a pair — `padding: "8 12"` is eight vertical
-and twelve horizontal — which no JSON number can carry, so it travels as text and is split on the
-space. A single value is still written as one: `padding: "0"`.
+Break Cues at meaningful phrases, emphasis, speaker changes and the needs of the chosen visual
+composition. `||` goes between complete Alignment Units and cannot split Dual Text. A short phrase
+can stand alone; a longer readable Cue can be correct. Fine's line wrapping and word-per-line setting
+are layout choices.
-`cue-min-words` and `cue-max-words` are not Recipe properties. Cue length belongs to Script `||`
-boundaries and is reported directly by `validate_script_cues`.
+Choose font, size, width, line height, contrast and motion together. If a Cue overflows, inspect both
+its authored grouping and its actual Style; do not assume every overflow has the same cause. Lead,
+tail and handoff shape visibility while karaoke follows semantic word timing.
-## Cue boundaries are marked in the Script, with `||`
-
-A Recipe holds no rule for where one Cue ends and the next begins. **The Script does**, as a `||`
-between two complete Alignment Units — `docs/quickstart/script.md` is authoritative for it, and
-the Script parser carries those breaks into the Caption Document.
-
-```
-<PRESENTER> It's generally good || at a lot of || different things, ||
- but it's not || as specialized || as some of these || other models.
-```
+Treat Caption, icons, flashes and other graphics as a composition. The interview's guest color and
+answer accents work together without coloring every system identically. Check readability across
+light and dark frames, avoid hiding the important face or product, and allow enough space above a
+tracked head for the whole Cue rather than only its anchor.
-A Segment with no `||` in it is **one Cue**, however long it is: the whole passage renders as a
-single line and runs off both edges of the frame. That is the shape to recognise — a caption that
-overflows is a Segment nobody broke, not a Style whose width or size is wrong, and widening the box
-or shrinking the type will not close it.
-
-Treat roughly **3–4 spoken words per Cue as the hard default** (fewer for long words, large type, or
-dense designs). A longer Cue is an explicit exception that must be justified by the reference and
-verified in the rendered bounds; it is never the result of forgetting `||`.
-
-`validate_script_cues --run <build.svrun>` reports every Cue over four visible words, including Dual
-Text display words. Split it with `||` between complete units.
-
-Mark the breaks where the reference breaks. The observation for a shot says what is on screen at
-once, and that is the Cue.
-
-`||` cannot sit inside a Dual Text unit or split one, since a break falls between units and never
-through one. Timing is not authored with it: each Cue is still timed from the alignment.
-
-## Keep the Script authoritative
-
-- Preserve the exact Script display text. Do not copy burned-in reference subtitles or rewrite the
- spoken source to match an existing visual caption.
-- Use Dual Text when display and pronunciation differ. A Dual Text Alignment Unit is indivisible for
- timing; a Selection that cuts through it is rejected.
-- Use `caption:Use role` for speaker-wide style and `caption:Use selection` for a semantic Selection's
- complete-unit projection. Ordered rules replace the complete Style, with the last matching rule
- winning.
-- Use `caption:Mute` to hide complete Alignment Units without deleting Script words, changing speech,
- or regrouping Cues.
-- Preserve original-language dialogue. Translation or alternate-language delivery is a separate
- authored Script decision, not a downstream model rewrite.
-
-## Keep authoring separate from timing
-
-- Script owns the CaptionDocument, including Display Words, N:M Alignment Units and authored `||`
- Cue Breaks.
-- Caption projects Selections/Roles to complete units before it sees any frame or audio measurement.
-- Each `whisperx:SemanticTake` measures one accepted normalized Segment take and packages its local
- timing; `speech:Track` assembles those Takes into the SemanticTrack used by `caption-fine:Track`.
-- Recompute the affected SemanticTake whenever the speech audio changes. This holds for every Track
- timed against it — Caption, Media, Typography, Ranking, Deck, Comment, Screen, Audio — because each
- one is otherwise measured against audio that no longer exists, and the drift is invisible in a
- still frame.
-
-## Design for readability
-
-- Define one explicit default Style covering every Alignment Unit, then use only the overrides the story needs.
-- Keep caption placement inside a safe region and clear of faces, products, device screens, buttons,
- and essential evidence.
-- Use consistent font bytes, width, size, line height, Cue bounds, and padding when stable readability
- matters. Avoid decorative motion or active scaling that makes consecutive Cues appear unrelated.
-- Short spoken phrases remain complete even when they cannot satisfy a preferred minimum word count.
- Never remove words merely to force a visual layout target.
-- Treat captions and editorial overlays as separate Tracks with deliberate stack orders and spatial
- regions so they do not compete for the same area.
-
-## Review the actual program
-
-- Review the full delivery with real speech timing, not only a still frame or a structural plan.
-- Verify every word, Role Style, muted unit, Cue boundary, timing window, line wrap, safe zone, and
- overlap with Media/Text Tracks.
-- Listen while reviewing: a visually plausible Caption Track still fails if it leads or trails the
- actual spoken word.
+Use [Caption tracking](caption-tracking.md) for the produced-video → face boxes → head regions →
+rerender loop. Fixed placement remains a valid design. Review the moving result with speech for
+reading rhythm, Role assignment, cut transitions and visual collisions; a single styled frame is
+not sufficient evidence of Caption timing.
diff --git a/skills/hypit/references/playbooks/craft/compositing.md b/skills/hypit/references/playbooks/craft/compositing.md
new file mode 100644
index 00000000..f9f42ed3
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/compositing.md
@@ -0,0 +1,76 @@
+# Compositing pictures, screens and overlays
+
+Read this when several visual contributions share a frame: a persistent board over a presenter,
+a live inset, a cutout, a screen inside a device or a designed background carrying media and text.
+[Tracks](../../production/tracks.md) owns the authoring mechanics; this page owns the visible relationship.
+
+## Give the layers room together
+
+Decide which information leads at each beat. A small inset can still dominate through movement,
+contrast or a face; a large quiet field can support the main action. Keep necessary faces, mouths,
+gestures, product labels and readable text clear of persistent graphics.
+
+Plan composition before generating the base image when a long-lived overlay reserves part of it.
+Describe a natural scene that leaves the useful area free, such as a person to the right with a table
+on the left. Keep the intended graphic out of that scene prompt when it will be authored separately.
+The smallest owning response to a collision may be a new crop, a moved overlay, simpler content or a
+newly framed picture.
+
+Canvas dimensions, intrinsic media extent, destination Frame and fit/crop are separate facts. Check
+the result of all of them, not just the Frame coordinates. A tall cutout can consume most of a
+vertical Canvas even when its width seems modest. Stack order is explicit inside Tracks, not the
+order they happen to appear in Film.
+
+## Distinguish container motion from content motion
+
+Watch the edges of the device, card or browser frame. If its corners stay fixed while a page moves,
+the content is scrolling inside a stationary container. Animate or play the inner material under
+that container's clip; translating the whole device tells a different story.
+
+A still can represent a state that the viewer only needs to read. A recording or authored sampling
+motion can preserve actual scrolling when the scroll matters. Use explicit states or a Sequence
+when the content changes discretely. Match the medium to the observed behavior: preserve meaningful
+interaction and let an intentionally unchanged screen remain still.
+
+## Preserve screen and product evidence
+
+Use actual screenshots or recordings when the interface's wording, numbers, navigation or behavior
+are evidence. A generated context shot may surround that screen; explicit compositing is useful
+when the exact interface must remain editable and legible. A screenshot as a model reference helps
+direct appearance but does not establish that every generated label remained accurate.
+
+Keep the screen on the visible screen plane, with believable perspective, gaze and physical access.
+For a reverse angle, reason about which background sector the camera now sees instead of mirroring
+the first image. Two views may legitimately share landmarks when their geometry remains coherent.
+[Visual continuity](visual-continuity.md) covers reference
+relationships across those views.
+
+Inspect at delivery size. Glare, tiny lettering, crop, moving fingers or captions can hide the very
+fact the insert was meant to show. A plausible-looking product interaction is not evidence of a real
+product capability by itself.
+
+## Inset, cutout and flattened composite are distinct choices
+
+A rectangular image or normalized video can be placed directly as a Media Item. A still portrait
+can use background removal when a cutout is intended. A deterministic image composition can flatten
+several layers into a reusable still when that frozen result is the useful artifact. If a cutout
+belongs inside that still, removal precedes composition; neither operation is mandatory for an
+ordinary inset or for a source that already has suitable transparency.
+
+Inspect cutout edges against the final background: hair, fingers, translucent edges, holes, halos
+and color spill. Match light and color when the layers should read as one scene; an intentionally
+graphic collage can have a different visual logic. Keep original media and editable layer choices
+when future reframing or changes are likely.
+
+For a live reaction or call layout, silent participants can breathe, adjust posture or react while
+remaining silent. Main/inset swaps keep each participant
+with their own camera, room and identity; this is different from reversing cameras in one shared
+physical space. Generated call footage and separately composited feeds are both possible designs.
+
+Choose sound explicitly. A moving inset need not contribute audio, and visible source audio does
+not enter Film by implication. Avoid doubled speech when a clip is also used in the performance
+Track. Reuse prepared or generated Outputs through the Run when revising downstream composition.
+
+Review the coexistence of layers through entry, handoff and exit. A clean still does not reveal a
+one-frame A-roll exposure, a late reaction, a clipped sound or a board that vanishes after each reveal.
+Use [frame coverage](frame-coverage.md) for those boundary questions.
diff --git a/skills/hypit/references/playbooks/craft/examples/conversation-images.md b/skills/hypit/references/playbooks/craft/examples/conversation-images.md
new file mode 100644
index 00000000..ab0ecdc4
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/examples/conversation-images.md
@@ -0,0 +1,221 @@
+# Podcast and interview image direction examples
+
+These are English renditions of production prompts, with output aspect ratio moved to the model
+parameter. They retain the strong aesthetic direction, specific wardrobe, setting and spatial choices
+that made the examples useful. Each case states its own inputs; use its relationships without treating
+the character, product or prop inventory as a conversation template. Some images were generated
+separately and imported as files.
+
+## Shared capture language
+
+Use `phone-ugc-v1` from `@hypit/gpt-image-kits` for this photographic language. Its fixed paragraph is:
+
+```text
+A photograph with the texture of real iPhone footage, captured as a single frame from a video
+actually shot on an iPhone. The image looks real, without an oily, overprocessed finish, and has
+the texture of video footage. The background is clearly visible, with no depth-of-field blur.
+Skin texture is natural and fine, the lighting is natural, and the image is coherent and free
+of visual artifacts.
+```
+
+Each direction below follows that paragraph. When using the Kit, put its framing sentences in `shot`,
+its scene and subject direction in `direction`, and any reference responsibilities in `references`.
+The Kit supplies the capture paragraph once. Set the output aspect ratio, such as `9:16`, on the
+model; do not spend prompt attention repeating it. Without the Kit, prepend the paragraph to the
+selected direction. Connect the stated reference images as actual model inputs.
+
+## Restaurant podcast views
+
+### Main host: establish a person and a place together
+
+Inputs: text only. The character's beauty, muscular contrast, styling and relaxed social situation
+belong together. The table at lower left balances her placement on the right and helps establish
+where her off-screen partner might sit.
+
+```text
+Generate a close half-body podcast photograph. The woman sits toward the right of the frame, her
+body turned slightly left, looking left as though talking with someone outside the frame. Her face
+is largely visible from the front, with natural light on it. She sits back on a comfortable fabric
+sofa with her legs crossed.
+
+The setting is the inviting outdoor seating area of a Korean street-side restaurant. Behind her
+are a beautiful dark wooden exterior wall with a grainy texture, coral-red architectural details,
+some plants and other tables. A half-eaten strawberry bingsu sits on the table at the lower left.
+A podcast microphone extends from the left, labeled HYPIT in a well-designed uppercase typeface.
+
+She is a muscular woman with extraordinarily beautiful Japanese-American features: very large,
+beautiful eyes, very fair skin, a small refined face with smooth facial planes, and the beauty of
+a Korean girl-group idol. She has long straight black hair with blunt bangs and wears beautiful
+blue contact lenses.
+
+Her physique creates a striking contrast: a powerfully built, muscular body in a black strapless
+top with an angel-wing pattern. Her arms are muscular, with clearly visible veins and muscle
+definition. She wears relaxed, light-colored tweed trousers with an asymmetric striped pattern.
+Her shoulders are very broad and her head-to-shoulder proportions are excellent. She is close to
+the camera while remaining contained within the frame.
+```
+
+### Other host: a complementary view of the same place
+
+Input 1: main-host image. The parent's useful world is retained; the other host, gaze, microphone
+entry and visible background sector change. “Symmetrical” describes the conversational relationship,
+not a horizontally flipped copy of the same wall.
+
+```text
+Generate a complementary half-body podcast photograph, with the pose and composition corresponding
+to the reference from the opposite side. The person now sits toward the left and looks right.
+The microphone extends from the right and still reads HYPIT. Keep the lighting natural.
+
+The setting is still outside the same Korean restaurant, but the background contains a different
+set of objects because the camera now looks toward the other side of the space.
+
+Replace the woman with a skinny American high-school boy who looks like a nerd. He wears a
+light-colored printed T-shirt with an abstract little-devil graphic, black trousers and a cool
+necklace. His curly hair is messy and he wears black-framed glasses, but his face is still handsome.
+```
+
+### Main host holding the product
+
+Input 1: main-host image. Input 2: the actual app icon. Screen-left and screen-right describe hands
+as seen by the viewer, avoiding an ambiguous “her left” across camera views.
+
+```text
+Keep the natural lighting throughout the image and the microphone position completely unchanged.
+The woman holds a phone whose screen displays a square image: the icon in reference image 2.
+She still looks left, as though talking to the person there. She raises the phone with the hand on
+the right side of the image and points at it with the hand on the left side of the image.
+```
+
+### Other host holding the product
+
+Input 1: other-host image. Input 2: the same icon. Derive this from his view, not from the woman's
+product pose; her camera geometry does not become his merely because both hold the same phone.
+
+```text
+Keep the natural lighting throughout the image and the microphone position completely unchanged.
+The boy holds a phone whose screen displays a square image: the icon in reference image 2.
+He still looks right, as though talking to the person there, and raises the phone with the hand
+on the left side of the image.
+```
+
+## Main host in everyday life
+
+Each image below takes the main-host image as input 1 and the relevant company/product logo as
+input 2. These are independent branches. They preserve her recognizable beauty and strong physique
+while changing the situation, clothing, camera and setting.
+
+### Company reception selfie
+
+```text
+Generate a raised-arm selfie. The woman from the reference is at a company's reception area,
+turning toward her raised phone to take the photograph. She has changed into a light-gray sleeveless
+lightweight sports cardigan with a hood, over a coral-red bandeau top. She wears both the hood and
+a baseball cap. She makes a lively expression and a peace sign.
+
+There is a suggestion of other people inside the company. Her physique and arms remain powerful,
+and she is still strikingly beautiful. The company logo is the logo in reference image 2.
+The lighting looks like real light in the room, including the light on her face.
+```
+
+### Playful mirror selfie in a shop
+
+```text
+Generate a mirror selfie. The woman from the reference stands inside a small street-side shop,
+holding her phone toward a mirror. She has changed into an expensive coral-red tank top and wears
+gray-black over-ear headphones. Her other hand holds a refined art object whose design comes from
+the logo in reference image 2.
+
+She makes a lively expression with her mouth slightly open, as though playfully about to eat the
+object. Her physique remains powerful, her arms are very muscular, and she is still exceptionally
+beautiful. Her phone has a cute CASETiFY case with a little rabbit pattern. She looks at the phone
+screen. Some of the world outside is visible through the window.
+
+The lighting looks real, including the light on her face. The composition is lively rather than stiff.
+```
+
+### Low-angle study scene
+
+```text
+Generate a low-angle photograph. The woman from the reference is in her study at home. The phone
+appears to be placed on the desk, looking up at her as she studies seriously on a laptop.
+She has changed into a cute coral-red camisole-style bib-overall outfit, with a white hair clip
+holding back part of her hair. She is still exceptionally beautiful.
+
+The laptop is light-colored, and the logo on its back is the logo from reference image 2 in coral red.
+The room has a warm, modern Korean interior. Real afternoon sunlight illuminates the home with
+bright golden light, and her face also has believable natural illumination.
+```
+
+These cases intentionally use different exposure situations. Their light/dark and color words are
+preserved as authored choices. [Image direction](../image-direction.md) explains how to judge the
+combined palette and large bright areas when making a new image while retaining a scene's intended
+light.
+
+## Optional split-screen opening
+
+Inputs: both final host views. The output shape remains a model parameter.
+
+```text
+Create a top-and-bottom split screen, with the boy in the upper half and the woman in the lower
+half. Both are close views focused on their upper bodies.
+```
+
+The references already establish the people and setting, so this direction can stay short. The
+corresponding video action gives the silent woman a small posture adjustment and an attentive look;
+that motion belongs in video direction, not a longer still-image description.
+
+## Street interview views
+
+### Shared scene: establish both people before choosing a close view
+
+Inputs: text only. This example creates the encounter, microphone relationship, car and gaze axis
+in one image. Its specific luxury styling serves this character; it is not a street-interview rule.
+
+```text
+Generate a close street-interview photograph. On a wealthy street in New York, a matte light-green
+Porsche is parked at the curb. Near the center-left stands a mob wife beside the front of the car,
+partly facing the camera. Her sunglasses rest on her forehead and her hands are at chest height.
+The car's nose points left; the Porsche badge is visible between the two people near the bottom
+of the image.
+
+She has luxurious black hair in long loose waves, wears an expensive-looking dark fur coat over a
+leopard-print strapless mini dress, and has a gold-inlaid cross necklace. The hand on the left side
+holds an exceptionally expensive Hermès bag. She is about twenty, very young and extraordinarily
+beautiful, with Japanese-Italian features, very fair skin and a clear, refined, affluent presence.
+Her beauty is on the level of a Hollywood film star.
+
+On the right is a cheerful young American college man, seen side-on by the camera. He wears a funny
+backward cap, a coral-red designer graphic T-shirt, a spiked belt and fashionable flared jeans.
+He is handsome, with curly strands escaping the cap. Both people are framed through roughly the
+upper seventy percent of their bodies. He holds a microphone labeled HYPIT toward the woman's mouth.
+There are no other people in the image.
+```
+
+### Guest close view
+
+Input 1: shared scene. Change the attention and crop while inheriting the person and encounter.
+
+```text
+Focus the image on the woman from the reference. Place her in the center of the frame, looking
+toward the right side of the image.
+```
+
+### Interviewer close view
+
+Input 1: shared scene, independently of the guest closeup. The remaining piece of the woman keeps
+his close view connected to the encounter.
+
+```text
+Focus the image on the man from the reference. Place him in the center, slightly larger in frame.
+He continues looking left and holding up the microphone in the same pose. Part of the woman's
+body remains visible at the left side of the image.
+```
+
+## What to transfer to another production
+
+Transfer the decision, not the decorative inventory: start with a useful person in a world, derive
+the views needed, state what each parent preserves, and connect authoritative references where the
+production needs exact private or factual identity.
+The podcast branches change camera, prop state or daily situation for different reasons. The
+interview branches change attention while keeping a shared encounter. Neither graph asks for a
+chain of generated video end frames, and neither requires redrawing all materials for every Take.
diff --git a/skills/hypit/references/playbooks/craft/examples/image-direction.md b/skills/hypit/references/playbooks/craft/examples/image-direction.md
new file mode 100644
index 00000000..0bd11927
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/examples/image-direction.md
@@ -0,0 +1,159 @@
+# Image direction examples
+
+Read this alongside [Directing generated images](../image-direction.md) when learning the actual
+prompt language and aesthetic choices behind Hypit's phone-video images.
+
+The record-store case pairs its exact English production prompt with the supplied output; its public
+WebP viewing copy preserves the original 1152 × 2048 dimensions. The other three pictured cases pair
+their supplied outputs with faithful English translations of the Chinese production prompts; those
+copies preserve the original 1520 × 2688 dimensions. Framing is consolidated into `shot`, and output
+orientation is moved to the external model settings. The translated English versions illustrate the
+direction but have not themselves been submitted as generation requests.
+
+In each prompt, the first paragraph comes from the Kit's fixed capture block, the next is the
+`shot` input, and the remaining paragraphs are the `direction` input. These examples use no reference
+media. A different work can connect references and explain their roles through the optional
+`references` input. The Kit's README in the Distribution owns the exact SVML assembly.
+
+The suggested settings for these prompts are `aspect-ratio="9:16"` and `resolution="2K"` on
+`gpt:Image`. These are external model settings; the prompt describes the composition within that
+shape without repeating it.
+
+The frontal half-body view and microphone belong to this series of versatile speaking images.
+Speaking and loosely gesturing describe an ongoing presence, leaving the later video to direct the
+particular line and gesture. Carry the capture language into another useful shot without
+automatically carrying this staging. Read examples whose directing question is relevant.
+
+## Shanghai record-store owner: one coherent person
+
+![Shanghai record-store owner: green knit, bob, and headphones in a working record shop](https://hypit.s3.us-east-1.amazonaws.com/assets/skills/hypit/image-direction/v1/shanghai-record-store.webp)
+
+The casting idea is a beautiful woman with distinctive taste, at ease in a place she knows deeply.
+The following choices explain the prompt's directing intent as a whole.
+
+- **Beauty with a particular character.** “Exceptionally beautiful” and “the striking appeal of a
+ top girl-group idol” state the strength of the desired appeal. “The cool presence of an independent
+ film actress” gives it a particular character. These describe complementary qualities of one person;
+ they do not request a collage of different faces. “Shanghai” locates her social world, but the city
+ name alone does not supply this casting direction.
+- **Expertise expressed as presence.** Recognizing a record from its first two seconds conveys ease,
+ confidence, and a relationship to music without prescribing a facial pose. The closing sentence
+ makes her someone giving a personal recommendation to the viewer. That relationship gives the
+ image a more specific human intention than a beautiful person simply occupying a shop.
+- **Styling and surroundings that agree.** The neat bob, knitted polo, silver hoops, and headphones
+ support her composed, music-literate persona. Album sleeves and a handwritten recommendation card
+ make this her working shop. Each detail helps the same person become legible.
+- **A palette that lets her stand out.** Jade-green clothing and walnut shelves establish distinct
+ subject and setting colors. The face stays clearly lit while the shelves retain shadows and detail.
+ Color, material, and lighting work together; there is no request to brighten the whole room.
+- **A body situated in the room.** The lower-left turntable gives the rightward placement a physical
+ reason. Comfortable proximity, visible shoulders and upper body, and explicit head-to-shoulder
+ proportions work together to keep her present without asking for an extreme close-up. The fixed
+ iPhone-video paragraph supplies the capture language for this highly attractive, deliberately styled
+ person.
+
+For a different character, carry forward the relationship between these choices. A different persona
+may call for flowing hair, workwear, a bustling outdoor setting, or another palette. A bob, green
+clothing, walnut shelves, and two beauty comparisons are not a reusable formula for an attractive
+woman. Keep the aesthetic direction forceful while making its visible details belong to the new person.
+
+In the saved result, her face draws attention between the black bob, green knit, and wooden shelves.
+The knit stitches, headphone surfaces, silver hoops, and reflections on the record sleeves give
+different materials their own visible character. Small highlights are visible on her nose and lips.
+These are observations of this output. Its prompt does not separately request skin highlights,
+record-sleeve reflections, or visible knit stitches.
+
+The direct gaze, open mouth, microphone, and forward gesturing hand make the frame read as an ongoing
+conversation. The turntable occupies the lower left, while the records and handwritten recommendation
+cards make the shop legible around her. The camera sits slightly above her eye line, while one
+shoulder meets the right edge of the image. The original request remains intact below so that
+intention and output can be compared.
+
+Complete English prompt:
+
+```text
+A photograph with the texture of real iPhone footage, captured as a single frame from a video actually shot on an iPhone. The image looks real, without an oily, overprocessed finish, and has the texture of video footage. The background is clearly visible, with no depth-of-field blur. Skin texture is natural and fine, the lighting is natural, and the image is coherent and free of visual artifacts.
+
+Generate a half-body image of a Chinese woman in her late twenties inside the independent record shop she owns in Shanghai. She sits slightly to the right, comfortably near the camera, with her face level and directed toward it. A turntable on a low cabinet enters the lower-left part of the frame beside her chair. Her shoulders and upper body remain clearly visible.
+
+She holds a small handheld microphone while speaking to the camera, her free hand gesturing naturally. She has the effortless confidence of someone who recognizes a record from its first two seconds. She is exceptionally beautiful, with the striking appeal of a top girl-group idol and the cool presence of an independent film actress. She has a small face, broad shoulders, excellent head-to-shoulder proportions, and beautifully cared-for skin.
+
+Her hair is cut into a neat chin-length bob. She wears a jade-green knitted polo, small silver hoop earrings, and a pair of over-ear headphones resting around her neck. Behind her are walnut record shelves, a few displayed album sleeves, and a handwritten recommendation card tucked into a record bin.
+
+The jade-green clothing gives her definition against the walnut surroundings. The shop has ordinary interior lighting: her face is clearly lit, while the shelves retain natural shadows and readable detail. It feels like a favorite local record-store owner taking a moment to tell you which album you should take home.
+```
+
+## Mob Wife: strong glamour in a captured world
+
+![Mob Wife: strong glamour in a captured world](https://hypit.s3.us-east-1.amazonaws.com/assets/skills/hypit/image-direction/v1/mob-wife.webp)
+
+The beauty comparison and the attitude give this person a vivid social presence. Fur, layered gold,
+red lips, leather seating, and an expensive restaurant reinforce it. The production prompt
+names these materials without adding instructions for leather grain, fabric folds, or metal
+reflections. Its final sentence places her in the social world of a mob wife meeting her girlfriends.
+The deep-red nails and dark-brown hair below preserve the production prompt that belongs to this
+example. Apply the current palette guidance when directing a new image.
+
+Complete English prompt:
+
+```text
+A photograph with the texture of real iPhone footage, captured as a single frame from a video actually shot on an iPhone. The image looks real, without an oily, overprocessed finish, and has the texture of video footage. The background is clearly visible, with no depth-of-field blur. Skin texture is natural and fine, the lighting is natural, and the image is coherent and free of visual artifacts.
+
+Generate a close half-body image of a Latina woman in her thirties, seated slightly to the right and near the camera. Keep her body within the frame. Her face is directed straight ahead without any tilt or rotation, and the lower part of her body is visible and unobstructed.
+
+She holds a handheld microphone in one hand and speaks to the camera, while her other hand gestures. Her commanding attitude says, “Stay out of my husband's business.” She is exceptionally beautiful, with the intense beauty of a top Italian actress and the stunning appeal of a young Monica Bellucci. She has broad shoulders, excellent head-to-shoulder proportions, and a larger-than-life presence.
+
+She wears a leopard-print fur coat over a black low-cut top, several chunky gold chains layered around her neck, and large gold hoop earrings. Her long nails are deep red. Her dark-brown hair falls in voluminous waves; she wears classic red lipstick and bold but clean eye makeup. She sits in a leather booth in an expensive-looking Italian restaurant. An oil painting hangs on the wall behind her, a bar is visible farther back, and candles stand on a nearby windowsill.
+
+The restaurant's background palette is mainly red and gold. It feels like an upscale private dining room where a mob wife meets her girlfriends for a meal.
+```
+
+## Orange-cat CEO: comic authority through body and setting
+
+![Orange-cat CEO: comic authority through body and setting](https://hypit.s3.us-east-1.amazonaws.com/assets/skills/hypit/image-direction/v1/orange-cat-ceo.webp)
+
+The boss's authority organizes the picture. A round face, large belly, crooked tie, straining suit
+buttons, and undersized cat tree make that authority funny. The actual prompt obtains its character
+appeal through those relationships; it adds no general handsome-animal requirement or individual-fur
+detail. It names a leather chair and a gray-and-orange textured office palette without cataloging
+fabric weave or leather grain. The capture paragraph supplies the photographic premise.
+
+Complete English prompt:
+
+```text
+A photograph with the texture of real iPhone footage, captured as a single frame from a video actually shot on an iPhone. The image looks real, without an oily, overprocessed finish, and has the texture of video footage. The background is clearly visible, with no depth-of-field blur. Skin texture is natural and fine, the lighting is natural, and the image is coherent and free of visual artifacts.
+
+Generate a close half-body image of a plump orange cat, seated slightly to the left in a large leather chair and near the camera. Keep its body entirely within the frame. Its face is directed straight ahead without any tilt or rotation, and the lower part of its body is visible and unobstructed.
+
+The cat wears a three-piece suit. One front paw rests on a small handheld microphone as it faces the camera, while the other gestures. Its expression carries the born-to-be-the-boss authority of an orange cat.
+
+Its tie is crooked and its suit buttons strain around its large belly. It has classic orange-and-white tabby stripes, a round face, and long whiskers. Its whole body rests back in the leather chair. Behind it is a boss's office with a floor-to-ceiling window overlooking the city skyline. A desk to its side and rear holds a MacBook and a mug marked “BIG BOSS”; a cat tree in the corner is plainly too small for its owner.
+
+The office's background design combines gray and orange textures. It looks like a standard boss's office.
+```
+
+## Mermaid: an impossible subject in a photographed world
+
+![Mermaid: an impossible subject in a photographed world](https://hypit.s3.us-east-1.amazonaws.com/assets/skills/hypit/image-direction/v1/mermaid.webp)
+
+The mermaid identity, explicit beauty, and friendly curiosity direct the person. Wet hair, shells,
+real pearls, shafts of underwater sunlight, and sand place her in a specific physical world. The
+actual prompt names those states and objects, then finishes by saying that she really appears to be
+sitting underwater. It leaves ordinary surface behavior for the model to resolve, without adding
+separate instructions about shell texture or contact against the skin.
+
+Complete English prompt:
+
+```text
+A photograph with the texture of real iPhone footage, captured as a single frame from a video actually shot on an iPhone. The image looks real, without an oily, overprocessed finish, and has the texture of video footage. The background is clearly visible, with no depth-of-field blur. Skin texture is natural and fine, the lighting is natural, and the image is coherent and free of visual artifacts.
+
+Generate a close half-body image of a mermaid seated in the center and near the camera. Keep her body within the frame. Her face is directed straight ahead without any tilt or rotation, and the lower part of her body is visible and unobstructed.
+
+She holds a handheld microphone in one hand and speaks to the camera, while her other hand gestures. She has the curious, friendly presence of an underwater princess, as though she is teaching people on land about ocean life. She is exceptionally beautiful, with the delicate beauty of a mermaid princess, broad shoulders, excellent head-to-shoulder proportions, and graceful upper-body lines.
+
+Scales with a sea-blue gradient are visible on her neck and shoulders, with small fin-like decorations beside her ears. Her long, wet sea-blue-green hair is threaded with a few small shells and pearls. She wears a top made from shells and starfish and a necklace of real pearls. She sits on a coral rock on the seabed. Behind her is an underwater world with colorful coral colonies, a few small fish swimming past, and shafts of light filtering down from the water's surface farther away. A few shells lie scattered on the sandy seabed.
+
+The background palette combines sea blue and coral orange, like a shallow-water coral reef reached by sunlight.
+
+The image looks real, as though this woman is actually sitting underwater.
+```
diff --git a/skills/hypit/references/playbooks/craft/frame-coverage.md b/skills/hypit/references/playbooks/craft/frame-coverage.md
index be8534e3..c06c493b 100644
--- a/skills/hypit/references/playbooks/craft/frame-coverage.md
+++ b/skills/hypit/references/playbooks/craft/frame-coverage.md
@@ -1,82 +1,28 @@
-# Every instant has a picture, authored or not
-
-A Source is written as a list of placements. A delivery is a picture at every frame. The two are not
-the same shape, and the difference is where this whole class of defect lives.
-
-Nothing is ever absent. An instant no Track covers is not blank — it is filled by whatever lies
-beneath, and the viewer sees that with exactly the weight of everything that was chosen. Which wrong
-thing appears is decided by what happened to be underneath: the Film's background, a layer placed
-behind, the shot before. So one defect wears several faces — a black gap, a flash of the wrong picture, a panel that
-blinks out and returns — and reading them as separate problems is how they get fixed one at a time,
-for ever.
-
-## Audit edges, not placements
-
-Every interval has two edges. An edge you chose is an edit. **An edge you inherited is a hole**, and
-an interval inherits its edges whenever its length comes from something other than your decision:
-
-- a window derived from speech, which starts and stops with words and therefore excludes the silence
- around and between them;
-- a still image has no duration-bearing timeline and must not receive a `playback` value; the
- playback check applies only to moving/generated media whose material can end before its window;
-- an insert, whose material ends where the generator stopped rather than where its window does — and
- then draws nothing for the rest of it, because `playback` defaults to `once-start`, so whatever it
- was covering is alone again mid-phrase. This is the one edge on the list a machine can find before a Build:
- `reconstruction_check` reads each Recipe and refuses the default on generated material.
- `generated-dependencies.md` says what to set instead. The Segment's own picture has no such edge —
- the take that speaks it is the take that draws it, so the two lengths are one number;
-- a blend, whose frames are edges of partial coverage — a one-frame fade is one frame on which the
- layer beneath is half visible, and naming the Recipe for a cut does not make it one;
-- a schedule inside a component, which draws only where its own Program says to and stops between.
-
-The list is not the point and will never be complete. The question is, and it is the same question
-every time: **for each edge, did I choose this instant, and what becomes visible on the other side of
-it?** Anything derived answers "no" to the first half.
-
-## Fix the interval; a layer underneath is not a repair
-
-Putting something beneath a hole changes which wrong picture is shown. It does not close the hole,
-and it makes the defect quieter rather than absent, which is harder to find. The interval is what has
-to change: the window that ends early is lengthened, the material that runs out is replaced with
-material that lasts, the stretch nothing claims is claimed by whatever the reference shows there.
-
-**A stretch is moving footage unless the shot's own observation says its background is static.** That
-is the default, and it is not a judgement to make from the Source or to measure off the reference:
-the third visual question already asks whether the picture moves, and a held photograph or card that
-only appears and disappears is still however long it is on screen. Read the answer for that shot. No
-answer means moving.
-
-Nothing that came out of an ffmpeg filter can stand in for that answer. A filter reads the whole
-composited frame, so a reference whose background is frozen under a moving overlay measures as
-moving, and one measured as moving proves nothing about the background — which is the only thing the
-question is about.
-
-So a still spanning the program is never right: it would need every shot's observation to say the
-background is static. Neither is one held under a voiceover because the take beneath it was too
-short — that stretch has a length, and the take is what has to reach it.
-
-The picture that goes wrong this way reads as an edit rather than as a fault, and the reconstruction
-looks finished while the same edges are still wrong. Nothing downstream catches it either: a still
-has no timeline, so it takes no `playback` and the pre-Build check does not apply to it, and Gate 4
-measures black, which a still removes.
-
-The preview mocks the comparison round renders under an element never reach the Source. They exist in
-that render and nowhere else — the Source never names them, and the checks that decide
-coverage read the Source's Recipes and bindings rather than any picture. A mock cannot quiet a hole
-it is structurally unable to reach.
-
-## Measure it; the eye is the wrong instrument
-
-Two of these are settled before a Build, from the Source alone, and neither needs a threshold.
-Whether every word carries a picture is a yes or no per word: `reconstruction_check` resolves each
-Frame to where it actually sits, collects the ones drawn over each word, and names the words whose
-pictures leave part of the Canvas unpainted. Whether the material lasts its window is the `playback`
-reading above.
-
-The pictures over a word are read **together**. One filling the Canvas is the ordinary case; several
-tiling it is the other one, and it is just as covered. A `until={story.moment.X}` shortens what an
-element claims, so a picture that leaves half way through the program answers for the words before
-that Moment and not the ones after.
-
-Anything `reconstruction_check` reports under `coverage.gaps` is an inherited edge. Take it back to
-the interval that produced it rather than to the layer that revealed it.
+# Coverage at visual boundaries
+
+At a boundary, ask what the viewer should see before, during and after it. An intentional return to
+the speaker is an edit; an accidental one-frame exposure between inserts is a defect. Coverage is
+about the intended picture, not just the absence of black pixels.
+
+Several independent decisions can expose the layer below:
+
+- adjacent semantic windows may leave the inter-word pause unclaimed;
+- a source may finish before its Item's window;
+- entry or exit opacity may reveal the underlying picture during a transition;
+- a component may draw only during each item activation when its background should persist;
+- a spatial frame or crop may leave an unintended part of the Canvas uncovered.
+
+[B-roll craft](b-roll.md) explains the first two. Fix the responsible boundary, sampling choice,
+transition or component schedule. A persistent MG board needs an outer visibility window as well as
+item events. Multiple frames can intentionally tile the Canvas; coverage does not require one
+full-frame clip or a universally lowest A-roll Track.
+
+A still, a designed background or a moving shot can each be correct. Choose from the intended work
+and observed reference, not a rule that every unclassified region must contain generated motion.
+A fallback layer is useful when it is actually the designed background; it does not by itself
+repair an unintended gap in the foreground.
+
+Use Studio and local frame-range rendering around suspected boundaries to inspect the actual
+composition. Check the first and last visible frames of neighboring items, source exhaustion and
+transition frames. Script and Recipes explain the cause, but their names alone cannot prove what
+was drawn.
diff --git a/skills/hypit/references/playbooks/craft/generated-dependencies.md b/skills/hypit/references/playbooks/craft/generated-dependencies.md
index 9bf3f524..3f350664 100644
--- a/skills/hypit/references/playbooks/craft/generated-dependencies.md
+++ b/skills/hypit/references/playbooks/craft/generated-dependencies.md
@@ -1,306 +1,55 @@
-# What one generation owes another
+# Reference relationships
-Two generated things that must match are wired to each other. One is generated, accepted, and becomes
-an input to the next. Describing both in prose is a wish — two prompts saying "the same warm studio"
-produce two different studios. An edge is a constraint.
+Use a reference because the next image or Take needs a fact it already contains. The useful graph
+follows creative dependencies: a person, a camera view, a shared place, a product or a physical state.
+Reference count and graph depth are consequences of those needs, not production goals of their own.
-Everything below is an instance of that one sentence. Where the rule says "for example `gpt:Image`",
-that is the ordinary choice, not a survey to run: pick it and move on.
+## Keep the useful parent close
-Never stop to ask the author which generator to use. Picking between two things that both work is
-your job, and asking costs them an interruption to answer a question the rules already answer. Ask
-only about the video: what it should say, who is in it, what it is for.
+| Work | Useful relationship |
+| --- | --- |
+| UGC / Ranking | One character-and-scene image supplies all ordinary talking Takes. |
+| Podcast | Main host view supplies the complementary host view; each host view plus product supplies its own product-holding variation. |
+| Lifestyle montage | Each scene derives independently from the main character reference, with a logo/product added where needed. |
+| Three-view interview | Shared two-person image supplies both close views; all Takes reuse that view set. |
-## The location is generated once
+A first useful camera image can establish person and location together. Another view can grow
+directly from it when that parent already supplies the difficult facts. Describe what changes and
+what matters to preserve.
-- Before any take in a location, generate and accept one image establishing it. Use the background
- alone, or the background with the person in it when every take there shows them.
-- Generate every other view of that location **from that image**, as a reference. Do not describe the
- room a second time in words; a second description is a second room.
-- Every take references the image for its own view.
-- A reverse angle is another view, derived the same way. It shows a different wall — which is what
- `visual-continuity.md` requires — while staying the same place, which prose alone cannot deliver.
-- Naming the camera positions before generating anything, as `visual-continuity.md` already says,
- is what tells you how many images you need.
+Reference responsibilities can differ. A lifestyle image may preserve identity and physique while
+changing clothes, camera and setting. A product-holding variation may preserve nearly the whole
+camera view while changing hands and prop state. The same input does not imply the same preservation
+rule. See [the worked image examples](examples/conversation-images.md).
-Images therefore generate in dependency order: the establishing image is produced before the views
-derived from it, and the reference edges the Source declares are what state that order.
+For multiple references, connect actual image edges and explain their roles. “Reference 2” means the
+second image in that request; reference numbers are request-local. A description of a reference cannot
+supply a missing image.
-## A split picture's parts all start from the same image
+## Let edited Takes meet through their shared world
-This is about a generation that carries no speech — an insert, a cutaway, a stretch of B-roll. A take
-that speaks its Segment is one generation by construction, and the Segment is cut to fit it.
+In ordinary UGC, podcast and interview production, stable reference views support independently
+generated Takes that meet at editorial cuts. Those cuts can remove dead pauses, change the object of
+attention and make the performance feel like edited social video.
-A continuous picture that exceeds the generator's duration ceiling is split into as many takes as it
-needs. **Every part references the same first-frame image** — the one accepted for that shot — and no
-part references another part.
+A truly continuous action is a different creative requirement. Direct that intended shot through
+the chosen model's suitable mode; repeated references alone do not guarantee identical poses across
+generated seams.
-This is the one place where the "wire what must match" principle does *not* mean chaining. Chaining
-each part to the one before it makes them strictly sequential — part two cannot start until part one
-has finished generating and its frame has been extracted — so a shot split four ways costs four
-generations end to end. Pointing every part at the same accepted image lets all four generate at
-once, and they still hold the same person, framing, wardrobe and light, because they came from the
-same picture.
+A Segment can carry multiple speakers and camera cuts. A split-screen Take can contain both the
+speaker and a living silent listener. Neither a new Role turn nor another visible person mandates
+another generated Take. Choose Segment boundaries for natural production passages and duration fit.
-The parts do not continue each other frame for frame at the seams. **That is fine and needs no
-handling.** Do not try to close it, do not raise it in a comparison, and do not spend an attempt on
-it: it is a small jump in pose, the seam a viewer reads as an ordinary cut. Split the shot, generate
-the parts, move on.
+## Keep media provenance and visual role separate
-## A Segment is a generation boundary
+A file may be an authored generated image imported after production elsewhere. Use it directly.
+When future variation needs the original reference relationship, retain the useful prompt and source
+images as project inputs rather than inventing them from the filename.
-A Segment is what one `whisperx:SemanticTake` aligns one Take to, so each one is a separate
-generation and a separate seam. Cut the Script the way the program is *spoken*, not the way its shots are numbered: splitting a
-stretch that is delivered unbroken invents a seam nobody asked for, and inviting a generator to
-re-establish the room across that seam is how continuity is lost for nothing.
+A-roll is the performance carrying the passage. It stays A-roll when covered by B-roll or presented
+in an inset. Independently authored narration is also valid; it does not require an unseen talking
+person to be generated. [Voice and performance](voice-and-performance.md) owns this distinction.
-Consecutive Segments carrying one unbroken voiceover are one Segment with Selections inside it. The
-pictures over that stretch are placed by those Selections — `frame-coverage.md` governs what that
-costs and what has to cover the silence between them — and the speech stays one Take, up to the
-length one generation produces. Past that it is two Segments; the rule below says so and
-`../../reconstruction/final-sources.md` says where the seam goes.
-
-Name Segments for what they hold. Names are handles: the Script's meaning lives in the words, and no
-part of the pipeline reads a Segment name back for anything a reader would see.
-
-## A voice is generated once, and the take that draws a Segment is the take that speaks it
-
-- One accepted voice sample per person, from `mimo:VoiceDesign`. That is what the voice generator is
- for: a sample, once.
-- **The sample is a reference on every take, and the take generates the speech.** Write
- `generate-audio="true"` and hand it the sample as `<seedance:Reference audio={…}/>`. The
- `whisperx:SemanticTake` for that Segment aligns that take's own media, and the full-frame picture
- over that Segment comes from the same generation.
-- Do not select a voice separately per take. Two selections of "the same warm mid-range voice" are two
- voices, and a viewer hears it immediately.
-
-One generation carries both, and that is what makes the Segment's length and its picture's length the
-same number. Generating the speech separately makes them two numbers arrived at independently — the
-Segment as long as whatever a voice generator produced, the picture as long as whatever a video
-generator was asked for — and two numbers arrived at independently do not agree. Where they disagree,
-the picture ends first and there is nothing to take its place.
-
-### The base of a Segment is whichever picture speaks it
-
-**Speech decides which picture is the base, and depth has nothing to say about it.** Read the
-reference this way: the picture showing a person saying the words the transcript carries for that
-stretch is that Segment's base, wherever it sits in the frame and whatever else is on screen with it.
-
-This is the reading that goes wrong most often. A reference cuts to a full-frame board with the
-speaker inset in a corner, and the board is the larger, lower, more obviously "background" thing —
-so the board is authored as the base and the speaker as an insert over it. It is the other way
-round: the inset speaks, so the inset is the base, and the board is what covers most of it. Nothing
-about being large, or full-frame, or visually underneath makes a picture a base.
-
-Check it against the words rather than the layout. A person whose mouth moves over speech that is not
-theirs is B-roll — `../../reconstruction/continuity.md` is what keeps a moving mouth from becoming a
-speaker — and a small inset saying the transcript's words is the base.
-
-#### A split screen, and what a turn of speech costs
-
-Two people stacked in one frame, each half the height, is this rule at its plainest. Whichever half is
-speaking is that Segment's base: it carries `generate-audio="true"`, its `whisperx:SemanticTake`
-aligns it, and it is drawn into the half it occupies. The other half is a second generation over the
-same Segment, bound `during={story.segment.X}`, and it is B-roll however continuously that person is
-on screen.
-
-**When the speaker changes, that is the next Segment.** A Segment has one Take and a Take has one
-Segment, so a turn of speech cannot be shared: cut the Script where the speaking changes hands, and
-each turn becomes its own Segment with its own base in whichever half is talking. The layout does not
-move — the two halves stay where they are — and what changes is which one the Segment is built from.
-
-Neither half fills the frame, and the pair still covers it. `frame-coverage.md` reads the pictures
-over each word together, so a Segment whose two halves tile the Canvas is covered; one where the
-listening half is left out is not, and the words are named.
-
-Generate each half's first frame at `aspect-ratio="1:1"` and let the half crop it. Half of a 9:16
-Canvas is close to square — 1080×960 on a 1080×1920 delivery — and no ratio the model offers is that
-shape, so something is cropped whichever one is asked for. Ask for the square: the subject sits in the
-middle of it, the crop comes off the top and bottom where a head-and-shoulders framing has room to
-lose it, and 1:1 is the ratio the model holds most reliably. Asking for `9:16` here and letting the
-half take a slice out of the middle is what produces two halves whose people are different sizes.
-
-### Stack order is authored per Segment, never once for "the base"
-
-A picture is the base *of a Segment*. The same Track can hold the base for one Segment and something
-almost entirely covered in the next, and those two are different stack orders decided separately.
-
-So do not fix a Track's `stack-order` because of what it is: give each unit the order its own stretch
-needs, from what the reference shows over it there. A `stack-order: 0` written once because "this is
-the base" is what leaves a Segment's speaker under a panel that was only meant to cover the Segment
-before it.
-
-### A Segment fits one generation
-
-`whisperx:SemanticTake` selects "the single authored Segment performed by this Take", so a Segment has
-one Take and a Take has one Segment. The speech coming from that Take means the Segment can be no
-longer than one generation. Read the selected model's declared duration range from the model.
-
-Cut the Script so every Segment's speech fits. A passage longer than that is two Segments, and
-`../../reconstruction/final-sources.md` decides where the seam falls — on a sentence, not mid-clause.
-
-This is why the split above is about pictures rather than speech.
-
-## A take starts from an accepted image
-
-Never generate video from a prompt alone. Without a first frame nothing fixes identity, framing,
-lighting or wardrobe, so the take can be reviewed against nothing and the next take can match
-nothing. Use the shape that takes a first frame, or the shape that takes ordered references.
-
-Generate it on the smallest tier — `model="mini"` for a Seedance take — unless the author named a
-model or the delivery genuinely needs a resolution only the top tier offers. Takes are regenerated
-more often than they are kept, so the tier multiplies the whole bill rather than one request.
-`seedance-directing.md` holds the model contracts.
-
-## A component's media slots are filled, never left empty
-
-A component that shows media — a card, a board, a frame, an insert — declares its media inputs as
-separate attributes (`image`, `video`, `media`, `surface`), each with its own `accepts` type, and
-`inspect_svml_vocabulary` reads them — `../../vocabulary.md` names the command. Recognising them is
-the first half; the second is that every
-slot the reference actually shows content in is **filled**. A slot the observation says holds a
-picture is given a generated picture; one that holds video is given a take. A slot left empty where
-the reference showed something is a card with a hole in it — the same failure as a missing inner
-picture, at one level up: the frame was recognised but the content was not generated.
-
-This is why a full-screen board that contains two media boxes is read as *two* media boxes, not as a
-single flat composition. The component owns its surface; the boxes are inputs, and each one is
-filled by generation when the reference shows content in it.
-
-## A semantic window covers words, so the silence around it belongs to nobody
-
-This is the commonest inherited edge in a speech-led program; `frame-coverage.md` holds the general
-form and the measurements. `during={story.selection.X}` spans that Selection's first word to its last,
-so the pause between two Selections and the breath before a Segment's first word are in neither.
-
-Decide, for each thing you place, which of three kinds it is:
-
-- **Continuously present** — a sheet the reference holds up, a panel that stays behind a whole
- passage, a badge that stays. Take its window from a Segment, or from the first occurrence's start to the last one's end.
- Never from a Selection whose occurrences have gaps, however well the occurrences line up with the
- words: they do not touch.
-- **Handing over to the next one** — one insert replaced by another with nothing meant to show
- between them. Close the first on the second's first word, or open the second on the first's last:
- the Script's markers carry which side of a word a boundary lands on.
-
- | Marker | Where the boundary lands |
- |---|---|
- | `@id` | Open, right-absorbing — at the next word's start |
- | `~@id` | Open, left-absorbing — at the previous word's end |
- | `@/id` | Close, left-absorbing — at the previous word's end |
- | `@/id~` | Close, right-absorbing — at the next word's start |
-
- A plain `@a … @/a @b … @/b` closes on one word's end and opens on another word's start, and the
- pause between those two words is in neither Selection. Written `@/a~` or `~@b` the two windows meet,
- and what is under them stays under them. The same file carries `||`, which marks where one Caption
- Cue ends and the next begins — `captions.md` says what happens to a Segment nobody broke.
- `docs/quickstart/script.md` is authoritative for the
- markers.
-- **Genuinely coming and going** — an insert that appears for one phrase and leaves. A plain Selection
- is exactly right, and the gap is the point.
-
-**Where the base is meant to stay hidden, the covering Selections tile the Segment.** A voiceover-led
-stretch still has a speaking take — that is where the speech comes from, so it is the base — and the
-reference never shows it, so every word of that Segment is inside one covering Selection or the next, with the
-markers above joining them. A gap does not read as black there; it reads as a presenter appearing for
-half a second in a program that has none.
-
-This is settled in the Script rather than by looking: mark the covering ranges, read them back, and
-confirm the Segment's first word opens one and its last word closes one with nothing between.
-
-The same question decides a component you write yourself. A Program built only from item arrival
-windows draws only inside them unless you give it an outer span of its own, so a page built from one
-window per row vanishes between rows. A project-local notebook-ranking package may do that deliberately
-and say so in its own appearance text; a sheet the reference never takes down must not inherit it. When
-a component both persists and changes, its schedule carries two different things — one span for how
-long it is on screen, one window per item for when that item arrives — and conflating them is what
-produces the blink.
-
-## An insert runs out where its material ends, and the base shows through
-
-An insert is a second generation over a Segment the speaking take already fills, so its length and
-its window are two numbers arrived at separately. Where the material is the shorter of the two, the
-`playback` key on its appearance Recipe decides what the rest of the window shows. The default is
-`once-start`: the material draws once and then nothing is drawn, so those frames fall through to
-whatever is beneath. `hold-start` pins the last frame for the rest of the window, `loop-start`
-repeats, `stretch` retimes to fit.
-
-What appears is the Segment's base — the insert leaves early and the picture that speaks the stretch
-is alone again mid-phrase. Read it as an insert with the wrong length rather than as an edit, and give the Recipe a `playback` that says
-what should happen there. `reconstruction_check` reads the Recipe before a Build and refuses the
-default on generated material.
-
-Read the selected model's duration ceiling too, from the model: a longer insert is more than one Item
-rather than one Item asked for a length the model refuses.
-
-The other way an insert leaves a stretch it should have held is the boundary above: a plain Selection
-close lands on a word's end, so the pause before the next one belongs to neither. That one is fixed
-in the Script rather than the Recipe.
-
-A layer beneath makes a blend visible, so check the Items' entry and exit while you are here: `enter` and `exit`
-default to `none`, and a Recipe named for a cut that fades for a frame is one of the inherited edges
-`frame-coverage.md` describes.
-
-## A Selection carries two edges; a Moment carries one
-
-Both name time in the Script's own words, and which to reach for follows how many edges the words
-fix.
-
-- **Both edges are spoken.** `@id` … `@/id` opens and closes a Selection around the stretch, and
- `during={story.selection.X}` spans its first word to its last. That is what the tiling above is
- about: an insert that arrives on a phrase and leaves on another, one Selection picking up where the
- last left off.
-- **One edge is spoken and the other is decided elsewhere.** `@id!` marks a Moment — a point, not a
- range, right-absorbing at the next word's start, `~@id!` left-absorbing at the previous word's end.
- Give the element the span it actually occupies and let the Moment cut it. The accepted spelling for
- a window from the program start to that Moment is `start="program.start" end="moment.cue"
- moment={story.moment.X}`; `at={story.moment.X}` places a single arrival there. A Deck that stacks
- cards as they are named and clears on a word reads this way. `during="program" until={...}` is not
- a valid temporal projection.
-
-A Selection is free to open in one Segment and close in another. Each end records its own Segment,
-and nothing closes it at the boundary — the only refusal is `SCRIPT_SELECTION_UNCLOSED`, raised after
-the whole Script is read for a Selection with no close marker anywhere. Selections may also cross one
-another; they do not nest like tags. What a Selection crossing a Segment does cost is upstream: the
-Segment is the generation boundary the section above describes, so a window spanning two of them
-spans two Takes and two seams.
-
-Selection and Moment share one name namespace, so the same id cannot be both.
-
-## A short stretch is not a short take
-
-An authored take stays inside the selected model's declared duration range — read the range from the
-model, since it differs between them and a literal in a document goes stale. The measured speech
-length (`hypit measure`) may be shorter than a paid model's minimum: write the model-valid floor (or a
-shared longer take) as the literal duration, while the SemanticTake remains aligned to the words. Trim or hold the visual material as needed; never pad the SemanticTake or substitute reference
-timings for it.
-
-This too is about a generation that carries no speech. A Segment always has its own speaking take,
-however short its words are.
-
-An observed stretch shorter than that floor is never authored as its own take. Decide by what the
-observation says about the picture:
-
-- **It moves** — fold the consecutive short shots into one take at or above the floor and let the
- take cut internally, rather than generating each beat separately. How many references that take
- gets is decided by what the beats *show*:
- - **The same material** — one place, one person, one object, seen from a couple of angles or at a
- couple of moments — takes **one** image. The beats are a performance, so they belong in the
- prompt: say what happens and where it cuts. Handing the model four pictures of one scene is how
- a continuous space turns into four subtly different rooms, and it costs four generations to make
- it worse.
- - **Different material** — a different place, a different object, a different subject in each beat
- — takes one accepted image per distinct thing, in the order they appear. There is nothing for a
- single picture to establish here; the cuts are the point.
-
- The question is not how many beats there are but how many *things* they show.
-- **It is still** — a screenshot, a card, a poster, a held photograph — author stills placed on a
- Media Track and cut at the observed boundaries. More faithful than asking a video model to hold
- something still, fully controlled, and far cheaper.
-- **Only its contents move** — a phone screen being scrolled, a browser page running past, a document
- paged through. The frame is fixed and a still of the page goes inside it, which is the previous case
- with the movement accounted for. `graphic-compositions.md` holds the reading and the evidence that
- settles it; the trap is authoring the frame as the thing that travels.
-
-Never pad a take to reach the floor. If the beat is two seconds long, it is two seconds of a longer
-take or it is a still; it is not a four-second generation trimmed by two.
+A short B-roll window may consume the beginning of a longer generated clip. A montage may combine
+several scenes in one request. A still can be placed directly when a still is what the work needs.
+Choose the shape through [B-roll craft](b-roll.md).
diff --git a/skills/hypit/references/playbooks/craft/graphic-compositions.md b/skills/hypit/references/playbooks/craft/graphic-compositions.md
index aada0bc0..4b0c1daf 100644
--- a/skills/hypit/references/playbooks/craft/graphic-compositions.md
+++ b/skills/hypit/references/playbooks/craft/graphic-compositions.md
@@ -1,142 +1,77 @@
-# Graphic compositions and material
-
-This file decides what a picture *is* before anything decides which component draws it. It applies to
-original authoring and to reconstruction equally.
-
-## A base picture is a depicted scene
-
-- A base picture is a depicted scene: a place, a person, an object, or a world with its own space,
- light and camera. Live action and animation both qualify — a drawn or rendered world is a scene.
-- A designed graphic field is never a base picture. Ruled or gridded paper, document sheets, flat or
- gradient colour, blurred wallpaper, boards, canvases, panels and slide backdrops exist so that
- authored elements can sit on them. They are the surface of a composition, not a place.
-- Judge by what the surface is *for*, not by how convincing it looks. A photographed desk with a real
- notebook on it is a scene. A full screen of paper that exists only so words can appear on it is a
- graphic composition, however good the paper texture is.
-- Never send a designed field to a video generation model as a shot, and never author one as a base
- Track. A scene generator asked for a backdrop returns unreproducible footage in place of content
- you could have timed, edited and corrected.
-
-## A full-screen graphic composition is one component
-
-- When the whole picture is a designed field carrying authored content — a list, a ranking, a
- leaderboard, a chart, a score, a quiz, a code sheet, a card wall, a title board — that whole
- picture is one self-contained composition. It owns its background surface, its elements, its
- reveal and its motion.
-- Author it as one component that owns all of it. Never as a generated base plus a separate text or
- overlay Track: that split makes the background unreproducible and scatters one visual system
- across unrelated tags with no shared timing.
-- Text drawn over a depicted scene stays an overlay on that scene. Only a picture whose entire field
- is designed becomes a composition of its own. A framed graphic occupying part of a scene is an
- inserted element, and the same ownership rule applies inside its frame.
-- **A designed field is still one composition when it covers only part of the frame.** A ranking
- down the left third, a leaderboard across the bottom half, a scoreboard band over a live shot —
- each is a designed field carrying authored content, and each is one component that owns its own
- surface, its rows and its reveal, sitting on a Frame that is not the whole Canvas. It does not
- become an overlay because it is small, and it does not need a visible border or card edge to be a
- field: a slab of colour holding rows is a surface. The question is never how much of the frame it
- covers, but whether what it covers is designed or depicted.
-- If no installed package owns the composition, that is a real vocabulary gap. Read
- `../../local-author-package.md` and build the package. Do not approximate it with tags that own a
- different role.
-
-## Material and structure are sourced differently
-
-Every visible thing is either depicted material or drawn structure.
-
-- **Depicted material** is what a picture must show: scenes, people, products, textures, paper and
- backdrop surfaces, artwork, screenshots, and any picture sitting inside a frame, card, device or
- inset.
-- **Drawn structure** is what the composition computes: text content, exact font, size, weight, line
- height, spacing, alignment, colour, stroke colour and width, shadow colour, offset, blur and
- opacity, glow, emphasis or active-item treatment, frame geometry, borders, corner radius, padding,
- stack order, placement, and reveal or typing rhythm.
-
- That list is also the checklist for accepting a package: `../../vocabulary.md` requires every one of
- these that changes what the viewer sees to be resolved before a component is chosen, and a property
- with nowhere to land in the declared vocabulary is what makes a gap.
-
-Never bake drawn structure into generated material. A generated picture of text cannot be re-timed,
-re-read or corrected, and its wording drifts. A card, inset, phone, browser or screenshot element is
-not one picture: its inner picture is material, its frame and entry are structure.
-
-### A page scrolling inside a frame is a frame that does not move
-
-The frame and its inner picture are two things, so they move independently, and the one that is moving
-has to be named. A screen recording — a phone app being scrolled, a browser page running past, a
-document paged through — is **a frame sitting still while its contents travel**. The device stays
-exactly where it is: same position, same size, same corner radius, same edge, frame after frame.
-
-Read the wrong way round, this becomes an element that slides up and down the canvas, and that is the
-misreading to watch for: nothing in the reference translated, and the reconstruction has a phone
-sliding about the screen. The evidence separating them is the frame's own edge. Track the border,
-the corners and the outer rectangle across the stretch: if they hold their position, the frame is
-fixed and everything that moved was inside it.
-
-Author it that way. The frame is a fixed `space:Frame` at the position and size the reference holds it
-at, and the inner picture is **one still image** of the page, placed inside it. Do not generate a video
-of a scrolling page and do not animate the inner picture past the frame: a still of the page at the
-moment the reference dwells on is what the viewer reads, it is fully controlled, and it costs one
-image. `generated-dependencies.md` says the same thing from the take side — a stretch whose picture
-does not move is authored as a still rather than asked of a video model.
-
-What is worth reproducing is any state the reference shows and the still cannot: a selected row, a
-badge, a check mark. Those are drawn structure over the still, on the words where the reference shows
-them, rather than a reason to make the whole thing move.
-
-## A component's own surface belongs to the component
-
-Depicted material divides again, and getting this wrong produces a component that cannot draw
-itself.
-
-- **Component-owned surface** is the chrome a composition always shows: its paper, board, panel,
- ruled lines, grain, texture, default backdrop. It is part of the component's identity. It ships
- **inside the package as an ordinary file**, exactly as the package's preview image does, and is
- read with `readFile(new URL("../assets/…", import.meta.url))`.
-- **Source-supplied material** is content that differs between videos: photographs, screenshots,
- thumbnails, product shots, character images.
-
-The test is one question: **would two different videos using this component show the same picture
-there?** If yes, it belongs to the package. If they would show different pictures, it is an edge the
-source supplies.
-
-The two are also *obtained* differently, and this is where the line is most often crossed. A
-component draws its own chrome in code: its Surface, Producer and Fragment render the paper, board,
-panel or backdrop, and the preview image its Surface owes is captured from that rendering.
-Source-supplied material is **declared in the Source as a generation** — `<gpt:Image prompt={…}/>`
-fed by a `copy:Value` that holds its description — so the picture and the words that produce it live
-together and can be reread, corrected, planned and rebuilt through `hypit plan` and `hypit build`.
-Generating that material yourself and pointing `media:Image src=` at the file throws the description
-away and leaves a picture nobody can regenerate; `media:Image` is for material the author already had.
-
-Never make a component's own surface a required input, and never make it a generated raster either.
-A component whose chrome arrives from the graph cannot render on its own, cannot produce the preview
-image its Surface owes, and forces every project that installs it to obtain a picture that was never
-theirs to choose. A component whose chrome is an image-model texture committed into the package
-cannot be adjusted, themed or regenerated by anyone who did not run that generation. If you find
-yourself writing a Run Source whose only purpose is to produce a component's own texture, or reaching
-for an image model to make one, the chrome is in the wrong place: draw it in the component.
-
-A package is installed vocabulary. `.svml`, `.svs` and `.svrun` are documents that use it. A package
-that needs one of those documents in order to draw itself has inverted that relationship.
-
-## Missing material must be generated
-
-- Decide first whether the picture is component-owned surface or source-supplied material. A
- component's own surface is generated once while the package is being authored and committed as a
- file inside it; the rest of this section is about source-supplied material.
-- Source depicted material in this order: material supplied for the task or already in the project;
- an Artifact the project already produces; otherwise generation.
-- If a required picture does not exist, generating it is mandatory. Do not substitute flat colour, an
- empty frame, a placeholder, a stand-in borrowed from elsewhere, or a silently emptied element. A
- picture inside a card is part of the work, not decoration.
-- Generate it with `gpt:Image`, reading that package's README for its ports. Surveying what is
- installed before doing something you already know how to do costs time and buys nothing; the
- listing `../../vocabulary.md` documents exists for finding a capability you did not know was there,
- not for confirming a familiar one.
-- Static material is generated as an image. Generate video only when the element is a moving depicted
- scene.
-- Generate one material per depicted thing, at the aspect ratio it will be used at, carrying only
- what it depicts. Keep captions, labels, arrows, badges and titles out of the prompt; the
- composition draws those.
-- Pin accepted Records for reuse. `../../authoring.md` says how a Record is named in the Run Source.
+# Directing graphic composition
+
+Read this for boards, comparisons, charts, titles, cards, diagrams and designed visual fields.
+Start with what the viewer should understand or feel. A graphic can explain, organize, set a tone,
+punctuate a joke or create delight; it does not have to justify itself as literal information alone.
+
+## Compose an idea, not a stack of decorations
+
+Decide what the eye should find first, what supports it and what changes at the next meaningful beat.
+Use scale, spacing, grouping, contrast, color and motion to express that hierarchy. A ranking's rows,
+an interview's unanswered slots and a product comparison's two sides communicate relationships even
+before the viewer reads the words.
+
+Coordinate the whole frame. A presenter's position can leave space for a board; the same accent can
+connect Caption, an answer icon, a question mark and a reveal flash. Treat palette, occupied area and
+brightness together. A large pale panel behind pale clothing can flatten the shot even when each
+element looks attractive alone. [Image direction](image-direction.md) explains planning that space
+into the source picture; [compositing](compositing.md) covers the layer relationships.
+
+Motion should make a change legible: arrival, replacement, accumulation, comparison, reaction or
+completion. Entry is not the whole design. Decide what remains after it, how later elements join,
+and how the system leaves the frame. A settled board may carry more meaning than its animation.
+
+## Put the right facts in editable structure
+
+Use authored text, exact fonts, geometry and state when wording, alignment, timing, data or repeated
+visual relationships need control. Use supplied, found or generated media for photographs, artwork,
+textures, product imagery and other material whose picture is itself the content. A real screenshot
+or finished graphic can remain media; recreating every pixel as a component is not automatically useful.
+
+The boundary follows the work. A sign photographed in a scene belongs to that scene. A score that
+must change on a spoken answer is editable graphic state. A textured paper field may be drawn,
+procedurally made, found or generated; choose according to its intended appearance, theming and
+editing needs.
+
+An icon, portrait, interface or other picture can identify a subject, carry a theme, show a factual
+state or deliver a visual joke. Choose its source from the information the viewer needs. When exact
+current wording, data, UI, private identity or a particular brand asset is itself evidence, use the
+authoritative supplied or found material and record its source and relevant use conditions.
+
+For a familiar public icon, person, object, meme or place whose job is visual recognition or creative
+adaptation, a broadly informed image model can paint the needed material directly or from references;
+a found asset is another ordinary choice. Judge whether the result carries the intended identity and
+graphic role. Reconstruction preserves the useful recognizability and relationship; adaptation may
+replace it with a new theme. Provenance alone does not make one image more visually truthful than
+another. Keep generated prompts and reference edges in Source so their creative intent stays editable.
+
+## Choose a component boundary around shared behavior
+
+A ranking board often deserves one component because its rows share layout, state and transitions.
+A label and an independent photo can remain peer Tracks. A composition may occupy the entire Canvas
+or only a corner; size does not decide the boundary, and a full-screen composition need not become
+one enormous component.
+
+Group elements when their shared layout, state or semantic behavior would otherwise have to be
+reimplemented across unrelated tags. Keep independently useful layers separate when ordinary
+composition already expresses the relationship. A new shared visual role can be a project component.
+
+The package owns reusable mechanics, default chrome and any bundled assets that belong to its
+identity. Source and Recipe supply this work's text, media, palette, placement and events. A surface
+may also accept an authored theme or background when customization is part of its design.
+
+## Expose meaningful control
+
+A useful Surface offers the content and relationships an author needs: rows or slots, labels,
+icons, a Frame, Styles, outer visibility, reveal Selections or Moments, and initial state where it
+makes sense. Avoid hardcoding this video's number of answers, speaker side, product or palette into
+reusable behavior. Expose a useful range rather than every internal pixel or animation calculation.
+
+`preset` means content already present in the initial state of a component that supports it. It is
+not a substitute for a Style and not a generic timing escape. A reveal Window, a point activation
+and an outer lifetime are different controls. [Track authoring](../../production/track-authoring.md)
+explains their implementation.
+
+Judge the configured work at delivery size: the opening state, the changing state, the settled state
+and the exit. Check hierarchy, reading time, collisions and whether a sound or flash helps the event
+land. Improve the visual idea when polished animation still fails to make the relationship clear.
diff --git a/skills/hypit/references/playbooks/craft/image-direction.md b/skills/hypit/references/playbooks/craft/image-direction.md
new file mode 100644
index 00000000..2cf5df19
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/image-direction.md
@@ -0,0 +1,342 @@
+# Directing generated images
+
+Read this when an image must establish a person, place, product, visual world, or useful camera view
+for the production. Read `../../creation/transformations.md` when deciding what a supplied
+identity or product changes across the work.
+
+## Begin with the world the image must establish
+
+Image generation and reference-conditioned video generation form one directing system. The image
+creates a credible person, space, object, composition, and visual language; the video model lets that
+world perform, move, and be photographed over time. Choose the audience's first impression as part
+of that production purpose: who or what draws attention, what presence it has, and what encounter
+the viewer feels invited into. For invented social-video presenters, actively choose an attractive,
+distinctive presence suited to the work. Make the intended appeal as clear as the required framing.
+
+Generate an image when the work needs to establish or change visible facts. Reuse an existing image
+when it already supplies them; some shots can proceed directly to video generation.
+
+For the social-native videos Hypit most often makes, a photographic frame with the texture of real
+phone footage is a strong default. Presenter-led UGC, podcasts, street interviews, lifestyle B-roll,
+product demonstrations, and many comic or fantastical subjects all benefit from beginning inside a
+specific captured world. The Brief, Treatment, or reference work can instead call for illustration,
+animation, designed graphics, studio product photography, archival imagery, or another visual form.
+
+Treat photographic credibility as an ordinary production goal. The intended result belongs to the
+same visible category as a plausible captured frame, rather than to a separate “AI-looking” category.
+Judge the world the image creates. A person, animal, meme character, mermaid, or imagined location can
+inhabit the photographic language of recorded footage when its materials, light, camera, and
+surroundings behave as if they were physically present.
+
+## Use a concrete capture direction
+
+For social-native photographic work, direct the model toward a recognizable capture process rather
+than asking abstractly for “photorealism” or “high quality.” The phone-video capture direction
+describes the result as one frame cut from video actually shot on an iPhone: real without an oily,
+overprocessed finish, carrying video texture, with readable background,
+fine skin and material texture, natural-looking lighting, and an intact image.
+
+That description combines a familiar social-video camera language, believable surfaces, and enough
+background information to establish a real place that can continue into a moving shot. Choose the
+subject's styling and the way the camera records it separately: a glamorous, carefully dressed person
+can appear in casually recorded phone footage. Extraordinary beauty or fantastical subject matter
+does not require a beauty-campaign or illustrated capture style.
+
+The capture language describes how the picture looks, not a prop that must appear in it. Add a
+specific material or lighting direction when the shot needs that fact.
+
+When the model exposes aspect ratio, resolution, or output dimensions as request parameters, treat
+those parameters as their authority. Numeric ratios and resolution labels usually need no repetition
+in the descriptive prompt. Keep directional camera or orientation language when it materially clarifies
+composition, then spend the remaining attention on the actual shot: camera distance, subject placement,
+what remains visible, and how the subject relates to the setting. The model package owns the exact
+parameter names and supported values.
+
+For this capture language, import `@hypit/gpt-image-kits/phone-ugc-v1`. Its fixed
+English capture paragraph preserves the production method, while `shot` and `direction` carry the
+current image and optional `references` text explains the connected media. The Source export enters
+the production's Source Closure directly. The installed package README owns its exact assembly,
+inputs and working example.
+
+[Image direction examples](examples/image-direction.md) pairs the record-store portrait with its
+English production prompt and observations of the result, alongside three supplied case images with
+faithful English translations of their production prompts. Use these when the capture language,
+aesthetic specificity, or relationship between character and scene choices is unfamiliar. Each case
+identifies what its evidence covers.
+
+Within one production, use a prompt language the selected model handles well and keep reusable capture
+wording consistent.
+Preserve aesthetic force, social meaning and specific facts when translating: confident praise, a
+familiar cultural type and a vivid attitude retain their full strength. Keep dialogue, visible text,
+names and other literal wording in the language the work requires.
+
+## Direct a person from identity and presence
+
+Begin with the kind of person the audience should recognize, the role they play, and the presence
+they bring to camera. A social archetype, subculture, profession, attitude, or compact piece of
+character language can coordinate face, styling, posture, environment, and props more effectively
+than an inventory of facial measurements.
+
+When on-camera attraction, charisma, beauty, handsomeness, strength, cuteness, awkwardness, age, or
+comic authority matters, state it directly and with conviction. A direction such as “exceptionally
+beautiful, with the presence of a top Korean girl-group idol,” “the striking beauty and commanding
+presence of a leading Italian film actress,”
+or “a round orange cat with effortless CEO authority” gives the model an overall aesthetic target.
+Support it with a few visible anchors that distinguish this character. Let millimeter-level anatomy
+remain subordinate to the intended person and the camera image.
+
+Photographic credibility can coexist with exceptional beauty, precise makeup, excellent skin and
+strong styling. Preserve the requested appeal; natural texture describes how the captured surface
+reads, while the person remains as polished, attractive or distinctive as the direction requires.
+
+For the attractive, invented presenters in this photographic style, explicitly direct **broad
+shoulders and excellent head-to-shoulder proportions**. Overly narrow, pinched shoulders beneath a
+disproportionately large head can make a generated half-body portrait feel flimsy or doll-like even
+when the face is convincing. This is a useful whole-figure direction, alongside strong beauty or
+handsomeness, rather than a request for anatomical measurements. Preserve the actual physique of a
+supplied person and any different body type intentionally chosen for the character.
+
+Express the intended appeal in the character's own terms:
+
+- For an appealing older character, state distinguished beauty or handsomeness, vitality, and the
+ presence of someone who was strikingly good-looking in youth. Age remains part of the person.
+- For an animal, choose the imposing, cute, or comic presence the role needs. A lustrous coat and
+ handsome proportions can serve a majestic animal; the orange-cat CEO's round face, large belly,
+ straining suit, and undersized cat tree give its authority a comic form.
+- For a recognizable Meme character, preserve its defining features, silhouette, and proportions.
+ Express appeal within that character's visual identity while giving it the requested capture language.
+
+Use wardrobe, grooming, jewelry, makeup, silhouette, and memorable details to reinforce
+the same identity. They should belong to one person rather than read as unrelated fashionable items.
+A beauty comparison can establish the strength of the appeal and another phrase its particular
+character; a role-specific disposition makes that person socially present. In the
+[record-store example](examples/image-direction.md#shanghai-record-store-owner-one-coherent-person),
+idol-level beauty, an independent film actress's cool presence, and effortless musical expertise
+describe compatible qualities of one woman. The bob, knitted polo, headphones, and shop then give
+that casting idea visible form. The transferable choice is this coherence: another person may need
+different beauty language, styling, and surroundings, without acquiring a fixed number of comparisons
+or a required idol-and-actress formula.
+
+When the user supplies the exact private person, pet, product, or character they want, the reference
+owns that identity. Describe observable production-relevant qualities and the intended new shot
+without replacing the supplied identity with a prose reconstruction.
+
+## Let the setting belong to the subject
+
+A useful camera image normally creates the person and their setting together. The setting is not an
+empty plate waiting for a subject to be inserted. It reveals who this person is, what they are doing,
+and what kind of video the audience believes they are watching.
+
+Choose a small number of details that carry that relationship: condensation on an iced latte in a
+Korean-style café, a product diagram on a startup whiteboard, a cat tree that is visibly too small for
+an orange-cat CEO, drying flowers on a textured wall, or worn candles inside a real stone chapel.
+Favor details that connect choices across the image. The record-store owner's turntable belongs to
+her work and gives her rightward placement a spatial reason; a handwritten recommendation card
+expresses how she runs the shop. Make the details that define this person, place, and shot explicit,
+then leave incidental particulars open for the model to resolve within that direction.
+
+Give the scene a relationship to its viewer when that relationship matters: the owner is taking a
+moment to recommend an album to you. A compact line like this conveys ease, expertise, and personal
+attention without prescribing a smile or a precise gesture. After describing the visible details,
+a closing vibe sentence can bring the whole image back to the intended encounter or atmosphere,
+rather than repeating a list of props or adding unrelated style adjectives.
+
+Describe the setting from the camera view that will actually be used. Another useful angle can grow
+from that image while showing the naturally different part of the same place. The work needs camera
+images that do a real job. An independent location image is useful when the work needs that location
+on its own; otherwise the actual camera view can establish both the person and the place.
+
+Write fluent natural-language direction, with exact props and relationships singular and clear.
+Separate mutually exclusive visual states into the images the work needs. Preserve dominant facts
+across related images, including the chosen capture language on derived views: an identity reference
+and a capture direction do different jobs.
+
+## Frame the image for what it will become
+
+A camera image can establish identity, space, composition, and capture language together. A portrait
+used only for identity or a product reference used only for geometry does not also dictate camera
+position, pose, or setting. State which facts the downstream shot should inherit. A reference is not
+necessarily its literal first frame; exact endpoint control is a separate shot decision.
+
+For recurring presenter images, favor a sustainable presence: relaxed confidence, attentive curiosity,
+or effortless authority. This is the useful idle principle. Give the video room to perform the line,
+gesture, or emotional change instead of fixing the person in a blink, peak grimace, or contorted pose.
+Describe a disposition, such as warmth or a compelling gaze, instead of choreographing a raised
+eyebrow, narrowed eyes, a grin, a head tilt, or a precise hand gesture. For these reusable speaking
+images, “speaking to the camera, with the free hand gesturing naturally” gives enough direction.
+Idle retains the character's emotional presence while leaving the later performance room to change.
+
+For a presenter image, that may be a clear face, readable upper body, handheld microphone, natural
+gaze, and a posture with room for gesture. For a podcast reverse view, eye line and microphone entry
+matter more than front-facing symmetry. A selfie needs a physically credible phone-camera
+relationship. A product-use image needs the hands, product, and contact geometry that the action will
+continue from. B-roll may begin with a more specific action because the visual event itself carries
+the passage.
+
+The original character-image series uses half-body views with the person modestly near the camera,
+the face level and directed straight ahead, a handheld microphone, and clear shoulders and arms.
+Direct distance and proportions together: “She sits slightly nearer the camera in a comfortable
+half-body composition, with broad shoulders and excellent head-to-shoulder proportions.” The face
+should be readable while the shoulders and upper body still establish the person. Repeatedly
+intensifying “close” can instead favor a face-dominated crop. Asking to keep the body in frame means
+preserving the intended visible silhouette, not widening the shot until the whole body fits.
+
+Choose left, center, or right placement from the scene and the eventual composition. A slight offset
+can give the image a casually captured quality, but it should have a spatial reason. A small table
+entering the lower-left corner can balance a person on the right; a chair or thighs angled toward
+the left can establish the same relationship through posture. Describe where the person sits in the
+place, rather than merely moving a centered portrait toward an edge. The balancing area remains a
+real part of the setting, with its own objects and texture.
+
+Use seat and leg details when they explain that relationship. A brief direction such as “her thighs
+angle toward the table on her left” can be useful; a catalog of shoes or clothing outside the intended
+crop can compete with the framing. A foreground table, visible feet or lower-body detail belongs when
+it serves the scene and leaves the face, microphone and important gesture area readable.
+
+Apply that speaking-reference solution when the work has the same need. A side-on conversation,
+product action, or full-body shot needs its own gaze, hand occupancy, contact, and composition.
+A specific starting action is useful when the shot is actually about that action.
+
+Compose for the final stack. A Ranking icon on the left can call for a presenter toward the right;
+the same person may remain on that side across every related shot. Keep the face, microphone, and
+useful gesture area clear of the overlay's actual footprint and movement. A lower-left table can
+balance the shot while leaving an upper-left icon area available. Position and scale depend on the
+work, not a fixed left/right alternation or a universal percentage.
+
+Translate that layout into visible image direction: describe subject placement and usable background
+space. Author the MG separately in its component; mentioning a future icon is not a request to paint
+it into the source image. Carry the intended spatial relationship into the downstream performance.
+If Caption follows a face, leave usable space around the head. If a board covers the lower frame,
+place the performer in the region that remains visible. If a product or screen must be read, give
+it enough scale and a credible relationship to the person.
+
+## Make imagined subjects physically present
+
+Fictional content does not imply an illustrated or computer-generated finish. Place the extraordinary
+subject inside an ordinary physical camera world. The mermaid prompt establishes wet hair, shells,
+real pearls, coral, fish, light entering the water, and shells scattered on the sandy seabed. These
+specific states and surroundings make the intended world concrete.
+
+Describe the fantastical facts positively and give the physical directions the scene needs. Familiar
+material names and a few decisive states can be sufficient; explicit grain, reflection, wear, and
+contact instructions belong where they resolve an actual ambiguity or serve the shot. The result can
+remain strange, funny, or impossible while feeling as though somebody pointed a phone at it.
+
+For this photographic fantasy method, finish by reaffirming the subject's physical presence in the
+specific place: “The image looks real, as though this woman is actually sitting underwater.” This
+repeats the intended reading of the whole image after its fantastical details.
+
+## Direct color through material and atmosphere
+
+Compose the palette across the whole frame. Consider the visible area and relative lightness of
+skin, hair, clothing, furniture, and background together. Decide where the person should separate
+from the setting, which colors belong together, and where the eye should settle. Material texture
+alone cannot give a poorly coordinated palette a clear subject or believable tonal depth.
+
+In one portrait, a cream knit against a white background made the image feel too bright and washed
+out; navy clothing gave the person definition against the light surroundings. This is a relationship
+between wardrobe and setting, not a rule against cream or white. For an intentionally pale, luminous
+image, direct the tonal separation, skin color,
+surface variation, and lighting that keep it convincing. When exact wardrobe or brand colors are
+fixed, make the adjustable surroundings work with them.
+
+For these character portraits, two anchor colors can establish a compact palette that supports the
+overall atmosphere. Let incidental colors belong to that whole; this does not require every object
+to use exactly one of two colors.
+
+Then name useful hues and materials. Coral fabric, charcoal wood paneling, weathered brass, or cream
+plaster carries color together with physical response. A few relevant material cues support the
+overall direction; every surface does not need its own grain, seam, defect, or texture instruction.
+
+In palette descriptions, name hues without casually adding brightness modifiers such as “bright,”
+“dark,” “deep,” or “light.” These words can steer the whole image's lighting when only a color was
+intended. Describe the wanted lighting separately.
+
+For white or black areas whose exact color is not essential, prefer a light- or dark-toned material
+with visible surface variation. This is a deliberate alternative to an extreme black/white field,
+not a reason to attach brightness modifiers to every hue. When exact black or white is required,
+keep it and use a concise material or texture cue to give the area visible variation.
+
+| Palette shorthand to improve | A material-led direction |
+| --- | --- |
+| deep purple and pure black | purple fabric and charcoal wood panels |
+| cream clothing against an extensive white background, when it washes out the intended image | give the subject definition through wardrobe and background together, such as a navy knit against light plaster |
+| a pure white wall | light-toned textured plaster |
+| a required black jacket | black leather with visible grain |
+
+These examples teach authored choices, not automatic word substitutions. Exact product, wardrobe,
+makeup, and brand facts remain exact. Preserve the actual wording when documenting an existing result;
+apply the current palette judgment when directing a new image. Surface detail supports the image;
+avoid turning the correction into an inventory of defects or a demand for roughness.
+
+When an image feels washed out or its color balance feels wrong, identify what is visible: large pale
+areas merging, missing highlight detail, flattened skin color, or a color cast. These observations
+point to different adjustments; an overly pale palette alone does not establish a white-balance
+fault. Keep wardrobe and set design, exposure and lighting, and color balance distinct in the
+diagnosis, then make them serve the same image.
+
+Light belongs to the same physical description. State the source and broad relationship that matter:
+soft window light from camera left, ordinary overhead office light, overcast street light, or warm
+lamps within the room. Let texture and small irregularities survive. The goal is not to make every
+image dark, flat, or underproduced; it is to make polish arise from a believable captured world.
+
+“The lighting is natural” means the light belongs convincingly to the scene. It can come from
+daylight, room fixtures, or the practical lights of a night location. Do not automatically translate
+it into a bright daytime interior. A readable background needs focus and useful detail, not the same
+illumination as the face. A large open doorway, pale surroundings, and added daylight can collectively
+suggest an airy, uniformly lit scene even when no individual color is called “bright.”
+
+For a workshop that should retain an interior feeling, direct a clearly exposed face and a room
+with its own gentle shadows and visible detail. Choose wardrobe, wall colors, light sources, and
+the area they occupy together. Preserve the intended beauty; solve excessive brightness through
+the scene's tonal relationships instead of compensating with damaged skin or an all-black palette.
+
+## Give references clear responsibilities
+
+Use references when the image needs a fact that public visual knowledge or prose cannot reliably own,
+or when exactness itself matters: the user's identity, a private or obscure product, a particular
+current logo, proprietary UI, or a camera image already used by the work. A familiar public icon,
+person, meme, object or place can be generated directly when recognizable visual meaning is enough.
+State what each reference contributes and what the new image may change. Choose it because it owns a
+needed fact, not merely because it was generated most recently. A new view can inherit the same room
+while showing a different arrangement of its objects in the frame.
+
+Keep the relationship shallow and useful. The first actual A-roll camera image often establishes the
+person, setting, camera culture, and art direction together. Another A-roll view can use it to retain
+the person and world while changing eye line and camera position. A B-roll image can share the person
+or product when continuity matters. One useful image can constrain several later images and Takes.
+
+The Source owns the exact Resource edges. The Treatment explains why this work preserves or changes
+the relationship. Model documentation owns reference count, media support, aspect, resolution, and
+other request limits.
+
+[Conversation image examples](examples/conversation-images.md) show this distinction in complete
+podcast and interview directions: a complementary host view, product-holding variations, independent
+lifestyle scenes and two close views derived from one shared encounter. Use
+[Reference relationships](generated-dependencies.md) when deciding which parent each image needs.
+
+## Judge visible causes, not provenance
+
+Look at the generated image as the intended audience will see it and as the downstream video model
+will use it. Consider whether the intended appeal and personality actually come through, whether
+the subject draws attention within the whole frame, and whether the image supports the next shot.
+Name the visible cause of a weak result:
+
+| Visible result | Revisit |
+| --- | --- |
+| an interchangeable polished face | the character's role, presence, and aesthetic direction |
+| an oversized-looking head above pinched shoulders | shoulder breadth, head-to-shoulder proportions, and the camera framing |
+| a beauty campaign instead of social footage | the capture direction, light, texture, and camera relationship |
+| an empty showroom or decorative collage | the few setting details that reveal the subject's world |
+| flat dark or light regions | material, surface variation, palette, and local lighting |
+| a pale subject merging into a pale setting, or an overall washed-out image | the relative lightness and visible area of clothing and background, skin color, and exposure |
+| implausible hands, gaze, microphone, phone, or product contact | the physical relationship and framing |
+| identity, product, or room drift across useful views | the selected reference and its stated responsibility |
+| a strong still that cannot support the intended motion or overlays | the shot's downstream role and performable state |
+
+Authorized image outputs continue downstream through the relationships declared in Source. When
+looking at an existing image or Result, use this table to diagnose the visible problem. If a result
+cannot serve the user's goal, identify the owning direction or reference decision. Additional paid
+generation is an explicit production decision under `../../production/authoring.md` and the user's
+spending authority. Build quality into the direction and reuse produced media during deterministic
+refinement.
diff --git a/skills/hypit/references/playbooks/craft/image-prompt-style.md b/skills/hypit/references/playbooks/craft/image-prompt-style.md
deleted file mode 100644
index 71495604..00000000
--- a/skills/hypit/references/playbooks/craft/image-prompt-style.md
+++ /dev/null
@@ -1,176 +0,0 @@
-# Image generation and prompt craft
-
-## Author images in SVML
-
-- Put each prompt in a `copy:Value` from `@hypit/text@1`.
-- Generate with an explicit image Surface — `gpt:Image` — and read its package README for the ports.
-- Connect every identity, product, scene, or UI reference as a visible Artifact edge. For GPT Image,
- use ordered `gpt:Reference` children and consume `{shot.image}` downstream.
-- Set aspect ratio and resolution on the model Surface. Do not put pixels, resolution, or aspect-ratio
- tokens into prompt prose.
-- Never describe output dimensions in the prompt itself: do not write values such as `1:1`, `16:9`,
- `9:16`, `square image`, `portrait orientation`, `2K`, or `4K`. Those belong in the `gpt:Image`
- attributes. Use a shot description such as “close portrait” or “medium close-up” only when it
- explains composition, not as a substitute for the model's size parameters.
-- Do not name real people in image prompts. Describe the visible subject instead: age range, skin tone,
- face shape, eyes, brows, nose, mouth, hair, facial hair, build, clothing, and expression.
-
-## Write every generation prompt in English
-
-Write the final prompt as continuous natural-language prose, with no section headings, category
-labels, slash-separated field names, or key-value formatting. Cover these four concerns in order,
-but never print their names into the prompt:
-
-1. **Reality contract:** open every photographic prompt with this sentence, verbatim, with only the
- bracketed shot replaced. It is concatenated in front of the rest, not paraphrased — a described
- reality contract drifts between prompts and a copied one does not.
-
- > A photograph with the texture of real iPhone footage. Generate a vertical [SHOT — for example a
- > seated medium close-up], as one frame cut out of video actually shot on an iPhone: genuinely
- > real rather than glossy, carrying the texture of video and not of a posed photograph. The
- > background stays clearly visible, with no depth-of-field blur. Skin texture is fine and real,
- > the light is natural, and no part of the picture is broken.
-
- This is for pictures of the photographed world — people, places, products, held objects. A drawn
- asset such as a paper texture, a board or a panel is not a photograph, and this sentence would
- damage it; write those prompts plainly.
-2. **Visible story:** state the exact person/product, wardrobe, location, action, emotion, objects,
- object count, and initial physical state that must be visible. When a person is the main subject,
- make their face and identity the most specific part of the shot description rather than treating
- them as a generic figure inside a detailed set.
-3. **Camera geometry:** state shot size, camera owner/placement, height, direction, lens relationship,
- reflection logic, and which requested objects must fit inside the frame.
-4. **Reference contract:** assign each reference a role and state which identity, product geometry,
- room, or UI fact remains stable.
-
-Describe the final image directly. Do not write an edit-operation checklist, conditional branches,
-or long negative inventories containing unwanted concrete objects. Split mutually exclusive states
-into separate prompts.
-
-## Spend prompt detail on the subject
-
-Use a deliberate detail budget. For a person-led image, the person is the visual priority: spend most
-of the descriptive space on intended ethnicity or heritage when it is authored or known, apparent age,
-face shape, brow and eye structure, nose, lips, jaw and chin, hairline, hair texture and hairstyle,
-skin tone and undertone, distinctive marks, shoulder line, body silhouette, and wardrobe. These are the
-facts that make the generated person recognizable and stable across shots.
-
-Treat the background as support, not a second subject. Usually describe it in one short sentence with
-only the setting and the one or two landmarks that continuity actually needs. Do not enumerate decor,
-patrons, furniture, surfaces, atmosphere, or lighting variations unless one of them changes the story
-or the camera geometry. Keep required props, action, and framing explicit, but remove ornamental detail
-that competes with identity.
-
-When the identity comes from a supplied reference, say to preserve that exact identity and describe
-only observable, production-relevant traits; never infer sensitive background from appearance. A useful
-priority order is: identity and silhouette, required prop or action, camera geometry, then the concise
-setting and finish.
-
-## Keep the reality prefix on every photographic image
-
-The reality contract is an invariant prompt prefix, not a hint for the model. Every `gpt:Image`
-generation that depicts a photographic or photoreal scene must concatenate the exact prefix before
-its shot-specific body, including generations that also have one or more `gpt:Reference` children.
-References constrain identity, geometry, or continuity; they do not replace, shorten, or override the
-prefix. Keep the wording and order stable across a prompt family and change only the bracketed shot
-slot. A reference image with no prefix is a different visual contract and is not an acceptable
-shortcut. Non-photographic illustrations and deliberately graphic assets use their own plain visual
-contract instead of pretending to be iPhone footage.
-
-## A reusable description spine
-
-The strongest prompts turn adjectives into observable evidence and keep the same order every time:
-
-1. **Frame purpose and setting.** Name what the frame is doing (podcast, interview, product proof,
- establishing view), where it is, and what part of the environment must remain visible.
-2. **Composition and camera geometry.** State shot size, subject position relative to the frame,
- body lean, gaze direction, camera side and height, lens feel, and the background sectors or
- landmarks that must be included. Relational instructions such as “subject slightly right,
- leaning left, looking toward an unseen person on the left” are more reliable than three isolated
- adjectives.
-3. **Identity and appearance anchors.** For any person-led image, make the identity description the
- visual center of the prompt. Establish the recurring person with concrete, stable traits first:
- age presentation; specifically intended ethnicity, nationality, or mixed heritage; face shape;
- brow and eye shape and spacing; nose structure; lips, jaw, and chin; hairline, hair texture, and
- hairstyle; skin tone and undertone; natural pores, fine lines, under-eye texture, small
- asymmetries, and any distinctive marks. Then add body silhouette, wardrobe, accessories, and
- styling. Use enough of these facts to make the person recognizable across generations instead of
- writing a generic attractive face. For a male-presenting subject whose physique matters, state a
- visible shoulder line — for example, “broad shoulders and a strong upper-body silhouette” — and
- choose a half-body or wider frame that can actually show it. When mixed Asian heritage is part of
- the intended identity, name the combination explicitly, such as “Japanese-American mixed-race
- man” or “Korean-American mixed-race man”; do not leave a new, authored identity at the generic
- word “Asian.” Keep heritage as one stable identity anchor, never as a bundle of stereotyped
- physical claims. If a supplied reference owns an existing person's identity, do not guess a
- sensitive background from appearance; describe observable facial traits and tell the model to
- preserve that exact identity. Prefer specific, renderable human detail over generic superlatives
- such as “extremely handsome,” “perfect face,” or “flawless skin,” which tend to produce synthetic,
- interchangeable people.
-4. **Action and physical relationships.** Give one readable starting action and posture. Say who the
- subject is addressing, what supports their body, which hands are occupied, and how props contact
- the scene. This explains a gaze, crossed legs, a microphone entering from frame left, or a person
- leaning toward an off-screen interlocutor instead of leaving the model to invent the cause.
-5. **Props, branding, and scale.** Name object count, side of entry, relative size, and attachment to
- the environment. Keep diegetic labels short and specify their placement; use supplied assets or
- an explicit Track whenever lettering must be exact rather than trusting generated typography.
-6. **Light and material response.** Describe light source and direction, indoor/outdoor quality,
- contrast, skin texture, surface texture, and the desired level of polish. “Natural indoor light,
- fine skin texture, background still readable” gives the model physical evidence instead of only
- saying “high quality.”
-7. **A small set of positive acceptance constraints.** Repeat only the few failure modes that matter
- for this shot (for example, no depth-of-field blur, no broken/fragmented regions, background
- visible). Avoid long negative inventories: they consume attention and often introduce the very
- objects they name.
-8. **Reference roles.** For each ordered reference, say whether it locks identity, room geometry,
- product shape, wardrobe, or UI. State what must remain stable and what the new shot is allowed to
- change. Do not describe a reference-locked room a second time in prose as if it were a fresh set.
-
-For a prompt family, preserve this order after the invariant prefix, but write the result as flowing
-natural-language prose. The numbered parts above are an authoring checklist, never headings, labels,
-field names, slash-separated categories, or a key-value outline in the generated prompt. In
-particular, do not emit openings such as `Scene/purpose:`, `Composition/camera:`, or
-`Subject/identity/wardrobe:`. A finished prompt should read like a concise description of the image,
-for example:
-
-```text
-The frame is a compact neighborhood podcast studio; keep the acoustic wall and desk edge visible.
-Compose a seated medium close-up from the guest's eye level, with him slightly right of center and
-leaning toward an unseen host on the left. He is a Japanese-American mixed-race man in his early
-thirties with a broad square face, softly hooded dark-brown eyes set beneath straight brows, a
-medium-width nose with a rounded tip, defined cheekbones, a strong jaw and chin, and a slightly uneven
-smile. His warm light-olive skin has visible pores, faint under-eye creases, and subtle cheek
-asymmetry. His short coarse black hair has a mildly uneven hairline and a natural forward texture.
-He has broad shoulders and a strong upper-body silhouette, wearing a faded charcoal work jacket over
-a white T-shirt. He rests one forearm on the desk and holds one matte-black microphone near his mouth
-while listening with a restrained smile. Keep both shoulder edges, the microphone, and its contact with
-his hand inside the frame. Use the first reference to preserve his exact identity and wardrobe while
-allowing the new posture and camera distance described here.
-```
-
-This example demonstrates the prose shape, not wording to paste literally. One or several short
-paragraphs are acceptable, but every sentence must continue the image description rather than name
-a prompt section. Keep critical facts singular and unambiguous; use controlled repetition only for a
-fact that must survive across every view (identity, camera side, or lighting direction). Separate
-mutually exclusive poses, locations, or before/after states into different prompts rather than
-joining them with “or.”
-
-## Keep people and cameras physically possible
-
-- Make the first generated identity anchor a clear complete face with both eyes visible. Vary face
- direction naturally only after that anchor exists.
-- If broad male shoulders are part of the design, keep both shoulder edges and enough upper torso in
- the identity anchor; a tight face crop cannot establish that invariant for later references.
-- Respect hand occupancy. A person holding a phone or product cannot simultaneously have both hands
- free; assign only physically necessary tasks and avoid arbitrary left/right choreography.
-- For a selfie, specify one real camera topology: an arm-held front camera, a mirror/reflective-surface
- shot with explainable reflection geometry, or a fixed low/front camera. If another person or a
- third-party camera owns the shot, do not call it a selfie.
-- Make shot size agree with the story. Do not place essential feet, table-under actions, or lower-body
- props outside a close or waist-up frame.
-- Make shot size agree with the overlays too. A board, band or sheet that covers part of the frame for
- most of the video decides where the subject can be, so frame for the region that is left rather than
- for the whole picture; `overlays.md` states the rule and how to write it as geometry.
-- For reverse views, define both background sectors before writing prompts and apply the hard rule in
- `visual-continuity.md`.
-- Make before/after states visibly distinguishable through the authored condition, posture, setting,
- styling, or evidence while preserving the intended recurring identity and product facts.
diff --git a/skills/hypit/references/playbooks/craft/overlays.md b/skills/hypit/references/playbooks/craft/overlays.md
deleted file mode 100644
index a4da1808..00000000
--- a/skills/hypit/references/playbooks/craft/overlays.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# Overlay craft
-
-An overlay should add information the photographed or generated base does not already communicate.
-Keep every overlay as an explicit peer Track with its own content, placement, timing, appearance, and
-stack order.
-
-## Give every overlay one job
-
-- Use an overlay to name, emphasize, compare, direct attention, or add necessary context. Remove any
- layer whose only function is decoration.
-- Keep copy short enough to read in one scan. Put explanations in speech or captions rather than a
- second paragraph inside a badge or lower third.
-- Present related title, label, icon, and card elements as one clear hierarchy on the same story beat.
-- Use a small stable visual vocabulary. Color, size, border, paint, and motion should express hierarchy,
- not random variation.
-- Keep base-generation prompts free of editorial captions, arrows, cards, floating logos, and UI
- callouts. Author those elements separately.
-
-## A covering overlay decides how the base is framed
-
-An overlay that holds a fixed region of the frame for a long stretch — a tier board across the bottom
-half, a leaderboard band, a scoreboard, a full-width lower third, a screenshot filling the top half —
-takes that region away from the picture underneath. The base has to be generated for the frame that
-is left, not for the whole one.
-
-- Work out which region the overlay covers before writing the base prompt, and frame the subject
- clear of it: a strip owning everything below 51% of the height means the speaker's head, face and
- shoulders sit **above** the midline, not centred in the whole frame.
-- Say it as positive geometry in the prompt — where the eyes fall, where the shoulders end, what is
- in the part the overlay will cover. Never name the overlay itself; a generator told about a graphic
- draws one.
-- The same applies to a persistent overlay at the top: a sheet covering the upper half pushes the
- subject down, and a base framed for it looks wrong the moment the overlay leaves. If one shot is
- covered at the top and another at the bottom, those are different framings and therefore different
- images, not one image used twice.
-- A face, a mouth or a gesturing hand behind an opaque overlay is the failure this prevents, and it
- survives every structural check: the Source is legal, both tracks build, and the speaker is
- headless. Place the overlay so the base picture's face, mouth and hands stay clear of it, and
- author the base picture's framing to leave that clearance.
-
-## Choose the native overlay surface
-
-Use `typo:Track` for editable typography:
-
-- declare exact font bytes with `fonts:Stack` or `media:Font`;
-- compile appearance with `typo:Style` and an SVS Recipe;
-- choose `typo:Point`, `typo:Area`, or `typo:Path` according to the intended geometry;
-- put reusable plain copy in `copy:Value` and connect it through `content={copy}`.
-
-Use `media-track:Track` for images, generated/supplied video, prepared media, or an already-authored
-compositable surface:
-
-- place every Item in an explicit `space:Frame`;
-- select one source form: `image` with `extent`, `video`, `media`, or `surface`;
-- keep fitting, clipping, frame paint, border, shadow, and lifecycle motion in SVS Recipes;
-- use ordered Layers for a deliberate composite and `media-track:Sequence` for changing visual states.
-
-Changing or scrolling content must remain explicit. Author distinct timed Text/Media Items or a
-Sequence for each state; do not bake several states into one generated image.
-
-When the overlay is a *picture within the picture* — the base must stay dominant and a smaller
-framed image, a cutout, or a video sits on top of it — read `pip-overlay.md`. It is a specific
-craft: the source forms (a rectangular `media-track:Item`, a `remove:Background` cutout, a
-`compose:Image` freeze) are a chain rather than alternatives, and placement, appearance and cutout
-edges are inspected. A PIP is not an ordinary overlay and is not covered by this file alone.
-
-## Bind overlays to story time
-
-- Pass `semantic={speech.semantic}` to the Track and use `during={story.selection.NAME}` for a
- semantic range.
-- Use `at={story.moment.NAME}` with an explicit `for` duration for a point event.
-- Use `during="program"` for persistent overlays and explicit `start`/`end` expressions for deliberate
- author-time placement.
-- Author another named Selection and overlay item when the same effect should repeat later.
-- Let an overlay appear when the information is actually spoken or visible, and leave enough time to
- read it. Do not place important copy only in the final instant of a shot.
-
-## Preserve source truth
-
-- Use supplied screenshots, charts, finished graphics, logos, and alpha artwork as media when their
- exact appearance matters.
-- Keep editable text as Text, not rasterized generator output.
-- Preserve alignment across related frames. Left, center, or right anchoring is a continuity decision,
- not an incidental per-frame choice.
-- Keep overlays clear of captions, faces, product labels, key UI, gestures, and the base shot's main
- evidence. Resolve collisions by moving or simplifying the overlay before reducing readability.
-
-## Review overlays in motion
-
-- Watch the full sequence to evaluate entry timing, reading time, hierarchy, transition rhythm, and
- exit timing; a still image cannot validate these properties.
-- Check every overlay both with captions present and with the surrounding Media Tracks visible.
-- When the screen feels crowded, remove information before accelerating animations or shrinking type.
-- Verify the final `film:Film` stack order. Higher recipe `stack-order` values render above lower ones,
- so accidental ordering can hide otherwise correct content.
diff --git a/skills/hypit/references/playbooks/craft/pip-overlay.md b/skills/hypit/references/playbooks/craft/pip-overlay.md
deleted file mode 100644
index d14f5f84..00000000
--- a/skills/hypit/references/playbooks/craft/pip-overlay.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Picture-in-picture craft
-
-Use picture-in-picture only when the base evidence must remain dominant while a presenter, reaction,
-secondary feed, or supporting image stays visible.
-
-## Choose the source form
-
-- Use a normal rectangular `media-track:Item media={...}` for a live reaction, presenter feed, screen
- recording, or secondary camera, normalizing the footage through `pipeline:Normalize` first.
-- Use `remove:Background` when a still portrait must become a transparent cutout. Place the resulting
- image with `image={cutout.image}` plus an explicit `space:Extent`.
-- Use `compose:Image` with ordered `compose:Layer` children when the PIP should be frozen into one
- deterministic still before it enters the timeline. Cutting out and composing are a chain, not a
- choice between two: when a cutout is what goes into the composite, the cutout's output is the
- layer's source. Reaching for `compose:Image` does not replace removing the background first.
-- Use `surface={...}` only when the upstream component already produces an authored compositable
- surface. Keep the source form explicit rather than guessing from a generic Artifact.
-
-```svml
-<remove:Background id="presenter-cutout" source={presenter.image}/>
-<space:Extent id="presenter-extent" width="1200" height="1600"/>
-<space:Frame id="presenter-pip" within={vertical}
- left="64%" top="52%" right="96%" bottom="92%"/>
-
-<media-track:Track id="presenter-overlay" semantic={speech.semantic} canvas={vertical}>
- <media-track:Item image={presenter-cutout.image} extent={presenter-extent}
- frame={presenter-pip} during="program"
- appearance={recipes.media.pip} motion={recipes.motion.pip}/>
-</media-track:Track>
-```
-
-## Lock placement and appearance
-
-- Define one stable Frame, fit, crop, border/paint treatment, stack order, and safe margin for a
- persistent PIP. Preserve them across shots unless a deliberate transition changes the layout.
-- Keep the PIP clear of captions, faces, product labels, key UI, action buttons, and the base shot's
- main evidence.
-- Match source light direction, color temperature, contrast, and apparent camera quality to the base
- closely enough that the composite reads as intentional.
-- For transparent cutouts, inspect the actual edges against the final base: hair, fingers, motion
- blur, holes, residual background, halos, and color spill.
-- Scale tall portraits against both width and resulting height. A narrow cutout can still consume most
- of a vertical frame.
-
-## Keep speech and motion truthful
-
-- A reaction PIP may remain visually alive through breathing, eye movement, and expression while
- silent. Do not imply that it speaks unless its real audio is explicitly authored.
-- Normalize a video Item's source with `audio="default"` only when it should contribute sound;
- otherwise pass `audio="none"` and put the intended audio on a separate Track.
-- Only the active Script speaker moves their mouth in a dialogue format. A listener PIP reacts without
- invented words.
-- Preserve the same identity, wardrobe, crop, scale, and placement when a PIP persists across edits.
-
-## Time and review the PIP
-
-- Enter or exit on a perceptible story event, Script Selection, or Moment. Use the assembled
- SemanticTrack as the timing authority.
-- Give the audience enough time to recognize both the base evidence and the PIP; avoid rapid toggling
- that makes neither readable.
-- Review edge quality first, then placement on every relevant base shot, then entry/exit motion, audio
- inclusion, caption collision, and final stack order.
-- Pin an accepted cutout or PIP source through `.svrun` `build-record` and `satisfy` instead of
- regenerating it with unrelated downstream changes.
diff --git a/skills/hypit/references/playbooks/craft/screen-demo.md b/skills/hypit/references/playbooks/craft/screen-demo.md
deleted file mode 100644
index affcf526..00000000
--- a/skills/hypit/references/playbooks/craft/screen-demo.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Screen-demo craft
-
-A screen demo must make the person/device relationship physically possible and preserve the real
-product interface as evidence.
-
-## Choose the presentation form
-
-- Use a full-screen screenshot or recording when the interface itself is the primary evidence.
-- Use a framed `media-track:Item` when the screen is an overlay over live action.
-- Use a context/proof pair when the story needs both the user and the interface: first establish the
- person/device relationship, then show the screen from the user's physically possible position.
-- Keep editorial explanations outside the UI on `typo:Track`. Keep the product's own labels, buttons,
- values, and navigation physically attached to the supplied screen asset.
-
-## Enforce hard reverse-view geometry
-
-Define both views before generating either one:
-
-- name camera position A for the person-facing view and camera position B for the device-facing view;
-- name the background sector and dominant landmarks visible from each position;
-- require position B to show the opposite sector with a different landmark set;
-- require the two views to show different background sectors and different landmark sets;
-- reject and regenerate if both views show the same main wall, window, furniture arrangement, or a
- mirrored/cropped version of the same background.
-
-For example, a person-facing classroom view may show chairs behind the user, while the device-facing
-reverse view shows the lectern and blackboard behind the laptop. Writing only “the same classroom”
-for both views is insufficient. Apply the complete geometry review in `visual-continuity.md`.
-
-## Keep the interface on the correct surface
-
-- A readable laptop UI can appear only on the screen facing the camera. Never place interface content
- on the laptop lid, back, keyboard, or another physically impossible plane.
-- Use a real supplied screenshot or captured screen whenever exact wording, data, layout, logo, or
- interaction state matters. Do not ask an image or video generator to guarantee exact UI text.
-- When generating a contextual device image, connect the real UI screenshot as an explicit image
- reference and describe its role in the English prompt.
-- Preserve device orientation, bezel, screen plane, user eye line, room geometry, and the interface
- state across the context/proof pair.
-
-## Direct generated screen motion
-
-- Use the vendored `broll-v1` Kit with a Recipe selecting `material-mode: screen-demo`.
-- Prefer `edit-language: continuous-shot` when the screen, receipt, document, or values must remain
- unchanged throughout the take.
-- Prefer `camera-language: reference-locked` for proof and stable UI, or `product-macro` for a motivated
- close detail. Avoid unnecessary reframing that makes the interface unreadable.
-- Put only the physical interaction and small camera/action change in the English `story` slot.
-- Generate with `seedance:ReferenceVideo generate-audio="false"`; narration and effects remain on
- explicit Audio Tracks.
-
-## Assemble and inspect
-
-- Place screenshots, recordings, and generated demonstrations with `media-track:Track`; define an
- explicit Frame, appearance Recipe, motion Recipe, timing window, and stack order.
-- Use `during={story.selection.NAME}` for a spoken demonstration range, a Moment plus `for` for an
- event, or explicit `start`/`end` timing in the SemanticTrack frame domain for a silent demo.
-- Inspect legibility at delivery size, not only full-resolution source size. Reject changed text,
- unreadable controls, moire, impossible perspective, screen reflections that hide evidence,
- same-background reverse views, or a hand interaction that does not match the UI state.
-- Pin accepted screenshots, contextual frames, and generated demo takes in later Builds with
- `.svrun` `build-record` and `satisfy`.
diff --git a/skills/hypit/references/playbooks/craft/seedance-directing.md b/skills/hypit/references/playbooks/craft/seedance-directing.md
index 0543afa5..aad72b96 100644
--- a/skills/hypit/references/playbooks/craft/seedance-directing.md
+++ b/skills/hypit/references/playbooks/craft/seedance-directing.md
@@ -1,83 +1,74 @@
-# Seedance directing
-
-## Build the prompt inputs
-
-1. Vendor one matching Kit into the project's `./kits/` directory. `../../seedance-kits.md` lists the
- seven shipped Kits, the dynamic slots each one requires and the ordered references it expects.
-2. Import generic Text as `copy` and the vendored Kit under its own alias.
-3. Put stable creative choices in a named SVS Recipe.
-4. Render the Kit with `copy:Render`; connect only dynamic `dialogue`, `action`, `story`, or
- `direction` slots through `copy:Set`.
-5. Feed the rendered Text to one explicit Seedance Surface and keep every reference edge visible.
-
-**A take with `generate-audio="true"` says whatever its prompt carries, so trace that prompt back to
-the words before authoring the take.** Follow the edge from the take's `prompt=` to the `copy:Render`
-that produced it, and confirm one of that Render's `copy:Set` slots carries the Segment's `dialogue`.
-A prompt bound straight to a `copy:Value` holding a performance direction reaches the model with no
-words in it: the model invents its own, and the take sounds fluent while saying nothing the Script
-holds.
-
-That state survives every structural check. `hypit check`, `preview_check` and `plan` all pass,
-because the graph is legal and complete — the prompt is a Text and the take consumes it.
-`whisperx:SemanticTake` then fits the Segment's words onto whatever audio arrived, so the Caption
-Track renders the Script over speech that shares none of it and every downstream measurement stays
-clean. Reading the Source is what finds it. `../../seedance-kits.md` names the slot the words travel
-through.
-
-Write every user-authored image/video generation instruction in English. Verbatim dialogue may retain
-the Script's authored language; do not translate or paraphrase quoted Script lines inside prompts.
-
-Choose the Kit by meaning:
-
-| Use | Kit | Expected ordered references |
-|---|---|---|
-| one speaking person | `speaker-v1` | image 1 = person/scene; audio 1 = voice when used |
-| silent B-roll | `broll-v1` | one or more authored images |
-| two-person podcast | `podcast-v1` | images 1/2 = final A/B views; audio 1/2 = A/B voices |
-| video call | `call-v1` | images 1/2 = reversed call layouts; audio 1/2 = A/B voices |
-| street interview | `street-interview-v1` | images 1/2/3 = interviewer/guest/shared views; audio 1/2 = interviewer/guest |
-| body-motion transfer | `motion-reference-v1` | image 1 = subject; video 1 = motion reference |
-| camera-language transfer | `camera-reference-v1` | image 1 = subject; video 1 = camera reference |
-
-Use `seedance:TextVideo` for prompt-only generation, `seedance:FrameVideo` for first/optional-last
-frame control, and `seedance:ReferenceVideo` for image/video/audio references. Do not duplicate the
-Kit's fixed reference, role, voice, microphone, camera, or text-hygiene blocks in freeform prose.
-Set `generate-audio="false"` for silent B-roll and set it deliberately for speaking formats rather
-than relying on an unstated assumption.
-
-## Respect model contracts
-
-- **`mini` is the model, unless the author named another one.** Write `model="mini"` on every take
- and do not reach for `fast`, `standard` or `2.5` on your own judgement: a video is many takes, most
- of them are regenerated more than once, so the tier multiplies the whole bill for a difference that
- costs more to find than it is worth. Take an instruction to use a particular model literally when
- one is given, and otherwise never raise the tier and never stop to ask which to use.
-- The other values are `fast`, `standard` and `2.5`. `mini`, `fast` and `2.5` all render at 480p or
- 720p only; `standard` alone also supports 1080p/4k, which is the one reason to name it — a delivery
- that genuinely requires 1080p, recorded as the deliberate choice it is. What `2.5` buys is
- duration and reference capacity, not resolution.
-- Keep duration an integer inside the selected model's declared range, and read that range from the
- model rather than from memory: they differ, and one accepts far longer takes than the others.
- Invalid values fail closed.
-- Never generate from a prompt alone, and never author a take shorter than the floor.
- `generated-dependencies.md` says what to do with a stretch too short to be a take.
-- Respect the ReferenceVideo caps, which the selected model declares along with its duration range.
- `mini`, `fast` and `standard` take at most 9 images, 3 videos, 3 audio clips and 12 files in total,
- and their reference audio requires at least one visual reference; `2.5` takes more of each and
- imposes neither of those two constraints.
-- Use `hypit measure` for speech-driven duration planning and write the seconds as the literal
- `duration`; it estimates pronunciation length but does not create measured timing.
-
-## Direct the shot
-
-- Write one or two readable events: a macro action plus small eye, brow, breath, smile, concern, or
- posture feedback. Do not choreograph frame-by-frame poses.
-- Start from the reference pose, objects, emotion, camera, and room. Add only motion that follows from
- visible facts already established by the image.
-- Give objects a physical motion envelope: known starting support/contact, short believable travel,
- and stable count/shape. Avoid teleporting, flying, multiplying, or detaching props.
-- Tie speech actions to Script order. Quote only exact Script words; otherwise refer to semantic beats
- such as opening, reversal, evidence, and verdict.
-- Keep faces readable and hands away from the face unless contact is the authored action.
-- Keep editorial subtitles, titles, cards, stickers, and floating text out of Seedance. Preserve only
- physical labels/UI already attached to referenced objects.
+# Directing generated performance
+
+Read this when turning useful visual references and Script into living speech, interaction or
+silent action. The image establishes who and where; motion makes something happen to them.
+
+## Give each input its own responsibility
+
+| Input | Responsibility |
+| --- | --- |
+| Character-and-scene references | appearance, setting, framing and the physical state to preserve |
+| Recurring voice references | the intended speaker's voice identity |
+| Script dialogue projection | the exact words and speaking turns |
+| Kit Recipe | recurring camera, edit, pace and performance choices |
+| Action direction | this passage's attitude, attention, physical interaction and motivated cuts |
+
+The `@hypit/seedance-kits` README owns template assembly and reference order. The exact model module
+owns invocation modes, duration and media limits. Kits produce ordinary Text; the Source connects
+that Text and explicit references to a model request. Action does not secretly add those references.
+
+Use the Script's `.dialogue` Text rather than retyping dialogue into action. Map Role names to the
+Kit's A/B identities where necessary. Preserve one recurring voice reference per character when
+voice continuity matters. See [Voice and performance](voice-and-performance.md) for A-roll versus
+genuinely independent narration.
+
+## Direct the reason for a gesture
+
+Start with the social situation and attitude: affectionate ridicule, candid surprise, dry confidence,
+playful skepticism. Then choose a few visible actions that communicate it. A restrained lean, an
+open-palmed explanation, a knowing shrug or a short glance can carry more than elaborate choreography.
+Vibe alone may leave an important interaction unspecified; describe the decisive action when the
+story needs a handoff, a look toward a partner or an exit.
+
+Natural emphatic gestures are usually more reliable than asking fingers to display an exact number.
+Let speech, Caption or MG convey the quantity while pointing and hand actions serve the performance.
+
+Silence still has behavior. A listener can settle in the chair, notice the object, glance down and
+look back up, breathe or smile while keeping their mouth out of the speaking performance. Pick small
+actions that follow the exchange.
+
+An encounter also has edges. Someone being interrupted can first be busy; someone finishing can
+begin to leave. Those small causes make the clip feel like a piece of life rather than a pose that
+starts and stops at the encoder's boundaries.
+
+## Choose cuts as part of the performance
+
+UGC can benefit from pause-trim jump cuts. A podcast can cut with the speaker or toward a meaningful
+reaction. A street interview can favor the guest and use the interviewer close view for surprise.
+Stable camera framing, expressive acting and frequent edits are compatible choices.
+
+One Take can contain multiple shots, several speaking turns or a split-screen composition. One
+Segment is not one speaker turn or one camera shot. Conversely, several UGC Takes can use the same
+character-and-scene image and meet at natural editorial cuts. A genuinely continuous shot calls for
+the model mode and direction that preserve that action. See [Reference relationships](generated-dependencies.md).
+
+The Speaker Kit's `pause-trim-jump-cuts` requests an edited rhythm from the model. It does not inspect
+or trim the returned media. If a produced pause actually needs editing, use an explicit media
+operation and align the resulting edited media; a prompt choice is not a deterministic postprocess.
+
+## Size the request around the delivery
+
+Use `hypit measure` on the adopted Segment before writing its duration. Estimate the desired pace,
+then account for the interaction and any intentional pause. Check the selected model's actual range
+with `hypit vocabulary @hypit/seedance`; Mini in these examples accepts 4–15 whole seconds. This is
+a bound on those requests, not on all video models or the finished video's duration.
+
+If a passage is too dense, tighten it or divide it at a natural stage. Avoid filling the maximum
+duration merely because it is available. A short question, an answer with a reaction, and a payoff
+can have different lengths. After production, use actual normalized media and alignment for time;
+the estimate never supplies the final word anchors.
+
+Watch the result for the decisions that matter: engaged performance, correct speaking identity,
+legible interaction, intentional cuts and the right degree of energy. Correct words alone do not
+establish that the scene works. Continue the authorized production and revise a visible problem at
+its owner.
diff --git a/skills/hypit/references/playbooks/craft/sfx.md b/skills/hypit/references/playbooks/craft/sfx.md
deleted file mode 100644
index 87f26f57..00000000
--- a/skills/hypit/references/playbooks/craft/sfx.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# Sound-effects craft
-
-Sound effects support discrete visible or editorial events. They do not replace music, ambience, or
-clear dialogue.
-
-## Give each sound one purpose
-
-- Add a sound only when the audience can perceive the corresponding event: contact, landing, UI state
- change, reveal, transition, or completion.
-- One sound should perform one job. Do not stack impact, whoosh, click, and ambience on the same beat
- unless the story explicitly requires a layered event.
-- Trigger at the audience-perceived event, not automatically at every shot boundary.
-- Keep one consistent sound vocabulary for repeated UI states, cards, reveals, and actions.
-- Let music carry continuous emotion; use SFX for discrete events and ambience for environmental
- continuity.
-
-## Author SFX in SVML
-
-Declare the source, normalize it to audio-only `SynchronizedMedia`, and place it with an `audio:Clip`:
-
-```svml
-<media:Audio id="reveal-source" src="./assets/reveal.wav"/>
-<pipeline:Normalize id="reveal-media" source={reveal-source}
- video="none" audio="default" span-authority="audio" clock={clock}/>
-
-<audio:Track id="effects" semantic={speech.semantic}>
- <audio:Clip source={reveal-media.media}
- at={story.moment.reveal} for="600ms"
- playback="once" gain="0.45" fade-in="0f" fade-out="3f"/>
-</audio:Track>
-```
-
-- Use `during={story.selection.NAME}` for a range, a Script Moment plus `for` for a point event, or
- explicit `start`/`end` timing in the SemanticTrack frame domain — the last only for a program
- with no speech to anchor to, under the same explicit-placement rule in `overlays.md` and `screen-demo.md`.
- Copying a video's own seconds into a `start=`/`end=` is the same defect
- `../../script-time.md` names for covering content.
-- Use `playback="once"` for a discrete effect, loop only for a genuinely repeating texture, and
- bounded pitch-preserving stretch only when the occupancy must fill an authored range.
-- Use explicit trim, gain, fade-in, and fade-out. The Audio Track preserves source level and does not
- add automatic loudness normalization or ducking.
-- For a sound owned by a Media Item or Sequence transition, use `media-track:Sound` with an explicit
- enter, exit, or named Handoff trigger.
-
-## Protect dialogue
-
-- Dialogue remains the most important audio. Keep effects short and light enough not to mask
- consonants, numbers, names, product terms, or conclusions.
-- Avoid strong transients on the same instant as a critical word. Move, shorten, or reduce the effect
- rather than sacrificing speech clarity.
-- Leave breathing space between repeated events. A dense series of identical effects usually means
- the visual rhythm or sound plan needs simplification.
-
-## Review the complete mix
-
-1. Listen to dialogue alone.
-2. Add music and confirm every word remains clear.
-3. Add effects one family at a time.
-4. Listen on headphones and ordinary phone/laptop speakers.
-5. Play the entire program from start to finish and judge cumulative density, not isolated loops.
-
-Verify each trigger against the visible event and check the first/last second for clipped tails or
-effects that outlive the picture.
diff --git a/skills/hypit/references/playbooks/craft/sound-mix.md b/skills/hypit/references/playbooks/craft/sound-mix.md
index 5a137880..83ec3368 100644
--- a/skills/hypit/references/playbooks/craft/sound-mix.md
+++ b/skills/hypit/references/playbooks/craft/sound-mix.md
@@ -43,11 +43,21 @@ event that gives it meaning: contact, arrival, state change, reveal, transition,
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.
+events in the produced 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.
+Layer an impact, click or whoosh when their combination gives the event a useful character; adding
+every available effect to every cut quickly exhausts the listener. A tactile process can instead
+depend on delicate contact and material texture. Preserve those small sounds and match their onset
+to the visible action rather than burying them under a generic impact.
+
+An independent sound can use an Audio Clip at a Script Moment with a deliberate duration. A sound
+intrinsic to a Media Item or Sequence transition can use that component's enter, exit or Handoff
+trigger. The component owns that event relationship. [Tracks](../../production/tracks.md) gives a
+Clip example; `@hypit/audio-track` and `@hypit/media-track` own exact playback and trigger syntax.
+
## Preserve continuity through edits
Picture cuts do not necessarily imply acoustic cuts. Room tone can continue across coverage, music
@@ -63,7 +73,8 @@ the intended handoff rather than hide an unexplained discontinuity.
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.
+Finally listen to the complete Film without stopping. Use the available listening setup that represents
+the delivery, and compare headphones with ordinary speakers when translation between them matters.
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
diff --git a/skills/hypit/references/playbooks/craft/visual-continuity.md b/skills/hypit/references/playbooks/craft/visual-continuity.md
index 268424c2..b1e5f07e 100644
--- a/skills/hypit/references/playbooks/craft/visual-continuity.md
+++ b/skills/hypit/references/playbooks/craft/visual-continuity.md
@@ -1,49 +1,42 @@
-# Visual continuity
-
-## Encode continuity in SVML
-
-- Declare recurring anchors as explicit `media:Image`/`media:Audio` assets or accepted generated
- outputs. Reuse the same Artifact edges; do not redraw identity from prose for every take.
-- Generate the location once and derive its other views from that image, rather than describing the
- room again per take; every part of a shot split by the duration ceiling references that same
- accepted image, so the parts generate in parallel rather than in a chain.
- `generated-dependencies.md` states both, and the reverse-view geometry below is what decides how
- many views a location needs.
-- Keep one authoritative reference set and one stable Recipe for a continuous shot group. Split a
- group only for a genuine edit or the selected model's duration ceiling; preserve camera, room, wardrobe,
- light, props, action state, and reference order across its parts.
-- Put each stable physical fact in both the reference image and the relevant prompt contract. Prefer
- simple, symmetric props when a distinctive feature repeatedly duplicates or mutates.
-
-## Enforce shot/reverse-shot geometry
-
-Treat reverse-view geometry as a hard acceptance rule, not a stylistic suggestion.
-
-1. Name camera positions A and B, their facing directions, and the background sector/landmarks that
- each position must see before generating either image.
-2. For opposing positions, require different main background sectors and different dominant
- landmarks. The room, people, lighting logic, and key props remain continuous, but the background
- behind the subject must not be the same or a cosmetic crop of the same wall.
- The two views must show different background sectors and different landmark sets.
- In short: opposing views must show different backgrounds.
-3. Reject both images if they show the same main background, the same landmark arrangement, or a
- mirrored duplicate. Regenerate before either image enters downstream generation.
-
-Use explicit English geometry such as:
-
-`Camera A faces the subject with the window wall behind them. Camera B is the opposite reverse view from the subject's position, with the counter and blackboard wall behind the device. The two views show different sides of the same room.`
-
-For a person-facing/device-facing pair, the person-facing image shows what is behind the person;
-the device-facing reverse image shows what is behind the device. Writing only “cafe interior” or
-“office interior” for both views is a continuity failure.
-
-## Review each accepted group
-
-- Compare identity, face angle, eye line, wardrobe, lighting direction, room layout, camera height,
- lens feel, prop count, handed tasks, and action state across every image/take in the group.
-- Keep camera movement within the selected Kit Recipe. Do not introduce a new room, camera, outfit,
- or unexplained object inside a reference-locked take.
-- Let only the active Script Role speak. Keep listeners visibly alive through breath, gaze, and
- reaction without invented dialogue.
-- Keep supplied physical text attached to its product, screen, document, or sign; put editorial text
- on explicit Tracks.
+# Visual continuity across edited views
+
+Continuity lets the viewer believe the people, place and action persist through a cut. It does not
+require the cut to disappear. Use [reference relationships](generated-dependencies.md) for the graph
+and this page when a visible change makes the shared world hard to understand.
+
+## Preserve the relationship, change the view
+
+Complementary podcast views share a location, lighting logic and conversation axis. A host on the
+right looks toward the partner on the left; the partner's view reverses that attention. Microphone
+entry, furniture and background help explain the two camera positions. The second view shows another
+sector of the location rather than a mirrored duplicate of the first image.
+
+A plausible reverse view can be derived from the first host image because it already establishes the
+person, setting and conversation axis. If the second image breaks the relationship, revise the
+image or prompt responsible; a problem in one branch does not automatically invalidate both hosts.
+
+In an interview, the shared image establishes both people and the microphone relationship. Derive
+the close views from it. Keeping a piece of the guest in the interviewer closeup can preserve the
+sense of their proximity without needing another establishing shot.
+
+## Preserve the facts this cut depends on
+
+Identity, wardrobe, setting and recurring voice often remain stable across a conversation. Pose,
+hands, shoulders and expression can change naturally at an edit while the cut remains coherent.
+
+Props sometimes require a more specific account: a phone remains in the same hand, a product passes
+to the partner, or the microphone is extended toward a reply. State the meaningful possession or
+direction clearly. Avoid exhaustive hand choreography when a simple interaction communicates it.
+
+Physical text already on a microphone, product or sign belongs to the filmed world. Preserve it when
+it matters; editorial Caption and MG remain separately authored composition.
+
+## Inspect the cut in context
+
+Look at the images together, then the actual moving exchange. Check gaze and spatial relationships,
+who speaks, who listens, and whether prop changes have a cause. An isolated beautiful frame cannot
+prove that an exchange works. A coherent reference pair likewise does not guarantee perfect motion.
+
+Let the intended edit determine what must match. A lifestyle cut can deliberately change clothes
+and location while retaining the same person; a product variation in the same camera has a different
+preservation burden. Carry only the necessary facts into the next prompt.
diff --git a/skills/hypit/references/playbooks/craft/voice-and-performance.md b/skills/hypit/references/playbooks/craft/voice-and-performance.md
index 850c7eea..3b0c34b1 100644
--- a/skills/hypit/references/playbooks/craft/voice-and-performance.md
+++ b/skills/hypit/references/playbooks/craft/voice-and-performance.md
@@ -13,7 +13,8 @@ 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.
+The covering B-roll may even show the same person doing a silent lifestyle action. Seeing a person while
+hearing words does not by itself identify that picture as their speaking Take or 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
diff --git a/skills/hypit/references/playbooks/formats/asmr.md b/skills/hypit/references/playbooks/formats/asmr.md
deleted file mode 100644
index 197a0c07..00000000
--- a/skills/hypit/references/playbooks/formats/asmr.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# ASMR format
-
-Use close material detail, one readable physical action per shot, and deliberately synchronized
-texture sound to create a calm, satisfying micro-film.
-
-## Author the visual
-
-1. Establish one accepted first frame with clear material texture, exact tool/object count, visible
- contact points, and a physically possible starting state.
-2. Vendor `broll-v1.svs`. Use `product-beauty` or `practical-real`, `single-moment` or
- `process-demo`, `continuous-shot`, `product-macro` or `reference-locked`, and `micro` or
- `readable` motion.
-3. Put only the visible action in the English `story` slot: cut, pour, wipe, press, fold, rub, peel,
- place, or another small event that can complete naturally in one take.
-4. Use `seedance:FrameVideo` for one controlling first frame or `seedance:ReferenceVideo` for
- multiple ordered material references. Set `generate-audio="false"`.
-5. Keep raw Seedance duration an integer inside the selected model's declared range. Use explicit
- media Trim/Retime only after
- reviewing the generated take.
-
-Avoid rapid edits, large camera moves, busy backgrounds, multiple simultaneous actions, or motion
-that hides the contact point. Use `standard` for 1080p/4k detail; `fast`, `mini` and `2.5` render at
-480p or 720p.
-
-## Author the sound
-
-- Use supplied or generated texture sound, ambience, and optional music as explicit sources.
-- Normalize every Blob with `pipeline:Normalize`, then place it through `audio:Track
- semantic={…}` and `audio:Clip`.
-- Align impacts and texture changes to the audience-perceived contact event with explicit timing.
-- Use one sound for one function. Do not cover a delicate material sound with unnecessary impacts,
- whooshes, or dense music.
-- Set trim, playback, gain, fade-in, and fade-out explicitly. Do not assume automatic looping,
- ducking, or loudness normalization.
-
-For a speech-free ASMR edit, keep the `whisperx:SemanticTake` and `speech:Track` declarations and
-satisfy `<track>.semantic` in `.svrun` with `build-record` and `satisfy`. That Record is the delivery
-time contract, and every window is an explicit `start`/`end` against it. Omit the Caption components.
-`../index.md` says why the declarations stay.
-
-## Review and reuse
-
-Inspect the actual take for material detail, tool/object count, hand geometry, contact, motion speed,
-label stability, duplicated objects, camera drift, and broken tail frames. Then review sound against
-the visible event, including headphones and ordinary speakers. Pin accepted first frames, takes,
-and audio Records with `.svrun` `build-record` and `satisfy`.
-
-Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`, `../craft/b-roll.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/mixcut.md b/skills/hypit/references/playbooks/formats/mixcut.md
deleted file mode 100644
index 577de298..00000000
--- a/skills/hypit/references/playbooks/formats/mixcut.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Visual mixcut format
-
-Use several short, visually distinct shots to create a music- or voice-led product/story montage.
-The pictures carry the argument; captions are optional and normally omitted when there is no speech.
-
-## Lock the beat structure
-
-Give each shot a distinct role, for example:
-
-1. hook: an immediately readable benefit, contrast, or visual question;
-2. rhythm: a larger but controlled action that establishes momentum;
-3. detail/proof: a stable close view of texture, mechanism, or result;
-4. conversion/payoff: product, outcome, CTA, or a final memorable image.
-
-Adjacent shots must differ in location, camera relationship, action, evidence, or emotional state.
-A crop of the same image is not a new beat.
-
-## Author the SVML shots
-
-1. Generate or supply the exact first frame for each beat and review every generated image before it
- drives a video.
-2. Vendor `broll-v1.svs`; select one coherent material/edit language while varying the beat-specific
- English `story` slot.
-3. Prefer `seedance:FrameVideo` when the first frame is the controlling fact. Use
- `seedance:ReferenceVideo` when the shot needs multiple ordered references. Set
- `generate-audio="false"`.
-4. Add only motion that follows from the accepted first frame. Do not introduce a new person, room,
- product, camera side, or label inside the motion prompt.
-5. Use explicit `pipeline:Transform` Trim/Retime operations when the accepted source needs a precise
- effective length. Place final clips as ordered full-frame `media-track:Item` inputs.
-
-## Author timing, text, and sound
-
-- Lock the delivery SemanticTrack before laying out Items. For a voice-led cut, the speaking take
- supplies program time and semantic anchors, and sits under the cut as the base the Items cover. For a music-only cut, keep the `whisperx:SemanticTake`
- and `speech:Track` declarations and satisfy `<track>.semantic` in `.svrun` with `build-record` and
- `satisfy`, then author explicit `start`/`end` windows against it — `../index.md` says why the
- declarations stay. Do not treat music as speech evidence.
-- 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.
-- Omit Caption components when there is no spoken Script. Use `typo:Track` for title, benefit, and CTA
- copy.
-- Keep no more than one or two text groups on screen at once. Align text handoffs to the final trimmed
- clip boundaries, and update them whenever a clip length changes.
-- Normalize BGM or voiceover before placing it on an Audio Track. Make the musical idea or spoken hook
- audible within the first three seconds. Use explicit gain and fades.
-
-## Preserve product truth
-
-- Use supplied product art, labels, UI, screenshots, and alpha graphics when exact appearance matters.
-- Product and ingredient claims must match verified source material and the visible shot.
-- Keep labels facing a readable direction and inspect the product frame at pause-level detail.
-- Alpha stickers and arrows must retain transparency and point to the intended CTA or evidence.
-
-## Review and reuse
-
-Review first frames, motion continuity, object/label stability, effective clip lengths, text handoffs,
-audio start/end, claim accuracy, and the first/last second of the complete Film. Pin every accepted
-image, clip, audio source, and the SemanticTrack with `.svrun` `build-record` and `satisfy`; regenerate
-only failed beats.
-
-Read `../craft/image-prompt-style.md`, `../craft/b-roll.md`, `../craft/overlays.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/ranking-listicle.md b/skills/hypit/references/playbooks/formats/ranking-listicle.md
index 452eae1c..0bc3ba41 100644
--- a/skills/hypit/references/playbooks/formats/ranking-listicle.md
+++ b/skills/hypit/references/playbooks/formats/ranking-listicle.md
@@ -1,30 +1,71 @@
-# Ranking-listicle format
+# Ranking and listicle
-Use a progressive ranking or list to reveal an ordered set while speech and evidence explain why
-each item belongs where it is placed. The format is a narrative pattern; the concrete visual board
-comes from the vocabulary/component-fit decision, not from a required package or tag.
+A ranking makes an argument through comparison. The board remembers earlier judgments while the
+current person, evidence and performance explain the next one. It can combine with
+[UGC performance](talking-head.md), independent narration or another presentation form.
-## Plan the story
+## Make the board's state tell the story
-- Open with a clear question, claim or ranking criterion.
-- Give every item a stable id, an explicit order or tier, one evidence beat and a concise reveal.
-- Keep order, labels, icon/image treatment and evidence relationships stable across the list.
-- Build toward a decisive top-ranked reveal and close with the implication or CTA.
+Decide what is already established when the clip opens and what the viewer will see decided now.
+A partially filled board can imply an ongoing ranking. In the football example, preset players
+occupy their rows from the beginning while the two spoken passages introduce the active players.
-## Author the sources
+Keep these notions separate when reading a component's vocabulary:
-1. Create the semantic speech chain and one outer ranking window.
-2. Declare exact fonts and the package-owned Style selected during vocabulary inspection.
-3. Use the selected ranking/list component and its documented timing/placement vocabulary; do not
- invent attributes or copy a removed component's timing model.
-4. Connect semantic timing, the outer window, explicit placement, Style and the complete ordered
- item set. Reveal timing must come from the component's admitted Moment/Selection inputs.
-5. Add the visual output to `film:Film`; keep proof clips or screenshots on a separate media track.
-6. Add the Caption pipeline when spoken words should be captioned, then route the delivery through
- `.svrun`.
+- the outer Window is when the board exists;
+- a preset item is part of its initial state;
+- a newly activated item enters at an authored event or passage the component accepts;
+- the component owns how that activation changes the board and how long the resulting state stays.
-## Review and reuse
+A ranking item's activation Selection need not mean the item vanishes when the Selection ends.
+Read the package's actual consumption semantics. Here, `preset` means initial board content owned by
+this component.
-Check item identity and order, reveal timing, labels, icon assets, evidence alignment, safe zones,
-stack order and optional sounds. Read `../craft/captions.md`, `../craft/overlays.md`,
-`../craft/b-roll.md` and `../craft/sfx.md`; the always-read craft in `../index.md` applies too.
+## Arrange the person and the argument together
+
+Reserve useful space while drawing the host. The example places the person toward the right,
+uses the left for the active player's icon, and gives the lower region to the board and evidence.
+This is an authored composition; another ranking can have another layout. A setting detail can
+balance an offset host so they do not look artificially pushed aside for graphics.
+
+Speech supplies attitude and explanation. Caption follows its reading rhythm. Static or moving
+B-roll can illustrate a joke, comparison or claim on overlapping Selections. The board should remain
+understandable through the appearance and disappearance of those inserts.
+
+Some graphic systems publish both picture and sound. Use their peer outputs deliberately when the
+board already owns its drop or movement sound; an extra Audio Track is useful for distinct sounds,
+not for accidentally duplicating an existing event.
+
+## Give each picture the information role it needs
+
+An icon may identify the actual subject being ranked, establish an initial board state, carry the new
+theme of an adaptation or turn a comment into a visual joke. Decide what the viewer must recognize or
+believe before choosing how to make it.
+
+Use a supplied or found asset when its exact current identity, wording, version or factual authority
+matters; record the source and relevant use conditions. A familiar player, company, product, app,
+meme or public symbol can also be painted by a broadly informed image model when recognizable visual
+meaning is the need. Connect an exact reference when the model cannot reliably own the important
+fact. In reconstruction, preserve the icon's function and the recognition on which the original
+depends. In adaptation, a new subject or visual theme may call for a different icon altogether.
+
+Whichever source is useful, inspect identity, exact version, resolution, crop, padding and transparency at
+the final displayed size. Builds consume the selected project file or generated Output; sourcing is
+an authoring decision rather than work repeated on every Run.
+
+Supporting B-roll has a different job. In the football example, generated comic inserts interpret the
+commentary while player icons identify the board entries. Each insert chooses the visual language its
+joke needs; a parody interface or a theatrical still need not inherit the presenter's phone-camera
+Kit. A factual screenshot or product proof instead gets its authority from the fact it displays.
+
+## Choose the representation the argument needs
+
+A tier board, ordered column and comparison chart have different state and motion. Inspect a plausible
+Surface and use its public inputs. When the work needs a new structure or reveal behavior, create a
+project Track rather than modifying an installed package or forcing unrelated attributes onto it.
+
+Watch the current claim, the icon's movement, the board state and the supporting image together.
+Their timing can reinforce the same idea without all starting on the same frame. Use a shared
+Moment when several layers truly represent one event, and a Selection when a passage owns an interval.
+See [B-roll](../craft/b-roll.md), [Caption](../craft/captions.md), and
+[Track authoring](../../production/track-authoring.md) for those local decisions.
diff --git a/skills/hypit/references/playbooks/formats/scenario-call.md b/skills/hypit/references/playbooks/formats/scenario-call.md
deleted file mode 100644
index 1a6868e0..00000000
--- a/skills/hypit/references/playbooks/formats/scenario-call.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Scenario-call format
-
-Use two final video-call states: A in the main tile with B inset, and B in the main tile with A
-inset. Both tiles remain live while the active speaker changes.
-
-## Author the SVML program
-
-1. Write explicit A/B Script turns and prepare two clean voice references in that order.
-2. Prepare two accepted call-layout images. Image 1 is A-main/B-inset; image 2 is B-main/A-inset.
- Preserve both identities, local rooms, wardrobe, webcam perspective, borders, controls, crop, and
- tile geometry.
-3. Vendor `call-v1.svs`. Select `framing`, `edit-language`, `pacing`, `performance`, `reaction`, and
- `gesture` in an SVS Recipe.
-4. Render each Segment with `copy:Render`; connect Script dialogue and optional English action
- direction through `copy:Set`.
-5. Generate each take with `seedance:ReferenceVideo generate-audio="true"`, the two layout images,
- and the two ordered voice references.
-6. Normalize each take, produce its `whisperx:SemanticTake`, assemble the results with
- `speech:Track`, then add the exact-font Caption chain, Typography, Media, and Audio Tracks.
-7. Assemble in `film:Film`, render with `render:Video`, and stage review/delivery in `.svrun`.
-
-## Preserve call-state truth
-
-- Main and inset geometry must exchange roles exactly; the layout may not drift between states.
-- A's local background remains A's background whether A is main or inset. The same rule applies to B.
- These are two live feeds changing layout, not two physical cameras reversing inside one room.
-- Only the active speaker moves their mouth. The listener remains live through gaze, breath, posture,
- and silent reaction; do not freeze the inset into a portrait.
-- Keep interface controls, borders, labels, and notification states supplied by the accepted layout
- media. Seedance should preserve them, not invent new messages, captions, or badges.
-- Use `typo:Track` for editorial labels or explanations that sit outside the physical call UI.
-
-## Review and reuse
-
-Review the two layout references side by side for exact main/inset exchange, participant/background
-identity, crop, controls, and aspect ratio. Review each take for speaker/voice assignment, lip-sync,
-live listener reaction, UI stability, and generated text. Pin every accepted layout and take with
-`.svrun` `build-record` and `satisfy`.
-
-Read `../craft/seedance-directing.md`, `../craft/captions.md`, `../craft/overlays.md`, and
-`../craft/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 d4773a14..89c71f2e 100644
--- a/skills/hypit/references/playbooks/formats/street-interview.md
+++ b/skills/hypit/references/playbooks/formats/street-interview.md
@@ -1,57 +1,89 @@
-# Street-interview format
-
-Use explicit interviewer, guest and shared street views, two Script Roles, and a microphone handoff.
-Write camera changes and performance together in each take's action, in the order they occur.
-
-## Author the SVML program
-
-1. Write Script turns with explicit interviewer and guest Role Cues. Render the Kit dialogue so the
- interviewer is `A:` and the guest is `B:`.
-2. Prepare three accepted final views in order: image 1 for interviewer A, image 2 for guest B, and
- image 3 for their shared scene and full spatial relationship.
-3. Prepare two clean voice references in the same order: audio 1 for A, audio 2 for B.
-4. Vendor `street-interview-v1.svs`. Select `framing`, `pacing`, `performance`, `reaction`, and
- `gesture` in an SVS Recipe.
-5. For each Script Segment, use `copy:Render` with dialogue plus an English action that states the
- camera and performance sequence directly, then call `seedance:ReferenceVideo
- generate-audio="true"` with all three views and both voices.
-6. Normalize each accepted Segment take, produce its `whisperx:SemanticTake`, assemble the results
- with `speech:Track`, then add Caption, Media, Typography, and Audio Tracks as needed.
-7. Assemble peer Tracks in `film:Film`, render with `render:Video`, and use separate `.svrun`
- Sources with explicit Targets for review and delivery.
-
-## Preserve the street-interview grammar
-
-- Select the shared, interviewer or guest reference directly in the action whenever the camera
- changes. Preserve the authored camera side, background sector and spatial relationship of the
- selected view.
-- Only the active Role moves their mouth. The listener remains alive through eye focus, breath,
- posture, nods, and an appropriate silent reaction.
-- A always holds the same microphone. On A lines it remains near A; on B lines A extends it toward B
- through a believable wrist/arm movement. The microphone must not duplicate or switch hands
- without an authored action.
-- Let each answer complete one natural idea. Compact handoffs are useful, but intelligibility wins
- over speed.
-- In the opening take, include about one second of silent surprise before the first authored line;
- budget it inside the generated duration and do not add unauthored words.
-
-## Add proof and editorial layers
-
-- Place B-roll and proof media with `media-track:Item` during Script Selections. Let the spoken setup
- begin before the picture enters and let the next spoken beat begin before the picture exits when a
- J-cut/L-cut improves continuity.
-- Use the complete Caption chain with one program-wide Planner. Use `typo:Track` for titles, names,
- questions, or CTA copy.
-- Keep exact signs, product labels, and device UI as supplied physical media. Do not ask Seedance to
- add editorial cards or captions.
-
-## Review and reuse
-
-Review speaker/voice assignment, lip-sync, microphone position, listener silence, identities,
-street continuity, reaction timing, text hygiene, and caption placement. Pin accepted scene images
-and takes with `.svrun` `build-record` and `satisfy` before downstream assembly.
-
-Read `../craft/seedance-directing.md`, `../craft/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.
+# Street interview
+
+An interviewer encounters someone with their own life, asks something, and receives an answer worth
+watching. The guest usually carries the story; the interviewer helps the viewer discover it.
+
+## Establish the encounter, then derive attention
+
+For the three-view method, generate a shared image containing both people and their real spatial
+relationship. Derive the guest close view and interviewer close view directly from it. In the
+interviewer view, retaining part of the guest at the opposite edge keeps the exchange legible.
+The guest looks toward the interviewer, and the interviewer looks back across the same screen axis.
+
+```text
+shared street scene ──> guest close view
+ └─> interviewer close view, retaining part of guest
+```
+
+The [worked image directions](../craft/examples/conversation-images.md#street-interview-views)
+show how little the derived prompts need to add once the shared image is doing its job.
+
+`street-interview-v1` uses this supplied set: interviewer A, guest B, shared view, then the two voices
+in A/B order. All ordinary Takes reuse it. Its three-view limit is the design of this Kit, not a
+restriction on every street interview or on Hypit. The interviewer keeps the microphone and moves
+it toward whoever speaks; extending it to the guest is not handing over ownership.
+
+## Cut toward the person who matters now
+
+In the worked piece, guest answers favor the guest close view. A brief neutral interviewer question
+can stay in the shared view; disbelief or an emotionally important challenge earns the interviewer
+close view. This directs attention rather than alternating cameras on a timer.
+
+Action can specify cuts between the Kit's supplied setups. Several questions and answers fit in one
+Segment and one generated Take. Keep the chosen framing behavior within each setup and let the cut
+move directly to the next; an invented travel shot between cameras changes the scene's grammar.
+
+## Give the encounter a before and an after
+
+At the opening, the guest is occupied with something plausible: looking into a bag, checking an
+object, or looking down. The interviewer takes a small step forward and asks; the guest looks up
+or turns toward them in response. Begin the exchange naturally rather than imposing a fixed silent
+delay before every line.
+
+At the end, return attention to the guest and let them begin to turn away after the final thought.
+These small actions imply life outside the clip. They work because of their cause, not because
+every interview must contain the same bag check and exit direction.
+
+For the worked opening, action alongside the Script can make the causal sequence concrete:
+
+```text
+BOY is interviewer A; WIFE is guest B. Open in the shared reference setup. She is looking into her
+bag as he takes a small step toward her and begins the question. She looks up toward him in response.
+Cut directly to her supplied close view for her answer. Use the shared view for his brief follow-up,
+and his supplied close view when the surprising answer earns his disbelief. Keep the reaction
+interested and spontaneous rather than theatrical; he continues to hold and position the microphone.
+```
+
+On the final passage, a short additional direction can return to her close view and let her begin
+turning away after the punchline. The opening and ending actions belong to those actual passages;
+intermediate Takes carry the behavior of their own exchange.
+
+For the middle, give a few readable gestures a purpose: amused certainty, a compact shrug, a glance
+that registers a surprising answer. Avoid exaggerated emotion, constant motion and exact numerical
+finger poses. The performer should seem to respond, not execute an animation checklist.
+
+## Make a reveal one event across several layers
+
+The example's answer Moment updates one slot in an emoji strip, starts a short sound and triggers
+a colored flash. Earlier answers remain visible; future answers remain question marks. Reuse the
+same Script Moment for these consumers so a changed delivery still makes the reveal land together.
+
+Design Caption colors, placeholder and answer icons, flash colors and sound character as one visual
+and rhythmic treatment. An icon's role can supply an accent color; not every layer needs the same
+color. Use actual image assets when matching icon shape and color matters.
+
+This answer strip is a normal project component. Its outer Window owns visibility; child Moments
+own reveals; its implementation owns the resulting persistent state. See
+[Track authoring](../../production/track-authoring.md) for that distinction and other Track roles.
+
+## Caption can follow the guest's head
+
+The worked interview first produced its speaking footage with ordinary Caption placement. Face
+detection on the produced footage then supplied boxes; the author expanded them to head regions
+and rendered again with Caption anchored above those regions, reusing the paid media.
+
+Use [Caption tracking](../craft/caption-tracking.md) when this placement serves the piece. It is a
+specific production loop with an external measurement step, not a required first step for interviews.
+Fixed interviewer Caption and tracked guest Caption can coexist. Fine styles handle these examples;
+a new structural Caption treatment can be a project Caption family using the shared Script,
+Caption data and semantic timing.
diff --git a/skills/hypit/references/playbooks/formats/talking-head.md b/skills/hypit/references/playbooks/formats/talking-head.md
index 1460d08c..f7801eaa 100644
--- a/skills/hypit/references/playbooks/formats/talking-head.md
+++ b/skills/hypit/references/playbooks/formats/talking-head.md
@@ -1,61 +1,65 @@
-# Talking-head format
-
-Use one recurring presenter identity for a sequence of direct-to-camera speech takes, then add
-captions, B-roll, and editorial typography as peer Tracks.
-
-## Author the SVML program
-
-1. Write one Script with a strong opening Segment and 2–3 following Segments for context, evidence,
- mechanism, payoff, or CTA. Keep each generated speaking take inside the selected model's declared range; 8–12 seconds is
- a useful target when the delivery remains natural.
-2. Run `hypit measure` for each Segment before generation and write the literal durations.
-3. Vendor `speaker-v1.svs`. Put stable `composition-stability`, `camera-motion`, `edit-rhythm`,
- `performance`, and `gesture` choices in an SVS Recipe.
-4. Render each take prompt with `copy:Render`; connect the Segment dialogue and one short English
- action direction through `copy:Set`.
-5. Generate each take with `seedance:ReferenceVideo generate-audio="true"`, one accepted full
- presenter/scene image, and the intended voice reference. Keep reference order identical across
- the shot group.
-6. Normalize each accepted take, create one `whisperx:SemanticTake` from that media and its Script
- Segment, then assemble those Semantic Takes in Script order with `speech:Track`.
-7. Add the exact-font Caption chain when captions are wanted: `caption-fine:Style` →
- Script-owned `CaptionDocument`/`caption:Program` → `caption-fine:Track`.
-8. Add B-roll through `media-track:Track`, editorial copy through `typo:Track`, then assemble with
- `film:Film` and render with `render:Video`.
-
-## Direct the presenter
-
-- Keep face, apparent age, hair, wardrobe, room, light direction, lens feel, and framing envelope
- stable across A-roll.
-- Put spoken words only in the Script-derived dialogue slot. Put visible performance in the action
- slot: gaze changes, brows, nods, compact gestures, posture, breath, or one motivated object action.
-- Let each Segment finish one thought. Do not fragment a sentence merely to manufacture more cuts.
-- Keep hands inside the established frame and away from the face unless contact is the authored
- action. Preserve every prop's count, support, label, and starting position.
-- Use B-roll for a genuine change of place, proof, mechanism, or emotional state. Do not make the
- presenter identity drift to create variety.
-
-## Handle screens and reverse views
-
-When the presenter-facing shot is paired with a device-facing proof shot, define both camera
-positions before generating either image. The two opposing views must show different background
-sectors and different dominant landmark sets. Reusing the same wall, window, or furniture group is
-an automatic rejection. Preserve the same room, presenter, device, lighting logic, and eye line.
-
-Use supplied UI media whenever exact interface content matters. Keep explanatory text on
-`typo:Track`, not inside the generated shot.
-
-## Review and reuse
-
-- Review the full-resolution presenter image before any speaking take.
-- Review every A-roll take for identity, lip-sync, exact words, voice assignment, stable background,
- hands, props, and generated text.
-- Review B-roll independently, then review the joined Film for pacing, semantic timing, caption
- collisions, and audio clarity.
-- Pin every accepted image and take in the next Build with `.svrun` `build-record` and `satisfy`.
-
-Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`,
-`../craft/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.
+# UGC and talking-head performance
+
+A compelling person speaks to the viewer. Their attitude carries the piece; Caption, evidence and MG
+help the viewer follow it. A ranking board is one possible companion, not a requirement of UGC.
+For that relationship, combine this page with [Ranking](ranking-listicle.md).
+
+## One useful image can carry the whole performance
+
+Make a character-and-scene image with the presence, camera distance, posture and available graphic
+space the video needs. [Image direction](../craft/image-direction.md) owns that craft. A person placed
+slightly right can leave room for an icon on the left; a table or the direction of their seated body
+can make that composition feel inhabited. Choose it for this layout, not as a universal UGC pose.
+
+Use that same image and the person's recurring voice reference for every ordinary talking Take.
+The Ranking example does exactly this for both player passages. Each Take returns to the same useful
+visual premise and contributes another piece of the edited performance.
+
+Natural cuts are part of the desired result. A small change in pose between passages can make the
+video feel like a creator's edited recording. Stable character-and-scene references can support each
+Take independently because this work wants edited speech rather than an unbroken simulated recording.
+
+## Use the tested Speaker Kit when its shape fits
+
+For a single presenter returning to one useful camera image through natural edited cuts, `speaker-v1`
+from `@hypit/seedance-kits` is a tested fit. It combines that character-and-scene image, one voice
+reference, Script dialogue, a Recipe for recurring direction, and optional action Text for the passage.
+Read the package README for assembly and the selected template for its actual choices. A work whose
+camera, cast, or performance relationship differs can use another Kit or ordinary authored direction.
+
+In the worked Ranking example, its Recipe combines stable framing with
+`edit-rhythm: pause-trim-jump-cuts`. The camera can
+stay fixed while the edit removes dead pauses and the performer remains expressive. This is a prompt
+instruction to the generator; it does not run an automatic trimming operation on the returned file.
+
+Action supplies what the scene means to this person. For a teasing ranking host, amused disbelief,
+a knowing look and a compact dismissive gesture are more useful than a limb-by-limb animation plan.
+Give a few actions a reason: a shrug dismisses an argument; a quick lean makes a punchline personal.
+Let speech, Caption or MG carry exact numbers while the hand makes a readable emphatic gesture.
+
+One useful action direction, alongside Script dialogue, is:
+
+```text
+Play this as an affectionate roast from someone who knows the subject well. Start with amused
+certainty, let the comparison earn a brief disbelieving look, and land the last line with a small
+knowing shrug. The free hand makes relaxed emphatic gestures; keep the microphone easy and steady.
+```
+
+This illustrates attitude and a few visible beats; it does not prescribe every creator's personality.
+See [Directing generated performance](../craft/seedance-directing.md) for listeners, gestures and cuts.
+
+## Let speech and graphics do different work
+
+Write natural stages in Script and measure each Segment before choosing a literal generation
+duration. A Segment can contain several edited shots, Caption Cue Breaks, graphic changes and
+speaking turns. Choose its boundaries and length from the performance it carries.
+
+Normalize the produced speaking media, align its own audio to its Segment, and assemble the
+SemanticTakes. Keep that performance's sound when B-roll covers its picture. Place evidence on
+Selections and reveals on the component's declared timing inputs. A persistent board can continue
+through a cut while the current portrait, evidence image and Caption change.
+
+Watch whether the person feels engaged and whether the visual layers support that engagement.
+Stable identity and a coherent setting matter; identical pose at every seam does not. A static
+expression, mechanically repeated gestures or relentless intensity can undermine the result even
+when every requested word is present.
diff --git a/skills/hypit/references/playbooks/formats/two-person-podcast.md b/skills/hypit/references/playbooks/formats/two-person-podcast.md
index 57281251..8258ceaf 100644
--- a/skills/hypit/references/playbooks/formats/two-person-podcast.md
+++ b/skills/hypit/references/playbooks/formats/two-person-podcast.md
@@ -1,57 +1,96 @@
-# Two-person podcast format
-
-Use two final camera-view references and intentional speaker/reaction cuts to build a coherent
-two-person conversation.
-
-## Lock the two-view geometry first
-
-Draw the room and name camera positions A and B before generating either view.
-
-- View A and View B belong to the same room, but they must show different background sectors and
- different dominant landmark sets.
-- The two backgrounds must never be identical, near-identical, horizontally mirrored, or the same
- wall with only the person changed.
-- Preserve seating, eye lines, table edge, microphones, shared props, light direction, lens feel,
- and left/right relationship across the pair.
-- Reject and regenerate both images when the geometry cannot explain how the two cameras occupy the
- room.
-
-## Author the SVML program
-
-1. Write Script turns with explicit A/B Role Cues. Use Dual Text for exact display/pronunciation
- differences while preserving the intended visible spelling.
-2. Prepare the accepted final A-view and B-view images plus ordered A/B voice references.
-3. Vendor `podcast-v1.svs`. Select `framing`, `edit-language`, `pacing`, `performance`, `reaction`,
- and `gesture` in an SVS Recipe.
-4. Render each Segment with `copy:Render`, Script dialogue, and an optional English action direction.
-5. Generate each take with `seedance:ReferenceVideo generate-audio="true"`, both final views, and
- both voice references in the Kit's declared order.
-6. Normalize each accepted take, produce its `whisperx:SemanticTake`, assemble the results through
- `speech:Track`, then add exact-font Captions, evidence Media, Typography, and optional Audio Tracks.
-7. Assemble with `film:Film`, render with `render:Video`, and use separate `.svrun` Sources with
- explicit Targets for staged review and delivery.
-
-## Direct turns and cuts
-
-- Let each speaker finish a natural thought. Short challenges may lead into longer grounded answers;
- do not create rapid alternation by splitting one sentence into fragments.
-- Use the Recipe's speaker-following or reaction-cut pattern. Do not write camera cuts, new angles,
- zooms, or location changes into the action slot.
-- Camera stability and performer intensity are independent: a host may lean, laugh, gesture, or
- change posture while the two established camera views remain fixed.
-- Only the current speaker moves their mouth. A listener cutaway stays silent but visually alive.
-- A skeptical format works well as bold claim → short challenge → mechanism/evidence → grounded
- payoff that returns to the hook. A phone CTA is optional and appears only when the Script requires it.
-
-## Review and reuse
-
-Review the two reference images side by side before video generation. Reject same-background reverse
-views, broken eye lines, contradictory seating, duplicated microphones, prop drift, or impossible
-lighting. Then review every take for voice assignment, exact words, lip-sync, reaction timing,
-camera selection, and identity. Pin accepted views and takes through `.svrun` `build-record` and
-`satisfy`.
-
-Read `../craft/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.
+# Two-person podcast
+
+The relationship between two people carries the argument: a question invites a claim, a reaction
+changes its meaning, and a reply pays it off. Let that relationship motivate framing and performance.
+
+## Build the pair from a useful first view
+
+Generate the main host in the actual setting first. Use that image to derive the other host's
+complementary view: opposite screen position and gaze, microphone entering from the other side,
+and another visible sector of the same location. The first host view establishes the shared world;
+the complementary view changes what the other camera can see.
+
+The worked restaurant example has this reference structure:
+
+```text
+main host in restaurant ──> other host in restaurant
+main host + product ──────> main host holding product
+other host + product ─────> other host holding product
+main host (+ logo) ───────> each lifestyle scene
+both host views ──────────> optional split-screen opening image
+```
+
+Most new views are one hop from their useful parent. Derive lifestyle scenes from the main host,
+not from one another. Product-holding views inherit their own host's camera and add the actual
+product reference. Preserve gaze, lighting and microphone placement while changing the intended
+prop state. File imports are valid inputs even when those images were generated outside Source.
+
+[Podcast and interview image examples](../craft/examples/conversation-images.md) preserve the
+concrete English production directions and explain what each reference is responsible for.
+
+## Direct conversation inside a Take
+
+`podcast-v1` takes two final camera views and two voices, in matching A/B order. Map the Script's
+actual Role names to those hosts explicitly in action direction. Script remains the sole dialogue
+text; a single Segment can contain several turns and speaker cuts.
+
+The Kit's Recipe supplies recurring framing, editing, pace, performance, reaction and gesture choices.
+Action adds this passage's attention and interaction: who is making the claim, who is skeptical,
+when a reaction earns the other view, and who holds the product. Keep silent listeners physically
+alive through a posture adjustment, a brief glance down and back up, or an attentive expression while
+preserving their silence.
+
+A handoff needs legible possession. The main host offers the product toward their partner; the
+partner receives it in the complementary view; later shots reflect who now has it. A few clear
+relations are more useful than prescribing every finger. Cuts can carry this exchange without
+requiring serialized frame-continuation generation.
+
+For example, action accompanying a product-offer passage can say:
+
+```text
+GIRL is Host A and GUY is Host B. She treats the recommendation with amused certainty; his reaction
+is playful disbelief, not outrage. She offers the product toward the left edge of her view. In his
+complementary view it arrives from the right; he receives it and keeps it. When returning to her,
+the product is no longer in her hand. Keep the exchange casual, with compact gestures and no
+extra dialogue.
+```
+
+This particular direction assumes those view and prop inputs. A phone link sent digitally calls for
+the corresponding screen or conversational interaction instead of a physical handoff.
+
+## An opening can establish both people at once
+
+A top/bottom split screen can immediately reveal the pair before the first question finishes. In
+the worked example, the man speaks above while the woman below looks down, adjusts her seat and
+looks back up. Those small silent actions establish a conversation already in progress.
+
+```text
+Keep the supplied top-and-bottom composition. The man in the upper panel delivers the question to
+his partner. In the lower panel, the woman briefly looks down, settles into her seat and looks back
+toward him as she listens. She remains silent. Let both panels feel like the same conversation
+already underway, without large gestures or a frozen listener.
+```
+
+The split reference and its matching video direction form one authored opening Take that can carry
+both people and a speaker change. The ordinary two-view Podcast Kit suits the later exchange. Use a
+split-screen opening when that attention device serves the work; use another component or Take shape
+for a different layout.
+
+## Coverage can follow a thought rather than every noun
+
+The example generates three lifestyle scenes together as a short silent montage, then places that
+one clip over a Selection spanning the host's examples and the start of the partner's response.
+The viewer understands the broader habit even when each visual cut is not synchronized to its noun.
+Give the montage enough room to play through once at native speed, so its last scene is not cut off.
+The Selection may slightly outlast the clip; let the underlying picture return when playback ends.
+The partner's incoming voice can precede that return: a useful J-cut relationship. Avoid a frozen
+tail or retiming merely to fill the Selection. Use the B-roll craft's current playback guidance
+rather than treating an existing project's Recipe as a required choice.
+
+Use separate clips when exact scene-to-cue correspondence matters, especially in reconstruction.
+Generate each within the selected model's actual range and consume only the needed section. Read
+[B-roll](../craft/b-roll.md) for source duration, `stretch`, short windows and gap-free boundaries.
+
+Host-colored Caption can clarify the speaker even over full-frame B-roll. Coordinate it with the
+scene palette and product treatment; choose the colors for this pair. Judge the whole exchange for
+responsive timing, restrained reactions, prop continuity and a payoff that feels earned.
diff --git a/skills/hypit/references/playbooks/index.md b/skills/hypit/references/playbooks/index.md
index 3ad67b7e..16ded81a 100644
--- a/skills/hypit/references/playbooks/index.md
+++ b/skills/hypit/references/playbooks/index.md
@@ -22,8 +22,18 @@ not need a matching playbook before it can be understood or made.
| Read | When the current question concerns |
| --- | --- |
+| [Directing generated images](craft/image-direction.md) | phone-video realism, character presence, image prompts, materials and palette, or preparing a useful visual reference |
| [Voice and performance](craft/voice-and-performance.md) | who performs speech, recurring voice identity, A-roll under coverage, or genuinely independent narration |
+| [Directing generated performance](craft/seedance-directing.md) | using a video Kit, directing attitude and small actions, natural cuts, listeners, or sizing Takes |
+| [Reference relationships](craft/generated-dependencies.md) | deciding which images or Takes should depend on which references |
+| [Visual continuity](craft/visual-continuity.md) | complementary camera views, gaze, prop state, or what must remain coherent through a cut |
+| [B-roll](craft/b-roll.md) | exact cue coverage versus montage, short display windows, source playback, J-cuts, or adjacent Selections |
+| [Frame coverage](craft/frame-coverage.md) | an unintended exposure, gap, crop or transition at a visual boundary |
+| [Caption](craft/captions.md) | speech-linked text, reading rhythm, Fine styles, or a new Caption family |
+| [Caption tracking](craft/caption-tracking.md) | measuring produced footage and placing Caption above a moving head without regenerating the media |
| [Sound and mix](craft/sound-mix.md) | the relationship among speech, music, ambience, effects, loudness, ducking, and continuity |
+| [Graphic composition](craft/graphic-compositions.md) | visual hierarchy, boards, graphic state, editable structure, component boundaries or coordinated palette and reveals |
+| [Compositing](craft/compositing.md) | overlays, picture-in-picture, cutouts, screen evidence, container versus content motion, or live call layouts |
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
@@ -33,6 +43,10 @@ unless the decision has changed.
| Read | When the work's shape includes |
| --- | --- |
+| [UGC and talking-head performance](formats/talking-head.md) | one person directly addressing the viewer, with natural edited performance |
+| [Two-person podcast](formats/two-person-podcast.md) | complementary host views, conversational reactions, product interaction or lifestyle coverage |
+| [Street interview](formats/street-interview.md) | a motivated encounter, guest/interviewer/shared views, reveals or tracked Caption |
+| [Ranking and listicle](formats/ranking-listicle.md) | a persistent comparison or board whose state changes with the argument |
| [Narration-led work](formats/narration-led-demo.md) | independent narration organizing products, hands, screens, demonstrations, montage, or MG |
A format page is useful when its relationships illuminate this work. It is not a category the
diff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.md
index ba9ad666..d06b9ad4 100644
--- a/skills/hypit/references/production/authoring.md
+++ b/skills/hypit/references/production/authoring.md
@@ -3,6 +3,12 @@
Read this when turning the current Treatment into Author Sources, Recipes, Runs, project components,
and Builds, or when revising an existing production.
+[Source syntax](source-syntax.md) explains imports, references and language forms.
+[Composing Tracks](tracks.md) connects the visual and audio roles; [Track authoring](track-authoring.md)
+and [Caption authoring](caption-authoring.md) explain creating a new project component for them.
+[System relationships](system.md) connects these concepts to execution and Results;
+[media preparation](media.md) explains the values entering the timeline.
+
## Turn the Treatment into relationships
Begin with the work the Treatment describes, not with a package inventory. Identify:
@@ -22,6 +28,10 @@ When observation has already produced useful authored data—such as a per-frame
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.
+When the desired measurement depends on generated footage, the first Build supplies that footage.
+Observe it, author the resulting data, and reuse the produced media in the next composition Build.
+[Caption tracking](../playbooks/craft/caption-tracking.md) describes this loop for head placement.
+
## Give each production surface one job
- An **Author Source** (`.svml`) owns the target Script, media requests, components, Tracks, Film, and
@@ -34,26 +44,25 @@ component's declared input. It is part of the chosen production design, just lik
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.
+their demanded Outputs or Candidate selections genuinely differ. 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 [Source syntax](source-syntax.md) for language forms and [Runs](runs.md) for execution choices.
+`hypit vocabulary <package>` or a focused tag or visual query supplies the installed Surface's
+attributes and outputs. Package-local documentation supplies its exact behavior and API. Source
+imports select author vocabulary; Runtime configuration selects external facilities.
## 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.
+the demanded Output is usually the finished video, and the Build produces its required media
+dependencies through the same graph. 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.
+Every public Author Output that completes while satisfying the demanded Target 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.
The Author Graph supplies primary Candidates. A Run may explicitly select another compatible
Candidate for a Logical Output:
@@ -65,14 +74,21 @@ Candidate for a Logical Output:
- `<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.
+compatibility and plans the combined Author and Run graphs. It replaces the displaced upstream
+subgraph 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.
+Stand-ins carry the dimensions, duration, and clock required by downstream composition.
+[Runs and substitutes](runs.md#a-complete-layout-preview) provides a complete example with media
+normalization and estimated semantic timing.
## Reuse produced work explicitly
+For a revision or retry, continue using produced media that still serves the current intent. Preserve
+the Run's unrelated Candidate selections and add explicit selections for newly completed Outputs
+that the next Build should keep. Replacing one image or changing a Caption does not release every
+other output back to generation. Removing a `satisfy` restores that output's primary Candidate, which
+may submit a new paid request even when the Source and output name have not changed.
+
The exact address of an earlier public Output is its Build id plus Output name:
```svml
@@ -86,18 +102,40 @@ the old Result's public name, while `satisfy output` names the current graph pos
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.
+Output, then write that exact choice into the Run. Results retain public Outputs even when no file
+was exported into `assets/` or `output/`; inspect them before concluding that material is missing.
+A failed or cancelled Build may still contain completed public Outputs worth using. Reuse those
+Outputs rather than submitting their generation again to recover a later failure. 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.
+submitting the same paid media requests again. The following examples locate the reuse boundary:
+
+| Current change | Keep through Candidates | Recompute or request |
+| --- | --- | --- |
+| Caption appearance, MG, an Effect or composition changes | Existing media and SemanticTakes whose Script identities and timing still apply | The changed visual systems and render |
+| Only some B-roll images must change | The existing performance, voice and all other still-useful media | The deliberately replaced images and their downstream composition |
+| The same video needs different normalization or semantic timing | Its generated video Output, or normalized media when that still applies | The affected normalization or alignment and downstream consumers |
+| New spoken wording requires a new performance | Unaffected Takes and other still-useful inputs | The changed performance and the timing derived from it |
+
+Choose an Output upstream of the work being changed, with the same nominal Type and the intended
+creative meaning. An unchanged SemanticTake can preserve both media and alignment. It is valid only
+while its Narrative, Segment, token and anchor identities and timing still describe the current
+Script and media. A Script edit does not automatically invalidate every Take; inspect what changed.
+Do not satisfy a changed Track or final composition with its old rendered Output, which would hide
+the current edit. Type compatibility alone cannot establish that an old performance or timing still fits.
+
+For example, correcting three wrong B-roll selections means replacing those selections while keeping
+the produced performance. Inspect the resulting plan: the new image requests may be intended; a new
+performance request is not explained by that correction. [Builds](builds.md) covers submission and
+inspection when an earlier attempt may still be running.
## 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.
+Before editing an existing production, establish the current facts that can affect the change. Read the
+relevant parts of its Brief and Treatment and the affected Source, Recipe or Run; inspect Results and
+Runtime activity when reuse or active execution matters. Read the relevant diff and preserve unrelated work.
- Revise Treatment when the creative design changed.
- Revise Script when words, Cue breaks, Selections, or Moments changed.
@@ -113,7 +151,7 @@ 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.
+`hypit check` establishes Source and graph legality. `hypit plan <run>` shows the selected graph 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
index 7dd2c24e..6860af39 100644
--- a/skills/hypit/references/production/builds.md
+++ b/skills/hypit/references/production/builds.md
@@ -1,12 +1,65 @@
# 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.
+Build, continuing after a failed attempt, following work after an observer disconnects, or retrieving
+completed Outputs.
+
+[Runs](runs.md) owns Candidate syntax and substitutes. [System relationships](system.md) explains
+how the selected graph becomes a Build, and [rendering](rendering.md) covers whole or partial video outputs.
+
+## Reuse available Outputs and identify active Builds
+
+For a revision, identify the relevant Run and its completed Outputs, then preserve the still-useful
+ones with `build-record` and `satisfy`. Keep unrelated Candidate selections. [Authoring](authoring.md#reuse-produced-work-explicitly)
+explains which media or SemanticTake Output to keep without freezing the downstream edit. A failed
+Build can still supply completed Outputs; a missing exported file is not evidence of missing media.
+
+If the CLI or observation tool loses its reply while submitting or following a Build, inspect the
+local Runtime and project Results: the Worker may already be executing that Build.
+
+```bash
+hypit activity
+hypit status <build-id>
+hypit builds
+hypit inspect <build-id>
+```
+
+Use the original project and Runtime Profile for activity, status and cancellation; pass
+`--runtime <profile>` when it is not the project's selected Profile. `builds` and `inspect` read
+project-owned Results without a Runtime argument. An empty activity view in another Runtime does
+not establish that the original submission stopped.
+
+Use the known Build id. If it was not returned, use project activity and Results to identify the
+submission from its Run, Source and submission time; the latest unrelated Build is not its identity.
+Follow active work with `status --watch` and reuse completed Outputs. A closed terminal or interrupted
+observation is distinct from a failed Provider request inside the Build. Finishing an incomplete
+Result is covered below and does not require regenerating media.
+
+## Continue after a failed attempt
+
+A failed Build leaves the work and evidence produced by that attempt. Prepare a new Run that selects
+its usable Outputs through `build-record` and `satisfy`, then submit a new Build for the remaining
+work. The next attempt's choices belong in that Run; the earlier Build retains its failure.
+
+When a Provider task-submission request times out without a task ID or another usable receipt,
+report the request failure and the absence of a receipt. The available information cannot distinguish
+a request that never created a task from one whose acknowledgement was lost. Record that uncertainty
+and proceed with a new submission through a new Build under the user's spending authority. Establishing
+the unknown remote outcome is not a prerequisite for continuing, and there is no receipt to recover
+or query. Keep any Outputs already available from the attempt selected in the new Run.
+
+When a usable receipt does exist and gives access to a generated asset, the Agent can retrieve that
+asset as an ordinary project file and select it with `file` and `satisfy` in the new Run. This supplies
+the file Output; downstream preparation and alignment still run when needed. A completed SemanticTake
+can instead be reused directly through its existing Result Output.
+
+Use `status <build-id> --verbose` for active task receipts and `inspect <build-id> --json` for the
+finished Result's execution records. They include the Endpoint, Need identity, credential references,
+known task ID, and the recorded error or last progress. Secret values stay in their Credential Store.
## 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.
+Plan the actual Run after its reuse choices and requested changes are expressed:
```bash
hypit check path/to/build.svrun
@@ -23,10 +76,16 @@ Provider's declared price page or that its price source is unknown. Hypit does n
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.
+Read the remaining Needs against this change. A Caption or MG-only revision should keep its existing
+media generation satisfied; replacing selected B-roll should leave the unchanged performance satisfied.
+Rendering and other required processing may still appear as Needs. Explain each new media request
+from the user's goal or an explicit generation decision. If a request appears because a Candidate was
+lost or never selected, repair the Run and plan again before asking to spend or submitting work.
+
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.
+obtain authorization before `build`. Authorization to correct downstream work does not silently extend
+to regenerating unchanged media. Additional paid work outside the authorized scope needs a new decision.
## Submit one durable Build
@@ -35,8 +94,9 @@ 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.
+did not change. Cross-Build reuse requires explicit Run Candidates; repeating the same command does
+not resume the earlier Build or automatically select its Outputs. 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
@@ -69,6 +129,13 @@ 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.
+When an action fails, the attempt ends and local reservations are released. Any last-observed remote
+status remains evidence, rather than a condition the old Build must resolve before the next attempt.
+
+Providers that expose `actionLimits` can separately limit asynchronous `submit`, `poll` and `collect`
+actions through `concurrency` and `rate: { limit, periodMs }`. These budgets share the Profile's pool.
+Task occupancy, overlapping network actions and starts permitted per time period are different quantities;
+`activity --json` exposes the actual resource claims. Provider-local documentation owns available settings.
## Separate active work from Result outcome
@@ -93,12 +160,16 @@ Producer, resubmit generation, or choose another Candidate. Use it only for the
`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:
+When the user asks to stop submitted work, cancel that exact Build explicitly:
```bash
hypit cancel <build-id> --reason "superseded by the corrected Run"
```
+Check the reported state afterward. Detaching the observer does not send this cancellation, and a
+cancellation request cannot undo already completed Provider work. Preserve completed usable Outputs
+and leave unrelated Builds alone.
+
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.
@@ -135,6 +206,26 @@ The title, note, and highlights live in that Result manifest. They do not rename
or create a project-wide history index. Reuse still names the exact Build id and Output through the
Run mechanism in `authoring.md`.
+## Select the Result repository deliberately
+
+Result storage belongs to the video project. The official default is the filesystem repository at
+`.hypit/results`. An explicit `hypit.results.json` selects an adapter with the envelope
+`format: "hypit.build-results@1"`, `use` and adapter-owned `config`. Read the installed
+`@hypit/build-result-fs` README for a custom filesystem path, or `@hypit/build-result-s3` for bucket,
+prefix, deployment options and its credential setup. Do not put this selection into the Runtime
+Profile or assume a generation Endpoint's credentials also configure S3.
+
+`hypit paths` locates the project; `hypit doctor` checks its selected repository, even without a
+Runtime Profile. Result listing, export, history and Studio's finished library read that repository.
+If expected Results are absent, first check the project and repository selection rather than
+regenerating media or searching Runtime SQLite as a history database.
+
+A submitted Build retains the repository destination captured at submission. Changing the project
+selection while it runs does not redirect its eventual Result. Use the original destination to
+find that Result; changing a selection does not migrate earlier history. Preserve any Result that
+still supplies a Run Candidate: exported files are optional copies, and explicit reuse may still
+reference Resources in the original Result.
+
## Reload changed execution code deliberately
A running Worker keeps the Runtime Profile, inherited environment, Distribution code, and package
diff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.md
new file mode 100644
index 00000000..40e4e576
--- /dev/null
+++ b/skills/hypit/references/production/caption-authoring.md
@@ -0,0 +1,110 @@
+# Writing a Caption family
+
+Read this when a work needs a new relationship among its spoken words, layout and motion.
+[Caption craft](../playbooks/craft/captions.md) owns readability and directing judgment;
+[Track authoring](track-authoring.md) owns project package wiring.
+[Fonts and text](fonts-and-text.md) explains exact font resources and fallbacks;
+[component visuals](component-visuals.md) explains the final drawing representation.
+
+## Decide what is actually new
+
+Fine Caption already covers uniform flowing text with exact fonts, Paint, boxes, karaoke states,
+placement and motion. Different colors, Role styles, cue entrances or head tracking may only require
+Source and Recipe changes. A keyword occupying a separate oversized line, words playing different
+visual roles, or a recurring spatial relationship among speakers can justify a new family directly.
+Creating that family is normal video production.
+
+The result is still Caption when the displayed words correspond to speech and remain close to its
+delivery. Independent slogans, summaries and titles usually belong to Typography even if they react
+to a Script Moment.
+
+## Keep the existing text and timing chain
+
+```text
+Script → CaptionDocument (display words, alignment units, authored Cue breaks)
+Styles + Role / Selection / word-attribute applications → CaptionProgram
+CaptionDocument + CaptionProgram + SemanticTrack → TimedCaptionProjection
+projection + family parameters → explicit family schedule
+schedule + document + program + ProgramSpace → VisualTrack
+```
+
+Reuse `@hypit/caption` for the common Program and timing join. It handles display-versus-spoken
+wording, N:M alignment units and complete-unit Selection boundaries. Do not transcribe again,
+rebuild timing by splitting a string, or use the video model's requested duration as speech evidence.
+The package README explains the extension inputs and points to their owning implementations.
+
+The ordinary Program Surface remains useful with a new family's Styles:
+
+```svml
+<caption:Program id="captions" document={story.caption} narrative={story}
+ default={base-style}>
+ <caption:Use role="GUEST" style={guest-style}/>
+ <caption:Use selection={story.selection.punchline} style={punchline-style}/>
+</caption:Program>
+```
+
+These names assume Styles have already been declared by the chosen family. They are complete Style
+applications, not CSS inheritance. For word-specific roles, Script can mark `useful{emphasis}` and
+`caption:Use attribute="emphasis"` can select a Style. The new family must deliberately interpret
+the resulting word runs; Fine rejects them. A structural word role should not be guessed by the
+renderer from spelling, capitalization or “the third word.”
+
+## Design a family-specific schedule
+
+Separate measured speech time from visible time. Preserve each alignment unit's measured boundaries
+and identity; resolve lead, tail, stagger, hold and handoff into an explicit schedule before rendering.
+The renderer draws that schedule and does not silently add another tail or reorder Cues.
+
+For a “large keyword plus supporting phrase” family, the schedule might identify each Cue's display
+words, its emphasized word ids, their measured units and the visible interval of the two groups.
+Its layout then computes the two groups together. Decide what happens with no keyword, several
+keywords, long text and an N:M pronunciation span. Make author correction possible through word
+attributes, `||` and Style configuration instead of inventing missing text or dropping words.
+
+The common projection respects authored Cue breaks and structural boundaries. Visual line wrapping
+is a separate operation. A narrow width should not silently rewrite the Script into new spoken Cues.
+If the family needs an additional grouping rule, give that rule explicit parameters and preserve the
+original word/unit associations in the schedule.
+
+`caption:Mute` suppresses selected display units while preserving speech. A new family should use
+the common mute application when scheduling, as Fine does. Validate that schedule, document, narrative
+and ProgramSpace belong together; do not silently accept timing from another video.
+
+## Give Style, layout and rendering clear owners
+
+The Style Surface validates a Recipe and exact font references, then emits the common Caption Style
+shape with the new family's name and parameters. The Track Surface accepts the document, semantic
+timeline and Caption Program; its Fragment performs the common timing join and its own schedule and
+render operations. Register the new family's Producers and any new schedule Type in its own package.
+
+The renderer owns typography, structural relationships, stacking and motion. Use the existing text
+shaping and Visual IR facilities; do not depend on an arbitrary system font or browser layout state.
+Read `@hypit/caption-fine`'s `fragment.ts`, `schedule.ts` and `render.ts` as separate implementation
+examples. Reuse the common parts and replace the actual family behavior, including its parameter
+validation; renaming Fine while retaining its uniform-word assumption will not implement a structural
+keyword treatment.
+
+The common Program does not automatically dispatch Styles to different renderers. Fine rejects a
+foreign family. A new family can provide its own ordinary and emphasized treatments in one Program;
+if the work combines separate Caption Tracks, author their coverage or mutes so the same words do
+not appear twice. Define any mixed-family support explicitly in the component that implements it.
+
+If this family supports spatial tracking, take an explicit RegionTimeline and map it into the actual
+composition. Define subject matching and absent-region behavior. Detection belongs to the measurement
+step described in [Caption tracking](../playbooks/craft/caption-tracking.md), not to this renderer.
+
+## Check the relationships that matter
+
+Use a short Script with a normal phrase, the new structural treatment, a Role change and a Dual Text
+unit. Verify displayed words and their association with measured speech, then inspect the new layout
+at the intended frame size and around its handoffs. Check long words, overflow and direct seeking
+where relevant. A still can show typography; only the configured timeline establishes timing.
+
+Expose the family with useful vocabulary and a designed preview. Keep wording, font choices, palette
+and authored word roles editable in the project. The package adds its rendering language while
+consuming the existing Script, Caption and semantic-time owners.
+
+For live Cue entities and Inspector editing, add a [Studio Companion](studio.md#give-a-project-component-a-useful-companion)
+that consumes the family's actual schedule, CaptionDocument and Program. Preserve the selected
+Style reference for each Cue rather than exposing one misleading global Style. Caption Fine's
+Companion is a useful example of these relationships; the new family's layout stays in its renderer.
diff --git a/skills/hypit/references/production/component-sharing.md b/skills/hypit/references/production/component-sharing.md
new file mode 100644
index 00000000..46f5c084
--- /dev/null
+++ b/skills/hypit/references/production/component-sharing.md
@@ -0,0 +1,51 @@
+# Sharing an Author Package
+
+Read this when a project component has become useful in another project.
+
+## Keep one identity
+
+A new component begins as an ordinary package in the video's project, normally under `packages/`.
+Give it the owner's scope from the start, such as `@studio/score-strip`. Its Source import names the
+logical Module ABI:
+
+```xml
+<import as="score" from="@studio/score-strip@1"/>
+```
+
+The trailing `1` is the Module interface version. The package manager separately records the npm
+release installed by this project. Moving the same package from a project workspace to a registry
+does not require a new Module name, a new tag, or a copy in the Hypit repository.
+
+## Share with the ordinary package system
+
+When the owner wants cross-project use, build the package to JavaScript and include the activation,
+preview assets, and files its vocabulary opens. Publish that package to the owner's npm scope or
+private registry. The consumer installs an explicit release and commits its ordinary lockfile:
+
+```bash
+pnpm add @studio/[email protected]
+```
+
+Changing the installed release is an explicit package-manager operation. A Build never installs or
+updates component code. Hypit reads the version already selected by the project, and a missing
+package remains a precise installation problem.
+
+An executable Author Package uses `hypit/author-kit` plus the relevant `hypit/*` domain subpaths while
+it is developed, then publishes only its own built code and assets. The current Hypit Distribution
+supplies those APIs when it loads the activation. Package code is trusted JavaScript in the current
+process, so install only code the project owner chooses to run.
+
+## Data packages remain data
+
+A Prompt Kit does not need activation code. It can export an `.svs` Source from ordinary package
+`exports`, and a project imports that exact Source:
+
+```xml
+<import as="ugc" source="@studio/image-kits/phone-ugc-v1"/>
+```
+
+This reads the selected package data without activating JavaScript. The package manager still owns
+installation and versioning; Hypit does not scan a registry or maintain a second catalogue.
+
+If Hypit itself later adopts a component as an official Distribution capability, that is a separate
+product and framework decision. Cross-project reuse does not depend on that adoption.
diff --git a/skills/hypit/references/production/component-visuals.md b/skills/hypit/references/production/component-visuals.md
new file mode 100644
index 00000000..f093dad5
--- /dev/null
+++ b/skills/hypit/references/production/component-visuals.md
@@ -0,0 +1,85 @@
+# Drawing a component
+
+Read this while implementing a project component's rendered output. [Track authoring](track-authoring.md)
+owns its author interface, temporal inputs and state behavior. [Spatial layout](spatial.md) explains
+the incoming geometry; [Studio](studio.md) explains an optional Companion.
+
+## From program to visible Track
+
+A component's drawing output describes what appears, where it appears and how it changes over its
+visible lifetime. For a reveal card, those decisions become a box and text, a destination Frame,
+an entrance animation and the interval for which the answer remains visible.
+
+A component can first compute a domain program, such as a list of answers and their reveal times.
+Its drawing Producer receives that program, ProgramSpace, Frames, Style and explicit assets, then
+returns a VisualTrack. A simple component can produce the Track directly when no separate program
+would help its behavior or editing.
+
+The public representation has these parts:
+
+| Part | What it means |
+| --- | --- |
+| Track | Named picture contribution belonging to one ProgramSpace |
+| Present | An independently timed and stacked appearance |
+| `span` | Program frames from `startFrame` through the frame before `endFrameExclusive` |
+| `stacking` | Absolute paint order among Presents; higher order appears above lower order |
+| Elements | One rooted tree of boxes, text, media, masks or compositable surfaces |
+| Animation | Keyframes relative to the containing Present's start |
+
+Use several Presents when items have separate lifetimes or stacking positions. A persistent board
+can keep its settled rows visible while later rows enter. Its domain program decides those spans
+and states; the drawing output makes them explicit.
+
+## A working drawing function
+
+[visuals.ts](examples/visuals.ts) contains `renderCard`, a complete pure drawing function using
+`sealVisualTrack` from `@hypit/composition`. It receives a projected span and a resolved Frame,
+draws a colored box with exact-font text, and optionally fades in relative to the Present's start.
+Its colors, size, padding, layer and entrance duration are supplied by the caller.
+
+The root uses Canvas coordinates. The text child uses the root's local coordinates, so padding is
+added once. When a component computes child geometry in Canvas space, subtract the parent's origin
+before writing child `left` and `top`.
+Element `order` values are distinct within the Present; `stacking.order` separately places that
+whole Present among the composition's other appearances.
+
+The function is the drawing part of a package. Connect it to a Producer with matching typed inputs,
+then publish the Track through the Fragment and Surface as described in
+[Track authoring](track-authoring.md#connect-the-implementation-at-its-real-boundaries). Surface outputs
+map the Fragment's export name to a public Source name such as `answers.track`.
+
+Use `programSpaceFrameCount` from `@hypit/program-space` for the full program's frame count and
+`assertVisualTrackIdentity(track, space)` to check a produced Track against that space. Direct seeking
+and range rendering evaluate the same declared keyframes at the requested frame.
+
+## Elements, fonts and other assets
+
+`box` provides a container or painted shape. `text`, `text-flow` and `path-text` carry text and exact
+font resources. `image` and `video` reference their media artifacts. A `mask` names owned mask and
+content children in the same Present. The installed vocabulary queries expose their value shapes:
+
+```bash
+hypit vocabulary --visual visual-track
+hypit vocabulary --visual text
+```
+
+Visual styles use the supported CSS-shaped property vocabulary. Motion currently interpolates
+`opacity`, `transform`, `filter` and `clip-path` through frame-indexed keyframes. Media sampling
+separately describes which source frame to show at each part of a Present; it is needed for timed
+video playback, trims, loops and holds. Existing Media Track is useful when that is the whole role.
+
+Carry asset and font references through declared inputs. Source assets can be resolved at the
+Surface's asset boundary; generated media remains a graph reference until its Producer runs.
+The drawing function receives those values. For a visual preparation that reads bytes or invokes an
+external tool, use its preparation capability and pass the resulting material into drawing.
+
+## Compose externally prepared pixels
+
+A `surface` element accepts a CompositableSurfaceRef: prepared pixels with explicit extent, color,
+alpha and, for animation, frame information. This is useful when the component uses a raster or
+animated asset produced by another tool. Its preparation determines the pixels; the Track determines
+placement, sampling and lifetime.
+
+For an effect that transforms an image, pass that image as an explicit input to the effect's
+preparation. For a local mask, own the mask and content in the same element tree. These relationships
+make the required materials available both in Studio and in a render of any selected interval.
diff --git a/skills/hypit/references/production/examples/look.svs b/skills/hypit/references/production/examples/look.svs
new file mode 100644
index 00000000..56483baf
--- /dev/null
+++ b/skills/hypit/references/production/examples/look.svs
@@ -0,0 +1,6 @@
+<?svml using="@hypit/svs@1"?>
+<sheet version="1">
+ media.performance { fit: cover; }
+ text.title { size: 54; weight: 700; stack-order: 20; }
+ film.main { background: #18212A; }
+</sheet>
diff --git a/skills/hypit/references/production/examples/preview.svrun b/skills/hypit/references/production/examples/preview.svrun
new file mode 100644
index 00000000..36762a6e
--- /dev/null
+++ b/skills/hypit/references/production/examples/preview.svrun
@@ -0,0 +1,22 @@
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+ <author source="./production.svml"/>
+ <import as="stand-in" from="@hypit/stand-in@1"/>
+ <import as="estimate" from="@hypit/semantic-take-estimate@1"/>
+ <target output="main.composition"/>
+
+ <fragment id="card" using="stand-in:video">
+ <input name="canvas" from="canvas"/>
+ <input name="duration" value="5"/>
+ <input name="clock" from="clock"/>
+ </fragment>
+ <satisfy output="performance.video" candidate="card.video"/>
+
+ <fragment id="timing" using="estimate:semantic-take">
+ <input name="narrative" from="story"/>
+ <input name="segment" from="story.segment.opening"/>
+ <input name="media" from="performance-media.media"/>
+ <input name="policy" from="estimated.policy"/>
+ </fragment>
+ <satisfy output="opening-semantic.take" candidate="timing.take"/>
+</svrun>
diff --git a/skills/hypit/references/production/examples/production.svml b/skills/hypit/references/production/examples/production.svml
new file mode 100644
index 00000000..be443439
--- /dev/null
+++ b/skills/hypit/references/production/examples/production.svml
@@ -0,0 +1,63 @@
+<?svml using="@hypit/markup@1"?>
+<svml>
+ <import from="@hypit/script@1"/>
+ <import as="text" from="@hypit/text@1"/>
+ <import as="seedance" from="@hypit/seedance@1"/>
+ <import as="pipeline" from="@hypit/media-pipeline@1"/>
+ <import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="estimate" from="@hypit/semantic-take-estimate@1"/>
+ <import as="speech" from="@hypit/speech-track@1"/>
+ <import as="space" from="@hypit/spatial@1"/>
+ <import as="program" from="@hypit/program-space@1"/>
+ <import as="fonts" from="@hypit/fonts-open@1"/>
+ <import as="typo" from="@hypit/typography-track@1"/>
+ <import as="film" from="@hypit/film@1"/>
+ <import as="render" from="@hypit/render-hyperframes@1"/>
+ <import as="look" source="./look.svs"/>
+
+ <script id="story">
+ <opening><HOST>Here is @proof the useful part @/proof.</opening>
+ </script>
+ <space:Canvas id="canvas" width="720" height="1280"/>
+ <program:Clock id="clock" frame-rate="30"/>
+ <space:Frame id="full" within={canvas}
+ left="0%" top="0%" right="100%" bottom="100%"/>
+ <space:Frame id="title-frame" within={canvas}
+ left="8%" top="12%" right="92%" bottom="30%"/>
+
+ <text:Value id="direction">
+ A close, naturally lit phone-video view of a presenter in a workshop.
+ The presenter looks into the camera and says: Here is the useful part.
+ </text:Value>
+ <seedance:TextVideo id="performance" model="mini" prompt={direction}
+ duration="5" aspect-ratio="9:16" generate-audio="true"/>
+ <pipeline:Normalize id="performance-media" source={performance.video} clock={clock}
+ video="primary-moving" audio="default" span-authority="video"/>
+ <whisperx:SemanticTake id="opening-semantic" narrative={story}
+ segment={story.segment.opening} media={performance-media.media} language="en"/>
+ <estimate:SemanticTake id="estimated" narrative={story}
+ segment={story.segment.opening} media={performance-media.media}
+ language="en" pace="normal" min="4" max="15" rounding="round"/>
+ <speech:Track id="speech" visual-frame={full}
+ visual-appearance={look.media.performance} visual-z="0">
+ <speech:Take source={opening-semantic.take}/>
+ </speech:Track>
+
+ <fonts:Stack id="title-font" family="inter" weight="700" style="normal" emoji="color"/>
+ <typo:Style id="title-style" recipe={look.text.title} font={title-font}>
+ <typo:Fill color="#F1E7D8"/>
+ <typo:Stroke color="#18212A" width="2" placement="outside"/>
+ </typo:Style>
+ <typo:Track id="titles" semantic={speech.semantic}>
+ <typo:Area id="proof-label" placement={title-frame} style={title-style}
+ during={story.selection.proof}>The useful part</typo:Area>
+ </typo:Track>
+ <film:Film id="main" canvas={canvas} semantic={speech.semantic} appearance={look.film.main}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audio}/>
+ <film:Track source={titles.track}/>
+ </film:Film>
+ <render:Video id="final" composition={main.composition} semantic={speech.semantic}/>
+ <render:Video id="detail" composition={main.composition} semantic={speech.semantic}
+ start-frame="30" end-frame-exclusive="90"/>
+</svml>
diff --git a/skills/hypit/references/production/examples/production.svrun b/skills/hypit/references/production/examples/production.svrun
new file mode 100644
index 00000000..e2ebc6ca
--- /dev/null
+++ b/skills/hypit/references/production/examples/production.svrun
@@ -0,0 +1,5 @@
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+ <author source="./production.svml"/>
+ <target output="final.video"/>
+</svrun>
diff --git a/skills/hypit/references/production/examples/visuals.ts b/skills/hypit/references/production/examples/visuals.ts
new file mode 100644
index 00000000..12471c4e
--- /dev/null
+++ b/skills/hypit/references/production/examples/visuals.ts
@@ -0,0 +1,62 @@
+import { sealVisualTrack } from "@hypit/composition";
+import type { FrameSpan } from "@hypit/composition";
+import type { FontArtifactRef } from "@hypit/media";
+import type { ProgramSpace } from "@hypit/program-space";
+import { VISUAL_IR_V1 } from "@hypit/visual-ir";
+
+// The caller supplies its projected Window, resolved Frame and selected font faces.
+export function renderCard(input: {
+ id: string;
+ space: ProgramSpace;
+ span: FrameSpan;
+ frame: { x: number; y: number; width: number; height: number };
+ text: string;
+ fonts: readonly FontArtifactRef[];
+ color: string;
+ textColor: string;
+ size: number;
+ padding: number;
+ layer: number;
+ entranceFrames: number;
+}) {
+ const root = `${input.id}-box`;
+ const length = input.span.endFrameExclusive - input.span.startFrame;
+ const entranceEnd = Math.min(input.entranceFrames, length - 1);
+ return sealVisualTrack({
+ id: input.id,
+ programSpaceId: input.space.id,
+ visualIr: VISUAL_IR_V1,
+ presents: [{
+ id: `${input.id}-present`,
+ subjectId: input.id,
+ span: input.span,
+ stacking: { order: input.layer, tieBreak: input.id },
+ elements: [{
+ kind: "box", id: root, order: 0,
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "left", value: input.frame.x },
+ { name: "top", value: input.frame.y },
+ { name: "width", value: input.frame.width },
+ { name: "height", value: input.frame.height },
+ { name: "background-color", value: input.color },
+ ],
+ ...(entranceEnd > 0 ? { animation: { keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }] },
+ { atFrame: entranceEnd, style: [{ name: "opacity", value: 1 }] },
+ ] } } : {}),
+ }, {
+ kind: "text", id: `${input.id}-text`, parent: root, order: 1,
+ text: input.text, fonts: input.fonts,
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "left", value: input.padding },
+ { name: "top", value: input.padding },
+ { name: "width", value: input.frame.width - 2 * input.padding },
+ { name: "color", value: input.textColor },
+ { name: "font-size", value: input.size },
+ ],
+ }],
+ }],
+ });
+}
diff --git a/skills/hypit/references/production/examples/wordless-take.ts b/skills/hypit/references/production/examples/wordless-take.ts
new file mode 100644
index 00000000..d6f977c6
--- /dev/null
+++ b/skills/hypit/references/production/examples/wordless-take.ts
@@ -0,0 +1,23 @@
+import type { SynchronizedMedia } from "@hypit/media";
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+import { materializeSemanticTake } from "@hypit/speech";
+
+// Expose this adapter through a project Producer/Surface with a take output.
+export function wordlessTake(
+ narrative: Narrative,
+ excerpt: NarrativeExcerpt,
+ media: SynchronizedMedia,
+) {
+ if (excerpt.kind !== "segment" || excerpt.tokenStart !== excerpt.tokenEndExclusive) {
+ throw new Error("wordlessTake requires one Script Segment with no spoken Tokens.");
+ }
+ const segment = narrative.segments.find((item) => item.id === excerpt.id);
+ if (segment === undefined) throw new Error(`Script Segment ${excerpt.id} is missing.`);
+ return materializeSemanticTake(narrative, excerpt, media, {
+ tokens: [],
+ anchors: [
+ { identity: segment.startAnchorId, frame: 0 },
+ { identity: segment.endAnchorId, frame: media.timeline.frameCount },
+ ],
+ });
+}
diff --git a/skills/hypit/references/production/fonts-and-text.md b/skills/hypit/references/production/fonts-and-text.md
new file mode 100644
index 00000000..4597b15a
--- /dev/null
+++ b/skills/hypit/references/production/fonts-and-text.md
@@ -0,0 +1,93 @@
+# Fonts and independent text
+
+Read this when choosing exact fonts, handling multiple writing systems or Emoji, or placing titles
+and labels. [Caption](../playbooks/craft/captions.md) covers text displayed with speech.
+
+The font's glyph shapes and spacing determine how text wraps and how much room it needs. A font
+resource supplies those glyphs, a Style supplies their size and treatment, and a text item supplies
+the wording, placement and lifetime. Changing one of these can preserve the others.
+
+## Select a face or a fallback stack
+
+```svml
+<import as="fonts" from="@hypit/fonts-open@1"/>
+
+<fonts:Face id="headline-font" family="archivo-black" weight="400" style="normal"/>
+<fonts:Stack id="body-font" family="inter" weight="700" style="normal" emoji="color">
+ <fonts:Fallback family="noto-sans-sc" weight="700" style="normal"/>
+</fonts:Stack>
+```
+
+The Face is one exact font resource. Stack preserves an ordered set: here Inter, Noto Sans SC,
+then a color Emoji face. Choose fallback faces for the actual writing systems in the video.
+Weight and style must exist in the chosen family. `hypit vocabulary @hypit/fonts-open` and that
+package's README describe the installed catalog and supported combinations.
+
+Font bytes are explicit production resources, so rendering uses the selected faces regardless of
+the machine's installed fonts. A supplied brand font can be declared with its exact face metadata:
+
+```svml
+<import as="asset" from="@hypit/media@1"/>
+<asset:Font id="brand-font" src="./assets/brand-semibold.woff2" weight="600" style="normal"/>
+```
+
+Pass `{brand-font}` to the receiving Style. The file and metadata describe the actual supplied face.
+
+`emoji="color"` adds a color face; `emoji="mono"` chooses monochrome. Some symbols have both text
+and Emoji presentation. Write the intended Unicode sequence, such as `☎️`, when its color form is
+wanted.
+
+## Give independent text its own placement and lifetime
+
+Typography is useful for titles, labels, verdicts and copy that follows its own display rhythm.
+Script Caption remains appropriate when the displayed wording follows the performance.
+
+The following excerpt assumes the named Fonts, layout Frames, SemanticTrack and Recipes exist:
+
+```svml
+<import as="copy" from="@hypit/text@1"/>
+<import as="typo" from="@hypit/typography-track@1"/>
+
+<typo:Style id="headline-style" recipe={look.text.title} font={headline-font}>
+ <typo:Fill color="#F1E7D8"/>
+</typo:Style>
+<copy:Value id="headline">A useful idea, clearly shown.</copy:Value>
+<typo:Track id="titles" semantic={speech.semantic}>
+ <typo:Area id="opening-title" content={headline} placement={title-frame}
+ style={headline-style} during={story.selection.proof}/>
+</typo:Track>
+```
+
+Include `titles.track` in Film. The Style supplies typography, Paint and layer order; the item
+supplies content, placement and time. Use `during="program"` for a title that lasts throughout the
+program, or the component's declared Window forms for a shorter appearance.
+
+For the example above, `look.text.title` can be the Recipe
+`text.title { size: 54; weight: 400; stack-order: 20; }`, matching the selected headline face.
+
+| Placement | Input and use |
+| --- | --- |
+| Point | A SpatialPoint anchoring text whose box follows its content |
+| Area | A SpatialFrame for wrapping and fitting text in a bounded region |
+| Path | A SpatialPath for text following an authored curve |
+
+Query `hypit vocabulary @hypit/typography-track --tag Style` for the Recipe properties and
+`--tag Track` for placement, content and motion forms. [Spatial layout](spatial.md) explains the
+geometry these inputs carry.
+
+## Rich text and motion
+
+An item can take graph Text through `content={...}`, or own an inline document with `typo:P`,
+`typo:Span` and `typo:Break`. For example, inside an Area:
+
+```svml
+<typo:P>Made for <typo:Span style={accent-style}>this moment</typo:Span>.</typo:P>
+```
+
+A paragraph or Span Style replaces that run's complete typography and Paint, including its font
+and size. The outer item continues to supply placement and layer order.
+
+Typography Motion can act on the item or stagger words and graphemes. Use the installed Motion
+vocabulary for its frame offsets and normalized sequence positions. For a new speech-text layout
+or scheduling relationship, [Caption authoring](caption-authoring.md) explains creating a family
+that consumes the existing Caption document and semantic timing.
diff --git a/skills/hypit/references/production/media.md b/skills/hypit/references/production/media.md
new file mode 100644
index 00000000..8e8d88aa
--- /dev/null
+++ b/skills/hypit/references/production/media.md
@@ -0,0 +1,137 @@
+# Preparing media for a production
+
+Read this when admitting files, connecting generated media, choosing streams, or editing a clip
+before using it in a Track or a model reference. [Tracks](tracks.md) covers placement and playback.
+
+Media carries the visible performance and sound. Preparing it for a video answers two further
+questions: how it occupies the program's time, and which Script passage it realizes. Normalization
+establishes the frame clock and selected picture/audio streams. A SemanticTake adds the association
+with Script and the locations of its words and boundaries.
+
+## Files and generated Outputs
+
+File declarations publish a **BlobArtifact**, a reference to the file's bytes, under their own id:
+
+```svml
+<import as="asset" from="@hypit/media@1"/>
+
+<asset:Image id="product" src="./assets/product.png"/>
+<asset:Video id="performance" src="./assets/performance.mp4"/>
+<asset:Audio id="music" src="./assets/music.wav"/>
+```
+
+Use `{product}`, `{performance}` and `{music}` as inputs that accept these BlobArtifacts. A model
+Surface can publish the same kind of value under an output path, such as `{portrait.image}` or
+`{opening.video}`. The package vocabulary gives that path. File paths are relative to their Source;
+[project setup](../creation/project-files.md#establish-the-project-boundary) explains the declared project boundaries.
+
+An image reference can enter a model directly. A still placed by Media Track needs its actual
+IntrinsicExtent as well. Inspect its dimensions with `hypit media probe <file>` and declare them
+with `space:Extent`; [spatial layout](spatial.md) explains extent versus destination Frame.
+
+## Prepare moving media on the program clock
+
+Clips can arrive with different frame rates, several streams or picture and sound of different
+lengths. Normalize selects the intended streams and expresses them on the program's frame clock,
+so their lengths and later playback can be combined precisely.
+
+The following excerpt prepares a performance and an independent soundtrack:
+
+```svml
+<import as="program" from="@hypit/program-space@1"/>
+<import as="pipeline" from="@hypit/media-pipeline@1"/>
+
+<program:Clock id="clock" frame-rate="30"/>
+<pipeline:Normalize id="performance-media" source={performance} clock={clock}
+ video="primary-moving" audio="default" span-authority="video"/>
+<pipeline:Normalize id="music-media" source={music} clock={clock}
+ video="none" audio="default" span-authority="audio"/>
+```
+
+The Clock is an authored rate; the prepared media supplies the resulting length. Share the Clock
+across Takes that will join one program.
+
+- `video` selects the moving-picture stream, or `none` for audio-only material.
+- `audio` selects the embedded audio, or `none` when the material should carry no sound.
+- `span-authority` chooses which stream determines the prepared duration when stream lengths differ.
+
+`primary-moving` excludes attached cover art. The default audio selection uses the default or
+unambiguous audio stream; select an explicit stream when the container has several intended choices.
+`hypit vocabulary @hypit/media-pipeline --tag Normalize` gives the supported selectors.
+
+Normalization inspects the bytes and produces `{performance-media.media}`: a SynchronizedMedia value
+with an exact frame count, optional picture and optional audio on the shared timeline. Audio is
+prepared as a 48 kHz render stem with its level preserved. Balance, fades and music ducking remain
+mix decisions in [Audio Track and sound mix](../playbooks/craft/sound-mix.md).
+
+## Associate a performance with Script
+
+For an already declared Script and prepared spoken performance:
+
+```svml
+<import as="whisperx" from="@hypit/whisperx@1"/>
+
+<whisperx:SemanticTake id="opening-semantic" narrative={story}
+ segment={story.segment.opening} media={performance-media.media} language="en"/>
+```
+
+WhisperX measures the audio; alignment locates the authored words in that evidence. The result
+`opening-semantic.take` contains the same media and that Segment's local timing. Speech Track
+assembles Takes in their intended order and translates their local positions into program time.
+Use the performed language supported by the selected package and Endpoint.
+
+For a layout study before speech exists, estimated timing can preserve the same Script identities.
+[Runs and substitutes](runs.md) explains choosing it and the evidence it supplies.
+
+## Wordless passages use media boundaries
+
+An ordinary Script Segment such as `<empty></empty>` can carry a wordless passage. Its media gives
+it a duration, so the resulting SemanticTake has the Segment's start/end anchors and no timed words.
+It enters the same Speech Track assembly as a spoken Take.
+
+[wordless-take.ts](examples/wordless-take.ts) shows the adapter: it calls `materializeSemanticTake`
+from `@hypit/speech` with the authored Segment, normalized media, a start at frame zero and an end at
+the media's frame count. A project Surface can expose it with `narrative`, `segment` and `media`
+inputs and one `take` output. [Track authoring](track-authoring.md) explains that package wiring.
+
+The speech estimator allocates spoken Tokens across a span; this wordless adapter uses the actual
+media boundaries directly. Action, music or visual rhythm can determine the chosen passage length.
+
+## Give a still a duration when that is its role
+
+A still B-roll Item already occupies an authored Window. To make one or several images into a
+time-bearing clip, use StillVideo:
+
+```svml
+<import as="media" from="@hypit/media-pipeline@1"/>
+
+<media:StillVideo id="opening-still" source={product} duration="6" clock={clock}/>
+<pipeline:Normalize id="opening-media" source={opening-still.video}
+ video="primary-moving" audio="none" span-authority="video" clock={clock}/>
+```
+
+StillVideo produces a silent video BlobArtifact. Multiple `media:Still` children divide the authored
+duration by their optional weights. Normalization then makes that clip usable as prepared moving
+media. Choose this when the still should supply a Take's time or a video reference.
+
+## Edit bytes at an explicit point in the graph
+
+```svml
+<media:Transform id="edited" source={performance-media.media}>
+ <media:Trim tail="0.25s"/>
+ <media:Retime rate="1.05" pitch="preserve"/>
+</media:Transform>
+<media:ExtractAudio id="voice-reference" source={edited.video} audio="default"/>
+<media:ExtractFrame id="frame-reference" source={edited.video}
+ video="primary-moving" at="last"/>
+```
+
+Transform applies its operations in order. These Outputs are BlobArtifacts; normalize an edited
+clip again when feeding it into a prepared-media input, and align the edited performance when its
+timing changed. Extracted audio or a frame can directly feed a compatible model reference port.
+`ExtractFrame` also accepts `first`, `frame:<index>` and `time:<seconds>`.
+
+Use graph operations for repeatable preparation belonging to the production. `hypit media` commands
+are useful for inspection and deliberately exported evidence. Image geometry changes, compositing
+and cutouts have separate installed vocabulary in `@hypit/image-transform`, `@hypit/image-compose`
+and `@hypit/background-removal`; select the operation that matches the asset's intended use.
diff --git a/skills/hypit/references/production/rendering.md b/skills/hypit/references/production/rendering.md
new file mode 100644
index 00000000..8d519b54
--- /dev/null
+++ b/skills/hypit/references/production/rendering.md
@@ -0,0 +1,70 @@
+# Composition and rendering
+
+Read this when assembling the deliverable or rendering a frame interval for review. [Tracks](tracks.md)
+explains the contributing layers; [Runs](runs.md) explains selecting existing media for this execution.
+
+Composition chooses which pictures and sounds form the video and how they share space and time.
+Rendering evaluates that composition over a frame interval and produces the encoded media. The
+same composition can therefore be inspected in Studio, rendered in part, or rendered as a whole.
+
+## Assemble the picture and sound
+
+With the named inputs already declared:
+
+```svml
+<import as="film" from="@hypit/film@1"/>
+<import as="render" from="@hypit/render-hyperframes@1"/>
+
+<film:Film id="main" canvas={canvas} semantic={speech.semantic}
+ appearance={look.film.main}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audio}/>
+ <film:Track source={coverage.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={music.track}/>
+</film:Film>
+<render:Video id="final" composition={main.composition} semantic={speech.semantic}/>
+```
+
+An example Film Recipe is `film.main { background: #18212A; }`. Canvas supplies the picture dimensions;
+the SemanticTrack supplies program time. Include each wanted audio output explicitly. A covering
+picture leaves the included performance audio audible. Layer order is authored in the Tracks'
+Presents, so moving these Film children does not reorder the picture.
+
+`main.composition` is the assembled work, usable in Studio. `final.video` asks for an encoded video.
+A compatible Composition from another component can also feed the render Surface.
+
+## Choose a render interval in frames
+
+```svml
+<render:Video id="detail" composition={main.composition} semantic={speech.semantic}
+ start-frame="240" end-frame-exclusive="360"/>
+```
+
+Both bounds refer to the original program's frame clock. The interval includes frame 240 and ends
+before 360: 120 frames, or seconds 8–12 at 30 fps. Omit both bounds for the whole program. For a
+rational frame rate, compute seconds from its numerator and denominator rather than rounding the
+rate first.
+
+The original animation time remains intact, and picture and sound use the same interval. A short
+Run can target `detail.video` while the normal Run continues to target `final.video`.
+
+**The range limits final rendering. Upstream generation still follows the selected graph.** Keep
+the Run Candidates for usable media and SemanticTakes when inspecting a Caption or MG revision.
+Inspect `hypit plan` for the work that remains before submission. [Authoring](authoring.md#reuse-produced-work-explicitly)
+explains choosing the reuse boundary.
+
+## Execution and capacity
+
+HyperFrames compiles the selected composition and renders its picture. Timeline audio is rendered
+from the included AudioTracks, then picture and sound are muxed into the delivered file. A Runtime
+can bind these capabilities to different compatible Endpoints.
+
+For the local HyperFrames Provider, `workers` selects parallel frame workers and `browserCapacity`
+limits shared browser usage. These belong to the Runtime configuration; the Source keeps the same
+render declaration. [Runtime profiles](../environment/profile.md) explains worker choices, shared
+capacity and inspecting the selected Provider's configuration. Confirm that the chosen Endpoint
+supports range requests; the local HyperFrames implementation does.
+
+Use [Builds and Results](builds.md) to submit, follow and retrieve `final.video` or `detail.video`.
+Use [Review](review.md) to judge the observed interval or complete deliverable against the intended work.
diff --git a/skills/hypit/references/production/review.md b/skills/hypit/references/production/review.md
index cd05cebd..b24be87c 100644
--- a/skills/hypit/references/production/review.md
+++ b/skills/hypit/references/production/review.md
@@ -3,6 +3,9 @@
Read this when opening Studio, judging an encoded Result, comparing a reconstruction with its
reference, or deciding where a visible problem should be repaired.
+[Studio](studio.md) explains launch, session reuse, displayed information, Source writeback and
+project Companions. [Builds and Results](builds.md) explains retrieval and explicit Output reuse.
+
## Review the work the Run actually selects
Open Studio with the ordinary Run intended for the work. That Run binds the Author Source, Targets,
@@ -11,12 +14,12 @@ A separate review Run is useful when its Candidate selection is intentionally di
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
+generation. When that closure 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.
+continuity, or the interaction between the selected production media and graphics.
## Separate legality from judgment
@@ -25,7 +28,7 @@ configured composition displays. A completed Build can establish what the select
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
+Look at the complete Film at its intended delivery size 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.
@@ -45,14 +48,16 @@ Use whichever view can answer the current question:
- 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.
+ [Rendering](rendering.md#choose-a-render-interval-in-frames) gives the frame-bound syntax and the
+ relationship to upstream Candidate reuse.
- 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.
+ pixels, adjacent frames, or a short passage.
- 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.
+Choose and combine these views according to the current question. 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:
diff --git a/skills/hypit/references/production/runs.md b/skills/hypit/references/production/runs.md
new file mode 100644
index 00000000..635bc682
--- /dev/null
+++ b/skills/hypit/references/production/runs.md
@@ -0,0 +1,141 @@
+# Runs, Candidates and substitutes
+
+Read this when choosing deliverables, reusing an Output, replacing media, or preparing a layout
+study before a performance exists. [Authoring](authoring.md#reuse-produced-work-explicitly) explains
+which produced value still fits an edit; [Builds](builds.md) explains finding and executing it.
+
+A Run says what this execution should complete and which existing or alternative values it should
+use. A **Target** names a deliverable Output. A **Candidate** supplies an Output needed along the
+way. The selected dependencies determine the work that remains.
+
+For example, changing a title can keep the performance and its timing while producing a new final
+video. The Source describes the changed title; the Run keeps the produced Take.
+
+## Select the Output that the current work needs
+
+```svrun
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+ <author source="./production.svml"/>
+ <target output="final.video"/>
+ <build-record id="kept-take" build="bld_..." output="opening-semantic.take"/>
+ <satisfy output="opening-semantic.take" candidate="kept-take"/>
+</svrun>
+```
+
+Replace `bld_...` with the actual Build id found through Results. The historical `output` is the
+name in that Result; the `satisfy output` is the current Author Output. Keeping this SemanticTake
+preserves both media and timing when its Script identities still fit. A changed Caption or MG can
+then recompute downstream.
+
+Each Run has one Author entry. Its Targets name public computed Outputs, such as `main.composition`
+for composition work, `final.video` for delivery, or an intermediate the work needs independently.
+The selected graph includes the dependencies needed to complete those Outputs.
+
+## Choose what the replacement supplies
+
+A file can replace a byte-producing Output:
+
+```svrun
+<file id="supplied-performance" type="@hypit/artifact@1#BlobArtifact"
+ from="./assets/performance.mp4" media-type="video/mp4"/>
+<satisfy output="performance.video" candidate="supplied-performance"/>
+```
+
+Here the file replaces the generated video bytes. Normalization and alignment still follow it.
+Selecting a completed SemanticTake instead preserves its media, Script association and timing
+together. Choose the Output whose meaning matches what should stay; the receiving Type identifies
+which kind of value fits that position.
+
+## Use a Fragment when the substitute needs computation
+
+A Run Fragment connects the computations that produce a Candidate. A generic video card, for
+example, needs the chosen Canvas, clock and duration:
+
+```svrun
+<import as="stand-in" from="@hypit/stand-in@1"/>
+<fragment id="card" using="stand-in:video">
+ <input name="canvas" from="canvas"/>
+ <input name="duration" value="5"/>
+ <input name="clock" from="clock"/>
+</fragment>
+<satisfy output="performance.video" candidate="card.video"/>
+```
+
+Place imports after `author` and before execution declarations. `using` names a Fragment from an
+installed package. `from` on an input names a public value of the Run's Author entry, including a
+computed Output. The latter retains its own dependencies and any Candidate selection. It does not
+name another Run Candidate or automatically expose an imported Source's private bindings.
+
+The resulting Candidate is named `card.video`. Selecting it replaces the performance request while
+retaining the preparation and composition that consume that video. A substitute can also consume
+an existing computed Output; that Output remains part of the selected dependencies.
+
+## A complete layout preview
+
+The small [production Source](examples/production.svml), [Recipe](examples/look.svs),
+[production Run](examples/production.svrun) and [preview Run](examples/preview.svrun) demonstrate
+the same Film with two execution choices. Copy the files together into a video project to study or
+adapt them. Their simple performance request illustrates system wiring; the actual video's casting,
+references and direction come from its Treatment and the relevant Playbook.
+
+The Source declares measured timing and an estimated alternative. The estimated Surface publishes
+its authored `estimated.policy` as a typed value. The preview Run uses the estimate package's Run
+Fragment to supply the Candidate for the original measured Take:
+
+```svrun
+<fragment id="timing" using="estimate:semantic-take">
+ <input name="narrative" from="story"/>
+ <input name="segment" from="story.segment.opening"/>
+ <input name="media" from="performance-media.media"/>
+ <input name="policy" from="estimated.policy"/>
+</fragment>
+<satisfy output="opening-semantic.take" candidate="timing.take"/>
+```
+
+Together with the card selection, this leaves card creation, inspection and normalization as the
+media work. The original generated performance and WhisperX alignment are outside this preview's
+selected graph. The estimator retains the real Segment, Token and Anchor identities and distributes
+their positions across the prepared media's frame count. Those positions show provisional rhythm;
+real alignment supplies the performance's actual word timing.
+
+From the directory containing the copied example:
+
+```bash
+hypit check preview.svrun
+hypit plan preview.svrun
+hypit-studio --run preview.svrun
+```
+
+Studio can materialize this preview with a selected local media Provider that supports the required
+transient capabilities. If the chosen environment does not provide them for Studio, build the
+selected preview media through that environment and reuse its completed Outputs. The normal
+production Run still requests generation and measured alignment, under the work's spending authority.
+
+For an existing production with usable footage, select its Result or file directly. A generic card
+is useful for spacing and timing questions; the actual shot is needed to judge overlap with a face,
+color relationships, performance or identity. [Studio](studio.md) explains what the preview can show.
+
+## Preserve the choices that still apply
+
+Retain unrelated `satisfy` declarations when adding a new choice. Removing one restores the Author
+computation for that Output. A new Build does not infer reuse from matching names or unchanged prompts.
+Read the plan to see whether the changed selection leaves the intended generation, preparation and
+rendering work. [Rendering](rendering.md) explains why a short render interval still needs explicit
+upstream reuse.
+
+## Other value and export forms
+
+`<value id="settings" type="@owner/module@1#Settings" from="./settings.json"/>` admits a typed
+serialized value as a Candidate. The file contains a StoredValue wrapper, for example
+`{"kind":"inline","value":{"enabled":true}}`. The inner value must match the declared Type.
+Use `build-record` for structured Outputs already held in Results, where their associated media
+resources can be resolved with them.
+
+Fragment input `value` supplies a scalar: number, boolean, null or text. Structured inputs use
+`from` to reference typed Author values. Exports are addressed as `instance.export`; optional
+`<export name="video"/>` children choose which exports the instance exposes. Selecting an export
+includes the computations that it requires.
+
+The package's Run Fragment documentation gives its inputs and exports. Surface vocabulary queries
+describe Markup tags; a Fragment-only package can therefore have no entries in that query.
diff --git a/skills/hypit/references/production/source-syntax.md b/skills/hypit/references/production/source-syntax.md
new file mode 100644
index 00000000..44b1ad4f
--- /dev/null
+++ b/skills/hypit/references/production/source-syntax.md
@@ -0,0 +1,144 @@
+# Reading and writing Source syntax
+
+Read this for the language around a production: imports, references, literal values, Recipes and
+Run choices. [Script and time](../creation/script-and-time.md) owns prose, Roles, Dual Text, Cue
+breaks, Selections and Moments. [Tracks](tracks.md) explains how those meanings drive picture and sound.
+[System relationships](system.md) explains authored values and computed Outputs.
+
+## Three documents, three decisions
+
+A `.svml` normally describes the work, a `.svs` holds reusable authored values, and a `.svrun`
+chooses what to execute and reuse. Each document's Header selects its parser; the filename extension
+is the convention used to recognize its role.
+
+This small Author Source produces Text and Script values; it makes no media request:
+
+```svml
+<?svml using="@hypit/markup@1"?>
+<svml>
+ <import from="@hypit/script@1"/>
+ <import as="copy" from="@hypit/text@1"/>
+ <import as="kit" source="./direction.svs"/>
+
+ <script id="story">
+ <opening><HOST>Here is @proof the useful part @/proof.</opening>
+ </script>
+ <copy:Value id="direction">She leans in slightly, amused by her own observation.</copy:Value>
+ <copy:Render id="prompt" template={kit.performance}>
+ <copy:Set name="dialogue" text={story.segment.opening.dialogue}/>
+ <copy:Set name="direction" text={direction}/>
+ </copy:Render>
+</svml>
+```
+
+Package imports expose vocabulary under a local alias. Source imports expose a document's public
+values: `<import as="look" source="./look.svs"/>`. A data package can expose the same kind of Source,
+for example `<import as="ugc" source="@hypit/gpt-image-kits/phone-ugc-v1"/>`; its own relative imports
+and assets stay inside that package. Put imports in the leading prologue, before body declarations.
+Use a package's logical Module ABI, such as `@hypit/text@1`, in `from`; installed package versions
+belong to ordinary package management. Reading a packaged Source does not activate its JavaScript.
+
+A Source alias qualifies public bindings; it does not rename a Narrative's authored identity.
+Two imported Sources declaring different Scripts both named `story` therefore conflict. Share the
+one Script that owns the work, or give genuinely separate Narratives distinct ids.
+
+## Braces connect values
+
+`duration="5"` is literal attribute text interpreted by the receiving Surface.
+`prompt={direction}` is a whole-value graph reference, checked against the declared input Type.
+`prompt="direction"` is a string, not that reference. Braces contain whole-value graph references.
+Use `copy:Render` with a TextTemplate and explicit bindings to assemble text; use the receiving
+package's expression syntax where it declares one, such as temporal offsets.
+
+Output paths are package vocabulary, not inferred from the element's tag:
+
+- `copy:Value id="direction"` publishes `{direction}`;
+- an imported `media:Image id="logo"` publishes `{logo}`;
+- `gpt:Image id="portrait"` publishes `{portrait.image}`;
+- `pipeline:Normalize id="prepared"` publishes `{prepared.media}`;
+- `speech:Track id="speech"` publishes `{speech.semantic}`, `{speech.visual}` and `{speech.audio}`.
+
+Inspect `hypit vocabulary` for the actual Surface's exports and use the published path it reports.
+Public bindings can be authored Records or realizable Logical Outputs. Script,
+Recipes and literal Text already exist as authored data; they are not Run Targets. The computed
+`prompt` from `copy:Render` is a Logical Output that can be targeted or satisfied by a Candidate.
+Name declarations before the structured Surfaces that resolve their inputs; the current Markup
+handlers inspect imported values and earlier declarations during decoding. Graph edges, rather than
+XML body order, schedule execution.
+
+Different bodies have different readers. Script uses its own prose grammar; structured components
+declare their permitted attributes and children; Text has its own literal/template forms. JSX,
+HTML, CSS and callback syntax have no meaning unless the receiving package explicitly declares that
+language. Consult `@hypit/markup`, `@hypit/script` and the receiving package when punctuation or
+escaping is significant.
+
+## Recipes are named values
+
+```svs
+<?svml using="@hypit/svs@1"?>
+<sheet version="1">
+ media.cover {
+ fit: cover;
+ stack-order: 10;
+ }
+</sheet>
+```
+
+Imported as `look`, this rule is `{look.media.cover}`. Recipe rule names use dotted paths, such as
+`media.cover`. Rules do not inherit or cascade. Scalars, strict JSON arrays and strict JSON objects are
+supported; each consumer owns the allowed properties, defaults and units. A Caption Style's Recipe
+is not interchangeable with Media appearance merely because both have a color or size.
+
+Some packages, such as TextTemplate, explicitly define parameter precedence. That local behavior
+does not create global SVS inheritance. A Prompt Kit remains a reusable text program; image
+references, voice references, model parameters and generated Outputs stay explicit in Author Source.
+
+The `direction.svs` used above selects Text's own Recipe Frontend to produce a TextTemplate rather
+than ordinary Recipes. This is the same file-extension convention with a different explicit Header:
+
+```svs
+<?svml using="@hypit/text/svs@1"?>
+<sheet version="1" id="performance">
+ text-template.performance { separator: paragraph; }
+ text-template.performance.block.dialogue {
+ kind: slot;
+ order: 10;
+ slot: dialogue;
+ }
+ text-template.performance.block.direction {
+ kind: slot;
+ order: 20;
+ slot: direction;
+ }
+</sheet>
+```
+
+This small Kit just joins two Text inputs. It does not generate a video. Fixed blocks and variable
+axes can be added when they express reusable direction; `@hypit/text` owns that template grammar.
+
+## Runs demand Outputs and choose Candidates
+
+For the Text example saved as `main.svml`, beside `direction.svs`:
+
+```svml
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+ <author source="./main.svml"/>
+ <target output="prompt"/>
+</svrun>
+```
+
+A video Run usually targets the renderer's public video Output. Several Targets are valid when
+several deliverables are wanted. Targets are public Output names; requests outside the demanded graph
+are not executed.
+
+To reuse a prior Output, declare a `build-record` Candidate and select it with `satisfy`; the prior
+Result name and the current Logical Output name can differ. A raw MP4 file is a Blob Artifact, not
+an aligned SemanticTake. Select Candidates by their real nominal Type and creative meaning, retaining
+normalization or alignment where still needed. [Runs](runs.md) explains complete Candidate forms,
+Fragment inputs and exports; [Authoring](authoring.md) owns the creative reuse decisions;
+`@hypit/run-markup` owns the complete Run grammar.
+
+`hypit check <run>` checks Source and graph legality. `hypit plan <run> --runtime <profile>` exposes
+the selected graph and external requests without submitting them. A legal document can still describe a
+poor image, a misplaced Caption or an unhelpful cut; those remain directing questions.
diff --git a/skills/hypit/references/production/spatial.md b/skills/hypit/references/production/spatial.md
new file mode 100644
index 00000000..68804f4e
--- /dev/null
+++ b/skills/hypit/references/production/spatial.md
@@ -0,0 +1,66 @@
+# Spatial layout
+
+Read this when positioning or fitting media, text or a project component. Timing is explained in
+[Script and time](../creation/script-and-time.md); it is independent of these coordinates.
+
+## Canvas, extent and destination
+
+The Canvas gives the final image's pixel dimensions. An IntrinsicExtent gives a source image's
+dimensions. A Frame gives the destination rectangle a consumer should occupy. A landscape image
+can therefore retain its real extent while appearing in a portrait composition.
+
+```svml
+<import as="space" from="@hypit/spatial@1"/>
+
+<space:Canvas id="canvas" width="1080" height="1920"/>
+<space:Extent id="photo-size" width="1600" height="1200"/>
+<space:Frame id="full" within={canvas}
+ left="0%" top="0%" right="100%" bottom="100%"/>
+<space:Frame id="content" within={full}
+ left="6%" top="8%" right="94%" bottom="90%"/>
+```
+
+Coordinates start at the top left; x increases rightward and y downward. Frame edges are positions
+from the parent's left/top, so `right="94%"` is the right edge at 94% of parent width. It leaves a
+6% margin. A percentage on the x axis uses the parent width; on y it uses parent height. Nesting
+changes that reference rectangle. Pixel lengths use `px`.
+
+## Anchor an object or preserve its aspect
+
+```svml
+<space:AnchoredFrame id="label" within={content}
+ x="50%" y="85%" width="80%" height="12%" anchor="center"/>
+<space:AspectFrame id="photo-frame" within={content}
+ x="100%" y="0%" width="45%" aspect={photo-size} anchor="top-right"/>
+```
+
+AnchoredFrame pins the named point of a sized rectangle to x/y in the parent. AspectFrame derives
+one dimension from the other: specify width or height, plus an Extent or a ratio such as `4/3`.
+An `offset-x` or `offset-y` is an additional pixel nudge. An anchored frame can extend beyond its
+parent when that is the intended composition.
+
+For text, `space:Point` supplies a pixel position and `space:Path` supplies authored Move/Line/curve
+commands. [Fonts and text](fonts-and-text.md) shows which Typography placement consumes each.
+
+## Fit the source into the Frame
+
+Media Track and Speech Track consume fit choices through their appearance Recipes:
+
+- **contain** keeps the complete image visible and may leave space around it;
+- **cover** fills the destination and may crop the image;
+- **stretch** changes the source proportions to occupy the destination.
+
+Choose fitting with the subject and its surrounding composition in view. A Frame only places the
+rectangle; it does not identify the face or choose an editorial crop. Query the selected component's
+appearance vocabulary for its crop and alignment controls.
+
+## Carry measured regions through the same geometry
+
+RegionTimeline contains already measured boxes indexed by program frame. Its recipe uses normalized
+`[x, y, width, height]` boxes and `null` for absent measurements, converted against the chosen Canvas.
+Take-local measurements need their actual program offsets. Reframed or cropped footage needs the
+corresponding spatial transform before its boxes can position text correctly.
+
+[Caption tracking](../playbooks/craft/caption-tracking.md) explains producing and applying head
+regions. In a new component's visual element tree, child positions are relative to their parent;
+[component visuals](component-visuals.md) shows that final layout boundary.
diff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.md
new file mode 100644
index 00000000..246b8157
--- /dev/null
+++ b/skills/hypit/references/production/studio.md
@@ -0,0 +1,107 @@
+# Working in Studio and adding a Companion
+
+Read this when opening a Run, using its timeline and Inspector, or giving a project component a
+useful Studio presentation. [Review](review.md) owns the judgment made from the visible work;
+[Track authoring](track-authoring.md) owns the component's production behavior.
+
+## Open the actual Run
+
+From the video project, use the installed Distribution's command:
+
+```bash
+hypit-studio --run build.svrun
+```
+
+Supply `--runtime <profile>` when intentionally using a different Profile from the project's
+`hypit runtime use` selection. Studio needs a Run whose selected targets reach one Film and a
+resolvable semantic projection. An image-generation-only Run is not a Film view; several distinct
+Films need separate Runs or sessions.
+
+Open the URL actually printed by the process and retain it with the Run it serves. The default
+requested port is 5179; `--port` selects another, and an occupied port can cause Vite to choose a
+different one. A guessed localhost link does not establish a running session. Reuse an existing
+session when it serves the intended project and Run rather than starting another for each edit.
+
+Studio watches the Run and its loaded Author/Recipe Sources and recompiles them after changes.
+Changing package code, adding a package import, changing Companion activation, or selecting another
+Runtime or Result repository requires restarting that Studio session: those implementations and
+selections are loaded at startup. A browser refresh alone does not reload the server-side modules.
+Stop only the relevant Studio process; stopping Studio does not cancel a submitted Build.
+
+## Read the different views
+
+| View | What it shows and what it can change |
+| --- | --- |
+| Source | The exact Run, Author and imported Source/Recipe files. Select a file and use Edit source; changes save automatically, and Cmd/Ctrl+S saves immediately. Check save/error state. This is not a project filesystem browser. |
+| Preview | The selected Film composition rendered by HyperFrames in the browser. Play or seek to inspect the actual selected media and graphics. |
+| Timeline | Semantic Segments, Selections and Moments, plus the component-projected Track entities and their visible intervals, materials or event lanes. A rectangle may describe occupancy, activation or persistent visibility; read the component's meaning. |
+| Inspector | With nothing selected, project, Canvas, time and Run facts. For a selected entity, only its declared adjustable fields, organized under Where, How and When where applicable. |
+| Tasks | Finished project Results and, with a selected Runtime, read-only active Build/Operation information. This is a view of execution, not a replacement Build submission mechanism. |
+| Artifacts | Public media files from project Results, including files inside Composite Outputs. Previewing one does not select it as a Candidate in the Run. |
+
+Use [Builds and Results](builds.md) to inspect Output names, export media, finish an incomplete Result,
+edit Result presentation metadata or select an earlier Output. Studio reads the same project Result
+repository. With no Runtime selected, finished Results remain accessible; preview works when its
+display closure needs no unresolved Endpoint work. Active Runtime status and transient Endpoint
+processing require the selected environment.
+
+Studio creates no Build and submits no paid generation. It can execute deterministic Producers and
+only those exact immediate capabilities a Provider explicitly permits for transient authoring.
+If new image/video generation blocks the display closure, select an existing Output or file; use
+an explicit stand-in Candidate when the current question only concerns structure, layout or time.
+A stand-in does not establish performance, identity or the composition of future generated media.
+
+[Runs and substitutes](runs.md#a-complete-layout-preview) includes a complete Source and Run with
+a card Candidate, normalization and estimated semantic timing for this kind of layout study.
+
+## Edit the owning Source fact
+
+Inspector fields and timeline handles write back to actual Source endpoints. A field can live in a
+referenced Frame, Style or SVS Recipe rather than on the selected Track tag. Editing a shared Recipe
+changes every consumer that uses it; create and select a separate authored instance when the design
+needs independent variation. Lists and records have a local draft with Apply and Reset; Apply writes
+the complete validated value. Check save status and the resulting preview.
+
+Dragging a Selection boundary or Moment changes that identity in Script. Every Track consuming it
+then follows the changed semantic relation. A clock-based handle instead changes its declared time
+parameter. Use the displayed handles and their actual authority; a visible item is not automatically
+independently draggable. A derived or fixed value without a supported inverse may be read-only.
+Do not replace a semantic relation with guessed seconds just to make a rectangle move.
+
+Source edits outside Studio are observed too. If a stale UI edit conflicts with a newer file, read
+the current Source and retry the intended change against it instead of overwriting the newer work.
+All successful edits return to the ordinary Sources; they do not create a second Studio project.
+
+## Give a project component a useful Companion
+
+The component's Producers own its rendered video. A **Studio Companion** explains that component to
+the editor: which output it understands, what its timeline entities mean, which materials to show,
+which authored parameters to expose and how an edit relates back to Source.
+
+Generic VisualTrack and AudioTrack presentation already exists. Add a Companion when it makes the
+new role legible or editable: for example, a score board's outer lifetime and per-score activations,
+or a Caption family's Cue text and actual per-Cue Style. A static vocabulary preview helps recognize
+a component; it does not supply these live entities or edit bindings.
+
+Keep Companion code separate from domain computation and contribute its Host facet from the
+Source-selected project package's activation. The Distribution supplies official Companions; a
+project package can supply its own without editing Studio or adding a Studio Profile. Installing an
+otherwise unselected package does not activate a plugin. The installed `@hypit/studio-adapter`
+README gives the exact ABI, a minimal Companion and the activation wiring.
+
+Expose meaningful deterministic schedule/program outputs when the Companion needs more than the
+terminal Track. Ask for exact same-Surface output ports through `requiredValues`, or follow one
+exact typed authored reference. Preserve child identities and consume the real Window/Instant graph
+edges so Studio can trace temporal authority. Never infer a Moment from matching frame numbers,
+an id prefix or a parsed attribute name.
+
+Declare Source bindings separately from visible Inspector fields. Offer the parameters useful to
+this production, including explicit reference paths into Recipes. The Companion selects finite
+presentation and controls; Studio owns DOM, CSS, validation and Source writes. A Companion does not
+need its own filesystem mutation, Provider calls or rendering loop.
+
+For implementation patterns, read the installed `@hypit/ranking-studio` for persistent state and
+activation lanes, `@hypit/caption-fine-studio` for Cue/Style relationships, or
+`@hypit/media-track-studio` for media occupancy. Verify the new component in an ordinary Run:
+select the intended entity, adjust one exposed value, inspect the exact Source change and seek to
+the affected frames. For shared semantic timing, also inspect the other consumers of that marker.
diff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.md
new file mode 100644
index 00000000..c4bcc48a
--- /dev/null
+++ b/skills/hypit/references/production/system.md
@@ -0,0 +1,80 @@
+# How a Hypit production fits together
+
+Read this for the relationships that connect authoring, media, composition and execution.
+
+SVML expresses what belongs together in a video: which media carries a passage, which picture
+supports an idea, and which words or events a Caption, graphic or sound follows. Those relationships
+let the production survive revision. When a performance becomes longer, a graphic attached to the
+same phrase can still appear with that phrase.
+
+## Script gives meaning; media gives it time
+
+Script names the work's Segments, words, Selections and Moments. A Segment identifies a passage;
+a Selection identifies a range within the Script; a Moment identifies a point. The author can refer
+to them before a performance has been generated.
+
+Once the media exists, normalization gives it a shared frame clock. A **SemanticTake** associates
+that media with one Script Segment and records its word and boundary positions in local frames.
+Speech Track assembles the Takes, translating their positions into a **SemanticTrack** for the
+complete program. Its **ProgramSpace** supplies the program's time axis.
+
+This is how “show the proof while she explains the result” becomes a precise interval in the
+produced video. A wordless Segment works through the same relationship: its media supplies the
+span, with start and end boundaries and no spoken words to locate.
+
+[Script and semantic time](../creation/script-and-time.md) explains the authoring forms.
+[Media preparation](media.md) explains normalization and constructing Takes.
+
+## Components turn those relationships into picture and sound
+
+A component gives an authored relationship its behavior. A ranking board can consume a phrase's
+Selection to animate an entry; a reveal, flash and sound can share one Moment. Each interprets the
+event according to its role. The board may keep the revealed answer visible after the entrance ends.
+
+Placement and appearance have their own inputs: a Frame says where the board belongs, a Style says
+how it looks, and supplied text or images say what it contains. This lets one behavior serve several
+productions while each production chooses its content and art direction.
+
+Components publish visual and audio Tracks. Film assembles the wanted Tracks into a **Composition**,
+and rendering turns that composition into the delivered video. Including performance audio lets
+it continue under B-roll; a silent covering picture changes only the visible layer.
+
+[Tracks](tracks.md) explains the available roles. [Spatial layout](spatial.md) and
+[fonts and text](fonts-and-text.md) explain their shared inputs. A new role can be implemented as a
+[project component](track-authoring.md) and included through the same composition model.
+
+## Source describes the work; Run selects this execution
+
+The Author Source connects the Script, media requests, components and deliverables. Recipes hold
+reusable authored choices such as Styles or prompt configurations. The connections form a dependency
+graph: completing the final video requires the values used to make it.
+
+A **Run** selects which public Outputs to complete through **Targets**, and can choose a different
+**Candidate** for an Output. That Candidate might be a supplied file, a prior Result, or a computation
+provided by a Run Fragment.
+
+For a Caption revision, keep the existing SemanticTake and target the final video. The selected Take
+already supplies the performance and its timing; the changed Caption and downstream rendering remain
+work to do. This separates revising the video from repeating media generation. The Run records that
+reuse explicitly.
+
+A submitted execution is a **Build**. Its **Result** retains completed public Outputs for inspection,
+delivery and future selection, including useful Outputs completed before a later failure.
+
+[Source syntax](source-syntax.md) explains declarations and references. [Runs](runs.md) explains
+selection and substitutes. [Builds and Results](builds.md) explains submission and retrieval.
+
+## Runtime supplies the execution facilities
+
+Some computations arrange values; others require media tools or external services. The latter
+produce a **Need** describing that work. A model package defines a request's meaning, and a Provider
+implements the corresponding capability through an Endpoint. The Runtime Profile selects the
+facilities, credentials and capacity used to execute it.
+
+For example, the Source declares the composition and requested render interval; the local
+HyperFrames Provider's configuration chooses its worker count. A production can keep its authored
+relationships while using the execution setup selected for it.
+
+[Runtime profiles](../environment/profile.md) explains those choices. [Rendering](rendering.md)
+explains whole and partial video outputs. [Studio](studio.md) provides interactive inspection and
+editing of the same authored work with its selected media.
diff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.md
new file mode 100644
index 00000000..b1dc0b76
--- /dev/null
+++ b/skills/hypit/references/production/track-authoring.md
@@ -0,0 +1,161 @@
+# Writing a project Track
+
+Read this when a production needs new graphic structure, state or rendering behavior. Begin from
+what the viewer should perceive and what should follow a changed performance.
+[Composing Tracks](tracks.md) covers existing Track roles; [vocabulary](vocabulary.md) covers discovery
+and project package ownership. [Caption authoring](caption-authoring.md) covers the speech-text case.
+
+## Start with the author-visible behavior
+
+Write a small intended Source use before implementing it. A new score strip might have one Style,
+an outer Window, preset scores and score-changing Moments. Decide whether its items appear briefly,
+remain after activation, replace a previous state, or rearrange the layout. Those differences define
+the component more usefully than a long list of decorative parameters.
+
+This existing answer-strip vocabulary illustrates a concrete choice:
+
+```svml
+<emoji:Track id="answers" semantic={speech.semantic} canvas={canvas}
+ style={answer-style} placeholder={question-icon} during="program">
+ <emoji:Item id="known" icon={known-icon} preset="true"/>
+ <emoji:Item id="surprise" icon={answer-icon} at={story.moment.reveal}/>
+</emoji:Track>
+```
+
+Its outer Window owns visibility; source order owns slots; preset answers exist at the beginning;
+each Moment changes only its slot and the answer persists. A chart or scoreboard can instead own
+repeated updates or simultaneous events.
+
+## Keep selection, projection and consumption distinct
+
+Script names meaning: a Selection, Segment or Moment. The semantic timeline supplies where that
+meaning occurred in the produced media. Temporal projection resolves it into an Instant or Window
+in the program's frame space. The consuming component then decides what to do there.
+
+```text
+Script Selection / Segment / Moment + SemanticTrack
+ ↓ temporal projection
+ ProgramSpace + Window / Instant
+ ↓ component consumption
+ media occupancy, graphic state, sound or effect
+```
+
+This separation lets one Moment drive an answer reveal, a short sound and a flash. Each consumer
+receives its own appropriate projection, but all refer to the same authored event. Changed speech
+moves the event without asking each component to search for a word or inspect the Script parser.
+
+For a Window consumer, `during={story.selection.example}` can take both semantic boundaries.
+`at={story.moment.answer} for="8f"` starts a short effect at a Moment. An Instant consumer may accept
+`at={story.moment.answer}` with no duration because it owns a state transition. Read the actual
+Surface: identical-looking `at` attributes do not imply identical consumption. The owning
+`@hypit/temporal-markup` README describes shared author forms; `@hypit/temporal` describes their values.
+
+## Separate lifetime, activation and persistent state
+
+For a board that stays on screen, author its outer Window independently of individual reveals.
+Then decide what its children mean:
+
+- an Item window may mean “draw only during this interval,” as with ordinary Media;
+- an activation window may stage an item's entrance and movement, after which it remains in a board;
+- a Moment may replace a question mark with an answer that persists until the outer Window ends;
+- a preset item may already occupy the initial state and need no reveal trigger.
+
+Document that meaning in the component. `preset` is the answer strip's package-owned initial-state
+concept. An answer strip may sensibly accept only Moments for child reveals; expose the timing forms
+that match the component's behavior.
+
+The interview's project emoji strip illustrates this design: one outer Window, ordered answer
+items, a placeholder asset and one icon per answer. Each Moment changes its own slot. The Track does
+not decide when the spoken answer occurred; it consumes the already projected event.
+
+## Make spatial decisions equally explicit
+
+CanvasSpace identifies the coordinate system. SpatialFrame, anchors, extents and fitting describe
+where content goes and how its intrinsic shape occupies that place. RegionTimeline supplies authored
+per-frame regions in a chosen Canvas. These are distinct from ProgramSpace, which owns the clock.
+
+Keep image dimensions, placement and crop transformations visible so a measured head or a reserved
+MG area maps into the actual composition. Do not hardcode a global 9:16 canvas, fixed speaker side,
+renderer viewport or detector into a reusable Track. A project's chosen dimensions and positions
+are ordinary Source and Recipe decisions.
+
+## Write the smallest component that expresses the role
+
+Declare the new package in the project's `packages/` and ordinary package configuration. Read the
+installed `hypit/author-kit` README for the public package boundary and inspect a close installed sibling for
+the relevant implementation, rather than depending on a monorepo example directory being present.
+`@hypit/interview-emoji-reveal` demonstrates persistent Moment-driven state; `@hypit/ranking`
+demonstrates reveal Windows and settled rows; `@hypit/media-track` demonstrates occupancy and Handoffs.
+
+The Surface exposes author intent and lowers its supported temporal forms through shared projection
+helpers such as `createTemporalWindowProjection` and `createTemporalInstantProjection`. The Fragment
+wires those projections, explicit ProgramSpace/Canvas and authored values into the component's
+Producers. The Producer consumes the resulting time and geometry and owns the visual/state behavior;
+Studio consumes that published meaning for presentation and editing.
+
+Keep actual text, icons, images, colors and event references in Source or Recipe. The package owns
+its reusable persistent-state behavior, motion and visual structure. A new Caption family consumes
+the common Caption document and timing.
+
+## Connect the implementation at its real boundaries
+
+The useful pieces of a project package are:
+
+| Piece | Responsibility |
+| --- | --- |
+| Manifest | Module identity, nominal Types, Producer input/output ports and dependencies |
+| Surface | Validate authored attributes and children, resolve typed references, emit inert Records, Components and Fragments |
+| Fragment | Wire the finite computation graph and publish outputs |
+| Producer | Compute the immutable state or render program from declared inputs |
+| Activation | Register the Manifest, deterministic handlers and Markup facets with their matching Host ABI |
+| Vocabulary and preview | Explain the role and show a recognizable, configured example |
+| Optional Studio Companion | Project meaningful editor entities, real parameter bindings and temporal lineage without changing video rendering |
+
+For a semantic Window, call `createTemporalWindowProjection` in the Surface with the resolved
+SemanticTrack and authored element. For an event, use `createTemporalInstantProjection`. Preserve
+all returned `records`, `components` and `fragments`, and wire its returned `ref` into the domain
+Fragment. Merely reading `ref` and dropping those drafts leaves no producer for that value.
+
+Validate the temporal forms the component actually accepts. The answer strip, for example, checks
+that `at` references a Moment before using the shared helper; it intentionally does not accept a
+Selection boundary. Keep a child `subjectId` meaningful to the component while qualifying graph ids
+by the owning Track so two instances cannot collide. The exact helper options live in
+`@hypit/temporal-markup`.
+
+Project ProgramSpace from the SemanticTrack once within the Fragment. Domain Producers then receive
+that space and traced Windows/Instants, alongside Canvas/Frame, Style and explicit content inputs.
+If the component consumes repeated children, a finite create/append/finalize graph is one established
+pattern: each operation retains declared ports, and every child's media remains a real graph edge.
+
+For persistent state, reason about a requested frame directly. For example: outside the outer Window,
+draw nothing; inside it, each slot shows its preset/activated answer or its placeholder. Apply an
+entrance motion relative to that slot's activation frame. Do not increment a mutable browser counter
+or rely on having rendered every preceding frame. Studio scrubbing and partial or concurrent rendering
+must yield the same state from the same inputs.
+
+Emit the public VisualTrack representation through `@hypit/composition` and `@hypit/visual-ir`.
+[Component visuals](component-visuals.md) explains Presents, element trees, local animation,
+prepared surfaces and a complete drawing function. [Spatial layout](spatial.md) explains incoming
+Frames, and [Fonts and text](fonts-and-text.md) explains font resources.
+Pass asset references and exact font data through declared inputs. A visual Producer does not open
+files, call GVI, run ffmpeg or choose a Provider. If an external preparation operation is needed,
+represent it separately through its capability; its result becomes another input.
+
+A component-owned sound can be a peer AudioTrack output; alternatively the Source can place a sound
+on the same Moment. Neither choice requires a Track to inspect another Track's private state.
+Document which Outputs are public, including useful deterministic program values for inspection.
+
+## Verify the behavior the component introduced
+
+When the new role needs its own timeline presentation or Inspector, read
+[Studio and Companions](studio.md#give-a-project-component-a-useful-companion). Expose the domain
+schedule and temporal identities at their actual boundaries so the editor consumes them directly
+instead of reconstructing them from pixels.
+
+Give the component a concise README, public vocabulary, a meaningful visual example and a preview
+showing the state change. Verify the actual intended transition: an answer appears on its Moment,
+previous answers persist, future ones remain hidden, and the whole strip respects its outer Window.
+A designed still alone cannot establish that behavior. For stateful MG, a few meaningful frame
+checks around activation and exit are more useful than snapshots of every implementation detail.
+Also check a second instance, a differently sized Frame and direct seeking into the middle when
+those exercise the new behavior.
diff --git a/skills/hypit/references/production/tracks.md b/skills/hypit/references/production/tracks.md
new file mode 100644
index 00000000..15a1e719
--- /dev/null
+++ b/skills/hypit/references/production/tracks.md
@@ -0,0 +1,128 @@
+# Composing Tracks
+
+Read this when putting performance, coverage, graphics, text and sound together. For a new component's
+implementation, read [Track authoring](track-authoring.md); for a new Caption family, read
+[Caption authoring](caption-authoring.md).
+
+[Media preparation](media.md) explains incoming files, normalized media and SemanticTakes;
+[spatial layout](spatial.md) explains placement, and [rendering](rendering.md) explains the deliverable.
+
+## Choose by the layer's job
+
+| Role | Owns | Common published values |
+| --- | --- | --- |
+| SemanticTrack | The ordered media timeline and aligned semantic locations; it draws nothing | Usually `speech.semantic` |
+| Speech Track | An ordered performance's picture and sound | `.semantic`, `.visual`, `.audio` |
+| Media Track | Framed images, prepared moving media, or authored surfaces; B-roll is one use | `.program`, `.visual`, optional `.audio` |
+| Audio Track | Independently timed music, ambience and effects | `.program`, `.track` |
+| Caption | Script-derived display text presented with speech | Fine publishes `.schedule`, `.track` |
+| Typography / Text | Titles, labels and other independently authored text | `.program`, `.track` |
+| Semantic MG | A board, comparison, reveal or another system responding to meaning | Package-owned; often `.program` and a visual Track |
+| Effect | A treatment such as a flash over an authored interval | Package-owned visual output |
+
+These are authoring roles. Film receives ordinary peer VisualTrack and AudioTrack values; it has no
+special rule for a podcast, ranking or B-roll. A component can publish both picture and sound.
+
+## Semantic Takes supply the media timeline
+
+Declare a Clock for normalization, normalize generated or supplied media with explicit stream
+choices, and associate each Segment with its SemanticTake, locating spoken words when present. Speech Track assembles
+those Takes in source order; global frame positions follow their actual normalized lengths.
+
+```svml
+<speech:Track id="speech" visual-frame={layout.full}
+ visual-appearance={look.performance} visual-z="0">
+ <speech:Take source={opening-take}/>
+ <speech:Take source={answer-take}/>
+</speech:Track>
+```
+
+This is an assembly excerpt: the imports, layout, fit Recipe and SemanticTakes must already exist.
+One Take may contain several speakers or generated cuts. Estimates help request a duration; they do
+not supply word timestamps. Covering or reframing its picture leaves the same performance and audio.
+Speech Track's appearance is a fit Recipe; use Media Track for a separate animated presentation.
+
+Semantic structure also supports a wordless passage. A named empty Script Segment receives its
+actual boundaries from prepared media and remains addressable through the assembled SemanticTrack.
+[Media preparation](media.md#wordless-passages-use-media-boundaries) owns that construction.
+
+## Coverage has a Window and a separate playback choice
+
+```svml
+<media-track:Track id="coverage" semantic={speech.semantic} canvas={canvas}>
+ <media-track:Item image={portrait.image} extent={portrait-extent}
+ frame={layout.full} during={story.selection.example} appearance={look.still}/>
+ <media-track:Item media={prepared-broll.media}
+ frame={layout.full} during={story.selection.proof} appearance={look.clip}/>
+</media-track:Track>
+```
+
+An image needs its intrinsic Extent. Moving media enters through explicit normalization as `media`;
+`surface` accepts an already compositable surface from another component. Frame says where it goes;
+fit/crop says how the source occupies it.
+
+With `once-start`, a short Window truncates the clip; a long Window returns to the layer below after
+the clip finishes. A still occupies its Window without a video playback mode. `hold-start` freezes a
+tail; `stretch` retimes. Choose deliberately; `@hypit/media-track` owns the precise sampling rules.
+
+Independent Items can overlap. A Sequence instead owns one succession of Members and their pairwise
+Handoffs. Use it when a replacement relationship or transition belongs to the same visual slot.
+Touching Script Selections require matching affinity when an inter-word pause should remain covered;
+also check source exhaustion and transition opacity. [B-roll](../playbooks/craft/b-roll.md) explains
+the editorial choices and [frame coverage](../playbooks/craft/frame-coverage.md) explains boundary failures.
+
+Media source audio is opt-in. Include the Track's audio output in Film when wanted, and avoid routing
+the same speech twice. A silent covering image does not mute the performance below it.
+
+## Sound, text and Caption answer different events
+
+An Audio Clip takes normalized audio-bearing media. `gain` is a linear multiplier; fades and trim
+are explicit. Normalizing input media does not automatically balance or duck the complete mix.
+
+```svml
+<audio:Track id="effects" semantic={speech.semantic}>
+ <audio:Clip source={reveal-sound.media} at={story.moment.reveal} for="600ms"
+ playback="once" gain="0.45" fade-in="0f" fade-out="3f"/>
+</audio:Track>
+```
+
+Use one Moment for an MG reveal, a sound and a flash when they express one event. A Window consumer
+needs a duration; an MG state transition may only need the Instant. Explicit clock placement remains
+valid for events independent of speech even in a speaking video.
+
+Typography uses exact fonts, its own Style and Point/Area/Path placement. Graph Text and rich inline
+content are alternatives. A rich Span Style replaces that run's typography rather than cascading
+CSS properties. A headline held over several sentences is generally Typography. Caption instead
+reads `story.caption`, applies a Caption Program and joins to `speech.semantic`; Role overrides,
+Selection overrides and authored `||` breaks retain Script as the wording owner.
+
+[Fonts and text](fonts-and-text.md) covers exact faces, fallbacks, Emoji and Typography placement.
+
+## Persistent MG is more than another timed image
+
+A ranking board can remain visible throughout the program while one Selection controls a row's
+entrance and settled state. An answer strip can start with a preset answer and reveal later slots
+on Moments. Ending an activation does not necessarily remove the result. Read that component's
+consumption rules, including preset state, event order and outer lifetime.
+
+Keep the event in Script, the authored layout and palette in Source/Recipe, and the reusable state
+behavior in the component. The same Moment can be used by several components without one reaching
+inside another. Their outputs remain ordinary peers.
+
+## Assemble the intended peers
+
+Film's domain assembly receives a Canvas, a ProgramSpace and a Film Recipe. The current `film:Film`
+Surface takes `canvas`, `semantic` and `appearance`, deriving the space from the SemanticTrack.
+Include each desired visual and audio
+output explicitly. Listing a Track later does not move it to the front: absolute stacking is authored
+inside the Track's Presents. Use intentional, distinguishable layer orders where things overlap.
+
+Canvas geometry and Program time are separate. Keep an inset's intrinsic extent, destination Frame,
+crop and any measured regions in the same explicit coordinate relationship. Changing final crop or
+framing can invalidate head-tracking placement even when timestamps remain unchanged.
+
+Read the selected package's vocabulary for exact ports rather than treating every Track as one
+universal interface. Inspect the dense frame, the state-changing beat, source endings and the
+complete mix when reviewing the configured work.
+
+[Composition and rendering](rendering.md) shows Film, the final video Surface and frame-range requests.
diff --git a/skills/hypit/references/production/vocabulary.md b/skills/hypit/references/production/vocabulary.md
index c723aa40..fdecc850 100644
--- a/skills/hypit/references/production/vocabulary.md
+++ b/skills/hypit/references/production/vocabulary.md
@@ -14,7 +14,7 @@ Name what the element must do in the work before choosing its implementation. Us
- 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:
+Query the likely package owners:
```bash
hypit vocabulary @hypit/caption-fine
@@ -23,20 +23,23 @@ 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.
+and designed previews. The package README supplies exact syntax and behavior. When the question
+requires more detail, inspect the relevant implementation and public API. An existing component can
+also provide a useful implementation example for a new project package.
-## Judge fit by behavior, not resemblance
+Run Fragment libraries have a separate interface. A package such as `@hypit/stand-in` can provide
+useful Candidates while declaring no Markup Surfaces. Read [Runs](runs.md) and the library's
+package-local Fragment documentation for those inputs and exports.
+
+## Choose a component for its behavior
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.
+A catalogue preview helps identify the component's visual role. Its declared inputs and behavior
+show what can be adapted; its configured appearance in Studio shows how it serves this production.
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.
@@ -45,33 +48,46 @@ and elements. Those two places contain the useful reason and the exact choice.
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.
+video. Do not patch Hypit Core, the CLI, or an installed Distribution package to implement one video's
+component. Author the behavior in the video's project package and select it through normal imports.
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;
+- the package owns reusable mechanics, rendering behavior, input shapes, defaults and the 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.
+- Provider packages implement media tools and external services.
+
+Read the installed `hypit/author-kit` README for the public package boundary and a relevant component
+for an implementation example. Give the new package its own Module identity and use the project
+owner's scope; the selected Distribution owns the reserved `@hypit/*` namespace.
+
+Describe the Surface's role, attributes and outputs with a small valid example so a future author
+can select it. A visual preview makes its appearance recognizable; Studio shows the actual
+configuration used in a production.
-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.
+For existing Track composition, read [Tracks](tracks.md). For a new Track, read
+[Track authoring](track-authoring.md) when deciding temporal inputs, spatial ownership, persistent
+state, preset content or peer visual/audio outputs. [Caption authoring](caption-authoring.md) covers
+a new speech-text family without rebuilding its transcript or timing.
-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.
+[Studio and Companions](studio.md) covers timeline presentation and Inspector editing for the new
+component.
+
+[Component visuals](component-visuals.md) explains the actual Track and element representation,
+with a drawing example. [System relationships](system.md) places it in the complete production.
## 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.
+by Source or Run imports and their declared dependencies. Project packages resolve from the project;
+reserved `@hypit/*` packages come from the selected Distribution. 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.
+
+[Sharing an Author Package](component-sharing.md) owns the packaging, identity and upgrade details.
diff --git a/skills/hypit/references/seedance-kits.md b/skills/hypit/references/seedance-kits.md
deleted file mode 100644
index edd035d3..00000000
--- a/skills/hypit/references/seedance-kits.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Seedance Prompt Kits
-
-Hypit ships seven English Text Templates in the installed Distribution under
-`packages/seedance-kits/kits/`. Use `hypit paths --json` to locate that Distribution. Each Kit owns the
-repeatable prompt contract; the project Recipe selects its stable directing axes, and explicit Text
-slots carry shot-specific dialogue or action.
-
-| Format | Kit | Required dynamic slots | Ordered references |
-|---|---|---|---|
-| Talking head | `speaker-v1.svs` | `dialogue`; optional `action` | image 1 = speaker/scene, audio 1 = voice |
-| Silent B-roll | `broll-v1.svs` | `story` | one or more authored images |
-| Two-person podcast | `podcast-v1.svs` | `dialogue`; optional `action` | images 1/2 = A/B views, audio 1/2 = A/B voices |
-| Video call | `call-v1.svs` | `dialogue`; optional `action` | images 1/2 = reversed call layouts, audio 1/2 = A/B voices |
-| Street interview | `street-interview-v1.svs` | `dialogue`; optional `action` | images 1/2/3 = interviewer/guest/shared views, audio 1/2 = interviewer/guest |
-| Motion transfer | `motion-reference-v1.svs` | optional `direction` | image 1 = subject, video 1 = motion reference |
-| Camera transfer | `camera-reference-v1.svs` | optional `direction` | image 1 = subject, video 1 = camera reference |
-
-## Required procedure
-
-1. Read the installed `packages/seedance-kits/README.md` and selected Kit file for exact axes and defaults.
-2. Copy only that `.svs` file into the video project's `./kits/` directory; import the vendored copy.
-3. Put stable axis choices in `recipes.svs` as a named Recipe.
-4. Import `@hypit/text@1` as `copy`. Use `copy:Render` with the Kit Template and Recipe, then
- connect dynamic slots with `copy:Set`.
-5. Feed the rendered Text to the appropriate low-level Seedance Surface. Keep duration, resolution,
- model, and every image/audio/video reference explicit in the Author Source.
-
-Select these Recipe axes instead of rewriting their prompt blocks:
-
-| Kit | Stable Recipe axes |
-|---|---|
-| `speaker-v1` | `composition-stability`, `camera-motion`, `edit-rhythm`, `performance`, `gesture` |
-| `broll-v1` | `material-mode`, `story-shape`, `edit-language`, `camera-language`, `motion-intensity` |
-| `podcast-v1` / `call-v1` | `framing`, `edit-language`, `pacing`, `performance`, `reaction`, `gesture` |
-| `street-interview-v1` | `framing`, `pacing`, `performance`, `reaction`, `gesture` |
-
-Use a freeform English prompt only when none of the seven Kit contracts matches. Keep dialogue in
-its authored language when it must be spoken verbatim.
diff --git a/skills/hypit/scripts/check-credentials.mjs b/skills/hypit/scripts/check-credentials.mjs
deleted file mode 100755
index b7309ec5..00000000
--- a/skills/hypit/scripts/check-credentials.mjs
+++ /dev/null
@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-import process from "node:process";
-const names = process.argv.slice(2);
-if (names.length === 0) { console.error("Usage: node check-credentials.mjs NAME [...NAME]"); process.exitCode = 2; }
-for (const name of names) console.log(`${name}\t${process.env[name]?.trim() ? "set" : "missing"}`);
diff --git a/skills/hypit/scripts/check-environment.mjs b/skills/hypit/scripts/check-environment.mjs
deleted file mode 100755
index 3a5222c7..00000000
--- a/skills/hypit/scripts/check-environment.mjs
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-import { execFileSync } from "node:child_process";
-import process from "node:process";
-const commands = [
- ["node", ["--version"]],
- ["ffmpeg", ["-version"]],
- ["ffprobe", ["-version"]],
- ["uv", ["--version"]],
-];
-for (const [command, args] of commands) {
- try {
- const version = execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }).trim().split(/\r?\n/, 1)[0];
- console.log(`${command}\tok\t${version}`);
- } catch { console.log(`${command}\tmissing`); }
-}
-console.log(`platform\t${process.platform}\t${process.arch}`);