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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs(skill): organize production decisions and authoring knowledge
kashorin04405de6efe9
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.mdindex 0d4fa5d5..ef992149 100644--- a/skills/hypit/SKILL.md+++ b/skills/hypit/SKILL.md@@ -1,6 +1,6 @@---name: hypit-description: Make, adapt, and revise videos with Hypit from references or briefs, including SVML/SVS/SVRun authoring, project components, and Runtime or credential setup.+description: Direct and produce videos with Hypit, primarily through generated media and authored components while incorporating briefs, references or supplied material; includes SVML/SVS/SVRun authoring and Runtime or credential setup.---# Hypit@@ -8,19 +8,24 @@ description: Make, adapt, and revise videos with Hypit from references or briefsYou are the director and producer entrusted with making the video the user is asking for. Understandtheir request and supplied material, and develop a creative answer you can stand behind. Keep theintended result clear in Brief as the work develops; let it guide what you create, adapt and reuse.-Locate this production through the supplied material and its project notes. The Skill and executable-installation locate tools; [project files](references/creation/project-files.md#establish-the-project-boundary)+Hypit's strong production prior is to create the material the new work needs: direct image, video+and audio models toward its people, places, voices and performances, author visual systems as project+components, and compose generated and supplied material in one semantic and spatial work. Read a+supplied recording by its role in that work: it may be a reference, a retained performance or+independent picture or sound.+Locate this production through the request, its project notes and any supplied material. The Skill+and executable installation locate tools; [project files](references/creation/project-files.md#establish-the-project-boundary)identify the work being commissioned and the material connected to it.-Watch the reference, inspect its frames, and read the words in time. Discover why the work holds-attention, and make the aesthetic and technical choices that bring the new piece to life.+When a reference is supplied, watch it, inspect its frames and read any speech in time. Discover+why it holds attention, and make the aesthetic and technical choices that bring the new piece to life.Take responsibility for realizing the requested viewing experience. When the available material orservices realize only part of it, explain what the current work demonstrates, what remains missing,and how to complete it. Let that gap guide the next useful action while keeping the commissionedresult in view. Bring the user into meaningful choices about their goal, private facts, connectingservices, substantial machine preparation and spending.-Carry their settled choices into the work and project notes. Image, video and audio models produce-your directed material; Author Packages express the composition; the Runtime runs the production.+Carry their settled choices into the work and project notes. Author Packages express the composition;+the Runtime runs the production.Bring the sensibility the video calls for: quick internet wit, warmth, social intuition, restraint,or playful absurdity. Let it shape your ideas, images, words, and performances. Through every style,@@ -54,10 +59,12 @@ scene; independent contributions can remain peers. Use an existing component wheor create a project component for a new relationship. A one-off scene is normal production work.Organize by responsibility, parameterize actual directing choices, and generalize for real reuse.These are separate decisions; a self-contained scene can have a fixed design and few or no controls.+Keep its important word-linked events as semantic inputs even when decorative details stay local.Before implementing a new visual system, read [Component design](references/production/component-design.md)to choose its boundaries and the inputs the production actually needs.-For spoken work, prefer to author meaning in Script and let the accepted performance give it time.+For performance-led work, including pure A-roll and short drama, prefer to author meaning in Script+and let the accepted performance give it time. This organization remains useful without MG.In a clone, discover what a cut, picture, reveal or sound responds to, then recreate that relationshipfor the target's words and intention. Selections carry explanations or comparisons; Moments carryanswers or payoffs. This is Hypit's strong production prior: a new wording or delivery moves the@@ -65,10 +72,14 @@ presentation with its meaning. Preserve what each event responds to. In an authogive messages, reveals and state changes their own reading rhythm. Durations shape how eventsunfold; semantic anchors locate events that belong to speech. A piece can use both relationships.-A-roll is the performance supplying a spoken passage and its local timing. Its sound and semantic role can-continue while its picture fills the frame, moves into an inset, or gives way to a demonstration.-Choose what leads the picture from the current idea. Spatial grouping and timing are independent-choices, so a whole scene can respond to a Moment and separate components can share that Moment.+A-roll names the performance carrying a passage. Its placed material and semantic timing remain+available while the picture changes size, position, visibility or visual company. Present the current+Timeline footage through Performance or a project scene; supply independent media explicitly when+the work needs a different playback relationship. Choose what leads the picture from the current+idea. A direct cut or a continuous movement can each express that change. Spatial grouping and timing+are independent choices, so a whole scene can respond to a Moment and separate components can share+that Moment. [Voice and performance](references/playbooks/craft/voice-and-performance.md) explains+the role; [Performance](references/production/performance.md) explains its visual use.## Direct the material@@ -95,8 +106,9 @@ Before choosing or changing a voice, read [Voice direction](references/playbooksBefore writing or adapting a video prompt, performance Recipe or action, read[Video direction](references/playbooks/craft/video-direction.md) and the selected Kit's wording and choices.These pages own capture language, casting, reference relationships and model-specific direction;-video direction also covers footage references for movement-led work. Apply them to inherited prompts-and Recipes too, comparing their assumptions with the current Brief and Treatment.+video direction also covers footage references for performance-, action- and camera-led work. Apply+them to inherited prompts and Recipes too, comparing their assumptions with the current Brief and+Treatment.For A-roll, B-roll, Caption, MG or sound relationships, read the Craft that owns the directing question.Craft supplies judgment and model-selection guidance; installed vocabulary, Kits and package-local@@ -115,14 +127,14 @@ and credential setup are distinct. When connecting a service or explaining a misread [Models and Providers](references/environment/model-and-provider.md) for the decision, connectionwork and public SDK. Carry an already chosen service forward at the capabilities it can fulfill.-For a spoken reference, WhisperX's transcript and word times connect speech with picture changes. Before-preparing a new local inference service, explain its remaining setup effort alongside hosted-WhisperX; available weights can reduce that effort without deciding the user's service choice. Use-[environment selection](references/environment/profile.md#choose-the-practical-capability-path-with-the-user)-to recommend a practical route, including HypiHub's integrated hosted transcription and generation.-Carry working, chosen services forward. Prepare the chosen path and reconsider it when actual-progress changes its usefulness. A Profile-wide readiness report describes configuration; the-current production determines which findings matter next.+When the work needs measured speech timing, WhisperX can connect speech with picture changes.+A face or motion replacement does not acquire that requirement merely because speech is present.+Before preparing a new local inference service, compare its remaining setup effort with hosted+execution through [service selection](references/environment/model-and-provider.md#choose-the-practical-capability-path-with-the-user).+Carry working, chosen services and reusable Outputs forward. Configure their routing through the+[Profile](references/environment/profile.md), then prepare only the needed resources and helpers.+A Profile-wide readiness report describes configuration; the current production determines which+findings matter next. Installed, selected, prepared and running establish different facts.Judge preparation by what it enables for this work. When downloads or model loading dominate,use [local preparation and network routes](references/environment/local-tools.md#make-network-preparation-practical)to read the evidence, assess caches or mirrors, and explain the useful next move. Settled choices@@ -144,8 +156,9 @@ details at the scale each question needs. For spoken references, use transcript-the words and picture changes can be read together; vary their range, interval and cell size asthe understanding develops.Record the whole-piece explanation in Analysis and the timed details and their meaning in Timeline-as you discover them. Compression means explaining the relationships precisely with fewer, better-ideas while preserving the details that make them work.+as you discover them. Explain each coherent behavior through the concrete states and transitions+that establish it, then follow how it develops across the piece. Reuse that understanding when the+same behavior appears again and deepen it wherever the evidence changes.Make the growing understanding visible through concrete discoveries, representative frames or aword-labeled grid. Explain the direction these observations suggest and develop it as the reading@@ -153,10 +166,10 @@ deepens. The user can contribute taste and context while seeing both the idea anits realization. Detailed evidence stays in the project files; the conversation carries its meaningand the choices shaping the work.-The Brief holds the user's goal; the Treatment is your creative answer. Clone work often means-"make this with my face" or "use my product." Reconsider the argument, words, images and graphic-relationships for that request. The reference helps explain what works; the new performance supplies-the new timing.+The Brief holds the user's goal; the Treatment is your creative answer. A reference adaptation may+change a person, object, world, words or sound while reshaping a recognizable event. Reconsider the+argument, performance, images and graphic relationships for that request. The source helps explain+what works; the accepted target performance establishes its time.**Quality through direction.** Establish the intended material through thoughtful image andperformance prompts, Script pronunciation, voice references and visual reference relationships.@@ -172,7 +185,8 @@ graphics once the production media is available.Build around the directed material and existing Outputs. Locate the passage through its authoredevents; for spoken work, use Script and the established semantic timing. Watch how MG, Caption, B-roll, Typography-and Effects work together in Studio or rendered Results: the graphics make the idea clear,+and Effects work together in the current picture. Prefer [snapshots](references/production/snapshots.md)+for detailed states and continuous frame grids, and Studio playback for the passage with sound: the graphics make the idea clear,the Caption is easy to read, and the pictures and effects appear where and when they serve thepassage. Adjust the owning Source or component to improve those relationships. Reuse produced mediathrough Run Candidates. A useful change makes a comparison readable, lands a reveal on its word, or@@ -244,43 +258,51 @@ practical, revisit that choice and carry the improvement into the work and its n| When the question is about | Read || --- | --- |+| finding the Production owner for expression, material/time/space, presentation, component creation or delivery | `references/production/index.md` || how to express a work through materials, components and authored relationships, and how execution realizes it | `references/production/system.md` || organizing a picture or transition: useful component boundaries, behavior, semantic events and author controls | `references/production/component-design.md` |-| locating the active `hypit`, working in a remote Agent environment, or checking and updating the executable and Skill through their own channels | `references/environment/distribution.md` |-| what this machine can do, credentials, Model/Provider/Endpoint choices or shared capacity | `references/environment/profile.md` |-| explaining model-service costs, using HypiHub, the user's API or model deployment, or making a project Model/Provider extension | `references/environment/model-and-provider.md` |-| preparing local WhisperX or a render browser, choosing a browser download source, installing local tools, or repairing a Managed Program | `references/environment/local-tools.md` |+| locating, installing or updating the selected executable and Skill; reusing tools, dependencies and produced work | `references/environment/distribution.md` |+| choosing HypiHub or BYOK, connecting the user's API/deployment, or implementing a project Model/Provider | `references/environment/model-and-provider.md` |+| selecting/editing a Profile, wiring credentials and bindings, setting capacity, or deciding when changes take effect | `references/environment/profile.md` |+| configuring and preparing local media tools, browsers or WhisperX; managing helpers, caches, mirrors and logs | `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` |-| cloning with supplied faces or products, changing the Script, language, length, or combining references | `references/creation/transformations.md` |-| writing or revising `<script>`: wording and pronunciation, Segments, Roles, Dual Text, `||` Caption Cues, word attributes, Selections, Moments, empty passages, or measured delivery | `references/creation/script-and-time.md` |+| reshaping a reference while changing a person, object, world, performance, Script or sound; combining references | `references/creation/transformations.md` |+| choosing wording, pronunciation, performable passages, semantic relationships or measured delivery | `references/creation/script-and-time.md` |+| writing `<script>`: current syntax, display/speech, spaces, grouping, Roles, Cue breaks, attributes or marker affinities | `references/production/script-syntax.md` |+| placing a component in time: semantic bindings, authored clock positions, offsets, durations or what a timeline edit changes | `references/production/timing.md` || project layout, picking work back up, or handing an editable production to someone else | `references/creation/project-files.md` || directing a generated person, setting, product, B-roll image, camera view, visual reference or image prompt | `references/playbooks/craft/image-direction.md` || choosing, designing or adapting a character's voice, its appeal, vocal qualities or casting sample | `references/playbooks/craft/voice-direction.md` |-| directing generated video, visible performance, silent action, camera behavior, cuts or request duration | `references/playbooks/craft/video-direction.md` |-| deciding who is A-roll, recurring voice identity, covered performance or independent narration | `references/playbooks/craft/voice-and-performance.md` |-| designing B-roll coverage, montage, short display windows or editorial handoffs | `references/playbooks/craft/b-roll.md` |+| directing generated video, deciding when performed action or camera behavior needs source footage, visible speech, silent action, cuts or request duration | `references/playbooks/craft/video-direction.md` |+| deciding who is A-roll, recurring voice identity, covered performance, independent narration or the role of supplied speech | `references/playbooks/craft/voice-and-performance.md` |+| directing material-led pictures or B-roll: still or moving sources, visual role, composition or handoffs | `references/playbooks/craft/b-roll.md` |+| directing a screen demonstration: real interface evidence, captured interaction, authored illustration or how the viewer follows the screen | `references/playbooks/craft/screen-demonstrations.md` || grouping Chinese, English or mixed-script Caption, reading rhythm, styling or placement | `references/playbooks/craft/captions.md` |+| the user's reference visibly uses Caption that follows a speaking person's head, or the user asks for it | `references/playbooks/craft/caption-tracking.md` || applying Caption Styles by speaker or passage, overriding a treatment, or hiding selected captions | `references/production/caption-presentation.md` |-| designing MG, a board, cards, graphic state, hierarchy, palette or reveals | `references/playbooks/craft/graphic-compositions.md` |-| deciding which generated images or videos should depend on which references | `references/playbooks/craft/generated-dependencies.md` |-| directing music, sound effects, ambience, gain, ducking or the completed mix | `references/playbooks/craft/sound-mix.md` |+| arranging MG, boards, cards or diagrams with material: visual hierarchy, occupied area and palette | `references/playbooks/craft/graphic-compositions.md` |+| directing visual effects or MG in motion: states, actions, handoffs, persistent objects and visual rhythm | `references/playbooks/craft/motion-graphics.md` |+| deciding which generated images or videos should depend on which references, including people, places, views and continuing props | `references/playbooks/craft/generated-dependencies.md` |+| mixing performed or B-roll source sound with chosen music and effects, including balance, ducking and continuity | `references/playbooks/craft/sound-mix.md` || presenting existing Timeline sound, local gain, silence, fades or explicit source blending | `references/production/sound.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` || choosing an existing Prompt Kit, assembling its wording or authoring a new one | `references/production/prompt-kits.md` || Run syntax, material Targets, Candidates, Run Fragments or reusing produced media | `references/production/runs.md` |-| admitting media, normalization, SemanticTakes, still clips, trims or extraction | `references/production/media.md` |+| admitting or reusing images/video/audio for the role this work gives them, model references, normalization, SemanticTakes, trims or processed variants | `references/production/media.md` |+| presenting independent images, prepared video or surfaces, playback and replacement sequences | `references/production/media-presentation.md` |+| placing independent music, narration, ambience or effects and selecting source playback | `references/production/audio-presentation.md` || downloading a reference or source video from a link with yt-dlp | `references/production/video-downloads.md` || capturing a website, recording a page interaction or exporting a local HTML graphic | `references/production/browser-capture.md` || composing, correcting, resizing, cropping or cutting out an image | `references/production/image-operations.md` |-| faces, MG, Caption, insets or layered screens must share one frame, or a subject's background needs removing | `references/playbooks/craft/compositing.md` |+| selecting original/cutout footage or preparing transparency before presentation | `references/production/media.md` || Canvas, Frames, aspect, fitting, cropping or coordinate relationships | `references/production/spatial.md` || choosing or finding fonts, using local font files, multilingual text, Emoji or Typography | `references/production/fonts-and-text.md` || which installed Surface to use, or whether to write a project component | `references/production/vocabulary.md` || sharing a component, Prompt Kit, Model, or Provider across projects | `references/production/component-sharing.md` || placing Takes, gaps, overlap, complete duration or a pure MG work on one Timeline | `references/production/timeline.md` |-| composing Performance, Media, Audio, Caption, Text, MG and Effect Tracks | `references/production/tracks.md` |+| choosing content ownership and composing visual/audio contributions | `references/production/tracks.md` || presenting existing Timeline footage with broad or local Uses, a moving viewport or a custom Performance Style | `references/production/performance.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` |@@ -289,6 +311,7 @@ practical, revisit that choice and carry the improvement into the work and its n| showing the editable work before export: Comments, Studio timeline, parameters, timestamped feedback and interface language | `references/production/studio.md` || giving a component useful timeline entities, picture selection and author controls | `references/production/studio-companions.md` || Film assembly, pure MG with authored time, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` |+| exact frames or paginated grids of an existing production, without a new render Build | `references/production/snapshots.md` || judging the preview or finished Result and deciding what to fix | `references/production/review.md` || recognizing a whole-work format, combining formats, or discovering another directing Craft | `references/playbooks/index.md` |diff --git a/skills/hypit/references/creation/reference-video.md b/skills/hypit/references/creation/reference-video.mdindex 871cf118..819d67bd 100644--- a/skills/hypit/references/creation/reference-video.md+++ b/skills/hypit/references/creation/reference-video.md@@ -32,8 +32,8 @@ sharpen the question and recognize what the reference is doing.A motion's name is a starting point. Inspect its path, scale or opacity change, pace, overshoot orsettling, and relationship to neighboring events when those make the effect distinctive. Likewise,understand a graphic's hierarchy, typography, palette and spacing through what the viewer must read-first and compare next. Compression comes from identifying a coherent behavior that explains many-frames. A dimmer copy during an exit may be one object's fade, for example; inspect the sequence to+first and compare next. Identify the coherent behavior linking the observed frames, including the+details that make its states and transitions work. A dimmer copy during an exit may be one object's fade, for example; inspect the sequence tounderstand the change.Whole-piece and close readings revise each other. An object that survives a camera cut belongs to a@@ -80,7 +80,7 @@ for local execution, prepare that language's resources as described inIts timed Chinese characters help locate a phrase precisely; group those characters into meaningfulphrases when describing the reference and writing the new Script.-[Environment selection](../environment/profile.md#choose-the-practical-capability-path-with-the-user)+[Service selection](../environment/model-and-provider.md#choose-the-practical-capability-path-with-the-user)explains assessing local preparation and choosing the local or hosted path for this transcription.WhisperX's recognized spelling reflects the recognizer's interpretation of the audio. Coined words@@ -100,6 +100,22 @@ The local `hypit media` commands expose the source at the scale needed:- `boundaries` locates abrupt visual changes worth inspecting;- `fetch` saves a supported video link locally.+For a close reading of motion, `frames --every-frame` and `tiles --every-frame` retain every original+frame in the selected interval. Each interval is decoded continuously once, then the images are+paginated at the requested cell size. Actual source timestamps preserve variable-rate footage.+Use `--ranges` with `tiles` to visit several intervals, and `--transcript` to read their word context.++```bash+hypit media tiles references/ad/source.mp4 --start 6.8 --end 8.4 --every-frame \+ --columns 4 --rows 3 --cell 480 --transcript references/ad/transcript.json \+ --to references/ad/evidence/list-motion+```++For the production being composed, [snapshot](../production/snapshots.md) captures its existing+picture directly from Studio or compiled HTML. Align the comparison by the event's meaning and+then inspect its concrete frames. Coarse and fine readings continue to inform each other: understand+the whole work, establish the particular behavior, and revisit the whole explanation with that knowledge.+Read grids along the developing explanation, using the transcript's phrases and word times as thepreferred guide for spoken references. Pass `--transcript` to keep those words beside the frames;`--around` can locate the phrase whose picture change you want to understand.@@ -201,9 +217,9 @@ The user's request determines how those relationships should live in the new pieperson or product may change the argument, copy, number of examples, graphic content, placement andduration. Use [transformations](transformations.md) to think through that adaptation. PreferSelections for meaningful spans and Moments for events in the target Script, and let the accepted-performance establish their time. [Script and time](script-and-time.md) owns that authoring language.+performance establish their time. [Script syntax](../production/script-syntax.md) owns that authoring language.-For generated camera imagery, [image direction](../playbooks/craft/image-direction.md#compress-the-idea-into-decisive-anchors)+For generated camera imagery, [image direction](../playbooks/craft/image-direction.md#two-ideas-behind-every-sentence)turns the observed appearance into a coherent styling and scene direction, with the decisive detailsthe target needs. The reference notes retain the observations behind those choices.@@ -223,6 +239,6 @@ Keep the current question, passages or systems still to examine, and next usefulaccounts when the reading changes. When resuming, read these files and reopen the source at therecorded locations. The user's goal remains in Brief and your new design in Treatment.-When the intended adaptation depends on an action's exact movement or camera path, preserve a useful-source excerpt as motion evidence for [reference-directed generation](../playbooks/craft/video-direction.md#let-footage-carry-motion-that-matters).-The analysis explains what matters; the footage can carry that movement into the model request.+When the intended adaptation depends on a performed, physical or camera relationship unfolding in+time, preserve a useful source excerpt as temporal evidence for [reference-directed generation](../playbooks/craft/video-direction.md#let-footage-carry-temporal-behavior-that-matters).+The analysis explains what matters; the footage can carry that behavior into the model request.diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.mdindex f87ed5ae..8c8f9d99 100644--- a/skills/hypit/references/creation/script-and-time.md+++ b/skills/hypit/references/creation/script-and-time.md@@ -1,10 +1,9 @@# Script and semantic time-Read this before writing or revising `<script>`, when balancing spoken delivery across generated-Takes, or when attaching pictures, Captions, MG, Effects, and Audio to what is said. It also explains-how a passage with no spoken words receives semantic boundaries. This page contains the complete-stable author-facing Script vocabulary; the installed `@hypit/script` package owns parser validation-and edge cases.+Read this when deciding the target wording, pronunciation, performable passages and the meanings+that picture and sound should follow. It also covers measured delivery and wordless passages.+[Script syntax](../production/script-syntax.md) owns the authoring forms;+[Timing](../production/timing.md) owns their projection into the work.[Source syntax](../production/source-syntax.md) covers the surrounding imports, references, Recipesand Runs; [Tracks](../production/tracks.md) covers the consumers of Script meaning.@@ -36,7 +35,7 @@ Choose Script structure from the thought being expressed and the performance car```svml<script id="story"><hook>- <HOST> @{claim!} I made the @{proof} <API | A P I> || work overnight @{/proof}.+ <HOST> @{claim!} I made the @{proof}<API | A P I> || work overnight.@{/proof}</hook></script>```@@ -53,80 +52,47 @@ Use `||` when the same Segment, turn and Style still needs another deliberate re[Caption craft](../playbooks/craft/captions.md#design-cue-rhythm-with-the-caption-system) owns how thepicture, language, family and Recipe shape that decision.-The author-facing forms are:--| Form | Meaning |-| --- | --- |-| `<opening>...</opening>` | A Segment named `opening`; all spoken prose belongs inside a Segment. |-| `<pause/>` | A self-closing Segment with identity and boundaries but no words. |-| `<HOST>` | A Role Cue inside the current Segment; it applies until another Role Cue or the Segment end. |-| `<display text \| spoken text>` | One Dual Text unit with separate visible and pronounced wording. |-| `<display text\|>` | One complete display/speech unit using the same wording for both; individual spoken word times remain available. |-| `< \| spoken text>` | Spoken words that keep semantic timing while contributing no visible Caption words. |-| `||` | A Caption Cue handoff between complete Alignment Units. |-| `word{emphasis,keyword}` | Boolean attributes on one complete display word for a Caption family to interpret. |-| `word{importance=2,tone=warm}` | Named string, number or boolean attribute values on that display word. |-| `@{proof} ... @{/proof}` | A Selection: one named semantic range. |-| `@{claim!}` | A Moment: one named semantic point. |--A Script contains one or more uniquely named lower-case Segments. A paired Segment can carry prose-or be wordless; the self-closing form also carries a wordless passage. A Role Cue is a bare turn marker rather than a-paired element: the next Role Cue begins the next turn, and closing the Segment ends the final turn-and resets its Role. When a Segment uses Roles, place the first Role before that Segment's first-spoken text. One Segment can contain several Role turns without requiring several generated Takes.--Dual Text can contain several visible or spoken words on either side; its display side feeds Caption-and its spoken side feeds pronunciation. An empty display side intentionally omits those spoken words-from Caption while keeping them in the Narrative and semantic timing. Selections and Moments can be-placed on the spoken side because that side owns the speech anchors. Place Cue Breaks around the-complete Dual Text unit, not inside it. Attributes for a displayed Dual Text word belong on the-display side before the pipe. Inside that display side, use `\@` when the visible text itself needs an-at-sign.--When the wording is identical, `<组件化|>` is shorthand for `<组件化|组件化>`. It can group a name,-compound or phrase for Caption presentation while leaving its spoken Tokens and timing intact:-`把<动效|><组件化|>。|| 以后就能<直接复用|>。` Choose groups for the intended expression; ordinary-Chinese prose does not require word-by-word markup. The group's Style determines its visual response;-`||` still controls which reading phrases appear as separate Cues.--With speech omitted, the left side supplies both projections, so semantic markers can be placed-there and Studio writes back there: `<组@{beat!}件化|>`. Display attributes and markers are metadata,-not spoken words. Attributes still apply to the preceding display word rather than the whole group.-With an explicit spoken side, markers continue to belong on that right-hand side.--Script comments use ordinary Markup comments outside the prose:--```svml-<!-- This note enters no text projection. -->-<social><HOST> Follow us \@hypit.</social>-```--Reserved Script punctuation remains literal when escaped: `\@` produces `@`, `\<` produces `<`,-`\{` produces `{`, `\}` produces `}`, `\|` produces `|`, and `\\` produces `\`. A plain `>` needs-no escape in ordinary prose; inside Dual Text, `\>` keeps it from closing that unit. A single `|` in-ordinary prose is literal; `||` is the Caption Cue handoff. Inside Dual Text, the first unescaped `|`-separates display from pronunciation; write `\|` for a literal pipe and `\|\|` for two literal pipes.-These escapes belong to Script prose, while structured Source attributes and elements use the Markup-escaping described in [Source syntax](../production/source-syntax.md).--Script derives speech tokens from words and numbers. Punctuation remains attached to the displayed-word it belongs with and does not create another speech time unit. CJK prose commonly contributes-one Han, Hiragana or Katakana character per lexical unit; compounds, decimal numbers and the spoken-side of Dual Text preserve their own lexical structure. This is why Cue breaks, word attributes and-semantic markers attach to complete authored units instead of punctuation or visual line positions.-Character-level timing does not call for character-sized Cues: use `||` for meaningful reading-phrases. [Caption craft](../playbooks/craft/captions.md#language-changes-the-reading-unit) explains-Chinese, English and mixed-script grouping, spacing and their fit in the picture.+[Script syntax](../production/script-syntax.md) owns the exact forms, display/speech projections,+spacing, grouping and marker affinities. Use those forms to express the choices above.## Write the intended pronunciationChoose pronunciation while writing the Script. For coined names, unfamiliar brands and abbreviationswhose reading needs direction, use Dual Text to keep the intended display spelling and give theperformer a clear spoken form. Write that form as readable words, syllables or letter names in the-performed language. Keep ordinary spelling when it already expresses the intended reading; an-English name inside Chinese speech does not automatically need a phonetic replacement. The spoken-side is literal model input, so invented respellings and punctuation can suggest unintended sounds.-Use a reading established for the selected language and voice, and retain the user's chosen spelling.+performed language. Familiar word sounds, phonetic respellings and homophones can make an unfamiliar+name's intended sound concrete while its display spelling stays intact. Keep ordinary spelling when+it already expresses the intended reading; an English name inside Chinese speech does not+automatically need a phonetic replacement. Choose the reading for this language and character,+retaining the user's chosen display spelling.++### Choose the sound the spelling should carry++These examples illustrate authored pronunciation choices, not generation results verified for every+model. The spoken column is the literal text supplied through `.speech` or inside `.dialogue`:++| Intended reading | Script fragment | Caption displays | Spoken text |+| --- | --- | --- | --- |+| Name the letter S | `<S\|ess>` | `S` | `ess` |+| Say each letter of CSS by name | `<CSS\|see ess ess>` | `CSS` | `see ess ess` |+| Spell out an abbreviation using separated letters | `<API\|A P I>` | `API` | `A P I` |+| Say SQL as the word “sequel” | `<SQL\|sequel>` | `SQL` | `sequel` |+| Give a coined name familiar syllables, when “zoo no” is the chosen reading | `<Zuno\|zoo no>` | `Zuno` | `zoo no` |+| Give a name a chosen Mandarin homophonic reading | `<Lumi\|露米>` | `Lumi` | `露米` |++Letter names, letter sounds and an acronym pronounced as a word are different choices. `ess` names+S; it does not ask for a sustained /s/ sound. Likewise, `sequel` chooses one reading of SQL; use the+intended letter names when the character should spell it out instead. Choose natural phrasing for+the whole expression rather than inserting artificial pauses between every letter or syllable.++Phonetic notation, including IPA, can guide a model that understands it. Script forwards the written+form literally; it does not interpret IPA or expose a phoneme-control API. The spoken projection also+feeds measurement and semantic preparation, so choose a representation usable by that production's+speech path. Any model-specific pronunciation feature belongs to that model's documented inputs.+Keep a reading aid such as `ess` on the spoken side; prose instructions such as “pronounce this as”+belong in performance direction when needed, not among the words the Script asks the character to say.++### Carry the chosen reading through the work```svml<script id="story">@@ -152,44 +118,14 @@ wording, including the syllables hidden behind its compact numeric display. Captauthored simplified or traditional characters; transcription supplies timing rather than rewritingthe displayed Script.-## Use the Script's deliberate projections--One Script publishes the full Narrative and the narrow views needed by the rest of the work:--| Reference | What it carries |-| --- | --- |-| `{story}` | The complete authored Narrative. |-| `{story.segment.hook}` | The `hook` Segment as a NarrativeExcerpt for one SemanticTake. |-| `{story.segment.hook.dialogue}` | Role-aware dialogue using the spoken side of Dual Text, suitable for a speaking performance request. |-| `{story.segment.hook.speech}` | Pronunciation-only Text, suitable for `hypit measure` or independent speech. |-| `{story.caption}` | Display Words, Alignment Units, attributes, Roles, and authored Cue Breaks for Caption. |-| `{story.selection.proof}` | The named semantic range. |-| `{story.moment.claim}` | The named semantic point. |--For example, this Segment inside `story` assigns two speaking turns:--```svml-<exchange>- <HOST> Let me show you.- <GUEST> That looks much easier.-</exchange>-```--`{story.segment.exchange.dialogue}` supplies:--```text-HOST: Let me show you.-GUEST: That looks much easier.-```--Pass that Text to the speaking prompt. In action direction, relate HOST and GUEST to the supplied-character views and voices. The selected [Prompt Kit](../production/prompt-kits.md) owns its reference-order; [podcast direction](../playbooks/formats/two-person-podcast.md#direct-conversation-inside-a-take)-shows how those roles and references form one performed exchange.+## Choose performable passages-These are projections of one authored Script, not copies to maintain. The performance request,-Caption system, and semantic timing therefore remain connected even when their visible and spoken-wording differ.+Supply the Segment's `.dialogue` to the speaking prompt; it includes Role labels and the chosen+pronunciation. `.speech` supplies pronunciation without Role labels for measurement or speech-only+requests. The Caption view preserves the display wording. These are projections of one Script,+so revising the words does not require maintaining another copy in a prompt or subtitle file.+[Script projections](../production/script-syntax.md#use-the-scripts-deliberate-projections) shows the+references and a two-speaker example.Script also represents passages without speech:@@ -212,6 +148,10 @@ picture cut. One Segment and Take can carry several speaking turns, camera cutsconversation. One continuous narration can carry many B-roll changes through Selections. Edited UGCcan deliberately use several Takes driven by the same character-and-scene image; a natural cut isoften part of its appeal. A Role change or `||` does not require another generation.+When retained recorded speech carries the passage, a file cut changes that performed material but+does not automatically create a Segment. Several retained stretches can form one passage; distinct+passages can use separate Takes. Write the Script for the final performed words and align the+prepared result on its own local clock.## Time an authored animation@@ -292,86 +232,12 @@ For a picture, Caption treatment, MG state, sound, or effect that belongs to spoSelection or Moment and use the consuming component's Surface to project it through the Timeline.Use explicit seconds for genuinely clock-based or speechless design.-Every semantic marker is enclosed in `@{...}`, with `/`, `!` and `~` inside. The marker contributes-no text or whitespace. `是的@{part}就是这样@{/part}` stays joined; `是的 @{part}就是这样@{/part}`-keeps its authored space. Do not add spaces to make a marker parse. Markers cannot split a speech-Token or its attached punctuation: write `@{beat!}“测试”`, not `“@{beat!}测试”`. Attributes stay attached to their display word: `word{emphasis}@{beat!}`. Write literal-`@{part}` as `\@\{part\}`. Bare 0.1 markers require explicit migration before use with 0.2.--Selections may overlap, cross, or span Segments; they are named semantic ranges rather than nested-markup. Selection and Moment names share one namespace. Inside spoken text, each marker chooses an-adjacent semantic boundary:--| Marker | Boundary |-| --- | --- |-| `@{name}` | Open a Selection at the next word's start. |-| `@{~name}` | Open a Selection at the previous word's end. |-| `@{/name}` | Close a Selection at the previous word's end. |-| `@{/name~}` | Close a Selection at the next word's start. |-| `@{name!}` | Place a Moment at the next word's start. |-| `@{~name!}` | Place a Moment at the previous word's end. |--Markers may sit between or outside Segments when the meaning crosses structural passages. For-example, this Selection owns the complete Script program rather than borrowing the first and last-word boundaries:--```svml-@{~whole}-<opening><HOST>First thought.</opening>-<answer><HOST>Final answer.</answer>-@{/whole~}-```--At a Script or Segment edge, the corresponding structural boundary remains available even when-there is no neighboring word. Thus `@{videos} videos @{/videos}` covers exactly that word. For adjacent-B-roll windows that should also own the pause between words, choose which neighboring Selection-owns that gap through the explicit affinities; [B-roll craft](../playbooks/craft/b-roll.md) shows the-shared-boundary forms.--The consuming component's Surface projects the authored identity through the real Timeline.-For example, `during={story.selection.proof}` on a visual Item makes that Surface construct a Window.-A persistent MG reveal can use `at={story.moment.claim}` to consume an Instant; an Audio Item uses-`at={story.moment.claim} for="600ms"` to occupy a Window. The component's Fragment and Producers-consume that value and own playback, visible duration, animation, and state behavior; Script supplies-the meaning and its Anchors.--Surfaces that expose Hypit's shared temporal vocabulary accept the forms appropriate to their role.-A Window occupies an interval:--| Form | Result |-| --- | --- |-| `during="program"` | The complete program Window. |-| `during={story.segment.hook}` | The Segment's Window. |-| `during={story.selection.proof}` | The Selection's Window, including its authored affinities. |-| `at={story.moment.claim} for="8f"` | A Window beginning at a Moment and lasting eight frames. |-| `at="2s" for="12f"` | A Window beginning two seconds into the film and lasting twelve frames. |-| `until={story.moment.claim} for="250ms"` | A 250 ms Window ending at a Moment. |-| `start="program.start" end="moment.cue" moment={story.moment.claim}` | A Window composed from two explicit endpoints. |--Each Window uses one complete form. Explicit endpoint expressions can use `program.start`,-`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end`, or `moment.cue`,-with the corresponding semantic reference supplied alongside it. They can also use a clock position-such as `1.5s` or an offset such as `selection.start - 2f`. Frames and milliseconds are integers;-seconds may be fractional.--An Instant names one point:--| Form | Result |-| --- | --- |-| `at={story.moment.claim}` | The authored Moment. |-| `at="2s"` or `at="12f"` | A point on the film clock, in seconds or frames. |-| `at={story.selection.proof} boundary="start"` | The Selection's chosen boundary. |-| `at={story.segment.hook} boundary="end"` | The Segment's chosen boundary. |-| `instant="program.start + 8f"` | An explicit clock expression. |-| `instant="moment.cue + 12f" moment={story.moment.claim}` | Twelve frames after the Moment, following it when the delivery changes. |--`at="12f"` locates an event; `for="12f"` gives an interval its length. Frames use the selected-film clock. Semantic projection keeps the event's Script identity alongside its resolved frame,-so its authored relationship remains available for later changes.--A particular Surface may deliberately expose only some of these forms. Its vocabulary reports the-attributes it actually accepts; the shared spelling does not grant every component every temporal-behavior.+Choose an anchor by the event it names, including which side owns a pause. For adjacent B-roll,+one Selection can end where the next begins; for a held reaction, a range can include the silence+before the next word. [Marker affinities](../production/script-syntax.md#bind-meaning-to-script-identities)+express these choices through word and structural boundaries. [Timing](../production/timing.md)+explains projecting those identities into a component's Instant or Window, adding deliberate offsets,+and what a later Studio edit changes.Reference archives keep original seconds and explain which original words or content events an itemserves. The target Source names the intended relation against the target Script. After the target'sdiff --git a/skills/hypit/references/creation/transformations.md b/skills/hypit/references/creation/transformations.mdindex 5bbd3416..e69916d0 100644--- a/skills/hypit/references/creation/transformations.md+++ b/skills/hypit/references/creation/transformations.md@@ -1,7 +1,7 @@# Transforming a reference into a target-Read this when a user brings a reference and asks for their own version: their face, their product,-a different story, or another audience. Several changes can belong to one creative intention.+Read this when a user brings a reference and asks for their own version: another person, object,+world, performance, story, or audience. Several changes can belong to one creative intention.Look at the supplied material and think about the reference together with the user's request. Whatmakes the original compelling, and how can that appeal belong to this new person or product? Keep@@ -46,14 +46,35 @@ Useful transformation lenses include:These lenses are prompts for thought, not fields to complete. Follow the relationships the actual workcontains.+## Reshape an event from footage++Some adaptations are recognizable through an unfolding event rather than any one subject's pixels.+A stylized direct-address performance, dance phrase, fight, moving camera view, or mishap seen by a+fixed camera may depend on particular timing and physical relationships. These are useful places to+look for temporal evidence: discover what carries the reference's appeal, from performed delivery+and reaction to movement, contact, camera position and payoff.++The target may change a person, object, setting, spoken words, sound, visual world, or several of+these together. Changing the person is common; a narrow substitution may leave most other+relationships intact. When a new body, object or story changes what an action means, reshape the+action to serve the target's intention. Brief and Treatment hold the requested change and the new+creative answer; the source footage remains evidence rather than a ready-made target timeline.++In a comic speaking reference, an unusual camera angle may work together with role-played vocal+phrasing, expression and gesture. Put the intended words in Script, choose whose voice belongs to+the target, and direct how the visible performance delivers the joke. A supplied portrait establishes+appearance, not the voice or delivery. [Voice direction](../playbooks/craft/voice-direction.md) owns+casting; [video direction](../playbooks/craft/video-direction.md#let-footage-carry-temporal-behavior-that-matters)+owns when a selected source excerpt should condition the new shot.+## "Make this with my face"Suppose the user supplies a portrait and a football Ranking video. The jokes concern the players, sothe spoken argument and comic reveals may already suit the new presenter. Bring the user into thecamera image with the reference's teasing confidence, useful framing, and room for the board. Keepthe full [image craft](../playbooks/craft/image-direction.md), directing the supplied person's appeal-and presence with the same care as an invented character. That image can carry all ordinary talking-Takes and supply the person's other appearances.+and presence with the same care as any leading performer in this work. That image can carry all+ordinary talking Takes and supply the person's other appearances.A joke about the original presenter's appearance or personal story needs another look: decide howits setup and payoff fit the new casting and Brief. The new person may invite a different delivery ordiff --git a/skills/hypit/references/environment/distribution.md b/skills/hypit/references/environment/distribution.mdindex 63e765a2..a6b342ce 100644--- a/skills/hypit/references/environment/distribution.md+++ b/skills/hypit/references/environment/distribution.md@@ -1,38 +1,46 @@-# Executable Distribution+# Installations, updates and reuse-Read this to locate, install, or update the executable Hypit Distribution after installing the Skill.+Read this to find the Hypit already available, install a missing executable, update a selected+installation, or continue a production without discarding its tools and material.+[Services](model-and-provider.md) owns account and model access; [Profile](profile.md) owns execution+selection; [local tools](local-tools.md) owns preparation after that selection.++Go to [locating the executable](#find-the-installation-already-available),+[installation](#install-the-executable-package), [reuse](#reuse-what-already-serves-the-production),+or [updates](#let-the-installation-channel-own-updates) for the current question.## Keep three lifecycles separate-The installed Skill supplies production judgment. The executable Distribution supplies `hypit`,-`hypit studio`, official packages, and Runtime hosts. A video project supplies the work's Sources,-Runs, assets, local packages, Profile selection, and Results. They can live in unrelated locations-and none is installed as a side effect of another. `npx skills add hypit-ai/hypit -g` installs the-Skill's knowledge; the executable is the separate npm package `@hypit/hypit`.+| Part | What it supplies | Where changes belong |+| --- | --- | --- |+| Hypit Skill | Production judgment and navigation | The Skill's own installation channel |+| Executable Distribution, `@hypit/hypit` | CLI, Studio, Runtime and bundled packages | Its npm/release installation |+| Video project | Sources, Runs, assets, project packages, selected Profile and Results | The project's files and package lock |++An installed Skill does not install the executable. Installing the executable does not connect an+account, supply model credits, or prepare every browser and model. Updating either does not itself+rewrite a project's Sources or regenerate its Outputs.-Work from the capabilities of the current Agent environment: project-file access, command execution,-service connectivity and a way to return previews or media to the user. A browser interface can-control a remote execution environment; its files, processes and localhost addresses belong there.-Use the environment's available preview forwarding or file delivery, and retain the project and-accepted material in storage that lasts beyond a disposable session. Reading the Skill establishes-available knowledge; the actual tools and locations establish what can run.+Work from the actual Agent environment: file access, command execution, service connectivity, and+a way to return media or previews. In a remote environment, processes, files and localhost URLs belong+to that host. Use its preview forwarding and persistent storage. A production does not need a+contributor checkout merely because the Agent can read Hypit's source.## Find the installation already available-An available launcher can identify its version and physical locations:+Use the relevant observations from the project directory:```bash-hypit --versionhypit version-hypit --helphypit paths+hypit --help```-`version` identifies the executing Distribution and launcher without opening a project or Runtime.-`paths` includes the active Distribution, project, and host locations. A missing Runtime Profile is-a separate setup question from whether the executable is installed.+`version` identifies the active executable and launcher without opening a Runtime.+`paths` identifies the project, selected Profile, Distribution and host locations. A missing Profile+is a configuration question, not evidence that Hypit needs reinstalling.-If the shell cannot find `hypit`, inspect the project's and npm's global package records:+If the shell cannot find the executable, inspect existing package records:```bashnpm ls @hypit/hypit --depth=0@@ -40,105 +48,129 @@ npm ls --global @hypit/hypit --depth=0npm prefix --global```-A project installation can run through `npm exec --no -- hypit --version` and-`npm exec --no -- hypit paths`; `--no` declines npm's offer to install a missing package. A global-installation may need its executable directory added to the current shell's PATH: `<prefix>/bin`-on POSIX systems, or the prefix itself on Windows. Use the existing installation or its known-launcher, and retain the working command and location in project notes when useful for resuming.+A project installation runs through `npm exec --no -- hypit version`; `--no` declines npm's offer to+install a missing package. A global installation's executable directory is normally+`<prefix>/bin` on POSIX or the prefix itself on Windows. Use the selected installation's launcher+and inspect its reported version; a global command and a project-local command may select different+releases. Record the useful command and location in project notes when resuming will need them.## Install the executable package-The usual machine-wide installation command for a published release is:+For a machine-wide published installation:```bashnpm install --global @hypit/hypit```-A project can instead keep Hypit in its own dependencies and lockfile:+For a project that deliberately keeps the executable in its dependencies:```bashnpm install --save-dev @hypit/hypit-npm exec --no -- hypit --help+npm exec --no -- hypit version```-Use the release version selected by the user or project when one is specified. If the selected-registry reports a missing package or version, that release is unavailable there. An official release-supplied as a tarball can be installed directly, for example-`npm install --global /path/to/hypit-release.tgz`. Report the actual installation error when the-release cannot be obtained.+Use the project's chosen package manager and version when specified. Its package manifest and+lockfile own physical versions. A supplied release tarball can also be installed through npm, for+example `npm install --global /path/to/hypit-release.tgz`.++A registry's missing version is an availability fact for that registry. Preserve the chosen version+when investigating a stale mirror or slow download; [network preparation](local-tools.md#make-network-preparation-practical)+explains matching the remedy to the actual download. Verify the active launcher after installation,+then continue with the capability needed by the work.++## Reuse what already serves the production++| Existing work | How to carry it forward |+| --- | --- |+| A suitable executable | Use it across projects; identify the active launcher before adding another installation |+| A chosen service and stored credential | Reuse its explicit Profile selection and CredentialRef within the user's account choice |+| Prepared local tools or model weights | Inspect the selected Provider's actual paths and configuration; reuse compatible resources there |+| Project components and dependencies | Keep their package versions and lockfile; edit the project's own implementation where needed |+| Generated or processed Outputs | Select them explicitly as Run Candidates so the next Build does not repeat that work |++Host tools and prepared resources have their own locations; creating another video project does not+require copying a Python environment or browser into it. An existing cache can reduce preparation+without selecting a different model, language, account or browser.++For cross-project component reuse, follow [component sharing](../production/component-sharing.md):+keep project components with their project, or explicitly install an owner's versioned package when+sharing is needed. Its ordinary package manifest and lockfile select the implementation. Update that+dependency deliberately; a Hypit or Skill update does not upgrade every project's component packages.-If installation is slow or a registry mirror lacks the selected release, use-[network preparation](local-tools.md#make-network-preparation-practical) to inspect the actual download-source and choose a reachable route. Keep the requested version when changing registries.+Preserve project assets, Results and current Run selections during an update. A newer executable is+not a reason to regenerate accepted material. [Output reuse](../production/authoring.md#reuse-produced-work-explicitly)+owns choosing compatible produced values, including useful Outputs from failed Builds.+If a release changes authoring requirements, make the relevant project change explicitly from its+documented meaning rather than guessing a migration or silently substituting another capability.## Let the installation channel own updates-The Distribution supplies local execution and HypiHub Providers, plus public SDKs and examples for-project extensions. A service the user brings can use an installed or project-authored Provider;-its absence from the official bundle is an extension question. Follow-[Models and Providers](model-and-provider.md) for that connection. Installing the executable does-not choose a service account or prepare every model that a production might eventually use.+Check versions when a reported fix, missing capability, update request or release change matters to+the work. Continue ordinary production on its selected versions; Build does not upgrade them.-Install, update, and remove the Distribution through the same package or release channel. Updating-it does not update an installed Skill or edit a video project. Updating the Skill does not replace the-executable Distribution. After installation or an update, use the selected launcher for `--version`,-`--help`, and `paths`, then continue with-`profile.md` for the current project's capabilities and Runtime choices.+```bash+hypit version --check+```++This read-only query reports npm release information and its source. `--registry <url>` selects a+registry for the check; `--json` gives structured output. Local `hypit version` and `--version`+do not contact a registry. With an older executable lacking the command, use+`npm view @hypit/hypit@latest version` through the project's configured registry.-The installed Distribution is the authority for exact Surface syntax. If a package or Surface named-by the Skill is absent from `hypit vocabulary`, check package selection and the installed release.-Explain whether the work needs an available package, a supported alternative or a Distribution update.+A failed query leaves the remote release unknown. A different version can mean a newer checkout or+a stale mirror. Read the relevant [release notes](https://github.com/hypit-ai/hypit/releases) and+explain which installation and behavior would change.## Check and update the relevant installation-Use the installed version and release information to understand available capabilities or a reported-fix. The active launcher above identifies what is running. Check the latest published executable-without installing anything:+When the chosen target is the latest published release, update the selected installation only:```bash-hypit version --check+npm install --global @hypit/hypit@latest```-This reads npm's public registry and prints the source and release-notes link. Use `--registry <url>`-with `--check` for a chosen mirror, or `--json` for structured output. A different version can mean-a newer local checkout or a stale mirror; a failed query leaves the remote version unknown. Neither-observation changes the project or starts an upgrade. Ordinary `hypit version` and `--version` stay-local. For an older executable without this command, the existing package-manager query still works:+For the project-local development dependency shown above, run instead from that project:```bash-npm view @hypit/hypit@latest version+npm install --save-dev @hypit/hypit@latest+npm exec --no -- hypit version```-`npm view` reads the configured npm registry; a stale mirror or failed query leaves the upstream version-uncertain. The [Hypit releases](https://github.com/hypit-ai/hypit/releases) explain published changes.-Tell the user which change matters to this work and which installation needs it. Updating follows-the selected installation method above, respecting the project's chosen version and lockfile.+Use an exact selected release instead of `latest` when the user or project pins one, and preserve+the existing dependency kind and package-manager workflow. These are alternative installation scopes,+not two steps to run together. Recheck the launcher the production will actually use.-An installed Skill has its own source and installation scope. For the-[skills installer](https://github.com/vercel-labs/skills#skills-update), inspect its current help and-installed records (`npx skills list -g` for the global scope). When updating a globally installed-Hypit Skill, use a targeted update:+The Skill updates separately. For an installation managed by the+[skills CLI](https://github.com/vercel-labs/skills#skills-update), inspect its installed records and+current supported options. The following targets only the globally installed Hypit Skill:```bash+npx skills list -gnpx skills update hypit -g```-This changes that installed Skill; it is not a read-only check. Use the scope and-options supported by the actual installer. A different installer or explicitly selected checkout-uses its own update method. Updating Hypit need not update unrelated skills or project dependencies.-Read the updated Skill from the installation the Agent uses; an already loaded instruction can-still reflect its earlier contents. Report what was updated and what remains unchanged or unknown.+For a project-scoped installation, use the installer's project scope (`-p` on `update`) from that+project. A local checkout or another installer keeps its own update method. The update command is a+mutation, not a read-only version check; preserve intentional local Skill edits before replacing them.+Do not update unrelated skills as a side effect. Read the updated instructions from the installation+the Agent actually uses; content already loaded in a conversation can still be the old text.++The installed packages' vocabulary and README describe their available interfaces. If a newer Skill+mentions an absent option, inspect the selected package and release. Explain the missing capability+and the useful update or explicitly chosen alternative; do not pretend the option already exists.## Project changes and execution code-A contributor checkout can execute its own Distribution after its documented workspace setup, but it-is a development arrangement, not an assumed location for ordinary production. Use one only when the-user explicitly supplied or selected that checkout.--Optional upstream npm tools live under the Host package home reported by `paths`, with one installation-per exact package version. Separate Distribution requirements can coexist there, while npm still shares-its download cache. `hypit packages install <package@version>` reports `install.log`; inspect that file-when a download appears stalled or fails. Installing an upstream tool does not start a service or-restart an existing service. Project component edits are loaded by the next Build. See-[Build execution](../production/builds.md#build-with-the-current-project-implementation) for Distribution-bootstrap changes and service lifetimes.+Project component and Profile changes apply to a new Build through its execution context. Updating+the Distribution or the environment inherited by an active Worker concerns that process's lifetime.+Use [configuration changes](profile.md#know-when-a-change-takes-effect) before restarting it, and+preserve active work and accepted Outputs.++Optional upstream npm tools live in the Host package home reported by `paths`, per exact package+version, with npm's ordinary download cache. Explicit preparation may acquire these declared+dependencies. `hypit packages install <package@version>` addresses a reported exact dependency;+its `install.log` explains progress and failure. Installing a dependency does not start a service.++A contributor checkout is an explicit development choice. Use one when the user has selected it;+ordinary production, project components and project Model/Provider extensions use the installed+public interfaces.diff --git a/skills/hypit/references/environment/local-tools.md b/skills/hypit/references/environment/local-tools.mdindex 4200212a..ef0245d3 100644--- a/skills/hypit/references/environment/local-tools.md+++ b/skills/hypit/references/environment/local-tools.md@@ -3,6 +3,13 @@Read this when assessing local preparation, selecting local WhisperX, or preparing and repairing alocal Endpoint's executable or Managed Program.+Go to [host tools](#supply-host-executables-at-machine-scope),+[local media configuration](#configure-local-media-tools),+[Program lifecycle](#let-the-selected-endpoint-own-its-program),+[render browser](#prepare-the-local-rendering-browser),+[WhisperX](#select-local-whisperx-explicitly), or+[downloads and mirrors](#make-network-preparation-practical) as needed.+## Assess local preparationUse `hypit paths` to locate the selected Profile and machine state. Inspect relevant service@@ -12,7 +19,7 @@ command leaves that installation's state unknown. The installed `@hypit/providerREADME owns its preparation and service locations.Establish what already works, what needs starting or repair, and what needs downloads. Use those-findings in [environment selection](profile.md#choose-the-practical-capability-path-with-the-user),+findings in [service selection](model-and-provider.md#choose-the-practical-capability-path-with-the-user),then prepare the chosen setup using its Provider instructions and the evidence from its logs.Consider hardware and actual network reachability alongside installed files. A cached environmentcan still need speech-model weights or a language's alignment model before its first useful request.@@ -20,6 +27,11 @@ Existing weights can make local preparation attractive; report that fact while oand hosted choice. Starting a newly configured large-model service is preparation even when allweights are cached. A previously chosen, working service can be carried forward directly.+Available, selected, prepared and running answer different questions. A binary on disk is not+necessarily the selected executable; a Profile declaration does not install resources; a running+speech service does not establish that a new language's aligner is cached. Check the fact the next+operation actually needs, rather than treating the machine as globally ready or unready.+## Diagnose the selected local capabilityChoose the observation that answers the current question:@@ -30,7 +42,7 @@ Choose the observation that answers the current question:| Is the Worker running, and is work active? | `hypit runtime status` || What has the Worker reported? | `hypit runtime logs` || Which selected local helpers answer, and where are their logs? | `hypit programs status --verbose` |-| Does the selected Profile's broader configuration and service access work? | `hypit doctor` |+| Does a selected Endpoint's configuration and service access work? | `hypit doctor --endpoint <instance>` |Read the failing Endpoint's message and package README before changing the machine. The Profile sayswhich local implementation was selected; another project's working service is not evidence that this@@ -41,6 +53,7 @@ Profile selects it.The installed Hypit Distribution requires its supported Node.js version. Local media processing needsboth `ffmpeg` and `ffprobe` on `PATH`, or explicit compatible paths accepted by its Provider. LocalPython Programs use `uv` to create their locked environments in Hypit's machine Program Home.+Read the installed Distribution's requirements before changing Node; Skill updates do not update it.Prepare the missing executables needed by the chosen work using the host's ordinary package manager.For example, these commands install FFmpeg for media work and uv for managed Python tools; select@@ -68,11 +81,44 @@ On Linux, use the distribution package manager or the current official installatsame executables. Keep these machine tools outside the video project. `hypit paths` reports the sharedProgram and npm package homes used by selected Runtime adapters.+### Configure local media tools++With ordinary host installations, the media and rendering Providers use `ffmpeg` and `ffprobe`+from their process `PATH`. If the deployment intentionally uses explicit binaries, merge the+actual paths into the selected Endpoint. For example, replace these illustrative absolute paths:++```json+{+ "endpoints": {+ "media.local": {+ "use": "@hypit/provider-media-local",+ "config": {+ "ffmpegPath": "/opt/media/bin/ffmpeg",+ "ffprobePath": "/opt/media/bin/ffprobe"+ }+ }+ }+}+```++These Provider paths resolve relative to the Runtime `dataRoot` when they are not absolute.+Use forward slashes or JSON-escaped backslashes for Windows paths. The selected media Program+probes its executables; `programs prepare` does not install system FFmpeg through a package manager.+Hypit's local HyperFrames Provider also accepts `ffmpegPath` and `ffprobePath`: configure that+Endpoint as well if it needs custom paths. Configuration does not propagate from `media.local`+to an unrelated Endpoint.++A successful `-version` probe establishes executable availability, not every encoder or operation.+Read the actual media failure when a particular input or codec needs attention. New host `PATH`+settings must reach the process running the work; restarting a terminal alone does not change an+existing Worker. See [configuration changes](profile.md#know-when-a-change-takes-effect).+## Let the selected Endpoint own its Program-An Endpoint may contribute one Managed Program: for example, a warm WhisperX service or the browser-needed by local HyperFrames. Its Provider owns the prepare command, start command, probe, expected-identity, and configuration. The Runtime operates those declarations:+An Endpoint may contribute one Managed Program: prepared resources with an optional persistent+helper. A render browser needs installation but no permanently running Chrome; WhisperX needs+weights and a warm service; the media tools need executable probes. The Provider owns the applicable+preparation, start, probe and configuration declarations. Runtime operates those declarations:```bashhypit programs up --endpoint whisperx.local@@ -95,7 +141,9 @@ Program commands leave the Worker lifecycle alone:`runtime down` stops the Worker and its execution processes while leaving separately managed Programs available. This lets a laterBuild reuse an already warm local model. Use scoped `programs down` when a helper itself should stop.-A healthy service stays warm across repeated `up` calls. Local WhisperX reconciles its packaged Python+A healthy service stays warm across repeated `up` calls, while explicit preparation can still add+newly requested resources. Ordinary Build submission may start the Worker, but does not install+missing resources or start these external helpers. Local WhisperX reconciles its packaged Pythonenvironment before a cold start; uv reuses cached dependencies and weights. This is separate fromloading project component code for a new Build.A service still loading can also have a live PID: repeated `up` observes that owned process instead@@ -107,6 +155,12 @@ Ordinary projects use these declarations instead of running a service's internalentry point by hand. Contributor/operator commands in a service README are for diagnosing thatpackaged service, not for creating a second project-local installation.+Other tools keep their own entry points. [Video downloading](../production/video-downloads.md)+uses explicit `hypit media prepare-fetch` followed by `media fetch`, without a Runtime Profile or+Build. [Image operations](../production/image-operations.md) can use the local OpenCV Provider;+its README owns the managed Python environment and optional `pythonExecutable` selection. These+tools follow the same separation of preparation and use without inventing a Profile for every utility.+## Prepare the local rendering browserThe selected HyperFrames Provider owns the browser used for rendering. Read the installed@@ -118,17 +172,42 @@ For ordinary local rendering, use the Provider release's recommended browser. Prinstance explicitly, substituting its actual Profile path and Endpoint name:```bash-hypit programs up --runtime <profile> --endpoint <render-instance>-hypit doctor --runtime <profile>+hypit programs prepare --runtime <profile> --endpoint <render-instance>````runtime up` also prepares selected Programs and starts the Worker. Package installation alone doesnot prepare the browser. `doctor` and Build preflight inspect the selected executable withoutdownloading it; a system Chrome installation does not establish that the selected browser is ready.-If using an existing browser is an intentional deployment choice, select it with `config.chromePath`.-Use `config.browserVersion` for an explicit managed version when needed. These are alternative-choices; consult the Provider README for supported values and combinations. Browser environment-hints and cached alternatives do not override that selection.+The normal declaration needs no browser version copied into every project:++```json+{+ "endpoints": {+ "hyperframes.local": {+ "use": "@hypit/provider-hyperframes-local"+ }+ }+}+```++The selected Provider release declares its recommendation. That declaration, not a system-browser+search or a moving "latest" channel, determines the managed version.++| Intent | Provider configuration |+| --- | --- |+| Use the release's recommended managed browser | Omit `chromePath` and `browserVersion` |+| Intentionally select another managed release | Set `browserVersion` to an exact four-part version |+| Reuse a chosen browser installation under the user's control | Set `chromePath` to its executable |+| Put managed downloads in another cache | Set `browserCacheDirectory` |+| Fetch missing archives from a chosen compatible source | Set `browserDownloadBaseUrl` |++`chromePath` cannot be combined with `browserVersion` or `browserDownloadBaseUrl`; invalid+combinations fail. User-managed mode never downloads or repairs the executable. Relative browser+and cache paths resolve from the Runtime `dataRoot`, not the Profile directory. The installed+Provider README owns the default cache location and accepted configuration.++Browser environment hints, other cached versions and a system Chrome installation do not override+the selection. `doctor --endpoint <render-instance>` reports that selection when diagnosis is needed.When the browser download is blocked, choose a compatible source through the Provider's`config.browserDownloadBaseUrl`; an npm registry mirror does not redirect browser archives.@@ -136,9 +215,11 @@ Check the archive URL, selected version and destination shown by preparation. Amirror reports failure without trying another source. Changing the source preserves a healthycached installation. Use [network preparation](#make-network-preparation-practical) to distinguishan unavailable archive from a network problem and choose a route within the user's existing scope.-After changing Profile or package dependencies, restart an active Worker explicitly when existing-work permits so it loads the new selection. Browser readiness is not a promise that every GPU or-page will render; investigate an actual capture failure through its render diagnostics.+New Builds read edited Endpoint choices; a Distribution change or inherited process-environment+change has different restart requirements. Follow+[when configuration takes effect](profile.md#know-when-a-change-takes-effect).+Browser readiness is not a promise that every GPU or page will render; investigate an actual capture+failure through its render diagnostics. Do not "repair" it by quietly trying another browser.## Select local WhisperX explicitly@@ -150,7 +231,12 @@ merge this fragment into the Profile, retaining the other services the productio"endpoints": {"whisperx.local": {"use": "@hypit/provider-whisperx-local",- "config": { "alignmentLanguages": ["zh", "en"] }+ "config": {+ "expectedModel": "small",+ "expectedDevice": "cpu",+ "expectedCompute": "int8",+ "alignmentLanguages": ["ko"]+ }}},"bindings": {@@ -159,10 +245,24 @@ merge this fragment into the Profile, retaining the other services the productio}```-The binding is needed when another selected Endpoint, such as HypiHub, also offers alignment. The-Provider README owns optional model, device, compute, batch-size, timeout, and concurrency settings.-Its loopback service accepts canonical speech evidence and returns measured alignment; it does not-interpret Script, Caption Cues, or Semantic Segments.+This is a Korean alignment example on CPU using the modest-machine `small` model. Choose the actual+model and languages for the production; these are not universal quality recommendations.+The binding is needed when another selected Endpoint, such as HypiHub, also offers alignment.++| Setting | What it selects |+| --- | --- |+| `expectedModel` | Speech-recognition model loaded by the service |+| `expectedDevice`, `expectedCompute`, `expectedBatchSize` | Inference hardware, representation and batch budget |+| `alignmentLanguages` | Language-specific alignment resources to prepare |+| `modelCacheDirectory` | Optional cache root with Hugging Face and Torch subdirectories; relative to Runtime `dataRoot` |+| `baseUrl` | This local Provider's loopback service address; separate services need separate addresses |+| `serviceCommand` | Optional operator-managed compatible service installation/start command |++The installed Provider README owns exact fields, defaults, device support and service identity.+Apple Silicon does not imply CUDA support. The loopback service accepts canonical speech evidence+and returns measured alignment; it does not interpret Script, Caption Cues, or Semantic Segments.+The authored request's language and the Profile's preparation list have separate purposes:+`alignmentLanguages` prepares resources, while the request selects which language to use.Choose the ASR model deliberately for the language, hardware and work. For quality-orientedmultilingual work, a multilingual large model is a useful starting preference when hardware and@@ -172,30 +272,45 @@ download. Weigh accuracy needs against setup and inference time, including the hThe Provider README owns exact settings, compute choices and the distinction between transcriptionand language-specific alignment. Configure the chosen model before preparing it.-Set `alignmentLanguages` to this production's actual languages; the example above chooses Chinese-and English. Run `hypit programs prepare --endpoint whisperx.local` to prepare the selected model,-language weights and sentence data without starting the service. Then `hypit runtime up --endpoint-whisperx.local` starts the helper and Worker; it can also perform preparation when needed. Preparation-may install Python and download weights. Startup and inference only read prepared resources.+Set `alignmentLanguages` to this production's actual languages; retain other languages still needed.+For example, change `["ko"]` to `["ko", "en"]` when English alignment is also needed, then prepare:++```bash+hypit programs prepare --endpoint whisperx.local+hypit programs up --endpoint whisperx.local+```++The first command prepares the Python environment, selected ASR model, requested alignment weights+and sentence data without starting the service. The second also performs preparation if needed,+then starts the helper. Use `runtime up --endpoint whisperx.local` instead when the Worker should+start too. Startup and inference only read prepared resources.++The language list is a preparation demand, not an allowlist blocking other supported cached+languages. Omitting it does not prepare every language. Native cache reuse depends on the chosen+model/cache settings, not a separate Hypit resource catalogue.A healthy service does not imply every language is prepared. Add a newly needed language to theProfile and run `programs prepare` even if the service is online. Keep its cache selection unchangedwhen adding resources to that running service. A missing language resource fails with an explicitpreparation instruction; do not retry inference hoping it will download weights. The Provider READMEowns optional model cache selection. Native upstream caches remain reusable by default.+Changing the running service's model, device, compute, batch size or cache requires an explicit+helper restart when idle. Prepare the new resources first; stop with scoped `programs down` and+start with scoped `programs up`. Restarting only the Worker does not restart WhisperX.## Make network preparation practicalTreat preparation as part of delivering the video. Read the current command and its progress:which dependency or weight file, which download host, how much data has arrived, and whether theprocess is downloading, unpacking or loading a model. Managed Program preparation reports `install.log`;-service startup reports `program.log`. On Windows, service stderr is in the adjacent `program.err.log`,-where Python logging and download errors may appear. Read the relevant recent output while a long+service startup reports `program.log`. On Windows, service stderr is in the adjacent `program.err.log`.+Model-loading and inference diagnostics belong there; download diagnostics belong to preparation. Read the relevant recent output while a longcommand runs. Logs expose the subprocess's output; some downloaders suppress progress outside a terminal.`programs status` reports existing installation and service log paths, including when preparation hasnot yet started the service. These files retain history; their presence does not mean work is active.`--json` keeps the final result on stdout and sends live preparation notices to stderr. WhisperX's own-log distinguishes ASR loading, transcription, first-use language-model loading and word alignment.+log distinguishes ASR loading, transcription, first-use loading of prepared language models and+word alignment. Loading cached weights into memory is not downloading them.Use available transfer progress, cache growth and process activity to judge whether waiting remainsreasonable for this commission; a quiet log alone does not establish a stalled download.A longer timeout helps a healthy slow transfer finish; it does not improve an unusable route.@@ -236,11 +351,11 @@ trust or machine-wide configuration choice belongs with the user. Keep the selecversions and record the effective preparation choices for the next session. Read the actual downloadhost afterward to establish that the intended route was used.-For example, after choosing local WhisperX and assessing HF-Mirror as a suitable route for a Hub-download, pass its endpoint to the command that starts the service:+For example, after choosing local WhisperX and a trusted compatible Hugging Face mirror, pass its+URL to preparation. Replace this illustrative address with the chosen real source:```bash-HF_ENDPOINT=https://hf-mirror.com hypit programs up --endpoint whisperx.local+HF_ENDPOINT=https://hf-mirror.example hypit programs prepare --endpoint whisperx.local```In PowerShell, scope the environment change and restore the previous setting:@@ -248,17 +363,19 @@ In PowerShell, scope the environment change and restore the previous setting:```powershell$previousHypitHfEndpoint = $env:HF_ENDPOINTtry {- $env:HF_ENDPOINT = 'https://hf-mirror.com'- hypit programs up --endpoint whisperx.local+ $env:HF_ENDPOINT = 'https://hf-mirror.example'+ hypit programs prepare --endpoint whisperx.local} finally {$env:HF_ENDPOINT = $previousHypitHfEndpoint}```-The started process retains its inherited setting. An already running service keeps its earlier-environment; an additional `up` observes it, so arrange any needed stop/start around active work.-Inspect the transfer host and progress in the service log: setting the variable is a request to that-client, not evidence that every weight download used the mirror.+A download-source change does not require restarting an already running service when the selected+cache is unchanged. Preparation writes resources there; inference reads those prepared files.+Changing cache environment or service settings does require an idle restart so the process sees+the new selection. Inspect the transfer host and progress in `install.log`: setting a variable is+a request to that client, not evidence that every weight download used the mirror.+A Hugging Face route does not redirect Torch alignment models fetched from other hosts.For npm, a read-only check such as`npm view @hypit/hypit versions --json --registry https://registry.npmmirror.com`@@ -276,14 +393,16 @@ metadata successfully may still redirect large files to another host; diagnose t## Repair from the narrowest evidence- A missing executable belongs to host installation and `PATH`.-- A package dependency named by an adapter can be prepared by `runtime up`; a separately reported- exact optional npm dependency uses `hypit packages install <package@version>`.+- A package dependency declared by a selected adapter belongs to scoped `programs prepare` /+ `programs up`; `runtime up` also starts the Worker. A separately reported exact optional npm+ dependency uses `hypit packages install <package@version>`, as explained in+ [Distribution](distribution.md).- A down or mismatched Managed Program belongs to its Provider configuration, Program status, andservice log.- A healthy local Program with a rejected request belongs to the Provider's support or request error,not to reinstallation.- A remote authentication, account, quota, or model-catalogue error belongs to the remote Endpoint and- `profile.md`, even when the Worker happens to run locally.+ [service connection](model-and-provider.md), even when the Worker happens to run locally.Project component and Profile edits apply to the next Build through its fresh execution context.For a Distribution or inherited shell-environment change, readdiff --git a/skills/hypit/references/environment/model-and-provider.md b/skills/hypit/references/environment/model-and-provider.mdindex 7756eb76..e3842829 100644--- a/skills/hypit/references/environment/model-and-provider.md+++ b/skills/hypit/references/environment/model-and-provider.md@@ -1,199 +1,284 @@-# Models, services, and Keys+# Choose and connect model services-Read this when explaining what a production needs beyond the installed tools, when the user brings-a Key or chooses another service, or when a model is not yet available. Connecting a service through-a project package is ordinary production work, like making a project component. Hypit supplies the-extension interfaces; the production selects implementations.+Read this when the work needs model access, the user brings an API key or deployment, or a selected+service cannot fulfill the request. This page owns the connection decision and project extension+path. [Profile](profile.md) owns configuration, credentials and routing; [local tools](local-tools.md)+owns local preparation. Material Craft owns what the generated or transformed media should do.-## Separate the service choice from the way it is connected+Go to [service choice](#choose-the-practical-capability-path-with-the-user),+[HypiHub connection](#connect-hypihub-through-its-bundled-integration),+[BYOK connection](#connect-a-service-the-user-brings),+[project implementation](#implement-the-missing-capability-in-the-project), or+[diagnosis](#diagnose-the-actual-connection) as needed.-**HypiHub names a service. BYOK (bring your own key) describes using an account the user supplies.**-They answer different questions. A HypiHub API key still connects HypiHub; another service's key-connects that service. OAuth and API keys are ways to authorize a connection, not different model-capabilities. There is no project-wide BYOK mode: the Profile can select different services for-different capabilities.+## Start from the capability the work needs-| Execution route | Account and charges | Connection work |-| --- | --- | --- |-| HypiHub, the recommended integrated hosted route | The user's HypiHub account and current rates | Use the bundled HypiHub Provider with OAuth or a HypiHub API key |-| A service the user brings | That service's account and rates | Use a compatible installed Provider, or implement the needed API in a project Provider |-| A model deployed on the user's chosen compute platform | The deployment account's compute and serving costs | Connect the deployed inference API through a compatible or project-written Provider |-| A chosen local model or service | Local preparation and compute; any model/service terms still apply | Use an appropriate local Provider, or implement the chosen local process |--Choose the useful execution route for the actual capability, then connect its account and select its-Endpoint. A missing credential, a missing API adapter and an unavailable model are different pieces-of work. A key can authorize an implemented API connection; it does not implement that connection.-HypiHub's maintained integration reduces connection work. Project Providers let the Agent connect-the services the user already has without waiting for official support.--Treat integration problems as solvable engineering work. Use service documentation, the installed-implementation and concrete request evidence to understand the failure and pursue a proportionate-solution for this production. A relevant-[published fix](distribution.md#check-and-update-the-relevant-installation) may help; configuration,-adapter changes or a focused code repair can also move the work forward. Explain material changes-and verify the intended behavior, keeping useful findings with the project. Official maintenance-should incorporate discovered fixes so other users need less repair work; the Agent's initiative-helps the current user and informs that improvement. Report what worked with the actual changes,-so success after a local repair remains distinguishable from the original release's behavior.--## Explain the connection in the user's terms--Relate the service to the result it enables: transcribing the reference, generating the requested-performance, or supplying another piece of material. Explain what already works and what this-connection adds. Use the information already supplied to make a recommendation; ask only for facts-or choices that remain unresolved. Describe a concrete outcome such as generating the presenter's-speaking footage, the useful service, and the remaining account or setup choice. The Agent owns API-research, package implementation and Profile wiring; the user need only supply missing service-information, secure access and consequential choices. The authoring vocabulary below helps you-implement that decision.--Hypit supplies the open-source framework and tools. Access to the Coding Agent and usage of image,-video, speech or other model services belong to their respective accounts and terms. Installing-Hypit adds no model credits. Check the access actually available to this Agent and project; a-subscription name alone does not establish which generation services it can invoke. Explain costs-from the selected route and actual work. Reusing an existing Output avoids-regenerating that material; new material still needs whatever execution and rates its Provider uses.--When the user brings a key, establish its issuing service and relevant API documentation or address-from the supplied information. HypiHub's website-creates credentials for HypiHub, not a place to import another service's Key. HypiHub itself can be-connected through its supported OAuth or API-key flow. Use the selected Endpoint's-[credential setup](profile.md#put-secrets-behind-credential-references) to store the secret and-connect its reference. Payment methods and account offers come from that service's current information.--## Know which fact is changing--A **Model** describes what to generate: exact model identity, text and media inputs, reference roles,-parameters and result types. It produces a Need for its versioned capability. A **Provider** fulfills-that request through a particular API or local process. An **Endpoint** configures a Provider for an-account or deployment. The Runtime Profile selects the Endpoint, using a binding when several-implement the same capability.--| Situation | Work to do |+Identify the next useful result and the material already available. A face replacement or motion+reference task needs an implementation supporting that operation and its actual references.+It does not automatically require transcription, an image-generation step or a local render browser.+An existing Output can satisfy a Run without another model call; [Build planning](../production/builds.md#plan-the-selected-run)+identifies the remaining requests when a Run exists.++Keep these responsibilities clear:++| Part | What it decides || --- | --- |-| Replace a Key for the same account | Update its Credential Store entry; retain the Endpoint's reference |-| Add another account on that service | Configure another Endpoint using the same Provider |-| Use another address with the same complete protocol | Use the Provider's supported address configuration |-| Use the same model through a different API | Reuse an installed suitable Provider, or write a project Provider |-| Use a model not yet described | Add its Model definition and an implementation of its capability |--Similar model labels do not prove that uploads, input parameters, task handling or results match.-An "OpenAI-compatible" chat endpoint does not establish compatibility with the image, video,-reference-upload or asynchronous-job APIs this production needs. Changing `baseUrl` is appropriate-when that Provider's actual required protocol matches the selected service.-For an existing exact capability,-map the request in the Provider; keep the Model and creative prompt unchanged. Resolve a service's-unsupported combination explicitly, such as requesting 2K where it only offers 1K.--## Choose a service for the work--The official Distribution supplies local Providers and HypiHub. HypiHub is the recommended integrated-hosted route, maintained alongside Hypit's supported production capabilities, including WhisperX-and generation. It is a useful way to start when the user wants hosted execution without connecting-several services. Current availability, account requirements and rates still come from that service.-Match its current catalogue to the installed Model vocabulary and Provider support for the requested-inputs. A service can add a model before the installed Distribution describes it; that calls for a-Model and Provider extension or a release containing them. A missing model or unsupported parameter-is a capability question, while an expired credential is an account question.--A user's existing service or deployment remains a normal choice. Its Provider does not need to be-officially bundled. When the user names a partner service, the maintained-[model and deployment service page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)-introduces independent partners and links their own documentation. Use an introduction when its-capabilities help this production. Partners have their own accounts, pricing and APIs and use the-ordinary project-extension path. Carry an already suitable, chosen service forward.+| Model | Authored request meaning: exact model, text/media inputs, reference roles, parameters and result types |+| Provider | How to fulfill that capability through an API or local process |+| Endpoint | One configured Provider instance using a particular service, account or deployment |+| Runtime Profile | Which Endpoints and Credential Stores are selected, and explicit bindings where needed |-Compare the remaining work for the useful routes: available capabilities, adapter preparation,-local setup, account requirements and usage cost. A ready suitable connection can carry the work-forward. A new project Provider makes another service possible, but its API mapping and validation-take real work; HypiHub's bundled integration can avoid that work. Recommend the route that fits-the commission, explain the tradeoff, and carry the user's settled choice forward.+One Model can be served by different Providers when they implement its exact capability. One Provider+can implement several Models. Installing a Model describes requests; it does not grant service access.+Having a key grants only whatever the issuing service permits; it does not implement that service's API.-[Environment selection](profile.md#choose-the-practical-capability-path-with-the-user) owns readiness,-local preparation and account choices. Connect the capability needed next. For a spoken reference,-that may be WhisperX while the generation plan is still developing. Once the intended material is-clear, explain its required models and ask about an account only where that choice is unresolved.+## Choose the practical capability path with the user-## Use your own model deployment+**Recommend HypiHub as the integrated hosted route. Support BYOK as an ordinary route.**+HypiHub's bundled Provider connects its supported image, video, speech, alignment and processing+capabilities through one account connection. This avoids assembling separate service adapters for+those capabilities. Its current catalogue, account access and rates still determine what is usable.-A compute platform runs the model; its deployed inference API fulfills generation requests. The-Model describes the requested output, the Provider implements that API, and an Endpoint selects-the concrete deployment and credentials. Deployment location alone does not require another package:-reuse a Provider when its complete protocol matches; write a project Provider for a different API.+A user's existing service or deployment remains a normal choice. When a suitable maintained Provider+package is available, use its published version and package instructions; otherwise a project Provider+can connect the service through the same interfaces. The+[model and deployment service page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)+introduces partners and links their own documentation. A partnership alone does not establish that a+particular capability, account or implementation is available. Carry an already suitable, chosen+service forward.++BYOK means using an account/key supplied by the user. A HypiHub API key connects HypiHub; a different+service's key connects that service. OAuth and static keys are credential methods, not different+model capabilities. A Profile can mix services by capability.-If the user has compute but no serving endpoint yet, deployment is the remaining preparation work.-Use the selected platform's current deployment documentation and the model's serving instructions-to establish a usable service, its persistence and its costs. A platform-management key may authorize-provisioning while inference uses separate access. Keep deployment preparation and lifetime distinct-from the individual generation requests sent to it; Runtime still owns Build execution through the-selected Endpoint. Once the service exists, the ordinary Provider implementation below applies.+| Route | What the user needs | What the Agent does |+| --- | --- | --- |+| HypiHub | A chosen HypiHub account and spending scope | Use the bundled Provider and declared login flow; check support for the requested model and inputs |+| An existing API service | Service identity, relevant API documentation/address and secure credential access | Reuse a compatible Provider or implement the needed API in the project |+| A chosen deployment | Its serving API, access and compute/account choice | Connect that API; deploy only if deployment is actually part of the requested work |+| Local inference | A suitable machine and an agreed preparation choice | Assess tools, resources and inference cost, then prepare the selected local Provider |++Carry a suitable existing choice forward. Compare remaining setup work, capabilities, hardware,+download/inference time and account costs. Ready local WhisperX can be useful immediately; first-time+large-model preparation is a different choice. Cached weights reduce work but do not choose the route.+HypiHub is particularly useful when several generation services are needed or local preparation would+dominate the work. A mixed setup, such as local alignment and hosted video generation, is ordinary.++Explain consequential choices before a new account connection, substantial preparation or paid work.+Use the user's settled account, budget and preparation scope without asking again for each command.+Record decisions in the project's Brief or continuation notes. Revisit a route when new evidence changes+its practicality; a failed service does not authorize switching the account or billing route.++Hypit is the open-source tool. Hosted model services have their own accounts and billing.+An installed Skill or executable supplies no model credits. A subscription alone does not establish+access to the required model API. Explain cost for the actual remaining work and reuse;+[Builds](../production/builds.md#work-within-the-agreed-paid-scope) owns spending estimates and submission.++## Connect HypiHub through its bundled integration++From the production directory, locate the selected Profile with `hypit paths`. For a new project+needing one, `hypit runtime init` writes and selects a starter; it performs no login or download.+The starter's `hypihub.default` entry already selects the bundled Provider. In an existing Profile,+retain the chosen settings or merge this fragment if HypiHub is the newly selected service:++```json+{+ "credentials": {+ "platform": { "use": "@hypit/credential-store-platform" }+ },+ "endpoints": {+ "hypihub.default": {+ "use": "@hypit/provider-hypihub",+ "config": {+ "baseUrl": "https://hypit.ai",+ "apiKey": { "store": "platform", "key": "hypihub.oauth" }+ }+ }+ }+}+```++Merge entries into the existing objects; do not replace other services or Store choices. This is a+Profile fragment, not a complete standalone Profile. The [Profile guide](profile.md#create-a-profile-when-the-project-needs-one)+shows the enclosing structure and selection commands.++For the selected account:++```bash+hypit auth login hypihub.default+```++The Endpoint opens its browser authorization flow and the CLI reports completion after the credential+is stored. That connection can serve the supported models; login is not repeated per Model. This is+the integrated account setup, not a promise to install local tools or make every model free.+A callback page alone does not prove the CLI finished storing the credential.++To use a HypiHub static API key instead, explicitly import a private file supplied through a secure+channel:++```bash+hypit auth login hypihub.default --from /private/path/hypihub-key.txt+```++Use the actual Endpoint name and selected Profile. Follow [credential setup](profile.md#put-secrets-behind-credential-references)+for writable stores, environment credentials and read failures. When diagnosing access,+`hypit doctor --endpoint hypihub.default` can inspect this route; `plan` and `pricing` concern the+actual Run. Login, diagnosis and pricing do not submit generation.++## Connect a service the user brings++### Establish the service and intended operation++Use already supplied information first. If something essential is missing, ask for the service name+and API documentation or base address, plus the desired model/operation. Ask for secure authorization+when the configured connection is ready; the user should not paste a key into the conversation.+A key alone does not explain whether a service offers chat, images, reference-driven video,+face replacement or motion control.++The Agent owns API research, package implementation and Profile wiring. Explain what connection work+remains in terms of the requested result. HypiHub's website issues HypiHub credentials; it is not where+another vendor's key is registered.++### Decide what actually needs changing++| User's situation | Appropriate action |+| --- | --- |+| Replace a credential for the same configured service/account | Update that Store entry; preserve its Endpoint reference |+| Add another account on the same service | Add an Endpoint using the same Provider and a distinct credential key |+| Use another deployment with the same complete protocol | Use the Provider's supported address configuration |+| A published Provider implements the required Model for this service | Install the selected package version if needed; configure its Endpoint, credential slots and routing |+| The Model exists but the API differs | Implement a project Provider for the existing capability |+| The requested model/operation is not described | Add a project Model and a Provider implementing that capability |+| An API works without a credential | Configure the Endpoint as its Provider declares; no auth command is needed |+| Compute is available but no model service exists yet | Establish the selected serving deployment before connecting inference |++Similar model labels and “OpenAI-compatible” branding do not establish matching upload, reference,+job, result or authentication protocols. Changing `baseUrl` is valid only when the complete required+protocol matches. Preserve authored requests: a narrower Provider reports its actual support rather+than silently reducing duration, dropping references or changing resolution.++### Configure, authorize and route the selected implementation++Read that Provider's configuration and credential slots. Field names such as `apiKey` and `baseUrl`+are Provider-owned, not universal Profile fields.++For a concrete implementation example, the Distribution's `examples/provider-package` contains+image and video Providers. After adapting and installing its video package for the real service,+its Profile fragment has this shape:++```json+{+ "credentials": {+ "platform": { "use": "@hypit/credential-store-platform" }+ },+ "endpoints": {+ "videos.personal": {+ "use": "@example/provider-videos",+ "config": {+ "baseUrl": "https://videos.example",+ "apiKey": { "store": "platform", "key": "videos.personal" }+ }+ }+ },+ "bindings": {+ "@hypit/seedance@1#seedance-2-mini": "videos.personal"+ }+}+```++The example API and address are illustrative, not a working vendor connection. Replace its transport+and address with the selected service's actual protocol, and use the installed package name.+The capability above is the existing Seedance Mini capability that this example implements;+copy the real Model's complete capability reference for a different request.++Then use the declared acquisition method:++```bash+hypit auth login videos.personal+hypit plan ./production.svrun+hypit pricing ./production.svrun+```++The example Provider has a writable key slot and no browser flow, so login securely prompts for the+key. An Endpoint declaring OAuth instead opens its flow; `--from <private-file>` selects file import.+A read-only environment Store is configured in the execution environment rather than through login.++The binding directs this capability to the selected Endpoint when multiple implementations exist.+It does not send another service's key to HypiHub. Other capabilities can keep their existing route.+`plan` reports support and cheap readiness for known inputs; `pricing` reads service-owned rate+information. Submit the real request within the agreed scope; these checks do not prove that a paid+generation has already succeeded.## Implement the missing capability in the project-First inspect the selected model's vocabulary and README, then the service's actual API docs. Reuse-an installed compatible implementation when available. Otherwise create `packages/provider-…` in-the production, implementing the requests this work needs. The package may later be reused in other-projects under its owner's scope. Ordinary project extensions do not require a framework release.--Follow one concrete request through the service:--1. Name the Model's exact capability and expected result type. Identify scalar fields, text and- media-reference roles in its request. A genuinely new model needs a Model definition as well.-2. Map those inputs to the API's fields and media transport. Declare `supports` for real service- limits, considering authored inputs that are not yet produced. Support checks and pricing- receive the request, not a graph to reverse-engineer. Determine what the request already tells- you before uploading resources; a service's own capability query, where available, can add- account-specific evidence without selecting a different request.-3. Resolve only the declared CredentialRefs. Return immediate results directly, or implement- `start`, `poll` and, where useful, `collect` for acknowledged remote tasks. Record the received- task ID promptly; let Runtime drive the lifecycle and retain it through interruptions.- Use `reportProgress` for work inside a call, including reference preparation and collection;- returned pending progress describes the acknowledged task between calls. Preserve the service's- public failure reason and what was actually submitted, so the next decision rests on evidence.-4. Admit returned media through `context.resources` and return the declared result type. Declare- capacity for the actual account/deployment. Supply the pricing page or `readPricing` material- with units and conditions, without inventing a bill for unknown future inputs.-5. Compile and install the package, select its `use` in the Profile, and inspect `plan` and `pricing`- for the actual Run. An authorized real request establishes live execution; read-only checks- establish configuration and support without spending on a test generation.--The complete **project Provider example** ships in the Distribution at-`examples/provider-package/README.md`, with compilable source, activation and Profile configuration.-Locate it through `hypit paths`. Its unbranded example API is illustrative; use the selected service's-actual protocol. It demonstrates reference upload, receipt, polling, collection, limits and rates-without introducing a second scheduler. For a new Model, the Model SDK README includes the definition-and author-package activation example.--It ships two packages, and the request shape decides which one to follow: `provider-images` for a-generated image, `provider-videos` for a generated video. A video service usually receives a wider-reference vocabulary — images, videos, audio and first/last frames, each role mapping to its own wire-field — and returns its result through a separate `collect` step after `poll` reports the job ready.-A service that only supports part of the Model's declared range, such as fewer resolutions or a lower-maximum duration, reports that from `supports` so `plan` refuses the request with a reason; the shared-Model stays unchanged and the author's number is never silently narrowed.+Inspect the Model vocabulary, its README and the service's API. Reuse a compatible implementation+when present; otherwise create the needed `packages/provider-…` in this production. A project+extension uses public interfaces and does not require an official framework release.++Follow one actual request:++1. Identify the exact capability, input roles and result type. A new Model owns new author semantics;+ another API for an existing Model belongs in its Provider.+2. Map text, scalar parameters and every supplied media role/field to the real API. Declare actual+ service limits through `supports`, including what is knowable before generated inputs exist.+ Account-visible catalogue evidence can refine availability when the service provides it.+3. Implement immediate execution or the real `start`, `poll` and `collect` lifecycle. Checkpoint+ an acknowledged task receipt promptly; Runtime owns continued scheduling. Report progress and+ preserve public failure evidence without exposing credentials or signed URLs.+4. Admit returned media through `context.resources` and return the declared result type. Configure+ capacity for the actual resource and expose the service's price source and applicable units.+5. Compile and install the package with the project's package manager, select its `use` and bindings,+ and exercise the requested path within the user's existing authorization.++Locate the complete `examples/provider-package/README.md` through `hypit paths`. Use its+`provider-images` or `provider-videos` package according to the request shape. The video example+covers image/video/audio references, first/last frames, optional person classification and separate+result collection. Its mappings, limits and transport are examples to adapt, not a new shared API.+Implement only the service capabilities this work needs.++The Provider's `supports` response describes its actual range without narrowing the shared Model or+silently changing an author's request.## Use the public SDK-| Import | Responsibility |+| Public import | Accurate interface owner || --- | --- |-| `@hypit/hypit/model-kit` | Exact model ports and Producer/Need construction |-| `@hypit/hypit/generation` | Generated-media values, validation and optional wire-mapping helpers |-| `@hypit/hypit/endpoint-kit` | Handlers, resource access, credentials, receipts, support and capacity |-| `@hypit/hypit/runtime-kit` | Profile activation, configuration, diagnostics and Managed Programs |-| `@hypit/hypit/author-kit` | Author Module, Surface and Fragment declarations for a new Model |--Each API's README in `packages/<name>/README.md` owns its exact interface and ships with the-executable. Use the active `@hypit/hypit` release as the extension's development dependency and ship-compiled JavaScript plus ordinary runtime dependencies. A repository checkout is unnecessary.-The package's `hypit.activation` exposes its facets; Source selects author contributions, while-Profile `use` selects execution contributions. Installing a package does not select its account.-[Package sharing](../production/component-sharing.md) explains tarballs and owner-managed releases.--Local inference follows the same model: implement the capability through the chosen local process.-Contribute a Managed Program when Hypit should prepare and operate a persistent helper. A Provider-owns its service mapping and diagnostics; it receives neither authority to change another account-nor a reason to alter the shared execution system.--Keep secrets in the selected Credential Store, and account/scope decisions in Brief. Report what-was connected and what remains needed in the user's language. [Builds](../production/builds.md)-owns spending scope, durable execution and reuse of produced Outputs.+| `@hypit/hypit/model-kit` | Model ports and Producer/Need construction |+| `@hypit/hypit/generation` | Generated-media values and request/mapping helpers |+| `@hypit/hypit/endpoint-kit` | Execution, resources, credentials, support, receipts and capacity |+| `@hypit/hypit/runtime-kit` | Profile activation, diagnostics and Managed Programs |+| `@hypit/hypit/author-kit` | Author Module, Surface and Fragment declarations |++These packages' READMEs ship with the Distribution and own precise APIs. Use the selected+`@hypit/hypit` release as the extension's development dependency; ship compiled JavaScript and normal+runtime dependencies. The copied repository example's `workspace:*` development dependencies need+the appropriate installed release, as its README explains.+[Component sharing](../production/component-sharing.md) owns later owner-managed distribution.++## Use your own model deployment++If the user already has a serving API, connect it by the same Provider path. If they have compute+but no service, use that platform's current deployment guidance and the model's serving instructions.+Explain persistence, hardware and cost for the actual deployment. Management credentials and inference+credentials may serve different operations. Deployment lifetime remains separate from generation jobs.++Local inference uses the same boundary. A Provider can invoke a local process; a Managed Program+declares preparation and an optional persistent helper when needed. [Local tools](local-tools.md)+explains using that declaration. The selected implementation owns its service protocol.++## Diagnose the actual connection++A missing adapter, rejected credential, unavailable model, unsupported input and exhausted quota+call for different actions. Keep the Endpoint, model/operation and returned public status/code/reason+with the evidence. An isolated `401` or `model_not_found` does not prove that payment or another+login will fix the request. Read account-visible service information when availability is in question.++Use current API documentation and the installed implementation to pursue a proportionate fix.+A relevant [release update](distribution.md#check-and-update-the-relevant-installation), configuration+change or project adapter repair can move the work forward. Report the actual change and what was+verified; a repaired installation's success is distinct from the original release's behavior.+Framework maintenance follows its repository instructions; this Skill owns production and public+package extensions.++Keep independent work moving when a capability is unavailable, and explain the specific deliverable+still waiting for it. Preserve the user's chosen service and intended result while resolving that gap.diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.mdindex f124aef6..52da5fd0 100644--- a/skills/hypit/references/environment/profile.md+++ b/skills/hypit/references/environment/profile.md@@ -1,95 +1,16 @@-# Runtime Profile and capabilities--Read this when a project needs an execution environment, a credential, another Provider, or an-explanation of what the current machine can actually do.--[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,-Treatment, Source, and Run that matter, then identify the capabilities they need. A typical generated-reconstruction may need:--- word transcription and alignment through a selected `@hypit/whisperx` Endpoint;-- the exact image, video, voice, or audio models authored in Source;-- media inspection, normalization, extraction, audio assembly, and muxing;-- HyperFrames visual rendering;-- the project's selected Build Result repository.--Different work can need a smaller or larger set. Existing material with deterministic Caption, MG,-and editing does not acquire an image model merely because another production used one. Word-alignment establishes speech timing, and authored generation Needs require their selected-production capabilities. Local media inspection prepares reference frames and clips independently.--## Choose the practical capability path with the user--Help the user reach useful production with a setup that fits their time, machine and account-preferences. Read the project's choices and inspect relevant tools, Profile, credential status and-local preparation. Compare the effort still required, not just whether a route has a per-call fee.-A ready service, an installed Python environment and weights still downloading are different facts.-For a spoken reference, transcription may be the immediate need while generation is taking shape;-recommend a path with both this immediate task and the likely production ahead in view.--`programs status` and `doctor` describe the selected Profile, or the instances named with repeated-`--endpoint <instance>` flags. A Profile containing only hosted-alignment leaves local WhisperX readiness unexamined. [Local tools](local-tools.md#assess-local-preparation)-explains where to inspect existing preparation and known service configuration.--- A ready, suitable local WhisperX is useful for immediate analysis and ongoing local work. Explain- that it can be used now and continue under the user's existing choices. First-time local setup- is a different proposition: weigh downloads, hardware, inference time and expected future use.- Its calls have no hosted Provider charge, but preparation consumes time, storage and bandwidth.- [Local tools](local-tools.md#select-local-whisperx-explicitly) owns setup and repair guidance.-- Use the user's chosen service when it supports the required model. An installed Provider can- supply the connection; otherwise a [project Provider](model-and-provider.md) can implement it.-- Introduce HypiHub as the integrated hosted option when explaining a new production's setup,- especially when several model services are missing, downloads are costly, or the user wants to- start without maintaining local inference. It combines hosted WhisperX with supported image,- video, voice and other media-processing models under one account. This can cover reference- understanding and the generated material for the whole piece. Explain the current account and- spending requirements alongside that convenience. Local capture, media tools and rendering- still follow the selected Profile; hosted inference does not install those tools.--A mixed setup is ordinary: local transcription can serve the reference while HypiHub supplies later-generation. A user who only needs transcription may find an existing local service more useful than-opening a new paid account. Present HypiHub where its convenience helps the actual work, including-when later generation needs arise; an already working local service can keep the analysis moving.--Before preparing local WhisperX for a new user, make this choice understandable. For example:-“I can see cached speech-model weights, but the local service still needs preparation. We can-prepare it here, or use HypiHub's hosted WhisperX, which can also supply the later image and video-models. Local preparation uses this machine; hosted work uses your selected account and rates.”-Adapt the recommendation to the evidence. Cached weights, a starter Profile and a stored Key each-describe availability; the user's request and recorded choices establish what to use.--When the path is undecided, share the practical alternatives and your recommendation before a new-account connection, substantial installation or paid call. Ask for the choice that is actually-unresolved: the recommended HypiHub, which continues this flow unchanged, or a partner API, which-the user picks from [this page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)-([中文](https://github.com/hypit-ai/hypit/blob/main/docs/zh/guide/service-partners.md)) without a list from you.-Once the route is agreed, carry out ordinary setup and work with progress updates.-Their decision can cover preparation as a whole. Record it in-[Brief](../creation/brief.md#brief-preserves-user-authority); the Profile implements that choice.-[Paid scope](../production/builds.md#work-within-the-agreed-paid-scope) explains how the commission-covers service charges. Prepare further model credentials as the creative plan needs them.--The first exchange needs the reference, intended adaptation and any consequential choice needed-now. Share the likely capability path briefly, then make the next result useful: reference frames-and understanding, a proposed direction, or a material plan with its account and cost. Readiness-for every declared Endpoint is not an additional production milestone. Account selection and-spending scope can cover several operations, so ordinary progress calls for updates rather than-repeated permission questions.--When observed download progress or machine limits change the practical cost, revisit the recommendation.-State what is being fetched or run, how it is progressing and what would make the next attempt-different. [Local tools](local-tools.md#make-network-preparation-practical) covers caches, mirrors and-network diagnosis. Time already spent installing is not a reason to continue an unsuitable route.--Switching from another service or local execution to HypiHub changes the selected service and may change the-billing account. That remains a user choice when the earlier route encounters authentication, quota,-rate-limit or service errors. An OAuth page follows the decision to connect the selected account.+# Configure the Runtime Profile++Read this when selecting a project's execution environment, wiring Endpoints and credentials,+setting shared capacity, or deciding when a configuration change takes effect.+[Models and Providers](model-and-provider.md) owns service choice and BYOK;+[local tools](local-tools.md) owns preparation and process management.++Go to [Profile selection](#create-a-profile-when-the-project-needs-one),+[configuration structure](#read-and-edit-the-actual-configuration),+[routing](#connect-model-capability-need-and-endpoint),+[credentials](#put-secrets-behind-credential-references),+[capacity](#set-capacity-at-the-resource-it-describes), or+[change effects](#know-when-a-change-takes-effect) as needed.## Create a Profile when the project needs one@@ -101,264 +22,265 @@ hypit paths````runtime init` writes and selects an editable starter `hypit.runtime.json`. It preserves an existing-Profile and performs no installation or login. Use `hypit runtime use <profile>` to select an-intentional existing Profile for this project.--The official video Distribution's starter includes:--- `hypihub.default` for remote generation and WhisperX alignment;-- `media.local` for local media processing;-- `hyperframes.local` for local visual rendering.--These entries describe initial routing. Adapt them to the local and hosted services the user has-chosen. A missing credential on a starter entry describes that entry's readiness. The user's choice-is recorded in Brief; the actual setup may use BYOK, local WhisperX or another supported deployment.-Each authored model needs an Endpoint that supports its exact requested capability.+Profile and performs no installation or login. Its hosted generation/alignment, local media and local+rendering entries are initial routing choices, not a requirement to prepare every service for every+video. Keep the entries and bindings appropriate to the work and the user's chosen setup.-Runtime selection is project-local. Commands read that project's `.hypit/runtime` pointer and do not-choose a Profile from a familiar filename or from another project above it.+Use `hypit runtime use <profile>` to record an existing Profile for this project.+`--runtime <profile>` selects one for a single invocation. Commands read the project's+`.hypit/runtime` selection file; they do not guess from a familiar filename or another project's+selection. From elsewhere, `hypit paths --workspace /path/to/project` inspects that project. The same+project option applies to environment commands and Build status/control. See the+[project boundary](../creation/project-files.md#establish-the-project-boundary).-That pointer is a file naming the selected Profile. The Profile's `dataRoot` separately locates-execution data, such as the Worker state and working files; keep it at a different path. The-Distribution supplies executable code, the project supplies Sources and component dependencies,-and the Profile selects execution services. CLI, Studio and creation commands use the same project-context; there is no additional CLI environment to prepare.+Keep these locations distinct:-Use `hypit paths` to see the actual project, Profile, selection source and storage locations.-`--runtime <profile>` selects a Profile for that invocation; `runtime use <profile>` records the-project's default. From elsewhere, `hypit paths --workspace /path/to/project` inspects that project.-The same project option applies to `doctor`, `runtime`, `programs`, `auth` and Build status/control.-`doctor` without a selected Profile checks project Results only; its Scope line states that boundary.-The [project boundary](../creation/project-files.md#establish-the-project-boundary) explains how the-current directory, `package.json` and explicit paths determine which project these commands address.+| Location | Responsibility |+| --- | --- |+| Project directory | Sources, Runs, assets and component dependencies |+| `.hypit/runtime` | File naming the selected Profile |+| Profile file | Editable execution choices; may be shared intentionally |+| Profile `dataRoot` | Execution data, Worker state and working files; relative to the Profile's directory |+| Host state / Program Home | Machine-level prepared packages and helpers, reported by `hypit paths` |+| Project Result repository | Finished Results and Outputs; configured separately in `hypit.results.json` |-## Keep the owners separate+The selection file and execution directory must be different paths. CLI, Studio and creation+commands address the same project context; there is no second CLI environment to initialize.+Installed code, selected configuration and existing execution data remain separate.-| Owner | What it decides |-| --- | --- |-| Author and Run Sources | what the work is and which public Outputs this execution requires |-| Runtime Profile | which environmental packages, Endpoint instances, credentials, and bindings are selected |-| Provider Endpoint | how one capability is supported, diagnosed, invoked, and priced |-| Credential Store | how one explicitly named secret is resolved |-| Managed Program | how a selected local Endpoint's resources are prepared and probed, and its helper is started when one exists |-| Project Result repository | where finished Build Results and their public Outputs live |+## Read and edit the actual configuration-Changing an Endpoint does not change the Author Source. Result storage is selected separately in-`hypit.results.json`; it is not a Runtime Profile field. Workspace and project-package resolution are-also independent of the Profile.+A complete minimal Profile for credential-free local media work is:-The Profile itself contains only environmental choices:+```json+{+ "format": "hypit.runtime-local@1",+ "dataRoot": ".hypit/execution",+ "credentials": {},+ "endpoints": {+ "media.local": {+ "use": "@hypit/provider-media-local"+ }+ },+ "bindings": {}+}+```-- `credentials` selects Credential Store adapters;-- `endpoints` names Provider adapter instances and their configuration;-- `bindings` chooses an Endpoint when several selected instances offer the same capability;-- an optional shared `pool` says that several instances consume one real account, deployment, or- compute quota.+This selects media processing only. It needs compatible FFmpeg and FFprobe supplied by the host;+it does not install them, select an image model, or render HyperFrames pictures. Use it when those+are the actual requirements, not as a replacement for a production's existing Profile.-Read each selected Provider README for its accepted configuration and capability support. Installing-a package only makes it available; a Profile entry selects it.+| Field | How to choose it |+| --- | --- |+| `credentials` | Named Credential Store adapters; empty when no selected Endpoint needs a secret |+| `endpoints` | Named Provider instances. `use` selects the package; its README defines `config` |+| `bindings` | Complete capability keys mapped to Endpoint instance names |+| Endpoint `pool` | Optional identity of a real shared account, deployment or compute quota |+| `dataRoot` | Where this Runtime keeps execution state; changing it selects different state |+| Optional `worker.executionMemoryMb` | Memory budget for Build execution processes; startup policy owned by the Runtime package |++Merge documentation fragments into the corresponding existing objects. Retain other services,+credential references and bindings the project uses. A fragment without `format` and `dataRoot`+is not a complete Profile. Package installation makes an adapter available; declaring it here+selects an instance. Configuration keys belong to that package, so a `baseUrl` or `apiKey` field+from one Provider is not a universal schema for all Providers.## Connect Model, capability, Need and Endpoint-These names describe different facts about the same work:+The [Model and Provider roles](model-and-provider.md#start-from-the-capability-the-work-needs)+keep authoring separate from deployment. One authored request produces a concrete external **Need**+only if its output remains demanded by the Run. Existing Result Candidates can satisfy that output+without another generation request.-| 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 different services 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:+A **capability** identifies the required operation. The Profile routes it to an **Endpoint**, a+configured Provider instance. A **binding** is that explicit routing choice. For example, after+declaring and configuring `whisperx.local`, merge:```json-"bindings": {- "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"+{+ "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.+Use the complete capability key from the Model/Provider vocabulary, not a vendor model label.+The named Endpoint must actually offer it and support the concrete request. One eligible Endpoint+needs no binding; several unbound choices are an error, not a fallback order. This lets the same+Source use local alignment in one deployment and hosted alignment in another.-Readiness and package discovery are separate. Explicit bindings let capability-scoped commands load-the named Endpoints directly. Without a binding, discovering which Provider can serve a capability-can require loading the Profile's Endpoint packages; a declared but uninstalled package can therefore-block discovery even when its service would not ultimately be used. Correct that declaration or make-the intended binding explicit. An unused account need not be logged in merely to resolve the work.+Explicit bindings let capability-scoped commands load the named Endpoints directly. Without a+binding, discovering eligible implementations can require loading the declared Endpoint packages;+an uninstalled declared package can therefore block discovery. Correct the declaration or select+the intended binding. An unused account need not be logged in merely to resolve the work.-## Set capacity at the resource it describes+The complete local alignment example is in+[local WhisperX](local-tools.md#select-local-whisperx-explicitly). Hosted and BYOK examples are in+[service connections](model-and-provider.md). Result storage and project-package resolution are+separate from this routing.++## Put secrets behind credential references-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.+A Profile names a Store and a key. The value stays in that Store.-| Control | What it limits |+| Store package | Storage and use || --- | --- |-| 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` | A fixed Chrome count, or `"auto"` to adapt within a per-render ceiling |-| HyperFrames `config.maxWorkers` | Optional per-render ceiling for `"auto"`; otherwise the Provider derives it from CPU and memory |-| HyperFrames `config.browserCapacity` | Chrome slots shared by render Needs; each reserves its fixed count or auto ceiling 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 fixed request larger than the configured browser capacity is a configuration error. Auto fits its-ceiling to that capacity and the requested range. 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.-Local HyperFrames holds both its request slot and browser units until the whole render Need finishes,-including preparation and encoding. The reserved units are a scheduling budget, not a live count of-currently open Chrome processes. Omitting `browserCapacity` leaves only the request limit.--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. 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. Ending the Build attempt releases its local claims while-preserving any remote receipt and last known status. 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-Provider README for-accepted settings. Use `hypit activity` to inspect actual claims. New Builds use the current Profile-and project implementation; see [Build execution scope](../production/builds.md#build-with-the-current-project-implementation).+| `@hypit/credential-store-platform` | Starter policy: macOS Keychain, Windows Credential Locker, or an owner-private unencrypted file on Linux |+| `@hypit/credential-store-os` | Explicit OS locker selection on supported platforms |+| `@hypit/credential-store-file` | Explicit unencrypted private file storage outside the project |+| `@hypit/credential-store-env` | Reads one named environment variable; read-only |-## Put secrets behind credential references+The platform policy selects by operating system; it is not a sequence of stores to try.+A read failure never migrates a secret or falls back to another Store. Preserve an existing choice.+The platform/file Store's default file directory is under the Host state root shown by `hypit paths`;+its optional `config.path` chooses a private directory. Read that Store's installed README for path+and platform rules, including filesystem permissions.-A Profile names a Credential Store and key; the secret stays in that store. The platform store is the-portable choice: macOS Keychain or Windows Credential Locker on those two platforms, and an-owner-private file on Linux. The OS store is that same locker on macOS and Windows only. The-environment store reads one explicitly named environment variable and is read-only. The file store-always stores an unencrypted document outside the project, never in an OS locker.--`runtime init` writes an editable starter that selects the platform store, so the Profile it writes-opens on every host without an edit. Selecting one Store explicitly instead means naming it in-`credentials` and in the Endpoint's credential reference, as-`{ "file": { "use": "@hypit/credential-store-file" } }` and-`{ "store": "file", "key": "<chosen-key>" }`, while preserving other Endpoint settings and bindings. File-backed storage writes into `credentials` under-the Host state root printed by `hypit paths`, and an optional Store `config.path` chooses another-private directory; ensure a Windows directory's ACL is private to the user. Preserve an existing-Store choice; never switch or migrate credentials just because one Store could not read them.--Inspect credential slots only when the selected Endpoint declares them. A credential-free Endpoint-such as local media processing needs no auth command; prepare its tools directly. For an Endpoint-with declared slots, inspect their state without revealing values:+To select a Store explicitly, name it under `credentials` and use that name in the Endpoint's+credential reference. A credential-free Endpoint needs no auth command; prepare its tools directly.-```bash-hypit auth status <selected-endpoint>+For example, these are the Store declaration and credential reference used by a HypiHub Endpoint:++```json+{+ "credentials": {+ "platform": { "use": "@hypit/credential-store-platform" }+ },+ "endpoints": {+ "hypihub.default": {+ "use": "@hypit/provider-hypihub",+ "config": {+ "apiKey": { "store": "platform", "key": "hypihub.oauth" }+ }+ }+ }+}```-Once the user has chosen to connect that account, use its declared acquisition flow or the selected-store's interactive input:+After the user has chosen that account connection:```bash-hypit auth login <selected-endpoint>+hypit auth login hypihub.default+```++A Provider declaring browser acquisition uses that flow immediately. Otherwise, a writable Store+uses secure terminal input. `--from /private/path/key.txt` explicitly imports a secret file instead+of opening OAuth. Wait for CLI success: a successful browser callback alone does not establish+that the Store write succeeded. Login/logout can replace/remove a damaged value without reading it;+status and execution still report read errors.++For an intentionally environment-backed deployment, merge this alternative Store and change the+selected Endpoint's credential reference accordingly:++```json+{+ "credentials": {+ "env": { "use": "@hypit/credential-store-env" }+ },+ "endpoints": {+ "hypihub.default": {+ "use": "@hypit/provider-hypihub",+ "config": {+ "apiKey": { "store": "env", "key": "HYPIT_HUB_API_KEY" }+ }+ }+ }+}```-The Endpoint already identifies the service and its Provider. `auth status` shows whether a-credential exists and the Provider's declared browser acquisition when present. For a writable-OAuth Endpoint, `auth login` opens that browser flow immediately; without a browser acquisition it-securely prompts for the secret. `--from <secret-file>` explicitly imports a secret instead of-opening OAuth. An Endpoint backed by the read-only environment store is configured in the Worker-process environment instead. Login and logout use the declared slot and write capability without-reading the old credential; a damaged stored value can therefore be replaced or removed. Status and-execution still report read errors.+Here `HYPIT_HUB_API_KEY` is the explicitly selected variable name. Supply it securely to both+the CLI commands that need it and the Worker process at startup. `auth login` cannot write an+environment Store. Changing a terminal's environment does not change an already running Worker.+Other services use their own Endpoint, credential slot and variable, not this HypiHub example.-For example, after choosing HypiHub, `hypit auth login hypihub.default` uses its browser login;-`hypit auth login hypihub.default --from /private/path/hypihub-key.txt` instead stores a HypiHub API-key. A different service uses its own configured Endpoint and key. Credential entry does not create-that service's Provider, select a model binding, or transfer another service's balance to HypiHub.+Use distinct Endpoint names and credential keys for separate accounts. Binding selects which one+serves the requested capability; entering another service's key does not change the Provider.+Local credential-free Endpoints need no login. `auth status <endpoint>` reports declared slots+without revealing values; configured does not mean accepted, funded, reachable, or authorized for+every model. Keep secrets out of Sources, Runs, Profile JSON, command arguments, commits and chat.-Keep secrets out of Author Sources, Runs, Runtime Profile JSON, project documentation, command-arguments, commits, and conversation text. Ask the user to complete a Provider browser flow or secure-terminal prompt rather than paste a key into chat. Report the Store, key name, Endpoint, and whether-it is configured; never report the stored value.+## Set capacity at the resource it describes-A stored credential proves only that a value is available. It does not prove that the account is-current, has quota, can reach a model, or is accepted by the remote service.+The Runtime Worker advances Builds. HyperFrames `workers` counts Chrome processes inside one+render Need. These are different controls; there is no extra Build-wide model concurrency setting.++| Control | Responsibility |+| --- | --- |+| Provider request capacity, commonly `config.defaultConcurrency` | Simultaneous Needs across Builds using the resource |+| Provider-specific model/action limits | Model quota or submit/poll/collect concurrency and rate; use that Provider's accepted fields |+| Endpoint `pool` | Shared resource identity for instances consuming the same real quota |+| HyperFrames `workers`, `maxWorkers` | Per-render Chrome count or automatic ceiling |+| HyperFrames `browserCapacity` | Shared Chrome budget alongside the whole-request budget |++For example, merge this Endpoint entry for an intentionally chosen render budget:++```json+{+ "endpoints": {+ "hyperframes.local": {+ "use": "@hypit/provider-hyperframes-local",+ "pool": "local-render",+ "config": {+ "defaultConcurrency": 2,+ "workers": 4,+ "browserCapacity": 6+ }+ }+ }+}+```++Only one four-browser request fits the six-browser budget at once, even though the request limit is+two. These numbers illustrate the relationship; choose them for the actual machine. HyperFrames+reserves both budgets until the whole render finishes, including preparation and encoding.+It does not release capacity each time one browser closes.++Instances sharing a pool must agree on its limits. Separate accounts do not share one merely because+they offer the same model. Capacity coordination covers Builds sharing a Runtime Execution Store;+it is not a cross-machine account quota service. Accepted asynchronous Operations retain their task+claim while pending. Short submit/poll/collect calls have separate action budgets when declared.+Ending a Build attempt releases local claims while retaining receipts and last known remote state;+it does not imply a remote task has been cancelled.++Use `hypit activity` when actual claims matter. The installed Runtime and Provider READMEs own the+exact settings. Studio's permitted transient work has session-local concurrency.## Ask each command for the fact it owns-| Command | What it can establish |+| Question | Command and boundary |+| --- | --- |+| Which project, Profile and storage locations apply? | `hypit paths` |+| Is a named credential present? | `hypit auth status <endpoint>`; no account-access guarantee |+| What will this Run demand? | `hypit plan <run>`; concrete requests, support checks and cheap readiness of their selected Endpoints |+| Can the selected services be reached and used? | `hypit doctor --endpoint <instance>`; bounded active diagnosis, no generation submission |+| Is the Worker running and work active? | `hypit runtime status` |+| Which local helpers answer, and where are their logs? | `hypit programs status --endpoint <instance> --verbose` |++Choose the observation needed now; this is not a mandatory sequence before every operation.+Without a selected Profile, `doctor` checks project Results only. With one, it may contact remote+services for bounded diagnostics. `plan` does not actively probe remote services or install missing+resources. Neither command prepares every language model just because a local service is healthy.++Prepare the selected resources and start needed helpers through+[local Program commands](local-tools.md#let-the-selected-endpoint-own-its-program).+A missing capability can leave independent Script, reference or component work possible; explain+which requested outcome still depends on it. [Review](../production/review.md#show-what-the-current-work-establishes)+distinguishes useful intermediate evidence from the intended deliverable.++## Know when a change takes effect++| Change | What to do || --- | --- |-| `hypit paths` | resolved project, selected Profile, and physical host/runtime locations |-| `hypit auth status <endpoint>` | whether that Endpoint's declared credential slots are configured |-| `hypit doctor` | an active, read-only audit of the selected or supplied Profile and Result repository |-| `hypit plan <run> --runtime <profile>` | the exact external Needs of one Run and cheap readiness of that demanded slice |-| `hypit runtime status` | Worker, active Build, and selected Managed Program state |--With no Profile selected or supplied, `doctor` checks the project Result repository alone. With a-Profile, it may authenticate and ask a remote Endpoint for its bounded capability catalogue. It-submits no generation request. A successful login followed by a failing doctor is useful evidence:-report the Provider's current explanation rather than treating credential storage as proof of-reachability.--Keep the failing request's scope with its evidence: selected Endpoint, requested model or capability,-and the returned status, code and explanation. These describe what failed; infer a cause only as far-as they support it. For example, `model_not_found` establishes that this request could not reach the-named model through that route, but does not itself establish a missing payment or permission.-Use the account-visible service information when investigating availability; a public model catalogue-alone cannot establish access for this account. Explain what is known and what still needs checking.--`plan` knows the chosen Target and Candidates, so it identifies the capabilities this Run will demand-and applies the selected Endpoint's normal request-support check. Its preflight checks configuration,-credential presence, packages, executables, and relevant Managed Programs without actively probing a-remote service. Read `../production/builds.md` for planning, spending authority, and submission.--## Be honest about the available production--When a capability is unavailable, explain the part of the requested result that depends on it and-the practical choices available. Reference frames, supplied text and product material can still-support interpretation, Script and visual planning. Existing media can support composition with-HyperFrames MG, Caption and Typography when those serve the Brief. Generated performances and-measured speech timing depend on the corresponding capabilities becoming available. Keep the-completed work and the remaining dependency clear so the user can decide how to proceed.-When showing that work, [composition review](../production/review.md#show-what-the-current-work-establishes)-helps distinguish useful intermediate evidence from the intended deliverable.--When the user brings another model, service, or Key, use-[Models and Providers](model-and-provider.md) to distinguish credential setup, Endpoint configuration,-and a package extension. A project can install or author its own Provider or Model through the public-package APIs. The actual service protocol determines whether an existing Provider is reusable.--## Prepare the selected environment--After choosing the services and their needed resources, use `hypit programs prepare --endpoint-<instance>` to prepare without starting helpers, `hypit programs up --endpoint <instance>` to prepare-and start them, or `hypit runtime up --endpoint <instance>` to start the Worker as well. Preparation-remains available for a running service; process health alone does not establish new resource readiness.-Repeat the flag for several instances. Omission deliberately prepares the whole Profile, even when-a capability is bound elsewhere. Preparation follows each Provider's declared dependencies and-Programs; it does not log into remote accounts. `hypit doctor --endpoint <instance>` actively checks-that selected service when diagnosis is useful. `plan` already narrows readiness to the Endpoints-resolved for the Run. Choose the command for the current question; these are not mandatory checks-before every Build. Resource readiness does not imply that a helper process exists.--For example, local media work can use `hypit programs prepare --endpoint media.local` to prepare-only, or `hypit runtime up --endpoint media.local` when execution needs the Worker. Neither requires-an account. Inspect tool readiness with `hypit programs status --endpoint media.local`, and Worker-state with `hypit runtime status`. Account connection is a separate decision for services that-actually declare credential slots.--Use `local-tools.md` when a selected local binary or Managed Program needs installation or repair.-Read `../production/builds.md` for how submission uses the prepared environment and Worker.+| Source, Run or project component implementation | Create a new Build for the changed work |+| Endpoint config or binding | New Builds read current choices; an existing Build retains its selected configuration |+| Writable Store credential value | Subsequent credential resolution uses that Store; changing a secret is not a blanket Worker restart instruction |+| Distribution installation, Worker startup policy or its inherited environment | Restart the Worker explicitly when active work permits |+| A running local service's model, device, compute, batch size or cache location | Prepare its selected resources, then restart that helper when idle |+| Additional WhisperX alignment language in the same cache | Run scoped `programs prepare`; the service can stay running |+| Browser download mirror | Used for the next required preparation; a healthy cached browser remains usable |+| Profile used by an existing Studio session | Restart the session if it needs to load the edited selection |++A new Build's execution context is not a snapshot of every external file or service.+Read [Build execution scope](../production/builds.md#build-with-the-current-project-implementation)+before restarting a coordinator or changing dependencies during active work.+Do not restart everything after every edit, or expect a completed Build to rerun itself.diff --git a/skills/hypit/references/playbooks/craft/b-roll.md b/skills/hypit/references/playbooks/craft/b-roll.mdindex f3f81b29..06501f7f 100644--- a/skills/hypit/references/playbooks/craft/b-roll.md+++ b/skills/hypit/references/playbooks/craft/b-roll.md@@ -1,121 +1,94 @@-# 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. Several lifestyle images can feed one short B-roll request whose direction owns their-scene order, while the result covers 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. A partner can start responding while the-last lifestyle picture is still visible, with their camera returning 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 Sound output included in Film 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:--```text-@{coffee} my coffee @{/coffee~} @{smoothie} my smoothie @{/smoothie}-```--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. [Script and semantic time](../../creation/script-and-time.md#bind-meaning-to-script-identities)-contains 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.--For speech-free work, author timing from the visual, musical and action relationships. Independent-Media Items can occupy chosen Windows. A named wordless Segment is useful when a real media passage-should supply reusable start/end anchors; [media preparation](../../production/media.md#empty-segments-use-their-media-boundaries)-explains that option. [Timeline](../../production/timeline.md) also supports graphics-only intervals-and complete animation without media-backed Segments.+# Material-led pictures and B-roll++An image or video can carry a passage's visual answer: evidence for a claim, a place to inhabit, an+action to understand, a contrast or a joke. B-roll is a common editorial use of that material while+a performance carries the passage's words and time. The same materials can also lead the picture+through a narrated explanation or a speech-free sequence. Choose their role from what the viewer+needs to see, rather than from whether the source is a still, a moving clip or a person.++## Give the material a reason to appear++Creator-led video often shows the speaker's life while their performed words continue: working,+studying, travelling, using a product or reacting in another situation. Those pictures make the+person and world more tangible. The person visible in a lifestyle image or silent clip may be the+same person whose voice is heard; the placed performance still owns the words. A different passage+may use a visible speaking Take whose own delivery carries the words. [Voice and performance](voice-and-performance.md)+owns that distinction.++An image can hold a product fact while the speaker makes a claim. A moving demonstration can show+the action that proves it. A screenshot can make an interface state readable. One well-chosen+picture may carry the thought more clearly than a new shot for every noun. When the work needs new+material, [image direction](image-direction.md) or [video direction](video-direction.md) owns its+creation; this page owns why and how it appears in the work. When the screen itself carries the+explanation or evidence, [screen demonstrations](screen-demonstrations.md) owns that directing choice.++## Choose the relationship to the thought++**Exact correspondence** serves a claim whose meaning depends on a particular picture being+visible at that point. Give that image or clip the semantic Window the claim needs. A brief+display can use part of a longer source; the generation request's duration does not set its+display duration.++**A visual thought across several pictures** can convey a habit, history, process or attitude.+The pictures may be separate Items or scenes inside one generated clip. Their changes can follow+the argument's beats without assigning a cut to every spoken noun. When the reference's exact+picture-to-claim correspondence matters, preserve that closer relationship instead.++A generated multi-scene clip needs direction for scene order and meaningful actions. The+`@hypit/seedance-kits/broll` Kit's `story` Text can express that relationship for Seedance; its+package README owns the tested wording and edit choices. A direct image, an existing video or+independently arranged media may serve the same visual purpose without that Kit.++## Compose material and performance in the same picture++A still can fill the Canvas; a video can play beside a moving presenter; either can sit within a+frame, crop, mask or designed border. The chosen picture can lead attention while the performance+remains visible elsewhere, or it can occupy the whole view while that performance's Sound+continues. Its location and paint order follow the composition, not its B-roll name.++For an independent picture, [Media presentation](../../production/media-presentation.md) supplies+the image or prepared video, its Frame, appearance and playback. A still has a display Window+without needing video conversion. [Performance](../../production/performance.md) presents footage+already placed on the Timeline and retains its source position as its view changes. When material,+presenter and graphics share layout or motion, a [project component](../../production/component-design.md)+can own that visual behavior together. A border or animated frame is a presentation choice; it+does not require a new kind of source material. [Spatial layout](../../production/spatial.md) owns+the Canvas, Frames, fitting and crop that realize the chosen arrangement.++A video's location sound or action sound can contribute to the mix when it helps the moment.+Picture placement by itself does not replace the performed speech; [sound and mix](sound-mix.md)+owns how those audible contributions meet.++## Let the picture enter and leave on its own terms++A picture answering a spoken claim can follow a Selection or Moment; a musical beat or physical+action may call for authored time. Its visual Window need not start or end with a speaker's+appearance. A partner may begin speaking while the last lifestyle picture stays up, then become+visible later: the sound-picture handoff forms a J-cut. The placed Takes and Sound establish whose+words are heard while the visual composition chooses when views change.++Choose the end by the thought, action and time needed to read the picture. A still remains present+through its Window; a moving source also has its own playback span. Let a clip finish when its+last action matters, or cut it where the work gains the better beat. Holding, looping or retiming+is another expressive choice, not a consequence of the Window being longer than the source.+[Media presentation](../../production/media-presentation.md#keep-display-time-and-source-playback-distinct)+owns those sampling modes.++Adjacent pictures may meet at one semantic boundary, bridge the pause between words or intentionally+expose another view. [Script marker affinities](../../production/script-syntax.md#bind-meaning-to-script-identities)+owns the exact shared-boundary forms; [review](../../production/review.md#make-the-composition-work)+locates an unintended flash or gap. Watch the actual result: a nominally continuous Window cannot+make an exhausted source or transparent frame fill the picture.++## When material leads the whole passage++A music-led montage, tactile process film or visual product explanation can make images and clips+the main sequence. Choose cuts from the visual argument, physical action or musical phrase. A close+view earns its change when it reveals what the wider view could not; a quiet contact or settling+motion may deserve time to finish. [Sound and mix](sound-mix.md) owns how recorded, generated or+separately authored sound supports that material.++The same [Timeline](../../production/timeline.md) holds performed Takes, gaps and directly authored+intervals. Independent material can occupy any of them. A wordless performed passage can supply+its own reusable media boundaries; a passage made entirely of pictures and graphics can use+authored time. Neither requires a hidden speaking picture.diff --git a/skills/hypit/references/playbooks/craft/caption-tracking.md b/skills/hypit/references/playbooks/craft/caption-tracking.mdindex db3a3989..e0f783d0 100644--- a/skills/hypit/references/playbooks/craft/caption-tracking.md+++ b/skills/hypit/references/playbooks/craft/caption-tracking.md@@ -1,22 +1,35 @@# Caption above a moving head-Use this when following a person's head adds character or keeps Caption clear of the image. The-relationship uses external face measurements, authored head regions and Fine's existing-placement input. The detector measures evidence; the author decides the Caption design.+Read this when the user's reference visibly uses Caption that follows a speaking person's moving+head, or the user asks for that treatment. Ordinary Caption uses its family's layout and Style+placement; the presence of a face does not by itself call for head boxes. The optional measured or+authored regions answer where this particular speaker's words should appear in the actual picture.-## Produce the footage that will actually be measured+## Resolve who, where and when-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.+Script Role identifies who says the Cue. The intended view of that person in the final composition+determines where the Cue follows them; GVI face-track ids do not establish identity. The speech and+the directed Caption treatment determine when it appears. In ordinary turn-taking, the previous+speaker's Caption hands off as the next speaker starts. Their face remaining visible is not a reason+to keep their earlier words on screen.-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.+Measure whichever available picture lets those relationships be mapped accurately:-## Obtain useful boxes outside Build+- A supplied clip or prepared Take gives source-local positions that must follow its placement,+ playback, crop and any moving view into the composition.+- A composed view already contains its camera framing and program time, provided graphics do not+ obscure the person being measured.++Retain the relation between the measured source and its use. A source timestamp can change meaning+after trim or retiming, and a face box can move after crop or reframing. A presenter shrinking into an+inset needs positions that follow that actual transformation. When the same person appears in+several views simultaneously, choose the view this Caption follows. Fine accepts one region per Role+per frame; several simultaneous text placements need an explicitly authored presentation.++Leave room for the complete Cue and nearby graphics. A correctly measured head can still be an+awkward place to put a long phrase; the work may instead use ordinary Caption placement there.++## Read face observationsThe 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@@ -37,16 +50,18 @@ person identity: a cut can split one guest across several tracks, and one sharedseveral people. Combine the fragments that visibly belong to the Role in final program time. Selectingthe first or largest face alone can attach the guest's Caption to the interviewer.-## Author one head region per final program frame+## Map observations into the compositionTransform the useful observations into ordinary project data, with these decisions explicit:-- **Clock:** resample onto the Timeline's frame rate. A Take-local observation becomes global by- adding that Take's actual placement start, including any authored gap or overlap. Sequential- placement uses preceding prepared durations. Final-video measurements already use the global clock.+- **Clock:** sample the observations on the Timeline's frame clock using the actual source playback+ mapping. For a prepared Take on the same clock at native speed, add its actual placement start,+ including any gap or overlap. Apply any source trim or rate change when measuring other footage.+ Final-video measurements already use that rendered program's clock.- **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.+ box through that actual placement before normalizing it to the final Canvas. Update this mapping+ through a moving or resizing view; a single fixed rectangle cannot describe that movement.- **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;@@ -54,15 +69,25 @@ Transform the useful observations into ordinary project data, with these decisio- **Missing observations:** make any interpolation or smoothing an explicit external preparationchoice within a continuous shot and the same person. Inspect it, stop at cuts and occlusion, andwrite `null` when no usable region exists. Fine does not invent a missing box.-- **Role visibility:** intersect the assembled head regions with the turns where that Role is intended- to own Caption, including only any lead or tail deliberately wanted at the boundary. Write `null`- through other speakers' turns and other intervals. This prevents a correctly detected face from- becoming placement evidence for Caption that does not belong to that person.-The final array has exactly one box or `null` per program frame. Caption already follows the Role's-spoken Cues; the region track supplies measured position and an explicit visibility boundary, not a-second speech detector. Other composition choices, such as hiding that Role's Caption under B-roll,-can use the same authored null regions or the appropriate Caption selection behavior.+Each Role track's final array has exactly one box or `null` per program frame. Keep the actual array+in a project Recipe such as `tracking.svs`. A project script can perform the transformations using+explicit source, clock and geometry inputs. Changing the camera use can require remapping positions.++## Place only the intended speaker's Caption++Script and Caption already connect a Role's words to their timed Cue; the region input supplies the+head position for the frames where this treatment follows them. A `null` region also hides that+Role's Cue on that frame. Use the Cue's presentation window or `null` regions to end its appearance+at the intended handoff, including when a Style's tail would otherwise leave the old words over the+next speaker. When the person is absent, obscured or in another camera view, choose whether the+Caption ends or uses an authored ordinary placement. Neither a detector track nor the mere presence+of a listening face extends someone's speech.++[Caption presentation](../../production/caption-presentation.md) owns Style coverage and hiding.+A Role with no region track keeps ordinary Style placement; a `null` inside an existing track hides+the Cue rather than switching placement automatically. A deliberate tracked-to-ordinary change can+use explicit Caption Uses or separate Tracks with the same Script and Timeline.For example, this is a three-frame data-shape illustration, not a ready timeline for a real video:@@ -75,10 +100,7 @@ heads.default {}```-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+## Connect the placement to Caption```svml<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>@@ -90,14 +112,14 @@ these transformations reproducible when needed, taking explicit media, clock andThe RegionTimeline's ids match Script Roles. Fine places a single-Role Cue at that region's topcenter; `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.+font and motion. Supplying `regions` requires every Cue on that Track to have one Script Role, even+when that particular Role uses fixed placement. Author the relevant Role Cues in Script. The+`@hypit/spatial` and `@hypit/caption-fine` READMEs own the exact data behavior.++## Inspect the actual placement++Use Studio or [snapshots](../../production/snapshots.md) to inspect the current picture around+camera changes and speaker handoffs. Check the first and last frames of each tracked Cue, the whole+Cue's clearance above hair or hats, top-edge clipping and collisions with graphics. Play the passage+with speech to judge jitter, wrong-person jumps and reading rhythm. When source timing or visual+presentation changes, remap the affected observations rather than carrying stale coordinates forward.diff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.mdindex 7b880117..d1f16481 100644--- a/skills/hypit/references/playbooks/craft/captions.md+++ b/skills/hypit/references/playbooks/craft/captions.md@@ -9,6 +9,14 @@ Script's Dual Text permits intentional display/pronunciation differences: “201remain 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.+For a coined name or letter-name reading, use+[Script pronunciation](../../creation/script-and-time.md#choose-the-sound-the-spelling-should-carry):+`<CSS|see ess ess>` keeps `CSS` on screen while supplying its chosen reading to the performance.+`<New York|>` instead keeps identical display/speech wording in one complete correspondence;+`<|再见>` retains the spoken words and their anchors while omitting them from Caption. These forms+choose content and correspondence; the Caption family decides their visual treatment. Place `||`+between complete units when another reading handoff is wanted.+For implementation of a new visual family, read[Caption authoring](../../production/caption-authoring.md). That guide keeps the common text/timingchain and shows where the new family owns scheduling and rendering.@@ -27,31 +35,10 @@ A short handoff can land a punchline; a longer phrase can let an explanation brewhen the viewer can read the thought and follow the picture. The reference, language and intendedenergy inform that judgment rather than prescribing a fixed Cue length or one caption look.-## Caption families, Styles and parameters--Script publishes one `CaptionDocument`: ordered display words, complete Alignment Units, speaking-Roles, word attributes and authored Cue handoffs. Caption joins it to the real Timeline. That-common typed relationship is what makes the result Caption; an official renderer is not the-definition. A project package can provide another Caption family while keeping the same Script words-and measured speech evidence.--Direct the presentation through three related layers:--| Choice | What it decides |-| --- | --- |-| **Family** | The structural visual language and scheduling behavior the Caption can express: uniform flowing words, independently arranged phrases, speaker-attached shapes, or another authored relationship. |-| **Recipe and resolved Style** | One coherent treatment within that family. An SVS Recipe gathers a useful combination; the family's Style Surface resolves it with fonts or other explicit resources. Role or Selection applications can choose among those Styles. |-| **Parameters** | The individual decisions inside that treatment: placement and anchors, usable width, wrapping, typography, Paint and boxes, active-word response, Cue motion, reveal, lead, tail and handoff. |--The installed family vocabulary owns exact parameter names and accepted values. Craft owns how the-combination serves this picture and this reading rhythm. Keep a proven production treatment in its-project `.svs`; a set that has earned reuse across works can become an ordinary versioned data package-under its owner's scope. Such a collection preserves the family, Recipe and intended use together-rather than turning isolated parameter values into universal defaults.--Caption Track Uses choose when those Styles apply, optionally filtered by speaker. Cue content-stays complete when presentation changes midway through a phrase. [Caption styling and coverage](../../production/caption-presentation.md) explains-overrides, Segment-wide selections, word attributes and hiding selected captions with a Hidden Style.+Choose the reading phrase, its layout and its emphasis together while keeping their responsibilities+clear. A meaningful phrase may wrap over two lines; one line may stay fully visible while its spoken+word changes color. Hiding a caption for a demonstration changes presentation, not the Script or the+performed speech. The following sections connect these decisions to the actual picture.## Keep wording and timing in their owners@@ -64,46 +51,13 @@ Use the produced performance's normalized and aligned audio. A change to that auits cuts can change word timing and requires corresponding alignment. A visual-only restyle canreuse the same semantic and media outputs through the Run.-## Reuse Fine or author a new family--UGC, podcast and interview work can 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--<caption-fine:Track id="captions" document={story.caption}- timeline={speech.timeline}>- <caption-fine:Use style={primary-caption}/>- <caption-fine:Use role="GUEST" style={guest-caption}/>- </caption-fine:Track>-```--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.--Fine is to Caption what Media is to ordinary picture presentation: a broadly useful reusable-component. A new visual relationship can become a project component directly. A Caption family can-arrange a phrase around its keyword, place speakers' phrases in a shared composition, or coordinate-words and graphics as one visual event. Word attributes and Selections carry the authored meaning;-the family owns how that meaning appears and moves. This is ordinary video authorship, including for-a treatment used in only one work.--Apply the same freedom to component boundaries. Independently behaving captions can remain a peer-Track. Words and graphics whose layout or motion belongs together can share a component, consuming-the common Caption document and semantic timing. Caption names the relationship between displayed-speech and its performance; it does not prescribe a separate visual layer or the Fine renderer.-[Caption authoring](../../production/caption-authoring.md) explains building that family or scene.-## Design Cue rhythm with the Caption systemA Cue is one timed block of displayed speech. Its family and Recipe determine what that block looks-like; Script's `||` determines an additional handoff between blocks inside the same Segment, speaking-turn and Style run. Those other boundaries already form new Cues. A visual line is different: Fine-may wrap one Cue over several lines without another `||`.+like; Script's `||` determines an additional handoff between blocks inside the same Segment and+speaking turn. Segment and turn boundaries already form new Cues. A Style Use can change presentation+partway through a Cue while retaining its complete content and original word times. A visual line is+different: Fine may wrap one Cue over several lines without another `||`.Choose the grouping from language and picture together. Let one Cue carry a coherent phrase orthought that the viewer can grasp while still watching the performance. Preserve words whose meaning@@ -123,6 +77,7 @@ or character count cannot make that choice. Count the display side of Dual Text| --- | --- || English | Keep a useful phrase together, including its articles, negation and name or quantity. Word lengths vary, so the chosen face and width matter more than a word count. || Chinese | Keep compounds, names, modifiers and their objects together. Let a complete short clause share a Cue when it fits; repeated tiny character groups fragment both meaning and the screen. |+| Korean | Preserve the authored word spaces and keep grammatical phrases readable together. `3개월` and `3 개월` are different authored spellings; the Caption layout follows the chosen one. || Mixed Chinese and English | Read the phrase as a whole. A Latin brand name or number can occupy several Han characters' width; its lexical unit count does not predict that width. |Fine preserves authored display separators in every writing system. Its `word-gap` sizes those@@ -130,9 +85,14 @@ separators; a Chinese/Latin or number/letter boundary does not create one. Writewhen that space is intended, and `3D` or `3개월` when the text should stay joined. `letter-spacing`adjusts glyph tracking. `<expression|>` groups an expression for caption behavior; it is not neededto preserve spelling or spaces.-The same timing supports a stable complete Cue, current-character color or a trail. For flowing-Chinese speech, a readable phrase with restrained emphasis often works better than a separate bounce-or reveal on every character. Choose the response for the performance's energy.++### Choose emphasis independently of grouping++The same timing supports a stable complete Cue, current-word or current-character color, or a trail.+A stable phrase can let the viewer follow a detailed demonstration while still reading the speech.+An active-word response can draw attention to its delivery; a whole-expression response can give a+name or punchline one visual accent. Choose from the intended viewing rhythm. Character-level timing+remains available even when the design keeps the whole phrase steady.For whole-character highlighting, use `karaoke: current` with `karaoke-transition: step`.Choose `trail` instead of `current` when the already spoken characters should stay highlighted.@@ -153,12 +113,13 @@ Cue available to read while Karaoke supplies emphasis; `on-start` reveals wholeremains one shared timing unit. Scope it to the expression needing a pronunciation hint so thesurrounding Chinese characters retain their own timing.-With Fine's uniform-flow family, direct the common Cue to remain on one line by considering its-grouping together with the Recipe's font size, usable width and word gap. A stable line lets each-handoff replace one readable block without repeatedly changing the block's height and the viewer's-reading position. A Caption family designed around a two-line stack, an oversized keyword with a-supporting phrase, or another internal composition owns that relationship itself; its intentional-line structure is not a reason to add another `||`.+### Choose line layout for the picture++A single-line treatment can give successive short Cues a stable reading position. Direct it through+the phrase grouping, font size, usable width and spacing together. When a complete thought needs+more room, Fine can wrap the same Cue over several lines. An independently arranged oversized keyword+with supporting text can instead belong to a new Caption family. Choose the structure for the+picture and meaning; a visual line break alone is not a reason to add another `||`.For example, these groupings preserve short ideas in each language:@@ -174,6 +135,11 @@ For example, these groupings preserve short ideas in each language:一张参考图 || 就能重新设计镜头和节奏,||让字幕和特效 || 为你的产品服务。</explanation-zh>++<explanation-ko><HOST>+ 참고 영상 하나로 || 촬영과 편집의 리듬을 바꾸고, ||+ 자막과 효과를 || 제품에 맞출 수 있어요.+</explanation-ko>```These are alternative Script excerpts, not a bilingual performance. Another width or delivery can@@ -185,28 +151,102 @@ that count is usually characters. Leave it unset for ordinary width-based flow;deliberate counted row serves the design. `max-lines` checks those counted rows and requires thatsetting; it does not make a long Cue fit one physical line. The package README owns these controls.-Use Studio or a rendered interval to see the Cue with actual speech. Repeatedly flashing tiny groups-usually means the viewer is being asked to reacquire text too often; an overfull block usually means-the language, Recipe or family is asking one visual state to carry too much. Change `||` when the-reading unit is wrong. Change the Recipe when the reading unit is right but its size, wrap, placement-or motion is wrong. Change the family when the desired relationships cannot be expressed by that-family's structure.+## Give captions a place in the visual languageChoose font, size, width, line height, contrast and motion together. If a Cue overflows, inspect bothits 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.-Judge weight and outline from the actual glyphs. Dense Han characters need their internal spaces to-stay open; a heavy Latin-caption outline can overwhelm them. A clear face with a modest outline or-compact shadow can separate speech from a busy picture while preserving the letterforms. Changing-the language calls for reconsidering the treatment, not merely replacing the text in an English Recipe.+Judge weight, outline and shadow from the actual glyphs against the moving picture at delivery size.+A bold outline can give an energetic caption its shape and separation; a compact shadow can separate+a quieter treatment. Keep the internal spaces of dense glyphs legible as the weight grows. The useful+strength depends on font, size, background and intended style, including when changing languages.++Lettering and decoration can share a palette without coloring each word differently. A two-color+accent beneath a steady phrase, a shaped background or an offset shadow can connect Caption to the+film's visual language. Use an existing Style when it expresses that relationship, or author the+coordinated text and decoration in a project Caption family. Let the decoration's extent, position+and movement answer the text it supports.Treat Caption, icons, flashes and other graphics as a composition. A guest color and answer accentscan work together without coloring every system identically. Check readability acrosslight and dark frames, avoid hiding the important face or product, and allow enough space above atracked head for the whole Cue rather than only its anchor.-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.+Ordinary Caption placement belongs to the chosen family's layout and Style: it can hold a stable+reading area or respond to the composition without face boxes. When the user's reference visibly+uses head-following Caption, or the user asks for that treatment, use the optional+[Caption tracking](caption-tracking.md) relationship. A visible face alone does not choose it.++## Caption families, Styles and parameters++Script publishes one `CaptionDocument`: ordered display words, complete Alignment Units, speaking+Roles, word attributes and authored Cue handoffs. Caption joins it to the real Timeline. That+common typed relationship is what makes the result Caption; an official renderer is not the+definition. A project package can provide another Caption family while keeping the same Script words+and measured speech evidence.++Direct the presentation through three related layers:++| Choice | What it decides |+| --- | --- |+| **Family** | The structural visual language and scheduling behavior the Caption can express: uniform flowing words, independently arranged phrases, speaker-attached shapes, or another authored relationship. |+| **Recipe and resolved Style** | One coherent treatment within that family. An SVS Recipe gathers a useful combination; the family's Style Surface resolves it with fonts or other explicit resources. Role or Selection applications can choose among those Styles. |+| **Parameters** | The individual decisions inside that treatment: placement and anchors, usable width, wrapping, typography, Paint and boxes, active-word response, Cue motion, reveal, lead, tail and handoff. |++The installed family vocabulary owns exact parameter names and accepted values. Craft owns how the+combination serves this picture and this reading rhythm. Keep a proven production treatment in its+project `.svs`; a set that has earned reuse across works can become an ordinary versioned data package+under its owner's scope. Such a collection preserves the family, Recipe and intended use together+rather than turning isolated parameter values into universal defaults.++Caption Track Uses choose when those Styles apply, optionally filtered by speaker. Cue content+stays complete when presentation changes midway through a phrase. [Caption styling and coverage](../../production/caption-presentation.md) explains+overrides, Segment-wide selections, word attributes and hiding selected captions with a Hidden Style.++## Reuse Fine or author a new family++UGC, podcast and interview work can 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+<caption-fine:Track id="captions" document={story.caption}+ timeline={speech.timeline}>+ <caption-fine:Use style={primary-caption}/>+ <caption-fine:Use role="GUEST" style={guest-caption}/>+ </caption-fine:Track>+```++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.++Fine is to Caption what Media is to ordinary picture presentation: a broadly useful reusable+component. A new visual relationship can become a project component directly. A Caption family can+arrange a phrase around its keyword, place speakers' phrases in a shared composition, or coordinate+words and graphics as one visual event. Word attributes and Selections carry the authored meaning;+the family owns how that meaning appears and moves. This is ordinary video authorship, including for+a treatment used in only one work.++Apply the same freedom to component boundaries. Independently behaving captions can remain a peer+Track. Words and graphics whose layout or motion belongs together can share a component, consuming+the common Caption document and semantic timing. Caption names the relationship between displayed+speech and its performance; it does not prescribe a separate visual layer or the Fine renderer.+[Caption authoring](../../production/caption-authoring.md) explains building that family or scene.++## Review in the current composition++Use [snapshots](../../production/snapshots.md) from Studio or the existing HTML to inspect the actual+glyphs, spaces, outline, decoration, wrapping and neighboring visual states. Play the passage in+Studio to judge reading rhythm, emphasis, Role assignment, cut transitions and tracked movement with+speech. The current composition supplies this evidence while the Run retains its accepted media and+semantic Outputs. Inspect the encoded file too when delivering an export.++Repeated tiny handoffs can ask the viewer to reacquire text too often; an overfull block can ask one+visual state to carry too much. Change `||` when the reading unit needs another handoff. Change the+Style when the reading unit works but its size, wrap, placement or motion does not. A different+structural relationship can become a project Caption family. Check that the resulting treatment+works with the actual spoken pace and picture, including its entrances and exits.diff --git a/skills/hypit/references/playbooks/craft/compositing.md b/skills/hypit/references/playbooks/craft/compositing.mddeleted file mode 100644index d185732d..00000000--- a/skills/hypit/references/playbooks/craft/compositing.md+++ /dev/null@@ -1,190 +0,0 @@-# 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.--## Keep physical, camera and editorial space distinct--One finished frame can relate three kinds of space:--| Space | What it owns |-| --- | --- |-| Physical scene | The people, setting and objects actually recorded or generated; gaze, touch and physical interaction belong here. |-| Camera composition | The viewpoint, framing, subject placement, scale and crop through which that scene is seen. |-| Editorial composite | The Caption, MG, inset, mask and other Tracks placed over or around the source picture, including their stack order. |--The final design can make these spaces answer one another without merging them. A later overlay can-influence the camera composition chosen for a source picture, but it does not become an object inside-that picture's physical scene. The source remains a complete image of its world; the overlay remains-an authored layer in the final composition.--## 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.-Frame the subject and anything that must remain readable outside the overlay's planned footprint while-directing the whole image as a complete natural scene. 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. [Spatial layout](../../production/spatial.md) owns the exact-Frames and fitting once the intended relationship is known.--## 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.-For acquiring that material, [browser capture](../../production/browser-capture.md) provides direct-screenshots and ordinary scripts for real page interaction and recording.--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.--## Choose an A-roll presentation--The performance carrying a spoken Segment remains A-roll across several common visual-presentations. Choose the source shape and final Frame from the intended relationship, the reference-evidence, and the feeling of the shot rather than from a fixed layout recipe.--| Presentation | Useful starting judgment |-| --- | --- |-| Full-frame | A `9:16` character-and-scene image and reference-generated performance are the common fit for vertical creator footage. Frame the face, body and real setting for the later composite. |-| Upper or lower split | A square camera image and performance often cover a `9:8` half of a vertical Canvas cleanly, with a small top/bottom crop. A close, intimate phone view may instead be a vertically generated performance whose other half is covered. |-| Foreground cutout | A vertical performance often preserves a natural amount of the speaking body. Remove its background, normalize the alpha-bearing result, and use that same prepared performance as the SemanticTake. |-| Circular picture-in-picture | A square source with the face near its own center is a useful starting point. Present the semantic performance through Performance with a square Frame and rounded clip whose radius is half the side. |-| Audio-only A-roll | The performance contributes semantic time and sound but no picture. Another Track fills the Segment with the intended demonstration, POV, B-roll, Typography or MG. |--For a non-overlapping upper/lower split, equal stacking order can express two peer regions; the-Frames themselves keep them separate. Other unambiguous stack choices can serve the same picture.-Use Content Fit to map the source into its destination Frame rather than changing the source's-semantic role.--When reconstructing an apparent half-screen presenter, the final rectangle alone does not reveal its-source shape. Inspect camera distance, intimacy, body crop, background coverage and related views. A-close phone feeling can support the reading that a vertical performance is partly covered; a flatter,-more distant composition can support a native square view. These are useful priors, while the actual-visual evidence and intended target composition decide.--The source image and video direction describe a complete physical scene and camera view. Position a-face high or low, left or right, through framing and meaningful scene relationships when that serves-the final layout. Editorial graphics are composed with the generated material; they may share a component when their-layout or motion belongs together. They are not objects for the generated-person to see, touch or point toward. [Image direction](image-direction.md#frame-the-image-for-what-it-will-become)-owns the camera-image wording; [Spatial layout](../../production/spatial.md) owns Frame, fit and crop.--### Prepare a moving cutout plate--When the intended A-roll presentation is a moving cutout, a chroma-backed camera image is a useful-way to prepare the performance. Direct the person's identity, appeal, styling, framing, visible body-extent and performable presence with the same care as another A-roll image. Give that photographed-world a continuous, evenly lit chroma backdrop whose color separates clearly from the person's hair,-clothing, skin, microphone and other carried objects. Green is a common starting point; another flat-chroma color can provide better separation when green belongs to the subject.--This image is a production plate for the speaking performance. Use it as the actual image reference-for the video generation, direct the person's Script delivery and physical performance, and keep the-backdrop visually stable through the clip. The resulting moving video then follows one relationship:--```text-chroma-backed camera image- → generated speaking performance- → moving-video matting- → alpha-preserving normalization- → SemanticTake- → Timeline placement → Performance or project-scene presentation-```--The chroma backdrop establishes subject separation rather than the final story setting. The final-background, screen, B-roll or MG belongs to the editorial composite, where it can change without-regenerating the accepted performance. [Image direction](image-direction.md) still owns the person's-identity, framing and useful performance state; the matting section below owns the processed video.--## Inset, cutout and flattened composite are distinct choices--A speaking rectangular inset, circular inset or normalized cutout can be presented by-Performance or a project scene. A circular inset is a geometric crop: use a square Frame and a rounded clip whose-radius is half that square's side. The camera background remains inside the circle. A cutout instead-follows the person's silhouette and needs suitable transparency in the source. Timeline assembly retains-the Take's positions; its visual component presents the prepared picture. Media Track can use the same prepared-media when the work intentionally gives it an independent Window, playback, trim or visual role.--A speaking person in either presentation remains A-roll when their performance carries the main-Script. Choose placement and stacking for the viewer's attention; preserve the performance's-semantic timing and route its speech once.--When the intended composition needs an isolated silhouette, a still portrait can use-[image background removal](../../production/image-operations.md#remove-a-background). A moving subject-needs video background removal or a suitable key/matte for the changing silhouette.-Choose from what the selected capability actually accepts and returns. Removing the background from-one reference image does not establish transparency in the generated video, and a frozen portrait-cutout does not supply the speaking motion of a live presenter.--Matting changes the picture, not the clip's role in the work. Apply removal to the generated or-supplied clip, then-[normalize the processed video](../../production/media.md#prepare-moving-media-on-the-program-clock).-The normalized result continues into Script alignment and a SemanticTake when it carries the A-roll.-For B-roll, use that normalized result directly in Media Track. Transparency belongs to the picture-and needs to survive normalization; the semantic step belongs to the performance's role in the work.--The Source selects an installed video-matting Surface, and the Runtime Profile selects the Endpoint-that performs it. For the official portrait-matting Model, use-`hypit vocabulary @hypit/volcengine-matting --tag Portrait` for the installed Surface, output and-format values; its package README owns current Model and Provider availability. Normalize the returned-video while preserving alpha, then consume it according to its role in this work.--The semantic step keeps the prepared picture and adds the Script's timing; transparency does not-require another kind of Take or Track. Choose which role the cutout serves in this work:--| Role | Consume the prepared output |-| --- | --- |-| A speaking performance with local semantic timing | `cutout-media.media` → SemanticTake → Timeline assembly; show its placed picture through Performance or a project component and present its placed audio through Sound. |-| An independent visual overlay | `cutout-media.media` → a Media Item's `media` input; select its Window on the Timeline and include the Track's visual output in Film. |--When the intended artifact is a fixed flattened arrangement of still images, use-[Image Compose](../../production/image-operations.md#flatten-a-fixed-still-image-arrangement).-That page owns its exact role, limits and Source syntax.--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/frame-coverage.md b/skills/hypit/references/playbooks/craft/frame-coverage.mddeleted file mode 100644index 9aced77c..00000000--- a/skills/hypit/references/playbooks/craft/frame-coverage.md+++ /dev/null@@ -1,28 +0,0 @@-# 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. A fallback layer works when it is the designed background; an unintended-foreground gap belongs to the boundary, transition, source duration, or component schedule that-exposed it.--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.mdindex c5fe22f9..797fc9b2 100644--- a/skills/hypit/references/playbooks/craft/generated-dependencies.md+++ b/skills/hypit/references/playbooks/craft/generated-dependencies.md@@ -1,82 +1,38 @@# Reference relationships-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.+Every image request asks the painter for a complete picture. Connected references bring useful visual memory into that request: a person's appearance, a product's form, a place's atmosphere and geometry, a camera relationship, or a physical state. Some details need close continuity; others give the painter a world to reinterpret from a new viewpoint. Direct what the current picture carries forward and what it now shows. The relationships among images take the shape of those creative needs.-## Keep the useful parent close+## Let one picture open another view-| Work | Useful relationship |+A podcast host image can establish a person, an encounter and the restaurant around them in one camera view. The image for the other host can use it as an anchor while changing several parts of the picture at once:++| Part of the new picture | How the new view uses the host image || --- | --- |-| 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. |-| Short drama | A small set of camera images establishes each dramatic setting; its Takes reuse those views until the story needs new visible facts. |--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.--The first image in a dramatic setting may contain one person or several. Within that setting,-complementary views can retain the shared atmosphere, palette, materials and spatial relationship-while showing the different background sector visible to each camera. Those useful views can support-several Takes; a modest change of performance or framing does not require another image edge.--A meaningfully new setting can begin with an actual camera image in that world, connected to the-authoritative character, product or continuing prop references it needs. Each setting can branch from-those closest facts while leaving incidental objects from previous scenes behind. This keeps the graph-shallow as a consequence of clear reference responsibilities.--A supplied portrait can enter the first useful camera image, with the full capture and art direction-the target needs. In a podcast where only the second host changes, the first view supplies the shared-place and the user's portrait supplies the new second host. In a street interview, supplied identities-can enter the shared two-person image before its close views are derived. A product image enters the-views where it appears, such as a host's product-holding variation. Use the existing image directly-when it already serves the intended shot.--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).--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.--When adapting an existing production, keep useful views that still fit. A reverse angle that inherited-only the room may remain usable after the other host's face changes. A shared image containing that-host needs the new identity. Judge the visible relationship and carry the resulting reuse choices-into [Run Candidates](../../production/authoring.md#reuse-produced-work-explicitly).--## Let edited Takes meet through their shared world--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.--When the movement itself is the reference, connect a useful video excerpt alongside the target-identity or world inputs. [Motion references](video-direction.md#let-footage-carry-motion-that-matters)-explains choosing excerpts and assigning those inputs distinct responsibilities.--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.--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.--## Keep media provenance and visual role separate--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-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.--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).+| Capture | The same phone-video photographic language. |+| Person | Cast the other host with their own appearance within this shared encounter. |+| Shot | The two views form a conversation: the new host sits on the other side, looks toward their partner, and receives the microphone from the corresponding side. |+| Setting | Both cameras inhabit the same Korean street-side restaurant and palette; this camera sees a different sector of its architecture, furniture and activity. |++The painter makes a full new view. The shared world and conversational geometry connect the pictures even as person, composition and visible background change. The symmetry belongs to the encounter; the second camera sees the part of the place available from its position.++The relationship matters more than copying a backdrop. A two-person encounter can carry who faces whom, where the microphone enters and which part of the place each camera sees. Separate call or reaction feeds can instead establish different rooms; their shared fact is who addresses or responds to whom, not a common wall.++The first host view can also meet a product image in another request. In that picture, the host and much of the camera view continue, while her hands, the phone and its displayed product change. One reference can support very different kinds of variation because each new picture has its own intention. The [podcast and interview image examples](examples/conversation-images.md) show the actual prompts and inputs behind these relationships.++## Give each new picture the references it needs++A useful first camera image can establish person and place together. It may show one person, several people or the whole encounter. When another view needs that world, carry its atmosphere, palette, materials and spatial relationships into the view the new camera should see. Several Takes can then use the resulting images.++A new location can begin with a camera image that already places the people in that setting. Their established views can supply identity or styling; a product or continuing prop can supply its form and state. The new picture establishes the location and composition together, while the prior images carry the facts that persist across the move. A character reference can also carry identity directly into video direction when the new place does not need its own key image.++If one character leaves a living-room argument holding a phone, a hallway view can inherit the person's identity and the phone's relevant state when that moment merits an image. The furniture and camera angle of the living room have finished their job. An intentional change of clothes, time or setting similarly changes which facts the next picture needs to carry. A view may grow from the previous story view when its changing state matters, or branch from a character reference when earlier settings have nothing to contribute.++A portrait may contribute identity while clothes, action and place change. A product-holding variation may carry nearly the whole view while changing the hands and object. When there is no person, the picture can still draw on a product, place, graphic or composition reference. Choose the useful reference by the relationship the next picture needs. Keeping close to the image that actually knows that relationship also keeps incidental details from unrelated intermediate scenes from accumulating.++An existing image can serve the intended view directly. When the work asks for another picture, connect the images that carry its needed facts and describe their roles in the prompt. With several references, “reference 2” means the second image connected to this request; the actual image input gives that phrase its meaning. A request whose references already establish much of the picture may need only a short direction for the change. The selected image package owns the exact reference-input syntax.++Keep useful prompts and source images with the project when later views may need the same relationship. [Image direction](image-direction.md) owns the picture's casting, framing, palette and capture language; [Run Candidates](../../production/authoring.md#reuse-produced-work-explicitly) explain reuse of completed Outputs.++## Carry the shared world into motion++The image graph records visual facts to carry forward, not the video work's shot order or request boundaries. One camera image may guide a passage with several views or multiple Takes in the same world; several images may contribute different facts to one request. A video excerpt can carry performed action or camera behavior that a still cannot show; [video direction](video-direction.md#let-footage-carry-temporal-behavior-that-matters) owns those input choices and the requested action. [Voice and performance](voice-and-performance.md) and [B-roll](b-roll.md) own the resulting footage's roles in the work.diff --git a/skills/hypit/references/playbooks/craft/graphic-compositions.md b/skills/hypit/references/playbooks/craft/graphic-compositions.mdindex 096e0f19..e08086b8 100644--- a/skills/hypit/references/playbooks/craft/graphic-compositions.md+++ b/skills/hypit/references/playbooks/craft/graphic-compositions.md@@ -3,6 +3,7 @@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.+[Motion graphics](motion-graphics.md) owns how that picture changes over time.## Compose an idea, not a stack of decorations@@ -14,28 +15,42 @@ before the viewer reads the words.Coordinate the whole frame. A presenter's position can leave space for a board; the same accent canconnect Caption, an answer icon, a question mark and a reveal flash. Treat palette, occupied area andbrightness 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.+element looks attractive alone. Work with the actual material's framing and movement; the next+section explains how source direction and authored presentation can answer each other.Make the visual direction concrete before extending it across scenes. Translate a reference's vibeinto a few shared choices: palette, type, edges, depth and motion character. A small representativepassage can show those choices together with the actual footage. Carry the accepted direction intoshared Recipes or project styling so a later change reaches the related components consistently.-Let action demonstrate the claim. A rejected placement can show the object follow an attempted-drag and visibly return. Keep a developing-demonstration active while the speech explains it, with acceleration, contact and settling that-make the relationship perceptible. Preserve continuing objects across phases when the argument-continues through them.-Give graphic text its own job: identify, compare or emphasize what the picture needs beyond Caption.When removing a redundant heading or label, recompose the remaining content and its spacing. Theformer text slot need not remain an unexplained hole; the demonstration should still feel complete.+## Give material and graphics room together++Keep the generated or recorded scene, its camera view and the final Canvas in view as distinct+relationships. People interact with the people, props and setting in their scene. The camera frames+that scene. Authored media views, Caption and graphics organize the final picture. A recorded sign+can belong to the scene while an explanatory label belongs to a component.++Plan the useful room for recurring graphics when directing new footage. Translate that need into+camera facts: subject placement, visible body extent, gesture room, distance and background. Give+the image model those picture requirements; the future MG, editorial text and explanation remain+with their own components. [Image direction](image-direction.md#frame-the-image-for-what-it-will-become)+owns the wording. Accepted footage supplies concrete framing to work with: adjust its view, the+graphic or their shared arrangement according to what should remain legible.++Decide which contribution leads now. A small moving face can command attention while a large quiet+field supports it. Protect the mouth, meaningful gesture, product fact or text that carries this+beat. Placement, source crop, occupied extent and paint order all affect the result;+[Spatial layout](../../production/spatial.md) owns their geometry. The material's A-roll role gives+it no reserved region or permanent place behind everything else.++For a screen that carries the claim, [screen demonstrations](screen-demonstrations.md) owns the+choice between captured evidence and an authored explanation. Its view shares the Canvas geometry+and visual hierarchy of the surrounding composition.+## Put the right facts in editable structureUse authored text, exact fonts, geometry and state when wording, alignment, timing, data or repeated@@ -60,37 +75,11 @@ graphic role. Reconstruction preserves the useful recognizability and relationshreplace it with a new theme. Provenance alone does not make one image more visually truthful thananother. 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.-[Component design](../../production/component-design.md) connects that visual idea to semantic behavior,-useful author controls and its place in the actual composition.--The component owns its visual behavior and design. Source and Recipe supply the content, media,-events and directing choices that belong outside it. A one-off scene can retain its illustrative-text, palette and detailed layout internally; a shared treatment can expose the variation its uses-actually need. Independence gives a responsibility an owner, without requiring every design choice-to become an input.--## Expose meaningful control--A useful Surface offers the content and relationships the production needs. Derive its inputs from-the decisions the author will supply or revise: these may include content, placement, visibility,-semantic events or a chosen treatment. For reuse, expose the variation shared uses demonstrate;-internal geometry and animation can continue to realize a coherent fixed design.--`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.+## Carry the picture into the component-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.+A ranking board can share one visual owner when its rows move and retain state together; a label+and independent photo can remain peers. That boundary follows behavior, not the size or beauty of+the graphic. [Component design](../../production/component-design.md) owns the chosen boundary,+external inputs and author controls. [Motion graphics](motion-graphics.md) owns the change the+viewer experiences; [review](../../production/review.md#make-the-composition-work) tests how that+change reads with the actual material.diff --git a/skills/hypit/references/playbooks/craft/image-direction.md b/skills/hypit/references/playbooks/craft/image-direction.mdindex 8d0da5de..5d656277 100644--- a/skills/hypit/references/playbooks/craft/image-direction.md+++ b/skills/hypit/references/playbooks/craft/image-direction.md@@ -1,247 +1,95 @@# Directing generated images-Read this before writing or adapting an image prompt, including one inherited from another project.-An image establishes the person and world that a reference-conditioned video can bring to life.--UGC, podcast and street-interview work commonly share the same photographic foundation: the visible-credibility of a frame from real iPhone video, with an appealing person and a readable environment.-Use the full capture paragraph in `@hypit/gpt-image-kits/phone-ugc-v1`. Direct the particular person,-camera relationship and setting around that foundation. A change of format usually changes those-relationships while retaining the capture language. An invented or fantastical person can inhabit-this photographed world too.--## Compress the idea into decisive anchors--Study a reference as a coherent visual impression. Understand how the person, styling, camera-relationship and setting create its appeal, and which details carry that character. Keep useful-observations in the reference notes; distill them into the direction the new picture needs. Careful-observation makes concise prompting possible: the detail earns its place through what it contributes.--For social-video portraits, look first to Gen-Z styling and social aesthetics for language that-captures the closest-fitting look and presence. Soft goth, clean girl, coquette or relaxed streetwear-can organize hair, makeup, clothing and attitude together. Use the words that express this particular-person, combining descriptions where that is more accurate than a named style. The user's goal and-references still determine identity, age and defining features; the styling language articulates-the appearance to preserve or adapt. Where the brief invites new casting, it also offers a useful-starting point for an original look.--Make the choices that determine the picture explicit. Cultural background, age, intended complexion,-strength of attraction, a recognizable styling idea and the setting's palette can each change the-whole direction. Select them deliberately instead of leaving the important decisions at “a young-woman in a nice room.” A supplied reference can establish the facts it already contains.--A muscular Barbie-like woman, a nerdy student or a sailor-style outfit can also organize visible-qualities in a few words. “Creator” and “founder” describe a role; alone they give little direction-about appearance. Keep a role when it belongs to the work, and still cast and style the person.--Use specific detail where it preserves identity, expresses a useful relationship or settles a key-structure: exact product features, HYPIT lettering, a face's placement, or broad shoulders and-excellent head-to-shoulder proportions. A concise direction can be forceful and precise. Give the-image model the visual intention and decisive anchors, and let it realize the picture and organize-incidental detail within that direction.--When adapting a reference, recover its visual idea before rewriting its details. Relaxed collegiate-styling may carry what matters about a shirt; the exact fraction of forearm exposed by its rolled-sleeve may be incidental. If the sleeve exposes a featured watch, preserve that relationship. Keep-the details the new work depends on, and let its new person and camera realize the shared style.-More painstaking description does not by itself make the direction more faithful or attractive.--## Describe the picture being made--Translate the complete design into what this image should contain. A later comparison board may-motivate placing a person on the right. In the image prompt, describe that placement and a natural-scene relationship, such as a table entering the lower-left corner. The board's own content and-animation belong to its component. The image receives the visible consequence of the design.--High-level anchors still direct the picture: soft goth specifies styling, idol-like beauty specifies-the kind and strength of appeal, and a Korean street-side café specifies a recognizable setting.-Keep that compression. For an action or interaction, choose what actually appears. If water should-be poured, direct that action; if only a gesture is intended, describe the hand gesture itself.-Resolve figurative or uncertain wording when taking it literally would add the wrong prop or event.--The requested output determines what belongs. A photographed sign or a generated graphic can include-its intended lettering and symbols. A photographic source for a later composite receives its own-person, scene and camera view. [Direction and its inputs](../../production/system.md#give-each-part-the-direction-it-can-realize)-explains how these local instructions retain the whole design.+An image model can paint the visual world the work needs: a person in a camera view, a lived-in place, a product, an icon, or a fantastical event seen through ordinary footage. Each request directs a complete picture. The author gives it a subject, aesthetic force and visible relationships; the model realizes the details that make those choices into an image. References bring selected visual facts into that same act of painting.-## Four paragraphs, four responsibilities+For the common phone-video portrait, the [phone-UGC Kit](#use-a-concrete-capture-direction) supplies tested capture wording; the author directs the person, camera encounter and place. The [complete examples](examples/image-direction.md) show prompts alongside their results.-For a complete character-and-scene camera image, use this order:+## Two ideas behind every sentence-| Paragraph | Question | Direction |-| --- | --- | --- |-| Capture | What kind of photographed image is this? | The Kit's full fixed iPhone-video paragraph. |-| Person | Who should we want to watch? | Cultural background and age, strong attraction and a cultural or aesthetic comparison for that appeal, complexion, defining appearance, proportions and styling. |-| Shot | How does the camera see them, and what are they doing with whom? | Framing, distance, posture, face direction, placement, speech, gestures and useful relationships with props or other people. |-| Setting | What place surrounds them? | A recognizable place, overall palette, and a few useful structures, materials or objects. |+**A capable painter has visual habits.** “A person at a desk” leaves the face, styling, encounter and room to the model’s usual associations. A casting noun, the kind and strength of beauty, a hairstyle or the social character of a place can shift the whole picture. Choose the few dimensions that matter to this work and direct them clearly; the model can complete the rest.-These are paragraph responsibilities, not a form requiring a sentence for every possible attribute.-A hairstyle name can settle the hair; a styling idea and a memorable item can settle the outfit.-Related information can share a sentence. Keep each paragraph focused while considering the picture-together: wardrobe participates in the palette, and a table can explain an offset composition.+**A few decisive strokes carry the picture.** For a presenter that may be an arresting face and a clear camera encounter; for a product, its defining form and use; for an icon, a readable visual idea; for a place, a few telling objects and spatial relationships. These choices establish more than a long inventory of incidental details. Spend words where they change the image and let the model complete the rest. “Few” describes the number of important decisions, not a word limit. The [balcony portrait](examples/image-direction.md#japanese-sailor-on-an-apartment-balcony) shows the difference between authored anchors and details the model supplied.-The [balcony example](examples/image-direction.md#japanese-sailor-on-an-apartment-balcony) preserves-a successful complete prompt. Use it to see the amount and kind of direction that-produced the result, rather than turning every incidental detail in the image into another requirement.+When the work calls for a presenter people want to watch, direct attractiveness with conviction at the character’s actual age. Photographic credibility and exceptional beauty can coexist. Fatigue, comedy or a difficult expression can also be part of the character or moment when the story calls for them.-## Use a concrete capture direction+## Four paragraphs, four responsibilities-The Kit preserves the chosen capture paragraph verbatim. It establishes a frame from actual iPhone-video, the photographic surface, a clearly visible background, natural fine skin texture, natural-lighting and a coherent image. Carry this wording intact into phone-footage images; later paragraphs-direct this picture's content. Adding sensor grain, exposure falloff or elaborate lighting language-is an additional aesthetic choice, not a necessary completion of the capture paragraph.+For a phone-UGC image establishing a person in a scene, the tested starting shape is the Kit’s fixed **Capture** paragraph followed by **Person**, **Shot** and **Setting**. These are directing responsibilities, not a form to fill attribute by attribute. A reference may already settle a person or place, while a different kind of image may need a different shape altogether.-GPT Image 2 is the usual choice. Favor `2K` for a full-screen picture or video reference; `1K` often-suffices for an inset or small graphic. Set aspect ratio and resolution on the model's parameters.-The prompt concentrates on composition inside that shape. For an illustration, product photograph-or other explicitly different visual form, select capture language that serves that goal.+| Part | What the author decides |+| --- | --- |+| Capture | The photographic language; [the Kit](#use-a-concrete-capture-direction) supplies the tested phone-video wording. |+| Person | Who this is, why they are compelling, and the few appearance choices that make them particular. |+| Shot | What they are doing, whom they address, and how the camera meets their face, body and surroundings. |+| Setting | Where this happens, with a palette and visible details that make the place feel inhabited. |-The Kit assembles `person`, `shot` and `setting` after the fixed capture paragraph:+The parts influence each other: an outfit contributes to the palette; a table can make an offset framing feel natural. Keep each paragraph focused without treating the boundaries as walls.-```svml-<import as="text" from="@hypit/text@1"/>-<import as="ugc" source="@hypit/gpt-image-kits/phone-ugc-v1"/>+## Seven questions for a presenter image-<text:Render id="portrait-prompt" template={ugc.phone-ugc-v1}>- <text:Set name="person" text={portrait-person}/>- <text:Set name="shot" text={portrait-shot}/>- <text:Set name="setting" text={portrait-setting}/>-</text:Render>-```+For a complete person-and-place image, these questions help find the high-value decisions:-These slots take ordinary paragraphs, not individual appearance parameters. Pass `{portrait-prompt}`-to the image Surface and connect reference images there. For a derived view, a reference may already-establish person or setting; the Kit permits those blocks to be omitted. State the needed inheritance-and change in the relevant paragraph. Its package README owns the exact assembly interface.+1. What kind of captured image is this?+2. Who is this person, and what kind and strength of appeal should they have?+3. Which appearance choices make them recognizable rather than generic?+4. What ongoing activity or disposition can the next video moment continue?+5. How does the camera frame this encounter, including face, body, gaze and useful space?+6. What visible relationships make the place and the person belong together?+7. Which colors give the whole image its intended character?-## Make the person immediately compelling+One phrase can answer several questions; some are already answered by the brief or a reference. They are a way to notice what matters in this picture, not seven required sentences.-Begin an invented person's paragraph with the cultural background and age range you intend. State-the intended complexion when choosing it; a broad identity label need not settle it. A supplied-person's image and the user's description establish their identity and appearance.+## Cast the person with force-For an invented human presenter in this photographic style, **explicitly state strong beauty or-handsomeness, with an appropriate visual comparison, and explicitly include broad shoulders and-excellent head-to-shoulder proportions**. Preserve their force when revising. “Exceptionally,-strikingly beautiful, with the looks of a top Korean girl-group idol” directs both strength and kind-of appeal. “Idol-level polish” describes grooming and cannot replace that beauty direction.+When casting an adult presenter in this GPT Image 2 phone-video direction, start with **girl** or **boy** followed by the actual adult age. This tested wording has produced appealing, lifelike adult faces; the noun steers the portrait while the explicit age and role still define the person. For example: *a Chinese girl in her mid-forties, exceptionally beautiful, with the presence of a leading actress of her generation*; *an Indian boy in his late thirties, strikingly handsome, with the easy confidence of a leading actor in his late thirties*. When a reference establishes the person’s appearance, let it carry that identity into the current picture.-The shoulder and proportion wording is a deliberate structural anchor for these half-body portraits:-pinched shoulders beneath a large-looking head can undermine the intended human presence. Keep the-anchor across centered, offset, seated and standing views. Develop the appeal of a supplied person-while preserving their recognizable identity and physique. Animal and established character designs-use the appealing proportions and defining features that belong to them.+Give beauty or handsomeness both **strength and kind**. *Exceptionally, strikingly beautiful, with the looks of a top Japanese idol* carries more direction than *attractive*; a different age, culture or role calls for its own equally strong comparison. Cultural background, visual appeal and a social or aesthetic type—jirai-kei, soft goth, clean girl, a particular kind of founder—can work together, but only the choices that define this character need words. A role alone rarely casts the face.-Choose a few appearance anchors under the whole-person idea. Long straight black hair with bangs,-alluring goth eye makeup and a sweet-but-edgy beret can establish a person without an inventory of-facial measurements or garment construction. Overall makeup style, a strong eye-makeup emphasis and-the intended allure can work together. Keep the strength of these choices rather than replacing them-with general praise such as “well presented.”+Choose a few visible anchors that realize that direction: hair around the face, eye makeup or gaze, a memorable garment or accessory. For a half-body human presenter, *very broad shoulders and excellent head-to-shoulder proportions* is a useful structural anchor against the large-head, narrow-shoulder look. Its value is the proportion, not an instruction to expose every part of the shoulders.-Attraction is a positive casting goal. Photographic credibility does not call for automatically-adding fatigue, rough skin or an unflattering pose. Select a particular appearance because this-person and work need it. A cultural or styling anchor has a scope: goth can describe the person-while an ordinary classroom, balcony or café supplies their surroundings.+A portrait can establish a person’s identity, a chosen appearance cue or a useful camera view. Direct what the current picture carries from it and what changes in the camera view, styling or setting. [Reference relationships](generated-dependencies.md) show how an image can anchor another complete view while its person, composition and visible environment change.-## Frame the image for what it will become+## Choose an idle state for the encounter-The Shot paragraph makes the encounter visible. For a reusable, direct-to-viewer UGC image, explicitly-settle these relationships. The wording in the successful example provides a useful baseline:+A reusable character image gives the video a state it can continue. Speaking toward the viewer with a free hand gesturing is an ongoing activity, not a frozen pose; an alluring, curious or teasing presence can persist through several beats. A wide laugh or a startled face commits the image to one instant, which is useful when that instant is the shot’s subject. Let the intended performance decide.-| Relationship | Useful direction and its purpose |-| --- | --- |-| Framing and distance | A medium or close half-body shot, fairly close to the camera, makes the face, shoulders and gestures readable. Framing decides visible extent; distance decides the camera relationship. |-| Posture | Sitting on a chair or standing gives the body a clear arrangement. Choose the posture the scene needs. |-| Address and activity | Holding a handheld microphone and speaking directly to the viewer establishes an ongoing exchange. Choose a microphone or other prop when it belongs to that encounter. |-| Accompanying movement | With the free hand gesturing gives the speaking state visible life. Adapt this to the hands and objects involved; an exact finger pose usually adds little. |-| Frontal face | “Her face points straight toward the lens, with no head tilt or rotation.” Preserve this explicit wording for the reusable frontal speaking view. |-| Placement | State where the face belongs: for example, toward the upper-right part of the frame. Choose the position for this picture and its later composition. |-| Scene relationship | A table entering the lower-left corner can balance a person on the right and explain their placement. A seat, partner or body orientation can do this in another encounter. |--Centered, leftward, rightward, seated and standing images all retain deliberate framing and body-proportions. Plan shared space with later MG through the source camera view. Describe the actual-person and scene; author the later graphic in its component. An image made for a half-screen or-circular presentation needs a camera view that serves that crop. [Compositing](compositing.md)-owns those presentation relationships.--### Choose an idle state for the encounter--Idle is a readable exchange that can continue into different passages. Speaking, gesturing and an-engaging gaze belong in it. Give the person a useful state from which to perform. An elaborate-“about to say something outrageous” expression chooses a particular dramatic beat; use such a beat-when the passage earns it. Natural speaking gestures need no finger-by-finger choreography.--Choose direction from whom the person addresses:--| Encounter | Face and body relationship |-| --- | --- |-| Directly addressing the viewer | Keep the reusable frontal view explicit, including no head tilt or rotation, with an engaged speaking state. |-| Podcast partners | Look toward the partner, keeping the face usefully visible to this camera; preserve complementary positions and microphone relationships. |-| Interviewer and guest | Preserve the shared encounter and its gaze axis in the two-person image and derived close views. |+For a direct-to-viewer presenter, *the face points straight toward the lens, with no head tilt or rotation* gives a dependable starting view while the body can turn and the hands can work. Podcast partners or interviewees instead have a gaze relationship with each other. Their reference images should establish that relationship, with faces readable from the camera angle the work needs.-A deliberate story image can show a particular laugh or action. Opening and closing performance-beats belong in the relevant video passage. The reference supplies visual facts; the selected model-mode determines whether it is a literal first frame. See [video direction](video-direction.md) and-[conversation images](examples/conversation-images.md).+## Frame the image for what it will become-## Establish the place with a few details+Direct framing, camera distance, body arrangement, face angle and placement as one encounter. A close half-body presenter can make the face, shoulders and gesture legible; a wider view can carry an action or a second person. Place the face where the later composition needs it, while describing only the physical scene the image model should paint. A table, another person or a doorway may make an offset position natural when it also belongs to the story. An offset can also be a straightforward camera choice.-Begin the Setting paragraph with a recognizable place and give it an overall palette. Add the few-structures and objects that make this camera view specific. A Korean street-side café, navy blue and-yellow, with stairs, an entrance, textured walls, plants and railings gives the model a coherent-world to arrange. The prose can place the palette at the end while it guides the choice of details.+For a camera view that will sit alongside later MG, direct the photographed scene the viewer will see. An icon painted on a sign or phone screen belongs to that image and travels with it. A ranking icon meant to appear or move independently can be made as its own image Resource; a component can then place and animate that Resource, or draw the icon itself. Describe the person’s actual interaction with people and objects in their scene. Choose the source view for the body, gestures and setting the performance needs; [spatial fitting and crop](../../production/spatial.md) can present it in other viewports. [Graphic composition](graphic-compositions.md#give-material-and-graphics-room-together) owns its relationship with surrounding content.-Texture and spatial construction contribute different things. Wood grain varies a surface; a doorway,-balcony railing, shelving aisle or view beyond a window helps establish how a place continues. A wall-covered with many small notes can remain one flat plane. Choose actual spatial anchors rather than-adding more decoration merely to make the description detailed. A broad wall can naturally belong to-a well-chosen view. The person, setting and objects need not all express the same subculture or job.+## Establish the place with a few details-A useful object can carry several relationships: a half-eaten bingsu suggests a café visit underway-and adds color; the nearby table belongs in Shot when it explains the person's framing or interaction.-Keep the setting concise enough for the model to complete the incidental architecture and arrangement.+A setting should carry a social world, not serve as a color field behind the face. Name the recognizable place and a few details that explain why this person is there: café seating and a half-finished dessert, a record shelf continuing into an aisle, a classroom door and student posters. A view through a window or an opening behind the person can give the scene distance. Choose objects for their story and visual character, then let the model complete the ordinary remainder.-### Give the frame a clear color relationship+Give the place a deliberate palette. *Coral red and yellow* or *terracotta and green* can be carried by the actual architecture, clothing, plants and objects rather than painted as a uniform wall. A broad light or dark field can gain interest from the place’s real surfaces and contents—wood grain, tiles, shopfronts, foliage—when those belong to the scene. Describe color as color and material; the Kit already supplies natural-light capture language. Time of day, weather or a particular light event earns a place in the prompt when the story or reference depends on seeing it.-Choose the overall palette explicitly and consider it with the person's skin, hair and clothes.-Give the larger areas a useful relationship and let smaller colors support or accent them. Navy-clothing, terracotta architecture and green plants can separate the person from the setting while-belonging to one image. A place and a few material names can carry this direction without assigning-a separate color to every object.+## Use a concrete capture direction-For clean phone-footage images, prefer considered colors and material variation to an unchosen white-or flat-gray background. Avoid defaulting to broad white clothing against a broad white wall: that-combination can wash the person into the setting. Wood, tile, fabric and foliage can provide tangible-variation. The useful choice is the combination; a texture adjective cannot repair a weak palette.+For a phone-video frame, `@hypit/gpt-image-kits/phone-ugc-v1` preserves the tested iPhone capture paragraph. Keep that paragraph intact while directing the picture’s content in ordinary prose. A fantastical person can still inhabit a photographed world; an illustration, product render or other visual goal calls for capture language that serves that goal.-Keep lighting at the natural premise supplied by Capture unless the scene calls for a particular-light event. Avoid casually adding dim lighting, dark shadows, exposure falloff or sensor grain to-make the picture “more real.” Name hues directly when hue is what you intend. A local dark textured-wall or white trim is a surface choice, not a request to darken or brighten the whole image. Preserve-exact product and wardrobe colors, and choose their surroundings to support them.+The Kit assembles `person`, `shot` and `setting` after the fixed paragraph:-## Let references supply the facts they own+```svml+<import as="text" from="@hypit/text@1"/>+<import as="ugc" source="@hypit/gpt-image-kits/phone-ugc-v1"/>-Look at a supplied person before directing them. Their reference establishes identity; the Person-paragraph develops the styling and appeal this work needs. A parent view can establish the shared-place; an exact product reference establishes the product. Put these responsibilities in the paragraph-they affect, with the needed preservation and change. Connect actual reference Resources on the model-Surface in the stated order; mentioning an image in prose does not supply it.+<text:Render id="portrait-prompt" template={ugc.phone-ugc-v1}>+ <text:Set name="person" text={portrait-person}/>+ <text:Set name="shot" text={portrait-shot}/>+ <text:Set name="setting" text={portrait-setting}/>+</text:Render>+```-Keep a derived view as short as its inherited facts allow. A close view can change attention and crop;-a product-holding view can change hands and prop state while keeping the camera and setting. Preserve-the capture language. Another angle may reveal different surroundings within the same place.-[Reference relationships](generated-dependencies.md) and [conversation examples](examples/conversation-images.md)-own these branches; [Transformations](../../creation/transformations.md) owns a swap across the video.+These slots carry paragraphs, not individual appearance fields; the Kit allows `person` or `setting` to be omitted when a reference already supplies those facts. Pass `{portrait-prompt}` to the image Surface and connect reference images there. GPT Image 2 is the usual choice for this direction; `2K` often serves a full-screen picture or video reference, while `1K` can serve an inset. Aspect ratio and resolution are model parameters, not prompt words. The Kit package README owns its assembly interface.++## Let references supply the facts they own-## Keep successful direction useful+A supplied portrait can establish identity; a camera view can establish a shared place; a product image can establish the product. Say what each reference contributes and what the current picture should show, and connect the actual images on the Source. When references already provide the difficult visual facts, the prompt can concentrate on the new encounter or viewpoint. The model paints that whole view, carrying forward the facts the work needs and realizing the new ones.-Judge a picture first by the intended person, appeal and feeling, then by the framing, color and-interactions the video needs. Use that understanding when directing another image. Preserve useful-results with their exact prompts, references and known model settings. Distinguish a proposed rewrite-from the wording that actually produced an image. A successful rendering of individual leaves,-tiles or reflections does not make their exact arrangement necessary in the next prompt.+Carry the phone-video capture direction into another view when the work keeps the same photographic world. [Reference relationships](generated-dependencies.md) owns multi-view branches; [transformations](../../creation/transformations.md) owns a face or product swap across the video.-Carry accepted material into the production. When a new request calls for a different image, revise-the choice responsible for that difference while retaining the direction that still serves the work.+The finished prompt should read as one picture with a clear subject, visible relationships and visual character, with words spent on the decisions that make it useful to this work. The examples preserve complete prompts as evidence of those particular pictures, not as sentences to transfer unchanged into every new one.diff --git a/skills/hypit/references/playbooks/craft/motion-graphics.md b/skills/hypit/references/playbooks/craft/motion-graphics.mdnew file mode 100644index 00000000..56855f26--- /dev/null+++ b/skills/hypit/references/playbooks/craft/motion-graphics.md@@ -0,0 +1,68 @@+# Directing motion graphics++Read this when authored graphics, effects or a coordinated scene change the picture over time.+Motion graphics can explain a relationship, make a comparison felt, give a joke its timing or+establish a visual attitude. The work may use a small accent, a moving presenter and diagram,+or an entire animated passage. [Graphic composition](graphic-compositions.md) owns the hierarchy+of the picture they share; this page owns what their changes do to the viewing experience.++## Direct the change, not just the entrance++Understand what the viewer sees before an event, what changes, and what remains afterward. A board+can accumulate answers; a picture can be picked up, moved to a slot and rejected; a camera view can+recede while another idea takes the foreground. In each case the action gives the next state its+meaning. A satisfying entrance cannot compensate for a settled state that fails to show the claim.++Follow the identity of an object through its changes. When a card becomes an attachment, the same+card can keep its image, shape or trajectory; when a demonstrated interface changes style, its+recognizable controls can remain while its treatment changes. That continuity lets the audience+understand *what changed* without learning a new diagram at every beat. A clean cut is also a+strong handoff when the next idea is better understood immediately than through a journey.++An effect can serve feeling as well as literal explanation. A springy arrival may make an answer+playful; a sudden hard replacement may give a claim force; a slow, precise construction may make a+relationship easier to study. Choose the motion character that belongs to this film, then give the+result enough visible life for its content to register. The appropriate hold and pace depend on+the words, sound, picture size and amount the audience must read.++## Make the motion belong to one visual language++Palette, type, edges, texture, depth, motion and sound can reinforce one another. A retro cartoon+treatment, a precise mathematical diagram and a spatial 3D scene call for different choices about+weight, path, perspective and rhythm. Their names are creative directions, not renderer or component+types. Extract the actual relationships that make the chosen style convincing, and carry shared+decisions into the project's Recipes or ordinary component dependencies when several scenes use them.++Keep the scene's meaningful objects complete through a restyle. If a folder's contents, an editor's+controls or a comparison's result carry the idea, preserve their job as the look changes. Recoloring+only the outer panels changes less than the audience may think, while removing a label can require+the remaining layout to be recomposed. The film's Treatment owns its particular palette, ornament+and attitude.++Work with source media as part of that language. A moving viewport changes how an existing Take is+seen; it does not change the Take's performed time. An independently moving image, a drawn border+and a caption may share a moment without having the same visual owner. When footage and graphics+must move as one scene, their shared geometry can be directed together. [Performance](../../production/performance.md)+owns the current Timeline footage, and [component design](../../production/component-design.md)+owns the implementation boundary.++## Give events and movement different jobs++An explanation, reveal or comparison can respond to a Script Selection or Moment; a silent animated+passage can use authored time. The reference locates the behavior and its meaningful changes in+the work; travel, settling, texture and secondary motion can be designed locally around them.+[Timing](../../production/timing.md) and [component design](../../production/component-design.md#let-meaning-drive-the-behavior)+own the exact projection and author inputs.++Derive related movement from the relationships it depicts. A pointer arrives at the control it+presses; a badge follows the object it labels; a rejected drag returns from the place it reached.+That keeps a layout revision from breaking the visual action. Coordinate entrance, response,+persistence and exit across a scene, while leaving independent Caption, sound or media contributions+free to serve their own roles.++Inspect the changing passage with its actual material and sound. Exact frames can show whether a+shape, overlap or settled state reads; playback reveals weight, pace and whether the handoff lands.+Judge the effect at delivery size and in the neighboring picture, including the moment after its+most impressive motion. [Snapshots](../../production/snapshots.md) and+[review](../../production/review.md) provide those views; [drawing](../../production/component-visuals.md)+owns how the selected visual behavior is rendered.diff --git a/skills/hypit/references/playbooks/craft/screen-demonstrations.md b/skills/hypit/references/playbooks/craft/screen-demonstrations.mdnew file mode 100644index 00000000..7f0cee11--- /dev/null+++ b/skills/hypit/references/playbooks/craft/screen-demonstrations.md@@ -0,0 +1,51 @@+# Directing screen demonstrations++Read this when a website, app, terminal, editor or other screen is part of what the viewer must+understand. A screen can document an actual state, show an action with its consequence, or stage+an explanation of a relationship. Decide which of those jobs this passage needs before choosing+its material or visual treatment.++## Choose the evidence the claim needs++A screenshot makes wording, arrangement or a particular result available to read. A recording+preserves an interaction and the interface's actual response. An authored component can isolate a+concept, choreograph an example or keep changing labels and states editable. These choices can+coexist in one passage: an actual product recording can establish the behavior, while surrounding+graphics explain what to notice. A still can also move under a viewport to guide attention across+its existing contents; that motion expresses a view of the still, not a recorded interaction.++When exact wording, data or behavior is the claim, use material that establishes that fact and keep+its source identifiable in the project. When the screen is an illustration, direct the invented+states and actions so the viewer understands the idea they stand for. The film may move between+evidence and illustration, as long as their roles remain clear in the argument. In one making-of+piece, actual Studio footage showed the working interface while an authored chat-and-pointer scene+explained how a request becomes an attached reference. Their different jobs guided the choice of+material in that work.++## Stage the useful view++Choose the part of the screen that carries the fact or action. The audience may need the whole+interface for orientation, then a closer view to read a control or notice a change. A crop, zoom,+cursor or highlight should guide attention while preserving enough context to know *where* the+action happened. Judge type and controls at the video's delivery size; a sharp full-resolution+capture can still be unreadable when shrunk into a phone-sized inset.++Give an interaction a comprehensible before and after. Its useful states might include a target,+an action, visible response and enough time to register the result. An edit can begin with the+result and return to the cause; the important relationship is what the viewer can infer. When the+page scrolls, distinguish the moving page or inner list from movement of the viewport, device or+whole screen card. Those motions say different things about the interface. A real recording can+carry the interface's own pace; an authored demonstration can place its meaningful changes on the+work's semantic events.++Treat the screen's surrounding picture as a directing choice. A bare crop can give the interface+authority and reading room; a photographed device can locate it in a person's world; a graphic+frame can connect it to the film's visual language. Preserve the readability of the actual screen+while deciding what the presenter, Caption and other graphics contribute beside it.+[Graphic composition](graphic-compositions.md) owns that shared hierarchy; [motion graphics](motion-graphics.md)+owns the animation around or within an authored demonstration.++[Browser capture](../../production/browser-capture.md) owns saving a real page or recording,+[Media presentation](../../production/media-presentation.md) owns its playback and crop, and+[component design](../../production/component-design.md) owns an editable screen scene. Choose the+realization that serves this passage's screen role.diff --git a/skills/hypit/references/playbooks/craft/sound-mix.md b/skills/hypit/references/playbooks/craft/sound-mix.mdindex 72854889..d691b2d7 100644--- a/skills/hypit/references/playbooks/craft/sound-mix.md+++ b/skills/hypit/references/playbooks/craft/sound-mix.md@@ -1,77 +1,70 @@# Sound and mix-Read this when speech, music, ambience, and sound effects must work together across a passage or the-complete Film. Voice identity and the source of spoken performance belong to-`voice-and-performance.md`.--## Give each layer a dramatic job--Treat the soundtrack as a composition of independently authored contributions:--- **speech** carries words, performance, and intelligibility;-- **music** carries continuous pace, mood, tension, release, and structural change;-- **ambience** gives places and edits a believable acoustic world;-- **sound effects** answer discrete visible or editorial events.--Choose sounds for what the new piece is doing: a reveal can earn a short accent, a comparison can-share a recognizable motif, and a transition can carry the music into the next idea. Let the video's-character guide the sound palette. The Treatment describes these choices; the Source expresses them-with ordinary audio Resources and Tracks.-An audio library, generated sound, recorded material, or an earlier accepted Output can all supply a-layer; choose from the work's need rather than treating origin as an audible category.--## Let speech organize the available space--In a work with dialogue or narration, every required word should remain effortless to understand on-ordinary phone and laptop speakers. Shape music, effects, and ambience around consonants, names,-numbers, claims, punchlines, and the CTA. A louder layer is not automatically more exciting if it-makes the argument disappear.--Use level changes, fades, arrangement gaps, frequency balance, or ducking when the music should yield-to speech. Let an intentional pause, reveal, or montage earn a fuller musical moment. When a passage-has no speech, the other layers can occupy more space without implying that every silence needs to be-filled.--Normalize each selected source into media the program can place, then author its audible level and-span. Normalization prepares a source; it does not decide the creative balance or master the complete-Film. Keep speech, music, ambience, and effect families independently inspectable until their-relationship is understood.--## Attach sound to meaning--Continuous music usually follows a structural passage or the whole program. Ambience follows the-world and may bridge picture cuts that remain in one place. A sound effect follows the perceived-event that gives it meaning: contact, arrival, state change, reveal, transition, or completion.--Use Script Selections and Moments when the sound belongs to spoken meaning. Use clock time when the-event is genuinely independent of speech. The final accepted speech alignment locates semantic-events in 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 Item 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-can bind a montage, and a speaking Take can remain audible while B-roll or MG changes the picture.-Conversely, a change of place, speaker perspective, narrative state, or designed silence may deserve-an audible transition even when the picture changes gently.--Give speech its complete phrase and let effect tails finish naturally. Use fades and overlaps to-carry the intended handoff. Keep the mix coherent across the piece: clear speech, a consistent sound-palette, and emphasis reserved for the moments that deserve it.--For an existing performed passage, [Sound](../../production/sound.md) supplies local Uses for gain,-silence and source handoffs while retaining its playback position. A crossfade Style names the two-sources it blends; the selected Window controls its duration. Independent music and effects keep-their own Audio Tracks.+Read this when deciding what the audience should hear across a passage or the complete Film, and+how the work's existing sound relates to added music or effects. [Voice and performance](voice-and-performance.md)+owns who performs the words and where that voice comes from.++## Start with the sound the material already carries++In speaking-video A-roll, the person's picture, words and voice belong to the same performed Take.+Its sound continues at the current Timeline position while B-roll, graphics or a different view+changes the picture. Audio-only A-roll likewise supplies performed speech, with its picture authored+separately. A wordless performance may carry its own sound or be silent. Present the selected Take's+audio through [Sound](../../production/sound.md) according to what this passage should actually play.++B-roll can be a still, a silent video, or video with useful source sound. Its visual role alone does+not decide whether the audience hears that sound. A lifestyle shot might contribute a particular+door, footstep or burst of laughter; a picture covering a presenter's explanation may contribute no+audio at all. [Media](../../production/media-presentation.md#include-sound-deliberately) makes source+audio an explicit choice, leaving the selected performance voice available beneath a silent picture.++Listen to what the chosen material already contributes before adding sound. Music can carry pace,+mood or a change of thought; a short effect can give contact, reveal or transition an audible edge.+A sustained environmental sound can locate a place or connect cuts when the material itself does not.+These describe jobs in the work, not separate layers to fill. Environment may already be audible in+the performance; its duration alone does not make it a different kind of asset from an effect.+Designed quiet can be just as expressive as an added sound.++Hypit provides ways to prepare, place and mix audio, not a maintained stock collection of BGM,+short effects or long environmental sounds. Choose or make the particular material the work calls+for from supplied, recorded, generated or otherwise available sources and project Outputs. Treatment+captures why it belongs; Source and the chosen components express its use.++## Shape what leads the ear++When speech carries the idea, let the important words be readily understood in the finished mix.+Music and effects can yield around a name, number, claim, punchline or quiet reaction, then take+more space in a pause or a passage led by action or music. Set that relationship through level,+placement, fades, arrangement and the selected source, rather than assuming every moment needs the+same balance. Normalization prepares a source; the audible balance is decided in the composition.++Give each added sound an expressive reason. A comparison can share a motif; a reveal may earn one+precise accent. A tactile process may be better carried by its small contact sounds than by a large+impact. Repeating an effect because another cut occurred can exhaust its meaning; variation is useful+when the event's dramatic role changes. Let the piece's character guide the palette.++## Attach sound to the event it answers++A sound responding to spoken meaning can follow a Script Selection or Moment, so it moves with the+accepted performance. A sound belonging to a component's own entrance, state change or handoff can+follow that event within the component. Music or another independently directed event can occupy+an authored span of the Film. Choose the time relationship from what makes the sound happen; the+same visual and audible event can share a cause without being forced into separate timing schemes.++The owner follows that relationship. [Sound](../../production/sound.md) presents audio from placed+Takes; [Audio Track](../../production/audio-presentation.md) places independent audio; Media or a+project component can publish sound coupled to its own picture and events. Film includes the wanted+audio contributions explicitly. These are composition choices, while the installed packages own+their exact playback, trigger and gain syntax.++## Preserve continuity across picture changes++A picture cut need not cut the acoustic world. Room tone can continue across views of one place,+music can bind a montage, and a speaking Take can remain audible as another picture takes the frame.+A change of place, speaker perspective or narrative state may instead call for an audible handoff+even when the picture changes gently. Follow the listener's sense of the encounter.++Let speech, source action and effect tails meet in the rhythm the scene needs. Use silence, fades or+overlaps where they make that handoff audible. Review the actual Film where these sounds coexist:+the chosen voice remains clear when it carries meaning, an effect belongs to its event, and the+soundtrack retains the work's intended character across the passage.diff --git a/skills/hypit/references/playbooks/craft/video-direction.md b/skills/hypit/references/playbooks/craft/video-direction.mdindex 32b4e285..c3bd48a2 100644--- a/skills/hypit/references/playbooks/craft/video-direction.md+++ b/skills/hypit/references/playbooks/craft/video-direction.md@@ -9,6 +9,49 @@ they are saying and draws someone into the thought. Voice, expression and movemerelationship together. Expressiveness concerns how clearly the attitude comes through; it can beoutgoing or restrained.+## Let footage carry temporal behavior that matters++Choose generation inputs from what the new shot must actually realize. A still can establish a+person, object, place or composition; prose can direct an action and its expressive purpose. When a+particular unfolding in time is essential to the result—its performed rhythm, path, contact,+coordination or camera relationship—and prose and stills would lose that information, use the+relevant source footage as a video reference to a model that accepts it. This judgment follows the+action the work needs, whether or not the user names a generation method. A broadly described action+can leave more freedom to the model when its exact movement is not the point.++Replacing a person is a common case; the target may instead change an object, world, words or sound.+A comic speaking performance can depend on the relation between vocal phrasing, face, gesture and+camera angle; dance on coordination, a fight on contact, and a fixed-camera mishap on how its cause+and payoff develop within the view. Watch and listen to learn what the source contributes. Its vocal+manner can inform direction, while Script and [voice direction](voice-direction.md) establish the+target's words and voice. The video reference can carry temporal behavior while image references+establish the new visible facts and the prompt directs their relationship.+[Transformation](../../creation/transformations.md#reshape-an-event-from-footage) owns what the+new work keeps and reshapes. Watching a reference to understand a work is distinct from connecting+a selected excerpt as an actual generation input.++Choose an excerpt that contains the useful action and, when relevant, its preparation or settling.+Its range follows the relationship to preserve, the intended new duration and the selected model's+reference limits. Connect the actual footage in Source; describing it in prose does not supply+its temporal behavior to the model. The selected model and Provider determine supported combinations+and media requirements; read their installed vocabulary and package documentation for the exact+request, including any person-reference metadata.++For a longer action, distinguish the duration of source footage the model can accept from the+duration it can produce in one request. Use one request when the model's capability and the work's+continuity allow it. A forty-second fight might contain several exchanges and reversals, or its+uninterrupted choreography might be the point. If separate requests serve the work, select excerpts+around meaningful action or camera relationships and carry forward the target+people, objects and world through useful references. A literal boundary frame helps when that exact+continuity is intended; it is not needed for every new passage. The accepted outputs establish the+target's actual time. When uninterrupted continuity is essential, use a capability that can carry+it or explain what an edited interpretation changes. When an accepted wordless action carries the+passage, [empty Segments](../../production/media.md#empty-segments-use-their-media-boundaries)+let that material establish its time without word tokens.++[Reference relationships](generated-dependencies.md) owns how images carry identity and world+forward across requests. This page owns the decision to give a video request temporal evidence.+## Direct the reason for an actionGive the passage a clear expressive intention, then specify the few details that decide how it@@ -17,7 +60,7 @@ a discovery with a friend, weighing an ambitious claim with skeptical interest,roasting something they know well. Such directions suggest voice, expression, posture and rhythmtogether. Their value is the performable relationship they contain.-As with [Image direction](image-direction.md#compress-the-idea-into-decisive-anchors), high-level+As with [Image direction](image-direction.md#two-ideas-behind-every-sentence), high-levellanguage should carry sensory direction. The model can realize "admiring but incredulous" across awhole passage. Words such as "lively" or "expressive" set an energy level; the speaker's particularresponse to the meaning gives that energy direction. Locate the consequential thought in the Script@@ -125,13 +168,28 @@ An encounter also has edges: someone interrupted can first be occupied, and somebegin to leave. Small causes make a clip feel like a piece of life rather than a pose bounded by theencoder.+## Prepare footage for subject isolation++When the work needs a moving silhouette, choose a background-removal method that can process the+actual footage. For new generation, a continuous, evenly lit chroma backdrop can support a chosen+keying workflow. Choose a color separated from the person's hair, clothing and carried objects;+direct the visible body extent, performance and stable backdrop as facts of this recording. This+is a material-preparation choice for that use. Existing footage can instead use a suitable matting+capability, and an opaque camera view can remain useful through cropping and reframing.++The moving result needs its own alpha-producing operation. A transparent reference still alone+does not establish transparency in generated video. Keep the original when the final work also uses+its setting. [Media preparation](../../production/media.md#keep-original-and-processed-material-explicit)+owns processing, alpha-preserving normalization and explicit use of those outputs. Judge the moving+edge against its intended background, including shoulders, hair, hands, spill and changes in opacity.+## Give each input its own responsibility| Input | Responsibility || --- | --- || Character-and-scene references | appearance, setting, framing and the physical state to preserve || Product, interface or other factual references | the visible facts that need continuity or exactness |-| Motion or camera video references | temporal behavior whose phrasing, coordination or path should guide the new shot |+| Source-footage references | performed, physical or camera relationships whose timing should guide the new shot || Recurring voice references | a speaker's intended voice identity when the model accepts them || Script dialogue | the exact words, intended pronunciation and speaking turns for a visible performance || Prompt Kit or Recipe | a reusable prompt relationship that fits this kind of work |@@ -187,28 +245,6 @@ Read the selected template's wording when choosing its Recipe. Composition, cameperformance and gesture choices shape different aspects of the footage. Choose them to support theintended delivery, and use action Text for the passage's particular meaning and reactions.-## Let footage carry motion that matters--When the defining value of a reference is its movement, let a video reference carry that evidence to-an appropriate video model. Dance phrasing, coordinated body action and a distinctive camera move-can be easier to preserve through footage than through a long verbal reconstruction. Understand what-makes the movement work, then state which motion to follow and which person, setting or appearance-to change. The reference supplies temporal behavior; the prompt and other references direct the new-visible result.--Choose a useful excerpt around the complete action and its preparation or settling. Size it using-the source passage, the target's intended duration and the selected model's actual reference-duration,-count and size limits. A long reference can yield several purposeful excerpts. Preserve continuous-action where it matters, and use natural editorial boundaries where separate requests make sense.-Connect the actual video as a reference input; an excerpt mentioned only in prose is not an input.--The same [reference relationships](generated-dependencies.md) apply: each image, video or audio carries-specific facts, and the nearest useful references guide the next request. Image references can supply-the target identity or world while video supplies movement. The selected model and Provider determine-which combination is supported. Read their installed vocabulary and exact media requirements,-including any declared person-reference metadata, before submitting. Motion reference is another-way to direct capable generation, alongside text, camera images and voice references.-## Direct camera and cuts as part of the passageFor ordinary direct-to-camera social video, prefer pause-trim jump cuts at phrase boundaries. This@@ -227,6 +263,13 @@ the model relationship and direction that preserve that action. See[Reference relationships](generated-dependencies.md) when deciding which visual or motion evidenceshould condition each request.+When supported by the selected model, several camera images can guide one request through different+views or locations. Direct which people, settings and states each image contributes and how the+passage develops among them. Reference images in this relationship guide the generated footage;+they become literal first or last frames only when that is the chosen generation relationship.+Choose the request's span from the intended performance and the model's supported duration and+reference inputs, not from a one-image-per-shot correspondence.+A prompt-directed jump cut asks the generator for an edited rhythm; it does not inspect or trim thereturned media. When produced footage needs a deterministic cut, speed change or trim, use thecorresponding media operation and align the edited result before it becomes a SemanticTake.diff --git a/skills/hypit/references/playbooks/craft/visual-continuity.md b/skills/hypit/references/playbooks/craft/visual-continuity.mddeleted file mode 100644index 455274c0..00000000--- a/skills/hypit/references/playbooks/craft/visual-continuity.md+++ /dev/null@@ -1,42 +0,0 @@-# 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, palette, material language 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.mdindex b39f5b55..098f01b0 100644--- a/skills/hypit/references/playbooks/craft/voice-and-performance.md+++ b/skills/hypit/references/playbooks/craft/voice-and-performance.md@@ -1,24 +1,25 @@# Voice and performance-Read this when deciding who performs spoken material, how a recurring person keeps one voice, or-whether an off-screen passage continues an A-roll performance or uses independent speech.+Read this when deciding what performance carries a passage, how a recurring person keeps one voice,+or whether an off-screen passage continues an A-roll performance or uses independent speech.[Voice direction](voice-direction.md) owns casting an appealing voice and writing its direction.## Let the Segment reveal the A-rollA Segment is one authored passage in the Script. Before production it has identity and meaning but no-seconds. In Hypit, A-roll names the performance that makes a spoken Segment time-bearing. It can be-a visible A-roll whose picture and sound are performed together, or an audio-only A-roll whose-independent speech carries the passage while other Tracks supply the picture.+seconds. A-roll names the performance carrying that passage. Its prepared media supplies duration;+spoken words acquire local timing through semantic preparation. Visible performance can carry+picture and sound together; audio-only performance carries the passage while other contributions+supply its picture.-Performing the Segment gives that passage its duration and local word times. Timeline assembly-places it within the complete work, ordinarily after the previous Take, or at an authored position.+Timeline assembly places the prepared Take within the complete work, ordinarily after the previous+Take, or at an authored position.The work can also contain graphics-only passages before, between or after those performances.-[Tracks](../../production/tracks.md#place-prepared-takes-on-the-timeline) owns the exact+[Timeline authoring](../../production/timeline.md) owns the exactSemanticTake assembly and projection mechanism.-This gives a practical question: **who is speaking this Segment?** For visible A-roll, that person's-generated Take carries words, mouth movement, gesture, gaze, delivery, picture, and sound together.+For spoken work, ask **who is speaking this Segment?** The selected visible performance carries+words, mouth movement, gesture, gaze, delivery, picture, and sound together.In a multi-person exchange, the speaking performance can include listeners, several turns, or cameracuts while still carrying one Segment. The number of people visible in the frame does not determinehow many semantic clocks exist.@@ -34,18 +35,29 @@ occupy the Timeline directly, with no Take. Choose from the content the passage## Keep the performance role separate from the picture-A-roll is not the bottom layer, the largest rectangle, or the currently visible face. Its-SemanticTake retains the role when its picture is full-frame, one half of a split, a circular inset,-a moving cutout, or completely covered by B-roll or MG. A large app recording can be the primary-picture while a small presenter in a corner supplies the passage's words and timing.+A-roll identifies a performance's role in the work. Its accepted material, Script relationship and+Timeline placement persist while the author changes its visual use. The picture can lead the frame,+share space, appear more than once, become part of a diagram or leave the picture entirely. A large+app recording can lead attention while a small presenter supplies the passage's words and timing.+Several such changes can happen within one Take; a visual treatment can also continue across Takes.The covering B-roll may even show the same person doing a silent lifestyle action. Seeing a personwhile hearing words does not by itself make that picture the speaking Take or create a new speech-source. More fundamentally, the sound already belongs to the A-roll performance that created this-Segment's semantic time. B-roll changes or supplements the visual answer; it does not inherit the-speech merely because a person appears in it. Follow that positive ownership relationship through-the composition. [Compositing](compositing.md#choose-an-a-roll-presentation) owns the full-frame,-split, cutout and circular presentation choices.+source. Sound presents the placed performance's audio, while the visual contribution chooses what+to show. The same source clip can also serve as an independently timed replay or example elsewhere.+Its role follows that use; size, crop, transparency and the presence of a face do not establish it.++Follow the relationship the picture needs: [Performance](../../production/performance.md) and project+scenes can present the current Timeline footage; [Media](../../production/media-presentation.md)+receives independently supplied material and playback choices. A change of emphasis can be a direct+cut, a held arrangement or a continuous motion. Decide from the idea and viewing rhythm. For a+continuous move, retain the source playback position while directing the viewport's motion; for a+direct cut, make the two intended states meet at the chosen event. Speech remains independently+connected through [Sound](../../production/sound.md).++The [presenter-led explainer guide](../formats/presenter-led-explainer.md) develops the whole-work+relationship among performance, demonstration and graphics. [Graphic composition](graphic-compositions.md) owns+their visual hierarchy, and [Spatial layout](../../production/spatial.md) owns geometry and fitting.## Let neighboring A-roll performances keep their time@@ -69,23 +81,34 @@ choice for creator speech.## Give a recurring person one accepted voice+When the intended work retains a person's recorded delivery, prepare that passage and align its+actual sound to Script; its picture, if retained, is available to Performance. A supplied recording+may instead guide a new performance or provide a short Voice Reference. Voice Design can make such+a reference when a new performance needs one and none was supplied; Voice Clone can then perform+independently narrated lines from Script. The intended use of the recording, not its mere presence,+decides which relationship holds.+A **Voice Reference** is an ordinary accepted audio Resource that establishes a person's vocalidentity. Reusing that Resource wherever the same person performs is what carries the relationshipthrough the production.-Give each recurring person who speaks their own Voice Reference. A silent listener does not acquire-a voice merely by appearing in the picture; when that character speaks elsewhere, their own-reference follows them into that performance.+For newly generated performances, give each recurring speaker their own Voice Reference. A silent+listener does not acquire a voice merely by appearing in the picture; when that character speaks+elsewhere, their reference follows them into the new performance.When the user supplies the exact private voice they want, prepare a clean representative excerpt asthe Voice Reference. Otherwise use [Voice direction](voice-direction.md) to cast the character throughVoice Design and choose its sample line. A public character type or an imagined voice can be designeddirectly.-About five seconds of clear, natural speech is usually enough to establish a useful reference while-remaining easy to reuse across models. Choose words that exercise the delivery the work needs. Keep-the sample free of other speakers, music, clipping, heavy room echo, and long silence. The selected-model's documentation owns any exact count, duration, or format limits for its references.+For a newly cast person, a short designed sample is a strong starting point: it establishes a usable+voice at modest generation cost and stays easy to carry into speaking-video requests. About five+seconds of clear, natural speech usually gives the model enough vocal identity without spending+reference duration on a finished passage. Choose words that exercise the delivery the work needs;+keep the sample free of other speakers, music, clipping, heavy room echo, and long silence. When one+video request includes several speakers, give each a compact reference and keep their combined+duration within the selected model's reference-audio limit. The selected model's documentation owns+exact count, duration and format limits.Once accepted, reuse that same Resource wherever the same person must sound like themselves.@@ -101,9 +124,11 @@ Voice Design or supplied audiovisible A-roll audio-only A-roll```-An A-roll-capable video model receives the reference while generating the person's visible speaking-Take. Voice Clone receives the same reference when the work genuinely needs that person to speak as-an independent audio source. These are two uses of one ordinary Resource, not two voice identities.+An A-roll-capable video model receives the short reference and the actual Script while generating+the person's visible speaking Take. Voice Clone receives the same reference and the passage's Script+when the work needs independent speech; it generates that passage's audio, whose length follows the+passage and the selected speech model's request limits rather than the short reference's duration.+These are two uses of one ordinary Resource, not two voice identities.A work may combine them. A host can perform visible A-roll and later narrate a passage that has nounderlying on-camera performance; using the same Voice Reference makes both sound like the samediff --git a/skills/hypit/references/playbooks/craft/voice-direction.md b/skills/hypit/references/playbooks/craft/voice-direction.mdindex 5a0753e3..19b4bc4c 100644--- a/skills/hypit/references/playbooks/craft/voice-direction.md+++ b/skills/hypit/references/playbooks/craft/voice-direction.md@@ -14,7 +14,7 @@ creator supplies context; still choose what this particular person sounds like.voice" describes its relationship to the casting. Name the appealing sound chosen for thatrelationship so the voice model has a vocal character to realize.-As in [Image direction](image-direction.md#compress-the-idea-into-decisive-anchors), use high-level+As in [Image direction](image-direction.md#two-ideas-behind-every-sentence), use high-levellanguage that carries sensory information, then make the decisive qualities specific. "Magnetic"states the desired appeal; a clear, youthful tone and nimble, teasing phrasing begin to express it.Pitch, vocal weight, brightness, softness or grain are casting choices, not interchangeable words@@ -75,22 +75,25 @@ photo? Okay, now you've got my attention." A considered observation can suit theThe line should make the intended manner useful to the thought, rather than merely name the product.Write the intended pronunciation for unfamiliar names in Script before using the line as a sample.-Voice Design uses that line to establish the reusable voice. The finished passages receive their-own dialogue and direction. [Voice and performance](voice-and-performance.md#give-a-recurring-person-one-accepted-voice)-owns reference preparation, reuse and the choice between visible A-roll and independent speech;-the selected model's package documentation owns its exact inputs.+Voice Design turns that short line into a reusable Voice Reference. A speaking-video model can use+it while performing the finished Script; a passage built around independent narration can use the+same reference through Voice Clone. The casting line and the finished passage have different jobs.+[Voice and performance](voice-and-performance.md#give-a-recurring-person-one-accepted-voice) owns+reference preparation, reuse and that performance choice; the selected model's package documentation+owns its exact inputs.## Let one voice express different thoughtsThe reference carries vocal identity and demonstrates a manner of speaking. Each finished passagehas its own reason to be spoken: draw someone in, challenge a claim, become delighted by an example,-or deliver a confident verdict. Direct those attitudes in the video or independent speech request-while keeping the same person recognizable. One accepted voice can express different thoughts;-recurring identity does not require one fixed emotional state throughout the work.+or deliver a confident verdict. Direct those attitudes through the video performance or the selected+speech model's available inputs while keeping the same person recognizable. One accepted voice can+express different thoughts; recurring identity does not require one fixed emotional state throughout+the work.[Video direction](video-direction.md#direct-the-reason-for-an-action) connects that attitude to gaze,-gesture and interaction. For independent speech, the speech request carries the delivery direction.-Choose time from this intended performance using+gesture and interaction. For independent speech, the Script and supported speech-model inputs shape+delivery. Choose time from this intended performance using[Script measurement](../../creation/script-and-time.md#measure-before-choosing-durations).The pace estimate sizes the passage; the voice and performance direction give it character. Fastspeech alone does not establish emphasis, changing attitude or expressive intonation.diff --git a/skills/hypit/references/playbooks/formats/narration-led-demo.md b/skills/hypit/references/playbooks/formats/narration-led-demo.mdindex 94dec004..92eb48b2 100644--- a/skills/hypit/references/playbooks/formats/narration-led-demo.md+++ b/skills/hypit/references/playbooks/formats/narration-led-demo.md@@ -56,10 +56,11 @@ and README for its exact inputs and limits.## Keep the narrator one person across the work-Use `../craft/voice-and-performance.md` to establish the narrator's accepted Voice Reference and-generate independent speech from it. If the same person also appears in visible A-roll elsewhere,-the same Voice Reference can condition both the visible performance and independent narration. The-work then changes sound-picture relationship without changing who is speaking.+The passage can use already recorded final narration or generated speech from an accepted Voice+Reference; [Voice and performance](../craft/voice-and-performance.md) distinguishes these uses.+When new performances are generated for someone who also appears in visible A-roll, the same Voice+Reference can condition both the visible performance and independent narration. The work then+changes sound-picture relationship without changing who is speaking.`../../creation/script-and-time.md` owns measurement and alignment. One accepted narrationperformance can carry many picture changes; their semantic relations follow that performance withoutdiff --git a/skills/hypit/references/playbooks/formats/presenter-led-explainer.md b/skills/hypit/references/playbooks/formats/presenter-led-explainer.mdindex 7edefd06..313996a7 100644--- a/skills/hypit/references/playbooks/formats/presenter-led-explainer.md+++ b/skills/hypit/references/playbooks/formats/presenter-led-explainer.md@@ -34,17 +34,43 @@ One scene may also develop across several Takes. Spoken segment boundaries do noboundaries or camera cuts.Use [Performance](../../production/performance.md) for presentation of the Timeline's existing visual-material and [Media](../../production/media.md) for independent supplied material. A full-frame view,-a circular crop and a moving viewport can share the same playing source. Its playback clock continues-while the frame moves; foreground and enlarged background views of that source need the same sample.-Let the visual emphasis follow who or what currently carries the idea, including returning to the-presenter for an expressive reaction or direct address.+material and [Media](../../production/media-presentation.md) for independently supplied material.+Treat the accepted footage as available material for the changing picture: it can fill a view,+appear in several views, join a comparison or disappear while the argument continues. A project+scene can consume its Timeline mapping alongside other inputs when their layout or action belongs+together. Let visual emphasis follow who or what currently carries the idea, including returning+to the presenter for a reaction or direct address.++For example, one work may move its full-frame presenter into a small window while a diagram takes+over; another may cut straight from the original camera view to an isolated presenter beside evidence.+Both preserve the accepted performance while changing how the viewer encounters it. The semantic+event motivates the change. Whether it cuts, moves, holds or fades follows this work's expressive+rhythm. Full-frame, inset and cutout describe appearances, not separate production pipelines.Speech sound remains an independently connected contribution when MG covers the presenter. Genuinelyindependent narration uses the [narration-led relationship](narration-led-demo.md). A montage or silentending can occupy ordinary time outside any Take: the complete Timeline has room for both semanticanchors and independently authored events. No invented performance is needed to create that room.+## Direct material for its intended uses++For footage expected to fill the picture much of the time, the final aspect ratio is a useful+starting point for generation. Anticipate the body, gestures, setting and detail the work will need+when the picture changes. A later small or differently shaped viewport can sample that same source;+its destination shape alone does not determine the source ratio. A tight source crop cannot later+supply missing hands or setting. Choose the source view from the actual visual needs across the work.++Recurring graphics and the source framing can support each other. Translate that plan into concrete+camera requirements for image generation: a person positioned to one side, sufficient body extent,+space around gestures, or a particular camera distance. Keep future MG, editorial writing and the+explanation's metaphors with their components. The image request describes only the image being+made. [Graphic composition](../craft/graphic-compositions.md#give-material-and-graphics-room-together)+and [image direction](../craft/image-direction.md#frame-the-image-for-what-it-will-become) own that translation.++Transparency is useful when the design needs the subject's silhouette. Preserve opaque footage+when its real setting also matters. [Media preparation](../../production/media.md#keep-original-and-processed-material-explicit)+owns those explicit outputs; their visual uses can change while the chosen performance continues.+## Give events meaning and transitions durationName the spoken idea that motivates a change in Script, then connect its Moment or Selection to the@@ -52,10 +78,11 @@ component. That establishes why the event happens there. Local durations and easthe change unfolds. A phrase can start a movement that continues into the next phrase; the settledstate can remain useful long after the entrance finishes.-Design handoffs from the states on both sides: what remains present, which geometry should meet,-and where attention should land. A brief presentation Use can connect two longer treatments without-changing the underlying footage. Read the actual contribution's interval and override semantics;-shared timing does not make independent Tracks mutually exclusive.+Design handoffs from the states on both sides: what remains present and where attention should land.+A direct cut selects the new state at the event. When following a continuous transformation is useful,+a brief presentation Use can connect two longer treatments without changing the underlying footage.+Meet both the viewport geometry and its source crop at the endpoints. Read the actual contribution's+interval and override semantics; shared timing does not make independent Tracks mutually exclusive.[Temporal projection](../../production/track-authoring.md#keep-selection-projection-and-consumption-distinct)and the owning component documentation supply exact syntax.@@ -74,7 +101,8 @@ The reference supplies the appearance and behavior to understand, not a compulsoPreserve the detail that makes the scene convincing when simplifying it. Removing a redundant titlechanges the remaining layout; a folder still needs readable contents, and a working terminal needsvisible activity while the narration describes it. A demonstration has a designed hold as well as-an entrance. [Graphic composition](../craft/graphic-compositions.md) owns this visual judgment.+an entrance. [Motion graphics](../craft/motion-graphics.md) owns how that change reads over time;+[graphic composition](../craft/graphic-compositions.md) owns its hierarchy in the picture.## Organize the behavior at its useful scale@@ -96,11 +124,9 @@ Derive connected motion from shared layout so moving a target also moves its poi## Develop the work with visible feedback-Use generated material for the photographed or illustrated content it should actually contain.-Use recorded interfaces when their literal state and actions are evidence; keep a recording as-reusable material whose crop and timing can be revised. Authored MG can demonstrate a relationship-without pretending to be a measured product recording. Material direction and reference relationships-belong to their [Craft pages](../index.md#craft).+A screen passage can carry actual interface evidence, an authored explanation, or both.+[Screen demonstrations](../craft/screen-demonstrations.md) owns that choice; generated material+direction and reference relationships belong to their [Craft pages](../index.md#craft).Review a useful passage in its surrounding composition as the design develops. Explain what itdemonstrates and what is still being built. Comments can carry a change of visual idea that nodiff --git a/skills/hypit/references/playbooks/formats/short-drama.md b/skills/hypit/references/playbooks/formats/short-drama.mdindex 755026aa..8d4fddfe 100644--- a/skills/hypit/references/playbooks/formats/short-drama.md+++ b/skills/hypit/references/playbooks/formats/short-drama.md@@ -22,36 +22,39 @@ generated together without defining the story's scenes. [Script and time](../../owns measurement, while [generated video direction](../craft/video-direction.md#size-the-request-around-the-delivery)owns how the selected model's request range informs the performable passage.-## Establish a small useful set of camera images+## Establish the story's useful camera viewsReference-conditioned generation is a strong starting point when the work depends on recognizable-people, a shared world, staging or composition. Direct each image and Take in natural language for the-current dramatic intention. Free direction suits the variety of dramatic scenes; a reusable Prompt-Kit becomes useful when repeated productions reveal a stable prompt relationship worth preserving.+people, a shared world, staging or composition. A key image can establish the character, a complete+story view with the characters in their setting, or both. Direct images and Takes in natural language+for the current dramatic intention. Free direction suits the variety of dramatic scenes; a reusable+Prompt Kit becomes useful when repeated productions reveal a stable prompt relationship worth preserving.-The first useful image can contain one person, several people, or the whole encounter. Start with the-view that establishes the difficult facts:+The first useful image can be a character reference or a view of the encounter itself. Build later+views from the images that hold the facts they need:-- a shared two-person image can establish the bodies, gaze axis and encounter before closer views;-- one person's actual camera view can establish the place before a complementary view introduces the- other person;+- a character image can carry identity into a view that establishes a new place and dramatic state;+- a shared two-person view can establish the bodies, gaze axis and encounter before closer views;+- one story view can carry a costume, prop or spatial relationship into the next;- a supplied image can serve directly when it already expresses the intended character and shot.Within one location, a small set of useful views can support many Takes. In a living-room dialogue,-one view for each conversational side may preserve everything the edit needs; modest reframing,-performance and natural cuts can happen in video. Another image becomes useful when a new view must+one view for each conversational side may preserve everything the passage needs; modest reframing,+performance and camera changes can happen in video. Another image becomes useful when a new view mustestablish an important fact, such as a changed relationship, decisive prop state or plot-bearing partof the space.-A meaningfully new place, time or visual situation is usually worth establishing with a camera image-that already contains the characters in that new world. It can connect the authoritative references-needed for their identities, products, costumes or continuing prop state, while establishing the new-setting and composition together. The resulting graph stays shallow because each edge carries a real-creative dependency; the work itself determines the useful image count.+Decide separately which views to establish and which dramatic action to generate together. One Take+can move among several shots or places while key images establish the people, objects, composition+or continuity that need explicit visual direction; one view can also guide several Takes. A new+place merits an image when the story needs that particular view established, while other moves and+cuts can develop within the video passage. The image graph follows those visual dependencies rather+than the count of locations or edits.[Reference relationships](../craft/generated-dependencies.md) owns these image edges. The[two-person podcast](two-person-podcast.md) and [street interview](street-interview.md) show two-different ways of establishing a conversational world.+different ways of establishing a conversational world. [Video direction](../craft/video-direction.md#direct-camera-and-cuts-as-part-of-the-passage)+owns the generated passage's shots and reference relationship.## Let every camera see the same world differently@@ -65,18 +68,18 @@ One camera can reveal the part of the place surrounding one character while anotdifferent sector around their partner. [Image direction](../craft/image-direction.md#establish-the-place-with-a-few-details)owns this relationship between person, setting and view.-## Let performance and editing carry the event+## Let performance carry the eventAction direction should preserve cause and attention: who initiates, who notices, what changes hands,-what a reaction answers, and why the cut moves now. It can freely describe the behavior and edit the-current passage needs. A glance, interruption, withheld response or turn away matters when it changes-the dramatic relationship.+what a reaction answers, and why attention or the camera moves now. It can describe the behavior and+views the current passage needs. A glance, interruption, withheld response or turn away matters when+it changes the dramatic relationship.Caption, typography, MG, effects and B-roll can sharpen that event without replacing its human spine.A text message can reveal information, an insert can prove what a character sees, and a graphic canmake a payoff readable. Keep the A-roll performance and its sound meaningful even when another layercovers the picture.-Review the finished work for dramatic causality as well as visual continuity: the viewer should know-who is acting, what changed, and why the next shot or scene follows. A new short-drama form can combine-these relationships differently while keeping that responsibility.+Review the finished work for dramatic causality and coherent people, places and action: the viewer+should know who is acting, what changed, and why the next view or scene follows. A new short-drama+form can combine these relationships differently while keeping that responsibility.diff --git a/skills/hypit/references/playbooks/formats/talking-head.md b/skills/hypit/references/playbooks/formats/talking-head.mdindex f57e440b..b43ea61b 100644--- a/skills/hypit/references/playbooks/formats/talking-head.md+++ b/skills/hypit/references/playbooks/formats/talking-head.md@@ -5,13 +5,18 @@ help the viewer follow it. A ranking board is one possible companion, not a requFor that relationship, combine this page with [Ranking](ranking-listicle.md).When evolving demonstrations and MG carry much of the argument, use[Presenter-led visual explainers](presenter-led-explainer.md) for their relationship to that performance.+This relationship follows the speaking performance, whether its footage is newly made or retained+from a recording.## One useful image can carry the whole performanceMake 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.+space the video needs. For a performance expected to stay mostly full-frame, its final aspect ratio+is a useful starting point. Preserve the body and gesture room needed across its later uses;+destination viewports can change around the same footage. [Image direction](../craft/image-direction.md)+owns that craft. A person placed slightly right can leave room for an icon on the left; the image+prompt describes the person and visible setting, while the icon belongs to its component. A table+or the direction of their seated body can make that placement feel inhabited. Choose it for this work.For a reusable frontal speaking image, explicitly keep the face toward the lens, with no head tiltor rotation. A vivid attitude and an easy speaking gesture give this settled view life. The@@ -60,9 +65,11 @@ See [Generated video direction](../craft/video-direction.md) for listeners, gest## 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.+Write natural stages in Script. For newly generated Takes, measure each Segment before choosing a+literal generation duration. When the work retains recorded speech, its edited delivery supplies+the actual duration; [media preparation](../../production/media.md) explains how to prepare and+align it. A Segment can contain several edited shots, Caption Cue Breaks, graphic changes and+speaking turns. Choose its boundaries from the performance it carries.Normalize the produced speaking media, align its own audio to its Segment, and assemble theSemanticTakes. Keep that performance's sound when B-roll covers its picture. Place evidence ondiff --git a/skills/hypit/references/playbooks/index.md b/skills/hypit/references/playbooks/index.mdindex c13b5be4..d88f8d3d 100644--- a/skills/hypit/references/playbooks/index.md+++ b/skills/hypit/references/playbooks/index.md@@ -22,24 +22,29 @@ 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 capture, compelling people, camera relationships and settings; four-paragraph image direction and reference use |+| [Directing generated images](craft/image-direction.md) | directing the picture a work needs, including people, places, products and icons; phone-video capture, casting, camera relationships and references || [Directing a voice](craft/voice-direction.md) | casting an appealing voice, choosing its vocal character, writing Voice Design direction or selecting a sample line |-| [Voice and performance](craft/voice-and-performance.md) | how performances supply local word timing, who is A-roll, recurring voice identity, visual A-roll presentations, or genuinely independent narration |-| [Directing generated video](craft/video-direction.md) | choosing a generation relationship, directing visible performance or silent action, camera behavior, cuts, or request duration |-| [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 |+| [Voice and performance](craft/voice-and-performance.md) | what performance carries a passage, recurring voice identity, changing visual use of the same material, or genuinely independent narration |+| [Directing generated video](craft/video-direction.md) | choosing a generation relationship, deciding when source footage should carry performed action or camera behavior, directing visible speech or silent action, cuts, subject-isolation footage or request duration |+| [Reference relationships](craft/generated-dependencies.md) | what existing images or footage contribute to a new request: people, places, conversational views, continuing props and new-scene branches |+| [Material-led pictures and B-roll](craft/b-roll.md) | what an image or video contributes to a passage; full-frame or framed views, exact evidence versus a visual thought, and picture/performance handoffs |+| [Screen demonstrations](craft/screen-demonstrations.md) | what a website, app, terminal or editor must show; captured states and interactions versus authored explanations, and how viewers follow them || [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) | physical scene versus camera framing and editorial layers, overlays, picture-in-picture, cutouts, screen evidence, or live call layouts |+| [Caption tracking](craft/caption-tracking.md) | the user's reference visibly uses head-following Caption or the user asks for it; matching face observations to Roles, picture placement and Cue time |+| [Sound and mix](craft/sound-mix.md) | what existing material already sounds like, which music or effects the work needs, and how those sounds share time and attention |+| [Graphic composition](craft/graphic-compositions.md) | attention and coexistence of material and graphics, source framing, boards, spatial hierarchy and coordinated palette |+| [Motion graphics](craft/motion-graphics.md) | how graphics, effects and scenes change over time, carry objects through handoffs, establish a motion language and meet the performance |Read every craft whose question genuinely appears in the work, including questions discovered aftera Studio preview or completed Result. Repeated use of the same craft does not require rereading itunless the decision has changed.+For authoring those decisions, [Performance](../production/performance.md) presents current Timeline+footage and [Media](../production/media-presentation.md) supplies independent pictures and playback.+[Media preparation](../production/media.md#keep-original-and-processed-material-explicit) owns source+processing, including transparency; [Spatial layout](../production/spatial.md) owns fitting and crop.+These choices compose according to the intended use of the material.+## Examples| Read | When a concrete directing example would help |diff --git a/skills/hypit/references/production/audio-presentation.md b/skills/hypit/references/production/audio-presentation.mdnew file mode 100644index 00000000..903abb01--- /dev/null+++ b/skills/hypit/references/production/audio-presentation.md@@ -0,0 +1,49 @@+# Place independent sound++Read this when supplying music, ambience, narration or effects independently of placed Takes.+[Sound](sound.md) presents audio already on the Timeline. If a narration performs the work's Script,+prefer an audio-only SemanticTake and Sound so its words establish reusable semantic time.+An independent audio contribution can still follow that same Script's events.++## Prepare and place the source++With the source, Clock, Script and Timeline already declared:++```svml+<import as="pipeline" from="@hypit/media-pipeline@1"/>+<import as="audio" from="@hypit/audio-track@1"/>+<pipeline:Normalize id="hit-media" source={hit-source} clock={clock}+ video="none" audio="default" span-authority="audio"/>+<audio:Track id="effects" timeline={program.timeline}>+ <audio:Item id="reveal-hit" source={hit-media.media}+ at={story.moment.reveal} for="600ms" playback="once"+ gain="0.45" fade-in="0f" fade-out="3f"/>+</audio:Track>+```++An Item consumes normalized audio-bearing media and a projected Window. Music can occupy a Segment+or the program; effects can follow Moments. Shared [time forms](timing.md) also allow independent+clock events. The Track publishes `.program` and `.audio`; select `.audio` in Film to hear it.+An explicit Item id gives Studio a useful name. Two Items using one source remain two placements.++## Choose source playback and mix++`trim-start` and `trim-end` are source durations in frames, milliseconds or seconds; the end is+exclusive. For example, `1s` to `3s` selects those two source seconds. This differs from Media Track's+integer frame trim properties. Destination time remains the Item's Window.++- `once` / `once-start` plays from the Window start; `once-end` aligns native playback to its end.+- `loop` / `loop-start` and `loop-end` repeat with the selected alignment.+- `stretch` retimes with pitch preserved and requires explicit `min-rate` and `max-rate` bounds.++Playback expresses the intended occupancy. A long Window does not automatically loop or stretch+a short source. The installed `@hypit/audio-track` README owns exact behavior and rate constraints.++`gain` is a linear multiplier, defaulting to 1; fade durations default to `0f`. Normalization preserves+source level. Overlapping Audio Items mix; overlapping visual Items instead compose by paint order.+Balance music, speech, ambience and effects in the actual Film. [Sound direction](../playbooks/craft/sound-mix.md)+owns the audible judgment, including ducking and continuity.++A sound can share a semantic Moment with a reveal while remaining a separate contribution. If a+visual component owns a coupled sound, it can publish a peer AudioTrack output; Film still selects+that sound explicitly. Neither route requires reading another component's private state.diff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.mdindex 078313ab..cf902b93 100644--- a/skills/hypit/references/production/authoring.md+++ b/skills/hypit/references/production/authoring.md@@ -4,21 +4,23 @@ Read this when turning the current Treatment into Author Sources, Recipes, Runs,and Builds, or when revising an existing production.[Script and semantic time](../creation/script-and-time.md) explains target wording, Segments, Roles,-Caption Cue handoffs and semantic anchors. [Source syntax](source-syntax.md) explains imports,-references and the language around that Script.+Caption Cue decisions and semantic relationships. [Script syntax](script-syntax.md) gives their exact+forms; [Timing](timing.md) projects them into components. [Source syntax](source-syntax.md) explains+imports and references.[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.[Component design](component-design.md) explains shaping its behavior and controls around the work.[System relationships](system.md) connects these concepts to execution and Results;-[media preparation](media.md) explains the values entering the timeline.+[media preparation](media.md) explains material inputs. [Production navigation](index.md) locates+specialized questions without requiring every page for every revision.## Turn the Treatment into relationshipsBegin with the work the Treatment describes, not with a package inventory. Identify:-- the Script passages and speaking roles, where the work has speech;-- the performances and other material the work needs, and their placement on its complete Timeline;-- the Caption, Typography, MG, Effect, and Audio systems that act with them;+- the meaningful, performable Script passages and any speaking roles;+- the performances placed on Timeline and the independent material supplied to other components;+- the picture and sound contributions the work needs, including a simple full-frame performance;- the semantic relations that should follow words, phrases, pauses, or content events;- the genuinely clock-based events;- the final Film or other deliverables.@@ -31,15 +33,23 @@ other layers will follow,[voice direction](../playbooks/craft/voice-direction.md) for casting and directing a character's voice,[voice and performance](../playbooks/craft/voice-and-performance.md) for A-roll and recurring voices,[B-roll](../playbooks/craft/b-roll.md) for coverage,+[screen demonstrations](../playbooks/craft/screen-demonstrations.md) when an interface carries evidence or explanation,[Caption](../playbooks/craft/captions.md) for speech-linked text, and-[graphic composition](../playbooks/craft/graphic-compositions.md) for MG and designed visual state.+[graphic composition](../playbooks/craft/graphic-compositions.md) for designed visual hierarchy,+with [motion graphics](../playbooks/craft/motion-graphics.md) for changes within it.These pages establish what the authored relationship should accomplish. Installed vocabulary thensupplies the exact language for expressing it.+For a performance-led work, including pure A-roll or short drama, prefer Script and semantic+preparation even when the presentation is simple. Preserve the actual event relationships when+additional Caption, sound or visual direction is introduced. A standalone asset edit can instead+end at its requested media Output.+Author those relationships explicitly. Script Selections and Moments carry meaning through placedperformances into real time; authored positions locate independently timed events on the same Timeline.-Track and Film elements arrange the resulting picture and sound. One Source-carries the whole creative program; its cuts are relationships inside that program.+Track and Film elements arrange the resulting picture and sound. One Author entry connects the+work; imported Sources and project modules divide its meaningful responsibilities. A camera cut+is not by itself a reason for another Source, Segment, component or Build.When a role first leads to an installed Surface in the current work, query its actual declarationbefore writing the element:@@ -159,6 +169,9 @@ submitting the same paid media requests again. The following examples locate the| 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 |+| Moment/Selection placement changes, with unchanged spoken tokens and Take identities | The accepted SemanticTakes and other material | Current Script references, their projections and presentation |+| Cue grouping, word attributes or display-only Dual wording changes without changing speech tokens | The accepted SemanticTakes | The current CaptionDocument and its presentation |+| Take placement or complete Timeline extent changes | The prepared local Takes | Timeline assembly, all affected projections and presentation || 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 presenter changes while the spoken argument still fits | Unaffected B-roll, icons, music and other media that still serve the target | The new presenter images, affected performances, their normalization and semantic timing, and downstream composition || A new product changes the demonstration or claims | Views and media whose content still fits the new Treatment | The affected product views, performance, Script-dependent timing and visual treatment |@@ -169,6 +182,13 @@ Choose an Output upstream of the work being changed, with the same nominal Typecreative meaning. An unchanged SemanticTake can preserve both media and alignment. It is valid onlywhile its Narrative, Segment, token and anchor identities and timing still describe the currentScript and media. A Script edit does not automatically invalidate every Take; inspect what changed.+Markers select existing token/Segment anchors. Moving a marker can therefore reuse accepted timing+when those anchors and spoken tokens remain the same; no acoustic measurement is needed merely+because a cue now follows another word. Changing spoken text, tokenization, Segment identity or the+source performance requires a fresh judgment about the affected Take. Keep the media upstream when+it still fits and let the required preparation recompute. No reuse selection automatically adapts an+old Take to new speech.+Do not satisfy a changed Track or final composition with its old rendered Output, which would hidethe current edit. Type compatibility alone cannot establish that an old performance or timing still fits.@@ -191,7 +211,8 @@ Runtime activity when reuse or active execution matters. Read the relevant diff- Revise Script when words, Cue breaks, Selections, or Moments changed.- Revise Source or Recipe when composition, parameters, or authored timing relations changed.- Revise the Run when the demanded deliverable or selected Candidate changed.-- Revise a project package when its reusable visual role or rendering behavior is wrong.+- Revise a project package when its fixed or reusable behavior needs to change; an unexposed local+ design detail can be edited there without creating a new parameter.- Revise a media request when the desired shot or the user's requested media has changed.Generated Result bytes are evidence and reusable inputs, not editable Source. A change that stilldiff --git a/skills/hypit/references/production/browser-capture.md b/skills/hypit/references/production/browser-capture.mdindex f6b0d852..3d7f4b69 100644--- a/skills/hypit/references/production/browser-capture.md+++ b/skills/hypit/references/production/browser-capture.md@@ -1,15 +1,11 @@# Capturing websites and authored HTML-Read this when a real interface, product page or locally authored graphic should become picture-material in the video. `hypit capture` supplies browser capture from the installed Distribution;-the project's scripts describe the actual page interactions.--Choose the material from its role. A screenshot preserves wording and a visible state. A long page-can become a controlled scroll through Media Track's Sampling. A recording preserves interaction-and changing page content when those changes are part of the demonstration. A local HTML file can-produce a static card or graphic. [Graphic composition](../playbooks/craft/graphic-compositions.md)-explains when editable component state is useful, and-[compositing](../playbooks/craft/compositing.md) explains the screen's place in the frame.+Read this when a page, product interface or locally authored HTML should become captured picture+material. [Screen demonstrations](../playbooks/craft/screen-demonstrations.md) owns what the screen+must show and why; this page owns how to save that material. `hypit capture` supplies browser+capture from the installed Distribution; the project's scripts describe the actual page interactions.+A captured image or recording enters the composition through Media, while an editable demonstration+can use a project component. [Spatial layout](spatial.md) owns fitting either into its destination.## Save a page or region@@ -71,11 +67,9 @@ argument to `screenshot` or `record` to capture it. Returning finishes open recothe browser. Completed captures survive a later script failure.For a scrolling demonstration, identify the container that actually scrolls; a gallery may move-inside a fixed page. Frame the useful content at its intended viewing size and record from a useful-start state through the action. Compare separated saved frames to confirm that the intended rows or-states change. Crop and presentation can then be revised around this recording without repeating-the capture. An authored diagram or simulated interaction whose motion must follow Script events-belongs in an editable component; a recording supplies the real interface behavior being shown.+inside a fixed page. Record the intended interaction and compare separated saved frames to confirm+that the page's rows or states actually change. Crop and presentation can then be revised around+this recording without repeating the capture.For local inputs beside the script, `new URL('../assets/card.html', import.meta.url).href` locatesthe file. Relative output paths follow the directory where the command runs. `args` contains the@@ -113,6 +107,6 @@ placing it in the composition.Keep captures in project assets and record the source page and its purpose in the project notes.An image enters through `media:Image`; a recording enters through `media:Video` and the ordinary[normalization path](media.md). Place them with-[Media Track](tracks.md#coverage-has-a-window-and-a-separate-playback-choice) and the Script's+[Media presentation](media-presentation.md#keep-display-time-and-source-playback-distinct) and the Script'sSelections or Moments as appropriate. Their visibility, crop, scroll and transitions belong to thecomposition, so those changes can reuse the captured file.diff --git a/skills/hypit/references/production/builds.md b/skills/hypit/references/production/builds.mdindex 46bb044c..37f6b263 100644--- a/skills/hypit/references/production/builds.md+++ b/skills/hypit/references/production/builds.md@@ -174,8 +174,9 @@ 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. Itdoes not install packages or start a missing Managed Program. When the environment has already beenprepared and only the Worker is stopped, Build ensures that Worker becomes available. When-preparation is missing, use `hypit runtime up` as described in `../environment/profile.md` and submit-again after it succeeds.+preparation is missing, prepare the selected Endpoint with `hypit programs prepare --endpoint <instance>`;+use `programs up` if its helper also needs starting. [Local preparation](../environment/local-tools.md#let-the-selected-endpoint-own-its-program)+explains their scope and the combined `runtime up` command. Submit again after the required preparation succeeds.The Worker owns execution after durable submission. `--follow` only observes it; closing orinterrupting that terminal detaches the observer and leaves the Build running. Reattach with:@@ -205,10 +206,10 @@ ends the attempt and preserves available remote receipts; it does not resubmit tWhen an action fails, the attempt ends and local reservations are released. Any last-observed remotestatus 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 --verbose --json` exposes the actual resource claims. Provider-local documentation owns available settings.+`activity --verbose --json` exposes actual resource claims when capacity explains a wait.+Task occupancy, overlapping network actions and starts permitted per time period are different+quantities. [Runtime profiles](../environment/profile.md) owns their configuration and selection;+the selected Provider's documentation owns its available settings.## Separate active work from Result outcomediff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.mdindex bfe7b41d..44c5e50c 100644--- a/skills/hypit/references/production/caption-authoring.md+++ b/skills/hypit/references/production/caption-authoring.md@@ -25,15 +25,17 @@ to a Script Moment.## Own the visual relationship-Media can present ordinary footage; a scene component can coordinate footage with diagrams or other-graphics. Fine and custom Caption families have the same relationship. Their shared input is the+Performance presents placed footage; Media supplies independent pictures. A scene component can+coordinate either with diagrams or other graphics. Fine and custom Caption families have the same relationship. Their shared input is theauthored speech and its semantic timing; the implementation owns the spatial structure and motion.Start from what the viewer should understand or feel. A supporting phrase might establish thethought while its key word takes the emphasis. Design how they enter, share space, respond to speechand hand off to the next thought. That relationship suggests useful controls: the word's authored-role, fonts, relative sizes, placement and motion. Put the work's choices in its Style/Recipe and-the reusable arrangement in the renderer.+role, fonts, relative sizes, placement and motion. Put the choices the production actually needs to direct in its Style/Recipe and the arrangement+in the renderer. A qualitative mode and a numeric field need the same justification; fixed decorative+details can remain local. [Component design](component-design.md#expose-the-choices-the-work-needs)+owns that interface decision.The output remains an ordinary VisualTrack. Its Presents can own trees of text, boxes, images andother visual elements. When words and graphics share layout or motion, they can live in the same@@ -60,7 +62,7 @@ Use `@hypit/hypit/caption` for content timing and Use coverage, and `@hypit/hypiScript document types. A family Track accepts `document`, `timeline` and ordered `Use` children:```svml-<keyword:Track id="captions" document={story.caption} timeline={film.timeline}>+<keyword:Track id="captions" document={story.caption} timeline={program.timeline}><keyword:Use style={base-style}/><keyword:Use role="GUEST" style={guest-style}/><keyword:Use during={story.selection.punchline} style={punchline-style}/>@@ -95,11 +97,11 @@ is a separate operation. A narrow width should not silently rewrite the Script iIf the family needs an additional grouping rule, give that rule explicit parameters and preserve theoriginal word/unit associations in the schedule.-Display Words follow the Script's writing system: a Han character is normally one Word, while an-English word is normally one Word. Keep that timing granularity separate from a phrase's visual-grouping. Compose adjacent Han characters without Latin word gaps, preserve punctuation with its-word, and use the selected fonts' actual widths for layout. Exercise mixed-script names as well as-plain English when the family will carry Chinese copy.+Display Words reflect Script's lexical units: a Han character is normally one Word, while an+English word is normally one Word. Keep that timing granularity separate from visual grouping.+Use each word's authored `separatorBefore` and `text`, including attached punctuation; derive no gaps+from the writing system. Measure with the selected fonts' actual widths. Exercise Chinese with an+intentional space, Korean word spaces, and mixed numeric/Latin spellings when the family carries them.For speech-following emphasis, activate each complete unit from its projected start and end.A Cue-wide left-to-right progress bar follows elapsed time and text width, which is a differentdiff --git a/skills/hypit/references/production/caption-presentation.md b/skills/hypit/references/production/caption-presentation.mdindex bfe8e9fe..3d5477c1 100644--- a/skills/hypit/references/production/caption-presentation.md+++ b/skills/hypit/references/production/caption-presentation.md@@ -10,7 +10,7 @@ text and pronunciation associations. Each Use selects a complete Style inside a```svml<caption:Hidden id="hidden"/>-<caption-fine:Track id="captions" document={story.caption} timeline={film.timeline}>+<caption-fine:Track id="captions" document={story.caption} timeline={program.timeline}><caption-fine:Use style={base-style}/><caption-fine:Use role="GUEST" style={guest-style}/><caption-fine:Use during={story.selection.answer} style={answer-style}/>@@ -34,7 +34,7 @@ caption can use a project family with its own layout and behavior.| Explicit window | `start="8s" end="10s"` || A particular speaker | Add `role="GUEST"` to any of these |-[Performance timing](performance.md) explains the shared expressions and semantic references.+[Timing](timing.md) owns the shared expressions and semantic references.Use semantic boundaries when the treatment follows what is being said. Absolute times remain usefulfor an explicitly timed presentation. A Role filters whose content is presented, independently of thewindow: it can cover several turns and does not change the Window shown in Studio.diff --git a/skills/hypit/references/production/component-design.md b/skills/hypit/references/production/component-design.mdindex 1d8a997f..43e80d1a 100644--- a/skills/hypit/references/production/component-design.md+++ b/skills/hypit/references/production/component-design.md@@ -5,7 +5,8 @@ Design it with the taste of a director and the care of someone who will use it iA useful component makes a particular idea legible and keeps its behavior understandable within theproduction. Its author interface can be as small as the work requires.-[Graphic composition](../playbooks/craft/graphic-compositions.md) owns visual hierarchy and motion;+[Graphic composition](../playbooks/craft/graphic-compositions.md) owns visual hierarchy;+[motion graphics](../playbooks/craft/motion-graphics.md) owns changes in the picture over time;[Track authoring](track-authoring.md) owns the implementation. A new Caption family also draws on[Caption craft](../playbooks/craft/captions.md) and [Caption authoring](caption-authoring.md).@@ -48,6 +49,11 @@ that owner; reuse preserves a relationship across uses. These decisions serve di| Parameterization | The production needs an external choice: an asset, a spoken trigger, a placement or a setting the author will actually adjust. || Reusable design | Actual uses share a relationship or treatment. Share that behavior and generalize only the variation those uses need. |+An author input is not a requirement to publish a package or provide a Studio control. A shared+internal function is not necessarily another Track. Numeric and qualitative choices use the same+criterion: does an external dependency or a useful directing decision belong here? A color, mood,+layout mode or easing name does not deserve a public parameter merely because it could vary.+One-off effects can be independently organized with fixed designs. A future edit may appropriatelychange their implementation. Consider likely revisions to reveal tangled responsibilities or usefulinputs, rather than treating every possible edit as a parameter to implement in advance. Even repeated@@ -74,6 +80,11 @@ remain with its owner, while a shared change should flow through a shared dependrequires reconstructing the same decision across several scenes, consolidate that decision's source.The aim is to make the relationship explicit, whether its owner is a fixed implementation or an author input.+A useful revision question is: if delivery pauses before the result, which event should move and+which local design should stay? Inspect the input that carries that event rather than counting how+many parameters the component exposes. If the work needs a qualitatively different relationship,+change its implementation or define a new component instead of accumulating speculative mode flags.+Keep revisions local as the scene grows. Separate independently edited scene bodies, styling andframe evaluation into ordinary source modules while sharing their actual mechanics. A palette,typing function or media-sampling helper can be an ordinary project dependency; it needs no Surface@@ -122,6 +133,18 @@ have their own trigger. Use semantic examples first for speech-led roles, showinpreserves the relationship. [Authored animation](rendering.md#compose-an-authored-animation) coversthe film clock when there is no performance.+A semantic outer Window alone does not establish the timing of its internal events. In a drag-and-drop+scene, selecting a picture, dropping it into an editor and revealing the result may answer three+different phrases. Give those actions their own semantic inputs. Placing them at fixed seconds or+at 20%, 50% and 80% of the outer Window preserves neither their identities nor their relationship+to unevenly changed speech.++The Surface can accept an outer Selection and separate Moments for those events, projecting each+through Timeline. The implementation derives movement between the resulting events and keeps its+pointer path, button geometry, click rebound and decoration local. A movement that simply unfolds+inside one authored event interval may use normalized progress there; it needs no marker for every+animation key. Meaningful event location and the designed duration/shape of motion are different choices.+Choose the temporal input from what the component does. A picture covering an explanation occupiesits Selection. An answer revealed on a word can remain visible after that word ends. A ranking itemmay move during a reveal Window and stay in its settled row afterward. The board's outer lifetime,diff --git a/skills/hypit/references/production/component-sharing.md b/skills/hypit/references/production/component-sharing.mdindex 61104c72..7a90fe04 100644--- a/skills/hypit/references/production/component-sharing.md+++ b/skills/hypit/references/production/component-sharing.md@@ -19,12 +19,38 @@ Keep the same name when distributing it. The Source import names its logical Mod<import as="score" from="@studio/score-strip@1"/>```-Here `1` is the Module interface version. The package manager separately records the npm release,-such as `1.2.0`. A release that preserves that interface keeps the same Source import.+Here `@1` names the logical Module ABI used by the Source. The package manager separately records+the physical npm release, such as `1.2.0`. Updating that package release does not by itself change+the logical import. Follow the package's actual published vocabulary for its author interface.++## Publish for repeated distribution++For stable reuse across projects, publish a versioned package under its owner's npm scope or private+registry when that owner chooses distribution. For a public scoped package, the publication command is:++```bash+npm publish --access public+```++Consumers install the selected release with their usual package manager:++```bash+npm install --save-exact @studio/[email protected]+# or+pnpm add --save-exact @studio/[email protected]+```++The project lockfile records the installed dependency tree. Updates are explicit package-manager+operations; Builds use the selected installed code. A missing package is an installation problem.+Select the intended new release in the consumer project, inspect its changed vocabulary where+relevant, check the actual Source/Run and review the changed behavior. New Builds load that selected+implementation; restart an existing Studio session to load package-code changes. Reuse compatible+media through Run Candidates while recomputing the component being revised. The package's own+release notes describe any required author changes; no Build upgrades or migrates it automatically.## Send a tarball to another person-For a direct handoff, build the package and run `npm pack` in its directory. A TypeScript package+For an explicit direct handoff or development check, build the package and run `npm pack` in its directory. A TypeScript packagecompiles to JavaScript; a JavaScript package may already have executable files. Its `prepack` scriptcan perform the build. For example:@@ -46,26 +72,6 @@ and the lockfile. Source imports select author contributions; Runtime Profile encontributions. To send the next release, give it a new package version, create a new tarball, andinstall that file explicitly.-## Publish for repeated distribution--When the owner wants a registry release, publish the built package under their npm scope or private-registry. For a public scoped package, the publication command is:--```bash-npm publish --access public-```--Consumers install the selected release with their usual package manager:--```bash-npm install @studio/[email protected]-# or-pnpm add @studio/[email protected]-```--The project lockfile records the installed dependency tree. Updates are explicit package-manager-operations; Builds use the selected installed code. A missing package is an installation problem.-## Make a public release discoverablePeople can find a public component through its npm page, source repository, or a community link.diff --git a/skills/hypit/references/production/component-visuals.md b/skills/hypit/references/production/component-visuals.mdindex bbd64f0a..d0201be1 100644--- a/skills/hypit/references/production/component-visuals.md+++ b/skills/hypit/references/production/component-visuals.md@@ -40,7 +40,9 @@ visual relationships rather than the nesting of tags in Source.[visuals.ts](examples/visuals.ts) contains `renderCard`, a complete pure drawing function using`sealVisualTrack` from `@hypit/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.+Its colors, size, padding, layer and entrance duration are supplied by the caller. These drawing-function+arguments need not all become Surface parameters: the owning component can supply its fixed design+and expose only the inputs the production needs.The root uses Canvas coordinates. The text child uses the root's local coordinates, so padding isadded once. When a component computes child geometry in Canvas space, subtract the parent's origin@@ -126,12 +128,19 @@ video sampling and font handling while participating in the program's HTML layouused by the program belong in its `artifacts` list; `hyperframesResourceUri` supplies their resourceURLs. The rendering environment materializes those references.-For a semantic performance, `projectTimelineMedia(semantic, window.span)` from+For a placed performance, `projectTimelineMedia(timeline, window.span)` from`@hypit/hypit/timeline` returns each intersecting Take's prepared media, program span and source-span. Subtract the outer Window's start to obtain Present-local video sampling intervals. Preserve+span. Subtract the containing Present's start to obtain Present-local video sampling intervals+(when that Present uses the outer Window as its span, subtract the Window start). Preservethe returned source offset: moving or reframing a video changes its presentation while playbackcontinues from the same place. A separate Sound presentation can continue the existing audio in Film.+Project each independently meaningful event before rendering. Convert its program frame to the+containing Present's local frame once, then animate relative to that event. Keep source sampling+based on the returned source span; neither the event's local offset nor the viewport's movement+replaces it. [Component design](component-design.md#let-meaning-drive-the-behavior) distinguishes these+inputs from internal motion details.+A reusable scene might expose `during={story.selection.explanation}` for its lifetime and`reveal={story.moment.demonstrate}` for its layout change. The Surface projects these independently;the Producer receives a Window and an Instant. The installed Distribution'sdiff --git a/skills/hypit/references/production/examples/direction.svs b/skills/hypit/references/production/examples/direction.svsnew file mode 100644index 00000000..beee1f46--- /dev/null+++ b/skills/hypit/references/production/examples/direction.svs@@ -0,0 +1,14 @@+<?svml using="@hypit/text/svs@1"?>+<sheet version="1" id="performance">+ text-template.performance { separator: paragraph; }+ text-template.performance.block.direction {+ kind: slot;+ order: 10;+ slot: direction;+ }+ text-template.performance.block.dialogue {+ kind: slot;+ order: 20;+ slot: dialogue;+ }+</sheet>diff --git a/skills/hypit/references/production/examples/production.svml b/skills/hypit/references/production/examples/production.svmlindex bd7a3ed3..628c132b 100644--- a/skills/hypit/references/production/examples/production.svml+++ b/skills/hypit/references/production/examples/production.svml@@ -1,6 +1,5 @@<?svml using="@hypit/markup@1"?><svml>- <import as="media-track" from="@hypit/media-track@1"/><import as="sound" from="@hypit/sound@1"/><import as="performance" from="@hypit/performance@1"/><import from="@hypit/script@1"/>@@ -16,9 +15,10 @@<import as="film" from="@hypit/film@1"/><import as="render" from="@hypit/render-hyperframes@1"/><import as="look" source="./look.svs"/>+ <import as="kit" source="./direction.svs"/><script id="story">- <opening><HOST>Here is @{proof} the useful part @{/proof}.</opening>+ <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"/>@@ -29,9 +29,13 @@<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.+ HOST is the presenter, speaking to the camera with relaxed confidence.</text:Value>- <seedance:TextVideo id="performance" model="mini" prompt={direction}+ <text:Render id="prompt" template={kit.performance}>+ <text:Set name="direction" text={direction}/>+ <text:Set name="dialogue" text={story.segment.opening.dialogue}/>+ </text:Render>+ <seedance:TextVideo id="performance" model="mini" prompt={prompt}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"/>diff --git a/skills/hypit/references/production/image-operations.md b/skills/hypit/references/production/image-operations.mdindex a96d314e..c8d496c0 100644--- a/skills/hypit/references/production/image-operations.md+++ b/skills/hypit/references/production/image-operations.md@@ -87,9 +87,9 @@ checks which Endpoint will serve this Source. A service advertising background ra matching Provider capability in the installed Distribution.For a speaking video cutout, the moving silhouette must be removed across the clip. This image-operation supplies neither video matting nor a moving mask. [Compositing](../playbooks/craft/compositing.md#inset-cutout-and-flattened-composite-are-distinct-choices)-explains the choice between a geometric inset, a still cutout and a live presenter cutout, including-how the same A-roll performance keeps its semantic role.+operation supplies neither video matting nor a moving mask. [Moving-media preparation](media.md#keep-original-and-processed-material-explicit)+explains video matting, operation order, retained originals and the processed picture's subsequent use.+[Spatial layout](spatial.md#shape-the-outer-frame) owns geometric clips such as circular insets.## Keep operation and presentation distinctdiff --git a/skills/hypit/references/production/index.md b/skills/hypit/references/production/index.mdnew file mode 100644index 00000000..dab351d4--- /dev/null+++ b/skills/hypit/references/production/index.md@@ -0,0 +1,73 @@+# Production: express, compose and deliver++Enter at the question the current work raises. These groups locate knowledge; they are not stages+that every task must complete. [System relationships](system.md) explains the common model.+Creation and the relevant [Format/Craft](../playbooks/index.md) supply the creative decisions.++For performance-led work, including pure A-roll and short drama, prefer Script → prepared+SemanticTakes → Timeline. Performance and Sound present the selected footage and audio; Caption and+other contributions join where useful. Semantic organization remains valuable even with no MG.+For a standalone asset edit, follow the actual material operation and deliver its output.++## Express the work++| Current question | Owner |+| --- | --- |+| How do materials, Timeline, Canvas, components and execution relate? | [System](system.md) |+| How do Source imports, references, values and Recipes work? | [Source syntax](source-syntax.md) |+| How do I write Script, spaces, pronunciation, Cues and semantic markers? | [Script syntax](script-syntax.md) |+| How do I connect the creative choices and revise existing work? | [Authoring](authoring.md) |+| Which installed interface fits, or how do I add a project package? | [Vocabulary](vocabulary.md) |+| How do I select or write a Prompt Kit? | [Prompt Kits](prompt-kits.md) |++## Prepare material and establish time and space++| Current question | Owner |+| --- | --- |+| Files, generated/reused outputs, stream selection, normalization, semantic preparation or processed variants | [Media preparation](media.md) |+| Take placement, gaps, overlap and complete duration | [Timeline](timeline.md) |+| Semantic events, clock positions, offsets, durations and timing edits | [Timing](timing.md) |+| Canvas, destination Frames, source extents, fit, crop and coordinates | [Spatial layout](spatial.md) |+| Download source footage | [Video downloads](video-downloads.md) |+| Obtain real screenshots, recordings or HTML graphics | [Browser capture](browser-capture.md) |+| Crop, resize, compose or isolate an image | [Image operations](image-operations.md) |++## Present content++[Tracks](tracks.md) chooses by content source and shared behavior, without classifying files as+A-roll-only or B-roll-only.++| Current question | Owner |+| --- | --- |+| Present existing Timeline footage; change its treatment while playback continues | [Performance](performance.md) |+| Place independent images, video or surfaces; choose sampling and replacements | [Media presentation](media-presentation.md) |+| Present existing Timeline audio; silence, gain or explicit source blends | [Sound](sound.md) |+| Place independent music, narration, ambience or effects | [Audio presentation](audio-presentation.md) |+| Present Script words with broad/local Styles or speaker filters | [Caption presentation](caption-presentation.md) |+| Exact fonts, multilingual text, Emoji and independent Typography | [Fonts and text](fonts-and-text.md) |++## Create the component the work needs++| Current question | Owner |+| --- | --- |+| What should share a component, and which choices should become inputs? | [Component design](component-design.md) |+| How do I connect Surface, projections, Fragment and Producers? | [Track authoring](track-authoring.md) |+| How do I draw elements, video, graphics and frame-driven motion? | [Component visuals](component-visuals.md) |+| How do I create a new Caption layout using existing wording and timing? | [Caption authoring](caption-authoring.md) |+| How do I expose meaningful Studio entities and actual author controls? | [Studio Companions](studio-companions.md) |+| How does an owner distribute and update a package across projects? | [Component sharing](component-sharing.md) |++## Execute, revise and deliver++| Current question | Owner |+| --- | --- |+| Choose Targets, file/Result Candidates and computed substitutes | [Runs](runs.md) |+| Decide which completed value preserves material while allowing this edit | [Reuse boundaries](authoring.md#reuse-produced-work-explicitly) |+| Plan, price, submit, follow, recover and retrieve work | [Builds and Results](builds.md) |+| Inspect the current picture, precise frames and continuous motion grids | [Snapshots](snapshots.md) |+| Assemble Film, request full/range rendering and export the result | [Rendering](rendering.md) |+| Open the selected work, read feedback and edit its Source | [Studio](studio.md) |+| Judge the actual performance, composition and encoded deliverable | [Review](review.md) |++For installation, service selection or local preparation, follow the [Environment routes](../../SKILL.md#where-the-current-question-is-answered).+Package vocabulary and package-local documentation own exact ports and implementation-specific options.diff --git a/skills/hypit/references/production/media-presentation.md b/skills/hypit/references/production/media-presentation.mdnew file mode 100644index 00000000..3cb89ec6--- /dev/null+++ b/skills/hypit/references/production/media-presentation.md@@ -0,0 +1,111 @@+# Present independent images, video and surfaces++Read this when explicitly supplying picture content and arranging its appearance or playback.+Use [Performance](performance.md) for footage and source positions already established by Timeline.+The distinction is content ownership, not whether the picture contains a person, covers the frame,+or has transparency. [Media preparation](media.md) owns the incoming values.++## Supply a source and its destination++With the named assets, Timeline, Canvas, Frames and Recipes declared:++```svml+<import as="media-track" from="@hypit/media-track@1"/>+<media-track:Track id="evidence" timeline={program.timeline} canvas={canvas}>+ <media-track:Item id="photo" image={product} extent={product-extent}+ frame={detail-frame} during={story.selection.example} appearance={look.media.still}/>+ <media-track:Item id="demo" media={demo-media.media}+ frame={detail-frame} during={story.selection.proof} appearance={look.media.clip}/>+</media-track:Track>+```++Each Item takes one direct source form: `image` with its actual `extent`, prepared `media`, or a+compositable `surface`. The current Surface takes no raw `video` attribute. Generated and file-backed+assets use the same inputs once they have the required Type. A still image needs no video conversion;+its Item supplies the display duration. Code-authored graphics can publish their own Track directly.++`frame` places the destination on the Canvas. `appearance` supplies fitting, clipping, decoration,+source sampling and required `stack-order`. [Spatial layout](spatial.md) explains fitting the source's+real extent into that Frame. Independent Items may overlap; a full-frame Item is also ordinary Media.++## Keep display time and source playback distinct++An Item's Window says when it is active. It can follow a Selection, Segment, Moment plus duration,+or an authored interval through the shared [time forms](timing.md). Its source sampling separately+says which frames to show. A semantic Window does not automatically inherit a Take's source offset.++For moving media, choose playback from the intended result:++| Intended behavior | Appearance `playback` |+| --- | --- |+| Play from the start at native speed, then expose the lower picture when exhausted | `once-start` (default) |+| Align native playback to the Window end | `once-end` |+| Hold the ending or beginning picture over excess time | `hold-start` / `hold-end` |+| Repeat at native speed with start/end alignment | `loop-start` / `loop-end` |+| Fit the selected source duration into the Window by retiming | `stretch` |++`trim-start` and `trim-end` select a pair of integer source-frame boundaries, with an exclusive end.+Omit both for the whole source. Under native playback, prepared media uses the Timeline's frame rate.+A shorter Window can truncate a longer clip; extending the Window does not extend the source.+Choose a hold, loop or retime only when that behavior serves the picture.++Durationless images reject playback and trim options. Their appearance Window is sufficient.+A surface's preparation supplies any frame information; its installed vocabulary describes the+applicable sampling. The `@hypit/media-track` README owns exact mode and boundary rules.++For example, independently replaying footage on a spoken claim can intentionally start that footage+from its beginning. Presenting the speaker continuously midway through a placed Take should instead+retain the Timeline source mapping through Performance or a project scene.++## Coordinate layers and replacements++An Item can declare ordered `Paint` and sampled `Layer` children instead of one direct source.+The Item owns the outer Frame, clip, border and motion; each sampled Layer has its own fit and+picture treatment. Use this when the parts make one framed unit. Separate Items own independent+placement. A richer scene can own further shared behavior in a [project component](component-design.md).++Use a Sequence when content replaces content in one visual slot:++```svml+<media-track:Track id="cards" timeline={program.timeline} canvas={canvas}>+ <media-track:Sequence id="steps" frame={card-frame} appearance={look.media.card}+ until={story.selection.demo} until-boundary="end">+ <media-track:Member id="first" image={first-image} extent={card-extent}+ at={story.moment.first}/>+ <media-track:Member id="second" image={second-image} extent={card-extent}+ at={story.moment.second}/>+ <media-track:Handoff id="replace" from="first" transition={look.transition.cards}/>+ </media-track:Sequence>+</media-track:Track>+```++Members have ordered activation Instants and the Sequence has a terminal Instant. Each adjacent+pair declares a Handoff, including a cut. `from` names the outgoing Member; the next Member is its+successor. Transition duration and boundary ratio shape the handoff around the logical event;+they do not relocate that event. The Sequence retains the shared outer geometry as its contents change.+Query the selected package for its exact Layer, Member, Sampling and Handoff forms.++## Move the presentation or sample the picture++A `motion` Recipe moves or fades the framed unit. `Sampling` children pan, zoom or rotate the fitted+picture inside that frame. A still can receive the same spatial sampling motion. [Spatial layout](spatial.md#move-the-frame-or-move-its-contents)+shows the distinction and an example.++A single Item's local motion may follow progress through its Window. When separate internal actions+answer separate lines, give them separate events or use a scene exposing those events. An outer+semantic Window alone cannot keep every internal action aligned with changed speech.++## Include sound deliberately++Source audio is opt-in: `source-audio="content"` selects the direct source, or a child Layer id selects+that Layer's sound. A `Sound` child can instead attach normalized audio to an Item's entrance/exit+or to a Sequence handoff. The Track publishes `.visual`, `.program`, and `.audio` when sound is present.+Film includes the desired outputs separately.++Source audio follows the selected sampling policy; holding a picture does not synthesize held sound.+An otherwise silent overlay leaves the Film's existing Sound contribution audible. Use+[Audio Track](audio-presentation.md) for independent sound placement and avoid routing the same voice twice.++When uninterrupted visual coverage matters, inspect semantic pause boundaries, source exhaustion+and transition opacity together. [B-roll](../playbooks/craft/b-roll.md) owns the editorial choice;+[review](review.md#make-the-composition-work) locates an unintended exposure in the actual picture.diff --git a/skills/hypit/references/production/media.md b/skills/hypit/references/production/media.mdindex 4267364d..2338939f 100644--- a/skills/hypit/references/production/media.md+++ b/skills/hypit/references/production/media.md@@ -1,15 +1,34 @@# Preparing media for a productionRead 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.+before using it in a component or a model reference. [Media presentation](media-presentation.md)+owns independent picture placement and playback; [Tracks](tracks.md) routes other content relationships.For a source video at a link, read [video download](video-downloads.md).For acquiring website screenshots, page recordings or local HTML graphics, read[browser capture](browser-capture.md).-Media carries picture and sound. Normalization establishes its frame clock, local duration and-selected picture/audio streams. A SemanticTake adds the association with a Script passage and the-local locations of its words and boundaries. [Timeline assembly](timeline.md) then determines where-the prepared Take belongs in the complete work.+## Choose preparation from the intended use++Keep source facts, preparation and presentation distinct:++| Material or use | What the next consumer needs |+| --- | --- |+| Still image, including a transparent cutout | Bytes and its real dimensions for independent placement; the component supplies its display Window. |+| Video, with or without audio or transparency | Selected streams, local duration and a frame clock when entering prepared-media composition inputs. |+| Audio | The selected audio stream and prepared local time; its role can be a Script performance, music, narration or an effect. |+| Compositable surface | Its declared pixels, extent and any animation information; use the producing package's output directly. |+| Code-authored text, shapes or a scene | The component's data and resources; it can draw directly without an intermediate media file. |+| A model reference | The exact image, video or audio input accepted by that model's Surface; normalization is not a universal prerequisite. |++Files, generated Outputs and earlier Results are sources of these values. A reference need not+appear in the film. A video containing a person is not automatically a SemanticTake; the author+establishes that relationship when it performs a Script passage. [Runs](runs.md) owns explicit Result+reuse. [Image operations](image-operations.md) owns still-image preparation.++Normalization establishes moving media's frame clock, local duration and selected picture/audio+streams. A SemanticTake adds one Script passage and its local word/boundary positions.+[Timeline assembly](timeline.md) then places that Take in the work. Independent material goes to its+own component without a SemanticTake. Its presentation still uses the same Timeline for event times.## Files and generated Outputs@@ -28,6 +47,28 @@ Surface can publish the same kind of value under an output path, such as `{portr`{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.+A supplied recording can be a reference for new work, an independent picture or sound, or material+the finished work retains. When the intended passage keeps its actual recorded delivery, that+recording can carry the Script without regenerating it. If only part of the file belongs in the+work, prepare a new file locally with `hypit media cut`:++```bash+hypit media probe assets/recording.mp4+hypit media cut assets/recording.mp4 --start 12.4 --end 19.8 --to assets/opening.mp4+hypit media cut assets/recording.mp4 --keep 12.4:15.7 --keep 16.2:19.8 --to assets/opening-edited.mp4+hypit media cut assets/voice.wav --keep 0.3:4.1 --keep 4.6:9.2 --to assets/narration-edited.wav+```++The first form retains one interval; repeated `--keep` joins selected parts of the *same* recording.+The command keeps existing audio and picture together and can write an ordinary MP4 or audio-only+WAV. Import that output as `asset:Video` or `asset:Audio` for its intended use. If the edited+delivery is a Script performance, normalize and align that result as the SemanticTake below.+Independent footage can instead enter Media or another visual component, with source sound included+when the work needs it. A file cut does not choose Script or Segment boundaries. The installed Video+CLI README owns exact options and output behavior. `hypit transcribe` accepts either audio or video+when a transcript helps inspect the recording; its word times refer to that input file, while a+retained edited performance receives its own semantic alignment in the Build.+An image reference can enter a model directly. A still placed by Media Track needs its actualIntrinsicExtent as well. Inspect its dimensions with `hypit media probe <file>` and declare themwith `space:Extent`; [spatial layout](spatial.md) explains extent versus destination Frame.@@ -63,12 +104,16 @@ unambiguous audio stream; select an explicit stream when the container has sever`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+with an exact local frame count, optional picture and optional audio on the chosen Clock. Audio isprepared as a 48 kHz render stem with its level preserved. Balance, fades and music ducking remainmix decisions in [Audio Track and sound mix](../playbooks/craft/sound-mix.md).## Associate a performance with Script+For a performance-led work, including pure A-roll and short drama, prefer this path even when the+picture needs no additional graphics. Script preserves the performed wording and meaningful+passages; semantic preparation lets later presentation and revisions use their actual times.+For an already declared Script and prepared spoken performance:```svml@@ -91,8 +136,9 @@ timing. [Timeline assembly](timeline.md) places Takes sequentially or at authoretranslates their local positions into Program time.Use the performed language supported by the selected package and Endpoint.-Audio-only A-roll follows the same path with audio-only media. Voice Clone produces the Segment's-performed audio from its Script and the person's Voice Reference. Normalize that output with+Audio-only A-roll follows the same path with audio-only media. Its final speech can be a supplied+recording, or Voice Clone can produce it from the Segment's Script and the person's Voice Reference.+Normalize that audio with`video="none"`, `audio="default"` and `span-authority="audio"`, then align it to the same Segment.The resulting SemanticTake publishes semantic time and sound through Timeline assembly without inventinga visual performance; the work's Media, Typography or MG Tracks supply the picture.@@ -113,7 +159,9 @@ The semantic Surface maps an empty Segment directly to its prepared media domainThis performs boundary materialization without a transcription request because the Segment has noTokens. Action, music or visual rhythm can determine the media duration. The ordinary SemanticTake-enters Timeline assembly alongside spoken Takes.+enters Timeline assembly alongside spoken Takes. This supplies Segment boundaries, not automatic+within-shot action detection. An event such as a silent door opening needs its own observed timing+if another component must respond to it. A simple material edit does not require inventing a Segment.## Give a still a duration when that is its role@@ -154,6 +202,45 @@ Use graph operations for repeatable preparation belonging to the production. `hyare useful for inspection and deliberately exported evidence. Image geometry changes, compositingand 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.-When the composition calls for isolating a subject from its background, read-[insets and background removal](../playbooks/craft/compositing.md#inset-cutout-and-flattened-composite-are-distinct-choices)-for the choice of treatment and how its processed media returns to this preparation flow.++## Keep original and processed material explicit++A crop, background removal or flattened composite produces a selected asset. Normalization prepares+that output; it does not make original pixels recoverable through a different presentation Style.+A transparent video can enter the same SemanticTake/Timeline/Performance path as an opaque video.+A circular clip or rounded Frame instead masks a presentation geometrically; it does not remove+the subject's background from the underlying bytes.++If the whole performance should use a processed picture, prepare it before the SemanticTake and+place that Take. When both the original and processed picture appear, keep both outputs and bind the+one each presentation needs. For example, Timeline can hold the cutout while an opening Media Item+explicitly uses the original. [Performance](performance.md#choose-the-picture-actually-held-by-the-timeline)+explains that presentation boundary.++For a moving portrait, the installed `@hypit/volcengine-matting` package exposes `Portrait` with+`source={performance.video}` and publishes `cutout.video`; query its vocabulary and README for+transparent formats and current Provider support. Existing transparent material can enter Normalize+directly. Removing a still reference's background does not establish transparency in generated video.++Choose an operation for the material it actually accepts: [image background removal](image-operations.md#remove-a-background)+produces a still cutout; a moving silhouette needs a video matte or suitable keying operation.+[Video direction](../playbooks/craft/video-direction.md#prepare-footage-for-subject-isolation) explains+preparing and judging footage for that use. A fixed flattened arrangement of still images can use+[Image Compose](image-operations.md#flatten-a-fixed-still-image-arrangement) when that is the desired output.++Operation order matters to the selected implementation. The current local Media Provider's Normalize+preserves input alpha, while its Transform emits opaque MP4. When using that Transform for trimming+or retiming a cutout performance, perform it before matting. Read the selected operation's output+behavior rather than assuming every video operation preserves transparency.++A picture-only operation can preserve the accepted local timing when frames still represent the+same source instants. A project preparation component may explicitly combine that picture with the+accepted Take's audio and evidence. That is an authored computation with both inputs, not automatic+variant inheritance. Trimming, retiming or replacing the performance changes the relationship and+requires timing prepared for that result. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)+explain which completed Output can remain selected.++Choose source proportions and framing for the actual footage the work needs. A full-frame spoken+piece can start from the final aspect ratio; a later inset or split does not dictate the generated+source shape. [Spatial layout](spatial.md) owns destination geometry. Image and video direction own+the camera view; pass those requests visible, performable facts rather than unconverted MG instructions.diff --git a/skills/hypit/references/production/performance.md b/skills/hypit/references/production/performance.mdindex c658407c..bab0ab68 100644--- a/skills/hypit/references/production/performance.md+++ b/skills/hypit/references/production/performance.md@@ -1,9 +1,14 @@# Presenting an existing performance-Read this to place existing A-roll full frame, in an inset, beside graphics, or in a changing layout.-[Timeline](timeline.md) places the prepared Takes; Performance directs their picture. Media Items-instead take independently supplied material, just as Typography supplies text while Caption uses-Script's words. A-roll may be audio-only, leaving the picture to other components.+Read this to present footage already placed on the [Timeline](timeline.md), including a pure A-roll+work whose picture stays full-frame. Performance obtains that footage and its current source position;+Uses direct how it appears. [Media Items](media-presentation.md) explicitly receive independent material+and playback choices. Picture size, subject and transparency do not select between these paths.++For a short drama, spoken scene or direct address, retain Script and the accepted SemanticTakes even+when a single full-frame Style is the complete visual treatment. A-roll's semantic role continues+through later reframing or coverage. An audio-only performance needs [Sound](sound.md) but supplies+no picture for Performance.## Broad treatment, local Uses@@ -31,6 +36,42 @@ fixed-duration change. No matching rule contributes no picture; an intentionallyrule stays empty. Source gaps and audio-only Takes need no visual stand-in. Extend Timeline's endfor a code-authored closing passage, and place its graphics there directly.+## Preserve source playback and the original Use time++Timeline placement determines which source frame is current. If a Take starts at program second 5,+a Use beginning at second 7 sees source second 2. Hiding and showing footage does not restart it.+The Style also retains the original Use Window for its animation, even where another Use covers+part of it or a Take boundary cuts through it. Visibility, source playback and animation progress+are separate facts.++The ordinary Style draws available visual sources in Timeline declaration order, later above+earlier. Timeline itself retains them all. An audio-only Take contributes no picture; a gap remains+empty. Overlapping sources do not automatically crossfade, and separate Performance Tracks can+intentionally show the same content in multiple places.++For simultaneous views of the current performance, share this Timeline mapping and let each visual+owner choose its crop and treatment. A close foreground and enlarged background can therefore show+the same source instant. A replay starting from a chosen earlier moment has a different playback+relationship: supply that prepared source to Media or the scene explicitly. Neither use requires+another copy of the speech in Film.++## Choose the picture actually held by the Timeline++A Take contains the selected prepared picture, including any background removal already performed.+Changing its Frame, crop or Style does not restore an original background. Keep the original output+and bind it explicitly when a presentation needs it. [Media preparation](media.md#keep-original-and-processed-material-explicit)+owns that material choice and any preparation adapter.++For example, a cutout can continue in a lower corner through Performance while an opening Media Item+shows the retained original from the start of the same passage. If the handoff occurs later inside+a Take, both pictures need the corresponding source position. A project Style or scene can receive+the original explicitly and use the Timeline projection to sample it, when the two inputs share+that frame mapping. It does not search for hidden variants or assume two independent clips align.+Route the intended voice once through Sound. A direct cut between those materials needs no animated+journey between their Frames. If the intended effect instead dissolves an original into its cutout,+both views must depict the corresponding source instant and align the subject through their fitting,+crop and transforms. Equal destination Frames alone do not establish equal subject geometry.+## Give a new visual behavior a StyleA recurring presenter motion can be a project Style. It receives the Timeline, Canvas and original@@ -38,10 +79,14 @@ Use Window, plus its own explicit parameters. Think of a specific reusable behavfull-frame viewport moving into a side Frame. The family owns its trajectory and exposes the inputsthat make it useful; arbitrary Styles do not automatically morph into one another.-Declare the initial treatment, then the settled treatment starting at the event, then the short-movement Use last. It covers the start of the settled treatment and naturally reveals that treatment-when finished. Matching endpoint geometry comes from shared Frames or parameters. The source video-continues playing throughout; partial coverage does not reset its animation clock.+For a direct switch, a local Use selects the new treatment at its semantic event. For a continuous+handoff, declare the initial treatment, then the settled treatment starting at the event, then the+short movement Use last. It covers the start of the settled treatment and reveals that treatment+when finished. Match both endpoint Frames and their source fitting/crop through shared values so the+subject meets the intended view. The source video continues playing throughout; partial coverage+does not reset its animation clock. Additional actions that answer other words receive their own+projected events, as described in+[component design](component-design.md#let-meaning-drive-the-behavior).An overlap transition is also a Use. For two Takes, its Window can run from the next Segment's startto the previous Segment's end:diff --git a/skills/hypit/references/production/prompt-kits.md b/skills/hypit/references/production/prompt-kits.mdindex 0e98d0db..2c57c513 100644--- a/skills/hypit/references/production/prompt-kits.md+++ b/skills/hypit/references/production/prompt-kits.md@@ -135,6 +135,15 @@ produced elsewhere remains a graph edge rather than being copied into a scalar b</svml>```+Save the template above as `phone-shot.svs`. For this example, `look.svs` can be:++```svs+<?svml using="@hypit/svs@1"?>+<sheet version="1">+ prompt.main { camera: handheld; }+</sheet>+```+The optional Recipe supplies scalar properties consumed by the template. Template defaults applyfirst, Recipe values replace those defaults, and explicit `text:Param` children replace Recipevalues. `text:Set` replaces one Text binding through a graph edge; `text:Append` adds another Textdiff --git a/skills/hypit/references/production/rendering.md b/skills/hypit/references/production/rendering.mdindex e6d0de99..ab9394bc 100644--- a/skills/hypit/references/production/rendering.md+++ b/skills/hypit/references/production/rendering.md@@ -3,8 +3,9 @@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+Components author the picture and sound contributions. Film assembles the selected contributions+with Timeline and Canvas into a Composition. Rendering evaluates that composition over a frame+interval and produces the encoded media. Thesame composition can therefore be inspected in Studio, rendered in part, or rendered as a whole.## Assemble the picture and sound@@ -27,7 +28,7 @@ With the named inputs already declared:<film:Track source={voice.audio}/><film:Track source={coverage.visual}/><film:Track source={captions.track}/>- <film:Track source={music.track}/>+ <film:Track source={music.audio}/></film:Film><render:Video id="final" composition={main.composition} timeline={speech.timeline}/>```@@ -38,7 +39,9 @@ picture leaves the included performance audio audible. Layer order is authored iPresents, 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.+A compatible Composition from another component can also feed the render Surface. Pure A-roll may+need only the Performance and Sound contributions, with Caption when wanted. Additional coverage+and graphics in this excerpt illustrate optional independent contributions.## Compose an authored animation@@ -108,24 +111,21 @@ Before the first local render, or when browser startup reports a missing executa[browser preparation](../environment/local-tools.md#prepare-the-local-rendering-browser).That selected Provider owns browser installation and download configuration.-For the local HyperFrames Provider, `workers` selects independent Chrome processes within one render.-They share the staged document and decoded source frames, capture different parts of the selected-interval, and produce one encoded result. Prefer `workers: "auto"` for ordinary local rendering;-the Provider adjusts capture concurrency within its reserved ceiling using the current job's work.-An explicit worker count preserves that deployment choice. `defaultConcurrency` limits simultaneous render Needs;-optional `browserCapacity` budgets their combined browser reservations. These belong to the Runtime-configuration; the Source keeps the same render declaration. [Runtime profiles](../environment/profile.md)-explains shared capacity and inspecting the selected Provider's configuration. The local HyperFrames-Provider supports range requests. A project Provider declares the request forms its deployment supports.+The local HyperFrames Provider supports range requests and can capture different parts of one+render with several browser workers. Browser selection, download settings and worker capacity+belong to that Provider's Profile configuration. [Runtime profiles](../environment/profile.md)+and the selected Provider's README own those choices; the Source retains the same render declaration.+Another Provider declares the request forms its deployment supports.A short interval reduces frame capture and source-frame extraction, but still prepares the document'sdeclared assets and validates typed Surfaces. Extra browsers help only while the machine can use them;preparation and final encoding contribute separately. Reusing media through the Run avoids generation work; it doesnot preserve a previous render's temporary preparation.-For a local composition change, render the interval that shows the changed relationship and its-handoffs. Keep accepted material selected in the Run, then render the complete deliverable when-the composition is ready. Frame ranges reduce repeated work without changing the authored clock.+For a local composition change, use [snapshot](snapshots.md) first to inspect the changed+relationship and its handoffs in the current Studio programme. Keep accepted material selected in+the Run. Range rendering supplies an encoded clip when that is needed; render the complete+deliverable when the composition is ready.While rendering, communicate the current phase and meaningful progress. The Provider reportsdecoding, browser startup, capture, encoding and storage; `hypit logs <build-id>` preserves theirtimings and execution details when a slow or failed stage needs investigation.diff --git a/skills/hypit/references/production/review.md b/skills/hypit/references/production/review.mdindex f89727cf..a09ca498 100644--- a/skills/hypit/references/production/review.md+++ b/skills/hypit/references/production/review.md@@ -3,6 +3,10 @@Read this when opening Studio, judging an encoded Result, or improving the layout, timing andexpression of the new Film.+For picture inspection, start with [Snapshots](snapshots.md) of the current Studio work or existing+HTML. Single frames establish detail; continuous frame grids establish movement and handoffs.+Use Studio playback to hear and feel the passage, and the exported file to judge encoded delivery.+[Studio](studio.md) explains launch, session reuse, displayed information, Source writeback andproject Companions. [Timestamped Comments](studio.md#revise-from-timestamped-comments) connects userfeedback to the owning production facts. [Builds and Results](builds.md) explains retrieval and explicit Output reuse.@@ -14,7 +18,9 @@ render and inspect that encoded deliverable as a separate step.## Make the composition work-Compose MG, Caption, B-roll, Typography and Effects around the directed material and existing Outputs.+Watch the selected performance and its assembled picture and sound. In pure A-roll, judge whether+speech, action, reactions, camera changes and pauses carry the intended passage. In a mixed work,+judge the additional Caption, evidence and graphic relationships together with that performance.Watch their actual arrangement in Studio or a rendered Result: is the comparison clear, is theCaption readable, does the B-roll cover the intended explanation, and do entries and exits land onthe right words or actions? Does a persistent object retain its identity and state through the@@ -31,8 +37,8 @@ and semantic Outputs through layout and component revisions.Use the Run that selects the production's actual material. It binds the Author Source, Targets,files and earlier Results. Preserve the produced media and semantic Outputs as the composition-changes. A focused Run can render the affected interval; Studio can open the same selected work-for interactive playback and editing.+changes. Studio opens the selected work for playback and editing; snapshot captures its current+compiled picture directly. A focused Run serves a requested encoded interval.Judge the relationship that the evidence can establish. A component's own example can show itsstyle and behavior. The actual production image establishes its framing and color; the produced@@ -50,7 +56,7 @@ Present intermediate work with its purpose, what it already realizes and the impneeded for the Brief. A storyboard can settle framing; the produced performance establishes howa person actually moves and speaks. A working preview can support either discussion. Make itscurrent scope clear so the user can give useful direction, and continue the remaining work within-the agreed commission. [Environment selection](../environment/profile.md) owns unresolved service choices.+the agreed commission. [Service selection](../environment/model-and-provider.md#choose-the-practical-capability-path-with-the-user) owns unresolved service choices.Read missing behavior through its material and presentation together. For intended speech, listen tothe selected Film: an available audio file establishes material, while admission and the chosen@@ -72,15 +78,15 @@ location remains an open question.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.+- Once frame positions are known, use [snapshot](snapshots.md) to inspect the existing programme+ directly. Select individual states or continuous frames; keep the surrounding handoffs visible.+ The locations can come from semantic events, the playhead or authored clock time.- On an encoded Result, focused media operations such as frames, cut, and tile can expose exactpixels, adjacent frames, or a short passage.- Open Studio when interactive playback, parameter editing or a component's Companion helps thecurrent work. Seek or select semantic entities to inspect their place in the composition.+- Use a [range render](rendering.md#choose-a-render-interval-in-frames) when the question requires+ an encoded clip with sound, such as testing an export setting or delivering a passage.- Watch the whole deliverable when the question concerns Hook clarity, story movement, payoff,CTA, or how A-roll, B-roll, Caption, MG and Effects work together.@@ -90,11 +96,14 @@ media supplies that evidence.Inspect the relationships that make the composition work:+- **performance** — the selected footage actually contains the intended speech, action and reaction;+ presentation motion does not substitute for missing action in the material;- **picture and coverage** — B-roll supports the passage and its display window carries the intendedexplanation or handoff;- **semantic timing and motion** — cuts, Caption Cues, MG states and Effects occur on the- intended word, phrase, pause, or clock event; entry, settling, active behavior and exit make the- intended emphasis and handoff perceptible;+ intended word, phrase, pause, or clock event; inspect important internal events as well as the+ outer interval. A scene that starts on the correct phrase can still reveal its result on the+ wrong word. Entry, settling, active behavior and exit should make the intended handoff perceptible;- **shared layout** — a layout established for a passage remains coherent while its individualcontents change; inspect the handoffs as well as the populated states, so replacing a card orending a Selection does not accidentally release space the passage still needs;@@ -110,6 +119,12 @@ Check containment and capacity at each boundary, then judge optical alignment. Ibleed, overlap, and asymmetric balance are part of the design when they help the work; measurementsdescribe what happened and the picture decides whether it succeeds.+At a visual handoff, inspect what is actually visible before, during and after the change. A return+to the speaker may be intended; a one-frame flash of that picture between other views may not be.+If the exposure is unintended, locate the owning cause: the active Window, source playback,+transition opacity, component background lifetime or spatial crop. Several Frames or a designed+background can form the intended picture without one full-frame source.+Repeated appearances of one observed visual configuration can share a judgment. A visibly changedspeaker, placement, Style, content shape, behavior, or surrounding composition supplies differentevidence.diff --git a/skills/hypit/references/production/runs.md b/skills/hypit/references/production/runs.mdindex e1ed561e..d0ff7aa9 100644--- a/skills/hypit/references/production/runs.md+++ b/skills/hypit/references/production/runs.md@@ -42,7 +42,8 @@ not Run declarations.Replace `bld_...` with the actual Build id found through Results. The historical `output` is thename in that Result; the `satisfy output` is the current Author Output. Keeping this SemanticTakepreserves both media and timing when its Script identities still fit. A changed Caption or MG can-then recompute downstream.+then recompute downstream. Marker and display-only edits may also preserve the Take; use the+[reuse table](authoring.md#reuse-produced-work-explicitly) to distinguish them from changed speech or media.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.@@ -97,7 +98,9 @@ The resulting Candidate is named `product-hold.video`. Selecting it replaces theMedia requests depend on the Script, direction, references and requested duration. Once thosechoices are ready and the commission covers their cost, a Run can target the prepared Takes whilecomponent and Recipe work continues. Shared decisions such as where a presenter leaves room for-an overlay belong in Treatment and image direction; encode them in both the material and composition.+an overlay belong in Treatment. Translate the material side into visible camera facts for image+and video direction; pass the composition side as actual layout and event inputs. Independent+requests can run while their downstream components are authored.The small [production Source](examples/production.svml), [Recipe](examples/look.svs),[material Run](examples/material.svrun) and [production Run](examples/production.svrun) illustratediff --git a/skills/hypit/references/production/script-syntax.md b/skills/hypit/references/production/script-syntax.mdnew file mode 100644index 00000000..8d14a30c--- /dev/null+++ b/skills/hypit/references/production/script-syntax.md@@ -0,0 +1,236 @@+# Script syntax++Read this when writing or correcting `<script>`, including display spelling, pronunciation,+spaces, Caption grouping and semantic markers. [Script and semantic time](../creation/script-and-time.md)+owns the creative decisions; [Source syntax](source-syntax.md) owns imports and graph references;+[Timing](timing.md) explains how components use the resulting identities.++These are the current 0.2 author forms. Package releases and logical Module ABIs are different:+`@hypit/script@1` remains the import. A syntax error calls for an explicit correction to the source;+do not reinterpret old bare markers or remove authored spaces to make an inherited example work.+The installed Script package owns the parser and exact diagnostics.++## Keep the languages distinct++| Where you are writing | Form | Meaning |+| --- | --- | --- |+| Structured Source attribute | `narrative={story}` | A whole-value graph reference. |+| Script prose | `@{reveal!}` | A semantic Moment; contributes no displayed or spoken text. |+| Script prose | `clear{emphasis}` | An attribute on the preceding display word. |+| A model's prompt text | `@image1` | That model's reference notation, when its Kit declares it. |+| A temporal attribute | `instant="moment.cue + 8f"` | The component's explicit time expression. |++Braces and at-signs have no global substitution rule. The receiving Surface owns its body's grammar.++## Structure, grouping and display attributes++The author-facing forms are:++| Form | Meaning |+| --- | --- |+| `<opening>...</opening>` | A Segment named `opening`; all spoken prose belongs inside a Segment. |+| `<pause/>` | A self-closing Segment with identity and boundaries but no words. |+| `<HOST>` | A Role Cue inside the current Segment; it applies until another Role Cue or the Segment end. |+| `<display text \| spoken text>` | One Dual Text unit with separate visible and pronounced wording. |+| `<display text\|>` | One complete display/speech unit using the same wording for both; individual spoken word times remain available. |+| `< \| spoken text>` | Spoken words that keep semantic timing while contributing no visible Caption words. |+| `\|\|` | A Caption Cue handoff between complete Alignment Units. |+| `word{emphasis,keyword}` | Boolean attributes on one complete display word for a Caption family to interpret. |+| `word{importance=2,tone=warm}` | Named string, number or boolean attribute values on that display word. |+| `@{proof} ... @{/proof}` | A Selection: one named semantic range. |+| `@{claim!}` | A Moment: one named semantic point. |++A Script contains one or more uniquely named Segments matching `[a-z][a-z0-9_-]{0,63}`;+`script` is reserved. A paired Segment can carry prose or be wordless; the self-closing form also+carries a wordless passage. A Role Cue is a bare turn marker: the next Role Cue begins the next turn,+and closing the Segment ends the final turn+and resets its Role. When a Segment uses Roles, place the first Role before that Segment's first+spoken text. One Segment can contain several Role turns without requiring several generated Takes. A bare tag+inside a Segment is a Role Cue by context, not by capitalization: `<host>`, `<主持人>` and+`<진행자>` can name speakers. The label directs the request through dialogue; it selects no voice+or character asset by itself.++Dual Text can contain several visible or spoken words on either side; its display side feeds Caption+and its spoken side feeds pronunciation. An empty display side intentionally omits those spoken words+from Caption while keeping them in the Narrative and semantic timing. Selections and Moments can be+placed on the spoken side because that side owns the speech anchors. Place Cue Breaks around the+complete Dual Text unit, not inside it. Attributes for a displayed Dual Text word belong on the+display side before the pipe. Inside that display side, use `\@` when the visible text itself needs an+at-sign.++The three Dual forms serve distinct author choices:++| Script fragment | Display | Speech | Use |+| --- | --- | --- | --- |+| `<S\|ess>` | `S` | `ess` | Keep the spelling while specifying the letter's spoken name. |+| `<New York\|>` | `New York` | `New York` | Keep the same words and internal space in one complete correspondence. |+| `<\|再见>` | No Caption words | `再见` | Retain speech and its semantic anchors without displaying it. |++[Pronunciation choices](../creation/script-and-time.md#choose-the-sound-the-spelling-should-carry)+shows letter names, abbreviations, coined names and homophonic readings. The spoken side is ordinary+Text supplied to the selected model, not a separate phonetic language interpreted by Script.++When the wording is identical, `<组件化|>` is shorthand for `<组件化|组件化>`. It can group a name,+compound or phrase for Caption presentation while leaving its spoken Tokens and timing intact:+`把<动效|><组件化|>。|| 以后就能<直接复用|>。` Choose groups for the intended expression; ordinary+Chinese prose does not require word-by-word markup. The group's Style determines its visual response;+`||` still controls which reading phrases appear as separate Cues.++With speech omitted, the left side supplies both projections, so semantic markers can be placed+there and Studio writes back there: `<组@{beat!}件化|>`. Display attributes and markers are annotations,+not spoken words. Attributes still apply to the preceding display word rather than the whole group.+With an explicit spoken side, markers continue to belong on that right-hand side.+Either form needs a spoken word: `<API|...>` supplies no speech correspondence for its display.++Script comments contribute no text and do not split a word: `hel<!--note-->lo` remains `hello`.+In ordinary prose, a comment or zero-width marker also leaves a following attribute attached to its+word: `hello<!--note-->{emphasis}` and `hello@{beat!}{emphasis}` annotate `hello`.+An actual space before `{emphasis}` breaks that attachment.+A comment can also stand between passages:++```svml+<!-- This note enters no text projection. -->+<social><HOST> Follow us \@hypit.</social>+```++Reserved Script punctuation remains literal when escaped: `\@` produces `@`, `\<` produces `<`,+`\{` produces `{`, `\}` produces `}`, `\|` produces `|`, and `\\` produces `\`. A plain `>` needs+no escape in ordinary prose; inside Dual Text, `\>` keeps it from closing that unit. A single `|` in+ordinary prose is literal; `||` is the Caption Cue handoff. Inside Dual Text, the first unescaped `|`+separates display from pronunciation; write `\|` for a literal pipe and `\|\|` for two literal pipes.+These escapes belong to Script prose, while structured Source attributes and elements use the Markup+escaping described in [Source syntax](../production/source-syntax.md).++Script derives speech tokens from words and numbers. Punctuation remains attached to the displayed+word it belongs with and does not create another speech time unit. CJK prose commonly contributes+one Han, Hiragana or Katakana character per lexical unit; compounds, decimal numbers and the spoken+side of Dual Text preserve their own lexical structure. This is why Cue breaks, word attributes and+semantic markers attach to complete authored units instead of punctuation or visual line positions.+Character-level timing does not call for character-sized Cues: use `||` for meaningful reading+phrases. [Caption craft](../playbooks/craft/captions.md#language-changes-the-reading-unit) explains+Chinese, English and mixed-script grouping, spacing and their fit in the picture.++## Preserve spelling independently of timing++Ordinary whitespace runs become one displayed/spoken space. Leading and trailing whitespace in a+Turn and padding at the edges of each Dual side are omitted. A Source newline is prose formatting;+`||` makes a Caption Cue handoff, and the Caption family controls visual line wrapping.++| Script body inside a Segment | Display text | What the author chose |+| --- | --- | --- |+| `是的 就是这样` | `是的 就是这样` | A real space in Chinese prose. |+| `是的@{answer}就是这样@{/answer}` | `是的就是这样` | Joined text with a zero-width semantic range. |+| `是的 @{answer}就是这样@{/answer}` | `是的 就是这样` | The same range after an authored space. |+| `Hello @{place}New York.@{/place}` | `Hello New York.` | English spaces and attached punctuation. |+| `이건 3개월 동안 만든 영상이에요.` | `이건 3개월 동안 만든 영상이에요.` | Korean word spaces; no space inside `3개월`. |+| `3 개월` | `3 개월` | An explicitly different spelling. |+| `3D` / `3 D` | `3D` / `3 D` | Numeric/Latin adjacency is also authored. |+| `<New York\|>` | `New York` | One Alignment Unit with an internal space. |+| `<API\|A P I>` | `API` | One correspondence to several spoken tokens. |+| `<\|只说不显示>` | *(no visible words)* | Spoken content and semantic timing remain. |++Do not insert spaces around markers for parsing, strip Chinese spaces, or infer Korean/English gaps+from speech tokens. A space is display information, not an extra timed token. Caption consumers use+`separatorBefore` together with each display word's `text`; suppress a leading separator at a displayed+line/Cue start. [Caption authoring](caption-authoring.md) explains consuming these values in a new family.++The Script source and its projections answer different needs. Source preserves the author's prose;+display and speech normalize ordinary whitespace as above. Studio moving a marker relocates only+that annotation and retains unrelated source whitespace. Explicit Script formatting may reindent+and compact whitespace while preserving the same parsed meaning.++## Use the Script's deliberate projections++One Script publishes the full Narrative and the narrow views needed by the rest of the work:++| Reference | What it carries |+| --- | --- |+| `{story}` | The complete authored Narrative. |+| `{story.segment.hook}` | The `hook` Segment as a NarrativeExcerpt for one SemanticTake. |+| `{story.segment.hook.dialogue}` | Role-aware dialogue using the spoken side of Dual Text, suitable for a speaking performance request. |+| `{story.segment.hook.speech}` | Pronunciation-only Text, suitable for `hypit measure` or independent speech. |+| `{story.caption}` | Display Words, Alignment Units, attributes, Roles, and authored Cue Breaks for Caption. |+| `{story.selection.proof}` | The named semantic range. |+| `{story.moment.claim}` | The named semantic point. |++For example, this Segment inside `story` assigns two speaking turns:++```svml+<exchange>+ <HOST> Let me show you.+ <GUEST> That looks much easier.+</exchange>+```++`{story.segment.exchange.dialogue}` supplies:++```text+HOST: Let me show you.+GUEST: That looks much easier.+```++Pass that Text to the speaking prompt. In action direction, relate HOST and GUEST to the supplied+character views and voices. The selected [Prompt Kit](prompt-kits.md) owns its reference+order; [podcast direction](../playbooks/formats/two-person-podcast.md#direct-conversation-inside-a-take)+shows how those roles and references form one performed exchange.++These are projections of one authored Script, not copies to maintain. The performance request,+Caption system, and semantic timing therefore remain connected even when their visible and spoken+wording differ.++## Bind meaning to Script identities++Every semantic marker is enclosed in `@{...}`, with `/`, `!` and `~` inside. The marker contributes+no text or whitespace. `是的@{part}就是这样@{/part}` stays joined; `是的 @{part}就是这样@{/part}`+keeps its authored space. Do not add spaces to make a marker parse. Markers cannot split a speech+Token or its attached punctuation: write `@{beat!}“测试”`, not `“@{beat!}测试”`.+`hel@{beat!}lo` and `안@{beat!}녕` also split tokens. Grouping with Dual Text does not make these+positions legal. Attributes stay attached to their display word: `word{emphasis}@{beat!}`.+Write literal `@{part}` as `\@\{part\}`.++Selections may overlap, cross, or span Segments; they are named semantic ranges rather than nested+markup. Selection and Moment names share one namespace and match `[a-z][a-z0-9_-]{0,63}`.+Inside spoken text, each marker chooses an+adjacent semantic boundary:++| Marker | Boundary |+| --- | --- |+| `@{name}` | Open a Selection at the next word's start. |+| `@{~name}` | Open a Selection at the previous word's end. |+| `@{/name}` | Close a Selection at the previous word's end. |+| `@{/name~}` | Close a Selection at the next word's start. |+| `@{name!}` | Place a Moment at the next word's start. |+| `@{~name!}` | Place a Moment at the previous word's end. |++Markers may sit between or outside Segments when the meaning crosses structural passages. For+example, this Selection owns the complete Script program rather than borrowing the first and last+word boundaries:++```svml+@{~whole}+<opening><HOST>First thought.</opening>+<answer><HOST>Final answer.</answer>+@{/whole~}+```++At a Script or Segment edge, the corresponding structural boundary remains available even when+there is no neighboring word. Thus `@{videos} videos @{/videos}` covers exactly that word. Adjacent+visual Windows can share a boundary at either side of the pause between words. To give that pause+to the incoming picture, meet at the previous word's end:++```svml+@{coffee} my coffee @{/coffee} @{~smoothie} my smoothie @{/smoothie}+```++To give it to the outgoing picture, meet at the next word's start:++```svml+@{coffee} my coffee @{/coffee~} @{smoothie} my smoothie @{/smoothie}+```++Both Selections now meet at one instant in either example. A `||` between the phrases changes+Caption grouping, not their visual boundary. [Material-led picture craft](../playbooks/craft/b-roll.md)+owns whether the edit should meet there, leave a pause visible or let another picture continue.++The marker locates meaning, not an animation's lifetime. A reveal may leave its answer visible;+a covering picture may occupy the full Selection. [Timing](timing.md) explains those consuming forms.diff --git a/skills/hypit/references/production/snapshots.md b/skills/hypit/references/production/snapshots.mdnew file mode 100644index 00000000..b3af50b2--- /dev/null+++ b/skills/hypit/references/production/snapshots.md@@ -0,0 +1,90 @@+# Inspect the current picture++Use `hypit snapshot` first when the question concerns an existing production's visible state,+layout or motion sequence. It captures selected frames of the current picture through the+Profile's `render-frames` Endpoint. Studio playback supplies motion with sound; an encoded video+supplies evidence about the delivered file. Choose the view that establishes the relationship.++## Capture the work already open in Studio++Open the actual Run using [Studio](studio.md). After its current preview is ready:++```bash+hypit snapshot --studio http://localhost:5191 \+ --at-frame 240 --to evidence/comparison-detail++hypit snapshot --studio http://localhost:5191 \+ --at-frame 240,255,269 --grid 3x1 --cell 480 --to evidence/comparison-states++hypit snapshot --studio http://localhost:5191 \+ --start-frame 240 --end-frame-exclusive 270 --step-frames 1 \+ --grid 4x3 --cell 480 --to evidence/comparison-motion+```++Use the address of the existing Studio session and frames located in that programme. The examples+demonstrate the options. Locate meaningful events through Script, Timeline or the Studio playhead;+pass their resulting frame positions to the observation command. Frame selection does not change+the authored timing relationship.++Studio supplies its already compiled `HyperframesDocument` and the material selected by the Run.+This preserves declared fonts, images, video sampling, transparent Surfaces and resources used+inside a component's browser program. The command sends one immediate request, keeping the original+programme clock and component-local clocks. It writes images directly into the chosen directory.+There is no new Build, material generation or video encoding in this call.++Use `--runtime <profile>` and `--workspace <project>` when the invocation needs an explicit selection;+otherwise run in the project that already selected its Profile. The command names the selected+Endpoint before execution. If several Endpoints offer frame capture, select one with the Profile's+`@hypit/render-hyperframes@1#render-frames` binding. Browser preparation remains with that Provider:+[local tools](../environment/local-tools.md#prepare-the-local-rendering-browser).++## Read frames at the scale the question needs++- `--at-frame` chooses one frame or a strictly increasing list of frames.+- A range includes `--start-frame` and excludes `--end-frame-exclusive`. `--step-frames 1` retains+ every frame. Frame indices start at zero on the original programme clock.+- Every selected frame is saved as a full-size PNG. Open one for typography, edges and geometry.+- `--grid columnsxrows` adds paginated contact sheets. `--cell` chooses the width of each picture;+ labels sit below it and give its original frame index and time. The full-size PNGs remain available.+- `--json` reports the output paths and frame positions for subsequent inspection.++Widen the interval to understand a handoff, follow every frame to understand a movement, and enlarge+the image to judge small detail. Compare the corresponding event in reference and production;+different performances can put that event at different seconds. Revisit the whole passage in Studio+to hear and feel how the observed states work together.++## Existing HTML and source video++An already materialized HyperFrames HTML file can also be the input:++```bash+hypit snapshot ./picture/index.html --at-frame 240 --to evidence/html-detail+```++The HTML carries its compiled frame clock and frame-sampling declarations. Its directly referenced+media and fonts travel with the request; scripts and styles are inline. An HTML URL is accepted too.+For a current Studio work, prefer `--studio`: its compiled document also retains resource declarations+inside JavaScript data and the full typed Surface input. Snapshot is a programme-frame operation;+[browser capture](browser-capture.md) owns screenshots of ordinary websites and applications.++For an existing source video or encoded Result, use the media commands. Native-frame extraction+decodes each chosen interval once and retains the source's actual timestamps, including variable+frame rates:++```bash+hypit media tiles reference.mp4 --start 8 --end 9 --every-frame \+ --columns 4 --rows 3 --cell 480 --to evidence/reference-motion+```++`media frames --every-frame` saves individual images; `media tiles --ranges ranges.json+--every-frame` follows several selected intervals. `--transcript` adds the words around each+actual frame. [Reference understanding](../creation/reference-video.md) connects these views to+coarse and fine observation.++## After a composition change++Keep accepted material selected in the Run, let Studio compile the updated Source, then capture the+affected states and their handoffs. Carry discoveries back to the owning Source, component or+Treatment. This is the preferred picture-review path. Use a+[range render](rendering.md#choose-a-render-interval-in-frames) when a short encoded video with sound+is the evidence or deliverable needed; render and inspect the full file for final export.diff --git a/skills/hypit/references/production/sound.md b/skills/hypit/references/production/sound.mdindex 85f5d81a..979f287e 100644--- a/skills/hypit/references/production/sound.md+++ b/skills/hypit/references/production/sound.md@@ -1,8 +1,7 @@# Presenting existing soundUse Sound to present audio from Takes already placed on the [Timeline](timeline.md). Use-[Audio Track](tracks.md#sound-text-and-caption-answer-different-events) for independently supplied-music and effects. Sound chooses how existing sources are heard; [Performance](performance.md)+[Audio Track](audio-presentation.md) for independently supplied sound. Sound chooses how existing sources are heard; [Performance](performance.md)chooses how their pictures appear. Neither changes the Script or the Take placements.## Broad treatment and local Usesdiff --git a/skills/hypit/references/production/source-syntax.md b/skills/hypit/references/production/source-syntax.mdindex 5a97b9f7..e4f475ef 100644--- a/skills/hypit/references/production/source-syntax.md+++ b/skills/hypit/references/production/source-syntax.md@@ -1,8 +1,8 @@# Reading and writing Source syntaxRead 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.+Run choices. [Script syntax](script-syntax.md) owns prose, Roles, Dual Text, Cue breaks, display+attributes and markers. [Timing](timing.md) explains how components consume those identities.[System relationships](system.md) explains authored values and computed Outputs.## Three documents, three decisions@@ -21,7 +21,7 @@ This small Author Source produces Text and Script values; it makes no media requ<import as="kit" source="./direction.svs"/><script id="story">- <opening><HOST>Here is @{proof} the useful part @{/proof}.</opening>+ <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}>@@ -71,7 +71,7 @@ declare their permitted attributes and children; Text has its own literal/templastructured Markup, use the receiving Surface's declared attributes, children, literals, Recipes andreference expressions, and escape `&`, `<`, `>`, `"`, and `'` as `&`, `<`, `>`,`"`, and `'`; comments use `<!-- ... -->` outside raw bodies. Script owns the punctuation-inside its raw body, as described in [Script and time](../creation/script-and-time.md).+inside its raw body, as described in [Script syntax](script-syntax.md).## Recipes are named valuesdiff --git a/skills/hypit/references/production/spatial.md b/skills/hypit/references/production/spatial.mdindex 31b7a01f..0a5bb0fd 100644--- a/skills/hypit/references/production/spatial.md+++ b/skills/hypit/references/production/spatial.md@@ -1,16 +1,23 @@# Spatial layoutRead 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. Read-[Compositing](../playbooks/craft/compositing.md#keep-physical-camera-and-editorial-space-distinct)-when deciding the relationship among the generated scene, camera framing and later visual layers;-this page owns their exact authoring geometry.+[Timing](timing.md); it is independent of these coordinates. Read+[component design](component-design.md) when deciding which content shares layout or motion;+[image direction](../playbooks/craft/image-direction.md) owns the source camera view. This page owns+the destination geometry, for Performance, independent Media and project scenes alike.## 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.+The Canvas gives the final image's pixel dimensions and coordinate basis. Introduce Frames and+component scopes where they help organize the picture; they need not tile the canvas or remain+separate rectangles. Components can overlap, share motion and own local trees. Canvas itself does+not contain a central list of layers. Each rendered Present supplies its own paint order.++An IntrinsicExtent gives a source image's actual dimensions. A Frame gives the destination rectangle+a consumer should occupy. A landscape image can retain its real extent while appearing in a portrait+composition. An A-roll source has no prescribed Frame or crop. For performance remaining mostly+full-screen, its intended final aspect can guide source direction; later insets or splits remain+presentation choices. Translate required source framing into visible camera facts before generation.```svml<import as="space" from="@hypit/spatial@1"/>@@ -47,7 +54,7 @@ commands. [Fonts and text](fonts-and-text.md) shows which Typography placement c## Fit the source into the Frame-Media Track separates two spatial roles:+Media Track and the ordinary Performance Style share two spatial roles:- The **destination Frame** places the visual on the Canvas and supplies its outer shape.- The **fitted content rectangle** places the scaled source inside that Frame. Its size and position@@ -69,7 +76,7 @@ Choose fitting through the component's appearance Recipe:- **cover** fills the destination and may crop the image;- **stretch** changes the source proportions to occupy the destination.-The installed vocabulary also exposes `fit-width`, `fit-height`, `native` and `scale-down` when one+The selected Media/Performance vocabulary also exposes `fit-width`, `fit-height`, `native` and `scale-down` when onedimension or the source's own pixel size should determine the scale. The default is centered`contain`. `fit: stretch` is spatial resizing; Media Track's `playback: stretch` is a separate choiceabout video speed.@@ -167,8 +174,8 @@ coordinates the viewport with surrounding graphics can own the shared motion in[component program](component-visuals.md#compose-video-and-graphics-in-one-browser-program), retainingsource playback positions.-[Tracks](tracks.md) explains the Media and Performance inputs and timing roles. Read their installed-vocabulary for the complete appearance and motion fields.+[Media presentation](media-presentation.md) and [Performance](performance.md) own their content and+playback inputs. Read their installed vocabulary for the complete appearance and motion fields.## Carry measured regions through the same geometrydiff --git a/skills/hypit/references/production/studio-companions.md b/skills/hypit/references/production/studio-companions.mdindex 4d563477..71c05fcc 100644--- a/skills/hypit/references/production/studio-companions.md+++ b/skills/hypit/references/production/studio-companions.md@@ -88,7 +88,10 @@ Declare `bindings` for the actual author endpoints, then choose visible `inspectbinding can follow a shared authored Frame or Style through `referenced`, or an SVS Recipe through`recipe`. Use `parameterReferences` for an entity's actual reference, when a derived entity points to a different authored object. Shared values retain their shared effect when edited.-A Companion is a view of the author model, not a reason to expand it. When an Inspector adjustment+A Companion presents the author model. A meaningful semantic event may deserve a timeline handle+without turning every animation key into an Inspector field. Conversely, a visible number or+qualitative setting inside drawing code need not become a public input. The+[parameter boundary](component-design.md#expose-the-choices-the-work-needs) applies before choosing UI controls. When an Inspector adjustmentis actually needed, bind it to a real Source input or domain event. A label inside a one-off renderercan remain an implementation detail until external control has a purpose. Useful child entities canlive inside the same Track, and selection can be read-only. The@@ -154,7 +157,7 @@ projection, `temporalLineageFor(context, item.id, "activation")` follows that acuse the real input name, such as `window`, `outer` or `activation`. `authoredChildFor` and`childEntities` connect domain child identities to their exact author origins.-The [authored time form](studio.md#edit-the-owning-source-fact) determines the edit: a direct+The [authored time form](timing.md#choose-what-a-later-edit-changes) determines the edit: a directSelection changes its two Script anchors, a direct Moment changes one anchor, and a quoted clockexpression changes its local time or offset. A projected frame alone does not establish thatrelationship. Several objects can consume the same Selection or Moment; changing it updates themdiff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.mdindex dd011657..61a403a1 100644--- a/skills/hypit/references/production/studio.md+++ b/skills/hypit/references/production/studio.md@@ -111,6 +111,11 @@ pass, read the latest file. [Composition review](review.md) explains the judgmen## Review before export+For visual inspection, use [snapshot](snapshots.md) on this session first. It reads the current+compiled programme and selected resources, captures exact original frames, and writes PNGs with+optional grids. Studio remains the interactive view for playback, sound and editing.++When the composition is substantially ready and the user can access it, open the current Run at`#comments` for discussion and introduce Comments and Studio together. Comments lets the userpause and leave direction at a time; Studio shows the timeline, component relationships and exposed@@ -189,7 +194,8 @@ Provider permits for transient authoring, such as media inspection and normalizafiles or produced Outputs through the Run for the material the view needs. If a required generationis still running, continue component work and open its resulting composition when the material is ready.-[Runs](runs.md) explains selection and reuse. [Rendering](rendering.md) provides frame-range Builds+[Runs](runs.md) explains selection and reuse. [Snapshots](snapshots.md) captures the current picture+directly with `hypit snapshot --studio <this-studio-url>`. [Rendering](rendering.md) provides frame-range Buildsfor inspecting the composition as encoded media; choose the view that helps answer the current question.## Edit the owning Source fact@@ -212,37 +218,16 @@ through the selected Style. It edits the shared font declaration; its weight andavailable in the chosen family. A local font continues to use its exact file. A project componentcan offer its own font or preset choices through Companion fields.-Dragging a direct Selection or Moment changes that identity in Script. Every Track consuming it-then follows the changed relation. The authored time form determines what the gesture changes:+Timeline's placed Takes and complete extent provide reference information. Edit their `at` and+`end` declarations in Source when their placement should change. Presentation handles edit Uses+or component events; they do not move Takes or adjust Canvas dimensions implicitly.-| Time form | Timeline editing |-| --- | --- |-| `during={story.selection.proof}` | Move both boundaries by the same number of semantic stops; the duration can change. Trim either boundary independently. |-| `at={story.moment.reveal}` on an event | Move its Moment anchor. |-| `at={story.selection.proof} boundary="start"` or `boundary="end"` on an event | Move only that Selection boundary. |-| `at={story.moment.reveal} for="8f"` | Move the Moment, or trim the trailing edge to change the duration. |-| `until={story.moment.reveal} for="8f"` | Move the Moment, or trim the leading edge to change the duration. |-| `at="2s" for="8f"` | Move the clock position, or trim the trailing duration; `until/for` works conversely. |-| `instant="moment.cue"` or `instant="moment.cue + 2f"` with a bound Moment | Move the local offset while retaining the Moment; an omitted offset starts at zero. |-| `start="..." end="..."` | Trim one endpoint's time expression, or move both by the same frame delta. Referenced Script markers stay in place. |--A semantic stop is a distinct frame position occupied by word or structural boundaries. Select a-semantic marker to see its exact anchors; when several share a frame, the Inspector offers the-choices supported by its editable consumers. Word starts, word ends and structural boundaries-are all eligible anchors; a pause can belong to-either neighboring interval. Direct Segment/Program spans follow their structural boundaries-without timeline dragging. The executed time authority determines the available gestures, and-the Companion connects them to the component's entities and Source bindings.--Clock-based dragging writes the changed value or offset in whole frames at the current frame rate.-Unedited expressions retain their units: `2s` keeps its duration across frame-rate changes, while-`60f` keeps its frame count. Direct semantic dragging changes the Script anchors instead.--Script marker moves use the [same semantic affinities](../creation/script-and-time.md#bind-meaning-to-script-identities)-as authored markers. Writeback normalizes ordinary same-line spacing while preserving line breaks,-indentation, words, punctuation, pronunciation and display attributes. The resulting formatting-becomes the next edit's starting point. A shared Selection or Moment remains one relationship:-editing through any consumer updates its other consumers according to their own projections.+Timing edits follow the authored relationship. A direct Selection or Moment edits that identity+in Script; a quoted expression edits its local clock value or offset; a duration changes independently.+[Timing and edit behavior](timing.md#choose-what-a-later-edit-changes) gives the complete forms,+affinity choices and shared-consumer consequences. Marker moves preserve unrelated prose whitespace. With unchanged spoken tokens and identities,+new marker references can use the existing Take's anchor times. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)+explain when to retain prepared Takes and when to retain only their upstream media.A successful parameter or timeline edit saves the owning Source and recompiles the selected Runfor the view. Rejected edits retain the accepted Source and values. Result renaming instead updatesdiff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.mdindex 086a35f1..071707b3 100644--- a/skills/hypit/references/production/system.md+++ b/skills/hypit/references/production/system.md@@ -1,230 +1,169 @@# How a Hypit production fits together-Read this for the relationships that connect authoring, media, composition and execution.+Read this for the relationships among material, meaning, time, space, presentation and execution.+[Production navigation](index.md) routes each current question to its detailed owner.> Give semantics to the timeline, rather than the timeline to semantics.>> Give layers to the canvas, rather than the canvas to layers.-The work has a complete time range and a canvas. Add semantic attachments where events belong to-speech, and introduce component boundaries where they express useful shared behavior. A silent-ending can contain only graphics. A moving presenter and diagram can share one scene. Neither time-nor space needs to be completely partitioned by the same kind of object.--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.--Treat components as vocabulary you can use and extend. A comparison, a scrolling conversation or a-presenter making room for a diagram can each have named content, events and behavior. Define the-parts that make this work understandable and useful to change. Existing Media, Caption and other-components can supply familiar behavior; a project component supplies a new role through the same-interfaces. [Component design](component-design.md) explains how to find those boundaries.--For spoken work, semantic authoring is the preferred starting point, including a clone.-Understand which idea, question, answer or action each layer serves. Express that relationship in-the target's Script and components, then project it through the new media. For example, a product-picture follows the explanation of its benefit and a graphic settles when the speaker gives the-verdict. The reference's seconds locate evidence; the target's actual performance supplies its time.--## Materials meet composition at the Timeline--```text-Script + directed or supplied material- ↓ normalization and, for Script performance, semantic preparation- prepared material with local time- ↓ placement- Timeline: full extent, Takes and semantic anchors- ↓ selected content, event times and source playback positions- components → Film → rendered video-```--Independent images, B-roll and music bring their own assets to their components. Caption also uses-the Script's display text. The Timeline supplies their common time context; a Frame supplies spatial-placement. The diagram describes relationships, not a serial production checklist: independent-material requests and component implementation can progress together.--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.-The **Timeline** places prepared Takes within the complete work. Their global word and boundary-positions are local positions plus the Take's placement start. It can contain gaps or overlapping-Takes, or no Takes at all. A pure MG work uses this same declaration with an authored end.--[Timeline authoring](timeline.md) explains sequential defaults, relative and absolute placement,-head/tail space and the unified component input.--In spoken work, the performance carrying the main Script is the A-roll. A single presenter, a-conversation with several speakers, and an independent narration can each carry this spine.-Covering the speaker with B-roll does not change whose words establish time. Timeline assembly places-the relevant Takes and retains their source material. Performance or a project-component presents the placed picture; Sound presents the placed audio. Film explicitly selects-their contributions.-The speaker can occupy a small circular inset or appear as a cutout above a full-screen demonstration.-That speaking performance still supplies the SemanticTake. A-roll describes this semantic role;-screen area and stacking belong to its visual presentation.--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.-A gap instead reserves time without a Take. Use Timeline placement and extent for such passages;-their graphics can be authored directly.--[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--Choose content ownership as well as presentation:--| Content relationship | Useful starting point |-| --- | --- |-| An independent image, video or surface with its own placement | Media |-| Existing Timeline footage shown full frame, inset, hidden or moving | Performance |-| Existing Timeline audio | Sound |-| Independently supplied music and effects | Audio Track |-| Independently authored text | Typography |-| Existing Script words presented at their performed times | Caption |-| A newly coordinated visual role with shared layout, state or motion | A project component |--These are useful abstractions to compose and extend. A custom Performance Style can direct footage;-a scene owning a presenter and diagram can expose their combined behavior. [Performance](performance.md)-and [component design](component-design.md) explain those choices. [Sound](sound.md) applies local-treatments to existing audio through the same Use model.--Content, Use and Style answer different questions: what is available, when a treatment applies,-and what that treatment does. Performance, Sound and Caption share timed Uses: a broad Use sets-the treatment, and later matching Uses replace it locally, including hidden or silent presentation.-The original source playback and word timing continue beneath those choices. Independent Tracks-can coexist when the work calls for simultaneous presentations. [Caption presentation](caption-presentation.md)-explains how complete Cues retain their content while their styling changes.--Choose each relationship at the scale that makes it useful. Script describes what an event follows;-Frames describe placement; a component owns shared layout, state and motion. The dependency graph-says which values that work needs. These structures can differ: a Source element can produce several-appearances, and one appearance can contain a whole scene of video and graphics.--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.--Where placement, appearance or content need external direction, a component can accept a Frame,-Style, text or images for those choices. This lets one behavior serve different uses. A one-off scene-can instead keep its specific design local while receiving the media and semantic events it needs.--Visual and audio components publish Tracks. A visual Track groups named appearances; each appearance-owns its lifetime, paint order and internal element tree. A moving video and its diagram can form-one scene, with independent Caption beside it. Media provides ordinary presentation, and a project-component can own the shared behavior of a more specific scene. [Component design](component-design.md)-explains that choice; [drawing a component](component-visuals.md) shows both structural elements and-HTML/CSS programs with frame-driven behavior.--The component's Surface can accept a Moment, Selection or direct time and use shared projection-helpers to provide the resulting Instant or Window to its behavior. The author expresses the-relationship in one place; the implementation handles its conversion to frames. When presenting-speech media, its playback mapping also identifies the right Take and source frame. Moving its-viewport can therefore leave the performance playing continuously.--A local HTML/CSS program can own the needed layout, state and motion while participating in the-same composition as ordinary Media and Caption. It does not need to become an intermediate video.-The scene's internal implementation can use further functions and parts without making each one a-separate Track. This lets an author expose the useful controls and implement the rest locally.--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.-A component coordinating graphics and sound can publish both contributions; Film selects each-explicitly. Their shared event can preserve synchronization without making audio inclusion implicit.--[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.+The work has a complete time range and a canvas. Attach events to their meaning in the performed+work; introduce component boundaries where content shares useful layout, state or motion. Semantic+coverage need not fill time, and visual components need not partition the canvas into fixed regions.+The author decides which relationships the work needs. Hypit expresses and realizes them.++## Materials acquire their roles through use++A supplied file, a generated Output and a reused Result can supply the same kind of material.+An image has dimensions; moving media has local time and selected picture/audio streams. Transparency+is a property of the prepared picture. A model reference, a performed passage and an independent+illustration are uses of material, not separate file classes.++For a work carried by performance, including a short drama or an otherwise pure A-roll piece,+prefer Script and semantic preparation. Script names meaningful, performable passages and events;+the accepted performance supplies their actual time. This remains useful without MG: replacing a+passage, revising dialogue, placing Caption or directing sound can preserve the same relationships.+A Segment need not equal one camera shot or one speaker turn.++In this spoken chain, A-roll is the performance carrying the Script passage. Its picture can fill+the frame, move, disappear beneath evidence, or be absent in an audio-only performance. That role+specifies neither a source aspect ratio nor a visual component type.++Material identity, performance role and current appearance answer different questions. One placed+performance can supply several simultaneous views; a later replay of its source can have independent+playback. Direct cuts and continuous movement are authored ways to change presentation. The Timeline+keeps the performance's time, while each visual owner determines its use on the Canvas. A layout+change can reuse the same accepted material and semantic evidence.++A **SemanticTake** combines one Segment's prepared media with its local word and boundary positions.+The current Timeline Take input is this value. Independent images, video inserts and music instead+enter the components that use them; they do not need artificial Script passages. A wordless performed+Segment has real media and its boundary times. A standalone material transformation can finish with+the transformed asset. [Media preparation](media.md) explains these input relationships.++## One Timeline provides the work's time++The **Timeline** holds the complete range and placed Takes. A Take's placement translates its local+positions into program time. Gaps, overlaps and a range with no Takes are valid. A code-authored ending+can extend past the last performance; a wholly authored animation uses the same Timeline.++For an event that responds to a word or passage, retain the Script Moment or Selection. The component's+Surface projects that reference through the actual Timeline to an Instant or Window. Independent+rhythm can use authored clock positions, and motion can have its own duration. These all use the+same program clock. [Timeline](timeline.md) owns placement; [Timing](timing.md) owns event expressions.++Placed content is available before any presentation is selected. Timeline chooses no winning+picture, transition or audible mix. An overlap supplies multiple sources; the presentation owns how+they appear or sound. Independent Media, graphics and audio also use this Timeline to place events,+including events attached to speech.++## One Canvas provides the work's space++The **Canvas** supplies picture dimensions and coordinates. A Frame locates a destination; fitting+maps a source's real extent into it. Components own their internal layout and motion. A presenter+and diagram can share a scene, while an independent title remains a peer. Frames may overlap, nest,+move or extend beyond the canvas.++Canvas is a geometry value, not a second asset store or a central layer tree. Each visual contribution+publishes its own appearances and internal trees. A **Present** owns an appearance's lifetime and+paint order; that order determines what covers what. [Spatial layout](spatial.md) owns geometry;+[component design](component-design.md) owns useful visual scope.++Time authority and visual scope are independent choices. One scene can follow several semantic+events; separate components can share one Moment. Giving a scene the whole canvas does not require+fixed-second choreography. Giving an image a semantic Window does not turn it into a Take.++## Present existing content or supply independent content++Two content relationships recur in ordinary authoring:++| Content | Present already authored content | Supply content for this contribution |+| --- | --- | --- |+| Picture | Performance obtains footage and source positions from Timeline. | Media receives images, prepared video or compositable surfaces. |+| Sound | Sound obtains placed audio from Timeline. | Audio Track receives independent audio-bearing material. |+| Text | Caption obtains Script display content and its performed timing. | Typography/Text receives independent writing. |++These are useful starting points. A project scene can combine placed footage, independent assets,+text and projected events when they share behavior. The same video can carry a performance here and+serve as an independent replay elsewhere. [Tracks](tracks.md) routes the actual presentation choices.++Performance, Sound and Caption separate available content, timed **Uses**, and the **Style** applied+by each Use. Later matching Uses replace the treatment locally; independent Tracks can coexist.+The content retains its original timing under these choices. Each family owns its rendering and+content-specific rules.++Keep three times distinct: program time locates the appearance, source time identifies the media+frame, and local animation time determines the presentation's state. A Take placed at second 5 is+at source second 2 at program second 7, even if its viewport only becomes visible then. Performance+and project scenes can consume this mapping directly. An independent Media Item instead declares+its own source and playback policy. [Performance](performance.md) explains continuous presentation.++An original and a cutout are explicit material choices. If the placed Take contains only the cutout+picture, a presentation needing its original background must receive the retained original as an+input. No Style can recover pixels absent from its material.++## Components express the relationship worth preserving++A component owns shared behavior. Its public inputs connect actual dependencies and useful directing+choices: selected assets, important events, placement or a treatment that the work needs to vary.+Decorative geometry and a fixed local design can remain in its implementation. A one-off scene is+ordinary production work; reuse and cross-project distribution are separate decisions.++Critical internal events need their own semantic relationships when they answer different parts of+the performance. Making only the scene's outer Window semantic does not keep several word-linked+actions synchronized. Interpolation and local motion can then follow those events without exposing+every number as a control. [Component design](component-design.md#let-meaning-drive-the-behavior)+explains that boundary; [Track authoring](track-authoring.md) explains the public implementation path.++Visual components publish VisualTracks; audible contributions publish AudioTracks. Film explicitly+selects the wanted contributions and combines them with Timeline and Canvas into a **Composition**.+Including picture does not include sibling sound automatically. A whole scene can publish both+outputs while keeping their assembly explicit. Source nesting, component scope, paint order and+execution dependencies describe different relationships and need not have matching boundaries.## Give each part the direction it can realize-The Agent connects the complete design to the responsibilities of its parts. Treatment retains the-creative reasoning; each production input expresses the choice its recipient should realize.+The Agent keeps the complete creative intention and translates it into each part's effective inputs.-| Recipient | Useful direction |+| Recipient | Direction it can realize || --- | --- |-| Image generation | The intended picture: appearance, style, camera relationship, visible activity, setting and reference facts. |-| Video generation | The performed passage: dialogue, attitude, audible and visible expression, actual interaction, camera behavior and cuts. |-| Voice generation | The intended vocal character and delivery, with the wording and references appropriate to that request. |-| Visual and audio components | The selected materials, content, layout, presentation, mix and authored events they should arrange. |--A planned graphic may affect where the camera places a person. Give the image request that camera-relationship and give the graphic component its own placement and events. This preserves the shared-design through different inputs rather than copying the whole Treatment into each request.--High-level language earns its place through the sensory or behavioral choices it communicates.-Preserve recognizable styling and performable attitudes; resolve an uncertain action or a figurative-idea into the output actually intended. [Image direction](../playbooks/craft/image-direction.md),-[video direction](../playbooks/craft/video-direction.md) and-[voice direction](../playbooks/craft/voice-direction.md) own those concrete judgments. The-[Prompt Kit](prompt-kits.md) preserves useful wording and assembles the chosen direction.+| Image generation | Visible appearance, setting, camera relationship, activity and reference facts. |+| Video generation | Dialogue, performance, physical interaction, camera behavior and intended cuts. |+| Voice generation | Wording, vocal character, delivery and suitable voice references. |+| Visual/audio components | Selected content, layout, events, treatments and mix. |++A planned diagram may call for a person framed on the right. Give the image request that visible+camera relationship; give the diagram component its placement and events. Translate later MG or+screen-writing needs into the picture facts the image model can produce. The full Treatment remains+the director's context. [Image direction](../playbooks/craft/image-direction.md),+[video direction](../playbooks/craft/video-direction.md), [voice direction](../playbooks/craft/voice-direction.md)+and [Prompt Kits](prompt-kits.md) own those local decisions and templates.## 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.-The author graph describes those dependencies; the run graph incorporates this execution's selected-Targets and Candidates. Visual grouping, paint order and execution dependency remain separate-relationships: one scene can require several material requests, while one material can supply-several appearances.--These graphs have different jobs. The Author Graph offers the work's public Outputs and their-default computations. The Run Graph supplies Targets and explicit alternative Candidates. Planning-applies those choices, follows the selected dependencies and freezes one execution definition for-the Build. Runtime advances that selected work; it does not reconsider Candidates or rediscover reuse.--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.--Selecting only the generated video instead leaves normalization and semantic preparation downstream.-Selecting the Take keeps those prepared relationships too; selecting the final composition would-also keep its earlier layout. Choose the boundary that preserves the material without preserving the-thing being edited. A new named Output can reference existing bytes, including inside a composite-value; a new Build does not by itself mean new media or another stored copy.--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.-Runtime maintains the running work; Result files keep its products available independently of that-process. If an attempt fails, a new Run can select those products for a new Build. When changing the-video, locate the owning choice—material direction, placement, presentation or execution selection—-and preserve the other relationships that still serve the work.--[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.--In Studio, a component's Companion makes its authored choices recognizable and editable. Content-and Uses can occupy one Track with an internal Band; independent child objects can have their own-lanes. A Style can supply its own controls through a parameter Companion. Editing a Use changes its-application; editing a shared Style, Frame or Selection changes that shared source and its consumers.-[Companion authoring](studio-companions.md) explains how project components supply these views and-writeback relationships through the same public interfaces.+The Author Source connects content, media requests, components and deliverables. Recipes provide+authored values. A Run chooses public Outputs as **Targets** and can supply alternative **Candidates**,+such as a file or an exact earlier Result Output. The selected dependencies determine what executes.++For a layout revision, keeping a compatible SemanticTake preserves the performance and alignment+while the presentation recomputes. Keeping only its generated video lets normalization and alignment+recompute too. Keeping the old Composition would also preserve the old layout. Choose the reuse+boundary according to the current edit. [Authoring](authoring.md#reuse-produced-work-explicitly)+owns that judgment; [Runs](runs.md) owns the syntax.++A **Build** executes the selected work. Its **Result** retains completed public Outputs, including+usable products completed before a later failure. A new Build uses prior work only through explicit+selection. [Builds](builds.md) owns execution, recovery and retrieval.++## Runtime and Studio serve the authored work++External work is expressed as a Need. Model and processing packages define capabilities; Providers+implement them through Endpoints selected by a Runtime Profile. Tools, credentials and capacity belong+to those execution choices. [Environment](../environment/profile.md) owns setup; [rendering](rendering.md)+owns requesting an encoded output from the Composition.++Studio inspects the same selected Run. A package's Companion connects recognizable entities and+useful controls to their actual authored facts. Editing a shared Style or semantic event affects+its consumers; a local parameter changes its own owner. Studio does not require every internal+detail to become editable. [Studio](studio.md) explains use and writeback;+[Companion authoring](studio-companions.md) explains project integration.diff --git a/skills/hypit/references/production/timeline.md b/skills/hypit/references/production/timeline.mdindex dcf0dd44..14eca6bc 100644--- a/skills/hypit/references/production/timeline.md+++ b/skills/hypit/references/production/timeline.md@@ -1,12 +1,15 @@# Placing Takes on the TimelineUse this when placing prepared Takes, leaving passages for MG, or creating a work without speech.-[Media preparation](media.md) produces local SemanticTakes; [Script and time](../creation/script-and-time.md)-owns Selection/Moment meaning, and [Tracks](tracks.md) explains presentation.+[Media preparation](media.md) produces local SemanticTakes; [Script syntax](script-syntax.md)+names Selection/Moment identities. [Timing](timing.md) projects them; [Tracks](tracks.md) explains presentation.A Timeline contains the complete time range and the Takes placed within it. Semantic anchors exist-where those Takes supply them. For an event responding to speech, bind to its Selection or Moment;-use authored time for independently directed rhythm. Both belong to this one Timeline.+where those Takes supply them. Prefer this semantic organization for performance-led work, including+pure A-roll and short drama without MG. A meaningful passage can span shots or speakers; its actual+performance gives the authored words and boundaries time. For an event responding to speech, bind+to its Selection or Moment; use authored time for independently directed rhythm. Both belong to this+one Timeline.The project's reference `TIMELINE.md` records observations and their meaning; the production`time:Timeline` declaration places the new work's material. Reference times locate evidence, whileproduction placements determine the rendered work.@@ -34,6 +37,12 @@ Reordering Take declarations changes placements that depend on `previous.end`, iSeconds, milliseconds and frames must resolve to exact frames on the Clock. All complete Takes fitinside the authored extent. Take placement retains native speed and local semantic evidence.+The current `time:Take source` accepts a SemanticTake, not an arbitrary image, video or audio file.+Independent assets enter their own components with this Timeline as their time context. Each placed+Segment and its token/anchor identities occur once in a Timeline. To show the same footage again as+an independent replay, use Media; a separate performed Script occurrence has its own Segment.+Timeline holds placed material and evidence; it publishes no picture or sound by itself.+A gap contains no performance source. A wordless Segment instead has actual prepared media, as withsomeone dancing. MG can occupy either passage according to the intended picture. Pure MG needs noplaceholder media or Script:@@ -55,7 +64,7 @@ consume the same placed footage and projected event times. New display Windows pframe corresponding to the current Program time; moving a viewport does not restart playback.Overlapping Takes make both sources available. They do not prescribe a dissolve or choose a picture.-Performance places its sampled layers in declaration order; for a coordinated blend or layout,+The ordinary Performance Style places its sampled layers in declaration order; for a coordinated blend or layout,use a scene that owns that behavior. Simultaneous Caption Cues retain their spoken intervals; useRole-based styles or separate Caption presentations when their placement should differ.diff --git a/skills/hypit/references/production/timing.md b/skills/hypit/references/production/timing.mdnew file mode 100644index 00000000..4d2862a2--- /dev/null+++ b/skills/hypit/references/production/timing.md@@ -0,0 +1,96 @@+# Timing authored relationships++Read this when deciding when a component acts or what moving it in Studio should change.+[Script syntax](script-syntax.md) names speech relationships; [Timeline](timeline.md) places prepared+Takes and declares the complete work. This page owns the common author-facing time forms.+The consuming package's vocabulary declares which forms its Surface actually supports.++## Choose time from the relationship++For speech-led work, bind a reveal to the Moment it answers and a covering picture to the Selection+it explains. The accepted SemanticTake locates those identities in its media; Timeline placement+carries them into the whole work. Rewording or changing the performance can then preserve what the+picture follows. Reference timecodes document observations, not the new performance's timing.++Authored animation can instead place messages or state changes on a clock and give them an intended+reading rhythm. It needs no invented Script or media-backed Segment. A spoken Moment can also trigger+a component whose internal animation uses authored durations. The trigger, its offset and the length+of its response are separate decisions; one video can use all of them.++## Express an Instant or Window++Surfaces that expose Hypit's shared temporal vocabulary accept the forms appropriate to their role.+A Window occupies an interval:++| Form | Result |+| --- | --- |+| `during="program"` | The complete program Window. |+| `during={story.segment.hook}` | The Segment's Window. |+| `during={story.selection.proof}` | The Selection's Window, including its authored affinities. |+| `at={story.moment.claim} for="8f"` | A Window beginning at a Moment and lasting eight frames. |+| `at="2s" for="12f"` | A Window beginning two seconds into the film and lasting twelve frames. |+| `until={story.moment.claim} for="250ms"` | A 250 ms Window ending at a Moment. |+| `start="program.start" end="moment.cue" moment={story.moment.claim}` | A Window composed from two explicit endpoints. |++Each Window uses one complete form. Explicit endpoint expressions can use `program.start`,+`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end`, or `moment.cue`,+with the corresponding semantic reference supplied alongside it. They can also use a clock position+such as `1.5s` or an offset such as `selection.start - 2f`. Frames and milliseconds are integers;+seconds may be fractional.++An Instant names one point:++| Form | Result |+| --- | --- |+| `at={story.moment.claim}` | The authored Moment. |+| `at="2s"` or `at="12f"` | A point on the film clock, in seconds or frames. |+| `at={story.selection.proof} boundary="start"` | The Selection's chosen boundary. |+| `at={story.segment.hook} boundary="end"` | The Segment's chosen boundary. |+| `instant="program.start + 8f"` | An explicit clock expression. |+| `instant="moment.cue + 12f" moment={story.moment.claim}` | Twelve frames after the Moment, following it when the delivery changes. |++`at="12f"` locates an event; `for="12f"` gives an interval its length. Frames use the selected+film clock. Semantic projection keeps the event's Script identity alongside its resolved frame,+so its authored relationship remains available for later changes.++A particular Surface may deliberately expose only some of these forms. Its vocabulary reports the+attributes it actually accepts; the shared spelling does not grant every component every temporal+behavior.++## Choose what a later edit changes++Dragging a direct Selection or Moment changes that identity in Script. Every Track consuming it+then follows the changed relation. The authored time form determines what the gesture changes:++| Time form | Timeline editing |+| --- | --- |+| `during={story.selection.proof}` | Move both boundaries by the same number of semantic stops; the duration can change. Trim either boundary independently. |+| `at={story.moment.reveal}` on an event | Move its Moment anchor. |+| `at={story.selection.proof} boundary="start"` or `boundary="end"` on an event | Move only that Selection boundary. |+| `at={story.moment.reveal} for="8f"` | Move the Moment, or trim the trailing edge to change the duration. |+| `until={story.moment.reveal} for="8f"` | Move the Moment, or trim the leading edge to change the duration. |+| `at="2s" for="8f"` | Move the clock position, or trim the trailing duration; `until/for` works conversely. |+| `instant="moment.cue"` or `instant="moment.cue + 2f"` with a bound Moment | Move the local offset while retaining the Moment; an omitted offset starts at zero. |+| `start="..." end="..."` | Trim one endpoint's time expression, or move both by the same frame delta. Referenced Script markers stay in place. |++A semantic stop is a distinct frame position occupied by word or structural boundaries. Select a+semantic marker to see its exact anchors; when several share a frame, the Inspector offers the+choices supported by its editable consumers. Word starts, word ends and structural boundaries+are all eligible anchors; a pause can belong to+either neighboring interval. Direct Segment/Program spans follow their structural boundaries+without timeline dragging. The executed time authority determines the available gestures, and+the Companion connects them to the component's entities and Source bindings.++Clock-based dragging writes the changed value or offset in whole frames at the current frame rate.+Unedited expressions retain their units: `2s` keeps its duration across frame-rate changes, while+`60f` keeps its frame count. Direct semantic dragging changes the Script anchors instead.++Script marker moves use the [same semantic affinities](script-syntax.md#bind-meaning-to-script-identities)+as authored markers. Writeback removes and inserts the moved markers while preserving unrelated+source whitespace, words, punctuation, pronunciation and display attributes. A shared Selection or Moment remains one relationship:+editing through any consumer updates its other consumers according to their own projections.++A component's Companion exposes the gestures it can write back to the authoring source.+[Studio](studio.md) explains the editing interface; [Track authoring](track-authoring.md) explains+using the shared temporal helpers in a project component. The installed `@hypit/temporal-markup`+package owns exact parsing, projection and write-target APIs.diff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.mdindex b62fbc1e..b48215eb 100644--- a/skills/hypit/references/production/track-authoring.md+++ b/skills/hypit/references/production/track-authoring.md@@ -1,6 +1,7 @@# Writing a project Track-Read this when a production needs new graphic structure, state or rendering behavior. Begin from+Read this when a production needs new visual or audible structure, state or rendering behavior,+including a scene that coordinates existing footage with independent content. Begin fromwhat the viewer should perceive and what should follow a changed performance.[Component design](component-design.md) develops that idea into a useful author interface and acoherent treatment in the actual composition.@@ -12,7 +13,9 @@ and project package ownership. [Caption authoring](caption-authoring.md) coversPrefer semantic inputs when the component responds to the words or performance. A comparison can occupya Selection; a verdict can trigger a Moment; the whole board can live for a Segment. Expose thosechoices on the Surface and pass their projected Windows or Instants to the implementation. This-keeps the component useful when a new performance changes the pace. In an authored animation,+keeps the component useful when a new performance changes the pace. Expose separately meaningful+internal events as well as the outer lifetime. The [event-versus-animation boundary](component-design.md#let-meaning-drive-the-behavior)+explains why a single semantic Window cannot replace several word-linked triggers. In an authored animation,content events carry their own reading rhythm. Their Instants and Windows enter the same componentinputs; durations and frame offsets direct how a change unfolds.@@ -63,8 +66,7 @@ content children with their own events and a picture drawn entirely in code.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. [Script and semantic-time](../creation/script-and-time.md#bind-meaning-to-script-identities) describes the shared author+Surface: identical-looking `at` attributes do not imply identical consumption. [Timing](timing.md) describes the shared authorforms; the component chooses which of them fit its behavior.## Separate lifetime, activation and persistent state@@ -103,9 +105,10 @@ where content goes and how its intrinsic shape occupies that place. RegionTimeliper-frame regions in a chosen Canvas. These are distinct from Timeline, which owns the complete time range.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.+MG area maps into the actual composition. Take the production's Canvas and the placement inputs the role needs. Derive related internal+geometry from their common owner. A project scene may keep a fixed layout and speaker arrangement;+a reusable behavior exposes the variation its real uses require. Keep renderer viewport selection+and any detector in their own execution or measurement boundary.## Write the smallest component that expresses the role@@ -192,7 +195,10 @@ schedule and temporal identities at their actual boundaries so the editor consuminstead 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,+showing the state change. State each exposed event's meaning and which state persists after it.+When several actions follow different phrases, check their separate anchors through a delivery with+uneven spacing; stretching only the outer Window would conceal a wrongly fixed internal trigger.+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 framechecks around activation and exit are more useful than snapshots of every implementation detail.diff --git a/skills/hypit/references/production/tracks.md b/skills/hypit/references/production/tracks.mdindex 2e61a7ae..04c901c6 100644--- a/skills/hypit/references/production/tracks.md+++ b/skills/hypit/references/production/tracks.md@@ -1,260 +1,67 @@-# Composing Tracks+# Choosing and composing contributions-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).+Read this to choose how content enters the picture or sound. [System](system.md) explains the+relationships; [media preparation](media.md), [Timing](timing.md) and [spatial layout](spatial.md)+own the shared inputs. A new shared behavior belongs in a [project component](component-design.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 content relationship-## Choose by the contribution's job--| Role | Owns | Common published values |+| Content relationship | Useful starting point | Published contribution || --- | --- | --- |-| Timeline | Complete time range and placed Takes, with any semantic evidence; it draws nothing | `.timeline` |-| Performance | Existing Timeline footage, with broad and local presentation Uses | `.visual` |-| Media Track | Independently supplied images, prepared moving media, or authored surfaces; B-roll is one use | `.program`, `.visual`, optional `.audio` |-| Sound | Existing Timeline audio, with broad and local presentation Uses | `.audio` |-| Audio Track | Independently timed music, ambience and effects | `.program`, `.audio` |-| 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.--## Follow Selection → Surface projection → component consumption--Script publishes a Selection, Moment or Segment as a semantic identity. It carries authored Anchor-identities, not a Window, Instant, second or frame number. A component that wants to use that meaning-exposes an appropriate projection form on its own Surface:--```svml-<media-track:Item image={portrait.image} extent={portrait-extent}- frame={layout.full} during={story.selection.example} appearance={look.still}/>-```--Here `during` belongs to `media-track:Item`. While lowering that element, Media Track's Surface-resolves the Selection and Timeline, creates the temporal projection Records and Fragment, and-wires the projected `Window` into Media Track's own Fragment. The projection subgraph resolves the-Selection's start and end Anchors against the selected Timeline and composes the resulting-Instants into that Window.--The Media Track's internal Producers consume the Window together with the media, Frame and authored-specification. Only there do occupancy, playback and motion acquire their component-specific meaning.-The internal Producers receive the projected Window, not the Script Selection, and do not search-Script words themselves.--The same chain supports different semantics without a central timing dispatcher. A graphic Surface-may project a Moment to an Instant and consume it as a persistent state change; an Audio Surface may-project a Selection to a Window and consume it as a Clip interval. A component may expose only the-projection forms its behavior can honestly consume.--```text-Script Selection / Moment / Segment- ↓ component Surface projection through Timeline- Window / Instant- ↓ component Fragment and Producers- occupancy, playback, state, sound or visual behavior-```--A render-range request is farther downstream: it chooses which already-authored output frames to-inspect or deliver and changes none of these relationships. [Script and time](../creation/script-and-time.md)-owns Selection, Moment and shared projection spellings; each selected Surface's vocabulary says which-forms that component exposes.--## Place prepared Takes on the Timeline--Each SemanticTake holds local prepared media and the Script Segment's local word/boundary positions.-[Timeline authoring](timeline.md) places those Takes: sequentially by default, or with authored-starts that leave gaps or overlap. The complete Timeline can extend before and after all Takes.-A wholly authored animation uses the same Timeline with zero Takes and an explicit end.--Caption, MG, Media, Typography, Audio and Effects share `timeline={program.timeline}`. Word-related-events retain Selection/Moment bindings; independent events can use authored positions. Source-overlap provides simultaneous content. Its visible presentation or crossfade belongs to the visual-component, not assembly. Original audio follows the same placements and remains silent in gaps.--For the usual spoken production, the performance carrying each Segment is the A-roll. In a podcast,-the participants' turns belong to that shared performance timeline; each visible speaker does not-create a separate program clock. Audio-only A-roll can also carry one Segment when that passage is-independent-narration-led. Music, sound effects and covering footage then follow the-assembled work. [Voice and performance](../playbooks/craft/voice-and-performance.md) owns the choice-between visible A-roll, covered visible A-roll and audio-only A-roll.--A-roll can be a circular presenter inset or a moving cutout over a demonstration. Its role is-semantic: it carries the Script. Timeline assembly places its prepared material and semantic evidence; Performance and Sound-independently decide how its pictures and audio are presented.--```svml-<time:Clock id="clock" frame-rate="30"/>-<time:Timeline id="speech" clock={clock}>- <time:Take source={opening-take}/>- <time:Take source={answer-take}/>-</time:Timeline>-<sound:Style id="voice-style"/>-<sound:Track id="voice" timeline={speech.timeline}>- <sound:Use style={voice-style}/>-</sound:Track>-<performance:Style id="performance-style" frame={layout.full} appearance={look.performance}/>- <performance:Track id="performance" timeline={speech.timeline} canvas={canvas}>- <performance:Use style={performance-style} during="program"/>- </performance:Track>-```--The imports, Canvas, Frame, Recipe and prepared SemanticTakes exist in this excerpt. The Media-Recipe specifies `stack-order`, fitting and frame presentation. Select `performance.visual` and-`voice.audio` from the Sound Track in Film. The material is generated once and remains the same performance.--[Performance](performance.md) owns broad and local presentation Uses. Its Timeline supplies source-positions; an interval from program seconds 7 to 10 samples source seconds 2 to 5 when that Take-starts at second 5. Ordinary Styles reuse Media geometry and appearance; project Styles can define-movement and mixing. Media Items retain independent playback and source trim.--A moving performance viewport and its neighboring diagram may belong in one component because they-share a layout change. That component consumes prepared material and projected Moments or Windows,-then draws their shared state. Independent Caption and coverage remain separate when useful.-Its Surface can expose a Scene, Item or another useful authoring unit. Inside the component,-`projectTimelineMedia` supplies the intersecting prepared Takes, their program spans and their source-offsets, so changing the layout preserves playback alignment.-[Component design](component-design.md) explains where to draw these boundaries;-[drawing a component](component-visuals.md#compose-video-and-graphics-in-one-browser-program) explains-HTML, CSS and frame-driven code inside one visual contribution.--Semantic structure also supports a wordless passage. It has no speaking A-roll, yet a named empty-Script Segment receives its actual boundaries from prepared media and remains addressable through-the assembled Timeline. Semantic identity here means that the work can refer to the passage and-its boundaries; it does not classify the passage or require spoken words.-[Media preparation](media.md#empty-segments-use-their-media-boundaries) owns that construction.--Every Take contributes its placed Segment boundaries to the Timeline. When its prepared-media has no audio stream, Sound has no audio candidate from that Take. A visual consumer skips-the missing source picture of an audio-only Take while its time and speech remain available.--## Coverage has a Window and a separate playback choice--```svml-<media-track:Track id="coverage" timeline={speech.timeline} 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.--[Spatial layout](spatial.md#fit-the-source-into-the-frame) explains the shared destination/content-model, including alignment, rounded corners, padding, borders and the difference between moving-the Frame and moving its contents. A Media Item or Sequence takes its outer Frame from `frame` and-its stack order from the appearance Recipe's `stack-order`.--For a picture with a designed backing, an Item can use ordered `Paint` and `Layer` children in place-of a direct source. Paint fills the frame; each sampled Layer has its own fit and picture styling.-The unit owns the shared clip, border and motion. A Sequence keeps that outer presentation while its-Members replace the content. Use separate Items when pictures need independent Frames. The Media-Track vocabulary supplies the exact Layer, Sampling and Handoff forms.--For natural moving B-roll, start with `once-start`: a short Window truncates the clip; a long Window-returns to the layer below after the clip finishes. If uninterrupted coverage matters, choose its-media and boundaries from the actual clip length. `hold-start` freezes a tail; choose it when that-stillness is intended. `stretch` retimes. A still occupies its Window without a video playback mode.-`@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--[Sound](sound.md) presents audio already placed on the Timeline, including local silence, gain-changes and explicit source blends. Audio Track supplies independent sources.--An Audio Item 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.-Like Media Track, Audio Track places independent Items and accepts the shared timing forms.-Its `.audio` output connects to Film. Overlapping Audio Items mix; visual Items compose by draw-order. An explicit Item `id` gives Studio a recognizable name; unnamed Items display their source-reference while retaining independent timing and editing identities.--```svml-<audio:Track id="effects" timeline={speech.timeline}>- <audio:Item 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-joins `story.caption` to `speech.timeline`; timed Uses choose presentation while authored `||`-breaks retain Script as the content-grouping owner.--[Fonts and text](fonts-and-text.md) covers exact faces, fallbacks, Emoji and Typography placement.--## Fine Caption and new Caption families--`@hypit/caption-fine` is the usual fine-grained Caption renderer. Its Recipe exposes placement,-font and size, glyph and box Paint, wrapping, active-word coloring, Cue and token motion, lead/tail-and handoff. Script supplies display wording, Roles and `||` Cue breaks; `@hypit/caption` joins that document to the actual semantic timing. Fine publishes a visible `.schedule`-and a rendered `.track`.--Use those controls for the appearance and rhythm they express. When the design needs a different-structure—such as a keyword on its own oversized line beside a supporting phrase—create a project-Caption family. It reuses the common document, Style applications and timing while owning its new-schedule and layout. [Caption authoring](caption-authoring.md) explains that extension. A new family-can be chosen directly for a new visual role; making one is ordinary production work.--For the selected family's exact attributes and Recipes, use `hypit vocabulary @hypit/caption-fine`-and its installed README. [Caption craft](../playbooks/craft/captions.md) explains reading rhythm;-[Caption styling and coverage](caption-presentation.md) explains timed Uses, Role filters, mid-Cue Style changes and hiding;-[Caption tracking](../playbooks/craft/caption-tracking.md) explains measured moving 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.--Ranking is a useful implementation reference: its outer Window keeps the board visible, each-Selection stages a reveal, and the resulting placement can persist. Its TopThree form uses-activation Instants instead. Read the installed `packages/ranking/README.md` for its forms and the-path from authored markers to schedule, drawing and Studio Companion. [Track authoring](track-authoring.md)-uses that same separation when designing a new semantic component.--## Assemble the intended peers--Film's domain assembly receives a Canvas, a Timeline and a Film Recipe. The current `film:Film`-Surface takes `canvas`, `appearance` and `timeline={program.timeline}`. Its Timeline supplies the-complete range and any semantic evidence. Pure MG can consist entirely of visual-components. [Rendering](rendering.md#compose-an-authored-animation) shows the complete time setup.-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.+| Present footage already placed on Timeline | [Performance](performance.md) | `.visual` |+| Supply an independent image, prepared video or compositable surface | [Media](media-presentation.md) | `.visual`, optional `.audio` |+| Present audio already placed on Timeline | [Sound](sound.md) | `.audio` |+| Supply independent audio-bearing material | [Audio Track](audio-presentation.md) | `.audio` |+| Present Script's display words at their performed times | [Caption](caption-presentation.md) | Fine publishes `.track` |+| Supply a title, label or other independent writing | [Typography/Text](fonts-and-text.md) | Package-owned; Typography publishes `.track` |+| Coordinate content through a new layout, state or motion | [Project component](track-authoring.md) | Its declared VisualTrack and/or AudioTrack outputs |++The table routes common relationships; it does not define a closed list of visual roles. A board,+effect or whole scene is a component whose behavior owns its inputs and outputs. Images, text and+video can share one scene. Film receives their ordinary visual and audio contributions.++## Present a performance without reauthoring its playback++For pure A-roll as well as mixed work, place prepared SemanticTakes on the [Timeline](timeline.md),+then use Performance and Sound for the picture and audio the work needs. A broad Style can cover the+whole program; local Uses change its treatment. Caption independently joins Script display content+to that same timing. A performance need not remain visible to supply speech and semantic events.++An audio-only Take supplies no picture. A wordless performed Take can supply material and Segment+boundaries. A gap has no Take. These facts remain independent of graphics occupying that interval.+Independent material can also occupy the full canvas; size and transparency do not decide its role.++A new scene can consume `projectTimelineMedia` to keep placed footage at its current source frame+while coordinating it with other content. [Performance](performance.md) explains Styles;+[component visuals](component-visuals.md#compose-video-and-graphics-in-one-browser-program) explains+owning a larger scene. Media receives separately supplied material when that is the intended use.++## Let events and shared behavior determine organization++A Media picture can cover a Selection, a sound can follow a Moment, and a board can retain its answer+after a reveal. All use the same Timeline, with timing forms supported by their own Surfaces.+[Timing](timing.md) owns those forms; [Track authoring](track-authoring.md#keep-selection-projection-and-consumption-distinct)+owns implementing their projection and consumption.++An outer Window describes a component's lifetime. Internal events can have their own semantic+triggers, and the resulting state may persist. A scene's single lifetime does not justify moving all+its meaningful events to fixed percentages of that Window. Use the [component design principles](component-design.md#let-meaning-drive-the-behavior)+to separate event relationships from local animation.++Shared movement or state can justify a shared component. Independent contributions may stay peers+while consuming the same Moment. A Track is not required for each asset, each Script Segment or each+rectangle, and creating a component does not require publishing a package outside the project.++## Assemble the intended contributions++Film receives Canvas, Timeline and each selected visual/audio output. Timeline establishes the+complete extent; components establish appearances and their paint order. Include sibling audio+explicitly when wanted. A silent covering picture leaves the selected voice audible; selecting the+same voice through multiple audio contributions can duplicate it.++Film child order does not move a picture to the front. Each Present has its authored stacking and+its internal element tree. An internal transform, mask or transition can keep related content+together while independent Presents overlap it according to their own stacking.++[Rendering](rendering.md#assemble-the-picture-and-sound) shows assembly and full/range delivery.+[Review](review.md) judges the selected work, including performance, boundaries and the complete mix.