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: a route for a video that has nothing to copy
rpone28023e798c31
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.mdindex 2e3ec556..62258a3d 100644--- a/.agents/skills/hypit/SKILL.md+++ b/.agents/skills/hypit/SKILL.md@@ -1,6 +1,6 @@---name: hypit-description: Author, check, preview, build, inspect, and retrieve Hypit/SVML projects; configure runtimes and credentials; reconstruct reference videos; develop missing project-local author packages; and apply native video production playbooks. Use for the Hypit repository, SVML/SVS/SVRun authoring, reconstruction, package vocabulary, runtime operations, or video craft decisions.+description: Produce a complete video program from a description — a ranking, a talking head, an explainer, a short — or reconstruct one from a reference video; author, check, preview, build, inspect and retrieve Hypit/SVML projects; configure runtimes and credentials; develop missing project-local author packages; and apply native video production playbooks. Use for making a video with Hypit, the Hypit repository, SVML/SVS/SVRun authoring, reconstruction, package vocabulary, runtime operations, or video craft decisions.---# Hypit@@ -20,18 +20,30 @@ Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, andaround it, is this route** even when no verb is given at all. The path is the whole request: theworking directory, the project location and the vocabulary are yours to decide rather than to askfor.-- Ordinary SVML/SVS/SVRun authoring or syntax selection → read `references/authoring.md`, then- `references/quickstart.md` and the linked authoritative docs/package READMEs.+- Making a video from a description, brief, topic, script or format name, with nothing to copy →+ read `references/original-authoring/index.md`. This is the route whatever shape the request takes —+ "make me a 45-second ranking video", "a talking-head explainer about X", an ad for a product, a+ written script to produce, a topic and a duration, a format named on its own, or the same idea in+ any language — and **a description with no video path attached is this route** even when no verb is+ given at all. What it is for, who is in it and what it says are the author's; the working+ directory, the project location, the packages and the generators are yours to decide rather than to+ ask for.+- A syntax question about one element, or a source that already exists → read+ `references/authoring.md`, then `references/quickstart.md` and the linked authoritative+ docs/package READMEs. A whole video is `references/original-authoring/index.md`, not this file.+- Which package owns an element, what vocabulary is installed at all, or whether a capability is+ genuinely missing → read `references/vocabulary.md`.- Creating a new author component outside reference reconstruction → read`references/local-author-package.md`.-- Previewing current Author Source → read `references/preview.md`.+- Seeing what the sources produce, or proving the graph traces before any Build → read+ `references/preview.md`.- Runtime setup, plan/build/status/inspect/get/reuse → read `references/runtime.md`.- Environment diagnosis or credentials → read `references/environment.md` and`references/credentials.md`.- Seedance prompt assembly → read `references/seedance-kits.md`.-- Production craft or format selection → read `references/playbooks/index.md`,- `references/playbooks/craft/production-gates.md`,- `references/playbooks/craft/visual-continuity.md`, and the selected craft/format reference.+- Production craft or format selection → read `references/playbooks/index.md` and follow its+ required load order. That list is the authority for which craft every program needs; naming a+ subset here is how it goes stale.Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out ofcommits. Repository docs and package-owned declarations remain authoritative.diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.mdindex 13f9aa5a..9b82242f 100644--- a/.agents/skills/hypit/references/authoring.md+++ b/.agents/skills/hypit/references/authoring.md@@ -4,22 +4,32 @@ Read `quickstart.md`, then the authoritative page it selects under `docs/quickstKeep Author Source, Recipe Source and Run Source complete and internally consistent rather thanassembling independent per-shot source fragments.-Before writing an element, read the owning package README and, when available, inspect its current-vocabulary declaration. For `@hypit/<name>@1`, the repository README is-`packages/<name>/README.md`. Never invent a component, attribute, child, port, Recipe property or-literal value. Do not infer one package's syntax from a neighboring package.+Before writing an element, read the owning package README and inspect what its Surface actually+declares — `vocabulary.md` names the command and decides which package owns an element in the first+place. For `@hypit/<name>@1`, the repository README is `packages/<name>/README.md`. Never invent a+component, attribute, child, port, Recipe property or literal value. Do not infer one package's+syntax from a neighboring package.-Install dependencies after package selections change. Validate with the existing command:+Install dependencies after package selections change. Validate with the existing commands:```bash-pnpm hypit check path/to/source+pnpm check+pnpm hypit check path/to/main.svml+pnpm hypit check path/to/recipes.svs+pnpm hypit check path/to/build.svrun```-Do not create a check wrapper. A successful check establishes legal syntax, references and graph-structure; it does not prove that an uncertain video observation was semantically correct.+Check all of them, not only the Author Source: a Recipe the Author Source references and a Target the+Run Source demands are just as able to be wrong. Do not create a check wrapper.++**A check that passes is not a graph that traces.** `hypit check` proves a Source is legal — its+syntax, its references, its graph structure — and proves nothing about whether the tracks it declares+can actually be built, nor that an uncertain requirement was understood correctly. `preview.md`+proves the Run traces, before any Provider is reached.This file is about writing an element correctly, which is a narrower question than making the videoright. What a Track should contain, when a picture may be generated at all, how long a thing stays onscreen and what shows through when it does not — those are decided in `playbooks/index.md`, whose-required load order names the craft every program needs regardless of format. A Source can pass-`hypit check` with every one of those decisions still unmade.+required load order names the craft every program needs regardless of format. A whole video is+`original-authoring/index.md`, not this file: a Source can pass every check above with every one of+those decisions still unmade.diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.mdindex 048faf4c..39513876 100644--- a/.agents/skills/hypit/references/environment.md+++ b/.agents/skills/hypit/references/environment.md@@ -1,6 +1,20 @@# Cross-platform environment-Requirements: Node.js 22+, pnpm 10.33.x via Corepack, Python 3.10–3.13 only for local+## Where you are++This skill lives inside the Hypit repository. Find the root from the skill's own location — the+directory containing `package.json` and `packages/` — and work from there. Repository paths written in+these files, `.agents/skills/hypit/scripts/…`, `packages/…`, `examples/…`, are relative to that root+and to nothing else.++Several commands resolve against the **working directory** rather than against the Source they are+given: `list_svml_packages` reads `node_modules/@hypit` from the cwd and refuses when it is empty, and+`preview-check.mjs` resolves `tsx` the same way. Running them from the repository root is not a+convention, it is the condition under which they work.++## Requirements++Node.js 22+, pnpm 10.33.x via Corepack, Python 3.10–3.13 only for localWhisperX/OpenCV, `uv` for locked Python environments, and `ffmpeg`/`ffprobe` for local media.macOS/Linux or Windows PowerShell:diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex b69a7f6d..9dc38fd3 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -204,9 +204,59 @@ node --import tsx .agents/skills/hypit/scripts/preview-check.mjs path/to/build.sIt takes the Run Source, not the `.svml`. A pass here means the graph reaches a Film and a semanticspine; it exits zero while the Providers are still unrun, and says which capabilities it is waiting-on. See `reconstruction/final-sources.md` for what that does and does not prove — notably, a+on. See `preview.md` for what that does and does not prove — notably, aProducer that refuses the media kind it is handed is not caught here, because nothing is handed toit until the Build runs.Do not continue to final authoring until the package and sources pass the existing checks and thegraph traces.++## When the result is accepted, decide whether the package should leave the project++A delivery that shipped may have produced one or more project-local packages on the way. Before+moving on, judge each one and put the question to the author. Not automatically, and not before the+result is accepted — this is an offer, and promoting it is a separate contribution.++**The judgement is one question: would a second, unrelated video want this vocabulary?** A component+that is *this* video's content shaped as a component is not reusable however well it is written — a+sheet whose steps are this product's onboarding, a board whose rows are this ranking. What travels is+a *role* the installed packages do not cover: a Style family that differs from `caption-fine` in its+timing model, a board that differs from `ranking` in the shape of its rows. If the slots are inputs+and the chrome is the component's own, it is probably reusable; if the package would have to be+rewritten for the next video, say so and keep it where it is.++Say which it is either way. A local package nobody flagged is a local package nobody revisits.++### Promotion is not a move++If the author wants it promoted, these are the parts. Say up front that this is a checklist rather+than a path anyone has walked — no package under `packages/` began under `examples/`, so the first+person to do it should correct what follows.++- **The name is load-bearing in six places.** `@hypit/local-<slug>` becomes `@hypit/<slug>` in+ `package.json`; in the Module ref in `src/manifest.ts`, where renaming it **renames every nominal+ Type and Producer in the Module at once**, because each is built from that one const; in every+ Author Source that writes `import … from "@hypit/local-<slug>@1"`; in the root `package.json`+ `devDependencies`; in the package's own test harness; and in **both** package catalogs,+ `docs/guide/packages.md` and `docs/zh/guide/packages.md`. An English-only catalog entry is a half+ promotion.+- **Studio keeps a hand-maintained list.** `packages/studio/src/adapters/generic.ts` enumerates the+ modules that get the component adapter. A package missing from it still renders, through the visual+ fallback — second-class in Studio, and invisible as itself in review.+- **Its own chrome is untracked today.** `examples/**/assets/` is ignored, so the texture the package+ reads with `readFile(new URL("../assets/…"))` is not in git. Promotion is the first moment those+ bytes enter the repository, and **no package under `packages/` has a non-`preview/` asset+ directory**. Promotion establishes that convention rather than following it; decide it deliberately.+- **It newly owes tests.** The suite globs `packages/*/test/**/*.test.ts`. A local package ships+ `test/render-preview.ts`, which is a harness, not a suite, so a promoted package contributes zero+ coverage where every peer has some. Writing one is part of promotion.+- **It newly owes clean imports.** Repository hygiene requires that anything `src/` imports appears in+ `dependencies`, not `devDependencies` — a rule examples are exempt from. A package carrying its+ render-harness dependencies in `devDependencies` fails on the way in.+- **The workspace already covers both locations.** `pnpm-workspace.yaml` lists `packages/*` and+ `examples/*/packages/*`, and `tsconfig.json` includes both. No glob needs adding in either+ direction; adding one is a change that does nothing.++What promotion never means: merging the behaviour into the package it was modelled on. It installs+beside that package as a sibling family, for the reasons the boundary section above gives.+diff --git a/.agents/skills/hypit/references/original-authoring/index.md b/.agents/skills/hypit/references/original-authoring/index.mdnew file mode 100644index 00000000..5022c0d8--- /dev/null+++ b/.agents/skills/hypit/references/original-authoring/index.md@@ -0,0 +1,91 @@+# Making a video from a description++This route produces a complete video program from what the author says they want: `main.svml`,+`recipes.svs`, `build.svrun` and the `hypit.runtime.json` that binds what they demand — wired, then+built in rounds until there is a delivery.++The counterpart route is `../reconstruction/index.md`, which starts from a video to copy. Everything+between the two — what a picture is, what one generation owes another, which package owns an element,+how a Build is staged — is the same work and is written once, in the files this page links. This page+owns the order, and nothing else.++## What this route delivers, and what it does not++Unlike reconstruction, this route **does spend**. It generates pictures, takes, speech and a render.+What it does not do is spend them all at once: `../playbooks/craft/production-gates.md` stages the+work so that an unreviewed expensive output cannot silently feed a later Operation, and the delivery+Build is the last thing that happens, not the first.++There is no reference to check against, so the two things a reconstruction gets for free have to be+decided deliberately here: what the program is *for*, and what every appearance value *is*. Neither+has an evidence file to consult. Write them down rather than discovering them at render time.++## A description is the whole request++The author gives what the video should be — its subject, its length, its audience, who is in it, what+it says. That is theirs. The working directory, the project location, which packages to use, which+generator, which model tier and how many takes are **yours to decide rather than to ask for**;+`../playbooks/craft/generated-dependencies.md` states this for generators and it holds for the rest.++Ask about the video and nothing else. What is missing from a description is usually the duration, the+aspect ratio and the language — ask those together, once, and not one at a time.++Everything else this route needs is discoverable:++- **Where you are, and what is installed.** `../environment.md`.+- **Credentials.** `../credentials.md` lists which variables each Provider needs.+- **Where the project goes.** `../runtime.md` keeps the project and package boundaries distinct.++## Before deciding anything++1. Every craft file listed in the first item of `../playbooks/index.md`'s required load order — the+ ones it marks always-read — complete, in the order it gives them. That list decides which files,+ and it grows: one added there is required here from the moment it is added. Restating the set on+ this page is what once left a required craft file reachable from one route and invisible to the+ other, so this page does not restate it.+2. The format. `../playbooks/index.md` lists them; read the one that fits and only the additional+ craft files its own footer names.+3. `../vocabulary.md` — which installed packages own the systems this program contains, and whether+ any of them is genuinely missing. A system you never inspected is a system you are about to+ invent, and inventing one here is easy: there is no reference to contradict you.++## Write the Script, then the sources++`../authoring.md` is the syntax authority and names the checks. The Script comes first and the shots+come out of it, not the other way round: a Segment is what the Spine binds one Take to, so how the+Script is cut decides how many generations there are and where the seams fall —+`../playbooks/craft/generated-dependencies.md` says why over-splitting manufactures seams nobody+asked for.++Write all four files before building any of them. The Runtime Profile is part of the deliverable, not+an afterthought — `../runtime.md` says how to author one.++## Check it, then prove it is wired++`../authoring.md`'s check set proves the sources are legal. That is not the same as the graph tracing,+and neither is bounded by any attempt ceiling: `../preview.md` proves the Run traces before a Provider+is ever reached, and a graph that does not trace is not done.++## See it before you pay for it++`../preview.md` again: one element rendered to a still locally, or the whole Run opened in Studio for+the author. Both are free. Looking at a composition before generating into it is the cheapest review+in the sequence.++## Generate in rounds++`../playbooks/craft/production-gates.md`, Gates 1 through 4 in order. Pictures are accepted before+takes reference them; takes are accepted before they are assembled; the delivery is demanded last and+watched and measured whole.++Gate 4 ends the job — and ends with the question of whether a component built along the way should+outlive this one video. `../local-author-package.md` says how to judge that and what promoting it+actually costs.++## When a step outgrows this page++This directory holds one file today, because every step above already has a home to link to. That is+the intended shape, not an unfinished one. **When a step here grows past three sentences that are not+links, its content belongs in a file of its own, or in the shared file it should have linked** — the+disease this route was split out to cure is whole-job knowledge accumulating in one place where only+one route can find it.diff --git a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.mdindex cfb8b6d5..e8e9562a 100644--- a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md+++ b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md@@ -44,6 +44,20 @@ handling.** Do not try to close it, do not raise it in a comparison, and do notit: it is a small jump in pose, the seam a viewer reads as an ordinary cut. Split the shot, generatethe parts, move on.+## A Segment is a generation boundary++A Segment is what the Spine binds one Take to, so each one is a separate generation and a separate+seam. Cut the Script the way the program is *spoken*, not the way its shots are numbered: splitting a+stretch that is delivered unbroken invents a seam nobody asked for, and inviting a generator to+re-establish the room across that seam is how continuity is lost for nothing.++Consecutive Segments carrying one unbroken voiceover are one Segment with Selections inside it. The+pictures over that stretch are placed by those Selections — `frame-coverage.md` governs what that+costs and what has to cover the silence between them — and the speech stays one Take.++Name Segments for what they hold. Names are handles: the Script's meaning lives in the words, and no+part of the pipeline reads a Segment name back for anything a reader would see.+## A voice is generated once- One accepted voice sample per person, however it was chosen.@@ -67,7 +81,8 @@ more often than they are kept, so the tier multiplies the whole bill rather thanA component that shows media — a card, a board, a frame, an insert — declares its media inputs asseparate attributes (`image`, `video`, `media`, `surface`), each with its own `accepts` type, and-`inspect_svml_vocabulary` reads them. Recognising them is the first half; the second is that every+`inspect_svml_vocabulary` reads them — `../../vocabulary.md` names the command. Recognising them is+the first half; the second is that everyslot the reference actually shows content in is **filled**. A slot the observation says holds apicture is given a generated picture; one that holds video is given a take. A slot left empty wherethe reference showed something is a card with a hole in it — the same failure as a missing innerdiff --git a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.mdindex 31145e2a..d607254b 100644--- a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md+++ b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md@@ -47,9 +47,14 @@ Every visible thing is either depicted material or drawn structure.- **Depicted material** is what a picture must show: scenes, people, products, textures, paper andbackdrop surfaces, artwork, screenshots, and any picture sitting inside a frame, card, device orinset.-- **Drawn structure** is what the composition computes: text content, exact font, size, weight,- spacing, alignment, colour, stroke, shadow, glow, frames, borders, corner radius, padding, stack- order, placement, reveal order and timing.+- **Drawn structure** is what the composition computes: text content, exact font, size, weight, line+ height, spacing, alignment, colour, stroke colour and width, shadow colour, offset, blur and+ opacity, glow, emphasis or active-item treatment, frame geometry, borders, corner radius, padding,+ stack order, placement, and reveal or typing rhythm.++ That list is also the checklist for accepting a package: `../../vocabulary.md` requires every one of+ these that changes what the viewer sees to be resolved before a component is chosen, and a property+ with nowhere to land in the declared vocabulary is what makes a gap.Never bake drawn structure into generated material. A generated picture of text cannot be re-timed,re-read or corrected, and its wording drifts. A card, inset, phone, browser or screenshot element is@@ -105,8 +110,8 @@ that needs one of those documents in order to draw itself has inverted that relapicture inside a card is part of the work, not decoration.- Generate it with `gpt:Image`, reading that package's README for its ports. Surveying what isinstalled before doing something you already know how to do costs time and buys nothing; the- listing exists for finding a capability you did not know was there, not for confirming a familiar- one.+ listing `../../vocabulary.md` documents exists for finding a capability you did not know was there,+ not for confirming a familiar one.- Static material is generated as an image. Generate video only when the element is a moving depictedscene.- Generate one material per depicted thing, at the aspect ratio it will be used at, carrying onlydiff --git a/.agents/skills/hypit/references/playbooks/craft/production-gates.md b/.agents/skills/hypit/references/playbooks/craft/production-gates.mdindex df347ed6..40aab9bb 100644--- a/.agents/skills/hypit/references/playbooks/craft/production-gates.md+++ b/.agents/skills/hypit/references/playbooks/craft/production-gates.md@@ -8,8 +8,9 @@ Use staged Run Sources so unreviewed expensive outputs cannot silently feed lateand factual claims before writing prompts.- Give every planned shot one job: hook, context, evidence, mechanism, reaction, payoff, transition,or CTA. Delete shots with no distinct job.-- Confirm credentials, Runtime Profile, installed packages, model limits, resolution, and Endpoint prerequisites.- Run `doctor`, `check`, and `plan` before the first paid Build.+- Confirm credentials, Runtime Profile, installed packages, model limits, resolution, and Endpoint+ prerequisites. `../../runtime.md` says how to author the Profile, and `../../vocabulary.md` how to+ find out what is installed. Run `doctor`, `check`, and `plan` before the first paid Build.## Gate 1: build and review reference images@@ -127,6 +128,9 @@ visual QA.Two cuts a quarter of a second apart is a picture nobody authored. Read it against`generated-dependencies.md` on windows that do not tile.- Preserve accepted Records for deliberate future reuse; never assume a rerun will reuse them.+- The delivery is accepted, so ask the last question: did this job produce a project-local package,+ and should it outlive this one video? `../../local-author-package.md` says how to judge that and+ what promoting it costs.Use explicit Run Source authoring for every accepted reuse:diff --git a/.agents/skills/hypit/references/playbooks/formats/asmr.md b/.agents/skills/hypit/references/playbooks/formats/asmr.mdindex 0d8c2edd..503c4142 100644--- a/.agents/skills/hypit/references/playbooks/formats/asmr.md+++ b/.agents/skills/hypit/references/playbooks/formats/asmr.md@@ -44,5 +44,8 @@ label stability, duplicated objects, camera drift, and broken tail frames. Thenthe visible event, including headphones and ordinary speakers. Pin accepted first frames, takes,and audio Records with `.svrun` `build-record` and `satisfy`.-Read `../craft/b-roll.md`, `../craft/sfx.md`, `../craft/persona-and-audio.md`, and-`../craft/production-gates.md`.+Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`, `../craft/b-roll.md`,+`../craft/persona-and-audio.md`, and `../craft/sfx.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md b/.agents/skills/hypit/references/playbooks/formats/mass-tarot.mdindex 7dd38675..35e55f69 100644--- a/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md+++ b/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md@@ -63,3 +63,6 @@ through `.svrun` `build-record` and `satisfy`.Read `../craft/b-roll.md`, `../craft/captions.md`, `../craft/overlays.md`, and`../craft/persona-and-audio.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/mixcut.md b/.agents/skills/hypit/references/playbooks/formats/mixcut.mdindex a807fb71..11dd362c 100644--- a/.agents/skills/hypit/references/playbooks/formats/mixcut.md+++ b/.agents/skills/hypit/references/playbooks/formats/mixcut.md@@ -56,5 +56,8 @@ audio start/end, claim accuracy, and the first/last second of the complete Film.image, clip, audio source, and ProgramSpace with `.svrun` `build-record` and `satisfy`; regenerateonly failed beats.-Read `../craft/image-prompt-style.md`, `../craft/b-roll.md`, `../craft/overlays.md`, and-`../craft/persona-and-audio.md`.+Read `../craft/image-prompt-style.md`, `../craft/b-roll.md`, `../craft/overlays.md`,+`../craft/persona-and-audio.md`, and `../craft/sfx.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md b/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.mdindex 6cc1bc58..789c477a 100644--- a/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md+++ b/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md@@ -44,5 +44,7 @@ Review resolved trigger count/order, terminal timing, item identity, rank/tier,evidence alignment, safe zones, stack order, and optional sounds. Pin accepted generated evidencemedia through `.svrun` before the final ranking Build.-Read `../craft/captions.md`, `../craft/overlays.md`, `../craft/b-roll.md`, and-`../craft/production-gates.md`.+Read `../craft/captions.md`, `../craft/overlays.md`, `../craft/b-roll.md`, and `../craft/sfx.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/scenario-call.md b/.agents/skills/hypit/references/playbooks/formats/scenario-call.mdindex 01c2932b..b84e6c26 100644--- a/.agents/skills/hypit/references/playbooks/formats/scenario-call.md+++ b/.agents/skills/hypit/references/playbooks/formats/scenario-call.md@@ -39,3 +39,6 @@ live listener reaction, UI stability, and generated text. Pin every accepted layRead `../craft/seedance-directing.md`, `../craft/captions.md`, `../craft/overlays.md`, and`../craft/persona-and-audio.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/street-interview.md b/.agents/skills/hypit/references/playbooks/formats/street-interview.mdindex 61096f60..b2f0a08e 100644--- a/.agents/skills/hypit/references/playbooks/formats/street-interview.md+++ b/.agents/skills/hypit/references/playbooks/formats/street-interview.md@@ -53,5 +53,8 @@ Review speaker/voice assignment, lip-sync, microphone position, listener silencestreet continuity, reaction timing, text hygiene, and caption placement. Pin accepted scene imagesand takes with `.svrun` `build-record` and `satisfy` before downstream assembly.-Read `../craft/seedance-directing.md`, `../craft/visual-continuity.md`, `../craft/b-roll.md`, and-`../craft/captions.md`.+Read `../craft/seedance-directing.md`, `../craft/persona-and-audio.md`, `../craft/captions.md`,+and `../craft/b-roll.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/talking-head.md b/.agents/skills/hypit/references/playbooks/formats/talking-head.mdindex ea806bd9..c119c624 100644--- a/.agents/skills/hypit/references/playbooks/formats/talking-head.md+++ b/.agents/skills/hypit/references/playbooks/formats/talking-head.md@@ -54,5 +54,9 @@ Use supplied UI media whenever exact interface content matters. Keep explanatorycollisions, and audio clarity.- Pin every accepted image and take in the next Build with `.svrun` `build-record` and `satisfy`.-Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`, `../craft/captions.md`,-`../craft/b-roll.md`, and `../craft/overlays.md` for the corresponding gates.+Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`,+`../craft/persona-and-audio.md`, `../craft/captions.md`, `../craft/b-roll.md`, and+`../craft/overlays.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md b/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.mdindex c1a5faaf..d1dc2bba 100644--- a/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md+++ b/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md@@ -51,5 +51,8 @@ lighting. Then review every take for voice assignment, exact words, lip-sync, recamera selection, and identity. Pin accepted views and takes through `.svrun` `build-record` and`satisfy`.-Read `../craft/visual-continuity.md`, `../craft/seedance-directing.md`, `../craft/captions.md`, and-`../craft/persona-and-audio.md`.+Read `../craft/seedance-directing.md`, `../craft/persona-and-audio.md`, `../craft/captions.md`,+and `../craft/b-roll.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md b/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.mdindex 60ee1a3f..6ceaa64e 100644--- a/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md+++ b/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md@@ -54,5 +54,8 @@ screen, product, hand, or proof changes.clipped narration, or visual proof that arrives before its setup.- Pin accepted narration and visuals through `.svrun` `build-record` and `satisfy`.-Read `../craft/screen-demo.md`, `../craft/b-roll.md`, `../craft/persona-and-audio.md`, and-`../craft/visual-continuity.md`.+Read `../craft/screen-demo.md`, `../craft/b-roll.md`, `../craft/persona-and-audio.md`,+`../craft/captions.md`, and `../craft/sfx.md`.++That list is complete: `../index.md` does not repeat it, and the craft its required load+order marks always-read is required regardless of format.diff --git a/.agents/skills/hypit/references/playbooks/index.md b/.agents/skills/hypit/references/playbooks/index.mdindex 25e32c46..608d3780 100644--- a/.agents/skills/hypit/references/playbooks/index.md+++ b/.agents/skills/hypit/references/playbooks/index.md@@ -10,10 +10,17 @@ needed for that craft or format.`craft/visual-continuity.md`, `craft/graphic-compositions.md`, and`craft/generated-dependencies.md`.2. Read `craft/seedance-directing.md` whenever the Author Source invokes Seedance.-3. Read the selected format file and only the additional craft files it names.+3. Read the selected format file and only the additional craft files **its own footer** names.+ That footer is the complete list; this index does not repeat it, and a footer that is wrong is+ fixed in the footer.4. Read `packages/<name>/README.md` for every package whose elements you write, and the relevantauthoritative Quickstart page for the model behind them.+No document a whole job needs may be reachable only through a conditional file. Craft and format+files are selected per job; a spine is walked by every job on its route, so anything every job needs+is named by `../original-authoring/index.md` or `../reconstruction/index.md` rather than by a craft+file that some jobs never open.+## Shared SVML contract- Put narrative truth in one `script` with Segments, Role Cues, Selections, and Moments.@@ -34,7 +41,8 @@ needed for that craft or format.- Stage expensive work with narrow `.svrun` Targets. Explicitly reuse an accepted Record through`build-record` plus `satisfy`; Hypit has no implicit cache.- Use only elements and attributes documented by the current Quickstart or package README. Never- invent a component or attribute to fill in missing syntax.+ invent a component or attribute to fill in missing syntax; `../vocabulary.md` says why, and how to+ find out what exists.## Prompt policy@@ -67,14 +75,20 @@ needed for that craft or format.## Formats-| Format | Additional craft to read |+| Format | Choose it when the request is ||---|---|-| `formats/talking-head.md` | `seedance-directing`, `persona-and-audio`, `captions`, `b-roll`, `overlays` |-| `formats/street-interview.md` | `seedance-directing`, `persona-and-audio`, `captions`, `b-roll` |-| `formats/two-person-podcast.md` | `seedance-directing`, `persona-and-audio`, `captions`, `b-roll` |-| `formats/scenario-call.md` | `seedance-directing`, `persona-and-audio`, `captions`, `overlays` |-| `formats/ranking-listicle.md` | `captions`, `overlays`, `sfx` |-| `formats/mass-tarot.md` | `b-roll`, `overlays`, `persona-and-audio`, `captions` |-| `formats/voiceover-desk-demo.md` | `persona-and-audio`, `b-roll`, `screen-demo`, `captions`, `sfx` |-| `formats/mixcut.md` | `image-prompt-style`, `b-roll`, `overlays`, `sfx` |-| `formats/asmr.md` | `image-prompt-style`, `seedance-directing`, `persona-and-audio`, `sfx` |+| `formats/talking-head.md` | one presenter speaking to camera — an explainer, an opinion piece, a piece to camera |+| `formats/street-interview.md` | a vox pop, passers-by being asked something, an interview on location |+| `formats/two-person-podcast.md` | a conversation between two people — a podcast clip, an interview at a table |+| `formats/scenario-call.md` | a video call or screen share, two live tiles, an active speaker that changes |+| `formats/ranking-listicle.md` | a top-N, a countdown, a tier list, "best X", any ordered set revealed in turn |+| `formats/mass-tarot.md` | a pick-a-card reading, a pick-a-pile, a several-option reveal |+| `formats/voiceover-desk-demo.md` | a voiceover over a product, a desk demo, a screen or hands walkthrough |+| `formats/mixcut.md` | a montage or music-led cut — short shots carrying the argument, nobody to camera |+| `formats/asmr.md` | close texture and sound, a satisfying micro-film, one physical action per shot |++Each format file's own footer is the single authority for the additional craft that format needs.+This table routes; it does not require. **An inventory may carry descriptions, and may not carry+requirements.** A stale description misroutes and the first line of the file it opens corrects it; a+stale requirement is silently unmet and nothing corrects it, which is what the craft column that used+to sit here did in seven of these nine rows.diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex 09662935..12fe8100 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -1,4 +1,61 @@-# Preview current source+# See what you authored, without paying++Three ways to look at a Source before a Provider is ever reached: prove the graph traces, render one+element to a still, and open the whole Run for a person. They answer different questions, and none of+them costs a generation.++## The graph traces before anybody opens it++`hypit check` proves a Source is legal; it proves nothing about whether the tracks it declares can+actually be built. A Run that does not trace fails the same way the moment the author opens Studio —+a new package with a bad schedule, a target that is not an output, a Film with no traceable+composition. Find that now, not on the author's screen:++```bash+# from the repository root: tsx is the repository's dependency+node --import tsx .agents/skills/hypit/scripts/preview-check.mjs path/to/build.svrun+```++It takes the Run Source, not the Author SVML — Studio's unit of work is the Run, and it reads the+`.svml` back out of it.++It exits non-zero when the graph itself is wrong, and it names what refused — a target that is not a+Film or Render output of the current SVML, a Film with no traceable composition, a Film with no+`SemanticTake` / Speech Track chain. This is not a guessing problem: the error says what is wrong, and+you repair that. A graph that does not trace is not done, and **every failure it reports must be+repaired until the check passes**, however many attempts that takes.++**One refusal is a pass, and it is the one you will see most.** A Source that declares its generation+rather than performing it leaves the closure waiting on Providers, and Studio requires the whole+closure before it will open. That is the expected state of a Source nobody has built yet, not a defect+in it. When every issue is `the Studio projection closure requires unresolved capabilities: …`, the+graph traced all the way to a Film and a semantic spine, and what remains is work a Provider has to+do — the script prints the waiting capabilities and exits zero:++```+preview-check: the graph is sound, waiting on 6 capabilities.+ - @hypit/seedance@1#seedance-2-mini+ - @hypit/whisperx@1#whisperx-alignment+ ...+```++Any other refusal means the graph is wrong and no amount of generation will fix it.++What this proves is that the graph is **wired**, not that every track **draws**. A Producer that+refuses the media kind it is handed is not caught here, because nothing is handed to it until the+Build runs.++## Render one element to a still, locally++One element — a new component, one caption system, one inserted card — can be rendered to an image+without a paid Provider. A new package's visual Surface needs a preview image anyway. The repository's+own visual test `packages/hyperframes/test/browser-visual.test.ts` shows the path end to end: build+the Track, compile the HyperFrames document, and render it through the local HyperFrames Runtime.++This is the image to reach for whenever one element has to be looked at rather than the whole+program. Rendering the delivery to inspect a single piece is the waste it exists to prevent.++## Open the whole Run for a personAfter a meaningful Author Source change, start Hypit Studio and give the author the actual URL.Kill the previous server first so the user does not inspect a stale composition.@@ -16,4 +73,7 @@ reuses accepted Build records.Studio opens a Run whose material is satisfied. When a projection is missing it names the issue andstops, so a Run that opens is a Run whose Tracks all resolved.+Studio is a browser preview **for a person to look at**. It is not a source of images for an+automated comparison — that is what the local still render above is for.+`docs/quickstart/preview.md` is authoritative.diff --git a/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.mdindex 37d349f8..908e2018 100644--- a/.agents/skills/hypit/references/reconstruction/final-sources.md+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md@@ -12,34 +12,20 @@ systems this reference actually contains, and write one complete project:dependencies.- `hypit.runtime.json` binds an Endpoint to every capability those sources demand.-The Runtime Profile is part of the deliverable even though this route runs nothing. Without it the-first thing the author meets is `RUNTIME_CAPABILITY_UNBOUND`, and the work of discovering which-Provider serves each model falls on them — work you have already done, since you chose every package-in the Source. Copy the nearest existing `examples/*/hypit.runtime.json` and bind one Endpoint per-capability your Sources actually reach: the picture and video models, speech, alignment, the media-Provider and the local renderer. Read each Provider's README for the shape of its `config`, and-reference credentials through the store rather than writing any secret into the file.--A capability whose credential this machine does not hold is still declared. Preflight names it before-any Build is submitted, which is the correct place for the author to find out.+The Runtime Profile is part of the deliverable even though this route runs nothing: without it the+first thing the author meets is `RUNTIME_CAPABILITY_UNBOUND`, and the work of binding a Provider to+each model falls on them — work you already did when you chose the packages. `../runtime.md` says how+to author one.Do not author one source fragment per shot. Do not let check success substitute for unresolvedsemantic evidence; return to a narrow `observe_reference` question when necessary.## A Segment is a stretch the reference actually plays as one-Cut the Script into Segments the way the reference is spoken, not the way its shots are numbered. A-Segment is what the Spine binds one Take to, so each one is a separate generation and a separate-seam; splitting a stretch the reference delivers unbroken invents a seam it does not have, and-inviting a generator to re-establish the room at that seam is how continuity is lost for nothing.--Consecutive Segments carrying one unbroken voiceover are one Segment with Selections inside it. The-pictures over that stretch are placed by those Selections — `../playbooks/craft/frame-coverage.md`-governs what that costs and what has to cover the silence between them — and the speech stays one-measured Take.--Name Segments for what they hold. Names are handles: the Script's meaning lives in the words, and no-part of the pipeline reads a Segment name back for anything a reader would see.+Cut the Script into Segments the way the reference is *spoken*, not the way its shots are numbered:+consecutive Segments carrying one unbroken voiceover are one Segment with Selections inside it.+`../playbooks/craft/generated-dependencies.md` says why — a Segment is a generation boundary, and+splitting a stretch the reference delivers unbroken invents a seam it does not have.## A take's duration is measured, not estimated@@ -56,69 +42,16 @@ original authoring, where nobody has said the words yet.Keep the estimate only where the reference cannot answer: a line the reconstruction adds, or aSegment whose speech the reference never contains.-Use existing checks only:--```bash-pnpm check-pnpm hypit check path/to/main.svml-pnpm hypit check path/to/recipes.svs-pnpm hypit check path/to/build.svrun-```--`hypit check` proves a Source is legal; it proves nothing about whether the tracks it declares can-actually be built. A track that fails the local preview fails the same way the moment the author-opens Studio — a new package with a bad schedule, a media edge whose artifact is not an-image, a reference that does not resolve. Find that now, not on the author's screen:--```bash-# from the repository root: tsx is the repository's dependency-node --import tsx .agents/skills/hypit/scripts/preview-check.mjs path/to/build.svrun-```--It takes the Run Source, not the Author SVML — Studio's unit of work is the Run, and it reads the-`.svml` back out of it.--It exits non-zero when the graph itself is wrong, and it names what refused — a target that is not a-Film or Render output of the current SVML, a Film with no traceable composition, a Film with no-`SemanticTake` / Speech Track chain. This is not a guessing problem: the error says what is wrong,-and you repair that.--A graph that does not trace is not done, and this is not the loop: the two-attempt ceiling governs-how *well* a wired element is tuned to the reference; it does not govern whether the element is-wired at all. Every failure this check reports must be repaired until the check passes. Repair as-many times as the failure needs, then re-run the check.--**One refusal is a pass, and it is the one you will see most.** A Source that declares its generation-rather than performing it — which is this route's own rule — leaves the closure waiting on Providers,-and Studio requires the whole closure before it will open. That is the expected state of a delivery,-not a defect in it.--So the check separates the two. When every issue is `the Studio projection closure requires-unresolved capabilities: …`, the graph traced all the way to a Film and a semantic spine and what-remains is work a Provider has to do — the script prints the waiting capabilities and exits zero:--```-preview-check: the graph is sound, waiting on 6 capabilities.- - @hypit/seedance@1#seedance-2-mini- - @hypit/whisperx@1#whisperx-alignment- ...-```--Any other refusal means the graph is wrong and no amount of generation will fix it — no Film or-Render target, a target that is not an output of the current SVML, no traceable Film composition, no-`SemanticTake` / Speech Track chain. Those exit non-zero and have no attempt ceiling.--What this gate proves is that the graph is **wired**, not that every track **draws**. A Producer that-refuses the media kind it is handed is not caught here, because nothing is handed to it until the-Build runs. Verify those on the real Build, report the check as exactly what it is, and do not let-it stand in for the delivery measurements in `../playbooks/craft/production-gates.md`.+Then check and wire, in that order. `../authoring.md` holds the check set — all four commands, not+only the Author Source — and `../preview.md` holds the graph check that comes after it. A Source that+passes every check can still declare a Run that does not trace, and neither gate is bounded by the+loop's two-attempt ceiling: a graph that does not trace is not a difference to weigh, it is work that+is not done.-What this check cannot see is equally important: a track that *builds* but looks wrong — a typeface-that does not match, a colour that is off, a shape that is misplaced — reports no error here, because-nothing failed. That is the loop's work, under `reconstruction-loop.md`, where Gemini compares the-rendered element against the reference and names the visible differences. Build failures are-repaired here until they pass; appearance differences are resolved there, bounded by the two-attempt-ceiling.+One thing to expect here rather than to debug: a route that declares its generation instead of+performing it leaves the closure waiting on Providers, so `preview-check` reporting only+`unresolved capabilities` and exiting zero **is the pass**, and is the state every reconstruction is+in when its sources are first written.Fix package resolution and package implementation before repairing source use. Continue until allthree files are accepted. Do not create `check_svml_project` or another wrapper.diff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.mdindex 02d0a72c..698f00d0 100644--- a/.agents/skills/hypit/references/reconstruction/index.md+++ b/.agents/skills/hypit/references/reconstruction/index.md@@ -49,9 +49,7 @@ which packages to use, not where to put the result — those are yours to decideis asking the author to do your job. Everything this route needs beyond the video path isdiscoverable:-- **Where you are.** This skill lives inside the Hypit repository; find its root from the skill's own- location (the directory containing `package.json` and `packages/`) and work from there. Repository- paths in these files — `.agents/skills/hypit/scripts/…`, `examples/…` — are relative to that root.+- **Where you are, and what is installed.** `../environment.md`.- **Where the project goes.** Its own directory: `examples/<something>-reverse/`, named after thevideo, beside the other examples, which the workspace already covers. Use a directory the authornamed only if they named one.@@ -116,8 +114,14 @@ Before acting on the evidence, read these files completely in order:and accepted Records are pinned for reuse.A file that list names and this one does not is read last, before `vocabulary.md`.-4. `vocabulary.md` — existing-package selection, appearance-property resolution, and the route for a- real vocabulary gap.+4. `../vocabulary.md` — how a package is chosen for any route: enumerate every system before naming+ one, what `list_svml_packages` and `inspect_svml_vocabulary` report, reuse before compose before+ declaring a gap, and what a real gap obliges.+5. `vocabulary.md` — what the reference evidence adds to that: enumerating from the observations, and+ measuring an appearance value rather than choosing it.+6. `../preview.md` — proving the Run traces before a Provider is reached, and rendering one element+ to a still without paying for it. Both are used later, by `final-sources.md` and+ `reconstruction-loop.md`; read them here so neither arrives as a surprise.Two more are required, at the point where they apply rather than now. Reading them here meansreading them half an hour before they matter, with a dozen other files in between:diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.mdindex d6e6e7a7..0b04d1f2 100644--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md@@ -6,7 +6,7 @@ something the reference never contained. Close that gap deliberately.This loop is about how an element *looks* against the reference, and it is bounded. Whether anelement is *wired at all* is a different gate with a different rule: `preview-check` (in-`final-sources.md`) must pass before this loop is even reached, and its failures are repaired+`../preview.md`) must pass before this loop is even reached, and its failures are repairedwithout any attempt ceiling. A graph that does not trace is not a difference to weigh; it is workthat is not done.@@ -64,8 +64,9 @@ repaired. It is not caught by looking at the frame yourself and choosing a fontresemble it — that route silently depends on the loop model having vision, and stops working themoment it does not.-Hypit Studio in `../preview.md` is a browser preview for a person to look at. It is not a-source of the image this loop needs.+Hypit Studio is a browser preview for a person to look at. It is not a source of the image this+loop needs: that image is the local still render in `../preview.md`, which draws one element without+a Provider.Repairing one element never re-runs the others. Do not rebuild the whole video to inspect one piece,and do not defer every comparison to a final delivery Build.@@ -140,3 +141,7 @@ stops as it is: the second repair is the last thing the observer saw, and therecomparison to name what remains. Do not spend one to find out — a comparison that changes nothingand exists only to report the gap is a paid step for a report nobody asked for. The element is whatit is; move on to the next one.++When there is no next element the route is over, except for one question. If a project-local package+was built along the way, decide whether it should outlive this video and put that to the author:+`../local-author-package.md` says how to judge it and what promoting it actually costs.diff --git a/.agents/skills/hypit/references/reconstruction/vocabulary.md b/.agents/skills/hypit/references/reconstruction/vocabulary.mdindex 5b1b4ffa..600dd658 100644--- a/.agents/skills/hypit/references/reconstruction/vocabulary.md+++ b/.agents/skills/hypit/references/reconstruction/vocabulary.md@@ -1,82 +1,34 @@# Reference-video vocabulary decisions-After observations, select candidate packages and run `inspect_svml_vocabulary`. Read each selected-package README as syntax authority. Compare the observation against declared inputs, outputs,-attributes, children, ports, Recipe properties, timing behavior, appearance and examples.+Read `../vocabulary.md` first. It decides how a package is chosen for any route — enumerate every+system before naming one, `list_svml_packages` and `inspect_svml_vocabulary`, reuse before compose+before declaring a gap, and what a real gap obliges. This file is only what the reference evidence+adds to that.-First enumerate every system the reference actually contains — base pictures, inserted elements,-full-screen graphic compositions, persistent overlays, captions, speech, music, sound effects — and-inspect candidates for each one. A system you never inspected is a system you are about to invent.-`inspect_svml_vocabulary` reads the packages you name, so name the ones you know and inspect them.-When a system has no package you can think of, `list_svml_packages` reports every installed package-with the tags it registers and the models it offers:+**Enumerate from the evidence, not from memory.** The systems this reference contains are the ones the+four whole-reference observations and the per-shot `visual` and `text_appearance` passes describe —+base pictures, inserted elements, full-screen graphic compositions, persistent overlays, captions,+speech, music, sound effects. Work that list, and inspect candidates for each entry on it. A system+you never inspected is a system you are about to invent, and here you would be inventing it against a+video that already answers the question.-```bash-hypit-reference-video-tools list_svml_packages-```+## Where an appearance value comes from-Run it before concluding that a capability is missing. Do not run it to confirm something you already-know: a vocabulary gap is proven by inspecting the candidates and finding none that fits, not by-failing to remember one.+`../vocabulary.md` says every declared property that changes what the viewer sees must be resolved+before a package is accepted, and that a default value is not a decision. In this route the values are+measured rather than chosen:-Use this decision order:--1. Reuse one existing component when it fully expresses the observation.-2. Compose multiple existing components when their declared outputs and timing express it without- changing the observed semantics.-3. Declare a real vocabulary gap only when neither option works.--Step 2 is not a way around step 3. Composition may express an observation with several components; it-may not move an element out of its role because some other tag happens to draw the same shape. What-an element **is** decides which vocabulary owns it — words spoken aloud are captions, a full-screen-designed field carrying content is one composition — and that answer does not change because the-element is styled beautifully or because the owning vocabulary is missing one property. A package-that owns the role but cannot express the observed appearance is a gap, exactly as much as no package-at all: `../playbooks/craft/captions.md` works one such case through.--Before accepting either step, name the observed appearance properties and say where each one lands in-the declared vocabulary. A property with nowhere to land is the finding, and it makes the gap —-there is no acceptable shortfall. The one thing that may not happen is quietly authoring something-else that resembles it.--Do not force a similar-looking tag into a role it does not own. Do not invent attributes or write a-nonexistent tag with the intention of implementing it later. A picture that-`../playbooks/craft/graphic-compositions.md` defines as one self-contained graphic composition may-never be split across unrelated tags to make installed vocabulary fit.--## Resolve every declared appearance property--Declared vocabulary tells you which properties exist. Only observation tells you their values.--- After inspection, list the declared properties that change what the viewer sees and are not yet- resolved by evidence: exact font and weight, size, line height, alignment, colour, stroke colour- and width, shadow colour, offset, blur and opacity, glow, emphasis or active-item treatment, frame- geometry, corner radius, border, padding, stack order, and reveal or typing rhythm.-- Each shot's `text_appearance` observation already describes drawn type in these terms. Read it+- Each shot's `text_appearance` observation already describes drawn type in those terms. Read itbefore asking anything.- Resolve what remains with a narrow `observe_reference --question` over the one to three shots wherethe element is most legible. Ask about visible attributes, never about components or syntax. Aquestion costs one request and does not disturb cached observations.-- A default value is not an observation. If the evidence came back inconclusive, ask again with a- narrower question rather than accepting a default: a value the observer never saw is not evidence,- and there is no state where a guessed value is acceptable.+- If the evidence came back inconclusive, ask again with a narrower question rather than accepting a+ default: a value the observer never saw is not evidence.- Read a persistent system's appearance from the shots where it is clearest and apply it to the wholesystem, as `continuity.md` requires.-## Real gaps--For a real gap, stop final-source authoring and read-`../local-author-package.md` completely. Implement and install the new project-local package, then-run `inspect_svml_vocabulary` against it before using its tag. That call is not redundant with having-just written the package: it proves the specifier resolves, the activation contribution is wired, and-the loader can decode the Surface. `pnpm check` proves none of those, because activation lookups fail-at runtime rather than at compile time.--The new package owns the whole observed composition. Its own surface — the paper, board, panel or-texture the composition always shows — is committed inside the package as a file, never demanded-from the graph. Only pictures that differ between videos are edges the source supplies.-`../playbooks/craft/graphic-compositions.md` draws that line; a component that cannot draw itself-without a project document is on the wrong side of it.+## After the gap is filledInstalling the package is not the end of the gap route. Read `final-sources.md` and write the threesources, then continue into `reconstruction-loop.md`: a component that loads is not yet a componentdiff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.mdindex d6e88b42..e174a429 100644--- a/.agents/skills/hypit/references/reconstruction/workflow.md+++ b/.agents/skills/hypit/references/reconstruction/workflow.md@@ -1,15 +1,18 @@# Reference-video workflow-The public interface is exactly five CLI subcommands from `@hypit/reference-video-tools`:+`@hypit/reference-video-tools` ships five CLI subcommands. Three of them are the reference evidence+and belong to this route:```bash-hypit-reference-video-tools list_svml_packageshypit-reference-video-tools prepare_reference --video-path <path>hypit-reference-video-tools observe_reference --reference-id <reference-id>-hypit-reference-video-tools inspect_svml_vocabulary --package <package> --tag <tag>hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id <shot-id> --image <path>```+The other two — `list_svml_packages` and `inspect_svml_vocabulary` — read installed vocabulary and+have nothing to do with a reference video. This route runs both, at the step the sequence names;+`../vocabulary.md` documents them and decides how a package is chosen.+Defaults are sufficient for normal use. Each also accepts `--input <json>`. Follow this sequence:```text@@ -29,13 +32,6 @@ list_svml_packages→ read reconstruction-loop.md, then render each authored element and compare it```-## list_svml_packages--Reports every installed package that declares an activation, with the Surface tags it registers.-This is the only way to know what vocabulary exists: `inspect_svml_vocabulary` reads packages you-name, and the Build CLI is deliberately unable to scan a directory. Run it before deciding anything-is missing.-## prepare_reference`prepare_reference` deterministically prepares clips, representative frames, tail frames, audio tails,diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.mdindex cd12dfd1..7226d488 100644--- a/.agents/skills/hypit/references/runtime.md+++ b/.agents/skills/hypit/references/runtime.md@@ -3,6 +3,21 @@Read `docs/quickstart/run.md` as the authority for Run Source, Target, Candidate, Runtime Profile,Build, retrieval, and reuse syntax. Use this file as the operational checklist.+## Author the Runtime Profile++The Runtime Profile is part of the deliverable, not a step the author does afterwards. Without it the+first thing they meet is `RUNTIME_CAPABILITY_UNBOUND`, and the work of discovering which Provider+serves each model falls on them — work you have already done, since you chose every package in the+Source.++Copy the nearest existing `examples/*/hypit.runtime.json` and bind one Endpoint per capability your+Sources actually reach: the picture and video models, speech, alignment, the media Provider and the+local renderer. Read each Provider's README for the shape of its `config`, and reference credentials+through the store rather than writing any secret into the file.++A capability whose credential this machine does not hold is still declared. Preflight names it before+any Build is submitted, which is the correct place for the author to find out.+## Execute the lifecycle```bashdiff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.mdnew file mode 100644index 00000000..267ce2a8--- /dev/null+++ b/.agents/skills/hypit/references/vocabulary.md@@ -0,0 +1,104 @@+# Choosing the vocabulary++This file decides which package owns an element, before anything writes one. It applies to original+authoring and to reconstruction equally: what changes between the two is where the requirement comes+from — a description, or a reference the evidence describes — not how a package is chosen to meet it.++## Enumerate every system before you name a package++First enumerate every system the program actually contains — base pictures, inserted elements,+full-screen graphic compositions, persistent overlays, captions, speech, music, sound effects — and+inspect candidates for each one. **A system you never inspected is a system you are about to invent.**++Then, for each: select candidate packages and run `inspect_svml_vocabulary`. Read each selected+package README as syntax authority. Compare what the element must be against declared inputs,+outputs, attributes, children, ports, Recipe properties, timing behavior, appearance and examples.++## What is installed: `list_svml_packages`++Reports every installed package that declares an activation, with the Surface tags it registers and+the models it offers. This is the only way to know what vocabulary exists: `inspect_svml_vocabulary`+reads packages you name, and the Build CLI is deliberately unable to scan a directory. Run it before+deciding anything is missing.++```bash+hypit-reference-video-tools list_svml_packages+```++It takes no arguments, needs no reference and no credentials — the binary is named for reconstruction,+this command is not. It does read `node_modules/@hypit` **relative to the working directory** and+refuses when that directory is empty, so run it from the repository root.++Run it before concluding that a capability is missing. Do not run it to confirm something you already+know: a vocabulary gap is proven by inspecting the candidates and finding none that fits, not by+failing to remember one.++## What a package declares: `inspect_svml_vocabulary`++Reads the packages you name and reports, per Surface, its tag, its attributes and their accepted+Types, its children, its ports, the Recipe properties it admits with their fallbacks, and its preview.++```bash+hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--package …] \+ [--tag <Tag> …] [--without-previews]+```++`--package` may be repeated. `--tag` is optional and repeatable: omit it and every Surface in the+named packages is returned. The README remains the syntax authority; this reports what the loader+will actually accept, which is what a mistaken attribute is checked against.++## Reuse, compose, or declare a gap++Use this decision order:++1. Reuse one existing component when it fully expresses the requirement.+2. Compose multiple existing components when their declared outputs and timing express it without+ changing what the element is.+3. Declare a real vocabulary gap only when neither option works.++Step 2 is not a way around step 3. Composition may express one element with several components; it+may not move an element out of its role because some other tag happens to draw the same shape. What+an element **is** decides which vocabulary owns it — words spoken aloud are captions, a full-screen+designed field carrying content is one composition — and that answer does not change because the+element is styled beautifully or because the owning vocabulary is missing one property. A package+that owns the role but cannot express the required appearance is a gap, exactly as much as no package+at all: `playbooks/craft/captions.md` works one such case through.++**Do not force a similar-looking tag into a role it does not own, and never invent a component,+attribute, child, port, Recipe property or literal value** — not even with the intention of+implementing it later. A picture that `playbooks/craft/graphic-compositions.md` defines as one+self-contained graphic composition may never be split across unrelated tags to make installed+vocabulary fit.++## Resolve every declared appearance property++Declared vocabulary tells you which properties exist. It never tells you their values; only evidence+does.++Before accepting step 1 or step 2, name the appearance properties the element must have and say where+each one lands in the declared vocabulary. A property with nowhere to land is the finding, and it+makes the gap — there is no acceptable shortfall. The one thing that may not happen is quietly+authoring something else that resembles it.++The properties to account for are the drawn structure that+`playbooks/craft/graphic-compositions.md` enumerates — the type, the paint, the geometry, the stack+order and the reveal. Work from that list rather than a second copy of it.++**A default value is not a decision.** A value nobody established is not evidence, and there is no+state where a guessed value is acceptable. Where the value comes from differs by route: a+reconstruction measures it — `reconstruction/vocabulary.md` says how — and original authoring decides+it deliberately and writes it down.++## A real gap++For a real gap, stop authoring sources and read `local-author-package.md` completely. Implement and+install the new project-local package, then run `inspect_svml_vocabulary` against it before using its+tag. That call is not redundant with having just written the package: it proves the specifier+resolves, the activation contribution is wired, and the loader can decode the Surface. `pnpm check`+proves none of those, because activation lookups fail at runtime rather than at compile time.++The new package owns the whole composition. Its own surface — the paper, board, panel or texture the+composition always shows — is committed inside the package as a file, never demanded from the graph.+Only pictures that differ between videos are edges the source supplies.+`playbooks/craft/graphic-compositions.md` draws that line; a component that cannot draw itself+without a project document is on the wrong side of it.