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: a copy is allowed, a stand-in is not a defect, and syntax is not craft

rponedbd1ec9071ba
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.md
index 6b13f7c0..13f9aa5a 100644
--- a/.agents/skills/hypit/references/authoring.md
+++ b/.agents/skills/hypit/references/authoring.md
@@ -1,6 +1,6 @@
# Hypit source authoring
-Read `references/quickstart.md`, then the authoritative page it selects under `docs/quickstart/`.
+Read `quickstart.md`, then the authoritative page it selects under `docs/quickstart/`.
Keep Author Source, Recipe Source and Run Source complete and internally consistent rather than
assembling independent per-shot source fragments.
@@ -17,3 +17,9 @@ pnpm hypit check path/to/source
Do not create a check wrapper. A successful check establishes legal syntax, references and graph
structure; it does not prove that an uncertain video observation was semantically correct.
+
+This file is about writing an element correctly, which is a narrower question than making the video
+right. What a Track should contain, when a picture may be generated at all, how long a thing stays on
+screen and what shows through when it does not — those are decided in `playbooks/index.md`, whose
+required load order names the craft every program needs regardless of format. A Source can pass
+`hypit check` with every one of those decisions still unmade.
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index 941a730c..048faf4c 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -42,7 +42,7 @@ hypit runtime status
Use `runtime up` for normal Build preparation: it owns the detached durable Worker and prepares the external
programs declared by the Runtime Profile. `programs up/status/down` is only the narrow external-
-program view and does not manage the Worker. See `references/runtime.md` for the Build lifecycle.
+program view and does not manage the Worker. See `runtime.md` for the Build lifecycle.
The repository owns skill discovery: `.agents/skills` is canonical, with repository-root
`.codex/skills` and `.claude/skills` links. This is checkout layout, not a skill setup operation.
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 17d32404..f576f218 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -57,6 +57,25 @@ Place the package at `<project>/packages/local-<slug>/`, named `@hypit/local-<sl
version `0.0.0-dev` and logical Module version `1`. Only create a new package: do not
edit, extend, delete or overwrite an existing Hypit package to fill the gap.
+**Starting that new package from a copy of the closest installed one is allowed, and is usually the
+right way to do it.** The ban is on modifying a package other projects share, not on learning from
+its source: a Style family that differs from `caption-fine` in its timing model, or a board that
+differs from `ranking` in its rows, is most of that package again. Copy it, then make it genuinely
+its own — a new Module ref, a new name for every nominal Type it declares, since a Type belongs to
+the Module that declares it, and new Producer names. Leave the original untouched. The official
+packages are built for exactly this: `caption-fine` states that Common Caption, Composition and Core
+know none of its Recipe fields or layout policy, and `deck-track` that another Deck family can
+install independently and lower to the same terminal `VisualTrack` without changing it. A sibling
+family is the designed extension point, not a workaround.
+
+Read "modelled on the installed packages" that way wherever it appears. Writing two thousand lines
+from scratch to avoid a copy is not more correct, and the ban does not ask for it.
+
+What a copy does cost is upstream: it will not receive the fixes the original gets, and nobody will
+notice it drifted. That is acceptable for a project-local package, which is part of one deliverable
+rather than a library. If the behaviour turns out to be generally useful, that is the promotion this
+section already describes — not a reason to add a parameter to the shared package after all.
+
The package is project-local even when the project is the Hypit checkout. Do not move it into an
official package automatically. After the result is accepted, offer promotion as a separate
contribution.
diff --git a/.agents/skills/hypit/references/quickstart.md b/.agents/skills/hypit/references/quickstart.md
index 3999fb5b..ed8a6ac7 100644
--- a/.agents/skills/hypit/references/quickstart.md
+++ b/.agents/skills/hypit/references/quickstart.md
@@ -11,7 +11,7 @@ The repository docs are authoritative:
| Speech Spine and SemanticMap | `docs/quickstart/timing.md` |
| Caption, Media, Text, Audio Tracks | `docs/quickstart/tracks.md` and the `@hypit/audio-track` package README |
| Film and rendering | `docs/quickstart/composition.md` |
-| Run Source, durable Runtime, Builds, retrieval, and reuse | `docs/quickstart/run.md` and `references/runtime.md` |
+| Run Source, durable Runtime, Builds, retrieval, and reuse | `docs/quickstart/run.md` and `runtime.md` |
Canonical path:
diff --git a/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.md
index 0865dc64..422c5f74 100644
--- a/.agents/skills/hypit/references/reconstruction/final-sources.md
+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md
@@ -89,6 +89,27 @@ does not govern whether the element builds at all. Every failure this check repo
until the check passes — the author should never open the Playground and find that something they
were delivered cannot be seen. Repair as many times as the failure needs, then re-run the check.
+One failure is not a defect, and it is worth knowing before spending repairs on it. The preview has
+to draw outputs nothing has produced yet, so it substitutes a stand-in — a black video frame as long
+as the shot. **A stand-in is not the kind of thing the real output will be**, so a Producer that
+validates the kind of media it receives can refuse it and be entirely correct at build time. A still
+Media Item is the case that bites: it requires image bytes, the stand-in for an unbuilt `gpt:Image`
+is `video/mp4`, and the preview reports a media edge whose artifact is not an image — the same
+sentence it would use for a genuine wiring mistake.
+
+Tell them apart before repairing. It is a stand-in artifact when the edge points at an output this
+Source generates rather than at supplied material, and the message is about the media *kind* rather
+than a value. Pinning does not settle it either: preview-check reads a Run Source but cannot open
+pinned Records without a Runtime, and the script does not offer one. Everything else it reports is
+still a real failure and still has no attempt ceiling.
+
+Two ways out, in order. In a component you own, decide the element kind from the Artifact's own
+`mediaType` instead of hard-coding it — the component then draws the stand-in as video and the real
+picture as an image, and the preview passes honestly. Against an installed Producer that legitimately
+demands one kind, the check cannot pass until the output exists: say so plainly, and verify that
+track on the real Build instead. Do not report the check as passed, and do not let it stand in for
+the delivery measurements in `../playbooks/craft/production-gates.md`.
+
What this check cannot see is equally important: a track that *builds* but looks wrong — a typeface
that does not match, a colour that is off, a shape that is misplaced — reports no error here, because
nothing failed. That is the loop's work, under `reconstruction-loop.md`, where Gemini compares the