videowright 0.1.0

package/skill/references/project_structure.md

@@ -0,0 +1,144 @@
+# Project Structure
+
+## Consumer repo layout
+
+A Videowright project follows this directory structure:
+
+```
+<repo-root>/
+├── videowright.config.ts           # project config (required)
+├── segments/                       # shared segment library
+│   ├── intro/
+│   │   └── index.ts                # one segment per folder
+│   ├── feature-cards/
+│   │   └── index.ts
+│   └── outro/
+│       └── index.ts
+├── components/                     # shared web components
+│   ├── animated-title/
+│   │   └── index.ts
+│   └── feature-card/
+│       └── index.ts
+├── transitions/                    # custom transition functions
+│   └── logo-morph.ts
+├── styles/                         # style folders
+│   ├── editorial-mono/
+│   │   ├── STYLE.md
+│   │   ├── tokens.css
+│   │   ├── brand.md
+│   │   ├── reference/
+│   │   │   ├── scenes.html
+│   │   │   └── animations.jsx
+│   │   └── sample/
+│   │       ├── title.ts
+│   │       ├── kinetic.ts
+│   │       └── ... (10 scene types)
+│   └── risograph/
+│       ├── STYLE.md
+│       └── tokens.css
+└── videos/                         # per-video folders
+    ├── demo/
+    │   ├── timeline.ts
+    │   ├── PLAN.md
+    │   ├── README.md               # optional
+    │   ├── voiceover_script/
+    │   │   └── script.md
+    │   └── audio/
+    │       ├── audio_plan.md
+    │       ├── originals/
+    │       │   ├── voiceovers/
+    │       │   │   └── v1/
+    │       │   │       ├── voiceover.ts    # typed Voiceover object
+    │       │   │       ├── audio.mp3       # audio file
+    │       │   │       ├── timing.json
+    │       │   │       └── provider_script.md
+    │       │   ├── sfx/            # slug-named subfolders
+    │       │   └── music/          # slug-named subfolders
+    │       └── tracks/
+    │           └── v1/
+    │               ├── track.ts    # typed AudioTrack object
+    │               ├── track.mp3   # rendered audio
+    │               └── plan_snapshot.md
+    └── launch_2026/
+        ├── timeline.ts
+        ├── PLAN.md
+        └── voiceover_script/
+            └── script.md
+```
+
+## File ownership rules
+
+### Shared (top-level directories)
+
+These directories are shared across all videos in the project:
+
+| Directory | Contains | Ownership |
+|---|---|---|
+| `segments/` | Segment modules. One folder per segment, each with an `index.ts`. | Any video can reference any segment. Do not duplicate segments for different videos. |
+| `components/` | Reusable web components used by multiple segments. | Shared across segments. Extract here when a visual element appears in more than one segment. |
+| `transitions/` | Custom transition functions. | Shared. Only create when a built-in transition (`fade`, `cut`, `slideLeft`, `slideRight`, `slideUp`, `slideDown`) does not fit. |
+| `styles/` | Style folders. One folder per style, each with `STYLE.md` and `tokens.css`. | Shared. Multiple styles can coexist. See [styles.md](styles.md). |
+
+### Per-video (`videos/<name>/`)
+
+Each video gets its own folder under `videos/`:
+
+| File | Purpose |
+|---|---|
+| `timeline.ts` | Timeline definition. Imports the style's `tokens.css`, defines segment order and transitions. Default-exports a `Timeline` object. |
+| `PLAN.md` | Working memory for the video. Design decisions, segment outline, script, append-only log. |
+| `voiceover_script/script.md` | Assembled VO script (generated by `videowright script --write`). Only present for videos with voiceover intent. |
+| `audio/` | Audio directory. Contains `audio_plan.md`, `originals/` (source voiceovers, SFX, music), and `tracks/` (rendered audio tracks). See [audio.md](audio.md). |
+| `audio/originals/voiceovers/<slug>/` | Voiceover folders. Each contains a `voiceover.ts` (typed Voiceover object), audio file, and optional provider timing/script files. See [audio/voiceover.md](audio/voiceover.md). |
+| `README.md` | Optional. Notes about the video for human readers. |
+
+Per-video files live **only** inside `videos/<name>/`. Do not put segments, components, or styles inside a video folder — those belong in the shared top-level directories.
+
+### Config
+
+`videowright.config.ts` lives at the repo root. It defines project-wide settings:
+
+```ts
+import { defineConfig } from 'videowright';
+
+export default defineConfig({
+  projectStructure: 'v1',
+  defaultStyle: 'editorial-mono',
+  defaults: {
+    resolution: [1920, 1080],
+    fps: 60,
+    aspectRatio: '16:9',
+  },
+});
+```
+
+See [types.md](types.md) for the full `Config` type.
+
+## Naming guidance
+
+### Segments
+
+- Use `kebab-case` for segment folder names: `feature-cards`, `intro`, `data-chart`.
+- The folder name is the segment's `id` — they must match.
+- Name segments by what they show, not which video they belong to. Good: `feature-cards`, `pricing-table`. Bad: `demo-slide-3`.
+
+### Videos
+
+- Use `snake_case` for video folder names: `demo_video`, `launch_2026_q1`.
+- A date prefix is suggested but not required: `2026_05_launch`.
+- The folder name is used in paths and references — keep it short and descriptive.
+
+### Styles
+
+- Use `kebab-case` for style folder names: `editorial-mono`, `swiss-console`, `risograph`.
+- The folder name is the style's slug — it must match the `slug` in `STYLE.md` frontmatter and the value in `defaultStyle` / `meta.style`.
+
+## The reuse rule
+
+Do not copy a segment to modify it for a different video. If two videos need the same visual with slight differences:
+
+- **Parameterize** the segment (use `mount` arguments, CSS variables, or data attributes to vary behavior).
+- **Extract shared parts** into a component in `components/`.
+- **Create a new segment** that composes the shared component differently.
+
+Any video can reference any segment in `segments/`. This is the primary reuse mechanism.

package/skill/references/setup.md

@@ -0,0 +1,109 @@
+# Setup
+
+Each input-gathering step is its own conversational turn. Do not stack questions.
+
+## When this is loaded
+
+You were routed here because the setup gate in SKILL.md is open: `videowright.config.ts` does not exist, or its `defaultStyle` field is missing or empty.
+
+This flow runs once per project. After it completes, the setup gate closes and SKILL.md skips this file on future invocations.
+
+## Preconditions: Verify install
+
+Before any setup work, verify that the Videowright installer was run successfully. Check all three of these conditions:
+
+1. `videowright` is in the project's `package.json` `dependencies` or `devDependencies`.
+2. `node_modules/videowright/` exists as a directory (i.e., `npm install` or equivalent was actually run).
+3. An instruction file contains a `<!-- videowright:start -->` marked region. Check `CLAUDE.md` if it exists; otherwise check `AGENTS.md`.
+
+If **any** of these checks fail, stop and tell the user exactly:
+
+> Videowright is not fully installed in this project. Visit https://github.com/scosman/videowright for install instructions.
+
+Do not attempt repair. Do not proceed with setup. The user should re-run the installer.
+
+## Gate semantics
+
+| Config state | What to do |
+|---|---|
+| `videowright.config.ts` does not exist | Full setup. Run all steps below. |
+| File exists but `defaultStyle` is missing or empty string | Partial setup. Skip directory scaffolding (step 2). Jump to step 3 (pick first style) and continue from there. |
+| File exists and `defaultStyle` is set to a slug | Gate is closed. You should not be here. Return to SKILL.md intent dispatch. |
+
+A partial setup means the user started setup previously but did not finish picking a style. Resume where they left off -- never re-scaffold files that already exist.
+
+## Steps
+
+### Step 1 -- Confirm intent
+
+Ask: "I'll set up a Videowright project here. This will create the directory structure, pick a visual style, and then we'll create your first video together. OK to proceed?"
+
+If the user says no, stop.
+
+### Step 2 -- Scaffold directories and gitignore
+
+Create the consumer repo directory structure:
+
+```
+<repo-root>/
+├── segments/               # shared segment library
+├── components/             # shared web components
+├── transitions/            # shared transition functions
+├── styles/                 # style folders (populated in step 3)
+└── videos/                 # per-video folders (populated after handoff to new_video.md)
+```
+
+Only create directories that do not already exist. Do not create any files inside these directories.
+
+**Ensure `.env` is in `.gitignore`.** Check if a `.gitignore` file exists at the repo root. If it does not exist, create one. In either case, verify that `.env` is listed as an ignored pattern. If it is not present, add `.env` to the file. This prevents API keys and other secrets from being committed to the repository.
+
+### Step 3 -- Pick first style
+
+The first style is required. Without it, there are no design tokens and any video will lack visual identity. There is no "skip and add later" path.
+
+This is its own conversational turn -- do not combine with any other question.
+
+Dispatch to [setup_new_style.md](setup_new_style.md) with:
+
+- `setAsDefault: false` -- do **not** let the style flow write `videowright.config.ts`. The config does not exist yet; Step 4 writes it with the chosen slug.
+- `copySample: true` -- install the sample segment into `segments/<slug>-sample/index.ts`. The sample segment showcases the chosen style.
+
+Wait for the style creation flow to complete. Record the chosen slug for Step 4.
+
+### Step 4 -- Write config
+
+Write `videowright.config.ts` at the repo root (if it does not already exist from partial setup):
+
+```ts
+import { defineConfig } from 'videowright';
+
+export default defineConfig({
+  projectStructure: 'v1',
+  defaultStyle: '<slug from step 3>',
+  defaults: {
+    resolution: [1920, 1080],
+    fps: 60,
+    aspectRatio: '16:9',
+  },
+});
+```
+
+If the file already exists (partial setup), only update `defaultStyle`.
+
+### Step 5 -- Hand off to first video
+
+Tell the user exactly:
+
+> Project configured. Starting first video.
+
+Then immediately load [new_video.md](new_video.md) and follow its intake flow. Do **not** add any transition question or suggestion between setup and new_video — `new_video.md` handles all intake (purpose, audience, audio intent, etc.) as part of its own flow.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| `videowright` not in `package.json` | Stop with install instructions. Do not proceed. |
+| Config exists but `defaultStyle` is empty | Resume at step 3 (pick style). Skip scaffolding. |
+| Some directories already exist | Skip creating them. Do not overwrite existing files. |
+| User declines to proceed at step 1 | Stop. Do not scaffold anything. |
+| User wants to skip style selection | Do not allow. Explain that the style is required for videos to have visual identity. Offer Mode 4 (pick a built-in pack) as the fastest path. |

package/skill/references/setup_new_style.md

@@ -0,0 +1,158 @@
+# Setup New Style
+
+## When this is called
+
+This is the shared style-creation flow. You were dispatched here from one of:
+
+- **[setup.md](setup.md)** -- picking the first style during initial project setup.
+- **[new_video.md](new_video.md)** -- user wants a different style for a specific video.
+- **[styles.md](styles.md)** -- user explicitly wants to add a style or change the default.
+
+The caller passes two flags:
+
+| Flag | Meaning | Default by caller |
+|---|---|---|
+| `setAsDefault` | Write this slug into `videowright.config.ts` as `defaultStyle` | `false` for setup (setup.md writes config itself), `false` for per-video styles, caller's choice for "change default style" |
+| `copySample` | Install sample segments at `segments/<slug>-sample-<scene>.ts` demonstrating the style | `true` during initial setup, `false` when adding mid-project (unless user asks) |
+
+## Flow
+
+Present this message verbatim — do not rephrase or regenerate it:
+
+<!-- Maintainer note: the built-in pack list below is baked in. Adding or removing a pack under skill/assets/styles/ requires updating this list. -->
+
+> How would you like to define your visual style?
+>
+> 1. **Generate from reference docs** — provide a marketing page, brand guide, CSS file, or other document and I'll derive a style from it.
+> 2. **Copy from a previous Videowright project** — provide a path to an existing project's style folder.
+> 3. **Describe it** — give me a short description and I'll generate a style. Example: "Neo-brutalist, Inter font, yellow accent color."
+> 4. **Built-in style pack** — pick one of these ready-made styles:
+>    - **Editorial Mono** — Black ink on cream paper. One red accent. Reads like a magazine.
+>    - **Swiss Console** — Strict 12-column grid. Hairline rules. Tabular numerals. Micro-labels everywhere.
+>    - **Neon Terminal** — CRT terminal interface. Mono throughout. Phosphor-green on near-black, stepped motion.
+>    - **Motion Engineering** — Aerospace HUD / blueprint. Charcoal canvas, cyan-white type, amber accent. Dimension lines and crosshairs.
+>    - **Iso Diagram** — Pencil-and-paper explainer aesthetic. Hand-drawn lines, pastel fills, isometric drawings.
+>    - **Risograph** — Two-color screen-print on warm paper. Pink + ink-blue, visible grain, stop-motion cadence.
+
+### Mode 1 -- Ingest reference material
+
+The user has a brand deck, CSS file, Figma export, paste-able content, local files/folders, or a URL pointing to an existing visual identity.
+
+1. Prompt: "Drop the content in chat, point me at local files or folders, or paste a URL. I'll extract the visual identity."
+2. Read whatever the user provides:
+   - **Pasted content or local files:** read directly.
+   - **Folder path:** read files from that path in place. Do **not** create a new top-level directory for source material.
+   - **URL:** fetch the page content and extract visual tokens (colors, typography, spacing, motion patterns) from the HTML/CSS/design assets.
+3. Transform the input into `styles/<slug>/`:
+   - Draft `STYLE.md` with frontmatter (`title`, `slug`, `picker_description`, `font_sources`) and body (aesthetic rules, motion vocabulary, don'ts).
+   - Draft `tokens.css` with `:root` custom properties. Always include the 6 recommended tokens (`--color-bg`, `--color-fg`, `--color-accent`, `--font-display`, `--font-body`, `--font-mono`). If the source material does not define values for all 6, pick reasonable defaults from the source's palette/typography and flag which ones you inferred.
+   - If `copySample` is true, also draft sample segments demonstrating the style. Each sample lives at `styles/<slug>/sample/<scene>.ts` and will be copied to `segments/<slug>-sample-<scene>.ts` in the final actions step.
+4. Read back a brief overview: "Here's what I built from your input: [summary]. Look good or any changes?"
+5. Iterate until the user confirms.
+
+### Mode 2 -- Copy from a previous Videowright project
+
+The user provides a path to another Videowright project (the "source project").
+
+1. Read `<source-project>/styles/` and list available styles (by reading `STYLE.md` frontmatter in each subfolder).
+2. If multiple styles exist in the source project, ask the user which one to copy. If only one, confirm it.
+3. Read `<source-project>/styles/<slug>/STYLE.md` and `<source-project>/styles/<slug>/tokens.css`.
+4. Write them to `styles/<slug>/STYLE.md` and `styles/<slug>/tokens.css` in this project (the current working directory). The slug is preserved from the source.
+5. If `copySample` is true and `<source-project>/styles/<slug>/sample/` exists, copy it to `styles/<slug>/sample/` in this project, then copy each `sample/<scene>.ts` to `segments/<slug>-sample-<scene>.ts` in this project.
+6. Show the user a summary of what was copied and ask: "Look good or any changes?"
+7. Iterate until confirmed.
+
+### Mode 3 -- Describe in chat
+
+The user types a description: "Modern look using Inter, white background, #e0e230 accent, sans-serif headers, monospace for code."
+
+1. Draft `STYLE.md` and `tokens.css` from the description.
+   - Always include the 6 recommended tokens. Infer values from the description; flag any you guessed.
+   - Write aesthetic rules, motion vocabulary, and don'ts that match the described feel.
+   - Pick Google Fonts URLs for `font_sources` based on the described typography.
+   - If `copySample` is true, also draft sample segments demonstrating the described style. Each sample lives at `styles/<slug>/sample/<scene>.ts` and will be copied to `segments/<slug>-sample-<scene>.ts` in the final actions step.
+2. Read back a brief overview and ask: "Look good or any changes?"
+3. Iterate until confirmed.
+
+### Mode 4 -- Pick a built-in style pack
+
+Choose one of the built-in packs shipped with Videowright. The pack list and descriptions are already shown in the question above — no need to read frontmatter at runtime.
+
+1. The user picks a pack from the list presented in the question. Confirm the choice.
+2. Copy the entire `node_modules/videowright/skill/assets/styles/<slug>/` folder into the consumer repo at `styles/<slug>/`. This includes `STYLE.md`, `tokens.css`, `brand.md`, `reference/scenes.html`, `reference/animations.jsx`, and `sample/*.ts`. The slug is locked to the pack's slug -- no rename.
+3. If `copySample` is true, copy each `styles/<slug>/sample/<scene>.ts` into `segments/<slug>-sample-<scene>.ts` (flat file directly under `segments/`). If any destination already exists, skip that file and report it to the user.
+
+After any mode, the user's copy in `styles/<slug>/` is the source of truth. The skill does not auto-update it from `skill/assets/` later.
+
+## Final actions
+
+After the style is created (any mode):
+
+1. **Modes 1 and 3 only:** Write `styles/<slug>/STYLE.md` and `styles/<slug>/tokens.css` to the consumer repo. (Mode 2 and Mode 4 already copied these in their respective steps.)
+2. If `copySample` is true, copy each `styles/<slug>/sample/<scene>.ts` to `segments/<slug>-sample-<scene>.ts`. The sources stay in the style folder as references; the copies in `segments/` are what videos use. If any destination already exists, skip that file and tell the user.
+3. If `setAsDefault` is true, set `defaultStyle: '<slug>'` in `videowright.config.ts`.
+4. Confirm to the user what was created and where.
+
+## STYLE.md shape
+
+```markdown
+---
+title: <Display Name>
+slug: <kebab-case-slug>
+picker_description: <One-liner for the picker>
+font_sources:
+  - <Google Fonts URL>
+  - <Google Fonts URL>
+---
+
+# Style: <Display Name>
+
+## When to use
+[1-2 sentences on when this style is the right choice]
+
+## Aesthetic rules
+- [Bullet rules the agent honors when authoring segments in this style]
+- [Typography, color, motion density, layout patterns]
+- [Sizing guidance: specify minimum font sizes for headings and body text, container widths, and how much of the frame content should fill. Defaults from authoring_segment.md apply (body 36px+, headings 64px+, containers 80-90%+ width) — override here only if the style demands different sizing.]
+
+## Motion vocabulary
+- [How elements enter, exit, and transition]
+- [Timing curves, duration ranges, choreography patterns]
+
+## Don'ts
+- [Things to avoid when using this style]
+```
+
+**Sizing rules in STYLE.md.** Every style's aesthetic rules section should specify how content fills the frame. The baseline from [authoring_segment.md](authoring_segment.md) applies unless the style explicitly overrides it: body text 36px+ at 1080p, headings 64px+, primary containers spanning 80-90%+ of the video width. Styles that intentionally use generous whitespace (e.g., editorial layouts) should document that choice and still ensure text remains legible.
+
+## tokens.css shape
+
+```css
+:root {
+  /* Colors */
+  --color-bg: #ffffff;
+  --color-fg: #1a1a1a;
+  --color-accent: #0066ff;
+
+  /* Typography */
+  --font-display: 'Inter', sans-serif;
+  --font-body: 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  /* Pack-specific tokens below */
+}
+```
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| Slug already exists in `styles/` | Ask the user: overwrite, pick a different name, or cancel. |
+| Sample segment already exists in `segments/` | Skip that file; tell the user which files were skipped. |
+| User pastes a huge style guide into chat (Mode 1) | Prompt for a folder path on disk instead. Do not create a new top-level directory for source material. |
+| User's source material has no typography info | Pick a sensible default (Inter for body/display, JetBrains Mono for mono). Flag the choice. |
+| User's source material has no color info | Pick neutrals (white bg, dark fg, blue accent). Flag the choice. |
+| No built-in packs exist yet (Mode 4) | Tell the user no built-in packs are available; suggest Mode 1 or Mode 3 instead. |
+| `font_sources` URLs are not Google Fonts | Accept any URL. Note that self-hosted fonts are not bundled -- the URL must be accessible at runtime. |
+| User provides a URL in Mode 1 | Fetch the page, extract CSS/design tokens from the markup, and proceed with style creation. If the URL is inaccessible, tell the user and suggest pasting the content directly. |
+| Source project path in Mode 2 does not contain a `styles/` folder | Tell the user the path does not appear to be a Videowright project. Ask them to check the path. |

package/skill/references/styles.md

@@ -0,0 +1,154 @@
+# Styles
+
+## When this is loaded
+
+You were routed here from the intent dispatch table. Relevant intents:
+
+- **Change the default style** — edit config and optionally cascade to existing videos.
+- **Match a past video's style** — extract the style from an existing video and apply it.
+- **General style questions** — how styles work, how segments consume tokens, how to add or swap styles.
+
+To **create a new style**, load [setup_new_style.md](setup_new_style.md).
+
+## Style folder structure
+
+Each style lives in `styles/<slug>/` at the consumer repo root. The slug is a kebab-case name that matches the folder name, the `slug` field in `STYLE.md` frontmatter, and the value written into `defaultStyle` or `meta.style`.
+
+```
+styles/
+├── editorial-mono/
+│   ├── STYLE.md            # description, rules, frontmatter (title, slug, picker_description, font_sources)
+│   ├── tokens.css           # CSS custom properties on :root
+│   ├── brand.md             # human-readable token rationale
+│   ├── reference/
+│   │   ├── scenes.html      # rendered scene mockups, browsable in a web browser
+│   │   └── animations.jsx   # motion vocabulary mockups
+│   └── sample/              # reference samples (one per scene type, stays here as templates)
+│       ├── title.ts
+│       ├── section.ts
+│       ├── kinetic.ts
+│       ├── bullet.ts
+│       ├── stat.ts
+│       ├── feature.ts
+│       ├── grid.ts
+│       ├── ui-showcase.ts
+│       ├── content.ts
+│       └── cta.ts
+└── risograph/
+    ├── STYLE.md
+    ├── tokens.css
+    └── ...
+```
+
+The `sample/` folder inside a style contains one TypeScript file per scene type. When installed, samples are copied to `segments/<slug>-sample-<scene>.ts` (flat files under `segments/`) for use in videos. The sources stay in the style folder as references.
+
+**Required files per style:**
+
+| File | Purpose |
+|---|---|
+| `STYLE.md` | Frontmatter (`title`, `slug`, `picker_description`, `font_sources`) + body (aesthetic rules, motion vocabulary, don'ts). The agent reads this when authoring segments in this style. |
+| `tokens.css` | CSS custom properties on `:root`. The only required token format. Imported by timeline.ts. |
+
+There is no `styles/default/`. Every style has a real name. Multiple styles can coexist in one repo.
+
+## Recommended token set
+
+Built-in packs use these tokens. User-authored styles may use any tokens they want — there is no enforced set — but following these conventions enables cross-style compatibility.
+
+| Token | Purpose |
+|---|---|
+| `--color-bg` | Page background |
+| `--color-fg` | Default text |
+| `--color-accent` | Primary accent / call-out |
+| `--font-display` | Headlines |
+| `--font-body` | Body copy |
+| `--font-mono` | Code / monospace |
+
+Packs may define additional tokens beyond these six.
+
+## How videos consume styles
+
+### Timeline.ts top-of-file import
+
+The active style's `tokens.css` is loaded via a CSS import at the top of the video's `timeline.ts`:
+
+```ts
+// videos/my_video/timeline.ts
+import '../../styles/editorial-mono/tokens.css';  // path relative to this file
+import type { Timeline } from 'videowright';
+
+const timeline: Timeline = {
+  meta: {
+    title: 'My Video',
+    // style: 'editorial-mono',  // optional — falls back to config defaultStyle
+  },
+  segments: [...],
+};
+export default timeline;
+```
+
+The import path is relative to the video's `timeline.ts` location. Adjust the `../../` prefix to match the actual directory depth.
+
+Vite (the dev server) and any bundler resolves the CSS import natively. The CSS is injected into the page; `:root` custom properties cascade through the player's DOM.
+
+**Keep the import in sync.** The top-of-file import must always match `meta.style ?? config.defaultStyle`. When you change the style for a video, update both the import path and `meta.style` (if set).
+
+### Per-video override
+
+Set `meta.style` on the timeline to override the project default for one video:
+
+```ts
+import '../../styles/risograph/tokens.css';
+import type { Timeline } from 'videowright';
+
+const timeline: Timeline = {
+  meta: {
+    title: 'January 2026 Launch',
+    style: 'risograph',  // overrides config defaultStyle
+  },
+  segments: [...],
+};
+export default timeline;
+```
+
+### Segments
+
+Segments use CSS variables directly: `var(--color-accent)`, `var(--font-display)`, etc. Segments do **not** import tokens themselves — the timeline-level import provides the variables at runtime via `:root` custom properties.
+
+This means one segment can be reused across videos with different styles — the CSS variables resolve to whatever the timeline imported.
+
+Segments may freely import additional CSS from any style folder if they want to mix styles or pull in supplementary resources. This is "off-book" and welcomed.
+
+### No per-segment style field
+
+There is no `style` field on segment entries. Segments are free-form: import any tokens, write any CSS, ignore the project style entirely. The "style" of a video is a directive the author honors via the segments they write — it is not enforced by the lib.
+
+## Changing the default style
+
+To change the project's default style:
+
+1. Edit `videowright.config.ts` — set `defaultStyle` to the new slug.
+2. Verify `styles/<new-slug>/tokens.css` exists. If not, create the style first via [setup_new_style.md](setup_new_style.md).
+3. Ask the user whether to update existing videos:
+   - **Yes**: scan `videos/*/timeline.ts`. For each video that does **not** have an explicit `meta.style` override, update the top-of-file CSS import to point to the new style. Leave videos with `meta.style` set completely untouched — an explicit override is an intentional pin.
+   - **No**: only new videos get the new default. Existing videos keep their current imports.
+
+## Matching a past video's style
+
+When the user asks to "match the look of \<past video\>":
+
+1. Read the past video's `PLAN.md` — check the Style section for the slug and any notes.
+2. Read `styles/<slug>/STYLE.md` — absorb the aesthetic rules and motion vocabulary.
+3. Read one or two representative segments from the past video to understand how the style was applied in practice.
+4. Apply the same style to the new video: set the same slug in `meta.style` (or confirm `defaultStyle` matches), use the same top-of-file import, and author segments following the same aesthetic rules.
+
+If the style folder no longer exists (deleted or renamed), offer to recreate it via [setup_new_style.md](setup_new_style.md) using the past video's segments as the reference input (Mode 1).
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| `defaultStyle` references a slug with no `styles/<slug>/` folder | Error with a clear message naming the missing slug and expected path. Offer to create it via [setup_new_style.md](setup_new_style.md). |
+| User wants to add a style mid-project | Route to [setup_new_style.md](setup_new_style.md) with `setAsDefault: false` by default. |
+| Timeline import path and `meta.style` are out of sync | Fix the import to match `meta.style ?? config.defaultStyle`. |
+| User asks "what styles do I have?" | List folders in `styles/` and read each `STYLE.md` frontmatter. |