Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: make the first Narratage workflow clear

kashorinff64c17bcb4e
diff --git a/README.md b/README.md
index 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:
```bash
cd /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.ts
index 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.md
index 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, Runtime
and 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 the
current `@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 records
diff --git a/docs/index.md b/docs/index.md
index b2dfee51..8ea1e720 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,13 +3,25 @@ layout: home
hero:
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 started
link: /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.md
index 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.md
index 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 targets
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 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 page
covers Caption, Media, Typography and Audio Track authoring.
diff --git a/docs/zh/index.md b/docs/zh/index.md
index 658b8ab1..59576a9c 100644
--- a/docs/zh/index.md
+++ b/docs/zh/index.md
@@ -3,13 +3,25 @@ layout: home
hero:
name: "Narratage"
+ text: "写下故事,编译视频。"
+ tagline: "面向 AI 视频生产的语义化图系统。作者意图保持可读,生成、定位、Track 与渲染由可替换的包完成。"
actions:
- theme: brand
text: 快速开始
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.md
index 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.md
index 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.mjs
index 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 customer
test("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 = [];