@shotstack/cli 0.4.1 → 0.6.0

package/references/ingest.md

@@ -0,0 +1,121 @@
+# Ingesting local files (Ingest API)
+
+The `shotstack ingest` commands host your own media on Shotstack so it can be
+referenced from an Edit. This is the **Ingest API** — a separate service from
+the Edit (render) API, living at `https://api.shotstack.io/ingest/{env}`. The
+CLI targets it automatically; the same `SHOTSTACK_API_KEY` works for both.
+
+Use it when your footage, audio, images, fonts, or subtitle files live on your
+machine (or behind a URL) rather than already being on a public CDN. Sources
+are stored until you delete them.
+
+## The one rule that matters
+
+**An Edit can only reference media by URL.** A local path in an `asset.src`
+will not render. So the flow is always:
+
+```
+local file ──▶ shotstack ingest upload ──▶ hosted "source" URL ──▶ Edit asset.src ──▶ shotstack render
+```
+
+`shotstack ingest upload <file>` performs the two-step Ingest dance for you in
+one command: it asks the API for a pre-signed URL, then streams your file's
+bytes straight to storage.
+
+## Get the hosted URL: use `--watch`
+
+The bare command returns only a source **id** — the hosted URL does not exist
+until ingestion finishes. Pass `--watch` to poll until the source is `ready`
+and print its URL:
+
+```sh
+shotstack ingest upload ./intro.mp4 --watch --output json
+# → {"id":"zzytey4v-...","status":"importing"}
+# → {"id":"zzytey4v-...","status":"ready","source":"https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/.../source.mp4","width":1920,"height":1080,"duration":12.4}
+```
+
+The `source` field is the URL to drop into your Edit. In text mode the final
+line is just `ready  <url>`, easy to capture in a shell variable:
+
+```sh
+SRC=$(shotstack ingest upload ./intro.mp4 --watch --output json | tail -n1 | jq -r .source)
+```
+
+Without `--watch`, capture the id and poll it later:
+
+```sh
+ID=$(shotstack ingest upload ./intro.mp4 --output json | jq -r .id)
+shotstack ingest status "$ID" --watch --output json
+```
+
+## Worked example: upload then render
+
+```sh
+# 1. Upload a local clip and a local logo, capturing the hosted URLs.
+VIDEO=$(shotstack ingest upload ./clip.mp4 --watch --output json | tail -n1 | jq -r .source)
+LOGO=$(shotstack ingest upload ./logo.png  --watch --output json | tail -n1 | jq -r .source)
+
+# 2. Reference them in an Edit (asset.src), then render.
+cat > edit.json <<JSON
+{
+  "timeline": {
+    "tracks": [
+      { "clips": [ { "asset": { "type": "image", "src": "$LOGO" },  "start": 0, "length": 5 } ] },
+      { "clips": [ { "asset": { "type": "video", "src": "$VIDEO" }, "start": 0, "length": 5 } ] }
+    ]
+  },
+  "output": { "format": "mp4", "size": { "width": 1920, "height": 1080 } }
+}
+JSON
+
+shotstack render edit.json --watch
+
+or
+
+shotstack studio edit.json
+```
+
+Remember `tracks[0]` is the **top** layer (see `shared/agent-core.md`), so the
+logo track sits above the video.
+
+## Fetch a remote URL instead of uploading
+
+If the media is already at a URL but you want Shotstack to host its own copy
+(stable, no hot-linking), use `fetch`:
+
+```sh
+shotstack ingest fetch https://example.com/big-video.mp4 --watch --output json
+```
+
+This only works for fully validated urls. YouTube and similar video hosting  
+platforms are not supported.
+
+## Manage stored sources
+
+```sh
+shotstack ingest list --output json          # every source you've ingested
+shotstack ingest status <id> --output json   # one source's status + hosted URL
+shotstack ingest delete <id>                  # remove a source from storage
+```
+
+## Status values
+
+`queued` → `importing` → `ready` (terminal). A failed import ends in `failed`
+(exit code 1 under `--watch`). `deleted` and `overwritten` are also terminal.
+
+## Supported files
+
+Video, image, audio, font, and subtitle (`.srt`/`.vtt`) files. The CLI infers
+a `Content-Type` from the file extension; uncommon extensions still upload
+(the API sniffs the content) but naming files with a correct extension is
+safest.
+
+## Environments
+
+Sources are ingested into the environment you target (`--env stage` or `--env
+v1`, default `v1`), mirroring `render`. Override the base URL for local testing
+with `SHOTSTACK_INGEST_BASE_URL`.
+
+```sh
+shotstack ingest upload ./clip.mp4 --watch --env stage
+```

package/references/motion.md

@@ -0,0 +1,151 @@
+# Motion language — the house vocabulary
+
+A small, closed set of timing, easing and stagger values that **every** animated clip should share. Composing motion from these tokens — instead of inventing a new easing and duration per clip — is what makes a multi-clip edit feel like one production instead of eight unrelated effects. Reach for these before hardcoding a `duration`, an `ease`, or a delay.
+
+> The values are video-paced for Shotstack's **second-based** timeline (most UI-motion guidance is frame-based). The GSAP/CSS easings below stand in for spring physics, which the render engine doesn't expose.
+
+## The tokens
+
+### Duration scale (seconds)
+
+| Token | Seconds | Use for |
+|---|---|---|
+| `instant` | 0.2 | micro shifts, near-imperceptible feedback |
+| `fast` | 0.33 | **exits**, small moves |
+| `base` | 0.6 | **the default entrance** — ~80% of reveals |
+| `slow` | 0.8 | large entrances, hero moves |
+| `slower` | 1.0 | full-scene transitions |
+| `hold` | 1.5 | minimum settled hold before a clip ends |
+
+Most entrances are `base` (0.6 s). Exits are deliberately faster than entrances — get out of the way faster than you came in.
+
+### Easing — one house curve, no overshoot by default
+
+| Where | Entrance / settle | Exit |
+|---|---|---|
+| **html5 GSAP** | `ease: 'power3.out'` | `ease: 'power2.in'` |
+| **html5 CSS** | `cubic-bezier(0.16, 1, 0.3, 1)` | `cubic-bezier(0.3, 0, 0.8, 0.2)` |
+
+`power3.out` / `cubic-bezier(0.16,1,0.3,1)` is the **house ease** — a confident "fast then settle" that reads like a heavily-damped spring with **no bounce**. Use it for anything the eye tracks (position, scale, blur). Never use raw `linear` / `'none'` for motion the eye follows; `linear` is only correct for a continuous drift (grain, marquee, a constant-speed ticker).
+
+**Overshoot is opt-in, not default.** A gentle `back.out(1.4)` (GSAP) is reserved for **one** "hero" element per scene where a pop is intended — a logo sting, a headline punch. Calm is the default; energetic is fine when it *earns* it. Never sprinkle bounce across every element.
+
+### Stagger — one value
+
+`0.13 s` (≈ 4 frames at 30 fps) between siblings in any cascade — words, list items, grouped reveals. One value everywhere; present but never frantic. In GSAP: `stagger: 0.13`. In CSS: `animation-delay` steps of `0.13s` (`0s, 0.13s, 0.26s, …`).
+
+### Travel & restraint
+
+- **Travel small:** translate **12–24 px**, not 80. The eye should feel the motion, not be dragged by it. Blur reveals: `10 px → 0`. Scale reveals: `0.92 → 1` (below ~0.85 is dramatic-zoom territory — avoid unless intended).
+- **One focal element per moment.** If two things compete, stagger them. Don't animate everything at once.
+- **Let it settle.** After a reveal lands, hold it (a trailing `gsap.to({}, { duration: <hold> })` or enough clip `length`) before the clip ends. Never cut a reveal the instant it arrives.
+
+## The three motion layers
+
+Shotstack exposes motion at three levels of control. Use the tokens at whichever level fits; reach down a level only when you need more control.
+
+| Layer | Control | Where the tokens apply |
+|---|---|---|
+| 1 — **clip `transition` / `effect`** | coarse (whole-clip in/out; only `Slow`/`Fast` variants) | pick `fade`, `slide*`, `zoom`; `Slow` ≈ `slow`, default ≈ `base`, `Fast` ≈ `fast` |
+| 2 — **`rich-text` `animation`** | medium (`preset` + `duration` + `style` + `direction`) | set `duration` from the scale; `style:"word"` gives the staggered cascade |
+| 3 — **`html5` GSAP / CSS** | full (any property, any easing) | the full vocabulary below — durations, the house ease, `0.13` stagger |
+
+### Layer 2 — rich-text animation, tokenised
+
+`animation.preset` maps onto the choreography names; set `duration` from the scale:
+
+| Intent | `rich-text` animation |
+|---|---|
+| fade in | `{ "preset": "fadeIn", "duration": 0.6 }` |
+| rise + fade (the workhorse) | `{ "preset": "ascend", "duration": 0.6, "direction": "up" }` |
+| slide in | `{ "preset": "slideIn", "duration": 0.6, "direction": "up" }` |
+| word-by-word cascade | `{ "preset": "shift", "duration": 0.6, "style": "word", "direction": "up" }` |
+| typewriter | `{ "preset": "typewriter", "duration": 0.8, "style": "character" }` |
+
+Schema constraints (`@shotstack/schemas` → `RichTextAnimation`): `preset` ∈ `fadeIn · slideIn · typewriter · ascend · shift · movingLetters`; `duration` 0.1–30 s; **`style` (`word`/`character`) applies only to `typewriter` and `shift`** (ignored on the others); `direction` is **required** for `slideIn`, `ascend`, `shift`, `movingLetters`. Rich-text `animation` is **entrance-only** — exits use the clip `transition.out` (Layer 1). Easing on the presets is engine-fixed; for full easing control, drop to html5 (Layer 3).
+
+## Choreography recipes (html5 / GSAP)
+
+Pure, seekable GSAP — obey [`html5.md`](html5.md) (no `setTimeout`/`rAF`/`Date.now`/`gsap.call()`; size the clip to the content). Each recipe is a named choreography helper you compose rather than reinventing.
+
+```js
+// entryFadeRise — THE workhorse: rise 12px + fade, house ease, base duration
+gsap.from('.el', { opacity: 0, y: 12, duration: 0.6, ease: 'power3.out' });
+
+// entryFade — presence only (overlays, avatars)
+gsap.from('.el', { opacity: 0, duration: 0.6, ease: 'power3.out' });
+
+// entryScale — calm scale-up
+gsap.from('.el', { opacity: 0, scale: 0.92, duration: 0.6, ease: 'power3.out' });
+
+// blurReveal — opacity + blur + rise off ONE tween (one progress, many channels)
+gsap.from('.el', { opacity: 0, y: 16, filter: 'blur(10px)', duration: 0.6, ease: 'power3.out' });
+
+// wordStagger — each word rises in sequence (wrap words in <span>)
+gsap.from('.word', { opacity: 0, yPercent: 120, duration: 0.6, ease: 'power3.out', stagger: 0.13 });
+
+// heroReveal — the ONE place a pop is allowed (≤1 per scene)
+gsap.from('.hero', { opacity: 0, y: 16, scale: 0.97, duration: 0.8, ease: 'back.out(1.4)' });
+
+// exitFadeFall — fade + drop, faster, ease-in (an exit doesn't settle)
+gsap.to('.el', { opacity: 0, y: 8, duration: 0.33, ease: 'power2.in' });
+```
+
+**Entrance → hold → exit, on one timeline:**
+
+```js
+const tl = gsap.timeline();
+tl.from('.el', { opacity: 0, y: 12, duration: 0.6, ease: 'power3.out' })  // in (base)
+  .to({},        { duration: 1.5 })                                       // hold
+  .to('.el',     { opacity: 0, y: 8, duration: 0.33, ease: 'power2.in' }); // out (fast)
+```
+
+### CSS equivalents (no JS)
+
+```css
+/* house ease entrance */
+.el { animation: rise 0.6s cubic-bezier(0.16, 1, 0.3, 1) both; }
+@keyframes rise { from { opacity: 0; transform: translateY(12px); } to { opacity: 1; transform: none; } }
+
+/* staggered siblings — 0.13s steps */
+.w:nth-child(1){animation-delay:0s}.w:nth-child(2){animation-delay:.13s}.w:nth-child(3){animation-delay:.26s}
+```
+
+## Brand kit — set the palette once, re-skin everything
+
+Don't hardcode hex and font per snippet. Declare the brand as top-level `merge[]` fields and reference the tokens in every clip's `css`/`html` — one edit re-skins the whole video — brand tokens applied once, via Shotstack merge:
+
+```json
+"merge": [
+  { "find": "ink",    "replace": "#141414" },
+  { "find": "accent", "replace": "#D96B82" },
+  { "find": "bg",     "replace": "#08080A" },
+  { "find": "font",   "replace": "Clash Display, system-ui, sans-serif" }
+]
+```
+
+```css
+.title { color: {{ink}}; font-family: {{font}}; }
+.cta   { background: {{accent}}; }
+```
+
+`merge` find/replace runs over the whole edit, including `html`/`css` strings, so `{{accent}}` resolves everywhere. Keep one accent and use it sparingly — a headline word, a number, a CTA, one glow — everything else neutral. **Colour is earned, never sprinkled.**
+
+## Motion checklist
+
+Before rendering anything animated:
+
+1. **Durations from the scale?** (`0.6` in, `0.33` out — not `0.45`, `0.7`, `1.2`.)
+2. **House ease, not linear?** `power3.out` / `cubic-bezier(0.16,1,0.3,1)` for tracked motion.
+3. **Overshoot only on one hero element**, if at all.
+4. **Stagger is `0.13`**, applied via `stagger` / `animation-delay`.
+5. **Travel 12–24 px; scale ≥ 0.92.** Restraint over flash.
+6. **One focal element per moment;** competing elements staggered.
+7. **It holds before it cuts** (settled `hold`, not an instant exit).
+8. **Brand colours via `merge[]`**, accent used sparingly.
+
+## See also
+
+- [`html5-snippets.md`](html5-snippets.md) — ready-made clips that already follow these tokens
+- [`html5.md`](html5.md) — the html5 sandbox rules these obey (seekable-only, sizing, fonts)
+- `shared/agent-core.md` → "Motion language" — the compact token summary (shared with the MCP server)

package/references/positioning.md

@@ -0,0 +1,64 @@
+# Positioning & coordinates
+
+How `position`, `offset`, `width`/`height`, `scale`, and the transform fields place a clip in the frame. `shared/agent-core.md` carries the one-paragraph summary; this is the full reference.
+
+## The coordinate model
+
+`position` picks one of nine **anchor points** in the frame; `offset` then nudges the clip from that anchor. **`offset` is a fraction of the output frame — not pixels, and not a centred −1..+1 grid:**
+
+- `offset.x` positive → **right** (a fraction of frame width); `offset.y` positive → **up** (a fraction of frame height). Note `y` is *up*-positive, the opposite of typical screen coordinates.
+- `position:"center"` with `offset:{ "x":0, "y":0 }` sits dead centre. `offset:{ "x":0.5 }` moves half a frame-width right; `offset:{ "x":-1 }` moves a full frame-width left — off-screen.
+- The field accepts ±10; anything past ±1 already moves the clip partly or fully out of frame (no error).
+
+## Anchor points
+
+`position` pins the clip's centre to the named point; `offset` shifts from there.
+
+| | left edge | centre | right edge |
+|---|---|---|---|
+| **top edge** | `topLeft` | `top` | `topRight` |
+| **middle** | `left` | `center` *(default)* | `right` |
+| **bottom edge** | `bottomLeft` | `bottom` | `bottomRight` |
+
+Example: `position:"topLeft"`, `offset:{ "x":0.05, "y":-0.05 }` → a 5% margin in from the top-left corner.
+
+## Offset in numbers
+
+On a 1920×1080 frame: `offset.x:0.1` → 192 px right; `offset.y:0.1` → 108 px up; `offset.x:-0.5` → 960 px left (half the frame). Because the shift scales with the frame, the same `offset` looks the same at any resolution.
+
+## Sizing & fit (image / video)
+
+Give a clip a `width`/`height` (pixels) to define a box; `fit` decides how the media fills it:
+
+| `fit` | behaviour |
+|---|---|
+| `crop` *(default)* | fill the box, keep aspect ratio, crop the overflow |
+| `contain` | fit entirely inside the box, keep aspect ratio, letterbox the gaps |
+| `cover` | stretch to the box exactly — **distorts** if the aspect ratio differs |
+| `none` | no scaling; crop to the box |
+
+`scale` then multiplies the result (`1` = the fit result, `0.5` = half). `scale` is uniform on both axes — for a deliberate non-uniform stretch, use `fit:"cover"` with a `width`/`height`.
+
+## Sizing text
+
+Give a `rich-text` clip a `width`/`height` to set its text box: text wraps to that width, and `align` (`horizontal`: `left`/`center`/`right`; `vertical`: `top`/`middle`/`bottom`) positions the text inside it. **Without a `width`/`height`, the box defaults to the whole frame** — so `align` centres the text across the entire output and `position`/`offset` then move that full-frame block, which is rarely what you intend. Set `width`/`height` on any text you want placed precisely.
+
+## Transforms
+
+- `scale` — uniform multiplier (above).
+- `transform.rotate.angle` — degrees clockwise; rotates around the clip's own centre, so it spins in place wherever you positioned it.
+- `transform.skew.x` / `.y` — shear.
+- `transform.flip.horizontal` / `.vertical` — mirror.
+- `opacity` — `0`–`1`.
+
+## Order of operations
+
+`fit` (scale media into the box) → `position` (anchor) → `offset` (nudge) → `rotate` / `skew` → `scale`. Worth remembering when a result surprises you: scaling is applied last, around the positioned anchor.
+
+## Common mistakes
+
+1. **`offset.y` sign.** Positive `offset.y` moves **up**; use a negative value to move down.
+2. **Expecting a centred −1..+1 grid.** There isn't one — `offset` is a fraction of the frame measured from the `position` anchor. `offset.x:-1` is a whole frame-width left, not "the left edge".
+3. **`fit:"cover"` distorts.** It stretches to the box. Use `fit:"crop"` to fill while keeping aspect ratio.
+4. **Unsized text.** A `rich-text` with no `width`/`height` fills the frame; set them to place text precisely.
+5. **Offsets off-screen.** Past ±1 the clip leaves the frame silently — no error.

package/references/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-Common errors and the fix for each. If your error isn't here, run `shotstack feedback` to file a pre-filled GitHub issue with the render UUID attached — engineers can find server-side state in seconds.
+Common errors and the fix for each. **Catch most of them before rendering:** `shotstack validate <file>` checks an Edit against the schema and flags same-track overlaps, unloaded fonts and non-public URLs offline — no API key, no credits. If your error isn't here, run `shotstack feedback` to file a pre-filled GitHub issue with the render UUID attached — engineers can find server-side state in seconds.
 
 ## Contents
 
@@ -9,6 +9,7 @@ Common errors and the fix for each. If your error isn't here, run `shotstack fee
 - Video looks stretched / squished after rendering
 - "Font not found"
 - Captions cover the whole frame
+- Clips flicker / "clips overlap" on one track
 - Timeline renders but layers are wrong
 - "Invalid asset URL"
 - "Render failed" with no other detail
@@ -63,6 +64,12 @@ A `rich-caption` clip without `width`, `height`, and `fit: "none"` defaults to f
 
 **Fix:** use one of the five named presets in `references/caption.md` (Nico, Kai, Kapow, Lovely Little Lychee, Rizz) which include the right dimensions, or set `width`/`height`/`fit: "none"` explicitly on your clip.
 
+## Clips flicker / "clips overlap" on one track
+
+Two clips on the **same track** have overlapping `start`/`length` ranges, so the engine can't decide which to show — they flicker. This is the most common structural mistake when several elements appear at once (e.g. a title, a price and a button on an end card all at `start: 8`).
+
+**Fix:** put anything visible at the same time on its **own track**. Sequential clips (one ends, the next begins — chain them with `"start": "auto"`) can share a track. `shotstack validate <file>` pinpoints the offending track and clip indices offline. See `shared/agent-core.md` → "Don't overlap clips on the same track" for a before/after.
+
 ## Timeline renders but layers are wrong
 
 You assumed `tracks[0]` was the bottom layer.

package/shared/agent-core.md

@@ -0,0 +1,262 @@
+# Shotstack Agent Core
+
+Universal Edit JSON authoring conventions. Read this **before composing any Edit JSON**. The conventions agents most often get wrong are listed here once. The same file ships with both the Shotstack CLI skill and the Shotstack MCP server.
+
+## Before composing JSON: check the schema
+
+Don't invent property names or enum values. The Shotstack schema is published — fetch one of these before composing JSON from scratch:
+
+- <https://shotstack.io/docs/api/api.edit.json> — single-file OpenAPI Schema. Machine-validatable; load it once and validate locally instead of round-tripping the API.
+- <https://shotstack.io/docs/api/> — interactive HTML reference. Fastest for human scanning.
+- <https://shotstack.io/docs/guide/llms-full.txt> — single-file LLM-friendly version of the full guide + reference.
+- <https://github.com/shotstack/oas-api-definition/tree/main/schemas> — raw OpenAPI YAML, source of truth.
+
+CSS naming conventions (`alignment`, `vertical: "center"`) **do not** apply. The spec uses precise names that often differ from web/CSS instincts:
+
+| You'd guess (wrong) | API uses (right) |
+|---|---|
+| `alignment` | `align` |
+| `align: "center"` (string on rich-text asset) | `align: { "horizontal": "center", "vertical": "middle" }` (object) |
+| `align.vertical: "center"` | `align.vertical: "middle"` |
+| `font.name` | `font.family` |
+| `duration` | `length` |
+| `transitions: [...]` (array) | `transition: { in, out }` (object) |
+| `fit: "cover"` (CSS instinct: scale+crop maintaining aspect) | `fit: "crop"` — Shotstack's `cover` STRETCHES without maintaining aspect ratio |
+
+When the API rejects a property, the error message names the field — fix and retry. Don't guess twice.
+
+## Track ordering is REVERSED
+
+`timeline.tracks` is an array. **The first element (`tracks[0]`) is the TOP layer; the last element is the BOTTOM layer.** This is opposite to most z-index conventions.
+
+> "Tracks are layered on top of each other in the same order they are added to the array with the top most track layered over the top of those below it." — [Shotstack docs](https://shotstack.io/docs/guide/architecting-an-application/guidelines/)
+
+Practical rule: **put captions, overlays, and titles in early tracks; put video/image backgrounds in later tracks.**
+
+```json
+{
+  "timeline": {
+    "tracks": [
+      { "clips": [/* TOP — captions */] },
+      { "clips": [/* MIDDLE — title overlay */] },
+      { "clips": [/* BOTTOM — background video */] }
+    ]
+  }
+}
+```
+
+## Smart clip strings
+
+These string values are accepted in addition to numbers:
+
+| Where | Value | Meaning |
+|---|---|---|
+| `clip.start` | `"auto"` | Start when the previous clip on the same track finishes |
+| `clip.start` | `"alias://<name>"` | Inherit start from another clip with `alias: "<name>"` |
+| `clip.length` | `"auto"` | Asset's natural duration. Use for foreground (video, voiceover, scene). |
+| `clip.length` | `"end"` | Until timeline ends, capped at asset duration. Use for background (music, captions, watermark). |
+| `clip.length` | `"alias://<name>"` | Inherit length from another clip |
+
+`"end"` does NOT loop short audio — use a numeric `length` if you need precise control.
+
+The `alias://` protocol is also used in `rich-caption` `src` to auto-transcribe a referenced audio/video clip — see `references/caption.md`.
+
+## Public HTTPS URLs only
+
+All asset `src` URLs must be publicly accessible HTTPS. **No local file paths, no `data:` URIs, no signed URLs that expire mid-render.** The render workers fetch assets from the public internet.
+
+For test renders without your own assets, use the placeholder library at <https://shotstack-assets.s3.amazonaws.com/> — see `references/asset-library.md`.
+
+## Don't overlap clips on the same track
+
+Clips on the same track must not have overlapping `start`/`length` ranges — overlapping clips flicker because the engine can't decide which to display. **Anything visible at the same time goes on a separate track.** This is the most common structural mistake.
+
+```jsonc
+// WRONG — three simultaneous end-card lines on ONE track (all overlap 8.0–11.0)
+{ "clips": [
+  { "asset": { "type": "rich-text", "text": "TITLE" },    "start": 8.0, "length": 3 },
+  { "asset": { "type": "rich-text", "text": "$395" },     "start": 8.0, "length": 3 },
+  { "asset": { "type": "rich-text", "text": "SHOP NOW" }, "start": 8.0, "length": 3 }
+] }
+
+// RIGHT — one track each
+"tracks": [
+  { "clips": [ { "asset": { "type": "rich-text", "text": "TITLE" },    "start": 8.0, "length": 3 } ] },
+  { "clips": [ { "asset": { "type": "rich-text", "text": "$395" },     "start": 8.0, "length": 3 } ] },
+  { "clips": [ { "asset": { "type": "rich-text", "text": "SHOP NOW" }, "start": 8.0, "length": 3 } ] }
+]
+```
+
+Sequential clips (one finishes, the next starts) **can** share a track — `"start": "auto"` chains them. A cross-fade needs two tracks with a small time overlap and a `transition` on each.
+
+**Validate before you render:** `shotstack validate <file>` catches same-track overlaps — plus unloaded fonts, non-public `src` URLs, and wrong property names/enums — offline, no API key, no credits.
+
+## Clip motion & rich-text fields (cheatsheet)
+
+Compose from this rather than round-tripping the full schema — these are the values renders actually use. (`api.edit.json` stays authoritative; `shotstack validate` checks against it.)
+
+**Clip-level (wraps any asset):**
+
+| Field | Values |
+|---|---|
+| `fit` | `crop` (fill + crop, default — CSS `object-fit: cover`) · `contain` (letterbox) · `cover` (stretch, ignores aspect) · `none` |
+| `position` | `center` `top` `bottom` `left` `right` `topLeft` `topRight` `bottomLeft` `bottomRight` |
+| `offset` | `{ "x": <−1..1>, "y": <−1..1> }` — fraction of the canvas; **`y` positive = up** |
+| `scale` / `opacity` | number (`1` = the fit result) / `0..1` |
+| `effect` | Ken-Burns drift: `zoomIn` `zoomOut` `slideLeft` `slideRight` `slideUp` `slideDown` — each also `…Slow` / `…Fast` |
+| `filter` | `blur` `boost` `contrast` `darken` `greyscale` `lighten` `muted` `negative` |
+| `transition` | `{ "in": …, "out": … }` ↓ |
+
+**`transition.in` / `.out`** — each also takes a `Slow`/`Fast` suffix (e.g. `fadeSlow`, `slideUpFast`):
+`none` `fade` `reveal` `wipeLeft` `wipeRight` `slideLeft` `slideRight` `slideUp` `slideDown` `carouselLeft` `carouselRight` `carouselUp` `carouselDown` `shuffle*` (eight corners, e.g. `shuffleTopRight`) `zoom`.
+
+**`rich-text` asset** — the styled-text workhorse (use instead of `text`/`title`):
+
+```json
+{
+  "type": "rich-text",
+  "text": "UTOPIA",
+  "font": { "family": "<loaded-family>", "size": 160, "weight": "700", "color": "#141414", "opacity": 1 },
+  "style": { "letterSpacing": 6, "lineHeight": 0.95, "textTransform": "uppercase", "textDecoration": "none" },
+  "stroke": { "width": 3, "color": "#000000" },
+  "shadow": { "offsetX": 0, "offsetY": 6, "blur": 18, "color": "#000000", "opacity": 0.4 },
+  "background": { "color": "#ffffff", "opacity": 1, "borderRadius": 16 },
+  "align": { "horizontal": "center", "vertical": "middle" },
+  "animation": { "preset": "fadeIn", "duration": 0.6, "style": "word", "direction": "up" }
+}
+```
+
+`align.horizontal` = `left|center|right`; `align.vertical` = `top|middle|bottom` (**not** `center`). `animation.preset` = `fadeIn` `slideIn` `typewriter` `ascend` `shift` `movingLetters`; `animation.style` = `character|word`; `animation.direction` = `left|right|up|down`. Give the clip a `width`/`height` box so text wraps and aligns where you expect.
+
+For motion beyond this (kinetic type, count-ups, shine sweeps, grain, pulsing CTAs) reach for `html5` — see [`references/html5-snippets.md`](../references/html5-snippets.md).
+
+## Motion language (house tokens)
+
+Compose motion from a **closed set of tokens** so a multi-clip edit feels like one production, not eight unrelated effects. **Don't invent a new easing or duration per clip.** Full recipes (GSAP/CSS, choreography, brand kit) in [`references/motion.md`](../references/motion.md).
+
+- **Durations (seconds):** `instant 0.2 · fast 0.33 · base 0.6 · slow 0.8 · slower 1.0 · hold 1.5`. Entrances default to **`base` (0.6)**; **exits are faster** (`fast`).
+- **One house ease, no overshoot:** html5 GSAP `power3.out` (in) / `power2.in` (out); CSS `cubic-bezier(0.16, 1, 0.3, 1)`. Never raw `linear` for tracked motion. A gentle `back.out(1.4)` is reserved for **one** hero element per scene — calm is the default.
+- **One stagger:** `0.13s` between siblings (GSAP `stagger: 0.13`; CSS `animation-delay` steps).
+- **Restraint:** translate 12–24 px (not 80), scale ≥ 0.92, one focal element per moment, let a reveal settle (`hold`) before it cuts.
+- **rich-text `animation`** (entrance-only — exits use the clip `transition.out`): set `duration` from the scale (e.g. `0.6`); `preset:"ascend"` + `direction:"up"` is the rise-and-fade workhorse; for a word cascade use `preset:"shift"` + `style:"word"` + `direction:"up"` (`style` works only on `typewriter`/`shift`; `direction` is required for `slideIn`/`ascend`/`shift`/`movingLetters`).
+- **Brand once:** put palette/font in top-level `merge[]` (`{{ink}}`, `{{accent}}`, `{{font}}`) and reference them in every clip — one edit re-skins the whole video. Accent used sparingly.
+
+## Positioning & coordinates
+
+`position` picks one of nine anchor points (`center` default; `top` `bottom` `left` `right` `topLeft` `topRight` `bottomLeft` `bottomRight`); `offset` nudges from there. **`offset` is a fraction of the output frame, not a centred −1..+1 grid:** `offset.x` positive → right (× frame width), `offset.y` positive → **up** (× frame height). Range is ±10; anything past ±1 pushes the clip off-frame.
+
+Clip-level `width`/`height` (pixels) define a bounding box. For `image`/`video`, `fit` fills it — `crop` (keep aspect, crop overflow) · `contain` (letterbox) · `cover` (**stretch, distorts**) · `none`. For `rich-text`, that same clip box sets the text-wrap width and the area `align` positions within — **size text on the clip, not the asset.** Without `width`/`height` a clip fills the frame, so unsized text centres across the whole output. `scale` then multiplies the result (uniform on both axes).
+
+Order of operations: fit → position → offset → rotate → scale. Full reference: [`references/positioning.md`](../references/positioning.md).
+
+## Output resolution
+
+Pick `output.resolution` (preset) OR `output.size.width`+`output.size.height` (custom):
+
+| Preset | Pixels @ fps |
+|---|---|
+| `preview` | 512×288 @ 15 |
+| `mobile` | 640×360 @ 25 |
+| `sd` | 1024×576 @ 25 |
+| `hd` | 1280×720 @ 25 (default) |
+| `1080` | 1920×1080 @ 25 |
+
+Custom sizes must be divisible by 2.
+
+## Asset types
+
+Use only the **current** asset types; the deprecated ones still parse but should not be used in new templates.
+
+### Current
+
+| Type | Purpose |
+|---|---|
+| `video` | Video file (mp4, mov, webm). |
+| `image` | Static image — `jpg`, `png`, `webp`, `gif`, `bmp`, `tiff`. |
+| `audio` | Audio clip placed at a specific time on the timeline. |
+| `rich-text` | Styled text overlay with full typography control. **Use this instead of `text`/`html`/`title`.** |
+| `svg` | Vector graphics from raw SVG markup. See `references/svg.md`. |
+| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap/d3/anime/lottie. See `references/html5.md`. **Never use the deprecated `html` asset.** |
+| `rich-caption` | Word-level animated captions sourced from audio, video, or subtitle files. See `references/caption.md`. |
+| `luma` | Luma matte for masking effects. |
+| `image-to-video` | **AI**: animate a still image into a short video clip. Billed per generation. |
+| `text-to-image` | **AI**: generate an image from a text prompt. Billed per generation. |
+| `text-to-speech` | **AI**: generate speech from a text prompt. Billed per generation. |
+
+`timeline.fonts[]` is a separate field for custom font URLs (not an asset type).
+
+For background music, **use an `audio` asset on its own track** with `length: "end"`. Do NOT use `timeline.soundtrack` — it is deprecated. The audio asset path supports keyframes, custom timing, fades, and effects; soundtrack does not.
+
+### Deprecated — do not use
+
+`text`, `title`, `caption`, `html`, `shape`. They still parse but produce inferior output. Replace with:
+
+| If you'd use… | Use instead |
+|---|---|
+| `text` or `title` | `rich-text` |
+| `caption` | `rich-caption` |
+| `html` | `html5` (for motion graphics or animated overlays) or `rich-text` (for static styled text) |
+| `shape` | `svg` with `<rect>`, `<circle>`, `<polygon>` etc. |
+| `timeline.soundtrack` | `audio` asset on its own track with `length: "end"` |
+
+### AI-generated assets
+
+`image-to-video`, `text-to-speech`, and `text-to-image` are billed per generation **even when invoked through the sandbox stage endpoint** (which is otherwise free). They are async — the render submits the AI job and waits. Renders containing AI assets take longer.
+
+## The design ladder — escalate from rich-text to html5
+
+One overlay is a `rich-text` job. **Several videos "in different styles" is not** — making them all `rich-text` ships one look eight times. Match the asset to the ambition:
+
+| Level | Asset | Use for |
+|---|---|---|
+| 1 — type & layout | `rich-text` | Titles, lower-thirds, kickers, captions, price/CTA pills. Fast and reliable; the right default for static styled text. |
+| 2 — shapes | `svg` | Colour panels, rules, badges, frames, geometric accents behind or around type. |
+| 3 — motion graphics | `html5` | Kinetic type, count-ups / price odometers, shine sweeps, animated gradients, film grain, masked reveals, data-driven overlays — anything that should *move* beyond a `transition` or a Ken-Burns `effect`. gsap / anime / d3 / lottie are preloaded. See [`references/html5.md`](../references/html5.md) and the copy-paste clips in [`references/html5-snippets.md`](../references/html5-snippets.md). |
+
+**When the brief asks for a *range*, deliberately spread across the ladder.** A strong set: a couple of clean `rich-text` studio cuts, one or two `svg` colour-block promos, and several `html5` pieces carrying the real motion (kinetic headline, price odometer, shine-swept CTA, grain-graded teaser). Reserve the elaborate `html5` treatments for the hero / hype cuts where motion sells the product. If every clip in a "variety" brief is `rich-text`, you have not delivered variety.
+
+## Fonts
+
+Use **custom Google Fonts via `timeline.fonts[]`**. System fonts (`Arial`, `Helvetica`, `Times New Roman`) are NOT installed and will fail with "Font not found".
+
+**CRITICAL: Do NOT construct or fabricate Google Fonts URLs from memory.** Google rotates them (`v26 → v31 → ...`) and the hash filenames change with each version. Any URL you reconstruct from training data is almost certainly a 404. **Use ONLY the verified entries below, copied verbatim.**
+
+See `references/fonts.md` for how to source fonts from the Studio SDK catalogue and the built-in fallback fonts.
+
+### Usage example
+
+```json
+{
+  "timeline": {
+    "fonts": [
+      { "src": "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf" }
+    ],
+    "tracks": [
+      {
+        "clips": [{
+          "asset": {
+            "type": "rich-text",
+            "text": "Hello",
+            "font": { "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c", "size": 60, "weight": "700", "color": "#ffffff" }
+          },
+          "start": 0, "length": 3
+        }]
+      }
+    ]
+  }
+}
+```
+
+The `font.family` value MUST match the `family` column in the table above (it's the filename basename without `.ttf`). If `family` and the URL's basename don't match, the font will not load.
+
+## Top 5 mistakes
+
+1. **Reverse track order.** `tracks[0]` is the TOP layer, not the bottom. Captions go in early tracks; backgrounds go in late tracks.
+2. **System fonts.** `Arial`, `Helvetica`, `Times New Roman`, etc. are not installed. Use Google Fonts via `timeline.fonts[]` (preferred) or one of the built-in fonts in `references/fonts.md`.
+3. **Captions fill the whole frame.** A `rich-caption` clip without `width`, `height`, and `fit: "none"` covers the entire output. Use a named preset from `references/caption.md`.
+4. **`<text>` inside an SVG asset.** Raw `<text>` is unsupported. Use a `rich-text` asset for any text content; reserve SVG for shapes only.
+5. **Composing custom caption styles when presets exist.** The five named presets (Nico, Kai, Kapow, Lovely Little Lychee, Rizz) cover the common styles. Use one verbatim from `references/caption.md` unless the user asks for something specific.
+
+## Per-topic deep dives
+
+For details beyond this core guide (rich-caption presets, SVG constraints, full font URL list, troubleshooting), see the `references/` directory in the Shotstack CLI repo or fetch the topic-specific docs from `https://shotstack.io/docs/guide/llms-full.txt`.