Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

refactor: a route step names the files it needs, and one Build ends the job (#81)

rponeawa71ae10395c11
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 789c8b99..8eab0a57 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -20,8 +20,8 @@ choice between things that all work, and asking costs the author an interruption
the references already answer. Decide it and keep going. A run that stops half way with a question is
a run the author has to restart.
-Use this file only to route the task. Read the selected reference completely before acting; when
-that reference names required child references, read those completely in the stated order.
+Use this file only to route the task. A route file is a sequence of numbered steps, and each step
+names the files it needs; read those when you reach that step rather than all of them up front.
Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, and
`hypit.runtime.json` Runtime Profile as separate languages and responsibilities.
@@ -38,7 +38,7 @@ the boundary and launcher selection. Read it before the first command of any rou
## Route
- Reference-video reconstruction, reverse engineering, shot/B-roll/overlay analysis, or recreating
- a video as Hypit source → read `references/reconstruction/index.md`. This is the route whatever
+ a video as Hypit source → read `references/reconstruction/route.md`. This is the route whatever
the author calls it — reconstruct, reverse-engineer, recreate, replicate, clone, remake, copy,
rebuild, or the same idea in any language — and **a path to a video file, with or without words
around it, is this route** even when no verb is given at all. A video path with a change attached —
@@ -46,7 +46,7 @@ the boundary and launcher selection. Read it before the first command of any rou
on the finished reconstruction. The path is the whole request: the working directory, the project
location and the vocabulary are yours to decide rather than to ask for.
- Making a video from a description, brief, topic, script or format name, with nothing to copy →
- read `references/original-authoring/index.md`. This is the route whatever shape the request takes —
+ read `references/original-authoring/route.md`. This is the route whatever shape the request takes —
"make me a 45-second ranking video", "a talking-head explainer about X", an ad for a product, a
written script to produce, a topic and a duration, a format named on its own, or the same idea in
any language — and **a description with no video path attached is this route** even when no verb is
@@ -55,11 +55,11 @@ the boundary and launcher selection. Read it before the first command of any rou
ask for.
- A syntax question about one element, or a source that already exists → read
`references/authoring.md`, then `references/quickstart.md` and the linked authoritative
- docs/package READMEs. A whole video is `references/original-authoring/index.md`, not this file.
+ docs/package READMEs. A whole video is `references/original-authoring/route.md`, not this file.
- Which package owns an element, what vocabulary is installed at all, or whether a capability is
genuinely missing → read `references/vocabulary.md`.
-- Creating a new author component outside reference reconstruction → read
- `references/local-author-package.md`.
+- Creating a new author component → read `references/local-author-package.md`. Both routes reach it
+ at the step that proves a vocabulary gap.
- Seeing what the sources produce, or proving the graph traces before any Build → read
`references/preview.md`.
- Runtime setup, plan/build/status/inspect/get/reuse → read `references/runtime.md`.
@@ -67,8 +67,7 @@ the boundary and launcher selection. Read it before the first command of any rou
`references/credentials.md`.
- Seedance prompt assembly → read `references/seedance-kits.md`.
- Production craft or format selection → read `references/playbooks/index.md` and follow its
- required load order. That list is the authority for which craft every program needs; naming a
- subset here is how it goes stale.
+ required load order, which names the craft every program needs regardless of format.
Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of
commits. Installed package declarations and published docs remain authoritative; repository
diff --git a/.agents/skills/hypit/agents/openai.yaml b/.agents/skills/hypit/agents/openai.yaml
index ec88313f..d0bd0ec5 100644
--- a/.agents/skills/hypit/agents/openai.yaml
+++ b/.agents/skills/hypit/agents/openai.yaml
@@ -1,4 +1,4 @@
interface:
display_name: "Hypit"
short_description: "Build SVML videos and reconstruct reference videos with CLI tools"
- default_prompt: "Use $hypit and route from SKILL.md. For reference-video reconstruction, read references/reconstruction/index.md and every required child reference in order before running the five CLI commands or authoring sources."
+ default_prompt: "Use $hypit and route from SKILL.md. For reference-video reconstruction, read references/reconstruction/route.md and follow its numbered steps, reading the files each step names at the step that names them."
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.md
index a1c29c4e..3758cbdd 100644
--- a/.agents/skills/hypit/references/authoring.md
+++ b/.agents/skills/hypit/references/authoring.md
@@ -27,9 +27,46 @@ syntax, its references, its graph structure — and proves nothing about whether
can actually be built, nor that an uncertain requirement was understood correctly. `preview.md`
proves the Run traces, before any Provider is reached.
+## Reuse an accepted Record
+
+Hypit holds no implicit cache. Connect a Record an earlier Build accepted to a later Build by naming
+it in the Run Source:
+
+```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 selected Candidate must supply the Logical Output's exact nominal Type. Core does not infer
+creative equivalence or propagate a substitute-quality label downstream. Changing the Target list
+alone does not select a Record.
+
+Pin as soon as a Build accepts something. **A Build that fails still accepted everything upstream of
+the failure** — every picture and every take that ran before the step that broke — and resubmitting
+without pinning them buys the same bytes again. Run `--pin` against the failed Build before touching
+the cause. `hypit history --source <author.svml> --pin` emits the pairs for the newest accepted
+Record of each output; do not transcribe Build ids by hand.
+
+**Pin what a Provider was paid to make, and nothing the Source computes.** `--pin` emits a line for
+every accepted output, including the ones the Script's own structure produced: `speech.semantic`,
+`speech.visual`, `speech.audio`, and the Caption Track's deterministic projection. Those are
+projections of the Takes — free to rebuild, and measured against the Script as it was. Paste them
+back after editing a Segment — renaming one, merging two — and the Build pins a skeleton whose
+anchors describe a program that no longer exists. It does not fail: every Track times itself against
+those stale anchors and the delivery is quietly wrong.
+
+**A `SemanticTake` is both.** Alignment is a served capability, so `<take>-semantic.take` is work
+something was paid for and is worth pinning, and its tokens and anchors are keyed to the Script
+Segment it aligned, so it goes stale on a Segment edit exactly as the projections above do. Pin it
+while the Script is untouched; drop it for the Takes whose Segment you edited, and let those
+re-align. This is the one line where "keep what was paid for" and "drop what the Script invalidated"
+disagree, and the Script wins.
+
This file is about writing an element correctly, which is a narrower question than making the video
right. What a Track should contain, when a picture may be generated at all, how long a thing stays on
screen and what shows through when it does not — those are decided in `playbooks/index.md`, whose
required load order names the craft every program needs regardless of format. A whole video is
-`original-authoring/index.md`, not this file: a Source can pass every check above with every one of
+`original-authoring/route.md`, not this file: a Source can pass every check above with every one of
those decisions still unmade.
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index 8884ba9f..ea215f01 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -66,22 +66,6 @@ Distribution is present and stop. A registry install is not a recovery path.
machine npm package home and selected Distribution. Those paths are facts; no repository locator or
environment lock is involved.
-Updates to an installed, published Distribution are an explicit package-manager operation, never an
-automatic mutation during authoring:
-
-```text
-npm outdated --global hypit
-npm update --global hypit
-npx skills update --global
-```
-
-Use `hypit --version` to report the installed Distribution. Check npm only when the user asks about
-updates or during deliberate environment maintenance; do not add a registry request to every route.
-
-Do not run those npm commands for a contributor checkout; update it through its repository workflow.
-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.
-
## Supported hosts and prerequisites
The supported desktop baseline is:
@@ -93,113 +77,16 @@ The supported desktop baseline is:
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.
-Run this skill-owned probe from the installed skill directory when diagnosing a machine:
-
-```text
-node scripts/check-environment.mjs
-```
-
`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 the section below unpacks them by
-hand on Windows. Credentials load from a project's `.env` in the same shell that runs the commands:
+host package manager puts them on `PATH` on macOS and Linux, and a manual install puts them on `PATH`
+on Windows. Credentials load from a project's `.env` in the same shell that runs the commands:
`set -a && . ./.env && set +a`.
`uv` is required only when the selected Runtime Profile uses a managed Python program such as
-WhisperX or OpenCV. Install `uv` with the host package manager, then let `uv` install the pinned
-Python interpreter.
-
-### 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
-
-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.
+WhisperX or OpenCV.
-### Install WhisperX prerequisites on macOS
-
-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. Verify it
-again before `prepare_reference` or a Build, since a first start can spend several minutes loading the
-model:
+When the Runtime Profile selects the local WhisperX Endpoint, verify that the service answered its
+health probe before `prepare_reference` or a Build, since a first start can spend several minutes
+loading the model:
```powershell
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8765/health
@@ -207,67 +94,8 @@ hypit programs status
hypit doctor
```
-If 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`.
-
-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.
-
-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.
-
-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
-```
-
-`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.
-
-Upstream npm dependencies follow the same lifetime. 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.
+`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
diff --git a/.agents/skills/hypit/references/host-setup.md b/.agents/skills/hypit/references/host-setup.md
new file mode 100644
index 00000000..eadab0d9
--- /dev/null
+++ b/.agents/skills/hypit/references/host-setup.md
@@ -0,0 +1,194 @@
+# 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 .agents/skills/hypit/scripts/check-environment.mjs
+```
+
+## 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 are an explicit package-manager operation, never an
+automatic mutation during authoring:
+
+```text
+npm outdated --global hypit
+npm update --global hypit
+npx skills update --global
+```
+
+Use `hypit --version` to report the installed Distribution. Check npm only when the user asks about
+updates or during deliberate environment maintenance; do not add a registry request to every route.
+
+Do not run those npm commands for a contributor checkout; update it through its repository workflow.
+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/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 3f63d431..34408ca4 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -258,49 +258,5 @@ it until the Build runs.
Do not continue to final authoring until the package and sources pass the existing checks and the
graph traces.
-## When the result is accepted, decide whether the package should leave the project
-
-A delivery that shipped may have produced one or more project-local packages on the way. Before
-moving on, judge each one and put the question to the author. Not automatically, and not before the
-result is accepted — this is an offer, and promoting it is a separate contribution.
-
-**The judgement is one question: would a second, unrelated video want this vocabulary?** A component
-that is *this* video's content shaped as a component is not reusable however well it is written — a
-sheet whose steps are this product's onboarding, a board whose rows are this ranking. What travels is
-a *role* the installed packages do not cover: a Style family that differs from `caption-fine` in its
-timing model, a board that differs from `ranking` in the shape of its rows. If the slots are inputs
-and the chrome is the component's own, it is probably reusable; if the package would have to be
-rewritten for the next video, say so and keep it where it is.
-
-Say which it is either way. A local package nobody flagged is a local package nobody revisits.
-
-### Promotion is not a move
-
-If the author wants it promoted, these are the parts. Say up front that this is a checklist rather
-than a path anyone has walked — no package under `packages/` began inside a project, so the first
-person to do it should correct what follows.
-
-- **The name is load-bearing in six places.** `@my-project/local-<slug>` becomes `@hypit/<slug>` in
- `package.json`; in the Module ref in `src/manifest.ts`, where renaming it **renames every nominal
- Type and Producer in the Module at once**, because each is built from that one const; in every
- Author Source that writes `import … from "@my-project/local-<slug>@1"`; in the root `package.json`
- `devDependencies`; in the package's own test harness; and in **both** package catalogs,
- `docs/guide/packages.md` and `docs/zh/guide/packages.md`. An English-only catalog entry is a half
- promotion.
-- **Studio support is a companion.** A project-owned `@my-project/local-<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 boundary section above gives.
+When the result is accepted, `package-promotion.md` says how to judge whether the package should
+outlive this one video and what promoting it costs.
diff --git a/.agents/skills/hypit/references/original-authoring/index.md b/.agents/skills/hypit/references/original-authoring/index.md
deleted file mode 100644
index 0dcc8db1..00000000
--- a/.agents/skills/hypit/references/original-authoring/index.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Making a video from a description
-
-This route produces a complete video program from what the author says they want: `main.svml`,
-`recipes.svs`, `build.svrun` and the `hypit.runtime.json` that binds what they demand — wired, then
-built in rounds until there is a delivery.
-
-The counterpart route is `../reconstruction/index.md`, which starts from a video to copy. Everything
-between the two — what a picture is, what one generation owes another, which package owns an element,
-how a Build is staged — is the same work and is written once, in the files this page links. This page
-owns the order, and nothing else.
-
-## What this route delivers, and what it does not
-
-Unlike reconstruction, this route **does spend**. It generates pictures, takes, speech and a render.
-What it does not do is spend them all at once: `../playbooks/craft/production-gates.md` stages the
-work so that an unreviewed expensive output cannot silently feed a later Operation, and the delivery
-Build is the last thing that happens, not the first.
-
-There is no reference to check against, so the two things a reconstruction gets for free have to be
-decided deliberately here: what the program is *for*, and what every appearance value *is*. Neither
-has an evidence file to consult. Write them down rather than discovering them at render time.
-
-## A description is the whole request
-
-The author gives what the video should be — its subject, its length, its audience, who is in it, what
-it says. That is theirs. The working directory, the project location, which packages to use, which
-generator, which model tier and how many takes are **yours to decide rather than to ask for**;
-`../playbooks/craft/generated-dependencies.md` states this for generators and it holds for the rest.
-
-Ask about the video and nothing else. What is missing from a description is usually the duration, the
-aspect ratio and the language — ask those together, once, and not one at a time.
-
-Everything else this route needs is discoverable:
-
-- **Where you are, and what is installed.** `../environment.md`.
-- **Credentials.** `../credentials.md` lists which variables each Provider needs.
-- **Where the project goes.** Its own directory outside the installed Distribution, normally
- `<home>/<name>/`, named after the video. `../runtime.md` defines the hard boundary.
-
-## Before deciding anything
-
-1. Every craft file listed in the first item of `../playbooks/index.md`'s required load order — the
- ones it marks always-read — complete, in the order it gives them. That list decides which files,
- and it grows: one added there is required here from the moment it is added. Restating the set on
- this page is what once left a required craft file reachable from one route and invisible to the
- other, so this page does not restate it.
-2. The format. `../playbooks/index.md` lists them; read the one that fits and only the additional
- craft files its own footer names.
-3. `../vocabulary.md` — which installed packages own the systems this program contains, and whether
- any of them is genuinely missing. A system you never inspected is a system you are about to
- invent, and inventing one here is easy: there is no reference to contradict you.
-
-## Write the Script, then the sources
-
-`../authoring.md` is the syntax authority and names the checks. The Script comes first and the shots
-come out of it, not the other way round: a Segment is what one `whisperx:SemanticTake` aligns one
-Take to, so how the Script is cut decides how many generations there are and where the seams fall —
-`../playbooks/craft/generated-dependencies.md` says why over-splitting manufactures seams nobody
-asked for.
-
-Write all four files before building any of them. The Runtime Profile is part of the deliverable, not
-an afterthought — `../runtime.md` says how to author one.
-
-## Check it, then prove it is wired
-
-`../authoring.md`'s check set proves the sources are legal. That is not the same as the graph tracing,
-and neither is bounded by any attempt ceiling: `../preview.md` proves the Run traces before a Provider
-is ever reached, and a graph that does not trace is not done.
-
-## See it before you pay for it
-
-`../preview.md` again: one element rendered to a still locally, or the whole Run opened in Studio for
-the author. Both are free. Looking at a composition before generating into it is the cheapest review
-in the sequence.
-
-## Generate in rounds
-
-`../playbooks/craft/production-gates.md`, Gates 1 through 4 in order. Pictures are accepted before
-takes reference them; takes are accepted before they are assembled; the delivery is demanded last and
-watched and measured whole.
-
-Gate 4 ends the job — and ends with the question of whether a component built along the way should
-outlive this one video. `../local-author-package.md` says how to judge that and what promoting it
-actually costs.
-
-## When a step outgrows this page
-
-This directory holds one file today, because every step above already has a home to link to. That is
-the intended shape, not an unfinished one. **When a step here grows past three sentences that are not
-links, its content belongs in a file of its own, or in the shared file it should have linked** — the
-disease this route was split out to cure is whole-job knowledge accumulating in one place where only
-one route can find it.
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
new file mode 100644
index 00000000..25d20ea3
--- /dev/null
+++ b/.agents/skills/hypit/references/original-authoring/route.md
@@ -0,0 +1,114 @@
+# Making a video from a description
+
+Read a step, do it, read the next one. Each step names the files it needs; read those at that step.
+
+This route produces a complete video program from what the author says they want: `main.svml`,
+`recipes.svs`, `build.svrun` and the `hypit.runtime.json` that binds what they demand — wired, then
+built once into a delivery.
+
+The counterpart route is `../reconstruction/route.md`, which starts from a video to copy. Everything
+between the two — what a picture is, what one generation owes another, which package owns an element
+— is the same work and is written once, in the files these steps link. This page owns the order.
+
+**This route spends.** One Build generates the pictures, the takes, the speech and the render, and
+step 10 is where the author says yes to it. There is no reference to check against, so the two things
+a reconstruction gets for free have to be decided deliberately: what the program is *for*, and what
+every appearance value *is*. Neither has an evidence file to consult. Write them down rather than
+discovering them at render time.
+
+## A description is the whole request
+
+The author gives what the video should be — its subject, its length, its audience, who is in it, what
+it says. The working directory, the project location, which packages to use, which generator, which
+model tier and how many takes are **yours to decide rather than to ask for**.
+
+---
+
+### 1. Select the Distribution and place the project
+
+**Read now:** `../environment.md` — the three independent places, Distribution selection and the
+launcher substitution rule. `../runtime.md` — the hard boundary between a project and a Distribution.
+
+The project gets its own directory outside the installed Distribution, normally `<home>/<name>/`,
+named after the video, with a `package.json` carrying a name and `"private": true`.
+
+### 2. Load credentials
+
+```bash
+set -a && source .env && set +a
+```
+
+**Read now:** `../credentials.md` — which variables each Provider needs.
+
+### 3. Ask what the description leaves out
+
+What is missing from a description is usually the duration, the aspect ratio and the language. Ask
+those together, once. Ask about the video and nothing else.
+
+Freeze the answers along with the Script's meaning, the format, the supplied assets and the factual
+claims before any prompt is written. Everything downstream is measured against them.
+
+### 4. Read the craft this program needs
+
+1. Every craft file named in the first item of `../playbooks/index.md`'s required load order, in the
+ order it gives them.
+2. The format. `../playbooks/index.md` lists them; read the one that fits and only the additional
+ craft files its own footer names.
+
+### 5. Choose the packages
+
+**Read now:** `../vocabulary.md` — which installed packages own the systems this program contains,
+and whether any is genuinely missing. A system you never inspected is a system you are about to
+invent, and inventing one here is easy: there is no reference to contradict you.
+
+For a proven gap, read `../local-author-package.md` completely and build the package.
+
+### 6. Write the Script
+
+The Script comes first and the shots come out of it: a Segment is what one `whisperx:SemanticTake`
+aligns one Take to, so how the Script is cut decides how many generations there are and where the
+seams fall. `../playbooks/craft/generated-dependencies.md` says why over-splitting manufactures seams
+nobody asked for.
+
+Give every planned shot one job — hook, context, evidence, mechanism, reaction, payoff, transition,
+or CTA. Delete shots with no distinct job.
+
+### 7. Write the four sources
+
+`main.svml`, `recipes.svs`, `build.svrun`, `hypit.runtime.json`. Write all four before building any
+of them; the Runtime Profile is part of the deliverable.
+
+**Read now:** `../authoring.md` — the syntax authority, the check set, and how an accepted Record is
+reused in the Run Source. `../runtime.md` — how to author a Profile.
+
+### 8. Check, then prove the graph traces
+
+`../authoring.md`'s check set proves the sources are legal, which is a narrower claim than the graph
+tracing. `../preview.md` proves the Run traces before a Provider is reached. Neither is bounded by any
+attempt ceiling: a graph that does not trace is work that is not done.
+
+### 9. See it before paying for it
+
+`../preview.md` again: one element rendered to a still locally, or the whole Run opened in Studio for
+the author. Both are free.
+
+### 10. The Build
+
+Confirm credentials, the Runtime Profile, the installed packages, model limits, resolution and
+Endpoint prerequisites. Run `doctor`, `check` and `plan`.
+
+`plan` is what makes the cost sayable. **Say what the Build will cost and get the author's yes before
+submitting it.** This is the one point on this route where their money is spent.
+
+**Read now:** `../runtime.md` — submitting the Build, `status`, `inspect`, and `get` for the finished
+Artifact.
+
+### 11. Ask whether the package outlives the video
+
+If this job produced a project-local package, `../package-promotion.md` says how to judge whether it
+should leave the project and what promoting it costs.
+
+---
+
+When a step here grows past three sentences that are not links, its content belongs in a file of its
+own, or in the shared file it should have linked.
diff --git a/.agents/skills/hypit/references/package-promotion.md b/.agents/skills/hypit/references/package-promotion.md
new file mode 100644
index 00000000..b387106c
--- /dev/null
+++ b/.agents/skills/hypit/references/package-promotion.md
@@ -0,0 +1,52 @@
+# 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. Not automatically, and not before the
+result is accepted — this is an offer, and promoting it is a separate contribution.
+
+**The judgement is one question: would a second, unrelated video want this vocabulary?** A component
+that is *this* video's content shaped as a component is not reusable however well it is written — a
+sheet whose steps are this product's onboarding, a board whose rows are this ranking. What travels is
+a *role* the installed packages do not cover: a Style family that differs from `caption-fine` in its
+timing model, a board that differs from `ranking` in the shape of its rows. If the slots are inputs
+and the chrome is the component's own, it is probably reusable; if the package would have to be
+rewritten for the next video, say so and keep it where it is.
+
+Say which it is either way. A local package nobody flagged is a local package nobody revisits.
+
+### Promotion is not a move
+
+If the author wants it promoted, these are the parts. Say up front that this is a checklist rather
+than a path anyone has walked — no package under `packages/` began inside a project, so the first
+person to do it should correct what follows.
+
+- **The name is load-bearing in six places.** `@my-project/local-<slug>` becomes `@hypit/<slug>` in
+ `package.json`; in the Module ref in `src/manifest.ts`, where renaming it **renames every nominal
+ Type and Producer in the Module at once**, because each is built from that one const; in every
+ Author Source that writes `import … from "@my-project/local-<slug>@1"`; in the root `package.json`
+ `devDependencies`; in the package's own test harness; and in **both** package catalogs,
+ `docs/guide/packages.md` and `docs/zh/guide/packages.md`. An English-only catalog entry is a half
+ promotion.
+- **Studio support is a companion.** A project-owned `@my-project/local-<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/.agents/skills/hypit/references/playbooks/craft/b-roll.md b/.agents/skills/hypit/references/playbooks/craft/b-roll.md
index 72260713..f2e9c129 100644
--- a/.agents/skills/hypit/references/playbooks/craft/b-roll.md
+++ b/.agents/skills/hypit/references/playbooks/craft/b-roll.md
@@ -34,13 +34,12 @@ Do this after placing a Selection and before paying for a generation. Startup an
1. Put the reference-frame prompt in an English `copy:Value` and generate the image with an explicit
image Surface such as `gpt:Image`.
-2. Pass the image through the image gate in `production-gates.md` before using it as a video reference.
-3. Vendor `broll-v1.svs`, choose the stable material/story/edit/camera/motion axes in an SVS Recipe,
+2. Vendor `broll-v1.svs`, choose the stable material/story/edit/camera/motion axes in an SVS Recipe,
and put only the shot-specific micro-story in an English `copy:Value`.
-4. Render the Kit with `copy:Render` and connect the story through `copy:Set`.
-5. Generate through `seedance:ReferenceVideo` with `generate-audio="false"` and explicit ordered
+3. Render the Kit with `copy:Render` and connect the story through `copy:Set`.
+4. Generate through `seedance:ReferenceVideo` with `generate-audio="false"` and explicit ordered
references.
-6. Place accepted shots with `media-track:Track` and `media-track:Item` or `media-track:Sequence`.
+5. Place shots with `media-track:Track` and `media-track:Item` or `media-track:Sequence`.
```svml
<copy:Value id="demo-story">
diff --git a/.agents/skills/hypit/references/playbooks/craft/captions.md b/.agents/skills/hypit/references/playbooks/craft/captions.md
index 91caf404..025026c0 100644
--- a/.agents/skills/hypit/references/playbooks/craft/captions.md
+++ b/.agents/skills/hypit/references/playbooks/craft/captions.md
@@ -130,9 +130,10 @@ through one. Timing is not authored with it: each Cue is still timed from the al
- Caption projects Selections/Roles to complete units before it sees any frame or audio measurement.
- Each `whisperx:SemanticTake` measures one accepted normalized Segment take and packages its local
timing; `speech:Track` assembles those Takes into the SemanticTrack used by `caption-fine:Track`.
-- Recompute the affected SemanticTake whenever the speech audio changes — `production-gates.md` Gate 3 states this for
- every Track that is timed against it, not only for captions. A Style-only change does not prove that
- a prior visual review is still valid.
+- Recompute the affected SemanticTake whenever the speech audio changes. This holds for every Track
+ timed against it — Caption, Media, Typography, Ranking, Deck, Comment, Screen, Audio — because each
+ one is otherwise measured against audio that no longer exists, and the drift is invisible in a
+ still frame.
## Design for readability
diff --git a/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md b/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md
index 454a66eb..d7c7ede2 100644
--- a/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md
+++ b/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md
@@ -76,11 +76,5 @@ tiling it is the other one, and it is just as covered. A `until={story.moment.X}
element claims, so a picture that leaves half way through the program answers for the words before
that Moment and not the ones after.
-What is left for the delivery is what only the delivery shows. An instant is a thirtieth of a second:
-watching finds a scene that is wrong and slides straight past a frame that is, and the shorter the
-hole the more it reads as intentional cutting. Both measurements are in `production-gates.md` Gate 4,
-one for holes over nothing and one for holes over something. Run both — a hole with something under
-it passes the first.
-
-Anything the measurements report is an inherited edge. Take it back to the interval that produced it
-rather than to the layer that revealed it.
+Anything `reconstruction_check` reports under `coverage.gaps` is an inherited edge. Take it back to
+the interval that produced it rather than to the layer that revealed it.
diff --git a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
index e6f9a175..8dfab6e7 100644
--- a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
+++ b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
@@ -23,8 +23,8 @@ only about the video: what it should say, who is in it, what it is for.
- Naming the camera positions before generating anything, as `visual-continuity.md` already says,
is what tells you how many images you need.
-Images therefore generate in rounds: the establishing image is accepted first, and the views derived
-from it are generated after. `production-gates.md` Gate 1 is one stage per round, not one stage.
+Images therefore generate in dependency order: the establishing image is produced before the views
+derived from it, and the reference edges the Source declares are what state that order.
## A split picture's parts all start from the same image
@@ -241,8 +241,6 @@ A layer beneath makes a blend visible, so check the Items' entry and exit while
default to `none`, and a Recipe named for a cut that fades for a frame is one of the inherited edges
`frame-coverage.md` describes.
-`production-gates.md` measures the delivery for these before it is reported as finished.
-
## A Selection carries two edges; a Moment carries one
Both name time in the Script's own words, and which to reach for follows how many edges the words
diff --git a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
index fe4f8679..cea78f3e 100644
--- a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
+++ b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
@@ -141,5 +141,4 @@ that needs one of those documents in order to draw itself has inverted that rela
- Generate one material per depicted thing, at the aspect ratio it will be used at, carrying only
what it depicts. Keep captions, labels, arrows, badges and titles out of the prompt; the
composition draws those.
-- Pass every generated image through the image gate in `production-gates.md` before connecting it
- downstream, and pin accepted Records for reuse.
+- Pin accepted Records for reuse. `../../authoring.md` says how a Record is named in the Run Source.
diff --git a/.agents/skills/hypit/references/playbooks/craft/image-prompt-style.md b/.agents/skills/hypit/references/playbooks/craft/image-prompt-style.md
index 529c9b0a..b171bb0e 100644
--- a/.agents/skills/hypit/references/playbooks/craft/image-prompt-style.md
+++ b/.agents/skills/hypit/references/playbooks/craft/image-prompt-style.md
@@ -55,9 +55,3 @@ into separate prompts.
`visual-continuity.md`.
- Make before/after states visibly distinguishable through the authored condition, posture, setting,
styling, or evidence while preserving the intended recurring identity and product facts.
-
-## Accept images before reuse
-
-Run the image gate in `production-gates.md`. When image viewing is available, inspect the actual
-output and reject identity drift, impossible anatomy/camera geometry, duplicate props, wrong text,
-same-background reverse views, watermarks, and unusable overlay clearance before downstream use.
diff --git a/.agents/skills/hypit/references/playbooks/craft/overlays.md b/.agents/skills/hypit/references/playbooks/craft/overlays.md
index a2ebcbf6..a4da1808 100644
--- a/.agents/skills/hypit/references/playbooks/craft/overlays.md
+++ b/.agents/skills/hypit/references/playbooks/craft/overlays.md
@@ -35,8 +35,8 @@ is left, not for the whole one.
images, not one image used twice.
- A face, a mouth or a gesturing hand behind an opaque overlay is the failure this prevents, and it
survives every structural check: the Source is legal, both tracks build, and the speaker is
- headless. Check it at the image gate in `production-gates.md`, where overlay clearance is already
- on the list.
+ headless. Place the overlay so the base picture's face, mouth and hands stay clear of it, and
+ author the base picture's framing to leave that clearance.
## Choose the native overlay surface
diff --git a/.agents/skills/hypit/references/playbooks/craft/persona-and-audio.md b/.agents/skills/hypit/references/playbooks/craft/persona-and-audio.md
index 0ecb54fd..8d43130b 100644
--- a/.agents/skills/hypit/references/playbooks/craft/persona-and-audio.md
+++ b/.agents/skills/hypit/references/playbooks/craft/persona-and-audio.md
@@ -21,7 +21,7 @@ Connect only the references a component actually needs.
## Author faces and voices explicitly
- Use `gpt:Image` with ordered `gpt:Reference` children when a new character/scene image must preserve
- supplied identity or product facts. Pass every generated image through `production-gates.md`.
+ supplied identity or product facts.
- Use `mimo:Preset` for a selected built-in voice or `mimo:VoiceDesign` for an English voice
description. Either one produces the sample, once per person.
- That sample is a reference on every take the person appears in, and the take speaks the Segment.
diff --git a/.agents/skills/hypit/references/playbooks/craft/production-gates.md b/.agents/skills/hypit/references/playbooks/craft/production-gates.md
deleted file mode 100644
index 6065ba90..00000000
--- a/.agents/skills/hypit/references/playbooks/craft/production-gates.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Production gates
-
-Use staged Run Sources so unreviewed expensive outputs cannot silently feed later Operations.
-
-## Gate 0: freeze author intent
-
-- Freeze Script meaning, target language, aspect ratio, delivery duration, format, supplied assets,
- and factual claims before writing prompts.
-- Give every planned shot one job: hook, context, evidence, mechanism, reaction, payoff, transition,
- or CTA. Delete shots with no distinct job.
-- Confirm credentials, Runtime Profile, installed packages, model limits, resolution, and Endpoint
- prerequisites. `../../runtime.md` says how to author the Profile, and `../../vocabulary.md` how to
- find out what is installed. Run `doctor`, `check`, and `plan` before the first paid Build.
-
-## Gate 1: build and review reference images
-
-This gate runs once per round, not once. An image generated **from** another image — a second view of
-a location derived from the one that established it — cannot be demanded until the image it derives
-from has been accepted, so establishing images are one round and the views derived from them are the
-next. `generated-dependencies.md` says which images derive from which.
-
-1. Create a narrow `.svrun` containing Targets only for the generated reference-image outputs of this
- round.
-2. Submit that Build, then use `inspect` and `get` to retrieve every candidate image.
-3. If the Agent can view images, open the actual full-resolution outputs and review every image
- itself. Do not approve from prompts, metadata, filenames, or thumbnails alone.
-4. Reject and regenerate any failed image. Do not connect a failed image to Seedance, Media Track,
- image composition, or another downstream generator.
-5. Reuse accepted image Records with `.svrun` `build-record` and connect them to the next Build with
- `satisfy`. Changing the Target list alone does not select those Records. Do not transcribe the
- Build ids by hand — `hypit history --source <author.svml> --pin` emits the pairs for the newest
- accepted Record of each output, ready to paste. Every Record you fail to pin is a generation you
- pay for twice.
-
-Pin as soon as a Build accepts something, not when you next want to build. **A Build that fails still
-accepted everything upstream of the failure**, and that is exactly when pinning is skipped: the run
-ended in an error, so it does not feel like a run that produced anything. It produced every picture
-and every take that ran before the step that broke, and resubmitting without pinning them buys the
-same bytes again. Run `--pin` against the failed Build before touching the cause.
-
-**Pin what a Provider was paid to make, and nothing the Source computes.** `--pin` emits a line for
-every accepted output, including the ones the Script's own structure produced: `speech.semantic`,
-`speech.visual`, `speech.audio`, and the Caption Track's deterministic projection. Those are projections of the Takes — free to
-rebuild, and measured *against the Script as it was*. Paste them back after editing a Segment —
-renaming one, merging two — and the Build pins a skeleton whose anchors describe a program that no
-longer exists. It does not fail. Every Track times itself against those stale anchors and the
-delivery is quietly wrong, which is the one failure this whole gate sequence exists to prevent.
-
-**A `SemanticTake` is both.** Alignment is a served capability, so `<take>-semantic.take` is work
-something was paid for and is worth pinning — but its tokens and anchors are keyed to the Script
-Segment it aligned, so it goes stale on a Segment edit exactly as the projections above do. Pin it
-while the Script is untouched; drop it for the Takes whose Segment you edited, and let those
-re-align. This is the one line where "keep what was paid for" and "drop what the Script invalidated"
-disagree, and the Script wins.
-
-Keep the pictures, the takes and the voices; let everything downstream of them recompute.
-
-**A Build that failed downstream may still hold the good draw from a model that does not repeat
-itself.** Caption grouping is Script-owned and deterministic; it is not a model Candidate and must
-be recomputed from the edited Script. Pin the normalized media and SemanticTake facts instead.
-
-Apply this checklist to every image:
-
-- identity: correct recurring person/product/location, complete face when required, no drift;
-- anatomy: plausible hands, fingers, limbs, pose, gaze, and object contact;
-- geometry: camera ownership, viewpoint, reflections, screen orientation, and visible objects are
- physically possible;
-- reverse views: opposing camera positions show different background sectors and landmarks; the
- same or near-identical main background is an automatic failure;
-- continuity: wardrobe, lighting, props, object count, handed tasks, and spatial relationships match
- the shot group;
-- text: required physical labels/UI are accurate enough for the use; no invented subtitles,
- watermarks, floating words, or accidental logos;
-- composition: requested framing, aspect, safe zones, and overlay clearance are present;
-- quality: no broken edges, duplicated objects, severe blur, malformed texture, or generation debris.
-
-If the Agent cannot view images, skip visual inspection and do not claim that the images passed
-visual QA.
-
-## Gate 2: generate and review video takes
-
-- Demand only the takes whose reference images have passed Gate 1.
-- **Before demanding any take with `generate-audio="true"`, trace its prompt back to the words it is
- supposed to say.** Follow the edge from the take's `prompt=` to the `copy:Render` that produced it,
- and confirm one of its `copy:Set` slots carries that Segment's `dialogue`. A prompt bound straight
- to a `copy:Value` holding a performance direction is the defect this catches: the model receives no
- words, invents its own, and the take sounds fluent and says nothing from the Script.
-
- It survives every structural check. `hypit check`, `preview_check` and `plan` all pass, because the
- graph is legal and complete — the prompt is a Text and the take consumes it. `whisperx:SemanticTake`
- then fits the Segment's words onto whatever audio arrived rather than reporting that they differ, so
- the Caption Track renders the Script over speech that shares none of it, and every downstream
- measurement stays clean.
-
- Two minutes of reading the Source here is the difference between finding it now and finding it in a
- delivery whose every take has been paid for. `seedance-directing.md` and `../../seedance-kits.md`
- name the slot the words travel through.
-- Keep Seedance duration inside the selected model's declared range, read from that model rather than
- from memory: the models differ and one accepts far longer takes. Invalid values fail validation rather
- than being silently clamped.
-- Review each take before assembly: verify the first-frame identity, reference continuity, lip-sync
- when applicable, physical motion, stable props/text, intended camera/edit language, and absence of
- generated editorial overlays.
-- Regenerate only failed takes. Pin accepted image/take Records explicitly in the next Build.
-
-## Gate 3: measure and author Tracks
-
-- Normalize every accepted speaking take, create its Segment-local `whisperx:SemanticTake`, then
- assemble those Takes with `speech:Track`. That take carries the Segment's picture as well as its
- speech, so one accepted generation settles both.
-- Recompute the affected SemanticTake whenever its speech audio changes. Every Track timed against it — Caption,
- Media, Typography, Ranking, Deck, Comment, Screen, Audio — is measured against audio that no longer
- exists otherwise, and the drift is invisible in a still frame. A Style-only change does not prove a
- prior review still holds.
-- Review Caption, Media, Typography, Ranking, Deck, Comment, Screen, and Audio Tracks against the
- real SemanticTrack. Check timing, safe zones, occlusion, stacking, audio clarity,
- and whether each Track contributes unique information.
-- Treat `check` and `plan` as structural proofs only. They do not prove visual quality, real speech
- alignment, Provider output quality, or factual correctness.
-- A reconstruction route has compared these Tracks against a reference before this gate. That
- comparison runs on renders made from the Source's values over a stand-in SemanticTake, so it
- settles how a Track looks and leaves everything this gate is about — timing against real speech,
- drift after a recompute, occlusion between Tracks that were rendered separately — still to be
- measured here. Review them against the real SemanticTrack whatever was compared earlier.
-
-## Gate 4: delivery Build
-
-- Demand `final.video` only after the upstream gates pass.
-- Inspect the durable Build and retrieve the final Artifact with `get`.
-- Watch and listen to the complete delivery, including the first and last second. Verify dialogue,
- captions, overlays, transitions, audio density, claims, and CTA as one program.
-- **Measure the delivery's own speech against the Script. This is the gate the whole program's words
- rest on.** The take that speaks a Segment generates that speech from its prompt, so what is said is
- decided by a video generator rather than handed to a synthesizer as text — it can drop a clause,
- reorder one, or say something adjacent. Nothing upstream reads it back: an agent reads pictures and
- cannot hear, so "listen and verify dialogue" above resolves to nothing on its own, and a take whose
- spoken words came from somewhere other than the Script passes `check`, `plan`, `preview_check` and
- both measurements below without a mark. Transcribe what was delivered and read it against the words
- the Script holds:
-
- ```bash
- hypit-reference-video-tools prepare_reference --video-path output/final.mp4 --observer agent
- ```
-
- Its `transcript` is measured locally by WhisperX from the delivery's own audio, so it is what the
- video says rather than what the Source intended. Compare it line by line with the Script's
- Segments. They correspond, or a take was generated from a prompt that did not carry its dialogue —
- read `seedance-directing.md` and the Kit contract in `../../seedance-kits.md`, which name the slot
- the words travel through.
-
- The symptom this catches is total rather than subtle: the captions render the Script while the
- voice says unrelated sentences, and alignment hides it by fitting the Script's words onto whatever
- audio arrived. Run it before reporting any delivery that contains speech.
-- Measure the delivery for empty picture before reporting it as finished. Watching finds a scene that
- is wrong; it slides straight past a second of black between two shots, and a program assembled from
- Selections can hold several. `ffmpeg -i final.mp4 -vf blackdetect=d=0.2:pic_th=0.90 -an -f null -`
- prints every stretch with its start and duration, and any hit is a hole in the picture rather than
- an edit — read `generated-dependencies.md` on covering a Segment. Report the delivery only after
- this comes back empty.
-- Measure the delivery for anything that flashes, which black detection does not catch once something
- is bedded underneath. A cut list makes it objective: any state that lives for a fraction of a second
- between two cuts is a hole showing the layer below, not an edit.
-
- ```bash
- ffmpeg -v error -i final.mp4 -vf "select='gt(scene,0.20)',metadata=print:file=-" -an -f null - \
- | grep -oE 'pts_time:[0-9.]+' | sed 's/pts_time://' \
- | awk '{if(p!=""&&$1-p<0.7)printf "%.2fs on screen at %.2fs\n",$1-p,p; p=$1}'
- ```
-
- Two cuts a quarter of a second apart is a picture nobody authored. Read it against
- `generated-dependencies.md` on windows that do not tile.
-- Preserve accepted Records for deliberate future reuse; never assume a rerun will reuse them.
-- The delivery is accepted, so ask the last question: did this job produce a project-local package,
- and should it outlive this one video? `../../local-author-package.md` says how to judge that and
- what promoting it costs.
-
-Use explicit Run Source authoring for every accepted reuse:
-
-```svml
-<target output="final.video"/>
-<build-record id="accepted-take" build="reviewed-build-001"
- output="opening-take.video"/>
-<satisfy output="opening-take.video" candidate="accepted-take"/>
-```
-
-The selected Candidate must supply the Logical Output's exact nominal Type. Core does not infer
-creative equivalence or propagate a substitute-quality label downstream.
diff --git a/.agents/skills/hypit/references/playbooks/craft/screen-demo.md b/.agents/skills/hypit/references/playbooks/craft/screen-demo.md
index 3d1a2250..5d7e5ea3 100644
--- a/.agents/skills/hypit/references/playbooks/craft/screen-demo.md
+++ b/.agents/skills/hypit/references/playbooks/craft/screen-demo.md
@@ -34,7 +34,7 @@ for both views is insufficient. Apply the complete gate in `visual-continuity.md
- Use a real supplied screenshot or captured screen whenever exact wording, data, layout, logo, or
interaction state matters. Do not ask an image or video generator to guarantee exact UI text.
- When generating a contextual device image, connect the real UI screenshot as an explicit image
- reference, describe its role in the English prompt, and pass the result through the image gate.
+ reference and describe its role in the English prompt.
- Preserve device orientation, bezel, screen plane, user eye line, room geometry, and the interface
state across the context/proof pair.
diff --git a/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md b/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md
index fbfadb80..dd998d2c 100644
--- a/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md
+++ b/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md
@@ -10,6 +10,20 @@
`direction` slots through `copy:Set`.
5. Feed the rendered Text to one explicit Seedance Surface and keep every reference edge visible.
+**A take with `generate-audio="true"` says whatever its prompt carries, so trace that prompt back to
+the words before authoring the take.** Follow the edge from the take's `prompt=` to the `copy:Render`
+that produced it, and confirm one of that Render's `copy:Set` slots carries the Segment's `dialogue`.
+A prompt bound straight to a `copy:Value` holding a performance direction reaches the model with no
+words in it: the model invents its own, and the take sounds fluent while saying nothing the Script
+holds.
+
+That state survives every structural check. `hypit check`, `preview_check` and `plan` all pass,
+because the graph is legal and complete — the prompt is a Text and the take consumes it.
+`whisperx:SemanticTake` then fits the Segment's words onto whatever audio arrived, so the Caption
+Track renders the Script over speech that shares none of it and every downstream measurement stays
+clean. Reading the Source is what finds it. `../../seedance-kits.md` names the slot the words travel
+through.
+
Write every user-authored image/video generation instruction in English. Verbatim dialogue may retain
the Script's authored language; do not translate or paraphrase quoted Script lines inside prompts.
@@ -67,6 +81,3 @@ than relying on an unstated assumption.
- Keep faces readable and hands away from the face unless contact is the authored action.
- Keep editorial subtitles, titles, cards, stickers, and floating text out of Seedance. Preserve only
physical labels/UI already attached to referenced objects.
-
-Review every reference image through `production-gates.md` before calling Seedance, then review the
-resulting take before normalizing it into a Semantic Take or adding it to a Media Track.
diff --git a/.agents/skills/hypit/references/playbooks/craft/visual-continuity.md b/.agents/skills/hypit/references/playbooks/craft/visual-continuity.md
index 9a026ca9..268424c2 100644
--- a/.agents/skills/hypit/references/playbooks/craft/visual-continuity.md
+++ b/.agents/skills/hypit/references/playbooks/craft/visual-continuity.md
@@ -47,4 +47,3 @@ the device-facing reverse image shows what is behind the device. Writing only
reaction without invented dialogue.
- Keep supplied physical text attached to its product, screen, document, or sign; put editorial text
on explicit Tracks.
-- Apply the image gate in `production-gates.md` before connecting any generated frame downstream.
diff --git a/.agents/skills/hypit/references/playbooks/formats/asmr.md b/.agents/skills/hypit/references/playbooks/formats/asmr.md
index ed89f41b..75515e50 100644
--- a/.agents/skills/hypit/references/playbooks/formats/asmr.md
+++ b/.agents/skills/hypit/references/playbooks/formats/asmr.md
@@ -48,5 +48,4 @@ and audio Records with `.svrun` `build-record` and `satisfy`.
Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`, `../craft/b-roll.md`,
`../craft/persona-and-audio.md`, and `../craft/sfx.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md b/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md
index 4e60a62a..22c22080 100644
--- a/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md
+++ b/.agents/skills/hypit/references/playbooks/formats/mass-tarot.md
@@ -71,10 +71,7 @@ through `.svrun` `build-record` and `satisfy`.
Read `../craft/b-roll.md`, `../craft/captions.md`, `../craft/overlays.md`, and
`../craft/persona-and-audio.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
-- The base is meant to stay hidden, so the covering Selections tile the Segment: its first word
- opens one, its last word closes one, and nothing falls between. Join them with the Script's
- absorbing markers — `../craft/generated-dependencies.md` holds the table. A gap shows the
- speaker for half a second in a program that has none.
+- The base is meant to stay hidden, so the covering Selections tile the Segment.
+ `../craft/generated-dependencies.md` states that rule and holds the marker table.
diff --git a/.agents/skills/hypit/references/playbooks/formats/mixcut.md b/.agents/skills/hypit/references/playbooks/formats/mixcut.md
index 7f2e977d..118610bb 100644
--- a/.agents/skills/hypit/references/playbooks/formats/mixcut.md
+++ b/.agents/skills/hypit/references/playbooks/formats/mixcut.md
@@ -36,10 +36,8 @@ A crop of the same image is not a new beat.
and `speech:Track` declarations and satisfy `<track>.semantic` in `.svrun` with `build-record` and
`satisfy`, then author explicit `start`/`end` windows against it — `../index.md` says why the
declarations stay. Do not treat music as speech evidence.
-- The base is meant to stay hidden, so the covering Selections tile the Segment: its first word
- opens one, its last word closes one, and nothing falls between. Join them with the Script's
- absorbing markers — `../craft/generated-dependencies.md` holds the table. A gap shows the
- speaker for half a second in a program that has none.
+- The base is meant to stay hidden, so the covering Selections tile the Segment.
+ `../craft/generated-dependencies.md` states that rule and holds the marker table.
- Omit Caption components when there is no spoken Script. Use `typo:Track` for title, benefit, and CTA
copy.
- Keep no more than one or two text groups on screen at once. Align text handoffs to the final trimmed
@@ -64,5 +62,4 @@ only failed beats.
Read `../craft/image-prompt-style.md`, `../craft/b-roll.md`, `../craft/overlays.md`,
`../craft/persona-and-audio.md`, and `../craft/sfx.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md b/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md
index ce54b756..2184a395 100644
--- a/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md
+++ b/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md
@@ -52,5 +52,4 @@ media through `.svrun` before the final ranking Build.
Read `../craft/captions.md`, `../craft/overlays.md`, `../craft/b-roll.md`, and `../craft/sfx.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/scenario-call.md b/.agents/skills/hypit/references/playbooks/formats/scenario-call.md
index b84e6c26..0202aa21 100644
--- a/.agents/skills/hypit/references/playbooks/formats/scenario-call.md
+++ b/.agents/skills/hypit/references/playbooks/formats/scenario-call.md
@@ -40,5 +40,4 @@ live listener reaction, UI stability, and generated text. Pin every accepted lay
Read `../craft/seedance-directing.md`, `../craft/captions.md`, `../craft/overlays.md`, and
`../craft/persona-and-audio.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/street-interview.md b/.agents/skills/hypit/references/playbooks/formats/street-interview.md
index b2f0a08e..4c03e8de 100644
--- a/.agents/skills/hypit/references/playbooks/formats/street-interview.md
+++ b/.agents/skills/hypit/references/playbooks/formats/street-interview.md
@@ -56,5 +56,4 @@ and takes with `.svrun` `build-record` and `satisfy` before downstream assembly.
Read `../craft/seedance-directing.md`, `../craft/persona-and-audio.md`, `../craft/captions.md`,
and `../craft/b-roll.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/talking-head.md b/.agents/skills/hypit/references/playbooks/formats/talking-head.md
index 1f1cca02..fbac77d5 100644
--- a/.agents/skills/hypit/references/playbooks/formats/talking-head.md
+++ b/.agents/skills/hypit/references/playbooks/formats/talking-head.md
@@ -58,5 +58,4 @@ Read `../craft/image-prompt-style.md`, `../craft/seedance-directing.md`,
`../craft/persona-and-audio.md`, `../craft/captions.md`, `../craft/b-roll.md`, and
`../craft/overlays.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md b/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md
index d1dc2bba..b10c0a4b 100644
--- a/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md
+++ b/.agents/skills/hypit/references/playbooks/formats/two-person-podcast.md
@@ -54,5 +54,4 @@ camera selection, and identity. Pin accepted views and takes through `.svrun` `b
Read `../craft/seedance-directing.md`, `../craft/persona-and-audio.md`, `../craft/captions.md`,
and `../craft/b-roll.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md b/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md
index 5b826049..2b1428f8 100644
--- a/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md
+++ b/.agents/skills/hypit/references/playbooks/formats/voiceover-desk-demo.md
@@ -34,12 +34,9 @@ screen, product, hand, or proof changes.
5. Build each visual beat from supplied media or the vendored `broll-v1` Kit. Generated desk/screen
shots use `seedance:FrameVideo` or `seedance:ReferenceVideo` with `generate-audio="false"`.
6. Place visuals by the measured Script Selections/Moments.
- The base is meant to stay hidden, so the covering Selections tile the Segment: its first word
- opens one, its last word closes one, and nothing falls between. Join them with the Script's
- absorbing markers — `../craft/generated-dependencies.md` holds the table. A gap shows the
- speaker for half a second in a program that has none.
- One sentence may span several visual
- cuts, and one visual may cover only part of a sentence.
+ The base is meant to stay hidden, so the covering Selections tile the Segment —
+ `../craft/generated-dependencies.md` states that rule and holds the marker table. One sentence
+ may span several visual cuts, and one visual may cover only part of a sentence.
7. Add editorial explanation with `typo:Track`; add the complete Caption chain only when narration
captions are wanted. Normalize only additional BGM/SFX before placing them on `audio:Track`.
@@ -69,5 +66,4 @@ screen, product, hand, or proof changes.
Read `../craft/screen-demo.md`, `../craft/b-roll.md`, `../craft/seedance-directing.md`,
`../craft/persona-and-audio.md`, `../craft/captions.md`, and `../craft/sfx.md`.
-That list is complete: `../index.md` does not repeat it, and the craft its required load
-order marks always-read is required regardless of format.
+That list is complete, and the always-read craft in `../index.md` applies regardless of format.
diff --git a/.agents/skills/hypit/references/playbooks/index.md b/.agents/skills/hypit/references/playbooks/index.md
index 584399a8..a36fc6fb 100644
--- a/.agents/skills/hypit/references/playbooks/index.md
+++ b/.agents/skills/hypit/references/playbooks/index.md
@@ -6,9 +6,9 @@ needed for that craft or format.
## Required load order
-1. Always read `craft/production-gates.md`, `craft/frame-coverage.md`,
- `craft/visual-continuity.md`, `craft/graphic-compositions.md`, and
- `craft/generated-dependencies.md`.
+1. Always read `craft/frame-coverage.md`, `craft/visual-continuity.md`,
+ `craft/graphic-compositions.md`, and `craft/generated-dependencies.md`. Each route file names the
+ step that reads them.
2. Read `craft/seedance-directing.md` whenever the Author Source invokes Seedance.
3. Read the selected format file and only the additional craft files **its own footer** names.
That footer is the complete list; this index does not repeat it, and a footer that is wrong is
@@ -18,7 +18,7 @@ needed for that craft or format.
No document a whole job needs may be reachable only through a conditional file. Craft and format
files are selected per job; a spine is walked by every job on its route, so anything every job needs
-is named by `../original-authoring/index.md` or `../reconstruction/index.md` rather than by a craft
+is named by `../original-authoring/route.md` or `../reconstruction/route.md` rather than by a craft
file that some jobs never open.
## Shared SVML contract
@@ -61,7 +61,6 @@ file that some jobs never open.
## Craft
-- `craft/production-gates.md` — staged Targets, image review, paid generation, and explicit reuse.
- `craft/visual-continuity.md` — identity, shot groups, reverse-view geometry, and prop invariants.
- `craft/graphic-compositions.md` — what counts as a base picture, full-screen graphic compositions,
and where missing material comes from.
@@ -95,5 +94,4 @@ file that some jobs never open.
Each format file's own footer is the single authority for the additional craft that format needs.
This table routes; it does not require. **An inventory may carry descriptions, and may not carry
requirements.** A stale description misroutes and the first line of the file it opens corrects it; a
-stale requirement is silently unmet and nothing corrects it, which is what the craft column that used
-to sit here did in seven of these nine rows.
+stale requirement is silently unmet and nothing corrects it.
diff --git a/.agents/skills/hypit/references/reconstruction/evidence.md b/.agents/skills/hypit/references/reconstruction/evidence.md
new file mode 100644
index 00000000..6e7263cc
--- /dev/null
+++ b/.agents/skills/hypit/references/reconstruction/evidence.md
@@ -0,0 +1,157 @@
+# 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. `make-placeholder` writes the mocks a comparison render needs;
+`reconstruction-loop.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.
+
+A reference is found from the Distribution rather than from where you are standing, so these commands
+may be run from anywhere. What does depend on where you are is which packages resolve: name the
+project with `--package-root` when the command is not run from inside it. `paths` reports both roots
+and every prepared reference, which is what to run when a command reports something it cannot see.
+
+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 comes from
+`estimate:Speech`, as `final-sources.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` and prepares everything else; run `hypit runtime up` for the
+project's selected Profile and prepare again. `../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; `reconstruction-loop.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 `reconstruction-loop.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 one to three `--shot-id` values, answers only that
+question from those shots' clips and frames in a single request, and neither reads nor writes the
+observation cache:
+
+```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}`. 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.
+
+## 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 to three
+relevant shots 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/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.md
index 63939e9a..3712b948 100644
--- a/.agents/skills/hypit/references/reconstruction/final-sources.md
+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md
@@ -66,6 +66,6 @@ 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 `reconstruction-loop.md`, and that work ends
-on `reconstruction_check` (`index.md` holds the command), which refuses to pass while any drawing
+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/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.md
deleted file mode 100644
index 99935aab..00000000
--- a/.agents/skills/hypit/references/reconstruction/index.md
+++ /dev/null
@@ -1,222 +0,0 @@
-# Reference-video reconstruction route
-
-This route reconstructs a complete reference video as usable `main.svml`, `recipes.svs`, and
-`build.svrun`. The main agent owns all decisions and source code. Observation is a separate job with a
-separate output: natural-language evidence about what the reference shows, written before and apart
-from any decision about what to build. `observers.md` says who does that job — Gemini, or you reading
-pictures — and the boundary holds either way.
-
-## What this route delivers, and what it does not
-
-The deliverable is **the components the video needs, the three source files, and the Runtime Profile
-that binds what they demand**, and it must be **wired**: the preview check proves every track the
-sources declare traces to the Film, so the author's first Build is not spent discovering that it
-never could have. Every generation the Source declares is declared, not performed: no Build is
-submitted for the pictures, and no video generation, speech synthesis, alignment or final render is
-run. Those belong to a later step that the author starts deliberately, after reading what was
-written.
-
-Seeing the reconstruction is what the author's first Build is for: Studio opens a Run whose material
-is satisfied, and until that Build runs this one's is not. What is *not* deferred is that the graph
-traces, which is the part a Build cannot repair.
-
-One exception, because it is not a generation of the video: a component's own surface — the field its
-elements are drawn on, whatever that is — is produced while the package is authored, with
-`hypit image`, and committed inside the package. `../playbooks/craft/generated-dependencies.md` draws
-that line.
-
-**That exception covers the component's surface and nothing else.** Every other picture the video
-shows — the inner picture of a card, an inserted screenshot, a thumbnail, a product shot, a logo
-wall, a phone or monitor's content — is the video's content, and content is **declared in
-`main.svml` as a generation**, never produced with `hypit image` into an assets directory and
-referenced as a file:
-
-```svml
-<copy:Value id="meme-look">A screenshot of a vertical social-media post…</copy:Value>
-<gpt:Image id="meme-shot" prompt={meme-look} aspect-ratio="4:5" resolution="2K"/>
-```
-
-Writing `<media:Image src="./assets/meme.png"/>` instead spends money this route is not supposed to
-spend, and loses the thing that mattered: the prompt. A declared generation carries its own
-description in the Source, so it can be reread, corrected and rebuilt; a PNG on disk carries nothing,
-and the next person has to invent the prompt again. `media:Image` is for material the author
-supplied, not for material you generated a moment ago.
-
-Reference observation is part of the work and is expected to cost what it costs.
-
-## A requested change is made after the reconstruction is complete
-
-The author often wants the result to differ from the reference: their presenter rather than the one
-in the video, their product rather than the promoted one, their brand. Reconstruct the reference as
-it is anyway, all of it, and then read what you wrote and change it to what they asked for.
-
-The reason is that the reconstruction is checkable only while it claims to reproduce the video that
-was observed. The observations describe the reference and are cached, and `compare_reconstruction`
-judges a rendered element against the reference. Author the change into the sources early and the
-evidence describes one video while the sources describe another, which leaves the reconstruction with
-nothing to be checked against while it is still being written.
-
-Afterwards the sources are yours to change. You wrote every one of them, and the identity of each
-recurring person and product is already a single anchor in them, because
-`../playbooks/craft/persona-and-audio.md` and `../playbooks/craft/visual-continuity.md` required that
-while you were writing.
-
-## A video path is the whole request
-
-The author gives one thing: the path to a video. Not a working directory, not a project name, not
-which packages to use, not where to put the result — those are yours to decide, and asking for them
-is asking the author to do your job. Everything this route needs beyond the video path is
-discoverable:
-
-- **Where you are, and what is installed.** `../environment.md`.
-- **Where the project goes.** Its own directory outside the installed Distribution, normally
- `<home>/<something>-reverse/`, named after the video. `../runtime.md` defines the hard boundary.
- Use a directory the author named only if they named one. Give it a `package.json` when you create
- it — a name and `"private": true`, nothing else, since no field in it is read. `hypit check`,
- `plan` and `build` find the package root by walking up from the project until a `package.json`
- appears, so the file is what stops that walk at the project and lets `packages/local-<slug>/`
- resolve. It is matched by no `pnpm-workspace.yaml` glob, so it enrolls the directory in nothing.
-- **Credentials.** A project may keep them in an uncommitted `.env`; load it as shown below. A variable a Provider
- needs and this machine does not hold is named, and the route stops there — with one exception, the
- Vertex pair, which selects an observer rather than blocking one. `observers.md` owns that.
-
-Ask the author about the video and nothing else: what it is for, who is in it, what it should say.
-Those answers describe the result they want rather than the reconstruction; record them and apply
-them once the reconstruction is complete. Never interrupt to ask which generator, which package,
-which directory, or whether to proceed.
-
-## Before the first command
-
-Ask the author which observer reads the reference, and ask it before anything runs. `gemini` uploads
-the video to Vertex and hears it; `agent` hands each observation to you as a picture to read and needs
-no credentials. Read `observers.md` first: it says what each one costs in the terms the author needs
-to choose between them, how to report what this machine holds rather than asking them to recall it,
-and what the `agent` observer can and cannot answer. The answer is passed once, as `--observer`, and
-the reference keeps it.
-
-When the Vertex credentials are absent, `agent` is what can run — say that, say that it reads the
-reference a little less closely, and take the author's answer. Then say which observer is reading,
-before the evidence starts. Both are in `observers.md`, which also says to give each observation to
-its own subagent where the harness has them: that is what makes the sweep parallel rather than serial,
-and what keeps the observations independent of one another.
-
-This is the only question this route asks about how it runs, and it is asked once, before the evidence
-starts.
-
-A project that keeps its credentials in a `.env` file does not load it automatically. Load it into the
-environment first — the `gemini` observer needs the Vertex pair, and either observer may still need
-credentials for the generation the author starts later:
-
-```bash
-set -a && source .env && set +a
-```
-
-`../credentials.md` lists which variables each Provider needs.
-
-## Start the evidence before you read
-
-`prepare_reference` and the full `observe_reference` sweep take several minutes and need none of the
-knowledge below: their prompts are fixed, and nothing you are about to read changes what they ask.
-Start them first and read while they run. Reading first and observing afterwards makes the same run
-several minutes longer for nothing. This is not the whole command order — `workflow.md` names the
-sequence — it is specifically that the observation sweep must not wait on the reading. `list_svml_packages`
-is an instant directory read that runs independently at the step the sequence names; it neither
-delays the sweep nor is delayed by it.
-
-```bash
-hypit-reference-video-tools prepare_reference --video-path <path> --observer <chosen> # about a minute
-hypit-reference-video-tools observe_reference --reference-id <id> # run in the background
-```
-
-On the `agent` observer both commands return immediately with the observations they owe, and reading
-the files below is what you do between answering them. Answer `prepare_reference`'s four first:
-`observe_reference` quotes them into every shot's question and refuses to run until they exist.
-
-Then read the files below while the sweep is working, and collect its result when you are done.
-
-Before acting on the evidence, read these files completely in order:
-
-1. `observers.md` — which observer is reading, what it is handed, and what it cannot answer. It is
- first because the answer to its question was needed before any of this ran, and because every file
- below describes evidence it shapes.
-2. `workflow.md` — CLI sequence, evidence flow and responsibility boundaries.
-3. `continuity.md` — mandatory shot, overlay, B-roll, speaker, product and persistent-system rules.
-4. **Every craft file listed in the first item of `../playbooks/index.md`'s required load order — the
- ones it marks always-read.** That list decides *which* files, and it grows: one added there is
- required here from the moment it is added, whether or not it appears among the notes below.
- Restating the set in this file is what once left a required craft file reachable from one route
- and invisible to the other.
-
- Its paths are written from `../playbooks/`, so a file it names as `craft/<name>.md` is
- `../playbooks/craft/<name>.md` from here. Only that list's first item is meant: the same section goes on
- to name Seedance directing, a format file and package READMEs conditionally, and none of those
- conditions can even be evaluated before the evidence is in.
-
- Read them in the order below, which is this route's rather than that list's — a reconstruction
- needs to know what a picture *is* before what one generation owes another, and needs both long
- before a Build is staged:
- - `../playbooks/craft/graphic-compositions.md` — what may be a base picture, when a full screen is
- one authored composition, and where a missing picture comes from.
- - `../playbooks/craft/generated-dependencies.md` — what one generation owes another: the location,
- the split picture, the voice, the first frame, and the stretch too short to be a take.
- - `../playbooks/craft/frame-coverage.md` — what is on screen at every instant, and the edges
- nobody chose.
- - `../playbooks/craft/visual-continuity.md` — recurring anchors as explicit artifacts, one
- location generated once, and the reverse-view geometry that must hold across takes.
- - `../playbooks/craft/production-gates.md` — images and takes generate and are reviewed in rounds,
- and accepted Records are pinned for reuse.
-
- A file that list names and this one does not is read last, before `vocabulary.md`.
-5. `../vocabulary.md` — how a package is chosen for any route: enumerate every system before naming
- one, what `list_svml_packages` and `inspect_svml_vocabulary` report, reuse before compose before
- declaring a gap, and what a real gap obliges.
-6. `vocabulary.md` — what the reference evidence adds to that: enumerating from the observations, and
- measuring an appearance value rather than choosing it.
-7. `../preview.md` — proving the Run traces before a Provider is reached, and rendering one element
- without paying for it. Both are used later, by `final-sources.md` and
- `reconstruction-loop.md`; read them here so neither arrives as a surprise.
-
-Two more are required, at the point where they apply rather than now. Reading them here means
-reading them half an hour before they matter, with a dozen other files in between:
-
-- `final-sources.md` when the components exist and the sources are about to be written.
-- `reconstruction-loop.md` **as soon as the sources place an element** — that is the first moment the
- loop has something to render, since what it compares is the element configured the way this video
- configures it. No Build is submitted on this route, so a trigger worded around one never fires; a
- trigger worded around a package's catalogue preview fires too early, before any Source exists to
- read values from.
-
-This route ends on a command rather than on a judgement that the work looks done. Every element the
-Source places that draws a Track must have been compared against the reference at least once, and
-that is checkable:
-
-```text
-hypit-reference-video-tools reconstruction_check projects/<name>/build.svrun
-```
-
-It names each element that has never been compared and the command that compares it, and reports
-`"passed": false` until none are left. It asks for participation rather than convergence —
-`reconstruction-loop.md` is deliberately bounded and may stop with visible differences remaining — so
-an element compared once and stopped at its ceiling passes, and an element nobody looked at does not.
-
-The same command settles one thing about the picture that a Build would otherwise be the first to
-show: it reads each timed picture's appearance Recipe and refuses a `playback` left at its default,
-which draws generated material once and then draws nothing for the rest of the window.
-`../playbooks/craft/generated-dependencies.md` says what to set and why the material's length cannot
-be relied on.
-
-It uses a prepared reference, and how it picks which one is worth knowing before it is run:
-
-- exactly one reference is prepared → it uses that one;
-- several are prepared → it demands `--reference-id <id>`, and refuses without it;
-- none → it refuses, telling you to run `prepare_reference` first.
-
-A comparison run without `--element` is not credited to any element, and a misspelled `--element`
-credits nothing either — it reports logged element names that do not exist in the Source. Which
-package draws an element makes no difference to the requirement: a Track from installed vocabulary
-carries authored values exactly as a project-local one does — a caption Style's size, colour and
-placement — and `render_element` stands in for the speech, so it renders before a Build like any
-other. A project that places no drawing element passes with nothing to require.
-
-Paths above are relative to this file's directory. Do not skip a file because the task looks like a
-familiar video format.
diff --git a/.agents/skills/hypit/references/reconstruction/observers.md b/.agents/skills/hypit/references/reconstruction/observers.md
index f2129b1d..5bbce490 100644
--- a/.agents/skills/hypit/references/reconstruction/observers.md
+++ b/.agents/skills/hypit/references/reconstruction/observers.md
@@ -49,7 +49,7 @@ The author reads the observations, the sources and eventually the video. Which o
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:
-`index.md` still owns the working directory, the project location, the vocabulary and the generators.
+`route.md` still owns the working directory, the project location, the vocabulary and the generators.
## The protocol is one loop
diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
index 6422d520..8cccb384 100644
--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
@@ -28,7 +28,7 @@ temperature of `1.0` buys paraphrase drift and another bill, so never re-run a c
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. `workflow.md` says when an observation is worth doubting and how to settle it: a
+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.
@@ -280,17 +280,16 @@ then source usage. Fixing source usage over a broken implementation hides the de
**There is one comparison round.** What it returns is the whole difference set this reconstruction
gets. Repair against that set and stop; do not compare again. This bounds the comparing, and nothing
else: a narrow `observe_reference --question` settles disagreeing evidence at any point, which is
-what `workflow.md` is for.
+what `evidence.md` is for.
The reference has nothing further to say after it: 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:
-`../playbooks/craft/production-gates.md` Gate 4 measures the delivery, and the section at the end of
-this file says what this route left unchecked. Passing `pnpm check` and `hypit check` is the
-precondition for the round, not a result of it.
+So **a repair is not verified here**, and the honest place to say so is the report: the section at
+the end of this file says what this route left unchecked. Passing `pnpm check` and `hypit check` is
+the precondition for the round, not a result of it.
Two things follow, and they are the whole discipline:
@@ -357,22 +356,21 @@ When there is no next element the reconstruction is complete, and three things f
was watched, because on this route no video exists: the Build has not run. Report the difference
rather than letting the word carry it.
-State plainly, in the completion report, that the following are unverified and name the gate each one
-waits for in `../playbooks/craft/production-gates.md`:
+State plainly, in the completion report, that the following are unverified:
-- **every generated picture and take** — the images and the shots a Provider has still to make, at
- Gate 1 and Gate 2;
+- **every generated picture and take** — the images and the shots a Provider has still to make;
- **the timing of every Track** — this route compares each one against a stand-in SemanticTake, so
how a Caption, Media or Typography Track sits against the speech that is finally delivered is
- measured at Gate 3, against the real SemanticTrack;
+ settled once that speech exists;
- **whether the picture is continuous** — the frames nobody authored that `frame-coverage.md` is
- about, at Gate 4, which measures them on the delivery. One inherited edge is settled before then:
- `reconstruction_check` reads each Recipe's `playback` and refuses an insert configured to stop
- when its material runs out. The rest
+ about. One inherited edge is settled here: `reconstruction_check` reads each Recipe's `playback`
+ and refuses an insert configured to stop when its material runs out. The rest
of them — a window that starts late, a blend whose frames are half-covered, a schedule inside a
- component that stops between activations — are measured on the delivery;
-- **whether the delivery says the Script's words** — measured at Gate 4 by transcribing the finished
- video, since a take generated from a prompt that lost its dialogue passes every gate before it.
+ 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 this route runs.
+ `../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.
`reconstruction_check` is the mechanical half of this: it names the elements that were never compared
and the timed pictures configured to empty their windows, and refuses to pass while either remains.
@@ -380,9 +378,9 @@ It cannot name what a Build has not produced yet, which is why
this list is stated rather than computed.
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. `index.md` says why that
+brand — read the sources you wrote and change them to what they asked for. `route.md` says why that
happens here rather than earlier.
If a project-local package was built along the way, decide whether it should outlive this video and
-put that to the author: `../local-author-package.md` says how to judge it and what promoting it
+put that to the author: `../package-promotion.md` says how to judge it and what promoting it
actually costs.
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
new file mode 100644
index 00000000..4ec4239d
--- /dev/null
+++ b/.agents/skills/hypit/references/reconstruction/route.md
@@ -0,0 +1,340 @@
+# Reference-video reconstruction route
+
+Read a step, do it, read the next one. Each step names the files it needs; read those at that step.
+
+## What this route delivers
+
+The components the video needs, `main.svml`, `recipes.svs`, `build.svrun`, and the Runtime Profile
+that binds what they demand — **wired**, meaning `preview_check` proves every track the sources
+declare traces to the Film. Every generation the Source declares is declared rather than performed:
+no Build is submitted, and no video generation, speech synthesis, alignment or final render runs.
+Those belong to the Build the author starts deliberately, after reading what was written.
+
+Seeing the reconstruction is what that Build is for. What is settled here is that the graph traces,
+which is the part a Build cannot repair.
+
+One exception, because it is not a generation of the video: a component's own surface — the field its
+elements are drawn on — is produced while the package is authored, with `hypit image`, and committed
+inside the package. `../playbooks/craft/generated-dependencies.md` draws that line.
+
+**That exception covers the component's surface and nothing else.** Every other picture the video
+shows — the inner picture of a card, an inserted screenshot, a thumbnail, a product shot, a logo
+wall, a phone or monitor's content — is the video's content, and content is declared in `main.svml`
+as a generation:
+
+```svml
+<copy:Value id="meme-look">A screenshot of a vertical social-media post…</copy:Value>
+<gpt:Image id="meme-shot" prompt={meme-look} aspect-ratio="4:5" resolution="2K"/>
+```
+
+Writing `<media:Image src="./assets/meme.png"/>` instead spends money this route does not spend, and
+loses the thing that mattered: the prompt. A declared generation carries its own description in the
+Source, so it can be reread, corrected and rebuilt; a PNG on disk carries nothing, and the next
+person has to invent the prompt again. `media:Image` is for material the author supplied.
+
+Reference observation is part of the work and is expected to cost what it costs.
+
+## The video path is the whole request
+
+The author gives one thing: the path to a video. The working directory, the project name, which
+packages to use and where the result goes are yours to decide. Ask the author about the video and
+nothing else — what it is for, who is in it, what it should say. Those answers describe the result
+they want; record them and apply them at step 24. Never interrupt to ask which generator, which
+package, which directory, or whether to proceed.
+
+The author often wants the result to differ from the reference: their presenter, their product,
+their brand. **Reconstruct the reference as it is anyway, all of it, and change it afterwards.** The
+reconstruction is checkable only while it claims to reproduce the video that was observed: the
+observations describe the reference and are cached, and `compare_reconstruction` judges a rendered
+element against it. Author the change in early and the evidence describes one video while the sources
+describe another.
+
+---
+
+## Phase 0 — Before any command
+
+### 1. Select the Distribution
+
+```bash
+hypit paths --json
+```
+
+**Read now:** `../environment.md` — the three independent places, Distribution selection, the
+prohibition on a registry install, the launcher substitution rule that makes every
+`hypit-reference-video-tools` string below resolvable in a checkout, and the rule that commands
+sharing reference state run from the same working directory.
+
+**Done when:** an installed CLI or a contributor checkout is selected. If neither is available,
+report that no runnable Hypit Distribution is present and stop.
+
+### 2. Choose the project directory
+
+Its own directory outside the installed Distribution, normally `<home>/<something>-reverse/`, named
+after the video. Use a directory the author named only if they named one. Give it a `package.json`
+with a name and `"private": true`, and nothing else — no field in it is read. `hypit check`, `plan`
+and `build` find the package root by walking up from the project until a `package.json` appears, so
+this file is what stops that walk at the project and lets `packages/local-<slug>/` resolve. It
+matches no `pnpm-workspace.yaml` glob, so it enrolls the directory in nothing.
+
+**Read now:** `../runtime.md` — the hard boundary between a project and a Distribution.
+
+### 3. Load credentials
+
+A project that keeps credentials in `.env` does not load them automatically:
+
+```bash
+set -a && source .env && set +a
+```
+
+**Read now:** `../credentials.md` — which variables each Provider needs. A variable a Provider needs
+and this machine does not hold is named, and the route stops there. The Vertex pair is the one
+exception: it selects an observer rather than blocking one, and step 5 owns it.
+
+### 4. Read the observer question
+
+**Read now:** `observers.md`, down to and including "Say which path is running" — the cost of each
+observer, the credential decision table, the disclosure the author is owed, and the rule that one
+reference has one observer for its whole life.
+
+### 5. Probe for Vertex credentials
+
+```bash
+node .agents/skills/hypit/scripts/check-credentials.mjs GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON
+```
+
+Report what this machine holds rather than asking the author to recall it. Both `set` means `gemini`
+is available and the author chooses. Either one `missing` means `agent` is the path that can run
+today.
+
+### 6. Ask which observer reads the reference
+
+Ask once. Name what each costs, and 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. Say it once, take
+the answer, and run.
+
+**This is the only question this route asks about how it runs.**
+
+### 7. Say which observer is reading
+
+One line, before any evidence starts.
+
+---
+
+## Phase 1 — Evidence, with reading alongside
+
+### 8. List installed vocabulary
+
+```bash
+hypit-reference-video-tools list_svml_packages
+```
+
+It reads `node_modules/@hypit` relative to the working directory and refuses when it is empty, so run
+it from the repository root. Name the project with `--package-root` when the command is not run from
+inside it. This is instant and may run before or during the sweep.
+
+### 9. Prepare the reference
+
+```bash
+hypit-reference-video-tools prepare_reference --video-path <path> --observer gemini|agent
+```
+
+Verify the WhisperX service answered its health probe before running this — a first start can spend
+several minutes loading the model. `../environment.md` says how; `../host-setup.md` covers the
+failure branches.
+
+**Read now:** `evidence.md` — what the four whole-reference observations cover, what `transcript` is
+and how to recover it when it reports `status: "unavailable"`, and the `--redo` values.
+
+**Done when:** the four whole-reference observations and `transcript` exist. On the `agent` observer
+they come back as `pending_observations` for you to answer with `record_observation`; answer those
+four first, because `observe_reference` quotes them into every shot's question and refuses to run
+until they exist.
+
+### 10. Run the full sweep, in the background
+
+```bash
+hypit-reference-video-tools observe_reference --reference-id <reference-id>
+```
+
+**Start this before step 11 and read while it runs.** Its prompts are fixed and nothing in step 11
+changes what they ask. Reading first and observing afterwards makes the same run several minutes
+longer for nothing.
+
+On the `agent` observer, give each task its own subagent where the harness has them and run a pass
+together; that is what makes the sweep parallel. Answering everything one call listed is not the end
+of it — the sweep ends when `pending_observations` and `unresolved` are both empty.
+
+### 11. Read the route's craft, while the sweep runs
+
+Read completely, in this order — a reconstruction needs to know what a picture *is* before what one
+generation owes another:
+
+1. `continuity.md` — shot, overlay, B-roll, speaker, product and persistent-system rules.
+2. `../playbooks/craft/graphic-compositions.md` — what may be a base picture, when a full screen is
+ one authored composition, and where a missing picture comes from.
+3. `../playbooks/craft/generated-dependencies.md` — what one generation owes another: the location,
+ the split picture, the voice, the first frame, and the stretch too short to be a take.
+4. `../playbooks/craft/frame-coverage.md` — what is on screen at every instant, and the edges nobody
+ chose.
+5. `../playbooks/craft/visual-continuity.md` — recurring anchors as explicit artifacts, one location
+ generated once, and the reverse-view geometry that must hold across takes.
+6. `../vocabulary.md` — how a package is chosen: enumerate every system before naming one, reuse
+ before compose before declaring a gap, and what a real gap obliges.
+7. `vocabulary.md` — what the reference evidence adds to that: enumerating from the observations, and
+ measuring an appearance value rather than choosing it.
+
+Do not skip one because the task looks like a familiar video format.
+
+---
+
+## Phase 2 — Interpret the evidence
+
+### 12. Collect the sweep and inspect what failed
+
+`unresolved` lists observations that failed outright. A complete observation that says "unclear" is
+still complete. Be most suspicious of anything an observation asserts about change over time.
+`evidence.md` says why and what to do.
+
+### 13. Settle conflicts with narrow questions
+
+```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?"
+```
+
+One to three shots per question; `--batch <questions.json>` sends several. Ask about visible
+attributes. Never ask which component to use. Do not re-observe a full shot to correct one.
+
+**Done when:** every appearance value that changes what the viewer sees is measured rather than
+defaulted, and every conflict between observations is settled.
+
+### 14. Inspect candidate packages
+
+```bash
+hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--package …]
+```
+
+Enumerate the systems from the observations, then inspect a candidate for each. A system you never
+inspected is a system you are about to invent.
+
+### 15. Develop a project-local package, only for a proven gap
+
+**Read now:** `../local-author-package.md`, completely.
+
+**Done when:** the package installs and `inspect_svml_vocabulary` reads its declaration. A component
+that loads is not yet a component that looks like the reference.
+
+---
+
+## Phase 3 — Author, check, wire
+
+### 16. Write the four files
+
+`main.svml`, `recipes.svs`, `build.svrun`, `hypit.runtime.json`. 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`.
+
+**Read now:**
+
+- `final-sources.md` — Segment boundaries, the forced seam, and take durations from `estimate:Speech`.
+- `../authoring.md` — never invent a component, attribute, child, port, Recipe property or literal
+ value, and how an accepted Record is reused in the Run Source.
+- `../playbooks/craft/captions.md` — Cue breaks, the Recipe keys, and what recomputes when speech
+ changes.
+- `../playbooks/craft/persona-and-audio.md` — one voice sample per person, and the identity anchors
+ that make step 24 cheap.
+- `../playbooks/index.md` and the craft files it names for the systems this reference actually
+ contains. Those conditions can only be evaluated now, with the evidence in.
+
+Do not author one source fragment per shot.
+
+### 17. Check all three sources
+
+```bash
+hypit check path/to/main.svml
+hypit check path/to/recipes.svs
+hypit check path/to/build.svrun
+```
+
+Check all of them. Do not create a check wrapper.
+
+### 18. Prove the graph traces
+
+```bash
+hypit-reference-video-tools preview_check /path/to/project/build.svrun
+```
+
+**Read now:** `../preview.md`.
+
+`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. Neither this gate nor step
+17 is bounded by the loop's attempt ceilings: a graph that does not trace is work that is not done.
+
+---
+
+## Phase 4 — The comparison loop
+
+### 19. Read the loop
+
+**Read now:** `reconstruction-loop.md`, as soon as the sources place an element — that is the first
+moment the loop has something to render.
+
+### 20. Render every stretch of every authored element
+
+```bash
+hypit-reference-video-tools render_element projects/<name>/build.svrun \
+ --element <id> --segment <id>|--selection <id> --reference-id <id> --out <path>.mp4
+```
+
+A whole round is one call: `--batch <renders.json>`. `render_element` calls `make-placeholder` itself
+for the layers a Build has not made.
+
+### 21. Send every comparison for the element at once
+
+```bash
+hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> \
+ --video <path>|--image <path> [--question <scope>] [--element <id>]
+```
+
+**Pass `--element <id>` every time**, or step 23 credits the comparison to nothing. Send all of an
+element's comparisons before repairing anything.
+
+### 22. Repair against the differences that round returned
+
+Within the two ceilings `reconstruction-loop.md` sets. Then return to step 20 for the next element.
+
+### 23. Close the route on the check
+
+```bash
+hypit-reference-video-tools reconstruction_check projects/<name>/build.svrun
+```
+
+It names each element that has never been compared and the command that compares it, and reports
+`"passed": false` until none are left. It asks for participation rather than convergence — the loop
+is deliberately bounded and may stop with visible differences remaining — so an element compared once
+and stopped at its ceiling passes, and an element nobody looked at does not.
+
+It also reads each timed picture's appearance Recipe and refuses a `playback` left at its default,
+which draws generated material once and then draws nothing for the rest of the window.
+`../playbooks/craft/generated-dependencies.md` says what to set.
+
+How it picks a reference: exactly one prepared → it uses that one; several → it demands
+`--reference-id <id>` and refuses without it; none → it refuses and tells you to run
+`prepare_reference`.
+
+A comparison run without `--element` is credited to no element, and a misspelled `--element` credits
+nothing either — it reports logged element names that do not exist in the Source. Which package draws
+an element makes no difference: a Track from installed vocabulary carries authored values exactly as
+a project-local one does, and `render_element` stands in for the speech. A project that places no
+drawing element passes with nothing to require.
+
+**Done when:** `"passed": true`.
+
+---
+
+### 24. Apply the author's requested change
+
+Read what you wrote and change it to what they asked for at step 6. The identity of each recurring
+person and product is already a single anchor, because `../playbooks/craft/persona-and-audio.md` and
+`../playbooks/craft/visual-continuity.md` required that while you were writing.
diff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.md
deleted file mode 100644
index 4c507e82..00000000
--- a/.agents/skills/hypit/references/reconstruction/workflow.md
+++ /dev/null
@@ -1,218 +0,0 @@
-# Reference-video workflow
-
-`@hypit/reference-video-tools` ships seven CLI subcommands. Four of them are the reference evidence
-and belong to this route:
-
-```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>]
-```
-
-`--observer` is answered once, before anything runs, and `observers.md` owns that question.
-`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.
-
-`make-placeholder` writes the mocks the comparison render needs for a base take or a media slot a
-Build has not filled; `reconstruction-loop.md` says when. The remaining two — `list_svml_packages`
-and `inspect_svml_vocabulary` — read installed vocabulary and have nothing to do with a reference
-video. This route runs both, at the step the sequence names;
-`../vocabulary.md` documents them and decides how a package is chosen. `list_svml_packages` reads
-`node_modules/@hypit` relative to the working directory and refuses when it is empty, so run it from
-the repository root.
-
-A reference is found from the Distribution rather than from where you are standing, so these commands
-may be run from anywhere. What does depend on where you are is which packages resolve: name the
-project with `--package-root` when the command is not run from inside it. `paths` reports both roots
-and every prepared reference, which is what to run when a command reports something it cannot see.
-
-Defaults are sufficient for normal use. Each also accepts `--input <json>`. Follow this sequence:
-
-```text
-list_svml_packages
-→ prepare_reference
-→ observe_reference for all shots, in the background — read the route's required
- files while it runs, since its prompts do not depend on anything you read.
- `index.md`'s "start the evidence before you read" is this line, not the whole
- order: `list_svml_packages` is instant and may run before or during the sweep
-→ narrow observe_reference questions for unresolved appearance and conflicts
-→ inspect_svml_vocabulary for candidate packages
-→ develop a project-local package only for a proven vocabulary gap
-→ read final-sources.md, then author complete main.svml, recipes.svs, build.svrun
- and the hypit.runtime.json that binds every capability they demand
-→ use existing checks and repair until legal
-→ run preview_check (final-sources.md) and repair until the graph traces —
- this has no attempt ceiling; a target Studio cannot trace is not done.
- Waiting on unrun Providers is a pass, not a failure
-→ read reconstruction-loop.md, then for each authored element: render every
- stretch it is drawn over with render_element, which reads the sources and
- mocks the layers a Build has not made, then send all those comparisons at
- once, before repairing anything
-→ repair against the differences that round returned, within the ceilings
-→ run reconstruction_check (index.md) and keep going until it passes; it names
- every drawing element that has never been compared, and every timed
- picture whose Recipe leaves playback at its default. When more than one
- reference is prepared it needs --reference-id <id>
-```
-
-## prepare_reference
-
-`prepare_reference` 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 each on-screen text reveal against the line that triggers it, timing a
-caption, checking that a voice observation matches what was actually spoken, or judging a Segment's
-natural boundary. It does not set a take's duration: the take is generated and its length comes from
-`estimate:Speech`, as `final-sources.md` requires. Do not run WhisperX
-by hand and do not ask a model to transcribe: the transcript is already there.
-
-`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` and prepares everything else; run `hypit runtime up` for the
-project's selected Profile and prepare again.
-`../environment.md` covers diagnosing that service and the rest of the local toolchain 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.
-
-## 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, not only the things that sit on top with
-an edge. A wash laid over the whole frame to darken it is covering content and gets reported as such;
-so is anything else the observation happens to describe 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, not 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.
-
-## 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 already 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
-`observe_reference --question` over that shot, which puts the question to the reference's own
-observer; several at once is `--batch <questions.json>`, an array of `{shot_ids, question}`. On the `gemini` observer that means you do not open the frame yourself;
-`reconstruction-loop.md` says which rule binds on which path. Do not re-observe
-the full shot: that is paid, and at temperature `1.0` it returns a paraphrase rather than a
-correction.
-
-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, rather than by believing the single pass that asserted it. A
-`compare_reconstruction` against a quick rendered probe works too, and is a probe rather than the
-element comparison `reconstruction-loop.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 one to three `--shot-id` values, answers only that
-question from those shots' clips and frames in a single request, and neither reads nor writes the
-observation cache:
-
-```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?"
-```
-
-Ask about visible attributes. Never ask which component to use.
-
-## compare_reconstruction
-
-`compare_reconstruction` sends the reference and the reconstruction as an unlabelled pair and returns
-a description of their visible differences. It is never told which is which, what was built, or how;
-`--question` carries what to look at — which region to read, which regions hold a placeholder to
-skip, or one visible quantity to measure — and never what to conclude. Results are not cached. `reconstruction-loop.md` governs when and how to use it.
-
-Which stretch of the reference the pair is cut from is named one of two ways. `--segment` and
-`--selection`, with the Run as `--run`, name a word range: the reference is cut from its own analysis
-video at the seconds it speaks those words, which is the stretch a render covers, and the rendered
-clip is trimmed by however far each end moved onto a shot boundary so both sides show the same word
-at the same offset. `--shot-id` names a cut in the picture and compares that whole shot.
-
-`--video <rendered.mp4>` compares the whole stretch and is the default choice, since a stretch can
-hold several states of an element without a cut and no single frame stands for it. `--image` is for
-the one case where the reference's own `visual:` observation says the element is completely still.
-Which pictures the pair is made of follows the observer: `gemini` receives the two clips; `agent`
-receives two frame tiles built against the compared stretch's own duration, so both grids sample
-alike.
-
-`--element` names the reconstructed element the render draws. It never reaches the observer — the
-comparison stays as blind as it is without it — and is written to the reference's `comparisons.jsonl`
-so `reconstruction_check` can tell an element that was looked at from one that never was. A
-comparison run without it is not credited to any element.
-
-The reference has one observer for its whole life, and this command goes through the same one that
-wrote its observations. On the `gemini` observer that observer is not you, and opening the reference
-frame yourself is what `reconstruction-loop.md` forbids; on the `agent` observer it is you, and that
-file names the discipline that takes the place of blindness.
-
-## 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, not 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 to three
-relevant shots 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/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.md
index 88fbb771..799611a2 100644
--- a/.agents/skills/hypit/references/runtime.md
+++ b/.agents/skills/hypit/references/runtime.md
@@ -171,6 +171,6 @@ Relative Author Sources and assets stay inside the independently resolved Source
`plan` and `build` walk up from the project until one appears, so a project without one resolves
its packages against an ancestor directory, and a project package resolves to nothing. Run those
commands with `--package-root .` from the project, or write the project the `package.json`
- `../environment.md` describes and drop the flag.
+ `environment.md` describes and drop the flag.
- Do not symlink an external project into the Distribution. The external directory is the intended
workspace, not an escape from one.
diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.ts
index c204509d..5e199437 100644
--- a/packages/reference-video-tools/src/authoring.ts
+++ b/packages/reference-video-tools/src/authoring.ts
@@ -269,7 +269,7 @@ const SILENT_AUDIO: BlobRef = { kind: "blob", digest: `sha256:${"0".repeat(64)}`
*
* Word ranges and Recipe values are exact on either clock, so which elements are on screen together,
* where each sits, at what size and colour follow from the Source itself. Alignment against the
- * speech a Build synthesizes waits for `production-gates.md` Gate 3.
+ * speech a Build synthesizes is settled once that speech exists.
*
* @param svmlPath the Author SVML this Source is written in
* @param frameRate the Program's frame rate, as a whole number of frames per second
@@ -829,8 +829,8 @@ function timingReport(reference: string | undefined, segments: readonly StandInT
*
* What this settles: which elements are on screen together, where each sits, at what size, weight and
* colour, and — on a reference-timed stand-in — how long each of them has to arrive in. What it does
- * not: alignment against the speech a Build synthesizes, which waits for
- * `playbooks/craft/production-gates.md` Gate 3. `timing` in the result, and the sidecar written
+ * not: alignment against the speech a Build synthesizes, which is settled once that speech
+ * exists. `timing` in the result, and the sidecar written
* beside the output, name which of the two clocks sized each Segment.
*/
export async function renderElement(input: RenderElementInput): Promise<Record<string, unknown>> {
diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.ts
index e74f3ea0..49efb061 100644
--- a/packages/reference-video-tools/src/checks.ts
+++ b/packages/reference-video-tools/src/checks.ts
@@ -456,12 +456,8 @@ function framesPastTheCanvas(svml: string): readonly OutOfBoundsFrame[] {
* comparison is a comparison. What it says is which elements have had their behaviour over their
* window looked at and which have only had their layout looked at.
*
- * Where each Frame sits is decided from the Source alone and is reported rather than required. A
- * Frame with an edge outside 0%–100% of its Canvas puts that much of whatever is drawn into it off
- * the picture, and a comparison cannot see it: the render and the stand-in are drawn at the same
- * Canvas, so both put the element in the same place off the edge and agree. Reaching past the edge is
- * also how an element slides in from off-screen and how a full-bleed picture is cropped by a `fit`,
- * which look identical here, so `passed` does not depend on it.
+ * Where each Frame sits is decided from the Source alone and is reported rather than required.
+ * `framesPastTheCanvas` above says why an overhang cannot decide `passed`.
*
* Frame coverage is decided from the Source alone and is required: a word is either drawn over by
* something bound to the whole picture or it is not. What covers is read from an element's own
@@ -946,7 +942,7 @@ export async function reconstructionCheck(
...(never.length === 0 ? {} : {
never_compared: {
ids: never.map((element) => element.id),
- next: "Read .claude/skills/hypit/references/reconstruction/reconstruction-loop.md, then for each: "
+ next: "Read .agents/skills/hypit/references/reconstruction/reconstruction-loop.md, then for each: "
+ "render the element as the Source configures it, mock the layers a Build has not made, "
+ "and compare the whole stretch blind — one comparison per Segment or Selection it is drawn over.",
commands: never.map((element) =>
@@ -1006,8 +1002,8 @@ export async function reconstructionCheck(
+ "Re-render each of these with render_element --reference-id "
+ `${reference} and compare again: the reference's own transcript times every Segment whose words `
+ "it carries, so each window runs for as long as the reference spends on it. What is left after "
- + "that is alignment against the speech the Build synthesizes, which is measured at "
- + "playbooks/craft/production-gates.md Gate 3.",
+ + "that is alignment against the speech the Build synthesizes, which is settled once that "
+ + "speech exists.",
commands: untimed.map((element) =>
`hypit-reference-video-tools render_element ${runPath} --element ${element.id} `
+ `--reference-id ${reference} --segment <the Segment the shot covers> --out <rendered clip>.mp4`),
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index be936d59..892dba8e 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -114,10 +114,6 @@ function usage(): string {
"with `--seconds` choosing its length (default 1). Never produce the mock with `hypit image` or a",
"script written by hand.",
"",
- "--element names the reconstructed element the image draws. It is written to the reference's",
- "comparison log and never sent to the observer, so the comparison stays blind while a later gate can",
- "still tell which elements have been compared.",
- "",
"record_observation takes the keys the agent observer is handed: the four whole-reference keys, a",
"shot key such as visual:003 or boundary:004, a narrow question keyed by the shots it was asked over",
"(question:003+004), and a comparison keyed by the `comparison_id` compare_reconstruction returned",