@bycrux/montaj-skills 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @bycrux/montaj-skills
+
+Transport-agnostic **Montaj domain skills** — the prose that teaches an agent
+*what* Montaj can do and *how to reason* about it, with zero assumptions about
+*how* the agent talks to a Montaj server.
+
+This bundle is published from the Montaj monorepo. The canonical source lives at
+`/skills/<name>/SKILL.md`; the files shipped here are derived copies, staged at
+pack time by `scripts/stage.mjs`.
+
+## What's in the bundle
+
+Flat Markdown files:
+
+| File | Source skill | What it covers |
+| --- | --- | --- |
+| `skills/select-takes.md` | `select-takes` | Choosing the best takes from raw footage |
+| `skills/overlay.md` | `overlay` | Placing graphic/text overlays on a render |
+| `skills/write-overlay.md` | `write-overlay` | Authoring the copy that goes into overlays |
+| `skills/image-search.md` | `image-search` | Sourcing imagery for a project |
+| `contract.md` | `_contract` | The **vocabulary contract** (see below) |
+
+Deliberately **excluded**: the `native` and `mcp` skills and the root
+`SKILL.md`. Those describe a specific transport and host wiring — they are not
+part of the portable domain bundle.
+
+## The vocabulary contract
+
+`contract.md` defines the shared vocabulary the domain skills speak: the nouns
+(projects, takes, overlays, media…) and the verbs/operations the agent invokes.
+The domain skills are written *against* this contract — they say "do operation
+X" without saying which HTTP route, MCP tool, or CLI call performs it.
+
+## Consumers MUST supply their own interface skill
+
+**This package ships domain knowledge and the contract only — no transport.**
+Montaj intentionally does not bundle an interface skill here.
+
+To use these skills, a consumer must provide its **own interface skill** that
+*implements* the vocabulary contract — mapping each operation in `contract.md`
+to a concrete call (an HTTP request to a Montaj server, an MCP tool invocation,
+a CLI command, etc.). The domain skills + contract + your interface skill
+together form a working agent. Without an interface skill, the domain skills
+have no way to actually reach a Montaj instance.
+
+## Versioning / publishing
+
+Published as `@bycrux/montaj-skills` to the public npm registry, tag-gated on
+`montaj-skills-v*`. The staged files are regenerated on every pack via the
+`prepack` script, so the published tarball always reflects `/skills` at the
+tagged commit.

package/contract.md

@@ -0,0 +1,50 @@
+---
+name: _contract
+description: "The shared vocabulary that domain skills use to name Montaj operations. Domain skills phrase every Montaj interaction as one of these verbs; an interface skill defines how each verb is actually performed. Load this to learn the canonical verbs before authoring or reading a domain skill."
+---
+
+# The Vocabulary Contract
+
+Montaj's skills are split into **domain skills** (what to do — transport-agnostic) and **interface skills** (how Montaj is reached — native CLI/HTTP here, or a consumer's remote interface in another repo). This document is the small, stable vocabulary the two sides share.
+
+A **domain skill** describes creative/editing work in terms of the canonical verbs below — and nothing else. An **interface skill** defines HOW each verb is performed on a particular transport. The domain skills never need to know which interface is in play.
+
+This is a contract written for an LLM reader: it is prose conventions, not a strict schema. Phrase things naturally, but stay inside these verbs.
+
+## The canonical verbs
+
+Each Montaj interaction is exactly one of these:
+
+- **run step `<name>` with `<args>`** — invoke a Montaj step and use its output. Steps are the core compute units: e.g. `waveform_trim`, `rm_nonspeech`, `transcribe`, `crop_spec`, `virtual_to_original`, `search_images`, `fetch_image`. (Authoring an overlay is NOT a step — overlays are written as files and saved into the project.)
+- **read the project** — get the current project state: clips, tracks, settings.
+- **save the project (delta)** — persist only the fields you changed. See the discipline below; this verb is never "save the whole thing I had cached."
+- **write a file `<path>` `<contents>`** — create or overwrite a workspace file (overlay JSX, fetched images, assets).
+- **read a file `<path>`** — read a workspace file back.
+- **log `<message>`** — emit operator-visible progress.
+
+## Save discipline (domain rule, transport-neutral)
+
+Saving the project is always **GET-fresh → merge → save**:
+
+1. **read the project** immediately before saving — get the current state right now.
+2. **merge** only your changed fields into that fresh state.
+3. **save the project (delta)** with those fields.
+
+Never save from a stale cached body. The operator may be editing the project concurrently, so a body you read minutes ago can clobber their work. Re-read every time, even if you "just" read it.
+
+## Two hard rules
+
+**No transport language.** Domain skills MUST phrase every Montaj interaction as one of the verbs above and MUST NOT name a transport. No `localhost`, no port numbers, no `montaj run`, no `PUT /api/...`, no `curl`, no reading or writing `project.json` directly. If a domain skill mentions a URL, a port, an HTTP method, or a literal on-disk project file, it has leaked the transport and is wrong. The interface skill owns all of that.
+
+**Name-based sub-skill references.** Refer to other skills by name, not by file path — e.g. "load skill `write-overlay`", not `skills/write-overlay/SKILL.md`. The reader resolves the name; the path may differ per interface.
+
+## Coverage note
+
+These verbs are sufficient for the Phase-1 domain skills:
+
+- **select-takes** — run step `crop_spec`, run step `virtual_to_original`; read the project.
+- **overlay** — read the project; save the project (delta); load skill `write-overlay`.
+- **write-overlay** — save the project (delta); write a file (the JSX); reference asset paths via written/read files.
+- **image-search** — run step `search_images`, run step `fetch_image`; write a file / read a file.
+
+If a future domain skill needs an operation not on this list, extend this contract first — do not let a domain skill invent its own transport-specific phrasing.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@bycrux/montaj-skills",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "skills",
+    "contract.md",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node scripts/stage.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/image-search.md

@@ -0,0 +1,71 @@
+---
+name: image-search
+description: "Find and download real images from the web — people, logos, brand/event stills, B-roll — to add as overlay image cards or project assets. Load when the prompt asks to source or insert images (e.g. 'add a photo of X', 'find images of the IPO', 'pull a shot of the factory')."
+---
+
+# Image Search
+
+Sourcing real imagery is a two-step pipeline: **`search_images`** finds candidate URLs, **`fetch_image`** downloads the one you pick to a workspace path. From there the image becomes an overlay image card (load skill `overlay`) or a project asset.
+
+Use this when the editing prompt asks for outside imagery — a person ("a photo of Elon Musk"), an event ("the IPO"), a logo, a brand still, or B-roll the footage doesn't contain. Never fabricate an image path or hotlink a remote URL into the project — always run step `fetch_image` to a real local file first (the preview player and render engine read local files).
+
+## Step 1 — `search_images`
+
+Run step `search_images` with the following args. Returns candidate results; no download is performed.
+
+| Arg | Default | Notes |
+|-----|---------|-------|
+| `query` | — | Search string. Be specific: `"Elon Musk portrait 2025"` beats `"elon"`. |
+| `provider` | `commons` | `commons` · `sportsdb` · `web` (see below) |
+| `limit` | `10` | Max results, capped at 30 |
+
+Output: `{ "results": [ { title, url, width, height, mime, license, artist, source, thumbnail? } ] }`
+`url` is always an HTTPS original (so the downstream `fetch_image` step accepts it).
+
+### Providers
+
+- **`commons`** (Wikimedia Commons, **keyless**) — license-clean, well-labeled. First choice for historical figures, landmarks, public-domain/CC imagery, and anything not time-sensitive.
+- **`sportsdb`** (TheSportsDB, **keyless**) — team badges / escudos. Use for sports crests.
+- **`web`** (open-web Google Images via SerpApi, **needs a key**) — broadest coverage. Use for current events, specific living people, brand/product shots, and anything Commons won't have. License is reported `"unknown"` — web results are **not** license-filtered; editorial use is the caller's judgment.
+
+Pick the **narrowest provider that will have the subject.** Reach for `web` only when `commons` won't cover it (recent news, a specific private individual, a current product).
+
+If the key is missing the step fails — tell the human to set up their SerpApi key via the native interface.
+
+## Step 2 — `fetch_image`
+
+Run step `fetch_image` with the following args. Downloads one HTTPS URL to a workspace path. Private/internal IPs are blocked; non-image and oversized responses are rejected.
+
+| Arg | Default | Notes |
+|-----|---------|-------|
+| `url` | — | HTTPS URL from a search result's `url` field |
+| `out` | — | Destination path. Use `<project>/assets/<name>.jpg` |
+| `max-bytes` | 25 MiB | Size cap |
+
+Output: `{ "path": "/abs/path/to/file.jpg" }`. Some hosts return `403` to non-browser fetches — if one fails, run step `fetch_image` with the next candidate instead of fighting it.
+
+## Picking the right image
+
+Search returns more than you need. Before committing:
+
+1. **Right subject** — read the `title` and dimensions. For a named person or specific event, confirm it's actually them/it, not a lookalike or a generic stock shot.
+2. **High enough resolution** — prefer ≥1000px on the long edge for full-frame cards. Tiny thumbnails upscale badly on 4K output.
+3. **Clean frame — verify visually.** After fetching, **look at the file** (read it as an image, or run step `analyze_media` with a "is there burned-in text or a watermark?" prompt). **Reject** images with burned-in captions, news-chyron bars, watermarks, logos stamped across them, or collages. Plain, uncluttered shots composite far better behind text overlays. This matters most for `web` results, which are unfiltered.
+4. **Fetch 1–2 backups** per subject when the first pick is uncertain — hosts 403, or the image turns out cluttered.
+
+## Where the image goes
+
+- **As an overlay image card** — the usual choice for a B-roll insert synced to a beat. Author/point a `photo_card`-style JSX overlay at it and pass the local path via `props`. Load skill `overlay` and load skill `write-overlay`.
+- **As a project asset** — add to `project.assets[]` (`{ id, type: "image", src, name }`) so it's tracked and reusable.
+
+Always use the **local fetched path** (absolute), never the remote URL.
+
+## Worked example
+
+```
+1. Run step `search_images` with {query:"Elon Musk portrait 2025", provider:"web", limit:6}
+2. Eyeball results → pick a clean ≥1500px original
+3. Run step `fetch_image` with {url:"https://…/elon.jpg", out:"<project>/assets/elon_musk.jpg"}
+4. Read the downloaded file → confirm subject + no watermark/chyron
+5. Add an image-card overlay (props.src = the fetched path) → load skill `overlay`
+```

package/skills/overlay.md

@@ -0,0 +1,110 @@
+---
+name: overlay
+description: "Agent-authored workflow task: decide what overlays to write, author the JSX, and add them to the project's overlay track. Load this when you hit montaj/overlay in a workflow."
+step: true
+subskills: "write-overlay"
+---
+
+# Overlay
+
+`montaj/overlay` is an agent-authored task — no CLI step, no API call. You decide what overlays the video needs, write the JSX files, and add them to the project's visual tracks.
+
+**Before writing any JSX, load skill `write-overlay`** — it contains the full JSX authoring reference (globals, `interpolate`/`spring` utilities, canvas rules, examples).
+
+## Sub-skills
+
+| Name | When to load |
+|------|--------------|
+| `write-overlay` | Before writing any JSX overlay — globals, `interpolate`/`spring` utilities, canvas rules, examples. |
+| `image-search` | When the prompt asks to source outside imagery (a photo of a person, a logo, an event/B-roll still) — find via `search_images` + download via `fetch_image`, then place as an image-card overlay. |
+
+---
+
+## Process
+
+### 1. Read the editing prompt and transcripts
+
+The prompt tells you the tone and intent. The transcript tells you the moments worth annotating. Read both before deciding what to write.
+
+### 2. Decide what overlays to write
+
+Ask: what does this video need that isn't already in the footage? Common answers:
+
+- **Opening hook** (0–3s) — almost always right for social content. A punchy text statement that sells the video before the viewer decides to scroll.
+- **Lower-thirds** — speaker name, context, stat callouts. Tied to specific transcript moments.
+- **Logo/watermark** — if assets include a logo, add it as a persistent or bookend overlay.
+- **Stat cards** — when the speaker cites a number ("33 million views"), a card reinforces it visually.
+- **Image cards / B-roll stills** — when the speaker names a person, company, event, or thing the footage doesn't show ("Elon Musk", "the IPO", a specific welder), a real photo synced to that beat lands hard. **If the prompt asks you to source images** ("add a photo of X", "find images of the IPO"), load skill `image-search` to find them via `search_images` and download via `fetch_image`, then add each as an image-card overlay (pass the local fetched path via `props`).
+
+If the prompt says "no overlays" — write nothing. Don't add an opening hook anyway.
+
+### Visual style defaults
+
+**Plain text directly on video is almost always the right call.** Skip the card. Skip the frosted glass. Big, bold text sitting right on the footage is more dynamic and feels native — not slapped on top.
+
+- **Go large** — 96–160px is a starting point, not a ceiling. If it looks a little too big, it's probably right. Small text gets scrolled past.
+- **No backgrounds** — avoid dark cards, frosted panels, and semi-transparent boxes unless the prompt asks for them. A text shadow (`textShadow: '0 2px 16px rgba(0,0,0,0.9)'`) is enough to ensure legibility on any footage without boxing the text in.
+- **Covering the face is fine** — text is more important than an unobstructed view of the speaker. Don't shrink or reposition text just to avoid the face.
+- **Match the energy of the speech** — fast, punchy delivery gets tight entrance animations (4–6 frames). Slower, deliberate speech gets a smoother slide or fade (10–15 frames).
+- **Use color sparingly** — one accent color maximum. White text with a colored word or icon reads better than multi-color text.
+- **Avoid the bottom ~350px** — that's where captions render and where platform UI lives (TikTok progress bar, Instagram controls). Keep `bottom` values above 350px, or use `top`-anchored placement instead.
+- **Avoid the right ~200px** — TikTok and Instagram stack action buttons (like, comment, share, follow) down the right edge. Don't push text or icons into that zone.
+
+### 3. Tie overlays to the transcript
+
+Use word-level timings from the transcript JSON to sync overlays to speech. An overlay that appears when the speaker says the word it displays lands harder than one that floats at an arbitrary time.
+
+### 4. Write the JSX files
+
+One JSX file per overlay component. Save to `overlays/<name>.jsx` in the project directory.
+
+**There are no built-in templates.** Every overlay is custom JSX. Style it to match the editing prompt — a "dark, cinematic" prompt gets different typography than "energetic TikTok vibes."
+
+See skill `write-overlay` for the full authoring reference.
+
+### 5. Save overlays to the project
+
+Overlays live in `tracks[1+]` — overlay tracks in the unified tracks array. Each inner array is one track. Items in the same track cannot overlap in time; items in different tracks are z-ordered (higher indexes render on top). `tracks[0]` is always the primary footage track.
+
+```json
+{
+  "tracks": [
+    [],
+    [
+      {
+        "id": "ov-0",
+        "type": "overlay",
+        "src": "/abs/path/to/project/overlays/hook.jsx",
+        "props": { "text": "The source code got leaked" },
+        "start": 0.0,
+        "end": 3.0
+      }
+    ]
+  ]
+}
+```
+
+For multiple non-overlapping overlays, add them to the same track. For simultaneous overlays at different z-levels, add them to separate tracks.
+
+Follow save discipline: **read the project**, merge the updated `tracks` array into the fresh state, then **save the project (delta)**.
+
+## Rules
+
+- **Use icons, not emojis** — `Ph.*` (Phosphor) or `FaIcon` with `FaSolid`/`FaBrands` (Font Awesome). Both are available as globals — no imports needed. Only use emojis if the prompt asks.
+- **Always use absolute paths** for `src` — the render engine won't resolve relative paths
+- **Don't overlap items at the same position** at the same time
+- **To cover footage fully**, set `"opaque": true` on the item — the render engine removes transparency and lets the JSX root's CSS define the background. The audio track is unaffected.
+- **Go large** — 96px+ for most text, 120–160px for hooks. Big text beats small text every time
+- **No backgrounds by default** — plain text on video with a text shadow is the preferred style. Only use cards or panels when the prompt explicitly asks, or when legibility genuinely requires it
+- **Covering the face is acceptable** — don't compromise text size or position to avoid the speaker
+- **Keep text short** — 2–6 words for lower-thirds, 4–8 for hooks. Short + large beats long + small
+- **Leave `offsetX`, `offsetY`, `scale` at defaults** (`0`, `0`, `1`) — the human positions overlays via the UI drag tool after preview
+- **Use assets from `project.assets`** — pass asset `src` paths as `props`, don't hardcode paths inside JSX
+
+## Render Constraints
+
+- Canvas is **1080 on the short edge** with the aspect ratio of `project.settings.resolution` (default `[1080, 1920]` portrait) — always, regardless of output resolution. The render pipeline captures overlay segments at design resolution (Puppeteer viewport = 1080-short-edge) and upscales to the final output resolution (e.g. 2× for 4K) at compose time. All sizing in JSX is authored for 1080-design coordinates.
+- **Never apply `transform: translate` or `scale` to the root element** — these are applied by the pipeline at compose time. Applying them in JSX pushes content off-canvas.
+- **Animations must complete before the overlay ends** — the last frame is held. If you fade out, opacity must reach 0 before the final frame. No mid-fade endings.
+- **HDR output** — when the project's `settings.colorSpace` is `hdr_hlg` or `hdr_pq`, the pipeline encodes the final output as HEVC 10-bit `yuv420p10le` with bt2020 color metadata (transfer `arib-std-b67` for HLG or `smpte2084` for PQ). Overlay segments are composited into the project's working color space at compose time; no action required in JSX.
+- **Split background from animated content** — never put `backdrop-filter: blur()` on a container whose children animate. It creates a GPU compositor layer that Chrome caches, producing stale/flashing frames in the rendered output. Put the frosted-glass card on its own lower track (where it can safely be cached — it's static), and put animated content on a higher track with no `backdrop-filter`. See skill `write-overlay` for the full split pattern and when to skip backdrop-filter entirely.

package/skills/select-takes.md

@@ -0,0 +1,149 @@
+---
+name: select-takes
+description: "Agent-authored workflow task: analyze transcripts across all clips, pick ONE best take per script section, discard all others. Load this when you hit montaj/select_takes in a workflow."
+step: true
+---
+
+# Select Takes
+
+`montaj/select_takes` is an agent-authored task — no CLI step, no API call. You reason across all clip transcripts and make editorial decisions. The output is a set of cropped trim specs ready for `rm_fillers` and `concat`.
+
+## Core Purpose
+
+**Pick one. Kill the rest.**
+
+Every repeated take of the same line is wasted runtime in the final video. Your job is to identify every section of the script, find all takes of that section across all clips, select the single best delivery, and discard everything else. If a section has three takes, two get cut entirely. If a clip is entirely a worse take of content covered better in another clip, that clip is dropped.
+
+This is the only step in the pipeline with full cross-file awareness. Use it.
+
+## Process
+
+### 1. Read all transcripts
+
+Read the SRT file for every clip from the preceding `transcribe` step. Read them all before making any decisions — the best take of a section may be in a different clip than you expect.
+
+### 2. Map the script
+
+Lay out every distinct section of the intended script in narrative order. A "section" is a unit of content — a sentence, a thought, a beat. Name each one.
+
+Example for a 5-clip set:
+```
+A. Hook — "this is insane, the source code got leaked"
+B. What happened — "at 3am someone posted, 33M views"
+C. What was found — "tamagotchi, Kyros mode, dreaming"
+D. Fallout — "copyright claims, repos taken down"
+E. Resolution — "people rewrote in different languages, Boris said human error"
+F. CTA — "go check it out, follow me"
+```
+
+### 3. Find all takes of each section
+
+For each section, find every occurrence across all clips. A take is any transcript segment that covers that section's content — same words, same idea, same intent. Include:
+- Complete takes
+- False starts (partial delivery that stops mid-sentence)
+- Repeated attempts (full delivery but not the best one)
+
+### 4. Pick the best take
+
+For each section, select **one** take. Apply these criteria in order:
+
+1. **Complete over truncated** — a take that finishes the thought beats one that trails off
+2. **No mid-sentence restarts** — a take with no repeated phrases within it beats one that corrects itself
+3. **Clean delivery** — fewer filler words, less dead air within the take
+4. **Last attempt wins ties** — speakers improve with repetition; when two takes are equally clean, prefer the later one
+
+**Do not hedge.** Pick one. If two takes are genuinely indistinguishable, pick the last one and move on.
+
+### 5. Scan each selected take for within-take repetition
+
+After picking a take, re-read its SRT segments carefully. Look for the **same phrase (3+ words) appearing more than once** within the selected window — this is a mid-take stutter where the speaker restarted a clause without a long enough pause to be split into a separate take by `waveform_trim`.
+
+For each repetition found:
+1. **Identify the repeated phrase** and all its occurrences in the SRT
+2. **Keep only the final occurrence** — the speaker lands the phrase correctly on the last attempt
+3. **Tighten the crop window** to start just before the final occurrence, discarding the earlier stumbles
+
+Example: SRT shows `"and always on mode, and always on mode called Kyros that basically lets and always on mode called Kyros..."` — the speaker repeated "always on mode" three times. Crop the section start to just before the last clean attempt.
+
+**This is a required check, not optional.** `rm_fillers` only removes um/uh/hmm; it will not catch repeated phrases. If you don't catch it here, it encodes into the final video.
+
+### 6. Determine the output order
+
+Arrange the selected takes in narrative order. This may differ from the original clip order. A clip that contains section C might come before a clip that contains section B if that serves the story.
+
+### 7. Check every seam for narrative overlap
+
+After ordering, read the **last sentence of section N** and the **first sentence of section N+1** for every adjacent pair. Flag any pair where:
+- The same fact, event, or phrase is stated in both (e.g. hook ends "source code got leaked" → next section opens "they had leaked the entire source code")
+- The same emotional beat lands twice in a row
+- A setup at the end of N is answered by N itself, making the opening of N+1 redundant
+
+For each flagged seam, fix it by trimming the crop window of whichever section is redundant — usually cutting the opening of N+1 forward to where it adds new information, or cutting the close of N back to where it hands off cleanly. Do not simply accept the overlap because both sections were independently "the best take."
+
+**This check is required before writing any spec files.** Seam problems cannot be caught by any automated step downstream.
+
+### 9. Crop the trim specs — do NOT call `trim`
+
+For each selected take, load the trim spec JSON produced by the preceding `waveform_trim` step for that clip. Crop it to the selected take's virtual-timeline window using the `crop_spec` step.
+
+**Never call the `trim` step.** That encodes an intermediate video file and breaks the single-encode chain. Cropping the spec keeps the original source file all the way through to `concat`.
+
+Run step `crop_spec` with `{"input": "/path/IMG_4893_spec.json", "keeps": [[8.5, 34.1]]}` → returns `{"path": "/path/IMG_4893_spec_cropped.json"}` (single window).
+
+Run step `crop_spec` with `{"input": "/path/IMG_4893_spec.json", "keeps": [[0, 2.4], [13.84, 18.33]]}` → returns `{"path": "/path/IMG_4893_spec_cropped.json"}` (multiple windows — skip rejected content in between).
+
+Run step `crop_spec` with `{"input": "/path/IMG_4893_spec.json", "keeps": [[40.28, null]]}` (open-ended: keep from virtual 40.28s to end of clip).
+
+The `keeps` field is a **native JSON array** of `[start, end]` pairs — not a string. Use `null` for an open-ended window.
+
+**Important:** the timestamps you pass to `crop_spec` are **virtual-timeline timestamps** — time within the waveform_trim spec's kept audio, not original-file timestamps. If your reference points come from an SRT transcript (which uses original-file timestamps), use `virtual_to_original --inverse` to convert them first (see below).
+
+Write each cropped spec to `<original>_selected.json` by saving the path returned by the step.
+
+### 9a. Timestamps — SRT is already virtual; use virtual_to_original for seam debugging only
+
+**SRT timestamps are virtual-timeline timestamps.** The `transcribe` step runs on the extracted audio (the waveform_trim keeps played back-to-back), so its timestamps are relative to that extracted audio — i.e., the virtual timeline. Pass them directly to `crop_spec` without any conversion.
+
+SRT shows the best take at 8.5s–34.1s → run step `crop_spec` with `{"input": "/path/IMG_4893_spec.json", "keeps": [[8.5, 34.1]]}` and pass the result directly.
+
+`virtual_to_original` is a **debugging tool**, not a conversion step in the normal workflow. Use it when you need to verify that a virtual timestamp maps to the right spot in the original file — for example, to check why a cut looks off:
+
+Run step `virtual_to_original` with `{"input": "spec.json", "verbose": true, "timestamp": 47.32}` → returns something like `47.32 → 95.483 (keep 10: [93.295, 96.166])`.
+
+The `inverse` option goes the other direction (original-file → virtual). Use it when you have an original-file timestamp from somewhere else (e.g., ffprobe output, manual note) and need to know where it falls in the virtual timeline:
+
+Run step `virtual_to_original` with `{"input": "spec.json", "inverse": true, "timestamp": 95.483}` → returns `47.320`.
+
+### 10. Output
+
+An ordered list of `_selected.json` trim spec paths — one per selected section, in narrative order. These become the inputs to `rm_fillers` and ultimately `concat`.
+
+## What to Log
+
+Before writing specs, log your decisions clearly:
+
+```
+select_takes decisions:
+  A. Hook → IMG_4891 0–18s (only take, clean delivery)
+  B. What happened → IMG_4893 0–7.5s (first clean take; second at 22s is identical but trails off)
+  C. What was found → IMG_4893 42.5–66.8s (THIRD take — first two at 26s and 34s cut off before "Kyros")
+  D. Fallout → IMG_4894 0–18.4s (only take)
+  E. Resolution → IMG_4895 8.5–34.1s (cleaner pivot take + Boris statement; dropping filler at 34–44s)
+  F. CTA → IMG_4896 12.9–18.9s (FOURTH take — first three are false starts)
+
+  Dropped entirely: IMG_4893 0–42s (repeated takes of B and C), IMG_4895 44–60s (trailing filler), IMG_4896 0–12.9s (false starts)
+```
+
+## Common Mistakes
+
+**Too conservative — the most common failure.** Keeping a wide window like `0–66s` because it "contains the best take" is wrong. It also contains two rejected takes. Crop to the specific take only.
+
+**Not reading all clips before deciding.** The best take of section C might be in clip 4, not clip 2. Read everything first.
+
+**Keeping false starts.** A false start is not content. If a speaker says "so the — actually let me start over — the tweet got..." cut before the restart.
+
+**Keeping the outro filler.** Clips often end with trailing "so yeah", "anyway", "alright" after the real content. Cut at the end of the last meaningful sentence.
+
+**Missing within-take phrase repetition.** Even after picking the best take, the speaker may have stumbled and repeated a clause mid-sentence — no automated step catches this. You must read the SRT for every selected take and crop out earlier occurrences of any repeated phrase. Choosing the "best" take is not enough if that take still contains an internal stutter.
+
+**Skipping the seam check.** Each section is picked independently, but the seams are where edits fall apart. A hook that ends "the source code got leaked" followed by an opener that says "they had leaked the entire source code" is the same beat twice — no automated step catches cross-section redundancy. Always read adjacent section boundaries as a pair before writing specs.

package/skills/write-overlay.md

@@ -0,0 +1,611 @@
+---
+name: write-overlay
+description: "Write a custom JSX overlay component and add it to the project's overlay track."
+---
+
+# Write Overlay
+
+An overlay is a React component rendered frame-by-frame by Puppeteer, composited over the footage at a specific timestamp. All overlays are custom JSX — there are no built-in templates.
+
+---
+
+## Execution context
+
+Custom overlay JSX runs in a sandboxed evaluator. All identifiers below are injected as globals:
+
+| Identifier | Type | Description |
+|------------|------|-------------|
+| `frame` | number | Current frame number (0 → duration-1). Drives all animation. |
+| `fps` | number | Output frame rate |
+| `duration` | number | Total frames this overlay is visible for |
+| `props` | object | The `props` object from the project.json item |
+| `interpolate` | function | Map a frame number to any output value |
+| `spring` | function | Physics-based easing (0 → 1) |
+| `Ph` | object | All [Phosphor Icons](https://phosphoricons.com) — e.g. `Ph.House`, `Ph.ArrowRight` |
+| `FaIcon` | component | `FontAwesomeIcon` renderer — use with `FaSolid` / `FaBrands` icon objects |
+| `FaSolid` | object | All [FA Free Solid](https://fontawesome.com/icons?s=solid) icon objects — e.g. `FaSolid.faHouse` |
+| `FaBrands` | object | All [FA Free Brands](https://fontawesome.com/icons?s=brands) icons — e.g. `FaBrands.faGithub` |
+| `THREE` | namespace | All [Three.js](https://threejs.org) primitives — `THREE.Vector3`, `THREE.MathUtils`, etc. Only reach for it when you genuinely need 3D — see "3D / Three.js" section. |
+| `Canvas` | component | [@react-three/fiber](https://r3f.docs.pmnd.rs) Canvas. **Always pass `frameloop="never"`** and mount a `useThreeFrame()` child — see "3D / Three.js" section. |
+| `useThreeFrame` | hook | Bridges r3f to Montaj's frame-stepped renderer. Mount exactly once inside any `<Canvas>`. |
+
+**No imports.** All `import` statements are stripped before evaluation. Do not import anything — use the globals above instead.
+
+### Top-level vs component-body
+
+**All calls to `interpolate`, `spring`, and any read of `frame`, `fps`, `duration`, or `props` must be inside the component function body.** The module's top-level code runs before the render shim sets up these globals — calling them outside a function will throw `interpolate is not defined` and crash the entire render.
+
+```jsx
+// WRONG — crashes at render time
+const opacity = interpolate(frame, [0, 10], [0, 1])
+export default function Hook() { ... }
+
+// CORRECT — inside the component, runs each frame
+export default function Hook() {
+  const opacity = interpolate(frame, [0, 10], [0, 1])
+  return <div style={{ opacity }}>...</div>
+}
+```
+
+Pure helper functions that receive their values as arguments are fine at the top level, as long as they don't call globals at definition time:
+
+```jsx
+// Fine — interpolate is only called when the function is invoked (inside the component)
+const itemStyle = (show) => ({
+  opacity: show,
+  transform: `translateY(${interpolate(show, [0, 1], [20, 0])}px)`,
+})
+
+export default function List() {
+  const show = spring({ frame, fps, stiffness: 300, damping: 24 })
+  return <div style={itemStyle(show)}>...</div>
+}
+```
+
+---
+
+## Writing the JSX
+
+> **Carousel text overlays follow a stricter contract.** For carousel projects, every text-bearing overlay must accept its font size, family, weight, style, color, alignment, transform, and background as props with string defaults — see skill `editable-text`. The "go large — for video" guidance below, and the hardcoded-style style of the `Hook` example, **do not apply** to carousel editable-text overlays.
+
+The default aesthetic is **plain bold text directly on video** — no card, no background, just a text shadow for legibility. Big text (96–160px) that covers the footage, including the speaker's face if needed.
+
+```jsx
+// overlays/hook.jsx — plain text on video, no background
+
+export default function Hook() {
+  const progress = interpolate(frame, [0, 8], [0, 1], { extrapolateRight: 'clamp' })
+  const slideY   = interpolate(frame, [0, 10], [40, 0], { extrapolateRight: 'clamp' })
+
+  return (
+    <div style={{
+      position: 'absolute', bottom: 180, left: 48, right: 48,
+      opacity: progress,
+      transform: `translateY(${slideY}px)`,
+    }}>
+      <div style={{
+        fontFamily: 'Anton, Impact, sans-serif', fontSize: 120, fontWeight: 900,
+        color: '#fff', lineHeight: 1.05, letterSpacing: '-1px',
+        textShadow: '0 2px 24px rgba(0,0,0,0.9), 0 0 60px rgba(0,0,0,0.5)',
+        textTransform: 'uppercase',
+      }}>
+        {props.text}
+      </div>
+    </div>
+  )
+}
+```
+
+Only add a card or background when the prompt explicitly asks, or when a specific overlay type genuinely requires it (e.g. a logo lockup, an opaque title card). When you do need a background, prefer a solid semi-transparent color over `backdropFilter: blur()` — see the track-splitting section below.
+
+### Rules
+
+- **Default export only** — the evaluator imports the default export
+- **No hooks** — `useState`, `useEffect`, etc. are not supported in the overlay component itself. The render shim drives re-renders by calling `flushSync` externally each frame; the component must be a pure function of its props/globals.
+- **Frame-driven** — all animation must derive from `frame`. No `setTimeout`, `setInterval`, CSS `animation`, or `transition`.
+- **Transparent background (default)** — overlays render with a transparent background by default. Do not set `background` on the root element; it will obscure whatever is beneath it.
+- **Opaque overlays** — when `"opaque": true` is set on the item in project.json, the root element's CSS controls the entire frame. You may freely set `background`, gradients, images, or any CSS on the root. Use this for full-frame covers, title cards, and animation sections.
+- **Absolute positioning** — the component fills the full video frame (1080 on the short edge, aspect of `project.settings.resolution`). The Puppeteer viewport is always 1080-short-edge regardless of output resolution; the renderer upscales to the final video dimensions at compose time. Place elements with `position: absolute`. Author all `fontSize`, padding, and `width` values at 1080-design coordinates — they have one consistent meaning across every resolution the project might render at.
+- **No side effects** — no API calls, no filesystem access, no global state mutations.
+- **`backdropFilter` caution** — `backdrop-filter: blur(...)` causes Chrome to create a separate GPU compositor layer that can be cached and replayed as a stale frame during rendering. Avoid putting `backdrop-filter` on any element whose children animate — the blur container will flash or freeze. See the track-splitting guidance below.
+
+---
+
+## Splitting background from content across tracks
+
+The most reliable way to use frosted-glass / blurred card backgrounds is to **put the background on a separate, lower track** and the animated content on a higher track. The render pipeline composites tracks in order, so the content renders on top.
+
+**Why this works:** A background card with `backdrop-filter` is essentially static — it fades in, then stays put. When Chrome's headless compositor caches the GPU layer for it, the cache is *correct* (the layer genuinely hasn't changed). The content overlay on the higher track has no `backdrop-filter`, so there's no caching issue and animations render cleanly every frame.
+
+**When to split:**
+
+| Background behavior | Animated content | Verdict |
+|---------------------|-----------------|---------|
+| Static or simple fade only | Any — text, icons, logos staggering in | **Split** |
+| Shakes, bounces, or translates together with content | Content must move with the background | **Keep together** (no backdrop-filter, use solid `background` instead) |
+
+**How to split in project.json:**
+
+```json
+{
+  "tracks": [
+    [],
+    [
+      {
+        "id": "ov-card-bg",
+        "type": "overlay",
+        "src": "/path/overlays/card-bg.jsx",
+        "start": 2.0,
+        "end": 6.0
+      }
+    ],
+    [
+      {
+        "id": "ov-card-content",
+        "type": "overlay",
+        "src": "/path/overlays/card-content.jsx",
+        "start": 2.0,
+        "end": 6.0
+      }
+    ]
+  ]
+}
+```
+
+**Background component — no animated children:**
+
+```jsx
+// overlays/card-bg.jsx
+// Just a frosted card that fades in. No children that animate opacity.
+const opacity = interpolate(frame, [0, 8], [0, 1], { extrapolateRight: 'clamp' })
+
+export default function CardBg() {
+  return (
+    <div style={{ position: 'absolute', bottom: 340, left: 0, right: 0, display: 'flex', justifyContent: 'center', opacity }}>
+      <div style={{
+        background: 'rgba(0,0,0,0.84)',
+        backdropFilter: 'blur(24px)',
+        borderRadius: 36,
+        padding: '44px 72px',
+        border: '1px solid rgba(255,255,255,0.10)',
+        minWidth: 560,
+        minHeight: 200,
+      }} />
+    </div>
+  )
+}
+```
+
+**Content component — no backdrop-filter:**
+
+```jsx
+// overlays/card-content.jsx
+// Animated items rendered on top of the background card.
+const s1 = spring({ frame: Math.max(0, frame - 4), fps, stiffness: 300, damping: 24 })
+
+export default function CardContent() {
+  return (
+    <div style={{ position: 'absolute', bottom: 340, left: 0, right: 0, display: 'flex', justifyContent: 'center' }}>
+      <div style={{ padding: '44px 72px', minWidth: 560 }}>
+        <div style={{ opacity: Math.min(1, s1 * 2.5), transform: `translateX(${interpolate(s1, [0, 1], [-24, 0])}px)` }}>
+          <Ph.CheckCircle size={52} weight="fill" color="#34d399" />
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+**When you can't split** (background and content animate together as one unit — e.g., a card that shakes on impact), skip `backdrop-filter` entirely and use a solid or semi-transparent `background` instead:
+
+```jsx
+// Instead of backdropFilter: 'blur(24px)'
+background: 'rgba(10,10,10,0.88)'  // solid dark — visually similar, no GPU layer caching
+```
+
+---
+
+## Utilities
+
+### `interpolate(frame, inputRange, outputRange, options?)`
+
+Maps a frame number to any output value. Clamps at both ends by default.
+
+```jsx
+// Fade in over frames 0–15
+const opacity = interpolate(frame, [0, 15], [0, 1])
+
+// Fade in then out
+const fadeIn  = interpolate(frame, [0, 15], [0, 1])
+const fadeOut = interpolate(frame, [duration - 15, duration], [1, 0])
+const opacity = Math.min(fadeIn, fadeOut)
+
+// Slide in from left
+const x = interpolate(frame, [0, 20], [-200, 0], { extrapolateRight: 'clamp' })
+```
+
+Options: `extrapolate`, `extrapolateLeft`, `extrapolateRight` — each `'clamp'` (default) or `'extend'`.
+
+### `spring({ frame, fps, mass?, stiffness?, damping?, initialVelocity? })`
+
+Returns a 0 → 1 value following spring physics. Overshoots and settles naturally.
+
+```jsx
+const scale = spring({ frame, fps, stiffness: 120, damping: 14 })
+// transform: `scale(${scale})`
+```
+
+Defaults: `mass: 1`, `stiffness: 100`, `damping: 10`.
+
+---
+
+## Icons
+
+Use icons instead of emojis unless the prompt explicitly asks for emojis. Icons scale cleanly, render crisply at any resolution, and look intentional.
+
+### Phosphor Icons — `Ph`
+
+Browse at [phosphoricons.com](https://phosphoricons.com). Over 9000 icons, six weights: `regular` (default), `bold`, `fill`, `duotone`, `light`, `thin`.
+
+```jsx
+// Basic usage
+<Ph.House size={48} color="white" />
+
+// With weight
+<Ph.ArrowRight size={32} color="#a78bfa" weight="bold" />
+<Ph.Star size={40} color="#fbbf24" weight="fill" />
+
+// In a card row
+<div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+  <Ph.CheckCircle size={36} color="#34d399" weight="fill" />
+  <span style={{ fontFamily: 'Inter, sans-serif', fontSize: 24, color: 'white' }}>Feature unlocked</span>
+</div>
+```
+
+### Font Awesome — `FaIcon` + `FaSolid` / `FaBrands`
+
+`FaIcon` is the renderer. `FaSolid` has general-purpose icons; `FaBrands` has logos (GitHub, YouTube, X, etc.).
+
+```jsx
+// Solid icon
+<FaIcon icon={FaSolid.faCode} style={{ fontSize: 48, color: 'white' }} />
+
+// Brand logo
+<FaIcon icon={FaBrands.faGithub} style={{ fontSize: 48, color: 'white' }} />
+
+// Sized via style
+<FaIcon icon={FaSolid.faBolt} style={{ fontSize: 36, color: '#fbbf24' }} />
+```
+
+### Which library to use
+
+- **Phosphor** — preferred for most overlays. Cleaner API, consistent stroke weight, large set.
+- **Font Awesome Brands** — when you need a specific brand logo (GitHub, YouTube, X/Twitter, TikTok, etc.)
+- **Font Awesome Solid** — for any icon Phosphor doesn't cover.
+
+---
+
+## Custom fonts (Google Fonts)
+
+The render host's system fonts are always available and preferred for performance — they avoid the network fetch entirely. On macOS render hosts (today's default) you can rely on `Helvetica`, `Arial`, `Georgia`, `Times`, `Courier`, `Impact`, and the `system-ui` / `-apple-system` generic stacks. `Inter` is **not** a macOS system font — use a Google Font declaration for it.
+
+To use a Google Font, declare it on the overlay item in `project.json` with a `googleFonts` array:
+
+```json
+{
+  "id": "ov-hook",
+  "type": "overlay",
+  "src": "/path/to/overlays/hook.jsx",
+  "start": 0.0,
+  "end": 5.0,
+  "googleFonts": ["Anton", "Playfair+Display:ital@1"]
+}
+```
+
+The render engine injects the font stylesheet into the page `<head>` before any component code runs, so the font is fully loaded at frame 0.
+
+**Do not use `@import url(...)` inside the JSX.** A dynamically-injected `@import` fires after the page loads — the font fetch is still in flight when the next overlay's page initialises, breaking its `window.__setFrame` setup. Always declare fonts in `googleFonts` instead, and reference the family name directly in styles:
+
+```jsx
+// In your JSX — just use the family name, no @import
+fontFamily: '"Anton", Impact, sans-serif'
+fontFamily: '"Playfair Display", Georgia, serif'
+```
+
+**Format:** `FamilyName` for regular, `FamilyName:ital@1` for italic, `FamilyName:wght@700` for a specific weight. Each family is a separate array entry.
+
+**System font fallbacks for common Google Fonts:**
+
+| Google Font | System fallback |
+|-------------|----------------|
+| Anton | Impact |
+| Playfair Display | Georgia |
+| Oswald | Arial Narrow |
+| Roboto / Inter | system-ui, sans-serif |
+
+If visual fidelity isn't critical, the system fallback avoids the network fetch entirely.
+
+---
+
+## 3D / Three.js (react-three-fiber)
+
+Overlay JSX can use Three.js for real 3D content via [@react-three/fiber](https://r3f.docs.pmnd.rs). Reach for it when you need depth, particles, shader effects, 3D text, or geometry that can't be faked in 2D. **Do not use it for things 2D HTML can do** — rotations, fades, slides, gradients are all cheaper and simpler in CSS.
+
+**Preview behavior — RAF-driven, not frame-stepped.** Three.js overlays render in both the live UI preview and the final rendered MP4. The two paths share globals and library versions via the `montaj-overlay-runtime` package, so what you see in the editor matches the render output visually. One difference to be aware of: in preview the 3D content animates via r3f's own `requestAnimationFrame` loop (the preview-context `Canvas` wrapper overrides `frameloop="never"` → `"always"` automatically), so motion is smooth but not perfectly frame-accurate to the scrubbed video position. In render, `frameloop="never"` is honored and the shim drives `gl.render()` synchronously each frame.
+
+### Two non-negotiable rules
+
+1. **`<Canvas frameloop="never">`.** The default r3f Canvas runs its own `requestAnimationFrame` loop, which is incompatible with Montaj's frame-stepped renderer — Puppeteer would screenshot arbitrary moments. `frameloop="never"` disables r3f's loop and lets the render shim drive each frame synchronously.
+2. **Mount `useThreeFrame()` exactly once inside the Canvas.** This hook registers the synchronous render trigger the shim calls every frame. Without it, Three never draws.
+
+Convention: put a tiny `<FrameBridge />` child component at the top of the Canvas that calls `useThreeFrame()` and returns `null`.
+
+### Drive everything from `frame`, never `useFrame`
+
+r3f's `useFrame` hook is tied to the internal animation loop we've disabled. **It does not work.** Compute transforms inline from the `frame` global, the same way 2D overlays do:
+
+```jsx
+export default function ThreeCube() {
+  const t      = frame / fps
+  const rotX   = t * Math.PI         // half-turn per second
+  const rotY   = t * Math.PI * 0.7
+  const pulse  = 1 + 0.08 * Math.sin(t * 4)
+
+  return (
+    <Canvas
+      frameloop="never"
+      style={{ position: 'absolute', inset: 0 }}
+      camera={{ position: [0, 0, 5], fov: 50 }}
+      gl={{ preserveDrawingBuffer: true, antialias: true, alpha: true }}
+    >
+      <FrameBridge />
+      <ambientLight intensity={0.6} />
+      <directionalLight position={[5, 5, 5]} intensity={1.2} />
+      <mesh rotation={[rotX, rotY, 0]} scale={[pulse, pulse, pulse]}>
+        <boxGeometry args={[1.6, 1.6, 1.6]} />
+        <meshStandardMaterial color="#3b82f6" metalness={0.3} roughness={0.35} />
+      </mesh>
+    </Canvas>
+  )
+}
+
+function FrameBridge() {
+  useThreeFrame()
+  return null
+}
+```
+
+### No async assets
+
+Textures, GLTFs, and any other resource that r3f loads via Suspense will **not** load in time for frame 0 — the renderer doesn't wait for Suspense the way it waits for `document.fonts.ready`. Stick to:
+
+- Primitive geometries: `<boxGeometry>`, `<sphereGeometry>`, `<planeGeometry>`, `<cylinderGeometry>`, `<torusGeometry>`, `<icosahedronGeometry>`, etc.
+- `<meshStandardMaterial>` / `<meshBasicMaterial>` with `color` (no `map`, `normalMap`, etc.)
+- Lights: `<ambientLight>`, `<directionalLight>`, `<pointLight>`, `<spotLight>`
+- Math helpers from the `THREE` global (`THREE.MathUtils.lerp`, `THREE.Vector3`, etc.)
+
+If you need a texture, render it on a 2D HTML overlay layered above the Canvas track instead.
+
+### Canvas placement and compositing
+
+`<Canvas>` fills its parent. Two patterns work:
+
+**Full-frame Canvas** — apply `style={{ position: 'absolute', inset: 0 }}` directly to `<Canvas>` so it covers the whole 1080×1920 design canvas. Use when 3D content should occupy the entire frame or be anchored relative to the camera (e.g. a particle field).
+
+**Positioned Canvas** — wrap `<Canvas>` in a `position: absolute` div with explicit `top`/`left`/`right`/`height` (or `bottom`), and set `style={{ width: '100%', height: '100%' }}` on the Canvas itself. Use when 3D content should sit in a specific region — e.g. a 3D logo lockup in the lower-third while a font overlay sits up top.
+
+```jsx
+<div style={{ position: 'absolute', top: 1100, left: 0, right: 0, height: 500 }}>
+  <Canvas frameloop="never" style={{ width: '100%', height: '100%' }} ...>
+    <FrameBridge />
+    ...
+  </Canvas>
+</div>
+```
+
+Make sure `gl={{ alpha: true }}` is set — the Canvas DOM element defaults to opaque, which would paint a black or white box over the underlying footage. With `alpha: true` + the renderer's default transparent page background, only the drawn 3D geometry shows up; the rest passes through to whatever is beneath.
+
+For text labels alongside 3D content, render them as a 2D HTML overlay on a separate track rather than as 3D text inside the Canvas. HTML text is sharper, cheaper, and supports the existing Google Fonts pipeline.
+
+### Worked reference
+
+A known-good minimal overlay lives at `tests/fixtures/overlays/three-cube.jsx` — it's the same file the render smoke test (`tests/test_render_three.py`) uses. Copy from it when starting a new 3D overlay; everything in it is checked end-to-end by CI.
+
+### Bundle weight
+
+Three.js + r3f add ~250 KB to an overlay segment's bundle after esbuild tree-shakes. Overlays that don't use `<Canvas>` pay zero cost. Don't reach for Three "just in case" — use it only when the result genuinely needs 3D.
+
+---
+
+## Charts / Recharts
+
+Overlay JSX can use SVG-based charts via [Recharts](https://recharts.org). Available globals: `BarChart`, `Bar`, `LineChart`, `Line`, `PieChart`, `Pie`, `Cell`, `XAxis`, `YAxis`, `CartesianGrid`, `Tooltip`, `Legend`, `ResponsiveContainer`.
+
+### Carousel-only (for now)
+
+Charts work in carousel slides today. Video overlays don't have a chart story yet — see follow-up plans. The carousel renderer screenshots SVG directly, so no special contract is required.
+
+### Non-negotiable rule: disable animations
+
+Set `isAnimationActive={false}` on every chart primitive (`<Bar>`, `<Line>`, `<Pie>`, etc.). Recharts animates by default; without this, the carousel renderer captures a mid-animation frame and the chart looks half-drawn. If you see fuzzy ticks or a half-faded legend in the rendered PNG, also pass `isAnimationActive={false}` to `<XAxis>` / `<YAxis>` / `<Legend>` defensively.
+
+### Size charts explicitly — don't use `<ResponsiveContainer>`
+
+`<ResponsiveContainer>` measures via `ResizeObserver`, which is asynchronous; the Puppeteer screenshot can fire before the first observer callback, producing a blank chart. Instead, take `boxWidth` / `boxHeight` as props (the slide wrapper passes them in automatically) and use them as explicit `width` / `height` on the chart root: `<BarChart width={innerW} height={innerH} ...>`.
+
+### Stick to bar / line / pie for v1
+
+Three system overlay templates ship today: `bar-chart`, `line-chart`, `pie-chart`. For one-off data viz, write a custom overlay using the same globals. For variants likely to be reused (area, scatter, donut-vs-pie variants beyond `innerRadius`), promote them to system overlays so they show up in the property panel for everyone.
+
+---
+
+## project.json item shape
+
+Place overlay items in `tracks[1+]` in `project.json`. Each item must have `type: "overlay"` and a `src` path pointing to the JSX file. All custom data goes inside `props`.
+
+```json
+{
+  "tracks": [
+    [],
+    [
+      {
+        "id": "ov-hook",
+        "type": "overlay",
+        "src": "/abs/path/to/project/overlays/hook.jsx",
+        "start": 0.0,
+        "end": 3.0,
+        "props": {
+          "text": "She built an AI employee"
+        }
+      },
+      {
+        "id": "ov-logo",
+        "type": "overlay",
+        "src": "/abs/path/to/project/overlays/logo.jsx",
+        "start": 0.0,
+        "end": 999.0,
+        "props": {
+          "logoSrc": "/abs/path/to/project/assets/logo.png"
+        }
+      }
+    ]
+  ]
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | yes | Unique identifier within the track |
+| `type` | yes | Always `"overlay"` for JSX overlays |
+| `src` | yes | Absolute path to the JSX file |
+| `start` | yes | Start time in output video (seconds) |
+| `end` | yes | End time in output video (seconds) |
+| `props` | no | Arbitrary data passed through to the component as the `props` global |
+| `googleFonts` | no | Google Font families to load before render (e.g. `["Anton", "Playfair+Display:ital@1"]`). See Custom fonts section. |
+
+**Use absolute paths for `src`.** Relative paths are resolved from `project.json` location, but absolute paths are unambiguous.
+
+---
+
+## Using assets
+
+Assets (logos, images) are declared in `project.assets`. Reference them by passing their `src` path in `props`, then use it in the component:
+
+```json
+{
+  "id": "ov-logo",
+  "type": "overlay",
+  "src": "/path/to/overlays/logo.jsx",
+  "start": 0.0,
+  "end": 30.0,
+  "props": { "src": "/path/to/assets/logo.png" }
+}
+```
+
+```jsx
+// overlays/logo.jsx
+const opacity = interpolate(frame, [0, 6], [0, 1])
+
+export default function Logo() {
+  return (
+    <img
+      src={props.src}
+      style={{
+        position: 'absolute', top: 40, right: 40,
+        width: 80, opacity,
+      }}
+    />
+  )
+}
+```
+
+Reference assets by their workspace path (e.g. `/abs/path/to/project/assets/logo.png`). How that path is resolved for preview or render is the interface's concern — the component always receives a usable URL for the path it was given.
+
+---
+
+## Live preview in the Overlays tab
+
+The Montaj UI has an **Overlays** tab that gives a real-time animated preview of every overlay in the project — no render needed.
+
+- Open the **Overlays** tab and select a project from the left panel to see its overlay list
+- Select any overlay item to see it playing over the preview image at full animation fidelity
+- **Live reload** — the preview automatically recompiles and restarts whenever you save a `.jsx` file; latency is typically under a second
+- Use the **⏸ / ▶** button in the bottom-right of the preview to pause on a specific frame
+- Asset paths passed via `props` (e.g. `logoSrc`, `src`) are proxied automatically — images and logos resolve correctly in the preview even though they are absolute local paths
+
+Use this tab to validate motion, timing, and asset rendering before committing to a full render.
+
+---
+
+## Writing multiple overlays in parallel
+
+When a workflow calls for several overlays, write them concurrently — each JSX file is independent.
+
+1. Identify all overlays needed from the editing prompt and transcript
+2. Write **every** JSX file first — author the whole set before sampling or persisting anything. Do **not** sample after each file; interleaving a Puppeteer sample between every write is slow and breaks your authoring flow.
+3. **Sample them all in one batch pass at the end** (see "Verify your overlays fit the canvas")
+4. Fix any overflow, then save the project (delta) adding all items to the overlay track in one update
+
+Common overlay set for a social reel:
+- Opening hook (0–3s) — text statement that earns the watch
+- Lower third (first speech moment) — speaker handle or title
+- CTA (final 3s) — follow / subscribe / link
+
+---
+
+## Authoring guidelines
+
+- **Use icons, not emojis** — use `Ph.*` or `FaIcon` for visual symbols. Emojis render inconsistently across platforms and look low-effort. Only use emojis if the prompt explicitly asks for them.
+- **Go large — for video.** On 1080×1920 video overlays carrying a short, glanceable hook (3–6 words) over moving footage, 96px is the floor, not the ceiling. 120–160px for hooks. Text should feel oversized; if it looks a little too big, it's probably right. This rule is calibrated to video viewing — a thumb-stop on TikTok/Reels. **Do NOT apply this rule to carousels, story panels, or other static formats** where the text is being *read* rather than *glanced at*, and where headlines run longer than a punchy hook. For carousels see skill `carousel` §6 (Typography). For other static formats, default to ~32–48px body, ~52–80px headline, and size down further as line length grows.
+- **No backgrounds by default** — plain text on video with `textShadow` for legibility is the house style. No dark cards, no frosted glass, no semi-transparent boxes unless the prompt asks. A well-placed `textShadow` works on any footage.
+- **Cover the face if needed** — text position and size take priority. Don't shrink or reposition to avoid the speaker.
+- **Tie to transcript** — use word timings from the transcript to sync text appearance with speech. An overlay that appears exactly when the speaker says the word it displays lands much harder.
+- **Match the energy of the speech** — fast, punchy delivery: 4–6 frame entrances. Slower delivery: 10–15 frame fades or slides.
+- **Short text** — 2–6 words for lower-thirds, 4–8 for hooks. Short + large beats long + small.
+- **One accent color max** — white text with one colored word or icon. Multi-color text reads as noise.
+- **Avoid the bottom ~350px** — captions render here, and platform UI (TikTok progress bar, Instagram controls) sits in this zone. Use `bottom: 350` or higher, or anchor from the top instead.
+- **Avoid the right ~200px** — TikTok/Instagram action buttons (like, comment, share) occupy the right edge. Keep text and icons within `right: 200` or use `left`-anchored layout.
+- **Don't overlap** — avoid two overlays occupying the same screen region at the same time
+- **Style to the prompt** — match font weight, color, and motion to the tone of the edit
+- **Opening hook** — almost always appropriate for social content; fires in the first 0–3s
+- **Persist after writing** — save the project (delta) with the new overlay items added to the track
+
+---
+
+## Verify your overlays fit the canvas — one sample pass at the end
+
+**Write all of your overlay JSX first. Then sample them in a single batch pass — do not sample after each file.** Per-file sampling stalls authoring and spins up a fresh Puppeteer process each time; one pass at the end over the finished set is faster and just as safe, since nothing downstream consumes an overlay until you save the project with the whole batch.
+
+Once every JSX file is written, loop over them in one pass — for each JSX file, **run step `sample_overlay`** with args `{ path, measure: true, googleFonts, props }`:
+
+Pass each overlay's declared `googleFonts` (and representative `props`) so the step measures with the real render-time font — see the Syne case study below.
+
+The step renders the overlay through the same Puppeteer path the production renderer uses and returns:
+
+```json
+{
+  "pngPath": "/tmp/sample-check.png",
+  "measurements": {
+    "anyOverflow": false,
+    "texts": [...],
+    "viewport": { "w": 1080, "h": 1920 }
+  }
+}
+```
+
+**`measurements.anyOverflow` is the go/no-go signal.** If it is `true`, at least one text element extends past the 1080×1920 design canvas and will be visually clipped in the final render. Inspect `measurements.texts[]` for per-element detail: `bbox` gives the element's position and dimensions, and `overflow.{left,right,top,bottom}` gives the pixel overshoot on each edge.
+
+**Two categories of false positives to rule out before fixing:**
+
+- **`transform: rotate()` or `transform: scale()`** — `getBoundingClientRect()` returns the axis-aligned bounding box of the transformed element, which is wider and/or taller than the un-rotated element. A 1000×100 banner rotated 45° reports a ~777×777 bbox and will look like it overflows even when it doesn't. Check the `transform` field on the flagged element. If it's not `matrix(1, 0, 0, 1, 0, 0)` (the identity), the overflow signal is unreliable for that element.
+- **`clippingAncestor`** — an element flagged for overflow may be the child of a container with `overflow: hidden` (animation sections that clip entering/exiting elements use exactly this). If the `clippingAncestor` field is non-null, the element is intentionally clipped. Compute `intersect(elementBbox, clippingAncestor.bbox)` to check effective overflow if you want to be precise.
+
+**Do not ship an overlay JSX until `anyOverflow` is false** — or until you have verified each overflowing element is covered by one of the two false-positive cases above.
+
+### The Syne overflow case study — why the editor preview cannot tell you
+
+When the Montaj editor preview shows a layout that fits, but the rendered video shows clipped text, the cause is almost always a **font-width mismatch**. The editor preview falls back to `sans-serif` when a Google Font is not installed locally. The renderer loads the overlay's declared `googleFonts` faithfully via the Google Fonts CDN before rendering frame 0.
+
+Display fonts like **Syne 800** are 60–70% wider than typical `sans-serif` fallbacks at the same `px` size. Concrete example: `"RECURSIVE"` at `fontSize: 160` measures ~933 px wide in fallback `sans-serif`, but ~1594 px wide in Syne 800 — 514 px of right-edge overflow on a 1080-wide canvas. The editor looked fine; the render was completely clipped.
+
+**Any overlay that declares a `googleFonts` entry must go through the end-of-authoring sample pass with `measure: true` and that same `googleFonts` spec, before you save the project with the batch.** The preview cannot tell you whether the text fits in the render. The sample can.