luckiest-co 1.0.19 → 1.0.21

package/skills/luckiest-video-studio/templates/diffusion/line-draw.tsx

@@ -0,0 +1,132 @@
+/* line-draw logo recipe, Diffusion Studio edition (luckiest-video-studio).
+ * Every path of the mark traces in its own color on a canvas surface, then fills and holds.
+ * Paths come from the logo SVG (see scripts/assemble-diffusion.mjs); `clip` paths are clipped to the
+ * artwork's clipPath rect. Time is local to the component's `start`, so it can sit in a sequence. */
+import { createEffect } from "solid-js";
+import { useTicker, type SceneNode } from "@diffusionstudio/jsx";
+
+export type LogoPath = { d: string; fill: string; clip: boolean };
+export type LogoArt = { paths: LogoPath[]; clip: [number, number, number, number] | null };
+
+type Props = {
+  id: string;
+  art: LogoArt;
+  start: number;
+  duration: number;
+  width: number;
+  height: number;
+  caption: string;
+  ink: string;
+  font: string;
+  drawSeconds: number;
+  logoSize: number;
+};
+
+const clamp = (v: number) => Math.max(0, Math.min(1, v));
+const easeOut = (t: number) => 1 - Math.pow(1 - t, 3);
+
+// Path lengths and the artwork's bounding box, measured once from a detached SVG.
+function measure(paths: LogoPath[]) {
+  const ns = "http://www.w3.org/2000/svg";
+  const svg = document.createElementNS(ns, "svg");
+  svg.setAttribute("style", "position:absolute;left:-9999px;top:0");
+  document.body.appendChild(svg);
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  const lengths = paths.map((p) => {
+    const el = document.createElementNS(ns, "path");
+    el.setAttribute("d", p.d);
+    svg.appendChild(el);
+    const b = el.getBBox();
+    x0 = Math.min(x0, b.x); y0 = Math.min(y0, b.y);
+    x1 = Math.max(x1, b.x + b.width); y1 = Math.max(y1, b.y + b.height);
+    return el.getTotalLength();
+  });
+  svg.remove();
+  return { lengths, box: { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } };
+}
+
+export function LineDrawLogo(props: Props) {
+  const { time } = useTicker();
+  const { lengths, box } = measure(props.art.paths);
+  const shapes = props.art.paths.map((p) => new Path2D(p.d));
+  const local = () => time() - props.start;
+  let surface: SceneNode | undefined;
+
+  createEffect(() => {
+    const canvas = surface?.element;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d")!;
+    const t = local();
+    const size = props.logoSize;
+    const s = (size * 0.9) / Math.max(box.w, box.h);
+    const k = s * (0.94 + 0.06 * easeOut(clamp(t / 3.2)));
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.translate(size / 2, size / 2);
+    ctx.scale(k, k);
+    ctx.translate(-(box.x + box.w / 2), -(box.y + box.h / 2));
+    shapes.forEach((shape, i) => {
+      const p = props.art.paths[i];
+      ctx.save();
+      if (p.clip && props.art.clip) {
+        const [cx, cy, cw, ch] = props.art.clip;
+        ctx.beginPath();
+        ctx.rect(cx, cy, cw, ch);
+        ctx.clip();
+      }
+      const draw = easeOut(clamp((t - i * 0.12) / props.drawSeconds));
+      const fill = easeOut(clamp((t - props.drawSeconds - i * 0.08) / 0.7));
+      const line = 2.4 * (1 - clamp((t - props.drawSeconds - 0.3 - i * 0.08) / 0.5));
+      ctx.globalAlpha = fill;
+      ctx.fillStyle = p.fill;
+      ctx.fill(shape);
+      if (line > 0 && draw > 0) {
+        ctx.globalAlpha = 1;
+        ctx.setLineDash([lengths[i], lengths[i]]);
+        ctx.lineDashOffset = lengths[i] * (1 - draw);
+        ctx.lineWidth = line / k;
+        ctx.lineJoin = "round";
+        ctx.lineCap = "round";
+        ctx.strokeStyle = p.fill;
+        ctx.stroke(shape);
+      }
+      ctx.restore();
+    });
+  });
+
+  const captionIn = () => easeOut(clamp((local() - props.drawSeconds - 1) / 0.6));
+  const end = () => props.start + props.duration;
+  return (
+    <>
+      <surface
+        id={`${props.id}-mark`}
+        x={(props.width - props.logoSize) / 2}
+        y={(props.height - props.logoSize) / 2 - 40}
+        width={props.logoSize}
+        height={props.logoSize}
+        start={props.start}
+        end={end()}
+        ref={surface}
+      />
+      <text
+        id={`${props.id}-caption`}
+        x={0}
+        y={(props.height + props.logoSize) / 2 + 10}
+        width={props.width}
+        height={40}
+        textAlign="center"
+        textBaseline="middle"
+        color={props.ink}
+        fontFamily={props.font}
+        fontSize={28}
+        fontWeight={500}
+        letterSpacing={9}
+        opacity={captionIn()}
+        start={props.start}
+        end={end()}
+      >
+        {props.caption}
+      </text>
+    </>
+  );
+}

package/skills/luckiest-video-studio/templates/logo-line-draw.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en" data-resolution="landscape">
+<head>
+<!-- line-draw logo recipe (luckiest-video-studio). Traces every path of the mark in its own color, fills, holds.
+     Fill {{paper}} and {{ink}} from brand.json, {{caption}} from the scene, paste the SVG, keep duration in sync with storyboard.json. --><meta charset="UTF-8" />
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:1920px;height:1080px;overflow:hidden;background:{{paper}}}
+#root{width:100%;height:100%;display:grid;place-items:center}
+.stage{width:520px;height:560px;display:grid;place-items:center}
+.mark{width:100%;height:100%;overflow:visible}
+.cap{position:absolute;bottom:110px;width:100%;text-align:center;font:500 28px/1 Inter,system-ui,sans-serif;letter-spacing:.32em;color:{{ink}};opacity:0}
+</style></head>
+<body>
+<div id="root" data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
+  <div class="stage clip" data-start="0" data-duration="6" data-track-index="0">
+<!--LOGO_SVG: paste the logo <svg> here and add class="mark" to it--></div>
+  <div class="cap clip" data-start="0" data-duration="6" data-track-index="1">{{caption}}</div>
+</div>
+<script>
+const mark=document.querySelector(".mark");const bb=mark.getBBox();const pad=Math.max(bb.width,bb.height)*0.04;mark.setAttribute("viewBox",[bb.x-pad,bb.y-pad,bb.width+2*pad,bb.height+2*pad].join(" "));
+const paths=[...document.querySelectorAll(".mark path")];
+const tl=gsap.timeline({paused:true});
+paths.forEach((p,i)=>{
+  const fill=getComputedStyle(p).fill; const len=p.getTotalLength();
+  p.style.stroke=fill; p.style.strokeWidth="2.4"; p.style.fillOpacity=0;
+  p.style.strokeDasharray=len+" "+len; p.style.strokeDashoffset=len;
+  tl.to(p,{strokeDashoffset:0,duration:1.9,ease:"power1.out"},i*0.12);
+  tl.to(p,{fillOpacity:1,duration:0.7,ease:"power2.out"},1.9+i*0.08);
+  tl.to(p,{strokeWidth:0,duration:0.5,ease:"power1.out"},2.3+i*0.08);
+});
+tl.fromTo(".stage",{scale:0.94},{scale:1,duration:3.2,ease:"power3.out"},0);
+tl.to(".cap",{opacity:1,duration:0.6,ease:"power2.out"},2.9);
+tl.to({},{duration:6},0);
+window.__timelines=window.__timelines||{}; window.__timelines["main"]=tl; tl.seek(0);
+</script>
+</body></html>

package/skills/luckiest-video-studio-ae/ATTRIBUTION.md

@@ -0,0 +1,9 @@
+# Attribution
+
+`luckiest-video-studio-ae` is a Luckiest sub-skill of `luckiest-video-studio`. It
+drives `luckiest-ae-mcp`, the Luckiest edition of **after-effects-mcp** by Dakkshin
+(`Dakkshin/after-effects-mcp`, MIT). See `packages/luckiest-ae-mcp/ATTRIBUTION.md`
+for the changes made to that server, including the removal of `eval()` from the
+bridge and of automatic `sudo` from the installer.
+
+Recipe looks come from `luckiest-video-studio/references/logo-recipes.md`.

package/skills/luckiest-video-studio-ae/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — luckiest-video-studio-ae
+
+## 1.0.0 — 2026-09-28
+- New sub-skill: rebuilds luckiest-video-studio motion and logo scenes as After
+  Effects comps through luckiest-ae-mcp, one precomp per scene, timings from
+  storyboard.json.
+- Setup never elevates without asking; only allowlisted bridge tools are used.

package/skills/luckiest-video-studio-ae/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: luckiest-video-studio-ae
+description: >-
+  Rebuild the motion and logo scenes of a luckiest-video-studio run as editable
+  Adobe After Effects compositions, one precomp per scene, through the
+  luckiest-ae-mcp server: import the logo, convert it to shapes, draw it on with
+  Trim Paths, mask, keyframe, parent, precompose, and render to MOV. Timing comes
+  from the run's storyboard.json, so the After Effects version matches the
+  HyperFrames render. Usually driven by luckiest-video-studio with --ae. Trigger on
+  "open this in After Effects", "make it editable in AE", "rebuild the logo
+  animation in After Effects", "export an AE project of the video", or "AE handoff".
+argument-hint: "<run-dir with storyboard.json> [--scene <id>]"
+user-invocable: false
+license: MIT. See ATTRIBUTION.md
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+metadata:
+  version: "1.0.0"
+  listing_id: luckiest-video-studio-ae
+  author: luckiest
+---
+
+# After Effects handoff
+
+Turn a rendered run into After Effects compositions a designer can keep editing.
+The HyperFrames render stays the timing reference; this track rebuilds each scene
+with real layers, keyframes, and precomps.
+
+## Staying current
+
+On activation, call the Luckiest MCP `check_updates` tool with
+`{ listingId: "luckiest-video-studio-ae", installedSemver: "1.0.0" }`. If
+`upToDate: false`, surface the `notice` once and continue. Never block on it.
+
+When done, call `report_usage` once with
+`{ listing_id: "luckiest-video-studio-ae", skill_version: "1.0.0", matched: true, success: <true|false> }`.
+Metadata only. Skip silently if unavailable.
+
+## Standing rules
+
+1. **Ask before any install or elevation.** Name the step and why.
+2. **Never run arbitrary ExtendScript.** Use only the tools listed below. The bridge
+   accepts strict JSON commands and an allowlist of scripts; do not work around it.
+3. **Work on a copy.** Save the After Effects project to the run folder
+   (`<run-dir>/ae/<title>.aep`), never over a project the user already had open.
+4. **Client marks stay untouched.** Import logos as they are; never redraw or
+   recolor a client's mark.
+
+## Step 0: Setup (once per machine)
+
+Check in this order and stop at the first gap, telling the user what to do:
+
+1. **After Effects** 2021 or later is installed.
+2. **The MCP server is built.** In the `luckiest-ae-mcp` folder:
+   `npm install --ignore-scripts && npm run build` (ask first; it downloads its
+   dependencies).
+3. **The MCP server is connected** to the agent, for Claude Code:
+   `claude mcp add luckiest-ae -- node <luckiest-ae-mcp>/build/index.js`
+4. **The bridge panel is installed:** `node install-bridge.js`. If it reports that
+   the copy needs administrator rights, show the user the printed command. Only
+   rerun with `--yes` after the user agrees to the password prompt.
+5. **After Effects allows it:** Settings, Scripting & Expressions, enable "Allow
+   Scripts to Write Files and Access Network", restart After Effects.
+6. **The panel is open:** Window, `mcp-bridge-auto.jsx`, with Auto-run on.
+
+Confirm with the `run-bridge-test` tool, then `get-results`.
+
+## Tools
+
+Dedicated tools (each waits for the result):
+
+| Tool | Use |
+|---|---|
+| `importFile` | Import SVG, AI, PDF, PNG, footage, or audio; `compName` adds it as a layer; `convertToShapes: true` runs Create Shapes from Vector Layer |
+| `trimPaths` | Add Trim Paths and animate End 0 to 100 for a draw-on |
+| `precompose` | Move layers into a new comp, one per scene or logo |
+| `setParent` | Parent a layer, or clear it with `parentIndex: null` |
+| `render` | Render Queue to `.mov`, `.mp4`, `.avi`, `.png`, `.tif`; `queueOnly` to leave it queued |
+| `create-composition` | New comp with size, fps, duration, background |
+| `setLayerKeyframe`, `setLayerExpression` | Animate any property |
+| `apply-effect`, `apply-effect-template` | Glow, blur, shadow, and templates |
+
+Through `run-script` (queue, then `get-results`): `createTextLayer`,
+`createShapeLayer`, `createSolidLayer`, `setLayerProperties`,
+`batchSetLayerProperties`, `setLayerMask`, `duplicateLayer`, `deleteLayer`,
+`createCamera`, `setCompositionProperties`, `listCompositions`, `getProjectInfo`,
+`getLayerInfo`.
+
+## Step 1: Read the run
+
+Read `<run-dir>/storyboard.json`, `brand.json`, and `TIMING.md`. Rebuild `motion`
+and `logo` scenes only; `demo` scenes stay as footage. With `--scene <id>`, rebuild
+only that scene.
+
+## Step 2: Master comp, then one precomp per scene
+
+There is no tool that places an existing comp inside another, so build every scene
+inside one master comp at its start time, then precompose each scene's layers.
+
+1. `create-composition` named `<title> master` at the storyboard's width, height,
+   and fps, with the total duration from `TIMING.md` and background `brand.paper`.
+2. For each `motion` and `logo` scene, add its layers to the master with
+   `startTime` set to the scene's in time from `TIMING.md` and the scene's
+   `duration`. Build by recipe (the look is in
+   `luckiest-video-studio/references/logo-recipes.md`):
+
+| Recipe | After Effects build |
+|---|---|
+| `line-draw` | `importFile` the SVG with `compName` = master, `startTime`, `convertToShapes: true`; `trimPaths` with the scene's draw time and `trimMultipleShapes: "individually"` for a stagger; keyframe fill Opacity after the draw |
+| `mask-wipe` | Import; `setLayerMask` with a feathered rectangle; keyframe the mask expansion across the reveal |
+| `piece-assembly` | Import with `asComposition: true` so each group is a layer; keyframe Position and Opacity per layer; `setParent` to a null for the final settle |
+| `sting` | Text or logo layer; Scale keyframes 130 to 100 with ease; one shape ring with Scale and Opacity keyframes |
+| `wall` | Import every logo; `setLayerProperties` into a grid; staggered Scale and Opacity keyframes |
+| `particle-build`, `ink-bleed`, `facet` | `importFile` the scene's rendered clip from `clips/` and note the effect stays rendered; offer a simpler native reveal |
+| Motion scenes | Rebuild text with `createTextLayer` and shapes with `createShapeLayer`; copy timings from the composition's GSAP timeline |
+
+   Keyframe times are absolute in the master: scene in time plus the time inside
+   the scene. `power2.out` maps to an ease-out with about 75% influence.
+3. `demo` scenes: `importFile` the rendered clip from `clips/` at its start time.
+4. `precompose` each scene's layers into a comp named `NN-<id>` so every scene can
+   be opened and edited on its own. With `--scene <id>`, rebuild only that scene's
+   layers and precompose them.
+
+## Step 3: Render and save
+
+1. Ask whether to render now. If yes, `render` the master to
+   `<run-dir>/ae/<title>.mov` with `outputModuleTemplate` "High Quality";
+   otherwise pass `queueOnly: true`.
+2. Tell the user to save the project (File, Save As) into `<run-dir>/ae/`.
+
+## Done when
+
+Every scene has its own precomp with timing that matches `TIMING.md`, the master comp
+plays the run in order, and the user knows where the project and any render are.

package/skills/luckiest-video-studio-cards/ATTRIBUTION.md

@@ -0,0 +1,22 @@
+# Attribution
+
+`luckiest-video-studio-cards` is a Luckiest sub-skill of `luckiest-video-studio`.
+Its two card packs, blueprint, scene templates, and the `build-registry.mjs` and
+`new-pack.mjs` scripts come from the style library and style templates of the
+**HyperFrames student kit** by Nate Herk and contributors. The kit is MIT; its
+style library and templates carry the Student Kit Use Permission. Both texts are
+kept in `luckiest-video-studio/LICENSE-student-kit` and
+`LICENSE-student-kit-pipeline`.
+
+## Changes in this edition
+
+- Renamed the two styles to `paper-collage` and `aurora-glass`. The originals
+  were named after a publication and a creator; the kit notes neither is official
+  or endorsed.
+- Removed AI Automation Society copy and its palette, which the kit does not
+  license for reuse, and replaced placeholder brand names with "Acme".
+- Removed remote Google Fonts imports. Cards take fonts and colors from the run's
+  `brand.json` through `apply-brand.mjs`.
+- Dropped the per-style preview pages and the one-off manifest generator, and the
+  templates' upstream registry URL.
+- Added a `qa` status per card. See `luckiest-video-studio/SECURITY.md` S39 to S47.

package/skills/luckiest-video-studio-cards/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog: luckiest-video-studio-cards
+
+## 1.0.0 (2026-09-30)
+- New sub-skill: 406 cards in the paper-collage and aurora-glass packs, a
+  blueprint, two scene templates, and registry and new-pack scripts.
+- Cards take brand.json colors and fonts; no remote font loading.
+- Fixed the 57 cards that failed HyperFrames lint in the kit; all 406 now lint
+  clean.

package/skills/luckiest-video-studio-cards/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: luckiest-video-studio-cards
+description: >-
+  Pick, brand, and place ready-made motion-graphic cards in a luckiest-video-studio
+  run: 406 cards in two packs (paper-collage, aurora-glass) covering full-frame
+  takeovers (section, stat, overview) and overlays that keep the speaker visible
+  (lower third, label), plus two scene templates. Cards take the run's brand.json
+  colors and fonts and render as storyboard motion scenes. Usually driven by
+  luckiest-video-studio or luckiest-video-studio-talk. Trigger on "add a stat card",
+  "use a card for this", "lower third with my name", "section title card",
+  "pick a card style", or "make a new card pack".
+argument-hint: "<run-dir> [--pack <id>] [--purpose <purpose>]"
+user-invocable: false
+license: MIT. See ATTRIBUTION.md
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+metadata:
+  version: "1.0.0"
+  listing_id: luckiest-video-studio-cards
+  author: luckiest
+---
+
+# Card packs
+
+A card is one finished motion-graphic moment: a big number, a section title, a
+name strap. Picking a proven card and filling its slots is faster and more
+consistent than drawing each beat from scratch.
+
+## Staying current
+
+On activation, call the Luckiest MCP `check_updates` tool with
+`{ listingId: "luckiest-video-studio-cards", installedSemver: "1.0.0" }`. If
+`upToDate: false`, surface the `notice` once and continue. Never block on it.
+
+When done, call `report_usage` once with
+`{ listing_id: "luckiest-video-studio-cards", skill_version: "1.0.0", matched: true, success: <true|false> }`.
+Metadata only. Skip silently if unavailable.
+
+## Standing rules
+
+1. **Sample copy is not content.** Card names, sources, and numbers are
+   placeholders. Replace every slot with the user's verified words, or leave the
+   card out.
+2. **Brand first.** Cards take the run's `brand.json`; never ship a pack's default
+   palette on a branded video without asking.
+3. **One pack per video.** Mixing packs reads as two videos.
+4. **Local assets only**, apart from the pinned GSAP script tag every card carries.
+
+`<skill-dir>` is the folder holding this file. Cards are in `<skill-dir>/packs/`,
+the index in `<skill-dir>/packs/registry.json`.
+
+## The packs
+
+| Pack | Look | Cards |
+|---|---|---|
+| `paper-collage` | Warm paper, engraving cutouts, serif statements, hand-drawn arrows, choppy stop-motion timing | 106 |
+| `aurora-glass` | Near-black canvas, soft glow from below, frosted glass panels, smooth glide and bloom | 300 |
+
+| Tier | Background | Purposes | Use |
+|---|---|---|---|
+| `tier1` | opaque, replaces the frame | `section`, `stat`, `overview` | its own storyboard scene |
+| `tier2` | transparent except the card | `lower-third`, `label` | on top of the speaker, inside a talk scene |
+
+Read a pack's `DESIGN.md` before choosing. The full card rules are in
+[references/card-contract.md](references/card-contract.md).
+
+## Step 1: Choose
+
+Filter `packs/registry.json` by pack, tier, and purpose, then open two or three
+candidates and pick the one whose layout fits the copy (slot count and length,
+one number or several). Every card lists its `slots` and a `duration` range.
+Check its `qa` field: prefer `render-ok`, avoid `broken`.
+
+## Step 2: Brand the pack for this run
+
+```bash
+node <skill-dir>/scripts/apply-brand.mjs <run-dir> <pack-id>
+```
+
+It copies the pack to `<run-dir>/composition/cards/<pack-id>/` and rewrites its
+`tokens.css` from `<run-dir>/brand.json` (paper, ink, accent, fonts). Fonts are
+loaded from `composition/assets/fonts/` when the files are there.
+
+## Step 3: Place
+
+- **tier1:** copy the branded card to `composition/compositions/<scene-id>.html`
+  (its `tokens.css` link, `cards/<pack-id>/tokens.css`, is already relative to
+  `composition/`, so it resolves in Studio and in the render), fill every
+  `data-slot`, and set `data-duration` to the scene length (inside the card's
+  range). Add a `motion` scene to `storyboard.json` with `composition` pointing at
+  it and the tokens file in `assets`.
+- **tier2:** mount the card inside a talk overlay scene with
+  `data-composition-src`, wrapped in a `<template>` as the contract describes, on
+  a track above the clip. The talk sub-skill owns the timing.
+
+Scene templates in `<skill-dir>/templates/` (`graph-paper` for a full-frame
+backdrop, `glass-popout` for a side panel over a reframed camera) are starting
+points for a whole scene rather than one card.
+
+## Step 4: Check
+
+Render the scene with the coordinator's `render-scenes.mjs` and look at the hero
+frame at full size and phone size: every slot filled with real copy, no text
+clipped at the longest slot value, the brand colors in place of the pack
+defaults.
+
+## Make a new pack
+
+```bash
+node <skill-dir>/scripts/new-pack.mjs 03 <slug> "Human Name"
+node <skill-dir>/scripts/build-registry.mjs
+```
+
+Fill `DESIGN.md`, `tokens.css`, and `style.json`, build cards under
+`packs/NN-slug/cards/`, and rebuild the registry. Follow the card contract.

package/skills/luckiest-video-studio-cards/packs/01-paper-collage/DESIGN.md

@@ -0,0 +1,50 @@
+# Paper Collage - Design Spec
+
+> Source of truth: this file and tokens.css.
+
+## Style Prompt
+
+Animated-documentary collage in a paper-collage house style. The frame is a sheet of warm, slightly aged paper - newsprint fiber, faint blueprint grid, a whisper of grain over everything. Onto it we paste **cutouts**: old engravings and halftone photographs, masked and outlined with a thick colored sticker-stroke (blue or orange), as if scissored from an archive and glued down. High-contrast serif type does the talking, anchored by the one signature move - a **bright blue shape** (circle or marker box) that the eye locks onto. Hand-drawn arrows and scribbles connect ideas like an editor's margin notes.
+
+The motion is the soul of it: **choppy, low-shutter, stop-motion**. Nothing eases smoothly. Elements snap and stutter into place on stepped timing, as if shot on twos. The camera lives in a shallow **3D space** - it pushes and racks focus to point the viewer exactly where to look, blurring background layers so the subject pops. It should feel handcrafted and editorial, never slick or corporate. The relationship to the speaker: tier-1 cards are full-paper takeovers (the speaker is gone, we're inside the story); tier-2 cards paste a cutout or a marker label beside the speaker without covering their face.
+
+## Colors
+
+- Background (paper): `#efe9dc` - warm newsprint. Variant kraft: `#e6dcc4`
+- Foreground / ink: `#17130e` - warm near-black print ink (text + engravings)
+- Accent (accent blue): `#4F8CFF` - the signature; circles + marker highlight boxes
+- Editorial red: `#e23b2e` - circles, scribbles, alarm
+- Cutout orange: `#f26a1b` - sticker outline / secondary accent
+
+5 symbolic colors, no more. The blue is sacred - one dominant blue shape per beat, never two competing. These match `tokens.css` exactly.
+
+## Typography
+
+- Display / headline: **Fraunces** - `300` for light editorial lines, `900` (+ italic) for the wordmark voice and emphasis. Extreme weight contrast. Optical high-contrast Didone feel at display sizes. Tracking `-0.03em`.
+- Metadata / kicker / label: **Archivo** - `700` uppercase, wide tracking (`0.16em`). The recedes-into-the-page voice: chapter tags, technical specs, dates, credits.
+- Handwriting accent: **Caveat** - arrow labels and margin scribbles ONLY. Never body copy.
+
+Pairing logic: Fraunces (statement) + Archivo (metadata) cross the serif/sans boundary. Caveat is a third, deliberately small voice - the editor's pen, used sparingly. Playfair Display is deliberately avoided (the AI-default Didone; banned by the type guide).
+
+## Motion
+
+- Entrance feel: **snap + stutter**. Paper-cut elements pop with `back.out(2.2)`; choppy moves run on `steps(6)` to fake a low shutter / shot-on-twos cadence.
+- Exit feel: quick - a `steps()` slide-off or a whip, never a slow fade.
+- Ambient: persistent **paper grain** (subtly flickering on stepped timing), a slow **camera push** on tier-1, and **rack focus** (background layers blurred so the subject reads).
+- Highlight reveal: the blue marker box / circle wipes on via `scaleX`/`scale` from 0 behind the text - the eye-magnet beat.
+- Timing: tier-1 ≈ 5–8s with a breathing hold; tier-2 ≈ 6–14s. Stagger sub-elements 0.08–0.14s. Sequence is hierarchy - the first thing in is the most important.
+
+## Card kinds in this style
+
+- **tier1 takeovers:** `section` (chapter/title takeover), `stat` (one big number), `overview` (a 3-up timeline of photo cards with dates).
+- **tier2 cards:** `lower-third` (name + role marker beside the speaker), `label` (annotated highlight callout with a hand-drawn arrow pointing at the subject).
+- **innovations:** the cutout placeholder system - image slots render as deliberate paper-cut frames (halftone fill + colored sticker outline) so a card reads as collage even before the agent drops in a real archive image.
+
+## What NOT to do
+
+- No pure white (`#fff`) or pure black (`#000`) backgrounds - always warm paper + warm ink. This pack never looks digital-clean.
+- No smooth, slow, symmetric eases. If it glides, it's wrong. Snap, stutter, overshoot.
+- No two blue focal shapes fighting in one frame. One eye-magnet per beat.
+- No centered, perfectly level layouts. Elements sit slightly skewed/off-grid, pasted by hand.
+- No gradients-as-decoration, no glows, no drop-shadow blur for "depth" - depth comes from scale, overlap, and rack focus, not soft shadows.
+- No sans-serif headlines. The statement voice is always the serif (Fraunces).