cinematic-scroll-skill 2.1.0

package/COMPATIBILITY.md

@@ -0,0 +1,244 @@
+# Platform Compatibility & Installation
+
+This document provides documented installation paths for each platform, with evidence included where terminal transcripts have been recorded.
+
+## Supported Platforms
+
+| Platform | Status | Install Method | Notes |
+|----------|--------|-----------------|-------|
+| Claude Desktop | ✅ Verified | Upload skill folder | Settings → Capabilities → Skills → Upload |
+| Cursor | ✅ Verified | Drop into `.cursor/skills/` | Auto-discovery, no reload required |
+| Hermes Agent | ✅ Verified | `git clone` to `~/.hermes/skills/` | Fully compatible; tested June 1, 2026 |
+| OpenClaw | ✅ Verified | `git clone` to `~/.openclaw/workspace/skills/` | Fully compatible; tested June 1, 2026 |
+| skills.sh | 🚀 Target | Registry submission | Primary distribution channel |
+
+---
+
+## Installation Instructions by Platform
+
+### Claude Desktop
+
+**Prerequisites:** Claude Desktop app (latest version)
+
+**Steps:**
+1. Download this repository as a ZIP file (or clone it)
+2. Open Claude Desktop → Settings → Capabilities → Skills
+3. Click **"Upload skill"**
+4. Drag the `cinematic-scroll-skill` folder into the upload dialog
+5. Confirm
+
+**Verification:**
+Open a new chat and try:
+```
+/describe a boutique hotel website using the Warm Scrapbook aesthetic with pinned chapters, 220vh pins, and title reveals via letter-spacing scrub
+```
+
+You should get back a multi-phase response (audit → storyboard → spec → build).
+
+---
+
+### Cursor
+
+**Prerequisites:** Cursor (latest version)
+
+**Steps:**
+1. Clone or download this repository to your local machine
+2. Locate your Cursor skills directory:
+   ```bash
+   # On macOS:
+   ~/.cursor/skills/
+
+   # On Linux:
+   ~/.cursor/skills/
+
+   # On Windows:
+   %APPDATA%\Cursor\skills\
+   ```
+3. Copy the entire `cinematic-scroll-skill` folder into `.cursor/skills/`
+4. Restart Cursor (or reload with Cmd+Shift+P → Reload Window)
+
+**Verification:**
+Open a new file in Cursor and try:
+```
+Generate a cinematic scroll site for a luxury real estate brand. Use the Symmetric Monument system. 5 chapters. References: David Chipperfield, minimalism, Italian countryside.
+```
+
+Cursor will auto-discover the skill and activate it.
+
+---
+
+---
+
+### Hermes Agent
+
+**Prerequisites:** Hermes Agent CLI (v0.15.1+)  
+**Install Hermes:** See [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com)
+
+**Installation (correct method):**
+```bash
+# Clone the full repository into Hermes skills directory
+git clone https://github.com/MustBeSimo/cinematic-scroll-skill ~/.hermes/skills/cinematic-scroll
+```
+
+**Verify installation:**
+```bash
+hermes chat
+# Type: /cinematic-scroll --help
+```
+
+**Usage (slash command syntax):**
+```bash
+hermes chat
+# Then in the chat prompt:
+/cinematic-scroll Build a minimalist architecture portfolio. Use Symmetric Monument system.
+```
+
+**Key findings:**
+- ✅ Full repository installs correctly via git clone
+- ✅ Skill manifest (SKILL.md) matches Hermes frontmatter spec
+- ✅ Skill is discoverable and enabled in skill list
+- ✅ Invocation via slash commands (`/cinematic-scroll`) per Hermes spec
+- ⚠️ Tested on Hermes v0.15.1 (2026-05-29) via Tailscale VPS
+
+**Integration:** Compatible with Hermes' skill system using standard YAML frontmatter + markdown format.
+
+---
+
+### OpenClaw
+
+**Prerequisites:** OpenClaw (latest version)  
+**Install OpenClaw:** See [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)
+
+**Installation (official Git method):**
+```bash
+openclaw skills install git:MustBeSimo/cinematic-scroll-skill@v0.1.2
+```
+
+**Or manual clone:**
+```bash
+git clone https://github.com/MustBeSimo/cinematic-scroll-skill ~/.openclaw/workspace/skills/cinematic-scroll-skill/
+```
+
+**Verify installation:**
+```bash
+ls -la ~/.openclaw/workspace/skills/cinematic-scroll-skill/
+# Should show: SKILL.md, examples/, templates/, references/, .git/
+```
+
+**Usage:**
+OpenClaw automatically discovers the skill from the workspace directory.
+
+**Key findings:**
+- ✅ Full repository installs correctly via git clone
+- ✅ SKILL.md (42KB) properly structured for OpenClaw agent contract
+- ✅ All reference files and examples included (43 commits)
+- ✅ MIT license verified
+- ✅ Skill discoverable and ready for invocation
+
+**Tested on:** OpenClaw (June 1, 2026)
+
+**Integration:** Compatible with OpenClaw's skill system using standard YAML frontmatter + markdown format, same as Hermes.
+
+---
+
+## Known Limitations
+
+### Platform-Specific
+
+| Issue | Platform | Workaround |
+|-------|----------|-----------|
+| Large file uploads may timeout | Claude Desktop | Use web version (claude.ai) or Cursor instead |
+| Asset paths require relative URLs | All | Ensure generated files use `./assets/` not `/assets/` |
+| Mode B requires Node.js 18+ | Hermes/OpenClaw | Update Node version or use Mode A (vanilla HTML) |
+| IMAGE-SPEC.md requires fal.ai key | All | Optional; use CSS-only visuals without it |
+
+### Feature Availability
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Mode A (vanilla HTML) | ✅ All platforms | Self-contained, no build required |
+| Mode B (Next.js template) | ✅ All platforms | Requires Node.js locally |
+| AI image generation | ⚠️ Opt-in | Requires fal.ai account and API key |
+| 7 visual systems | ✅ All platforms | See `references/film-archetypes.md` |
+| 5 live examples | ✅ Reference only | Cannot be directly modified via skill invocation |
+| Custom CSS-only render | ✅ All platforms | Default fallback if no images provided |
+
+---
+
+## Troubleshooting
+
+### "Skill not found" error
+
+**Hermes:**
+```bash
+# Clear the skill cache
+hermes skills clear-cache
+
+# Reinstall
+hermes skills install https://github.com/MustBeSimo/cinematic-scroll-skill
+```
+
+**OpenClaw:**
+```bash
+# Check Git connectivity
+git clone https://github.com/MustBeSimo/cinematic-scroll-skill /tmp/test-clone
+
+# Then reinstall
+openclaw skills install git:MustBeSimo/cinematic-scroll-skill@main
+```
+
+### "SKILL.md not found" error
+
+Ensure the skill folder includes all of these files:
+- `SKILL.md` ← main contract
+- `manifest.json` ← platform metadata
+- `README.md` ← user documentation
+- `references/` ← visual system library
+- `examples/` ← 5 live demo sites
+
+If any are missing, the platform will reject the skill.
+
+### Agent produces broken HTML
+
+This usually means `references/scroll-patterns.md` or `references/taste-guardrails.md` isn't accessible. Verify:
+```bash
+ls -la ./references/
+# Should show:
+# film-archetypes.md
+# scroll-patterns.md
+# taste-guardrails.md
+# performance-budget.md
+```
+
+### Generated images don't load
+
+This is normal if you haven't provided an `fal.ai` API key. The system falls back to CSS-only rendering. To use generated images:
+
+1. Get a key at [fal.ai](https://fal.ai)
+2. Set it in the agent environment: `FAL_KEY=your_key_here`
+3. Re-trigger the generation
+
+---
+
+## Version Compatibility
+
+| Skill version | Release | Notes |
+|---|---|---|
+| **2.0.0 (internal)** | Ongoing | Contract version; includes 5-phase pipeline, taste constraints, visual systems |
+| **v0.1.1 (public)** | 2026-06-01 | Initial open-source release; 5 live examples, all platforms supported |
+| **v0.1.2 (current)** | 2026-06-01 | Corrected README GSAP documentation and softened platform verification claims |
+| **v2.0.0 (legacy tag)** | N/A | Historical tag; do not use |
+
+**Current recommendation:** Use v0.1.2 for all new installations.
+
+---
+
+## What's Next
+
+After installation, see:
+- **`README.md`** for quickstart examples
+- **`examples/PROMPTS.md`** for 20+ copy-paste prompts
+- **`references/film-archetypes.md`** for visual system deep-dives
+- **`SKILL.md`** for the full agent contract (if you're integrating programmatically)
+
+For help, open an issue on [GitHub](https://github.com/MustBeSimo/cinematic-scroll-skill).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simone Leonelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MODELS.md

@@ -0,0 +1,92 @@
+# Image models — pick one, swap any time
+
+The skill ships with **`fal-ai/flux-2-pro`** as default. It's the best balance of editorial quality, photorealism, speed, and cost for this style of release page.
+
+**You only need to read this if you want to swap models.** The default works for 90% of projects.
+
+To swap: change `FAL_IMAGE_MODEL` in `.env.local`. **No code change needed** — the adapter in `lib/fal-models.ts` handles each model's different parameter names automatically.
+
+```bash
+# Example: switch to Nano Banana Pro for text-heavy chapter visuals
+FAL_IMAGE_MODEL="fal-ai/gemini-3-pro-image-preview"
+```
+
+Restart `npm run dev` after editing `.env.local`. Re-run `npm run generate` to regenerate chapter images with the new model.
+
+---
+
+## FLUX family — best for editorial, materials, atmospheric depth
+
+| Model ID | Cost/img | Speed | When to use |
+|---|---|---|---|
+| **`fal-ai/flux-2-pro`** | $0.06 | ~4s | **Default.** Editorial portraits, fabric, materials, classical compositions. |
+| `fal-ai/flux-2-max` | $0.08 | ~5s | Final hero renders when you want absolute max quality. |
+| `fal-ai/flux-2/turbo` | $0.02 | ~2s | Fast draft rounds — iterate on prompts cheaply. |
+| `fal-ai/flux-pro/v1.1/ultra` | $0.06 | ~10s | Previous-gen 4MP alternative. Slower than FLUX.2 Pro at same cost. |
+| `fal-ai/flux-pro/v1.1` | $0.05 | ~4.5s | High-volume batches where cost matters. |
+
+**Avoid `fal-ai/flux/dev`** — it's licensed for non-commercial use only.
+
+---
+
+## Google "Nano Banana" family — best for text-in-image, conversational editing
+
+(Yes, "Nano Banana" is the real Google/fal.ai nickname.)
+
+| Model ID | Nickname | Cost/img | Speed | When to use |
+|---|---|---|---|---|
+| `fal-ai/gemini-3-pro-image-preview` | Nano Banana Pro | $0.15 | ~8s | Complex prompts, baked-in typography, web-search grounding. |
+| `fal-ai/gemini-3.1-flash-image-preview` | Nano Banana 2 | $0.07 | ~2s | Newest Flash — fast + accurate text in image. |
+| `fal-ai/gemini-2.5-flash-image` | Nano Banana | $0.04 | ~2s | Cheapest Google option. |
+
+---
+
+## Imagen
+
+| Model ID | Cost/img | Speed | When to use |
+|---|---|---|---|
+| `fal-ai/imagen3` | $0.04 | ~3s | Solid photorealism at low cost. |
+
+---
+
+## When to use FLUX vs Nano Banana
+
+| Need | Use |
+|---|---|
+| Editorial depth, painterly atmosphere, material texture | **FLUX.2 Pro** (default) |
+| Text/labels baked into the image | **Nano Banana Pro** |
+| Iterative editing ("darken the background, add fog") | **Nano Banana 2** |
+| Fast cheap drafts to validate prompts | **FLUX.2 Turbo** |
+| Lowest cost per image | **Gemini 2.5 Flash** or **Imagen 3** |
+| Real-world references via web search | **Nano Banana Pro** |
+
+---
+
+## Cost for a full 8-chapter release page
+
+| Model | 8 images cost |
+|---|---|
+| FLUX.2 Pro (default) | ~$0.48 |
+| FLUX.2 Turbo | ~$0.16 |
+| Nano Banana 2 | ~$0.56 |
+| Nano Banana Pro | ~$1.20 |
+| Gemini 2.5 Flash | ~$0.32 |
+| Imagen 3 | ~$0.32 |
+
+You only pay when you actually run `npm run generate`. The demo-mode page (CSS-only chapter visuals) costs $0.
+
+---
+
+## Per-model parameter differences (for the curious)
+
+You don't need to know this — the adapter handles it. But if you're debugging:
+
+| Param | FLUX.2 | Nano Banana | Imagen 3 |
+|---|---|---|---|
+| Orientation | `image_size: 'landscape_16_9'` | `aspect_ratio: '16:9'` | `aspect_ratio: '16:9'` |
+| Multiple images | not supported (always 1) | `num_images: 1..4` | `num_images: 1..4` |
+| Negative prompt | not supported (inline in prompt) | not supported (inline in prompt) | not supported |
+| Resolution | fixed 4MP | `resolution: '1K' \| '2K' \| '4K'` | fixed |
+| Output formats | `'jpeg' \| 'png'` | `'jpeg' \| 'png' \| 'webp'` | `'png'` |
+
+Source: `lib/fal-models.ts` — single source of truth, verified against fal.ai docs.

package/README.md

@@ -0,0 +1,250 @@
+# Cinematic Scroll
+
+[![Install via skills.sh](https://img.shields.io/badge/Install%20via-skills.sh-blue?style=for-the-badge)](https://skills.sh/search?q=cinematic-scroll)
+
+<a href="https://mustbesimo.github.io/cinematic-scroll-skill/">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark_v2.png">
+    <source media="(prefers-color-scheme: light)" srcset="assets/banner-light_v2.png">
+    <img src="assets/banner-dark_v2.png" alt="Cinematic Scroll — a free Agent Skill for scroll-driven websites. Two finishes: Petroleum Editorial (dark) and Swiss Museum (light)." width="100%">
+  </picture>
+</a>
+
+👉 **[Visit the live landing page](https://mustbesimo.github.io/cinematic-scroll-skill/)** — it adapts to your GitHub theme. Dark mode → **Petroleum Editorial**. Light mode → **Swiss Museum**. Toggle either finish on the site.
+
+<a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/renaissance/">
+  <img src="assets/scroll-demo.gif" alt="The scroll grammar in motion — pinned chapters, multi-depth parallax, and a tracking index rail" width="100%">
+</a>
+
+<sub>↑ The <b>motion</b> is the skill — pinned chapters, multi-depth parallax, mask/stagger title reveals, a tracking index rail. The <b>look</b> is whatever you ask for. This clip happens to be a Renaissance editorial; the same grammar drives a brutalist drop, a neon Gen-Z launch, a noir game page, or your brand. <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/renaissance/">Scroll it live →</a></sub>
+
+**A free, open-source Agent Skill (Claude · Cursor · Hermes · OpenClaw) for building cinematic, scroll-driven websites from a brief to deployment.** Describe the aesthetic — palette, mood, references — and get a visual system, motion storyboard, pinned chapters, multi-depth parallax, 3D tilt, and full release pages art-directed to match. The cinematic *motion* is the constant; the *look* is yours.
+
+> **License:** MIT — free for any use, personal or commercial.  
+> **Status:** Developed from working demos and production-informed patterns, then released as open source. Provided as-is; no active maintenance commitment. Issues and PRs welcome.
+
+Built by [Simone Leonelli](https://w230.net) · [simone@w230.net](mailto:simone@w230.net)
+
+---
+
+## Get started — two paths
+
+Pick how you want to build:
+
+**Mode A: Single scroll section** — one runnable `.html` file, no build step, no keys. Perfect for a hero chapter or one-off section.  
+**Mode B: Full release site** — complete Next.js project, tested templates, optional AI image generation pipeline. Best for product launches and multi-chapter stories.
+
+---
+
+## Install
+
+Pick whichever channel fits your client. All four install the same skill.
+
+### Claude Code — plugin marketplace (recommended for Claude Code)
+```bash
+/plugin marketplace add MustBeSimo/cinematic-scroll-skill
+/plugin install cinematic-scroll@mustbesimo
+```
+Installs as a namespaced plugin and stays updatable with `/plugin marketplace update mustbesimo`.
+
+### Any client — npx installer
+```bash
+npx cinematic-scroll-skill          # copies the skill into ~/.claude/skills/cinematic-scroll
+npx cinematic-scroll-skill --dir .cursor/skills   # or a custom skills directory
+```
+
+### Any client — git clone
+```bash
+git clone https://github.com/MustBeSimo/cinematic-scroll-skill ~/.claude/skills/cinematic-scroll
+```
+
+### Registries
+```bash
+npx skills add MustBeSimo/cinematic-scroll-skill   # skills.sh
+```
+Also listed on **[agentskills.io](https://agentskills.io)** (search "cinematic-scroll").
+
+### Platform-specific
+Paths vary by client — see [`COMPATIBILITY.md`](./COMPATIBILITY.md) for step-by-step instructions:
+- **Claude Desktop** — Settings → Capabilities → Skills → Upload
+- **Cursor** — drop into `.cursor/skills/` (or `npx cinematic-scroll-skill --dir .cursor/skills`)
+- **Hermes Agent** — `git clone` to `~/.hermes/skills/`
+- **OpenClaw** — `openclaw skills install git:MustBeSimo/cinematic-scroll-skill@v2.0.0`
+
+### Quick start
+After installing, describe what you want to build in chat — see [`examples/PROMPTS.md`](./examples/PROMPTS.md) for 20+ copy-paste examples across aesthetic worlds.
+
+---
+
+## Live examples — five scrollable worlds, one grammar
+
+Same engine, deliberately clashing aesthetics — five **single, build-free `index.html` files** (GitHub-Pages-native) running the skill's **Mode A** grammar: vanilla JS on `requestAnimationFrame` with optional GSAP/ScrollTrigger enhancements. All five retain a dependency-free core; Noir, Luxe, and Pop progressively enhance one showcase beat with deferred GSAP + ScrollTrigger (loaded from CDN with vanilla fallback). All five render fully with **zero image files** (CSS-only placeholders that upgrade when you add stills). Proof the look is a variable, not a default.
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/renaissance/"><img src="assets/scroll-demo.gif" alt="Renaissance editorial example — warm classical scroll loop" width="100%"></a>
+    </td>
+    <td width="50%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/studio/"><img src="assets/studio-scroll-demo_v2.gif" alt="Brutalist creative-director example — monochrome scroll loop with 3D motion" width="100%"></a>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/renaissance/"><b>① Renaissance editorial →</b></a><br>
+      <sub>Warm, classical, ornate. Oil-painting heroes, gold↔oxblood morph, serif display. Mirrors the production edition at <a href="https://www.w230.net/reinassence">w230.net/reinassence</a>. <a href="./examples/renaissance/">Source</a>.</sub>
+    </td>
+    <td width="50%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/studio/"><b>② Brutalist creative-director →</b></a><br>
+      <sub>Cold, modern, severe. Giant grotesk type, monochrome + electric-blue accent, grey↔ink morph, scroll-driven 3D camera. A fictional CD portfolio in the spirit of spare Swiss-editorial sites. <a href="./examples/studio/">Source</a>.</sub>
+    </td>
+  </tr>
+</table>
+
+<table>
+  <tr>
+    <td width="33%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/noir/"><img src="assets/noir-scroll-demo.gif" alt="Sci-fi noir example — teal fog and crimson edge-light loop" width="100%"></a>
+    </td>
+    <td width="33%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/luxe/"><img src="assets/luxe-scroll-demo.gif" alt="Quiet luxury example — ivory and sand still-life loop" width="100%"></a>
+    </td>
+    <td width="33%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/pop/"><img src="assets/pop-scroll-demo.gif" alt="Gen-Z pop example — neon gradient and glassy UI loop" width="100%"></a>
+    </td>
+  </tr>
+  <tr>
+    <td width="33%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/noir/"><b>③ Sci-fi noir →</b></a><br>
+      <sub>Studio <b>VANTASCOPE</b>, title <b>HOLLOW STAR</b>. Near-black void, deep-teal fog, crimson edge-light, film grain. 4 chapters, scroll-linked 3D camera, vertical mask-wipe title reveals. <a href="./examples/noir/">Source</a>.</sub>
+    </td>
+    <td width="33%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/luxe/"><b>④ Quiet luxury →</b></a><br>
+      <sub>Maison <b>SOLENNE</b>. Warm ivory + sand, muted cognac accent, thin-serif display, vast negative space. 220vh pins, ~3% background drift, letter-spacing-scrub reveals. <a href="./examples/luxe/">Source</a>.</sub>
+    </td>
+    <td width="33%" valign="top">
+      <a href="https://mustbesimo.github.io/cinematic-scroll-skill/examples/pop/"><b>⑤ Gen-Z pop →</b></a><br>
+      <sub>App <b>BLOOM</b>. Candy-pink + electric-lime gradients, bold rounded type, fast parallax, floating CSS phone-UI. <a href="./examples/pop/">Source</a>.</sub>
+    </td>
+  </tr>
+</table>
+
+**Same motion grammar; any aesthetic.** These five show different visual directions the skill can art-direct — change the copy, palette, and references, and the same engine produces any world you describe. This isn't an exhaustive list of *styles* (the styling is infinite). It's a proof that the cinematic *motion* is the constant, and the *look* is whatever you ask for.
+
+### Aesthetic directions
+
+Beyond these five live examples, the skill can art-direct itself into any visual world. Below are six concept *style directions* to illustrate the range:
+
+<table>
+  <tr>
+    <td width="33%"><img src="assets/01_v2.png" alt="Brutalist editorial website interface — 'BUILD. BREAK. BIND.' oversized headline over exposed grid lines and raw concrete"><br><sub><b>Brutalist</b> — stark, grid-driven</sub></td>
+    <td width="33%"><img src="assets/02_v2.png" alt="Quiet luxury website interface — 'MOMENTS OF CALM' serif hero over warm dunes with restrained gold"><br><sub><b>Quiet luxury</b> — earth palette, space</sub></td>
+    <td width="33%"><img src="assets/03_v2.png" alt="Gen-Z pop website interface — 'POP WORLD ENERGY' headline on neon gradient with glassy cards"><br><sub><b>Pop</b> — neon, playful</sub></td>
+  </tr>
+  <tr>
+    <td width="33%"><img src="assets/04_v2.png" alt="Sci-fi noir website interface — 'NEON PROTOCOL' headline with lone figure in neon rain-lit city"><br><sub><b>Sci-fi noir</b> — teal, edge-lit</sub></td>
+    <td width="33%"><img src="assets/05_v2.png" alt="Organic wellness website interface — 'NATURALLY ROOTED' serif hero over soft watercolour botanical"><br><sub><b>Wellness</b> — blush, painterly</sub></td>
+    <td width="33%"><img src="assets/06_v2.png" alt="Retro archive website interface — 'DIGITAL ARCHIVE' headline over amber scan-lines and terminals"><br><sub><b>Retro archive</b> — amber, analogue</sub></td>
+  </tr>
+</table>
+
+<sub>Six style directions generated by the skill's own [fal.ai](https://fal.ai) pipeline (or bring your own images / go CSS-only at $0). These are concept stills that show possible aesthetic ranges — the five live examples above are the scrollable proofs.</sub>
+
+### Running locally
+
+```bash
+python3 -m http.server 8099   # then open /examples/renaissance/ · /studio/ · /noir/ · /luxe/ · /pop/
+```
+
+**Under the motion, every chapter ships with:**
+
+| | |
+|---|---|
+| **Cinematic depth** | 5–7 parallax layers per chapter, perspective camera, dolly-back transitions |
+| **Editorial type** | Oversized titles with word-stagger / clip-path mask / letter-spacing-scrub reveals |
+| **Atmosphere morphs** | Backgrounds crossfade between chapter color-worlds as you scroll |
+| **Image pipeline** | Optional: fal.ai-generated heroes (FLUX.2, Nano Banana, Imagen); required: bring your own images or render CSS-only visuals. Generated assets remain subject to your input rights and model-provider terms — review output before commercial deployment. |
+| **Bulletproof basics** | Reduced-motion fallback, iOS video safety, mobile-stacked layout, transform/opacity-only core hot paths; optional GSAP showcase enhancements in selected examples; no WebGL required. Validate performance on target devices before production. |
+
+---
+
+## Quickstart
+
+### Mode A — instant scroll section
+> *"Use cinematic-scroll to build a self-contained HTML pinned hero chapter for [YOUR BRAND]. Include a progress HUD."*
+
+You get one runnable `.html` file. Open it. Done.
+
+### Mode B — full release site
+> *"Use cinematic-scroll to scaffold a complete Shopify-Editions-tier release page for [YOUR PRODUCT IN ONE LINE]. Demo mode first — do not require my fal.ai key. Copy all bundled templates verbatim. 8 chapters. Finish with the exact commands to run."*
+
+Then, in the scaffolded project:
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:3000` — a full 8-chapter cinematic page, CSS-only visuals, **zero AI setup**.
+
+Want real generated chapter art? Add your own [fal.ai](https://fal.ai) key and run the command below. Generation cost varies by model and resolution — see `MODELS.md` and current fal.ai pricing before running a batch.
+
+```bash
+npm run setup        # interactive key wizard → writes .env.local
+npm run generate     # generates all chapter heroes into public/generated/
+```
+
+Full walkthrough: [`examples/GETTING_STARTED.md`](./examples/GETTING_STARTED.md). Model menu + costs: [`MODELS.md`](./MODELS.md).
+
+---
+
+## What's in the box
+
+```
+cinematic-scroll-skill/
+├── SKILL.md                  # the agent contract (Mode A + Mode B). For Claude, not humans.
+├── README.md                 # you are here
+├── COMPATIBILITY.md          # platform installation & verification (Claude, Cursor, Hermes, OpenClaw)
+├── LICENSE                   # MIT
+├── manifest.json             # skill metadata (free)
+├── MODELS.md                 # fal.ai model menu, costs, when-to-use
+├── examples/
+│   ├── PROMPTS.md            # 20+ trigger prompts across aesthetic worlds
+│   ├── GETTING_STARTED.md    # fal.ai setup, troubleshooting, queue+webhook
+│   ├── KNOWN_ISSUES.md       # QA log of real failure modes + fixes
+│   ├── renaissance/          # Mode A example — warm classical editorial
+│   ├── studio/               # Mode A example — brutalist creative-director portfolio
+│   ├── noir/                 # Mode A example — sci-fi noir (VANTASCOPE)
+│   ├── luxe/                 # Mode A example — quiet luxury (Maison Solenne)
+│   └── pop/                  # Mode A example — Gen-Z pop (BLOOM)
+└── templates/nextjs/         # tested, copy-verbatim Next.js App Router project
+    ├── app/ (+ api/fal/*, generate-edition-asset)
+    ├── components/ (ChapterScene, ChapterDemoVisual, EditionsPage, SmoothScrollProvider)
+    ├── lib/ (editions-manifest, fal-*, prompt-contract, use-lenis, use-device)
+    ├── scripts/ (setup.mjs, generate-chapter-assets.mjs)
+    └── package.json, tailwind.config.ts, tsconfig.json, …
+```
+
+## Peer dependencies (in the consuming app)
+
+```bash
+npm install choreo-3d framer-motion gsap @gsap/react lenis @fal-ai/client @fal-ai/server-proxy
+```
+
+The motion primitives target the [`choreo-3d`](https://www.npmjs.com/package/choreo-3d) package, with a built-in **vanilla fallback** (sticky + IntersectionObserver + rAF) for sandboxes where npm packages can't be installed — identical math, same keyframes.
+
+**On GSAP:** as of the 2025 Webflow acquisition, [GSAP is 100% free](https://gsap.com/) — every former Club plugin included (SplitText, ScrollSmoother, ScrollTrigger, MorphSVG…), commercial use too. The Next.js build (Mode B) uses **ScrollTrigger + SplitText** for pinning and title reveals; the standalone demos retain a **vanilla rAF core** with optional deferred GSAP enhancements in selected showcase beats (loaded from CDN with vanilla fallback). This means Mode A files run from `file://` with zero build, and gracefully fall back to CSS-only rendering if the CDN is unavailable. For low-level GSAP help, pair this with the official [`greensock/gsap-skills`](https://github.com/greensock/gsap-skills) — that skill teaches the GSAP API; this one teaches the cinematic system on top.
+
+---
+
+## Originality & legal
+
+The reference direction is Shopify Editions, used **only** as an art-direction benchmark — chaptered release storytelling. The skill never copies Shopify's assets, logos, copy, source, or exact compositions, and never bakes readable UI text into generated images or imitates a named living artist. Generated assets may be used subject to fal.ai, model-provider and input-rights terms. Review output before commercial deployment.
+
+## License
+
+MIT © 2026 Simone Leonelli — see [LICENSE](./LICENSE).
+
+Built something with it? I'd genuinely love to see it: **simone@w230.net**
+</content>
+</invoke>