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: teach the installed distribution lifecycle

kashorin193c9bbc3a13
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 64524e15..becc5bba 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -11,9 +11,9 @@ that reference names required child references, read those completely in the sta
Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, and
`hypit.runtime.json` Runtime Profile as separate languages and responsibilities.
-Every route runs against a Hypit checkout. `references/environment.md` finds one, clones it when this
-machine has none, and names the directory every path in these files is relative to. Read it before
-the first command of any route.
+Every route uses the machine-wide Hypit Distribution and an independent author project.
+`references/environment.md` establishes that boundary and installs the Distribution only when the
+`hypit` command is genuinely absent. Read it before the first command of any route.
## Route
@@ -51,4 +51,5 @@ the first command of any route.
subset here is how it goes stale.
Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of
-commits. Repository docs and package-owned declarations remain authoritative.
+commits. Installed package declarations and published docs remain authoritative; repository
+maintenance instructions apply only to contributors who deliberately cloned the repository.
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.md
index 9b82242f..a1c29c4e 100644
--- a/.agents/skills/hypit/references/authoring.md
+++ b/.agents/skills/hypit/references/authoring.md
@@ -1,22 +1,22 @@
# Hypit source authoring
-Read `quickstart.md`, then the authoritative page it selects under `docs/quickstart/`.
+Read `quickstart.md`, then the authoritative published page it selects.
Keep Author Source, Recipe Source and Run Source complete and internally consistent rather than
assembling independent per-shot source fragments.
Before writing an element, read the owning package README and inspect what its Surface actually
declares — `vocabulary.md` names the command and decides which package owns an element in the first
-place. For `@hypit/<name>@1`, the repository README is `packages/<name>/README.md`. Never invent a
+place. For `@hypit/<name>@1`, inspect its installed declaration and README with the vocabulary tool.
+Never invent a
component, attribute, child, port, Recipe property or literal value. Do not infer one package's
syntax from a neighboring package.
Install dependencies after package selections change. Validate with the existing commands:
```bash
-pnpm check
-pnpm hypit check path/to/main.svml
-pnpm hypit check path/to/recipes.svs
-pnpm hypit check path/to/build.svrun
+hypit check path/to/main.svml
+hypit check path/to/recipes.svs
+hypit check path/to/build.svrun
```
Check all of them, not only the Author Source: a Recipe the Author Source references and a Target the
diff --git a/.agents/skills/hypit/references/credentials.md b/.agents/skills/hypit/references/credentials.md
index 61c2c496..40d6dbab 100644
--- a/.agents/skills/hypit/references/credentials.md
+++ b/.agents/skills/hypit/references/credentials.md
@@ -1,7 +1,8 @@
# API keys and credentials
-`check` and `plan` do not need live keys. Before paid/external `build`, configure only variables used
-by the selected Runtime Profile:
+`check` and graph-only `plan` do not need live keys. A `plan` with a selected Runtime does not contact
+Providers, but its cheap preflight requires the demanded credential references to be present. Before
+paid/external `build`, configure only variables used by the selected Runtime Profile:
| Variable | Provider/use |
|---|---|
@@ -76,6 +77,7 @@ none, `status --watch` reports the Worker's state and tells you to start it.
An Endpoint whose Runtime Profile points at the read-only `env` CredentialStore must be configured
by setting its exact environment variable. `hypit auth login` deliberately refuses to prompt in
-that case. For an interactive workstation, select the writable macOS Keychain CredentialStore in
-the Runtime Profile; after `runtime use`, `hypit auth login <endpoint>` can store the secret.
-This is an explicit deployment choice, not a Provider-specific CLI branch.
+that case. For an interactive workstation, select the writable `os` CredentialStore in the Runtime
+Profile; after `runtime use`, `hypit auth login <endpoint>` stores the secret in macOS Keychain or
+Windows Credential Locker. The same `{ "store": "os", "key": "…" }` reference works on both
+supported systems. This is an explicit deployment choice, not a Provider-specific CLI branch.
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index 279a101a..dd996e11 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -1,90 +1,134 @@
# Cross-platform environment
-## Where you are
+## Three independent places
-Every route runs against a Hypit checkout: the `hypit` binary loads the repository's own sources and
-every `@hypit/…` package is unpublished, so the checkout is what supplies both. Find it before the
-first command of any route, from this skill's own directory — the one holding the `SKILL.md` you are
-reading:
+Hypit has three different lifetimes. Never collapse them into one directory.
-```text
-node scripts/locate-repository.mjs
-```
+- The **skill** is agent guidance. Install it globally once so later sessions and unrelated projects
+ can discover the same copy.
+- The **Distribution** is the globally installed `hypit` npm package. It owns the CLI, Studio,
+ official packages and packaged Python service source.
+- The **project** is the author's directory. It owns Sources, assets, project-local packages,
+ `hypit.runtime.json`, `.hypit/` Build state and output files.
+
+An ordinary user does not clone the repository and does not run pnpm, Corepack, `npm link`, or a
+service's `uv sync` by hand. A clone is only a contributor checkout.
+
+## Install once, reuse in every session
-It prints the checkout, and clones one into the home directory when this machine has none:
+The skill must be global; the skills CLI's default is project-local:
```text
-repository /Users/you/hypit
-source cwd
-installed yes
+npx skills add hypit-ai/hypit --global
```
-`source` says where that path came from: `cwd` for a working directory already inside a checkout,
-`skill` for a skill installed inside one, `home` for the clone it keeps, `cloned` when it made that
-clone just now, `env` for a `HYPIT_REPOSITORY` the author set. `installed no` means the workspace
-install below still has to run there.
+Check the program before installing it:
-Every repository path written in these files — `.agents/skills/hypit/scripts/…`, `packages/…`,
-`docs/…`, `examples/…` — is relative to the printed `repository` and to nothing else. That includes
-the other scripts: run the checkout's copies. `preview-check.mjs` reaches Studio's sources through
-its own position in the checkout, so that copy is the one that resolves them.
+```text
+hypit paths --json
+```
-Repository maintenance commands still run from the printed checkout because they consume its own
-dependencies. Authoring commands run from the external project. The `hypit` and `hypit-studio`
-launchers retain that project as the workspace/package root and use the printed checkout only as the
-read-only Distribution for official `@hypit/*` packages. The reference-video inspection tools read
-the installed Distribution vocabulary, so invoke them from the checkout as their reference pages
-show rather than moving the project there.
+Only when the command is missing, install the Distribution once:
-## Requirements
+```text
+npm install --global hypit
+```
-Node.js 22+, pnpm 10.33.x via Corepack, Python only for the local services — 3.10–3.13 for WhisperX
-and 3.13 for OpenCV, which `uv python install 3.13` satisfies for both — `uv` for locked Python
-environments, and `ffmpeg`/`ffprobe` for local media.
+Do not replace this with `npx hypit`, and do not reinstall it for a new project or a new agent
+session. `hypit paths --json` reports the current project boundary, project state, machine Program
+Home, machine npm package home and installed Distribution. Those paths are facts; no repository
+locator or environment lock is involved.
-macOS/Linux or Windows PowerShell:
+Updates are an explicit package-manager operation, never an automatic mutation during authoring:
```text
-node .agents/skills/hypit/scripts/check-environment.mjs
+npm outdated --global hypit
+npm update --global hypit
+npx skills update --global
```
-If the probe reports `corepack missing` (some newer Node.js distributions do not bundle it), install
-a compatible release from either shell:
+Use `hypit --version` to report the installed Distribution. Check npm only when the user asks about
+updates or during deliberate environment maintenance; do not add a registry request to every route.
+
+After updating Hypit, stop an idle Runtime Worker before the next Build so the next process loads the
+new Distribution. Existing project Sources and accepted Build records remain in the project.
+
+## Supported hosts and prerequisites
+
+The supported desktop baseline is:
+
+- macOS 13 or newer;
+- Windows 10 or 11, x64;
+- Node.js 22 or newer.
+
+Windows XP is not a supported target: Node.js 22, current Python and the Windows Credential Locker do
+not run there. Do not claim compatibility that the platform dependencies cannot provide.
+
+Run this skill-owned probe from the installed skill directory when diagnosing a machine:
```text
-npm install --global [email protected]
+node scripts/check-environment.mjs
```
-Then install and validate the workspace, which is what `installed no` asks for:
+`hypit` and Node are required. `ffmpeg` and `ffprobe` are required by local media and preview paths.
+`uv` is required only when the selected Runtime Profile uses a managed Python program such as
+WhisperX or OpenCV. For both services, install the interpreter once:
```text
-corepack enable
-corepack prepare [email protected] --activate
-pnpm install --frozen-lockfile
-npm link
-pnpm check
-pnpm test
+uv python install 3.13
```
-`npm link` exposes both `hypit` and `hypit-studio`; it links the replaceable tool checkout, never an
-author project into the checkout.
-
-For managed local programs:
+Then let the Runtime own installation and reuse:
```text
-uv python install 3.13
-uv sync --project services/whisperx --frozen
-uv sync --project services/image-opencv --frozen
-uv run --project services/whisperx --frozen hypit-whisperx-prepare
hypit runtime use hypit.runtime.json
hypit doctor
hypit runtime up
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 `runtime.md` for the Build lifecycle.
+`runtime up` probes each selected program. It creates that program's environment only when absent or
+unhealthy, then reuses it across projects and sessions. It never runs `uv sync` merely because a new
+project or Runtime Worker started.
+
+Upstream npm dependencies follow the same lifetime. The Distribution ships first-party Model,
+Provider, component and Studio code, but not every Fontsource family, AWS SDK, HyperFrames browser
+package or optional observer SDK. `runtime up` prepares only dependencies declared by the selected
+Runtime adapters. An author package reports an exact command when its own optional dependency is
+missing:
+
+```text
+hypit packages install @fontsource-variable/[email protected]
+hypit packages status @fontsource-variable/[email protected]
+```
+
+These commands use npm's ordinary `package.json` in the machine package home with no Hypit lock,
+receipt, digest inventory or project-local copy.
+
+## Machine Program Home
+
+Managed programs are machine-level installations, separate from both Distribution and project:
+
+- macOS: `~/Library/Application Support/Hypit/programs/`
+- Windows: `%LOCALAPPDATA%\Hypit\programs\`
+
+WhisperX, for example, lives under `programs/whisperx/`; OpenCV under
+`programs/image-opencv/`. Service process records and logs live with the program. Project Build and
+Worker state remains under `<project>/.hypit/`.
+
+This split is why opening a second project cannot install WhisperX again, and why updating the npm
+Distribution does not overwrite a Python environment or a user's project-local component.
+
+The sibling machine npm package home is:
+
+- macOS: `~/Library/Application Support/Hypit/packages/`
+- Windows: `%LOCALAPPDATA%\Hypit\packages\`
+
+The package set is reused by later sessions and unrelated projects. When a Distribution update
+changes an exact adapter dependency, the next explicit `runtime up` lets npm update that package.
+
+## Contributor checkout
-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.
+Only someone changing Hypit itself clones the repository. In that checkout, 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.
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index d143a15f..6b752b0c 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -21,10 +21,10 @@ package that draws one font, and the loop cannot repair what the package cannot
## Write `package.json` and the activation first
-Write those two before any implementation, run `pnpm install` once, and only then start on the
-vocabulary. They are short and almost the same in every package, and leaving them until the end means
-discovering at the end that nothing is linked — a failure that looks like broken code and is not.
-Everything after them is specific to this component and cannot be copied from anywhere.
+Write those two before any implementation. If the package has third-party npm dependencies, use the
+project's package manager once; otherwise no install step is needed. Leaving activation until the end
+means discovering at the end that nothing is selected — a failure that looks like broken code and is
+not. Everything after them is specific to this component and cannot be copied from anywhere.
## Required reading
@@ -36,13 +36,14 @@ rules here are the contract, the closest package is only a shape to learn from.
Then read:
-1. `docs/guide/component-anatomy.md` — the roles every component package fills, and how to find each
+1. `https://narratage.hypit.ai/guide/component-anatomy` — the roles every component package fills, and how to find each
one in an existing package. Read this first; it is what the rest is measured against.
-2. `docs/guide/author-packages.md`
-3. `docs/guide/packages.md` and `docs/guide/conventions.md`
-4. `packages/component-kit/README.md`
+2. `https://narratage.hypit.ai/guide/author-packages`
+3. `https://narratage.hypit.ai/guide/packages` and `https://narratage.hypit.ai/guide/conventions`
+4. the installed `@hypit/component-kit` README
-Then open the closest existing package and read **the roles you are about to write**, not the package
+Use `hypit paths --json` to locate the installed Distribution. Then open the closest existing
+package there and read **the roles you are about to write**, not the package
end to end. Anatomy names them; find them by what they export, since the filenames differ — `ranking`
calls two of them `schedule.ts` and `render.ts`, `media-track` calls them `program.ts` and `lower.ts`,
`comment-sticker` calls them `program.ts` and `author.ts`.
@@ -77,7 +78,7 @@ notice it drifted. That is acceptable for a project-local package, which is part
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 project is never the Hypit checkout. Do not move a local package into an official package
+The project is never the Hypit Distribution. Do not move a local package into an official package
automatically. 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,
@@ -183,7 +184,7 @@ tool Distribution. The `@hypit/*` namespace is reserved for that active Distribu
its own npm scope and cannot shadow official ABI packages with a same-named dependency. A project
does not join Hypit's workspace and needs no npm link merely to expose
one of its own packages. Use the project's own package manager only when its package genuinely adds
-third-party npm dependencies. Do not modify the Hypit checkout, hide packages under `.hypit/` or
+third-party npm dependencies. Do not modify the Hypit Distribution, hide packages under `.hypit/` or
invent another loader.
Repair in this order:
@@ -195,13 +196,12 @@ Repair in this order:
5. implementation behavior;
6. source usage.
-Use only existing checks:
+Use the installed checks:
```bash
-pnpm check
-pnpm hypit check path/to/main.svml
-pnpm hypit check path/to/recipes.svs
-pnpm hypit check path/to/build.svrun
+hypit check path/to/main.svml
+hypit check path/to/recipes.svs
+hypit check path/to/build.svrun
```
A package that cannot be *wired* is not done. `hypit check` proves the Source is legal, and nothing
@@ -210,8 +210,7 @@ the preview check and repair until it passes — a graph failure is not a differ
work that is not finished, and it is not bounded by the loop's attempt ceiling:
```bash
-# from the repository root: tsx is the repository's dependency
-node --import tsx .agents/skills/hypit/scripts/preview-check.mjs path/to/build.svrun
+hypit-preview-check path/to/build.svrun
```
It takes the Run Source, not the `.svml`. A pass here means the graph reaches a Film and a semantic
diff --git a/.agents/skills/hypit/references/original-authoring/index.md b/.agents/skills/hypit/references/original-authoring/index.md
index ec020560..0dcc8db1 100644
--- a/.agents/skills/hypit/references/original-authoring/index.md
+++ b/.agents/skills/hypit/references/original-authoring/index.md
@@ -34,7 +34,7 @@ Everything else this route needs is discoverable:
- **Where you are, and what is installed.** `../environment.md`.
- **Credentials.** `../credentials.md` lists which variables each Provider needs.
-- **Where the project goes.** Its own directory outside the tool checkout, normally a sibling or
+- **Where the project goes.** Its own directory outside the installed Distribution, normally
`<home>/<name>/`, named after the video. `../runtime.md` defines the hard boundary.
## Before deciding anything
diff --git a/.agents/skills/hypit/references/playbooks/index.md b/.agents/skills/hypit/references/playbooks/index.md
index 0a6192c8..f1af0879 100644
--- a/.agents/skills/hypit/references/playbooks/index.md
+++ b/.agents/skills/hypit/references/playbooks/index.md
@@ -13,7 +13,7 @@ needed for that craft or format.
3. Read the selected format file and only the additional craft files **its own footer** names.
That footer is the complete list; this index does not repeat it, and a footer that is wrong is
fixed in the footer.
-4. Read `packages/<name>/README.md` for every package whose elements you write, and the relevant
+4. Read the installed `packages/<name>/README.md` for every package whose elements you write, and the relevant
authoritative Quickstart page for the model behind them.
No document a whole job needs may be reachable only through a conditional file. Craft and format
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
index f2e897c4..35086a51 100644
--- a/.agents/skills/hypit/references/preview.md
+++ b/.agents/skills/hypit/references/preview.md
@@ -12,8 +12,7 @@ a new package with a bad schedule, a target that is not an output, a Film with n
composition. Find that now, not on the author's screen:
```bash
-# invoke the script from the tool checkout; the Run may live anywhere
-node --import tsx .agents/skills/hypit/scripts/preview-check.mjs /path/to/project/build.svrun
+hypit-preview-check /path/to/project/build.svrun
```
It takes the Run Source, not the Author SVML — Studio's unit of work is the Run, and it reads the
@@ -74,15 +73,8 @@ own directory, so pass it when the Run's relative Sources resolve against a diff
Studio opens a Run whose material is satisfied. When a projection is missing it names the issue and
stops, so a Run that opens is a Run whose Tracks all resolved.
-One Run in the repository is satisfied already, so Studio can be seen without spending anything:
-
-```bash
-cd /path/to/hypit
-hypit-studio --run examples/all-components-preview/studio.svrun --workspace .
-```
-
-It supplies its own Semantic Takes and Script-owned CaptionDocument from committed fixtures. Every other Run under
-`examples/` still names shots a Provider has to make, or footage that is not committed.
+Contributor fixtures may provide a satisfied demonstration Run, but an ordinary installed
+Distribution does not use its package directory as an author workspace.
## A timeline block is not the authored Selection
@@ -97,9 +89,9 @@ Studio keeps three stages of an item's time apart, and reading one for another m
one outer window alongside its reveal phases.
A projection line connects a source to its realized window, and the projection view is read-only.
-`docs/guide/studio-temporal-windows.md` is authoritative for what each stage carries.
+`https://narratage.hypit.ai/guide/studio-temporal-windows` is authoritative for what each stage carries.
Studio is a browser preview **for a person to look at**. It is not a source of images for an
automated comparison — that is what the local still render above is for.
-`docs/quickstart/preview.md` is authoritative.
+`https://narratage.hypit.ai/quickstart/preview` is authoritative.
diff --git a/.agents/skills/hypit/references/quickstart.md b/.agents/skills/hypit/references/quickstart.md
index 16db5b2a..0596c9ec 100644
--- a/.agents/skills/hypit/references/quickstart.md
+++ b/.agents/skills/hypit/references/quickstart.md
@@ -1,17 +1,17 @@
# Quickstart map
-The repository docs are authoritative:
+Published docs and installed package declarations are authoritative:
| Need | Read |
|---|---|
-| Script semantics | `docs/quickstart/script.md` |
-| SVS Recipes | `docs/quickstart/styles.md` |
-| Media and Seedance | `docs/quickstart/generation.md` |
-| Reusable Seedance Prompt Kits | `packages/seedance-kits/README.md` and the selected file under `packages/seedance-kits/kits/` |
-| Normalization, alignment and SemanticTrack assembly | `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 `runtime.md` |
+| Script semantics | `https://narratage.hypit.ai/quickstart/script` |
+| SVS Recipes | `https://narratage.hypit.ai/quickstart/styles` |
+| Media and Seedance | `https://narratage.hypit.ai/quickstart/generation` |
+| Reusable Seedance Prompt Kits | the installed `@hypit/seedance-kits` README and selected Kit |
+| Normalization, alignment and SemanticTrack assembly | `https://narratage.hypit.ai/quickstart/timing` |
+| Caption, Media, Text, Audio Tracks | `https://narratage.hypit.ai/quickstart/tracks` and installed package READMEs |
+| Film and rendering | `https://narratage.hypit.ai/quickstart/composition` |
+| Run Source, durable Runtime, Builds, retrieval, and reuse | `https://narratage.hypit.ai/quickstart/run` and `runtime.md` |
Canonical path:
@@ -29,6 +29,6 @@ the SemanticTrack is the frame domain every `start`/`end` window resolves into
`<track>.semantic` through `.svrun` `build-record` and `satisfy`, keep `<track>.visual` and
`<track>.audio` out of the Film so the alignment goes unreached, and omit the Caption components.
-For execution, preserve the full lifecycle: diagnose the Profile, start or reuse the durable
-Runtime, inspect the frozen plan, submit a named Build, inspect its accepted Records, retrieve
-Artifacts, and declare any reuse explicitly in a new Run Source.
+For execution, preserve the full lifecycle: select the Profile, inspect the frozen plan, run
+`runtime up` when preflight is not ready, submit a fresh automatically identified Build, inspect its
+accepted Records, retrieve Artifacts, and declare any reuse explicitly in a new Run Source.
diff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.md
index 3d1fed3a..4f89e900 100644
--- a/.agents/skills/hypit/references/reconstruction/index.md
+++ b/.agents/skills/hypit/references/reconstruction/index.md
@@ -69,10 +69,10 @@ is asking the author to do your job. Everything this route needs beyond the vide
discoverable:
- **Where you are, and what is installed.** `../environment.md`.
-- **Where the project goes.** Its own directory outside the tool checkout, normally a sibling or
+- **Where the project goes.** Its own directory outside the installed Distribution, normally
`<home>/<something>-reverse/`, named after the video. `../runtime.md` defines the hard boundary.
Use a directory the author named only if they named one.
-- **Credentials.** The repository keeps them in `.env`; load it as shown below. A variable a Provider
+- **Credentials.** A project may keep them in an uncommitted `.env`; load it as shown below. A variable a Provider
needs and this machine does not hold is named, and the route stops there — with one exception, the
Vertex pair, which selects an observer rather than blocking one. `observers.md` owns that.
diff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.md
index e74ee90b..f8ec751c 100644
--- a/.agents/skills/hypit/references/reconstruction/workflow.md
+++ b/.agents/skills/hypit/references/reconstruction/workflow.md
@@ -59,8 +59,8 @@ by hand and do not ask a model to transcribe: the transcript is already there.
`transcript` reports `status`, `transcript_ref` and `word_count`. Read the words from
`transcript_ref`, a JSON file of passages, each with its own `words` array of
`{ text, start_seconds, end_seconds, score }`. A machine with no WhisperX service running reports
-`status: "unavailable"` with a `reason` and prepares everything else; start the service with
-`uv run --project services/whisperx --frozen hypit-whisperx-service` and prepare again.
+`status: "unavailable"` with a `reason` and prepares everything else; run `hypit runtime up` for the
+project's selected Profile and prepare again.
`../environment.md` covers diagnosing that service and the rest of the local toolchain when starting
it is not enough.
diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.md
index 59986bb2..7d5ef280 100644
--- a/.agents/skills/hypit/references/runtime.md
+++ b/.agents/skills/hypit/references/runtime.md
@@ -1,6 +1,6 @@
# Durable Runtime and Build lifecycle
-Read `docs/quickstart/run.md` as the authority for Run Source, Target, Candidate, Runtime Profile,
+Read `https://narratage.hypit.ai/quickstart/run` as the authority for Run Source, Target, Candidate, Runtime Profile,
Build, retrieval, and reuse syntax. Use this file as the operational checklist.
## Author the Runtime Profile
@@ -26,6 +26,9 @@ hypit runtime use hypit.runtime.json
hypit plan build.svrun
+# Required once after changing Runtime packages, or whenever preflight reports not-ready state.
+hypit runtime up
+
hypit build build.svrun --follow
hypit inspect <build-id>
@@ -33,9 +36,15 @@ hypit get <build-id> \
--name final.video --to output/final.mp4
```
-Install dependencies after package selection changes. Use `check` during authoring and `doctor`
-or `runtime status` when diagnosing the deployment. `build` already ensures the detached Worker
-and demanded Managed Programs are available.
+Use `check` during authoring. `plan` works without a Runtime as a graph-only operation; with the
+project's selected Runtime it performs a cheap, read-only preflight over only unsatisfied Needs and
+returns non-zero when that slice is not ready. It never installs, starts or contacts a remote Store.
+
+After Runtime package selection changes, run `runtime up`: this is the explicit provisioning
+boundary for machine npm dependencies, Managed Programs and the detached Worker. Use `doctor` for
+an active full-profile diagnosis and `runtime status` to observe the deployment. `build` repeats the
+cheap preflight and fails before durable submission when deployment is not ready; it never installs
+or starts a Managed Program.
Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from claiming more Builds.
External programs are intentionally independent; stop them only with `programs down`. Durable
@@ -43,9 +52,10 @@ Builds remain archived and neither command cancels remote Provider work.
## Preserve durable semantics
-- `runtime up` starts or reuses the detached Worker plus declared external programs. A direct
- `build` durably submits first, then ensures a Worker containing every queued Build's implementation
- packages is running. A Worker skips work whose packages it has not loaded.
+- `runtime up` installs or reuses only the selected upstream npm packages, then starts or reuses the
+ declared external programs and detached Worker. A direct `build` does no provisioning: after a
+ clean preflight it submits durably, then ensures the Worker is running. A Worker skips work whose
+ implementation packages it has not loaded.
- `programs up/status/down` manages external programs only. Do not use it as the normal Build
bootstrap because it does not own the Worker lifecycle.
- A Build continues after durable submission. `--follow` only observes progress; interrupting the
@@ -59,14 +69,14 @@ Builds remain archived and neither command cancels remote Provider work.
- There is no implicit cache or Pin state. Reuse Records through a new `.svrun` containing
`build-record` and `satisfy`; the Candidate supplies the exact nominal Type required by the
current Logical Output.
-- **A running Worker holds the package code it loaded.** Edit a package — yours or an installed one —
- and the Worker that is already up keeps executing the version it started with, so the next Build
+- **A running Worker holds the package code it loaded.** Edit a project package or update the
+ Distribution and the Worker that is already up keeps executing the version it started with, so
+ the next Build
fails exactly as the last one did. Stop it before resubmitting; the next `build` starts a fresh one
that loads the edit:
```bash
- ps -eo pid,command | grep "hypit.mjs _worker" | grep <project>/hypit.runtime.json
- kill <pid>
+ hypit runtime down
```
Read an identical repeat failure as this until you have ruled it out. Reasoning about why a correct
@@ -80,24 +90,23 @@ Builds remain archived and neither command cancels remote Provider work.
a change that costs nothing on an idle Runtime costs the whole Build on a busy one. Nothing is lost
by waiting: accepted Records are durable, and the requests still in flight are the expensive ones.
-## Keep the tool checkout and every project physically separate
+## Keep the Distribution and every project physically separate
-The printed Hypit repository is a replaceable tool checkout. Never create an authored project,
-project-local package, generated asset or Build output inside it. A project is a sibling or otherwise
-external directory such as `<home>/<name>/`, holding its Sources, assets and `packages/` directory in
-its own Git/workspace boundary. `examples/` is only the published fixture set: read it for the nearest
-Runtime Profile and source shape, but never turn an example or a hidden checkout directory into the
-author's project.
+The Distribution reported by `hypit paths --json` is package-manager-owned and replaceable. Never
+create an authored project, project-local package, generated asset or Build output inside it. A
+project is any independent directory such as `<home>/<name>/`, holding its Sources, assets and
+`packages/` directory in its own Git/workspace boundary. Published examples are read-only reference
+material, never a place to turn into the author's project.
Studio and the CLI resolve explicit project packages from the project root, then fall back to the
read-only Hypit Distribution. The `@hypit/*` namespace is reserved for the active Distribution and
is resolved there first; project packages use their own scope. This bridge is Host configuration;
-it does not add the project to Hypit's pnpm workspace or modify either repository's lockfile.
+it does not add the project to Hypit's contributor workspace or modify the Distribution.
Relative Author Sources and assets stay inside the independently resolved Source Workspace.
- `--workspace` explicitly selects the Source Workspace boundary.
- `--package-root` only changes where the Host locates installed packages. It does not widen Source
access.
-- Do not symlink an external project into the repository. The external directory is the intended
+- Do not symlink an external project into the Distribution. The external directory is the intended
workspace, not an escape from one.
diff --git a/.agents/skills/hypit/references/seedance-kits.md b/.agents/skills/hypit/references/seedance-kits.md
index ea26e6f7..42ea9ce6 100644
--- a/.agents/skills/hypit/references/seedance-kits.md
+++ b/.agents/skills/hypit/references/seedance-kits.md
@@ -1,6 +1,7 @@
# Seedance Prompt Kits
-Hypit ships seven English Text Templates under `packages/seedance-kits/kits/`. Each Kit owns the
+Hypit ships seven English Text Templates in the installed Distribution under
+`packages/seedance-kits/kits/`. Use `hypit paths --json` to locate that Distribution. Each Kit owns the
repeatable prompt contract; the project Recipe selects its stable directing axes, and explicit Text
slots carry shot-specific dialogue or action.
@@ -16,7 +17,7 @@ slots carry shot-specific dialogue or action.
## Required procedure
-1. Read `packages/seedance-kits/README.md` and the selected Kit file for exact axes and defaults.
+1. Read the installed `packages/seedance-kits/README.md` and selected Kit file for exact axes and defaults.
2. Copy only that `.svs` file into the video project's `./kits/` directory; import the vendored copy.
3. Put stable axis choices in `recipes.svs` as a named Recipe.
4. Import `@hypit/text@1` as `copy`. Use `copy:Render` with the Kit Template and Recipe, then
diff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.md
index 267ce2a8..fb9c0946 100644
--- a/.agents/skills/hypit/references/vocabulary.md
+++ b/.agents/skills/hypit/references/vocabulary.md
@@ -25,9 +25,9 @@ deciding anything is missing.
hypit-reference-video-tools list_svml_packages
```
-It takes no arguments, needs no reference and no credentials — the binary is named for reconstruction,
-this command is not. It does read `node_modules/@hypit` **relative to the working directory** and
-refuses when that directory is empty, so run it from the repository root.
+It takes no arguments, needs no reference and no credentials — the binary is named for
+reconstruction, this command is not. It reads official vocabulary from the installed Distribution
+and project packages from the current project, so run it from the project directory.
Run it before concluding that a capability is missing. Do not run it to confirm something you already
know: a vocabulary gap is proven by inspecting the candidates and finding none that fits, not by
diff --git a/README.md b/README.md
index 8725c156..612227cd 100644
--- a/README.md
+++ b/README.md
@@ -43,15 +43,21 @@ Hypit gives AI agents (Claude Code, Codex...) a language and system to create vi
**To be clear:** cloning a video is the fastest way in, not the only one. You can start from our templates, or just describe the video you want and your agent writes the workflow from scratch. Generation models are optional too: a workflow can compile captions, motion graphics and code-rendered visuals into a finished video without calling a single model, so a video can cost exactly $0.
-## Install the Hypit skill
+## Install once
```bash
-npx skills add hypit-ai/hypit
+npm install --global hypit
+npx skills add hypit-ai/hypit --global
```
+The npm package is the Hypit Distribution: CLI, Studio, official components and managed-service
+source. The global skill is discoverable by later agent sessions in any project. Neither command
+clones an authoring repository into your project.
+
## Use the Hypit skill
-The `/hypit` skill is available to coding agents. Your agent fetches the repository it needs on first use. Ask it to set up the environment and create videos for you:
+The `/hypit` skill is available to coding agents. Start a session in any empty or existing project
+directory and ask it to create videos for you:
```text
/hypit Clone this viral video, show me a preview, and guide me through producing variants.
@@ -65,6 +71,17 @@ Or start without a reference video:
Your agent can check the environment, request only the credentials the video needs, preview the result, and build it.
+Projects, generated files and project-local components stay in that project directory. Machine
+programs such as WhisperX are installed on demand into the Hypit Program Home and reused by every
+project. Upstream npm packages such as one Fontsource family or HyperFrames are likewise installed
+only when selected, into a separate shared machine package home. Opening a new session does not
+install either again. Check with `hypit --version` and
+`npm outdated --global hypit`; update deliberately with `npm update --global hypit` and
+`npx skills update --global`.
+
+The supported desktop baseline is macOS 13+ or Windows 10/11 x64 with Node.js 22+. Repository cloning,
+pnpm and Corepack are contributor-only concerns.
+
## License
Hypit is released under the [Hypit Open Source License](./LICENSE). The videos and other outputs you create belong to you; third-party models and services may have their own terms.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 805f2d1a..c5d02c69 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -43,15 +43,20 @@ Hypit 给 AI Agents (Claude Code、Codex……) 打造了一门做视频的语
**说明一点:** 复刻视频是最快的入口,但不是唯一的入口。你可以直接从我们的模板开始,也可以直接描述你想要的视频,让 Agent 从零写出一份 workflow。生成模型同样不是必需的:字幕、动效、代码渲染的画面,不调用任何模型也能编译成一条成片——一条视频的成本可以是 0 元。
-## 安装 Hypit skill
+## 只安装一次
```bash
-npx skills add hypit-ai/hypit
+npm install --global hypit
+npx skills add hypit-ai/hypit --global
```
+npm 包是 Hypit Distribution,包含 CLI、Studio、官方组件和托管服务源码;全局 skill 能被以后
+任何项目里的 Agent 会话发现。这两个命令都不会把创作仓库克隆进项目目录。
+
## 使用 Hypit skill
-编程 Agent 可以直接使用 `/hypit` skill,首次使用时 Agent 会自行获取所需的仓库。让 Agent 配置环境并为你创建视频:
+编程 Agent 可以直接使用 `/hypit` skill。在任何空目录或现有项目目录里开启会话,让 Agent
+为你创建视频:
```text
/hypit 把这条爆款视频复刻出来,展示预览,并带我批量生成多个变体。
@@ -65,6 +70,15 @@ npx skills add hypit-ai/hypit
Agent 会检查环境,只索取视频实际需要的凭据,展示预览并执行构建。
+项目源码、生成文件和项目私有组件始终留在项目目录里。WhisperX 等机器程序按需安装到
+Hypit Program Home;Fontsource 单个字体、HyperFrames 等上游 npm 包也只在实际选择后安装
+到独立的机器共享目录。两者都会被所有项目复用,新开会话不会再装一遍。用 `hypit --version` 和
+`npm outdated --global hypit` 检查版本,需要更新时显式执行 `npm update --global hypit` 和
+`npx skills update --global`。
+
+桌面支持基线是 macOS 13+ 或 Windows 10/11 x64,以及 Node.js 22+。克隆仓库、pnpm 和
+Corepack 只属于贡献者工作流。
+
## 许可证
Hypit 采用 [Hypit 开源许可证](./LICENSE)。你创作的视频和其他产出归你所有;第三方模型与服务可能另有条款。
diff --git a/docs/guide/packages.md b/docs/guide/packages.md
index 172fc810..4fd6c29a 100644
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@ -5,10 +5,18 @@ description: The seven layers, dependency boundaries, package anatomy and facets
# Package Architecture
-Workspace packages under `packages/` are organized into seven architectural layers. Dependencies are
-declared by each package itself. The root installs the complete source checkout so the Package
-Loader can resolve any explicitly selected package, but TypeScript has no central path alias that can
-hide a package's undeclared import.
+Internal modules under `packages/` are organized into seven architectural layers. Dependencies are
+declared by each module itself. The published `hypit` Distribution includes the complete official
+module tree so the Package Loader can resolve any explicitly selected package, while TypeScript has
+no central path alias that can hide an undeclared import.
+
+The complete official tree is source/code, not an eager download of every upstream dependency.
+The base npm install contains only the launcher dependency. Selected Runtime adapters prepare their
+ordinary npm dependencies in the shared machine package home during explicit `runtime up`; optional
+author assets such as Fontsource families are installed with the exact `hypit packages install`
+command reported by compilation. npm's package manifest remains the authority—Hypit adds no second
+lock, receipt or hash inventory. Project-scoped third-party components and their dependencies remain
+owned by that project's package manager.
## The seven layers
@@ -140,7 +148,7 @@ queues, stores, credentials and process lifecycle; they never define author synt
@hypit/artifact-store-fs filesystem Artifacts
@hypit/artifact-store-s3 S3 Artifacts
@hypit/credential-store-env environment credentials
-@hypit/credential-store-keychain macOS Keychain credentials
+@hypit/credential-store-os macOS Keychain or Windows Credential Locker
```
### Layer 7: Applications
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index 2db8f78d..c43cd3fb 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -171,8 +171,9 @@ const adapter = createRuntimeEndpointAdapterFacet({
```
`hypit runtime up` prepares, starts and probes declared Managed Programs before starting the
-durable Worker. `build` starts only Programs backing capabilities demanded by its plan. Providers
-that call only remote APIs omit `program` entirely.
+durable Worker. `build` only preflights Programs backing capabilities demanded by its plan and
+fails before submission when one is not ready; it never installs or starts one. Providers that call
+only remote APIs omit `program` entirely.
## 6. Install
@@ -196,7 +197,7 @@ explicitly selects its `use` id.
"use": "@hypit/provider-my-service",
"pool": "my-service.account",
"config": {
- "apiKey": { "store": "keychain", "key": "my-service.api-key" },
+ "apiKey": { "store": "os", "key": "my-service.api-key" },
"defaultConcurrency": 2
}
}
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md
index e526d4f7..9c27a8af 100644
--- a/docs/guide/runtime.md
+++ b/docs/guide/runtime.md
@@ -95,8 +95,8 @@ hypit programs up
hypit programs down
```
-Program commands load Endpoint packages only. They do not open SQLite, Artifact Stores or Credential
-Stores.
+`programs up` first prepares the selected Endpoint packages' upstream npm dependencies, then operates
+their declared programs. The commands do not open SQLite, Artifact Stores or Credential Stores.
## Lifecycle
@@ -108,9 +108,13 @@ hypit runtime logs
hypit runtime down
```
-`runtime up` starts the local Worker. `build` submits work; `status`, `queue` and `cancel` observe or
-control it. A terminal Build is not resumed. Reusing an earlier result is an explicit Candidate in a
-new `.svrun`, not hidden Runtime behavior.
+`runtime up` asks npm to prepare the selected adapters' exact upstream packages in the shared
+machine home, prepares declared Managed Programs, then starts the local Worker. `build` performs no
+provisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Worker
+is available. `status`, `queue` and `cancel` observe or control durable work. A terminal Build is not
+resumed. Reusing an earlier result is an explicit Candidate in a new `.svrun`, not hidden Runtime
+behavior.
-Runtime packages are trusted local deployment code. npm or pnpm owns their installed versions; the
-Runtime does not implement another package manager or claim that metadata is a sandbox.
+Runtime packages are trusted local deployment code. npm or pnpm owns their installed versions;
+Hypit only selects exact requirements and invokes npm at the explicit `runtime up`/`packages install`
+boundary. It has no second package lock and does not claim that metadata is a sandbox.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index a0917260..98c3848d 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -18,16 +18,20 @@ Hypit turns that source into a visible execution graph. Before any model or exte
runs, you can check the source, choose a Run, and inspect the exact work it would require. This
page gets you to that first safe plan: it needs no API keys and makes no paid call.
-## Clone the repository
+## Install Hypit
```bash
-git clone https://github.com/hypit-ai/hypit.git
-cd hypit
+npm install --global hypit
+npx skills add hypit-ai/hypit --global
```
+The first command installs the reusable Distribution. The second installs the skill globally so a
+new agent session in another project can find it. Ordinary authoring never requires a repository
+clone.
+
## Use the Hypit skill
-`/hypit` is available from that working directory. Send your agent:
+`/hypit` is available from any project directory. Send your agent:
```text
/hypit Set up my environment, ask for only the API keys required by my Runtime Profile, and guide me through authoring and building my first SVML video.
@@ -36,36 +40,24 @@ cd hypit
It works through the same five steps below, asking you only for what your Runtime Profile actually
needs. Work through them yourself if you would rather not use an agent.
-## 1. Install the source workspace
-
-You need Node.js 22+ and pnpm 10.33.x through Corepack.
-
-```bash
-corepack enable
-pnpm install --frozen-lockfile
-npm link
-```
+## 1. Check the installed Distribution
-If `corepack` is unavailable:
+You need Node.js 22+ on macOS 13+ or Windows 10/11 x64.
```bash
-npm install --global [email protected]
-corepack enable
-corepack prepare [email protected] --activate
-pnpm install --frozen-lockfile
-npm link
+hypit paths --json
```
-`pnpm check` and `pnpm test` are repository-development commands. You do not need to run the full
-suite before using the CLI.
+The result separates the current project, its `.hypit` state, the machine Program Home and the npm
+Distribution. pnpm, Corepack and `npm link` are contributor tools, not user setup.
## 2. Compile the example
-The checked-in example includes a Script, two generated-video requests, speech assembly, WhisperX
+The linked example includes a Script, two generated-video requests, speech assembly, WhisperX
alignment, captions, a media Track, text, Film and final rendering.
```bash
-cd examples/talking-film-graph-check
+cd /path/to/copied-talking-film-graph-check
hypit check main.svml
```
@@ -111,8 +103,8 @@ shots without changing the authored video.
## 4. Start your own project
-Keep project files and generated media outside the Hypit repository. The linked `hypit`
-command works from that independent project directory:
+Keep project files and generated media outside the installed Hypit Distribution. The global
+`hypit` command works from that independent project directory:
```bash
cd /path/to/my-video
@@ -122,8 +114,8 @@ hypit runtime use hypit.runtime.json
hypit plan build.svrun
```
-A project with `package.json` owns its installed capability packages. A plain creative folder needs
-no Node project and uses packages from the linked checkout. Source and exported files remain in the
+A project with `package.json` owns its third-party packages. A plain creative folder needs no Node
+project and uses official packages from the installed Distribution. Source and exported files remain in the
project. Runtime state and Artifacts live under the selected Profile's `dataRoot`.
`runtime use` stores only a local pointer at `.hypit/runtime`. Source imports select author
packages; the Profile independently selects Runtime packages through `use`.
@@ -140,9 +132,10 @@ After reviewing the plan:
hypit build build.svrun --follow
```
-`build` assigns and prints a fresh Build id, stores the Build, ensures its Worker is available, and
-starts only the external programs declared by the selected endpoints. `--follow` is an observer;
-closing it does not stop the Build.
+`build` first repeats the same cheap local preflight, then assigns a fresh Build id, stores the Build
+and ensures its Worker is available. It never installs a package or starts a Managed Program. Run
+`hypit runtime up` explicitly when the selected deployment is not ready. `--follow` is only an
+observer; closing it does not stop the Build.
Use `check` while editing a source. Use `doctor` to diagnose a new or broken deployment. They are
safe, but neither is required as a repetitive pre-Build ceremony.
@@ -171,15 +164,26 @@ Install only what your selected Runtime Profile needs:
| Chromium | managed automatically by local HyperFrames rendering |
| API credentials | selecting remote KIE, Xiaomi or AWS endpoints |
+Upstream npm packages are demand-loaded into the shared machine package home shown by `hypit
+paths`; they are not copied into every project. `runtime up` prepares the exact npm packages required
+by its selected Runtime adapters. When an authored feature needs a package such as one Fontsource
+family, the compiler reports the exact repair command:
+
+```bash
+hypit packages install @fontsource-variable/[email protected]
+```
+
For local Python programs:
```bash
uv python install 3.13
-uv sync --project services/whisperx --frozen
-uv sync --project services/image-opencv --frozen
-uv run --project services/whisperx --frozen hypit-whisperx-prepare
+hypit runtime use hypit.runtime.json
+hypit runtime up
```
+The Runtime creates a missing managed environment in the machine Program Home and reuses it across
+projects and sessions. Do not run a service's `uv sync` from an author project.
+
Run `hypit doctor hypit.runtime.json` after changing a Runtime Profile. It reports missing tools,
credentials and endpoint configuration without executing the graph.
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
index 7070b179..9b51b895 100644
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@ -206,8 +206,8 @@ generic `text:Render` to produce the prompt, then connect that Text and the real
the low-level Seedance Surface.
Copy only the selected Kit `.svs` files into the video project's `./kits/` directory. Import the
-vendored project copy so the Kit bytes remain inside the Source Closure; do not reach back into a
-Hypit repository checkout from project source.
+vendored project copy so the Kit bytes remain inside the Source Closure; do not reach back into the
+installed Hypit Distribution from project source.
Read the
[`@hypit/seedance-kits` guide](https://github.com/hypit-ai/hypit/blob/main/packages/seedance-kits/README.md)
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index ecf9a0c4..821ea855 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -23,8 +23,8 @@ hypit build build.svrun --follow
hypit get <build-id> --name final.video --to output/final.mp4
```
-The Quickstart links the checkout's command once. Every command on this page then works as
-`hypit`, including from a separate video project.
+The Quickstart installs the Distribution once. Every command on this page then works as `hypit`
+from any independent video project.
Only `build` submits work. `plan` is the normal preview. `check` is an editing aid; `doctor` is a
deployment diagnostic. They are safe to run, but not mandatory ceremony before every Build.
@@ -204,9 +204,10 @@ change installed packages. See [Runtime](../guide/runtime.md) for the Profile sc
## Configure selected credentials
-`check` and `plan` do not make live Provider requests and do not need API keys. Before `doctor` or a
-paid/external `build`, configure only the environment variables referenced by the selected Runtime
-Profile:
+`check` and `plan` never make live Provider requests. A graph-only `plan` without a selected Runtime
+needs no deployment credentials; with a selected Runtime, its cheap preflight checks that demanded
+credential references are present. Before `doctor` or a paid/external `build`, configure only the
+variables referenced by the selected Runtime Profile:
| Variable | Provider/use |
|---|---|
@@ -270,9 +271,9 @@ Doctor validates every selected Runtime role, Endpoint configuration, credential
presence and bounded environment probes. It never starts the Worker or performs a paid request.
Doctor is intentionally a **full profile audit**. For the environment required by one Run, use
-`plan`: it checks only capabilities demanded by that finite plan. A valid plan remains a
-successful command even when `preflight.ok` is false; `doctor` or `build` enforces deployment
-readiness.
+`plan`: it checks only capabilities demanded by that finite plan. Missing readiness is returned in
+`preflight` and gives the command a non-zero exit status, while the frozen plan remains available in
+JSON for inspection.
### 3. Check source and inspect the plan
@@ -288,9 +289,14 @@ Review the frozen BuildPlan before spending money. The plan shows every Operatio
Scheduler would issue. With a selected Runtime, it also reports only the relevant Endpoint, credential and
external-program diagnostics. It never starts external work.
-`build` starts or reuses the selected Runtime automatically. Use `runtime up` to prepare it before
-submission and `runtime status` to observe it. `programs up|status|down` is the narrower lifecycle
-view for long lived processes declared by Endpoints.
+`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
+the deployment, while `programs up|status|down` is the narrower lifecycle view for long-lived
+processes declared by Endpoints.
### 4. Submit the Build
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index e1d450bc..20bcc6ae 100644
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@ -5,8 +5,14 @@ description: 七个分层、依赖边界、包的结构与 facet。
# 包架构
-`packages/` 下的工作区包被组织成七个架构分层。每个包自行声明依赖。根工作区会安装完整源码树,让 Package
-Loader 能解析任意被显式选择的包;但 TypeScript 不维护会掩盖漏依赖的中央路径别名。
+`packages/` 下的内部模块被组织成七个架构分层。每个模块自行声明依赖。发布的 `hypit` Distribution
+包含完整官方模块树,让 Package Loader 能解析任意被显式选择的包;但 TypeScript 不维护会掩盖漏依赖的中央路径别名。
+
+这里的完整官方树指首方源码/代码,并不意味着首次安装就下载全部上游依赖。基础 npm 安装只带
+启动器必需依赖;显式 `runtime up` 才会把所选 Runtime Adapter 的普通 npm 依赖准备到机器共享
+目录。Fontsource 等作者侧可选素材由编译器给出精确的 `hypit packages install` 命令。npm 的标准
+`package.json` 是唯一包集合依据;Hypit 不再造第二份 lock、receipt 或哈希库存。项目自己的第三方
+组件及依赖仍由项目包管理器负责。
## 七个分层
@@ -134,7 +140,7 @@ Frontend;不存在一个认识全部语法的中央解析器。
@hypit/artifact-store-fs 文件系统 Artifact
@hypit/artifact-store-s3 S3 Artifact
@hypit/credential-store-env 环境变量凭据
-@hypit/credential-store-keychain macOS Keychain 凭据
+@hypit/credential-store-os macOS 钥匙串或 Windows 凭据锁
```
### Layer 7:Applications
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index 03ceceb3..beba44ab 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -164,10 +164,11 @@ const adapter = createRuntimeEndpointAdapterFacet({
});
```
-`hypit runtime up` 会准备、启动并探测 Managed Program,然后启动耐久 Worker。`build` 只启动
-本次 Plan 所需 Capability 对应的 Program。只调用远程 API 的 Provider 不返回 `program`。
+`hypit runtime up` 会准备、启动并探测 Managed Program,然后启动耐久 Worker。`build` 只预检
+本次 Plan 所需 Capability 对应的 Program;未就绪时在提交前失败,绝不安装或启动它。只调用
+远程 API 的 Provider 不返回 `program`。
-## 6. 注册并锁定
+## 6. 声明依赖
在 Provider 自己的 `package.json` 中声明所有导入包:
@@ -188,7 +189,7 @@ const adapter = createRuntimeEndpointAdapterFacet({
"use": "@hypit/provider-my-service",
"pool": "my-service.account",
"config": {
- "apiKey": { "store": "keychain", "key": "my-service.api-key" },
+ "apiKey": { "store": "os", "key": "my-service.api-key" },
"defaultConcurrency": 2
}
}
diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.md
index fac680f1..b5760677 100644
--- a/docs/zh/guide/runtime.md
+++ b/docs/zh/guide/runtime.md
@@ -92,7 +92,8 @@ hypit programs up
hypit programs down
```
-这些命令只加载 Endpoint 包,不打开 SQLite、Artifact Store 或 Credential Store。
+`programs up` 会先准备所选 Endpoint 包的上游 npm 依赖,再操作其声明的程序。这些命令不打开
+SQLite、Artifact Store 或 Credential Store。
## 生命周期
@@ -104,8 +105,10 @@ hypit runtime logs
hypit runtime down
```
-`runtime up` 启动本地 Worker。`build` 提交任务,`status`、`queue`、`cancel` 用来观察和控制。
-终态 Build 不恢复;复用以前的结果必须在新的 `.svrun` 中显式写 Candidate。
+`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备 Managed
+Program 并启动本地 Worker。`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保
+Worker 可用。`status`、`queue`、`cancel` 用来观察和控制耐久工作。终态 Build 不恢复;复用
+以前的结果必须在新的 `.svrun` 中显式写 Candidate。
-Runtime 包是本地可信部署代码,其安装版本由 npm 或 pnpm 管理。Runtime 不再实现另一套包管理器,
-也不会把元数据冒充成沙箱。
+Runtime 包是本地可信部署代码,其安装版本由 npm 或 pnpm 管理。Hypit 只在显式 `runtime up` /
+`packages install` 边界选择精确依赖并调用 npm,不维护第二份包锁,也不会把元数据冒充成沙箱。
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index 14774f12..ee69eea5 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -17,16 +17,19 @@ Hypit 把这份源码编译成一张可见的执行图。在任何模型或外
选择一次 Run,并看清这次 Build 究竟需要执行什么。本页先带你得到第一份安全的 Plan:不需要 API Key,
也不会产生任何付费请求。
-## 克隆仓库
+## 安装 Hypit
```bash
-git clone https://github.com/hypit-ai/hypit.git
-cd hypit
+npm install --global hypit
+npx skills add hypit-ai/hypit --global
```
+第一条命令安装可复用的 Distribution;第二条把 skill 全局安装,使以后任何项目里的新 Agent
+会话都能找到它。普通创作不需要克隆仓库。
+
## 使用 Hypit skill
-在这个工作目录下就可以直接使用 `/hypit`。发送给你的 Agent:
+在任何项目目录下都可以直接使用 `/hypit`。发送给你的 Agent:
```text
/hypit 配置我的环境,只向我索取当前 Runtime Profile 实际需要的 API key,然后带我完成第一支 SVML 视频的创作与 Build。
@@ -34,36 +37,24 @@ cd hypit
它会走下面同样的五个步骤,并且只向你索取 Runtime Profile 实际需要的东西。不想用 Agent 的话,也可以自己依次完成这五步。
-## 1. 安装源码工作区
+## 1. 检查已安装的 Distribution
-需要 Node.js 22+,并通过 Corepack 使用 pnpm 10.33.x。
+需要 Node.js 22+,桌面系统为 macOS 13+ 或 Windows 10/11 x64。
```bash
-corepack enable
-pnpm install --frozen-lockfile
-npm link
+hypit paths --json
```
-如果系统没有 `corepack`:
-
-```bash
-npm install --global [email protected]
-corepack enable
-corepack prepare [email protected] --activate
-pnpm install --frozen-lockfile
-npm link
-```
-
-`pnpm check` 和 `pnpm test` 是修改 Hypit 本身时使用的整仓检查。第一次使用 CLI
-不需要先跑完整测试。
+结果会分别给出当前项目、项目 `.hypit` 状态、机器 Program Home 与 npm Distribution。
+pnpm、Corepack 和 `npm link` 只属于贡献者工作流。
## 2. 编译示例
-仓库里的示例包含 Script、两次视频生成需求、Speech Track、WhisperX 对齐、字幕、Media Track、
+链接中的示例包含 Script、两次视频生成需求、Speech Track、WhisperX 对齐、字幕、Media Track、
文字、Film 与最终渲染。
```bash
-cd examples/talking-film-graph-check
+cd /path/to/copied-talking-film-graph-check
hypit check main.svml
```
@@ -108,7 +99,7 @@ Runtime Profile 说明在哪里做。
## 4. 建立自己的项目
-把视频项目和生成产物放在 Hypit 仓库之外。完成上面的链接后,可以在独立项目目录里直接使用
+把视频项目和生成产物放在已安装的 Hypit Distribution 之外。全局命令可以在独立项目目录里直接使用
`hypit`:
```bash
@@ -119,8 +110,8 @@ hypit runtime use hypit.runtime.json
hypit plan build.svrun
```
-含有 `package.json` 的项目负责自己的能力包安装;普通创作文件夹不需要成为 Node 项目,直接使用
-链接仓库里的包。Source 与导出的文件留在项目里,Runtime 状态与 Artifact 位于所选 Profile 的
+含有 `package.json` 的项目负责自己的第三方包;普通创作文件夹不需要成为 Node 项目,直接使用
+Distribution 里的官方包。Source 与导出的文件留在项目里,Runtime 状态与 Artifact 位于所选 Profile 的
`dataRoot`。`runtime use` 只在 `.hypit/runtime` 保存一个本地指针。Source import 选择作者包,
Profile 则通过 `use` 独立选择 Runtime 包。
@@ -136,8 +127,9 @@ Profile 则通过 `use` 独立选择 Runtime 包。
hypit build build.svrun --follow
```
-`build` 会自动分配并打印一个新的 Build id、持久化这次 Build、确保对应 Worker 可用,并只启动
-所选 Endpoint 声明的外部程序。`--follow` 只是观察器;关掉它不会停止 Build。
+`build` 会先重复同一套便宜的本地预检,再分配新的 Build id、持久化 Build 并确保 Worker
+可用。它不会安装包,也不会启动 Managed Program;部署未就绪时应显式运行
+`hypit runtime up`。`--follow` 只是观察器;关掉它不会停止 Build。
编辑源码时使用 `check`;配置或排查部署时使用 `doctor`。它们都不会提交工作,但也不是每次
Build 前必须重复的仪式。
@@ -170,11 +162,13 @@ Runtime 会归档所有已经接受的中间 Record 和媒体。`get` 只负责
```bash
uv python install 3.13
-uv sync --project services/whisperx --frozen
-uv sync --project services/image-opencv --frozen
-uv run --project services/whisperx --frozen hypit-whisperx-prepare
+hypit runtime use hypit.runtime.json
+hypit runtime up
```
+Runtime 只会在机器 Program Home 中缺少托管环境时创建它,随后被所有项目和会话复用。不要在
+创作项目里手动执行服务的 `uv sync`。
+
修改 Runtime Profile 后运行 `hypit doctor hypit.runtime.json`。它会报告缺少的工具、凭据和
Endpoint 配置,但不会执行作者图。
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
index 6a3a3f11..1546211b 100644
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@ -185,7 +185,7 @@ Endpoint,不会改变作者图。
`@hypit/seedance-kits` 包含七个纯数据 Text Template。Kit 不是模型包装器:先用通用
`text:Render` 生成 prompt,再把该 Text 与真实媒体引用显式接入低层 Seedance Surface。
-只把项目实际选择的 Kit `.svs` 文件复制进视频项目的 `./kits/` 目录,并导入这份项目内副本,使 Kit 字节保持在 Source Closure 内;项目源码不要反向引用 Hypit 仓库 checkout。
+只把项目实际选择的 Kit `.svs` 文件复制进视频项目的 `./kits/` 目录,并导入这份项目内副本,使 Kit 字节保持在 Source Closure 内;项目源码不要反向引用已安装的 Hypit Distribution。
创作前阅读
[`@hypit/seedance-kits` 指南](https://github.com/hypit-ai/hypit/blob/main/packages/seedance-kits/README.md)
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index dd5955ff..bee4718c 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -21,7 +21,7 @@ hypit build build.svrun --follow
hypit get <build-id> --name final.video --to output/final.mp4
```
-快速开始只需链接一次仓库命令。此后本页所有命令都直接写作 `hypit`,在仓库外的视频项目中也一样。
+快速开始只需全局安装一次 Distribution。此后本页所有命令都直接写作 `hypit`,在任何独立视频项目中都一样。
只有 `build` 会真正提交工作。`plan` 是普通预览;`check` 用于编辑源码,`doctor` 用于配置和排查部署。它们都安全,但不是每次 Build 前必须重复的仪式。
@@ -179,8 +179,9 @@ hypit paths
包。Profile 结构和完整边界见 [Runtime](../guide/runtime.md)。
## 配置所选凭据
-`check` 与 `plan` 不会请求在线 Provider,因此不需要 API key。在运行 `doctor` 或付费/外部
-`build` 之前,只配置当前 Runtime Profile 实际引用的环境变量:
+`check` 与 `plan` 不会请求在线 Provider。没有所选 Runtime 的 `plan` 只看图,不需要部署
+凭据;有 Runtime 时,便宜预检会检查本次 Plan 所需凭据是否存在。在运行 `doctor` 或付费/
+外部 `build` 之前,只配置当前 Runtime Profile 实际引用的环境变量:
| 变量 | Provider / 用途 |
|---|---|
@@ -209,18 +210,19 @@ $env:MIMO_API_KEY = "your-key"
不要提交凭据、生成媒体、Runtime 状态/数据库或日志。
-### 0. 安装
+### 0. 准备按需依赖
+
+普通用户不运行 `pnpm install`。`runtime up` 会读取所选 Runtime Profile,把其 Adapter
+声明的上游 npm 包安装到机器共享目录,并准备外部程序。只有 Profile 选择 WhisperX、OpenCV
+等本地 Python 程序时,才需要先安装 [`uv`](https://docs.astral.sh/uv/)。
+
+作者侧缺少 Fontsource 等上游包时,`check`/`plan` 会给出精确命令,例如:
```bash
-pnpm install
+hypit packages install @fontsource-variable/[email protected]
```
-这条命令只安装 JavaScript 工作区,不会下载 Python 模型,也不会准备仓库内的所有 Provider。
-`runtime up` 会读取所选 Runtime Profile,并准备其中 Endpoint 声明的外部程序。只有 Profile 选择 WhisperX、OpenCV 等本地 Python 程序时,才需要先安装
-[`uv`](https://docs.astral.sh/uv/);具体锁定环境命令见 Quickstart 首页的 [安装](../quickstart.md#安装)。
-
-`hypit runtime up` 管理后台 Worker 和外部程序;`build` 会确保 Runtime 已运行,但不拥有
-Worker。
+`hypit runtime up` 管理依赖、后台 Worker 和外部程序;`build` 不做部署准备。
#### 把正式视频项目放在 Hypit 仓库之外
@@ -278,8 +280,8 @@ hypit doctor
Doctor 校验全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;它不启动 Worker,也不发付费请求。
`doctor` 有意检查完整 Runtime Profile。若只想检查某次 Run 真正需要的环境,请使用带
-所选 Runtime 下的 `plan`。只要计划本身有效,命令就成功;凭据或服务未就绪会写在
-`preflight.ok` 中,由 `doctor` 或 `build` 在部署阶段严格处理。
+所选 Runtime 的 `plan`。未就绪会写入 `preflight` 并令命令非零退出,但 JSON 中仍保留
+冻结计划供检查。
### 3. 检查 Source 与计划
@@ -294,8 +296,12 @@ hypit plan build.svrun
在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs;选择
Runtime 后只预检这次计划真正需要的 Endpoint、凭据和外部程序,不启动任何外部工作。
-`build` 会自动启动或复用后台 Runtime。只有希望提交前预热时才需要显式执行 `runtime up`;
-`runtime status` 用于观察。范围更窄的 `programs up|status|down` 只管理外部程序,不负责 Worker。
+`plan` 可以完全不带 Runtime;执行过 `hypit runtime use` 后,`plan` 和 `build` 都不必再写
+`--runtime`。`build` 必须能找到所选或显式 Profile。
+
+提交前用 `runtime up` 安装所选上游依赖、准备 Managed Program 并启动 Worker。`build` 只重跑
+便宜的只读预检;任何依赖未就绪都会在提交前失败,绝不在 Build 中安装或启动它。`runtime
+status` 用于观察,`programs up|status|down` 只管理外部程序。
### 4. 提交 Build