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: align local developer workflows
kashorin9238ad24160c
diff --git a/README.md b/README.mdindex c3f84fa9..29f5814d 100644--- a/README.md+++ b/README.md@@ -95,7 +95,7 @@ Details and current gaps are maintained inRequirements:- Node.js 22+-- pnpm+- pnpm for installing and testing this source workspace- Python 3.10–3.13 only when running the local WhisperX service```bash@@ -104,27 +104,38 @@ pnpm install --frozen-lockfilepnpm checkpnpm test+# `node --run` avoids launching pnpm for every CLI command.# Compile a complete provider-free author graph.-pnpm narratage check examples/talking-film-graph-check/main.svml \+node --run narratage -- check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .# Compile the self-described Run Graph and inspect its finite plan.-pnpm narratage plan examples/talking-film-graph-check/build.svrun \+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```+`node --run narratage -- ...` is the short form inside this checkout. To keep a real video project+in a completely separate directory, invoke the checkout's lightweight launcher from that project:++```bash+cd /path/to/my-video+/path/to/svml/narratage check main.svml \+ --package-lock svml.packages.lock --package-root /path/to/svml --root .+```++The launcher does not run pnpm and does not move source, state or outputs into this repository.+The live example uses an explicit Run Graph, declarative local Runtime Profile and externalcredentials:```bash-pnpm narratage build examples/talking-film-live/build.svrun \+node --run narratage -- build examples/talking-film-live/build.svrun \--runtime examples/talking-film-live/svml.runtime.json \- --package-lock examples/talking-film-live/svml.packages.lock \--root . \--build-id talking-film-live \--follow-pnpm narratage get talking-film-live \+node --run narratage -- get talking-film-live \--name final.video \--runtime examples/talking-film-live/svml.runtime.json \--to examples/talking-film-live/output/final.mp4diff --git a/docs/README.md b/docs/README.mdindex 5cbfe888..bf50038f 100644--- a/docs/README.md+++ b/docs/README.md@@ -32,6 +32,8 @@ the working tree contains only documents that should inform current implementaticommand hierarchy, visual language and decentralized Endpoint authentication.- [`runtime-adapter-loading.md`](./runtime-adapter-loading.md) — separately locked Providerand Store activation, physical-code identity, diagnostics and explicit Artifact maintenance.+- [`validation-boundaries.md`](./validation-boundaries.md) — the single-owner validation gates;+ what is mandatory, what stays optional and what must never be revalidated downstream.- [`build-archive-and-egress.md`](./build-archive-and-egress.md) — Targets, durable Records,Artifact retention and optional Host materialization as four separate concerns.- [`speech-alignment.md`](./speech-alignment.md) — the Script and the recording as twodiff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex 1ca4ae6e..2e0c69b7 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -131,7 +131,7 @@ Add the path mapping so TypeScript resolves `@narratage/my-component` to source:```bashpnpm install --frozen-lockfile-pnpm narratage lock-packages <lock-file> \+node --run narratage -- lock-packages <lock-file> \--package @narratage/my-component \[--package @narratage/other-direct-package ...] \--package-root .@@ -141,6 +141,18 @@ Only name direct packages you chose. Exact logical Module dependencies declaredare added from the installed physical dependency closure automatically; missing or ambiguousproviders make lock creation fail.+For an existing lock, add only this direct package without repeating the other selections:++```bash+node --run narratage -- lock-packages <lock-file> \+ --add @narratage/my-component \+ --package-root .+```++Use `--remove` for an explicit revocation, `--refresh` to accept changed bytes for the unchanged+selection, and `--verify` for a read-only closure check. Repeated `--package` always means the exact+complete direct selection.+## 8. Use in Author Source```xmldiff --git a/docs/guide/providers.md b/docs/guide/providers.mdindex b3d46d5a..27b63785 100644--- a/docs/guide/providers.md+++ b/docs/guide/providers.md@@ -90,26 +90,20 @@ import { createMyServiceProvider } from "./provider.js";const adapter = createRuntimeEndpointAdapterFacet({use: "@narratage/provider-my-service",- validate(context) {+ activate(context) {const config = runtimeConfigObject(context.config, "MyService");runtimeConfigExact(config, ["apiKey", "defaultConcurrency"], "MyService");- if (runtimeConfigCredentialRef(config.apiKey, "MyService apiKey") === undefined) {- throw new Error("MyService apiKey CredentialRef is required");- }- runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");- },-- create(context) {- const config = runtimeConfigObject(context.config, "MyService");const apiKey = runtimeConfigCredentialRef(config.apiKey, "MyService apiKey");if (apiKey === undefined) throw new Error("MyService apiKey CredentialRef is required");- return createMyServiceProvider({- instance: context.instance,- lane: context.lane,- apiKey,- ...(runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency") === undefined- ? {} : { defaultConcurrency: config.defaultConcurrency as number }),- });+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");+ return {+ endpoint: createMyServiceProvider({+ instance: context.instance,+ lane: context.lane,+ apiKey,+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),+ }),+ };},});@@ -122,9 +116,12 @@ export const svmlPackage = {export default svmlPackage;```-`validate` is pure and runs before authority is granted. `create` constructs the Endpoint only-after the profile, lock and permissions pass. Credential presence is diagnosed through the generic-CredentialStore/Endpoint description path; a Provider must not special-case environment variables.+`activate` is the one pure deployment declaration. The Endpoint it returns owns the credential+references, permissions, capabilities and scheduling facts used by both `doctor` and execution.+Activation must not resolve secrets or environment-sourced deployment values, access the network or+start work. It keeps environment names as references until a matching Need is handled. Credential+presence is diagnosed through the generic CredentialStore path; a Provider must not special-case+environment variables as a secret Store.## 5. Declare an external service (if needed)@@ -148,19 +145,24 @@ export function createMyExternalService(): RuntimeExternalService {}```-Wire it into the activation descriptor by passing `service` to `createRuntimeEndpointAdapterFacet`:+Return it beside the Endpoint from the same activation:```typescriptconst adapter = createRuntimeEndpointAdapterFacet({use: "@narratage/provider-my-service",- service: createMyExternalService,- // create, doctor …+ activate(context) {+ return {+ endpoint: createMyServiceProvider(/* parsed config */),+ externalService: createMyExternalService(),+ };+ },});````narratage runtime up` prepares, starts and probes declared external programs before starting the-durable Worker. `build` ensures that Runtime is running before submission. Providers that call only-remote APIs omit this step entirely—leave `"service"` out of `package.json`.+durable Worker. `build` starts only services backing capabilities declared by its selected Producer+steps. Providers that call only remote APIs omit this step entirely—leave `"service"` out of+`package.json`.## 6. Register and lock@@ -173,11 +175,15 @@ Add the path mapping to `tsconfig.json`:Lock into a Runtime package lock:```bash-pnpm narratage lock-packages <runtime-lock> \+node --run narratage -- lock-packages <runtime-lock> \--package @narratage/provider-my-service \--package-root .```+If the Runtime lock already exists, use `--add @narratage/provider-my-service` instead. This changes+only the local trust selection; the package remains inert until the Runtime Profile explicitly+instantiates its `use` id.+## 7. Reference from svml.runtime.json```json@@ -202,7 +208,7 @@ pnpm narratage lock-packages <runtime-lock> \Verify the configuration:```bash-pnpm narratage doctor svml.runtime.json+node --run narratage -- doctor svml.runtime.json```## Existing Providers to studydiff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.mdindex fa6c67f7..30d38a5a 100644--- a/docs/guide/runtime-profile.md+++ b/docs/guide/runtime-profile.md@@ -224,8 +224,8 @@ export default async function createRuntime() {Pass either form to `--runtime`:```bash-pnpm narratage build build.svrun --runtime ./svml.runtime.json-pnpm narratage build build.svrun --runtime ./svml.runtime.ts+node --run narratage -- build build.svrun --runtime ./svml.runtime.json+node --run narratage -- build build.svrun --runtime ./svml.runtime.ts```Both forms describe the same explicit assembly. The TypeScript form is trusted embedding code, not@@ -238,7 +238,7 @@ a source-language escape hatch or a place for author intent.Checks the Runtime Profile without running a Build or making paid requests:```bash-pnpm narratage doctor svml.runtime.json+node --run narratage -- doctor svml.runtime.json```Validates:@@ -249,30 +249,45 @@ Validates:- Required executables (ffmpeg, ffprobe, chrome) are found- Declared external services are reachable and match the selected profile-Runtime Adapter Host ABI `@1` separates a required pure configuration validator from the adapter-factory. `doctor` never constructs an Endpoint or Store, starts a service, writes Runtime state or-submits work. After configuration passes it may make bounded read-only environment probes. The first-configuration or prerequisite failure for one instance suppresses diagnostics that merely result-from that same failure.+Runtime Adapter Host ABI `@1` gives each Endpoint one pure activation declaration. `doctor` evaluates+that declaration and reads credentials, permissions and prerequisites from the resulting Endpoint+package; there is no diagnostic-only credential mirror. Activation may construct handlers but may+not resolve credentials, access the network, start a process or mutate durable state. `doctor` never+constructs a Scheduler, Worker, Build Store or author package, starts a service, writes Runtime state+or submits work. It opens only the CredentialStore adapters selected by the Profile, then closes+them, and may run explicitly declared bounded read-only probes.++### Credential control is not Runtime execution++`auth status|login|logout <endpoint-instance>` constructs only that exact Endpoint declaration and+the CredentialStores selected by the Profile. It does not open SQLite, start a Worker, load author+packages or construct unrelated Providers. Logging into KIE therefore cannot be blocked by an old+Build database or an unrelated Vertex configuration.## Runtime lifecycle```bash-pnpm narratage runtime up svml.runtime.json-pnpm narratage runtime status svml.runtime.json-pnpm narratage runtime logs svml.runtime.json-pnpm narratage runtime down svml.runtime.json+node --run narratage -- runtime up svml.runtime.json+node --run narratage -- runtime status svml.runtime.json+node --run narratage -- runtime logs svml.runtime.json+node --run narratage -- runtime down svml.runtime.json````runtime up` owns the detached Worker plus declared external programs. `services` remains a narrowexpert command for those external programs only. A Build submission ensures the Runtime is up, butthe Build terminal never owns execution.+During the pre-release period SQLite execution schemas are intentionally not migrated in place.+If a development database predates the selected Store implementation, the CLI names the exact path+and asks the operator to archive that database (including its WAL companions) or select a new path.+Artifact bytes live in the independently selected ArtifactStore and are never deleted by this+refusal.+### gc (garbage collection)```bash-pnpm narratage gc svml.runtime.json # dry-run-pnpm narratage gc svml.runtime.json --apply # delete unreachable Artifacts+node --run narratage -- gc svml.runtime.json # dry-run+node --run narratage -- gc svml.runtime.json --apply # delete unreachable Artifacts```Walks every retained BuildState and Operation, computes reachable Artifact digests, and reports@@ -286,13 +301,13 @@ Every Build archives all accepted Records and referenced Artifacts durably, inde### List Builds```bash-pnpm narratage builds --runtime svml.runtime.json+node --run narratage -- builds --runtime svml.runtime.json```### Inspect```bash-pnpm narratage inspect <build-id> --runtime svml.runtime.json+node --run narratage -- inspect <build-id> --runtime svml.runtime.json```Shows target bindings, demanded Logical Outputs, every accepted Record and Operation status.@@ -301,19 +316,19 @@ Shows target bindings, demanded Logical Outputs, every accepted Record and Opera```bash# By source output name-pnpm narratage get <build-id> --runtime svml.runtime.json \+node --run narratage -- get <build-id> --runtime svml.runtime.json \--name final.video --to output.mp4# By Record id-pnpm narratage get <build-id> --runtime svml.runtime.json \+node --run narratage -- get <build-id> --runtime svml.runtime.json \--record <record-id> --to output.json# By Logical Output id-pnpm narratage get <build-id> --runtime svml.runtime.json \+node --run narratage -- get <build-id> --runtime svml.runtime.json \--output <output-id># By Artifact digest-pnpm narratage get <build-id> --runtime svml.runtime.json \+node --run narratage -- get <build-id> --runtime svml.runtime.json \--artifact <sha256:...> --to file.bin```diff --git a/docs/guide/services.md b/docs/guide/services.mdindex 3ae5c303..6681a9fa 100644--- a/docs/guide/services.md+++ b/docs/guide/services.md@@ -10,15 +10,19 @@ Two lifecycle scopes are deliberately separate.## Runtime execution domain```bash-pnpm narratage runtime up svml.runtime.json-pnpm narratage runtime status svml.runtime.json-pnpm narratage runtime logs svml.runtime.json-pnpm narratage runtime down svml.runtime.json+node --run narratage -- runtime up svml.runtime.json+node --run narratage -- runtime status svml.runtime.json+node --run narratage -- runtime logs svml.runtime.json+node --run narratage -- runtime down svml.runtime.json````runtime up` starts or reuses the detached fenced Worker and also prepares/starts the externalprograms declared by selected adapters. The process identity, profile digest and log path areproject-scoped. Repeating `runtime up` does not create a second Worker for the same domain.+Independent external programs are prepared concurrently. The human CLI prints each bounded phase+(`Checking`, `Preparing`, `Starting`, `Waiting`, `Ready`) so a first WhisperX model preparation or+browser installation is visible instead of looking like a frozen command. JSON output remains one+clean final document.`runtime status` combines:@@ -38,9 +42,9 @@ is brought up again.## External programs only```bash-pnpm narratage services up svml.runtime.json-pnpm narratage services status svml.runtime.json-pnpm narratage services down svml.runtime.json+node --run narratage -- services up svml.runtime.json+node --run narratage -- services status svml.runtime.json+node --run narratage -- services down svml.runtime.json````services` is an expert/debugging command. It never starts the Worker and never reads or mutates a@@ -56,33 +60,45 @@ Remote-only Endpoints such as KIE have no local service.## Build relationship```bash-pnpm narratage build build.svrun --runtime svml.runtime.json-pnpm narratage build build.svrun --runtime svml.runtime.json --follow+node --run narratage -- build build.svrun --runtime svml.runtime.json+node --run narratage -- build build.svrun --runtime svml.runtime.json --follow```-Before submission, `build` validates the profile and ensures its Runtime is up. The Build command+Before submission, `build` derives the capabilities declared by the selected Producer steps and+prepares only external programs backing those capabilities. A text-only or Estimate-only Target+therefore does not load WhisperX merely because the Profile also offers it. This selection changes+no graph edge and does not route Providers; it only avoids starting unrelated deployment programs.+Concurrent launches are serialized per Profile, so they share one Worker and one managed instance+of each demanded external service. The Build commandthen stores one verified Build plus dispatch ticket. Without `--follow` it exits immediately after-submission. `--follow` observes durable state only; Ctrl-C detaches the observer and leaves the-Worker running.+submission. `--follow` observes durable state only and prints a line when the Build phase or+Operation revision/progress changes; if that Worker stops, it fails with a restart command instead+of waiting forever. Ctrl-C detaches the observer and leaves the Worker running.`--no-services` skips automatic external-program startup for an operator who already owns thoseprograms, but it does not create implicit Runtime services or move execution back into the CLI.+Explicit `runtime up` and `services up` still operate the complete Profile because their subject is+the deployment, not one Build.+## Visibility```bash-pnpm narratage queue --runtime svml.runtime.json-pnpm narratage queue --runtime svml.runtime.json --watch-pnpm narratage status <build-id> --runtime svml.runtime.json-pnpm narratage operations <build-id> --runtime svml.runtime.json-pnpm narratage operation <operation-id> --runtime svml.runtime.json+node --run narratage -- queue --runtime svml.runtime.json+node --run narratage -- queue --runtime svml.runtime.json --watch+node --run narratage -- status <build-id> --runtime svml.runtime.json+node --run narratage -- operations <build-id> --runtime svml.runtime.json+node --run narratage -- operation <operation-id> --runtime svml.runtime.json```-These views expose durable dispatch phase, lease/capacity facts, Operation attempts, checkpoints and-cancellation state. They do not reconstruct a secret second graph or ask a Provider for creative+These views expose the active durable dispatch set, Worker state, lease/capacity facts, Operation+attempts, generic Endpoint progress, checkpoints and cancellation state. They do not reconstruct a+secret second graph or ask a Provider for creativerouting.-Use `--json` for one versioned result and `--jsonl` for a watch stream.+Use `--json` for one versioned result and `--jsonl` for a watch stream. `queue --watch` emits the+first snapshot and later changes; it does not print an identical block every second while a remote+job remains in the same state.## WhisperXdiff --git a/docs/quickstart.md b/docs/quickstart.mdindex 6c3f922c..cdf40587 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -18,7 +18,8 @@ been published to npm yet.## Install-Requires Node.js 22+ and pnpm.+Requires Node.js 22+ and pnpm for installing/testing this source workspace. The ordinary CLI+examples use Node's built-in script runner so each command does not launch pnpm again.```bashcorepack enable@@ -27,6 +28,11 @@ pnpm checkpnpm test```+Inside the source checkout, commands use `node --run narratage -- ...`. A project outside this+repository uses `/path/to/svml/narratage ...` plus `--package-root /path/to/svml`; the checked-in+launcher starts the same CLI directly without pnpm, and all project state stays under that external+project's Runtime Profile root.+## Three inputsEvery Build takes three separate inputs:@@ -45,10 +51,10 @@ The `talking-film-graph-check` example compiles a complete video graph — ScripWhisperX, Gemini Caption, Media Track, Text, Film, HyperFrames — without calling any external service.```bash-pnpm narratage check examples/talking-film-graph-check/main.svml \+node --run narratage -- check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-pnpm narratage plan examples/talking-film-graph-check/build.svrun \+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.mdindex bbd514b6..a75409dc 100644--- a/docs/quickstart/composition.md+++ b/docs/quickstart/composition.md@@ -242,10 +242,10 @@ The complete data flow from Script to rendered video. This example is based on### Compile and verify```bash-pnpm narratage check examples/talking-film-graph-check/main.svml \+node --run narratage -- check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-pnpm narratage plan examples/talking-film-graph-check/build.svrun \+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```diff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex 85f9a028..6ee2a27f 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -114,6 +114,41 @@ historical Records as zero-input Candidates and connect them through Satisfactio</svrun>```+### Finding reusable output++Query an output name as it appeared in each historical Build's frozen Host Catalog:++```bash+node --run narratage -- history hook-take.video \+ --runtime ./svml.runtime.json+```++`history` reports only public Logical Outputs that the Build actually selected and accepted. It+does not list merely declared-but-unbuilt aliases or authored Record aliases that cannot back a+`build-record` Candidate. If the old name is unknown, list accepted output names from Builds whose+Catalog recorded an exact source path:++```bash+node --run narratage -- history --source ./main.svml \+ --runtime ./svml.runtime.json+```++An output name is a human locator inside one immutable historical Catalog, not its identity. The+historical Core Build, Logical Output and Record digests carry identity. If the current source+renames `hook-take.video` to `opening-shot.video`, keep the old name on `<build-record>` and use the+current name on `<satisfy>`:++```svml+<build-record id="approved-opening"+ build="my-film-001" output="hook-take.video"/>+<satisfy output="opening-shot.video"+ candidate="approved-opening" fidelity="substitute"/>+```++Narratage never infers that two names mean the same author intent. A human-readable build-id such+as `my-film-001` is supplied with `build --build-id`; omitting it uses the immutable compiled Core+Build digest. Reusing one explicit build-id for different compiled Author or Run intent is rejected.+### build-recordDeclares a zero-input Candidate backed by a historical Record from a previous Build:@@ -272,9 +307,11 @@ prevent one type of work from starving others.pnpm install```-This installs Node dependencies **and** prepares the Python services (WhisperX, OpenCV) that local-Builds need. When `uv` is not on your PATH the Python step is skipped with a warning — install-[uv](https://docs.astral.sh/uv/) first if you need local alignment or image processing.+This installs only the JavaScript workspace. It does not download Python models or prepare every+Provider found in the repository. `runtime up` / `services up` reads the selected Runtime Profile+and prepares only the external programs its chosen Endpoints declare. Install+[uv](https://docs.astral.sh/uv/) first only when that Profile selects a local Python service such as+WhisperX or OpenCV.`narratage runtime up` starts the durable Worker and the external programs declared by the selectedadapters. `build` also ensures that execution domain is running before it submits, but never owns@@ -288,12 +325,12 @@ Author files do not have to live under this repository. For example, keep a proj```bashcd /opt/narratage-pnpm narratage lock-packages /work/my-film/svml.packages.lock \+node --run narratage -- lock-packages /work/my-film/svml.packages.lock \--package @narratage/script \--package @narratage/estimate-pnpm narratage plan /work/my-film/build.svrun \- --package-lock /work/my-film/svml.packages.lock+node --run narratage -- plan /work/my-film/build.svrun \+ --runtime /work/my-film/svml.runtime.json```The Source Workspace defaults to the directory containing `build.svrun`; its relative Author@@ -343,7 +380,7 @@ other than the CLI installation.### 1. Diagnose the environment```bash-pnpm narratage doctor examples/talking-head-aroll/svml.runtime.json+node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json```Doctor validates both locks, every selected Runtime role, Endpoint configuration, credential@@ -352,8 +389,8 @@ presence and bounded environment probes. It never starts the Worker or performs### 2. Inspect the plan```bash-pnpm narratage plan examples/talking-head-aroll/build.svrun \- --package-lock examples/talking-head-aroll/svml.packages.lock --root .+node --run narratage -- plan examples/talking-head-aroll/build.svrun \+ --runtime examples/talking-head-aroll/svml.runtime.json --root .```Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the@@ -362,37 +399,49 @@ Scheduler would issue.### 3. Submit the Build```bash-pnpm narratage build examples/talking-head-aroll/build.svrun \+node --run narratage -- build examples/talking-head-aroll/build.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --package-lock examples/talking-head-aroll/svml.packages.lock \--root . \--build-id my-film-001 \--follow```Without `--follow`, `build` returns after durable submission. The detached Worker continues. With-`--follow`, the terminal is only an observer; interrupting it leaves the Build running.+`--follow`, the terminal is only an observer; it reports durable phase/Operation-count changes and+interrupting it leaves the Build running.| Flag | Description ||---|---|| `--runtime` | Path to the Runtime Profile |-| `--package-lock` | Path to the package lock file |+| `--package-lock` | Standalone compilation lock when no Runtime Profile is supplied; a JSON Profile single-sources it for `check`, `plan` and `build` || `--package-root` | Host directory containing the installed packages named by the lock || `--root` | Optional Source Workspace boundary; defaults to the entry Source directory || `--build-id` | User-chosen identifier for this Build (used for retrieval and reuse) |-| `--follow` | Stream Build progress to the terminal |+| `--follow` | Wait for terminal state as an observer; durable execution remains with the Worker |++Without `--build-id`, identity is derived from the compiled Author and Run intent: repeating the+same command addresses the same durable Build and does not silently buy another generation. An+unfinished Build continues from accepted Records and recoverable Endpoint checkpoints; a completed,+failed or cancelled Build remains terminal and is only reported. Use a new explicit id when the same+unchanged prompt intentionally needs another stochastic take. Reusing an explicit id for different+compiled intent is rejected with both repair choices.### 4. Retrieve results```bash-pnpm narratage get my-film-001 \+node --run narratage -- get my-film-001 \--runtime examples/talking-head-aroll/svml.runtime.json \--name final.video \--to examples/talking-head-aroll/output/final.mp4```Every accepted intermediate Record and Artifact is archived before the Build completes. `get` makes-a copy of an already durable Record.+a copy of an already durable Record. Blob Artifacts are streamed from the selected Store, checked+against their declared size and SHA-256 digest, and only then atomically replace the destination;+exporting a large MP4 does not buffer the complete file in CLI memory.++The terminal Build result prints the exact `get --name …` command for every targeted source alias;+there is no need to inspect opaque Record ids just to export `final.video`.### 5. Reuse in a new Build@@ -400,8 +449,7 @@ Create a new `.svrun` file that references the completed Build's Records (see [Rabove), then submit it:```bash-pnpm narratage build examples/talking-head-aroll/reuse-generated.svrun \+node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --package-lock examples/talking-head-aroll/svml.packages.lock \--root . --build-id my-film-reuse-001 --follow```diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.mdindex b549ce6c..a9ba622d 100644--- a/docs/zh/guide/author-packages.md+++ b/docs/zh/guide/author-packages.md@@ -126,7 +126,7 @@ export default svmlPackage;```bashpnpm install --frozen-lockfile-pnpm narratage lock-packages <lock-file> \+node --run narratage -- lock-packages <lock-file> \--package @narratage/my-component \[--package @narratage/other-direct-package ...] \--package-root .@@ -135,6 +135,17 @@ pnpm narratage lock-packages <lock-file> \这里只列出你直接选择的包。它们的 Manifest 声明的精确逻辑 Module 依赖,会从已安装的物理依赖闭包中自动加入;缺失、摘要不匹配或存在多个候选时,建锁会直接失败。+已有锁只需增加这个直接包时,不必重写其他选择:++```bash+node --run narratage -- lock-packages <lock-file> \+ --add @narratage/my-component \+ --package-root .+```++`--remove` 明确撤销一个直接选择,`--refresh` 在选择不变时接受当前安装字节,`--verify`+只读验证闭包。重复的 `--package` 始终表示一份完整、精确的直接选择,而不是增量添加。+## 8. 在 Author Source 中使用```xmldiff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.mdindex abe963b5..72a50018 100644--- a/docs/zh/guide/providers.md+++ b/docs/zh/guide/providers.md@@ -86,26 +86,20 @@ import { createMyServiceProvider } from "./provider.js";const adapter = createRuntimeEndpointAdapterFacet({use: "@narratage/provider-my-service",- validate(context) {+ activate(context) {const config = runtimeConfigObject(context.config, "MyService");runtimeConfigExact(config, ["apiKey", "defaultConcurrency"], "MyService");- if (runtimeConfigCredentialRef(config.apiKey, "MyService apiKey") === undefined) {- throw new Error("MyService apiKey CredentialRef is required");- }- runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");- },-- create(context) {- const config = runtimeConfigObject(context.config, "MyService");const apiKey = runtimeConfigCredentialRef(config.apiKey, "MyService apiKey");if (apiKey === undefined) throw new Error("MyService apiKey CredentialRef is required");- return createMyServiceProvider({- instance: context.instance,- lane: context.lane,- apiKey,- ...(runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency") === undefined- ? {} : { defaultConcurrency: config.defaultConcurrency as number }),- });+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");+ return {+ endpoint: createMyServiceProvider({+ instance: context.instance,+ lane: context.lane,+ apiKey,+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),+ }),+ };},});@@ -118,8 +112,10 @@ export const svmlPackage = {export default svmlPackage;```-`validate` 是无副作用的纯校验;通过 Profile、lock 与权限校验后才会调用 `create`。凭据是否-存在由通用 CredentialStore 与 Endpoint 描述路径诊断,Provider 不得硬编码环境变量 Store。+`activate` 是唯一的纯部署声明。它返回的 Endpoint 同时拥有供 `doctor` 与执行使用的凭据引用、+权限、capability 和调度事实。Activation 不得解析密钥或环境来源的部署值、访问网络或启动任务;+环境变量名会作为引用保留到真正处理匹配 Need 时。凭据是否存在由通用 CredentialStore 路径诊断,+Provider 不得把环境变量硬编码成特殊的密钥 Store。## 5. 声明外部服务(如需要)@@ -142,18 +138,22 @@ export function createMyExternalService(): RuntimeExternalService {}```-在 activation 描述符中通过 `service` 参数接入:+在同一个 activation 中把它与 Endpoint 一起返回:```typescriptconst adapter = createRuntimeEndpointAdapterFacet({use: "@narratage/provider-my-service",- service: createMyExternalService,- // create, doctor …+ activate(context) {+ return {+ endpoint: createMyServiceProvider(/* 已解析配置 */),+ externalService: createMyExternalService(),+ };+ },});```-`narratage runtime up` 会准备、启动并探测外部程序,然后启动耐久 Worker。`build` 会确保-Runtime 已运行。只调用远程 API 的 Provider 不声明 service。+`narratage runtime up` 会准备、启动并探测外部程序,然后启动耐久 Worker。`build` 只启动+所选 Producer steps 声明的 capability 所需服务。只调用远程 API 的 Provider 不声明 service。## 6. 注册并锁定@@ -166,11 +166,14 @@ Runtime 已运行。只调用远程 API 的 Provider 不声明 service。锁定进 Runtime 包锁文件:```bash-pnpm narratage lock-packages <runtime-lock> \+node --run narratage -- lock-packages <runtime-lock> \--package @narratage/provider-my-service \--package-root .```+如果 Runtime 包锁已经存在,改用 `--add @narratage/provider-my-service`。这一步只改变本地+信任选择;在 Runtime Profile 用 `use` 显式实例化之前,这个包仍然不会运行。+## 7. 在 svml.runtime.json 中引用```json@@ -195,7 +198,7 @@ pnpm narratage lock-packages <runtime-lock> \验证配置:```bash-pnpm narratage doctor svml.runtime.json+node --run narratage -- doctor svml.runtime.json```## 可供研究的现有 Providerdiff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.mdindex fd8b1618..a33cfd38 100644--- a/docs/zh/guide/runtime-profile.md+++ b/docs/zh/guide/runtime-profile.md@@ -85,14 +85,20 @@ CLI 进程里的计数器。容量租约跟随 Build 的 fenced lease;过期 W权限仍是显式 allowlist,例如 `network:<host>`、`filesystem:<scope>`、`process:<name>`。+## 凭据控制不是 Runtime 执行++`auth status|login|logout <endpoint-instance>` 只构造该 Endpoint 的声明和 Profile 明确选择的+CredentialStore,不会打开 SQLite、启动 Worker、加载作者包或构造其他 Provider。因此登录+KIE 不会被旧 Build 数据库或无关的 Vertex 配置拦住。+## 生命周期```bash-pnpm narratage doctor svml.runtime.json-pnpm narratage runtime up svml.runtime.json-pnpm narratage runtime status svml.runtime.json-pnpm narratage runtime logs svml.runtime.json-pnpm narratage runtime down svml.runtime.json+node --run narratage -- doctor svml.runtime.json+node --run narratage -- runtime up svml.runtime.json+node --run narratage -- runtime status svml.runtime.json+node --run narratage -- runtime logs svml.runtime.json+node --run narratage -- runtime down svml.runtime.json````runtime up` 管理耐久 Worker 与声明的外部程序。`services up/status/down` 只管理外部程序,@@ -100,17 +106,27 @@ pnpm narratage runtime down svml.runtime.json后台进程绑定覆盖 Profile 与两份 package lock 的有效修订摘要;任一文件变化后状态变为`stale`,下一次启动或提交会按新执行闭包替换进程,而不是继续复用旧装配。+`doctor` 会求值 Endpoint Adapter 唯一的纯 `activate()` 声明,并直接从产生的 Endpoint package+读取凭据、权限和前置条件;不存在另一份仅供诊断使用的凭据镜像。Activation 可以构造 handler,+但不得解析密钥、访问网络、启动进程或修改持久状态。`doctor` 不构造 Scheduler、Worker、Build+Store 或作者包,不会启动服务、写入 Runtime 状态或提交任务;它只打开 Profile 明确选择的+CredentialStore 来解析引用,完成后立即关闭,并可执行显式声明的有界只读探测。++预发布阶段不会原地迁移 SQLite 执行 schema。遇到更早的开发数据库时,CLI 会指出精确路径,+要求把数据库连同 WAL 文件归档,或在 Profile 选择新路径。ArtifactStore 是独立选择的;该+拒绝不会删除任何产物字节。+## Build、队列与归档```bash-pnpm narratage build build.svrun --runtime svml.runtime.json-pnpm narratage build build.svrun --runtime svml.runtime.json --follow-pnpm narratage queue --runtime svml.runtime.json --watch-pnpm narratage status <build-id> --runtime svml.runtime.json-pnpm narratage operations <build-id> --runtime svml.runtime.json-pnpm narratage operation <operation-id> --runtime svml.runtime.json-pnpm narratage inspect <build-id> --runtime svml.runtime.json-pnpm narratage get <build-id> --runtime svml.runtime.json --name final.video --to output.mp4+node --run narratage -- build build.svrun --runtime svml.runtime.json+node --run narratage -- build build.svrun --runtime svml.runtime.json --follow+node --run narratage -- queue --runtime svml.runtime.json --watch+node --run narratage -- status <build-id> --runtime svml.runtime.json+node --run narratage -- operations <build-id> --runtime svml.runtime.json+node --run narratage -- operation <operation-id> --runtime svml.runtime.json+node --run narratage -- inspect <build-id> --runtime svml.runtime.json+node --run narratage -- get <build-id> --runtime svml.runtime.json --name final.video --to output.mp4```不带 `--follow` 时,`build` 在耐久提交后退出;Worker 继续执行。`--follow` 只是观察,Ctrl-C@@ -119,8 +135,8 @@ pnpm narratage get <build-id> --runtime svml.runtime.json --name final.video --t## 取消```bash-pnpm narratage cancel build <build-id> --runtime svml.runtime.json-pnpm narratage cancel operation <operation-id> --runtime svml.runtime.json+node --run narratage -- cancel build <build-id> --runtime svml.runtime.json+node --run narratage -- cancel operation <operation-id> --runtime svml.runtime.json```Build 取消先关闭准入;Operation 取消只抑制那个精确实现。`accepted` 只是远端接受停止请求,diff --git a/docs/zh/guide/services.md b/docs/zh/guide/services.mdindex 134b292f..2fe2d7da 100644--- a/docs/zh/guide/services.md+++ b/docs/zh/guide/services.md@@ -10,16 +10,20 @@ description: 管理耐久 Worker 与 Profile 明确选择的本地程序。## 整个执行域```bash-pnpm narratage runtime up svml.runtime.json-pnpm narratage runtime status svml.runtime.json-pnpm narratage runtime logs svml.runtime.json-pnpm narratage runtime down svml.runtime.json+node --run narratage -- runtime up svml.runtime.json+node --run narratage -- runtime status svml.runtime.json+node --run narratage -- runtime logs svml.runtime.json+node --run narratage -- runtime down svml.runtime.json````runtime up` 启动或复用当前 Profile 的后台 Worker,并准备、启动该 Profile 声明的外部程序。重复执行不会创建第二个同域 Worker。`runtime status` 同时展示 Worker、耐久队列、共享容量和外部程序健康状态。+彼此独立的外部程序会并行准备。人类可读输出会显示 `Checking`、`Preparing`、`Starting`、+`Waiting`、`Ready`,首次准备 WhisperX 模型或浏览器时不会像命令卡死;JSON 模式仍只输出+一份干净的最终文档。+后台进程同时绑定 Profile 路径,以及覆盖 Profile 与两份 package lock 的有效修订摘要。任一文件变化后,旧进程会显示为 `stale`;下一次 `runtime up` 或 `build` 会先替换旧进程,不会让新 Dispatch 偷偷进入旧执行闭包。@@ -30,9 +34,9 @@ pnpm narratage runtime down svml.runtime.json## 只管理外部程序```bash-pnpm narratage services up svml.runtime.json-pnpm narratage services status svml.runtime.json-pnpm narratage services down svml.runtime.json+node --run narratage -- services up svml.runtime.json+node --run narratage -- services status svml.runtime.json+node --run narratage -- services down svml.runtime.json````services` 是调试/运维命令,只处理 Adapter 声明的程序,不启动 Worker、不读取或修改 Build@@ -47,23 +51,31 @@ KIE 这种纯远端 API Endpoint 没有本地 service。## 与 Build 的关系-`build` 会先验证并确保 Runtime 正在运行,然后耐久写入 Build 与 Dispatch ticket。无-`--follow` 时立刻退出;`--follow` 只观察。中断观察终端不会中断 Worker。+`build` 会先从选中 Producer steps 推导其声明的 capability,只准备承载这些 capability 的+外部程序。纯文本或纯 Estimate Target 不会仅仅因为 Profile 里也提供 WhisperX 就加载几 GB+模型;这不改变图、不替作者路由 Provider,只避免启动无关部署程序。之后 Build 与 Dispatch+ticket 会被耐久写入。无 `--follow` 时立刻退出;`--follow` 只观察,并在 Build phase 或+Operation 数量变化时输出一行。中断观察终端不会中断 Worker。`--no-services` 只表示外部程序由部署者另行维护,不会把执行塞回 CLI,也不会恢复任何隐式 Runtime 默认。+显式 `runtime up` 与 `services up` 仍管理整个 Profile,因为它们的对象是部署而非某次 Build。+## 可见性```bash-pnpm narratage queue --runtime svml.runtime.json --watch-pnpm narratage status <build-id> --runtime svml.runtime.json-pnpm narratage operations <build-id> --runtime svml.runtime.json-pnpm narratage operation <operation-id> --runtime svml.runtime.json+node --run narratage -- queue --runtime svml.runtime.json --watch+node --run narratage -- status <build-id> --runtime svml.runtime.json+node --run narratage -- operations <build-id> --runtime svml.runtime.json+node --run narratage -- operation <operation-id> --runtime svml.runtime.json```-这些命令展示 dispatch phase、租约/容量、Operation checkpoint 和取消状态。`--json` 输出-一次结构化结果,watch 命令可用 `--jsonl`。+这些命令展示活跃 dispatch、Worker 状态、租约/容量、Operation 的通用进度、checkpoint 和+取消状态。并发启动按 Profile 串行化,只会复用一个 Worker 和每个受管外部服务的一个实例;+`--follow` 若发现 Worker 已停止会明确报出重启命令,不会无限等待。`--json` 输出+一次结构化结果,watch 命令可用 `--jsonl`。`queue --watch` 只输出第一份快照和后续变化,+不会在远端任务状态没变时每秒重复刷同一个块。## WhisperXdiff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex c2d7df65..e2166ad5 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -24,6 +24,10 @@ pnpm checkpnpm test```+在源码仓库内可使用 `node --run narratage -- ...`。仓库外的视频项目直接执行+`/path/to/svml/narratage ... --package-root /path/to/svml`;这个轻量入口不再启动 pnpm,源码、+SQLite、Artifact 和输出仍全部留在外部项目的 Runtime Profile root 下。+## 三份输入每一次 Build 都接受三份彼此独立的输入:@@ -42,10 +46,10 @@ Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime ProfileWhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。```bash-pnpm narratage check examples/talking-film-graph-check/main.svml \+node --run narratage -- check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-pnpm narratage plan examples/talking-film-graph-check/build.svrun \+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.mdindex 1821ab46..e0820c47 100644--- a/docs/zh/quickstart/composition.md+++ b/docs/zh/quickstart/composition.md@@ -238,10 +238,10 @@ Build Target,也可以直接接到媒体裁切、音频/帧提取或模型参### 编译与验证```bash-pnpm narratage check examples/talking-film-graph-check/main.svml \+node --run narratage -- check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-pnpm narratage plan examples/talking-film-graph-check/build.svrun \+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdindex 3079bf03..8cb23683 100644--- a/docs/zh/quickstart/run.md+++ b/docs/zh/quickstart/run.md@@ -108,6 +108,39 @@ Narratage 没有隐式缓存。复用结果是显式的运行图编写——你</svrun>```+### 查找可复用输出++按照输出在各个历史 Build 冻结 Catalog 中的旧名字查询:++```bash+node --run narratage -- history hook-take.video \+ --runtime ./svml.runtime.json+```++`history` 只列出该 Build 确实选择并验收过的公开 Logical Output。仅仅在源码中声明但没有+运行出来的别名,以及不能作为 `build-record` Candidate 的 authored Record 别名,都不会混入+结果。如果忘了旧名字,可以按 Catalog 当时记录的精确源码路径列出真正验收过的输出名:++```bash+node --run narratage -- history --source ./main.svml \+ --runtime ./svml.runtime.json+```++输出名只是某个不可变历史 Catalog 内供人查找的名字,不是产物身份。真正身份由历史 Core+Build、Logical Output 和 Record 摘要共同确定。假如当前源码把 `hook-take.video` 改名为+`opening-shot.video`,`<build-record>` 仍写历史旧名,`<satisfy>` 写当前新名:++```svml+<build-record id="approved-opening"+ build="my-film-001" output="hook-take.video"/>+<satisfy output="opening-shot.video"+ candidate="approved-opening" fidelity="substitute"/>+```++Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-001` 这样的可读 build-id 由+`build --build-id` 提供;省略时使用不可变的编译后 Core Build 摘要。已经绑定的显式 build-id+不能再用于另一份作者意图或运行意图。+### build-record声明一个由先前 Build 的历史 Record 支持的零输入 Candidate:@@ -275,11 +308,11 @@ Worker。```bashcd /opt/narratage-pnpm narratage lock-packages /work/my-film/svml.packages.lock \+node --run narratage -- lock-packages /work/my-film/svml.packages.lock \--package @narratage/script \--package @narratage/estimate-pnpm narratage plan /work/my-film/build.svrun \+node --run narratage -- plan /work/my-film/build.svrun \--package-lock /work/my-film/svml.packages.lock```@@ -326,7 +359,7 @@ Runtime 状态、归档 Artifact 和 lock 仍全部留在 `/work/my-film`。只### 1. 诊断环境```bash-pnpm narratage doctor examples/talking-head-aroll/svml.runtime.json+node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json```Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;@@ -335,8 +368,8 @@ Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭### 2. 检查计划```bash-pnpm narratage plan examples/talking-head-aroll/build.svrun \- --package-lock examples/talking-head-aroll/svml.packages.lock --root .+node --run narratage -- plan examples/talking-head-aroll/build.svrun \+ --runtime examples/talking-head-aroll/svml.runtime.json```在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs。@@ -344,16 +377,14 @@ pnpm narratage plan examples/talking-head-aroll/build.svrun \### 3. 提交 Build```bash-pnpm narratage build examples/talking-head-aroll/build.svrun \+node --run narratage -- build examples/talking-head-aroll/build.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --package-lock examples/talking-head-aroll/svml.packages.lock \- --root . \--build-id my-film-001 \--follow```不带 `--follow` 时,Build 在耐久提交后退出,后台 Worker 继续。带 `--follow` 时终端也只是-观察者;Ctrl-C 不会取消任务。+观察者,并会报告 phase / Operation 数量变化;Ctrl-C 不会取消任务。| 标志 | 说明 ||---|---|@@ -364,24 +395,32 @@ pnpm narratage build examples/talking-head-aroll/build.svrun \| `--build-id` | 用户为此 Build 选择的标识符(用于检索和复用) || `--follow` | 将 Build 进度流式输出到终端 |+不传 `--build-id` 时,身份由编译后的作者意图和运行意图派生;重复同一条命令只会寻址同一个+耐久 Build,不会偷偷再买一次生成。未完成的 Build 从已验收 Record 和可恢复 Endpoint checkpoint+继续;已完成、失败或取消的 Build 保持终态,只返回状态。相同 prompt 明确需要另一份随机结果时,+使用新的显式 id。把已有显式 id 用到另一份编译意图上会被拒绝,并同时提示“换 id”或“恢复原 Source”。+### 4. 获取结果```bash-pnpm narratage get my-film-001 \+node --run narratage -- get my-film-001 \--runtime examples/talking-head-aroll/svml.runtime.json \--name final.video \--to examples/talking-head-aroll/output/final.mp4```-每个被接受的中间 Record 和 Artifact 在 Build 完成前都会被归档。`get` 会复制一份已持久化的 Record。+每个被接受的中间 Record 和 Artifact 在 Build 完成前都会被归档。`get` 会复制一份已持久化的+Record。Blob Artifact 会从所选 Store 流式读取,逐步校验长度与 SHA-256,完整通过后才原子替换+目标路径;导出大 MP4 不会把整段视频塞进 CLI 内存。+Build 的最终输出会为每个目标别名打印精确的 `get --name …` 命令,不必为了导出+`final.video` 去查不透明的 Record id。### 5. 在新 Build 中复用创建一个引用已完成 Build 的 Record 的新 `.svrun` 文件(参见上文[复用结果](#复用结果)),然后提交:```bash-pnpm narratage build examples/talking-head-aroll/reuse-generated.svrun \+node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --package-lock examples/talking-head-aroll/svml.packages.lock \- --root . --build-id my-film-reuse-001 --follow+ --build-id my-film-reuse-001 --follow```diff --git a/examples/bootstrap/README.md b/examples/bootstrap/README.mdindex cfd5f5ec..c41746ac 100644--- a/examples/bootstrap/README.md+++ b/examples/bootstrap/README.md@@ -5,7 +5,7 @@ self-described Markup entry source can import the Script Surface and recursivelysource selected by another Header. There is no built-in video prelude or suffix-selected parser:```bash-pnpm narratage check examples/bootstrap/main.svml \+node --run narratage -- check examples/bootstrap/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```diff --git a/examples/talking-film-graph-check/README.md b/examples/talking-film-graph-check/README.mdindex ff179e35..31d69835 100644--- a/examples/talking-film-graph-check/README.md+++ b/examples/talking-film-graph-check/README.md@@ -6,11 +6,11 @@ explicit HyperFrames rendering. `check` and `plan` do not invoke Seedance, WhispHyperFrames.```bash-pnpm narratage check examples/talking-film-graph-check/main.svml \+node --run narratage -- check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-pnpm narratage check examples/talking-film-graph-check/build.svrun \+node --run narratage -- check examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-pnpm narratage plan examples/talking-film-graph-check/build.svrun \+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```diff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.mdindex 10ad16b3..18919480 100644--- a/examples/talking-film-live/README.md+++ b/examples/talking-film-live/README.md@@ -23,32 +23,32 @@ Prerequisites for the exact checked-in Runtime Profile:Prepare and health-check WhisperX as described in[`../../services/whisperx/README.md`](../../services/whisperx/README.md). `narratage check` validates-source, Run Graph and exact Runtime capability coverage before scheduling, but it does not make a-paid Provider request or promise that remote credentials and service health are valid.+the source and Run Graph without making a paid Provider request. `narratage build` assembles the+selected Runtime and rejects missing capability coverage before scheduling external work; neither+command promises that remote credentials and service health are valid.Run the complete graph through the explicit Run Graph and declarative local Runtime Profile:The checked-in `svml.packages.lock` selects each author, Run and deterministic compute package-independently; there is no implicit video bundle. Regenerate it after changing one of those package-implementations with the package list documented in the lock file.+independently; there is no implicit video bundle. After changing a selected package implementation,+refresh its already explicit selection with+`node --run narratage -- lock-packages examples/talking-film-live/svml.packages.lock --refresh`.The independent `svml.runtime-packages.lock` selects Local execution, SQLite state, filesystemArtifacts, environment credentials, KIE, local media, local WhisperX, Vertex and local HyperFramesadapters; adding another implementation does not change the CLI.```bash-pnpm narratage runtime up examples/talking-film-live/svml.runtime.json+node --run narratage -- runtime up examples/talking-film-live/svml.runtime.json-pnpm narratage build examples/talking-film-live/build.svrun \+node --run narratage -- build examples/talking-film-live/build.svrun \--runtime examples/talking-film-live/svml.runtime.json \- --package-lock examples/talking-film-live/svml.packages.lock \- --root . \--build-id talking-film-live \--follow-pnpm narratage inspect talking-film-live \+node --run narratage -- inspect talking-film-live \--runtime examples/talking-film-live/svml.runtime.json-pnpm narratage get talking-film-live \+node --run narratage -- get talking-film-live \--runtime examples/talking-film-live/svml.runtime.json \--name final.video \--to examples/talking-film-live/output/final.mp4diff --git a/examples/talking-head-aroll/README.md b/examples/talking-head-aroll/README.mdindex 12fda6ab..0bd21378 100644--- a/examples/talking-head-aroll/README.md+++ b/examples/talking-head-aroll/README.md@@ -26,7 +26,7 @@ take at Seedance's 15-second request limit.Create the explicit package lock used by this development-workspace example:```sh-pnpm narratage lock-packages examples/talking-head-aroll/svml.packages.lock \+node --run narratage -- lock-packages examples/talking-head-aroll/svml.packages.lock \--package @narratage/artifact \--package @narratage/narrative \--package @narratage/media \@@ -58,7 +58,7 @@ pnpm narratage lock-packages examples/talking-head-aroll/svml.packages.lock \--package @narratage/run-markup \--package-root .-pnpm narratage lock-packages examples/talking-head-aroll/svml.runtime-packages.lock \+node --run narratage -- lock-packages examples/talking-head-aroll/svml.runtime-packages.lock \--package @narratage/local \--package @narratage/store-sqlite \--package @narratage/artifact-store-fs \@@ -71,36 +71,40 @@ pnpm narratage lock-packages examples/talking-head-aroll/svml.runtime-packages.l--package-root .```+After package implementation changes, retain these explicit selections without repeating the long+list:++```sh+node --run narratage -- lock-packages examples/talking-head-aroll/svml.packages.lock --refresh+node --run narratage -- lock-packages examples/talking-head-aroll/svml.runtime-packages.lock --refresh+```+Inspect the authored graph—including the visible `*.prompt` Text output and `*.program`—without a paid call:```sh-pnpm narratage check examples/talking-head-aroll/main.svml \- --package-lock examples/talking-head-aroll/svml.packages.lock \- --root .+node --run narratage -- check examples/talking-head-aroll/main.svml \+ --runtime examples/talking-head-aroll/svml.runtime.json```Inspect the exact paid plan before submitting it:```sh-pnpm narratage plan examples/talking-head-aroll/build.svrun \- --package-lock examples/talking-head-aroll/svml.packages.lock \- --root .+node --run narratage -- plan examples/talking-head-aroll/build.svrun \+ --runtime examples/talking-head-aroll/svml.runtime.json```Build the complete film after preparing the managed local WhisperX service and exposing `KIE_API_KEY`,`GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS_JSON`:```sh-pnpm narratage runtime up examples/talking-head-aroll/svml.runtime.json+node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json-pnpm narratage build examples/talking-head-aroll/build.svrun \+node --run narratage -- build examples/talking-head-aroll/build.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --package-lock examples/talking-head-aroll/svml.packages.lock \- --root . \--build-id talking-head-film-001 \--follow-pnpm narratage get talking-head-film-001 \+node --run narratage -- get talking-head-film-001 \--runtime examples/talking-head-aroll/svml.runtime.json \--name final.video \--to examples/talking-head-aroll/output/final.mp4@@ -113,10 +117,8 @@ Run the same downstream film from the four archived generated shots without anotsubmission:```sh-pnpm narratage build examples/talking-head-aroll/reuse-generated.svrun \+node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \--runtime examples/talking-head-aroll/svml.runtime.json \- --package-lock examples/talking-head-aroll/svml.packages.lock \- --root . \--build-id talking-head-film-reuse-001 \--follow```