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: route Hypit skill through focused references

rponeb15be982b48c
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 81b6b483..a7e0dc1b 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -1,192 +1,32 @@
---
name: hypit
-description: Author, check, plan, build, inspect, and retrieve Hypit/SVML video sources; configure the cross-platform Node/pnpm/Python runtime and API keys; reconstruct reference video directly as .svml/.svs/.svrun sources; and apply native SVML production playbooks for prompts, continuity, captions, B-roll, overlays, audio, and common video formats. Use for the Hypit repository, its quickstart, SVML authoring, runtime profiles, reference-video reconstruction, or video craft decisions.
+description: Author, check, preview, build, inspect, and retrieve Hypit/SVML projects; configure runtimes and credentials; reconstruct reference videos; develop missing project-local author packages; and apply native video production playbooks. Use for the Hypit repository, SVML/SVS/SVRun authoring, reference-video reconstruction, package vocabulary, runtime operations, or video craft decisions.
---
# Hypit
-Use this entrypoint for work in the `hypit` repository. Keep `.svml` Author Source, `.svrun` Run
-Source, and the declarative `hypit.runtime.json` Runtime Profile separate.
-
-## Route the task
-
-- Environment/setup or API keys → read `references/environment.md` and `references/credentials.md`.
-- SVML authoring → read `references/quickstart.md`, then the linked authoritative page under
- `docs/quickstart/`.
-- Seedance prompt assembly → read `references/seedance-kits.md`; reuse an official vendored Kit and
- SVS Recipe before writing format scaffolding by hand.
-- Production craft or format choice → read `references/playbooks/index.md`,
- `references/playbooks/craft/production-gates.md`, and
- `references/playbooks/craft/visual-continuity.md`, then the relevant craft/format file.
-- Reference-video reconstruction → read `references/reference-vlm.md`; use the three reference-video
- CLI commands, then author `main.svml`, `studio.svs`, and `build.svrun` yourself.
-- Showing an author what they have so far → start the SVML Playground and send them the link.
- See "Show the work" below.
-- Execution, Runtime control, Build inspection, or output retrieval → read
- `references/runtime.md`; diagnose and start the durable Runtime, `check` Author Source, `plan`
- before paid work, then submit, inspect, and retrieve the Build.
-
-## Reference-video reconstruction workflow
-
-When the user asks to reproduce, reverse, reconstruct, or analyze a reference video, this is a
-tool-driven task rather than an ordinary hand-authored video task.
-
-1. Read `references/reference-vlm.md` completely.
-2. Run the `prepare_reference` CLI command with the local video path.
-3. Run the `observe_reference` CLI command for the full reference. It prepares the previous tail frame, previous
- audio tail, whole-reference people, voice, and product context automatically and observes shots
- in parallel.
-4. Read every failed or unresolved observation. Run `observe_reference` with a narrow follow-up only
- where evidence conflicts or remains uncertain.
-5. Choose the packages needed by the observed video and run `inspect_svml_vocabulary` before
- writing any component, attribute, child, port, or Recipe.
-6. Decide whether existing packages can express every observed behavior. Prefer composing existing
- packages when their declared Types, time behavior and outputs are sufficient. If no legal
- composition can express an observation, follow "Develop a missing local component" below before
- writing a tag for it.
-7. Write one complete `main.svml`, one `studio.svs`, and one `build.svrun`. Do not write one partial
- SVML fragment per shot and concatenate them.
-8. Run the existing `pnpm hypit check` command and repair the package or sources until the project
- is legal.
-
-Gemini is only the eyes and ears. It returns natural-language evidence, never SVML, SVS, SVRun,
-component declarations, prompts containing package syntax, or a final structural decision. The
-calling agent owns the synthesis and all final files.
-
-The reconstruction invariants are mandatory:
-
-- The person who is speaking owns base; the lowest or largest picture does not.
-- Picture ownership and sound ownership are separate. Full-screen B-roll can cover the picture
- while the previous speaker remains the sound owner and base.
-- A B-roll person who appears to speak but whose B-roll is silent cannot take over the speaker,
- sound, or base.
-- A shot with no visible person can still carry the previous speaker's continuing sound.
-- The same overlay continuing across a cut remains one visual track; a cut alone never creates a
- replacement overlay.
-- Merge incorrectly split continuous shots only when the observations confirm one shot and the
- combined duration is at most 15 seconds. Three-shot continuity requires explicit evidence too.
-- Reuse the full-reference people, voice, and product evidence. Describe a promoted product once;
- do not invent a new product description in every shot.
-
-## Develop a missing local component
-
-This branch is part of reference reconstruction, but it is ordinary Hypit package development, not
-a VLM capability. `reference-video-tools` must remain limited to preparation, observation and
-vocabulary inspection. Do not add a component generator command to it.
-
-Enter this branch only after comparing the observation against the selected packages' README and
-the complete `inspect_svml_vocabulary` result. Prefer a composition of existing components. Do not
-force a similar-looking tag to express behavior its declaration does not own, and do not write an
-unknown tag into `main.svml` before its package exists.
-
-Before creating the package, read these sources completely:
-
-1. `docs/guide/author-packages.md`
-2. `docs/guide/packages.md`
-3. `docs/guide/conventions.md`
-4. `packages/component-kit/README.md`
-5. The README, Manifest, Surface, Component and activation files of the closest existing package
-
-Create one new package under the current project's `packages/local-<slug>/`. The physical and
-logical name is `@hypit/local-<slug>`, the physical version is `0.0.0-dev`, and Module identities
-use logical version `1`. The package is project-local even when the current project is the Hypit
-checkout. Never edit, delete, extend or overwrite an existing package to fill this gap, and never
-ask for permission merely to create this new local package once the gap is established.
-
-The main agent, not Gemini, writes the package. Gemini must not receive or produce TypeScript,
-`package.json`, Manifest, Surface, Producer, Validator, package syntax or implementation code. Use
-its natural-language observation only as evidence for the component's required behavior.
-
-Implement the complete package rather than a syntax stub. Include the package manifest and README,
-Module Manifest and Types, every required Producer and Validator, Markup Surface declaration and
-decoder, activation contribution, and the necessary lowering, Fragment or render implementation.
-Add a preview for a visual Surface. Decide raw versus structured Surface, timing dependencies,
-ProgramSpace, Frame, SemanticMap, Artifact, Recipe and output Types from the observed behavior and
-the closest package architecture; do not copy a fixed template blindly.
-
-Connect the new package through normal Node package resolution:
-
-- Reuse the current project's workspace configuration when it already includes `packages/*`.
-- Otherwise add the smallest `pnpm-workspace.yaml` and package dependency changes that include the
- new package.
-- Add the local package as a `workspace:*` dependency where the project's package root can resolve
- it, then run the necessary `pnpm install`.
-- Run `pnpm check`, followed by the existing `pnpm hypit check` for `main.svml`, `studio.svs` and
- `build.svrun`. Use `--workspace` or `--package-root` only when the project layout requires them.
-- Repair package resolution first, then activation, Manifest/implementation agreement, Surface
- decoding, Producer/Validator behavior, and finally the three project sources.
-
-The package is complete only after the existing checks accept it. Never create a check wrapper.
-After the reconstruction is accepted, tell the user that the local package can be moved into the
-official Hypit repository as a separate contribution if they want to keep it generally available;
-do not perform that promotion automatically.
-
-## Read the package README before writing its syntax
-
-Before writing any element from a package, read that package's README. The import
-`@hypit/<name>@1` is `packages/<name>/README.md` — every package that defines SVML elements has
-one, and it is the authority on that package's components, attributes, and ports.
-
-Never write a component or attribute you have not seen in that file, and never infer one package's
-syntax from another that looks similar. Two packages covering neighboring ground rarely take the
-same attributes.
-
-## Ordinary loop
-
-```bash
-cd path/to/project
-hypit runtime use hypit.runtime.json
-hypit plan build.svrun
-hypit build build.svrun --follow
-hypit inspect <build-id>
-hypit get <build-id> \
- --name final.video --to output/final.mp4
-```
-
-Install dependencies after import or Runtime package selections change. Use `check` while editing and
-`doctor` for deployment setup or diagnosis; do not impose either as ceremony before every Build.
-
-Treat `--follow` as an observer: stopping it does not stop the durable Build. Use `runtime down`
-to stop only the Worker; use `programs down` separately when external programs should also stop.
-Neither command cancels Builds or remote Provider work.
-
-After submitting without `--follow`, or after leaving an observer, reattach with
-`hypit status <build-id> --watch`. A plain `status` remains a one-time snapshot.
-
-Every `build` invocation receives a fresh automatic Build id. Never try to reclaim a prior Build by
-restoring Source bytes or choosing an id. Cross-Build reuse exists only through explicit
-`build-record` Candidates in a new Run Source.
-
-Reuse any accepted generated image or take in the next `.svrun` with `build-record` plus `satisfy`,
-then review the frozen plan before paid downstream work. Candidate selection has no Pin state or
-fidelity label.
-
-## Show the work
-
-After each step that changes a Source — a Script edit, a Frame moved, a B-roll placed, a Recipe
-adjusted — start the Playground and give the author the link. Reading a diff is not the same as
-seeing where a cutaway lands, and a Source draws before any Provider has run: an unmade shot stands
-in as the picture it names, held for the length it declares.
-
-```bash
-pkill -f svml-playground || true # never leave the old one holding the port
-pnpm svml:playground -- --source path/to/main.svml \
- --run path/to/build.svrun \
- --runtime path/to/hypit.runtime.json &
-# then send the author: http://localhost:5179/
-```
-
-Kill the previous server first. A second one silently picks another port, and the author ends up
-looking at a stale preview while you describe a new one. Pass `--port` only when the author asked to
-compare two Sources side by side, and send the port you actually used — read it from the startup
-line rather than assuming `5179`.
-
-Both extra arguments are optional and each answers one question. `--run` says which material and
-which timings to read the Source with. `--runtime` says where material earlier Builds produced is
-kept, and is needed only by a Source that reuses an accepted shot through `<build-record>`; without
-it that one shot is refused by name and everything else still draws.
-
-`docs/quickstart/preview.md` is the page to point an author at.
-
-Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of commits.
-The repository's docs remain the syntax authority.
+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.
+
+Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, and
+`hypit.runtime.json` Runtime Profile as separate languages and responsibilities.
+
+## Route
+
+- Reference-video reconstruction, reverse engineering, shot/B-roll/overlay analysis, or recreating
+ a video as Hypit source → read `references/reference-video/index.md`.
+- Ordinary SVML/SVS/SVRun authoring or syntax selection → read `references/authoring.md`, then
+ `references/quickstart.md` and the linked authoritative docs/package READMEs.
+- Creating a new author component outside reference reconstruction → read
+ `references/local-author-package.md`.
+- Previewing current Author Source → read `references/preview.md`.
+- Runtime setup, plan/build/status/inspect/get/reuse → read `references/runtime.md`.
+- Environment diagnosis or credentials → read `references/environment.md` and
+ `references/credentials.md`.
+- Seedance prompt assembly → read `references/seedance-kits.md`.
+- Production craft or format selection → read `references/playbooks/index.md`,
+ `references/playbooks/craft/production-gates.md`,
+ `references/playbooks/craft/visual-continuity.md`, and the selected craft/format reference.
+
+Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of
+commits. Repository docs and package-owned declarations remain authoritative.
diff --git a/.agents/skills/hypit/agents/openai.yaml b/.agents/skills/hypit/agents/openai.yaml
index ed4218a8..bd56af0d 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 to author, validate, or refine native SVML video sources; for reference-video reconstruction, run prepare_reference, observe_reference, and inspect_svml_vocabulary before writing complete SVML, SVS, and SVRun sources. If current vocabulary cannot express an observation, read the Hypit author-package guides and implement a complete project-local @hypit/local-* package without modifying existing packages."
+ default_prompt: "Use $hypit and route from SKILL.md. For reference-video reconstruction, read references/reference-video/index.md and every required child reference in order before running the three CLI commands or authoring sources."
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.md
new file mode 100644
index 00000000..6b13f7c0
--- /dev/null
+++ b/.agents/skills/hypit/references/authoring.md
@@ -0,0 +1,19 @@
+# Hypit source authoring
+
+Read `references/quickstart.md`, then the authoritative page it selects under `docs/quickstart/`.
+Keep Author Source, Recipe Source and Run Source complete and internally consistent rather than
+assembling independent per-shot source fragments.
+
+Before writing an element, read the owning package README and, when available, inspect its current
+vocabulary declaration. For `@hypit/<name>@1`, the repository README is
+`packages/<name>/README.md`. Never invent a component, attribute, child, port, Recipe property or
+literal value. Do not infer one package's syntax from a neighboring package.
+
+Install dependencies after package selections change. Validate with the existing command:
+
+```bash
+pnpm hypit check path/to/source
+```
+
+Do not create a check wrapper. A successful check establishes legal syntax, references and graph
+structure; it does not prove that an uncertain video observation was semantically correct.
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
new file mode 100644
index 00000000..1bcd8a43
--- /dev/null
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -0,0 +1,72 @@
+# Develop a project-local author package
+
+Use this workflow only after proving that no legal composition of installed packages expresses the
+required behavior. A similar-looking tag is insufficient when its declared Types, timing or output
+behavior differs. Never write an unknown tag before its package exists.
+
+## Required reading
+
+Read all of these completely before editing:
+
+1. `docs/guide/author-packages.md`
+2. `docs/guide/packages.md`
+3. `docs/guide/conventions.md`
+4. `packages/component-kit/README.md`
+5. The closest existing package's README, `manifest.ts`, `surface.ts`, `component.ts`, and
+ `activation.ts`
+
+## Package boundary
+
+Create a new package at `<project>/packages/local-<slug>/` named `@hypit/local-<slug>`. Use physical
+version `0.0.0-dev` and logical Module version `1`. Only create a new package: do not edit, extend,
+delete or overwrite an existing Hypit package to fill the gap.
+
+The package is project-local even when the project is the Hypit checkout. Do not move it into an
+official package automatically. After the result is accepted, offer promotion as a separate
+contribution.
+
+## Complete implementation
+
+The main agent writes all code. Gemini must not receive or produce TypeScript, `package.json`,
+Manifest, Surface, Producer, Validator or activation syntax.
+
+Implement the parts required by the behavior, including:
+
+- `package.json`, exports, dependencies and `hypit.activation`;
+- Module Manifest, nominal Types and Producers;
+- required Validators and deterministic Component handlers;
+- Markup Surface vocabulary and decoder;
+- activation contribution;
+- lowering, Fragment or renderer implementation needed to produce the declared output;
+- README and a preview for each visual Surface.
+
+Choose raw versus structured Surface, timing dependencies, ProgramSpace, Frame, SemanticMap,
+Artifact, Recipe and output Types from the observed behavior and closest package architecture. A
+declaration-only or Surface-only package is incomplete.
+
+## Install and validate
+
+Reuse an existing workspace when it already includes `packages/*`; otherwise make only the minimal
+workspace/package changes required. Add the package as a normal `workspace:*` dependency and run
+`pnpm install`. Do not hide it under `.hypit/`, modify the package loader or invent a registry.
+
+Repair in this order:
+
+1. package/workspace resolution;
+2. activation contribution;
+3. Manifest, Producer, Type and Validator agreement;
+4. Surface vocabulary and decoding;
+5. implementation behavior;
+6. source usage.
+
+Use only existing checks:
+
+```bash
+pnpm check
+pnpm hypit check path/to/main.svml
+pnpm hypit check path/to/studio.svs
+pnpm hypit check path/to/build.svrun
+```
+
+Use existing `--workspace` or `--package-root` options only when the project layout requires them.
+Do not continue to final authoring until the package and sources pass the existing checks.
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
new file mode 100644
index 00000000..c38cb43d
--- /dev/null
+++ b/.agents/skills/hypit/references/preview.md
@@ -0,0 +1,15 @@
+# Preview current source
+
+After a meaningful Author Source change, start the SVML Playground and give the author the actual
+URL. Kill the previous server first so the user does not inspect a stale composition.
+
+```bash
+pkill -f svml-playground || true
+pnpm svml:playground -- --source path/to/main.svml \
+ --run path/to/build.svrun \
+ --runtime path/to/hypit.runtime.json &
+```
+
+Read the startup output for the chosen port. Pass `--run` only when the preview needs Run Source
+material or timing, and `--runtime` only when the Author Source reuses accepted Build records.
+`docs/quickstart/preview.md` is authoritative.
diff --git a/.agents/skills/hypit/references/reference-video/continuity.md b/.agents/skills/hypit/references/reference-video/continuity.md
new file mode 100644
index 00000000..63731598
--- /dev/null
+++ b/.agents/skills/hypit/references/reference-video/continuity.md
@@ -0,0 +1,23 @@
+# Reference-video continuity rules
+
+These invariants override superficial layer order and shot boundaries:
+
+- Whoever is speaking owns base. The lowest, largest or currently visible picture does not decide
+ base.
+- Picture ownership and sound ownership are independent. Full-screen B-roll may cover the picture
+ while the prior speaker remains base and owns the continuing sound.
+- A person in silent B-roll cannot become speaker or base merely because their mouth appears to
+ move.
+- A shot with no visible person can carry continuing off-screen speech. Do not clear sound or base.
+- For alternating, overlapping or simultaneous speech, use audio evidence rather than visible-person
+ presence.
+- One overlay that continues across a cut remains one visual track spanning its full observed
+ lifetime. Do not recreate it once per shot.
+- Merge two or three incorrectly split clips only when continuity evidence confirms one camera shot
+ and the combined duration is at most 15 seconds. If the duration exceeds 15 seconds, preserve the
+ continuous-group relationship without creating an overlong shot.
+- Reuse whole-reference people, voice and product evidence. Describe the promoted product once and
+ do not replace it with conflicting per-shot descriptions.
+
+Shot boundaries are observation windows, not authoring units. Never generate independent SVML per
+shot and concatenate it afterward.
diff --git a/.agents/skills/hypit/references/reference-video/final-sources.md b/.agents/skills/hypit/references/reference-video/final-sources.md
new file mode 100644
index 00000000..8f66e080
--- /dev/null
+++ b/.agents/skills/hypit/references/reference-video/final-sources.md
@@ -0,0 +1,26 @@
+# Reference-video final sources
+
+After every required package exists and its vocabulary has been read, read
+`../authoring.md` completely and write one complete project:
+
+- `main.svml` describes the whole video in original time order, keeps continuing base/sound intact,
+ and represents one continuing overlay as one visual track.
+- `studio.svs` contains every Recipe actually referenced by `main.svml`, using only declared
+ properties and admitted values.
+- `build.svrun` references the Author Source and declares the required Targets with resolvable
+ dependencies.
+
+Do not author one source fragment per shot. Do not let check success substitute for unresolved
+semantic evidence; return to a narrow `observe_reference` question when necessary.
+
+Use existing checks only:
+
+```bash
+pnpm check
+pnpm hypit check path/to/main.svml
+pnpm hypit check path/to/studio.svs
+pnpm hypit check path/to/build.svrun
+```
+
+Fix package resolution and package implementation before repairing source use. Continue until all
+three files are accepted. Do not create `check_svml_project` or another wrapper.
diff --git a/.agents/skills/hypit/references/reference-video/index.md b/.agents/skills/hypit/references/reference-video/index.md
new file mode 100644
index 00000000..f51812da
--- /dev/null
+++ b/.agents/skills/hypit/references/reference-video/index.md
@@ -0,0 +1,15 @@
+# Reference-video reconstruction route
+
+This route reconstructs a complete reference video as usable `main.svml`, `studio.svs`, and
+`build.svrun`. The main agent owns all decisions and source code; Gemini supplies natural-language
+visual and audio evidence only.
+
+Before acting, read these files completely in order:
+
+1. `workflow.md` — CLI sequence, evidence flow and responsibility boundaries.
+2. `continuity.md` — mandatory shot, overlay, B-roll, speaker and product rules.
+3. `vocabulary.md` — existing-package selection and the route for a real vocabulary gap.
+4. `final-sources.md` — complete source authoring and check loop.
+
+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/reference-video/vocabulary.md b/.agents/skills/hypit/references/reference-video/vocabulary.md
new file mode 100644
index 00000000..3c500f12
--- /dev/null
+++ b/.agents/skills/hypit/references/reference-video/vocabulary.md
@@ -0,0 +1,21 @@
+# Reference-video vocabulary decisions
+
+After observations, select candidate packages and run `inspect_svml_vocabulary`. Read each selected
+package README as syntax authority. Compare the observation against declared inputs, outputs,
+attributes, children, ports, Recipe properties, timing behavior, appearance and examples.
+
+Use this decision order:
+
+1. Reuse one existing component when it fully expresses the observation.
+2. Compose multiple existing components when their declared outputs and timing express it without
+ changing the observed semantics.
+3. Declare a real vocabulary gap only when neither option works.
+
+Do not force a similar-looking tag into a role it does not own. Do not invent attributes or write a
+nonexistent tag with the intention of implementing it later.
+
+For a real gap, stop final-source authoring and read
+`../local-author-package.md` completely. Implement and install the new project-local package, then
+run `inspect_svml_vocabulary` against it before using its tag. The reference-video CLI remains
+limited to observation and vocabulary inspection; it does not generate components. Gemini does not
+write the package.
diff --git a/.agents/skills/hypit/references/reference-video/workflow.md b/.agents/skills/hypit/references/reference-video/workflow.md
new file mode 100644
index 00000000..8d40c4f9
--- /dev/null
+++ b/.agents/skills/hypit/references/reference-video/workflow.md
@@ -0,0 +1,34 @@
+# Reference-video workflow
+
+The public interface is exactly three CLI subcommands from `@hypit/reference-video-tools`:
+
+```bash
+hypit-reference-video-tools prepare_reference --video-path <path>
+hypit-reference-video-tools observe_reference --reference-id <reference-id>
+hypit-reference-video-tools inspect_svml_vocabulary --package <package> --tag <tag>
+```
+
+Each also accepts `--input <json>`. Follow this sequence:
+
+```text
+prepare_reference
+→ observe_reference for all shots
+→ narrow observe_reference follow-ups for unresolved conflicts
+→ inspect_svml_vocabulary for candidate packages
+→ develop a project-local package only for a proven vocabulary gap
+→ author complete main.svml, studio.svs, build.svrun
+→ use existing checks and repair until legal
+```
+
+`prepare_reference` deterministically prepares clips, representative frames, tail frames, audio
+tails and storyboard context, then obtains whole-reference people/product and voice observations.
+`observe_reference` automatically attaches the preceding tail frame/audio tail and whole-reference
+context. The main agent does not manually reconstruct this context.
+
+Gemini returns natural language only. Never send it SVML syntax, package declarations, vocabulary,
+previews or implementation code. Never ask it to write SVML, SVS, SVRun, a structured reference
+plan, component names or TypeScript. It is evidence, not the final decision maker.
+
+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 evidence itself must be refreshed.
diff --git a/.agents/skills/hypit/references/reference-vlm.md b/.agents/skills/hypit/references/reference-vlm.md
deleted file mode 100644
index 7f39f612..00000000
--- a/.agents/skills/hypit/references/reference-vlm.md
+++ /dev/null
@@ -1,98 +0,0 @@
-# Reference video reconstruction
-
-Use this only when the task is to reproduce or reverse a complete reference video into usable
-Hypit sources. The public interface is exactly three CLI subcommands in
-`@hypit/reference-video-tools`:
-
-- `hypit-reference-video-tools prepare_reference --video-path <path>` (or `--input <json>`) prepares the local video once, splits shots at or
- below 15 seconds, extracts every clip, representative frame, tail frame, and audio tail, and
- performs the one whole-reference people/product analysis and one whole-reference voice analysis.
-- `hypit-reference-video-tools observe_reference --reference-id <id>` (or `--input <json>`) observes all selected shots in
- parallel. It automatically supplies the previous shot's tail frame and audio tail, the whole
- reference people/voice/product evidence, and all neighboring boundaries. It returns natural
- language picture, sound, camera-continuity, overlay-continuity, and any three-shot or follow-up
- evidence.
-- `hypit-reference-video-tools inspect_svml_vocabulary --package <name>` (or `--input <json>`) reads the selected packages'
- current declarations and previews. It does not call Gemini and it does not know which component
- a visual observation should become.
-
-The fixed loop is:
-
-```text
-run prepare_reference
-→ run observe_reference for all shots
-→ run observe_reference with one narrow follow-up for each unresolved conflict
-→ run inspect_svml_vocabulary for the packages actually needed
-→ if vocabulary is insufficient, develop and install one complete project-local package
-→ main agent writes complete main.svml, studio.svs, build.svrun
-→ pnpm hypit check
-→ repair source syntax and run pnpm hypit check again
-```
-
-Never ask Gemini to write SVML, SVS, SVRun, a reference plan, component names, or package syntax.
-Gemini's output is evidence in natural language; the main agent decides the final source structure.
-Do not send vocabulary declarations or previews to Gemini.
-
-The reconstruction must preserve these facts:
-
-- Whoever is speaking is base. Visual layer order and screen area never decide base.
-- Picture and sound ownership are independent. Full-screen B-roll, a media insert, or a ranking
- typewriter may cover the frame while the previous speaker's base and sound continue.
-- A silent B-roll person who appears to speak cannot become the speaker or base.
-- A continuing voice survives a shot with no visible person.
-- One overlay that continues across a cut stays one visual track. Do not duplicate it in every shot.
-- Combine two or three incorrectly split shots only when the natural-language continuity evidence
- confirms one shot and the combined duration is no more than 15 seconds.
-- Reuse whole-reference people, voice, and product descriptions. A promoted product is described
- once and reused consistently.
-
-After observations, read the selected package README as syntax authority as well as the dynamic
-vocabulary returned by the `inspect_svml_vocabulary` CLI. Author one complete dependency graph, not separate
-per-shot source fragments. Use only declared tags, attributes, children, ports, Recipe properties,
-and admitted values. Use the existing `pnpm hypit check`; do not add or invent a check wrapper.
-
-## When the vocabulary has a real gap
-
-First try to express the observation by composing existing packages. A tag that looks similar is
-not sufficient: its declared inputs, outputs, timing behavior and visual result must actually cover
-the observation. Never write a nonexistent tag and plan to implement it later.
-
-If no existing legal composition can express the result, stop authoring the three source files and
-develop a project-local author package. This is main-agent software development; it is not a fourth
-reference-video command and it is not work for Gemini.
-
-Read all of the following before editing:
-
-- `docs/guide/author-packages.md`
-- `docs/guide/packages.md`
-- `docs/guide/conventions.md`
-- `packages/component-kit/README.md`
-- The closest existing package's README, `manifest.ts`, `surface.ts`, `component.ts`, and
- `activation.ts`
-
-Create only a new `packages/local-<slug>/` package named `@hypit/local-<slug>`. Do not change an
-existing Hypit package. The new package must have a complete Module Manifest, Types, Producers and
-Validators as required, Markup Surface declaration and decoder, activation descriptor, README,
-visual preview when applicable, and the implementation that produces its declared result. A Surface
-or vocabulary declaration without executable implementation is not a component.
-
-Connect the package to the current project's existing pnpm workspace and package root through an
-ordinary `workspace:*` dependency and `pnpm install`. Do not hide it under `.hypit/`, modify the
-package loader, or add a private registry. Then run:
-
-```bash
-pnpm check
-pnpm hypit check main.svml
-pnpm hypit check studio.svs
-pnpm hypit check build.svrun
-```
-
-Use the appropriate source paths and existing `--workspace` or `--package-root` options when the
-project layout needs them. Fix resolution, activation and package implementation errors before
-repairing source usage. Only continue the reconstruction when all existing checks accept the new
-package and final sources.
-
-Gemini must not write the local package or see its TypeScript and package syntax. The observed video
-is evidence for the behavior; the main agent owns all package architecture and code. If the user
-later approves the result, offer to promote the project-local package into the official Hypit
-repository as a separate contribution, but never move it automatically.