Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs(hypit): give revision its own route folder (#116)
rponeawa81044ef85d45
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.mdindex 053edd00..716dd44b 100644--- a/.agents/skills/hypit/SKILL.md+++ b/.agents/skills/hypit/SKILL.md@@ -94,13 +94,16 @@ invalid. Never commit `.env` or copy its secret values into route state, Source,under the checkout's `examples/` directory when it exists. Analyze a semantically matchingproject's author intent; otherwise use the document's general, open-ended fallback. Do nothard-code video types or skip the brief-sufficiency gate.-- A completed project followed by a natural-language change → read `references/revision.md` and use- the independent `revision_state` route. Restore the element's role in the frozen brief, 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 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 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, orfrom a validated existing project → read `references/variant-expansion/route.md`. The main agentinspects examples, freezes format/Slate/component decisions, enumerates vocabulary, discloses thediff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.mdindex fe829988..304a2183 100644--- a/.agents/skills/hypit/references/authoring.md+++ b/.agents/skills/hypit/references/authoring.md@@ -1,6 +1,6 @@# Hypit source authoring-For a post-completion natural-language change, use `revision.md`. That route edits Source/Recipe/Run+For a post-completion natural-language change, use `revision/route.md`. That route edits Source/Recipe/Runand reruns deterministic gates only; this authoring page's visual review guidance does not apply to arevision.diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.mdindex dac9bf86..5cb2b346 100644--- a/.agents/skills/hypit/references/element-review.md+++ b/.agents/skills/hypit/references/element-review.md@@ -2,7 +2,7 @@This visual-review page is for the initial reconstruction/description routes. A post-completionrevision does not use it, does not call a VLM/observer, and stops after deterministic gates; see-`revision.md`.+`revision/route.md`.Structural checks prove that a source is legal. They prove nothing about whether it looks like whatwas wanted. A newly written package can resolve, activate, decode and pass every check while drawingdiff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex 566f4102..c2b78fe4 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -16,7 +16,7 @@ a reconstruction gets for free have to be decided deliberately: what the programevery appearance value *is*. Neither has an evidence file to consult. Write them down rather thandiscovering them at render time.-If a completed project receives a natural-language change, use `../revision.md` instead of restarting+If a completed project receives a natural-language change, use `../revision/route.md` instead of restartingthis route. Revision is Source/Recipe/Run-only and deterministic; it does not invoke a VLM or visualobserver.This remains true after a paid Build has produced the full video: start `revision_state` against the@@ -225,7 +225,7 @@ explicitly requested; the variant route owns its own aggregate and paid-build ga**Read now:** `../studio-confirmation.md`. Before the paid gate, call the preview-mock realizer andstart Studio with its returned temporary `preview.svrun` (not the unresolved author Run). Show thecomplete estimate-timed mock, return the exact URL printed by Studio, and obtain explicit acceptance-and cost approval. If the author declines, enter `../revision.md` and do not submit a Build. After+and cost approval. If the author declines, enter `../revision/route.md` and do not submit a Build. Afteracceptance and paid Build submission, persist the accepted Build-Record Run, start Studio for thatRun, return its exact URL, and start the HyperFrames/final render concurrently.diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex b2f11a50..f5fe9e42 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -2,7 +2,7 @@Revision work does not invoke the visual-review workflow described below. It may run deterministicpreview checks (and optionally render for artifact integrity), but never calls a VLM/observer; read-`revision.md` for that route.+`revision/route.md` for that route.`preview_check` and `render_element` advance the project's `.hypit/route-state.json` only after theirsuccess predicates hold. After a new turn or interruption, read `../recovery.md`, reconcile the state,diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.mdindex 1911c40c..905c7b07 100644--- a/.agents/skills/hypit/references/reconstruction/route.md+++ b/.agents/skills/hypit/references/reconstruction/route.md@@ -14,10 +14,10 @@ Seeing the reconstruction is what that Build is for. What is settled here is thawhich is the part a Build cannot repair. The route then pauses at the Studio confirmation handoffbefore 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.md` from that completed Run; never continue this creation route or edit the rendered file.+`../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.md`. Revision edits Source/Recipe/Run and reruns deterministic+this creation route and read `../revision/route.md`. Revision edits Source/Recipe/Run and reruns deterministicgates; 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@@ -395,7 +395,7 @@ person and product is already a single anchor, because `../playbooks/craft/perso`../playbooks/craft/visual-continuity.md` required that while you were writing.If the author requests a change after seeing the preview, leave this route and follow-`../revision.md`; do not pay or Build a source that has not passed the final deterministic gate.+`../revision/route.md`; do not pay or Build a source that has not passed the final deterministic gate.### 24. Re-run the final deterministic gate@@ -411,7 +411,7 @@ unless the author explicitly requested it.**Read now:** `../studio-confirmation.md`. Realize the preview-mock Run first, then start Studio withthe returned temporary `preview.svrun` (never the original unresolved Run), show the completeestimate-timed mock, return the exact URL printed by Studio, and obtain explicit acceptance and cost approval. If the author declines, enter-`../revision.md` and do not Build. Once accepted, submit the paid Build and persist its accepted+`../revision/route.md` and do not Build. Once accepted, submit the paid Build and persist its acceptedBuild-Record Run; start Studio for that accepted Run, return the exact URL printed by Studio, whilethe HyperFrames/final render proceeds concurrently.@@ -419,5 +419,5 @@ After acceptance, continue with `../runtime.md` for the approved paid Build andWhen the accepted full video is available, a later request such as moving an element or raisingcaptions is a new revision request. Start `revision_state` against the accepted-material Run and-follow `../revision.md`; after its deterministic gates, Studio may hot-reload (or be started for the+follow `../revision/route.md`; after its deterministic gates, Studio may hot-reload (or be started for theRun if none is running), but Revision still performs no VLM/visual review.diff --git a/.agents/skills/hypit/references/recovery.md b/.agents/skills/hypit/references/recovery.mdindex be070ffe..37e37c79 100644--- a/.agents/skills/hypit/references/recovery.md+++ b/.agents/skills/hypit/references/recovery.md@@ -43,8 +43,10 @@ destinations. A component/package digest change, missing inspection evidence or`allowed_changes` is a conflict, not permission to overwrite it.For a completed project with a new natural-language change, use `.hypit/revision-state.json` and the-`revision_state` commands described in `revision.md`. Reconcile both the parent route snapshot and-the revision snapshot before editing. Revision does not call VLM/observer, render, or perform visual+`revision_state` commands described in `revision/route.md`. The project may be supplied directly and+need not have a parent creation route. When a parent route snapshot exists, reconcile it together+with the revision snapshot; otherwise validate the supplied Run as the baseline and start Revision+without inventing parent history. Revision does not call VLM/observer, render, or perform visualreview; it stops after the requested deterministic gates and leaves Studio untouched.After a completed revision, a request for many derivatives starts a new variant-expansion batch fromdiff --git a/.agents/skills/hypit/references/revision.md b/.agents/skills/hypit/references/revision/route.mdsimilarity index 52%rename from .agents/skills/hypit/references/revision.mdrename to .agents/skills/hypit/references/revision/route.mdindex ec51a0f5..71e7e5f3 100644--- a/.agents/skills/hypit/references/revision.md+++ b/.agents/skills/hypit/references/revision/route.md@@ -1,13 +1,27 @@# Post-completion natural-language revision route-When a completed reconstruction or description project receives a request such as “move this element-right” or “raise the captions”, start a separate revision route. Do not edit the rendered MP4, PNG,-WAV, preview mock or Artifact directly. The source remains authoritative.+Use this route whenever a natural-language change targets a completed Hypit project. The project may+have just finished reconstruction, original authoring or an earlier revision, or the author may hand+over an already completed project directory directly. Revision does not require the current agent to+have created the project and does not require a parent creation route to exist.++For a directly supplied directory, first locate its canonical Run and Source/Recipe closure, then+run `validate_local_author_packages`, `validate_script_cues`, `hypit check` and `preview_check` to+confirm the existing project is a sound revision baseline. If `.hypit/route-state.json` exists, read+and reconcile it; if it does not, do not invent a reconstruction or description history. Start+`revision_state` without `--parent-route` and persist the baseline check evidence with the first+checkpoint.++Requests such as “move this element right” or “raise the captions” start a separate revision route.+Do not edit the rendered MP4, PNG, WAV, preview mock or Artifact directly. The source remains+authoritative.## Recovery and state-Read `SKILL.md`, `recovery.md`, the parent `.hypit/route-state.json`, the project's-`.hypit/revision-state.json`, and `git status`. Start the state once:+Read `../../SKILL.md`, `../recovery.md`, the project's `.hypit/revision-state.json`, `git status`, and+the parent `.hypit/route-state.json` only when one exists. Start the state once.++From a completed reconstruction or original-authoring route:```bashhypit-reference-video-tools revision_state --action start \@@ -15,11 +29,19 @@ hypit-reference-video-tools revision_state --action start \--request 'raise the captions slightly'```-The snapshot is atomic and small. It records the parent route/state digest, request summary, impact-and affected Source, durable artifact references, decisions, current stage and `next_action`.-Use `revision_state read` and `revision_state reconcile` after interruption or context compaction;-never resume from chat memory. Manual intent mapping and Source edits require an explicit checkpoint.-Machine evidence may advance only when its file/check predicate is true.+From a directly supplied completed project with no parent route state:++```bash+hypit-reference-video-tools revision_state --action start \+ --project-root <project> --run build.svrun \+ --request 'raise the captions slightly'+```++The snapshot is atomic and small. It records the parent route/state digest when one exists, request+summary, impact and affected Source, durable artifact references, decisions, current stage and+`next_action`. Use `revision_state read` and `revision_state reconcile` after interruption or context+compaction; never resume from chat memory. Manual intent mapping and Source edits require an explicit+checkpoint. Machine evidence may advance only when its file/check predicate is true.Stages are:@@ -40,7 +62,9 @@ and give the author the exact URL with the updated result.## Work sequence1. Read the current `main.svml`, `recipes.svs`, `build.svrun`, runtime profile, brief and the target- package README/vocabulary. Recover the target element's role in the author's intent.+ package README/vocabulary. Recover the target element's role in the author's intent. For a+ directly supplied project, use its authored Source, project documentation and current graph as the+ frozen intent evidence; do not force it through reconstruction or original authoring first.2. Classify the request's impact: geometry/style, Script/semantic timing, graph structure, or paidgeneration. Record the affected Source files and the smallest invalidated graph closure.3. Map natural language to the authoritative field before editing. A request such as “move the@@ -51,7 +75,7 @@ and give the author the exact URL with the updated result.4. Edit only Source, Recipe or Run. Re-run package/Cue gates, `hypit check`, `preview_check`, and theroute-specific final check. Do not render, compare, review or inspect any frame during revision;existing unchanged artifacts may be reused by digest. Once the gates pass, follow- `studio-confirmation.md`'s conditional Studio handoff.+ `../studio-confirmation.md`'s conditional Studio handoff.5. Check the final gate. Confirm cost again only when an image/video/voice generation input changed;geometry and layout revisions do not trigger a paid Build. Build only after explicit approval.@@ -60,6 +84,6 @@ updated Run, that session must continue using the existing SVRun-native preview-revive `make_placeholder`, hand-written SemanticTracks, or absolute-path mock Candidates.If the author asks for many independent derivatives after this revision is complete, reconcile and-finish `revision_state`, then start `variant-expansion/route.md` from the revised project. The batch-is not another revision step: its main agent rechecks examples, format/component plans, package gaps-and per-variant scopes before copying or dispatching work.+finish `revision_state`, then start `../variant-expansion/route.md` from the revised project. The+batch is not another revision step: its main agent rechecks examples, format/component plans, package+gaps and per-variant scopes before copying or dispatching work.diff --git a/.agents/skills/hypit/references/studio-confirmation.md b/.agents/skills/hypit/references/studio-confirmation.mdindex f0792769..05712d80 100644--- a/.agents/skills/hypit/references/studio-confirmation.md+++ b/.agents/skills/hypit/references/studio-confirmation.md@@ -23,7 +23,7 @@ After the route-specific final check passes, but before submitting any paid Builintended result are acceptable for paid generation.5. Do not submit `hypit build` until the author explicitly accepts and confirms the cost.-If the author does not accept, do not Build. Capture the requested change and enter `revision.md`.+If the author does not accept, do not Build. Capture the requested change and enter `revision/route.md`.Revision edits Source/Recipe/Run and reruns deterministic gates; it does not ask an agent or VLM tojudge the picture.@@ -37,7 +37,7 @@ read-only presentation of the current Run while the render proceeds. Report rendthe Studio URL independently.After that full video is delivered, any new natural-language change is routed to-`revision_state start --run <accepted-material-run>` and `revision.md`. It is not a second visual+`revision_state start --run <accepted-material-run>` and `revision/route.md`. It is not a second visualreview loop and it never edits the rendered artifact; the revision updates Source/Recipe/Run andreruns only the deterministic gates before the next Studio handoff or paid Build confirmation.diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.mdindex 0b01884d..262906ab 100644--- a/packages/reference-video-tools/README.md+++ b/packages/reference-video-tools/README.md@@ -10,7 +10,9 @@ agent and checked with the installed `hypit check` command.For a completed project change, `revision_state --action start|read|checkpoint|reconcile` stores asmall atomic `.hypit/revision-state.json` snapshot. Revision edits Source/Recipe/Run and reruns-deterministic gates; it does not invoke a VLM/observer or perform visual review.+deterministic gates; it does not invoke a VLM/observer or perform visual review. The project may be+handed in as an already completed directory: after its baseline gates pass, Revision can start+without a parent reconstruction or description route state.For a validated source project that needs independent derivatives, `variant_state` stores the atomicbatch snapshot and base-project locator, `variant_init` copies the authored project without generateddiff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.tsindex b85ced57..7f2577ef 100644--- a/packages/reference-video-tools/src/cli.ts+++ b/packages/reference-video-tools/src/cli.ts@@ -32,6 +32,7 @@ function usage(): string {" hypit-reference-video-tools variant_init --project-root <base> --output-root <batch> --slate <slate.json>"," hypit-reference-video-tools variant_check --run <variant>/build.svrun [--runtime <hypit.runtime.json>]"," route_state start: --route reconstruction|description|variant|variant-package [--run <run>] [--reference-id <id>]",+ " revision_state start: [--run <run>] [--parent-route reconstruction|description] [--request <text>]"," checkpoint: --route <route> (--state <stage> | --step <n>) [--status in_progress|complete|blocked] [--next-action <text>] [--artifacts <json>]"," read/reconcile: --project-root <dir>"," hypit-reference-video-tools prepare_reference --video-path <path or link> [--observer gemini|agent] [--redo media|transcript|people|voices|systems|places|all]",