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: make the first Narratage workflow clear
kashorinff64c17bcb4e
diff --git a/README.md b/README.mdindex 11575e79..dcc59177 100644--- a/README.md+++ b/README.md@@ -1,235 +1,223 @@# Narratage-Narratage is a compiler and runtime for building expensive, recoverable creative workflows from-human-readable intent. Its sources are written in SVML, its graph markup language.--The name is a 1930s film-industry term — narration plus montage: narration-driven storytelling-with montage in a supporting role. The reference video distribution follows that technique. An-author addresses a video with words rather than timecodes: Script defines the semantic truth,-generated speech supplies acoustic evidence, and independent packages lower captions, B-roll,-text and speech into peer Tracks.+> Write the story. Compile the video.++Narratage is a semantic, graph-native system for making AI video. You write the story, choose the+models and visual components, and state which outputs you want. Narratage turns that intent into a+finite execution plan, runs only the work the result depends on, and keeps every accepted output+available for later Runs.++SVML is the authoring language. Narratage is the compiler, runtime and package ecosystem around it.++[Documentation](https://narratage.hypit.ai/) ·+[中文文档](https://narratage.hypit.ai/zh/) ·+[Quickstart](https://narratage.hypit.ai/quickstart) ·+[Examples](./examples/README.md)++Narratage currently runs from a source checkout. The npm packages and CLI have not been published+yet.++## What it feels like++The Script remains readable prose. Semantic anchors live beside the words they describe; generation,+timing, captions and composition refer back to that meaning.++```svml+<script id="story">+ <opening>+ <HOST>Meaning @demo becomes the source @/demo.</opening>+</script>++<seedance:TextVideo id="take"+ model="mini"+ prompt={direction}+ duration="5"+ generate-audio="true"/>++<whisperx:Alignment id="timing"+ narrative={story}+ audio={speech.audio}/>++<media-track:Item+ video={motion.video}+ during={story.selection.demo}+ frame={card-frame}/>++<film:Film id="main" canvas={vertical} space={speech.space}>+ <film:Track source={speech.visual}/>+ <film:Track source={cards.visual}/>+ <film:Track source={captions.track}/>+</film:Film>+```-Narratage is pre-release. It has completed a real paid talking-video acceptance sequence, but the-repository is currently a source-checkout workspace rather than a published npm distribution; its-public package names and video authoring ABI are not frozen yet.+This is an excerpt from the complete, checkable+[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml) example. Namespaced+elements are supplied by imported packages; the language does not hard-code Seedance, WhisperX,+Caption or Film into its Core.-## Why a graph language+## Try it without API keys-AIGC operations are slow, costly, fallible and non-deterministic. Their results frequently become-inputs to later compilation. A usable system must therefore distinguish:+You need Node.js 22+ and pnpm 10.33.x. These commands install the source workspace and compile a+complete video graph without starting a Provider or making a paid request:-- what the author requested;-- which implementation is used for this Run;-- which results are actually demanded;-- what has already been materialized;-- where an external capability executes;-- which facts and code produced every accepted result.+```bash+git clone https://github.com/hypit-ai/narratage.git+cd narratage+corepack enable+pnpm install --frozen-lockfile-Narratage compiles those decisions before execution:+node --run narratage -- check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock \+ --root .-```text-Author Graph + Run Graph + Satisfaction edges + Targets- │- ▼- frozen BuildPlan- │- ▼- recoverable verified execution+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock \+ --root .```-There is no privileged final-video root. Any public Logical Output can be a Target.--## Core model--- A **Logical Output** is an author-visible typed result promise.-- A **Candidate** is an independent typed supply backed by a Provided Value or Operation result.-- A **Satisfaction** explicitly connects one compatible Candidate to a Logical Output. Core does- not attach creative labels such as `exact`, `substitute` or `pin` to that edge.-- A **Target** says which outputs this Build requires.-- An **Operation** is one atomic execution instance. Shared identity means one execution; separate- instances execute separately even when their parameters match.-- Core resolves the selected reverse closure and freezes a finite BuildPlan before any external- command runs.--Product actions such as pinning a previous video, using a black preview or selecting an alternate-fragment are ordinary Run Graph authoring. Core contains no Pin, preview mode, automatic cache or-Provider fallback branch.--See [the architecture](docs/architecture.md) and-[Core Kernel specification](spec/core-kernel.md).--## What works today--The repository implements:--- domain-neutral Protocol, Core, graph elaboration and Node compiler Host;-- mandatory self-described Author/Run sources with no suffix-selected or default parser;-- official `.svml` markup, Script Surface, `.svs` Recipes and `.svrun` execution intent;-- locked trusted package activation without package-specific Core registration;-- recoverable Runtime scheduling with concurrency lanes, retries and cancellation;-- SQLite Build/Operation stores and filesystem/S3 Artifact stores;-- exact Endpoint binding and scoped credentials;-- eleven exact image/video models declaring their own input ports, reached through the KIE Provider;-- three exact MiMo TTS models, independently reached through Xiaomi's official Provider;-- local ffprobe/ffmpeg media processing;-- S3 multipart Artifact streaming and AWS Lambda media processing;-- managed warm local WhisperX service;-- Vertex Gemini display-only Caption planning;-- local frame-parallel HyperFrames rendering;-- recoverable Step Functions/Lambda HyperFrames rendering;-- Speech, Fine Caption, Typography, Media Item/Sequence, Deck, Ranking, Comment Sticker, Audio and- Screen Overlay packages lowering to peer Tracks, followed by Film, HyperFrames and final mux.--The complete live path is:+`check` verifies the Author Source and prints its typed outputs. `plan` shows the exact demanded+subgraph and every external capability a real Build would need. Planning never starts external work.-```text-Script → Estimate → Seedance × N → media normalization → WhisperX → SemanticMap- → Gemini CaptionPlan → peer Tracks → Film → HyperFrames → audio mix → MP4-```+See the [Quickstart](./docs/quickstart.md) if Corepack is unavailable or you want to run local media,+WhisperX, OpenCV or HyperFrames.-Details and current gaps are maintained in-[implementation status](docs/implementation-status.md).+## The files you control-## Quick start--Requirements:+| File | Purpose |+|---|---|+| `main.svml` | The video: Script, chosen models, Tracks and Composition |+| `studio.svs` | Optional reusable visual and prompt Recipes imported by the Author Source |+| `build.svrun` | The outputs required for one Run, including explicit reuse or alternate Candidates |+| `svml.runtime.json` | The machine environment: stores, endpoints, credentials and concurrency |+| `svml.packages.lock` | Generated lock for author and compute packages |+| `svml.runtime-packages.lock` | Generated lock for Runtime and Provider packages |-- Node.js 22+-- pnpm for installing and testing this source workspace-- Python 3.10–3.13 only when running the local WhisperX service+The boundaries are deliberate:-```bash-corepack enable-pnpm install --frozen-lockfile-pnpm check-pnpm test+- SVML says what the author means and explicitly chooses model families where that choice matters.+- SVRUN says what this Run should produce and which compatible results should satisfy its outputs.+- The Runtime Profile says where those operations execute.+- Providers translate exact capability requests into local programs or remote APIs. They do not+ reinterpret the author's creative choice.-# `node --run` avoids launching pnpm for every CLI command.-# Compile a complete provider-free author graph.-node --run narratage -- check examples/talking-film-graph-check/main.svml \- --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+## From source to output-# Compile the self-described Run Graph and inspect its finite plan.-node --run narratage -- plan examples/talking-film-graph-check/build.svrun \- --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+```text+main.svml + studio.svs+ │+ ▼+ Author Graph ◀──── build.svrun selects Targets and Candidates+ │+ ▼+ frozen BuildPlan no external work has started yet+ │+ ▼+ Runtime Profile ─────── Worker, Stores and exact Provider Endpoints+ │+ ▼+ accepted Records ────── inspect, reuse, or materialize with `get````-`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:+There is no privileged “final video” root. A Run can target a generated image, a transcript map, a+Track, or the completed video. The compiler follows dependencies backward from those Targets and+does not schedule unrelated work.++## Run a real project++Keep video projects outside the Narratage checkout. During source development, call the checkout's+lightweight launcher from the project directory:```bashcd /path/to/my-video+/path/to/narratage/narratage packages sync build.svrun \--runtime svml.runtime.json --root .-/path/to/narratage/narratage check main.svml --runtime svml.runtime.json --root .-/path/to/narratage/narratage plan build.svrun --runtime svml.runtime.json --root .-```--The Runtime Profile may point `packageRoot` at this checkout during source development. 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 external-credentials:+/path/to/narratage/narratage doctor svml.runtime.json+/path/to/narratage/narratage check main.svml \+ --runtime svml.runtime.json --root .+/path/to/narratage/narratage plan build.svrun \+ --runtime svml.runtime.json --root .-```bash-node --run narratage -- build examples/talking-film-live/build.svrun \- --runtime examples/talking-film-live/svml.runtime.json \- --root . \- --build-id talking-film-live \+/path/to/narratage/narratage build build.svrun \+ --runtime svml.runtime.json \+ --build-id my-video-001 \--follow-node --run narratage -- get talking-film-live \+/path/to/narratage/narratage get my-video-001 \+ --runtime svml.runtime.json \--name final.video \- --runtime examples/talking-film-live/svml.runtime.json \- --to examples/talking-film-live/output/final.mp4+ --to output/final.mp4```-The Build archives every accepted intermediate Record and Artifact before `get` makes an optional-human-readable copy. `builds`, `inspect` and `get --name` use a Host-only catalog of source aliases;-the selected Record is still verified against the authoritative BuildState.+`build` submits durable work and ensures the selected Worker is available. `--follow` only observes+that Build; closing the observer does not cancel it. Use `status`, `queue`, `operations` and+`inspect` to see what is happening.-Read its [deployment requirements](examples/talking-film-live/README.md) before running it. Paid-credentials, presenter assets, local databases and generated outputs are not committed.+Read [Run Source & Builds](./docs/quickstart/run.md) before the first paid Build. It covers Runtime+Profiles, credentials, concurrency, cancellation and explicit reuse of previous outputs.-## Author source versus execution environment+## Why a graph language-These inputs are separate by design:+AI generation is slow, costly, fallible and non-deterministic. Its outputs often become the next+step's inputs. A linear script or hidden workflow runner cannot clearly answer all of these questions:-| Input | Owns |-|---|---|-| `.svml` | author meaning, explicit model/component choices and graph references |-| `.svs` | reusable package-defined Recipe values |-| `.svrun` | Targets, Candidates and explicit Satisfaction edges for one reusable Run |-| `svml.runtime.json` / `svml.runtime.ts` | Scheduler, Stores, credential references, Endpoints and concurrency |-| `svml.packages.lock` | physical author/compute implementation closure |-| `svml.runtime-packages.lock` | physical Provider/Store adapter closure and privileged code identity |+- What did the author request?+- Which result is required right now?+- Which implementation and Provider will produce it?+- Which earlier image or video should be reused deliberately?+- What can run in parallel, and what is waiting on an upstream result?+- What actually produced the accepted output?-Source imports activate author vocabulary only. They never authorize network, filesystem, process,-credential or queue access.+Narratage makes those choices visible as two peer graphs: the Author Graph expresses the work, and+the Run Graph selects Targets and realizations for one Build. Core only resolves, verifies and+advances the resulting state machine; video concepts remain in independently installable packages.-## Packages and extension+For the full model, read [Architecture](./docs/architecture.md). For the small normative laws, read+the [Core Kernel specification](./spec/core-kernel.md).-A physical package may expose separately locked facets:+## Extend it without changing Core-```text-author Frontend, Surface, Graph Fragment-compute deterministic Producer or Type Validator-endpoint privileged local/remote capability implementation-runtime Scheduler or Store implementation-```+Packages may independently contribute:++- an author-facing Surface and its graph lowering;+- a typed contract shared with other packages;+- a deterministic compute operation;+- a local or remote Provider endpoint;+- a Scheduler, credential store or Artifact store implementation.-Packages communicate through nominal Types published by their owners. Core does not contain a-central union of Narrative, Track, Seedance or any other domain type. Installing a trusted package-can add a new component or Endpoint without republishing Core.+Core has no central list of video models, Tracks or Providers. Installed packages communicate through+nominal types and explicit graph edges.-Current package execution is for explicitly installed, byte-locked trusted code. Arbitrary-community Parser/Producer/Validator execution still needs a real isolation and permission boundary.+Choose the guide that matches your work:++- [Author a video](./docs/quickstart.md)+- [Understand package boundaries](./docs/guide/packages.md)+- [Add an author package](./docs/guide/author-packages.md)+- [Add a Provider](./docs/guide/providers.md)+- [Configure a Runtime Profile](./docs/guide/runtime-profile.md)+- [Develop Narratage itself](./docs/guide/develop.md)## Repository map```text-packages/protocol immutable wire contracts-packages/artifact domain-neutral content-addressed byte Type-packages/core domain-neutral Demand compiler and Build state machine-packages/source mandatory Source Header; no syntax default-packages/elaborator author declarations and hygienic Fragment expansion-packages/compiler-node reference Node compiler Host-packages/compiler-markup-node optional official Markup compiler assembly-packages/package-loader-node syntax-neutral trusted physical-package loading-packages/cli generic commands requiring an explicit Distribution-packages/video-cli official video command application; no author-package aggregate-packages/run syntax-neutral Run Source closure and complete Run Graph compiler-packages/run-markup optional official human-readable Run Frontend-packages/runtime environment-neutral scheduling and Store ports-packages/driver-node trusted Node command execution-packages/local in-process SQLite/filesystem developer assembly-packages/* optional Frontend, domain, Endpoint and adapter packages-services/whisperx managed warm local WhisperX External Service-spec current normative contracts-docs architecture, status, roadmap and focused implementation records-examples source-closure checks and the live acceptance witness+packages/ Core, compiler, Runtime, video packages and Provider adapters+services/ Local external programs such as WhisperX and OpenCV+examples/ Checkable sources and complete Runtime examples+docs/ User guides, architecture and implementation records+spec/ Normative protocol and video-package contracts+tools/ Repository checks and focused development tools```-Start with the [documentation map](docs/README.md) and [roadmap](docs/roadmap.md).-The [open-source distribution plan](docs/open-source-distribution.md) records what can ship-independently and what remains before the first public package release.-## Development-```bash-pnpm check # TypeScript across every workspace package-pnpm test # package test suites and repository boundary tests+The commands below are for changing Narratage itself, not for making a video:-pnpm test:whisperx-service-pnpm smoke:kie # opt-in paid Provider smoke test; requires credentials+```bash+pnpm check+pnpm test+pnpm docs:build```-## Current priorities--The domain-neutral Run/Runtime foundation, developer inspection path, replaceable local/AWS-Endpoint environments and current pre-release video packages are implemented. Current work is-delivery-driven correction, deployment hardening and preparing a source-checkout project for its-first public package release. Fresh generation, historical reuse and previews remain ordinary-explicit `.svrun` choices rather than a second workflow layer. The repository-internal Track and-Visual IR waist is frozen; author-facing video Surfaces remain pre-release. See the-[implementation status](docs/implementation-status.md) and [roadmap](docs/roadmap.md).+Current implementation facts and remaining work live in+[Implementation Status](./docs/implementation-status.md) and the [Roadmap](./docs/roadmap.md).diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex c7415830..67f17664 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -140,7 +140,7 @@ const enTheme = {{ text: "SVS Stylesheets", link: "/quickstart/styles" },{ text: "Media & Generation", link: "/quickstart/generation" },{ text: "Timing & Assembly", link: "/quickstart/timing" },- { text: "Caption, B-roll & Text", link: "/quickstart/tracks" },+ { text: "Caption, Media & Text", link: "/quickstart/tracks" },{ text: "Film & Rendering", link: "/quickstart/composition" },{ text: "Run Source & Builds", link: "/quickstart/run" },],@@ -183,7 +183,7 @@ const zhTheme = {{ text: "SVS 样式表", link: "/zh/quickstart/styles" },{ text: "媒体与生成", link: "/zh/quickstart/generation" },{ text: "时序与装配", link: "/zh/quickstart/timing" },- { text: "字幕、B-roll 与文字", link: "/zh/quickstart/tracks" },+ { text: "字幕、Media 与文字", link: "/zh/quickstart/tracks" },{ text: "Film 与渲染", link: "/zh/quickstart/composition" },{ text: "Run Source 与 Build", link: "/zh/quickstart/run" },],diff --git a/docs/README.md b/docs/README.mdindex 2eb92686..2fb45a8c 100644--- a/docs/README.md+++ b/docs/README.md@@ -1,20 +1,39 @@# Documentation-Narratage documentation is intentionally split by authority. Git history preserves discarded designs;-the working tree contains only documents that should inform current implementation or public use.+Use the shortest path that matches what you are trying to do. The author guides explain the product;+the developer guides explain extension points; architecture and specifications define implementation+boundaries.-## Start here+## Make a video-1. [`../README.md`](../README.md) — project overview and development entrypoint.-2. [`architecture.md`](./architecture.md) — current Author Graph, Run Graph, Satisfaction, Runtime+1. [`../README.md`](../README.md) — understand Narratage and run the first provider-free commands.+2. [`quickstart.md`](./quickstart.md) — install the checkout, compile a complete video graph and set+ up a project outside the repository.+3. [`quickstart/script.md`](./quickstart/script.md) through+ [`quickstart/composition.md`](./quickstart/composition.md) — author Script, style, generation,+ timing, Tracks, Film and rendering.+4. [`quickstart/run.md`](./quickstart/run.md) — choose Targets, configure the Runtime, build, inspect,+ reuse and retrieve results.++The website publishes these pages at [narratage.hypit.ai](https://narratage.hypit.ai/).++## Extend Narratage++1. [`guide/develop.md`](./guide/develop.md) — repository setup and guide index.+2. [`guide/packages.md`](./guide/packages.md) — package layers, facets and dependency rules.+3. [`guide/author-packages.md`](./guide/author-packages.md) — add author vocabulary and graph lowering.+4. [`guide/providers.md`](./guide/providers.md) — implement an external capability endpoint.+5. [`guide/runtime-profile.md`](./guide/runtime-profile.md) — assemble Schedulers, Stores and Providers.++## Understand the system++1. [`architecture.md`](./architecture.md) — current Author Graph, Run Graph, Satisfaction, Runtimeand package boundaries.-3. [`implementation-status.md`](./implementation-status.md) — what actually executes today.-4. [`roadmap.md`](./roadmap.md) — active domain-neutral, environment/Provider and delivery-driven- video-package work.-5. [`open-source-distribution.md`](./open-source-distribution.md) — what can ship independently,- current packaging truth and public-release gates.-6. [`../spec/core-kernel.md`](../spec/core-kernel.md) — compact normative Kernel laws for the+2. [`../spec/core-kernel.md`](../spec/core-kernel.md) — compact normative Kernel laws for thecurrent `@1` wire data.+3. [`implementation-status.md`](./implementation-status.md) — what actually executes today.+4. [`roadmap.md`](./roadmap.md) — remaining domain-neutral, environment and video-package work.+5. [`open-source-distribution.md`](./open-source-distribution.md) — packaging facts and release gates.## Domain-neutral implementation recordsdiff --git a/docs/index.md b/docs/index.mdindex b2dfee51..8ea1e720 100644--- a/docs/index.md+++ b/docs/index.md@@ -3,13 +3,25 @@ layout: homehero:name: "Narratage"+ text: "Write the story. Compile the video."+ tagline: "A semantic, graph-native system for AI video production. Author intent stays readable; generation, timing, tracks and rendering remain replaceable packages."actions:- theme: brand- text: Quickstart+ text: Get startedlink: /quickstart- theme: alt- text: Develop- link: /guide/develop+ text: View on GitHub+ link: https://github.com/hypit-ai/narratage++features:+ - title: Meaning before timelines+ details: Write scripts, semantic selections and visual intent. Components locate and render them without turning the source into a frame-by-frame edit.+ - title: Plan before spending+ details: Compile the exact demanded subgraph before any Provider starts. See every selected Candidate, Operation and external Need.+ - title: Packages, not a central catalog+ details: Models, tracks, Providers, stores and runtimes can be installed independently. Core does not contain a list of video components.+ - title: Durable creative work+ details: Accepted images, video, evidence and renders are archived as explicit results that later Runs can deliberately reuse.---<ClientOnly>diff --git a/docs/quickstart.md b/docs/quickstart.mdindex 5c356a68..965403ee 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -1,110 +1,192 @@---title: Quickstart-description: Set up Narratage and compile your first video graph.+description: Install Narratage, compile a complete SVML video graph, and prepare a real Build.---# Quickstart-The name **Narratage** comes from a 1933 *New York Times* review of the film *The Power and the-Glory*. The critic coined the word to describe a then-new cinematic technique:-**Narration + Montage** — a narrator's voice carries the story forward while the screen assembles-a montage of scenes to match.+Narratage turns an SVML author source into a visible execution graph. Before any model or external+service runs, you can check the source, choose a Run, and inspect the exact work it would require.-That is exactly what this system does. The author writes a narrated Script with semantic anchors,-and the compiler assembles generated video, captions, B-roll, text and audio into a finished film.-Author Sources are written in SVML (Semantic Video Markup Language) and carry the `.svml`-extension.+This page gets you to that first safe plan. It does not need API keys and does not make a paid call.-## Choose your path+## 1. Install the source workspace-### Use the Narratage skill+Narratage currently runs from a source checkout. You need Node.js 22+ and pnpm 10.33.x through+Corepack.-Send the following instruction to your agent:--```text-Install and use the narratage skill from this repository. 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.+```bash+git clone https://github.com/hypit-ai/narratage.git+cd narratage+corepack enable+pnpm install --frozen-lockfile```-### Continue manually+If `corepack` is unavailable:-Start with [Install](#install), then follow the seven guides in order.+```bash+npm install --global [email protected]+corepack enable+corepack prepare [email protected] --activate+pnpm install --frozen-lockfile+```-## Install+`pnpm check` and `pnpm test` are repository-development commands. You do not need to run the full+suite before using the CLI.-The source workspace requires Node.js 22+ and pnpm 10.33.x through Corepack. These commands are the-same in macOS/Linux shells and Windows PowerShell. The ordinary CLI examples use Node's built-in-script runner so each command does not launch pnpm again.+## 2. Compile the example-Some newer Node.js distributions do not bundle Corepack. If `corepack --version` is unavailable,-install a compatible release first from either shell:+The checked-in example includes a Script, two generated-video requests, speech assembly, WhisperX+alignment, captions, a media Track, text, Film and final rendering.-```text-npm install --global [email protected]+```bash+node --run narratage -- check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock \+ --root .```+`check` reads the self-described source, loads only its locked packages and prints the public typed+outputs it declares.++Now compile the Run Source:+```bash-corepack enable-corepack prepare [email protected] --activate-pnpm install --frozen-lockfile-pnpm check-pnpm test+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock \+ --root .```-Local media work also requires `ffmpeg` and `ffprobe` on `PATH`. Python is optional: install Python-3.10–3.13 and [`uv`](https://docs.astral.sh/uv/) only when the Runtime Profile selects local-WhisperX or OpenCV. Prepare the locked environments from either shell with:+`plan` binds the Author Graph and Run Graph, walks backward from `final.video`, and freezes the+Operations and external Needs that a Build would use. It never starts a Provider.++Open the three source files next:++- [`main.svml`](https://github.com/hypit-ai/narratage/blob/main/examples/talking-film-graph-check/main.svml) — the video;+- [`studio.svs`](https://github.com/hypit-ai/narratage/blob/main/examples/talking-film-graph-check/studio.svs) — reusable visual Recipes;+- [`build.svrun`](https://github.com/hypit-ai/narratage/blob/main/examples/talking-film-graph-check/build.svrun) — the requested output.++## 3. Understand the project files++A working video project normally has four authored/configured inputs and two generated locks:++| File | Answers |+|---|---|+| `main.svml` | What video are you making? |+| `studio.svs` | Which reusable Recipe values does it use? |+| `build.svrun` | Which outputs and Candidates does this Run select? |+| `svml.runtime.json` | Which machine, stores and Provider endpoints execute it? |+| `svml.packages.lock` | Which author/compute package bytes are allowed? |+| `svml.runtime-packages.lock` | Which privileged Runtime package bytes are allowed? |++The short form is:```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 svml-whisperx-prepare+SVML says what.+SVRUN says which.+Runtime Profile says where.```-Inside the source checkout, commands use `node --run narratage -- ...`. A project outside this-repository uses `/path/to/narratage/narratage ...` plus `--package-root /path/to/narratage`; the checked-in-launcher starts the same CLI directly without pnpm, and all project state stays under that external-project's Runtime Profile root.+One `main.svml` may have many `.svrun` files: generate images, render the film, or reuse approved+shots without changing the authored video.++## 4. Start your own project-## Three inputs+Keep project files and generated media outside the Narratage repository. Call the checkout's+lightweight `narratage` launcher from your project directory:-Every Build takes three separate inputs:+```bash+cd /path/to/my-video++/path/to/narratage/narratage packages sync build.svrun \+ --runtime svml.runtime.json --root .++/path/to/narratage/narratage doctor svml.runtime.json+/path/to/narratage/narratage check main.svml \+ --runtime svml.runtime.json --root .+/path/to/narratage/narratage plan build.svrun \+ --runtime svml.runtime.json --root .+```-| Input | What it owns | Typical file |-|---|---|---|-| **Author Source** | script, model choices, track composition, output graph | `.svml` |-| **Run Source** | which outputs to target, alternate candidates, satisfaction edges | `.svrun` |-| **Runtime Profile** | endpoints, credentials and concurrency | `svml.runtime.json` |+The launcher uses dependencies installed in the Narratage checkout, but Source, SQLite state,+Artifacts and outputs remain inside your project. `packages sync` derives both package locks from+the imports in your Run closure and the adapters selected by the Runtime Profile.-Author Source says *what*. Run Source says *which*. Runtime Profile says *where*.+Start from [`examples/talking-film-live`](https://github.com/hypit-ai/narratage/tree/main/examples/talking-film-live) when you need a+complete Runtime Profile. Copy the source structure, then replace its assets, Script, model choices+and credentials with your own.-## Your first graph check+## 5. Build and retrieve an output-The `talking-film-graph-check` example compiles a complete video graph — Script, Seedance, Speech,-WhisperX, Gemini Caption, Media Track, Text, Film, HyperFrames — without calling any external service.+After `doctor`, `check` and `plan` pass:```bash-node --run narratage -- check examples/talking-film-graph-check/main.svml \- --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+/path/to/narratage/narratage build build.svrun \+ --runtime svml.runtime.json \+ --build-id my-video-001 \+ --follow+```-node --run narratage -- plan examples/talking-film-graph-check/build.svrun \- --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+`build` 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.++```bash+/path/to/narratage/narratage status my-video-001 \+ --runtime svml.runtime.json++/path/to/narratage/narratage queue \+ --runtime svml.runtime.json --watch++/path/to/narratage/narratage get my-video-001 \+ --runtime svml.runtime.json \+ --name final.video \+ --to output/final.mp4```-`check` produces the typed Author Graph. `plan` binds the Author and Run graphs, resolves Targets-and outputs the frozen BuildPlan — every Operation and Needs the Scheduler would issue. Inspect it-before spending money.+The Runtime archives accepted intermediate Records and media. `get` makes a human-readable copy; it+does not decide whether an intermediate result should have been retained.++## Local tools used by real Builds++Install only what your selected Runtime Profile needs:++| Tool | Needed when |+|---|---|+| `ffmpeg` / `ffprobe` | using local media inspection, normalization or muxing |+| Python 3.10–3.13 and `uv` | using local WhisperX or OpenCV |+| Chromium | managed automatically by local HyperFrames rendering |+| API credentials | selecting remote KIE, Vertex, Xiaomi or AWS endpoints |++For local Python services:++```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 svml-whisperx-prepare+```++Run `narratage doctor svml.runtime.json` after changing a Runtime Profile. It reports missing tools,+credentials and endpoint configuration without executing the graph.++## Read next-## Guide contents+Follow the authoring path in order, or jump directly to the part you are changing:-| Guide | Topic |+| Guide | What you will learn ||---|---|-| [Script](./quickstart/script.md) | Segments, Role Cues, Dual Text, Selections, Moments, text projections |-| [SVS Stylesheets](./quickstart/styles.md) | CSS-like Recipes for film, caption, B-roll, text, speech and fonts |-| [Media & Generation](./quickstart/generation.md) | media:Image, media:Audio, estimate:Speech, Text Templates, Seedance |-| [Timing & Assembly](./quickstart/timing.md) | speech:Spine, whisperx:Alignment, ProgramSpace, SemanticMap |-| [Caption, Media, Text & Audio](./quickstart/tracks.md) | Caption, Media, Typography and Audio Track authoring |-| [Film & Rendering](./quickstart/composition.md) | film:Film, render:Video, full pipeline walkthrough |-| [Run Source & Builds](./quickstart/run.md) | .svrun syntax, targets, reuse, runtime profile, build workflow |+| [Script](./quickstart/script.md) | Segments, speakers, Dual Text, Selections and Moments |+| [SVS Stylesheets](./quickstart/styles.md) | Reusable Recipes for captions, media, text and film |+| [Media & Generation](./quickstart/generation.md) | Images, audio, prompt text and explicit model components |+| [Timing & Assembly](./quickstart/timing.md) | Speech Spine, WhisperX, ProgramSpace and SemanticMap |+| [Tracks](./quickstart/tracks.md) | Caption, Media, Typography and Audio Tracks |+| [Film & Rendering](./quickstart/composition.md) | Peer Track composition and explicit rendering |+| [Run Source & Builds](./quickstart/run.md) | Targets, reuse, Runtime Profiles, Builds and retrieval |++If you use a coding agent, ask it to use the repository's `narratage` skill. The skill follows the+same files and commands; it does not introduce a separate workflow.++## Why the name++*Narratage* was coined for narration-driven montage: the narration carries the story while images+assemble around it. That is the original video form behind this project—words are the semantic+spine, and visual contributions remain independently authored Tracks.diff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex 38fff225..99ac0c7f 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -5,11 +5,34 @@ description: Declaring build targets, reusing results and configuring the runtim# Run Source & Builds-The Run Source (`.svrun`) declares **what to build** — which outputs to demand and which explicit-Candidates, if any, should replace their authored implementations. The Runtime Profile-(`svml.runtime.json`) declares **where to run** — endpoints, credentials and concurrency.+The Author Source defines the video. A Run Source chooses which of its public outputs to produce and+which explicit Candidates, if any, should satisfy them. The Runtime Profile chooses the machine,+stores and Provider endpoints that execute the resulting plan.-Neither of these changes what the video **is**. That is the Author Source's job.+Most work follows the same loop:++```bash+narratage packages sync build.svrun --runtime svml.runtime.json --root .+narratage doctor svml.runtime.json+narratage check main.svml --runtime svml.runtime.json --root .+narratage plan build.svrun --runtime svml.runtime.json --root .+narratage build build.svrun --runtime svml.runtime.json --build-id my-video-001 --follow+narratage get my-video-001 --runtime svml.runtime.json --name final.video --to output/final.mp4+```++The checked-in source launcher is `/path/to/narratage/narratage`; commands written as `narratage`+on this page mean that launcher or the future installed CLI.++Only `build` submits work. `packages sync`, `doctor`, `check` and `plan` are safe preparation steps.++```text+main.svml author meaning+build.svrun this Run's Targets and Candidate choices+svml.runtime.json execution environment+```++Run Source and Runtime Profile do not silently rewrite the video. Creative model choices remain in+the Author Source or in packages that it explicitly imports.## Run Source syntax@@ -38,9 +61,9 @@ Every `.svrun` file begins with its processing instruction:### Targets-There is no privileged "final video" root. Any public Logical Output from any component can be a-Target. The compiler only executes Operations needed to satisfy the demanded Targets — everything-else is pruned.+A Target is simply an output you want from this Build. It may be a generated image, a video take, a+timing map, a Track or the final render. The compiler only executes Operations needed for the chosen+Targets; unrelated branches are left alone.### Multiple targetsdiff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex 39164a23..f724771b 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -5,10 +5,6 @@ description: Peer track components — captions, media, typography and authored# Caption, Media, Typography & Audio-> **Pre-release note:** Caption Fine, Media Track, Typography Track and Audio Track execute their declared author Surfaces.-> Their author APIs may still evolve; the shared terminal Track/Visual IR waist is frozen inside the-> repository but has not been published as an npm ABI.-Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat(no nesting), and visual z-order is determined by the `stack-order` property in SVS. This pagecovers Caption, Media, Typography and Audio Track authoring.diff --git a/docs/zh/index.md b/docs/zh/index.mdindex 658b8ab1..59576a9c 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -3,13 +3,25 @@ layout: homehero:name: "Narratage"+ text: "写下故事,编译视频。"+ tagline: "面向 AI 视频生产的语义化图系统。作者意图保持可读,生成、定位、Track 与渲染由可替换的包完成。"actions:- theme: brandtext: 快速开始link: /zh/quickstart- theme: alt- text: 开发指南- link: /zh/guide/develop+ text: 查看 GitHub+ link: https://github.com/hypit-ai/narratage++features:+ - title: 先表达意义,再处理时间线+ details: 写口播稿、语义区间和视觉意图;组件负责定位与呈现,作者源码不必退化成逐帧编辑指令。+ - title: 花钱之前先看 Plan+ details: Provider 启动前先编译真正需要的子图,清楚看到每个 Candidate、Operation 与外部 Need。+ - title: 包,而非中央能力表+ details: 模型、Track、Provider、Store 与 Runtime 都能独立安装;Core 不维护视频组件名单。+ - title: 可留存的创作过程+ details: 已接受的图片、视频、证据和渲染都会成为显式结果,之后的 Run 可以有意识地复用。---<ClientOnly>diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex 5ff38413..97a19a1b 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -1,104 +1,187 @@----title: Quickstart-description: 搭建 Narratage 并编译你的第一张视频图。+title: 快速开始+description: 安装 Narratage,编译第一张完整的 SVML 视频图,并准备真实 Build。----# Quickstart+# 快速开始-**Narratage** 这个名字来自 1933 年《*New York Times*》对电影《*The Power and the-Glory*》的一篇影评。那位影评人造出这个词,用来描述当时的一种新兴电影手法:-**Narration + Montage** —— 旁白的声音推动故事前进,同时画面组接出与之呼应的蒙太奇。+Narratage 把 SVML 作者源码编译成一张可见的执行图。在任何模型或外部服务开始工作之前,+你可以先检查源码、选择一次 Run,并看清这次 Build 究竟需要执行什么。-这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器则把生成的视频、字幕、B-roll、-文字与音频组装成一部完成的影片。Author Source 使用 SVML(Semantic Video Markup Language)编写,-扩展名为 `.svml`。+本页先带你得到第一份安全的 Plan:不需要 API Key,也不会产生任何付费请求。-## 选择开始方式+## 1. 安装源码工作区-### 使用 Narratage skill+Narratage 目前从源码仓库运行,需要 Node.js 22+,并通过 Corepack 使用 pnpm 10.33.x。-将以下指令发送给你的 Agent:--```text-安装并使用这个仓库里的 narratage skill。配置我的环境,只向我索取当前 Runtime Profile-实际需要的 API key,然后带我完成第一支 SVML 视频的创作与 Build。+```bash+git clone https://github.com/hypit-ai/narratage.git+cd narratage+corepack enable+pnpm install --frozen-lockfile```-### 手动开始+如果系统没有 `corepack`:-从[安装](#安装)继续,然后按顺序阅读七篇指南。+```bash+npm install --global [email protected]+corepack enable+corepack prepare [email protected] --activate+pnpm install --frozen-lockfile+```-## 安装+`pnpm check` 和 `pnpm test` 是修改 Narratage 本身时使用的整仓检查。第一次使用 CLI+不需要先跑完整测试。-源码工作区需要 Node.js 22+,并通过 Corepack 使用 pnpm 10.33.x。以下命令在 macOS/Linux-Shell 与 Windows PowerShell 中相同:+## 2. 编译示例-部分较新的 Node.js 发行版不再自带 Corepack。如果 `corepack --version` 不可用,先在任一-Shell 中安装兼容版本:+仓库里的示例包含 Script、两次视频生成需求、Speech Spine、WhisperX 对齐、字幕、Media Track、+文字、Film 与最终渲染。-```text-npm install --global [email protected]+```bash+node --run narratage -- check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock \+ --root .```+`check` 会读取自描述的源码,只加载锁中允许的包,并列出这份 Author Source 声明的公共类型化输出。++接着编译 Run Source:+```bash-corepack enable-corepack prepare [email protected] --activate-pnpm install --frozen-lockfile-pnpm check-pnpm test+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock \+ --root .```-本地媒体处理还要求 `ffmpeg` 与 `ffprobe` 位于 `PATH`。Python 是可选依赖:只有 Runtime-Profile 选择本地 WhisperX 或 OpenCV 时,才需要 Python 3.10–3.13 与-[`uv`](https://docs.astral.sh/uv/)。在任一 Shell 中按锁定环境准备:+`plan` 会连接 Author Graph 和 Run Graph,从 `final.video` 反向找到真正需要的子图,冻结将要使用的+Operations 与外部 Needs。它绝不会启动 Provider。++现在可以直接打开三份源码阅读:++- [`main.svml`](https://github.com/hypit-ai/narratage/blob/main/examples/talking-film-graph-check/main.svml):视频本身;+- [`studio.svs`](https://github.com/hypit-ai/narratage/blob/main/examples/talking-film-graph-check/studio.svs):可复用的视觉 Recipe;+- [`build.svrun`](https://github.com/hypit-ai/narratage/blob/main/examples/talking-film-graph-check/build.svrun):这次要求得到的输出。++## 3. 认识项目里的文件++一个实际视频项目通常有四份由人编写或配置的输入,以及两份自动生成的锁:++| 文件 | 回答的问题 |+|---|---|+| `main.svml` | 要做的是什么视频? |+| `studio.svs` | 使用哪些可复用的 Recipe 值? |+| `build.svrun` | 这一次 Run 要哪些输出、选择哪些 Candidate? |+| `svml.runtime.json` | 在哪台机器、哪些 Store 和 Provider Endpoint 上执行? |+| `svml.packages.lock` | 允许使用哪些 Author/Compute 包字节? |+| `svml.runtime-packages.lock` | 允许使用哪些特权 Runtime 包字节? |++最短的记法是:```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 svml-whisperx-prepare+SVML 说明做什么。+SVRUN 说明这次选什么。+Runtime Profile 说明在哪里做。```-在源码仓库内可使用 `node --run narratage -- ...`。仓库外的视频项目直接执行-`/path/to/narratage/narratage ... --package-root /path/to/narratage`;这个轻量入口不再启动 pnpm,源码、-SQLite、Artifact 和输出仍全部留在外部项目的 Runtime Profile root 下。+同一个 `main.svml` 可以对应很多份 `.svrun`:单独生成图片、渲染成片,或者复用已经认可的镜头,+都不需要修改作者对视频本身的表达。++## 4. 建立自己的项目++把视频项目和生成产物放在 Narratage 仓库之外。在项目目录里直接调用源码仓库提供的轻量启动器:++```bash+cd /path/to/my-video-## 三份输入+/path/to/narratage/narratage packages sync build.svrun \+ --runtime svml.runtime.json --root .-每一次 Build 都接受三份彼此独立的输入:+/path/to/narratage/narratage doctor svml.runtime.json+/path/to/narratage/narratage check main.svml \+ --runtime svml.runtime.json --root .+/path/to/narratage/narratage plan build.svrun \+ --runtime svml.runtime.json --root .+```-| 输入 | 各自负责什么 | 典型文件 |-|---|---|---|-| **Author Source** | 口播稿、模型选择、轨道构成、输出图 | `.svml` |-| **Run Source** | 要产出哪些输出、备选 candidates、satisfaction edges | `.svrun` |-| **Runtime Profile** | endpoints、凭据、并发 | `svml.runtime.json` |+启动器使用 Narratage 仓库已经安装好的依赖,但源码、SQLite 状态、Artifact 和输出都会留在你的项目里。+`packages sync` 根据 Run 闭包里的 imports 和 Runtime Profile 选择的 Adapter 生成两份包锁。-Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile 说明*在哪里做*。+需要完整 Runtime Profile 时,从+[`examples/talking-film-live`](https://github.com/hypit-ai/narratage/tree/main/examples/talking-film-live) 的结构开始:复制文件结构,+再换成自己的素材、Script、模型选择和凭据。-## 第一次图检查+## 5. Build 并取出结果-`talking-film-graph-check` 示例会编译一张完整的视频图 —— Script、Seedance、Speech、-WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。+在 `doctor`、`check` 和 `plan` 全部通过之后:```bash-node --run narratage -- check examples/talking-film-graph-check/main.svml \- --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+/path/to/narratage/narratage build build.svrun \+ --runtime svml.runtime.json \+ --build-id my-video-001 \+ --follow+```-node --run narratage -- plan examples/talking-film-graph-check/build.svrun \- --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+`build` 会持久化这次 Build、确保对应 Worker 可用,并只启动所选 Endpoint 声明的外部程序。+`--follow` 只是观察器;关掉它不会停止 Build。++```bash+/path/to/narratage/narratage status my-video-001 \+ --runtime svml.runtime.json++/path/to/narratage/narratage queue \+ --runtime svml.runtime.json --watch++/path/to/narratage/narratage get my-video-001 \+ --runtime svml.runtime.json \+ --name final.video \+ --to output/final.mp4+```++Runtime 会归档所有已经接受的中间 Record 和媒体。`get` 只负责把某个归档结果复制到便于人查看的位置,+不会决定哪些中间结果应该被保存。++## 真实 Build 可能使用的本地工具++只安装当前 Runtime Profile 真正选择的部分:++| 工具 | 什么时候需要 |+|---|---|+| `ffmpeg` / `ffprobe` | 使用本地媒体检查、归一化或 mux 时 |+| Python 3.10–3.13 与 `uv` | 使用本地 WhisperX 或 OpenCV 时 |+| Chromium | 本地 HyperFrames 渲染时由 Adapter 管理 |+| API 凭据 | 选择 KIE、Vertex、Xiaomi 或 AWS Endpoint 时 |++准备本地 Python 服务:++```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 svml-whisperx-prepare```-`check` 产出带类型的 Author Graph。`plan` 绑定 Author Graph 与 Run Graph,解析 Targets,-并输出冻结的 BuildPlan —— 其中包含 Scheduler 将会发出的每一个 Operation 与 Needs。花钱之前先检查它。+修改 Runtime Profile 后运行 `narratage doctor svml.runtime.json`。它会报告缺少的工具、凭据和+Endpoint 配置,但不会执行作者图。++## 接下来读什么-## 指南目录+可以按顺序理解完整创作路径,也可以直接进入正在修改的部分:-| 指南 | 主题 |+| 指南 | 你会学到什么 ||---|---|-| [Script](./quickstart/script.md) | Segment、Role Cue、Dual Text、Selection、Moment、文字投影 |-| [SVS 样式表](./quickstart/styles.md) | CSS 风格的 Recipe:film、caption、B-roll、text、speech、字体 |-| [媒体与生成](./quickstart/generation.md) | media:Image、media:Audio、estimate:Speech、Text Template、Seedance |-| [时序与装配](./quickstart/timing.md) | speech:Spine、whisperx:Alignment、ProgramSpace、SemanticMap |-| [字幕、Media、文字与音频](./quickstart/tracks.md) | Caption、Media、Typography 与 Audio Track 作者语法 |-| [Film 与渲染](./quickstart/composition.md) | film:Film、render:Video、完整流水线演练 |-| [Run Source 与 Build](./quickstart/run.md) | .svrun 语法、targets、复用、runtime profile、build 工作流 |+| [Script](./quickstart/script.md) | Segment、说话人、Dual Text、Selection 与 Moment |+| [SVS 样式表](./quickstart/styles.md) | 字幕、Media、文字与 Film 的可复用 Recipe |+| [媒体与生成](./quickstart/generation.md) | 图片、音频、Prompt Text 与显式模型组件 |+| [时序与装配](./quickstart/timing.md) | Speech Spine、WhisperX、ProgramSpace 与 SemanticMap |+| [Tracks](./quickstart/tracks.md) | Caption、Media、Typography 与 Audio Track |+| [Film 与渲染](./quickstart/composition.md) | 平级 Track 合成与显式渲染 |+| [Run Source 与 Builds](./quickstart/run.md) | Targets、复用、Runtime Profile、Build 与取回结果 |++如果使用编程 Agent,可以要求它使用仓库中的 `narratage` skill。Skill 遵循的仍然是同一套文件和命令,+不会创造另一套工作流。++## 名字的由来++*Narratage* 原本描述的是“叙述驱动的蒙太奇”:声音负责推动故事,画面围绕叙述组接。+这也是本项目最初的视频形态——文字是语义主轴,所有视觉内容以彼此平级的 Track 参与作品。diff --git a/examples/README.md b/examples/README.mdindex df821a1c..9395778a 100644--- a/examples/README.md+++ b/examples/README.md@@ -1,16 +1,23 @@# Examples-- [`talking-film-graph-check`](./talking-film-graph-check/README.md) compiles the complete- provider-free author graph through Speech, WhisperX, Caption, Media Track, Typography, Film and final render- requirements.-- [`talking-film-live`](./talking-film-live/README.md) executes the real paid two-take path with KIE,- local media processing, local WhisperX, Vertex Caption planning and local HyperFrames rendering.-- [`talking-head-aroll`](./talking-head-aroll/README.md) is the current four-take acceptance witness and- demonstrates a second Run that explicitly reuses historical shot Records as zero-input- Candidates without another KIE submission.-- [`talking-film-golden`](./talking-film-golden/README.md) is the larger authoring and visual design- fixture used while video packages remain pre-freeze.-- [`bootstrap`](./bootstrap/README.md) is the smallest official Markup/Script/SVS source-closure- check.+Choose an example by what you want to learn:-Generated assets, local Runtime databases and output media are ignored by Git.+| Example | Use it for | External work |+|---|---|---|+| [`bootstrap`](./bootstrap/README.md) | The smallest self-described `.svml` and imported `.svs` source | none |+| [`talking-film-graph-check`](./talking-film-graph-check/README.md) | A complete video graph and frozen plan | none |+| [`talking-film-live`](./talking-film-live/README.md) | A complete Runtime Profile and real two-take Build | KIE, WhisperX, Vertex and local HyperFrames |+| [`talking-head-aroll`](./talking-head-aroll/README.md) | Multiple generated takes and explicit reuse in a second `.svrun` | paid generation on the first Run |+| [`talking-film-golden`](./talking-film-golden/README.md) | A larger authoring reference with multiple speakers and B-roll | source reference only |++Start with `talking-film-graph-check`: both commands below are provider-free.++```bash+node --run narratage -- check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .++node --run narratage -- plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+```++Generated assets, local Runtime databases and output media stay outside version control.diff --git a/tools/repository-hygiene.test.mjs b/tools/repository-hygiene.test.mjsindex 0659ac53..4f0294db 100644--- a/tools/repository-hygiene.test.mjs+++ b/tools/repository-hygiene.test.mjs@@ -72,7 +72,7 @@ test("source distribution outside the mounted documentation contains no customertest("source distribution outside the mounted documentation contains no retired project identities", async () => {const retired = new RegExp(- String.raw`\b\x74\x77\x69\x6e\x69\x74\b|\b\x68\x79\x70\x69\x74\b|\b\x6d\x65\x67\x6e\x65\x74\x61\b`,+ String.raw`\b\x74\x77\x69\x6e\x69\x74\b|\b\x6d\x65\x67\x6e\x65\x74\x61\b`,"giu",);const failures = [];