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: clarify project layout and runtime selection
kashorinb8a937af970f
diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.mdindex 0a78dbac..d1f99bee 100644--- a/.agents/skills/hypit/references/runtime.md+++ b/.agents/skills/hypit/references/runtime.md@@ -90,6 +90,11 @@ hypit get <build-id> \--output final.video --to output/final.mp4```+Resolve the project before selecting its Runtime. `--workspace` is explicit; otherwise run from the+project directory (or one of its package-bounded descendants). `runtime use` writes one exact+project-local pointer. Never infer a Profile from its filename or let a parent project's selection+stand in for this project's choice.+The paid-build handoff is defined in `studio-confirmation.md`: show the complete preview-mock Run inStudio and obtain acceptance before `hypit build`; after acceptance, Studio for the accepted Run andthe HyperFrames/final render may start concurrently. The render must not be blocked on the author's@@ -107,7 +112,8 @@ After Runtime package selection changes, run `runtime up`: this is the explicitboundary for machine npm dependencies, Managed Programs and the detached Worker. Use `doctor` foran active full-profile diagnosis and `runtime status` to observe the deployment. `build` repeats thecheap preflight and fails before durable submission when deployment is not ready; it never installs-or starts a Managed Program.+or starts a Managed Program. If provisioning is already complete and only the Worker is stopped,+`build` starts that Worker before it submits the Build.Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from advancing active Builds.External programs are intentionally independent; stop them only with `programs down`. Saved Builddiff --git a/docs/guide/runtime.md b/docs/guide/runtime.mdindex d4ac6b7b..16e83eae 100644--- a/docs/guide/runtime.md+++ b/docs/guide/runtime.md@@ -203,6 +203,12 @@ hypit runtime logshypit runtime down```+`runtime use` binds one explicit Profile to one already resolved project. The project comes from+`--workspace`, or from the current directory's declared package boundary; the selection never+defines that boundary. Commands read only `<project>/.hypit/runtime`: they do not scan for a+conventionally named Profile and do not inherit a selection from a parent project. Separate projects+therefore select separately, even when their Profiles declare equivalent external Endpoints.+`runtime up` asks npm to prepare the selected adapters' exact upstream packages in the sharedmachine home, prepares declared Managed Programs, then starts the local Worker. `build` performs noprovisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Workerdiff --git a/docs/quickstart.md b/docs/quickstart.mdindex 58e6ff31..901856aa 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -116,6 +116,10 @@ project. By default, Build Results live under the project's `.hypit/results`; atemporary Resources always live under the selected Profile's `dataRoot`.`runtime use` stores only a local pointer at `.hypit/runtime`. Source imports select authorpackages; the Profile independently selects Credential Stores and Endpoints through their own `use` entries.+Project resolution happens first. `--workspace` selects it explicitly; otherwise the current+directory's nearest `package.json` is its boundary, or the current directory itself for a plain+creative folder. Only that exact project's `.hypit/runtime` is read—Profile filenames are never+guessed and parent-project selections are never inherited.Start from [`examples/talking-film-live`](https://github.com/hypit-ai/hypit/tree/main/examples/talking-film-live) when you need acomplete Runtime Profile. Copy the source structure, then replace its assets, Script, model choicesdiff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex fa66e091..e7fc0db7 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -30,22 +30,37 @@ from any independent video project.Only `build` submits work. `plan` is the normal preview. `check` is an editing aid; `doctor` is adeployment diagnostic. They are safe to run, but not mandatory ceremony before every Build.-One convenient project layout is:+One convenient layout for a project with several Author, Recipe and Run Sources is:```textmy-video/- main.svml author meaning- styles.svs optional authored styles- build.svrun this Run's Targets and Candidate choices- assets/ project-owned input media- output/ explicit exports for people and other tools- hypit.runtime.json execution environment+ package.json project boundary+ authors/+ main.svml one Author entry+ alternate.svml another Author entry, when genuinely needed+ recipes/+ visual.svs authored visual Recipes+ generation.svs authored generation Recipes+ runs/+ images.svrun one executable intention+ takes.svrun another executable intention+ final.svrun final delivery intention+ assets/ project-owned input media+ kits/ optional vendored Recipe Kits+ packages/ optional project-local Author packages+ output/ explicit exports for people and other tools+ hypit.runtime.json execution environment+ hypit.results.json optional Result repository selection+ .hypit/ generated local Runtime and Result data```-This is a convention, not a schema. Hypit uses the paths written in Source imports, `<author-source="…">`, CLI arguments and `get --to`; it does not require these names or recognize `assets/`-or `output/` specially. The managed Result repository remains separate under `.hypit/results` by-default.+This layout is only a human-facing recommendation, never a required project schema. A small project+may keep several `.svml`, `.svs` and `.svrun` files flat at its root, and another project may group+them differently. Hypit uses only the paths written in Source imports, `<author source="…">`, CLI+arguments and `get --to`; it does not require these names or recognize `authors/`, `recipes/`,+`runs/`, `assets/` or `output/` specially. Each Run selects one Author entry, while that Author+Source closure may explicitly import multiple Author or Recipe Sources. The managed Result repository+remains separate under `.hypit/results` by default.Run Source and Runtime Profile do not silently rewrite the video. Creative model choices remain inthe Author Source or in packages that it explicitly imports.@@ -220,6 +235,10 @@ hypit paths`runtime use` writes only `.hypit/runtime`. It does not start a Worker, create Runtime data orchange installed packages. See [Runtime](../guide/runtime.md) for the Profile schema and boundaries.+The CLI resolves the project first: `--workspace` is an explicit boundary; otherwise the nearest+`package.json` above the current directory is the boundary, falling back to the current directory+for a plain creative folder. It then reads only that project's `.hypit/runtime`. It never discovers+a Profile from a conventional filename or inherits another project's selection from a parent directory.## Configure selected credentials@@ -265,8 +284,8 @@ cd /work/my-filmhypit runtime use hypit.runtime.json```-The Workspace is the selected project or entry Source directory. Override it-only with `--workspace`. `--package-root` locates installed packages and never widens Source access.+The Workspace is resolved before the Runtime Profile. Override it explicitly with `--workspace`;+the entry Source path and Runtime selection never choose it. `--package-root` locates installed packages and never widens Source access.`--asset-root` grants read access to additional asset bytes without permitting Source imports there.```text@@ -327,9 +346,11 @@ external-program diagnostics. It never starts external work.`plan` may run without a Runtime at all. Both `plan` and `build` may omit `--runtime` after`hypit runtime use`; `build` requires either that selection or an explicit Profile.-Use `runtime up` to install selected upstream packages, prepare Managed Programs and start the-Worker before submission. `build` repeats only the cheap read-only preflight and refuses before-submission when anything is missing; it never provisions dependencies. `runtime status` observes+Use `runtime up` after selecting or changing a deployment to install selected upstream packages,+prepare Managed Programs and start the Worker. `build` repeats only the cheap read-only preflight+and refuses before submission when a required package or Program is missing; it never provisions+dependencies. When the deployment is already prepared and only its Worker is stopped, `build`+starts that Worker before durable submission. `runtime status` observesthe deployment, while `programs up|status|down` is the narrower lifecycle view for long-livedprocesses declared by Endpoints.diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.mdindex 63fa6465..43f8bafb 100644--- a/docs/zh/guide/runtime.md+++ b/docs/zh/guide/runtime.md@@ -188,6 +188,11 @@ hypit runtime logshypit runtime down```+`runtime use` 把一份显式 Profile 绑定到一个已经解析完成的项目。项目来自 `--workspace`,+或当前目录声明的 package 边界;Runtime 选择不能反过来定义项目。命令只读取+`<project>/.hypit/runtime`,不会扫描约定文件名,也不会继承父项目的选择。即使几个项目声明+了等价的外部 Endpoint,它们也必须分别完成选择。+`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备 ManagedProgram 并启动本地 Worker。`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保Worker 可用。`activity`、`cancel` 用来观察和控制活跃工作;`status` 分别读取 Runtime 与 Result,一边失败diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex 4a08f418..9af7f90c 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -111,6 +111,9 @@ Distribution 里的官方包。默认情况下,完整 Build Result 位于项不管理 Result,项目根的 `hypit.results.json` 可以把同一套 Result 模型指向 S3。Runtime 活跃状态与临时Resource 始终位于所选 Profile 的 `dataRoot`。`runtime use` 只在 `.hypit/runtime` 保存一个本地指针。Source import 选择作者包,Profile 则通过 Credential Store 与 Endpoint 各自的 `use` 独立选择环境包。+项目必须先确定:显式 `--workspace` 直接选择项目,否则以当前目录向上的最近 `package.json`+为边界;普通创作目录没有该文件时使用当前目录。CLI 只读取该项目自己的 `.hypit/runtime`,+不会猜测 Profile 文件名,也不会继承父项目的选择。需要完整 Runtime Profile 时,从[`examples/talking-film-live`](https://github.com/hypit-ai/hypit/tree/main/examples/talking-film-live) 的结构开始:复制文件结构,diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdindex 91ce2e12..9196044a 100644--- a/docs/zh/quickstart/run.md+++ b/docs/zh/quickstart/run.md@@ -26,21 +26,36 @@ hypit get <build-id> --output final.video --to output/final.mp4只有 `build` 会真正提交工作。`plan` 是普通预览;`check` 用于编辑源码,`doctor` 用于配置和排查部署。它们都安全,但不是每次 Build 前必须重复的仪式。-一种顺手的项目目录约定是:+当项目包含多份 Author、Recipe 和 Run Source 时,一种顺手的目录约定是:```textmy-video/- main.svml 作者意图- styles.svs 可选的作者样式- build.svrun 本次 Run 的 Target 与 Candidate 选择- assets/ 项目自己的输入素材- output/ 显式导出给人或其他工具的副本- hypit.runtime.json 执行环境+ package.json 项目边界+ authors/+ main.svml 一份 Author 入口+ alternate.svml 确有需要时的另一份 Author 入口+ recipes/+ visual.svs 视觉 Recipe+ generation.svs 生成 Recipe+ runs/+ images.svrun 一种执行意图+ takes.svrun 另一种执行意图+ final.svrun 最终交付意图+ assets/ 项目自己的输入素材+ kits/ 可选的项目内 Recipe Kit+ packages/ 可选的项目本地 Author 包+ output/ 显式导出给人或其他工具的副本+ hypit.runtime.json 执行环境+ hypit.results.json 可选的 Result 仓库选择+ .hypit/ 自动产生的本地 Runtime 与 Result 数据```-这只是推荐,不是项目格式。Hypit 只服从 Source import、`<author source="…">`、CLI 参数和-`get --to` 中明确写出的路径,不要求这些名字,也不会特殊识别 `assets/` 或 `output/`。受管理的-Result 仓库与它们分开,零配置时仍位于 `.hypit/results`。+这只是方便人整理内容的推荐,绝不是强制的项目格式。小项目可以把多份 `.svml`、`.svs` 和+`.svrun` 直接平铺在根目录,其他项目也可以采用不同分组。Hypit 只服从 Source import、+`<author source="…">`、CLI 参数和 `get --to` 中明确写出的路径,不要求这些名字,也不会特殊识别+`authors/`、`recipes/`、`runs/`、`assets/` 或 `output/`。每份 Run 选择一份 Author 入口,而这份+Author Source 的闭包可以显式导入多份 Author 或 Recipe Source。受管理的 Result 仓库与它们分开,+零配置时仍位于 `.hypit/results`。Run Source 与 Runtime Profile 不会悄悄改写视频。创作性的模型选择仍然留在 Author Source,或它显式导入的包里。@@ -186,6 +201,9 @@ hypit paths`runtime use` 只写入 `.hypit/runtime`,不会启动 Worker、创建 Runtime 数据或修改已安装包。Profile 结构和完整边界见 [Runtime](../guide/runtime.md)。+CLI 必须先确定项目:显式 `--workspace` 直接给出边界;否则使用当前目录向上的最近+`package.json`,普通创作目录没有该文件时就以当前目录为边界。随后只读取这个项目自己的+`.hypit/runtime`。它不会按约定文件名猜 Profile,也不会从父目录继承另一个项目的选择。## 配置所选凭据`check` 与 `plan` 不会请求在线 Provider。没有所选 Runtime 的 `plan` 只看图,不需要部署@@ -249,8 +267,8 @@ hypit runtime use hypit.runtime.jsonhypit plan build.svrun```-Workspace 依次取显式 `--workspace`、所选 `.hypit/runtime` 所在项目和入口 Source 目录。-Runtime Profile 无权改变这条源码边界。`--package-root` 只定位已经安装的+Workspace 在 Runtime Profile 之前确定;显式 `--workspace` 可以覆盖它,入口 Source 路径和+Runtime 选择都无权改变这条源码边界。`--package-root` 只定位已经安装的`node_modules`;`--asset-root` 只额外授权读取素材字节。外部项目通常应提交如下 `.gitignore`:@@ -320,9 +338,10 @@ Runtime 后只预检这次计划真正需要的 Endpoint、凭据和外部程序`plan` 可以完全不带 Runtime;执行过 `hypit runtime use` 后,`plan` 和 `build` 都不必再写`--runtime`。`build` 必须能找到所选或显式 Profile。-提交前用 `runtime up` 安装所选上游依赖、准备 Managed Program 并启动 Worker。`build` 只重跑-便宜的只读预检;任何依赖未就绪都会在提交前失败,绝不在 Build 中安装或启动它。`runtime-status` 用于观察,`programs up|status|down` 只管理外部程序。+选择或改变部署后,用 `runtime up` 安装所选上游依赖、准备 Managed Program 并启动 Worker。+`build` 只重跑便宜的只读预检;任何依赖或 Program 未就绪都会在提交前失败,绝不在 Build+中准备它们。若部署已经准备完毕而只有 Worker 停止,`build` 会在耐久提交前启动该 Worker。+`runtime status` 用于观察,`programs up|status|down` 只管理外部程序。### 4. 提交 Build