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.

docs(hypit): give revision its own route folder (#116)

rponeawa81044ef85d45
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 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 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.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, or
from a validated existing project → read `references/variant-expansion/route.md`. The main agent
inspects examples, freezes format/Slate/component decisions, enumerates vocabulary, discloses the
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.md
index 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/Run
and reruns deterministic gates only; this authoring page's visual review guidance does not apply to a
revision.
diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.md
index 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-completion
revision 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 what
was wanted. A newly written package can resolve, activate, decode and pass every check while drawing
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index 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 program
every appearance value *is*. Neither has an evidence file to consult. Write them down rather than
discovering 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 restarting
this route. Revision is Source/Recipe/Run-only and deterministic; it does not invoke a VLM or visual
observer.
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 and
start Studio with its returned temporary `preview.svrun` (not the unresolved author Run). Show the
complete 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. After
acceptance and paid Build submission, persist the accepted Build-Record Run, start Studio for that
Run, 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.md
index 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 deterministic
preview 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 their
success 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.md
index 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 tha
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.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 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
@@ -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 with
the returned temporary `preview.svrun` (never the original unresolved Run), show the complete
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 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 accepted
Build-Record Run; start Studio for that accepted Run, return the exact URL printed by Studio, while
the HyperFrames/final render proceeds concurrently.
@@ -419,5 +419,5 @@ After acceptance, continue with `../runtime.md` for the approved paid Build and
When the accepted full video is available, a later request such as moving an element or raising
captions 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 the
Run 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.md
index 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 visual
review; 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 from
diff --git a/.agents/skills/hypit/references/revision.md b/.agents/skills/hypit/references/revision/route.md
similarity index 52%
rename from .agents/skills/hypit/references/revision.md
rename to .agents/skills/hypit/references/revision/route.md
index 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:
```bash
hypit-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 sequence
1. 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 paid
generation. 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 the
route-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.md
index 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 Buil
intended 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 to
judge the picture.
@@ -37,7 +37,7 @@ read-only presentation of the current Run while the render proceeds. Report rend
the 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 visual
review loop and it never edits the rendered artifact; the revision updates Source/Recipe/Run and
reruns 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.md
index 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 a
small 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 atomic
batch snapshot and base-project locator, `variant_init` copies the authored project without generated
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index 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]",