@devinilabs/reelstack 1.2.0

package/docs/buyers-guide.md

@@ -0,0 +1,220 @@
+# ReelStack — Buyer's Guide
+
+Welcome. This guide walks you from a fresh laptop to your first rendered ReelStack reel in under 15 minutes.
+
+## 1. Prerequisites
+
+You don't need to install everything by hand — `init`'s readiness gate (v1.2+) detects what's missing and either offers to install it (macOS + Homebrew) or prints the exact command for your platform. The table below is for reference if you'd rather pre-install.
+
+| Tool | Why | macOS | Linux | Windows |
+|---|---|---|---|---|
+| **Node ≥ 20** | ReelStack CLI runtime | `nvm install 20` or [nodejs.org](https://nodejs.org/) | `nvm install 20` / [nodejs.org](https://nodejs.org/) | [nodejs.org](https://nodejs.org/) installer |
+| **Remotion 4** | Video framework | auto-bootstrapped by `init`, or `npm create video@latest` | same | same |
+| **ffmpeg** | Audio resample + render mux | `brew install ffmpeg` (init can run this for you) | `apt-get install ffmpeg` (Debian/Ubuntu) · `dnf install ffmpeg` (Fedora) · `pacman -S ffmpeg` (Arch) | `choco install ffmpeg` · `scoop install ffmpeg` |
+| **whisper-cpp** | Frame-accurate beat extraction (only required for `/reelstack-beats`) | `brew install whisper-cpp` (init can run this) | build from source: [github.com/ggerganov/whisper.cpp](https://github.com/ggerganov/whisper.cpp) | build from source, or `scoop install whisper.cpp` |
+| **Whisper model** | The `base.en` model file (only `/reelstack-beats`) | `curl -L -o /tmp/ggml-base.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin` | same | (PowerShell) `Invoke-WebRequest -Uri https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin -OutFile $env:TEMP\ggml-base.en.bin` |
+| **Claude Code** | Where you invoke the slash commands | [claude.com/claude-code](https://claude.com/claude-code) | same | same |
+
+**Platform note:** if you're on Linux or Windows, plan on running `init` twice — once to detect what's missing (it will print the right install command and exit), then again after you've installed. macOS+Homebrew users can stay in a single session because `init` will offer to run `brew install` directly.
+
+## 2. Buy a license
+
+- Visit [devini.io/reelstack](https://devini.io/reelstack).
+- Pay ₹149 INR (India) / $3 USD (elsewhere). Region is detected at checkout. You'll receive a license key by email within ~30 seconds.
+- Keep the key — you'll paste it during `init`.
+
+## 3. Install
+
+In any Remotion project, or in any folder where you want a fresh one created:
+
+```bash
+npx @devinilabs/reelstack init
+```
+
+`init` runs a **4-tier readiness gate** — every tier is a hard precondition for the next, and the success banner only prints if all four pass.
+
+```
+   1. License verify
+   2. Tier 1: Node ≥ 20                      (exits with nvm/fnm guide if not)
+   3. Tier 2: ffmpeg + whisper-cpp           (auto-install on macOS+brew;
+                                              prints platform-specific
+                                              command on Linux/Windows)
+   4. Install ~/.reelstack/ runtime
+      Install ~/.claude/skills/reelstack/
+      Install 13 slash command stubs
+   5. Tier 3: Remotion project bootstrap     (npx create-video@latest --yes
+                                              --blank reelstack-project,
+                                              unless --no-bootstrap)
+   6. Tier 4: smoke test                     (scaffolds Demo.tsx, runs
+                                              `npx remotion compositions`,
+                                              runs `ffmpeg -version`,
+                                              skip with --skip-smoke)
+   7. Success banner
+```
+
+State is recorded at `~/.reelstack/state.json` so subcommands like `/reelstack-beats` know whether the dep was previously declined and can fail-fast with a clear message.
+
+### Flags
+
+```bash
+npx @devinilabs/reelstack init                    # full flow
+npx @devinilabs/reelstack init --name=my-reels    # bootstrap dir name (Tier 3)
+npx @devinilabs/reelstack init --skip-smoke       # skip Tier 4 (CI re-runs)
+npx @devinilabs/reelstack init --no-bootstrap     # skip Tier 3
+                                                   # (already-Remotion projects)
+```
+
+### What you'll see on each platform
+
+**macOS + Homebrew (the magic-experience path):**
+```
+✗ ffmpeg not found.
+? Run `brew install ffmpeg`? (Y/n) y
+[brew output…]
+✓ ffmpeg installed
+```
+
+**macOS without Homebrew, Linux, Windows:**
+```
+✗ ffmpeg not found.
+  Install ffmpeg via:
+    apt-get install ffmpeg     # Debian/Ubuntu
+    dnf install ffmpeg         # Fedora
+    pacman -S ffmpeg           # Arch
+  Then re-run: reelstack init
+```
+
+(Linux is shown above; Windows prints `choco install ffmpeg` / `scoop install ffmpeg`; macOS-without-brew prints the Homebrew install URL.)
+
+If anything's missing, the CLI will tell you exactly what to install — and on macOS+Homebrew, do it for you.
+
+## 4. Make your first reel
+
+In Claude Code, type:
+
+```
+/reelstack-glass
+```
+
+ReelStack will:
+
+- Print a 7-preset menu with one-line use-cases (default `claudewatch` for long-form skill drops; `graphify` for premium product reveals; `paperclip` for open-source launches; `gstack` for long-form toolkits; `lilagents` for mascot reveals; `jcode` for benchmark narratives; `claudewatchcta` for an 8s outro). Reply with a number or preset key.
+- Ask for a reel name.
+- Ask for an optional voiceover path (skip if you'll record later).
+- Create `src/<Name>Reel.tsx` pre-wired with the family's palette, primitives, BEAT skeleton, and IG safe zones.
+- Register the new composition in `src/Root.tsx`.
+- Print the family reference doc so you can see exactly what tools are available.
+- Offer to launch Remotion Studio.
+
+The other 4 family commands (`/reelstack-paper`, `/reelstack-dark`, `/reelstack-warm`, `/reelstack-forbidden`) follow the same flow with their own preset menus. Forbidden auto-defaults silently — it has only one preset (`heretic`) at v1.1.1.
+
+That's it — you're inside a real ReelStack reel.
+
+## 5. Lock motion to voiceover
+
+If you have a voiceover .wav, run:
+
+```
+/reelstack-beats public/my-vo.wav
+```
+
+ReelStack will:
+
+- Resample to 16kHz mono via ffmpeg.
+- Run whisper-cli to produce an SRT.
+- Parse the SRT into frame-accurate `BEAT` constants.
+- Print the const block ready to paste.
+
+**Important:** whisper base.en mishears tech jargon ("Claude" → "Cloud", "Remotion" → "Re-motion"). Use the timings exactly, but copy on-screen text from your script. ReelStack reminds you of this every time you run `/reelstack-beats`.
+
+## 6. Iterate
+
+Open Remotion Studio:
+
+```bash
+npm run dev
+```
+
+Pick your reel from the comp list. Scrub the timeline, tune motion, swap palette accents.
+
+Common moves:
+
+- **Add a primitive.** Import from `~/.reelstack/families/<family>/components/`.
+- **Tune a spring.** Reach for `springs.snappy`, `springs.gentle`, `springs.bouncy`, `springs.glass` in `~/.reelstack/utils/easing.ts`.
+- **Fix overlap with Instagram chrome.** Toggle `<SafeZones visible={true} />` to see the reserved bands.
+- **Pull a brand logo.** Run `/reelstack-icons logos:react` (or any Iconify ID).
+- **Capture a product UI.** Run `/reelstack-capture https://example.com`.
+
+**Reference reels.** ReelStack ships 12 reference reels at `~/.reelstack/reference/<family>/<preset>.tsx`. After scaffolding, your AI agent (Claude Code, etc.) can study these to give better iteration advice. To force a specific reference, pass `--reference=<preset>` to the scaffold command. See `~/.reelstack/docs/design-discipline.md` for the full catalog.
+
+## 7. Validate before posting
+
+```
+/reelstack-lint src/MyReel.tsx
+```
+
+ReelStack will check:
+
+- **Safe zone breaches.** No hero copy under top 290px or above bottom 422px.
+- **Motion floors.** Each scene has ≥3 simultaneous animation layers (≥4 in the opener).
+- **Hero text fit.** Counters and hero text don't overflow the canvas.
+- **Audio lock.** If you import `<Audio>`, you've defined `BEATS`.
+- **Hand-drawn brand SVGs.** Inline `<svg>` longer than 800 chars gets flagged — pull the real one via `/reelstack-icons`.
+
+Lint must pass before render. Pass `--force` to skip if you know what you're doing.
+
+## 8. Render
+
+```
+/reelstack-render MyReel --platform=ig
+```
+
+Or directly:
+
+```bash
+npx reelstack render MyReel --platform=ig
+```
+
+Platform presets:
+
+- **ig / tiktok:** 1080×1920, H.264, CRF 18, 8 Mbps.
+- **shorts:** 1080×1920, H.264, CRF 17, 9 Mbps.
+
+Output lands in `out/<Name>-<platform>.mp4`. Preview before posting.
+
+## 9. Update
+
+```bash
+npx @devinilabs/reelstack@latest init
+```
+
+Re-runs the full readiness gate against the latest npm release. New presets shipped in v1.x are pulled automatically — your purchase covers all v1.x updates. Your license key and `~/.reelstack/state.json` are preserved across updates.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `License missing or expired` | Run `npx @devinilabs/reelstack init` again. |
+| `ffmpeg not found` | macOS: `brew install ffmpeg`. Linux: `apt-get install ffmpeg` / `dnf install ffmpeg` / `pacman -S ffmpeg`. Windows: `choco install ffmpeg` or `scoop install ffmpeg`. |
+| `whisper-cli is not installed (init flagged this)` | You declined or skipped whisper during `init`. macOS: `brew install whisper-cpp`. Linux/Windows: build from [github.com/ggerganov/whisper.cpp](https://github.com/ggerganov/whisper.cpp) (or `scoop install whisper.cpp` on Windows). Then re-run `npx @devinilabs/reelstack init`. |
+| `whisper-cli not found` (when init never ran) | Same as above, then re-run `init`. |
+| `Whisper model not found` | macOS/Linux: `curl -L -o /tmp/ggml-base.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin`. Windows (PowerShell): `Invoke-WebRequest -Uri https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin -OutFile $env:TEMP\ggml-base.en.bin`. |
+| `ReelStack is NOT ready — smoke test failed at <step>` | The named step tells you which check failed: `scaffold-demo` = your `Root.tsx` is wrong; `remotion-compositions` = Remotion CLI couldn't load the project; `ffmpeg-version` = ffmpeg binary not executable. Fix and re-run `init` (or pass `--skip-smoke` to bypass). |
+| `Found a package.json in this folder, but it doesn't parse as valid JSON` | Your project's `package.json` has a syntax error. Fix it, or run `init` from a different directory. |
+| Reel scaffold registered but Studio shows blank | Wait 10s for HMR; if still blank, delete `node_modules/.cache` and `npm run dev` again. |
+| Whisper SRT mishears tech terms | Use timings as-is; replace on-screen text from your script. |
+
+## Support
+
+- Bugs: GitHub issues at the private repo (your license email contains the URL).
+- Licensing: licensing@devinilabs.com.
+- Updates: announced on [reelstack.dev](https://reelstack.dev).
+
+## Acknowledgments
+
+ReelStack v1.1+ stands on the shoulders of two outside skills, fully baked in (no peer install required):
+
+- **[leonxlnx/taste-skill](https://github.com/leonxlnx/taste-skill)** (MIT) — UI design-discipline ruleset by `@leonxlnx`. ReelStack bakes the master rules and per-family variant overlays (Soft / Minimalist / Brutalist) directly into its components, palettes, and lint. Anti-emoji, font lockdown, max-1-accent rule, hardware-accel-only animation, `prefers-reduced-motion` parity, 4-px grid alignment — all enforced by default. Full rule citations at [`docs/design-discipline.md`](design-discipline.md).
+- **[alchaincyf/huashu-design](https://github.com/alchaincyf/huashu-design)** (Personal Use Only) — design productivity skill by `@AlchainHust` (花叔). ReelStack adopts huashu-design's UX patterns (Design Direction Advisor, 5-dimension critique, multi-format export) without copying any code or text. The Warm Signature family's `huashu` preset is named for this same project as a credit hook.
+
+If ReelStack helps you ship, please consider starring both upstream skills.

package/docs/design-discipline.md

@@ -0,0 +1,130 @@
+# ReelStack — Design Discipline
+
+> The canonical reference of which taste-skill rules ReelStack enforces, with line-numbered citations to where each rule is implemented. v1.1+.
+
+ReelStack inherits design discipline from two outside skills, fully baked in (no peer install required):
+
+| Influence | License | How it's incorporated |
+|---|---|---|
+| [`leonxlnx/taste-skill`](https://github.com/leonxlnx/taste-skill) | MIT | Rules baked into components, palettes, and lint. Per-family variant overlays (Soft / Minimalist / Brutalist) ship as additional components. |
+| [`alchaincyf/huashu-design`](https://github.com/alchaincyf/huashu-design) | Personal Use Only | UX patterns adapted (Design Direction Advisor, 5-dim critique, multi-format render). **No code or text copied** — patterns only, with credit. |
+
+---
+
+## Master rules — universal across all 5 families
+
+These rules apply to every scaffolded reel, regardless of family.
+
+### 1. Font lockdown — Geist / Geist Mono only
+
+- **Banned at lint time**: Inter, Roboto, Helvetica, Arial, Open Sans, Lato, Source Sans Pro, Nunito, Poppins, Montserrat, Raleway, PT Sans, Ubuntu.
+- **Allowed**: Geist Sans, Geist Mono, system-ui (fallback). Editorial-serif options for Cream Paper / Warm Signature variants: Lyon Text, Newsreader, Playfair Display.
+- **Implementation**: `utils/banned-fonts.ts` + `BANNED_FONT` lint rule in `cli/lint.js`.
+
+### 2. No pure `#000000` text
+
+- Every family palette declares family-specific ink colors with WCAG AA+ contrast comments.
+- **Allowed inks**: Glass `#0E0E12`, Paper `#1a1a1a`, Dark `#f5f5f7` (fg), Warm `#fafafa` (fg), Forbidden `#0E0B12`.
+- **Lint rule**: `PURE_BLACK_TEXT` (flags `color: "#000"` or `"#000000"`).
+
+### 3. Max one accent per family at <80% saturation (Dark exception)
+
+- Glass, Paper, Warm, Forbidden each export `ALLOWED_ACCENTS` arrays — lint flags any color outside the allowlist as `ACCENT_ALLOWLIST_VIOLATION`.
+- Dark Cinematic intentionally allows multi-brand (Stitch rose + Gemini blue + Claude terracotta + NotebookLM blue can coexist) — documented in `families/dark/palette.ts`.
+- **Implementation**: `families/<x>/palette.ts` `ALLOWED_ACCENTS` exports.
+
+### 4. Hardware-accelerated animation only
+
+- Every animated component uses `transform` + `opacity` only. Never `top`, `left`, `width`, `height`.
+- Perpetual-motion components (e.g. `IridescentText`'s rotating gradient) opt into `will-change: transform, opacity, filter`.
+- **Implementation**: enforced by component design; verified during template generation.
+
+### 5. Spring-physics defaults
+
+- Named spring configs in `utils/easing.ts`: `springs.snappy / gentle / bouncy / glass / smooth`.
+- Linear easing requires explicit justification.
+- **Easings exported**: `power2In/Out`, `power3In/Out`, `power4In/Out`, `power5In/Out`, `expoIn/Out/InOut`, `backIn/Out`, `linear`.
+- Soft variant adds: `softInOut`, `softElastic`, `softSnappy` cubic-beziers (`utils/cubic-bezier.ts`).
+
+### 6. Anti-emoji
+
+- `FloatingGlyphs` uses unicode math/code symbols only: `± ∞ ∑ ⟨ ⟩ ∫ ≠ ∂ ∇ ⊕ ⊗`.
+- **Lint rule**: `EMOJI_GLYPH` (flags any unicode emoji in JSX text).
+
+### 7. Anti-AI-purple
+
+- `utils/ai-purple-blocklist.ts` exports `AI_PURPLE_HEXES = ["#7c3aed", "#8b5cf6", "#6366f1", "#a78bfa", "#c084fc", "#9333ea", "#7e22ce", "#a855f7"]`.
+- **Lint rule**: `AI_PURPLE_ACCENT` (flags any of these hexes anywhere in scaffolded code).
+- **Note**: Forbidden's ultraviolet `#6B5BD9` and plasma `#A87FE8` are family-specific overrides, NOT in the blocklist; they live in the Forbidden palette explicitly.
+
+### 8. Complete-output discipline
+
+- Scaffolded files compile cleanly. No `// ...rest of code`, no `// TODO`, no truncation.
+- **Lint rule**: `GENERIC_PLACEHOLDER` (flags `Lorem ipsum`, `John Doe`, `Acme Corp`, etc. in non-template files).
+
+### 9. Anti-generic content
+
+- Banned in shipped reels: `Lorem ipsum`, `John Doe`, `Acme Corp`, `placeholder text`. Templates use `__PLACEHOLDER__` syntax which the scaffolder replaces — those are exempt.
+
+### 10. `prefers-reduced-motion` parity
+
+- Every animated component accepts a `reduceMotion?: boolean` prop. Default `false`.
+- Templates read `reduceMotion` from Remotion's `getInputProps()` at module load — buyers can render a low-motion variant via `npx remotion render <id> out/x.mp4 --props='{"reduceMotion":true}'`.
+- **Lint rule**: `MISSING_REDUCE_MOTION` (flags components that import `useCurrentFrame` but don't accept `reduceMotion`).
+
+### 11. 4-px grid alignment
+
+- `utils/grid.ts` exports `GRID = 4` plus `GRID_2 / 4 / 6 / 8 / 12 / 16 / 24` named multiples.
+- Every padding / margin / gap should be a multiple of 4.
+- **Lint rule**: `SPACING_NON_GRID` (flags non-grid values; allows 1, 2 for hairlines).
+
+---
+
+## Per-family variant overlays
+
+| Family | Variant overlay(s) | Concrete additions |
+|---|---|---|
+| **Glass Iridescent** | Soft + General | `<GlassCardBezel />` (Double-Bezel inner-1px glass border), `softInOut / softElastic / softSnappy` cubic-bezier easings, diffused multi-layer shadow stack via `bezel` prop on `<GlassCard />`. |
+| **Cream Paper** | Minimalist + Soft | `<EditorialSerifText />` (Lyon Text → Newsreader → Playfair Display fallback), generous py-24+ padding multiplier, ultra-flat Minimalist card variant. |
+| **Dark Cinematic** | Brutalist Tactical + General | `<Scanlines />` (CRT scanline overlay, perpetual scroll), monospace-dominant micro-typography variant, hazard-red `#E61919` accent option (within multi-brand allowance). |
+| **Warm Signature** | Minimalist + Soft | Editorial-serif optional Warm hero variant (via `<EditorialSerifText />` import — works across families), diffused warm shadow stack. Single-accent rule already enforced via `ALLOWED_ACCENTS`. |
+| **Forbidden** | Brutalist Swiss Industrial | `<NewsprintTexture />` (halftone grain on cream-rose paper), no-border-radius GlassCard variant via `radius={0}` prop, asymmetric negative-space layout. |
+
+---
+
+## Productivity patterns (huashu-inspired, license-safe)
+
+These are UX patterns adapted from `alchaincyf/huashu-design` — no code/text copied; pattern only.
+
+| Pattern | ReelStack implementation |
+|---|---|
+| One-sentence brief → deliverable | Slash commands accept natural-language ARGUMENTS or `--brief="…"` flag. The skill parses, infers family + preset + duration, asks 1-2 confirmation questions max. |
+| Design Direction Advisor | `/reelstack-direction "<brief>"` returns 3 differentiated family picks with reasoning. `cli/direction.js` keyword-scores the brief against family profiles. |
+| 5-dimension expert critique | `/reelstack-lint <file> --critique` renders a radar across **palette · motion · timing · hierarchy · brand fit** with a Keep/Fix/Quick punch list. Heuristic scoring in `cli/lint.js`. |
+| Multi-format export | `/reelstack-render --format=mp4,gif` produces both. `--bgm=<path>` mixes background music. `--interpolate=60` requests 60fps. `--palette-optimize` quantizes GIF to 64 colors. |
+| Pre-delivery render verification | Before `/reelstack-render` calls `npx remotion render`, the CLI renders frames 0 / mid / last via `npx remotion still` and checks each PNG > 30 KB. Warns if any frame looks all-black. |
+| Style direction × design philosophy registry | `cli/direction.js` maps each ReelStack family to a profile (mood, best-for cases, presets, slash command). Powers the advisor. |
+
+---
+
+## Skip list — taste-skill rules that DON'T apply to a video product
+
+These are deliberately not enforced because they're UI/website-specific:
+
+- Scroll-based animation rules (no scroll in a rendered MP4).
+- Hover / active interactive states (viewers can't interact with playback).
+- Form input rules (no forms in a reel).
+- Navigation routing (no multi-page).
+- Responsive breakpoint rules — reels are fixed 9:16, no breakpoints.
+- `min-h-[100dvh]` viewport fixes (Remotion canvas is fixed).
+- Keyboard nav & ARIA tab order (no keyboard input on a rendered reel).
+- Viewport-relative typography (`clamp()`) — fixed canvas, fixed `px` values.
+
+---
+
+## Acknowledgments
+
+- **leonxlnx/taste-skill** — MIT-licensed design-discipline ruleset by `@leonxlnx`. ReelStack v1.1+ bakes its master rules and per-family variant overlays directly into the package. Thank you for the canonical reference.
+- **alchaincyf/huashu-design** — Personal-Use-Only design skill by `@AlchainHust` (花叔). ReelStack's `huashu` preset (Warm Signature family) is named for this project; v1.1+ adopts huashu-design's UX patterns (Design Direction Advisor, 5-dim critique, multi-format export) without copying code or text.
+
+If you're shipping content with ReelStack, please consider checking out both upstream skills.

package/docs/family-galleries/dark.md

@@ -0,0 +1,95 @@
+# Dark Cinematic — Family Reference
+
+> Late-night ad-film mood. Mood-lit cards. Multi-brand accents allowed.
+
+The family for premium product narratives — partnership reveals, integration showcases, "secret" reveals. Where Glass is a daylight reveal, Dark is the after-hours telecine.
+
+## Palette
+
+```
+bg            #0a0a0b   Zinc void.
+bgLift        #141416
+surface       #1a1a1d
+surfaceLift   #222226
+
+cardForest      #1a2e1f   Dark forest green for embedded UI / terminal cards.
+cardForestLift  #243a28
+
+fg            #f5f5f7   Foreground text.
+fgSoft        #d1d1d6
+fgMuted       #8e8e93
+fgDim         #5a5a60
+
+claude        #D4663A   Claude terracotta. Default accent.
+claudeSoft    #e07a54
+stitch        #ff4d9b   Stitch rose (allowed in cross-product reels).
+stitchSoft    #ff7fb8
+gemini        #4285f4   Gemini blue.
+notebookBlue  #4F7DF3   NotebookLM blue.
+
+safe          #4fc46a
+danger        #e25822
+amber         #fcbb00
+violet        #8d54ff
+
+terminalGreen #5be8a0   For embedded terminal blocks.
+```
+
+## Primitives
+
+| Component | Purpose |
+|---|---|
+| `DriftingSpotlights` | Two overlapping radial gradients drifting on sine/cosine. Family's signature ambient. |
+| `RadialVignette` | Edge-darkening gradient. Adds the "telecine" feel. |
+| `GridBackground` | 60×60 grid at 4% opacity with radial mask. |
+| `SegmentOpacity` (`so()` helper) | Inline scene-fade controller. The family's editing model. |
+| `Crossfade` | 0.45s in / 0.55s out — the family's standard timing. |
+| `ForestCard` | Dark-green card surface for UI/terminal embeds. Used heavily in claudedispatch. |
+
+## Presets
+
+| Preset | Source | Frames | Use when |
+|---|---|---|---|
+| `stitch` | StitchReel | 2297 (76.6s) | Cross-product workflow demo. Multi-brand. PaletteChips legend. |
+| `stitch2` | Stitch2Reel | 600 (20s) | 20s teaser variant with letterboxed hero clip. |
+| `codedrop` | CodeDropReel | 1110 (37s) | Short-form drop with overlay-friendly first 20s. |
+| `claudedispatch` | ClaudeDispatchReel | 2220 (74s) | Hero narrative with embedded UI cards. ForestCard heavy. |
+| `notebooklm` | NotebookLMReel | 1680 (56s) | Product integration narrative. NotebookLM blue dominant. |
+| `gpt55` | GPT55Reel | 2900 (97s) | Benchmark-thesis reel. OpenAI green vs. rival purple. |
+| `resourcescta` | ResourcesCTAReel | 210 (7s) | Outro CTA. Append to other Dark reels. |
+| `skills` | SkillsReel | 1260 (42s) | Ecosystem showcase. Bento grid (categories × platforms). |
+
+## House rules (Dark-specific)
+
+1. **Crossfades 0.45s in / 0.55s out.** Don't hard-cut between scenes. The `so()` helper enforces this.
+2. **Drifting spotlights at 0.003-0.004 sine drift.** Slower = stillness; faster = nervous energy. Stay in this band.
+3. **Multi-brand accents are allowed** — Stitch rose + Gemini blue + Claude terracotta can coexist in one reel. The single-accent rule does NOT apply.
+4. **ForestCard is the embedded-UI surface.** When showing a UI screenshot, terminal block, or benchmark table, frame it with a ForestCard.
+5. **Vignette is non-negotiable.** Always compose a `<RadialVignette />` over the background. Without it the reel reads "flat" instead of "cinematic".
+
+## Motion vocabulary
+
+- **Scene transitions:** `so(frame, fps, startSec, endSec)` — fades in over 0.45s, fades out over 0.55s.
+- **Spotlight drift:** sine on x-axis at rate 0.004, cosine on y-axis at rate 0.003.
+- **Card entrance:** spring snappy (damping 20, stiffness 200) — same as Paper, different palette.
+- **Color reveals:** Crossfade between accents over 12 frames; never instant swap.
+
+## Variant overlay (v1.1+)
+
+Dark Cinematic inherits from **leonxlnx/taste-skill-brutalist** (Tactical Telemetry mode) + **leonxlnx/taste-skill (master)**. The Brutalist Tactical overlay adds:
+
+- **`<Scanlines />`** — perpetual CRT scanline overlay. Configurable `spacing` (default 4px), `opacity` (default 0.06), `scrollSpeed` (default 0.5px/frame). Drops the reel into "declassified telemetry" feel.
+- **`reduceMotion` prop** on `DriftingSpotlights`, `FilmGrain` (dampens grain opacity), and `Scanlines` (freezes scroll).
+- **Multi-brand allowance documented** — Dark intentionally has NO `ALLOWED_ACCENTS` export. Stitch rose, Gemini blue, NotebookLM blue, Claude terracotta can coexist by design. The lint command treats Dark as the multi-brand exception.
+- **WCAG AA+ contrast** documented inline in `palette.ts` (fg: 18.7:1, fgSoft: 13.4:1, fgMuted: 6.4:1).
+- **Optional hazard-red `#E61919` accent** — pull from the Brutalist tactical-telemetry palette for "hold / abort / kill switch" callouts.
+
+## Reference reels (v1.1.1+)
+
+3 reference reels ship for this family at `~/.reelstack/reference/dark/<preset>.tsx`:
+
+- **stitch** — Multi-brand workflow demo (Stitch rose + Gemini blue + Claude terracotta).
+- **claudedispatch** — Hero-narrative reel with ForestCard surfaces + drifting spotlights.
+- **notebooklm** — Product-integration narrative (Claude × NotebookLM). Eleven scenes.
+
+These are the actual Devini Labs reels (asset-stripped). Read them when iterating on your scaffolded reel. Pattern adaptation is encouraged; verbatim re-publication is not.

package/docs/family-galleries/forbidden.md

@@ -0,0 +1,78 @@
+# Forbidden — Family Reference
+
+> Forbidden, mysterious, slightly off-kilter. Desaturated palette suggests something declassified.
+
+Inherits primitives from Glass but with rose-purple tinted shadows for the cream-rose paper background. **Never use iridescent gold here** — that hue belongs to Glass.
+
+## Palette
+
+```
+bg              #F2EBE5   Cream-rose paper.
+bgWarm          #EFE3DB
+bgCool          #ECE6E8
+
+ink             #0E0B12   Slightly darker than Glass for contrast on rose-cream.
+inkSoft         #26222A
+inkMuted        #5A5560
+inkDim          #8A848F
+
+ember           #D97757   Burning orange.
+crimson         #C4506B   Deep rose / refusal.
+ultraviolet     #6B5BD9   Nightshade / mechanism.
+plasma          #A87FE8   Electric violet / stars.
+
+shadowSoft      rgba(120,80,120,0.10)   The family's secret weapon. Never pure black.
+shadowMid       rgba(120,80,120,0.18)
+shadowDeep      rgba(120,80,120,0.28)
+
+glassFill       rgba(255,248,245,0.46)   Warmer than Glass — rose-tinted whites.
+glassFillStrong rgba(255,248,245,0.66)
+glassBorder     rgba(255,248,245,0.88)
+```
+
+## Primitives
+
+Inherited from Glass family, with two preset-specific additions:
+
+| Component | Purpose |
+|---|---|
+| `ForbiddenCausticBlobs` (template-inline) | Same as Glass `CausticBlobs` but with ember/crimson/ultraviolet/plasma stops. Multiply blend (not screen). |
+| `tintedShadow(depth)` (template helper) | Returns rose-purple tinted box-shadows at soft / mid / deep depths. |
+| All Glass primitives | Imported directly: `HairlineGrid`, `GlassCard`, `EyebrowPill`, `StaggeredWords`, `Counter`, `SonarRings`, `ParticleBurst`, `FloatingGlyphs`. |
+
+## Presets
+
+| Preset | Source | Frames | Use when |
+|---|---|---|---|
+| `heretic` | HereticReel | 1639 (54.6s) | Forbidden product reveal. The reference (and only) preset. |
+
+## House rules (Forbidden-specific)
+
+1. **NO iridescent gold.** Gold is Glass-only. Forbidden uses ember/crimson/ultraviolet/plasma — period.
+2. **Shadows are tinted rose-purple, never pure black.** Use `palette.shadowSoft / shadowMid / shadowDeep`. The lint command will flag pure-black shadows.
+3. **Caustic blobs use multiply blend (not screen).** Multiply darkens the rose-cream bg into deeper rose tones — that's the look. Screen would wash it out.
+4. **Particle bursts use the Forbidden palette.** Pass `colors={[ember, crimson, ultraviolet, plasma]}` — never the Glass iridescent set.
+5. **EyebrowPill tints flip.** Use `tint="violet"` (which now reads as ultraviolet on cream-rose). `tint="teal"` reads as plasma — both work.
+
+## Motion vocabulary
+
+- **Same as Glass** — gentle springs, power4Out reveals, sonar rings at 300-frame periods. Forbidden is a **palette + shadow** family, not a motion-language family. Reuse Glass motion confidently.
+- **Camera feel:** slightly slower transitions than Glass. Adds the "uneasy" feel. Try multiplying typical animation durations by 1.15×.
+
+## Variant overlay (v1.1+)
+
+Forbidden inherits from **leonxlnx/taste-skill-brutalist** (Swiss Industrial Print mode) + **leonxlnx/taste-skill (master)**. The Brutalist Swiss overlay adds:
+
+- **`<NewsprintTexture />`** — pure-SVG halftone grain overlay tuned for cream-rose paper (multiply blend, ember-rose tinted noise). Drops the reel into "declassified document on newsprint" feel. Configurable `opacity` (default 0.08).
+- **`reduceMotion` prop** on `ForbiddenCausticBlobs` (pins blobs at center), `EyebrowPill`, `StaggeredWords`, `Counter`, `SonarRings`, `ParticleBurst`, `FloatingGlyphs`. NewsprintTexture has no motion to reduce.
+- **`ALLOWED_ACCENTS`** export — lint allows only `[ink, ember, crimson, ultraviolet, plasma]`. Forbidden's `ultraviolet` and `plasma` are the only family-allowed exceptions to the global anti-AI-purple rule; nowhere else in ReelStack are those hues permitted.
+- **WCAG AA+ contrast** documented inline in `palette.ts` (ink: 17.6:1, inkSoft: 13.0:1, inkMuted: 6.8:1).
+- **No-border-radius variant** — pass `radius={0}` to `<GlassCard />` for the Brutalist Swiss "rigid grid" look.
+
+## Reference reels (v1.1.1+)
+
+1 reference reel ships for this family at `~/.reelstack/reference/forbidden/<preset>.tsx`:
+
+- **heretic** — Cream-rose paper + ember/crimson/plasma. The only Forbidden reel.
+
+These are the actual Devini Labs reels (asset-stripped). Read them when iterating on your scaffolded reel. Pattern adaptation is encouraged; verbatim re-publication is not.

package/docs/family-galleries/glass.md

@@ -0,0 +1,98 @@
+# Glass Iridescent — Family Reference
+
+> Premium product reveal. Underwater-light caustics, glass surfaces, iridescent text shimmer.
+
+The foundational ReelStack family. Most other families inherit primitives from here. When in doubt, scaffold Glass.
+
+## Palette
+
+```
+bg            #EFEAF2   Lavender cream — the family's signature background.
+bgWarm        #E9E2EE
+bgCool        #E4E9F2
+
+ink           #0E0E12   Body text on light backgrounds.
+inkSoft       #26242C
+inkMuted      #5A5867
+inkDim        #86848F
+
+iriCyan       #7FE8D4   Iridescent stops. Used by CausticBlobs,
+iriViolet     #8B7FE8     ParticleBurst, FloatingGlyphs.
+iriRose       #E89BC4
+iriGold       #F2D88F
+
+violetPill    #9D8BF2   EyebrowPill tints.
+tealPill      #85DDC9
+
+glassFill     rgba(255,255,255,0.42)   Default GlassCard fill.
+glassFillStrong  rgba(255,255,255,0.62) Strong / heavy variants.
+glassBorder   rgba(255,255,255,0.86)
+```
+
+## Primitives
+
+| Component | Purpose | Frame cost |
+|---|---|---|
+| `CausticBlobs` | Animated radial gradients drifting on sine paths. The signature ambient bg. | Cheap (CSS only). |
+| `HairlineGrid` | Subtle 72×72 grid with radial mask fade. Provides "environment". | Free (static CSS). |
+| `GlassCard` | Frosted glass surface. Variants: default / strong / heavy. | Free (CSS). |
+| `EyebrowPill` | Small contextual labels. Spring entrance (gentle). | Cheap. |
+| `StaggeredWords` | Word-by-word text reveal with spring easing. | Per-word spring. |
+| `Counter` | Numeric ticker with scale + blur entrance. Power4Out easing. | Cheap. |
+| `SonarRings` | Concentric expanding circles. Period ~300 frames. | Cheap (SVG). |
+| `ParticleBurst` | 12-20 particles radiating with velocity + gravity. Lifetime 60-120 frames. | Cheap (SVG). |
+| `LightBeam` | Rotating radial gradient with screen blend. For hero-moment emphasis. | Free (CSS rotation). |
+| `FloatingGlyphs` | Drifting unicode math symbols. NEVER emojis. | Cheap. |
+| `FilmStrip` | Perforated 35mm film roll with colored play-button thumbnails. Optional vertical scrubber playhead. | Cheap (CSS). |
+| `IridescentRing` | Concentric chromatic halo rings — multi-stop gradient strokes that rotate as they expand. | Cheap (SVG). |
+| `IridescentText` | Hero-word gradient treatment. 5-stop iridescent `background-clip: text` with rotating angle. | Free. |
+| `BreakdownCard` | Glass card with mono filename header, accent dot, 1–4 arrow rows, optional blinking cursor. | Cheap. |
+
+## Presets
+
+| Preset | Source | Frames | Use when |
+|---|---|---|---|
+| `graphify` | GraphifyReel | 1956 (65.2s) | Default. Multimodal product reveal. The reference build. |
+| `paperclip` | PaperclipReel | 1650 (55s) | Open-source product launch. PaperclipGlyph is the signature element. |
+| `gstack` | GstackReel | 2820 (94s) | Long-form feature-callout reel. Heavy GlassCard usage. |
+| `lilagents` | LilAgentsReel | 2160 (72s) | Character-driven (Bruce + Jazz). Dark dock-bg variant. ThoughtBubbles. |
+| `jcode` | JcodeReel | 2164 (72s) | Performance-claim reel. Single rust accent. ScrambleText + film grain. |
+| `claudewatch` | ClaudeWatchReel | 3156 (105.2s) | Longest in catalog. FilmStrip + IridescentText + BreakdownCard centerpiece — the deluxe preset. |
+| `claudewatchcta` | ClaudeWatchCTAReel | 240 (8s) | Standalone CTA cut. Append to longer reels as outro. |
+
+## House rules (Glass-specific)
+
+1. **Glass cards always over textured background.** Caustics + grid mandatory beneath every GlassCard.
+2. **FloatingGlyphs use unicode math/code symbols only.** Never emojis. The set: `± ∞ ∑ ⟨ ⟩ ∫ ≠ ∂ ∇ ⊕ ⊗`.
+3. **Iridescent stops named, not free-mixed.** Pull from `palette.iriCyan / iriViolet / iriRose / iriGold` — don't hand-mix.
+4. **Counter caps at 256px width on 5-digit numbers.** Default fontSize 144 is safe; don't go bigger without checking.
+5. **Tinted shadows on cream variants only (Forbidden).** Glass uses neutral shadows: `rgba(20,20,32,0.10–0.14)`.
+
+## Motion vocabulary
+
+- **Springs:** `springs.gentle` (damping 15, stiffness 80) for text entrances. `springs.snappy` (damping 20, stiffness 200) for cards.
+- **Easings:** `ease.power4Out` for hero reveals. `ease.expoOut` for camera moves. `ease.backOut` for playful elements.
+- **SonarRings period:** 300 frames default (10s). Reduce to 240 for faster anchor scenes.
+- **ParticleBurst lifespan:** 80 frames default. Spread 360px is the family standard.
+- **Audio lock:** `BEAT` constants from `/reelstack-beats`. Never eyeball.
+
+## Variant overlay (v1.1+)
+
+Glass Iridescent inherits from **leonxlnx/taste-skill-soft** + **leonxlnx/taste-skill (master)**. The Soft overlay adds:
+
+- **`<GlassCardBezel />`** — Soft Double-Bezel inner-1px glass border. Outer shell + inner core for "expensive nested glass" feel.
+- **`bezel?: boolean` prop on `<GlassCard />`** — quick toggle for the inner-1px white border without the full nested wrapper.
+- **Soft cubic-bezier easings** in `utils/cubic-bezier.ts`: `softInOut` `(0.32, 0.72, 0, 1)`, `softElastic` `(0.16, 1, 0.3, 1)`, `softSnappy` `(0.22, 1, 0.36, 1)` — drop-in replacements for Remotion's `interpolate({easing})`.
+- **`reduceMotion` prop** on every motion component (CausticBlobs, EyebrowPill, StaggeredWords, Counter, SonarRings, ParticleBurst, LightBeam, FloatingGlyphs, IridescentText, IridescentRing). Buyers passing `inputProps: { reduceMotion: true }` get a low-motion variant.
+- **`ALLOWED_ACCENTS`** export — lint flags any color outside `[iriCyan, iriViolet, iriRose, iriGold, violetPill, tealPill, ink]` as a hue bleed.
+- **WCAG AA+ contrast** documented inline in `palette.ts` (ink: 16.8:1, inkSoft: 12.4:1, etc.).
+
+## Reference reels (v1.1.1+)
+
+3 reference reels ship for this family at `~/.reelstack/reference/glass/<preset>.tsx`:
+
+- **graphify** — Multi-modal product reveal, the family's motion-vocabulary reference.
+- **paperclip** — Open-source reveal with PaperclipGlyph stroke draw-in. Tight 55s pacing.
+- **claudewatch** — Longest reel in the catalog (105s). Dual-narration, FilmStrip + IridescentText centerpiece.
+
+These are the actual Devini Labs reels (asset-stripped). Read them when iterating on your scaffolded reel. Pattern adaptation is encouraged; verbatim re-publication is not.