@babylonjs-toolkit/agent 1.1.0

package/skills/bt-atlas/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: bt-atlas
+description: "The Babylon Toolkit Texture Atlas Skill generates texture atlas skin variations for a UV-mapped 3D model that stay strictly inside the UV islands, so they are drop-in swaps for the same geometry. Use whenever the user wants new skins / texture variants (different colors, faces, materials, camo, liveries, etc.) from a base color texture and its UV layout. Works for any model — not specific to any one asset."
+---
+
+# Invocation
+
+```
+/bt-atlas <base-texture> <uv-layout> <variation-brief>
+```
+- **`<base-texture>`** — the existing skin; defines overall look & feel.
+- **`<uv-layout>`** — the wireframe/island map for the same texture.
+- **`<variation-brief>`** — how to vary the texture while staying within the UV islands.
+- If any input is missing, ask for it before starting. Never guess a file path or URL.
+
+Example:
+```
+/bt-atlas → base_texture.png → uv_layout.png → "Change clothing + face, keep the horse hide and the eye island"
+```
+
+---
+
+# Generate Texture Atlas (UV-safe atlas variations)
+
+Create N variations of a model's base color texture atlas using AI image
+generation, guaranteeing every output keeps the **exact same UV layout** as the
+base so it can be swapped onto the same model geometry/UVs without re-mapping.
+
+Use the user's message after the skill name as the `arguments`.
+
+The core trick: AI image editors will not respect UV-island edges on their own —
+they bleed paint into the empty/padding areas and sometimes shift islands. So we
+**never ship the raw AI output**. We generate, then **mask-and-composite**: keep
+only the pixels inside the UV-island footprint from the AI image and take
+everything else verbatim from the base texture.
+
+This skill is general purpose. It makes no assumption about where islands sit in
+the atlas (top/bottom/left/right) — the mask is derived automatically from the
+UV layout image.
+
+## Inputs you need from the user (ask if missing)
+1. **Base color texture** (PNG) — the existing skin; defines overall look & feel.
+   A local file path or an `http(s)://` URL both work.
+2. **UV layout image** (PNG) — the wireframe/island map for the same texture
+   (white island outlines on dark background is the typical export). If only a
+   combined "all submeshes" layout exists, that works too. A local file path or
+   an `http(s)://` URL both work.
+3. **What to vary vs preserve** — e.g. "change clothing + face, keep the horse
+   hide and the eye island". Inspect the base + layout yourself to identify the
+   islands; confirm ambiguous ones with the user.
+4. **Number of variations and a brief per-variation description** (the creative
+   direction: skin tones, faces, color schemes, materials, etc.).
+5. **Output directory** — default to a `SkinVariations/` folder next to the base
+   texture if not specified.
+
+If the base texture or UV layout isn't supplied at all, ask for it — don't
+guess or substitute a placeholder. If it IS supplied (local path or URL) but is
+wrong (path doesn't exist, URL isn't reachable / doesn't return an image, or
+the content isn't actually an image), STOP before generating anything — do not
+guess, substitute a different file, or continue with a partial setup. Tell the
+user exactly which input failed and why, and ask for a corrected path/URL.
+
+## Tools
+- **Image generation**: use whichever image-generation tool is available by
+  default on the current platform (an MCP image-generation server such as
+  `kie-image-mcp`, a built-in model image-generation capability, or any other
+  configured image tool) — don't assume one specific provider. If the user
+  names a particular tool or model in their request (e.g. "use nano-banana-2",
+  "use Flux", "use imagen4"), use that one instead of the default. Whichever
+  tool is used, pass BOTH the base texture and the UV layout as reference
+  images to it. Match `aspect_ratio` to the texture (usually `1:1`), request a
+  resolution/size close to the texture size (e.g. `2K` for 2048px), and request
+  PNG output. If no image-generation tool is available at all, tell the user
+  and ask them to configure one before proceeding.
+- **Helper scripts** live in the `scripts/` folder next to this SKILL.md
+  (need Python 3 + Pillow + numpy):
+  - `scripts/uv_island_mask.py`  — build the island mask from the UV layout.
+  - `scripts/composite_skin.py`  — composite one AI output through the mask onto the base.
+  - `scripts/preview.py`         — `mask-overlay` to verify the mask; `sheet` for a contact sheet.
+  Resolve `<skilldir>` as the directory containing this SKILL.md file, so scripts
+  are at `<skilldir>/scripts/`. Install deps once if needed:
+  `python3 -m pip install -r <skilldir>/scripts/requirements.txt`
+  (or `python3 -m pip install pillow numpy`). Each script also auto-installs its
+  own missing deps on first run.
+
+## Procedure
+
+### 0. Validate inputs
+Confirm the base texture and UV layout are both usable before doing anything
+else:
+- **Local path**: confirm it exists and opens as a valid image.
+- **URL**: confirm it's reachable and actually returns image content, then
+  download it once into `<scratch>/` (e.g. `base_source.png` /
+  `uv_layout_source.png`) — the helper scripts below only work on local files,
+  so use these downloaded copies as "`<base.png>`"/"`<uv_layout.png>`" for every
+  step from here on.
+
+If either input fails validation, stop and report which one and why (missing /
+wrong path / URL unreachable / not an image) instead of proceeding — never fall
+back to a default or unrelated file.
+
+### 1. Inspect
+Read the base texture and the UV layout as images. Note the texture pixel size
+(`sips -g pixelWidth -g pixelHeight <file>` on macOS, or open the image and check
+its dimensions). Decide which islands change and which are preserved.
+
+### 2. Build the UV-island mask
+```
+python3 <skilldir>/scripts/uv_island_mask.py <uv_layout.png> <scratch>/island_mask.png --size <TEXSIZE>
+```
+Defaults: `--radius 9 --thresh 35`. Increase `--radius` if big internal triangles
+leave holes; lower `--thresh` if the wireframe is faint. Coverage is printed —
+sanity check it (a full-body atlas is typically 20–50%).
+
+### 3. Verify the mask (do not skip)
+```
+python3 <skilldir>/scripts/preview.py mask-overlay <base.png> <scratch>/island_mask.png <scratch>/overlay.png
+```
+Read `overlay.png`. The red tint MUST cover exactly the islands you intend to
+change and NOT the preserved islands / dead space. If it's inverted or off,
+re-run step 2 with adjusted params (the script already auto-strips a white border
+frame; if the layout has unusual framing, that is the usual culprit).
+
+### 4. Generate each raw variation
+Save raw AI outputs to `<scratch>/raw/skin_var_NN.png` (NOT the final folder).
+Use this prompt template with the chosen image-generation tool (the platform's
+default, or whichever one the user named), filling the per-variation creative
+bits and the preserve/change lists for the specific asset:
+
+```
+You are editing a {W}x{H} game model TEXTURE ATLAS (UV unwrap). Reference image 1
+is the base color atlas (use it as the guide for overall look, layout and
+proportions). Reference image 2 is the UV ISLAND MAP showing exact wireframe
+outlines of every UV island.
+
+ABSOLUTE LAYOUT RULES (this is a skin swap for one shared model — the UV layout
+MUST match exactly):
+- Reproduce reference image 1's GEOMETRY/LAYOUT exactly: every UV island stays in
+  the same position, size, rotation and shape. Painted detail must fit inside the
+  same island outlines.
+- Keep these islands unchanged: {LIST WHAT TO PRESERVE}.
+- Do NOT add any new art, portrait or object anywhere. Do NOT paint into the
+  empty/black/white background. Paint ONLY inside existing colored islands.
+- You may recolor/repattern ONLY: {LIST WHAT TO CHANGE}.
+- Flat evenly-lit albedo/diffuse texture, no baked shadows.
+
+VARIATION DETAILS: {creative description for this variant}
+```
+Generating several variants in parallel is fine. The raw output will likely bleed
+outside the islands — that is expected and removed in the next step.
+
+### 5. Composite through the mask -> final skins
+For each variant:
+```
+python3 <skilldir>/scripts/composite_skin.py <base.png> <scratch>/island_mask.png \
+    <scratch>/raw/skin_var_NN.png <FINAL_DIR>/skin_var_NN.png
+```
+This writes the shippable skin: island pixels from the AI image, everything else
+identical to the base. Optional `--feather` (default 1.0px) softens the seam.
+
+### 6. Review
+```
+python3 <skilldir>/scripts/preview.py sheet <scratch>/contact_sheet.png <FINAL_DIR>/skin_var_*.png
+```
+Read the contact sheet (and crop into key islands like faces if needed) to
+confirm variety and quality. Regenerate any weak variants by repeating steps 4–5
+for just those indices.
+
+## Notes & gotchas
+- Always pass BOTH base + UV layout as references to the generator; never rely on
+  the prompt alone to hold the layout.
+- The mask is the safety net. If a variant's island content is shifted inside its
+  island, the composite clips it to the island shape — re-prompt that variant
+  rather than widening the mask.
+- Keep raw AI outputs separate from finals so you can re-composite without
+  re-generating (e.g. after tuning the mask).
+- For engine import (Unity, Babylon, etc.), the finals go in the project's
+  texture folder; the engine generates its own meta/import settings.
+
+## How to use this skill
+- Invoke it directly (e.g. the `/bt-atlas` slash command, if your tool derives one
+  from this folder), or just ask in chat for new texture/skin variants — this
+  skill applies whenever the request matches its description.
+- Provide: the base color texture path, the UV layout image path, how many
+  variations you want, and which islands to change vs preserve (a short
+  creative direction per variation helps too). For example:
+  > `/bt-atlas textures/hero_base.png textures/hero_uv_layout.png 4 vary armor color and face, keep the sword and hair`
+- Anything you omit will be asked for before generation starts (see **Inputs**
+  below). You can also name a specific image-generation tool/model to use (see
+  **Tools** below) — otherwise the default available one is used.
+- Output lands in `SkinVariations/` next to the base texture unless you specify
+  another output directory.

package/skills/bt-atlas/scripts/composite_skin.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Composite a generated skin onto the base texture through a UV-island mask.
+
+Keeps ONLY the pixels INSIDE the UV-island mask from the generated image and
+takes everything else verbatim from the base texture. This guarantees the
+generated skin can never alter the UV layout / dead space, so it stays a valid
+drop-in skin swap for the same model geometry & UVs.
+
+Usage:
+  python3 composite_skin.py <base.png> <mask.png> <generated.png> <out.png> [--feather 1.0]
+"""
+import argparse
+
+
+def _ensure_deps():
+    """Auto-install Pillow/numpy on first run so users only need Python itself."""
+    import importlib
+    import subprocess
+    import sys
+    for mod, pkg in (("PIL", "pillow"), ("numpy", "numpy")):
+        try:
+            importlib.import_module(mod)
+        except ImportError:
+            print(f"[skin] installing missing dependency: {pkg} ...")
+            subprocess.check_call([sys.executable, "-m", "pip", "install", "--user", "--quiet", pkg])
+
+
+_ensure_deps()
+
+import numpy as np
+from PIL import Image, ImageFilter
+
+
+def composite(base_path, mask_path, gen_path, out_path, feather=1.0):
+    base = Image.open(base_path).convert("RGB")
+    size = base.size
+    mask = Image.open(mask_path).convert("L").resize(size)
+    if feather > 0:
+        mask = mask.filter(ImageFilter.GaussianBlur(feather))  # avoid hard seams
+    gen = Image.open(gen_path).convert("RGB").resize(size)
+
+    ba = np.array(base, dtype=np.float32)
+    ga = np.array(gen, dtype=np.float32)
+    ma = (np.array(mask, dtype=np.float32) / 255.0)[..., None]
+    out = ga * ma + ba * (1.0 - ma)
+    Image.fromarray(out.astype(np.uint8)).save(out_path)
+    print("wrote", out_path)
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser()
+    p.add_argument("base")
+    p.add_argument("mask")
+    p.add_argument("gen")
+    p.add_argument("out")
+    p.add_argument("--feather", type=float, default=1.0)
+    args = p.parse_args()
+    composite(args.base, args.mask, args.gen, args.out, args.feather)

package/skills/bt-atlas/scripts/preview.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Verification helpers for the skin generation workflow.
+
+mask-overlay : tint the base texture red where the island mask is active, so you
+               can confirm the mask covers the intended islands and nothing else.
+sheet        : build a contact sheet of several images for quick visual review.
+
+Usage:
+  python3 preview.py mask-overlay <base.png> <mask.png> <out.png>
+  python3 preview.py sheet <out.png> <img1> <img2> ... [--cols 5] [--cell 300]
+"""
+import argparse
+
+
+def _ensure_deps():
+    """Auto-install Pillow/numpy on first run so users only need Python itself."""
+    import importlib
+    import subprocess
+    import sys
+    for mod, pkg in (("PIL", "pillow"), ("numpy", "numpy")):
+        try:
+            importlib.import_module(mod)
+        except ImportError:
+            print(f"[skin] installing missing dependency: {pkg} ...")
+            subprocess.check_call([sys.executable, "-m", "pip", "install", "--user", "--quiet", pkg])
+
+
+_ensure_deps()
+
+import numpy as np
+from PIL import Image
+
+
+def mask_overlay(base_path, mask_path, out_path):
+    base = Image.open(base_path).convert("RGB")
+    size = base.size
+    mask = Image.open(mask_path).convert("L").resize(size)
+    ba = np.array(base, dtype=np.float32)
+    mm = (np.array(mask, dtype=np.float32) / 255.0)[..., None]
+    red = np.zeros_like(ba)
+    red[..., 0] = 255
+    ov = ba * (1 - 0.45 * mm) + red * (0.45 * mm)
+    Image.fromarray(ov.astype(np.uint8)).save(out_path)
+    print("wrote", out_path)
+
+
+def sheet(out_path, imgs, cols=5, cell=300):
+    rows = (len(imgs) + cols - 1) // cols
+    s = Image.new("RGB", (cols * cell, rows * cell), (20, 20, 20))
+    for i, pth in enumerate(imgs):
+        im = Image.open(pth).convert("RGB").resize((cell, cell))
+        s.paste(im, ((i % cols) * cell, (i // cols) * cell))
+    s.save(out_path)
+    print("wrote", out_path)
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers(dest="cmd", required=True)
+    a = sub.add_parser("mask-overlay")
+    a.add_argument("base"); a.add_argument("mask"); a.add_argument("out")
+    b = sub.add_parser("sheet")
+    b.add_argument("out"); b.add_argument("imgs", nargs="+")
+    b.add_argument("--cols", type=int, default=5)
+    b.add_argument("--cell", type=int, default=300)
+    args = p.parse_args()
+    if args.cmd == "mask-overlay":
+        mask_overlay(args.base, args.mask, args.out)
+    else:
+        sheet(args.out, args.imgs, args.cols, args.cell)

package/skills/bt-atlas/scripts/requirements.txt

@@ -0,0 +1,2 @@
+pillow>=10
+numpy>=1.24

package/skills/bt-atlas/scripts/uv_island_mask.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Build a binary UV-island footprint mask from a UV wireframe layout image.
+
+General purpose: makes NO assumption about where the islands sit in the texture
+(top/bottom/left/right). It thresholds the wireframe, optionally strips an outer
+white border frame, morphologically closes the triangles into solid island blobs,
+fills interior holes (position-independent flood from a padded border), then erodes
+back to the original boundary.
+
+Usage:
+  python3 uv_island_mask.py <uv_layout.png> <out_mask.png> \
+      [--size 2048] [--radius 9] [--thresh 35]
+
+Tune --radius up if islands have large internal triangles that don't merge;
+tune --thresh if the wireframe is faint (lower) or the background is noisy (higher).
+"""
+import argparse
+
+
+def _ensure_deps():
+    """Auto-install Pillow/numpy on first run so users only need Python itself."""
+    import importlib
+    import subprocess
+    import sys
+    for mod, pkg in (("PIL", "pillow"), ("numpy", "numpy")):
+        try:
+            importlib.import_module(mod)
+        except ImportError:
+            print(f"[skin] installing missing dependency: {pkg} ...")
+            subprocess.check_call([sys.executable, "-m", "pip", "install", "--user", "--quiet", pkg])
+
+
+_ensure_deps()
+
+import numpy as np
+from PIL import Image, ImageFilter, ImageDraw, ImageOps
+
+
+def build_mask(uv_path, size=2048, radius=9, thresh=35):
+    uv = Image.open(uv_path).convert("L").resize((size, size), Image.BILINEAR)
+    a = np.array(uv)
+    fg = a > thresh  # wireframe lines
+
+    # Auto-strip a white border frame if the image edge is mostly foreground
+    # (common in exported UV layout images). Harmless if no frame exists.
+    border = max(4, size // 170)
+    edge = np.concatenate([fg[0], fg[-1], fg[:, 0], fg[:, -1]])
+    if edge.mean() > 0.5:
+        fg[:border] = False
+        fg[-border:] = False
+        fg[:, :border] = False
+        fg[:, -border:] = False
+
+    m = Image.fromarray((fg.astype(np.uint8)) * 255)
+
+    # Close: dilate to merge wireframe triangles into solid island blobs
+    m = m.filter(ImageFilter.MaxFilter(2 * radius + 1))
+
+    # Fill interior holes, position-independent: flood the background starting
+    # from a 1px padded border, anything unreached is an interior hole.
+    inv = ImageOps.invert(m)              # background bright
+    padded = ImageOps.expand(inv, 1, fill=255)
+    ImageDraw.floodfill(padded, (0, 0), 128, thresh=10)
+    parr = np.array(padded)[1:-1, 1:-1]
+    holes = parr == 255                   # background not reached -> hole
+    filled = (np.array(m) > 127) | holes
+    mask = Image.fromarray((filled.astype(np.uint8)) * 255)
+
+    # Erode back to restore the original boundary size (undo the dilation),
+    # then a small safety dilation so island edges are not clipped.
+    mask = mask.filter(ImageFilter.MinFilter(2 * radius + 1))
+    mask = mask.filter(ImageFilter.MaxFilter(5))
+    return mask
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser()
+    p.add_argument("uv")
+    p.add_argument("out")
+    p.add_argument("--size", type=int, default=2048)
+    p.add_argument("--radius", type=int, default=9)
+    p.add_argument("--thresh", type=int, default=35)
+    args = p.parse_args()
+    mk = build_mask(args.uv, args.size, args.radius, args.thresh)
+    mk.save(args.out)
+    cov = 100.0 * (np.array(mk) > 127).mean()
+    print(f"saved {args.out} ({mk.size[0]}x{mk.size[1]}), island coverage {cov:.1f}%")

package/skills/bt-convert/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: bt-convert
+description: "The Babylon Toolkit Convert Skill converts source code to Babylon Toolkit TypeScript. Use when asked to convert source code or files to BabylonJS/Babylon Toolkit typescript."
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+Your goal is to convert source code to Babylon Toolkit based TypeScript. Always adhere to any rules or requirements set out in the project's agent instructions (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md) when responding.
+
+* Create new typescript (.ts) files for converted code
+* Make sure to convert all source code, do **not** omit anything (methods, properties, comments, etc), convert everything according to instructions
+* If an interface is only referenced (not defined in the source code being converted), do **not** generate the interface, just reference it
+
+---
+
+# Invocation
+
+```
+/bt-convert <source-code> <conversion-brief>
+```
+- **`<source-code>`** — the source code to convert. This is the *blueprint*.
+- **`<conversion-brief>`** — how to convert it. This is the *variable*.
+- If either is missing, ask for it before starting. Never guess a URL.
+
+Example:
+```
+/bt-convert → path/to/file.cs → "Convert to Babylon Toolkit TypeScript"
+```
+
+---
+
+**Use The Babylon Toolkit Agent Persona**
+
+---

package/skills/bt-copycat/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: bt-copycat
+description: "The Babylon Toolkit Copycat Skill forensically studies a live reference website, extracts its full design + motion DNA, and rebuilds a pixel-faithful frontend re-imagined around a new theme/subject for use as our project's Home page. Use when the user gives a URL (often with a creative brief) and wants a site that copies the *mechanics and craft* of the original — scroll choreography, load sequence, animation timing, layout rhythm, the whole `feel` — while re-skinning the subject, palette, and copy to their prompt."
+dependencies: bt-design
+---
+
+Your goal is to **reverse-engineer the reference website down to its DNA and rebuild it, pixel-faithful in mechanics, re-imagined in subject.** Always adhere to any rules or requirements set out in the project's agent instructions (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md) when responding.
+
+---
+
+# Invocation
+
+```
+/bt-copycat [--copilot] <reference-url> <re-imagining brief>
+```
+- **`<reference-url>`** — the site to study. This is the *blueprint*.
+- **`<re-imagining brief>`** — how to re-skin it. This is the *variable*.
+- **`--copilot`** *(optional flag)* — force **Mode B (User-Driven / Co-Pilot)** from the very start: the agent launches the shared chrome-devtools browser, you drive the scroll, it snapshots each beat. Skip the headless attempt entirely. Aliases: `--copilot`, `--co-pilot`, `--mode-b`. You can also just say "use co-pilot mode" / "I'll drive" anywhere in the prompt and it means the same thing.
+- If either the URL or brief is missing, ask for it before starting. Never guess a URL.
+
+Example (co-pilot from the jump):
+```
+/bt-copycat --copilot → https://www.igloo.inc/ → <re-imagining brief>
+```
+
+Example:
+```
+/bt-copycat --copilot → https://www.igloo.inc/ → Redesign this starter template to be the frontend for the prototype of a third person action adventure game called `Project Alpha`. Make sure there is `copy` on each phase of the hero stages. You don't have to use the igloo object — pick some sort of monolith or something that makes sense, but it needs that mystical winter, almost interstellar vibe: gorgeous, cinematic, otherworldly. The 3D scrolling cinematic should end with some engaging `Enter The Void` user interface that launches the `Player Demo` to start the prototype.
+```
+
+---
+
+# The Prime Directive
+
+**The mechanics are sacred. The skin is the variable.**
+
+You are NOT making "a site loosely inspired by" the reference. You are cloning the *machine that makes it feel amazing* — the exact scroll behavior, the exact load choreography, the exact animation timing and easing, the exact spatial rhythm and section cadence, the exact interaction feedback — and then swapping the subject, palette, typography flavor, imagery, and copy to match the brief.
+
+Split everything you observe into two buckets:
+
+| COPY EXACTLY (the DNA / mechanics) | RE-IMAGINE (the skin) |
+| --- | --- |
+| Scroll choreography & scrub mechanics | The hero object/subject |
+| Page-load sequence & reveal timing | Color palette & mood |
+| Animation durations, easings, stagger, delays | Typeface *personality* (not the exact font unless free) |
+| Section order, count, and vertical rhythm | Imagery / video content & generated assets |
+| Layout grid, alignment, spatial composition | Copywriting, headings, taglines |
+| Interaction patterns (hover, cursor, sticky, parallax) | Iconography & decorative motifs |
+| Pacing / "breathing" — where it holds and where it moves | Brand name, logo, product specifics |
+| Depth, layering, z-order, transitions between sections | Sound *design* content (the actual tracks/SFX & their theme) |
+| Audio behavior (ambient bed, scroll/hover SFX, mute UX, autoplay-gating) | |
+
+If in doubt about which bucket something belongs in: **feel-defining → COPY; content-defining → RE-IMAGINE.** A visitor should feel "this moves and breathes exactly like igloo.inc" while seeing something that is unmistakably *ours*.
+
+---
+
+## Phase 1 — Forensic Reconnaissance (DO NOT SKIP)
+
+You cannot recreate what you have not studied frame by frame. **Never build from a memory or a guess of what the site "probably" does.** Go look at the real thing.
+
+Prefer the **chrome-devtools** tools (a real headless browser — you can drive scroll, read the live DOM, capture the network, and profile motion). Fall back to **WebFetch** for raw HTML/CSS/JS only if a browser is unavailable, and **WebSearch** for "site of the year" write-ups, Awwwards case studies, and teardown articles that name the exact techniques used.
+
+### Choosing a Capture Mode
+
+Scroll-scrubbed 3D/video heroes (igloo.inc-class sites) are often **painfully slow or unreliable to drive headlessly** — the agent-driven scroll stutters, the WebGL timeline doesn't settle between frames, and a full teardown can stall out. When that happens, **do not keep grinding the headless scroll.** Switch to co-pilot mode. Pick the mode up front and tell the user which one you're using:
+
+- **Mode A — Agent-Driven (default).** You drive everything through chrome-devtools: navigate, scroll, screenshot, read the DOM, trace motion. Use this for standard sites and whenever headless scrolling is smooth.
+- **Mode B — User-Driven / Co-Pilot.** *You launch and share the chrome-devtools browser; the user drives the scroll while you direct and snapshot.* Use this when: the hero is a heavy scroll-scrubbed 3D/video timeline; headless scroll is janky, stalling, or not advancing the animation; the site blocks automation / needs a login or cookie wall; or the user simply asks to drive.
+
+**Start directly in Mode B when asked.** If the invocation includes the **`--copilot`** flag (or `--co-pilot` / `--mode-b`), or the user says anything like "use co-pilot mode" / "I'll drive" / "let me scroll", **begin in Mode B immediately — skip the headless Mode A attempt entirely** and go straight to the Mode B setup below.
+
+**Announce a switch:** if you start in Mode A and the scroll teardown is taking too long or not progressing after a couple of attempts, stop and say so — e.g. *"The headless scroll isn't keeping up with this 3D hero. Let's switch to co-pilot mode — I'll launch the browser, you drive the scroll, and I'll snapshot each beat."* — then follow the protocol below.
+
+### Mode B — User-Driven Co-Pilot Protocol
+
+You become the director; the user is the hands. Give **one clear instruction at a time, wait for the user's signal, then capture, then advance.** Never fire a wall of steps at once.
+
+**Setup (agent launches the browser, user parks it at the top)**
+1. **You launch the browser.** Open the reference URL in the shared **chrome-devtools** browser, maximized at desktop width. Let it fully load, then **say you're ready** and hand control to the user — e.g. *"Chrome DevTools is up on the reference site and fully loaded. It's yours — scroll it all the way back to the very top, get it parked and holding still, then say 'ready' and I'll take the first snapshot."*
+2. **The user positions the page.** The user takes the shared browser, scrolls fully back to the very top of the experience, and lets it settle.
+3. **Tell them the cadence + signal words** up front: the default checkpoint cadence is **~10% of page height per step**, plus any moment where the motion visibly changes. From the top the user signals **"ready"**; after that they follow your lead — scroll the amount you ask, let it hold still, and say **"ok"** / **"next"** (or "ready for the next snapshot") for each beat.
+
+> **Shared browser is the default here.** Because *you* launched the chrome-devtools browser, *you* take every screenshot and read live values yourself (`evaluate_script`, `list_network_requests`) at each checkpoint — the user only drives the scroll. Only fall back to asking the user to paste screenshots/snippets if the browser can't be shared.
+
+**Signal words (tell the user these up front)**
+- **"ready"** — user has parked the page at the very top and it's holding still; you take the **first snapshot** now, then begin the loop.
+- **"ok"** / **"next"** — user has completed the scroll step you asked for and the frame is holding still; safe for you to capture the next beat.
+- **"done"** — user has reached the bottom / end of the sequence.
+- **"back"** — user needs you to re-describe or repeat the previous step.
+- **"stop"** — abort the capture.
+
+**The loop (repeat until "done")**
+0. **User:** signals **"ready"** at the top. **You:** take the first snapshot and read the load/first-paint values before asking for any scroll.
+1. **You:** give exactly one instruction — e.g. *"Scroll down slowly until the object is roughly centered and the text has just finished fading in, then hold still and say 'ok'."* Be specific about what beat to stop on, not just a pixel amount.
+2. **User:** performs it and replies **"ok"** / **"next"**.
+3. **You:** capture the checkpoint yourself in the shared chrome-devtools browser — take the screenshot and read any live values you can. Note the scroll depth, what entered/exited, and the apparent timing/easing of that beat. (Only if the browser can't be shared, ask the user to paste/attach a screenshot.)
+4. **You:** confirm and advance — *"Got it, checkpoint 3 captured. Next: keep scrolling until the horizon tilts and a new panel pins — hold and say 'ok'."*
+5. Repeat. When the user says **"done"**, confirm you have top-to-bottom coverage; if a beat is missing, ask them to scroll back to it (**"back"**) and re-capture.
+
+**What you still must extract in Mode B.** Manual scrolling replaces only the *screenshotting of the journey*. You still need the real numbers — design tokens, easings, asset/network inventory, scroll-distance ratios. If you share the chrome-devtools browser with the user, pull these yourself via `evaluate_script` / `list_network_requests` between checkpoints. If you cannot, ask the user to run small snippets (e.g. `getComputedStyle`, `document.body.scrollHeight`, the Network tab's asset list) and paste the results. **Screenshots alone are not enough — vibes fail Phase 5 verification.**
+
+**Reuse this loop in Phase 5.** When verifying the rebuild's fidelity, run the exact same co-pilot protocol against *our* site so the storyboards are captured identically and compared beat-for-beat.
+
+Run this teardown against the reference (in either mode):
+
+1. **Load & watch the entrance.** Navigate to the URL. Capture the loader/preloader, the first paint, and the opening reveal. Note the *sequence and timing* of everything that animates in on load — order, delay, duration, easing. The first 3 seconds define the site's whole personality.
+2. **Screenshot the full scroll journey.** Capture the viewport at many scroll depths (e.g. 0%, 10%, 20% … 100%) at desktop width. This is the storyboard you will rebuild. Also capture at a mobile width via `resize_page`/`emulate` — note what reflows, hides, or simplifies.
+3. **Dissect the scroll mechanics.** Is the hero scroll-scrubbed (scroll position drives a video/3D timeline)? Sticky sections? Pinned panels? Horizontal scroll? Parallax layers at different speeds? Scroll-triggered reveals? Measure *how much scroll distance* maps to each beat of motion — this is the single most important thing to get right for a cinematic site.
+4. **Extract the exact design tokens.** Use `evaluate_script` against the live DOM to pull real values, not eyeballed ones: computed colors (bg/ink/accent), font families & weights, type scale, spacing rhythm, border-radii, shadow recipes, blur/backdrop values, and CSS custom properties. Read the actual CSS.
+5. **Time the motion.** Read `transition`/`animation` declarations and, where it matters, run a `performance_start_trace`/`stop_trace` across a scroll to see real durations and frame pacing. Capture easing curves (cubic-bezier values), stagger offsets, and loop timings.
+6. **Inventory the assets & tech.** Use `list_network_requests` to see what actually loads: video files (and their length/resolution — critical for a scrub hero), image formats, fonts, and the animation/3D libraries in play (GSAP/ScrollTrigger, Lenis/smooth-scroll, Three.js/Babylon, Lottie, WebGL shaders). Knowing the technique is how you reproduce the feel.
+7. **Map interactions.** Hover key elements, move through the nav, trigger the cursor — record custom cursors, magnetic buttons, hover distortions, link transitions, and any sound.
+8. **Check for audio (do not skip).** Determine whether the site has sound at all — many award-winning cinematic sites ship an ambient audio bed, scroll/hover SFX, or a reveal sting. Inspect the network inventory for audio files (`.mp3`/`.ogg`/`.wav`/`.m4a`) and the DOM/JS for `<audio>` elements, `AudioContext`/Web Audio, Howler.js, or muted-autoplay video used purely for sound. Record: is there an ambient loop, per-interaction SFX, or scroll-synced audio? How is playback gated (autoplay policy — first user gesture, an explicit sound toggle)? Is there a mute/unmute control, and where does it live? What is the default state (on/off)? If the site has **no audio**, note that explicitly so the rebuild doesn't invent it.
+
+**Deliverable of this phase:** enough captured evidence (screenshots + real numbers) that you could rebuild the site with the tab closed.
+
+## Phase 2 — Write the DNA Blueprint
+
+Before writing a single line of the new site, produce a written **DNA Blueprint** — the machine spec you will build against. Save it (e.g. `DNA-BLUEPRINT.md` in the work dir) so the rebuild is measured against it, not against vibes. It must contain:
+
+- **One-line essence** — the feeling in a sentence ("a lone object drifting through an endless, mystical winter, revealed by scroll").
+- **Load sequence** — ordered, timed list of what happens from blank page to interactive.
+- **Section-by-section storyboard** — for each section: purpose, layout, what enters/exits, on what trigger, over what scroll distance, with what timing/easing.
+- **Scroll model** — scrub vs. reveal vs. pin vs. parallax; scroll-distance-to-motion ratios; smooth-scroll behavior.
+- **Motion table** — durations, easings (real cubic-beziers), stagger, delays for the key moments.
+- **Audio model** — whether the site has sound at all; if so, the ambient bed / per-interaction SFX / scroll-synced audio, the playback-gating mechanism (autoplay policy, first-gesture unlock), the mute/unmute control and its default state — plus the **re-imagined** audio direction chosen for the brief. If the original is silent, say so.
+- **Design tokens** — the real extracted values, then the **re-imagined** values chosen for the brief beside them.
+- **Asset manifest** — every video/image/3D/audio asset the original uses, and what we will generate to replace it under the new theme.
+- **Tech approach** — which libraries/techniques reproduce each mechanic.
+
+## Phase 3 — Re-imagine to the Brief
+
+Now apply the creative brief to the *skin only*. Choose the new subject/object, palette, typographic personality, mood, and copy so they serve the prompt — while keeping every mechanic from the blueprint intact. The igloo becomes a lone monolith / a drifting seed / a frozen relic — but it still moves through the world on scroll exactly as the igloo did. Push the aesthetic hard and specific per the brief; do not water it down toward generic.
+
+**Fidelity governs the layout — but skin toward game-frontend console UI.** The reference's layout width and spatial composition live in the COPY-EXACTLY bucket, so match the original: if it's full-bleed / full page width (as the cinematic, award-winning references this skill targets almost always are), reproduce that faithfully; if it is genuinely fixed-width, keep it fixed-width — do **not** force full-bleed onto a reference that isn't. Within whatever width the blueprint dictates, push the *skin* toward the modern-console game-frontend feel from bt-design's *Layout Philosophy — Full-Bleed Console UI* (edge-anchored HUD/menu clusters, console focus/selection states, cinematic overlays), since the output is our game's Home page — never at the cost of a mechanic.
+
+## Phase 4 — Rebuild with `bt-design`
+
+**Load bt-design first — this phase is executed THROUGH it and cannot be done without it.** Where skills are loaded with a tool (the Babylon Toolkit App Builder platform), call `load_skill('bt-design')`, and fetch any of its bundled references with `read_skill_resource` using the paths the load returns — never a guessed path. Where skills are files on disk (Claude Code), read `bt-design/SKILL.md` from the same skills directory, `~/.claude/skills/` or the project's `.claude/skills/`. If bt-design is already in your context, skip the load. Earlier phases also lean on it by name (Phase 3's *Layout Philosophy — Full-Bleed Console UI*, and the anti-slop guidance below) — if you are reading those before you get here, load it there instead.
+
+Hand the DNA Blueprint to the **bt-design** skill to build the actual frontend as our `Home` page (plus any supporting pages the original implies).
+
+**Output target — where the rebuild lands (Babylon Toolkit projects):** the Home page is authored in **`src/pages/Home.tsx` + `src/pages/Home.css`** (supporting pieces in `src/pages/` / `src/components/`). It is deliberately pulled OUT of `app.tsx` — **`app.tsx` and `src/routing/**` are a READ-ONLY routing shell; never write the design into them.** The shell already routes `/` to `Home`, so replacing `Home.tsx`/`Home.css` IS replacing the landing page. Keep the play contract intact (`navigate('/play', { gameMode: … })` via `useUnifiedNavigation`; `src/pages`/`src/components` stay Babylon-free), and if the retheming extends to the game chrome (splash/preloader/overlay), that lives in `src/chrome/**` per the bt-landing skill's rules — including its ENGINE CONTRACT: the splash's engine-required element ids (`xbabylonjsSplashScreen`, `babylonjsLoadingDiv`, `babylonjsLoadingText`, `babylonjsLoadingDivStyle`, `xbabylonjsStatusTextDiv`) must survive any redesign byte-for-byte, or the engine cannot hide the splash to reveal the scene — and its IMPORTS rule: read each file you replace and copy its whole import block across character for character (`GameManager` is a DEFAULT export — `import GameManager from '../babylon/globals'`, never `{ GameManager }`). For non-Toolkit hosts, target whatever the root route's page component actually is — never a router/shell file.
+
+Instruct bt-design to:
+
+- Match the blueprint's mechanics and timing **exactly** — this is a fidelity job, not a fresh design. Where bt-design would normally improvise, here it executes the blueprint.
+- Generate the re-imagined video/image/3D assets (image & video generation) to fill the asset manifest under the new theme — as beautiful and cinematic as the original's.
+- Reproduce the load choreography, scroll behavior, and micro-interactions from the motion table.
+- **Reproduce the audio model from the blueprint** — if the original has sound, rebuild the equivalent behavior (ambient bed, interaction/scroll SFX, mute toggle, autoplay-gating on first user gesture per browser policy) and generate re-imagined audio assets that match the new theme. If the original is silent, do not add audio unless the brief asks for it.
+
+**Enforced build mandate (always apply):**
+- Make the new site **as cinematic and award-winning as the original**, and make it **feel like a real game prototype, not a generic template**.
+- **The user provides the prototype's own assets.** You may generate any *additional* cinematic imagery or video needed to fill out the storyboard — use image & video generation to create every necessary asset.
+- Make the new site **fully responsive** and working on all devices.
+- **Create a `DESIGN.md`** reflecting the new theme if it does not exist or is only an empty stub; otherwise update it.
+- **Update `SPEC.md`** with any significant architectural changes, if any.
+
+**Scroll-scrubbed / cinematic scroll heroes:** if the original's hero is scroll-driven (as igloo.inc is), this is a **3D-Hero-Scroll** job. Route through bt-design → `references/3d-hero-scroll.md` and copy the drop-in templates from `templates/3d-hero-scroll/` — do not re-implement the scrub engine from memory. Map the reference's real numbers (footage length, scroll-distance-per-second, telemetry, jump cuts) into `HS_CONFIG` and the `--hs-*` tokens.
+
+**ONLY IF** the user requests to add `3D scroll controls`, use the (bt-design → 3D-Hero-Scroll → playback controls) sub-skill with the requested `sweep` (default: `page`) to add smooth cinematic playback controls.
+
+## Phase 5 — Verify Fidelity Against the Original
+
+A copycat that "feels off" has failed. Before declaring done, verify the rebuild the same way you studied the original:
+
+- Open the rebuilt site in the browser and capture the **same scroll-depth storyboard** you captured in Phase 1. Compare side by side against the blueprint — does each beat land at the same scroll position with the same motion?
+- Check the load sequence, easings, and stagger match the motion table.
+- Confirm nothing is janky: smooth scrubbing, no layout shift, motion holds 60fps where the original does.
+- Confirm the audio behavior matches the blueprint: if the original had sound, ours has the equivalent ambient bed / SFX, a working mute toggle, and correct autoplay-gating; if the original was silent, ours is too (unless the brief asked otherwise).
+- Confirm the *skin* fully reads as the new brief, not a recolor of the original's content.
+
+Report any beat where fidelity is imperfect and fix it — do not paper over a mechanic you couldn't reproduce.
+
+---
+
+## Non-Negotiables
+
+- **Study first, build second.** No recreation begins before Phase 1 evidence and a Phase 2 blueprint exist.
+- **Numbers, not vibes.** Extract real colors, timings, and scroll ratios from the live site. "Roughly a fade" is not acceptable when you can read the exact `cubic-bezier`.
+- **Mechanics are copied; content is re-imagined.** Never invent a different scroll feel; never ship the original's subject/branding.
+- **Match the original's craft ceiling.** The reference is award-winning for a reason. The rebuild must be *as* beautiful — no generic AI-slop fallback (see bt-design's anti-slop guidance). If the original holds a held, breathing silence before a reveal, so does ours.
+- **Ship a prototype, not a template.** The result must feel like a real game prototype — cinematic and award-winning — fully responsive on all devices. The user supplies the prototype's assets; generate any additional cinematic imagery/video to complete the storyboard. Create `DESIGN.md` for the new theme (if missing or an empty stub) and update `SPEC.md` for any significant architectural changes.
+- **Verify against the source.** Done means the storyboards match.