@ericrisco/rsc 3.1.3 → 3.3.0

package/skills/design/evals/cases.yaml

@@ -1,56 +1,45 @@
 skill: design
 
 should_trigger:
-  - prompt: "Design a landing page for our new analytics SaaS — hero, pricing, the works."
-    why: "Explicit landing-page design with full marketing-page composition; this is the skill's core use case."
-  - prompt: "Our homepage looks generic, like every other AI-generated startup site. Can you make it feel premium and intentional?"
-    why: "Rescuing a 'feels generic / AI-slop' UI is named verbatim in the description and the When-to-use list."
-  - prompt: "Pick a color palette and type pairing for my product, and give me the Tailwind tokens."
-    why: "Choosing a visual system (color, type, tokens) is an explicit trigger; the skill ships Tailwind v4 @theme OKLCH tokens."
-  - prompt: "Can you do a design review of this hero section and tell me how to make it convert better?"
-    why: "Design review / critique plus conversion intent; the skill has a dedicated design-review QA checklist and a 0-10 visual-audit rubric."
-  - prompt: "I've got the React components built and working, but it all just looks flat and amateur — help me polish the visuals and spacing."
-    why: "A polish pass on an existing surface; user names the symptom (flat/amateur) without naming a tool, which the skill targets ('make an interface feel premium')."
-  - prompt: "Write the hero headline and a punchy value prop for our developer-tool site, and lay out the page so it sells."
-    why: "Conversion copy (hero/value-prop) plus page layout for selling — the skill owns visual + landing structure and co-owns copy; non-obvious because it leads with copy."
-  - prompt: "Add a bento-grid features section to our marketing site that doesn't look like a template."
-    why: "'bento section' is an explicit named trigger; involves layout/composition for a marketing surface."
+  - prompt: "Design a landing page for our new analytics SaaS."
+    why: "A public page to design from scratch is the page run's core case (Persuade mode)."
+  - prompt: "Our homepage looks generic, like every other AI-generated startup site. Make it look designed."
+    why: "'Looks generic / AI-made' is named in the description; the skill exists to replace the model's default."
+  - prompt: "Hazme la web de un restaurante de mi pueblo, que no parezca una plantilla."
+    why: "A local business page in Spanish; the inventory of the subject and real pictures are exactly what the run forces."
+  - prompt: "Rediseña el dashboard de facturación, que se ve feo y desordenado."
+    why: "An app screen redesign (Operate mode) follows the app-screen run with its own draw and inspector."
+  - prompt: "Review this portfolio page and tell me the three changes that would improve it most."
+    why: "A review of an existing page: record the before in the browser, critique the screenshots, stop at findings."
+  - prompt: "Restyle our docs site so it stops looking like every other docs template."
+    why: "Read mode: the style owns the frame while the reading column stays calm."
 
 should_not_trigger:
-  - prompt: "Write the SEO keyword strategy and do a technical SEO audit for our marketing site, targeting buyer-intent terms."
-    route_to: "marketing"
-    why: "Deep keyword research, GEO, and technical SEO audits are explicitly delegated to the marketing sibling; design only enforces SEO-aware markup structure."
-  - prompt: "Set up the Next.js 15 App Router routing, server actions, and data fetching for these pages."
+  - prompt: "Write the hero headline, offer and CTA copy for our pricing page."
+    route_to: "landing-copy"
+    why: "The words on a conversion page belong to landing-copy; design builds the page around them."
+  - prompt: "Where should the filter state live, in the URL or in the component, and how do we handle loading and errors?"
+    route_to: "ui-engineering"
+    why: "How interface is built (state, boundaries, async states) is ui-engineering, not visual design."
+  - prompt: "Make our web app pass WCAG 2.2 AA: fix the axe violations and keyboard traps."
+    route_to: "accessibility"
+    why: "Conformance remediation is the accessibility skill's job."
+  - prompt: "Create our logo brief and a full brand book with print colours."
+    route_to: "brand-identity"
+    why: "A brand system for every medium is brand-identity; design consumes it with --keep palette,type."
+  - prompt: "Set up Next.js App Router routing and server actions for these pages."
     route_to: "nextjs"
-    why: "Pure App Router / React 19 build mechanics are the nextjs sibling's job; design hands off the build."
-  - prompt: "Build a daily-use internal ops dashboard for our support team to triage tickets fast — pure data tables, no marketing."
-    route_to: "none"
-    why: "Dense internal operational tooling is explicitly a do-NOT-force-a-landing case; the skill says not to paint a marketing skin on a daily-use tool. Routes to product judgment, not a sibling."
-  - prompt: "Mirror our brand colors and typography into the Flutter mobile app's theme."
-    route_to: "flutter"
-    why: "Translating brand tokens into a Flutter app is the flutter sibling's job, not web UI design."
-  - prompt: "Implement an iOS 26 SwiftUI Liquid Glass material for this native settings panel."
-    route_to: "none"
-    why: "Native iOS Liquid Glass is the external liquid-glass-design reference; this skill ships only the web glass approximation, so it should decline/defer (no in-repo sibling)."
-  - prompt: "Help me wire up the spring physics and AnimatePresence layout animations for this modal in Framer Motion."
-    route_to: "none"
-    why: "Deep motion-code mechanics (springs, AnimatePresence internals) are explicitly deferred to the external motion-ui references; design only sets motion intent + budget."
+    why: "Framework build mechanics are nextjs."
 
 capability:
-  - scenario: "User asks: 'Design the hero section for our new SaaS landing page and make it look premium.' (No 02-DOCS/wiki/brand/ study exists in the repo yet.)"
+  - scenario: "Asked to build a landing page for a bakery with no brand and no photographs."
     must_include:
-      - "STOPS before designing and checks for a brand study at 02-DOCS/wiki/brand/ (via root CLAUDE.md ## Brand & voice); on finding it missing/incomplete, asks a focused batch of brand-grounding questions instead of guessing."
-      - "Runs (or states it will run) the research-first protocol: WebSearch award galleries / tier-1 sites and synthesize a cited DESIGN DIRECTION before prescribing, rather than shipping from memory."
-      - "Enforces the 5-second value-prop test: hero states what it is, who it's for, why it's better, above the fold — and shows the product, not a centered headline over an atmospheric gradient."
-      - "Uses design tokens (Tailwind v4 @theme, OKLCH color, modular type scale, 4/8px spacing, radius/shadow tokens) — no magic hex or arbitrary px."
-      - "Treats accessibility as a hard constraint: text contrast >= 4.5:1, visible focus, one <h1>, semantic landmarks, touch targets >= 24px (44px ideal)."
-      - "Treats Core Web Vitals as design constraints: LCP < 2.5s with next/image priority on the hero image, INP < 200ms, CLS < 0.1, next/font."
-      - "Benefit-led, specific copy that avoids the ban-list (revolutionary, seamless, game-changer, unlock, supercharge, elevate, etc.)."
-  - scenario: "User asks: 'Here's our current pricing page — do a design review and tell me how good it actually is.'"
+      - "inventory of eight to twelve things only this client has"
+      - "draw.mjs deals three directions; one is chosen against the inventory with a written reason"
+      - "an idea sentence that fails the competitor test, and one live thing"
+      - "at least four real pictures found with assets.mjs and credited"
+      - "inspect.mjs at 1440, 768 and 390 with zero FAIL before reporting"
+  - scenario: "The machine has no Chrome and Node 20."
     must_include:
-      - "Applies the design-review QA checklist (value prop in 5s, contrast >= 4.5:1, visible focus, one <h1>, semantic landmarks, LCP image priority, next/font, no transition: all, tokens not magic numbers, ban-list-clean copy, 360px fit, empty/loading/error states)."
-      - "Scores the 11-dimension visual-audit rubric 0-10 with weights and reports the weighted total on its /115 scale, mapped to a band (<69 generic / 69-91 competent / 92-108 premium / 109+ award-tier)."
-      - "For each dimension scoring below 8, gives a concrete actionable fix (e.g. exact spacing/token change), not a vague 'improve spacing'."
-      - "Checks copy against the ban-list and flags hype/vague value props that fail the 5s test."
-      - "Flags any transition: all, magic hex/px, cards-in-cards, or purple->blue everything gradient as defects, not preferences."
-      - "Ties findings back to the brand study / cited trend source where the bar is set, rather than asserting taste."
+      - "runs lint.mjs and critiques screenshots from another browser tool"
+      - "the report says 'inspector not run' with the reason and claims no gate pass"

package/skills/design/references/design-md.md

@@ -0,0 +1,49 @@
+# DESIGN.md: the record of the system
+
+Adapted from impeccable's `document` by Paul Bakaus (Apache-2.0), which follows the open
+`design.md` format. Rewritten and shortened.
+
+The point: the next edit, the next session and the next tool keep the look instead of drifting back
+to the model's default. Write it **after** the build, from what was actually built and measured,
+never before. A rulebook written ahead of the build gets defended against reality.
+
+## Where and when
+
+- `DESIGN.md` at the project root, committed with the code.
+- Written when a surface creates or replaces the visual system. Extending an existing surface reads
+  it and does not rewrite it.
+- If `02-DOCS/wiki/brand/` exists, `DESIGN.md` uses the brand's colours and faces and names that
+  file as its source.
+
+## Shape
+
+YAML front matter holds the tokens; the body explains them.
+
+```markdown
+---
+name: <product>
+description: <one line: the idea sentence>
+colors:
+  ground: "#…"
+  ink: "#…"
+  accent: "#…"
+  field: "#…"
+typography:
+  display: { fontFamily: "…", fontWeight: 600, letterSpacing: "-0.03em", lineHeight: 0.95 }
+  text: { fontFamily: "…", fontSize: "18px", lineHeight: 1.5 }
+rounded: { button: "0px", media: "0px" }
+spacing: { margin: "24px", section: "200px" }
+direction: { id: "<dealt id>", seed: <n> }
+---
+
+## Overview        the idea, the mode, the direction and why it was chosen
+## Colors          roles and proportions (one ground, one ink, one accent, fields)
+## Typography      the scale actually used, tracking, measure
+## Layout          grid, outer margins, section rhythm, the phone composition
+## Imagery         sources, crops, treatment, where credits live
+## Motion          the signature move and the entrance recipe
+## Components      buttons, navigation, the live thing, footer
+## Do's and Don'ts the house rules this project relies on, plus any `--allow` and its reason
+```
+
+Values come from the built CSS and the inspector's measurements, not from memory.

package/skills/design/references/finish-review.md

@@ -0,0 +1,46 @@
+# The fresh review
+
+Adapted from impeccable's finish reviewer by Paul Bakaus (Apache-2.0); rewritten and shortened.
+
+The builder believes its own page. The review runs **outside** the build: a fresh subagent with no
+history of this conversation, so it does not inherit the builder's framing or optimism. Without
+subagents, step fully out of the build and run the same checks yourself, and say in the report that
+the review was not independent.
+
+## The packet
+
+Hand it only this:
+
+- the original request and the user's answers;
+- the screenshots from `.taste-skill/inspect/` at every width (the reviewer has no browser);
+- the last `inspect.mjs` result;
+- the direction sheet (`draw.mjs --show`), the idea sentence and the live thing;
+- the paths of `../engine/RUN.md` (house rules) and `../engine/references/critique.md`.
+
+## The checks, in order
+
+0. **Evidence.** Every width captured, no blank or half-loaded screenshot, content where the
+   filename says. If one fails, the answer is `recapture` and nothing else.
+1. **First screen.** Within five seconds: what is this, why does it matter, what do I do?
+2. **The idea.** Is the idea sentence visible on the page, in every section, and does it fail the
+   competitor test (would it work for the nearest competitor)?
+3. **The direction.** Was the dealt direction built, or did the build drift back to the layout the
+   model would have made anyway?
+4. **Substance.** Real pictures, full content, no screen that is mostly empty ground.
+5. **Truth.** No invented customers, quotes, numbers or logos. Sample content marked.
+6. **Floor.** The house rules in `../engine/RUN.md`, plus what screenshots show and code hides:
+   states (hover, focus, loading, empty, error), themed selection and focus rings, text that fits.
+
+## The four words
+
+The first line of the answer is exactly one of these. The word follows from the checks:
+
+- `recapture`: the evidence failed, not the page. Capture again, then a full review.
+- `rebuild`: the focal element or the direction itself is wrong. Re-derive it; patches will not do.
+- `fix`: an ordered list of material fixes, at most eight, most important first.
+- `ship`: nothing material remains.
+
+Then: `fixes` (when `fix`) and `keep`, one line naming what must not be diluted while fixing.
+Apply the fixes in one batch, run the gate again, and send the new screenshots back for a verdict
+on each fix: resolved, partial or unresolved. Two rounds at most. A partial or unresolved fix
+never becomes `ship`. Report the reviewer's word as it was given.

package/skills/design/references/modes.md

@@ -0,0 +1,51 @@
+# The four modes
+
+Adapted from impeccable by Paul Bakaus (Apache-2.0); rewritten and shortened. The mode names what
+the visitor's success looks like on this surface. Pick it from the surface, never the product: a
+developer tool's landing page is Persuade, a fashion house's docs are Read.
+
+## Persuade
+
+The visitor decides and acts. The design is what they judge.
+
+- The first screen makes the offer clear and shows **the action visitors came to take, working**: a
+  flight search, open appointment slots, add to cart. A button that points somewhere else is not it.
+- The subject's world carries the page; it is never painted over it as a poster with no working parts.
+- Refuse both ends: the poster, and the stock product page (headline, subline, button, a row of
+  equal cards; or the split hero with a badge row under it).
+
+## Experience
+
+The visitor is inside the work: portfolio, gallery, showcase. The work leads from the first
+viewport and the interface recedes. Same page run as Persuade.
+
+## Operate
+
+The visitor completes a task. Someone who uses tools like this should know where everything is
+before they notice the style.
+
+- The direction lends four things only: **type, palette, density and one signature move** (service
+  health drawn as a transit map, a schedule in a timetable's column rhythm). Never the layout, the
+  navigation model or the controls.
+- Every control is the standard one the visitor already knows. No costume of a terminal, an
+  instrument bezel or ledger paper.
+- Colour does real jobs: a committed shell, state colours, data series, selection. A grey screen
+  with one accent is the category default without its polish.
+- Realistic data with units and one state worth seeing (an alert, a degraded service, an empty
+  filter). Never grey placeholder bars.
+- The bar is the cleanest product in its category; the signature move adds to that, never replaces it.
+
+The run, rules and checks for these screens: `../engine/references/app-screens.md`
+(`draw.mjs --app`, `inspect.mjs --app`).
+
+## Read
+
+The visitor understands something: docs, guide, article, changelog.
+
+- The style owns **the frame**: masthead, rail, ground, title and section openers, how code and
+  tables are set. That is where palette, type and the signature move commit fully.
+- The reading column stays calm: a reading face, real contrast, about 60–75 characters at about
+  16px. No monospace prose. Nothing performs behind the text.
+- The style never supplies the reading order or replaces the navigation with something to learn.
+- Check: can a reader tell where they are, where to go next, and read comfortably? Cover the name:
+  could this be any other product's docs? Then the frame has not taken the style yet.

package/skills/expo/SKILL.md

@@ -8,10 +8,9 @@ origin: risco
 
 # Expo & EAS: shipping React Native
 
-**Hand-off — the app vs its motion.** This skill owns the Expo platform: router, config plugins, EAS,
-native modules, store builds. **Animation and gestures** — Reanimated worklets, the UI runtime,
-sheets, screen transitions, press feedback, haptics, motion that stutters on a real device — are
-`../motion-craft/SKILL.md`'s.
+**Scope.** This skill owns the Expo platform: router, config plugins, EAS, native modules, store
+builds. Animation and gestures (Reanimated worklets, sheets, press feedback, haptics) follow
+`../react-native/SKILL.md`. Visual design of web pages and screens is `../design/SKILL.md`'s.
 
 
 ## What this skill owns

package/skills/marketing/references/landing-copy.md

@@ -1,6 +1,6 @@
 # Landing Copy by Section
 
-The words for every landing section, mapped 1:1 to the `design` skill's section anatomy (`../../design/references/landing-anatomy-and-cro.md`). `design` owns the visual treatment and layout; this file owns the copy that goes inside each section. Each section has **one copy job**; cut any section whose job you can't name. Ground every line in the brand study (`brand-grounding.md`) and run the value prop through the canvas (`copy-frameworks.md`) first.
+The words for every landing section. `../../design/SKILL.md` owns the visual treatment, the layout and which sections exist (its argument step: one claim per section); this file owns the copy that goes inside each section. Each section has **one copy job**; cut any section whose job you can't name. Ground every line in the brand study (`brand-grounding.md`) and run the value prop through the canvas (`copy-frameworks.md`) first.
 
 ## Section map (copy job + framework)
 
@@ -187,5 +187,5 @@ Good — "Stop babysitting staging. Start free — no credit card."
 
 - `copy-frameworks.md` — the frameworks and headline formulas each section uses.
 - `brand-grounding.md` — the value prop, proof, and voice every line is grounded in.
-- `../../design/references/landing-anatomy-and-cro.md` — the visual anatomy these words fill.
+- `../../design/SKILL.md` — the page these words fill; write the copy deck before its markup.
 - `campaigns-and-channels.md` — driving traffic to this page.

package/skills/react/SKILL.md

@@ -10,8 +10,8 @@ origin: risco
 
 **Hand-off — picking dependencies.** Which library to reach for (UI primitives, command menus,
 toasts, OTP inputs, charts, virtualization, drag and drop, state, styling, theming) is
-`../ui-engineering/SKILL.md`'s — build vs adopt is decided there, before hand-rolling a component. Animating what you
-install is `../motion-craft/SKILL.md`'s.
+`../ui-engineering/SKILL.md`'s — build vs adopt is decided there, before hand-rolling a component. The look of a page
+or screen, and its motion layer, is `../design/SKILL.md`'s.
 
 
 > Build or review a fast, typed, correctly-architected **client-side** React single-page app bundled by Vite. No server runtime, no RSC tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is `../nextjs/SKILL.md`.

package/skills/react-native/SKILL.md

@@ -8,9 +8,9 @@ origin: risco
 
 # React Native (app code)
 
-**Hand-off — the app vs its motion.** Animation and gestures in a React Native app — Reanimated
-worklets on the UI runtime, gesture handoff, sheets, press feedback, haptics — are
-`../motion-craft/SKILL.md`'s, whose guidance is platform-agnostic and applies to bare React Native as well as Expo.
+**Scope.** App code, including animation and gestures (Reanimated worklets on the UI runtime, gesture
+handoff, sheets, press feedback, haptics), in bare React Native and in Expo. Visual design of web
+pages and screens is `../design/SKILL.md`'s.
 
 
 You write the code that runs *inside* the app: render, navigate, animate, list, persist, and author native modules. Mobile is split across two skills by **verb** — run the verb test before doing anything:

package/skills/scroll-film/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: scroll-film
+description: "Use when a page's hero is a pre-rendered camera flight the visitor scrubs by scrolling, Apple-style: AI clips chained frame to frame so seams never pop, encoded for seeking, mounted with an engine that holds up on phones. NOT scroll reveals or pinning (that is `design`), NOT a finished MP4 (that is `ai-media`)."
+tags: [scroll-scrub, scroll-video, scrollytelling, landing-hero, image-to-video, camera-flight, seamless-video]
+recommends: [ai-media, fal, replicate-images, landing-copy, design, performance]
+profiles: [full]
+origin: risco
+---
+
+# scroll-film — the camera moves, the scroll is the playhead
+
+The page plays nothing. It holds a chain of pre-rendered clips and maps the scroll position to
+their playhead, so the visitor flies through scenes — outside a building, inside it, on to the
+next — without a cut. Three parts must be right, and each fails in its own way: the **chain**
+(seams), the **encode** (seeking) and the **page** (phones). This skill owns all three.
+
+**Not this skill — delegate:**
+- Scroll-linked reveals, parallax, pinned sections, a horizontal pan, with no video → `../design/SKILL.md`.
+- A finished MP4 with voice and music → `../ai-media/SKILL.md`.
+- The call to the model endpoint (queue, webhooks, cost per call) → `../fal/SKILL.md` or `../replicate/SKILL.md`.
+- The scene stills themselves → `../replicate-images/SKILL.md`.
+- The words over the film → `../landing-copy/SKILL.md`. A video rendered from code → `../remotion-video/SKILL.md`.
+
+## 1. The gate: nothing renders before the user agrees to a number
+
+A chain is many clips, each one slow and billed. Interview, price it, then wait for a yes.
+
+1. **Subject.** Ask it as an open question: what the world is about, in a sentence. A menu of
+   industries decides their business for them.
+2. **Scenes.** 4 to 7, in the order the camera visits them, proposed from their own value chain and
+   edited by them. The last one carries the call to action.
+3. **Look.** One art direction, written once as a style preamble and pasted unchanged into every
+   still prompt. Identical text is what makes separate renders read as one world.
+4. **Camera feel.** Always ask. It picks the chain shape (section 3).
+5. **Phones.** Always ask. A real phone version is a second chain (section 6) and doubles the video bill.
+6. **Brand.** 4 to 6 hex colours, a name, a tone. The page background is the scene background.
+
+Then the bill:
+
+| | Forward take (A) | Dive and hop (B) |
+| --- | --- | --- |
+| Video clips, desktop only | N | 2N − 1 |
+| Video clips, with the phone chain | 2N | 4N − 2 |
+
+Estimate = clips × seconds per clip × today's price per second, plus about 20% for re-rolls, plus N
+stills. Read the price from the provider at build time; it moves (reading cost per call →
+`../fal/SKILL.md`). State the total against the balance and wait for the yes. When money is tight,
+offer a previz pass: the whole chain on the **same** model at its lowest resolution, approve the
+journey, then render the finals.
+
+## 2. The model must continue a shot, not just start one
+
+A seam holds only if the model starts a clip on an exact frame you hand it. That capability, not
+quality or price, qualifies a model.
+
+- Every clip needs a **start-frame** input. Hops (shape B) also need an **end-frame** input. Field
+  names vary by endpoint (`image_url`, `start_image`, `first_frame`; `end_image_url`,
+  `tail_image_url`, `last_frame`): read the input schema before batching. Model landscape →
+  `../ai-media/SKILL.md`.
+- A **reference-image** input does not qualify. It steers the style; frame 0 is still a new
+  render, and the seam pops.
+- **Probe once before the batch**, with one cheap clip from a real still prepared at the clip's
+  aspect (16:9, or 9:16 for phones). Frame 0 must match the still and the bill must match the
+  advertised price. For hop duty, add an end frame from another still: the last frame must land on
+  that composition. A near miss is normal; the engine's dissolve covers it. Commands →
+  `references/chain.md`.
+- **One model for the whole chain.** Each model has its own grain, colour and motion; a swap
+  mid-chain keeps positions continuous and still pops. The one exception is a single clip a content
+  filter keeps blocking (`references/chain.md`).
+
+## 3. Pick the chain shape from the camera feel
+
+| The user says | Shape | Clip k starts on | Clip k ends on | Fits |
+| --- | --- | --- | --- | --- |
+| "one continuous walkthrough", "one fixed angle gliding over it" | **A — forward take** | leg k−1's real last frame (leg 0: the first still) | nothing — no end frame | photoreal, interiors, product, real estate |
+| "fly from one island to the next" | **B — dive and hop** | dive: its still. hop: dive k's real last frame | hop: dive k+1's real first frame | miniature, diorama, map-like worlds |
+
+- A renders one leg at a time, because each needs the previous one's last frame. B renders every
+  dive in parallel, then every hop.
+- Never give an A leg a wide establishing shot as its end frame. The camera pulls back to meet it,
+  and the take reverses.
+- **The velocity rule.** Inside one clip the camera is free: orbit, rise, push in and ease back.
+  Across a seam it never reverses. Position matches, the motion flips, and it reads as a rewind,
+  in both scroll directions. So every leg ends by settling into a slow forward drift, and the next
+  one begins inside it. B reverses at every seam on purpose (pull out, hop, dive): charming over a
+  miniature map, a stutter in a realistic walkthrough. If the user picks B for a photoreal look, say
+  so before rendering.
+
+Prompt templates (still, leg, dive, hop), the camera-move table by concept, the fixed-angle clause
+and the batch loops → `references/chain.md`.
+
+## 4. The seam law: hand off pixels, not descriptions
+
+Every render redraws its scene a little differently. A hop that ends on the *original still* of
+scene 3 meets a dive that starts on *its own render* of scene 3: two pictures of one place, and the
+seam pops. So both ends of every clip come from the neighbours' actual renders.
+
+```bash
+# The true last frame: -update 1 overwrites per decoded frame, so the final one is what stays.
+ffmpeg -v error -y -sseof -1 -i leg_02.mp4 -update 1 -q:v 2 leg_02_last.png
+ffmpeg -v error -y -i dive_03.mp4 -frames:v 1 -q:v 2 dive_03_first.png
+```
+
+A plain `-sseof -0.15 -frames:v 1` stops a few frames short of the end: 15 dB PSNR from the real
+last frame on a 24 fps test clip. The engine parks the outgoing clip on its real last frame, so a
+handoff from the earlier one starts the seam already off.
+
+- Look at each last frame before chaining the next clip. In A, one bad handoff poisons every leg
+  after it: re-roll that leg.
+- The engine dissolves over a tenth of a viewport at each seam. That hides an end frame that landed
+  close. It cannot hide a different picture.
+
+## 5. Encode for seeking, not for playback
+
+Scrubbing seeks on every frame, and each seek decodes every frame since the last keyframe. The
+keyframe interval sets how smooth the scrub feels.
+
+```bash
+# Desktop: native resolution (never upscale), a keyframe every 8 frames, no audio, index first.
+ffmpeg -i leg_01.mp4 -an -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p \
+  -g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart assets/vid/shot-01.mp4
+# Phone: 720 wide, a keyframe every 4 frames; a phone decoder pays more per frame.
+ffmpeg -i leg_01_portrait.mp4 -an -vf scale=720:-2 -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p \
+  -g 4 -keyint_min 4 -sc_threshold 0 -movflags +faststart assets/vid/shot-01-m.mp4
+# Poster: the clip's first frame. It is the LCP image and the reduced-motion fallback.
+ffmpeg -v error -i assets/vid/shot-01.mp4 -frames:v 1 -c:v libwebp -quality 82 assets/shot-01.webp
+```
+
+One recipe for every clip in the chain. All-intra (`-g 1`) is the last resort for a low-end phone
+that still stutters, at about three times the size.
+
+## 6. Phones get their own chain, not a crop
+
+A 16:9 film on a portrait phone shows its middle quarter. When the user asked for phones, render
+the chain again at 9:16, frame-locked to its own renders. A landscape frame inside the portrait
+chain pops on both sides. Start images: each still composited onto a 1080×1920 canvas in the page
+background colour. The encodes are the `-m.mp4` files above, and each portrait clip's first frame is
+its `posterMobile`.
+
+No budget for it: the engine crops the landscape film with `object-fit: cover`, steered by
+`--film-focus`. Tell the user this is a stopgap. Never ship it as "the mobile version".
+
+## 7. Mount the page
+
+Copy `assets/scrub-engine.js` and `assets/page-template.html` into the project. The template is a
+working page: its copy is real HTML that reads without JavaScript, and the script moves it onto the
+film once the engine mounts.
+
+```js
+const film = ScrollFilm.mount(document.getElementById('film'), {
+  shots: [
+    { section: 0, src: 'assets/vid/shot-01.mp4', srcMobile: 'assets/vid/shot-01-m.mp4',
+      poster: 'assets/shot-01.webp', posterMobile: 'assets/shot-01-m.webp', length: 1.4, hold: 0.4 },
+    { section: 0, src: 'assets/vid/hop-01.mp4', poster: 'assets/hop-01.webp', length: 0.9 },
+    // one entry per clip, in chain order
+  ],
+  onChange: ({ section, sectionProgress }) => { /* fade the copy block for `section` */ },
+});
+```
+
+What the engine does, and the failure each part prevents:
+
+- **Loads each clip as a Blob.** On a host that ignores byte-range requests, a streamed `<video>`
+  reports `seekable` as [0, 0] and every seek lands on frame 0. A Blob is always seekable.
+- **Keeps one seek in flight per clip.** Queued seeks are what freeze a phone on a fast flick.
+- **Keeps the poster up until a frame has painted**, and primes each clip with a muted play and
+  pause, again on the first touch. iOS paints nothing for a seeked video that never played.
+- **Picks phone sources at mount**, ignores height-only resizes on touch (the URL bar sliding), and
+  re-lays out on rotation.
+- **Reduced motion or Save-Data:** no video is fetched; posters dissolve with the scroll and the
+  copy still works.
+- **Fetches a clip once**, when the scroll comes within 1.5 viewports of it.
+- **`destroy()`** removes everything it added. Call it from the effect cleanup in React or Vue.
+
+`design` bans raw scroll listeners for animation. This one is passive and only requests a frame. If
+the page already owns a scroll source (ScrollTrigger, `useScroll`), pass `listen: false` and call
+`film.update()` from it. All options, the state object, theming, pacing and the Next.js and Vue
+wiring → `references/engine.md`.
+
+The film layer is `aria-hidden`; the meaning lives in the copy. Its words → `../landing-copy/SKILL.md`.
+Its type, colour and spacing → `../design/SKILL.md`.
+
+## 8. Verify before calling it done
+
+1. **The chain, by script.** Pass the clips in chain order:
+
+   ```bash
+   bash <skill-dir>/scripts/verify.sh --frames qa/seams \
+     assets/vid/shot-01.mp4 assets/vid/hop-01.mp4 assets/vid/shot-02.mp4
+   bash <skill-dir>/scripts/verify.sh --gop 4 --portrait \
+     assets/vid/shot-01-m.mp4 assets/vid/hop-01-m.mp4 assets/vid/shot-02-m.mp4
+   ```
+
+   It checks each clip's encode (H.264, yuv420p, no audio, index first, keyframe interval), that
+   the chain shares one size and frame rate, and scores every seam against the clips' own
+   frame-to-frame step. A fixed SSIM threshold cannot tell: on a soft landscape photo, a cut to a
+   different picture still scored 0.76 and a fresh render of the same scene 0.92. Measured against
+   the step (0.98 there), the frame-locked seam passed at 0.987 and both others were flagged. Open
+   every flagged pair in `qa/seams/` and judge by what you see: a wrong seam shows different objects.
+2. **In a browser.** Scroll slowly across each seam on desktop. Then emulate a phone at 4 to 6× CPU
+   throttle and flick fast. Turn reduced motion on: posters only. In the Network panel, the phone
+   gets the `-m.mp4` files and the desktop gets the masters.
+3. **On a real iPhone**, if phones shipped: the first scene shows at once and no scene goes blank.
+
+## Anti-patterns
+
+| Failure mode | Usually | Fix |
+| --- | --- | --- |
+| A visible pop at one seam | The hop's end frame was the original still, or came from `-sseof` a few frames early | Extract the true frames from the neighbouring renders (section 4) |
+| The camera seems to rewind at every seam | Velocity reverses across the seam: B in a realistic walkthrough, or an A leg given a wide end frame | Shape A with the settle-into-drift clauses and no end frame |
+| Stuck on the first frame in production, fine locally | The host ignores byte ranges | Load as Blob; keep it when porting the engine to a framework |
+| A phone freezes on a fast flick | A 1080p, 8-frame-GOP master on a phone decoder, plus queued seeks | `-m.mp4` encodes at GOP 4; keep one seek in flight |
+| Black scenes on iPhone until the first touch | The poster was hidden on `loadedmetadata`, or `muted`/`playsinline` lost in a port | Keep the poster until a frame paints; keep both attributes |
+| The film scrolls away instead of sticking | An ancestor has `overflow: hidden`, often `body { overflow-x: hidden }` | `overflow-x: clip` |
+| A cheaper model "just for the hops" | Each model renders its own grain and motion | One model for the chain; previz on the same model at low resolution |
+| A content filter blocks a harmless interior | Words like bed, pool, spa or wine in the prompt | Re-roll, neutral wording, then the remedies in `references/chain.md` |
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)