Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs(skill): remove superseded production routes
kashorinfefa7d45210f
diff --git a/skills/hypit/references/authoring.md b/skills/hypit/references/authoring.mddeleted file mode 100644index c8c383ca..00000000--- a/skills/hypit/references/authoring.md+++ /dev/null@@ -1,49 +0,0 @@-# Hypit source authoring--Read `quickstart.md` and the authoritative page it selects. Keep Author Source, Recipe Source and Run-Source complete rather than assembling independent per-shot fragments.--Before writing an element, inspect the owning package's public vocabulary and README. Never invent a-component, attribute, child, port, Recipe property or literal value, and never infer one package's-syntax from another.--Use direct reports as needed:--```bash-hypit-reference-video-tools validate_local_author_packages --run <run>-hypit-reference-video-tools validate_script_cues --run <run>-hypit check <run>-hypit-reference-video-tools preview_check <run> [<runtime>]-```--`hypit check` answers whether Source is legal. `preview_check` answers whether the Run traces to a-Film or whether only external capabilities remain unresolved. Neither records project progress.--An admitted model-neutral value is not proof that every Provider Endpoint accepts it. Before a paid-Build, read the selected Provider documentation and Runtime preflight. Resolve endpoint limitations-before submission.--## Reuse an accepted Result output--Reference a public output accepted by an earlier Build in a later Run:--```svml-<target output="final.video"/>-<build-record id="accepted-take" build="build-001" output="opening-take.video"/>-<satisfy output="opening-take.video" candidate="accepted-take"/>-```--The Candidate must have the exact nominal Type required by the Logical Output. Changing Targets alone-does not select a Result. When Studio or inspection needs a `build-record`, pass the Runtime Profile so-the Result repository can be opened.--Reuse generated media and paid SemanticTakes when their generating inputs still mean the same thing.-If a Script Segment changes, do not keep a SemanticTake whose tokens and anchors describe the old-Segment. Deterministic Track projections are recomputed from current Source; they are not historical-media to pin.--A failed Build may still have useful public outputs in its Result. Inspect and name those outputs, then-reference exactly the ones needed by the next Run. Do not resubmit the Build merely to recreate them.--For whole-video design decisions read `playbooks/index.md`. A later user-requested change follows-`revision/route.md` and edits Source/Recipe/Run, never generated media.diff --git a/skills/hypit/references/brief-intake.md b/skills/hypit/references/brief-intake.mddeleted file mode 100644index 05a50ddd..00000000--- a/skills/hypit/references/brief-intake.md+++ /dev/null@@ -1,71 +0,0 @@-# Dynamic brief intake for original authoring--An original-authoring request is not ready for Source merely because it contains a format name or a-single sentence. First freeze a brief that is sufficient to choose the narrative, Script, visual-semantics, timing, facts and paid generation inputs.--## Discover examples, never classify by filename--From the selected Distribution root, inspect `examples/` when it exists. Enumerate complete projects and-read each candidate's `main.svml`, `recipes.svs`, `build.svrun`, and relevant package README. A-read-only `hypit check` is allowed. Do not copy its Source, facts, people, assets, prompts or source-closure into the new project. Directory names, file names and component counts are only search clues.--For each candidate, read in this order:--```text-Script / Narrative-→ what the author wants the viewer to understand, believe, feel or do-→ opening attention strategy and Hook-→ narrative expansion, proof, reversal and payoff-→ visual, audio and text relationships-→ Recipe / Surface expression-→ Graph / Run implementation-```--Write an intent summary in your own words. It must distinguish what the Source explicitly says from-what you infer, and identify decisions that affect Graph structure, Script cuts, visual meaning,-timing, factual claims or paid generation. Compare the user's request with that summary. Ask only-for the high-impact decisions the request leaves unresolved. Never turn an example into a template or-a hard-coded type-specific questionnaire; an opening provocation is evidence of that author's Hook,-not a rule for a purported format.--After the intent comparison, use `playbooks/index.md` to determine whether a format playbook-matches the requested program. Read the matching format playbook completely, including its craft-notes and footer, and then read every additional craft file that footer names. The match is based on-the recovered intent and the user's goal, never on an example directory name, component count or a-fixed list of video types. If no format playbook matches, keep the general craft guidance and intent-analysis as the route's authority.--## General fallback when no example matches--If `examples/` is absent, empty, or semantically unlike the request, do not start Source and do not-skip intake. Use the user's words, installed vocabulary, craft references and the compilable SVML/SVS-/SVRun structure to derive an open-ended intent hypothesis:--- the promised viewer result and the central claim or tension;-- a plausible attention strategy and what expectation it creates;-- how the idea should develop and resolve;-- which visual, audio and text changes carry that meaning;-- which decisions are already made, which low-risk implementation details you may choose, and which- core facts, claims, Hook, audience promise, timing or paid inputs require confirmation.--This is an analysis method, not a list of ranking, interview, podcast or other type questions. Keep-the brief unfrozen while any unresolved answer could change the program's intent or graph.--## Project brief--Persist a concise JSON object at the one canonical path `.hypit/brief.json` (do not put it in Author-Source) containing:--- user goal and audience;-- intent, Hook/attention strategy and narrative progression;-- visual/audio/text relationships;-- example project path, or the general-analysis basis;-- confirmed decisions and unresolved questions;-- the expected SVML/SVS/SVRun structural consequences.--Keep one brief and edit it when the author clarifies intent. Do not create route-specific copies or a-second history of the brief. An agent may select fonts, package details and model tier when they are-genuinely low risk; it may not invent core facts, ranking criteria, claims, Hook or audience promises.-The brief is useful authoring content and the reference for later review, not a progress marker.diff --git a/skills/hypit/references/credentials.md b/skills/hypit/references/credentials.mddeleted file mode 100644index dc8e31f4..00000000--- a/skills/hypit/references/credentials.md+++ /dev/null@@ -1,118 +0,0 @@-# API keys and credentials--Credentials are resolved during environment setup, before media inspection, observation, authoring,-preview or Build. `check` and graph-only `plan` do not make paid requests, but a selected Runtime still-requires its demanded credential references to be present. HypiHub OAuth is the default; configure an-author-owned key only when the author explicitly requests it. Before continuing, configure only-variables used by the selected Runtime Profile:--| Variable | Provider/use |-|---|---|-| `KIE_API_KEY` | KIE generation: Seedance, GPT Image, and other selected KIE models |-| `GOOGLE_CLOUD_PROJECT` | Google Vertex project with Vertex AI enabled |-| `GOOGLE_APPLICATION_CREDENTIALS_JSON` | Vertex credential JSON contents, not a path |-| HypiHub OAuth login | HypiHub default paid provider for generation and Gemini VLM; run `hypit auth login hypihub.default --runtime hypit.runtime.json` and sign in at [hypit.ai](https://hypit.ai) |-| `MIMO_API_KEY` | Xiaomi MiMo Voice Design or Voice Clone when the user explicitly selects the official Provider |--Before any paid Build, report the selected Provider and credential source for every paid capability in-the Runtime Profile. Say the variable/store and endpoint (for example, `@hypit/provider-kie` using-`KIE_API_KEY` from env, or `@hypit/provider-hypihub` using HypiHub OAuth from the OS store); never print a-secret or a full credential JSON. If a required key is missing, invalid, returns 401/403, or cannot-reach the requested model, stop before payment and guide the author to [hypit.ai](https://hypit.ai)-for HypiHub OAuth login when that model is available there. Do not ask them to change Author Source just to-switch Provider.--When the selected HypiHub Endpoint uses the OS OAuth credential and it is missing, first explain to the-author why the login is being opened: no usable credential is configured, and browser sign-in lets the-Agent use HypiHub without asking the author to copy or paste an API key. If the account has no active-Hypit subscription, the author can purchase one on hypit.ai after signing in. The session is stored in-the OS credential store, and opening login does not itself submit a paid generation. Then the Agent must run-`hypit auth login <endpoint> --runtime <profile>` itself. This opens the browser login and waits for-the callback; do not ask the author to run the command or paste a key. Resume only after it succeeds.--HypiHub is the default for supported paid capabilities and Gemini VLM. It can be replaced only when the-author explicitly selects another Provider.-For ordinary `@hypit/gemini` Author Source, the Runtime Profile selects-`@hypit/provider-hypihub` or `@hypit/provider-vertex`; changing that Endpoint never changes Source.-The reference-video preprocessing observer uses the same Gemini Endpoint the selected Runtime Profile-binds: pass `--runtime <profile>` or select the Profile with `hypit runtime use`. There is no separate-environment switch for it. If a configured key cannot reach the requested-model, return to environment setup and use HypiHub OAuth when that model is available there; do not ask-them to change Author Source.--For reference-video reconstruction, HypiHub OAuth must be settled before observation or authoring begins-unless the author explicitly selected an author-owned provider credential. The `agent` observer's-technical ability to run without a key is not a permitted bypass; if the selected credential is absent,-stop at environment setup.--macOS/Linux session example:--A project that keeps its credentials in a `.env` file does not load them automatically — nothing in-this repository reads that file for you. Load it into the environment before any command that needs a-Provider:--```bash-set -a && source .env && set +a-```--Otherwise export them for the session:--```bash-read -r -s KIE_API_KEY-export KIE_API_KEY-read -r -s MIMO_API_KEY-export MIMO_API_KEY-export GOOGLE_CLOUD_PROJECT="your-project-id"-export GOOGLE_APPLICATION_CREDENTIALS_JSON="$(<"$HOME/.config/hypit/google-service-account.json")"-```--Windows PowerShell session example:--```powershell-$env:KIE_API_KEY = "your-key"-$env:MIMO_API_KEY = "your-key"-$env:GOOGLE_CLOUD_PROJECT = "your-project-id"-$env:GOOGLE_APPLICATION_CREDENTIALS_JSON = Get-Content -Raw "$HOME\.config\hypit\google-service-account.json"-```--Keep keys outside Author/Run/Runtime source and committed files. Verify presence without printing-values with, for example,-`node <skill-root>/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON`, then run-`hypit doctor` (once a Runtime Profile is selected with `hypit runtime use hypit.runtime.json`;-doctor audits the selected profile, so it needs no profile argument of its own).--## A changed credential does not reach a running Worker--The durable Worker keeps the environment it started with. Correct a key in `.env` or the shell while-one is running and the next Build still authenticates with the old value, which the Provider reports-as an ordinary `401 Invalid API Key` — pointing at the key you just fixed, or at the Provider, and-never at the stale process. Restart it:--```bash-hypit runtime down-```--The next Build starts a fresh Worker with the current environment. Do this before concluding that a-key is wrong; and when a `401` survives the restart, settle it against the API directly, once, rather-than by editing the key again:--```bash-curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $MIMO_API_KEY" \- https://api.xiaomimimo.com/v1/models-```--The reference-video route's `gemini` observer needs whatever credential the selected Runtime Profile's-Gemini Endpoint declares (HypiHub OAuth by default). Without one, that route can run its `agent` observer-instead, which reaches no Provider — `reconstruction/observers.md` says how the author chooses.--`hypit runtime down` stops the Worker for the whole project, so a Build running in another terminal-stops with it. The Build itself is durable and survives; bring the Worker back with `hypit runtime-up`, then reattach with `hypit status <build-id> --watch`. Observing requires a running Worker: with-none, `status --watch` reports the Worker's state and tells you to start it.--An Endpoint whose Runtime Profile points at the read-only `env` CredentialStore must be configured-by setting its exact environment variable. `hypit auth login` deliberately refuses to prompt in-that case. For an interactive workstation, select the writable `os` CredentialStore in the Runtime-Profile; after `runtime use`, `hypit auth login <endpoint>` stores the secret in macOS Keychain or-Windows Credential Locker. The same `{ "store": "os", "key": "…" }` reference works on both-supported systems. This is an explicit deployment choice, not a Provider-specific CLI branch.diff --git a/skills/hypit/references/element-review.md b/skills/hypit/references/element-review.mddeleted file mode 100644index 5787060a..00000000--- a/skills/hypit/references/element-review.md+++ /dev/null@@ -1,304 +0,0 @@-# Looking at what was built, before a Build runs--This visual-review page is for the initial reconstruction/description routes. A post-completion-revision does not use it, does not call a VLM/observer, and stops after direct deterministic checks; see-`revision/route.md`.--Structural checks prove that a source is legal. They prove nothing about whether it looks like what-was wanted. A newly written package can resolve, activate, decode and pass every check while drawing-something nobody asked for. Close that gap deliberately.--Both routes close it here, and both close it the same way: render one element as the Source-configures it, have somebody who did not build it read the picture, repair what they named, and stop-at a fixed ceiling. What differs is only the question put to the reader. A reconstruction has a-reference, so it asks what differs — `reconstruction/comparison-round.md`. A program authored from-a description has none, so it asks whether the picture is what it was asked to be —-`original-authoring/conformance-round.md`. Read this file first and that one after.--Whether an element is *wired at all* is a different question: `preview.md`'s `preview_check` reports-graph failures before this visual round. A graph that does not trace is not a difference to weigh; it-is work that is not done.--That check proves the graph is wired, not that every track draws. Nothing is-handed to a Producer until the Build runs, so a Producer that refuses the media it receives surfaces-there rather than here.--The two reports answer different questions. `preview_check` names the graph failure —-the target that does not trace, the chain that is missing — so its repairs are not guessing. This round-names what is visibly wrong with the picture, in words, and a repair aims at something the round-named. Each report tells you what is wrong; neither records hidden progress or grants approval.--## The round is named by the check, not chosen by you--`authoring_check` and `reconstruction_check` read the Source and return a `plan`: every stretch worth-looking at, as an element and a half-open range of the Script's own words, with the reason it earned a-place. Render that list and read that list. Nothing here asks you to decide which stretches matter.--One rule produces it, read off the Source: **a distinct declaration is a distinct picture**. An-element is looked at once per way it is declared, at the stretch where that declaration first-appears. This is also the floor, since every placed element declares something.--A token range is the stable identity used by every command. `--segment` and `--selection` remain-available for ranges that already have names.--The returned plan is the explicit review list. Review every entry it names; no separate workflow-state records whether the list is complete.--### Render what the Source configures, not what the catalogue shows--The thing read is the element **as this video places it**: the Recipe values the Source actually-passes, the Script text the Source actually feeds it, and the windows the Source actually binds. A-package's catalogue preview is a different picture drawn from different values — the package's own-sample copy and sample Recipe, chosen to show a reader the Surface's range — and a Source can fill-every one of those parameters with values that collide while the preview stays perfect. Reading the-preview answers a question nobody asked. `preview.md` keeps the two apart, says which command draws-which, and holds `render_element`'s own flags.--`render_element` reads the Canvas, the Recipe values and the Script text out of the Source, mocks-every layer a Build has not made, and drives the package's Producer. Nothing is transcribed by hand,-so nothing is transcribed one line at a time — which is what made a caption system look correct while-its lines collided.--**It draws the whole stretch, not the element alone.** `--element` names which element the round is-about; the picture is everything the Source places over those words, so two elements over one Segment-produce the same picture. Scope it with `--question` — that is what tells the reader which part of it-to read.--The window is named in words. `--segment` and `--selection` take a Script name, never a timestamp:-name the Segment or the Selection the element is drawn over, and give the same name to the round, so-every picture covers the same words. `script-time.md` says why a name travels where a number cannot.--### Mock the layers a Build has not made--The element rarely draws the whole frame. Below it is a base take that does not exist yet, and inside-it may be media slots the Source declares as generations. Render them as mocks rather than leaving-them out: a missing base is not a neutral background, it is black, and text that is legible on black-can be illegible on the picture that will replace it.--`render_element` delegates this to `@hypit/preview-mock`. The realizer finds every relevant logical-output in the compiled Author/Run Graph — the takes, stills and slot contents — derives geometry from-Graph inputs, and materializes them through `@hypit/mock-media` in a temporary Run under-`.hypit/preview/<run-name>/`. Never a paid generation the video will not reuse, and never a-placeholder drawn by a script written for the occasion.--Geometry follows the fixed Graph policy: Canvas width/height first, then generation aspect-ratio,-then Canvas fallback; resolution labels such as `720p` and `2K` are not converted to pixels, and-conflicting geometry fails.--Then tell the reader that those regions are preview mocks standing in for declared-but-unbuilt-generations, and to read only what the element itself draws. Said plainly it costs one clause and-saves the mock coming back as a finding in the one round there is.--### Geometry first: Canvas, outer frame, content--Every look starts with a geometry pass before style or polish. Identify the three nested levels:-Canvas, the outer Frame/background that owns the region, and the inner text or element that must fit-inside it. For each level, check the following explicitly:--- **Vertical centre:** when the design calls for vertical centring, compare the content centre with- the outer-frame centre on the Y axis. Report whether it is too high or too low and the approximate- offset. Do not treat a deliberate left/right bias as a defect; horizontal placement is decided by- the visual reference or the author's intent.-- **Containment:** report whether every visible glyph/mark stays inside its intended outer Frame and- whether the Frame itself stays inside the Canvas. Name the offending edge and the estimated amount- outside. Distinguish intentional bleed, crop, or enter/exit motion from an accidental overflow.-- **Capacity:** verify that the outer Frame is actually wide and tall enough for the text/element,- including padding, stroke, shadow, and the longest line. A centred item in an undersized box is still- a failure even when its centre is correct.-- **Canvas safety:** check the final visible bounds against all four Canvas edges. Nothing should be- clipped unless the reference/intent clearly calls for it.--Run and settle `layout_check` before this visual round. **Read now:** `layout-checks.md`. Its realized-Producer/DOM measurements accompany the render as candidate evidence only.-They help locate a relationship worth inspecting but never decide that alignment, offset, crop or-overlap is wrong. For reconstruction, reference observation is authoritative; for original authoring,-the user's brief and settled creative intent are authoritative.--Do not treat a clearly platform/player/export-tool watermark as authored content. Ignore it when its-provenance is obvious; if it could be part of the design, record the uncertainty instead of inventing-a repair.--A mock lives only in this render. It is never written into the Source, and no later check reads it: the-`playback` check reads the Source's Recipes, so a mock cannot be mistaken for coverage.--### The derived Run carries the mocks, and nothing else changes--The mocks are substituted into a Run that names the project's own Source. The whole program is drawn-and the window is cut out of the frames afterwards, so every element the Source places is present and-drawn wherever the Source puts it — what is on screen over the words being looked at is what the-delivery will put there.--That derived Run is on disk under `<project>/.hypit/preview/<run-name>/preview.svrun`, beside-its materialized Artifact attachments. Open it-whenever something you expected to see is not in the picture: an element that is in the Source and-still not on screen is the package failing to draw it.--### A caption Style is read once, where it first appears--Captions are the one element where the stretches are not different questions. A caption system is one-Style applied to whatever words fall under it, so two stretches drawn in the same Style differ only in-which words they hold — the typeface, size, weight, box, padding and placement are the same-declaration in both, and reading the second one returns the answer the first already gave.--So read **one stretch per distinct Style**, at the first occurrence of that Style. A program with-one default Style and a `caption:Use` override for one Selection is two looks, wherever those-two first appear, not one per Segment. This is the same reading `script-time.md` applies to every-other system that spans cuts: the system is authored once, so it is read once.--Stable package-internal realized bounds are checked separately by `layout_check`; this visual selection-remains one full clip per distinct declaration at first appearance and therefore covers motion as well.--### Render every stretch first, then send them all at once--No look's question depends on another's answer, so nothing is gained by waiting: rendering one and-reading it before rendering the next makes the round as long as the sum of its parts. Render the-whole set, then issue the round together.--**Send all of an element's pictures before repairing anything.** A repair changes what the next-picture would have shown, so a round interleaved with repairs is not one round — and what this round-is for is the set of findings across every stretch, which only exists once they have all come back.--## The reader is not the builder--This is the rule the whole round rests on, and it is not a preference. Somebody who knows what was-built, and what they hoped it would look like, confirms it. That is how a wrong typeface survives a-look: it resembles what the builder remembers choosing.--**Where the harness has subagents, one subagent per picture is required, and they run together.**-Claude Code and Codex have them. Give each its own, hand it the `instruction`, the `prompt` verbatim,-the `image_refs`, and — on a task that carries them — `transcript_ref` and `transcript_words`. Hand it-nothing else. Not what you built, not which component drew it, not what you expect it to find, not-another look's answer. Take the returned text and record it yourself, so one writer owns the log.--**Do not open the reference pictures yourself before the blind answer is recorded.** Whatever visual-ability the model running this round has, using the reference makes the reader and the builder the same-reader, and the round stops being evidence of anything. After a comparison or review has been recorded,-the Agent may open frames from its own render to diagnose an implementation defect; it must never use-that debugging path to inspect the reference. This is the same prohibition the `gemini` observer gets-for free by sending its pictures to a separate request; one subagent per task is what makes the other-paths equal to it rather than merely faster.--Answering inline is the fallback for a harness with no subagents, and only that. Read them one after-another rather than merging them into a single look — what the round is for is the set of findings-across stretches, and one answered in the light of the previous answer stops being independent-evidence of anything. There the discipline has to be explicit, because the reader is the builder and-nothing structural prevents it:--- **Write down what you see before naming a cause.** List what is visibly there, in the words you- would use if you had never seen the Source. Deciding what went wrong first, then looking, finds what- you expected.-- **Something you did not write down is not an attempt.** The two-attempt ceilings below count repairs- aimed at what the round named.-- **Measure rather than iterate.** A stroke that is too thick, a shape that is too tall, a margin that- is too wide — read the number off the frame against the frame's own width and height, and change the- value once.--## Repair in dependency order--When the finding is structural rather than cosmetic, repair in the order given by-`local-author-package.md`: package and workspace resolution, activation contribution, Manifest,-Producer, Type and Validator agreement, Surface vocabulary and decoding, implementation behaviour,-then source usage. Fixing source usage over a broken implementation hides the defect one layer down.--## One round--**There is one round.** What it returns is the whole set this program gets. Repair against that set-and stop; do not look again.--Two things follow, and they are the whole discipline:--- **Every repair aims at something the round named.** Changing something it did not mention is- thrashing, and it does not earn one of the attempts below.-- **A finding caused by an input that does not exist yet is not a repair target.** The mocks above- are preview-mock regions for a base take and media slots a Build has not filled, and a reader told where they- are should bypass them. One that reports a mock anyway is describing an absence, not a defect.--Something nobody can close is not a failure to record as one. A typeface the generator cannot-reproduce, a texture it will not hold, a grain that is not available — write it into the report and-leave it.--Read the frozen `.hypit/component-fit.json` only after the independent reader has returned its-findings. A difference that exactly matches a named accepted variance is recorded in the completion-report, consumes no repair attempt and does not block the round. Do not tell the reader about that-variance in advance. If a supposedly small difference instead changes the core look, role, structure-or behaviour, return to the vocabulary decision; do not copy or widen the installed package.--### Two ceilings, and they never share attempts--The first is over a *project-local package*: something that new package cannot express is its defect,-and fixing it means changing that package's structure. Installed packages are immutable; a finding-outside their accepted fit is a component-selection conflict, not permission to modify them. The-second ceiling is over the values: tune the Recipe, font, placement and motion the selected component-actually declares.--**Write-and-remake a project-local package: two attempts.** The first fixes what is obvious, the second fixes what-the first revealed. If it is still something the package cannot express — a typeface mix it has no-port for, a motion it cannot draw — the package is wrong rather than the values, and tuning values-is thrashing. Widen the package instead, which starts a fresh write-and-remake for the widened shape.--**Fill the parameters: two attempts.** The wrong weight, the wrong size, the wrong colour, the wrong-position. Beyond the ceiling, guesses overshoot — correcting past the target rather than towards it.-Time beats fidelity here by explicit choice.--**Each ceiling is two attempts for the element, across all its stretches.** Looking at an element in-five stretches does not buy ten attempts; it buys a fuller picture of what one attempt has to fix. One-repair aimed at something several stretches agree on is one attempt however many reported it.--## Measure what can be measured; iterate only on what cannot--Two attempts per element is not enough to converge by guessing, and it is not meant to be. Something-stated as a quantity — a stroke that is too thick, a shape that is too tall, type that is too large,-a margin that is too wide — is not a guessing problem. Ask for the number, over whichever stretch-renders the quantity most legibly. This is one reading of one number, not the coverage round, and-reading it off one where the thing is small buys a worse number for the same price.--Do that instead of spending an attempt. An attempt is for what has no number — a typeface's-character, a texture, a rhythm — where the only route is change it and look again.--Measure against the frame, not against the screen it is viewed on. A quantity read off a rendered-still means what it means relative to that still's own width and height — a stroke that is "one-percent of the frame height", a shape "a third of the frame width" — which is the same basis the-Recipe's fractions use. Saying "a little too tall" and changing it on feel spends the attempt the-measurement exists to save.--Stopping is the end, and the end carries no final look. When the attempts are spent the work on that element stops as-it is: the second repair is the last thing the reader saw, and there is no third round to name what-remains. Do not spend one to find out — a look that changes nothing and exists only to report the gap-is a step for a report nobody asked for. The element is what it is; move on to the next one.--Hypit Studio is a browser preview for a person to look at. It is not a source of the picture this-round needs: that picture is the local render in `preview.md`, which draws one element as the Source-configures it, 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 look to a final delivery Build.--## Say what this round did not settle--Every element was looked at and every repair stopped. That is what "complete" means here, and it does-not mean the video was watched: this round runs before the Build, so the pictures it read were renders-with preview-mock media under them. Report the difference rather than letting the word carry it.--State plainly, in the completion report, that the following are unsettled:--- **every generated picture and take** — the images and the shots a Provider has still to make;-- **the timing of every Track** — this round reads each one against an estimate-timed SemanticTake, so how a- Caption, Media or Typography Track sits against the speech that is finally delivered is settled once- that speech exists;-- **whether the picture is continuous** — the frames nobody authored that- `playbooks/craft/frame-coverage.md` is about. One inherited edge is reported here: the check reads each- Recipe's `playback` and refuses an insert configured to stop when its material runs out. The rest —- a window that starts late, a blend whose frames are half-covered, a schedule inside a component that- stops between activations — appear in the delivery;-- **whether the delivery says the Script's words** — a take generated from a prompt that lost its- dialogue passes every check made here.- `playbooks/craft/seedance-directing.md` says how to trace a take's prompt back to the Segment's- `dialogue` while the Source is being written, which is where this one is prevented.--The mechanical report names elements with no recorded review and timed pictures configured to empty-their windows. It cannot name what a Build has not produced yet, which is why this list is stated-rather than computed.--If a project-local package was built along the way, decide whether it should outlive this video and-put that to the author: `package-promotion.md` says how to judge it and what promoting it actually-costs.diff --git a/skills/hypit/references/environment.md b/skills/hypit/references/environment.mddeleted file mode 100644index a5ddd88b..00000000--- a/skills/hypit/references/environment.md+++ /dev/null@@ -1,235 +0,0 @@-# Cross-platform environment--## Three independent places--Hypit has three different lifetimes. Never collapse them into one directory.--- The **skill** is agent guidance. A Skill hub copies the real `skills/hypit/` subtree into an Agent's- global Skill directory so later sessions and unrelated projects can discover it.-- The **Distribution** is either an already installed machine-wide Hypit package, the machine-level- `<home>/hypit` checkout prepared by the Skill while npm publication is unavailable, or a contributor- checkout deliberately selected for repository work. It owns the CLI, Studio, official packages and- packaged Python service source.-- The **project** is the author's directory. It owns Sources, assets, project-local packages,- `hypit.runtime.json`, `.hypit/` Build state and output files.--Each project is an independent boundary. After selecting the active project, do not inspect another-author project or use anything from its `packages/` directory. Never copy, import or symlink a-project-local package across project boundaries. Resolve capabilities from the installed Distribution-or create the package inside the active project's own `packages/` directory through the local-package-workflow. Repository examples are read-only references only on routes that explicitly allow them;-they are never package dependencies.--Installing a Skill does not install the Distribution. OpenAgents and other Skill hubs own the installed-Skill copy; Hypit owns no second Skill registry and never rewrites that copy. Until the npm package is-published, the Agent prepares the Distribution checkout and its pinned dependencies once at machine-scope. The author does not clone it per project, run `npm link`, or run a service's `uv sync` by hand.--## Environment completion gate--This document must be read completely before any video-production route continues. Environment setup is-complete only when all of the following are true: a Hypit Distribution is selected; the project-directory and its package boundary are established; credentials for every capability the route will-use are resolved; the project's Runtime Profile is selected; `hypit runtime up` has finished installing-and starting every selected managed program; and every required health check passes. The local-WhisperX Endpoint is mandatory for video production and must report `Ready whisperx` (or an equivalent-successful probe).--Do not inspect media or examples, prepare or observe a reference, freeze a brief, inspect vocabulary,-write Source, preview, or Build until this checklist is complete. Do not substitute another-transcriber, defer installation, or continue from a partial or unconfirmed setup. Authentication is-part of this setup, not a later paid-build step. The explicit login-only request remains a fast path-for signing in and does not enter a production route.--## Credentials are part of environment setup--Resolve credentials immediately after selecting the Runtime Profile and before inspecting any media,-examples or references. HypiHub OAuth is the default for paid models and Gemini VLM. Check the selected-Endpoint:--```text-hypit auth status hypihub.default --runtime <hypit.runtime.json>-```--If its writable OS credential is missing, explain that browser sign-in lets Hypit use HypiHub without-copying an API key, then run the login yourself and wait for it to finish:--```text-hypit auth login hypihub.default --runtime <hypit.runtime.json>-```--Tell the author that an account without an active Hypit subscription can purchase one at-[hypit.ai](https://hypit.ai) after signing in. Do not ask the author to run the command or paste a key.-If the author explicitly asks to use their own provider key, configure that key instead and explain it-is the less-recommended path. A completed OS login is reusable across projects and later conversations-on the same machine; do not ask them to log in again when the credential is configured.--For reference analysis, strongly recommend Gemini VLM through HypiHub or Vertex: it can distinguish-speakers, align who speaks when, and extract voice/timbre and presentation traits, which improves-speaker replication and voice-design decisions. Do not use the credentialless agent observer as a way-to bypass credential setup.--## Select or prepare the Distribution--The Skill must be global. OpenAgents installs it from the repository's real `skills/hypit/` directory;-with the generic Skills CLI the equivalent command is:--```text-npx skills add hypit-ai/hypit --global-```--First try an already installed program:--```text-hypit paths --json-```--If that command is missing, do **not** run `npm install --global hypit`: the npm package is not-currently published. When the current task is repository development inside a Hypit contributor-checkout, use that checkout. For ordinary video production use `<home>/hypit` as the machine-level-Distribution. A valid checkout has all of these:--```text-package.json (name: "hypit")-bin/hypit.mjs-packages/reference-video-tools/bin/reference-video-tools.mjs-```--If `<home>/hypit` does not exist, clone the public repository there. If the path exists but is not the-Hypit checkout, do not overwrite or rename it; report the collision. Never create the checkout inside-the author project.--```text-git clone --branch main --single-branch https://github.com/hypit-ai/hypit.git <home>/hypit-```--At the first production turn in each conversation, fast-forward the selected checkout. Do not reset,-stash, discard or overwrite local changes. If the pull cannot fast-forward, report the exact checkout-and stop before production:--```text-git -C <distribution-root> pull --ff-only origin main-```--After the first clone or a successful pull, prepare the pinned dependencies from the Distribution-without changing the author project's working directory:--```text-corepack enable-corepack pnpm --dir <distribution-root> install --frozen-lockfile-```--Then use the Distribution entrypoints directly for the rest of the route:--```text-node <distribution-root>/bin/hypit.mjs paths --json-node <distribution-root>/packages/reference-video-tools/bin/reference-video-tools.mjs <subcommand> ...-node <distribution-root>/bin/hypit-studio.mjs --run <run> [--runtime <hypit.runtime.json>]-node <distribution-root>/bin/hypit-preview-check.mjs <run> [<hypit.runtime.json>]-```--In every reference that abbreviates these as `hypit`, `hypit-reference-video-tools`,-`hypit-studio` or `hypit-preview-check`, interpret them as the selected launchers above:--| Abbreviation | Checkout Distribution launcher |-|---|---|-| `hypit` | `node <distribution-root>/bin/hypit.mjs` |-| `hypit-reference-video-tools` | `node <distribution-root>/packages/reference-video-tools/bin/reference-video-tools.mjs` |-| `hypit-studio` | `node <distribution-root>/bin/hypit-studio.mjs` |-| `hypit-preview-check` | `node <distribution-root>/bin/hypit-preview-check.mjs` |--Do not interpret `hypit-studio` as a `studio` subcommand of `hypit`: Studio is a separate entrypoint.-Do not globally link the checkout, use `npx hypit`, or install dependencies into an author project.-Run reference-video-tool commands that share reference state from the same working directory, even-though their launcher lives in the checkout.--When a reference names `<skill-root>`, substitute the installed Hypit skill directory (the directory-containing `<skill-root>/SKILL.md` and `<skill-root>/scripts/`); it is not relative to the author's-project or checkout.--The installed Skill and the selected Distribution have separate update lifecycles. Pulling the-Distribution does not update an OpenAgents-installed Skill; existing OpenAgents users reinstall the-Skill when they want a newer workflow. Conversely, reinstalling the Skill does not replace a dirty or-diverged Distribution checkout.--`hypit paths --json` reports the current project boundary, project state, machine Program Home,-machine npm package home and selected Distribution. Those paths are facts; no repository locator or-environment lock is involved.--## Supported hosts and prerequisites--The supported desktop baseline is:--- macOS 13 or newer;-- Windows 10 or 11, x64;-- Node.js 22 or newer.--Windows XP is not a supported target: Node.js 22, current Python and the Windows Credential Locker do-not run there. Do not claim compatibility that the platform dependencies cannot provide.--`hypit` and Node are required. `ffmpeg` and `ffprobe` are required by local media and preview paths; a-host package manager puts them on `PATH` on macOS and Linux, and a manual install puts them on `PATH`-on Windows. Credentials load before any observer or Provider probe. In a checkout task, check the-checkout root `.env` and then the project root `.env` (project values override duplicates) in the same-shell:-`set -a; [ ! -f <checkout-root>/.env ] || . <checkout-root>/.env; [ ! -f <project-root>/.env ] || . <project-root>/.env; set +a`.-When these values satisfy the selected observer/Provider, do not ask the author for them again.-`uv` is required only when the selected Runtime Profile uses a managed Python program such as-WhisperX or OpenCV.-Reconstructing a video given as a link rather than as a file needs `uv` too: `yt-dlp` is pinned under-`services/yt-dlp` and run from there, so the version is the repository's rather than the machine's.-`prepare_reference` names what is missing when a link is passed without it.--When the Runtime Profile selects the local WhisperX Endpoint, `prepare_reference` probes the service's-health itself before transcribing, because a first start can spend several minutes loading the model.-A service that does not answer is reported in the command's result with a pointer to the repair rather-than silently producing an empty transcript.--`host-setup.md` holds the host toolchain installations and repairs, and is read when a command-reports that a service or a binary is unavailable.--## Machine Program Home--Managed programs are machine-level installations, separate from both Distribution and project:--- macOS: `~/Library/Application Support/Hypit/programs/`-- Windows: `%LOCALAPPDATA%\Hypit\programs\`--WhisperX, for example, lives under `programs/whisperx/`; OpenCV under-`programs/image-opencv/`. Service process records and logs live with the program. Project Build and-Worker state remains under `<project>/.hypit/`.--Reference-video state sits beside the Distribution, at `.hypit/reference-video-tools/<reference-id>/`.-Commands may run from any directory; the tool locates this canonical state from the selected-Distribution. It is keyed by the video, so two reconstructions of one file share-the observations it cost money to make; each command reports the root it used.--This split is why opening a second project cannot install WhisperX again, and why updating the npm-Distribution does not overwrite a Python environment or a user's project-local component.--The sibling machine npm package home is:--- macOS: `~/Library/Application Support/Hypit/packages/`-- Windows: `%LOCALAPPDATA%\Hypit\packages\`--The package set is reused by later sessions and unrelated projects. When a Distribution update-changes an exact adapter dependency, the next explicit `runtime up` lets npm update that package.--## Contributor checkout--A task changing Hypit itself uses its current contributor checkout rather than `<home>/hypit`. Follow-`docs/guide/develop.md` and use the pinned pnpm version and `pnpm-lock.yaml`. A contributor checkout may-also act as the Distribution for a video-production task, but the author project is still independent:-it may live anywhere and must never be added to the Hypit workspace or linked into the checkout.--The same fast-forward rule applies when a contributor checkout is selected. Updating its repository-refreshes its CLI, packages, services, examples, docs and canonical Skill source, but does not rewrite a-separately installed OpenAgents Skill copy.--A project directory carries its own `package.json` with the runtime-safe minimum-`{ "name": "<project-name>", "version": "0.0.0", "private": true, "type": "module" }`.-`hypit check`, `plan` and `build` locate the package root by walking-up from the project until some `package.json` appears; the file is what stops that walk at the-project, so `packages/<slug>/` resolves from there rather than from whichever ancestor-directory happened to hold one. It is matched by no `pnpm-workspace.yaml` glob and adds the project-to no workspace.diff --git a/skills/hypit/references/host-setup.md b/skills/hypit/references/host-setup.mddeleted file mode 100644index ddda9fb5..00000000--- a/skills/hypit/references/host-setup.md+++ /dev/null@@ -1,200 +0,0 @@-# Host setup--Installing and repairing the host toolchain a Hypit route depends on: FFmpeg, `uv`, the managed-WhisperX service, machine npm packages, and Distribution updates.--## General machine probe--Run this skill-owned probe when diagnosing a machine:--```text-node <skill-root>/scripts/check-environment.mjs-```--This checks shared host prerequisites only. Check the selected Distribution independently with-`hypit paths --json` or the checkout launcher defined in `environment.md`; a checkout does not need a-global `hypit` executable on `PATH`.--## Install FFmpeg prerequisites on Windows--Install a current FFmpeg build so both `ffmpeg.exe` and `ffprobe.exe` are available on `PATH`.-The preferred machine-wide route is Winget:--```powershell-winget install --id Gyan.FFmpeg.Shared -e-ffmpeg -version-ffprobe -version-```--If Winget is unavailable, download the current essentials ZIP from-`https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip`, extract it to a stable-directory such as `C:\Tools\ffmpeg`, and add its `bin` directory (for example,-`C:\Tools\ffmpeg\bin`) to the user or machine `PATH`. Open a new PowerShell window and verify:--```powershell-ffmpeg -version-ffprobe -version-```--Do not install FFmpeg into an author project or rely on a temporary download directory; the-executables are host prerequisites shared by Hypit projects.--## Install WhisperX prerequisites on Windows--Install `uv` with the host package manager, then let `uv` install the pinned Python interpreter.-Use Windows 10 or 11 x64 in PowerShell:--```powershell-winget install --id astral-sh.uv -e-uv --version-uv python install 3.13-```--Open a new PowerShell session if `uv` is not immediately on `PATH` after the Winget install.--Windows-specific checks before provisioning:--```powershell-Get-Command uv, ffmpeg, ffprobe-uv --version-ffmpeg -version-ffprobe -version-```--If the Hypit contributor checkout already contains a host toolchain (for example under-`.tools\ffmpeg-extract\...\bin`), prepend that `bin` directory to `$env:Path` for the current-PowerShell process before running media commands. Do not copy those executables into an author-project, and do not assume that a repository-local path is visible in a new shell.--## Install WhisperX prerequisites on macOS--Install `uv` with the host package manager, then let `uv` install the pinned Python interpreter.-Use macOS 13 or newer:--```bash-brew install uv-uv --version-uv python install 3.13-```--If Homebrew is not installed, install `uv` using Astral's current official installation method;-do not improvise a Python `pip install` for this managed-program workflow.--## Let Hypit install and run WhisperX--The project Runtime Profile must select the local WhisperX Endpoint. A minimal endpoint inside the-profile's `runtime.config.endpoints` is:--```json-"whisperx.local": {- "use": "@hypit/provider-whisperx-local",- "config": { "defaultConcurrency": 1 }-}-```--Then select and provision the Profile with the chosen Hypit launcher:--```text-hypit runtime use hypit.runtime.json-hypit runtime up-hypit runtime status-hypit doctor-```--`runtime up` owns the WhisperX installation: it creates or reuses the managed environment in the-machine Program Home, installs the locked service, prepares NLTK `punkt_tab`, starts the loopback-service on `127.0.0.1:8765`, and then starts the Worker. The first start may download the selected-Whisper and language-alignment model weights, so it can take substantially longer than later starts.-Do not run `uv sync` in an author project and do not install the `whisperx` Python package by hand.--`runtime up` printing `Ready whisperx` reports that the service answered its health probe.--`runtime up` probes each selected program. It creates that program's environment only when absent or-unhealthy, then reuses it across projects and sessions. It never runs `uv sync` merely because a new-project or Runtime Worker started.--### The health check fails--Do not reinstall Python packages: poll rather than launching a second copy, and read-`hypit runtime logs`. The managed WhisperX log is also at-`$env:LOCALAPPDATA\Hypit\programs\whisperx\program.log`, with the service's error stream beside it-in `program.err.log`.--Verify a running service with `hypit programs status` or `hypit doctor`. If preparation fails, read-`hypit runtime logs`; for a contributor checkout only, `services/whisperx/README.md` contains the-manual `uv sync --frozen`, prepare and check commands used to diagnose the packaged service.--### The log reports a missing `torchcodec` DLL--The log may contain a `torchcodec` warning about missing `libtorchcodec_core*.dll`, especially when-the host FFmpeg build is newer than the versions supported by that optional decoder. The warning is-diagnostic only: accept the service only after `/health` answers and a real Hypit transcription-request succeeds. Do not repair it with an author-project `pip install`; keep the Runtime-managed-environment authoritative.--### NLTK `punkt_tab` was blocked by a proxy or SSRF policy--If `runtime up` reports that NLTK `punkt_tab` is missing because Python's downloader was blocked by-a proxy or SSRF policy, install the same archive from NLTK's official data repository into the-managed WhisperX data root, then run `hypit runtime up` again. Do this only for that explicit network-failure; ordinary installs stay Runtime-managed.--Windows PowerShell:--```powershell-$whisperxData = Join-Path $env:LOCALAPPDATA "Hypit\programs\whisperx\nltk_data"-$download = Join-Path $env:TEMP ("hypit-punkt-" + [guid]::NewGuid().ToString("N"))-New-Item -ItemType Directory -Path $download | Out-Null-Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/packages/tokenizers/punkt_tab.zip" -OutFile (Join-Path $download "punkt_tab.zip")-New-Item -ItemType Directory -Path (Join-Path $whisperxData "tokenizers") -Force | Out-Null-Expand-Archive -LiteralPath (Join-Path $download "punkt_tab.zip") -DestinationPath (Join-Path $whisperxData "tokenizers") -Force-hypit runtime up-```--macOS:--```bash-whisperx_data="$HOME/Library/Application Support/Hypit/programs/whisperx/nltk_data"-download_dir="$(mktemp -d)"-mkdir -p "$whisperx_data/tokenizers"-curl -L "https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/packages/tokenizers/punkt_tab.zip" \- -o "$download_dir/punkt_tab.zip"-unzip -q "$download_dir/punkt_tab.zip" -d "$whisperx_data/tokenizers"-hypit runtime up-```--## A package reports a missing optional dependency--Upstream npm dependencies follow the same machine-level lifetime as managed programs. The-Distribution ships first-party Model, Provider, component and Studio code, but not every Fontsource-family, AWS SDK, HyperFrames browser package or optional observer SDK. `runtime up` prepares only-dependencies declared by the selected Runtime adapters. An author package reports an exact command-when its own optional dependency is missing:--```text-hypit packages install @fontsource-variable/[email protected]-hypit packages status @fontsource-variable/[email protected]-```--These commands use npm's ordinary `package.json` in the machine package home with no Hypit lock,-receipt, digest inventory or project-local copy.--## Update an installed Distribution--Updates to an installed, published Distribution remain an explicit package-manager operation:--```text-npm outdated --global hypit-npm update --global hypit-```--Use `hypit --version` to report an installed package Distribution. These commands apply only after the-package is published; do not add a registry request to every route. A checkout Distribution is updated-only with the fast-forward repository flow in `environment.md` and never through npm.--The installed Skill has a separate lifecycle. OpenAgents or another Skill installer updates its copy;-pulling a Distribution checkout does not rewrite it, and reinstalling the Skill does not modify the-checkout.--After updating Hypit, stop an idle Runtime Worker before the next Build so the next process loads the-new Distribution. Existing project Sources and accepted Build records remain in the project.diff --git a/skills/hypit/references/layout-checks.md b/skills/hypit/references/layout-checks.mddeleted file mode 100644index d4356a55..00000000--- a/skills/hypit/references/layout-checks.md+++ /dev/null@@ -1,60 +0,0 @@-# Layout checks are evidence, not design authority--Run this after `preview_check` whenever Source, SVS, runtime, fonts or a package can affect layout:--```bash-hypit-reference-video-tools layout_check --run <build.svrun> [--runtime <hypit.runtime.json>]-```--Pass the project's Runtime Profile when the Run contains `build-record` pins. The checker uses it-read-only to resolve those accepted Records; without it a pinned Run can fail before any layout is-measured.--The command does not render media, call a visual observer or invoke a paid Provider. It first realizes-the same preview-mock Run and Producer-generated Composition that the later visual render reuses, then-writes atomic state to-`.hypit/layout-check.json` and `.hypit/layout-decisions.json`.--It reports only `realized_layout`: DOM bounds after official or project-local Producers run, including-parent or Canvas overflow, vertical offset of package-internal content, and partial overlap between-independent top-level tracks. It does not treat literal SVML Canvas/Frame arithmetic as a quality verdict.--`Present` is the Composition IR's time-bounded visual unit: one Producer output with its internal-text, icons, boxes and other elements. For each Present/content state, the checker derives its longest interval in which layout-affecting IR-does not change and measures the interval's middle frame. Findings for that sample are restricted to-that Present. Peer overlap is reported only when both Presents share a sampled stable frame. A Present-with no stable interval of at least two consecutive frames is skipped and left to the full-clip visual-review; moving entry and exit frames are not treated as layout evidence.--Every reported item is a **candidate measurement**, never a declaration that the design is wrong.-Cropping, bleed, overlap, off-screen entry motion and optical offset can all be intentional. Read the-measured relation, the relevant brief/reference and the rendered visual evidence, then either repair a-real problem or accept the intentional geometry:--```bash-hypit-reference-video-tools layout_accept --run <build.svrun> \- --finding <id> --reason '<why this measured relationship is correct here>'-hypit-reference-video-tools layout_check --run <build.svrun> [--runtime <hypit.runtime.json>]-```--Several candidates from the same report can be accepted atomically with a JSON array (or an object-containing `findings`):--```bash-hypit-reference-video-tools layout_accept --run <build.svrun> --batch acceptances.json-```--Each entry is `{ "finding": "<id>", "reason": "<why this measured relationship is intentional>" }`.--The browser report separates candidates still needing judgement from intentional candidates carrying-a reason. It does **not** turn zero candidates into approval of the whole design. A browser, font or-Producer execution failure means no measurement was made and must be reported as such.--Finding identities are readable structural names built from the finding kind, package, Track,-Present, element and related element. They do not fingerprint the project. Rerun `layout_check` after-a visual repair, and read the affected declaration again when its appearance changed.--The 1 CSS px tolerance removes only browser numeric noise. It is not a design threshold and does not-turn measurements beyond it into mandatory fixes. Do not copy or edit an installed package after a-candidate appears; adjust legal SVS, choose another component, or use the formal project-local package-path.diff --git a/skills/hypit/references/local-author-package.md b/skills/hypit/references/local-author-package.mddeleted file mode 100644index 39ddf93a..00000000--- a/skills/hypit/references/local-author-package.md+++ /dev/null@@ -1,61 +0,0 @@-# Project-local author packages--Create a local package only after inspecting installed vocabulary and confirming that no existing-Surface can express an important visual role. A small stylistic difference is not a missing-capability.--## Boundaries--- Put the package under the author project's `packages/` directory and use the project's own scope.-- Do not edit, vendor or copy an installed package.-- Keep the package reusable across multiple elements in this project; video-specific words, people,- products and timing remain in Source/Recipe.-- Do not hand-author SVG assets or inline SVG.-- Use the public package activation, Surface, Producer and Fragment APIs only.--Inspect the real schemas before implementing:--```bash-hypit-reference-video-tools inspect_svml_vocabulary --package <closest-package>-hypit-reference-video-tools inspect_visual_schema-```--## Minimal package shape--The package must provide:--- a `package.json` with the appropriate Hypit activation entry;-- a public Surface vocabulary with explicit inputs, outputs and Recipe properties;-- a Producer that returns the declared nominal output Type;-- a Fragment that projects the produced value into the Runtime/Composition system;-- a README describing the public vocabulary and a preview project using it.--Prefer composition of existing public operations over new Runtime capabilities. Add a new capability-only when an external or local service genuinely owns that work.--## Validation--Install the project dependencies, then inspect the package through the same public loading path used-by an author project:--```bash-hypit-reference-video-tools list_svml_packages-hypit-reference-video-tools inspect_svml_vocabulary --package <local-package>-hypit-reference-video-tools validate_local_author_packages --run <project>/build.svrun-hypit-reference-video-tools validate_script_cues --run <project>/build.svrun-hypit check <project>/build.svrun-hypit-reference-video-tools preview_check <project>/build.svrun-hypit-reference-video-tools render_previews <project>/packages/<package>-hypit-reference-video-tools layout_check --run <project>/build.svrun-```--These commands report separate facts. A package is ready when its declared vocabulary loads, the-project actually imports and uses it, the graph traces, its previews render, and visual inspection-matches the requested design. Do not manufacture an override file when a command is broken. Report-the exact defect, fix the tool or package, and rerun the relevant command.--## Promotion--Finish the video before considering promotion. If the component has clear value across unrelated-projects, read `package-promotion.md` and ask the author before moving it into the Hypit repository.-Otherwise it remains ordinary project source.diff --git a/skills/hypit/references/original-authoring/conformance-round.md b/skills/hypit/references/original-authoring/conformance-round.mddeleted file mode 100644index 17256666..00000000--- a/skills/hypit/references/original-authoring/conformance-round.md+++ /dev/null@@ -1,123 +0,0 @@-# Reading each element against what it was asked to be--Completed reviews are ordinary content in the project review log. After an interruption, inspect that-log and the current render directly. Repeat a local review only when the visible source changed or the-caller explicitly wants a new reading.--**Read `../element-review.md` first.** It owns the round this file sits inside, and everything below-is what having no reference changes.--What it changes is the question. A reconstruction has a second picture and asks what differs. Here-there is one picture, and the question is whether it is what was asked for. Nothing external can-answer that, so the answer has to be written down before it is asked.--## What the element is judged against--Two things, both of which already exist by the time this round starts:--- **The answers frozen at step 3** — the subject, the length, the aspect ratio, the language, who is- in it, what it says. `route.md` requires them frozen before any prompt is written precisely so that- something here can be measured against them.-- **The appearance values written down at step 7** — every value that changes what the viewer sees.- A reconstruction measures those off the reference; here they are chosen, and a value nobody wrote- down cannot be wrong, which is the failure this round exists to catch.--Write the element's own share of both into a file and pass it as `--intent-file`. It is required, and-required for a reason: a conformance question with nothing to conform to asks whether the picture-looks acceptable, which it always does to whoever drew it.--Do not put the selected package, rejected candidates or component-fit rationale into the intent.-Details the author never specified and the brief never decided are not hidden requirements for the-reader to invent. Apply any named accepted variance only after the independent answer returns.--## The round--```-hypit-reference-video-tools review_element --run projects/<name>/build.svrun \- --element <id> --segment <id>|--selection <id> \- --video <rendered>.mp4 --intent-file <what this element was asked to be>-```--`--batch <reviews.json>` sends a whole round as one call, an array of-`{element, segment|selection, video_path, intent_file}` inheriting the Run. Render every stretch-first, then send them together.--The command does not render — `render_element` in `../preview.md` did that. It prepares the picture,-writes an entry to `<project>/.hypit/reviews.jsonl`, and hands back the task: the instruction, the-prompt and one picture. A clip becomes a grid of its own frames; a render that never changes becomes-one still.--There is **no observer question on this route**. The picture is a local render, nobody is billed to-look at it, and the reader is a subagent. If you came here from the skill entry expecting to ask the author-which observer reads the reference, that question belongs to the other route.--## What the reader is asked--`review_element` writes the whole prompt, so there is nothing to compose. It asks two things:--- **Whether the picture matches the description** — which parts it satisfies, which it does not, what- the description asks for that is not there, and what is present that the description never- mentioned.-- **What is visibly wrong** — anything cut off by the frame edge or reaching past it, anything- overlapping something meant to be read, any position or alignment against the frame's edges that- looks unintended, and anything too low in contrast to read. Over a clip it also asks what appears,- moves or leaves in a way the description does not account for.--The preview-mock clause is in the prompt already: the reader is told that flat-filled regions stand in-for generations that have not run and to read only what is drawn over them. Do not add it by hand, and-do not add anything that says what you built or what you expect to be found.--The visual pass is geometry-first. Read the hierarchy Canvas → outer Frame/background → inner text or-element. When the intent calls for vertical centring, compare the inner and outer centres on the Y axis-and report whether it is too high or too low. Deliberate left/right bias is not a mechanical defect.-Check containment at both boundaries (content inside its Frame,-Frame inside Canvas), naming any overflowing edge. Confirm the outer Frame is wide and tall enough for-the longest line/mark plus padding, stroke, shadow, and corner treatment; correct centring does not make-an undersized box acceptable. Separate intentional bleed/crop or enter/exit motion from accidental-overflow, and check the final visible bounds against all four Canvas edges.--The settled `../layout-checks.md` report supplies realized stable-state measurements alongside this-round. They are advisory candidates, not automatic failures. Make the conformance decision from the-rendered picture and intent; do not force centring, remove an intentional overlap or undo a deliberate-crop merely because the mechanical pass measured it.--Clearly platform/player/export-tool watermarks are not authored content and should be ignored. If a mark-could be intentional design, preserve the uncertainty and do not silently remove it.--`--question` is available and means what it means on the other route: which region to read, never what-to conclude.--## Recording the findings--```-hypit-reference-video-tools record_review --run projects/<name>/build.svrun \- --review-id <id> --text-file <the findings>-```--Until that lands, the picture has been drawn and handed over with nobody having said what it shows,-and `authoring_check` lists it under `awaiting_answer` and credits the element nothing. Record every-finding, including the ones that read as satisfied, in the words the reader used.--## Measuring, on this route--A quantity is read rather than guessed at, and here the instrument is a second subagent: give it the-same picture and ask for one number against the frame's own width and height. It costs a subagent and-no money, which is why it is always cheaper than spending one of the two attempts.--## Closing the round--```-hypit-reference-video-tools authoring_check projects/<name>/build.svrun-```--It names each element nobody has looked at and the command that looks at it, and reports-`"passed": false` until none are left. Like its counterpart it asks for participation rather than-convergence: an element reviewed once and stopped at its ceiling passes, and an element nobody looked-at does not.--It also applies every check the Source alone decides — a stretch of the Script nothing draws a-full-frame picture over, a Frame reaching past the Canvas, and a timed picture whose `playback` is-left at its default and so draws its material once and then nothing for the rest of its window.-`../playbooks/craft/generated-dependencies.md` says what to set.--**Done when:** `"passed": true`. Then, and only then, the Build.diff --git a/skills/hypit/references/original-authoring/route.md b/skills/hypit/references/original-authoring/route.mddeleted file mode 100644index 1002129f..00000000--- a/skills/hypit/references/original-authoring/route.md+++ /dev/null@@ -1,74 +0,0 @@-# Original authoring--Use this workflow when the request supplies a description, topic, script or format but no reference-video.--## 1. Establish the project--Read `../environment.md`, create an independent author project, and keep `.svml`, `.svs`, `.svrun`-and `hypit.runtime.json` separate. Read `../brief-intake.md`, semantically relevant complete examples,-and `../playbooks/index.md` before deciding the visual system.--Write the brief as ordinary project content. It may be edited when the request becomes clearer; there-is no frozen brief snapshot or hidden progress record.--## 2. Choose vocabulary--Inspect what actually exists:--```bash-hypit-reference-video-tools list_svml_packages-hypit-reference-video-tools inspect_svml_vocabulary --package <package>-hypit-reference-video-tools inspect_visual_schema-```--Use public Surfaces and Recipe fields. When no installed package can express an important role, read-`../local-author-package.md` and create a project-local package. Do not alter installed packages.--## 3. Author Source, Recipe and Run--Write the smallest complete program. Every visible spoken passage uses short Cues separated by `||`,-normally 3–4 words. Apply the relevant craft references for coverage, captions, overlays, generated-dependencies, persona/audio and continuity.--Inspect the actual files directly:--```bash-hypit-reference-video-tools validate_local_author_packages --run ./build.svrun-hypit-reference-video-tools validate_script_cues --run ./build.svrun-hypit check ./build.svrun-hypit-reference-video-tools preview_check ./build.svrun-hypit-reference-video-tools layout_check --run ./build.svrun-```--These commands are separate reports. Run the ones that answer a real question, repair confirmed-issues, and record a reason with `layout_accept` when a measured offset/overlap/overflow is intentional.--## 4. Read the visual result--Use `authoring_check` to obtain a useful review plan, then render the named element/window locally:--```bash-hypit-reference-video-tools render_element ./build.svrun \- --element <id> --tokens <from:to> --out ./review/<name>.mp4-hypit-reference-video-tools review_element --run ./build.svrun \- --element <id> --tokens <from:to> --video ./review/<name>.mp4 \- --intent-file ./review/<intent>.md-```--Record out-of-band findings with `record_review`. Fix what conflicts with the brief; do not chase a-numeric score or repeat the same view merely to obtain a different answer.--## 5. Build or hand off--Read `../runtime.md` and `../studio-confirmation.md`. Use Studio to show the current Run and report its-exact URL. When the user wants generated media, run `hypit plan`, disclose cost and external Provider-selection, obtain approval, then run `hypit build` once.--The Result from that Build is the durable answer. Give important Results/outputs human presentation-names. A later request edits the existing Source through `../revision/route.md`; it never edits the-rendered media.--For many variants, copy the accepted source project into ordinary independent directories and keep a-human-readable task list. Do not create an aggregate variant state system, and do not submit paid-Builds unless the author requested them.diff --git a/skills/hypit/references/package-promotion.md b/skills/hypit/references/package-promotion.mddeleted file mode 100644index 31846942..00000000--- a/skills/hypit/references/package-promotion.md+++ /dev/null@@ -1,52 +0,0 @@-# Promote a project-local package into the Hypit repository--This file says how to judge whether a project-local author package should outlive the video it was-built for, and what promoting it into the Hypit repository costs.--## 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 only when it clears a high bar. 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 many unrelated videos want this vocabulary, with little or no-rewriting?** 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. Promote only a component with an unusually clear, broad role that the installed packages do-not cover and that is strong enough to justify maintaining as an official package. If the package-would need substantial adaptation 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 inside a project, so the first-person to do it should correct what follows.--- **The name is load-bearing in six places.** `@my-project/<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 "@my-project/<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 support is a companion.** A project-owned `@my-project/<slug>-studio` may already provide- rich interpretation. Promotion moves that companion into an official Studio adapter package; it- never copies its code into `@hypit/studio` and never teaches the domain package about Studio.-- **Its own chrome becomes repository content.** Project package assets already belong to the- project's Git history. Promotion makes those accepted bytes official package content and must- deliberately choose their permanent location.-- **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 and projects are exempt from. A package- carrying its render-harness dependencies in `devDependencies` fails on the way in.-- **The workspaces stay separate.** Promotion adds the package to Hypit's `packages/*` and root- catalog; it never adds the external project or a project glob to Hypit's workspace.--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 package boundary section of-`local-author-package.md` gives.diff --git a/skills/hypit/references/preview-mock.md b/skills/hypit/references/preview-mock.mddeleted file mode 100644index 75b9e21b..00000000--- a/skills/hypit/references/preview-mock.md+++ /dev/null@@ -1,16 +0,0 @@-# Local preview material--`@hypit/preview-mock` replaces unresolved image, video, audio and SemanticTake needs with local-stand-ins so the authored Graph can be viewed without paid generation.--The realizer writes a working directory for the Run under `.hypit/preview/<run-name>/`, containing a-native mock Run, a Studio-ready preview Run and ordinary local resources. Re-running the command-updates that working directory. It is disposable preview material, not Build history or authoritative-project state.--The preview Run uses relative file Candidates and estimate timing. Mock media never enters Author-Source. Reference timing is used to select comparison windows, not to invent the preview's semantic-clock.--Use the exact `previewRun` path returned by the realizer. Do not reconstruct it from internal resource-names, and do not treat the presence of preview files as evidence that a paid Build ran.diff --git a/skills/hypit/references/preview.md b/skills/hypit/references/preview.mddeleted file mode 100644index 2e48b2d4..00000000--- a/skills/hypit/references/preview.md+++ /dev/null@@ -1,50 +0,0 @@-# See what you authored without paying--Preview and inspection commands are independent. They do not write progress state or automatically-run one another.--## Trace the Run--```bash-hypit-reference-video-tools preview_check /path/to/project/build.svrun-```--`hypit check` proves Source legality; `preview_check` proves the Run can trace toward a Film. A report-whose only unresolved items are external Provider capabilities is a normal unbuilt project. Other-errors identify source or graph wiring to repair.--## Render one element locally--```bash-hypit-reference-video-tools render_element /path/to/project/build.svrun \- --element <id> --segment <id>|--selection <id>|--tokens <from:to> \- --out <path>.mp4-```--The command realizes the Run with local preview media, renders once, and cuts the requested window.-It never writes mock Candidates into Author Source and never reaches a paid Provider. A batch file can-request several windows from the same realization.--`--element` is the bare Source element id. The window is named in Script terms, never by copying a-reference timestamp. The returned sidecar records estimate timing.--Use `layout_check` when actual browser geometry matters. Its overflow, overlap and offset candidates-are advisory measurements. Fix confirmed problems or annotate intentional geometry with-`layout_accept`; do not treat the report as an approval condition.--## Open the complete preview--The preview realizer returns the exact `previewRun` path. Open that path rather than reconstructing a-directory name:--```bash-hypit-studio --run <previewRun> --runtime hypit.runtime.json-```--Use the standalone Studio launcher. Reuse an existing process for the same Run and startup parameters;-stop it before changing those parameters. Report the exact URL printed after Studio starts.--Studio is for a person to inspect. Automated comparison uses `render_element` plus-`compare_reconstruction` or `review_element`.--`<distribution-root>/docs/quickstart/preview.md` is authoritative for Studio behavior.diff --git a/skills/hypit/references/quickstart.md b/skills/hypit/references/quickstart.mddeleted file mode 100644index 16f426b6..00000000--- a/skills/hypit/references/quickstart.md+++ /dev/null@@ -1,28 +0,0 @@-# Quickstart map--The selected Distribution's published docs and installed package declarations are authoritative.-`<distribution-root>` is the root reported by the selected launcher; it is not the installed Skill-directory and it is not the author project:--| Need | Read |-|---|---|-| Script semantics | `<distribution-root>/docs/quickstart/script.md` |-| SVS Recipes | `<distribution-root>/docs/quickstart/styles.md` |-| Media and generation | `<distribution-root>/docs/quickstart/generation.md` |-| Timing and SemanticTrack assembly | `<distribution-root>/docs/quickstart/timing.md` |-| Caption, Media, Text and Audio Tracks | `<distribution-root>/docs/quickstart/tracks.md` and package READMEs |-| Film and rendering | `<distribution-root>/docs/quickstart/composition.md` |-| Run, Runtime, Build, Result and reuse | `<distribution-root>/docs/quickstart/run.md` and `runtime.md` |--Canonical path:--`Script → hypit measure → literal durations on generated or supplied media → normalization → SemanticTake → speech:Track → peer visual/audio Tracks → Film → render:Video`.--Preview uses the same Graph with local mock media and estimate timing. It never edits Author Source and-never submits paid generation.--Use explicit imports, exact fonts, Canvas/Frames, SemanticTrack, Targets and Runtime authority. Reuse-is explicit through a named Result output referenced by `build-record` and `satisfy`.--Inspect the files and current Result directly after interruption. There is no route cursor to recover.-Do not submit a second paid Build when the needed Result already exists.diff --git a/skills/hypit/references/reconstruction/comparison-round.md b/skills/hypit/references/reconstruction/comparison-round.mddeleted file mode 100644index 06c7d5c5..00000000--- a/skills/hypit/references/reconstruction/comparison-round.md+++ /dev/null@@ -1,207 +0,0 @@-# Comparing what was built against the reference--Completed comparisons are ordinary content in `comparisons.jsonl`. After an interruption, inspect-that log and the current render directly. Do not repeat paid generation; make another local comparison-only when the current task calls for a new observation.--**Read `../element-review.md` first.** It owns the round this file sits inside: one element at a time,-render what the Source configures, realize preview mocks for what a Build has not made, one round, two attempt ceilings,-measure rather than guess, and the rule that the reader is not the builder. Everything below is what a-reference adds to that.--What it adds is a second picture. The round asks what differs between the reference and the render-rather than whether the render is what it was asked to be, and `compare_reconstruction` is how that-question is put.--## The reference side is finished--The reference video does not change, and its observations are cached. Re-observing at a fixed-temperature of `1.0` buys paraphrase drift and another bill, so never re-run a completed observation-to "check" it. `--reobserve` exists for a shot whose media was rebuilt, not for doubt.--Cached does not mean correct. The authority on the reference side is the picture, not the prose-written about it. `evidence.md` says when an observation is worth doubting and how to settle it: a-narrow `observe_reference --question` over the shot, put to the reference's own observer. That is-cheaper than re-observing the whole shot, and on the `gemini` observer it is how the picture gets-looked at, since opening it yourself is what the blindness rule below forbids.--Everything else happens on the reconstruction side, which changes every time a package, Recipe or-source edge is edited.--## The render uses estimate timing--`render_element` uses `@hypit/preview-mock` with the Source's literal durations. `--reference-id`-is reserved for selecting reference evidence and comparison windows, not for constructing mock tracks.-The comparison still cuts both sides to the same words and refuses a pair whose two halves are different-lengths. Animated elements are assessed against the deterministic estimate clock used by preview. The-container-duration allowance defaults to three frames and may be set explicitly with-`tolerance_frames` (or CLI `--tolerance-frames`) when a known encoder/container boundary requires it;-do not use a large tolerance to hide a wrong estimate or a missing segment.--A `--batch` round inherits the reference along with the Run, and `reconstruction_check`'s output is-the batch file.--The window is still named in words on both sides. A word range and a shot are different divisions of-the same video — one Segment routinely runs across five shots — and what a render and the reference-have in common is the words, which is why the name travels between them rather than a number.--One geometry has to agree before any of it means anything. The reference's own pixel dimensions are-stored under `video` in its `state.json`, and they size nothing here — but their **aspect** has to-match the Canvas's. When it does not, every comparison puts two differently-shaped pictures side by-side and the observer reports proportion differences that belong to the Canvas rather than to the-element. `reconstruction_check` refuses with a `canvas_aspect` entry and a false `passed` until the-Canvas matches the reference's shape.--## Compare the whole stretch, against every stretch the element is drawn over--Compare clips, not chosen frames:--```-hypit-reference-video-tools compare_reconstruction --reference-id <id> \- --run projects/<name>/build.svrun --segment <id>|--selection <id> \- --video <rendered>.mp4 --element <id>-```--The word range is the one the render was drawn over, and the reference is cut from its own analysis-video at the seconds it speaks those words, so the two sides hold the same words for the same length-of time. Each end moves onto a shot boundary when one lies inside its own end word, and the rendered-clip is trimmed by the same seconds, so the pair opens and closes where the picture changes while-still covering exactly the words asked for. An end with no boundary inside its word leaves the pair-part-way through a shot, and the prompt then says how many seconds of it to read as an incomplete-shot and to report no differences from. `--shot-id <id>` compares one cut of the picture as the whole-shot it already is, and refuses a render whose length is not that shot's.--An element that animates in, leaves, and is replaced by another within one static board does not-produce a cut, so a stretch can hold several states and no single frame represents it. Choosing one is-the failure this replaces: a caption system compared against the stretch with the shortest line looks-correct, because one line has nothing to collide with.--Compare it against **every stretch the element is drawn over**, not the clearest one. There is one-round and it comes before any repair, so a stretch left out of it is a stretch nothing will ever say-anything about. A caption Style is the one exception, and `../element-review.md` states it: one-stretch per distinct Style, at its first occurrence.--Where the reference shows a caption behaving differently somewhere, that is a stretch worth its own-comparison; where it shows the same design drawn over different words, it is not.--On the `gemini` observer the whole round is one call. The comparisons arrive from the check, not from-a file written by hand: `reconstruction_check`'s output carries a `comparisons` array — one entry per-stretch still owed, each already holding `run`, `tokens`, `video_path` and `element` — and that-output is the batch file. `plan` names its windows as `tokens`, which is the form the batch takes: two-whole numbers, `[from, to)`, not the `"48:52"` the flag takes (a string is refused rather than read as-its first two characters). Each entry carries its own `run`; only `--reference-id` is inherited from-the flag.--```-hypit-reference-video-tools reconstruction_check projects/<name>/build.svrun --reference-id <id> > round.json-hypit-reference-video-tools compare_reconstruction --reference-id <id> --batch round.json-```--It paces the requests itself, keeps each comparison's derived cuts apart, and returns them under-`comparisons`. One that fails arrives under `failures` beside the input that produced it and takes-only itself down. Do not write a shell script to fan these out: the pacing, the per-comparison result-and the isolation are what the batch is for, and a hand-rolled loop has none of them.--`--image` is available when the reference's own `visual:` observation states in words that the-element is completely still. It is also the deterministic fallback for an observer-rejected short-window: if a token range contains only one word or its derived stretch is under one second, do not-retry the clip. Render a still for that exact range and compare it with the same `--tokens` range:--```bash-hypit-reference-video-tools render_element <run> --element <id> --tokens <from:to> --out <still>.png-hypit-reference-video-tools compare_reconstruction --reference-id <id> --run <run> \- --tokens <from:to> --image <still>.png --element <id>-```--This fallback compares the visible state at the range midpoint and does not claim anything about-motion. The judgement for a normal window still comes from the reference observation, never from-looking at your own render and deciding that it does not move. If a longer clip returns-`INVALID_ARGUMENT`, record the complete error and treat it as a comparison/provider defect rather than-silently switching evidence modes.--Pass `--element <id>` every time so the comparison record names the element it assessed.--## One observer reads the reference, and it is the one the reference was prepared with--`compare_reconstruction` is how the reference frame is looked at, and `observers.md` says who looks.-The reference has one observer for its whole life, and the comparison goes through the same one that-wrote its observations.--**On the `gemini` observer, that observer is not you.** The command sends the reference clip and the-rendered clip as an unlabelled pair and returns the differences in words. Do not open the reference-yourself and look at it before the blind answer is recorded. After the answer is recorded, you may-inspect frames from your own render to diagnose an implementation defect; never inspect the reference-through that debugging path. A second observer is a second opinion paid for with the very bias it-claims to correct: it sees the reconstruction, knows what was built, and confirms what it expects.-This is why a font that is wrong is caught — the comparison names it, and the package is repaired,-rather than a font being chosen because it resembles what you remember.--**On the `agent` observer the command returns two pictures and the question instead of an answer.**-That observer reads pictures rather than video, so a clip comparison arrives as two frame tiles, both-built against the compared stretch's own duration, so the two grids sample at the same rate and the-same layout. What is compared is the same stretch either way, and `../element-review.md` says who-reads them: one subagent per comparison, dispatched together, and never you.--## Comparison is blind--- Never tell the observer which picture is the reconstruction, what was built, which component drew- it, or what you expect to be wrong. An observer told what to confirm will confirm it.-- `--question` carries what to look at, never what to conclude. Three things qualify: which region to- read, which regions to skip because they hold a preview mock standing in for a declared-but-unbuilt- generation, and one visible quantity to measure. None of them says which picture is the- reconstruction, what was built, or what you expect to be wrong — and a question that hints at the- answer, rather than naming what to look at, has stopped being scope.--The pair is always sent in one order: **one is the reference, two is the render.** The observer is not-told that and must not be; you need it, because a difference reported "in one" is a difference in the-reference and one "in two" is something to repair.--Only after the blind answer returns, read the frozen component fit. A reported difference that-exactly matches one of its accepted variances is documented rather than repaired. The observer never-receives the package name, fit rationale or variance list.--## Geometry is a first-class comparison--Before comparing colour, typography, or motion, compare the layout hierarchy: Canvas → outer-Frame/background → inner text or element. For every region intended to be vertically centred, report-the content-to-frame Y centre offset and whether it is too high or too low. Do not treat deliberate-left/right bias as a defect. Then report containment separately at each boundary: content-inside outer Frame, outer Frame inside Canvas, naming the edge and approximate overflow when one fails.-Check that the outer Frame has enough width/height for the longest line or mark plus padding, stroke,-shadow, and corner treatment. A box can be centred and still be too small. Treat intentional bleed,-crop, and enter/exit motion as a separate possibility and only call it a defect when the reference-does not show that intention.--Ignore any mark that is clearly platform UI, player chrome, an export-tool or editing-software-watermark/overlay; it is not authored video content and must not become a repair target. If its-provenance is uncertain or it may be an authored design element, keep it as an uncertainty and ask-for confirmation rather than silently discarding it.--The settled `../layout-checks.md` report supplies realized stable-state measurements alongside the-comparison. They are deterministic evidence, not a decision. Confirm each candidate against the-reference and rendered clip; do not treat it as an automatic failure or a command to remove intentional-overlap, crop, bleed, optical offset or enter/exit motion.--## Measuring, on this route--`../element-review.md` says to ask for a number rather than spend an attempt. Here that question is-`compare_reconstruction --question "how tall is the oval relative to the frame?"`, which returns a-measurement in one step, from whichever observer the reference holds.--## The reference has nothing further to say after the round--It already showed every stretch, and a second look re-reads the same frames to check your own work.-That spends the expensive half of the route — the renders and the observer — on verifying a repair-rather than on learning anything about the reference.--So **a repair is not verified here**, and the honest place to say so is the report. Passing-`preview_check` is the precondition for the round, not a result of it. The one thing-that is not bounded by the round is settling disagreeing evidence: a narrow-`observe_reference --question` does that at any point, which is what `evidence.md` is for.--`../element-review.md` lists what a pre-Build round leaves unsettled, and that list is what the-completion report carries.--If the author wants the result to differ from the reference — their presenter, their product, their-brand — read the sources you wrote and change them to what they asked for. `route.md` says why that-happens here rather than earlier.diff --git a/skills/hypit/references/reconstruction/continuity.md b/skills/hypit/references/reconstruction/continuity.mddeleted file mode 100644index cc5c3011..00000000--- a/skills/hypit/references/reconstruction/continuity.md+++ /dev/null@@ -1,71 +0,0 @@-# Reference-video continuity rules--These invariants override superficial layer order and shot boundaries:--- Whoever is speaking owns base. The lowest, largest or currently visible picture does not decide- base.-- Picture ownership and sound ownership are independent. Full-screen B-roll may cover the picture- while the prior speaker remains base and owns the continuing sound.-- A person in silent B-roll cannot become speaker or base merely because their mouth appears to- move.-- A shot with no visible person can carry continuing off-screen speech. Do not clear sound or base.-- For alternating, overlapping or simultaneous speech, use audio evidence rather than visible-person- presence. The `agent` observer has no audio evidence and reads these from the frames and the word- timings instead, which `observers.md` describes: the transcript is what decides whether anyone is- speaking at all, so it is what keeps a moving mouth in B-roll from becoming a speaker.-- The same evidence decides which picture is the Segment's base: whichever one shows a person saying- the words the transcript carries there, however small it is and whatever is on screen over it. A- full-frame board with the speaker inset in a corner is a base the size of the corner, covered by- most of a board. `../playbooks/craft/generated-dependencies.md` holds the rule and what follows- from it for stack order.-- One overlay that continues across a cut remains one visual track spanning its full observed- lifetime. Do not recreate it once per shot.-- Merge two or three incorrectly split clips only when continuity evidence confirms one camera shot- and the combined duration stays inside the duration ceiling of the model that will generate it. Past- that ceiling, preserve the continuous-group relationship without creating an overlong shot.-- Reuse whole-reference people, voice and product evidence. Describe the promoted product once and- do not replace it with conflicting per-shot descriptions.--Shot boundaries are observation windows, not authoring units. Never generate independent SVML per-shot and concatenate it afterward.--## Their seconds are not authoring units either--The shot list arrives as a table of `start_seconds` and `end_seconds`, and copying those numbers into-the Source as `start="3.25s" end="7.42s"` is the shortest path from the evidence to a placement. It-produces a reconstruction that is wrong the moment it is built.--Those seconds describe the reference's own clock, and nothing in the reconstruction runs on that-clock. `../script-time.md` says what to bind to instead, and why an Item bound to 3.25 seconds points-at whichever word happens to land there. The reference's seconds then decide *which words* a Selection-spans, which is what they can honestly tell you, rather than which frame an Item starts on.--## A system that spans shots is authored once--`../script-time.md` states the rule: one Program, one Track, one shared Style over the system's full-lifetime, and a scoped variation rather than a second Style. A new shot is never itself evidence of a-change in appearance.--The reference supplies the lifetimes. The `persistent_systems` observation from `prepare_reference`-is an inventory and a first lifetime hypothesis for the whole reference, including whether each one's-appearance appears to change. Do not treat its position, exact visible intervals or continuity as-settled geometry: confirm those claims with the relevant shot-level visual observations or an-exactly-one-shot narrow question. When the whole-reference inventory conflicts with a shot-specific-observation, preserve the conflict and use the more specific shot evidence for the reconstruction.--## Base pictures and designed fields--What may be a base picture at all, when a full screen is one graphic composition rather than a-generated base plus an overlay, and where a missing picture comes from, are decided by-`../playbooks/craft/graphic-compositions.md`. Read it; the rules there are not restated here and are-not weakened by any observation, package convenience or check result.--Each shot's `visual` observation states explicitly whether the frame is a depicted scene or a flat-designed field, describes each framed element's inner picture separately from its frame, and says-whether the picture moves. Those answers are the evidence for this decision and for how a stretch too-short to be a take is reconstructed.--The whole-reference `places` observation says how many locations there are, which camera positions-appear in each, and which parts of the video use each one — the grouping that-`../playbooks/craft/generated-dependencies.md` turns into one accepted image per position. Do not-infer that grouping by comparing per-shot prose.diff --git a/skills/hypit/references/reconstruction/evidence.md b/skills/hypit/references/reconstruction/evidence.mddeleted file mode 100644index 1799bc0c..00000000--- a/skills/hypit/references/reconstruction/evidence.md+++ /dev/null@@ -1,174 +0,0 @@-# Reference evidence--What the reference commands produce, what they refuse, and how to read what comes back.-`route.md` says at which step each one runs.--`@hypit/reference-video-tools` ships seven CLI subcommands. Four carry the reference evidence:--```bash-hypit-reference-video-tools prepare_reference --video-path <path> --observer gemini|agent-hypit-reference-video-tools observe_reference --reference-id <reference-id>-hypit-reference-video-tools record_observation --reference-id <reference-id> --key <key> --text-file <path>-hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id <shot-id> --video <path>|--image <path> [--question <scope>] [--element <id>]-```--`record_observation` is how the `agent` observer returns an answer; on the `gemini` observer the tool-writes its own and the command is unused. A long answer arrives whole with `--text-file <path>`;-`--text <text>` suits a short one. `render_element` delegates mock generation to `@hypit/preview-mock`;-`comparison-round.md` says when. `list_svml_packages` and `inspect_svml_vocabulary` read installed-vocabulary and have nothing to do with a reference video — `../vocabulary.md` documents them.--Use the canonical observation envelopes when consuming results: `prepare_reference` exposes the four-whole-reference observations under `observations.people_and_product`, `observations.voices`,-`observations.persistent_systems` and `observations.places`; a narrow single or batch answer is under-`result` and has the shape `{ status, text }`. The older direct fields and `answer` alias remain only-for compatibility. Do not mix `.text`, `.answer.text` and `.result.text` as competing conventions.--A reference is found from the Distribution rather than from where you are standing, so these commands-may be run from anywhere. `--package-root` only affects project package discovery when a project has-no `package.json` of its own; it never changes the reference-state location. `paths` reports both-roots and every prepared reference.--Defaults are sufficient for normal use. Each also accepts `--input <json>`.--## prepare_reference--It deterministically prepares clips, representative frames, tail frames, audio tails, storyboard-context and a word-level transcript, then obtains four whole-reference observations.-`people_and_product` and `voices` cover who recurs. `persistent_systems` covers the on-screen text-and graphic systems that continue or recur across the whole video, each one's lifetime, and whether-its appearance ever changes. `places` covers how many locations the video was shot in, which camera-positions appear in each, which parts of the video use each one, and each position described in-enough detail to draw from the words alone — which is what reconstructing a location depends on,-since reference frames are never fed to generation.--`transcript` is the verbatim speech of the whole reference with a start and an end for every single-word, measured locally by WhisperX. It is not an observation: no model wrote it, nothing about it-reaches an observer, and it does not go in the observation cache. It is identical on both observers,-and on the `agent` observer it is the only exact record of the sound. Read it whenever a decision-depends on when a word is said — placing an on-screen text reveal against the line that triggers it,-timing a caption, checking that a voice observation matches what was spoken, or judging a Segment's-natural boundary. It does not set a take's duration: the take is generated and its length is the-literal the author measured with `hypit measure`, as `../script-time.md` requires. Do not run WhisperX by hand and do not ask a model-to transcribe.--`transcript` reports `status`, `transcript_ref` and `word_count`. Read the words from-`transcript_ref`, a JSON file of passages, each with its own `words` array of-`{ text, start_seconds, end_seconds, score }`. A machine with no WhisperX service running reports-`status: "unavailable"` with a `reason`. Under the Skill's hard environment gate, do not continue from-that result: run `hypit runtime up` for the project's selected Profile, confirm the service health, and-prepare the reference again only after it reports ready. `../host-setup.md` covers diagnosing that-service when starting it is not enough.--When a completed preparation stage must be rerun, use one small `--redo` value:--```bash-hypit-reference-video-tools prepare_reference --video-path <path> --redo people-```--`--redo media` rebuilds shot media and clears every derived observation. `--redo transcript`-re-extracts the speech audio and measures the words again. `--redo people`, `--redo voices`,-`--redo systems` and `--redo places` rerun one whole-reference stage. `--redo all` reruns everything,-and is what changes a prepared reference's observer.--## observe_reference--Omit shot IDs to process all unfinished work; supply `--shot-id` one or more times to work on-selected shots. Each shot produces three observations:--- `visual` — the base picture, covering and non-covering content, continuity from the preceding shot,- whether the frame is a depicted scene or a flat designed field, and each framed element's inner- picture described separately from its frame;-- `text_appearance` — the typeface character, weight, size, spacing, alignment, colour, stroke,- shadow, glow, per-word emphasis, position and entry of text drawn over the picture;-- `audio` — who is speaking, and what continues from the previous shot.--The picture observation also says whether the picture moves and how, separating camera movement from-movement inside the frame. A held still and a moving shot are reconstructed differently.--Covering content is whatever changes what reaches the eye, including things that sit on top with an-edge and things that do not. A wash laid over the whole frame to darken it is covering content and-gets reported as such; so is anything else the observation describes in terms of the picture being-altered rather than something being added. Read it for what it says rather than matching it against-the kinds of element you already expect — the observation is the evidence, and the moment a category-is treated as a list of known items it stops being able to report the one thing nobody thought to-list.--Each cut produces one `continuity` observation answering both questions under their own headings —-whether the two shots are one continuous camera shot, and whether an overlay continues across the-boundary — and a window of three consecutive shots gets a three-shot continuity review when a-boundary observation reports continuity or uncertainty, or when `--reobserve` was passed. The-preceding tail frame, audio tail and full-reference evidence are attached automatically; do not-reconstruct that context by hand.--A shot is never shorter than a second. Fragments below that are not shots, and clips that short are-rejected by the model, so the detector merges them into the shot before them.--Completed observations are reused. Naming a shot does not re-run it. `--reobserve` re-runs a-completed observation without rebuilding its media, and it exists for rebuilt media rather than for-doubt. `--redo media` clears every observation as a side effect of rebuilding the shots, so the next-`observe_reference` runs all of them again.--`unresolved` lists the keys of observations that failed outright. It is not a judgement about-evidence quality: a complete observation that says "unclear" is still complete, and that is what a-narrow question is for. On the `agent` observer the same field means a question still outstanding.--## A complete observation can still be wrong--An observation is prose written once, at a fixed temperature, by a model that saw the shot and-nothing else. It comes back complete and confident whether or not it is right. On a twenty-shot-reference, four shots came back wrong: two described a picture belonging to a different shot, and two-reported letters being *deleted* from the screen where the text was only typing in.--The frames are on disk at `.hypit/reference-video-tools/<reference-id>/shots/NNN-representative.jpg`,-and the shot clips beside them. When evidence disagrees — one shot against the next, a shot against a-whole-reference pass, or an observation against what the video plainly is — settle it with a narrow-question over that shot, which puts the question to the reference's own observer. On the `gemini`-observer that means you do not open the frame yourself; `comparison-round.md` says which rule-binds on which path.--Be most suspicious of anything an observation asserts about change over time — something appearing,-vanishing, being removed, being drawn in a single frame. A describer working from one pass infers-those rather than seeing them, and infers them wrongly. A narrow question over the stretch is how-such a claim is checked. A `compare_reconstruction` against a quick rendered probe works too, and is-a probe rather than the element comparison `comparison-round.md` runs — that one is rendered from-the Source's own values and is credited with `--element`.--## Narrow questions--`--question` is a separate path. It requires exactly one `--shot-id` and answers only that question-from that shot's clip and frames. Keeping a measurement on one shot prevents descriptions from-mixing different layouts or time ranges. Cross-shot continuity is handled by the built-in boundary-and three-shot window observations, not by a narrow question. Its answer is cached like any other,-under a key naming the shot and the question itself, so asking the same question again returns what-was already answered and reports `reused`. `--reobserve` is what asks again. A different question-over the same shot gets its own key:--```bash-hypit-reference-video-tools observe_reference --reference-id <id> --shot-id shot-007 \- --question "How thick is the outline on the caption words, relative to the stroke width of the letters?"-```--Several at once is `--batch <questions.json>`, an array of `{shot_ids, question}` where every-`shot_ids` array contains exactly one id. Ask about visible attributes. Never ask which component to-use. Do not re-observe the full shot to correct one: that is paid, and at temperature `1.0` it returns-a paraphrase rather than a correction.--The whole-reference `persistent_systems` pass is an inventory and a lifetime hypothesis, not a settled-measurement. Confirm geometry, exact start/end frames and intermittent gaps with shot-level evidence or-an exactly-one-shot narrow question. If they conflict, preserve both statements with provenance and use-the more specific shot evidence; never silently rewrite the original whole-reference observation.--## Boundaries--An observation is natural language and nothing else. Never send an observer SVML syntax, package-declarations, vocabulary, previews or implementation code. Never ask for SVML, SVS, SVRun, a-structured reference plan, component names or TypeScript in an observation. Never state what you-built or what you expect to be found. An observation is evidence rather than the final decision-maker — which is a rule about what an observation may contain, so it binds when you are the one-writing it.--Inspect every failed or unresolved result. Follow up with one narrow question over one relevant shot-rather than repeating the entire analysis. Preserve successful cached observations-unless the selected shot or preparation stage must be refreshed. Do not pass model, concurrency,-rate-limit or temperature settings; on the `gemini` observer temperature is fixed at `1.0`.diff --git a/skills/hypit/references/reconstruction/final-sources.md b/skills/hypit/references/reconstruction/final-sources.mddeleted file mode 100644index 0d0cc5c3..00000000--- a/skills/hypit/references/reconstruction/final-sources.md+++ /dev/null@@ -1,56 +0,0 @@-# Reference-video final sources--After every required package exists and its vocabulary has been read, read-`../authoring.md` completely, then read `../playbooks/index.md` and the craft files it names for the-systems this reference actually contains, and write one complete project:--- `main.svml` describes the whole video in original time order, keeps continuing base/sound intact,- and represents one continuing overlay as one visual track.-- `recipes.svs` contains every Recipe actually referenced by `main.svml`, using only declared- properties and admitted values.-- `build.svrun` references the Author Source and declares the required Targets with resolvable- 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 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 unresolved-semantic evidence; return to a narrow `observe_reference` question when necessary.--## Where the Segments fall, and how long each take runs--`../script-time.md` decides both, and it decides them the same way for any program: a Segment is a-stretch that is spoken as one, the seam goes at a sentence end, and each take's duration is the-literal the author measured with `hypit measure`, not a value read from any clock.--The reference adds one thing to that, and it is a warning rather than a rule. The generated speech-plays at its own pace, not the reference's: its measured word timings describe how the original-speaker delivered the line, the reconstruction re-speaks it, and the generated take will not match-that recording second for second. Reading the reference's span onto the take fixes a length that has-nothing to do with how the generator speaks.--The estimate is also what lets a reconstruction survive the author changing the lines at the end of the route,-where a literal read off the old reference would not.--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 check is bounded by the-round's two-attempt ceiling: a graph that does not trace is not a difference to weigh, it is work that-is not done.--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 staying sound **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 all-three files are accepted. Do not create `check_svml_project` or another wrapper.--Accepted checks end the structural work, not the reconstruction. Every element you authored still has-to be rendered and compared against the reference under `comparison-round.md`, and that work ends-on `reconstruction_check` (`route.md` holds the command), which refuses to pass while any drawing-element has never been compared. It needs a prepared reference; when several are prepared it takes-`--reference-id <id>`.diff --git a/skills/hypit/references/reconstruction/observers.md b/skills/hypit/references/reconstruction/observers.mddeleted file mode 100644index 753fb27d..00000000--- a/skills/hypit/references/reconstruction/observers.md+++ /dev/null@@ -1,195 +0,0 @@-# Who reads the reference--Two observers can read a reference video. Gemini is the default and strongly recommended path; use the-calling agent only when the author explicitly requests it after environment setup. The choice is made-once per reference and recorded in its state.--Everything after the evidence is the same on both paths. The observation keys are the same, the-prompts are the same, the cache is the same file, and every file this route links reads the result-without knowing which observer produced it.--## The two--**`gemini`** uploads the shot clips and the whole reference to the Gemini Endpoint the selected Runtime-Profile binds (HypiHub by default; Vertex only when the author's Profile binds it). It sees motion as-motion and hears the sound. Each observation is a paid request; do not silently fall back-to `agent` because a credential is missing.--**`agent`** hands the observations to you. It needs no credentials and reaches no Provider: the CLI-prepares the same media, then returns each observation as a task carrying its prompt and the pictures-to answer it from. You look, you answer, you record the answer, and the result assembles exactly as-the other path's does. This technical property does not waive the reconstruction credential gate:-the author must first settle on HypiHub OAuth or an author-owned provider credential, and the Agent-must never select `agent` merely because no credential was found.--## Choosing--Before `prepare_reference`, inspect the selected Runtime Profile and report what this machine actually-holds. Credential setup should already be complete from `../environment.md`; if it is not, return to that-gate and complete HypiHub OAuth (or the explicitly requested author-owned key) before proceeding:--```text-node <skill-root>/scripts/check-credentials.mjs GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON-```--HypiHub OAuth configured means `gemini` is available through HypiHub. If the author explicitly selected-Vertex, both Google variables must be set. If neither selected backend is available, stop and return to-environment setup; never use `agent` as a credential bypass.-`../credentials.md` says what each variable is.--Say that `agent` reads the reference a little less closely — a shot arrives as sampled frames rather-than continuous video, so continuity across it is read rather than watched, and there is no sound, so-a voice is attributed rather than heard. The reconstruction it produces is a working one. Say it once,-take the answer, and run.--## Say which path is running--Once the observer is selected, tell the author which observer is reading the reference before the-evidence starts. Gemini is the default and recommended path; mention an explicit `agent` selection only-when the author requested it.--The author reads the observations, the sources and eventually the video. Which observer produced the-evidence changes what those are worth, and it is not visible in any of them.--This is the one question this route asks about how it runs. Everything else it decides:-`route.md` still owns the working directory, the project location, the vocabulary and the generators.--## The protocol is one loop--The tool asks, you answer, you record, you ask again. It ends when the tool asks for nothing.--```text-hypit-reference-video-tools prepare_reference --video-path <path> --observer agent-hypit-reference-video-tools observe_reference --reference-id <id>-hypit-reference-video-tools record_observation --reference-id <id> --key <key> --text-file <path>-```--The first two return `pending_observations`: tasks, each with its `key`, its `instruction`, its-`prompt` and the `image_refs` to read. `--text-file` is how a long answer arrives whole; `--text`-suits a short one.--Everything else about running this observer follows from one fact — **the answer comes back out of-band, so the tool cannot ask and be answered inside one call.** What follows is that fact seen from-four sides, not four rules to remember separately:--- **`pending` is a task handed out, not an answer received.** It is never cached, so an observation you- have not answered is asked again rather than read as finished. `unresolved` lists it, and here that- is a question outstanding rather than a question that failed.-- **The tool only hands out a task whose inputs exist.** The four whole-reference observations are- quoted into every shot's question, so `observe_reference` refuses the sweep until they are recorded,- and names the ones it is waiting for. A narrow `--question` is exempt, being a follow-up rather than- the sweep.-- **A task whose input is another answer appears on a later pass.** The three-shot continuity review is- decided from what the boundary observations say, so it cannot be handed out by the pass that asks for- them. It appears on the next one and is complete on the one after.-- **Empty `pending_observations` ends the sweep**, and empty `unresolved` says the same from the other- side. Answering everything one call listed is not the end of it.--The observer that answers in band walks all of this inside a single call, which is why the loop is easy-to leave out. Leaving it out stops before the three-shot review exists: `continuity.md` then has no-evidence for whether three clips are one continuous camera shot, and a stretch the reference plays-unbroken is authored as three, with two seams it does not have.--`--redo all --observer <other>` is how a reference changes observer, and it re-prepares everything,-because the observations it holds were read from the other kind of evidence.--## What the `agent` observer reads--Each shot arrives as one picture: its frames sampled evenly across its duration and tiled in reading-order, left to right then top to bottom. Read the grid as time passing. A task that carries a single-picture carries one moment. The number of frames follows the shot's length, from four for a short one-to nine for a long one, so a cell stays wide enough to read detail in.--A whole-reference task carries the storyboard — every shot's representative frame in one picture, for-reading the video at a glance — followed by every shot's tile, so the question sees every frame the-shot observations see. On a long reference that is a lot of pictures, and it is the whole evidence:-answer from all of them rather than from the storyboard alone, which shows one moment per shot and-therefore answers neither what moves nor what recurs.--## How sound is answered on the `agent` observer--You cannot hear the reference, and there is no second source of sound to fall back to, so the sound-observations are answered from the two things you do have. Answer them fully; do not leave them short-and do not put the gap to the author.--- **The transcript says when.** WhisperX measures every word locally on both paths, so the words and- their timings are exact whichever observer reads the pictures. That settles whether anyone is- speaking at a given moment, and where a word sits. It does not set a take's duration: the take is- generated and its length is the literal the author measured, as `../script-time.md` requires.-- **The pictures say who.** Attribute speech to the person the frames show speaking during the words- the transcript places there. A task that needs sound says so in its own prompt and asks for exactly- this reading.-- **The two together are the evidence.** `continuity.md` asks for audio evidence over visible-person- presence because a mouth moving in silent B-roll misleads. On this observer the transcript is what- keeps that from happening: a person whose mouth moves during a stretch the transcript places no- words in is not the speaker, however much they look like one.--`voices` and the sound half of each `boundary` are the observations this shapes. They are attributions-read off pictures and word timings, and that is what a later reader should take them for.--## Each task is answered in its own subagent--Every task is self-contained, and no task refers to another task's answer. **Where the harness can-spawn subagents — Claude Code and Codex can, and some cannot — one subagent per task is required, and-a pass runs them together.** `../element-review.md` states the rule and why it is not a preference;-this is what it means for a reference observation.--Hand the subagent the `instruction`, the `prompt` verbatim, the `image_refs`, and `transcript_ref` and-`transcript_words` when the task carries them — and nothing else. Not what you built, not which-component drew anything, not what you expect it to find, and not another observation's answer. Take-the returned text and record it yourself, so one writer owns the cache.--**Do not open the pictures yourself.** That is the whole point: the observer that uploads is a-separate request and cannot be you, and one task per subagent is what makes this path equal to it-rather than merely faster.--Two things follow from one task per subagent, and both of them are properties the `gemini` observer-has for free:--- **The observations are independent again.** Each one is answered by a reader that saw only its own- pictures and its own question, which is what a separate request to Gemini is. Two observations- agreeing is evidence again rather than one reader being consistent with itself.-- **The comparison closes blind.** A subagent handed two unlabelled images and the comparison question- does not know which is the reference, what was built or what you hoped to see. That is the same- unlabelled pair the other observer gets.--Answer the tasks in order yourself only where the harness has no subagents. It is slower, it is the-fallback rather than the shape to aim for, and the discipline below stands in for the blindness it-cannot have.--The comparison round arrives here in batches. One element is compared against every stretch it is drawn-over before any repair, and `comparison-round.md` has the renders all made before the first-comparison is sent, so they arrive together. Each is self-contained in the same way an observation-task is: no comparison's question depends on another's answer.--Dispatch one subagent per comparison and run them together. Where there are no subagents, answer them-one after another rather than folding them into a single look — what the round is for is the set of-differences across stretches, and one answered in the light of the previous answer stops being-independent evidence of anything.--A clip comparison reaches this observer as two frame tiles — the reference's own cut, and one built-from the render against the same duration, both drawn at the same cell width. Read them as a pair of-grids sampling the same stretch at the same rate.--`comparison-round.md` states the order the pair is sent in and why the observer is not told it. Read-the answer with that in hand.--### Record the differences against the comparison that asked for them--`compare_reconstruction` returns a `comparison_id`, and the answer goes back under it:--```bash-hypit-reference-video-tools record_observation --reference-id <id> \- --key comparison:<comparison_id> --text-file <the differences>-```--Until that lands, the comparison is a pair that was drawn, cut and handed over with nobody having said-what it shows, and `reconstruction_check` lists it under `awaiting_answer` and credits the element-nothing. The differences are what the round is for, so record every one — including the ones that read-as equivalent, in the words the observer used.--## Comparing without subagents--Answering the comparison yourself makes the report yours, and you know what you built.-`../element-review.md` states the declaration-change rule that selects comparisons, and it applies-here unchanged. What a subagent adds, and they cannot, is that the comparer is not the builder.diff --git a/skills/hypit/references/reconstruction/route.md b/skills/hypit/references/reconstruction/route.mddeleted file mode 100644index d0c1f937..00000000--- a/skills/hypit/references/reconstruction/route.md+++ /dev/null@@ -1,99 +0,0 @@-# Reference-video reconstruction--Use this workflow whenever a video file or link is the thing to reproduce, including an initial-presenter/product/brand adaptation requested together with the reference.--The reference is the sole design evidence for this route. Do not inspect Distribution example-projects, borrow another author project's files or packages, or wire the supplied reference itself-into a Film, Track, Take or final output. Every visible shot must be newly authored or explicitly-supplied by the author as replacement material.--## 1. Prepare and observe the reference--Read `../environment.md`, `../credentials.md` and `observers.md`. Ask once whether Gemini or the calling-agent should read the reference, then run:--```bash-hypit-reference-video-tools prepare_reference --video-path <path-or-link> --observer <gemini|agent>-hypit-reference-video-tools observe_reference --reference-id <reference-id>-```--For the agent observer, answer every returned task with `record_observation`. Prepared clips, frames,-storyboard, transcript and observations are the actual working material under-`.hypit/reference-video-tools/`; no route snapshot is created around them.--Read `evidence.md`, `continuity.md` and the relevant production craft. Separate:--- the base scene from covering overlays;-- an inset frame from the picture moving inside it;-- camera motion from motion inside the scene;-- persistent systems from one-off elements;-- spoken timing from visual shot boundaries.--## 2. Choose packages and author the faithful base--Inspect installed vocabulary instead of guessing:--```bash-hypit-reference-video-tools list_svml_packages-hypit-reference-video-tools inspect_svml_vocabulary --package <package>-hypit-reference-video-tools inspect_visual_schema-```--Read `vocabulary.md` and `final-sources.md`. Reuse public Surfaces when they fit. Use-`../local-author-package.md` only for a genuine missing capability. Never copy or edit an installed-package.--Write the faithful base before applying an initial requested presenter/product/brand substitution.-Short caption Cues use `||`, normally every 3–4 spoken words. Preserve shot coverage, overlay-continuity, picture-within-picture geometry and generated dependency ordering in Source/Recipe/Run.--## 3. Inspect the authored program--Run the direct reports that answer the current question:--```bash-hypit-reference-video-tools validate_local_author_packages --run ./build.svrun-hypit-reference-video-tools validate_script_cues --run ./build.svrun-hypit check ./build.svrun-hypit-reference-video-tools preview_check ./build.svrun-hypit-reference-video-tools layout_check --run ./build.svrun-```--These are independent reports. Layout output is advisory; repair a real issue or annotate intentional-geometry with `layout_accept` and a reason.--## 4. Compare actual visual elements--Read `comparison-round.md`. Render one named element over a Script window, then compare the render to-the corresponding reference stretch:--```bash-hypit-reference-video-tools render_element ./build.svrun \- --element <id> --segment <segment> --reference-id <reference-id> \- --out ./review/<element>.mp4-hypit-reference-video-tools compare_reconstruction \- --reference-id <reference-id> --run ./build.svrun --segment <segment> \- --video ./review/<element>.mp4 --element <id>-```--Use a still only when both sides are actually still. For an out-of-band agent observation, close the-returned comparison id with `record_observation`. Each explicit comparison is new; no file digest-silently replaces it with an older answer.--Use `reconstruction_check` as a summary of unreviewed elements, coverage and playback concerns. It is-not project state and does not prevent Build submission. Repair differences that matter to the-reference and the requested adaptation, then rerun only the affected inspection or comparison.--## 5. Build and deliver--Read `../runtime.md` and `../studio-confirmation.md`. Show the current Run in Studio and report its-exact URL. Before generation, run `hypit plan`, disclose cost and selected external services, obtain-approval, then run `hypit build` once.--The resulting project-owned Result is what that Build produced. Name important Results/outputs for-human retrieval. A later natural-language change follows `../revision/route.md` and edits Source,-Recipe or Run—not the generated video.--For many variants, copy the accepted project into independent directories and maintain an explicit-task list. Do not create variant state, aggregate completion records or hidden recovery history.diff --git a/skills/hypit/references/reconstruction/vocabulary.md b/skills/hypit/references/reconstruction/vocabulary.mddeleted file mode 100644index 08ffc86b..00000000--- a/skills/hypit/references/reconstruction/vocabulary.md+++ /dev/null@@ -1,46 +0,0 @@-# Reference-video vocabulary decisions--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.--**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.--**An observation's "base picture" is the full-frame underlying footage** — whatever fills the screen-under any overlays. The authoring base that `continuity.md` defines is a separate thing: it is the-picture showing the speaker saying the words, and `continuity.md` decides which picture that is. A shot observed as "the base picture is a classroom" is a full-frame-classroom; where the speaker is cut away to silently in that classroom while their voice continues,-the classroom is B-roll covering the base (see `../playbooks/craft/b-roll.md`), and the base remains-with the speaker. Read the observation for what fills the frame; read `continuity.md` for which-picture owns base.--## Where an appearance value comes from--`../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:--- Each shot's `text_appearance` observation already describes drawn type in those terms. Read it- before asking anything.-- Resolve what remains with a narrow `observe_reference --question` over the one shot where the- element is most legible. Ask about visible attributes, never about components or syntax. A- question costs one request and does not disturb cached observations.-- 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 whole- system, as `continuity.md` requires.--## After the gap is filled--Installing the package is not the end of the gap route. Read `final-sources.md` and write the three-sources, then continue into `comparison-round.md`: a component that loads is not yet a component-that looks like the reference.--The reference-video CLI remains limited to observation, vocabulary inspection and blind image-comparison; it does not generate components. Gemini does not write the package.diff --git a/skills/hypit/references/revision/route.md b/skills/hypit/references/revision/route.mddeleted file mode 100644index 634387d2..00000000--- a/skills/hypit/references/revision/route.md+++ /dev/null@@ -1,29 +0,0 @@-# Revising an existing project--A revision is an edit to the existing Source, Recipe or Run. It is not a new route object and it does-not require reconstruction history. The project directory supplied by the author is the baseline.--1. Read the request and inspect the current `.svml`, `.svs` and `.svrun` files.-2. Inspect `git diff` when the project is versioned so unrelated edits remain untouched.-3. Map the requested change to the smallest authoritative source fields.-4. Edit Source, Recipe or Run. Never edit a generated MP4, PNG, WAV or existing Result in place.-5. Run only the direct reports relevant to the change:-- ```bash- hypit-reference-video-tools validate_local_author_packages --run <run>- hypit-reference-video-tools validate_script_cues --run <run>- hypit check <run>- hypit-reference-video-tools preview_check <run> [<runtime>]- hypit-reference-video-tools layout_check --run <run> [--runtime <runtime>]- ```-- These reports do not form a sequence and do not approve the revision. Use them to find actual- source, graph or layout problems.-6. If the change affects a reviewed visual declaration, render and review that declaration again.- Do not invoke a visual observer when the visible design did not change.-7. If generation inputs changed and the author wants fresh generated media, run `hypit plan`, explain- cost and obtain approval before a new Build. Otherwise reuse the existing Result inputs directly.-8. Show the updated Run in an existing Studio session, or start Studio and report its exact URL.--The completion record is the edited source plus any new Result the author approved. Do not write a-revision id, parent snapshot, progress cursor or duplicate history file.diff --git a/skills/hypit/references/runtime.md b/skills/hypit/references/runtime.mddeleted file mode 100644index ccd9d51f..00000000--- a/skills/hypit/references/runtime.md+++ /dev/null@@ -1,201 +0,0 @@-# Durable Runtime and Build lifecycle--Read `<distribution-root>/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.--Start from the Runtime Profile template in `docs/guide/runtime.md` (the repository does not ship a-canonical `examples/*/hypit.runtime.json`). Bind one Endpoint per capability your Sources actually-reach: the picture and video models, Gemini VLM, 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.--### Disclose the paid Provider before submission--The paid handoff always includes a credential/provider summary before cost approval. Read the selected-Runtime Profile and the preflight result, then tell the author for each paid capability:--- which Provider endpoint will execute it;-- which credential slot and source are active (`KIE_API_KEY`, HypiHub OAuth, Vertex credentials,- `MIMO_API_KEY`, or an OS credential-store entry); and-- whether the key is present and the requested model is reachable.--Never reveal the secret itself. Credentials must have been resolved during environment setup. If any-required credential is missing or insufficient, do not submit the Build; return to environment setup-and complete the default HypiHub OAuth flow, or the author-owned key only when explicitly requested.-Switching Provider should not require any Source change. Continue only after the credential is usable-and the summary has been shown.--### Give the picture and video models room to run--The generation models are what a Build waits on, and they are the one place concurrency is worth-setting deliberately. Give Seedance and the image model room to run. HypiHub is the default paid-gateway, so a typical profile looks like this:--```json-"hypihub.<project>": {- "use": "@hypit/provider-hypihub",- "config": {- "apiKey": { "store": "os", "key": "hypihub.oauth" },- "defaultConcurrency": 20- }-}-```--`defaultConcurrency` is the total HypiHub pool shared by its model capabilities. Tune it to the-quota behind the key; image/video capabilities keep exact-model lanes while Gemini requests share-one conservative lane. Bind every paid capability HypiHub supports to this Endpoint by default,-including MiMo Voice Design and Voice Clone. Select KIE, Vertex, official MiMo or another BYOK Provider only when the-author explicitly asks not to use HypiHub or explicitly selects that Provider.--An Author Source importing `@hypit/gemini` remains Provider-neutral. Bind those capabilities to-`@hypit/provider-hypihub` for HypiHub's upload-backed Gemini endpoint, or to-`@hypit/provider-vertex` for direct Vertex. The reference-video preprocessing observer runs outside a-Build but reads the same Profile binding; there is no separate environment switch.--Provider-specific input limits are also part of preflight. For KIE GPT Image 2, `auto` is 1K-only,-`1:1` is unavailable at 4K, and `4:5` is 1K-only; `4:3` and `3:4` are valid.--The local Providers stay small: `media`, `whisperx` and `hyperframes` are bounded by this machine's-cores rather than by a remote queue, and raising them buys contention.--Set this while writing the Profile. Changing it later needs a Worker restart, and the restart rule-below makes that costly once a Build is in flight.--## Execute the lifecycle--```bash-cd path/to/project-hypit runtime use hypit.runtime.json--hypit plan build.svrun--# Required once after changing Runtime packages, or whenever preflight reports not-ready state.-hypit runtime up--hypit build build.svrun --follow--hypit inspect <build-id>-hypit get <build-id> \- --output final.video --to output/final.mp4-```--Resolve the project before selecting its Runtime. `--workspace` is explicit; otherwise run from the-project directory (or one of its package-bounded descendants). `runtime use` writes one exact-project-local pointer. Never infer a Profile from its filename or let a parent project's selection-stand in for this project's choice.--The paid-build handoff is defined in `studio-confirmation.md`: show the complete preview-mock Run in-Studio and obtain acceptance before `hypit build`; after acceptance, Studio for the accepted Run and-the HyperFrames/final render may start concurrently. The render must not be blocked on the author's-Studio viewing.--Use `check` during authoring. `plan` works without a Runtime as a graph-only operation; with the-project's selected Runtime it performs a cheap, read-only preflight over only unsatisfied Needs and-returns non-zero when that slice is not ready. It never installs, starts or contacts a remote Store.-Every take's duration is a literal in the Source, measured beforehand with `hypit measure`; read it-there when reviewing generated take length or cost. After execution, `hypit inspect <build> --json`-reports the accepted Records. Never probe a mock media file for a duration.--After Runtime package selection changes, run `runtime up`: this is the explicit provisioning-boundary for machine npm dependencies, Managed Programs and the detached Worker. Use `doctor` for-an active full-profile diagnosis and `runtime status` to observe the deployment. `build` repeats the-cheap preflight and fails before durable submission when deployment is not ready; it never installs-or starts a Managed Program. If provisioning is already complete and only the Worker is stopped,-`build` starts that Worker before it submits the Build.--Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from advancing active Builds.-External programs are intentionally independent; stop them only with `programs down`. Saved Build-Results remain in the project Result repository, and neither command cancels remote Provider work.--## Preserve durable semantics--- `runtime up` installs or reuses only the selected upstream npm packages, then starts or reuses the- declared external programs and detached Worker. A direct `build` does no provisioning: after a- clean preflight it submits durably, then ensures the Worker is running. A Worker skips work whose- implementation packages it has not loaded.-- `programs up/status/down` manages external programs only. Do not use it as the normal Build- bootstrap because it does not own the Worker lifecycle.-- A Build continues after durable submission. `--follow` only observes progress; interrupting the- terminal does not stop the Build.-- `status <build-id>` reads one snapshot; `status <build-id> --watch` reattaches an observer until- terminal state without resubmitting or taking execution ownership.-- Every `build` invocation creates a fresh automatic Build id. Source identity never reclaims an- earlier Build; reuse across Builds exists only through explicit Run Source Candidates.-- `inspect` reads one finished Build Result. `get --output <name>` reads or copies one uniquely named- public Output from that Result.-- A running Worker loads an installed Component package when a Build first names it and remembers- every physical package in that dependency closure. A later Build may add another installed- Component package without restarting the Worker; shared dependencies are not registered twice.-- There is no implicit cache or Pin state. Reuse Records through a new `.svrun` containing- `build-record` and `satisfy`; the Candidate supplies the exact nominal Type required by the- current Logical Output.-- **A running Worker holds the package code it loaded.** Edit a project package or update the- Distribution and the Worker that is already up keeps executing the version it started with, so- the next Build- fails exactly as the last one did. Stop it before resubmitting; the next `build` starts a fresh one- that loads the edit:-- ```bash- hypit runtime down- ```-- Read an identical repeat failure as this until you have ruled it out. Reasoning about why a correct- fix did not work is how an afternoon goes, and the fix was never loaded.-- **Prefer stopping an idle Worker.** A changed Runtime Profile or already-loaded package code takes- effect only after restart. Check active work first so an immediate in-process Producer is not- interrupted. Asynchronous Provider Operations are durable and are polled again after restart; the- Worker does not submit them a second time.-- Use the activity view before every restart:-- ```bash- hypit activity # proceed when no active Builds are listed- ```--## Keep the Distribution and every project physically separate--The Distribution reported by `hypit paths --json` is package-manager-owned and replaceable. Never-create an authored project, project-local package, generated asset or Build output inside it. A-project is any independent directory such as `<home>/<name>/`, holding its Sources, assets and-`packages/` directory in its own Git/workspace boundary. Published examples are read-only reference-material, never a place to turn into the author's project.--**Give the project directory its own `package.json`, before the first `check`.** Package discovery-starts at the project and walks up until it finds one; without it the search runs past the project-and settles on whichever directory above happens to have one, leaving every package under the-project's `packages/` unresolvable. A minimal-file is the whole fix, and it is what makes the directory a boundary rather than a place that-happens to hold Sources:--```json-{ "name": "<project-name>", "version": "0.0.0", "private": true, "type": "module" }-```--`hypit paths --json` confirms it: `project` names the project directory rather than something above-it. Passing `--package-root .` on each command papers over the same gap for one command at a time-and leaves the Worker — which resolves packages on its own — still looking in the wrong place.--Studio and the CLI resolve explicit project packages from the project root, then fall back to the-read-only Hypit Distribution. The `@hypit/*` namespace is reserved for the active Distribution and-is resolved there first; project packages use their own scope. This bridge is Host configuration;-it does not add the project to Hypit's contributor workspace or modify the Distribution.--Relative Author Sources and assets stay inside the independently resolved Source Workspace.--- `--workspace` explicitly selects the Source Workspace boundary.-- `--package-root` only changes where the Host locates installed packages. It does not widen Source- access. With a `package.json` at the project root, omit it. Use it when a project has no own- `package.json` or when explicitly selecting another package root; this never changes Source- Workspace resolution.-- Do not symlink an external project into the Distribution. The external directory is the intended- workspace, not an escape from one.diff --git a/skills/hypit/references/script-time.md b/skills/hypit/references/script-time.mddeleted file mode 100644index 0dac5392..00000000--- a/skills/hypit/references/script-time.md+++ /dev/null@@ -1,75 +0,0 @@-# The program runs on the script's words, not on a clock--Every take is generated. It comes back at whatever length the model returned, and the SemanticTrack is-built from the words WhisperX finds inside it. So a number of seconds is never what a program is-authored against: the words are, and everything placed is bound to them.--Both routes reach this file. What differs is only where the temptation to use a clock comes from — a-reference video hands you a table of seconds, and a brief hands you a duration — and the answer is the-same either way.--## Mandatory Cue breaks for readable captions--Whenever a Segment will appear as captions or other spoken on-screen text, author explicit short Cues-with `||` between complete Alignment Units. As the default, cut every roughly 3–4 spoken words (fewer-for long words, large type, or dense designs); permit a longer Cue only when the reference clearly-holds it and the rendered bounds prove it fits. This is a hard layout requirement, not an optional-style preference: a Segment with no `||` becomes one Cue, and the entire long passage can render beyond-the screen. Do not depend on automatic wrapping, a larger box, or a smaller font to fix it. Choose-breaks at natural phrase or sentence boundaries, and never place `||` inside Dual Text or through an-N:M Alignment Unit. A closing `</segment>` is also a hard Cue boundary: Cue counting and timing-restart at the next Segment, so a trailing `||` is not required merely to prevent a Cue crossing-Segments.--`validate_script_cues --run <build.svrun>` reports every Cue over four visible words. Fix the Script-before `hypit check` or preview.--## A Segment is a stretch that is spoken as one--Cut the Script into Segments the way the program is *spoken*, not the way its pictures 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 that is delivered unbroken invents a seam it does not have.--One thing does force a seam. The take that speaks a Segment generates that speech, so a Segment can-be no longer than one generation. Where an unbroken passage runs past what the model will produce in-one take, it becomes two Segments — and then the seam is yours to place rather than the ceiling's.-Put it where the speaker would draw breath: at a sentence end, never mid-clause.--## A take's duration is estimated--Every take is generated, and the generated speech plays at its own pace. So each take's duration is-the author's prediction of how long the generated line will be: measure the Segment with-`hypit measure <source> --segment NAME` before writing the Source, and write the seconds as the-literal `duration` on the take.--Nothing depends on the estimate being exact. Script Selections bind every placed element to the-words, and the SemanticTrack places the words where the generated audio actually has them, so a-take that comes back a little long or short moves the words, not the bindings. When the author-changes the lines, measure again and write the new number; the duration is a decision in the Source,-not a value the graph recomputes.--## Bind covering content to the words, not to a frame--Bind covering content to a Script Selection over the words it covers — mark the range in the Script,-pass `semantic={speech.semantic}` to the Track, and use `during={story.selection.NAME}` — and let the-projection resolve the frames.--An Item bound to 3.25 seconds points at whichever word happens to land there, which is not the word-the number was copied from. One take returning half a second long moves every window after it.--Explicit `start`/`end` is for a program with no speech to anchor to.-`playbooks/craft/b-roll.md` reads that as a deliberate choice rather than a transcription.--## A system that spans pictures is authored once--- A visual system that persists across cuts — captions, a running list that keeps its state, a- progress indicator, a persistent badge or logo, a recurring lower third — is one system: one- Program, one Track and one shared Style over its full lifetime, even when the visible- words, items or values change.-- Do not recreate the system per picture, and do not create a second Style because a new picture- begins. A new picture is never itself evidence of a change in appearance.-- Author a local difference as a scoped variation inside the one system, on exactly the- words, items or interval where it belongs.-- Whether the system is one Program with per-item timing or separate instances is decided by the- declared vocabulary of the chosen package, never by how many pictures there are.diff --git a/skills/hypit/references/studio-confirmation.md b/skills/hypit/references/studio-confirmation.mddeleted file mode 100644index 1079cc12..00000000--- a/skills/hypit/references/studio-confirmation.md+++ /dev/null@@ -1,38 +0,0 @@-# Studio handoff and paid Build--Studio display and paid execution are separate decisions.--## Before a paid Build--1. Read the selected Runtime Profile and preflight. Tell the author which Provider, Endpoint and- credential source will serve each paid capability without revealing secrets.-2. Produce a local preview through `render_element` or `realizePreviewMock` and use the exact- `previewRun` path it returns.-3. Start Studio with that Run and report the exact URL printed by the server.-4. Explain that the preview uses local stand-in media and estimate timing.-5. Run `hypit plan`, state the estimated cost, and wait for explicit approval before `hypit build`.--If the author requests a change, edit Source/Recipe/Run through `revision/route.md`. Studio display is-not permission to spend money.--## After a Build--Inspect the project-owned Result. It identifies the Build and its public outputs, including useful-intermediate component ports. Give important Results and outputs human presentation names.--To view or reuse accepted upstream material, write a separate Run with explicit `build-record` and-`satisfy` declarations. Do not satisfy the final target when Studio needs to trace the current Film-graph; keep the target unresolved and pin only the upstream generated values the preview needs.--Start Studio for that accepted-material Run and report the URL. Rendering and Studio viewing may run-at the same time; neither waits for the other.--## After an edit--Reuse a running Studio process for the same Run and startup parameters so its watcher can reload-Source. If the Run, workspace or port changes, stop the old process before starting another. A visual-edit may be reviewed when useful, but the revision has no hidden completion state and does not require-a new paid Build unless the author asks for regenerated material.--In a contributor checkout, `hypit-studio` means-`node <checkout>/bin/hypit-studio.mjs`; it is a standalone entrypoint, not `hypit studio`.diff --git a/skills/hypit/references/vocabulary.md b/skills/hypit/references/vocabulary.mddeleted file mode 100644index b75c81f0..00000000--- a/skills/hypit/references/vocabulary.md+++ /dev/null@@ -1,153 +0,0 @@-# 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 `hypit-reference-video-tools 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 reads official vocabulary from the installed Distribution-and project packages from the current project, so run it from the project directory.--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.--Both commands print one JSON object to stdout. `list_svml_packages` is an array of-`{ package_name, tags, models }`; `inspect_svml_vocabulary` returns `{ packages, surfaces }` where-each Surface carries `package_name`, `module`, `surface`, `tag`, `mode`, `outputs`, `readme_path` and-`vocabulary` — whose own keys are `summary`, `attributes`, `children`, `example` and `notes`. **The-Recipe properties are inside the `recipe` attribute**, at `vocabulary.attributes[name=recipe].recipe`,-one entry per property; there is no `recipe` key beside `attributes`. A Surface re-exported from-another package carries no `vocabulary` at all — follow its `module` to the one that declares it. Read-the `accepts` lists on attributes: that is the declared Type an element must satisfy, and a property-with nowhere to land in those lists is the finding that makes a gap.--**That output is the complete authoring contract. Author from it, and do not read a package's source-code to learn an element's syntax.** Every recipe property carries its own `summary` and its admitted-`values` — the parameter reference is in the inspect output, not in the package. The README is the-example, and it is not a parameter reference: some READMEs are a single illustrative recipe, and a-thin one is not missing documentation, it is a thin example next to a complete declaration. The-source is implementation, and the loader refuses a mistaken attribute against the declaration, not-against the source — so reading it neither teaches the contract nor matches how the element is-validated.--## Judge component fit before writing Source--List the installed vocabulary, inspect the packages that plausibly own each visual system, and make a-short judgement. This is not a property-by-property score and it is not an exhaustive search through-unrelated packages. The Agent decides whether a candidate is close enough for the job, records why,-and chooses one of three outcomes:--- `reuse-existing`: the package owns the right role and is sufficiently close to what the program- needs;-- `reuse-with-accepted-variance`: it is sufficiently close, but SVS cannot express a few named,- unimportant appearance differences;-- `project-local-package`: the difference materially changes the component's core look, function,- structure or behaviour.--Visual resemblance alone never qualifies a package for reuse. The candidate must also provide the-required function and contract — its input/output Types, timing behavior, ports and role in the-composition. A package that looks similar but performs a different job, exposes incompatible data,-or has a different temporal contract is a `project-local-package`, even when its rendered shape is-close. Do not force the Source through a visually similar tag just to avoid a package gap.--Original authoring does not turn silence into a hidden specification. If the author asks for a-ranking board without defining every icon, shadow or radius, those details remain the Agent's design-space and an installed ranking component normally qualifies as `reuse-existing`. Reconstruction has-a picture to compare against, but a package that clearly represents the same visual system may still-qualify with a few low-impact skin differences recorded as accepted variance. A brand signature,-visual Hook, hierarchy, legibility, geometry or motion difference is not a small variance.-Original authoring records a variance only when the frozen brief or the author explicitly accepts-that difference; an unspecified detail is design freedom, not a variance.--Composition remains valid when several installed components genuinely express the requested system;-it may not move an element into the wrong semantic role merely because another tag draws a similar-shape. Never invent a component, attribute, child, port, Recipe property or literal value.--Installed packages are immutable dependencies. Do not modify them, copy or vendor their source into-the project, or read implementation source to discover undeclared syntax. If the author explicitly-chooses to copy a named package as a close structural sibling, that package's README and required-role files may be read as the bounded implementation skeleton; this is the only source-reading-exception. When the fit is not good enough, use the project-local package route and author it from-the visible requirement, inspect contract, README and `local-author-package.md`.--## Record the judgement--Before package development or Source authoring, write the decisions to the canonical-`.hypit/component-fit.json`. Keep it concise and record only what affected the choice:--```json-{- "basis": ".hypit/brief.json",- "systems": [{- "role": "ranking board",- "inspected_candidates": ["@hypit/ranking"],- "selected_package": "@hypit/ranking",- "decision": "reuse-existing",- "rationale": "same visual role and sufficiently similar presentation",- "accepted_variances": []- }]-}-```--`accepted_variances` contains short natural-language differences only for-`reuse-with-accepted-variance`; it is empty for the other decisions. For `project-local-package`,-`selected_package` names the planned project specifier. This file records the actual design decision;-it does not unlock Source authoring and may be edited when the decision changes.--## A real gap--For a real gap, read `local-author-package.md` completely. Implement and install the new-project-local package, then run-`hypit-reference-video-tools 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.--After inspection, persist the result with `inspect_svml_vocabulary --run <build.svrun>`. Before-writing or checking Source, run `validate_local_author_packages --run <build.svrun>`. Every-project-owned package directory under `packages/` must expose a real Surface, Producer and-Fragment and must be imported and used by the compiled Graph; otherwise the route stops with a-machine-readable diagnostic. Package directory names are descriptive slugs, not a required-`local-` prefix.