luckiest-co 1.0.38 → 1.0.40

package/skills/video-watcher/scripts/setup.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+"""Base preflight, backend configuration, and an opt-in managed WhisperX install."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from config import (CONFIG_DIR, CONFIG_FILE, ConfigError, DETAILS, ENGINES, get_config,
+                    load_api_key, load_gemini_key, read_env_file, resolve_engine, write_settings)
+from runtime import configure_stdio, diagnostic, run_text
+
+REQUIRED_BINARIES = ['ffmpeg', 'ffprobe', 'yt-dlp']
+WHISPERX_VERSION = '3.8.6'
+UV_VERSION = '0.11.16'  # pinned installer; bump deliberately
+_PERM_WARNED: set[str] = set()
+ENV_TEMPLATE = '''# /watch configuration. No shell interpolation; last assignment wins.
+# Native captions always come first. Optional fallback: auto|whisperx|groq|openai|none.
+# auto preserves the Groq-then-OpenAI preference for existing installations.
+# The first-run skill wizard sets WATCH_DETAIL and WATCH_WHISPER_BACKEND.
+# WATCH_ENGINE=auto|gemini|local. auto uses Gemini when GEMINI_API_KEY is set.
+# With the gemini engine, local videos are uploaded to Google for analysis.
+GEMINI_API_KEY=
+GROQ_API_KEY=
+OPENAI_API_KEY=
+'''
+
+
+def _which(name):
+    return shutil.which(name)
+
+
+def _check_binaries():
+    return [name for name in REQUIRED_BINARIES if not _which(name)]
+
+
+def _check_file_permissions(path: Path) -> None:
+    # Native Windows mode bits do not describe NTFS ACLs. WSL Linux homes do.
+    if os.name == 'nt' or platform.system() == 'Windows' or str(path) in _PERM_WARNED:
+        return
+    try:
+        if path.stat().st_mode & 0o044:
+            _PERM_WARNED.add(str(path))
+            print(f'[watch] WARNING: {path} is readable by other users. Run: chmod 600 "{path}"', file=sys.stderr)
+    except OSError:
+        pass
+
+
+def _have_api_key():
+    backend, key = load_api_key()
+    return bool(key), backend
+
+
+def is_first_run():
+    return read_env_file(CONFIG_FILE).get('SETUP_COMPLETE') != 'true'
+
+
+def _scaffold_env():
+    if CONFIG_FILE.exists():
+        read_env_file(CONFIG_FILE)  # Fail safely before modifying bad config.
+        return False
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    fd = os.open(CONFIG_FILE, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+        stream.write(ENV_TEMPLATE)
+    return True
+
+
+def _write_setup_complete():
+    _scaffold_env()
+    write_settings({'SETUP_COMPLETE': 'true'}, CONFIG_FILE)
+
+
+def _brew_pkg(missing):
+    return list(dict.fromkeys('ffmpeg' if name == 'ffprobe' else name for name in missing))
+
+
+def _install_step(cmd, step):
+    print(f"[setup] {step}: {' '.join(map(str, cmd))}", file=sys.stderr, flush=True)
+    try:
+        result = subprocess.run(list(map(str, cmd)))
+    except OSError as exc:
+        raise SystemExit(f'{step}: cannot run {cmd[0]} ({type(exc).__name__}); install or repair that executable, then retry.') from None
+    if result.returncode:
+        raise SystemExit(f'{step} failed (exit {result.returncode}): retry setup after checking the error above. '
+                         'For WhisperX, allow at least 3 GB free disk and 8 GB RAM; package/model downloads need network access.')
+
+
+def _install_macos(missing):
+    if not _which('brew'):
+        return False, 'Homebrew is missing. Install it from https://brew.sh, then rerun setup.'
+    _install_step(['brew', 'install', *_brew_pkg(missing)], 'Install media dependencies')
+    return True, 'Installed media dependencies with Homebrew.'
+
+
+def _install_hint_linux(missing):
+    hints = []
+    if 'ffmpeg' in _brew_pkg(missing):
+        hints.append('apt: sudo apt install ffmpeg (or the equivalent package for your distribution)')
+    if 'yt-dlp' in missing:
+        hints.append('Install pipx, then: pipx install "yt-dlp[default,curl-cffi]"; pipx ensurepath. For YouTube also install Deno: https://deno.com/')
+    return '\n'.join(hints)
+
+
+def _install_hint_windows(missing):
+    hints = []
+    if 'ffmpeg' in _brew_pkg(missing):
+        hints.append('winget install --id Gyan.FFmpeg --exact')
+    if 'yt-dlp' in missing:
+        hints.extend(['winget install --id yt-dlp.yt-dlp --exact', 'winget install --id DenoLand.Deno --exact'])
+    return '\n'.join(hints) + '\nReopen your terminal/agent after PATH changes.'
+
+
+def _probe(cmd):
+    try:
+        result = run_text(cmd, timeout=20)
+        output = result.stdout or result.stderr
+        return {'ok': result.returncode == 0, 'version_line': output.splitlines()[0] if output else None, 'output': diagnostic(output, 2500)}
+    except SystemExit as exc:
+        return {'ok': False, 'output': str(exc)}
+
+
+def _whisperx_status(cfg, detailed=False):
+    from local_whisperx import sentinel_for
+    value = cfg['whisperx_bin']
+    executable = Path(value) if value else None
+    ready = bool(executable and executable.is_absolute() and executable.is_file() and sentinel_for(executable).is_file())
+    if ready and detailed:
+        # Explicit detailed diagnostics may start the CLI. --check never does.
+        try:
+            from local_whisperx import child_env
+            result = run_text([str(executable), '--help'], timeout=30, env=child_env())
+            ready = result.returncode == 0 and '--no_align' in result.stdout
+        except SystemExit:
+            ready = False
+    return ready
+
+
+def _status(detailed=False):
+    missing = _check_binaries()
+    _check_file_permissions(CONFIG_FILE)
+    cfg = get_config()
+    gemini_key = bool(load_gemini_key())
+    try:
+        engine = resolve_engine(cfg['engine'], gemini_key)
+    except ConfigError:
+        engine = 'gemini'  # Explicitly chosen but the key is missing; gemini_key_present reports it.
+    binaries_required = engine == 'local'
+    has_key, detected = _have_api_key()
+    chosen = cfg['whisper_backend']
+    backend = detected if chosen == 'auto' else chosen
+    local_ready = _whisperx_status(cfg, detailed)
+    backend_ready = local_ready if chosen == 'whisperx' else (bool(load_api_key(backend)[1]) if backend in ('groq', 'openai') else chosen == 'none')
+    blocked = bool(missing) and binaries_required
+    result = {'status': 'needs_install' if blocked else 'ready', 'can_proceed': not blocked,
+              'engine': engine, 'configured_engine': cfg['engine'], 'gemini_key_present': gemini_key,
+              'gemini_model': cfg['gemini_model'], 'binaries_required': binaries_required,
+              'first_run': is_first_run(), 'setup_complete': not is_first_run(),
+              'missing_binaries': missing, 'whisper_backend': backend, 'configured_backend': chosen,
+              'has_api_key': has_key, 'backend_ready': backend_ready,
+              'whisperx_ready': local_ready, 'whisperx_bin': cfg['whisperx_bin'],
+              'whisperx_model': cfg['whisperx_model'], 'config_file': str(CONFIG_FILE),
+              'watch_detail': cfg['detail'], 'platform': platform.system()}
+    if detailed:
+        tools = {}
+        for name in REQUIRED_BINARIES:
+            path = _which(name)
+            tools[name] = {'path': path, **(_probe([path, '--version' if name == 'yt-dlp' else '-version']) if path else {'ok': False})}
+        ytdlp = _which('yt-dlp')
+        result['tools'] = tools
+        result['youtube'] = {
+            'deno': _which('deno'), 'node': _which('node'),
+            'ejs': 'unknown (inspect the owning yt-dlp installation; no network probe)',
+            'impersonation': _probe([ytdlp, '--ignore-config', '--list-impersonate-targets']) if ytdlp else None,
+            'update_hint': 'Update the owning package: brew upgrade yt-dlp; pipx upgrade yt-dlp; or winget upgrade --id yt-dlp.yt-dlp --exact. Verify the executable path above.',
+        }
+    return result
+
+
+def cmd_check():
+    # Optional credentials and local-model readiness never block base watch.
+    status = _status()
+    if status['can_proceed']:
+        return 0
+    print(f"[watch] Missing {', '.join(status['missing_binaries'])}. Run python3 \"{Path(__file__).resolve()}\".", file=sys.stderr)
+    return 2
+
+
+def cmd_json():
+    print(json.dumps(_status(detailed=True), indent=2))
+    return 0
+
+
+def cmd_install(backend=None, detail=None, engine=None):
+    if engine:
+        _scaffold_env()
+        write_settings({'WATCH_ENGINE': engine}, CONFIG_FILE)
+    if engine == 'gemini':
+        if not load_gemini_key():
+            print(f'[setup] Add GEMINI_API_KEY privately to {CONFIG_FILE} (free key: https://aistudio.google.com/apikey), '
+                  'then rerun --engine gemini. Local videos will be uploaded to Google for analysis.', file=sys.stderr)
+            return 3
+        _write_setup_complete()
+        missing = _check_binaries()
+        note = (f" Optional: install {', '.join(_brew_pkg(missing))} for non-YouTube URLs and --engine local." if missing else '')
+        print(f'[setup] Gemini engine is ready. Configuration: {CONFIG_FILE}.{note}')
+        return 0
+    missing = _check_binaries()
+    if missing:
+        system = platform.system()
+        if system == 'Darwin':
+            ok, message = _install_macos(missing)
+            print(f'[setup] {message}', file=sys.stderr)
+            if not ok or _check_binaries():
+                return 2
+        else:
+            print(_install_hint_windows(missing) if system == 'Windows' else _install_hint_linux(missing), file=sys.stderr)
+            return 2
+    _scaffold_env()
+    if detail:
+        write_settings({'WATCH_DETAIL': detail}, CONFIG_FILE)
+    if backend == 'whisperx':
+        return install_whisperx()
+    if backend:
+        write_settings({'WATCH_WHISPER_BACKEND': backend}, CONFIG_FILE)
+        if backend in ('groq', 'openai') and not load_api_key(backend)[1]:
+            print(f'[setup] Base watch is ready. Add {backend.upper()}_API_KEY privately to {CONFIG_FILE}, then rerun --backend {backend}.', file=sys.stderr)
+            return 3
+        _write_setup_complete()
+    print(f'[setup] Base watch is ready. Configuration: {CONFIG_FILE}')
+    return 0
+
+
+def _ensure_uv():
+    name = 'uv.exe' if platform.system() == 'Windows' else 'uv'
+    installed = _which('uv')
+    fallback = Path.home() / '.local' / 'bin' / name
+    if installed or fallback.is_file():
+        return installed or str(fallback)
+    system = platform.system()
+    if system == 'Darwin':
+        if not _which('brew'):
+            raise SystemExit('WhisperX setup needs uv. Install Homebrew from https://brew.sh, then rerun setup.')
+        _install_step(['brew', 'install', 'uv'], 'Install uv')
+    elif system in ('Windows', 'Linux'):
+        # Pinned version, fetched to a file first: never pipe a moving URL into a shell.
+        windows = system == 'Windows'
+        url = f'https://astral.sh/uv/{UV_VERSION}/install.{"ps1" if windows else "sh"}'
+        with tempfile.TemporaryDirectory(prefix='watch-uv-') as temporary:
+            script = Path(temporary) / ('install.ps1' if windows else 'install.sh')
+            _install_step(['curl', '-LsSf', url, '-o', script], f'Download uv {UV_VERSION} installer')
+            run = ['powershell', '-NoProfile', '-ExecutionPolicy', 'ByPass', '-File', script] if windows else ['sh', script]
+            _install_step(run, f'Install uv {UV_VERSION}')
+    else:
+        raise SystemExit('Install uv from https://docs.astral.sh/uv/ before retrying WhisperX setup.')
+    installed = _which('uv')
+    if installed or fallback.is_file():
+        return installed or str(fallback)
+    raise SystemExit('uv installed but could not be found; reopen your terminal and rerun setup.')
+
+
+def install_whisperx():
+    from local_whisperx import settings, transcribe_audio
+    print('[setup] Local WhisperX: requires 3 GB free disk, 8 GB RAM, a 64-bit CPU, and network access for setup. '
+          'Downloads about 1 GB of packages plus the 464 MB small model. macOS Apple Silicon is verified; '
+          'Intel macOS, Linux, Windows, and CUDA installs are untested.', file=sys.stderr, flush=True)
+    if not _which('ffmpeg'):
+        raise SystemExit('Install FFmpeg first, then rerun setup.py --install-whisperx.')
+    cfg = settings()
+    # Check the existing config before downloading or modifying an environment.
+    _scaffold_env()
+    uv = _ensure_uv()
+    venv = Path.home() / '.cache' / 'watch' / 'whisperx-venv'
+    sentinel = venv / '.deps-ok'
+    windows = platform.system() == 'Windows'
+    python = venv / ('Scripts/python.exe' if windows else 'bin/python')
+    executable = venv / ('Scripts/whisperx.exe' if windows else 'bin/whisperx')
+    ready = sentinel.is_file() and python.is_file() and executable.is_file()
+    if not ready:
+        if venv.is_symlink():
+            raise SystemExit('Managed WhisperX venv is a symlink; choose a regular managed directory before installing.')
+        if venv.exists():
+            shutil.rmtree(venv)  # Only this fixed, installer-owned environment.
+        venv.parent.mkdir(parents=True, exist_ok=True)
+        _install_step([uv, 'venv', str(venv), '--python', '3.12'], 'Create WhisperX Python 3.12 environment')
+        if platform.system() in ('Linux', 'Windows'):
+            _install_step([uv, 'pip', 'install', '--python', python, 'torch==2.8.0', 'torchaudio==2.8.0',
+                           '--index-url', 'https://download.pytorch.org/whl/cpu'], 'Install CPU PyTorch wheels')
+        _install_step([uv, 'pip', 'install', '--python', python, f'whisperx=={WHISPERX_VERSION}'], 'Install WhisperX')
+    # Invalidate before warm-up: an interrupted repair is always safe to rerun.
+    sentinel.unlink(missing_ok=True)
+    cfg['whisperx_bin'] = str(executable)
+    with tempfile.TemporaryDirectory(prefix='watch-warmup-') as temporary:
+        audio = Path(temporary) / 'silence.mp3'
+        _install_step(['ffmpeg', '-hide_banner', '-loglevel', 'error', '-y', '-f', 'lavfi', '-i',
+                       'anullsrc=r=16000:cl=mono', '-t', '2', '-acodec', 'libmp3lame', str(audio)], 'Create warm-up audio')
+        transcribe_audio(audio, cfg, require_ready=False)
+    resolved = run_text([str(uv), 'pip', 'list', '--python', str(python), '--format', 'json'], timeout=60)
+    if resolved.returncode:
+        raise SystemExit(f'Could not record the WhisperX install: {diagnostic(resolved.stderr)}')
+    packages = json.loads(resolved.stdout)
+    (venv / 'watch-install.json').write_text(json.dumps({'whisperx': WHISPERX_VERSION, 'model': cfg['whisperx_model'],
+                                                       'platform': platform.system(), 'packages': packages}, indent=2), encoding='utf-8')
+    sentinel.write_text(WHISPERX_VERSION + '\n', encoding='utf-8')
+    write_settings({'WATCH_WHISPER_BACKEND': 'whisperx', 'WATCH_WHISPERX_BIN': str(executable),
+                    'WATCH_WHISPERX_MODEL': cfg['whisperx_model'], 'SETUP_COMPLETE': 'true'}, CONFIG_FILE)
+    print('[setup] WhisperX is ready; packages and both model caches are warmed.', file=sys.stderr)
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument('--check', action='store_true')
+    mode.add_argument('--json', action='store_true')
+    mode.add_argument('--install-whisperx', action='store_true')
+    parser.add_argument('--backend', choices=['auto', 'whisperx', 'groq', 'openai', 'none'])
+    parser.add_argument('--detail', choices=sorted(DETAILS))
+    parser.add_argument('--engine', choices=sorted(ENGINES))
+    args = parser.parse_args()
+    try:
+        if args.check:
+            return cmd_check()
+        if args.json:
+            return cmd_json()
+        return cmd_install('whisperx' if args.install_whisperx else args.backend, args.detail, args.engine)
+    except (ConfigError, OSError, ValueError) as exc:
+        print(f'[setup] {exc}', file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    configure_stdio()
+    raise SystemExit(main())

package/skills/website-cloner/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: website-cloner
+description: >-
+  Reverse-engineer and rebuild any website — including its WebGL/WebGPU/canvas
+  shader effects — into a clean local codebase. Use this whenever the user wants
+  to clone, replicate, rebuild, reverse-engineer, or copy a website or landing
+  page, especially designy sites with animated/shader/3D hero backgrounds. This
+  is the top-level coordinator: it does recon, classifies every page surface as
+  DOM vs GPU-rendered, routes plain layout to the luckiest-website-cloner-dom sub-skill and shader
+  surfaces to the luckiest-website-cloner-shaders sub-skill, scaffolds a build target on demand,
+  composites the two tracks, and runs automated visual QA. It also produces a
+  human-readable TEARDOWN.md (stack, measured design system, every effect with
+  its exact runtime params and how it works) — pass --analyze-only to stop there.
+  Trigger on "clone this site", "rebuild this page", "make a copy of this
+  website", "reverse-engineer this landing page", "clone this but the background
+  is some WebGL thing", any pixel-accurate site reproduction, AND on analysis
+  asks: "how did they build this", "tear down this site", "site teardown",
+  "break down this page", "what stack/animations does this site use", "how does
+  this effect work", "website blueprint", "steal this website's design",
+  "/site-teardown". Provide one or more target URLs.
+argument-hint: "<url1> [<url2> ...] [--analyze-only]"
+user-invocable: true
+license: MIT. See ATTRIBUTION.md
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, AskUserQuestion
+metadata:
+  version: "1.0.0"
+  listing_id: luckiest-website-cloner
+  author: luckiest
+---
+
+# Clone Site
+
+You are cloning **$ARGUMENTS** into a clean local codebase. Your job is to be
+the **general contractor**: survey the whole building, decide which trades do
+which parts, hand each trade a precise scope, then assemble and inspect.
+
+The reason this skill exists — and why it is not just "run the DOM cloner" — is
+that a modern designy site is really **two different materials welded together**:
+
+- **DOM/CSS material** — text, layout, images, buttons, normal animations. A
+  DOM extractor reading `getComputedStyle()` reconstructs this faithfully.
+- **GPU material** — WebGL / WebGPU / canvas shader effects (the hero that
+  ripples, the 3D blob, the generative gradient). None of it exists in the DOM.
+  `getComputedStyle()` sees an empty `<canvas>`. Clone it as HTML and you get a
+  dead box where the best part of the site was.
+
+Getting a clone right is mostly getting the **routing** right: sending each
+surface to the tool that can actually see it. That routing is this skill's spine.
+
+## Sub-skills you coordinate
+
+You do not reimplement extraction. You dispatch to two sibling skills and stitch
+their output together. Read each one's `SKILL.md` before you drive it:
+
+- **`../luckiest-website-cloner-dom/SKILL.md`** — extracts DOM/CSS/assets/content section by
+  section, writes a spec file per component, dispatches parallel builders.
+- **`../luckiest-website-cloner-shaders/SKILL.md`** — evidence-gated capture-and-replay of a
+  single GPU surface (locks the surface, captures the frame with Spector.js /
+  WebGPU Inspector, builds a verified local baseline). Do NOT hand it the whole
+  page — hand it one locked canvas surface plus an output directory.
+
+If either sibling is not installed, tell the user which one is missing and stop;
+you cannot substitute the DOM track for a GPU surface or vice versa.
+
+## Pre-flight
+
+1. **Browser automation is required.** You need a browser you can drive from
+   the session — any of: the `playwright-cli` skill (recommended: it is the
+   only path with `addInitScript` preload, which makes surface routing and
+   motion capture far more reliable; see `references/playwright-cli-recipes.md`
+   for the one-call preload recipe, eval quirks, hidden-state capture, asset
+   lists), Playwright MCP, Chrome/Claude-in-Chrome MCP, or a built-in browser
+   pane with a JavaScript-eval tool (post-hoc probes + screenshots only, no
+   preload; see `references/builtin-browser-recipes.md`). If none can load the target (bot wall, auth), stop and say so —
+   this skill cannot clone from a fetch or a screenshot.
+   Build the injectable probe bundle with `node scripts/build-bundle.cjs`, inject
+   it, then evaluate `JSON.stringify(surfaceMap())` etc. For a first look use
+   `motionSummary()` (small); the full `motionProbe()`/`tokensProbe()` output
+   goes to a file — never dump it into the conversation.
+2. Parse `$ARGUMENTS` into one or more URLs; validate each and confirm it loads.
+   Multiple sites → keep each site's artifacts in its own `output/<hostname>/`.
+3. Decide the **output directory** now (default `output/<hostname>/`; never
+   build inside a notes vault or another project's source tree). Every
+   artifact — surface map, probes, specs, captures, the built project — goes
+   under it, not into the conversation.
+4. Parse `--analyze-only`. If present, the run ends after Phase 1 with
+   `TEARDOWN.md` (+ the probe JSON) as the deliverable. If the user keeps a
+   research folder, offer to copy it there with a `## Key Takeaways` section on
+   top. Don't ask first — run and report.
+
+## Phase 1 — Recon & Surface Routing (the part that makes this skill worth it)
+
+This runs BEFORE any building. Its product is a **surface map**: a list of every
+visual region tagged with what material it's made of and which track owns it.
+
+1. **Instrument, then load.** If your browser tool supports preload scripts,
+   inject `scripts/surface-map.js`'s `instrumentGetContext()` as an init script,
+   THEN navigate. This records the real context type each canvas requests —
+   ground truth for routing. If preload isn't available, navigate normally and
+   rely on the post-hoc probe (still reliable for the common case).
+2. **Let the page settle** (scroll top→bottom once so lazy canvases initialize),
+   then run `surfaceMap()` from `scripts/surface-map.js` in the page context
+   (browser MCP evaluate / Playwright `page.evaluate`). Save the JSON to
+   `output/<hostname>/surface-map.json`.
+3. **Read the routing summary.** For each surface:
+   - `WEBGL1 / WEBGL2 / WEBGPU` → **luckiest-website-cloner-shaders track**. This is a GPU effect
+     the DOM track literally cannot capture.
+   - `CANVAS2D` / `CANVAS_UNKNOWN` → inspect. Many 2D canvases are decorative
+     particle fields (luckiest-website-cloner-shaders) but some are charting libs better rebuilt
+     from data. Use judgment; default animated fullscreen 2D → luckiest-website-cloner-shaders.
+   - `VIDEO` → **luckiest-website-cloner-dom track**, re-embed the source `<video>`. Do not rebuild
+     a looping video as a canvas — that's wasted effort and looks worse.
+   - `SVG_ANIMATED` → luckiest-website-cloner-dom, but preserve the SMIL/CSS animation.
+   - everything else (all normal DOM) → **luckiest-website-cloner-dom track**.
+4. **Record the interaction model.** The surface map also fingerprints smooth
+   scroll (Lenis / Locomotive) and scroll-timeline CSS. Note these — they change
+   how luckiest-website-cloner-dom must rebuild scroll-driven sections. Confirm by scrolling: does
+   content change on its own as you scroll (scroll-driven) or only on click?
+5. **Probe the motion runtime** — run `scripts/motion-probe.js` (`motionProbe()`;
+   with `instrumentMotion()` preloaded when using playwright-cli) and save to
+   `motion.json`. This asks the live libraries for their real params instead of
+   reading a minified bundle: every GSAP tween + `ScrollTrigger.getAll()`
+   (trigger/pin/start/end/scrub/vars), WAAPI animations with keyframes, CSSOM
+   `@keyframes` + scroll-timelines, Lenis options, Swiper/Splide params,
+   SplitText wrappers, transition signatures, IO registrations + input listeners
+   (instrumented mode). `summary.animationStack` is the one-line answer to "what
+   makes this site move".
+6. **Probe the design system** — run `scripts/tokens-probe.js` (`tokensProbe()`)
+   at 1440, 768, and 390 → `tokens-<w>.json`. Frequency-ranked palette, type
+   scale, fonts + `@font-face` src, spacing rhythm, radii, shadows, z-layers,
+   breakpoints, `:root` custom props, section list with offsets, fixed chrome.
+   These values ARE the design tokens luckiest-website-cloner-dom writes in its foundation step.
+7. **Sweep** — scroll in ~viewport steps taking screenshots; hover the obvious
+   interactives; click tabs/accordions. Anything that moves but isn't explained
+   by `motion.json` gets tagged OBSERVED. Only now, if a specific effect is
+   still unexplained, read its source: take the bundle URL from
+   `read_network_requests`, `curl` it to the output dir, and `grep` around the
+   selector — never WebFetch a bundle (the summarizer drops exactly the numbers
+   you need).
+8. **Write the routing plan** to `output/<hostname>/ROUTING.md`: the section
+   topology top-to-bottom, each section's track, and for GPU surfaces their
+   selector + bounding box + guessed driver (three.js / unicorn-studio / etc.),
+   so the composite step knows exactly where each effect sits and at what z-index.
+9. **Write `TEARDOWN.md`** per `references/teardown.md` — stack, measured
+   design system, effects table, reveals with exact params, assets, build plan.
+   Every claim tagged CONFIRMED / OBSERVED / INFERRED. This is the briefing the
+   builders get and the whole deliverable of `--analyze-only`. **Stop here if
+   `--analyze-only`.**
+
+If the routing summary shows **no GPU surfaces**, this is a pure DOM clone —
+proceed with just the luckiest-website-cloner-dom track and skip the luckiest-website-cloner-shaders phase. Say so.
+
+## Phase 2 — Scaffold the build target (on demand)
+
+Only scaffold once you know what you're building. Choose the lightest substrate
+that fits what you found — don't force a heavy framework onto a static page:
+
+- Static/marketing page, GPU effects present → **Vite + vanilla/TS** (the
+  luckiest-website-cloner-shaders baselines are framework-free; Vite composites them cleanly).
+- App-like, component-heavy, needs routing/SSR → **Next.js + Tailwind** (matches
+  the luckiest-website-cloner-dom builder conventions).
+- User specified a stack → honor it.
+
+Scaffold into `output/<hostname>/site/`. Verify it builds empty before adding
+anything. Record the choice in `ROUTING.md`. (Rationale: the old template hard-
+wired Next.js for every clone; that's overkill for a static shader showcase and
+fights the framework-free shader baselines. Pick per target.)
+
+## Phase 3 — Run the two tracks
+
+**Choose the DOM strategy first.** If the target ships scope-attributed CSS
+(`data-v-*`, CSS Modules, styled-components hashes, `_ngcontent`) and the user
+wants fidelity over a maintainable codebase, take the **fidelity fast path**
+(`references/fidelity-fast-path.md`): captured post-hydration HTML + the site's
+own stylesheets + rewritten paths, rebuilding only behaviors. Validated at
+0.02–0.06% pixel diff in one pass. Otherwise run luckiest-website-cloner-dom's rebuild. State the
+choice in `ROUTING.md`.
+
+**Choose the DOM strategy first.** If the target ships scope-attributed CSS
+(, CSS Modules, styled-components hashes, ) and the user
+wants fidelity over a maintainable codebase, take the **fidelity fast path**
+(): captured post-hydration HTML + the site's
+own stylesheets + rewritten paths, rebuilding only behaviors. Validated at
+0.02–0.06% pixel diff in one pass. Otherwise run luckiest-website-cloner-dom's rebuild. State the
+choice in .
+
+Run them **concurrently** — they touch different files and don't depend on each
+other until composite. But note (from the research): decomposing into many small
+builders is a choice for **speed and edit-isolation**, not because a strong model
+can't hold the context. With a capable model, prefer **fewer, larger** builder
+agents scoped to a whole section over many tiny ones; split only when a section
+is genuinely independent (distinct card variants, separate interactive widgets).
+Over-splitting adds merge overhead and coordination cost for no fidelity gain.
+
+**DOM track:** Follow `../luckiest-website-cloner-dom/SKILL.md`. Feed it the section topology from
+`ROUTING.md`, `TEARDOWN.md`, and the probe JSON (`tokens-*.json` seeds the
+design tokens verbatim; `motion.json` gives each section's interaction model and
+exact animation params — builders reproduce those numbers, not approximations)
+plus the output dir. It produces the page shell, styled sections,
+downloaded assets, and leaves **placeholder mounts** where GPU surfaces belong
+(a positioned empty container with the right id/size/z-index from the surface
+map). It must not try to rebuild the effect itself.
+
+**Assets you can't obtain or rebuild:** some assets are cross-origin/blocked, or
+are brand identity you shouldn't copy into a learning clone. Resolve every asset
+through the ladder in `../luckiest-website-cloner-dom/references/asset-resolution.md` — REAL first,
+then reconstruct, then GENERATE a decorative substitute via the Higgsfield MCP
+(never for logos/brand/identity), then placeholder — and carry the tier labels
+into the report. This is optional: if Higgsfield isn't connected, tier 3 degrades
+to placeholder. Never let a generated asset be reported as the real one.
+
+**GPU track:** For each GPU surface, follow `../luckiest-website-cloner-shaders/SKILL.md` once,
+handing it: the locked surface selector, its bounding box, the guessed driver,
+and an output dir `output/<hostname>/effects/<surface-id>/`. It returns a
+self-contained, verified effect module (WebGL/WebGPU replay) that renders into a
+canvas you can mount.
+
+## Phase 4 — Composite
+
+Wire the GPU effect modules into the DOM shell's placeholder mounts. See
+`references/compositing.md` for the mount contract (sizing, DPR, z-index,
+pointer-events, teardown, reduced-motion). The composite is where most "looks
+wrong" bugs actually live — an effect that renders fine in isolation can sit at
+the wrong z-index, block clicks, or ignore DPR once mounted. Verify each mount
+in the live page, not just the isolated baseline.
+
+## Phase 5 — Automated Visual QA (not eyeballing)
+
+Do NOT declare done by looking at a screenshot. Run a real pixel diff — but
+diff the two materials differently, because GPU effects are **nondeterministic**
+(they animate; two screenshots never match pixel-for-pixel):
+
+- **DOM regions** → Playwright `toHaveScreenshot()` (pixelmatch under the hood),
+  original vs clone at 1440 / 768 / 390. Tune `maxDiffPixelRatio` / `threshold`
+  rather than demanding zero diff (anti-aliasing alone causes false diffs).
+- **GPU regions** → **mask them** in the DOM diff (Playwright `mask:` option) so
+  their animation doesn't swamp the result, and verify them separately: does the
+  effect render, animate, and respond to pointer/scroll like the original?
+
+See `references/visual-qa.md` for the exact harness, thresholds, masking, and
+the harness gotchas (no reducedMotion, no networkidle against Vite, compare
+section heights before pixels, diff per viewport slice).
+For every real discrepancy: trace it to the spec (was the value extracted wrong?)
+or the build (spec right, builder wrong?) and fix at the source.
+
+## Completion report
+
+- `TEARDOWN.md` path + the one-line stack summary (`motion.json › summary`)
+- Section topology and per-section routing (DOM vs which GPU track)
+- GPU surfaces found, their drivers, and replay fidelity (SOURCE / PARTIAL /
+  approximate — carry luckiest-website-cloner-shaders's honesty labels through; don't upgrade them)
+- Build substrate chosen and why
+- Visual QA: DOM pixel-diff pass rates per breakpoint + GPU verification notes
+- Known gaps (cross-origin canvases that blocked readback, effects only
+  approximated, anything the surface map flagged CANVAS_UNKNOWN)
+
+## Handoff
+
+After the completion report, **ask one question and act on it**:
+
+> "Clone verified (diff numbers above). Make it yours now? — re-skin with your
+> brand/copy/assets, three design directions, tweak panel on the pick."
+
+- **Yes** → invoke the `luckiest-website-cloner-remix` skill with this run's output directory
+  (`Skill: luckiest-website-cloner-remix`, args `<output-dir>`). It consumes TEARDOWN.md,
+  tokens-*.json, motion.json, and site/ directly and stops for the user's input
+  at its own checkpoints. From the user's side the whole thing is one command.
+- **No / later** → end with: `/luckiest-website-cloner-remix <output-dir>` re-enters at any time.
+
+Do not start re-skinning inside luckiest-website-cloner; luckiest-website-cloner ends at a verified copy
+and luckiest-website-cloner-remix owns everything after.
+## Guardrails
+
+Clone for migration, for recovering your own lost source, or for learning how a
+build works. Do not use it to pass off someone else's brand or design as your
+own, for phishing or impersonation, or against a site whose terms forbid
+reproduction. Logos, brand assets, and copy belong to their owners.
+
+Stop and ask the user before continuing if any of these are true:
+
+- The target looks like it exists to be impersonated: a bank or wallet login, a
+  checkout, an account or password page.
+- The page is behind a login, a paywall, or a bot wall. Never supply
+  credentials, cookies, session tokens, or a stored browser profile to get past
+  one, and never work around the block.
+- The page holds personal data about real people.
+
+Capture only what renders publicly. Do not read or copy credentials, cookies,
+local storage, or session storage from the target.