@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/builds.md

@@ -0,0 +1,330 @@
+# Planning, Builds, and Results
+
+Read this when inspecting the work selected by a Run, obtaining spending authority, submitting a
+Build, continuing after a failed attempt, following work after an observer disconnects, or retrieving
+completed Outputs.
+
+[Runs](runs.md) owns Candidate syntax and substitutes. [System relationships](system.md) explains
+how the selected graph becomes a Build, and [rendering](rendering.md) covers whole or partial video outputs.
+
+## Reuse available Outputs and identify active Builds
+
+For a revision, identify the relevant Run and its completed Outputs, then preserve the still-useful
+ones with `build-record` and `satisfy`. Keep unrelated Candidate selections. [Authoring](authoring.md#reuse-produced-work-explicitly)
+explains which media or SemanticTake Output to keep without freezing the downstream edit. A failed
+Build can still supply completed Outputs; a missing exported file is not evidence of missing media.
+
+If the CLI or observation tool loses its reply while submitting or following a Build, inspect the
+local Runtime and project Results: the Worker may already be executing that Build.
+
+```bash
+hypit activity
+hypit status <build-id>
+hypit builds
+hypit inspect <build-id>
+```
+
+Use the original project and Runtime Profile for activity, status and cancellation; pass
+`--runtime <profile>` when it is not the project's selected Profile. `builds` and `inspect` read
+project-owned Results without a Runtime argument. Read active execution from the Runtime Profile
+that received the Build.
+
+Use the known Build id. If it was not returned, use project activity and Results to identify the
+submission from its Run, Source and submission time. Follow active work with `status --watch` and
+reuse completed Outputs. A closed terminal or interrupted
+observation is distinct from a failed Provider request inside the Build. Finishing an incomplete
+Result is covered below and does not require regenerating media.
+
+Follow-up commands printed by the CLI retain the project and relevant Runtime. Preserve that scope
+when adapting a command. Watching with `--json` still reports coalesced progress on stderr while
+stdout carries the final JSON; read both channels when the terminal tool exposes them. Translate the
+reported work, relevant uncertainty and useful next action into a concise update for the user.
+The Runtime owns execution; a conversational update or a detached observer does not pause it.
+
+For a slow or failed stage, read its retained execution evidence:
+
+```bash
+hypit logs <build-id> --lines 80
+```
+
+This reads Provider diagnostics and execution phases from active work or the finished Result.
+Completed Build logs remain accessible through the Result repository without the original Runtime.
+Use `hypit runtime logs` for Worker startup or process failures. Start with the relevant tail and
+expand it when the cause needs earlier context; a closed terminal does not erase the Build's log.
+
+## Continue after a failed attempt
+
+A failed Build leaves the work and evidence produced by that attempt. Prepare a new Run that selects
+its usable Outputs through `build-record` and `satisfy`, then submit a new Build for the remaining
+work. The next attempt's choices belong in that Run; the earlier Build retains its failure.
+
+When a Provider task-submission request times out without a task ID or another usable receipt,
+the Result can establish the request failure and absence of a receipt, while the remote outcome remains
+unknown. A later submission is a new Build. Assess its paid requests against the
+[agreed scope and cost](#work-within-the-agreed-paid-scope), and select any Outputs already available
+from the earlier attempt in its Run.
+
+When a usable receipt does exist and gives access to a generated asset, the Agent can retrieve that
+asset as an ordinary project file and select it with `file` and `satisfy` in the new Run. This supplies
+the file Output; downstream preparation and alignment still run when needed. A completed SemanticTake
+can instead be reused directly through its existing Result Output.
+
+The StarRouter Comfly workflow keeps the public task ID in a durable checkpoint. When status lookup
+or output download fails transiently, resume observation or collection of that same task. A lost
+response to the initial create request is different: without a public task ID its remote outcome is
+unknown, so do not resubmit a possibly paid request. Inspect the StarRouter task and billing records
+before authorizing a replacement.
+
+Use `status <build-id> --verbose` for task IDs, Endpoints and progress. Use
+`inspect <build-id> --verbose --json` for the Result's full retained execution records, including
+available credential references and receipts; increase `--limit` if the report lists omitted records.
+Secret values stay in their Credential Store. `--json` changes encoding, while `--verbose` requests
+these details.
+
+## Plan the selected Run
+
+`hypit plan` inspects an authored Run's execution demands. The creative direction shared with the
+user develops earlier from their request and reference evidence; it does not require a Run, a fully
+prepared environment or this command. Use the command when there is concrete execution to inspect.
+
+Plan the actual Run after its reuse choices and requested changes are expressed:
+
+```bash
+hypit check path/to/build.svrun
+hypit plan path/to/build.svrun
+```
+
+`check` validates the self-described Sources and graph without executing them. `plan` freezes the
+demanded subgraph after applying the Run's Candidate selections and lists every external Need that
+would be sent. Planning starts no external work.
+
+Use the default reports to follow the remaining work. `--json` changes the encoding; `--verbose`
+expands the scope. A Run's Candidate count is not its count of new requests or generated assets:
+Candidates may supply existing values or select another Producer. The confirmation view is the
+production plan itself: read the named requests and quantities for boards, depth videos, audio
+references, generated shots and processing work.
+
+With a selected Runtime Profile, the plan also names the Endpoint behind each request, applies that
+Endpoint's request-support rules and checks cheap readiness for the demanded capabilities. It does not
+calculate or show a concrete price. Planning remains local and does not require a billing account.
+
+When an operator separately needs Provider rate diagnostics, they may read the current pricing material:
+
+```bash
+hypit pricing path/to/build.svrun
+```
+
+`pricing` is an explicit read-only network operation. It creates no Build and submits no generation.
+The default report groups matching requests by their selected Endpoint and pricing material, showing
+known parameters, request counts, and the Provider's rate summary or document with its source URL. Explicit
+no-charge work is summarized in one count. Missing pricing declarations and failed queries stay
+visible as uncertainty; a declared price page remains useful when the Provider supplies no document.
+
+This command is not part of the generation confirmation gate and Hypit calculates no total.
+
+`--json` puts each group's `requests` beside its `pricingDocuments`, retaining the Provider's original
+data. Both views include all pricing groups by default. `--limit <count>` shortens only the human
+view; `--verbose` shows original documents and the no-charge work. Read these groups only when
+explicitly needed for billing diagnostics.
+
+Read the remaining Needs against this change. A Caption or MG-only revision should keep its existing
+media generation satisfied; replacing selected B-roll should leave the unchanged performance satisfied.
+Rendering and other required processing may still appear as Needs. Explain each new media request
+from the user's goal or an explicit generation decision. If a request appears because a Candidate was
+lost or never selected, repair the Run and plan again before asking to spend or submitting work.
+
+## Work within the agreed paid scope
+
+Paid-work authority covers the displayed production plan through the selected billing accounts. Before
+asking for authorization, show the work and quantities without calculating a concrete price. Account
+access and available quota describe what can run; approval of that plan establishes what may be
+submitted. If the user supplies a budget ceiling, never exceed it.
+
+The commission can cover a whole production, including reference transcription, generated media
+and semantic alignment, or just the reference analysis before the user decides to commission the
+video. Early hosted transcription fits either scope. Establish its coverage before invoking
+`hypit transcribe`, which immediately calls the selected Endpoint. A production Run need not exist yet.
+As the creative plan becomes concrete, `plan` exposes the exact remaining requests for that Run.
+
+Carry covered work forward and keep the user informed. The same agreement can apply across tool
+calls and Builds; a new command is not itself a new authorization request. Ask for a new decision
+when the work expands beyond the agreed plan, exceeds a user-supplied budget ceiling, or would use an
+account outside that agreement. Use the current plan and available Results to judge the remaining work.
+
+Preserve the user's agreement in [Brief](../creation/brief.md#brief-preserves-user-authority), and
+resume from it alongside the current Run, Results and Progress. Normal composition work carries
+usable generated media forward. A request to revise Caption or MG authorizes that revision;
+additional media generation follows an intentional production choice covered by the paid scope.
+Explain a meaningful change while proceeding when it is already covered; seek the user's decision
+when it changes what they have agreed to fund.
+
+## Submit one durable Build
+
+Review the current plan and obtain the user's confirmation before recording its approval. A paid
+Build requires the matching approval; every Build requires explicit `--confirmed`.
+
+```bash
+hypit plan path/to/build.svrun
+hypit plan path/to/build.svrun --approve
+hypit build path/to/build.svrun --title first-cut --confirmed --follow
+```
+
+Every invocation creates a fresh time-ordered Build id and one independent Result, even when the Run
+did not change. Cross-Build reuse requires explicit Run Candidates; repeating the same command does
+not resume the earlier Build or automatically select its Outputs. The optional title is a human-facing
+Result label; it does not replace the Build id or alter Source identity.
+
+Build performs a cheap preflight and submits only when the selected deployment slice is ready. It
+does not install packages or start a missing Managed Program. When the environment has already been
+prepared and only the Worker is stopped, Build ensures that Worker becomes available. When
+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 or
+interrupting that terminal detaches the observer and leaves the Build running. Reattach with:
+
+```bash
+hypit status <build-id> --watch
+```
+
+A plain `status` reads one current snapshot. `--max-wait-ms` bounds how long a caller watches; it
+does not bound or cancel the Build itself.
+
+## Observe shared work and capacity
+
+```bash
+hypit activity
+hypit runtime status
+```
+
+`activity` shows active Builds; `activity --verbose` also shows shared Provider capacity. The Worker may advance many unrelated
+Builds together. Capacity belongs to the exact Endpoint instances, real shared pools, and any narrower
+model limits declared by those Endpoints. Builds share only those actual resources, so unrelated work
+can advance together.
+
+Immediate work releases its capacity when it returns. An asynchronous Provider operation keeps its
+claim while that same accepted operation is being polled to completion. Losing the execution process
+ends the attempt and preserves available remote receipts; it does not resubmit the paid request.
+When an action fails, the attempt ends and local reservations are released. Any last-observed remote
+status remains evidence, rather than a condition the old Build must resolve before the next attempt.
+
+`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 outcome
+
+Runtime activity describes what is happening now. The finished Result records one outcome:
+`complete`, `failed`, or `cancelled`. These are different facts. `status` reads both sources and may
+therefore show, for example, a decided failure whose completed public Outputs are still being written
+to its Result.
+
+A failed or cancelled Build can retain useful public Outputs completed before its outcome. Inspect
+them normally. Cancellation withdraws work that has not begun and asks an Endpoint once to cancel an
+already submitted operation when it supports that; accepted completed output is retained.
+
+If Result storage or cleanup fails after execution has decided its outcome, `status` reports operator
+attention and the exact action:
+
+```bash
+hypit result finish <build-id>
+```
+
+That command writes from already accepted execution facts and working Resources. It does not invoke a
+Producer, resubmit generation, or choose another Candidate. Use it only for the Result write named by
+`status`. `hypit result discard <build-id>` applies only to an incomplete submission that never became
+active and has no Result to finish.
+
+When the user asks to stop submitted work, cancel that exact Build explicitly:
+
+```bash
+hypit cancel <build-id> --reason "superseded by the corrected Run"
+```
+
+Check the reported state afterward. Detaching the observer does not send this cancellation, and a
+cancellation request cannot undo already completed Provider work. Preserve completed usable Outputs
+and leave unrelated Builds alone.
+
+`runtime down` stops the coordinator and its execution processes for that Runtime. An unfinished
+Build that loses its execution context ends that attempt; starting the Worker again does not resume
+it. Completed Outputs and recorded receipts remain available for explicit reuse in a new Build.
+Stopping the Worker does not itself cancel remote Provider work; use `cancel` for a selected Build
+while its execution context is available.
+
+## Browse and export project Results
+
+```bash
+hypit builds
+hypit inspect <build-id>
+hypit history <public-output-name>
+hypit get <build-id> --output <public-output-name> --to <destination>
+```
+
+`builds` lists finished project Results newest first. `inspect` shows one Result's Targets,
+highlighted Outputs and outcome. Use `inspect <build-id> --output <public-output-name>` for a known
+Output, or `--verbose` to browse all available names and receipts. A Result can expose many forwarded
+Outputs from earlier work; this inventory does not mean those files were generated or copied again.
+`history` finds one named Output across Results, including reuse; it does not select one for the
+current Run. `get` exports one named Output to one explicit destination:
+
+- a Scalar becomes a JSON file;
+- a Resource becomes one streamed file;
+- a Composite becomes a directory containing `value.json` and its referenced Resources.
+
+The destination remains a user-facing export. The original Result stays in the project's selected
+repository. The default filesystem repository lives under the project; `hypit.results.json` may
+select another adapter such as S3 without changing these commands or the Run.
+
+Give useful Results presentation metadata when it helps people and Studio find them:
+
+```bash
+hypit result edit <build-id> --title "podcast take · coral captions" \
+  --note "speaker timing and framing for the current production" \
+  --highlight podcast-take.video
+```
+
+The title, note, and highlights live in that Result manifest. They do not rename its public Outputs
+or create a project-wide history index. Reuse still names the exact Build id and Output through the
+Run mechanism in `authoring.md`.
+
+## Select the Result repository deliberately
+
+Result storage belongs to the video project. The official default is the filesystem repository at
+`.hypit/results`. An explicit `hypit.results.json` selects an adapter with the envelope
+`format: "hypit.build-results@1"`, `use` and adapter-owned `config`. Read the installed
+`@hypit/build-result-fs` README for a custom filesystem path, or `@hypit/build-result-s3` for bucket,
+prefix, deployment options and its credential setup. `hypit.results.json` owns Result storage;
+the Runtime Profile owns execution, and the S3 adapter owns its credentials.
+
+`hypit paths` locates the project; `hypit doctor` checks its selected repository, even without a
+Runtime Profile. Result listing, export, history and Studio's finished library read that repository.
+If expected Results are absent, first check the selected project and Result repository.
+
+A submitted Build retains the repository destination captured at submission. Changing the project
+selection while it runs does not redirect its eventual Result. Use the original destination to
+find that Result; changing a selection does not migrate earlier history. Preserve any Result that
+still supplies a Run Candidate: exported files are optional copies, and explicit reuse may still
+reference Resources in the original Result.
+
+[Project handoff](../creation/project-files.md#hand-over-an-editable-production) explains carrying
+those Results and the authored work to another machine or collaborator.
+
+## Build with the current project implementation
+
+Each normal local Build receives its own loaded project implementation and selected Provider
+configuration. Edit project components or the Profile, then create a new Build;
+previously started work keeps its loaded implementation. Reuse completed material through the Run
+when changing composition. Warm services such as WhisperX remain available across Builds.
+
+Concurrent Builds share execution infrastructure; remote waiting does not reserve a whole-Build slot.
+A lost executor ends its affected attempts; completed Outputs and available remote receipts are
+retained. Continue with a new Build and explicit reuse. This execution boundary does not freeze files
+that a component chooses to read later.
+
+Changing the installed Distribution or the coordinator's inherited shell environment is a separate
+bootstrap change. Inspect `hypit activity` before restarting that Worker. External writable credential
+stores may expose updated values directly; environment-backed credentials use the environment in
+which the coordinator was started. `hypit runtime down` stops the Worker and its active executors;
+Managed Programs have their own lifetime.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/caption-authoring.md

@@ -0,0 +1,156 @@
+# Writing a Caption family
+
+Read this when a work needs a new relationship among its spoken words, layout and motion.
+[Caption craft](../playbooks/craft/captions.md) owns readability and directing judgment;
+[Caption styling and coverage](caption-presentation.md) owns applying visible and hidden Styles;
+[Track authoring](track-authoring.md) owns project package wiring.
+[Fonts and text](fonts-and-text.md) explains exact font resources and fallbacks;
+[component visuals](component-visuals.md) explains the final drawing representation.
+[Component design](component-design.md) connects a new family's visual idea to useful author controls
+and its fit beside the rest of the video.
+
+## Decide what is actually new
+
+Fine Caption already covers uniform flowing text with exact fonts, Paint, boxes, karaoke states,
+placement and motion. Different colors, Role styles, cue entrances or head tracking may only require
+Source and Recipe changes. A keyword occupying a separate oversized line, words playing different
+visual roles, or a recurring spatial relationship among speakers can justify a new family directly.
+Creating that family is normal video production. Name the family for the visual relationship it
+makes reusable, and name each Style for a particular treatment within it. A project can also own a
+single-use caption composition when that is what the video needs.
+
+The result is still Caption when the displayed words correspond to speech and remain close to its
+delivery. Independent slogans, summaries and titles usually belong to Typography even if they react
+to a Script Moment.
+
+## Own the visual relationship
+
+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 the
+authored 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 the
+thought while its key word takes the emphasis. Design how they enter, share space, respond to speech
+and hand off to the next thought. That relationship suggests useful controls: the word's authored
+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 and
+other visual elements. When words and graphics share layout or motion, they can live in the same
+component. [Component visuals](component-visuals.md#compose-video-and-graphics-in-one-browser-program)
+also describes HTML/CSS browser programs with typed media and text children. That drawing freedom
+applies to captions too: give the program the resolved caption schedule and explicit resources,
+and evaluate its state at the requested frame. Keep separately useful overlays as peers.
+
+## Keep the existing text and timing chain
+
+```text
+Script → CaptionDocument (displayed words, Cue breaks and word attributes)
+CaptionDocument + Timeline → complete timed Cues and original word times
+Track Uses → resolved time windows, Styles and optional speaker filters
+complete Cues + Uses + family parameters → family schedule → VisualTrack
+```
+
+Consume each display word's `separatorBefore` with its `text`; never rebuild wording by joining
+speech Tokens with spaces or guessing from a writing system. Suppress a separator at the start of
+a displayed Cue/line. Use the same authored boundaries in base glyphs, active layers and backgrounds.
+Separators are display content, not timed Tokens.
+
+Use `@hypit/hypit/caption` for content timing and Use coverage, and `@hypit/hypit/narrative` for
+Script document types. A family Track accepts `document`, `timeline` and ordered `Use` children:
+
+```svml
+<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}/>
+</keyword:Track>
+```
+
+These names assume the project family and its Styles have been declared. Reuse the common time
+projection helpers for `during`, `at`/`for`, `until`/`for` and `start`/`end`. A Use has the same
+meaning regardless of the family. `role` filters whose content it presents within that window.
+
+For a keyword layout, Script can mark `useful{emphasis}`. The family reads that attribute from the
+CaptionDocument and gives it a visual role within the complete Cue. The word role and the time
+window answer different questions; an emphasis attribute does not invent another time language.
+
+## Design a family-specific schedule
+
+Separate measured speech time from visible time. Preserve each alignment unit's measured boundaries
+and identity; resolve lead, tail, stagger, hold and handoff into an explicit schedule before rendering.
+The renderer draws that schedule. Preserve a Cue's original animation origin and apply the
+winning Use window as a separate visibility mask. A window starting midway through a Cue still
+receives the complete Cue and original word times. It can change appearance without restarting
+karaoke or text reveal.
+
+For a “large keyword plus supporting phrase” family, the schedule might identify each Cue's display
+words, its emphasized word ids, their measured units and the visible interval of the two groups.
+Its layout then computes the two groups together. Decide what happens with no keyword, several
+keywords, long text and an N:M pronunciation span. Make author correction possible through word
+attributes, `||` and Style configuration instead of inventing missing text or dropping words.
+
+The common projection respects authored Cue breaks and structural boundaries. Visual line wrapping
+is a separate operation. A narrow width should not silently rewrite the Script into new spoken Cues.
+If the family needs an additional grouping rule, give that rule explicit parameters and preserve the
+original word/unit associations in the schedule.
+
+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 different
+effect from following spoken characters. Keep within-glyph wiping an explicit visual choice.
+Use uneven unit durations and a pause in a short example to check that the chosen effect follows
+the intended clock.
+
+`caption:Hidden` supplies a Style with `rendering: null`. It takes part in later-Use precedence,
+clearing this Track's presentation in its window; a later visible Use can restore a smaller window.
+Use `captionUseVisibility` to resolve that coverage for each Cue's speaker. The content projection
+retains all Cues regardless of Style. Empty or uncovered time naturally produces no drawing.
+
+## Give Style, layout and rendering clear owners
+
+The Style Surface validates a Recipe and exact font references, then emits the common Caption Style
+shape with the new family's name and parameters. The Track Surface accepts the document,
+Timeline and timed Use children; its Fragment assembles the Uses, performs the common timing join,
+and runs its own schedule and render operations. Register the new family's Producers and any new schedule Type in its own package.
+
+The renderer owns typography, structural relationships, stacking and motion. Use the existing text
+shaping and Visual IR facilities with explicit font resources, including selected local font files,
+so the same faces reach the rendering machine.
+Read `@hypit/caption-fine`'s `surface.ts`, `schedule.ts` and `render.ts` as separate implementation
+examples. Reuse the common parts and replace the actual family behavior, including its parameter
+validation; renaming Fine while retaining its uniform-word assumption will not implement a structural
+keyword treatment.
+
+The chosen family interprets its own Styles. Fine handles its uniform-flow Styles; a structural
+family handles its own layouts. Each Track is independent, so multiple Tracks can intentionally
+show captions together or use complementary coverage. Mixed-family rendering, if useful, belongs
+to the component that implements it.
+
+If this family supports spatial tracking, take an explicit RegionTimeline and map it into the actual
+composition. Define subject matching and absent-region behavior. Detection belongs to the measurement
+step described in [Caption tracking](../playbooks/craft/caption-tracking.md), not to this renderer.
+
+## Check the relationships that matter
+
+Use a short Script with a normal phrase, the new structural treatment, a Role change and a Dual Text
+unit. Verify displayed words and their association with measured speech, then inspect the new layout
+at the intended frame size and around its handoffs. Check long words, overflow and direct seeking
+where relevant. A still can show typography; only the configured timeline establishes timing.
+
+Expose the family with useful vocabulary and a designed preview. Keep wording, font choices, palette
+and authored word roles editable in the project. The package adds its rendering language while
+consuming the existing Script, Caption and semantic-time owners.
+
+For live Cue entities and Inspector editing, add a [Studio Companion](studio.md#give-a-project-component-a-useful-companion)
+that presents complete Cue content and authored Uses as separate lanes. Read the Track's resolved
+Use collection, retain each child's Source range and temporal lineage, and expose the referenced
+Style on that Use. Caption Fine's
+Companion is a useful example of these relationships; the new family's layout stays in its renderer.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/caption-presentation.md

@@ -0,0 +1,66 @@
+# Caption presentation
+
+Read this to apply subtitle treatments, change them during a passage, or hide them temporarily.
+[Caption craft](../playbooks/craft/captions.md) owns visual direction;
+[Caption authoring](caption-authoring.md) explains creating a new family.
+
+**Script organizes content; Use organizes presentation in time.** `||` determines which words belong
+together. The Track joins `document={story.caption}` to the placed `timeline`, preserving displayed
+text and pronunciation associations. Each Use selects a complete Style inside a time window.
+
+```svml
+<caption:Hidden id="hidden"/>
+<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}/>
+  <caption-fine:Use during={story.selection.demonstration} style={hidden}/>
+  <caption-fine:Use at={story.moment.key} for="2s" style={impact-style}/>
+</caption-fine:Track>
+```
+
+Styles are declared by the chosen family. Fine Styles take a Recipe and exact fonts. A new structural
+caption can use a project family with its own layout and behavior.
+
+## One time language
+
+| Intent | Use |
+| --- | --- |
+| A treatment across the whole Timeline | `style={base}` with no time attributes |
+| Follow a semantic passage | `during={story.selection.answer}` |
+| Follow a placed Segment | `during={story.segment.answer}` |
+| Start at a meaningful word, for a fixed duration | `at={story.moment.key} for="2s"` |
+| End at a meaningful event | `until={story.moment.key} for="12f"` |
+| Explicit window | `start="8s" end="10s"` |
+| A particular speaker | Add `role="GUEST"` to any of these |
+
+[Timing](timing.md) owns the shared expressions and semantic references.
+Use semantic boundaries when the treatment follows what is being said. Absolute times remain useful
+for an explicitly timed presentation. A Role filters whose content is presented, independently of the
+window: it can cover several turns and does not change the Window shown in Studio.
+
+The last matching Use in Source order wins locally. Each match replaces the whole Style; properties
+are not merged. A hidden Use clears this Track's subtitle presentation throughout that window,
+including neighboring Cue lead/tail. Later Uses can restore a smaller interval. Audio and content
+stay unchanged. With no matching Use, nothing is drawn. With no subtitle content, a Use has nothing
+to draw. Independent Caption Tracks can intentionally show multiple presentations at the same time.
+
+## A style change can happen inside a Cue
+
+```text
+test1 || test2 @{select} test3 || test4 @{/select}
+```
+
+This contains three Cues: `test1`, `test2 test3`, and `test4`. The Selection starts before `test3`;
+it does not split `test2 test3`. With a broad ordinary Use and a later emphasized Use during `select`,
+the complete second Cue changes Style at that boundary, then the third Cue uses the same emphasis.
+
+Word times remain the original times. Karaoke or text reveal therefore continues at the appropriate
+word when the Style changes or returns after a hidden interval. The Window limits visibility; it does
+not restart the Cue's animation clock. Changing only one word's visual role is a different design
+choice: Fine provides current/trail unit emphasis, while a custom family can interpret authored word
+attributes for structural layouts. Display/pronunciation units remain complete.
+
+In Studio, the content row shows Cues and the Uses row shows authored windows. Select a Use to edit
+its time or referenced Style. Moving the Use does not move `||`. Inspect the resulting placement,
+handoffs and emphasis alongside the other visuals while reusing the existing media.