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: relax project package naming convention
rpone20a8c2a91085
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.mdindex 8725420a..f7966ee8 100644--- a/.agents/skills/hypit/SKILL.md+++ b/.agents/skills/hypit/SKILL.md@@ -49,7 +49,8 @@ before continuing. Never resume from chat memory alone, and never repeat a complwithout verifying its durable evidence.Before Source is accepted, every route must complete persisted vocabulary inspection,-`validate_local_author_packages` for every `packages/local-*` package, and+`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 finalcheck repeat these gates even if route-state claims they were completed.@@ -62,6 +63,13 @@ Node entrypoints instead. The npm package is not currently published, so absencecommand is not permission to install it from the registry. `references/environment.md` establishesthe 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 recreatingdiff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.mdindex 9dc2174b..87e8df5d 100644--- a/.agents/skills/hypit/references/environment.md+++ b/.agents/skills/hypit/references/environment.md@@ -79,8 +79,11 @@ not run there. Do not claim compatibility that the platform dependencies cannot`hypit` and Node are required. `ffmpeg` and `ffprobe` are required by local media and preview paths; ahost package manager puts them on `PATH` on macOS and Linux, and a manual install puts them on `PATH`-on Windows. Credentials load from a project's `.env` in the same shell that runs the commands:-`set -a && . ./.env && set +a`.+on Windows. Credentials load before any observer or Provider probe. In a checkout task, check the+checkout root `.env` and then the project root `.env` (project values override duplicates) in the same+shell:+`set -a; [ ! -f <checkout-root>/.env ] || . <checkout-root>/.env; [ ! -f <project-root>/.env ] || . <project-root>/.env; set +a`.+When these values satisfy the selected observer/Provider, do not ask the author for them again.`uv` is required only when the selected Runtime Profile uses a managed Python program such asWhisperX or OpenCV.Reconstructing a video given as a link rather than as a file needs `uv` too: `yt-dlp` is pinned under@@ -125,12 +128,13 @@ changes an exact adapter dependency, the next explicit `runtime up` lets npm updOnly someone changing Hypit itself clones the repository. A task already running from that checkoutmay 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`. Never place an-author project or its local packages inside that checkout.+`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.A project directory carries its own `package.json` — a name and `"private": true` is the whole file,since nothing reads its fields. `hypit check`, `plan` and `build` locate the package root by walkingup from the project until some `package.json` appears; the file is what stops that walk at the-project, so `packages/local-<slug>/` resolves from there rather than from whichever ancestor+project, so `packages/<slug>/` resolves from there rather than from whichever ancestordirectory happened to hold one. It is matched by no `pnpm-workspace.yaml` glob and adds the projectto no workspace.diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex 181557ce..09e51ee3 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -1,4 +1,4 @@-# Develop a project-local author package+# Develop an author package for the projectUse this workflow only after proving that no legal composition of installed packages expresses therequired behavior. A similar-looking tag is insufficient when its declared Types, timing or output@@ -93,11 +93,16 @@ is, so read its `mediaType` off the Artifact rather than assuming what the slot'## Package boundary-Place the package at `<project>/packages/local-<slug>/`, named in the project's own scope such as-`@my-project/local-<slug>`, with physical+Place the package at `<project>/packages/<slug>/`, named in the project's own scope such as+`@my-project/<slug>`, with physicalversion `0.0.0-dev` and logical Module version `1`. Only create a new package: do notedit, extend, delete or overwrite an existing Hypit package to fill the gap.+The directory and package name may use any valid, descriptive slug; do not add a `local-` prefix+just to identify where the package was created. The package README documents its public contract,+syntax, inputs, outputs and preview. It does not need to say that the package is temporary,+project-level or otherwise describe its provenance.+The package it stands beside is untouched. A Style family that differs from `caption-fine` in itstiming model, or a board that differs from `ranking` in its rows, installs as a sibling: its ownModule ref, its own name for every nominal Type it declares, since a Type belongs to the Module that@@ -114,7 +119,7 @@ The project is never the Hypit Distribution. Do not move a local package into anautomatically. After the result is accepted, offer promotion as a separate contribution.The component reaches Studio's generic Track fallback until its project adds a companion package,-for example `@my-project/local-<slug>-studio`, to the project's `hypit.studio.json`. That companion owns+for example `@my-project/<slug>-studio`, to the project's `hypit.studio.json`. That companion ownsonly Studio interpretation and operations through `hypit.studio-adapter@1`; it never edits`packages/studio`, and the author package never imports Studio. A generic block is valid while nospecial interpretation is needed.@@ -162,7 +167,7 @@ nothing.```bashhypit image --prompt "the surface this component draws on" \- --to <project>/packages/local-<slug>/assets/paper.png+ --to <project>/packages/<slug>/assets/paper.png```It writes a picture and nothing else — no Source, no Build, no Record, no Runtime Profile. A@@ -227,12 +232,13 @@ Before Source can be considered authored, run:hypit-reference-video-tools validate_local_author_packages --run <path/to/build.svrun>```-Every project-local `packages/local-*` package must expose a non-empty Manifest, at least one+Every project-owned package under `<project>/packages/` must expose a non-empty Manifest, at least oneMarkup Surface, at least one Producer and at least one Run Fragment with operations and exports. TheRun's compiled Graph must contain an operation from that package, and the Author Source must importand use its Surface. An import without use, a marker-only package, or a package replaced by a similarofficial component fails with a machine-readable diagnostic. If no gap exists, do not leave an unused-local package in the project.+package in the project. `validate_local_author_packages` discovers these package directories from+their manifests; the directory name is not a validation signal.The Host resolves the explicitly selected physical package name directly at`<project>/packages/<package-basename>/` and supplies official `@hypit/*` imports from the read-onlydiff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex 282d56b4..e79df2b2 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -43,7 +43,7 @@ interruption or context compaction, read `../recovery.md`, run `route_state --ac| `environment` | explicit checkpoint after Distribution, project and credentials are selected | `hypit paths --json` || `brief-frozen` | explicit checkpoint naming the frozen brief, audience, format and claims | return to the brief checkpoint || `vocabulary-checked` | vocabulary inspection is persisted for the Run | `inspect_svml_vocabulary --run <run>` |-| `package-ready` | every `packages/local-*` package has real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <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>` || `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` || `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` |@@ -70,15 +70,25 @@ model tier and how many takes are **yours to decide rather than to ask for**.**Read now:** `../environment.md` — the three independent places, Distribution selection and thelauncher substitution rule. `../runtime.md` — the hard boundary between a project and a Distribution.-The project gets its own directory outside the installed Distribution, normally `<home>/<name>/`,-named after the video, with a `package.json` carrying a name and `"private": true`.+When working in this checkout, put the independent project at+`<checkout-root>/projects/<video-name>/` (use a safe slug), with a `package.json` carrying a name and+`"private": true`.### 2. 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 && source .env && set +a+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 Provider, continue without asking the author for them+again. Ask only for a credential that is absent or invalid after both `.env` files are checked.+**Read now:** `../credentials.md` — which variables each Provider needs.### 3. Make the brief sufficient before writing Source@@ -147,7 +157,7 @@ hypit-reference-video-tools validate_local_author_packages --run build.svrunhypit-reference-video-tools validate_script_cues --run build.svrun```-`validate_local_author_packages` proves that every `packages/local-*` package has a real+`validate_local_author_packages` proves that every project-owned package under `packages/` has a realSurface/Producer/Fragment and is used by the compiled Source Graph. `validate_script_cues` rejectsany Cue over four visible words; split it with `||` before continuing.diff --git a/.agents/skills/hypit/references/package-promotion.md b/.agents/skills/hypit/references/package-promotion.mdindex b387106c..e9443302 100644--- a/.agents/skills/hypit/references/package-promotion.md+++ b/.agents/skills/hypit/references/package-promotion.md@@ -25,14 +25,14 @@ If the author wants it promoted, these are the parts. Say up front that this isthan a path anyone has walked — no package under `packages/` began inside a project, so the firstperson to do it should correct what follows.-- **The name is load-bearing in six places.** `@my-project/local-<slug>` becomes `@hypit/<slug>` in+- **The name is load-bearing in six places.** `@my-project/<slug>` becomes `@hypit/<slug>` in`package.json`; in the Module ref in `src/manifest.ts`, where renaming it **renames every nominalType and Producer in the Module at once**, because each is built from that one const; in every- Author Source that writes `import … from "@my-project/local-<slug>@1"`; in the root `package.json`+ Author Source that writes `import … from "@my-project/<slug>@1"`; in the root `package.json``devDependencies`; in the package's own test harness; and in **both** package catalogs,`docs/guide/packages.md` and `docs/zh/guide/packages.md`. An English-only catalog entry is a halfpromotion.-- **Studio support is a companion.** A project-owned `@my-project/local-<slug>-studio` may already provide+- **Studio support is a companion.** A project-owned `@my-project/<slug>-studio` may already providerich interpretation. Promotion moves that companion into an official Studio adapter package; itnever copies its code into `@hypit/studio` and never teaches the domain package about Studio.- **Its own chrome becomes repository content.** Project package assets already belong to thediff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex c169e37e..15cca096 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -36,7 +36,7 @@ hypit-preview-check /path/to/project/build.svrun```Prefer the subcommand. It takes `--package-root <dir>`, which is where the packages the Source-imports are resolved from — a project's own `packages/local-<slug>/` are installed against the+imports are resolved from — a project's own packages under `packages/<slug>/` are installed against theproject root, so name it there and the check reaches them from wherever you are standing. Withoutthe flag the working directory is used. The bare bin fixes the package root to the Run file's owndirectory and takes no flags, so reach for it when the Run sits at the project root and you want thediff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.mdindex 495f9161..b3f0e067 100644--- a/.agents/skills/hypit/references/reconstruction/route.md+++ b/.agents/skills/hypit/references/reconstruction/route.md@@ -83,7 +83,7 @@ of intent; files and check results remain the authority.| `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` | vocabulary inspection is persisted for the Run | `inspect_svml_vocabulary --run <run>` |-| `package-ready` | every `packages/local-*` package has real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <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>` || `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` || `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` |@@ -117,23 +117,31 @@ report that no runnable Hypit Distribution is present and stop.### 2. Choose the project directory-Its own directory outside the installed Distribution, normally `<home>/<something>-reverse/`, named-after the video. Use a directory the author named only if they named one. Give it a `package.json`+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 a name and `"private": true`, and nothing else — no field in it is read. `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 `packages/local-<slug>/` resolve. It+this file is what stops that walk at the project and lets the project's `packages/<slug>/` resolve. Itmatches 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-A project that keeps credentials in `.env` does not load them automatically:+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 && source .env && set +a+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. Ask only for a credential that is absent or invalid after both `.env` files are checked.+**Read now:** `../credentials.md` — which variables each Provider needs. A variable a Provider needsand this machine does not hold is named, and the route stops there. The Vertex pair is the oneexception: it selects an observer rather than blocking one, and step 5 owns it.@@ -257,7 +265,7 @@ claiming a vocabulary gap or writing Source.**Done when:** the package has a real Manifest, Types, Producers, Validators, Surface, decoder,Fragment, activation, README and preview, and `validate_local_author_packages --run <build.svrun>`reports that the Source imports and compiled Graph uses it. A component that merely loads is not done.-If no gap remains, remove unused `packages/local-*` directories.+If no gap remains, remove unused project-owned package directories.---diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.mdindex 335dbc6c..c1f2c668 100644--- a/.agents/skills/hypit/references/runtime.md+++ b/.agents/skills/hypit/references/runtime.md@@ -153,8 +153,8 @@ material, never a place to turn into the author's project.**Give the project directory its own `package.json`, before the first `check`.** Package discoverystarts at the project and walks up until it finds one; without it the search runs past the project-and settles on whichever directory above happens to have one, and every `packages/local-*` the-project owns becomes unresolvable — `cannot resolve installed package @scope/local-name`. A minimal+and settles on whichever directory above happens to have one, leaving every package under the+project's `packages/` unresolvable. A minimalfile is the whole fix, and it is what makes the directory a boundary rather than a place thathappens to hold Sources:diff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.mdindex c459f9a3..aa7662cc 100644--- a/.agents/skills/hypit/references/vocabulary.md+++ b/.agents/skills/hypit/references/vocabulary.md@@ -131,5 +131,7 @@ without a project document is on the wrong side of it.After inspection, persist the result with `inspect_svml_vocabulary --run <build.svrun>`. Beforewriting or checking Source, run `validate_local_author_packages --run <build.svrun>`. Every-`packages/local-*` directory must expose a real Surface, Producer and Fragment and must be imported-and used by the compiled Graph; otherwise the route stops with a machine-readable diagnostic.+Every project-owned package directory under `packages/` must expose a real Surface, Producer and+Fragment and must be imported and used by the compiled Graph; otherwise the route stops with a+machine-readable diagnostic. Package directory names are descriptive slugs, not a required+`local-` prefix.diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.tsindex 970b0455..2be20262 100644--- a/packages/reference-video-tools/src/authoring.ts+++ b/packages/reference-video-tools/src/authoring.ts@@ -131,7 +131,7 @@ function repositoryRoot(): string {* Where installed packages are resolved from, found the way `hypit check` finds it: the nearest* directory at or above the project that holds a `package.json`.*- * A project's own `packages/local-*` are installed against the project, so a root taken from+ * A project's own packages are installed against the project, so a root taken from* anywhere else resolves none of them. This is the same walk `packages/cli/src/main.ts` performs,* and the reason a project is given a `package.json` of its own — without one the walk passes* through it and lands on the tree.@@ -554,7 +554,7 @@ export async function renderElement(input: RenderElementInput): Promise<Record<sconst runPath = resolve(cwd, run);const projectRoot = dirname(runPath);// Where installed packages are found, which is not where the Hypit tree is. A project carries its- // own `packages/local-*`, so the search starts at the project and walks up the way the CLI's does —+ // own packages, so the search starts at the project and walks up the way the CLI's does —// resolving against the tree instead would miss every package the project installed for itself.const packageRoot = nearestPackageRoot(projectRoot) ?? repositoryRoot();const outPath = resolve(cwd, out);diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.tsindex d02ce5b3..81ff6e61 100644--- a/packages/reference-video-tools/src/checks.ts+++ b/packages/reference-video-tools/src/checks.ts@@ -125,7 +125,7 @@ async function checkedSources(runPath: string): Promise<{ readonly ok: boolean;: join(distributionRoot!, "bin", "hypit.mjs");// The project is the package root, the way `hypit check` finds it when it is run from there. A- // project inside a larger tree resolves none of its own `packages/local-*` without this.+ // project inside a larger tree resolves none of its own packages without this.const checked = spawnSync(process.execPath, [hypit, "check", runPath, "--package-root", dirname(runPath)], {encoding: "utf8", windowsHide: true, timeout: 600_000,env: { ...process.env, HYPIT_STRICT_SCRIPT_CUES: "1" },diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 6d5aedaf..0bdca9d0 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -1107,8 +1107,11 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst runPath = resolve(invokedFrom(), input.run);const projectRoot = nearestPackageRoot(dirname(runPath)) ?? packageRoot;const packagesRoot = join(projectRoot, "packages");- const localDirectories = (await readdir(packagesRoot, { withFileTypes: true }).catch(() => []))- .filter((entry) => entry.isDirectory() && entry.name.startsWith("local-"))+ // Project package directories are discovered by their location and manifest, not by a+ // naming convention. A package created for one video may use any valid descriptive slug;+ // requiring a `local-` prefix would let other project-owned packages evade this gate.+ const projectPackageDirectories = (await readdir(packagesRoot, { withFileTypes: true }).catch(() => []))+ .filter((entry) => entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith(".")).map((entry) => join(packagesRoot, entry.name));const expected = new Set(input.expected_packages ?? []);const distributionPackageRoot = videoCliDistribution.packageRoot;@@ -1137,7 +1140,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV// structural diagnostics for every local package instead of hiding them behind one exception.}const results: Record<string, unknown>[] = [];- for (const directory of localDirectories) {+ for (const directory of projectPackageDirectories) {const manifestPath = join(directory, "package.json");const manifest = await readJson<{ name?: string; hypit?: { activation?: string } }>(manifestPath);const specifier = manifest?.name ?? basename(directory);@@ -1192,7 +1195,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVvocabulary_checked: vocabularyEvidence,...(vocabularyEvidence ? {} : { errors: ["VOCABULARY_NOT_CHECKED"] }),packages: results,- ...(localDirectories.length === 0 && expected.size === 0 ? { note: "no project-local packages declared" } : {}),+ ...(projectPackageDirectories.length === 0 && expected.size === 0 ? { note: "no project-owned packages declared" } : {}),};}const model = options.model ?? process.env.GEMINI_MODEL?.trim() ?? "gemini-3.1-pro-preview";