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.

merge: align OpenAgents skill distribution

kashorin02f21dfd92c1
diff --cc README.md
index f06f0927,f06f0927..4fb1521c
--- a/README.md
+++ b/README.md
@@@ -53,6 -53,6 +53,9 @@@ Hypit gives AI agents (Claude Code, Cod
npx skills add hypit-ai/hypit -g
```
++OpenAgents and other Skill hubs install the same canonical `skills/hypit/` directory. On first use,
++the Skill prepares the executable Hypit Distribution separately; your video project can live anywhere.
++
## Examples
### UGC
diff --cc README.zh-CN.md
index c4fe82fd,c4fe82fd..854e7149
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@@ -53,6 -53,6 +53,9 @@@ Hypit 为 AI Agent(Claude Code、Code
npx skills add hypit-ai/hypit -g
```
++OpenAgents 等 Skill Hub 安装的是同一个 `skills/hypit/` 真目录。首次使用时,Skill 会另行准备
++可执行的 Hypit Distribution;视频项目可以放在任意位置。
++
## 示例
### UGC
diff --cc docs/guide/skill.md
index a2d5368d,a4b3dab6..4209255c
--- a/docs/guide/skill.md
+++ b/docs/guide/skill.md
@@@ -1,103 -1,512 +1,120 @@@
----
-title: Hypit Skill Architecture
-description: How the Hypit skill turns descriptions and reference videos into checked projects.
----
+# Video authoring workflow
-# Hypit Skill Architecture
+Hypit keeps authoring, execution and results separate:
-This document is the maintainer's map of the Hypit skill. The skill is an agent-driven production
-workflow: the agent makes creative decisions, and repository tools turn those decisions into
-SVML/SVS/SVRun, check the resulting graph, persist evidence and resume safely after interruption.
+- Source, Recipe and Run describe what should be made.
+- Runtime executes one Build from those inputs.
+- Result records what that Build actually produced.
+- Reference-video tools help an author understand and inspect content; they do not own Build or
+ project history.
-The important distinction is:
+There is no route database, revision history, recovery cursor or aggregate project state. Work is
+recoverable because the authored files and useful media/report files are ordinary project content,
+not because a second system reconstructs an agent's past actions.
-- the agent decides what the video means, what it should look like and what to change;
-- tools decide whether the written project is legal, wired, covered, measurable and recoverable;
-- a visual observer reports differences, but the agent decides whether a report is a real defect.
++## Skill installation and execution
+
-## How a request becomes a video
++`skills/hypit/` is the one real, agent-neutral Skill directory. OpenAgents and other Skill hubs install
++that subtree into their Agent's global Skill directory. Repository checkouts expose the same source to
++Claude Code and Codex through the two leaf links `.claude/skills/hypit` and `.codex/skills/hypit`; the
++parent Skill directories remain independent so either Agent can also have private Skills.
+
-```text
-user request
- → route selection
- → intent/reference evidence
- → format and vocabulary decisions
- → Author Source + Recipe Source + Run Source + Runtime Profile
- → graph/package/Cue/layout gates
- → preview materialization and visual comparison (creation routes)
- → repairs and repeated gates
- → final deterministic gate
- → Studio confirmation
- → explicitly approved paid Build
-```
-
-The result is a complete video because the route does not stop at writing a prompt or a component:
-it creates the Script and timing, connects every visual/audio Track to a Film, declares every external
-generation in the Run, checks that the graph reaches the requested Target, and only then hands the
-same Run to Studio or Build.
-
-## Route selection and handoffs
-
-| User input | Route | What it owns | Handoff |
-|---|---|---|---|
-| Description, topic, brief or named format with no reference video | `original-authoring` (original authoring) | Intent, Hook, Script, visual design and complete new project | Final gate → optional `variant-expansion`; later natural-language change → `revision` |
-| Reference video or link, optionally “use my presenter/product/brand” | `reconstruction` (reconstruction) | Reference evidence, shot structure, matching Source, then the requested initial adaptation | Final gate → optional `variant-expansion`; later natural-language change → `revision` |
-| Natural-language change to a completed project or completed variant | `revision` (revision) | A bounded Source/Recipe/Run edit and deterministic revalidation | Completed revision → optional `variant-expansion` or Studio/Build |
-| N independent versions from a validated project | `variant-expansion` (variant expansion) | Global format/component plan, package gaps, copy-first projects and child-agent scopes | Each child → `variant-complete`; later manual change to one child → `revision` |
-
-The initial presenter/product/brand change attached to a reconstruction remains inside reconstruction;
-it is not routed through Revision. Revision begins only when the user later asks for another change.
-
-## Credentials and login
++The installed Skill is guidance, not the executable Hypit Distribution. Until the npm package is
++published, the Skill selects an existing Hypit checkout or prepares a machine-level checkout at
++`<home>/hypit`, updates it only by fast-forwarding `origin/main`, installs its pinned dependencies and
++uses its Node entrypoints. A Skill-hub reinstall updates the installed guidance; pulling the checkout
++updates the executable Distribution. Neither silently rewrites the other.
+
-Credentials are an environment gate for every production route, not a step deferred until a paid Build.
-The Skill defaults to HypiHub, does not ask the author to choose a Provider, and does not require copying an
-API key.
++The Skill, Distribution and video project have independent locations and lifetimes. A video project
++may live anywhere, needs no Skill link, and is never added to the Hypit repository workspace.
+
-The standard sequence is:
+## Start from the request
-```text
-select Runtime Profile → check HypiHub credential → explain and run OAuth when missing
-→ confirm login → hypit runtime up → verify WhisperX/other programs
-→ only then inspect media, call Gemini, author Source or Build
-```
+Decide whether the task is original authoring or reconstruction from a reference. Then inspect the
+available packages and the public vocabulary they expose:
```bash
-hypit auth status hypihub.default --runtime hypit.runtime.json
-hypit auth login hypihub.default --runtime hypit.runtime.json
-hypit runtime up
+hypit-reference-video-tools list_svml_packages
+hypit-reference-video-tools inspect_svml_vocabulary --package <package>
+hypit-reference-video-tools inspect_visual_schema
```
-When status reports that the writable OS credential is missing, the agent must explain that browser OAuth
-avoids copying an API key, login itself does not submit a paid generation, and an account without an active
-subscription can purchase one after signing in at [hypit.ai](https://hypit.ai). The agent runs
-`hypit auth login` and waits for the callback; it must not merely hand the command to the author or switch to
-the credentialless observer because no key was found.
-
-The session is stored in the local OS credential store and is reusable by other projects and later
-conversations. Only when the author explicitly requests an author-owned Provider may the agent configure
-`KIE_API_KEY`, the two Vertex Google variables, or `MIMO_API_KEY`, and it must identify that as the
-non-default path. Secrets never enter `.svml`, `.svs`, `.svrun`, Runtime Source, state JSON or logs. Before
-a paid Build, report every Provider and credential source, disclose the cost and wait for approval; if a
-credential or model is unavailable, return to the environment gate and guide the author to HypiHub.
+Reuse an existing Surface when it expresses the requested visual role. Develop a project-local author
+package only when there is a real missing capability. Do not mutate an installed package to make one
+project pass.
-## Shared phases
+## Original authoring
-### 1. Environment and durable start
-
-The agent selects the Distribution, independent project directory, Runtime Profile, credentials and
-(for reconstruction) the observer. It starts the appropriate state machine before authoring:
+Write the smallest Source, Recipe and Run that express the request. Inspect them directly:
```bash
-hypit-reference-video-tools route_state --action start --project-root <project> --route description
-hypit-reference-video-tools route_state --action start --project-root <project> --route reconstruction
+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun
+hypit-reference-video-tools validate_script_cues --run ./build.svrun
+hypit check ./build.svrun
+hypit-reference-video-tools preview_check ./build.svrun
+hypit-reference-video-tools layout_check --run ./build.svrun
```
-The Runtime Profile is written before any command that needs a managed capability. `hypit runtime use`
-selects it and `hypit runtime up` prepares the local Worker/programs. This prevents later reference,
-preview or Build steps from failing because the execution environment was never declared.
-
-### 2. Establish intent or reference evidence
-
-For original authoring, read `brief-intake.md`, inspect semantically relevant complete projects under
-`examples/`, recover their intent rather than copying their Source, select the format playbook and
-freeze `.hypit/brief.json`. The brief records audience, Hook, narrative progression, visual/audio/text
-relationships, claims and unresolved decisions.
+These commands are independent reports. One does not approve or unlock another. Fix an actual issue
+because the report and the requested design justify the change. A layout candidate may be annotated
+as intentional with `layout_accept`; the annotation is keyed by the structural finding name, not by a
+snapshot of the whole project.
-For reconstruction, prepare the video and cache its bytes and whole-reference evidence:
+For a visual review, render the element and window that matter, then read the result against an
+explicit statement of intent:
```bash
-hypit-reference-video-tools prepare_reference --video-path <file-or-link> --observer <observer>
-hypit-reference-video-tools observe_reference --reference-id <id>
+hypit-reference-video-tools render_element ./build.svrun \
+ --element title --segment intro --out ./review/title-intro.mp4
+hypit-reference-video-tools review_element --run ./build.svrun \
+ --element title --segment intro --video ./review/title-intro.mp4 \
+ --intent-file ./review/title-intent.md
```
-Preparation supplies media metadata, transcript/alignment and the reference observation envelope.
-The observation sweep supplies persistent systems, people/voices, visual type and sound context for
-the whole video. Shot observations and narrow questions resolve structure that cannot be safely
-inferred from one frame. These artifacts are why reconstruction can produce a whole video rather
-than only imitate one screenshot.
+`authoring_check` can summarize coverage, playback and recorded reviews, but it is not project state
+and is not required to submit a Build.
-### 3. Choose format and vocabulary before Source
+## Reconstruction
- Prepare the reference once:
-The main agent reads `playbooks/index.md`, the selected format and its linked craft documents. It
-enumerates the visual/audio systems and runs:
++Do not inspect repository example projects on this route and never use the supplied reference as a
++Film, Track or Take source. Prepare it once as evidence:
```bash
-hypit-reference-video-tools list_svml_packages
-hypit-reference-video-tools inspect_svml_vocabulary --package <candidate> [--package ...]
-hypit-reference-video-tools inspect_visual_contract
-```
-
-`inspect_svml_vocabulary` is the public contract for what an installed Surface accepts. The visual
-contract describes Visual Element shapes, admitted styles, enum values and seal invariants. The agent
-records one concise component-fit decision per system in `.hypit/component-fit.json`: reuse an existing
-package, reuse it with a small accepted variance, or develop a project-local package. Installed
-package source is not needed for ordinary authoring. Only a confirmed close-sibling copy may read the
-copied package's necessary role files.
-
-If there is a real gap, the package route runs before dependent Source is accepted:
-
-```text
-gap-confirmed → guidance-loaded → types-frozen → implemented
-→ vocabulary-inspected → package-validated → graph-checked
-→ layout-checked → package-ready
+hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --observer agent
+hypit-reference-video-tools observe_reference --reference-id <reference-id>
```
-The package agent uses `local-author-package.md`, the public contract and the minimal fixture. It must
-expose a Manifest, Surface, Fragment, Producer, Validator, activation and preview, and it must be
-imported and used by the project graph. `validate_local_author_packages` is the package gate.
-
-After an original-authoring or reconstruction route completes, a project-local package may be
-considered for contribution. Read the Skill reference `references/package-promotion.md` and ask the
-author about a promotion when the component has clear, high reuse value across unrelated videos. If
-the author agrees, move it into Hypit's `packages/` folder and prepare a Pull Request; ordinary
-one-off components remain in the
-project. This is a post-completion offer, not an interruption or an automatic repository change.
+The prepared shot clips, frames, transcript and observations live under
+`.hypit/reference-video-tools/`. They are useful source material. `record_observation` fills an
+explicit pending observation when the `agent` observer is used.
-### 4. Author the four project sources
-
-| File | Responsibility |
-|---|---|
-| `main.svml` | Script, narrative, component declarations, prompts and semantic timing references |
-| `recipes.svs` | Style, appearance, playback, layout and other recipe values |
-| `build.svrun` | Author binding, Candidates, satisfactions and Targets |
-| `hypit.runtime.json` | Runtime packages, Providers, credentials and local execution |
-
-The Script is written before shot-level generation: Segments define Take boundaries, Cues keep
-captioned speech readable, and `estimate:Speech` provides deterministic timing. Source declarations
-make each generation and graph edge explicit, so later checks can identify exactly what is wrong.
-
-### 5. Deterministic graph and layout gates
-
-Before visual comparison, the route runs:
+Author the project from the observed picture, words and timing. Render the element over the same
+Script window and compare it directly:
```bash
-hypit-reference-video-tools validate_script_cues --run <run>
-hypit check <run>
-hypit-reference-video-tools preview_check <run>
-hypit-reference-video-tools layout_check --run <run>
-```
-
-These gates answer different questions:
-
-- package/Cue checks prove project packages and Script boundaries are usable;
-- `hypit check` proves Source syntax, references and graph structure;
-- `preview_check` proves tracks trace through packages to the Film;
-- `layout_check` realizes the actual composition in a hidden browser and reports candidate geometry
- findings such as internal vertical offsets, parent/Canvas overflow and settled top-level overlap.
-
-Layout findings are evidence for the agent, not automatic truth. The agent repairs genuine problems or
-records an intentional geometry decision with `layout_accept`, then reruns `layout_check` until all
-candidates are resolved or accepted. A relevant Source, Recipe, package, font or runtime change
-invalidates affected evidence.
-
-The two extraction rules used by both creation routes are:
-
-| Check | Extraction rule | Why |
-|---|---|---|
-| Visual review | For each distinct visual declaration/style change, take the **full clip at its first appearance**. | The full clip preserves entrance, movement, exit and transient visual differences. It avoids rechecking every caption text or timestamp when the visual declaration is unchanged. |
-| Mechanical layout | For each `Present`, take one frame from its **longest stable interval**. | A settled frame measures actual DOM geometry without mistaking normal animation for overflow or offset. |
-
-Do not swap these rules: visual review judges the complete clip against the brief or reference, while
-`layout_check` only measures realized layout and returns candidates for the Agent. Content/time extremes
-are not additional selection rules; stable overflow is found in the per-`Present` measurement, and
-transient or media-internal problems remain visible to the full-clip review.
-
-### 6. Creation-route visual review and repair
-
-Original authoring calls `authoring_check`; reconstruction calls `reconstruction_check`. Each command
-reads Source and creates the visual-review plan described above. The longest-stable-interval sample
-belongs only to the separate hidden-browser `layout_check`, not to this visual review.
-
-For each plan entry:
-
-```text
-render_element → rendered preview/mock artifact → visual observer/reviewer
-→ record findings → agent repairs Source/Recipe/package choice → rerun gates
-```
-
-Reconstruction compares the rendered element against the prepared reference with
-`compare_reconstruction`; original authoring uses `review_element`/`record_review` against the frozen
-brief. The observer reports visible differences. The agent decides which are defects, intentional
-design or an incorrect component-fit decision. It never copies or edits an installed package to force
-a match. After repairs, the plan and mechanical gates are rerun until the final check passes.
-
-### 7. Final gate, Studio and Build
-
-`authoring_check` or `reconstruction_check` is the final deterministic gate. It requires package/Cue,
-graph, layout and review/comparison evidence to be current. Only after it passes does the agent use
-`studio-confirmation.md` to materialize the estimate-timed preview and show the live Run in Studio.
-Studio acceptance is separate from visual comparison and confirms the intended structure before
-spending. `hypit build` is submitted only after explicit cost approval.
-
-## Route workflows
-
-### `original-authoring` (original authoring)
-
-#### Route entry and prerequisites
-
-1. Select the Distribution, project root and Runtime Profile, then create `route_state`.
-2. Before inspecting examples or freezing the brief, check the `hypihub.default` credential. If the writable HypiHub OS credential is missing, explain that OAuth avoids copying an API key and run `hypit auth login hypihub.default --runtime hypit.runtime.json`; an account without an active subscription can purchase one at hypit.ai.
-3. Run `hypit runtime up` and confirm WhisperX and every other selected program are healthy. Do not enter brief, vocabulary or Source work before this gate is complete.
-4. When vocabulary inspection proves a real gap, pause Source authoring and enter the project-package branch: create `packages/<slug>/`, write `package.json` and activation first, then implement the Manifest, Types, Producers, Validators, Surface/decoder, Fragment, README and preview. Install, import and pass `validate_local_author_packages`, `preview_check` and `layout_check` before returning to this route.
-
-```text
-environment → brief-frozen → examples/format/craft decisions
-→ vocabulary/component-fit → Script and four sources → source-authored
-→ package-ready → script-checked → graph-checked → layout-checked
-→ review-planned → preview-rendered → review-complete → repairs-complete
-→ final-checked → Studio confirmation → optional Build
-```
-
-This route turns an open-ended description into a complete program by freezing the intended viewer
-result first, choosing a format and package vocabulary second, then writing every semantic and graph
-edge needed by the Film. It has no reference video, so `brief.json` is the authority for later review.
-
-| Step | Agent work | Tool or document | Durable result and reason |
-|---|---|---|---|
-| 1. Start | Choose the Distribution, project directory, runtime and credentials; start the route snapshot. | `environment.md`, `runtime.md`, `route_state start`, `hypit paths`, `hypit runtime use/up` | A runnable project and a recovery cursor exist before authoring begins. |
-| 2. Make the request executable | Turn the description into audience, Hook, promise, beats, claims, speakers and visual/audio/text relationships. Inspect complete semantic examples; do not copy their Source. | `brief-intake.md`, `examples/` | `.hypit/brief.json` freezes what “correct” means, so review has a target instead of a vague “looks good”. |
-| 3. Freeze format and craft | Select the matching playbook and load its required craft documents. For original authoring, establish recurring person, product, voice, location, wardrobe, lighting and prop anchors before writing generation prompts, then reuse them across takes. | `playbooks/index.md`, `formats/*.md`, `craft/visual-continuity.md`, `craft/persona-and-audio.md`, `craft/generated-dependencies.md` | The program gets a timing model, shot grammar, caption rules and explicit cross-shot identity/scene continuity even without a reference video. |
-| 4. Fit components | Enumerate candidate packages, inspect their public vocabulary and decide reuse, accepted variance or a local package. | `list_svml_packages`, `inspect_svml_vocabulary`, `inspect_visual_contract`, `vocabulary.md`, `component-fit.json` | Every visual role has a legal Module/Tag/Recipe contract before Source is written; a real gap is solved once through `local-author-package.md`. |
-| 5. Write the Script | Split the narration into Segments/Takes and short Cues; assign each shot one job and keep timing semantic. | `script-time.md`, `authoring.md` | `main.svml` contains the complete spoken/text progression and deterministic `estimate:Speech` timing. |
-| 6. Wire the project | Author `main.svml`, `recipes.svs`, `build.svrun` and `hypit.runtime.json`; declare each generation, Track, Candidate, satisfaction and Target. | `authoring.md`, `runtime.md` | The Film graph is explicit and reproducible rather than a prompt plus disconnected assets. |
-| 7. Prove sources and graph | Run package, Cue, syntax, graph-trace and realized-layout gates. | `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check` | The project is legal, every Track reaches the Film, and browser geometry has been measured before visual review. |
-| 8. Plan the visual review | Ask the route check for one full clip at the first appearance of each distinct visual declaration/style change. | `authoring_check` | `.hypit/evidence/` records exactly what must be reviewed; the agent does not omit a style change or invent a render list. The longest stable sample is produced separately by `layout_check`. |
-| 9. Render and review | Materialize the planned preview/mock clips, read every entry against the frozen brief, and record findings. | `render_element`, `review_element`, `record_review`, `element-review.md`, `conformance-round.md` | Each visual system has explicit evidence, including text fit, coverage, contrast, motion and geometry. |
-| 10. Repair and close | Repair only confirmed issues, rerun affected gates and review entries, then run the final route check. | `layout_accept` when geometry is intentional; `authoring_check` | `final-checked` means no required visual review, graph, package, Cue or layout evidence is stale. |
-| 11. Hand off | Create the estimate-timed preview-mock Run, show Studio, disclose cost and Build only after approval. | `preview-mock.md`, `studio-confirmation.md`, `hypit plan/build/status/inspect/get` | Studio sees the live Film graph; the paid Build reuses the checked Run and produces the complete delivery. |
-
-### `reconstruction` (reconstruction)
-
-#### Route entry and prerequisites
-
-1. Select the project, Runtime Profile and observer and create `route_state`; do not inspect or copy the reference before the environment gate.
-2. Check HypiHub OAuth. If it is missing, explain why and run `hypit auth login hypihub.default --runtime hypit.runtime.json`, then run `hypit runtime up` and confirm WhisperX is ready before `prepare_reference`, observation or Gemini calls.
-3. Enumerate components only after reference evidence is complete. A proven vocabulary gap follows the project-package branch: implement and validate the complete package (`package.json`, activation, Manifest, Types, Producers, Validators, Surface/decoder, Fragment, README and preview). Never edit installed packages or copy reference media directly.
-
-Reconstruction is strictly evidence-first: the route never reads repository `examples/` projects, including
-their complete `.svml`, `.svs`, `.svrun`, README, assets or variants. The sole exception is the generic
-`examples/minimal-author-package/` fixture after a real vocabulary gap is proven and the local-package
-workflow requires its contract. The reference video and persisted observations are the source of truth;
-after observation, read only installed package vocabulary and craft guidance required by observed systems.
-Examples belong to original authoring and variant planning, not reconstruction.
-
-```text
-environment → reference-prepared → reference-observed
-→ reference/format/craft decisions → vocabulary/component-fit
-→ Script and four sources → source-authored → package-ready → script-checked → graph-checked
-→ layout-checked → review-planned → preview-rendered → comparison-complete
-→ repairs-complete → final-checked → initial-adaptation → final check again
-→ Studio confirmation → optional Build
-```
-
-The reference is converted into durable evidence, not kept in agent memory. Observations define
-people, persistent systems, shot boundaries, words and visual relationships; the Source recreates
-those as Segments, Takes, Tracks and Film edges. The comparison round checks rendered results against
-the corresponding reference stretches. That evidence/author/repair loop is what makes the route
-capable of rebuilding the entire video.
-
-The reconstruction order is deliberately different from a description-only job:
-
-| Step | Agent work | Tool or document | Durable result and reason |
-|---|---|---|---|
-| 1. Prepare | Select the observer once, resolve a local file or download/cache a link, and start route state. | `observers.md`, `credentials.md`, `prepare_reference`, `route_state start` | A stable reference id, media metadata and observer choice prevent later turns from rereading a different file or silently changing observers. |
-| 2. Observe the whole video | Run the fixed whole-reference sweep, then read its transcript/alignment, persistent systems, people/voices, visual type and sound context. | `observe_reference`, `evidence.md` | Whole-video evidence establishes what exists throughout the program; it is the basis for reconstructing every shot, not one representative frame. |
-| 3. Resolve structure | Inspect shot boundaries and ask narrow questions where a single frame cannot establish an appearance value, transition or relationship. | `observe_reference --question`, `continuity.md`, `reconstruction/vocabulary.md` | Ambiguities become persisted evidence before Source is authored, so timing and continuity are not guessed from chat memory. |
-| 4. Choose format and components | Use completed reference evidence and observed systems to enumerate candidate packages and inspect public vocabulary; do not read example projects. Only a proven gap may use `examples/minimal-author-package/` for the generic package contract. | `playbooks/index.md` (as needed), `list_svml_packages`, `inspect_svml_vocabulary`, `component-fit.json` | The recreated program has a legal component for each observed visual role; installed packages remain immutable. |
-| 5. Build a faithful Source | Convert transcript and observations into Script Segments/Takes/Cues, then author all four sources and every graph edge. | `final-sources.md`, `authoring.md`, `script-time.md`, `runtime.md` | The source describes the entire reference timeline, including narration, overlays, B-roll, transitions, audio and Targets. |
-| 6. Prove the baseline | Run Run-scoped vocabulary/package/Cue checks, syntax, graph tracing and realized layout. | `inspect_svml_vocabulary --run`, `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check` | No comparison is attempted until the written graph can actually produce every declared Track. |
-| 7. Create the comparison plan | Determine every distinct declaration and every reference stretch it occupies; keep stable intervals and shot boundaries. | `reconstruction_check`, `comparison-round.md`, `element-review.md` | The plan covers the whole video, not only a convenient still; each item has its own reference tokens and render window. |
-| 8. Render and compare | Render all planned stretches from the same Run, then submit the reference/render pairs to the selected observer. | `render_element --batch`, `compare_reconstruction --batch` | The observer reports visible differences while preserving the reference/render pairing and timing. |
-| 9. Repair the reconstruction | Agent judges each finding against evidence, fixes Source/Recipe or a component decision, and never copies/edits an installed package. | `reconstruction/route.md`, `layout-checks.md`, `layout_accept` | Confirmed defects are repaired; intentional crop, overlap or offset can be documented without corrupting the package boundary. |
-| 10. Recheck the faithful base | Rerun the comparison and deterministic gates until the reconstruction itself passes. | `reconstruction_check`, `preview_check`, `layout_check` | This separates “faithfully reconstructed” evidence from later author customization. |
-| 11. Apply initial customization | Only now replace the requested presenter, product or brand in the completed reconstruction. Rerun the route check plus deterministic gates; differences caused by the requested adaptation are not silently treated as package defects. | `main.svml`/`recipes.svs`/`build.svrun`, `reconstruction_check`, `hypit check`, `preview_check`, `layout_check` | The reference evidence remains honest while the delivered base contains the requested adaptation. This is still reconstruction, not Revision. |
-| 12. Hand off | Show the checked Run in Studio and request explicit cost approval before Build. | `studio-confirmation.md`, `hypit plan/build` | The same checked graph becomes the complete paid video; a later natural-language change routes to Revision. |
-
-The reconstruction data flow is:
-
-```text
-reference bytes
- ├─ transcript/alignment ───────────────→ Script Segments, Cues, estimate:Speech
- ├─ whole-video observations ───────────→ people, voices, persistent visual/audio systems
- └─ shot observations and questions ────→ shot boundaries, states, relationships
- ↓
- main.svml + recipes.svs + build.svrun + runtime profile
- ↓
- Tracks → packages → Film → Target
- ↓
- preview_check → review plan → render/compare every owed stretch
- ↓
- agent repairs → deterministic gates → Studio/Build
-```
-
-That mapping is the completeness guarantee: every observed word becomes timed Script, every observed
-visual/audio role becomes a Track or package-backed element, and every Track must trace to the Film
-before any paid generation is possible.
-
-### `revision` (revision)
-
-#### Route entry and prerequisites
-
-1. Locate the canonical Run, read and reconcile its state, and restore its Runtime Profile and credentials; never infer the baseline from chat memory.
-2. A source-only revision still requires a resolvable Runtime Profile. If the change will trigger paid generation, confirm HypiHub OAuth first and run `hypit auth login` when missing rather than deferring login until Build.
-3. If the change exposes a component gap, enter the project-package branch and complete the package plus Run-scoped validation before continuing Revision; change runtime or package only when capability truly changes.
-
-Revision can start from a directly supplied completed project, a reconstruction, an original project,
-an earlier revision or one completed variant:
-
-```text
-request-captured → impact-assessed → intent-mapped → source-updated
-→ gates-checked → optional preview-rendered/review-complete
-→ final-checked → revision-complete → optional Build
-```
-
-The agent locates the canonical Run and validates the existing baseline. It maps natural language to
-the smallest Source/Recipe/Run field, records the affected graph closure, edits only those layers,
-and reruns package/Cue, `hypit check`, `preview_check` and `layout_check`. Revision performs no VLM or
-reference comparison; Studio is only a display handoff after deterministic checks pass.
-
-| Step | Agent work | Tool or document | Durable result and reason |
-|---|---|---|---|
-| 1. Locate baseline | Accept a completed project directory directly or locate the parent route/variant and canonical Run. | `revision_state start`, `route_state read/reconcile`, `git status` | `request.json` and a new revision id preserve the exact baseline; Revision never invents a missing reconstruction history. |
-| 2. Assess impact | Decide whether the request affects geometry/style, Script/timing, graph wiring, package choice or paid generation. | `authoring.md`, current brief, component-fit, package README | `impact` and affected Source files define the smallest graph closure to invalidate. |
-| 3. Map intent | Translate natural language to an authoritative field (Cue, Frame/Placement, Style, Candidate, Target, etc.). | `revision_state checkpoint`, source and graph inspection | The change is scoped before editing, preventing a casual request from rewriting unrelated files. |
-| 4. Edit minimally | Modify only `main.svml`, `recipes.svs` or `build.svrun`; update runtime/package only when capability/component truly changes. | `revision/route.md`, `script-time.md`, `layout-checks.md` | Generated media and accepted Build artifacts remain untouched; source remains the authority. |
-| 5. Revalidate | Run package/Cue, syntax, graph, preview and realized-layout checks; repair or accept layout candidates. | `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check`, `layout_accept` | `gates-checked` proves the revision is wired and measurable without invoking a visual observer. |
-| 6. Finish or hand off | Persist final evidence, optionally show Studio, and Build only if generation inputs changed and cost is approved. | `revision_state`, `studio-confirmation.md`, `hypit plan/build` | A completed revision can feed another variant batch; a later request starts a new revision id. |
-
-### `variant-expansion` (variant expansion)
-
-#### Route entry and prerequisites
-
-1. The main agent reconciles the base project and confirms its final gates and Runtime Profile; every child inherits that settled environment.
-2. If the batch will perform paid generation, check HypiHub OAuth first; when missing, explain and run `hypit auth login`, then `hypit runtime up`. Child agents do not repeatedly ask for login and may not bypass the environment gate with a credentialless path.
-3. Every new package is completed once in staging: `package.json`, activation, Manifest, Types, Producers, Validators, Surface/decoder, Fragment, README and preview, plus package/graph/preview/layout validation. Freeze its digest before injecting it into children.
-
-The main agent makes global decisions before any child agent starts; variant expansion uses the validated base's complete SVML/SVS/SVRun and does not inspect repository examples:
-
-```text
-baseline-validated → base-inspected → format-plan-frozen → slate-drafted
-→ vocabulary-enumerated → component-plan-frozen → package-gaps-classified
-→ workload-disclosed → package-gaps-resolved → slate-frozen → projects-copied
-→ variants-dispatched → variants-complete → aggregate-checked
-→ [build-planned → build-approved → build-complete] → expansion-complete
-```
-
-Tools and outputs are:
-
-1. `variant_state start` records the base, count, request and delivery mode.
-2. Read the base project's complete sources, brief/route evidence and playbooks to produce `format-plan.json`; do not inspect repository examples.
-3. The main agent writes distinct direction quotas in `slate.json`; their counts add up to N. Each direction carries a shared brief and allowed file scope. `variant_init` expands the quotas into numbered concrete variants when dispatching, so a 100-item batch does not require 100 hand-written briefs.
-4. `list_svml_packages` and `inspect_svml_vocabulary` produce global vocabulary evidence and
- `component-plan.json`.
-5. The workload disclosure tells the author how many variants are SVML-only, medium-scope or require
- a new package. Each distinct package gap is solved once in staging and frozen by digest.
-6. `variant_init` copies the base first, preserves author assets and Source, excludes generated state
- and results, injects only ready packages and creates each child route state.
-7. Child agents read their copied project, brief, plans, allowed scope, assigned README/evidence and
- required playbook documents. They make the minimum change and run `validate_script_cues`,
- `hypit check`, `preview_check`, `layout_check` and `variant_check`.
-8. The batch aggregate check proves every child is complete. A later manual change to one child exits
- this route and starts `revision` in that child directory.
-
-Each child route is:
-
-```text
-baseline-copied → brief-frozen → change-scope-frozen → guidance-loaded
-→ vocabulary-verified → package-ready → script-checked → source-updated
-→ graph-checked → layout-checked → final-checked → variant-complete
+hypit-reference-video-tools render_element ./build.svrun \
+ --element ranking --segment list --reference-id <reference-id> \
+ --out ./review/ranking-list.mp4
+hypit-reference-video-tools compare_reconstruction \
+ --reference-id <reference-id> --run ./build.svrun --segment list \
+ --video ./review/ranking-list.mp4 --element ranking
```
-The batch is intentionally “copy first, then edit”:
-
-| Step | Main agent or child work | Tool or document | Durable result and reason |
-|---|---|---|---|
-| 1. Validate base | Confirm the parent creation/revision final gate and record its digest. | `route_state/revision_state reconcile`, `variant_state start` | Every child starts from the same known-good Film graph. |
-| 2. Decide the slate | Use the validated base and the author's request to choose directions and quotas totaling N, and freeze each direction's Format DNA and allowed scope; do not inspect examples. | `playbooks/index.md`, base Source/brief, `format-plan.json`, `slate.json` | Creative directions are decided once globally; dispatch expands each quota into a unique numbered child brief. |
-| 3. Decide vocabulary/workload | Inspect packages and public vocabulary, choose reuse/composition/new package, then disclose fast/medium/new-package counts. | `list_svml_packages`, `inspect_svml_vocabulary`, `component-plan.json`, `variant_state checkpoint` | The author knows the cost/time impact before agents start; no child discovers a package gap halfway through. |
-| 4. Stage new packages | Develop each distinct local package once, validate it in staging, freeze its digest and mark it ready. | `route_state --route variant-package`, `local-author-package.md`, `validate_local_author_packages`, `preview_check`, `layout_check` | Shared package work is reused safely and cannot mutate installed packages. |
-| 5. Copy the base | Clone the project with copy-on-write where possible, retain authored assets/source, remove generated state/results and old Build bindings, inject only ready packages. | `variant_init` | Each child is independent, reproducible and free of stale paid/generated artifacts. |
-| 6. Dispatch bounded work | Give each child its copied project, brief, format/component plan, README/evidence and allowed scope. | child `route_state`, `variant_state` | The batch can run in parallel while each child has an auditable contract. |
-| 7. Verify and edit | Child verifies vocabulary only when its component changes, edits the minimum allowed files, and runs all mechanical gates. | `inspect_svml_vocabulary --run` when needed, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check`, `variant_check` | A fast SVML-only variant stays fast; scope escapes become explicit conflicts instead of silent rewrites. |
-| 8. Aggregate and deliver | Reconcile unfinished children, aggregate checks, and optionally plan/approve paid Builds. | `variant_state reconcile`, aggregate report, `hypit plan/build` | 100-item batches resume only unfinished children and never repeat a paid Build after compaction. |
-
-## JSON state machines and recovery
-
-State is split into a current pointer and execution-scoped history so context compression never becomes
-the source of truth:
-
-| Concern | Durable location |
-|---|---|
-| Creation current view | `<project>/.hypit/route-state.json` |
-| Creation execution history/evidence | `<project>/.hypit/routes/<route-id>/state.json`, `.hypit/evidence/` |
-| Base brief and component fit | `<project>/.hypit/brief.json`, `<project>/.hypit/component-fit.json` |
-| Revision current view/history | `.hypit/revision-state.json`, `.hypit/revisions/<revision-id>/{state.json,request.json}` |
-| Variant batch locator | `<base>/.hypit/variant-expansions/<batch-id>.json` |
-| Variant batch state | `<batch>/.hypit/variant-expansion-state.json` |
-| Child/staging state | Child or staging `.hypit/route-state.json` and route history |
-
-Every state record contains the route id, current cursor, completed steps, `next_action`, decisions,
-conflicts, last command, artifact paths and artifact digests. Machine evidence is content-addressed;
-manual decisions such as the brief, component fit, format plan, Slate and allowed changes are recorded
-explicitly rather than inferred from files.
+Every explicit comparison is a new observation. The tool does not hash a render and silently reuse an
+older answer. `reconstruction_check` summarizes what has and has not been looked at; it does not own a
+workflow cursor.
-A route transition is always a write of evidence, not a chat assertion:
+## Build and reuse
-```text
-agent makes a decision or edits Source
- → checkpoint records the decision and input digest
-tool runs a check/render/review
- → successful output is stored at an immutable evidence path
-state advances only when that output satisfies the stage predicate
- → current view + execution history are atomically updated
-```
-
-The state shape is intentionally small but explicit:
-
-```json
-{
- "version": 1,
- "route": "description",
- "route_id": "...",
- "current_step": "graph-checked",
- "completed_steps": ["environment", "brief-frozen", "source-authored"],
- "next_action": "layout_check --run build.svrun",
- "decisions": { "brief": ".hypit/brief.json", "component_fit": ".hypit/component-fit.json" },
- "evidence": [{ "kind": "preview_check", "path": ".hypit/evidence/...json", "digest": "..." }],
- "conflicts": [],
- "last_command": "hypit-reference-video-tools preview_check ..."
-}
-```
-
-`checkpoint` is for an explicit agent decision or completed command; `read` is for displaying the
-durable cursor; `reconcile` recomputes only machine predicates and rolls back stale evidence; and
-`discover` finds a batch locator after the agent no longer remembers its directory. A stage is never
-advanced merely because a file happens to exist.
-
-The public state commands are:
-
-```bash
-# creation routes
-hypit-reference-video-tools route_state --action read --project-root <project>
-hypit-reference-video-tools route_state --action checkpoint --project-root <project> \
- --route <description|reconstruction> --state <stage>
-hypit-reference-video-tools route_state --action reconcile --project-root <project>
-
-# revision
-hypit-reference-video-tools revision_state --action start --project-root <project> \
- --run <project>/build.svrun --request '<change>'
-hypit-reference-video-tools revision_state --action read --project-root <project>
-hypit-reference-video-tools revision_state --action checkpoint --project-root <project> \
- --step <stage-number> --status complete --decision '<what was decided>'
-hypit-reference-video-tools revision_state --action reconcile --project-root <project>
-
-# variant batch
-hypit-reference-video-tools variant_state --action discover --project-root <base>
-hypit-reference-video-tools variant_state --action checkpoint --project-root <base> \
- --batch-id <id> --step <stage-number> --status complete
-hypit-reference-video-tools variant_state --action read --project-root <base> --batch-id <id>
-hypit-reference-video-tools variant_state --action reconcile --project-root <base> --batch-id <id>
-```
+Run `hypit plan` before paid generation when cost or external services matter. Run `hypit build` only
+when the user wants the Build. The Build's public outputs are saved into its Result. Intermediate
+component outputs that are public ports are saved as well, so later work can point at useful images,
+videos or structured values without changing the Run target into a list of every intermediate value.
-All JSON writes use a temporary file followed by atomic rename. A corrupt file is preserved and
-reported, never replaced by an empty state. `reconcile` verifies each machine-step predicate, checks
-parent/source/package/evidence digests, rolls stale steps back to the first unmet one and reports
-conflicts. It never invents creative decisions, silently widens an allowed scope, repeats a completed
-variant or resubmits a paid Build.
+Repeated Builds are distinct Results even when the Run files are unchanged. Give important Results
+and outputs human names through the Result presentation commands instead of inventing a content hash,
+central artifact table or hidden project history.
-After interruption or context compaction, read the skill and applicable route again, discover/read the
-canonical state, reconcile it, inspect conflicts, and execute only the first unmet `next_action`.
-This is why the skill can run a long reconstruction or a 100-variant expansion without relying on
-conversation memory.
+For bulk variants, use ordinary project directories and an explicit task list chosen by the caller.
+Copying, scheduling and naming those projects belongs to that caller or a dedicated batch tool; the
+reference-video package does not maintain a second variant state machine.
diff --cc docs/quickstart.md
index 901856aa,47cdab73..c0404e42
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@@ -16,13 -16,13 +16,14 @@@ page gets you to that first safe plan:
## Install
```bash
--npm install --global hypit
npx skills add hypit-ai/hypit --global
```
--The first command installs the reusable Distribution. The second installs the skill globally so a
--new agent session in another project can find it. Ordinary authoring never requires a repository
--clone.
++This installs the real `skills/hypit/` subtree globally so a new Agent session in any project can find
++it. OpenAgents installs the same subtree directly from the repository. Skill installation and the
++executable Distribution are separate: until the npm package is published, the Skill prepares or
++updates a machine-level checkout at `<home>/hypit` and uses its Node entrypoints. Video projects remain
++independent and may live anywhere.
## Use the Hypit skill
@@@ -35,16 -35,16 +36,21 @@@
It works through the same five steps below, asking you only for what your Runtime Profile actually
needs. Work through them yourself if you would rather not use an agent.
--## 1. Check the installed Distribution
++## 1. Check the selected Distribution
You need Node.js 22+ on macOS 13+ or Windows 10/11 x64.
```bash
hypit paths --json
++# Before npm publication, the Skill runs:
++node <home>/hypit/bin/hypit.mjs paths --json
```
--The result separates the current project, its `.hypit` state, the machine Program Home and the npm
--Distribution. pnpm, Corepack and `npm link` are contributor tools, not user setup.
++The result separates the current project, its `.hypit` state, the machine Program Home and the selected
++Distribution. The Agent prepares a checkout's pinned dependencies at machine scope; it never installs
++them into the video project or uses `npm link`.
++
++The remaining examples abbreviate either executable launcher as `hypit`.
## 2. Compile the example
diff --cc docs/zh/guide/skill.md
index ff17e7ad,fb248246..91ef54b4
--- a/docs/zh/guide/skill.md
+++ b/docs/zh/guide/skill.md
@@@ -1,91 -1,453 +1,107 @@@
----
-title: Hypit Skill 架构
-description: Hypit skill 如何把描述或参考视频变成可检查、可恢复的项目。
----
+# 视频创作工作方式
-# Hypit Skill 架构
+Hypit 把创作、执行和结果分开:
-这份文档是维护者理解 Hypit skill 的总图。skill 是由 agent 驱动的生产流程:agent 负责创意判断,
-仓库工具负责把判断写成 SVML/SVS/SVRun,验证 graph,保存证据,并在中断后恢复。
+- Source、Recipe、Run 描述要做什么;
+- Runtime 执行一次 Build;
+- Result 记录这次 Build 实际产生了什么;
+- reference-video-tools 帮助作者理解、预览和检查内容,不管理 Build 历史或项目历史。
-核心分工是:
+项目不再维护 route 数据库、revision 历史、恢复游标或批次总状态。可继续工作的依据是项目中
+真实存在的 Source、媒体和报告,而不是另一个系统对 agent 过去操作的复原。
-- agent 决定视频要表达什么、应该长什么样、要改什么;
-- 工具决定项目是否合法、graph 是否接通、布局和证据是否稳定;
-- 视觉 observer 只报告差异,是否算问题由 agent 判断。
++## Skill 安装与执行
+
-## 用户请求如何变成完整视频
++`skills/hypit/` 是唯一真实、与 Agent 无关的 Skill 目录。OpenAgents 等 Skill Hub 直接把这个
++子目录安装到对应 Agent 的全局 Skill 目录。仓库内的 `.claude/skills/hypit` 与
++`.codex/skills/hypit` 只是指向同一真身的两条叶子软链;两个上层目录仍然彼此独立,未来可以
++分别容纳各 Agent 私有的 Skill。
+
-```text
-用户请求
- → 路由选择
- → 意图/参考证据
- → 格式与词汇决策
- → Author Source + Recipe Source + Run Source + Runtime Profile
- → graph/package/Cue/layout 门禁
- → 预览素材与视觉比对(创作路径)
- → 修复并重复检查
- → 最终确定性门禁
- → Studio 确认
- → 明确批准后的付费 Build
-```
-
-之所以能产出完整视频,是因为流程不止写提示词或组件:它会建立 Script 和时间关系,把所有
-视觉/音频 Track 接到 Film,在 Run 中声明每个外部生成,检查 Target 是否真的可达,再把同一
-个 Run 交给 Studio 或 Build。
-
-## 路由选择与交接
-
-| 用户输入 | 路径 | 负责内容 | 下一步 |
-|---|---|---|---|
-| 描述、主题、brief 或格式名,没有参考视频 | `original-authoring`(原创制作) | 意图、Hook、Script、视觉设计和完整新项目 | 最终门禁后可进 `variant-expansion`(变体扩展);之后修改进 `revision`(修改) |
-| 参考视频或链接,可附带“换我的人物/产品/品牌” | `reconstruction`(复刻) | 参考证据、镜头结构、匹配 Source,以及本次初始改编 | 最终门禁后可进变体扩展;之后修改进 Revision |
-| 对完成项目或完成变体的自然语言修改 | `revision`(修改) | 有边界的 Source/Recipe/Run 修改和确定性复验 | 完成后可进变体扩展,或交给 Studio/Build |
-| 从已验证项目生产 N 个独立版本 | `variant-expansion`(变体扩展) | 全局格式/组件计划、包缺口、复制项目和子 agent 范围 | 每个子项目到 `variant-complete`;之后手动修改该子项目进 Revision |
-
-复刻请求中一开始就附带的人物、产品、品牌替换仍属于复刻;只有后续再次提出自然语言修改才进入 Revision。
-
-## 凭据与登录流程
++安装 Skill 只会安装指导内容,不等于安装可执行的 Hypit Distribution。在 npm 包正式发布前,
++Skill 会选择已有 Hypit checkout,或者在机器级 `<home>/hypit` 准备一份 checkout;更新时只允许
++从 `origin/main` 快进,依赖使用仓库锁定版本,命令通过它的 Node 入口运行。Skill Hub 重新安装
++更新的是指导内容,checkout 拉取更新的是可执行 Distribution,二者都不会暗中覆盖对方。
+
-凭据是每条生产路径的环境门禁,不是付费 Build 时才处理的事项。Skill 默认使用 HypiHub,不先询问
-Provider,也不要求用户复制粘贴 API key。
++Skill、Distribution 和视频项目的位置与生命周期相互独立。视频项目可以放在任意位置,不需要
++创建 Skill 软链,也不会被加入 Hypit 仓库 workspace。
+
-标准顺序:
+## 从真实需求开始
-```text
-选择 Runtime Profile → 检查 HypiHub 凭据 → 缺失时说明并执行 OAuth 登录
-→ 确认登录成功 → hypit runtime up → 检查 WhisperX/其他程序健康
-→ 才能读媒体、调用 Gemini、写 Source 或 Build
-```
+先判断任务是原创还是参考视频复刻,再查看现有包和它们公开的词汇:
```bash
-hypit auth status hypihub.default --runtime hypit.runtime.json
-hypit auth login hypihub.default --runtime hypit.runtime.json
-hypit runtime up
+hypit-reference-video-tools list_svml_packages
+hypit-reference-video-tools inspect_svml_vocabulary --package <package>
+hypit-reference-video-tools inspect_visual_schema
```
-当 status 显示可写的 OS 凭据缺失时,agent 必须说明:浏览器 OAuth 不需要复制 API key,登录本身不会
-提交付费生成;没有有效订阅的账号可以登录后在 [hypit.ai](https://hypit.ai) 购买。然后 agent 直接
-执行 `hypit auth login` 并等待回调成功,不能只把命令交给用户,也不能因为缺 key 改走无凭据 observer。
-
-登录会话保存在本机 OS credential store,可被其他项目和后续会话复用。只有用户明确要求自有 Provider
-时,才配置 `KIE_API_KEY`、Vertex 的两个 Google 变量或 `MIMO_API_KEY` 等,并明确这是非默认路径;
-secret 永不写入 `.svml`、`.svs`、`.svrun`、Runtime Source、状态 JSON 或日志。付费 Build 前必须
-先列出 Provider/凭据来源、披露费用并获得批准;凭据缺失或模型不可用时,回到环境门禁并引导 HypiHub。
+现有 Surface 能表达需要的视觉角色时直接复用。只有确实缺能力时才开发项目本地 author
+package,不能为了一个项目去修改已安装包。
-## 共用阶段
+## 原创视频
-### 1. 环境与持久化启动
-
-agent 选择 Distribution、独立项目目录、Runtime Profile、凭据,以及复刻路径的 observer。写作前启动对应状态机:
+用最小的 Source、Recipe、Run 表达需求,然后分别查看它们的真实情况:
```bash
-hypit-reference-video-tools route_state --action start --project-root <project> --route description
-hypit-reference-video-tools route_state --action start --project-root <project> --route reconstruction
+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun
+hypit-reference-video-tools validate_script_cues --run ./build.svrun
+hypit check ./build.svrun
+hypit-reference-video-tools preview_check ./build.svrun
+hypit-reference-video-tools layout_check --run ./build.svrun
```
-任何需要托管能力的命令之前必须先写 Runtime Profile,用 `hypit runtime use` 选择,用
-`hypit runtime up` 准备 Worker/程序,避免参考、预览或 Build 到最后才发现执行环境未声明。
-
-### 2. 建立意图或参考证据
-
-原创制作读取 `brief-intake.md`,检查 `examples/` 中语义匹配的完整项目,恢复其意图而不是复制
-Source,选择格式 playbook,并冻结 `.hypit/brief.json`。brief 记录受众、Hook、叙事推进、
-视觉/音频/文字关系、事实声明和未决决策。
+这些命令是相互独立的报告,不会互相批准或解锁。只有报告和设计需求共同说明存在实际问题时
+才修改项目。布局测量只是候选提示;有意的几何关系可以用 `layout_accept` 写下理由。这个理由
+关联的是可读的结构发现名称,不是整个项目快照。
-复刻先准备视频并缓存媒体和全片证据:
+需要看具体视觉时,直接渲染相关元素和时间窗口,再按照明确的创作意图阅读结果:
```bash
-hypit-reference-video-tools prepare_reference --video-path <file-or-link> --observer <observer>
-hypit-reference-video-tools observe_reference --reference-id <id>
+hypit-reference-video-tools render_element ./build.svrun \
+ --element title --segment intro --out ./review/title-intro.mp4
+hypit-reference-video-tools review_element --run ./build.svrun \
+ --element title --segment intro --video ./review/title-intro.mp4 \
+ --intent-file ./review/title-intent.md
```
-准备阶段提供媒体元数据、transcript/alignment 和参考观察包;全片观察提供持久系统、人物/声音、
-视觉类型和声音上下文。镜头观察和窄问题解决不能从单帧安全推断的结构。这样复刻依据的是持久
-证据,而不是 agent 对视频的短期记忆,所以可以重建整条视频。
+`authoring_check` 可以汇总画面覆盖、播放策略和已经记录的 review,但它不是项目状态,也不是
+提交 Build 的前置条件。
-### 3. 在写 Source 前确定格式和词汇
+## 参考视频复刻
- 先准备参考视频:
-主 agent 读取 `playbooks/index.md`、选定格式和其 footer 链接的 craft 文档,枚举视觉/音频系统,运行:
++这条路径不得查看仓库中的示例项目,也不得把参考视频直接作为 Film、Track 或 Take 的来源。
++先把它作为证据准备好:
```bash
-hypit-reference-video-tools list_svml_packages
-hypit-reference-video-tools inspect_svml_vocabulary --package <candidate> [--package ...]
-hypit-reference-video-tools inspect_visual_contract
-```
-
-`inspect_svml_vocabulary` 是已安装 Surface 的公开契约;visual contract 提供 Visual Element 形状、
-允许的样式、枚举值和 seal 不变量。agent 在 `.hypit/component-fit.json` 中为每个系统记录:
-复用现有包、复用并接受少量差异,或开发项目本地包。普通情况下不需要读取已安装包源码;只有
-确认复制 close sibling 作为实现骨架时才读取被复制包的必要 role 文件。
-
-确定存在真实缺口后,先完成包 staging 路径:
-
-```text
-gap-confirmed → guidance-loaded → types-frozen → implemented
-→ vocabulary-inspected → package-validated → graph-checked
-→ layout-checked → package-ready
+hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --observer agent
+hypit-reference-video-tools observe_reference --reference-id <reference-id>
```
-包必须有 Manifest、Surface、Fragment、Producer、Validator、activation 和 preview,并且被项目
-Source 导入、被 graph 使用;`validate_local_author_packages` 是包门禁。
-
-原创或复刻路线完成后,可以考虑是否贡献项目本地包。阅读 Skill 参考文档 `references/package-promotion.md`,当组件在无关
-视频中也有明确且很高的复用价值时,再向用户提出贡献建议。用户同意后,将它移入 Hypit 仓库的
-`packages/` 文件夹并准备 Pull Request;普通的一次性组件留在项目内部。这是完成后的可选建议,
-不会打断制作流程,也不会自动修改仓库。
+拆出的镜头、代表帧、逐词转录和观察结果保存在 `.hypit/reference-video-tools/`。它们本身就是
+有用内容。使用 `agent` observer 时,`record_observation` 负责填写明确返回的待回答观察。
-### 4. 编写四个项目源文件
-
-| 文件 | 职责 |
-|---|---|
-| `main.svml` | Script、叙事、组件声明、提示词和语义时间引用 |
-| `recipes.svs` | 样式、外观、playback、布局等 Recipe 值 |
-| `build.svrun` | Author 绑定、Candidate、satisfy 和 Target |
-| `hypit.runtime.json` | Runtime 包、Provider、凭据和本地执行 |
-
-Script 先于镜头生成:Segment 定义 Take 边界,Cue 保证字幕可读,`estimate:Speech` 提供确定性时长。
-Source 中每个生成和 graph edge 都显式写出,因此后续检查能定位问题。
-
-### 5. 确定性 graph 与布局门禁
-
-视觉比对前运行:
+根据画面、文字和时间信息创作项目。需要比较时,把相关元素在相同 Script 窗口中渲染出来:
```bash
-hypit-reference-video-tools validate_script_cues --run <run>
-hypit check <run>
-hypit-reference-video-tools preview_check <run>
-hypit-reference-video-tools layout_check --run <run>
-```
-
-它们分别回答:
-
-- package/Cue 检查:项目包和 Script 边界是否可用;
-- `hypit check`:Source 语法、引用和 graph 结构是否合法;
-- `preview_check`:Track 是否通过包接到 Film;
-- `layout_check`:在隐藏浏览器中实现真实 composition,报告内部上下偏移、父级/Canvas 越界、稳定状态下顶层组件重叠等候选。
-
-布局发现只是交给 agent 的辅助证据,不是自动真相。agent 修复真实问题,或用 `layout_accept` 记录有意几何,然后重跑 `layout_check`,直到候选消失或被接受。相关 Source、Recipe、包、字体或 runtime 改动会使证据失效。
-
-视觉检查和机械布局检查使用两条不同的抽取规则:
-
-| 检查 | 抽取规则 | 为什么这样做 |
-|---|---|---|
-| 视觉检查 | 每种不同视觉声明/样式变化,在首次出现处取一个**完整片段**。 | 完整片段保留出现、移动、离开和瞬时视觉差异;样式不变时无需因为每句 caption 或每个时间点重复检查。 |
-| 机械布局检查 | 每个 `Present` 在自己的**最长稳定区间**取一帧。 | 稳定帧才能测量真实 DOM,避免把正常动画过程误报成越界或偏移。 |
-
-两条规则不能互换:视觉检查对照 brief 或参考视频判断完整片段;`layout_check` 只测量真实布局并把结果作为候选交给 Agent。内容极值和时间极值不是额外选片规则:稳定越界由逐个 `Present` 的测量发现,瞬时或媒体内部的问题由完整片段的视觉检查负责。
-
-### 6. 创作路径的视觉检查与修复
-
-原创制作使用 `authoring_check`,复刻使用 `reconstruction_check`。命令读取 Source,按上面的视觉规则生成检查计划。最长稳定区间取样只属于另外的隐藏浏览器 `layout_check`,不属于视觉检查。
-
-每个计划项按以下闭环执行:
-
-```text
-render_element → 预览/mock 素材 → 视觉 observer/reviewer
-→ 记录发现 → agent 修复 Source/Recipe/组件决策 → 重跑门禁
-```
-
-复刻通过 `compare_reconstruction` 与对应参考片段比对;原创通过 `review_element`/`record_review` 与冻结 brief 比对。observer 报告看到的差异,agent 判断是缺陷、有意设计还是组件判断错误。不能复制或修改已安装包来强行贴合。修复后重复计划和机械门禁,直到最终检查通过。
-
-### 7. 最终门禁、Studio 和 Build
-
-`authoring_check` 或 `reconstruction_check` 是最终确定性门禁,要求 package/Cue、graph、layout 和
-视觉检查/比对证据都仍然有效。通过后才按 `studio-confirmation.md` 生成 estimate 时长的预览并在
-Studio 打开当前 Run。Studio 确认是付费前对结构的人工确认,不等同视觉比对;只有明确批准费用后才提交 `hypit build`。
-
-## 四条路径的完整流程
-
-### `original-authoring`(原创制作)
-
-#### 路径入口与前置
-
-1. 选择 Distribution、项目根目录和 Runtime Profile,建立 `route_state`。
-2. 在检查 examples 或写 brief 前,检查 `hypihub.default` 的凭据。没有可写的 HypiHub OS 凭据时,说明 OAuth 不需要复制 API key,并由 agent 执行 `hypit auth login hypihub.default --runtime hypit.runtime.json`;无有效订阅的账号可在 hypit.ai 购买。
-3. 运行 `hypit runtime up`,确认 WhisperX 和 Runtime Profile 中的其他程序健康;环境未完成时不能进入 brief、词汇或 Source 阶段。
-4. 组件出现真实词汇缺口时,暂停写 Source,转入“项目本地包”分支:在项目 `packages/<slug>/` 创建包,先写 `package.json` 与 activation,再完成 Manifest、Types、Producers、Validators、Surface/decoder、Fragment、README 和 preview;安装、导入并通过 `validate_local_author_packages`、`preview_check`、`layout_check` 后,才能回到本路线。
-
-```text
-environment → brief-frozen → examples/格式/craft 决策
-→ vocabulary/component-fit → package-ready → Script 与四个源文件
-→ script-checked → source-authored → graph-checked → layout-checked
-→ review-planned → preview-rendered → review-complete → repairs-complete
-→ final-checked → Studio 确认 → 可选 Build
-```
-
-它先冻结观众结果,再选择格式和词汇,最后写出 Film 所需的所有语义和 graph edge;因为没有参考视频,后续视觉检查以 `brief.json` 为意图依据。
-
-| 步骤 | Agent 做什么 | 工具或文档 | 持久化结果与作用 |
-|---|---|---|---|
-| 1. 启动 | 选择 Distribution、项目目录、runtime 和凭据,启动路线快照。 | `environment.md`、`runtime.md`、`route_state start`、`hypit paths`、`hypit runtime use/up` | 在写 Source 前就有可运行项目和恢复游标。 |
-| 2. 把描述变成可执行 brief | 确定受众、Hook、承诺、节拍、事实声明、人物以及视觉/音频/文字关系;检查完整语义 examples,但不复制其 Source。 | `brief-intake.md`、`examples/` | `.hypit/brief.json` 冻结“什么算正确”,后续检查不靠模糊的“看起来不错”。 |
-| 3. 冻结格式与 craft | 选择匹配的 playbook,并读取它要求的全部 craft 文档。原创时,在写生成提示词前先为反复出现的人物、产品、声音、地点、服装、灯光和道具建立锚点,再在各个 take 中复用。 | `playbooks/index.md`、`formats/*.md`、`craft/visual-continuity.md`、`craft/persona-and-audio.md`、`craft/generated-dependencies.md` | 即使没有参考视频,也能得到明确的时间模型、镜头语法、字幕规则,以及跨镜头的人物、场景和物品连续性。 |
-| 4. 适配组件 | 枚举候选包,检查公开词汇,决定复用、接受少量差异,或开发项目本地包。 | `list_svml_packages`、`inspect_svml_vocabulary`、`inspect_visual_contract`、`vocabulary.md`、`component-fit.json` | 每个视觉角色在写 Source 前就有合法的 Module/Tag/Recipe 契约;真实缺口通过 `local-author-package.md` 一次解决。 |
-| 5. 写 Script | 把旁白切成 Segment/Take 和短 Cue;每个镜头只承担一个明确任务,时间保持语义化。 | `script-time.md`、`authoring.md` | `main.svml` 包含完整的说话/文字推进和确定性的 `estimate:Speech` 时长。 |
-| 6. 接通项目 | 编写 `main.svml`、`recipes.svs`、`build.svrun`、`hypit.runtime.json`;显式声明每个生成、Track、Candidate、satisfy 和 Target。 | `authoring.md`、`runtime.md` | Film graph 是完整、可复现的,不是一个提示词加上一堆互不相连的素材。 |
-| 7. 证明 Source 与 graph | 运行包、Cue、语法、graph tracing 和真实布局门禁。 | `validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check` | 项目合法、每条 Track 都能到达 Film,并且在视觉检查前已经测过浏览器布局。 |
-| 8. 生成视觉检查计划 | 让路线检查为每种不同视觉声明/样式变化在首次出现处生成一个完整片段。 | `authoring_check` | `.hypit/evidence/` 记录必须检查的内容;Agent 不会漏掉样式变化,也不用手写 render 列表。最长稳定区间由独立的 `layout_check` 取样。 |
-| 9. 渲染并检查 | 生成计划中的 preview/mock 片段,逐项对照冻结的 brief,记录发现。 | `render_element`、`review_element`、`record_review`、`element-review.md`、`conformance-round.md` | 每种视觉系统都有证据,覆盖文字适配、画面覆盖、对比度、运动和几何。 |
-| 10. 修复并收口 | 只修复确认的问题,重跑受影响门禁和检查项,再运行最终路线检查。 | 有意几何用 `layout_accept`;最终用 `authoring_check` | `final-checked` 表示视觉、graph、包、Cue、布局证据都没有过期。 |
-| 11. 交接 | 创建 estimate 时长的 preview-mock Run,先披露每个付费能力实际使用的 Provider 与凭据来源,再打开 Studio、披露费用,获批准后才 Build。缺少或不可用的 key 引导前往 https://hypit.ai 获取 HypiHub key。 | `preview-mock.md`、`studio-confirmation.md`、`hypit plan/build/status/inspect/get` | Studio 看到的是活的 Film graph;付费 Build 复用已检查的 Run,产出完整交付。 |
-
-### `reconstruction`(复刻)
-
-#### 路径入口与前置
-
-1. 先选择项目、Runtime Profile 和 observer,并建立 `route_state`;不要先读取或复制参考视频。
-2. 检查 HypiHub OAuth。凭据缺失时由 agent 说明原因并执行 `hypit auth login hypihub.default --runtime hypit.runtime.json`,然后运行 `hypit runtime up`,确认 WhisperX 已就绪后才能 `prepare_reference`、观察或调用 Gemini。
-3. 参考证据完成后再枚举组件。确认词汇缺口时,按原创路径的项目本地包分支实现并验证完整包(`package.json`、activation、Manifest、Types、Producers、Validators、Surface/decoder、Fragment、README、preview),不能修改安装包或直接复制参考素材。
-
-复刻采用严格的“证据优先”顺序:整条复刻路径都禁止读取仓库 `examples/` 下的项目,包括完整的
-`.svml`、`.svs`、`.svrun`、README、素材和变体。唯一例外是确认真实词汇缺口、且项目本地包流程明确
-需要通用契约时,才允许读取 `examples/minimal-author-package/`。参考视频及其持久化观察证据是事实来源;
-之后只读取实际需要的安装包词汇和 craft 指南。Examples 属于原创制作和变体规划,不属于复刻。
-
-```text
-environment → reference-prepared → reference-observed
-→ reference/craft 决策 → vocabulary/component-fit → package-ready
-→ Script 与四个源文件 → script-checked → source-authored → graph-checked
-→ layout-checked → review-planned → preview-rendered → comparison-complete
-→ repairs-complete → final-checked → 初始改编 → 再跑 final check
-→ Studio 确认 → 可选 Build
-```
-
-视频先被转换成可恢复的观察证据;观察定义人物、持久系统、镜头边界、文字和视觉关系,Source
-再把它们表达为 Segment、Take、Track 和 Film edge。每轮把渲染结果与对应参考片段比对,修复后重跑,直到整条视频的最终门禁通过。
-
-复刻的顺序必须这样安排,因为它要重建的是整条参考视频,而不是一个截图:
-
-| 步骤 | Agent 做什么 | 工具或文档 | 持久化结果与作用 |
-|---|---|---|---|
-| 1. 准备参考 | 选择一次 observer,接收本地文件或下载并缓存链接视频,启动路线状态。 | `observers.md`、`credentials.md`、`prepare_reference`、`route_state start` | 得到稳定的 reference id、媒体元数据和 observer;恢复时不会换文件或换观察者。 |
-| 2. 观察全片 | 运行固定的全片观察,读取 transcript/alignment、持久视觉系统、人物/声音、视觉类型和声音上下文。 | `observe_reference`、`evidence.md` | 全片证据说明视频中到底有哪些镜头和系统,是重建所有镜头的依据,不是挑一帧模仿。 |
-| 3. 解决结构疑点 | 检查 shot 边界;单帧无法确定外观、转场或关系时,用窄问题补证据。 | `observe_reference --question`、`continuity.md`、`reconstruction/vocabulary.md` | 把歧义写入证据后再写 Source,时间和连续性不靠对话记忆猜。 |
-| 4. 选择格式与组件 | 只根据已完成的参考证据和实际观察到的系统,枚举候选包并检查公开词汇;复刻路径禁止读取 examples 项目,只有真实缺口且包流程需要时可读取 `examples/minimal-author-package/`。 | `playbooks/index.md`(仅按需)、`list_svml_packages`、`inspect_svml_vocabulary`、`component-fit.json` | 每个观察到的视觉角色都有合法组件;安装包保持不可变。 |
-| 5. 写出忠实 Source | 把 transcript 和观察结果转成 Script 的 Segment/Take/Cue,再写四个源文件和所有 graph edge。 | `final-sources.md`、`authoring.md`、`script-time.md`、`runtime.md` | Source 描述完整参考时间线,包括旁白、叠加层、B-roll、转场、音频和 Target。 |
-| 6. 证明基线 | 运行 Run 级词汇/包/Cue 检查、语法、graph tracing 和真实布局。 | `inspect_svml_vocabulary --run`、`validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check` | 只有每条声明的 Track 都确实能产出时,才进入昂贵的视觉比对。 |
-| 7. 生成比对计划 | 找出每种不同声明以及它覆盖的每个参考片段,保留稳定区间和 shot 边界。 | `reconstruction_check`、`comparison-round.md`、`element-review.md` | 计划覆盖整条视频,而不是挑一个好看的静帧;每项都有自己的 reference token 范围和渲染窗口。 |
-| 8. 渲染并比对 | 用同一个 Run 渲染所有计划片段,再把参考/渲染成对交给指定 observer。 | `render_element --batch`、`compare_reconstruction --batch` | observer 报告可见差异,同时保留参考与渲染的对应关系和时间范围。 |
-| 9. 修复复刻结果 | Agent 根据证据判断每条发现,修改 Source/Recipe 或组件决策;绝不复制/修改安装包。 | `reconstruction/route.md`、`layout-checks.md`、`layout_accept` | 真问题被修复;有意裁切、重叠或偏移可以记录理由,不破坏包边界。 |
-| 10. 重新确认忠实基线 | 重跑比对和确定性门禁,直到“复刻本身”通过。 | `reconstruction_check`、`preview_check`、`layout_check` | 把忠实复刻证据与后续用户定制分开。 |
-| 11. 应用初始改编 | 这时才把用户要求的人物、产品或品牌替换到已完成的复刻中。重跑路线检查和确定性门禁;由用户改编产生的差异不能被静默当成包缺陷。 | `main.svml`/`recipes.svs`/`build.svrun`、`reconstruction_check`、`hypit check`、`preview_check`、`layout_check` | 参考证据保持诚实,交付的母项目包含用户改编;这仍是 reconstruction,不是 Revision。 |
-| 12. 交接 | 在 Studio 展示已检查 Run,明确列出每个付费 Provider/凭据来源并批准费用后才 Build;key 不足时先引导 HypiHub。 | `studio-confirmation.md`、`hypit plan/build` | 同一个已检查 graph 进入付费生成;之后的新自然语言修改才路由到 Revision。 |
-
-复刻的数据流是:
-
-```text
-参考视频字节
- ├─ transcript/alignment ───────────────→ Script 的 Segment、Cue、estimate:Speech
- ├─ 全片观察 ──────────────────────────→ 人物、声音、持久视觉/音频系统
- └─ 镜头观察与窄问题 ──────────────────→ shot 边界、状态和元素关系
- ↓
- main.svml + recipes.svs + build.svrun + runtime profile
- ↓
- Track → package → Film → Target
- ↓
- preview_check → 比对计划 → 渲染/比对每个应检查的片段
- ↓
- Agent 修复 → 确定性门禁 → Studio/Build
-```
-
-这就是“能复刻整条视频”的完整性保证:观察到的每段话都变成有时长的 Script,观察到的每个
-视觉/音频角色都变成 Track 或由包实现的元素,并且在任何付费生成前,每条 Track 都必须能追到 Film。
-
-### `revision`(修改)
-
-#### 路径入口与前置
-
-1. 先定位 canonical Run,读取并 reconcile 现有状态;恢复该项目的 Runtime Profile 和凭据,不从聊天记录推断基线。
-2. 普通 Source/Recipe 修改也要保证 Runtime Profile 可解析;若修改会触发付费生成,先确认 HypiHub OAuth 已登录,缺失时由 agent 执行 `hypit auth login`,不能把登录推迟到 Build 前。
-3. 如果修改暴露了组件能力缺口,先切到项目本地包分支完成完整包和 Run 级验证,再继续 Revision;只有能力确实变化时才修改 runtime 或 package。
-
-Revision 可直接接收完成项目,也可接收复刻、原创、旧 Revision 或完成变体:
-
-```text
-request-captured → impact-assessed → intent-mapped → source-updated
-→ gates-checked → 可选 preview-rendered/review-complete
-→ final-checked → revision-complete → 可选 Build
-```
-
-agent 先定位 canonical Run 并验证基线,再把自然语言映射到最小 Source/Recipe/Run 字段,记录受
-影响的 graph closure,只修改这些层并重跑 package/Cue、`hypit check`、`preview_check`、`layout_check`。
-Revision 不调用 VLM 或参考比对;Studio 只是确定性检查通过后的显示交接。
-
-| 步骤 | Agent 做什么 | 工具或文档 | 持久化结果与作用 |
-|---|---|---|---|
-| 1. 定位基线 | 可直接接收完成项目目录,也可定位父路线/变体和 canonical Run。 | `revision_state start`、`route_state read/reconcile`、`git status` | `request.json` 和新的 revision id 固定准确基线;不会凭空补造复刻历史。 |
-| 2. 判断影响 | 判断请求影响几何/样式、Script/时间、graph、包选择还是付费生成。 | `authoring.md`、当前 brief、component-fit、包 README | `impact` 和受影响 Source 文件定义最小失效 graph closure。 |
-| 3. 映射意图 | 把自然语言映射到权威字段,例如 Cue、Frame/Placement、Style、Candidate 或 Target。 | `revision_state checkpoint`、Source 与 graph 检查 | 先定范围再编辑,避免一个小请求重写无关文件。 |
-| 4. 最小修改 | 只改 `main.svml`、`recipes.svs` 或 `build.svrun`;只有能力/组件真的变化才改 runtime/包。 | `revision/route.md`、`script-time.md`、`layout-checks.md` | 不碰 MP4、PNG、WAV、preview mock 或 Artifact;Source 始终是权威。 |
-| 5. 重新验证 | 运行包/Cue、语法、graph、preview 和真实布局检查,修复或接受布局候选。 | `validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check`、`layout_accept` | `gates-checked` 证明修改已接通且可测,不调用视觉 observer。 |
-| 6. 完成或交接 | 保存最终证据,可选打开 Studio;只有生成输入变化并获费用批准才 Build。 | `revision_state`、`studio-confirmation.md`、`hypit plan/build` | 完成的 Revision 可以继续做变体;下一次修改会创建新的 revision id。 |
-
-### `variant-expansion`(变体扩展)
-
-#### 路径入口与前置
-
-1. 主 agent 先 reconcile 母项目,确认最终门禁和 Runtime Profile;所有子项目继承这个已确认的环境。
-2. 批次需要付费生成时,先检查 HypiHub OAuth;缺失时由 agent 说明并执行 `hypit auth login`,再运行 `hypit runtime up`。不要让每个子 agent 重复询问登录,也不能用无凭据路径绕过环境门禁。
-3. 新包必须在 staging 中单独完成:`package.json`、activation、Manifest、Types、Producers、Validators、Surface/decoder、Fragment、README、preview,以及包/graph/preview/layout 验证;冻结 digest 后才能注入子项目。
-
-主 agent 在任何子 agent 启动前完成全局决策;变体直接使用已验证母项目的完整 SVML/SVS/SVRun,不读取仓库 examples:
-
-```text
-baseline-validated → base-inspected → format-plan-frozen → slate-drafted
-→ vocabulary-enumerated → component-plan-frozen → package-gaps-classified
-→ workload-disclosed → package-gaps-resolved → slate-frozen → projects-copied
-→ variants-dispatched → variants-complete → aggregate-checked
-→ [build-planned → build-approved → build-complete] → expansion-complete
-```
-
-具体工作和产物:
-
-1. `variant_state start` 记录母项目、数量、请求和交付模式。
-2. 读取母项目完整 Source、brief/route 证据和 playbooks,生成 `format-plan.json`;不读取仓库 examples。
-3. 主 agent 在 `slate.json` 中写出若干个不重复的变体方向和数量配额,所有配额之和正好为 N;每个方向声明共享 brief 和允许修改的文件范围。`variant_init` 在派发时再确定性展开成带编号的具体变体,因此 100 个变体不需要主 agent 手写 100 个 brief。
-4. `list_svml_packages` 与 `inspect_svml_vocabulary` 形成全局词汇证据和 `component-plan.json`。
-5. 工作量披露快速(只改 SVML)、中等(改 SVS/Run 或切换组件)和新包任务;每种新包只在 staging 开发一次,并以 digest 冻结。
-6. `variant_init` 先复制母项目,保留作者资产和 Source,排除生成状态/结果,只注入已就绪的包,并建立每个子项目的 route state。
-7. 子 agent 读取自己的项目、brief、plan、允许范围、指定 README/证据和 playbook,只做最小修改,然后运行 `validate_script_cues`、`hypit check`、`preview_check`、`layout_check`、`variant_check`。
-8. 批次 aggregate check 证明所有子项目完成。之后对某个子项目的手动修改离开本路径,进入该目录的 Revision。
-
-每个变体子项目使用:
-
-```text
-baseline-copied → brief-frozen → change-scope-frozen → guidance-loaded
-→ vocabulary-verified → package-ready → script-checked → source-updated
-→ graph-checked → layout-checked → final-checked → variant-complete
+hypit-reference-video-tools render_element ./build.svrun \
+ --element ranking --segment list --reference-id <reference-id> \
+ --out ./review/ranking-list.mp4
+hypit-reference-video-tools compare_reconstruction \
+ --reference-id <reference-id> --run ./build.svrun --segment list \
+ --video ./review/ranking-list.mp4 --element ranking
```
-变体路线刻意采用“先复制、后修改”:
-
-| 步骤 | 主 agent 或子 agent 的工作 | 工具或文档 | 持久化结果与作用 |
-|---|---|---|---|
-| 1. 验证母项目 | 确认父路线/Revision 已通过最终门禁并记录 digest。 | `route_state/revision_state reconcile`、`variant_state start` | 所有子项目从同一个已知良好的 Film graph 出发。 |
-| 2. 决定 Slate | 根据已验证母项目和用户请求决定变体方向及数量配额(总和为 N),冻结每个方向的 Format DNA 和允许范围;不检查 examples。 | `playbooks/index.md`、母项目 Source/brief、`format-plan.json`、`slate.json` | 创意方向一次全局决定;派发时按方向配额展开唯一编号的子项目。 |
-| 3. 决定词汇和工作量 | 检查包与公开词汇,决定复用/组合/新包,并披露快速、中等、新包数量。 | `list_svml_packages`、`inspect_svml_vocabulary`、`component-plan.json`、`variant_state checkpoint` | 子 agent 启动前用户就知道时间和成本影响,不会做到一半才发现缺包。 |
-| 4. 预先开发新包 | 每个不同缺口只开发一次,在 staging 验证、冻结 digest、标记 ready。 | `route_state --route variant-package`、`local-author-package.md`、`validate_local_author_packages`、`preview_check`、`layout_check` | 多个变体安全复用同一个包,且不会修改安装包。 |
-| 5. 先复制母项目 | 尽可能 copy-on-write,保留作者资产和 Source,删除生成状态/结果和旧 Build 绑定,只注入已 ready 的包。 | `variant_init` | 每个子项目独立、可复现,没有过期的付费产物或生成结果。 |
-| 6. 分批派发 | 给每个子 agent 自己的目录、brief、格式/组件计划、README/证据和允许范围。 | 子项目 `route_state`、`variant_state` | 可以并行处理,同时每个变体都有可审计的任务契约。 |
-| 7. 验证并最小修改 | 组件变化时才在副本中检查词汇,只改允许文件,运行所有机械门禁。 | 需要时 `inspect_svml_vocabulary --run`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check`、`variant_check` | 只改 SVML 的任务保持快速;越界修改会成为显式冲突,不会静默扩大。 |
-| 8. 汇总交付 | 恢复未完成子项目,运行 aggregate check;需要成片时再计划/批准付费 Build。 | `variant_state reconcile`、aggregate report、`hypit plan/build` | 100 项批次只恢复未完成项,且上下文压缩后不会重复付费 Build。 |
-
-## JSON 状态机与恢复
-
-状态拆成当前指针和执行范围内的历史,避免上下文压缩成为唯一记忆来源:
-
-| 内容 | 持久化位置 |
-|---|---|
-| 创作当前视图 | `<project>/.hypit/route-state.json` |
-| 创作历史/证据 | `<project>/.hypit/routes/<route-id>/state.json`、`.hypit/evidence/` |
-| brief 与组件判断 | `<project>/.hypit/brief.json`、`<project>/.hypit/component-fit.json` |
-| Revision 当前视图/历史 | `.hypit/revision-state.json`、`.hypit/revisions/<revision-id>/{state.json,request.json}` |
-| 变体批次 locator | `<base>/.hypit/variant-expansions/<batch-id>.json` |
-| 变体批次状态 | `<batch>/.hypit/variant-expansion-state.json` |
-| 子项目/staging 状态 | 子项目或 staging 的 `.hypit/route-state.json` 及其 history |
-
-每份状态记录 route id、当前游标、完成步骤、`next_action`、决策、冲突、最后命令、证据路径和 digest。
-机器证据可由工具确认;brief、component fit、format plan、Slate、allowed changes 等人工决策必须明确写入,不能从文件存在与否推断。
+每次明确发起的比较都是一次新的观察。工具不会根据文件摘要静默复用旧答案。
+`reconstruction_check` 只汇总哪些内容看过、哪些没看过,不持有工作流游标。
-路线状态的每次推进都必须写入证据,不能只依赖聊天中的一句“完成了”:
+## Build 与复用
-```text
-Agent 做出决策或修改 Source
- → checkpoint 写入决策和输入 digest
-工具执行检查/渲染/评审
- → 成功结果写入不可变 evidence 路径
-只有结果满足该步骤的成功谓词,状态才推进
- → 当前视图和执行历史原子更新
-```
-
-状态结构保持精简,但关键字段明确:
-
-```json
-{
- "version": 1,
- "route": "description",
- "route_id": "...",
- "current_step": "graph-checked",
- "completed_steps": ["environment", "brief-frozen", "source-authored"],
- "next_action": "layout_check --run build.svrun",
- "decisions": { "brief": ".hypit/brief.json", "component_fit": ".hypit/component-fit.json" },
- "evidence": [{ "kind": "preview_check", "path": ".hypit/evidence/...json", "digest": "..." }],
- "conflicts": [],
- "last_command": "hypit-reference-video-tools preview_check ..."
-}
-```
-
-`checkpoint` 用于记录明确的 Agent 决策或已完成命令;`read` 用于读取持久化游标;`reconcile`
-只重新计算机器成功谓词并让过期证据回滚;`discover` 用于 Agent 不再记得批次目录时通过 locator 找回批次。
-文件存在本身永远不能推进状态。
-
-常用接口:
-
-```bash
-# 创作路径
-hypit-reference-video-tools route_state --action read --project-root <project>
-hypit-reference-video-tools route_state --action checkpoint --project-root <project> \
- --route <description|reconstruction> --state <stage>
-hypit-reference-video-tools route_state --action reconcile --project-root <project>
-
-# Revision
-hypit-reference-video-tools revision_state --action start --project-root <project> \
- --run <project>/build.svrun --request '<change>'
-hypit-reference-video-tools revision_state --action read --project-root <project>
-hypit-reference-video-tools revision_state --action checkpoint --project-root <project> \
- --step <stage-number> --status complete --decision '<what was decided>'
-hypit-reference-video-tools revision_state --action reconcile --project-root <project>
-
-# 变体批次
-hypit-reference-video-tools variant_state --action discover --project-root <base>
-hypit-reference-video-tools variant_state --action checkpoint --project-root <base> \
- --batch-id <id> --step <stage-number> --status complete
-hypit-reference-video-tools variant_state --action read --project-root <base> --batch-id <id>
-hypit-reference-video-tools variant_state --action reconcile --project-root <base> --batch-id <id>
-```
+外部生成涉及费用时先运行 `hypit plan`;用户需要执行时再运行 `hypit build`。Build 的公开输出
+进入它自己的 Result。组件公开输出端口产生的中间图片、视频或结构值也会保存,因此后续工作
+可以直接指向它们,不需要把 Run target 偷换成所有中间值的清单。
-所有 JSON 都先写临时文件再原子 rename。损坏文件会被保留并报错,不会被空状态覆盖。`reconcile`
-验证每个机器步骤的成功谓词,检查父路径、Source、包和证据 digest,把过期步骤回滚到第一个未
-完成步骤并报告冲突;它不会发明创意决策、静默扩大 allowed scope、重复完成变体或重新提交付费 Build。
+即使 Run 文件完全没变,多次 Build 仍然得到互相独立的 Result。重要的 Result 和输出使用
+Result presentation 命令赋予人类名称,不建立内容摘要、中心 artifact 表或隐藏历史系统。
-中断或上下文压缩后,重新读取 skill 和对应路径,发现/读取 canonical state,执行 reconcile,检查冲突,
-然后只执行第一个未完成的 `next_action`。因此长时间复刻和 100 项变体批次都不依赖对话记忆。
+批量变体使用普通项目目录和调用者明确维护的任务清单。复制、调度和命名属于调用者或专门的
+批处理工具;reference-video-tools 不再维护第二套 variant 状态机。
diff --cc docs/zh/quickstart.md
index 9af7f90c,a2a3836f..f4009e24
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@@ -16,12 -16,12 +16,13 @@@ Hypit 把这份源码编译成一张可
## 安装
```bash
--npm install --global hypit
npx skills add hypit-ai/hypit --global
```
--第一条命令安装可复用的 Distribution;第二条把 skill 全局安装,使以后任何项目里的新 Agent
--会话都能找到它。普通创作不需要克隆仓库。
++这会把真实的 `skills/hypit/` 子目录安装到全局,使任何项目里的新 Agent 会话都能找到它。
++OpenAgents 也直接从仓库安装同一个子目录。Skill 安装和可执行 Distribution 是两件事:在 npm
++包正式发布前,Skill 会在机器级 `<home>/hypit` 准备或更新 checkout,并使用它的 Node 入口。
++视频项目与二者独立,可以位于任意位置。
## 使用 Hypit skill
@@@ -33,16 -33,16 +34,20 @@@
它会走下面同样的五个步骤,并且只向你索取 Runtime Profile 实际需要的东西。不想用 Agent 的话,也可以自己依次完成这五步。
--## 1. 检查已安装的 Distribution
++## 1. 检查选中的 Distribution
需要 Node.js 22+,桌面系统为 macOS 13+ 或 Windows 10/11 x64。
```bash
hypit paths --json
++# npm 发布前,Skill 实际运行:
++node <home>/hypit/bin/hypit.mjs paths --json
```
--结果会分别给出当前项目、项目 `.hypit` 状态、机器 Program Home 与 npm Distribution。
--pnpm、Corepack 和 `npm link` 只属于贡献者工作流。
++结果会分别给出当前项目、项目 `.hypit` 状态、机器 Program Home 与选中的 Distribution。
++Agent 会在机器级准备 checkout 的锁定依赖,不会把依赖安装到视频项目,也不会使用 `npm link`。
++
++下文统一把两种可执行入口简称为 `hypit`。
## 2. 编译示例
diff --cc packages/provider-hypihub/test/provider.test.ts
index 2ffbc64a,ee1a0528..ae0b1ed9
--- a/packages/provider-hypihub/test/provider.test.ts
+++ b/packages/provider-hypihub/test/provider.test.ts
@@@ -125,12 -118,12 +125,12 @@@ test("HypiHub uploads referenced Artifa
});
test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every media Artifact", async () => {
- const artifacts = new MemoryArtifactStore();
- const image = await artifacts.put(new Uint8Array([1, 2, 3]), "image/png");
- const video = await artifacts.put(new Uint8Array([4, 5, 6]), "video/mp4");
+ const resources = new MemoryResourceStore();
+ const image = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
+ const video = await resources.put(new Uint8Array([4, 5, 6]), "video/mp4");
const request: Need = {
id: "need:hypihub-gemini",
- capability: geminiCapabilities["gemini-3.7-flash"],
+ capability: geminiCapabilities["gemini-3.7-flash-openai"],
returns: textTypes.text,
constraints: sealGeminiRequest({
instruction: "Answer briefly.", prompt: "Inspect both references.",
diff --cc packages/reference-video-tools/README.md
index cb4ce2ed,80d61e66..332d0d50
--- a/packages/reference-video-tools/README.md
+++ b/packages/reference-video-tools/README.md
@@@ -21,62 -56,86 +21,64 @@@ new explicit observation; it is not sup
```bash
hypit-reference-video-tools list_svml_packages
-hypit-reference-video-tools prepare_reference --video-path ./reference.mp4
-hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --redo people
-hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --redo transcript
+hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --observer agent
hypit-reference-video-tools observe_reference --reference-id <reference-id>
-hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007
-hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007 --question "How thick is the outline on the caption words?"
-hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007 --reobserve
+hypit-reference-video-tools record_observation --reference-id <reference-id> --key <key> --text-file ./answer.md
hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/media-track --tag Track
-hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id shot-007 --image ./rendered.png
-hypit-reference-video-tools variant_state --action discover --project-root ./projects/base
-hypit-reference-video-tools variant_state --action start --project-root ./projects/base --output-root ./projects/base-variants/<batch-id> --count 100
-hypit-reference-video-tools variant_init --project-root ./projects/base --output-root ./projects/base-variants/<batch-id> --slate ./slate.json
-hypit-reference-video-tools variant_check --run ./projects/base-variants/<batch-id>/001-example/build.svrun
+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun
+hypit-reference-video-tools validate_script_cues --run ./build.svrun
+hypit-reference-video-tools preview_check ./build.svrun
+hypit-reference-video-tools layout_check --run ./build.svrun
+hypit-reference-video-tools render_element ./build.svrun --element title --segment intro --out ./title.mp4
+hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --run ./build.svrun --segment intro --video ./title.mp4 --element title
+hypit-reference-video-tools review_element --run ./build.svrun --element title --segment intro --video ./title.mp4 --intent-file ./title-intent.md
+hypit-reference-video-tools reconstruction_check ./build.svrun --reference-id <reference-id>
+hypit-reference-video-tools authoring_check ./build.svrun
```
-For automation, every command also accepts `--input '{"...":"..."}'` with the complete JSON input
-object. This is useful when the calling agent already has a structured request.
-
-`list_svml_packages` reports every installed package that declares an activation, with the Surface
-tags it registers. `inspect_svml_vocabulary` reads packages you can already name, and the Build CLI
-is deliberately unable to scan a directory, so this is how a caller finds out what vocabulary exists
-instead of working from memory.
-
-`prepare_reference` requires a local video path and stores derived media under the checkout's
-gitignored `.hypit/reference-video-tools/` directory, which is where every other command reads it
-from whichever directory it is run in. It produces four full-reference observations: `people_and_product`,
-`voices`, `persistent_systems` — 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 — and `places`: 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. Without `--redo`, completed stages are reused. Use `--redo media` to rebuild shot media and
-clear derived observations, `--redo transcript` to measure the words again, or `--redo people`, `--redo voices`, `--redo systems`, `--redo places`, or `--redo all` to
-rerun only the selected full-reference stages.
-
-It also produces `transcript`: the verbatim speech of the whole reference with a start and an end for
-every single word. Placing an on-screen text reveal against the line that triggers it needs the time
-of the word, not of the sentence around it, and that question comes up in every reconstruction. The
-speech audio is extracted to `speech.wav` beside the shot media and measured by the local WhisperX
-Provider in `@hypit/provider-whisperx-local`, which answers a loopback service on
-`http://127.0.0.1:8765`; start the selected managed service with `hypit runtime up`.
-The result reports `status`, `transcript_ref` and `word_count`, and the words themselves live in
-`transcript.json` as passages, each with a `words` array of `{ text, start_seconds, end_seconds, score }`.
-The transcript is deterministic local evidence rather than an observation: it is never written to the
-observation cache and nothing about it is sent to Gemini. A machine with no WhisperX service running
-reports `status: "unavailable"` with the reason and prepares everything else.
-
-`observe_reference` observes every unfinished shot, or only the shots named by `--shot-id`. Each shot
-produces three observations — `visual` (base picture, covering content, continuity, whether the frame
-is a depicted scene or a flat designed field, and each framed element's inner picture separately from
-its frame), `text_appearance` (typeface, weight, size, spacing, colour, stroke, shadow, glow,
-per-word emphasis, position and entry of drawn text), and `audio`. The picture observation also
-states whether the picture moves and how, separating camera movement from movement within it, since a
-held still and a moving shot are reconstructed differently. Each cut adds one `continuity`
-observation covering both whether the two shots are one continuous camera shot and whether an overlay
-continues across the boundary. The preceding tail frame, audio tail and full-reference context are
-attached automatically. Completed observations are reused; `--reobserve` is the only way to run a
-completed one again.
-
-Shots are never shorter than one second: a fragment below that is merged into the shot before it,
-because clips that short carry no evidence and the model rejects them outright.
-
-`HYPIT_REFERENCE_CONCURRENCY` and `HYPIT_REFERENCE_LAUNCH_GAP_MS` set how fast requests are issued,
-defaulting to four at a time with a 1.5 second gap. They describe the quota behind the credentials
-rather than anything about the video, so they are environment settings and not flags. Lower them if a
-quota objects; the failure to expect is rate limiting, which backs off on its own before giving up.
-
-`--question` is a separate narrow path: it requires exactly one `--shot-id`, answers only that
-question from that shot's clip and frames in a single request, and neither reads nor writes the
-observation cache. Cross-shot continuity uses the built-in boundary and three-shot window observations.
-
-`compare_reconstruction` sends the named shot's reference frame and a rendered image as an
-unlabelled pair and returns a description of their visible differences. It is never told which image
-is which, what was built, or how. `--question` narrows it to one region of the picture and nothing
-else. Results are not cached, because the rendered side changes on every iteration.
-
-`unresolved` lists the keys of observations that failed. It is not a judgement about evidence
-quality: a complete observation that says "unclear" is still complete.
-
-Gemini uses `HYPIT_GEMINI_PROVIDER=auto|hypihub|vertex` to select its backend. The backends are
-provided by `@hypit/provider-hypihub` and `@hypit/provider-vertex`. HypiHub uses
-`HYPIHUB_API_KEY` and optional `HYPIHUB_BASE_URL` (default `https://hypit.ai`); Vertex uses the
-existing `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` and optional
-`GOOGLE_CLOUD_LOCATION`. The model defaults to `gemini-3.7-flash-openai`. A missing or insufficient
-user key should be resolved by obtaining a HypiHub key at https://hypit.ai, not by changing Source.
+Every command prints one JSON result. Commands also accept `--input '{...}'` when structured input is
+more convenient. Batch forms read JSON arrays from files for observations, comparisons, renders,
+reviews and layout decisions.
+
+## Reference preparation
+
+`prepare_reference` accepts a local path or a supported video URL. It extracts bounded shot clips,
+representative frames, a storyboard, speech audio and a word-timed transcript. The returned reference
+id contains the source filename, byte length and modification time so it is inspectable without a
+lookup table.
+
+`--observer gemini` uses HypiHub or Vertex according to the configured provider. `--observer agent`
+calls no visual provider; it returns observation tasks with local pictures and transcript context for
+the calling agent to answer through `record_observation`.
+
+Prepared stages are reused until the caller explicitly asks for `--redo ...` or `--reobserve`. This
+is ordinary working data for one reference, not Build history.
+
+## Inspection and review
+
+`inspect_svml_vocabulary` reports the public Surfaces of packages the caller names.
+`inspect_visual_schema` reports the actual Composition schema accepted from drawing Producers.
+`validate_local_author_packages`, `validate_script_cues`, `preview_check`, `layout_check`,
+`reconstruction_check` and `authoring_check` are independent reports. None approves or unlocks
+another command.
+
+`layout_check` always measures the current realized DOM. Its report contains advisory candidates such
+as overflow, overlap and vertical offset. `layout_accept` attaches a human reason to a structural
+finding id; it does not fingerprint the project or cache a previous measurement.
+
+`render_element` draws one element directly from the Run using local preview media. A comparison reads
+that render against the requested reference stretch. A review reads it against an explicit intent.
+Their JSONL logs contain the actual question, paths and prose answer so later inspection does not
+depend on a separate state database.
+
+## Environment
+
- Reference observation uses `HYPIT_GEMINI_PROVIDER=auto|hypihub|vertex`. HypiHub reads
- `HYPIHUB_API_KEY` and optional `HYPIHUB_BASE_URL`; Vertex reads `GOOGLE_CLOUD_PROJECT`,
- `GOOGLE_APPLICATION_CREDENTIALS_JSON` and optional `GOOGLE_CLOUD_LOCATION`.
++Reference observation uses `HYPIT_GEMINI_PROVIDER=auto|hypihub|vertex`. HypiHub first reads the
++`hypihub.oauth` session written by `hypit auth login` from the OS credential store, then falls back to
++`HYPIHUB_API_KEY`; `HYPIHUB_BASE_URL` remains optional. Vertex reads `GOOGLE_CLOUD_PROJECT`,
++`GOOGLE_APPLICATION_CREDENTIALS_JSON` and optional `GOOGLE_CLOUD_LOCATION`. Gemini defaults to
++`gemini-3.7-flash-openai`.
+
+Transcript preparation uses the selected local WhisperX service. Start services through the normal
+Runtime configuration with `hypit runtime up`. `HYPIT_REFERENCE_CONCURRENCY` and
+`HYPIT_REFERENCE_LAUNCH_GAP_MS` only control observation request pacing.
diff --cc packages/reference-video-tools/src/checks.ts
index 14cc81e3,f7e2ab6a..14c39845
--- a/packages/reference-video-tools/src/checks.ts
+++ b/packages/reference-video-tools/src/checks.ts
@@@ -1180,12 -1182,12 +1180,12 @@@ export async function authoringCheck
never_compared: {
ids: never.map((element) => element.id),
next: mode === "reconstruction"
- ? "Read .agents/skills/hypit/references/element-review.md and "
- + ".agents/skills/hypit/references/reconstruction/comparison-round.md, then for each: "
- ? "Read skills/hypit/references/element-review.md and "
- + "skills/hypit/references/reconstruction/comparison-round.md, then for each: "
++ ? "Read <skill-root>/references/element-review.md and "
++ + "<skill-root>/references/reconstruction/comparison-round.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."
- : "Read .agents/skills/hypit/references/element-review.md and "
- + ".agents/skills/hypit/references/original-authoring/conformance-round.md, then for each: "
- : "Read skills/hypit/references/element-review.md and "
- + "skills/hypit/references/original-authoring/conformance-round.md, then for each: "
++ : "Read <skill-root>/references/element-review.md and "
++ + "<skill-root>/references/original-authoring/conformance-round.md, then for each: "
+ "render the element as the Source configures it, mock the layers a Build has not made, "
+ "and have it read against what this element was asked to be — one review per Segment or "
+ "Selection it is drawn over.",
diff --cc packages/reference-video-tools/src/tools.ts
index d3f5dd38,35bf40d1..25951765
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@@ -1307,7 -1676,7 +1321,7 @@@ export function createReferenceVideoToo
...(fetched === undefined ? {} : { source_url: fetched.url, downloaded: !fetched.cached }),
pending_observations: pending,
...(whisperx?.ok === false
- ? { whisperx: `${whisperx.reason}. Read .agents/skills/hypit/references/host-setup.md for the failure branches.` }
- ? { whisperx: `${whisperx.reason}. Read skills/hypit/references/host-setup.md for the failure branches.` }
++ ? { whisperx: `${whisperx.reason}. Read <skill-root>/references/host-setup.md for the failure branches.` }
: {}),
};
},
diff --cc skills/hypit/SKILL.md
index 8365a947,ac5a035c..18d95fed
--- a/skills/hypit/SKILL.md
+++ b/skills/hypit/SKILL.md
@@@ -5,114 -5,298 +5,134 @@@ description: Produce a complete video p
# Hypit
-> **Scope boundary:** This is a production skill for creating, reconstructing, previewing, reviewing,
-> revising and building videos with Hypit. It is **not a development skill for the Hypit repository
-> itself**. If the task is to implement, debug, test, refactor or otherwise develop Hypit packages,
-> CLIs, Studio, runtime or repository infrastructure, ignore the video-production routes and follow
-> the repository's contributor/development instructions instead.
+> **Scope boundary:** This is a production skill. When the task is to implement, debug, test or
+> refactor the Hypit repository itself, do not use this production workflow.
-## Project isolation (hard boundary)
+Complete the production task without asking the author to choose routine implementation details.
+Interrupt only for an action that spends their money, for genuinely missing credentials, or for the
+choice of observer that will read a reference video.
-Every author project is an independent workspace. Once the active project boundary is selected, read
-and modify only that project's Sources, assets, Runtime Profile, state, outputs and `packages/`
-directory. Never inspect, import, copy, symlink or otherwise borrow files from another author project,
-including another project's local package. A missing capability must use an installed official package
-or the formal local-package workflow inside the active project; it is never solved by taking a package
-from a sibling project. Repository `examples/` are read-only reference material and may be inspected
-only when the selected route explicitly permits it (currently original authoring); they are not
-dependencies and their local packages must never be reused. The sole reconstruction exception,
-`examples/minimal-author-package/`, is generic contract guidance after a proven gap, not a package to
-install or copy across projects. Reconstruction and variant routes keep their existing stricter
-prohibition on reading repository examples.
+Before a paid Build, run `hypit plan`, state the estimated cost and the selected Provider/credential
+source without exposing secrets, and obtain approval. A Build is never an implicit consequence of a
+preview, inspection or review command.
-## Session initialization
+## Project model
-When this Skill is loaded for the first time in a new conversation, synchronize the complete Hypit
-repository before entering any production route. If the selected Distribution is a Hypit contributor
-checkout, update that checkout first:
+Keep these separate:
-```bash
-git pull --ff-only origin main
-```
-
-This is a whole-repository update: it refreshes the CLI, packages, services, examples, docs and Skill
-source together. Do not run a Skill package-manager update or overwrite the installed Skill from this
-startup path. Run the repository pull once per conversation, do not repeat it for later turns, and then
-continue with the current request using the current checkout. Do
-not reset or overwrite local changes: if `git pull --ff-only origin main` cannot fast-forward, stop and
-report the sync conflict. If no contributor checkout is selected, there is no local repository to pull;
-use the currently installed Skill without attempting a Skill update. If the repository pull cannot
-complete because the network or Git is unavailable, report that the latest state could
-not be confirmed before proceeding; never pretend the repository is current.
+- `.svml` Author Source describes the program;
+- `.svs` Recipe Source describes generation choices;
+- `.svrun` Run Source binds one executable request;
+- `hypit.runtime.json` selects external execution facilities;
+- a Build is one execution;
+- a Result is the project-owned record of what that Build produced.
-**Run the route to the end without stopping.** There is one thing worth interrupting the author for;
-everything else is yours to decide:
+Do not create route state, revision state, recovery cursors, content-addressed evidence directories or
+aggregate approval state. Continue from the files that actually exist in the project. A reference
+observation, render, comparison, layout report or Result is useful content; it is not proof that an
+agent completed an abstract stage.
-- **Spending their money.** A Build generates, and generating is billed. Say what it will cost and
- get a yes before submitting one. Before asking for approval, report the Provider and credential
- source used by every paid capability (without revealing secrets). Credential setup must already be
- complete at the environment gate; do not defer login until this paid handoff.
+Do not repeat a paid Build just because conversation context was compacted. Inspect the Run and its
+Results directly. If a Result exists, use it. If execution is still active, use Runtime status. If
+there is no Result and no active Build, ask before submitting a new paid Build.
-Everything else — the working directory, the project location, which packages to use, which generator
-draws a picture, how to name a Segment, what to do about something a review reported — is a
-choice between things that all work, and asking costs the author an interruption to answer a question
-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.
++Once the active project boundary is selected, read and modify only that project's Sources, assets,
++Runtime Profile, state, outputs and `packages/` directory. Never borrow, copy or link a local package
++from another author project. Use an official package from the selected Distribution or create the
++missing component inside the active project. Distribution examples are read-only inspiration for
++original authoring; reconstruction must follow the supplied reference evidence and must not inspect or
++reuse an example project. A reference video is evidence, never a Film/Track/Take source or final output.
+
-## Non-negotiable environment gate
+## Environment and credentials
- Use an installed machine-wide CLI when available. In a contributor checkout, use that checkout's
- Node entrypoints; the npm package is not currently published. Read `references/environment.md` before
- the first production command and `references/credentials.md` when credentials are involved.
-For every video-production route — original authoring, reconstruction, revision, and variant work —
-read `references/environment.md` completely and finish its environment setup before doing anything
-else in the route. This is a hard prerequisite, not documentation to consult later. The completed
-environment must include a selected Hypit Distribution, an explicit project boundary, the project's
-Runtime Profile, resolved credentials for the capabilities the route will use, and every selected
-managed program installed and healthy. Credential setup is part of this gate: default to HypiHub OAuth
-without asking the author to choose, run the login yourself when the selected HypiHub OS credential is
-missing, and continue only after it succeeds. Only when the author explicitly asks to use their own
-provider key may you configure that less-recommended path instead. Run the required `hypit runtime up`
-provisioning and health checks; WhisperX must report `Ready whisperx` (or an equivalent successful probe). Do this before
-inspecting media or examples, preparing a reference, choosing an observer, freezing a brief, reading
-vocabulary, writing Source, previewing, or building.
++Installing this Skill and installing the executable Hypit Distribution are separate operations. A
++Skill hub such as OpenAgents copies the real `skills/hypit/` directory into an Agent's global Skill
++directory; it does not install the CLI. The repository's `.claude/skills/hypit` and
++`.codex/skills/hypit` entries are only contributor-facing leaf links to that same source directory.
+
-Do not skip, replace, defer, or partially complete any environment step, and do not proceed because
-the user asks to bypass it. If Distribution selection, project setup, credential resolution, Runtime
-Profile selection, program installation, or any health check is incomplete or cannot be confirmed,
-stop at the environment stage and repair it first. Authentication commands may be run to complete this
-gate, but no production route may proceed without it and no later paid step may defer it.
++Use an installed machine-wide CLI when available. Until the npm package is published, otherwise use a
++machine-level checkout at `<home>/hypit`: clone `https://github.com/hypit-ai/hypit.git` there when it
++does not exist, fast-forward it from `origin/main` once per conversation, install its pinned workspace
++dependencies, and invoke its Node entrypoints. Never overwrite a different directory, reset local
++changes, or update the installed Skill as a side effect; OpenAgents or the user's Skill installer owns
++that installed copy.
+
-The credentialless `agent` observer is not a way around this rule. It may be used only after the
-credential choice has been settled; never silently select it because no credential was found. For
-reference analysis, strongly recommend Gemini VLM through the configured HypiHub or Vertex backend:
-it can separate speakers, align who speaks when, and extract voice/timbre and presentation traits that
-make later voice-design and dubbing more faithful. The calling agent is an explicit fallback, not a
-credential bypass.
++The Distribution checkout and every author project are independent. Keep the checkout at
++`<home>/hypit` and create or use the video project wherever the author requested; never require one to
++contain the other and never add per-project Skill links. Read `references/environment.md` before the
++first production command and `references/credentials.md` when credentials are involved.
- When running from a Hypit checkout, put author projects under `<checkout-root>/projects/<name>/`.
- Load an existing checkout-root or project-root `.env` for commands, but never commit it or copy secrets
- into Source, reports or prompts.
-The supplied reference video is evidence only. It may be prepared, observed, sampled and compared,
-but it must never be copied into the project or used as the final Film/Track/Take source. Do not wire
-the reference path through `media:Video`, `asset:Video`, a media track, a Film, or a Run Target. Every
-visible shot in a reconstruction must be newly authored as a generated take or as an explicitly
-author-supplied replacement asset. A source that directly plays the reference is not a reconstruction
-and must be rejected before preview or Build.
++Load an existing Distribution-root or project-root `.env` for commands, but never commit it or copy
++secrets into Source, reports or prompts.
-**Reconstruction has an evidence-first reading order.** On the reconstruction route, never inspect the
-repository's `examples/` projects at any point. Do not read their complete SVML, SVS, SVRun, README,
-assets or variants: that material can anchor the agent to an unrelated implementation and overwhelm the
-reference evidence. The only permitted `examples/` exception is the
-`examples/minimal-author-package/` fixture, and only after a real vocabulary gap has been proven and
-the local-package workflow explicitly requires its generic contract. First complete the environment
-gate, prepare the reference, run the selected observer and resolve its shot/continuity evidence. Then
-consult only the installed package vocabulary and the specific craft guidance needed by the observed
-systems. Complete examples are for original authoring and variant planning, never reconstruction.
-
-## Login-only fast path
-
-If the request is only to sign in or authenticate HypiHub (for example, `login to hypit`), treat it as
-credential setup, not video production. Do not read or enter the reconstruction, original-authoring,
-observer, playbook, vocabulary, preview, or recovery routes; do not inspect media, create a project,
-start a Worker, or ask which observer to use. Do not read any supporting reference for this path,
-including `environment.md` and `credentials.md`; this section contains the needed login instructions.
-This is a strict login-only fast path, not a general environment-diagnosis route. Do not run
-`ls`, `find`, `rg`, `pwd`, `which`, `cat`, `head`, `tail`, `grep`, `doctor`, `runtime status`,
-`runtime logs`, `runtime up`, any `--help` command, or any other exploratory command. Do not inspect
-`.env`, `hypit.runtime.json`, package code, CredentialStore implementations, or repository metadata.
-Do not compose exploratory shell commands around the login commands. Use the already selected Runtime
-Profile (or the explicit profile the author names) and invoke the configured launcher directly. For
-the standard HypiHub OAuth endpoint, the only allowed probe is:
+For a login-only request, do no project discovery. Use only:
```bash
hypit auth status hypihub.default [--runtime <explicit-profile>]
hypit auth login hypihub.default [--runtime <explicit-profile>]
```
-Wait for it to finish. The login-only path consists solely of `auth status`, the one short explanation,
-and `auth login`; never add discovery, help, diagnostics, or source inspection between them.
-
-## Credentials: complete them during environment setup
-
-During environment setup, before any media inspection, observer call, model call, preview, or Build,
-check the selected HypiHub Endpoint's credential with `hypit auth status <endpoint> --runtime <profile>`.
-If the writable OS credential is missing, explain that HypiHub OAuth is the default because it avoids
-copying a key, then immediately run `hypit auth login <endpoint> --runtime <profile>` yourself. Do not
-ask the author to run the command or paste a key. A configured credential needs no repeated login. If
-the author explicitly requests their own key, configure the requested Provider instead and tell them
-this is the less-recommended path. Never defer credential setup until a paid Build.
+Run login only when status says the selected credential store is writable and the credential is
+missing. Explain that browser sign-in stores a session in the OS credential store and does not submit
+a paid generation.
-When a selected HypiHub Endpoint is missing its OS credential, first tell the author why you are opening the login: no usable credential is configured, and browser sign-in lets Hypit use HypiHub without asking them to copy or paste an API key. If the account has no active Hypit subscription, they can purchase one on hypit.ai after signing in. The session is stored in the OS credential store, and opening login does not itself submit a paid generation. Then run `hypit auth login <endpoint> --runtime <profile>` yourself. The command opens the HypiHub login page, waits for the OAuth callback, and stores the resulting session in the OS credential store. Do not tell the author to copy a key or run the command manually. Continue only after login succeeds; if it is cancelled or fails, stop at environment setup.
+## Authoring rules
-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.
+Every captioned or on-screen spoken passage must use short complete Cues separated by `||`. Default to
+roughly 3–4 spoken words per Cue, fewer for dense words. Read `references/script-time.md` and the
+caption craft before writing Script text.
-Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, and
-`hypit.runtime.json` Runtime Profile as separate languages and responsibilities.
+Never rely on renderer wrapping to rescue a long Cue. Never hand-author SVG files, inline SVG or SVG
+data URLs in an author project or project-local package. Never modify an installed package for one
+project; use another public Surface or create a project-local package for a real capability gap.
-Non-negotiable Script rule: every captioned or on-screen spoken passage must be split into short,
-complete Cues with `||` in the Script. As the default, cut after roughly 3–4 spoken words (fewer when
-the words are long or visually dense); longer runs require an explicit visual reason. Never rely on
-renderer line wrapping or a wide Caption box to rescue a long Segment: a Segment without `||` is one
-Cue and will overflow the Canvas. Read
-`references/script-time.md` and the caption craft before writing Script text; put breaks between
-complete Alignment Units, never inside Dual Text.
+The temporary `@hypit/ranking` branch restriction remains: do not select, read or use that installed
+package. Use another applicable capability or develop a project-local alternative.
-Every route is resumable. At the start of a route, create the project's current
-`.hypit/route-state.json` view; the execution history lives at
-`.hypit/routes/<route-id>/state.json`. Revisions likewise keep the current
-`.hypit/revision-state.json` view and execution history under `.hypit/revisions/<revision-id>/`.
-After any new turn, interruption, or context compaction, read
-`references/recovery.md`, inspect that snapshot and reconcile it against the artifacts and checks
-before continuing. Never resume from chat memory alone, and never repeat a completed or paid step
-without verifying its durable evidence.
+## Direct inspection
-## Conversation language preference
+The reference-video commands are independent tools, not ordered stages:
-On the first production turn, infer the author's preferred reply language from the current request and
-record it in the route JSON state as a decision such as `user-language: zh-CN` (use an appropriate BCP 47
-language tag). If the author explicitly requests a different language, update that decision. On every
-later turn in the same conversation, read the current route state and reply in its recorded language;
-do not switch languages merely because a command, filename, prompt or quoted source uses another one.
-Keep code, CLI commands, model names and quoted Script text unchanged. Login-only conversations have no
-production route state; keep the preference in conversation context until a project route starts.
-
-Temporary branch constraint: do not select, use or read the installed `@hypit/ranking` package or
-its declarations, README, examples or source on this branch. If a request needs a ranking-like
-visual system, choose another applicable installed capability or treat the requirement as a genuine
-gap and use the formal project-local package workflow from the visible requirement. Do not copy,
-vendor or modify `@hypit/ranking`. This is an internal routing constraint: do not tell the author
-that a choice was made because of the skill or this constraint. Present the chosen alternative or
-new local component as the normal production decision, with its practical rationale when useful.
-
-Before Source is accepted, every route must complete persisted vocabulary inspection,
-`validate_local_author_packages` for every project-owned package under the project's `packages/`
-directory, and
-`validate_script_cues` (maximum four visible words per Cue). `preview_check` and the route's final
-check repeat these gates even if route-state claims they were completed.
-When a Run contains accepted `build-record` pins, pass its Runtime Profile to
-`validate_local_author_packages`, `preview_check`, `layout_check` and the final check so the archive
-can resolve those Records before any graph or layout result is trusted.
-
-Agent-boundary constraint: do not read or rely on the memory of Codex, Claude Code, or any other
-coding agent.
-
-Do not create or hand-author SVG images anywhere in an author project or project-local package.
-This includes `.svg` assets, inline `<svg>` markup, and SVG data URLs.
-
-Every route uses a Hypit Distribution and an independent author project. Prefer an installed
-machine-wide CLI; when the task is running from a Hypit contributor checkout, use that checkout's
-Node entrypoints instead. The npm package is not currently published, so absence of the `hypit`
-command is not permission to install it from the registry. `references/environment.md` establishes
-the boundary and launcher selection. Read it before the first command of any route.
-
-When running from a Hypit checkout, create new author projects under
-`<checkout-root>/projects/<project-name>/`. Before asking for credentials, check for `.env` at the
-checkout root and at the project root, load any present file into the command environment, and use
-the credentials it provides. If the loaded credentials satisfy the selected observer or Provider,
-do not ask the author to repeat them; ask only when a required credential is genuinely absent or
-invalid. Never commit `.env` or copy its secret values into route state, Source, logs or prompts.
-
-## Route
-
-- Reference-video reconstruction, reverse engineering, shot/B-roll/overlay analysis, or recreating
- 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 video, with or without words around it, is
- this route** even when no verb is given at all. A path to a file and a link to one — TikTok,
- YouTube, Instagram, Bilibili — are the same request; a link is fetched with `yt-dlp` and everything
- after that reads the file. A video with a change attached —
- this one but with our presenter, our product, our brand — is this route too, and the change is made
- on the finished reconstruction. **Do not inspect any `examples/` project on this route; the only
- exception is the generic `examples/minimal-author-package/` fixture after a proven package gap.** The
- reference evidence is the sole source of truth for 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/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 attached is this route** even when no verb is
- given at all. What it is for, who is in it and what it says are the author's; the working
- directory, the project location, the packages and the generators are yours to decide rather than to
- ask for.
-- Every original-authoring request → read `references/brief-intake.md` and inspect complete projects
- under the checkout's `examples/` directory when it exists. Analyze a semantically matching
- project's author intent; otherwise use the document's general, open-ended fallback. Do not
- hard-code video types or skip the brief-sufficiency gate.
-- A completed project followed by a natural-language change → read `references/revision/route.md`
- and use the independent `revision_state` route. The completed project may come from reconstruction,
- original authoring, a completed variant or an earlier revision, or the author may supply an existing completed project
- directory directly; it does not need to have been created in the current session. Restore the
- element's role in the frozen intent, edit only Source/Recipe/Run, invalidate the affected graph
- closure, and rerun deterministic gates. Revision never invokes VLM/observer visual inspection;
- after the change, start Studio only when the current Run has no Studio session so the author can
- see the updated result. This routing rule also applies after a paid Build has produced the full
- video: revise the accepted-material Run, never the rendered artifact and never by resuming either
- creation route.
-- A request for many independent versions after reconstruction, original authoring or revision, or
- from a validated existing project → read `references/variant-expansion/route.md`. The main agent
- uses the validated base project's complete SVML/SVS/SVRun, freezes format/Slate/component decisions,
- enumerates vocabulary, discloses the fast/medium/new-package workload, and resolves package gaps
- before copying or dispatching variant agents. Do not inspect repository `examples/` on this route;
- examples are only for an initial original-authoring request. Initial presenter/product/brand
- adaptation attached to a reconstruction remains inside the reconstruction route; it is not Revision.
- Variant expansion defaults to mechanically checked Source and performs no visual review or paid Build
- unless the author explicitly requests outputs.
-- If original authoring or reconstruction created a project-local package, wait until that route is
- complete, read `references/package-promotion.md`, and judge whether the component has clear, high
- reuse value across unrelated videos. Only when that bar is met, ask the author whether they want the
- Agent to move it into the Hypit repository's `packages/` folder and prepare a Pull Request for
- Hypit. Do not interrupt the production route for this question, move or submit anything without
- the author's answer, and do not suggest promotion for an ordinary component or one that only
- contains this video's content.
-- 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/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 → 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`.
-- Recovering after interruption or context compaction → read `references/recovery.md` before any
- other route step.
-- Preview-only media realization, temporary preview Runs, mock Artifact caching, or estimated
- SemanticTake timing → read `references/preview-mock.md`.
-- Paid-build handoff, pre-payment mock confirmation, post-build Studio display, or Studio behavior
- after a revision → read `references/studio-confirmation.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` and follow its
- 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
-maintenance instructions apply only to contributors who deliberately cloned the repository.
+```bash
+hypit-reference-video-tools list_svml_packages
+hypit-reference-video-tools inspect_svml_vocabulary --package <package>
+hypit-reference-video-tools inspect_visual_schema
+hypit-reference-video-tools validate_local_author_packages --run <build.svrun>
+hypit-reference-video-tools validate_script_cues --run <build.svrun>
+hypit check <build.svrun>
+hypit-reference-video-tools preview_check <build.svrun>
+hypit-reference-video-tools layout_check --run <build.svrun>
+```
-Studio URL handoff is mandatory: whenever a Studio process is started, capture the URL printed by
-the server and include the exact URL in the user-facing response. A statement that Studio started
-without the URL is incomplete; if the startup parameters change, stop the old process first and
-report the new URL after the replacement is listening.
+Use the reports that answer the current question. A report does not unlock another command. Layout
+measurements are advisory; repair a genuine issue or record an intentional structural finding with
+`layout_accept` and a reason.
+
+When a Run contains accepted `build-record` pins, pass its Runtime Profile to commands that must read
+those Results.
+
+## Task routing
+
+- Reference video, link, reconstruction or reverse engineering: read
- `references/reconstruction/route.md` and `references/reconstruction/observers.md`.
++ `references/reconstruction/route.md` and `references/reconstruction/observers.md`. Do not inspect
++ Distribution examples on this route; the reference itself is authoritative.
+- Description, topic, script or format with no reference video: read
+ `references/original-authoring/route.md` and `references/brief-intake.md`.
+- A natural-language change to an existing completed project: read `references/revision/route.md`.
+ Edit Source/Recipe/Run, never rendered media.
+- Many independent versions: create ordinary independent project directories from the accepted source
+ project and keep an explicit human-readable task list. Do not construct a second project history or
+ variant state machine. Paid Builds remain individually approved.
+- Package discovery or a possible capability gap: read `references/vocabulary.md`.
+- A new author component: read `references/local-author-package.md`.
+- Preview or visual inspection: read `references/preview.md`, `references/preview-mock.md`,
+ `references/element-review.md` and `references/layout-checks.md` as needed.
+- Runtime setup, Build, status, Result inspection and reuse: read `references/runtime.md`.
+- Studio handoff: read `references/studio-confirmation.md`.
+- Production craft: read `references/playbooks/index.md` and its required craft references.
+
+If a project-local component has clear reuse value across unrelated videos, finish the current video
+first, then read `references/package-promotion.md` and ask before moving it into the Hypit repository.
+
+Preserve unrelated changes. Keep credentials, generated media, Runtime state and logs out of commits.
+Whenever Studio is started, report the exact URL printed by the server.
diff --cc skills/hypit/references/brief-intake.md
index 257aae4a,2d314723..05a50ddd
--- a/skills/hypit/references/brief-intake.md
+++ b/skills/hypit/references/brief-intake.md
@@@ -6,7 -6,7 +6,7 @@@ semantics, timing, facts and paid gener
## Discover examples, never classify by filename
--From the Hypit checkout root, inspect `examples/` when it exists. Enumerate complete projects and
++From the selected Distribution root, inspect `examples/` when it exists. Enumerate complete projects and
read each candidate's `main.svml`, `recipes.svs`, `build.svrun`, and relevant package README. A
read-only `hypit check` is allowed. Do not copy its Source, facts, people, assets, prompts or source
closure into the new project. Directory names, file names and component counts are only search clues.
diff --cc skills/hypit/references/environment.md
index 20576b92,90cd971d..a5ddd88b
--- a/skills/hypit/references/environment.md
+++ b/skills/hypit/references/environment.md
@@@ -4,16 -4,23 +4,26 @@@
Hypit has three different lifetimes. Never collapse them into one directory.
--- The **skill** is agent guidance. Install it globally once so later sessions and unrelated projects
-- can discover the same copy.
--- The **Distribution** is either an already installed machine-wide Hypit package or the Hypit
-- contributor checkout the task is deliberately running from. It owns the CLI, Studio, official
-- packages and packaged Python service source.
++- The **skill** is agent guidance. A Skill hub copies the real `skills/hypit/` subtree into an Agent's
++ global Skill directory so later sessions and unrelated projects can discover it.
++- The **Distribution** is either an already installed machine-wide Hypit package, the machine-level
++ `<home>/hypit` checkout prepared by the Skill while npm publication is unavailable, or a contributor
++ checkout deliberately selected for repository work. It owns the CLI, Studio, official packages and
++ packaged Python service source.
- The **project** is the author's directory. It owns Sources, assets, project-local packages,
`hypit.runtime.json`, `.hypit/` Build state and output files.
- An ordinary user does not clone the repository and does not run pnpm, Corepack, `npm link`, or a
- service's `uv sync` by hand. A clone is only a contributor checkout.
+ Each project is an independent boundary. After selecting the active project, do not inspect another
+ author project or use anything from its `packages/` directory. Never copy, import or symlink a
+ project-local package across project boundaries. Resolve capabilities from the installed Distribution
+ or create the package inside the active project's own `packages/` directory through the local-package
+ workflow. Repository examples are read-only references only on routes that explicitly allow them;
+ they are never package dependencies.
+
-An ordinary user does not clone the repository and does not run pnpm, Corepack, `npm link`, or a
-service's `uv sync` by hand. A clone is only a contributor checkout.
++Installing a Skill does not install the Distribution. OpenAgents and other Skill hubs own the installed
++Skill copy; Hypit owns no second Skill registry and never rewrites that copy. Until the npm package is
++published, the Agent prepares the Distribution checkout and its pinned dependencies once at machine
++scope. The author does not clone it per project, run `npm link`, or run a service's `uv sync` by hand.
## Environment completion gate
@@@ -59,23 -66,23 +69,25 @@@ speakers, align who speaks when, and ex
speaker replication and voice-design decisions. Do not use the credentialless agent observer as a way
to bypass credential setup.
--## Select a Distribution; do not assume registry publication
++## Select or prepare the Distribution
--The skill must be global; the skills CLI's default is project-local:
++The Skill must be global. OpenAgents installs it from the repository's real `skills/hypit/` directory;
++with the generic Skills CLI the equivalent command is:
```text
npx skills add hypit-ai/hypit --global
```
--First check for an already installed program:
++First try an already installed program:
```text
hypit paths --json
```
If that command is missing, do **not** run `npm install --global hypit`: the npm package is not
--currently published. Check whether the current directory or one of its ancestors is a Hypit
--contributor checkout. A checkout has all of these:
++currently published. When the current task is repository development inside a Hypit contributor
++checkout, use that checkout. For ordinary video production use `<home>/hypit` as the machine-level
++Distribution. A valid checkout has all of these:
```text
package.json (name: "hypit")
@@@ -83,32 -90,32 +95,48 @@@ bin/hypit.mj
packages/reference-video-tools/bin/reference-video-tools.mjs
```
--In that checkout, prepare dependencies only when they are absent or stale, using the contributor
--workflow and the pinned lockfile:
++If `<home>/hypit` does not exist, clone the public repository there. If the path exists but is not the
++Hypit checkout, do not overwrite or rename it; report the collision. Never create the checkout inside
++the author project.
++
++```text
++git clone --branch main --single-branch https://github.com/hypit-ai/hypit.git <home>/hypit
++```
++
++At the first production turn in each conversation, fast-forward the selected checkout. Do not reset,
++stash, discard or overwrite local changes. If the pull cannot fast-forward, report the exact checkout
++and stop before production:
++
++```text
++git -C <distribution-root> pull --ff-only origin main
++```
++
++After the first clone or a successful pull, prepare the pinned dependencies from the Distribution
++without changing the author project's working directory:
```text
corepack enable
--corepack pnpm install --frozen-lockfile
++corepack pnpm --dir <distribution-root> install --frozen-lockfile
```
--Then use the checkout entrypoints directly for the rest of the route:
++Then use the Distribution entrypoints directly for the rest of the route:
```text
--node <checkout>/bin/hypit.mjs paths --json
--node <checkout>/packages/reference-video-tools/bin/reference-video-tools.mjs <subcommand> ...
--node <checkout>/bin/hypit-studio.mjs --run <run> [--runtime <hypit.runtime.json>]
--node <checkout>/bin/hypit-preview-check.mjs <run> [<hypit.runtime.json>]
++node <distribution-root>/bin/hypit.mjs paths --json
++node <distribution-root>/packages/reference-video-tools/bin/reference-video-tools.mjs <subcommand> ...
++node <distribution-root>/bin/hypit-studio.mjs --run <run> [--runtime <hypit.runtime.json>]
++node <distribution-root>/bin/hypit-preview-check.mjs <run> [<hypit.runtime.json>]
```
In every reference that abbreviates these as `hypit`, `hypit-reference-video-tools`,
`hypit-studio` or `hypit-preview-check`, interpret them as the selected launchers above:
--| Abbreviation | Contributor checkout launcher |
++| Abbreviation | Checkout Distribution launcher |
|---|---|
--| `hypit` | `node <checkout>/bin/hypit.mjs` |
--| `hypit-reference-video-tools` | `node <checkout>/packages/reference-video-tools/bin/reference-video-tools.mjs` |
--| `hypit-studio` | `node <checkout>/bin/hypit-studio.mjs` |
--| `hypit-preview-check` | `node <checkout>/bin/hypit-preview-check.mjs` |
++| `hypit` | `node <distribution-root>/bin/hypit.mjs` |
++| `hypit-reference-video-tools` | `node <distribution-root>/packages/reference-video-tools/bin/reference-video-tools.mjs` |
++| `hypit-studio` | `node <distribution-root>/bin/hypit-studio.mjs` |
++| `hypit-preview-check` | `node <distribution-root>/bin/hypit-preview-check.mjs` |
Do not interpret `hypit-studio` as a `studio` subcommand of `hypit`: Studio is a separate entrypoint.
Do not globally link the checkout, use `npx hypit`, or install dependencies into an author project.
@@@ -116,13 -123,13 +144,13 @@@ Run reference-video-tool commands that
though their launcher lives in the checkout.
When a reference names `<skill-root>`, substitute the installed Hypit skill directory (the directory
--containing `SKILL.md` and `scripts/`); it is not relative to the author's project or checkout.
--
--When a reference names `<skill-root>`, substitute the installed Hypit skill directory (the directory
--containing `SKILL.md` and `scripts/`); it is not relative to the author's project or checkout.
++containing `<skill-root>/SKILL.md` and `<skill-root>/scripts/`); it is not relative to the author's
++project or checkout.
--If neither an installed CLI nor a contributor checkout is available, report that no runnable Hypit
--Distribution is present and stop. A registry install is not a recovery path.
++The installed Skill and the selected Distribution have separate update lifecycles. Pulling the
++Distribution does not update an OpenAgents-installed Skill; existing OpenAgents users reinstall the
++Skill when they want a newer workflow. Conversely, reinstalling the Skill does not replace a dirty or
++diverged Distribution checkout.
`hypit paths --json` reports the current project boundary, project state, machine Program Home,
machine npm package home and selected Distribution. Those paths are facts; no repository locator or
@@@ -189,22 -196,22 +217,14 @@@ changes an exact adapter dependency, th
## Contributor checkout
--Only someone changing Hypit itself clones the repository. A task already running from that checkout
--may also use it as the Distribution when no installed CLI exists, as described above. Follow
--`docs/guide/develop.md` and use its pinned pnpm version and official `pnpm-lock.yaml`. Video-production
--projects in this checkout live under `<checkout-root>/projects/<project-name>/`; they remain independent
--author projects and are not part of the repository workspace globs.
--
--When this checkout is the selected Distribution and the Hypit Skill is loaded for the first time in a
--new conversation, synchronize the complete repository before using it:
--
--```text
--git pull --ff-only origin main
--```
++A task changing Hypit itself uses its current contributor checkout rather than `<home>/hypit`. Follow
++`docs/guide/develop.md` and use the pinned pnpm version and `pnpm-lock.yaml`. A contributor checkout may
++also act as the Distribution for a video-production task, but the author project is still independent:
++it may live anywhere and must never be added to the Hypit workspace or linked into the checkout.
--This updates the CLI, packages, services, examples, docs and Skill source together. Never reset or
--overwrite local changes; a pull that cannot fast-forward is a sync conflict and blocks the route until
--it is resolved. Updating only the installed Skill does not make the contributor checkout current.
++The same fast-forward rule applies when a contributor checkout is selected. Updating its repository
++refreshes its CLI, packages, services, examples, docs and canonical Skill source, but does not rewrite a
++separately installed OpenAgents Skill copy.
A project directory carries its own `package.json` with the runtime-safe minimum
`{ "name": "<project-name>", "version": "0.0.0", "private": true, "type": "module" }`.
diff --cc skills/hypit/references/host-setup.md
index 3c4d5dbb,b962ab86..ddda9fb5
--- a/skills/hypit/references/host-setup.md
+++ b/skills/hypit/references/host-setup.md
@@@ -8,9 -8,9 +8,13 @@@ WhisperX service, machine npm packages
Run this skill-owned probe when diagnosing a machine:
```text
- node .agents/skills/hypit/scripts/check-environment.mjs
-node skills/hypit/scripts/check-environment.mjs
++node <skill-root>/scripts/check-environment.mjs
```
++This checks shared host prerequisites only. Check the selected Distribution independently with
++`hypit paths --json` or the checkout launcher defined in `environment.md`; a checkout does not need a
++global `hypit` executable on `PATH`.
++
## Install FFmpeg prerequisites on Windows
Install a current FFmpeg build so both `ffmpeg.exe` and `ffprobe.exe` are available on `PATH`.
@@@ -182,15 -182,13 +186,15 @@@ Updates to an installed, published Dist
```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 Distribution registry request to
- every route. The Hypit Skill itself is different: its `SKILL.md` requires one
- `npx --yes skills update hypit --global --yes` refresh the first time the Skill is loaded in each new
- conversation.
-every route. The Hypit Skill is synchronized from the contributor checkout, when one is selected,
-by the session-initialization `git pull --ff-only origin main` step.
++Use `hypit --version` to report an installed package Distribution. These commands apply only after the
++package is published; do not add a registry request to every route. A checkout Distribution is updated
++only with the fast-forward repository flow in `environment.md` and never through npm.
++
++The installed Skill has a separate lifecycle. OpenAgents or another Skill installer updates its copy;
++pulling a Distribution checkout does not rewrite it, and reinstalling the Skill does not modify the
++checkout.
--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 --cc skills/hypit/references/preview.md
index ce99b1ee,cb59f42d..2e48b2d4
--- a/skills/hypit/references/preview.md
+++ b/skills/hypit/references/preview.md
@@@ -17,34 -81,99 +17,34 @@@ errors identify source or graph wiring
```bash
hypit-reference-video-tools render_element /path/to/project/build.svrun \
- --element <id> --segment <id>|--selection <id> --out <path>.mp4
+ --element <id> --segment <id>|--selection <id>|--tokens <from:to> \
+ --out <path>.mp4
```
-It compiles the Author/Run Graph once, delegates preview substitutions to `@hypit/preview-mock`,
-materializes ordinary mock Artifacts through `@hypit/mock-media` into the temporary preview Store, and
-drives the package's deterministic Producers from the generated `preview.svrun`. No mock file or
-SemanticTake is hand-authored in the project.
-
-`--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The
-command appends the output suffix itself when it looks for the track, so `--element captions.track`
-matches nothing: it refuses with `the Source places no element named captions.track` and lists the
-bare ids that are placed.
+The command realizes the Run with local preview media, renders once, and cuts the requested window.
+It never writes mock Candidates into Author Source and never reaches a paid Provider. A batch file can
+request several windows from the same realization.
-`--segment` and `--selection` take a Script name, never a timestamp. `--tokens from:to` takes a
-half-open range of the Script's own words, which is what a stretch nobody named is written as — a
-caption Cue ends at a speaker change, so it has a range and no id. Without any of the three, the whole
-program is drawn. An `--out` ending `.mp4`, `.mov` or `.webm` writes the stretch as a clip; any other
-extension writes one still from the middle of it.
+`--element` is the bare Source element id. The window is named in Script terms, never by copying a
+reference timestamp. The returned sidecar records estimate timing.
-A whole round is one call: `--batch <renders.json>`, an array of `{element, segment|selection|tokens,
-out}` inheriting the Run, and the `renders` array `reconstruction_check` returns is exactly that.
-The program is realized once into a shared preview frame cache for the whole round, then the entries
-are processed serially and cut from those frames. Asking for eight windows therefore costs one full
-draw and eight cuts without concurrent workers racing over the shared `preview.svrun`. The picture
-does not depend on `--element` — it is
-everything the Source places over those words — so two elements over one stretch share the render as
-well.
+Use `layout_check` when actual browser geometry matters. Its overflow, overlap and offset candidates
+are advisory measurements. Fix confirmed problems or annotate intentional geometry with
+`layout_accept`; do not treat the report as an approval condition.
-Each Segment's length comes from the Source's own `estimate:Speech`; `--reference-id` selects reference
-evidence and comparison windows only. The sidecar records `"timing_basis": "estimate"`.
+## Open the complete preview
-Before reading the picture, run and settle `layout_check` and keep `.hypit/layout-check.json` with the
-render. **Read now:** `layout-checks.md`. Its realized stable-state measurements are candidates for the
-Agent to interpret, not automatic failures or instructions to edit. `layout_check` creates and records
-the preview-mock Run and live Composition without encoding media; this later render reuses that same
-upstream. The observer still confirms the look and the Agent decides whether any crop, offset or overlap
-is intentional.
-
-## Open the whole Run for a person
-
-After the route's final check, read `studio-confirmation.md`: before a paid Build, start Hypit Studio
-for the complete preview-mock Run and obtain the author's acceptance. After a revision, if Studio for
-that Run is not already running, start it and give the author the URL; an existing Studio session
-hot-reloads the changed Source. Stop the previous server before changing Studio startup parameters
-(for example, selecting a different `--run`, `--workspace` or port) to avoid port conflicts; do not
-restart merely because the same Run's SVML/SVS changed.
+The preview realizer returns the exact `previewRun` path. Open that path rather than reconstructing a
+directory name:
```bash
-cd /path/to/project
-# Start Studio with the persisted previewRun returned by realizePreviewMock.
-hypit-studio --run .hypit/preview/<digest>/preview.svrun --runtime hypit.runtime.json &
+hypit-studio --run <previewRun> --runtime hypit.runtime.json
```
-`hypit-studio` is the standalone Studio launcher (`node <checkout>/bin/hypit-studio.mjs` in a
-contributor checkout), not a `studio` subcommand of `hypit`.
-
-If another Studio process is already using a different Run or startup parameters, stop that process
-before launching this command; otherwise reuse the existing process and let its Source watcher reload.
-
-Read the startup output for the chosen port and return the exact Studio URL to the author. `--run` is
-required: Studio's unit of work is the Run
-Source, and it reads the Author SVML back out of it. Pass `--runtime` only when the Author Source
-reuses accepted Build records. `--workspace` selects the Source Workspace and defaults to the Run's
-own directory, so pass it when the Run's relative Sources resolve against a different root.
-
-Studio opens a Run whose material is satisfied. When a projection is missing it names the issue and
-stops, so a Run that opens is a Run whose Tracks all resolved.
-
-Contributor fixtures may provide a satisfied demonstration Run, but an ordinary installed
-Distribution does not use its package directory as an author workspace.
-
-## A timeline block retains its authored Selection
-
-Studio keeps three stages of an item's time apart, and reading one for another misreads the program:
-
-- the **semantic source** the author named — a Selection, Segment, Moment or Program, with its
- identity and anchors on the Semantic Track;
-- the **projection** of that source into frame space, after offset evaluation, clipping and frame
- quantization. One resolved authored binding projects to one window;
-- the **consumption** window the realized Track actually uses, which the projection does not have to
- equal — a source-audio trim reads different samples than its target window, and a Ranking exposes
- one outer window alongside its reveal phases.
-
-A projection line connects a source to its realized window, and the projection view is read-only.
-`../../../docs/guide/studio-temporal-windows.md` is authoritative for what each stage carries.
-
-When the executed lineage names a Selection or Moment, dragging the realized block may issue
-`timeline.adjust` against that shared semantic identity. Script owns the inverse from semantic Anchor
-identity back to markers, so every consumer follows the edit. This does not turn the block into a
-Selection or infer a source from matching frames. Derived schedule phases and missing lineage remain
-read-only.
+Use the standalone Studio launcher. Reuse an existing process for the same Run and startup parameters;
+stop it before changing those parameters. Report the exact URL printed after Studio starts.
-Studio is a browser preview **for a person to look at**. It is not a source of images for an
-automated comparison — that is what the local still render above is for.
+Studio is for a person to inspect. Automated comparison uses `render_element` plus
+`compare_reconstruction` or `review_element`.
- `../../../../docs/quickstart/preview.md` is authoritative for Studio behavior.
-`../../../docs/quickstart/preview.md` is authoritative.
++`<distribution-root>/docs/quickstart/preview.md` is authoritative for Studio behavior.
diff --cc skills/hypit/references/quickstart.md
index 00000000,e38c81e0..93289eb2
mode 000000,100644..100644
--- a/skills/hypit/references/quickstart.md
+++ b/skills/hypit/references/quickstart.md
@@@ -1,0 -1,44 +1,28 @@@
+ # Quickstart map
+
-Published docs and installed package declarations are authoritative:
++The selected Distribution's published docs and installed package declarations are authoritative.
++`<distribution-root>` is the root reported by the selected launcher; it is not the installed Skill
++directory and it is not the author project:
+
+ | Need | Read |
+ |---|---|
-| Script semantics | `../../../docs/quickstart/script.md` |
-| SVS Recipes | `../../../docs/quickstart/styles.md` |
-| Media and Seedance | `../../../docs/quickstart/generation.md` |
-| Reusable Seedance Prompt Kits | the installed `@hypit/seedance-kits` README and selected Kit |
-| Normalization, alignment and SemanticTrack assembly | `../../../docs/quickstart/timing.md` |
-| Caption, Media, Text, Audio Tracks | `../../../docs/quickstart/tracks.md` and installed package READMEs |
-| Film and rendering | `../../../docs/quickstart/composition.md` |
-| Run Source, durable Runtime, Builds, retrieval, and reuse | `../../../docs/quickstart/run.md` and `runtime.md` |
++| Script semantics | `<distribution-root>/docs/quickstart/script.md` |
++| SVS Recipes | `<distribution-root>/docs/quickstart/styles.md` |
++| Media and generation | `<distribution-root>/docs/quickstart/generation.md` |
++| Timing and SemanticTrack assembly | `<distribution-root>/docs/quickstart/timing.md` |
++| Caption, Media, Text and Audio Tracks | `<distribution-root>/docs/quickstart/tracks.md` and package READMEs |
++| Film and rendering | `<distribution-root>/docs/quickstart/composition.md` |
++| Run, Runtime, Build, Result and reuse | `<distribution-root>/docs/quickstart/run.md` and `runtime.md` |
+
-Canonical production path:
++Canonical path:
+
-`Script → estimate:Speech/text → Seedance or supplied media → pipeline:Normalize → whisperx:SemanticTake → speech:Track → peer Caption/Media/Typography/Audio Tracks → Film → render:Video`.
++`Script → estimate:Speech/text → generated or supplied media → normalization → SemanticTake → speech:Track → peer visual/audio Tracks → Film → render:Video`.
+
-Preview path uses the same Graph with `@hypit/preview-mock`: image/video/audio outputs are replaced
-by ordinary mock Artifacts, and WhisperX `SemanticTake` is replaced by `semantic-take-estimate` using
-`estimate:Speech`. This preview substitution never enters Author Source and is not final timing evidence.
++Preview uses the same Graph with local mock media and estimate timing. It never edits Author Source and
++never submits paid generation.
+
-Use explicit imports, exact fonts, Canvas/Frames, the SemanticTrack, Targets, and Runtime
-authority. There is no implicit cache; reuse is explicit with `build-record` + `satisfy`.
++Use explicit imports, exact fonts, Canvas/Frames, SemanticTrack, Targets and Runtime authority. Reuse
++is explicit through a named Result output referenced by `build-record` and `satisfy`.
+
-`speech:Take source={...}` assembles one aligned `whisperx:SemanticTake` into the Track, in program
-order. The take that speaks a Segment is the take that draws it, so that one value carries the
-program time, the speech and the picture together; peer Media Tracks put inserts over it.
-
-For a program with no spoken words, keep the `whisperx:SemanticTake` and `speech:Track` declarations —
-the SemanticTrack is the frame domain every `start`/`end` window resolves into — satisfy
-`<track>.semantic` through `.svrun` `build-record` and `satisfy`, keep `<track>.visual` and
-`<track>.audio` out of the Film so the alignment goes unreached, and omit the Caption components.
-
-For execution, preserve the full lifecycle: select the Profile, inspect the frozen plan, run
-`runtime up` when preflight is not ready, submit a fresh automatically identified Build, inspect its
-accepted Records, retrieve Artifacts, and declare any reuse explicitly in a new Run Source.
-
-Both production routes expose current progress in `.hypit/route-state.json` and preserve each
-execution under `.hypit/routes/<route-id>/`; after an interruption, follow
-`recovery.md` and reconcile before resuming. Before `preview_check`, run
-`inspect_svml_vocabulary --run`, `validate_local_author_packages --run` and
-`validate_script_cues --run`; the preview and final checks repeat these gates.
++Inspect the files and current Result directly after interruption. There is no route cursor to recover.
++Do not submit a second paid Build when the needed Result already exists.
diff --cc skills/hypit/references/reconstruction/route.md
index ebaf61f7,c0712ad2..d0c1f937
--- a/skills/hypit/references/reconstruction/route.md
+++ b/skills/hypit/references/reconstruction/route.md
@@@ -1,15 -1,244 +1,20 @@@
-# Reference-video reconstruction route
+# Reference-video reconstruction
-Read a step, do it, read the next one. Each step names the files it needs; read those at that step.
+Use this workflow whenever a video file or link is the thing to reproduce, including an initial
+presenter/product/brand adaptation requested together with the reference.
-**Evidence-first rule:** This route never reads the repository's `examples/` projects. Do not open their
-SVML, SVS, SVRun, README, assets or variants at any stage. The sole exception is the generic
-`examples/minimal-author-package/` fixture, and only after a real vocabulary gap is proven and the local
-package workflow requires its contract. The reference video and its persisted evidence are the source of
-truth; after observation, consult only installed package vocabulary and craft guidance for the observed
-systems. Examples belong to original authoring and variant planning, not reconstruction.
++The reference is the sole design evidence for this route. Do not inspect Distribution example
++projects, borrow another author project's files or packages, or wire the supplied reference itself
++into a Film, Track, Take or final output. Every visible shot must be newly authored or explicitly
++supplied by the author as replacement material.
+
-## What this route delivers
+## 1. Prepare and observe the reference
- Read `../environment.md`, `credentials.md` and `observers.md`. Ask once whether Gemini or the calling
-The complete environment is the hard gate. At route entry, read `../environment.md` completely, then
-finish its checklist through the environment steps: Distribution, project boundary, credentials,
-Runtime Profile, all selected managed programs, and health checks. The local WhisperX Endpoint is
-mandatory and must report `Ready whisperx` (or an equivalent successful probe). Do not enter the
-observation or authoring steps while any environment item is missing, installing, unhealthy, or
-unconfirmed.
-
-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. The route then pauses at the Studio confirmation handoff
-before any paid Build; after explicit acceptance it may proceed with the Runtime Build lifecycle.
-Once the paid Build has produced the accepted full video, any new natural-language change starts
-`../revision/route.md` from that completed Run; never continue this creation route or edit the rendered file.
-
-If the project is already complete and the author asks for a natural-language change, stop following
-this creation route and read `../revision/route.md`. Revision edits Source/Recipe/Run and reruns deterministic
-gates; it does not invoke a VLM or visual observer.
-
-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="9:16" 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.
-
-The reference video itself is never supplied project media. It is observation/comparison evidence only.
-Never copy it into project assets or wire its path into `media:Video`, `asset:Video`, a Media Track,
-the Film, or a Run Target. Every visible shot must be newly authored as a generated take or an
-explicitly author-supplied replacement asset. A project that directly plays the reference is invalid
-and must be rejected before preview or Build.
-
-Reference observation is part of the work and is expected to cost what it costs.
-
-## The video is the whole request
-
-The author gives one thing: a video, as a path to a file or as a link to one. A link — TikTok,
-YouTube, Instagram, Bilibili — is fetched by `prepare_reference` before anything else runs, with the
-`yt-dlp` pinned under `services/yt-dlp` and run through `uv`, and every step after that reads the downloaded file without knowing it was ever a link. The
-download is cached by the link, so a route restarted after an interruption reaches the same bytes and
-therefore the same reference rather than paying for its observations twice. 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 23. 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.
-
-If that same initial request also asks for many variants, step 23 still applies the requested
-presenter/product/brand adaptation inside reconstruction. After step 24 passes, hand the adapted base
-to `../variant-expansion/route.md`. Do not route the initial adaptation through Revision.
-
-## Checkpoint and recovery
-
-Start the project snapshot before the first route decision:
-
-```bash
-hypit-reference-video-tools route_state --action start --project-root <project> \
- --route reconstruction
-```
-
-The route tools update machine-owned stages after successful checks, renders, and comparisons. After
-reference/observer decisions, Source edits, repairs, or Build actions, write an explicit checkpoint.
-After any interruption or context compaction, read `../recovery.md`, run `route_state --action
-reconcile --project-root <project>`, and resume only from its `next_action`. The snapshot is evidence
-of intent; files and check results remain the authority.
-
-### Durable stage map
-
-| state | update / completion predicate | recovery entry |
-| --- | --- | --- |
-| `environment` | explicit checkpoint after Distribution, project, credentials, Runtime Profile, selected programs and all health checks are ready | `hypit paths --json` / `hypit runtime up` |
-| `reference-prepared` | checkpoint after `prepare_reference` reports ready `state.json` | `prepare_reference` or `route_state reconcile` |
-| `reference-observed` | explicit observer checkpoint; all required observation answers are complete | `observe_reference` / `record_observation` |
-| `vocabulary-checked` | Run-scoped vocabulary inspection and the frozen `.hypit/component-fit.json` are both persisted | `inspect_svml_vocabulary --run <run>` |
-| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` |
-| `package-ready` | every project-owned package under `packages/` has a real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <run>` |
-| `script-checked` | every caption Cue has at most four visible words | `validate_script_cues --run <run>` |
-| `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` |
-| `layout-checked` | `layout_check` executed and every candidate was repaired or explicitly accepted | `layout_check --run <run>` / `layout_accept` |
-| `review-planned` | `reconstruction_check` writes a plan | `reconstruction_check <run>` |
-| `preview-rendered` | render output and timing sidecar both exist | `render_element --batch <round.json>` |
-| `comparison-complete` | comparison log contains a complete record for the planned element | `compare_reconstruction` / `record_observation` |
-| `repairs-complete` | explicit checkpoint after applying comparison findings | edit Source, then rerun the checks |
-| `final-checked` | final `reconstruction_check` returns `passed: true` after all gates | `reconstruction_check <run>` |
-| `build-complete` | explicit checkpoint after the durable Build record is accepted | `hypit build` (confirm cost first) |
-
-The numeric `current_step` is only a cursor; `reconcile` starts at the first unmet predicate. It never
-infers the observer's creative judgement or a repair from file presence alone.
-
----
-
-## 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
-
-When working in this checkout, create the independent project at
-`<checkout-root>/projects/<video-name>-reverse/` (use a safe slug). Use a directory the author named
-only if they explicitly named one. Give it a `package.json`
-with the runtime-safe minimum `{ "name": "<project-name>", "version": "0.0.0", "private": true, "type": "module" }`.
-`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 the project's `packages/<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
-
-Check `<checkout-root>/.env` first, then `<project-root>/.env` if present, and load each before
-credential probing (the project file overrides duplicate names):
-
-```bash
-set -a
-[ ! -f <checkout-root>/.env ] || . <checkout-root>/.env
-[ ! -f <project-root>/.env ] || . <project-root>/.env
-set +a
-```
-
-If the loaded variables satisfy the selected observer/Provider, continue without asking the author
-for them again. HypiHub OAuth is the default; only configure an author-owned key when explicitly requested.
-
-**Read now:** `../credentials.md` — which variables each Provider needs. A variable a Provider needs
-and this machine does not hold is named. If HypiHub OAuth is not configured, complete that login before
-continuing; do not use `agent` to bypass the environment gate.
-
-Create the project's `hypit.runtime.json` now with at least the local media and WhisperX endpoints,
-then select and start it before reference preparation:
-
-```bash
-hypit runtime use hypit.runtime.json
-hypit runtime up
-```
-
-Step 15 completes the same Profile with every capability reached by the authored Source; it does not
-create the first Profile after transcription has already needed one. Checkpoint `environment` only
-after this preliminary Profile and the selected credentials are ready.
-
-### 4. Read the observer guidance
-
-**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. Use the default Gemini observer
-
-`observers.md`'s "Choosing" section holds the credential checks and disclosure. Environment setup has
-already completed the credential flow. Use `gemini` by default; use `agent` only after an explicit user
-request.
-
-### 6. Say which observer is reading
-
-One line, before any evidence starts.
-
----
-
-## Phase 1 — Evidence, with reading alongside
-
-### 7. List installed vocabulary
-
-```bash
-hypit-reference-video-tools list_svml_packages
-```
-
-It resolves project-owned packages from the working directory (or the directory named by
-`--package-root`) and resolves installed `@hypit/*` packages from the active Hypit Distribution
-fallback. `--package-root` never replaces that Distribution root, so no `npm link` or package self-link
-is needed. This is instant and may run before or during the sweep.
-
-### 8. Prepare the reference
-
-```bash
-hypit-reference-video-tools prepare_reference --video-path <path or link> --observer gemini|agent
-```
-
-`--video-path` takes a link as readily as a path. The result names the link it fetched under
-`source_url`, which is the only record of which video was reconstructed once the bytes are on disk.
-
-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.
-
-### 9. Run the full sweep, in the background
++Read `../environment.md`, `../credentials.md` and `observers.md`. Ask once whether Gemini or the calling
+agent should read the reference, then run:
```bash
+hypit-reference-video-tools prepare_reference --video-path <path-or-link> --observer <gemini|agent>
hypit-reference-video-tools observe_reference --reference-id <reference-id>
```
diff --cc skills/hypit/references/runtime.md
index d1f99bee,4907e93d..69b3e317
--- a/skills/hypit/references/runtime.md
+++ b/skills/hypit/references/runtime.md
@@@ -1,6 -1,6 +1,6 @@@
# Durable Runtime and Build lifecycle
- Read `../../../../docs/quickstart/run.md` as the authority for Run Source, Target, Candidate, Runtime Profile,
-Read `../../../docs/quickstart/run.md` as the authority for Run Source, Target, Candidate, Runtime Profile,
++Read `<distribution-root>/docs/quickstart/run.md` as the authority for Run Source, Target, Candidate, Runtime Profile,
Build, retrieval, and reuse syntax. Use this file as the operational checklist.
## Author the Runtime Profile
diff --cc skills/hypit/scripts/check-environment.mjs
index 94c38200,94c38200..3a5222c7
--- a/skills/hypit/scripts/check-environment.mjs
+++ b/skills/hypit/scripts/check-environment.mjs
@@@ -3,7 -3,7 +3,6 @@@ import { execFileSync } from "node:chil
import process from "node:process";
const commands = [
["node", ["--version"]],
-- ["hypit", ["paths", "--json"]],
["ffmpeg", ["-version"]],
["ffprobe", ["-version"]],
["uv", ["--version"]],
diff --cc test/hypit-skill-reachability.mjs
index 4865b929,6d59f785..00000000
deleted file mode 100644,100644
--- a/test/hypit-skill-reachability.mjs
+++ /dev/null
@@@ -1,329 -1,329 +1,0 @@@
--/**
-- * What a reader of the hypit skill can still reach, as a set of sentences.
-- *
-- * Editing the skill means moving prose between files: a passage two routes both need is written
-- * once and linked from both, and a passage filed under one route is moved to a shared file. Every
-- * one of those edits is supposed to be invisible to a reader — they follow a link instead of
-- * reading on, and arrive at the same words. Checking that the links resolve does not check that.
-- * A link resolves perfectly to a file that lost a clause on the way in.
-- *
-- * So the unit here is the sentence, not the file and not the link. Two runs of `--route` are
-- * comparable with `comm`, and a sentence that was reachable before and is not reachable now is a
-- * loss wherever it used to live. Which file a sentence sits in is deliberately not part of the
-- * key: a move is meant to score as a no-op.
-- *
-- * One detail decides whether any of this works. The skill's prose is hard-wrapped at about 100
-- * columns, so a sentence is routinely split across two lines and any line-based comparison sees
-- * two halves rather than one sentence. `grep -rn "never inspected is a system"` finds three files;
-- * there are four. That is the failure this tool exists to make impossible, and it is why
-- * normalization collapses a paragraph's newlines before it splits on sentence ends.
-- *
-- * node test/hypit-skill-reachability.mjs --route reconstruction
-- * node test/hypit-skill-reachability.mjs --at HEAD --route description
-- * node test/hypit-skill-reachability.mjs --links
-- * node test/hypit-skill-reachability.mjs --orphans
-- * node test/hypit-skill-reachability.mjs --restatements [--threshold 0.45]
-- */
--import { execFileSync } from "node:child_process";
--import { readFileSync, readdirSync } from "node:fs";
--import { dirname, join, posix, relative, resolve } from "node:path";
--import { fileURLToPath } from "node:url";
--
--const repositoryRoot = fileURLToPath(new URL("../", import.meta.url));
- const skillRoot = ".agents/skills/hypit";
-const skillRoot = "skills/hypit";
--
--/** A path in one of these is written from the repository root; anything else is relative to its file. */
--const rootRelativePrefixes = ["docs/", "examples/", "packages/", "services/", "test/"];
--
--/**
-- * Where each route starts reading, and where it stops.
-- *
-- * Both begin at `SKILL.md`, because that is what routes the task. But `SKILL.md` names both route
-- * files, so a traversal that followed every link from it would reach the whole skill twice and the
-- * two routes would come back identical — which is exactly the question this tool is asked. Each
-- * route therefore refuses to enter the other's directory, and that refusal is the property under
-- * test: a passage filed under `reconstruction/` is a passage the description route cannot read,
-- * which is the defect the moves in this change are for.
-- */
--const routes = {
-- reconstruction: {
-- roots: [`${skillRoot}/SKILL.md`, `${skillRoot}/references/reconstruction/route.md`],
-- closed: `${skillRoot}/references/original-authoring/`,
-- },
-- description: {
-- roots: [`${skillRoot}/SKILL.md`, `${skillRoot}/references/original-authoring/route.md`],
-- closed: `${skillRoot}/references/reconstruction/`,
-- },
--};
--
--/**
-- * Reads a file as of a commit, or from the working tree when `at` is undefined.
-- *
-- * Reading the baseline through `git show` rather than from a copy on disk is what keeps the
-- * baseline from drifting: there is no second tree to forget to refresh, and the comparison is
-- * always against a named commit rather than against whatever was captured at some earlier moment.
-- */
--function read(path, at) {
-- try {
-- if (at === undefined) return readFileSync(join(repositoryRoot, path), "utf8");
-- // A path that does not exist at that commit is an answer, not an error: `--links` asks exactly
-- // that question. `git show` says so on stderr, which would otherwise interleave with the report.
-- return execFileSync("git", ["show", `${at}:${path}`], { cwd: repositoryRoot, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
-- } catch {
-- return null;
-- }
--}
--
--/** Every `.md` under the skill, as repository-relative paths. */
--function everySkillFile(at) {
-- if (at === undefined) {
-- const found = [];
-- const visit = (directory) => {
-- for (const entry of readdirSync(join(repositoryRoot, directory), { withFileTypes: true })) {
-- const child = posix.join(directory, entry.name);
-- if (entry.isDirectory()) visit(child);
-- else if (entry.name.endsWith(".md")) found.push(child);
-- }
-- };
-- visit(skillRoot);
-- return found.sort();
-- }
-- const listed = execFileSync("git", ["ls-tree", "-r", "--name-only", at, "--", skillRoot], { cwd: repositoryRoot, encoding: "utf8", windowsHide: true });
-- return listed.split("\n").filter((line) => line.endsWith(".md")).sort();
--}
--
--/**
-- * Where a backticked path in `from` points.
-- *
-- * Two conventions are in use and telling them apart is not cosmetic. A path under `docs/`,
-- * `packages/`, `services/`, `examples/` or `test/` names a place in the repository; everything else
-- * names a file beside the one doing the linking. Resolving both the same way produces a dozen
-- * reports of which most are the scanner misreading the convention, and the two real breaks are
-- * lost among them.
-- */
--function resolveLink(from, target) {
-- if (rootRelativePrefixes.some((prefix) => target.startsWith(prefix))) return target;
-- return posix.normalize(posix.join(posix.dirname(from), target));
--}
--
--const linkPattern = /`([^`\n]+\.md)`/g;
--
--/** `packages/<name>/README.md` names the shape of a path, not a path. Angle brackets mark the difference. */
--const isTemplate = (target) => target.includes("<");
--
--function linksIn(text, from) {
-- const found = new Set();
-- for (const match of text.matchAll(linkPattern)) {
-- if (isTemplate(match[1])) continue;
-- found.add(resolveLink(from, match[1]));
-- }
-- return [...found];
--}
--
--/**
-- * The files one route can reach.
-- *
-- * `playbooks/` is added wholesale rather than followed link by link. `playbooks/index.md` routes to
-- * a format by name and a route reads whichever one fits, so which craft files a given run reaches
-- * depends on the video rather than on the route. Treating them all as reachable from both routes
-- * keeps that choice from showing up as a difference between two runs of this tool.
-- */
--function reachable(route, at) {
-- const { roots, closed } = routes[route];
-- const seen = new Set();
-- const queue = [...roots];
-- while (queue.length > 0) {
-- const path = queue.shift();
-- if (seen.has(path) || path.startsWith(closed)) continue;
-- const text = read(path, at);
-- if (text === null) continue;
-- seen.add(path);
-- for (const link of linksIn(text, path)) if (!seen.has(link)) queue.push(link);
-- }
-- for (const path of everySkillFile(at)) if (path.startsWith(`${skillRoot}/references/playbooks/`)) seen.add(path);
-- return [...seen].sort();
--}
--
--const fence = /^```/;
--
--/**
-- * A fenced block as one comparable unit.
-- *
-- * The content is kept whole rather than split into sentences — a command is not prose, and a flag
-- * that changed is a different command. Only whitespace is collapsed, so a block reflowed across
-- * different lines still matches: where the line breaks fall in a shell invocation is layout, and
-- * reporting that as a loss would bury the changes that are not.
-- */
--function flattenBlock(lines) {
-- return `code:${lines.join(" ").replace(/\s+/gu, " ").trim()}`;
--}
--
--/**
-- * A file's comparable units: its fenced blocks whole, and its prose as sentences.
-- *
-- * A fenced block is compared byte for byte because a command is not prose — a flag that changed is
-- * a different command, and splitting one into sentences would compare it on the wrong axis. The
-- * prose either side of it is unwrapped first, so a sentence the file broke across two lines is one
-- * unit again.
-- *
-- * Short units are dropped. Below about forty characters the population is headings, table cells and
-- * fragments like "One line is enough", which collide across files that have nothing to do with each
-- * other and would report a loss every time an unrelated heading was reworded.
-- */
--function unitsIn(text) {
-- const units = [];
-- const lines = text.split("\n");
-- const prose = [];
-- let block = null;
--
-- for (const line of lines) {
-- if (fence.test(line)) {
-- if (block === null) block = [];
-- else { units.push(flattenBlock(block)); block = null; }
-- continue;
-- }
-- if (block !== null) block.push(line);
-- else prose.push(line);
-- }
-- if (block !== null) units.push(flattenBlock(block));
--
-- for (const paragraph of prose.join("\n").split(/\n\s*\n/)) {
-- const flat = paragraph
-- // A list marker is layout, not content, and it has to come off every line rather than only the
-- // first: a bullet list is one paragraph, so after the unwrap the second bullet onward would keep
-- // its dash inline and stop matching the same sentence written as prose. Moving a rule out of a
-- // list and into a paragraph is exactly the edit this file exists to prove safe.
-- .replace(/^[\s>]*(?:[-*+]|#+)\s+/gmu, "")
-- .replace(/\s+/gu, " ") // the unwrap: a hard-wrapped sentence becomes one string
-- .replace(/[`*_]/gu, "")
-- .trim();
-- if (flat.length === 0) continue;
-- for (const sentence of flat.split(/(?<=[.!?])\s+/u)) {
-- const unit = sentence.trim().toLowerCase();
-- if (unit.length >= 40) units.push(unit);
-- }
-- }
-- return units;
--}
--
--function unitsForRoute(route, at) {
-- const lines = [];
-- for (const path of reachable(route, at)) {
-- const text = read(path, at);
-- if (text === null) continue;
-- // Tab-separated so `cut -f1` isolates the unit. A pipe would not: the prose uses it in tables.
-- for (const unit of unitsIn(text)) lines.push(`${unit}\t${path}`);
-- }
-- return lines;
--}
--
--/** Word trigrams, for asking whether two units say the same thing in different words. */
--function trigrams(unit) {
-- const words = unit.split(/\s+/u).filter((word) => word.length > 0);
-- const grams = new Set();
-- for (let index = 0; index + 2 < words.length; index += 1) grams.add(words.slice(index, index + 3).join(" "));
-- return grams;
--}
--
--function jaccard(left, right) {
-- let shared = 0;
-- for (const gram of left) if (right.has(gram)) shared += 1;
-- const union = left.size + right.size - shared;
-- return union === 0 ? 0 : shared / union;
--}
--
--/**
-- * Where the same thing is said in more than one place.
-- *
-- * Identical units are grouped rather than paired. One sentence repeated across nine format files is
-- * one thing to look at, not the thirty-six pairs the cross product produces — and at that volume the
-- * rewordings, which are the ones worth finding, are buried under the exact repeats.
-- *
-- * This is a review list and never a gate. Some repetition is deliberate: each format file closes
-- * with the same footer pointing back at the always-read craft, and that is the footer doing its job.
-- * The output says where to look; whether a given entry should survive is a judgement.
-- */
--function restatements(at, threshold) {
-- const entries = [];
-- for (const path of everySkillFile(at)) {
-- const text = read(path, at);
-- if (text === null) continue;
-- for (const unit of unitsIn(text)) {
-- if (unit.startsWith("code:")) continue;
-- const grams = trigrams(unit);
-- if (grams.size >= 4) entries.push({ path, unit, grams });
-- }
-- }
--
-- const identical = new Map();
-- for (const entry of entries) {
-- const holders = identical.get(entry.unit) ?? new Set();
-- holders.add(entry.path);
-- identical.set(entry.unit, holders);
-- }
-- const repeats = [...identical].filter(([, holders]) => holders.size > 1)
-- .map(([unit, holders]) => ({ unit, files: [...holders].sort() }))
-- .sort((one, other) => other.files.length - one.files.length);
--
-- // One representative per distinct unit, so a sentence in nine files does not pair with itself.
-- const distinct = [...identical.keys()].map((unit) => entries.find((entry) => entry.unit === unit));
-- const pairs = [];
-- for (let i = 0; i < distinct.length; i += 1) {
-- for (let j = i + 1; j < distinct.length; j += 1) {
-- const score = jaccard(distinct[i].grams, distinct[j].grams);
-- if (score >= threshold) pairs.push({ score, a: distinct[i], b: distinct[j] });
-- }
-- }
-- return { repeats, pairs: pairs.sort((one, other) => other.score - one.score) };
--}
--
--function flagValue(argv, name) {
-- const index = argv.indexOf(name);
-- return index === -1 ? undefined : argv[index + 1];
--}
--
--const argv = process.argv.slice(2);
--const at = flagValue(argv, "--at");
--const route = flagValue(argv, "--route");
--
--if (route !== undefined) {
-- if (routes[route] === undefined) throw new Error(`--route must be one of ${Object.keys(routes).join(", ")}`);
-- process.stdout.write(`${unitsForRoute(route, at).join("\n")}\n`);
--} else if (argv.includes("--links")) {
-- // Only a path that resolves to nothing is reported. A path this scanner reads the wrong way round
-- // would be reported too, which is what the root-relative rule above is for.
-- let broken = 0;
-- for (const path of everySkillFile(at)) {
-- const text = read(path, at);
-- if (text === null) continue;
-- for (const match of text.matchAll(linkPattern)) {
-- if (isTemplate(match[1])) continue;
-- const target = resolveLink(path, match[1]);
-- if (read(target, at) === null) { process.stdout.write(`${path}: \`${match[1]}\` -> ${target} does not exist\n`); broken += 1; }
-- }
-- }
-- process.stdout.write(`${broken} broken\n`);
--} else if (argv.includes("--orphans")) {
-- // A file no route reaches is a file nobody reads. It is the failure a sentence-level diff cannot
-- // see: create a new shared file, link it from one route, and the other route silently loses it.
-- const reached = new Set([...reachable("reconstruction", at), ...reachable("description", at)]);
-- let orphans = 0;
-- for (const path of everySkillFile(at)) if (!reached.has(path)) { process.stdout.write(`${path}\n`); orphans += 1; }
-- process.stdout.write(`${orphans} orphaned\n`);
--} else if (argv.includes("--restatements")) {
-- const threshold = Number(flagValue(argv, "--threshold") ?? 0.45);
-- const { repeats, pairs } = restatements(at, threshold);
-- process.stdout.write("== said identically in more than one file ==\n");
-- for (const repeat of repeats) {
-- process.stdout.write(`${repeat.files.length} files: ${repeat.unit}\n`);
-- for (const file of repeat.files) process.stdout.write(` ${file}\n`);
-- }
-- process.stdout.write(`\n== said differently in more than one file (>= ${threshold}) ==\n`);
-- for (const pair of pairs) {
-- process.stdout.write(`${pair.score.toFixed(2)}\n ${pair.a.path}: ${pair.a.unit}\n ${pair.b.path}: ${pair.b.unit}\n`);
-- }
-- process.stdout.write(`\n${repeats.length} repeated, ${pairs.length} reworded\n`);
--} else {
-- process.stdout.write("usage: --route <reconstruction|description> | --links | --orphans | --restatements [--threshold N] [--at <commit>]\n");
-- process.exit(1);
--}