takomi 2.1.40 → 2.1.42

package/.agents/plugins/marketplace.json

@@ -4,29 +4,29 @@
     "displayName": "J StaR Films Studios"
   },
   "plugins": [
-    {
-      "name": "takomi-codex",
-      "source": {
-        "source": "local",
-        "path": "./plugins/takomi-codex"
+    {
+      "name": "takomi-codex",
+      "source": {
+        "source": "local",
+        "path": "./plugins/takomi-codex"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    },
-    {
-      "name": "takomi-flow",
-      "source": {
-        "source": "local",
-        "path": "./plugins/takomi-flow"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "takomi-flow",
+      "source": {
+        "source": "local",
+        "path": "./plugins/takomi-flow"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/README.md

@@ -24,7 +24,7 @@ This isn't prompt engineering. This is **orchestrated development** — a battle
 
 ## Features
 
-- **🧠 72+ Skills** — Specialized capabilities from security audits to AI video generation, installed on demand
+- **🧠 95+ Skills** — Specialized capabilities from security audits to AI video generation, installed on demand
 - **🔄 Universal IDE Sync** — Install once, sync to Antigravity, Claude Code, Codex, Cursor, Kilo Code, Pi, and Windsurf
 - **🏗️ Full Project Lifecycle** — From genesis (planning) through design, build, and finalize — with verification gates at every step
 - **🎭 Specialized Agent Modes** — Orchestrator, Architect, Coder, Debugger, Reviewer — each with purpose-built workflows
@@ -147,7 +147,7 @@ See [TakomiFlow Onboarding](docs/takomi-flow-onboarding.md) and [TakomiFlow Publ
 
 ## Skill Ecosystem
 
-Think of skills as specialized team members you can summon on demand. Takomi ships **72+ skills** organized by category.
+Think of skills as specialized team members you can summon on demand. Takomi ships **95+ skills** organized by category.
 
 ### Core Skills (Default Install)
 
@@ -176,7 +176,7 @@ npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite
 
 **Convex** — `convex`, `convex-agents`, `convex-best-practices`, `convex-component-authoring`, `convex-cron-jobs`, `convex-file-storage`, `convex-functions`, `convex-http-actions`, `convex-migrations`, `convex-realtime`, `convex-schema-validator`, `convex-security-audit`, `convex-security-check`
 
-**Frontend / UI** — `frontend-design`, `web-design-guidelines`, `building-native-ui`, `ui-ux-pro-max`, `component-analysis`, `21st-dev-components`, `stitch`, `webapp-testing`
+**Frontend / UI** — `frontend-design`, `web-design-guidelines`, `building-native-ui`, `ui-ux-pro-max`, `component-analysis`, `21st-dev-components`, `stitch`, `webapp-testing`, `figma`
 
 **Docs / Office / Extraction** — `pdf`, `docx`, `pptx`, `xlsx`, `high-fidelity-extraction`, `crafting-effective-readmes`, `exam-creator-skill`
 
@@ -184,7 +184,9 @@ npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite
 
 **AI Media / Content Creation** — `ai-avatar-video`, `ai-marketing-videos`, `ai-podcast-creation`, `ai-product-photography`, `ai-social-media-content`, `ai-voice-cloning`, `takomi-flow`
 
-**Creative / Video / Art** — `algorithmic-art`, `blender-mcp-scene-director`, `takomi-flow`, `remotion`, `youtube-pipeline`, `ai-avatar-video`, `ai-marketing-videos`, `photo-book-builder`
+**Creative / Video / Art** — `algorithmic-art`, `blender-mcp-scene-director`, `takomi-flow`, `remotion`, `remotion-real-ui-video`, `youtube-pipeline`, `ai-avatar-video`, `ai-marketing-videos`, `photo-book-builder`, `hyperframes`, `general-video`, `motion-graphics`
+
+**HyperFrames** — `hyperframes`, `hyperframes-core`, `hyperframes-keyframes`, `hyperframes-animation`, `hyperframes-creative`, `hyperframes-media`, `hyperframes-registry`, `hyperframes-cli`, `remotion-to-hyperframes`, `media-use`, `embedded-captions`, `faceless-explainer`, `general-video`, `motion-graphics`, `music-to-video`, `pr-to-video`, `product-launch-video`, `slideshow`, `talking-head-recut`, `website-to-video`
 
 **Skill Building / Prompting / Orchestration** — `skill-creator`, `prompt-engineering`, `subagent-driven-development`, `spawn-task`
 
@@ -322,6 +324,7 @@ Takomi-original skills, workflows, and runtime extensions — including `21st-de
 | **[Vercel AI SDK](https://github.com/vercel/ai)** | AI SDK reference, Web Design Guidelines |
 | **[UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)** | Premium design intelligence |
 | **[Remotion](https://github.com/remotion-dev/skills)** | Programmatic video creation |
+| **[HyperFrames](https://github.com/heygen-com/hyperframes)** | HTML-native video creation and animation framework: HyperFrames core, keyframes, creative, media OS, animation engine, registry, CLI, and specialized creator workflows (product launch, website showcase, faceless explainer, music video, PR walkthrough, overlays, captions) |
 | **[Subagent Development](https://github.com/obra/superpowers)** | Advanced implementation planning |
 | **[Context7](https://github.com/upstash/context7)** | Library documentation fetcher |
 | **[Audit Website](https://github.com/squirrelscan/skills)** | Professional website auditor |

package/assets/.agent/skills/embedded-captions/CATALOG.md

@@ -0,0 +1,93 @@
+# THE CATALOG — one front-end, three engines behind
+
+This is the skill's single selection surface. **The user picks an IDENTITY from
+this table; everything else (engine, compiler, authoring file) is derived by
+lookup — never ask the user (or yourself) "Standard or Cinematic or Theme?"**
+Those are backend names; a product has one UX even when it has several engines.
+
+Routing procedure (replaces any mode decision):
+
+1. Probe the clip (decision gate + pre-flight probes as in SKILL.md).
+2. Shortlist 2–3 identities from this table by **content register + the user's
+   own words + scene constraints**.
+3. Recommend ONE with a one-line why; the user picks.
+4. Author the identity's file (last column), then render with its engine's
+   pipeline. Done — no category question ever surfaced.
+
+## Identities
+
+| Identity      | Reading surface                                          | Voice (one line)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Recommend for                                                                                                                                                                                                  | Scene needs                                                                                                            | Author → engine                 |
+| ------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `cream`       | scene-embedded column flow                               | warm poetic light, emergence + glow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | introspective, narrative, emotional monologues                                                                                                                                                                 | dark/mid-tone warm scenes (luma < 150)                                                                                 | cinematic.json → make-cinematic |
+| `ink`         | scene-embedded column flow                               | letterpress pressed into bright surfaces                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | the bright scenes everything else washes out on                                                                                                                                                                | BRIGHT scenes (luma > 150)                                                                                             | cinematic.json → make-cinematic |
+| `editorial`   | scene-embedded column flow                               | lowercase italic serif, pen-stroke glides                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | fashion / beauty / lyrical / premium brand films                                                                                                                                                               | mid/dark scenes                                                                                                        | cinematic.json → make-cinematic |
+| `keynote`     | scene-embedded column flow                               | confident centered slides-in-the-scene                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | launches, founder updates, tech explainers (mood over verbatim reading)                                                                                                                                        | any mid/dark                                                                                                           | cinematic.json → make-cinematic |
+| `documentary` | scene-embedded column flow                               | burn-in stillness, bone on charcoal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | interviews, journalism, testimony — gravitas IS the style                                                                                                                                                      | any                                                                                                                    | cinematic.json → make-cinematic |
+| `loud`        | scene-embedded, body in front                            | percussion type that competes with the face                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | hype, social reels, sport, music, motivational                                                                                                                                                                 | any (counter-accent handles warm)                                                                                      | cinematic.json → make-cinematic |
+| `neon`        | scene-embedded column flow                               | captions as neon signage in the dark                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | cyberpunk / nightlife / tech-noir / music                                                                                                                                                                      | dark scenes                                                                                                            | cinematic.json → make-cinematic |
+| `glitch`      | scene-embedded column flow                               | corrupted-feed RGB-split type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | hacker / AI / dystopia content                                                                                                                                                                                 | mid/dark                                                                                                               | cinematic.json → make-cinematic |
+| `chrome`      | scene-embedded column flow                               | liquid-metal hero with sheen sweeps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | fashion-tech, Y2K, product-flex                                                                                                                                                                                | mid/dark                                                                                                               | cinematic.json → make-cinematic |
+| `velocity`    | scene-embedded column flow                               | every word arrives along its motion vector                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | sport, automotive, fitness, kinetic content                                                                                                                                                                    | any mid/dark                                                                                                           | cinematic.json → make-cinematic |
+| `anchor`      | verbatim lower-third rail + 1 settled climax             | the quiet professional — fade-up rail that simply reads; the apex settles behind the subject with a drawn accent underline. Discipline IS the style.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | explainers, tutorials, corporate, news-adjacent — **where every word must be read**; the conservative default                                                                                                  | any (opaque rail; settle carries a soft veil)                                                                          | theme.json → make-theme         |
+| `ordnance`    | stamped verbatim rail + detonation apex                  | military marking system; everything has mass; the room reacts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | punchy announcements, drops, "炸一点 / 像 AE 做的" asks                                                                                                                                                        | any (charge-dim makes its own contrast)                                                                                | theme.json → make-theme         |
+| `terminal`    | typed console panel + glyph-decode apex                  | the transcript is a signal log; apex decodes from noise                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | tech / data / AI / investigative, "终端/控制台/解码" asks                                                                                                                                                      | cool/dusk preferred                                                                                                    | theme.json → make-theme         |
+| `neonsign`    | warm tube rail + hand-written neon apex                  | a sign district at dusk; the apex is WRITTEN stroke by stroke                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | lifestyle / music / mood, "霓虹/手写" asks                                                                                                                                                                     | dusk/dark backdrop; needs `python3` (stroke-path gen)                                                                  | theme.json → make-theme         |
+| `stardust`    | accumulating poem, condensing letters                    | words condense from dust and return to it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | poetic / memory / science-wonder monologues                                                                                                                                                                    | one clear column side (probe fails → fall back to `cream`)                                                             | theme.json → make-theme         |
+| `stomp`       | full-frame takeover cards                                | hard-cut typographic takeover with a void before the drop                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | hooks, manifestos, ad openers — the words ARE the show                                                                                                                                                         | any (plate runs dimmed)                                                                                                | theme.json → make-theme         |
+| `lastpage`    | manuscript rail + a blurred future-field                 | the future hangs unreadable in the room; one rack-focus reveals every faint line was the apex word                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | visionary thesis, prophecy-toned talks, trailers, literary content                                                                                                                                             | mid/dark (the field needs air)                                                                                         | theme.json → make-theme         |
+| `nightcity`   | corrupted-UI rail + cover-letterform apex                | body words boot through a corrupted-cyan frame into acid-yellow UI; the apex slams in BEHIND the subject set in the CP2077 cover replica typeface (cyan offset, baseline streak, circuit trace), tears in as displaced slices, lives as a glitching print                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | gaming / tech-edge / glitch culture / hype drops, "赛博朋克/游戏封面" asks                                                                                                                                     | any (the lockup carries its own contrast); CP2077-adjacent content only (fan-kit terms)                                | theme.json → make-theme         |
+| `scoreboard`  | split-flap chyron rail + departures-board apex           | stadium split-flap mechanics — body words flip-cycle wrong words on tiles before clacking onto the real one; ROW counter + odometer chip furniture; the apex is a giant departures board behind the subject that locks the word letter-by-letter under floodlights and a crowd-flash, status ticker types on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | sports, transit/travel, scores, countdowns, reveals, "翻牌/记分牌/机场大屏" asks                                                                                                                               | any (board + chyron bring their own dark metal contrast)                                                               | theme.json → make-theme         |
+| `transit`     | LED departure-strip rail + illumination-wipe apex        | amber dot-matrix station PA — body words light column-by-column (L→R LED wipe + arrival flicker) on a docked departure strip whose lines page by scroll-snap; platform tag, ticking clock, ⚠ DELAYED → ● ON TIME gag; the apex panel expands behind the subject inside a chasing LED-marquee border, the word illuminates column-by-column under a PA flash + ding pulses, then pages up and collapses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | travel/transit, announcements, schedules, countdowns, retro-terminal, "LED屏/车站到站/点阵屏" asks                                                                                                             | any (LED strip + panel bring their own dark contrast)                                                                  | theme.json → make-theme         |
+| `vhs`         | camcorder OSD rail + REC-FREEZE tracking-slam apex       | tape playback — permanent lens vignette + OSD furniture (▶ PLAY, ● REC, blinking green timestamp); body words carry a permanent red/cyan misregistration fringe, arrive by tracking glitch and REWIND off with flat-white echoes + scrub lines (the deck flips PLAY→REW in dead air); the apex is REC FREEZE: 1-frame white tear + head-switching noise bar, the word slams in behind the subject as three sheared tracking bands that SNAP into register, misregistration breathes through the hold under tape weave + auto-iris, then rewinds off                                                                                                                                                                                                                                                                                                                                                                                                                   | retro / nostalgia / found-footage / home-video, '90s tech, music & lifestyle edits, "录像带/VHS/复古/DV" asks                                                                                                  | any (backlight-comp scrim makes its own contrast on bright skies)                                                      | theme.json → make-theme         |
+| `arcade`      | arcade HUD rail + pixel-block boss-intro apex            | 8-bit cabinet attract mode — the frame plays through CRT scanlines + a corner vignette; body words coin-pop onto a bordered HUD bar (blinking 1UP, CREDIT 01) with a 1-frame white blip each, emphasis words run a cyan→magenta palette swap, lines dissolve checkerboard; the apex is a BOSS INTRO behind the subject: the room dims, WARNING blinks twice, ~64 seeded pixel blocks fall quantized into a matrix grid over the word rect, the word flashes ON in Press Start 2P with chromatic ghost layers + a 3-frame palette strobe while letterbox bars slam in and a HI-SCORE odometer rolls top-right; everything dissolves checkerboard and the blocks drop away                                                                                                                                                                                                                                                                                              | gaming, retro-tech, playful hype, launches, achievement/level-up beats, "像素/街机/8-bit/打游戏" asks                                                                                                          | any (boss dim + dark HUD bar bring their own contrast)                                                                 | theme.json → make-theme         |
+| `dossier`     | manila case-file strip + rubber-stamp apex               | cold-war case file — carbon Special Elite HAMMERS onto a manila transcript strip char by char (seeded baselines + ribbon ink, every strike kicks the paper; typed case header, CONFIDENTIAL watermark, red ink circles around the evidence; pages are X-row over-struck and carriage-fed away); the apex is a RUBBER STAMP behind the subject: the footage goes sepia-archival, the stamp crushes in at −8° with a double-strike ghost + thin-ink patches, then holds DEAD STILL — sold only by a breathing paper indent — until the page is filed away with a mechanical yank                                                                                                                                                                                                                                                                                                                                                                                        | investigations, exposés, true-crime, document-driven storytelling, declassified/archival framing, "档案/卷宗/解密/盖章" asks                                                                                   | any (the manila strip is self-lit; the stamp brings its own sepia charge)                                              | theme.json → make-theme         |
+| `laser`       | beam-ignited rail + 6-beam laser-cage apex               | concert laser rig in a blackout — every body word is IGNITED where a green and a magenta beam converge on it two frames early (flare pop, snap-on, single strobe on emphasis; a sweeper beam carries each line away); the apex is the drop: a 6-beam array sweeps to one hot point, the word ignites behind the subject in an additive glow stack with two controlled strobe pops, a criss-cross beam cage draws around it, the array fans out wide through the hold, then the beams sweep everything off L→R                                                                                                                                                                                                                                                                                                                                                                                                                                                         | music, nightlife, festivals, drops, hype reveals, keynote 'one more thing' beats, "激光/灯光秀/蹦迪字幕" asks                                                                                                  | any (the concert blackout makes its own contrast, bright skies included)                                               | theme.json → make-theme         |
+| `thunder`     | rain-washed rail + branched-bolt strike apex             | the storm is the editor — slate storm mood on the room, ambient slanted rain falling in front of the subject, and the sky "kisses" (1-frame brighten) on every body word; rail words arrive with a lit-bright lightning pop (emphasis = sheet-lightning double flash mirrored by a double sky-kiss); the apex is THE STRIKE: a hand-authored branched bolt flashes two frames before the word, the word slams in lit HARD with its shadow flipped toward the bolt, ozone under-glow breathes through the hold while the rain doubles, then everything washes downward with the rain                                                                                                                                                                                                                                                                                                                                                                                   | dramatic reveals, storm/weather content, epic hype beats, trailer-toned monologues, "雷电/闪电/暴风雨字幕" asks                                                                                                | any (charge-dim + radial word scrim make their own contrast, bright skies included)                                    | theme.json → make-theme         |
+| `hologram`    | volumetric projection plate + hologram-boot apex         | every caption is LIGHT cast from an emitter — body words boot onto a scanlined projection plate with a rising sweep, a 1-frame interference glitch and a permanent cyan/magenta fringe (emphasis words drop out for 2 frames and restore brighter; lines drift in rotationY and exit by projector cut); the apex is the full volumetric boot: a desk emitter dot pops, the cone snaps wide, a seed beam fires, and the word materializes behind the subject as a 7-layer hologram with climbing interference bands — a hand passes through it before the projector cuts it back to the dot                                                                                                                                                                                                                                                                                                                                                                            | tech / sci-fi / AI / space / imaging explainers, futuristic product reveals, "全息/投影/科幻字幕" asks                                                                                                         | any (the apex scrim + dim make their own contrast; wants a lower frame edge for the emitter dots)                      | theme.json → make-theme         |
+| `biolume`     | jellyfish glow-on rail + bioluminescent-bloom apex       | deep-sea bioluminescence — the clip sinks into an abyss grade with a breathing vignette and every caption is a living light: body words GLOW ON like jellyfish (radial bloom from center while a cyan glow breathes in; emphasis words pulse a slow propulsion double-beat) across two coexisting floating rows and SINK away dimming; seeded plankton motes drift the open water and the ones ringing the apex are pulled into the bloom; the apex is the BLOOM behind the subject: a creature pre-glow double-beats and crushes to a point, the word condenses in, six luminous tendrils draw outward like filaments while caustics shimmer, cyan light spills onto the scene and spores burst past — then all the light sinks back into the deep                                                                                                                                                                                                                   | ocean / nature / science-wonder docs, dreamy or meditative monologues, slow night-time reveals, "深海/发光水母/水下字幕" asks                                                                                  | any (the abyss grade + pocket scrim make their own contrast on bright scenes)                                          | theme.json → make-theme         |
+| `aurora`      | iridescent sheen rail + silk-ribbon draw-on apex         | polar-night elegance — two huge aurora blobs drift the sky all clip; body words are silk serif ink whose rose→teal→violet sheen drifts continuously through the letters (entrance = 2-frame flow-on + y8 settle; emphasis = one bright highlight sweep marching through the word), lines share two coexisting rows like a woven couplet and dissolve UPWARD into drifting light streaks; the apex is a SILK RIBBON: the hero word is hand-WRITTEN into the sky behind the subject stroke by stroke (script single-line font, blurred halo + bright core, a light mote riding the pen) and the aurora gradient keeps FLOWING through the drawn ribbon during the hold while a soft spill tints the sky and light motes rise past the subject — gentle, no shake                                                                                                                                                                                                        | dreamy / romantic / wonder content, night-sky and travel pieces, poetry, weddings, elegant brand films, "极光/丝带/优雅手写字幕" asks                                                                          | any (apex scrim + dark understroke carry contrast on bright skies; loves dusk/night)                                   | theme.json → make-theme         |
+| `spectrum`    | oscilloscope scope-band rail + phosphor trace-write apex | an oscilloscope is listening — a dark scope band hosts an ALWAYS-ALIVE waveform (seeded pseudo-RMS envelope: speech grows it, silence flattens it, every word arrival kicks a local burst) under VT323 phosphor lines that wipe in L→R over reserved slots with a 2-frame just-traced flash (emphasis words get a ticking frequency-readout chip, the trig LED blinks on every word); the apex is the trace itself LEAPING off the scope (surge column) to hand-WRITE the hero word in a thin phosphor script stroke, fill flicker-on, hum + breathe, then COLLAPSE to a flatline before the next spoken word — and on the FINAL word the trace explodes to max-amp chaos, flatlines to a single dot and stamps SIGNAL LOST                                                                                                                                                                                                                                           | science / signal / audio / measurement / astronomy explainers, data-nerd content, retro-lab or synth aesthetics, "示波器/波形/信号字幕" asks                                                                   | any (the scope band brings its own dark glass; the apex scrim handles bright skies); needs `python3` (stroke-path gen) | theme.json → make-theme         |
+| `papercut`    | paper-chip craft rail + stop-motion papermat apex        | stop-motion paper craft — the frame becomes an animator's table: body words are cream paper chips PLACED one by one (steps(2) drop, seeded crooked, ~5fps wobble) on a kraft strip with torn top edge, washi-taped corners and a handwritten cut&paste tag; emphasis words get a washi-tape slap, the final word is an accent-red sign-off chip, and a red paper star stands in for the hero word; the apex is a torn kraft mat slapped down behind the subject where torn-edge letter chips DROP with stepped gravity + anticipation shadows, land crooked, settle in 12fps poses, wobble at 8fps while a warm vignette charges — then the FINAL word bumps the table and everything scatters off down-right                                                                                                                                                                                                                                                         | craft/DIY, kids & family, indie product demos, behind-the-scenes, maker channels, "手工/剪纸/定格动画字幕" asks                                                                                                | any (kraft strip + cream chips bring their own warm contrast)                                                          | theme.json → make-theme         |
+| `popup`       | pop-up book page rail + centerfold starburst apex        | a pop-up book opens inside the frame — body words POP UP on a baseline hinge (rotationX back.out, paper overshoot, a growing back-shadow) along a cream page strip that unfolds from the bottom edge (center foldline, two alternating reading rows); emphasis words land bigger with a contact squash the page FEELS (1px strip dip), then flick-wobble with a blue paper strut leaning in behind; line exits fold flat in an L→R wave (the page closing), the whole page TILTS on the final word and the strip folds shut on the last frame; the apex is THE CENTERFOLD: blue + cream 12-point paper starbursts unfold behind the subject, the hero word pops up in three hinged clip-path segments, kraft struts lean in, backdrop + word wobble-settle TOGETHER and breathe through the hold — then the whole spread folds flat before the next sentence; a blue paper star holds the hero slot on the rail and paper confetti flicks past the subject at the pop | kids and family content, storytelling, education, greeting-card / wholesome brand spots, picture-book and craft channels, "立体书/弹出书/纸艺字幕" asks                                                        | any (the cream page strip is self-lit; the apex dusk scrim guards bright skies)                                        | theme.json → make-theme         |
+| `chalkboard`  | chalk-band rail + hand-written chalkwrite apex           | night lecture — a worn deep-green chalk band where every word is SCRIBBLED in fast chalk (2-frame pop + steps(4) scribble reveal + dust puff at the base, seeded crooked); emphasis gets double underline dashes, the final word lands in yellow chalk, and between sentences an ERASER SWIPE smears the old words off (blurred light band, ghost smudges stay — chalk never fully erases); the apex: the band GROWS into a full blackboard behind the subject and the hero word is HAND-WRITTEN 130px tall stroke by stroke (jittered chalk nib, dust falling from the pen, blurred halo under a tight core), finished with a hand-slap dust CLAP in front of the subject + a 1-frame board shake and two violent accelerating underlines, then the halo breathes through the hold                                                                                                                                                                                   | education / explainers, science and lecture content, teacher channels, documentary asides, "黑板/粉笔/板书/老师讲课字幕" asks                                                                                  | any (the deep-green board brings its own contrast); needs `python3` (stroke-path gen)                                  | theme.json → make-theme         |
+| `graffiti`    | marker rail + spray-tagged handstyle apex                | street bombing run — marker words FLICK onto the rail crooked (1-frame squeak skew, seeded rotation, back.out settle); emphasis takes alternating yellow/magenta paint + a spray-underline swoosh with overspray dots; spent lines are ROLLER-BUFFED away (gray roller sweep, wet smear lingers) and the final word lands BIG in yellow with the punch; the apex: the dusk wall dims, the can RATTLES, and the hero word is spray-TAGGED stroke by stroke behind the subject in fat yellow paint (dark under-stroke armor + blurred overspray halo + glowing nib + seeded overspray dots), paint DRIPS grow from the low points through the hold, a magenta paint splat pops at the pen-finish and the plate punches on it                                                                                                                                                                                                                                            | street culture, hip-hop / rap, sneaker & fashion drops, urban sports, skate/BMX, rebellious brand spots, "涂鸦/喷漆/街头字幕" asks                                                                             | any (the dark under-stroke armors the tag against bright skies); needs `python3` (stroke-path gen)                     | theme.json → make-theme         |
+| `brush`       | washi paper-band rail + sumi-e brush-gesture apex        | sumi-e study — a deckle-edged washi paper band swipes in behind a traveling brush-head shadow; body words are brush-WIPED on in a Mincho serif (clip reveal behind a per-word brush head, seeded ±1° tilt), emphasis gets a double curved ink underline, and spent lines are wiped OFF right-to-left like a wet cloth (erase brush head riding the wipe); the apex: a warm paper wash charges behind the subject and the hero word is written in ONE violent calligraphic gesture — pressure-tapered wet brush (four stacked stroke widths, blurred bleed underneath), start-SPLAT at the first pen contact with ink flecks kicking past the subject, spatter droplets ejected at the sharpest curves — then the ink BLEEDS into the paper through the hold (the work breathes) and a vermilion SEAL chop (観) stamps beside the ink with the plate punch                                                                                                             | calm-authority explainers, craft / design / philosophy / Japan-adjacent content, tea / meditation / writing channels, elegant brand films, "水墨/毛笔/书法字幕" asks                                           | mid/bright scene band (dark ink + its paper wash carry the contrast); needs `python3` (stroke-path gen)                | theme.json → make-theme         |
+| `inkwater`    | three-row ink rail + ink-drop bloom apex                 | sumi ink dropped in still water — paper-white radial washes back the text zones, Mincho-serif ink words BLEED into three fixed reading rows (blur+scale bleed over a paper-glow halo, dark blurred halo overshoots then tightens, an ink-settling hairline under each line, emphasis sheds a curling ink wisp) and spent lines re-dissolve upward like dispersing ink; the apex: a dark drop falls behind the subject, hits an invisible water surface at the word point and BLOOMS (three stacked blurred ink ellipses at counter-rotating rates + two thin ripple rings) while the world stills under a gentle vignette — the hero words resolve out of the blob on their own spoken times, breathe at the glyph edges through the hold, then re-dissolve before the next thought needs the reader                                                                                                                                                                  | contemplative / literary / scientific-wonder narration, astronomy / nature / memory / essay films, poetry and slow-craft channels — one liquid meditative event instead of an impact, "水墨滴落/墨水字幕" asks | mid/bright scene band (dark ink + its paper washes carry the contrast)                                                 | theme.json → make-theme         |
+| `ransom`      | cutout-chip collage rail + ransom-note slam apex         | kidnapper's collage — every word is a chip clipped from a different page (cream Anton / black Inter / newsprint typewriter / accent-yellow marker, torn edges, hard offset shadows) PASTED crooked on the rail with misaligned baselines (the apex slam at low amplitude); emphasis words get a 1-frame RE-PASTE lift (shadow grows, rotation flips sign for good) and spent chips are RIPPED off one by one under 1-frame paper-tear flashes; the apex: a collage scrim darkens the sky and the hero word slams in letter by letter as a ransom note BEHIND the subject — each letter a different cutout chip, flight shadow popping tight on contact — the whole word JOLTS as the last letter lands (the plate punches with it), looms crooked through the hold, then is torn off chip by chip while the closing line speaks                                                                                                                                       | true crime, mystery / thriller, heist energy, punk / DIY zine aesthetics, edgy drops, unhinged-comedy hooks, "勒索信/剪贴/拼贴字幕" asks                                                                       | any (solid chip backgrounds carry their own contrast; the apex scrim guards bright skies)                              | theme.json → make-theme         |
+
+## Shortlisting heuristics (identity-level, not category-level)
+
+- **"每个词都要被读到 / accessibility / 教程·新闻"** → rail or panel surfaces:
+  `anchor`, `ordnance`, `terminal` (all verbatim by construction).
+- **"嵌进场景 / 电影感 / 高级"** → the column-flow ten; pick by register + scene luma
+  (bright → `ink`; warm dark → `cream`; fashion → `editorial`; …). Bright + must-read → `anchor`.
+- **"炸 / 特效 / 酷炫 / 像 AE"** → `ordnance`, `stomp`, `terminal`, `loud` — pick by
+  what should explode: a word (`ordnance`), the frame (`stomp`), a decode (`terminal`),
+  every beat (`loud`).
+- **Named worlds** → direct hits: 控制台/终端 → `terminal`; 霓虹/招牌 → `neonsign`;
+  诗/星尘/记忆 → `stardust`; 军事/重击 → `ordnance`; 预言/未来/悬念揭示 → `lastpage`;
+  赛博朋克/游戏封面/夜之城 → `nightcity`.
+- **Scene constraints veto last**: luma > 180 kills cream/screen column looks
+  (→ `ink` or a rail/panel surface); dusk/dark unlocks `neon`/`neonsign`.
+- **Unsure** → `anchor` (the conservative default: words read, scene safe, zero spectacle).
+  EXCEPTION: if the ask literally says "嵌进场景 / embed into the scene / 电影感", that signal
+  OUTRANKS the conservative default — go column-flow (pick by register + luma), not a rail.
+
+Adjacencies worth knowing (these pairs are why the old mode question was hard —
+recommend by the difference, don't agonize over category): `loud` vs `ordnance`
+(percussive type vs a themed world with plate reaction) · `neon` vs `neonsign`
+(neon-styled captions vs a sign being written) · `cream` vs `stardust` (warm
+embedded flow vs an accumulating poem with semantic dispersal) · `terminal` vs
+`glitch` (a console WORLD with typed log + decode vs corrupted-feed styling on
+normal captions) · `stomp` vs `loud` (every beat takes over the dead-center
+frame vs energetic type that still shares the frame with the subject).
+
+## Rules
+
+- Identities are **engine-locked** — no cross combos. Opening a new combo (e.g.
+  another DNA under rail) is a validation event: render → user review → flip the
+  DNA's `deliveries.rail` flag (see dna/README.md).
+- New identities join via their family's registry rules (dna/README.md for
+  classic, themes/README.md for themed — "any input, zero hand-fixing" bar).
+- The engines' internals (Standard/Cinematic/Theme compilers, gates, layers)
+  are documented in their own files; this catalog is the only routing surface.

package/assets/.agent/skills/embedded-captions/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: embedded-captions
+description: 'Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.'
+metadata:
+  tags: captions, embedded-captions, occlusion, matting, talking-head, rembg-matting, whisper, ffmpeg, cinematic
+---
+
+# Embedded Captions
+
+**One catalog, picked up front** ([CATALOG.md](CATALOG.md) — 17 identities; the three engines behind it are backend detail). **Standard** (default) builds a clean verbatim **rail** (lower-third subtitle carrying most text) + an **embed** climax composited _into_ the scene behind the subject at the peak. **Cinematic** is pure embed — no rail, every caption composited behind the subject (hero typography, accumulation, occlusion as the effect). **Theme** is a complete themed constitution — body paradigm × hero setpiece × front fx × plate reaction, composed from registries ([themes/README.md](themes/README.md)): `ordnance` `terminal` `neonsign` `stardust` `stomp`. Most explainer / voiceover is **Standard**; **embed is the scarce, earned peak** — embedding every word is the common mistake; Theme is for VFX-grade asks ("炸", "特效", "像 AE 做的").
+
+---
+
+## Operational flow (TL;DR)
+
+The craft prose below is long; the **pipeline itself is short** — and everything
+deterministic is computed or compiled, never hand-written:
+
+1. **Decision gate** (refuse bad clips) → **pick ONE identity from [CATALOG.md](CATALOG.md)** (17 identities; engine/compiler derived by lookup — never surface a mode/category question)
+2. `hyperframes init` (skip it if the project dir already exists with the video inside — `matte.cjs`/`transcribe.cjs` adopt any video in the dir as source.mp4) → **`bash scripts/prepare.sh <project>`** (matte ∥ transcribe ∥ audio-envelope in parallel, then safe-zones v2 with scene palette/optics/lighting — one command, nothing forgotten)
+3. **author a small JSON of creative choices** (read `safe-zones.json` first):
+   Cinematic → `plan.json` → `fill-timings.cjs` → `fit-fonts.cjs` → `make-composition.cjs`;
+   Theme → `theme.json` → `make-theme.cjs` (rail/panel/poem/takeover paradigms; `anchor` is the quiet rail default)
+4. **Visual QA**: `node scripts/preview-frames.cjs <project>` → faithful composite previews in ~2s/frame (no render). Check § Visual QA before paying for a render.
+5. `render-and-composite.sh` → gates (timing / occlusion+hero / overflow / hand-off) → `final.mp4`
+
+Load-bearing rules people miss:
+
+- **rail (default) + embed (promotion).** `drop` (filler, not shown) / `rail` (verbatim lower-third subtitle, in front, carries most text) / `embed` (a peak word composited behind the subject). **Standard mode does both**, embedding only the peak(s). See **§ Caption model**.
+- **The video is delivered UNTOUCHED (Standard/Cinematic; **Theme mode's PLATE budget is the one sanctioned exception** — register-gated reaction beats (charge-dim, punch, shake, grain) defined per theme DNA and applied AFTER the matte composite so subject+text+plate move as one frame)** — captions are the only thing added; the matte just lets the subject occlude the embed track. Never grade/recolor/scanline the footage.
+- Two rulebooks: **rail → [references/rail.md](references/rail.md)** (thin), **embed craft → [references/composition-craft.md](references/composition-craft.md)** (rich, embed-only). Skim by need.
+
+---
+
+## Caption model — rail + embed
+
+Every spoken phrase is one of three things:
+
+|           | What                                             | How it's shown                                                                                                                                                    |
+| --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **drop**  | filler — um/uh, stutters, self-corrections       | not shown                                                                                                                                                         |
+| **rail**  | the default — ordinary spoken content (verbatim) | clean lower-third subtitle, **in front**, readable. A punch word can get an inline `emphasis` highlight (accent colour / active-word pop) — it stays on the rail. |
+| **embed** | a promoted peak — the headline beat              | one big word composited **behind the subject** (matte occlusion), designed entrance + exit                                                                        |
+
+**The rail carries most of the text; embed is the scarce, earned peak.** Scarcity is **per beat/block, not per clip**: ≤1 hero per block (thought), never two co-visible, ≥ a beat of air between hero windows (the compiler warns under 0.6s). A short clip → usually 1–2; a long explainer → ~one per section. Among multiple heroes, the **largest authored one is the APEX** (it alone gets the full lockup embed + width-fit raise); smaller ones are **MINOR peaks** that ride their column as oversized emphasis lines (fg, damped motion) — not every beat needs the matte showcase, which is exactly what keeps the apex an event. Embedding every word is still the common mistake.
+
+Rail-surface identities build exactly this (rail = `rail.html`, embed = the climax in `index.html`). Column-flow identities drop the rail and make everything embed-style — recommend them only for mood-over-verbatim asks, never for explainer / voiceover where the words must read (CATALOG.md encodes this per identity).
+
+---
+
+## Step 0 — pick ONE identity from the CATALOG
+
+**One front-end, three engines behind.** The user picks an IDENTITY from
+[CATALOG.md](CATALOG.md) (17 entries: 12 classic + 5 themed); the engine,
+compiler and authoring file are derived by lookup from the catalog row.
+**Never surface "Standard vs Cinematic vs Theme" as a question** — those are
+backend names (a product has one UX even with several engines). The catalog
+encodes everything routing needs: reading surface, voice, recommend-for, scene
+needs, adjacency notes for the genuinely-close pairs (loud↔ordnance,
+neon↔neonsign, cream↔stardust).
+
+Procedure: probe the clip → shortlist 2–3 identities from the catalog →
+recommend ONE with a one-line why → **the user picks** → author that identity's
+file. Identities are engine-locked (no cross combos; opening one is a
+validation event — see dna/README.md).
+
+**Always present your recommendation and let the user pick before you author.** Don't silently default.
+
+(The full identity table lives in [CATALOG.md](CATALOG.md) — single source of truth for routing. The engine docs below describe each backend's authoring contract.)
+
+**Recommendation heuristic**: use the "Shortlisting heuristics" in [CATALOG.md](CATALOG.md) — they are identity-level (e.g. "炸" shortlists ordnance/stomp/terminal/loud and picks by WHAT should explode), never category-level. Unsure → `anchor`.
+
+- **Cinematic** → write `plan.json` for a locked template, compiled by `make-composition.cjs`.
+- **Theme** → read [themes/README.md](themes/README.md), author `theme.json`, run `scripts/render-theme.sh` (compiles + renders + plate reaction → **final_fx.mp4**).
+
+---
+
+## Decision gate — RUN FIRST
+
+Probe the video and classify the scene before either mode.
+
+```bash
+ffprobe <video.mp4>                    # specs
+ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # at 20/50/80%
+```
+
+Read the samples. Refuse if:
+
+- Multiple speakers / hard cuts (split & render each shot, or refuse)
+- No human subject (this skill is for talking-head)
+- Under 3 seconds, **no speech**, or face never clearly visible — `transcribe.cjs` warns when audio is near-silent (Whisper hallucinates words like "Thank you." over silence); **heed it and refuse** rather than caption fabricated words
+- **Source already has burned-in captions / subtitles / heavy text graphics** — adding a second caption system conflicts and the footage ships untouched (no covering/inpainting). Burned text often appears only mid-clip: sample a **1fps contact sheet** (`ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png`), don't trust 3 spot frames.
+- **Transcript is garbage** — non-native/heavy-accent speech can transcribe into confident gibberish. Sanity-read `transcript.json` before authoring; if it doesn't parse as language, try `WHISPER_MODEL=medium` once, else refuse (a verbatim rail of fabricated words is worse than no captions).
+- Busy handheld with fast motion (matte flickers)
+
+### Pre-flight probes (cost nothing, prevent the worst failures)
+
+1. **Shot-cut probe.** Sample frames at 20%, 50%, 80%. If a different subject/scene appears, **trim the clip** before the cut.
+2. **Letterbox / pillarbox probe.** Black bars on the first frame? Compute safe content rect and constrain caption placement inside it.
+3. **Luminance probe.** Sample the caption region's average luminance — `under 60` → light text reads as-is, `60-180` → add the glyph scrim, `180+` → opaque text + scrim (never bare light text). **Cinematic templates are cream+`screen` and LOCKED** — use this probe to _pick a fitting identity_ (bright scenes → `ink`, or the opaque-rail `anchor` theme), never to recolour one.
+4. **Identity recommendation by tone (you recommend; the user picks — see Step 0 + CATALOG.md).** explainer / interview / must-read words → rail/panel-surface identities; poetic / social / "cinematic" → column-flow identities by register; "炸 / 特效 / VFX" / named worlds → themed identities. When unsure → `anchor` (words read, scene safe) — but present a shortlist and let the user choose.
+
+---
+
+## Pipeline — 5 steps
+
+```
+1. hyperframes init <project> --non-interactive --video <video.mp4>
+2. bash scripts/prepare.sh <project>       # matte ∥ transcribe (parallel) → safe-zones. One command.
+                                           #   → frames_fg/ transcript.json safe-zones.json
+3. [AGENT STEP — the only creative step] author a small JSON; see below by mode
+   Cinematic: author plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
+   Theme:     author theme.json → bash scripts/render-theme.sh <project>   (compiles + renders + plate fx)
+4. node scripts/preview-frames.cjs <project>   # ~2s/frame composite previews → § Visual QA (BEFORE the render)
+5. bash scripts/render-and-composite.sh <project>  # gates → final.mp4 + history/ snapshot
+   (Theme mode: SKIP steps 3b/5 — render-theme.sh already runs compile + render-and-composite
+    + _postfx.sh; the deliverable is final_fx.mp4, final.mp4 is pre-plate-reaction)
+```
+
+Step 1's `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
+
+Step 3 differs by mode:
+
+### Step 3 — Cinematic mode (pure embed)
+
+1. **Read `safe-zones.json` first.** Narration planes go in **`zones.hugLeft`/`hugRight`** — clean strips ABUTTING the silhouette (text far from the body reads as floating, not embedded; far corners are the fallback, not the default). The hero defaults to `heroAnchor`/`heroBands.best` (centered ON the subject, ~30–55% occluded). `recommendation:"fg"` moves NARRATION in front for legibility; **the hero stays embedded whenever `heroBands.feasible`** — hero-fg is the last resort.
+2. **The DNA is the identity you picked in Step 0** (CATALOG.md) — do not re-open the choice here. Sanity-check it against the scene (bright hero band luma > 150 wants `ink`; full pick guidance lives in the catalog, covering all ten incl. neon / glitch / chrome / velocity). State your pick + why; the user decides. The DNA locks type/palette/blend/motion + hero three-act; safe-zones v2 (`palette`/`optics`/`lighting`) parameterizes it to THIS scene automatically.
+3. **Author `<project>/cinematic.json`** — `"dna": "<name>"` + thought-BLOCKS, not raw groups: each block = lines of words (grouped 2–5 at clause boundaries) + the plane it stacks in + per-line `css` (size/weight/style only — no positions) + at most ONE line marked `"hero": true` (the promoted word; `"text"` for display form). Schema: `scripts/make-cinematic.cjs` header.
+4. **Compile**: `node scripts/make-cinematic.cjs <project>` — lowers blocks → plan.json → index.html. Generated for you: transcript-sequenced timings, accumulate-within-block, page-flip-between-blocks, **the hero LOCKUP** (a hero block's pre-context, HERO and post-context stack as ONE bonded composition centered on the subject — reading order top→bottom = spoken order by construction; context floats in FRONT while the hero embeds BEHIND = the depth sandwich; a mass rule keeps the hero dominating its context), apex/minor hero split, **reading order by construction**, fg fallback per safe-zones. Then the gates run as usual. _(Hand-authoring plan.json directly remains possible for designs blocks can't express — then run `fill-timings.cjs` + `fit-fonts.cjs` + `make-composition.cjs` yourself.)_
+
+### Step 3 — Theme mode (themed constitution)
+
+**Read [themes/README.md](themes/README.md) FIRST** — paradigm/setpiece registries, linkages, hard rules, and the exact `theme.json` schema.
+
+1. **Pick a theme DNA** by content register (each `themes/<name>.json` has `voice` + `when`). State your pick + why; the user decides.
+2. **Author `<project>/theme.json`** — `dna`, `lines` (verbatim, transcript order; 1–5 words each — for `takeover` each line is one CARD), `minors` (emphasis words), `hero:{match}` (the climax word/phrase; leave it OUT of `lines` for embed setpieces, keep it IN for inline setpieces and panel+redact).
+3. **Render**: `bash scripts/render-theme.sh <project>` — compiles (verbatim-completeness gate at compile time), renders both layers, composites, applies the plate reaction → `final_fx.mp4`. Use `preview-frames.cjs` between compile and render for Visual QA.
+
+---
+
+## Visual QA — preview BEFORE you render
+
+`node scripts/preview-frames.cjs <project> [t…]` composites **faithful preview frames in ~2s each**
+(caption layers screenshotted at seek-time + real video frame + matte occlusion + rail overlay = what
+the final composite will look like at that moment). Default samples = each group/climax window.
+A full render costs minutes — never use it to _discover_ layout problems.
+
+Check the previews (`<project>/preview/sheet.png`) against this list — these are the failures the
+geometric gates **cannot** catch:
+
+1. **Washout** — light text over a bright region (window/sign/sky): unreadable → move the plane or change DNA/mode (bright scene → `ink`).
+2. **Text-on-text** — captions over the scene's own text/graphics, or two caption groups colliding.
+3. **Reading order** — on-screen vertical order must match spoken order; the hero must not sit below later words.
+4. **Hero presence** — the climax should be BIG and visibly behind the subject (~30–55% occluded), not a floating label in a margin.
+5. **Balance** — one coherent column/band, not scattered fragments; margins breathing; nothing clipped.
+
+Then the **5 positive checks** in [references/reference-bar.md](references/reference-bar.md)
+(poster test · timid test · one-glance hierarchy · scene handshake · dead-air audit) — the
+failure list keeps a render from being broken; the positive list is what makes it _designed_.
+Ship when both pass.
+
+**Fresh-eyes review (recommended for anything user-facing):** you have confirmation bias about your
+own layout. If you can spawn a subagent, give it ONLY the preview sheet + this checklist and ask for
+PASS/FIX verdicts per frame ("review these caption previews against the 5-point checklist; answer
+PASS or the specific fix per frame"). Apply fixes in plan.json / theme.json, recompile, re-preview —
+each loop costs seconds. Render once, when the previews pass.
+
+---
+
+## The DNA registry — ten visual languages (replaces the template catalog)
+
+Both modes draw from **[dna/](dna/README.md)** — six art-directed visual languages that
+**parameterize per scene** (accent sampled from the footage, contact shadow along the
+measured light direction, depth-match blur, RMS-coupled hero amplitude):
+
+| DNA             | Register       | Scene fit                                       | Voice                                                                                              |
+| --------------- | -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **cream**       | premium-warm   | dark/mid warm scenes                            | Inter + warm cream + screen; glowing emergence hero (successor of cinematic-cream)                 |
+| **ink**         | premium        | **bright scenes (luma > 150)**                  | near-black multiply — type printed ON the wall; the bright-scene answer                            |
+| **editorial**   | editorial-luxe | introspective / fashion / poetic                | Bodoni Moda, lowercase-italic hero — magazine elegance                                             |
+| **keynote**     | tech-premium   | product / launch                                | opaque white Inter 800, dead-center stillness                                                      |
+| **documentary** | formal         | interview / serious                             | burn-in reveals, no hero — gravitas IS the style                                                   |
+| **loud**        | loud           | hype / sport / social                           | Anton + scene-sampled accent, single-unit slam + ripple; body ANNOUNCES in front (`bodyLayer: fg`) |
+| **neon**        | loud-cyber     | cyberpunk / nightlife / tech-noir (dark scenes) | electric-cyan signage, ignition flicker, the hero powers ON like a sign                            |
+| **glitch**      | loud-cyber     | digital / hacker / AI                           | RGB-split echoes snap together on landing; machine-percussive timing                               |
+| **chrome**      | loud-luxe      | Y2K / fashion-tech / music                      | liquid-metal gradient hero + one sheen sweep during the hold                                       |
+| **velocity**    | loud-sport     | sport / auto / fitness                          | every word arrives along its motion vector (streak+skew), hero passes with speed trails            |
+
+Pick by `safe-zones.json` (`heroAnchor.bandLuma`, `palette.temperature`) × content
+register — [dna/README.md](dna/README.md) has the decision rule. Authoring:
+`cinematic.json` takes `"dna": "<name>"`.
+
+The engine generates the **hero three-act** from the DNA (no authoring needed):
+co-visible captions dim (setup) → per-letter entrance with amplitude ∝ spoken loudness
+(impact) → breathe + glow until exit (afterglow).
+
+(Legacy: `plan.template:"cinematic-cream"` maps to `dna:"cream"` automatically.
+The retired 54-template library lives outside the skill at
+`~/Downloads/embedded-captions-archive/standard-templates-54/`; `_motion.md` remains
+in-skill as the motion-verb reference catalog.)
+
+---
+
+## Aesthetic decision — tone × shot × platform (input to the catalog shortlist, NOT a second router)
+
+Classify the clip on 3 axes and feed the result into CATALOG.md's shortlisting — this section never picks a mode/engine by itself:
+
+**Tone** (what feel does the content have?)
+
+- documentary | conversational | energetic | poetic | keynote | investigative | music-video
+
+**Shot** (what's the framing?)
+
+- close-up (head + shoulders) | mid-shot (torso+) | wide (full body+) | cut-montage (mixed shots)
+
+**Platform** (where will it play?)
+
+- 9:16 portrait (TikTok/IG/Shorts) | 16:9 landscape (YouTube/web) | 1:1 square | broadcast export
+
+Cross-reference in [references/direction-catalog.md § Classification matrix](references/direction-catalog.md) for direction language — then return to [CATALOG.md](CATALOG.md) to shortlist identities (this matrix informs the shortlist; the catalog is the only routing surface).
+
+## Composition craft (embed track) — read before embedding
+
+The full **embed-track** playbook lives in **[references/composition-craft.md](references/composition-craft.md)**:
+transcript role-annotation, phrase grouping, planes & clean-zone anchoring, zone coherence,
+climax pop & readability, edge-breathing, the occlusion 3-step judgement, and
+accumulation/persistence. It governs how a _promoted_ phrase sits INTO the scene — read it
+before authoring any embed (Cinematic `plan.json` or Standard `index.html`). The default **rail**
+track has its own, much simpler spec → **[references/rail.md](references/rail.md)**.
+
+---
+
+## Shared knowledge
+
+| Doc                                                                      | What                                                                                                                               |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| [references/rail.md](references/rail.md)                                 | **The rail track** — standard lower-third subtitle spec (the default; carries most text).                                          |
+| [references/composition-craft.md](references/composition-craft.md)       | **The embed-track playbook** — grouping, planes, climax pop, occlusion judgement, accumulation/persistence. Read before embedding. |
+| [dna/README.md](dna/README.md)                                           | **The DNA registry** — six scene-parameterized visual languages; how to pick.                                                      |
+| [references/reference-bar.md](references/reference-bar.md)               | **The taste bar** — per-register world-class references + the 5 positive checks.                                                   |
+| [references/aesthetic-principles.md](references/aesthetic-principles.md) | **The 18 rules.** Beat Veed AI on taste. Read first.                                                                               |
+| [references/motion-vocabulary.md](references/motion-vocabulary.md)       | 10 named motion primitives + tone→timing lookup                                                                                    |
+| [references/direction-catalog.md](references/direction-catalog.md)       | 10 ship-ready aesthetics + tone×shot×platform matrix                                                                               |
+| [references/anti-patterns.md](references/anti-patterns.md)               | Bugs already locked out (CoreML, letter-spacing reflow, etc.)                                                                      |
+| [references/scene-types.md](references/scene-types.md)                   | When a wall surface is usable (4 conditions)                                                                                       |
+| [references/layout-heuristics.md](references/layout-heuristics.md)       | Plane positioning, clean-zone selection, crown 3 conditions, pillarbox math                                                        |
+| [references/typography-presets.md](references/typography-presets.md)     | Font-size × column-width matrix (starting points)                                                                                  |
+| [references/caption-grouping.md](references/caption-grouping.md)         | Word → group rules (pauses, sentence boundaries)                                                                                   |
+| [references/failure-modes.md](references/failure-modes.md)               | Long tail of dev gotchas                                                                                                           |
+| [references/bespoke-vs-presets.md](references/bespoke-vs-presets.md)     | Why presets fail sometimes; clone-and-tweak pattern                                                                                |
+
+**Read the aesthetic principles and direction catalog FIRST.** Everything else is implementation detail.
+
+---
+
+## Non-negotiables
+
+- **Face must never be 100%-covered continuously** — every 0.3s window, face bbox ≥30% uncovered.
+- **WCAG contrast** — final render lints; fix palette if it fails.
+- **Deterministic** — no `Math.random()`, no `Date.now()`, no `repeat:-1`.
+- **Never grade/recolor the video.** The footage ships untouched — captions are the only addition. No full-frame scanlines / duotone / darken / vignette over the a-roll. Cyberpunk/CRT texture belongs _inside_ a caption element, not over the whole frame.
+- **Rail-first for talking-head / explainer.** Don't embed the whole transcript — most text is the rail; embed only peaks. Embedding everything is the default mistake.
+- **Embed is scarce + spaced.** ≤1 embed per sentence/beat, never two adjacent or co-visible, ≥ a beat apart, at most one `apex`. climax = per-beat peak, **not** "the single payoff of the entire clip."
+- **Matte = the PERSON (hyperframes `remove-background`, u2net_human_seg, Apache-2.0).** Human segmentation by intent, but not surgically: thin offset furniture (mic boom arms) is usually excluded — captions render over it, behind the person — while large salient objects NEAR the subject (a telescope, a desk rig) can still leak into the matte and occlude captions. Objects HELD by the subject (products, phones) may drop out intermittently, letting captions pass in front. NEVER assume: sample `frames_fg/` at 2-3 timestamps before placing the hero, and prefer hero positions clear of any leaked furniture (`heroAnchor` can be skewed by leaks — cross-check against frames_bg).
+- **safe-zones is PROP-BLIND — eyeball every band you use.** Zones/heroBands score _subject_ occlusion + luma only: a mic, telescope, or screen sitting inside a "clean" zone is invisible to them (and a prop leaking INTO the matte skews `heroAnchor.centerXPct` off the person). Before authoring, extract ONE frame of each band you intend to use; if a prop lives there, measure its bbox and move/shrink the plane. Two real cases shipped clean only because the agent did exactly this. (Auto prop-saliency is a known gap; zones' `peakLuma` only catches _moving_ bright objects.)
+- **Captions stay on-frame.** Cinematic mode hard-gates frame-overflow; Standard mode runs `check-overflow.cjs` as a WARNING (intentional bleed is the only exception — read the warning).
+- **Each caption ≥ 0.5s on screen** — shorter = unreadable.
+- **Word timings must match transcript.json within 80ms** — a caption firing 500ms off-beat destroys the scene illusion. Cinematic runs `check-timing.cjs --strict` before rendering (via render-and-composite.sh); THEME mode enforces the same timings at compile time instead (make-theme's sequential transcript matcher + verbatim completeness gate — drift is a compile error). Never pack multiple transcript words into one entry (e.g. `"FUTURE OF"` or an `IT` + line-break + `ALL` stack with one start/end) — the second word inherits the first's timestamp and fires early. Split them into separate word entries with their own timings, even if you want them on the same visual line (use CSS `white-space` / natural wrap instead of `<br>`). Creative substitutions where caption text ≠ transcript (e.g. `"15%"` replacing `"fifteen percent"`) are supported — register them in `CREATIVE_SUBS` inside `check-timing.cjs`.
+- **Group windows must envelop their words** — `group.in ≤ min(word.start)` and `group.out ≥ max(word.end)` for every group. If `group.in` is later than a word's start, the word is silently delayed until the container mounts (we've shipped 800ms lag bugs from this). The validator enforces this.
+- **No two caption groups may overlap in both time AND screen region** — overlapping-in-time captions create text-on-text pileups. Options: (a) **spatial separation** — place each group in a non-overlapping vertical band so they can coexist (memory-wall cascade style); (b) **handoff** — set the earlier group's `out` ≤ the next group's `in` so only one is on screen; (c) **deliberate layered typography** — add `"allow_overlap": true` on one of the groups to silence the validator. The validator estimates each group's vertical bbox from its CSS and flags collisions. Pick (a) by default — it's what makes cinematic-cream feel like a poem accumulating, not a subtitle track replacing itself.
+- **Screen-blend fails on bright backgrounds (>180 luminance).** **Cinematic** templates are cream + `screen` and that DNA is **locked** (the plan can't recolour them) → on a bright backdrop they wash out, so pick `ink` (letterpress built FOR bright surfaces) or the `anchor` theme (opaque rail surface) rather than overriding a look.
+- **Don't animate `letter-spacing` or `filter:blur` on word entrance** — inline-block reflow causes line-jumps.
+- **CoreML banned for matting** — the onnxruntime CoreML EP's mixed-precision partitioning corrupted face alpha (observed with the previous RVM engine; don't re-try it). Matting is CPU-only (~2 fps @1080p ≈ 2-3 min per 10s clip; budget for it on long clips).
+
+---
+
+## Dependencies
+
+- **hyperframes**, built (`packages/cli/dist/cli.js`). Scripts auto-resolve the checkout: `HYPERFRAMES_ROOT` env → repo root if this skill ships _inside_ hyperframes → `~/Downloads/hyperframes`. Build with `bun install && bun run build`.
+- **Node-first; two Python touchpoints via `uvx` (no manual installs):** transcription runs WhisperX through `uvx` (word-level timings; falls back per SKILL §transcription), and Theme's `drawon` setpiece shells `python3 scripts/gen-stroke-path.py` at compile time. Everything else runs on the toolchain hyperframes already ships: matting via the hyperframes CLI's **`remove-background`** (u2net_human_seg; weights auto-download once, ~168 MB, to `~/.cache/hyperframes/`), image/alpha math via **`sharp`**, layout/occlusion/overflow via **`puppeteer`**, plus **`ffmpeg`**. The scripts auto-resolve these from the hyperframes checkout — nothing extra to install.
+- **Transcription = WhisperX via `uvx`** (word-level timings + alignment; no manual install — `transcribe.cjs` drives `uvx whisperx`). Falls back to an existing word-level `transcript.json` if present.
+- **Source video** — `matte.cjs` / `transcribe.cjs` auto-resolve `source.mp4` (or glob the clip / read `hyperframes.json`), so `hyperframes init --video X.mp4` needs no manual rename.
+- **fps** — `matte.cjs` extracts at the source's native rate and records `matte.fps`; `render-and-composite.sh` uses that so the matte stays frame-aligned.
+- Matting weights are NOT bundled: `matte.cjs` shells the hyperframes CLI's `remove-background`, which downloads u2net_human_seg (~168 MB, Apache-2.0) once to `~/.cache/hyperframes/background-removal/models/`. First prepare on a fresh machine needs network for that one download.
+
+If a hard dependency is missing, STOP and ask the user — don't silently skip steps.