luckiest-co 1.0.38 → 1.0.40

package/skills/website-cloner-dom/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: website-cloner-dom
+description: >-
+  Extract and rebuild the DOM/CSS layer of a web page — layout, typography,
+  colors, spacing, real content, assets, and normal interactions — into clean
+  components, section by section, from exact getComputedStyle() values rather
+  than guesses. This is the DOM/CSS track: it deliberately does NOT handle
+  WebGL/WebGPU/canvas shader surfaces (those go to luckiest-website-cloner-shaders). Usually
+  driven by the luckiest-website-cloner coordinator, but can be used directly when the user
+  wants to rebuild a page's markup/styling and there are no GPU-rendered
+  effects. Trigger on "rebuild this section", "extract the CSS/layout", "clone
+  the markup and styling of this page", or the DOM half of a full site clone.
+argument-hint: "<url> | <output-dir with surface-map.json + ROUTING.md>"
+user-invocable: false
+license: MIT. See ATTRIBUTION.md
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+metadata:
+  version: "1.0.0"
+  listing_id: luckiest-website-cloner-dom
+  author: luckiest
+---
+
+# DOM Clone
+
+Rebuild the DOM/CSS layer of a page as clean components whose every value is
+**measured, not estimated**. The difference between a clone that reads as
+"pixel-perfect" and one that reads as "AI slop" is almost entirely whether the
+spacing, type scale, and colors are the site's real computed values or an
+approximation. So the whole method is built to remove guessing.
+
+**Scope boundary — read this first.** This track handles DOM/CSS only. Any
+`<canvas>` painting WebGL/WebGPU/2D pixels is invisible to `getComputedStyle()`
+and belongs to `luckiest-website-cloner-shaders`. When you meet a GPU surface (the surface map
+tags them, or you see a `<canvas>` you can't style your way into), do NOT rebuild
+it — leave a **placeholder mount** (below) and move on. Rebuilding a shader as
+HTML is the classic failure that makes a clone look empty.
+
+## Inputs
+
+- Driven by luckiest-website-cloner: you get an output dir containing `surface-map.json` and
+  `ROUTING.md`. Build only the sections routed to the DOM track; leave mounts for
+  GPU surfaces.
+- Standalone: you get a URL. Do a quick recon first (screenshots + the interaction
+  sweep below). If you spot GPU `<canvas>` surfaces, tell the user those need the
+  luckiest-website-cloner-shaders track and build the DOM around them.
+
+Requires a browser MCP (Chrome/Playwright/Puppeteer). Keep large extraction
+artifacts in the output dir, not the conversation.
+
+## The method: extract → spec → build → verify
+
+### 1. Foundation first (sequential, do it yourself)
+
+Nothing can be built until the shared ground exists, because every later
+component depends on it:
+
+- **Design tokens** — run `../luckiest-website-cloner/scripts/tokens-probe.js`
+  (`tokensProbe()`) at 1440/768/390 if the coordinator hasn't already left
+  `tokens-*.json` in the output dir. Its frequency-ranked palette, type scale,
+  spacing, radii, shadows, and `:root` custom props ARE the tokens — write them
+  as CSS variables / Tailwind theme, keeping the site's own `--names` when it
+  has them. Colors and fonts wrong here poison every component.
+- **Motion params** — likewise take `motion.json` (`../luckiest-website-cloner/scripts/
+  motion-probe.js`) as the source for every GSAP/ScrollTrigger/Lenis/WAAPI
+  value a spec needs. A spec that says `scrub: 1.2, start: "top top", end:
+  "+=200%"` came from the runtime; one that says "scrubs on scroll" is a guess.
+- **Fonts** — identify actual `font-family` on headings/body/labels; wire up the
+  same families (self-hosted or Google) so metrics match.
+- **Global assets** — favicons, logos, and site-wide images to the project.
+  Resolve each through the asset ladder in `references/asset-resolution.md`:
+  download the REAL file first; only fall back to reconstructing, generating
+  (Higgsfield, for decorative assets — never brand identity), or a placeholder,
+  and label which tier was used. This keeps the clone honest about what's real.
+- **Global behaviors** — smooth-scroll library (Lenis/Locomotive), scroll-snap,
+  global keyframes. See `references/interaction-fingerprints.md` to detect and
+  reproduce these; they change how sections must be built.
+
+Verify the empty shell builds before going further.
+
+### 2. Extract each section with exact values
+
+For each DOM section top-to-bottom, use the browser to capture — don't hand-
+measure:
+
+- A section screenshot (for the builder's reference and later QA).
+- **Computed styles** for every meaningful element via `getComputedStyle()` —
+  real px/color/weight values, not "looks like `text-lg`".
+- **Real content** — verbatim text, alt text, and every image/`<img>`/background
+  image in the section, including **layered/overlay** images (a hero is often a
+  background + a foreground mockup + an icon; miss the overlay and it looks bare).
+  Resolve each asset through `references/asset-resolution.md` (REAL → RECONSTRUCT
+  → GENERATE → PLACEHOLDER), tagging any that couldn't be downloaded.
+- **All states, not just the default** — for tabs/accordions click each and
+  record per-state content; for scroll- or hover-triggered changes, capture the
+  before AND after computed styles and the transition (duration/easing) plus the
+  exact trigger. See `references/interaction-fingerprints.md`.
+
+### 3. Write a spec file — the contract
+
+Write one spec per section to `<output>/specs/<section>.spec.md` BEFORE building.
+This is the contract between measurement and construction: the builder works from
+the spec, not from its memory of a browser session, so it can't drift into
+guessing. A spec has: target file, screenshot path, **interaction model**
+(static / click / scroll / hover / time), exact computed styles per element,
+per-state content, assets with local paths, verbatim text, and responsive
+behavior at 1440 / 768 / 390. If a builder would have to invent any value, the
+spec isn't done yet.
+
+For GPU surfaces in this section, the spec says only: **placeholder mount** — a
+positioned empty container with the id, size, z-index, and pointer-events from
+the surface map, for luckiest-website-cloner-shaders to fill later. Nothing more.
+
+### 4. Build — size agents to the model, not to dogma
+
+Dispatch builders that each receive their spec inline (never "go read the spec").
+On agent granularity: splitting a page into many tiny builders is a choice for
+**speed and edit-isolation**, not a fidelity requirement — a capable model holds
+a whole section's spec fine. So prefer **one builder per section** by default,
+and split further only when a section contains genuinely independent pieces
+(three distinct card variants, separate interactive widgets) that benefit from
+parallel isolation. Over-splitting just adds merge and coordination cost.
+
+If builders run in parallel and might touch shared files, isolate them (git
+worktrees or separate output subtrees) and merge with the section topology in
+hand. Each builder verifies its own typecheck/build before finishing.
+
+### 5. Verify with a real diff
+
+After assembly, run an automated pixel diff (Playwright `toHaveScreenshot()`),
+original vs clone, at all three breakpoints — **masking any GPU placeholder
+regions** so their emptiness/animation doesn't dominate the result. Tune
+`maxDiffPixelRatio` rather than demanding zero diff (anti-aliasing causes false
+positives). For each real discrepancy, decide: was the spec value wrong
+(re-extract, fix spec) or did the builder ignore a correct spec (fix component)?
+Fix at the source, not with a compensating fudge.
+
+## Output
+
+- `site/` (or the coordinator's chosen substrate) with styled sections + mounts
+- `specs/*.spec.md` — one per section, the audit trail
+- Downloaded assets under the project's public dir
+- QA diff results per breakpoint + list of placeholder mounts left for GPU track
+
+## What not to do
+
+- Don't clone from a screenshot; extract the real DOM/CSS/content.
+- Don't rebuild a `<canvas>` shader/3D effect as HTML — leave a mount.
+- Don't approximate a computed value you could have measured.
+- Don't freeze a `<video>` or animated SVG to a static image — re-embed / keep it.
+- Don't build a click-based UI when the original is scroll-driven; settle the
+  interaction model before building (it's a rewrite, not a tweak, to change later).
+
+## 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.

package/skills/website-cloner-remix/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: website-cloner-remix
+description: >-
+  Turn a cloned (or any measured) website into YOUR site: re-skin it with your
+  brand, copy, and assets; generate three deliberately different design
+  directions as token/motion/shader overrides and render them side by side;
+  then put a live tweak panel on the direction you pick. This is the step after
+  /luckiest-website-cloner — it consumes the clone's TEARDOWN.md, tokens-*.json, motion.json,
+  and site/ and never re-probes. Use when the user says "/remix", "remix this
+  clone", "make this mine", "re-skin this", "give me three versions of this
+  site", "variations of this design", "add a tweak panel", "let me tune the
+  colors/spacing/motion", or has just approved a clone and wants to move from
+  copying to owning. NOT for cloning (use /luckiest-website-cloner) and NOT for building a
+  site from scratch.
+argument-hint: "<clone-dir or site-dir> [--phase reskin|directions|panel]"
+user-invocable: true
+license: MIT. See ATTRIBUTION.md
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+metadata:
+  version: "1.0.0"
+  listing_id: luckiest-website-cloner-remix
+  author: luckiest
+---
+
+# Remix Site
+
+A clone is a **measured design system plus a proven structure**. The teardown
+already enumerated every knob — palette, type scale, spacing rhythm, motion
+params, shader props, section order. Remixing means changing what flows
+through those knobs, in three phases that each **stop for the user's call**
+(unlike `/luckiest-website-cloner`, which runs autonomously):
+
+1. **Re-skin** — swap the three things that make it *theirs*: copy, brand, hero
+   assets. Output: a de-branded template. Non-negotiable and first.
+2. **Directions** — three deliberately different combinations of the big forks
+   (palette mood × type pairing × hero treatment × motion personality), rendered
+   side by side. The user picks one.
+3. **Tweak panel** — the chosen direction's 10–15 real knobs made live in the
+   page, with permalink state. Not 80 sliders; the ones they'll keep turning.
+
+`--phase` runs a single phase (e.g. a second re-skin for another client, or a
+panel on a site that never came from the cloner).
+
+## Inputs (the luckiest-website-cloner contract)
+
+Resolve `$ARGUMENTS` to a directory and look for:
+
+| File | Used for |
+|---|---|
+| `TEARDOWN.md` | stack, effects table, assets table, known gaps |
+| `tokens-*.json` | the measured design system — the knob list |
+| `motion.json` | exact animation params — the motion knobs |
+| `surface-map.json` | which regions are GPU (shader knobs live here) |
+| `site/` | the rebuilt project (Vite/Next) |
+| `assets/` or `site/public/assets/` | original assets, tiered |
+
+If only `site/` exists (not a clone), run `tokens-probe.js` and
+`motion-probe.js` from `../luckiest-website-cloner/scripts/` against the dev server once to
+produce the JSON — then proceed. Never re-probe when the JSON is present.
+
+## Phase 0 — Tokenize (mechanical, do it before anything)
+
+The clone's CSS is full of literal values (`#1f3bff`, `32.04px`). Nothing can be
+varied until those literals become variables. Run:
+
+```bash
+node scripts/tokenize-css.cjs <site>/src/<site>.css <tokens-1440.json> <site>/src
+```
+
+It rewrites the stylesheet so every measured token value goes through
+`var(--rx-<role>, <original>)` and writes `remix-tokens.css` (the defaults). If
+the site already exposes its own `--vars` (Nuxt/Vue sites often do), the script
+aliases those instead of inventing new names — keep the site's vocabulary.
+
+Route motion through a config too: the clone's behavior JS should read from
+`window.__remix.motion` (seeded from `motion.json` → `remix-motion.js`), and
+shader mounts from `window.__remix.shaders`. If the builder hard-coded them,
+hoist now. This is the one code change remix makes to the clone — everything
+after is data.
+
+Verify the site still renders identically (`qa/diff.mjs` against itself before
+/after: must be 0%). **Show the user the knob list** (`remix/knobs.json`) and
+stop: "These are the N things we can turn. Re-skin next?"
+
+## Phase 1 — Re-skin
+
+Ask for, in one batch: **brand** (name, logo file or "generate a placeholder
+mark", primary + accent colors or "derive from logo"), **copy** (a doc/URL to
+pull from, bullet points to expand, or "placeholder in their structure"), and
+**hero/section assets** (files, or "generate").
+
+Then:
+- **Copy** — replace every text node section by section, keeping the
+  original's *shape* (eyebrow / headline / sub / CTA / card counts). Headline
+  lengths matter for layout: match ±20% characters or the hero reflows. Note
+  any overflow in the report.
+- **Brand** — logo into the header/footer slots; primary/accent into
+  `remix-tokens.css`; favicon/OG.
+- **Assets** — resolve through `../luckiest-website-cloner-dom/references/asset-resolution.md`
+  with the roles flipped: the original's REAL assets are now the thing to
+  *remove*. Decorative (hero background, textures, ambient imagery) →
+  GENERATE via Higgsfield using the original's composition as the brief (aspect,
+  subject placement, mood) — see `references/reskin.md` for the brief
+  template. Identity (their logo, their people, their product shots) → must be
+  replaced, never kept. Fonts: if the original's are commercially licensed,
+  swap to an open pairing with matching metrics (`references/reskin.md` has
+  the lookup); if open, keep.
+- **Remove** analytics, their API endpoints, their links.
+
+Render, screenshot the hero + two sections, **stop**: "This is the template
+with your brand. Directions next?"
+
+## Phase 2 — Three directions
+
+**Ask first, one batch, before touching anything** (this is the question that
+decides whether the directions are coats of paint or actually different sites):
+
+1. **Amplitude** — *subtle* / *medium* / *big*?
+   | | moves | layer |
+   |---|---|---|
+   | subtle | palette, accent, motion timing, shader colors | `overrides.json` only |
+   | medium | + surface (radius/border/shadow), density (spacing ×), type scale + weights, grain | + `patch.css` |
+   | big | + hero treatment (photo → type-only / GPU-led / engraving), layout (grid ↔ editorial ↔ bento), section order, nav style, own hero asset per direction | + `patch.js` + generated assets |
+   If unsure, recommend **medium** — subtle reads as "same site, different coat"
+   side by side; big costs generations.
+2. **Anchors** — "any aesthetics in mind?" *none* / *describe it* / *reference
+   sites or images* / *pull from my taste library* (`/taste-vault`). With none:
+   nearest-legit / opposite / wildcard from `references/directions.md`. With
+   anchors: one direction per anchor, built *toward* it, and say which fork each
+   anchor maps to so the user sees the translation.
+
+Not five. Five converge; three deliberately different forks give a real choice.
+Each direction is **data + an optional patch layer**, scoped to
+`:root[data-rx="<slug>"]` so directions never collide:
+
+```
+remix/directions/<slug>.json
+{ "name": "...", "thesis": "one line",
+  "tokens": { "--rx-accent": "#…", "--rx-font-display": "…", "--rx-space-unit": "…" },
+  "motion": { "reveal": { "y": 22, "duration": 0.7, "ease": [.16,1,.3,1] }, "stagger": 0.08 },
+  "shaders": { "hero": { "colorFront": "#…", "intensity": 0.5 } },
+  "assets": { "hero-bg": "generated/<slug>-hero.jpg" } }
+remix/directions/<slug>.patch.css   (medium+)  surface / density / type scale under :root[data-rx="<slug>"]
+remix/directions/<slug>.patch.js    (big)      structural: hero variant, section order, layout classes
+```
+
+`apply-overrides.cjs` picks up `<slug>.patch.css` / `.patch.js` next to the
+JSON automatically. Patches must be **additive and scoped** — never edit the
+base HTML/CSS for a direction, or the other two break.
+
+Derive the three from the original's *axes*, not from taste alone — see
+`references/directions.md` for the fork table (palette mood, type pairing, hero
+treatment, density, motion personality) and the rule that each direction must
+differ on **at least three** forks. If the user has a taste library
+(`/taste-vault` or reference images), pull the directions from there. Generate
+per-direction hero assets only for the decorative layer.
+
+Apply each with `node scripts/apply-overrides.cjs <site> remix/directions/<slug>.json`
+(writes `remix-tokens.<slug>.css` + `remix-motion.<slug>.js`; the site loads
+the active set via `?rx=<slug>`). Then `node scripts/gallery.cjs <site>` writes
+`<site>/directions.html`: all directions **live side by side in iframes** (real
+shaders + motion), synced scroll, click-a-name fullscreen, and a *pick* button
+that stores the choice in `localStorage.rx-pick`. Open it in the user's browser
+(this is the deliverable — not a static contact sheet), and also render
+`remix/directions.jpg` for the report. **Stop** with the URL and one line per
+direction: thesis + what changed. The user picks (read `rx-pick` or ask).
+
+## Phase 3 — Tweak panel
+
+On the pick only. Choose **10–15 knobs** from `knobs.json` — the ones that
+matter for *this* direction (accent, display font size base, section spacing
+unit, radius, reveal distance/duration/ease, stagger, shader intensity/colors,
+hero gradient angle, grain opacity). Write `remix/panel.json`
+(`references/tweak-panel.md` has the schema: type, range, step, default, CSS
+var or motion/shader path) and inject `scripts/tweak-panel.js` into the site.
+
+The panel: fixed, collapsible, grouped (Color / Type / Space / Motion / GPU),
+writes CSS vars live, pokes `window.__remix` for motion/shader knobs and
+re-renders the affected mount, serializes state into `#rx=` so a URL is a
+permalink, and has Copy JSON / Reset / Export-as-direction. Keyboard: `` ` ``
+toggles it. It is **dev-only** — stripped from the production build.
+
+Verify: every knob visibly changes the page, permalink round-trips, reset
+returns to the direction's defaults. Screenshot with the panel open.
+
+## Completion report
+
+- Template: what was replaced (copy sections, brand slots, assets by tier —
+  GENERATED assets listed), fonts kept/swapped and why
+- Directions: the contact sheet + the three theses + which was picked
+- Panel: knob list, permalink example
+- Still theirs: anything structural you kept verbatim that the user should
+  know about (section order, interaction patterns) — a remix is legitimate
+  because the *expression* is new; say plainly what the skeleton still owes
+  to the original
+
+## Guardrails
+
+Phase 1 is mandatory before anything ships: no remix leaves with the
+original's logo, copy, people, product imagery, or licensed fonts. If the user
+asks to skip re-skinning and just "change the colors", say why that's still
+their site and do Phase 1 first.

package/skills/website-cloner-shaders/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: website-cloner-shaders
+description: >-
+  Extract, reproduce, and locally replay a single WebGL / WebGPU / Canvas /
+  shader / animated-3D visual effect from a web page — the GPU-rendered surface
+  that DOM/CSS cloning is blind to. Use whenever a page has a WebGL/WebGPU/canvas
+  shader background, animated 3D hero, generative gradient, particle field, or
+  Unicorn Studio / Spline / Three.js effect that must be captured and rebuilt as
+  a runnable local module. This is the GPU track of a site clone (driven by
+  luckiest-website-cloner) but also stands alone. Trigger on "extract this shader", "clone the
+  WebGL background", "port this canvas effect", "rebuild this animated hero",
+  "reproduce this Three.js scene locally". NOT for ordinary DOM/CSS cloning
+  (use luckiest-website-cloner-dom).
+argument-hint: "<url> | <locked surface: selector + rect + driver + output-dir>"
+user-invocable: false
+license: MIT. See ATTRIBUTION.md
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+metadata:
+  version: "1.0.0"
+  listing_id: luckiest-website-cloner-shaders
+  author: luckiest
+---
+
+# Shader Extract
+
+Capture one GPU-rendered surface and rebuild it as a verified, runnable local
+effect module. The governing principle — inherited from the vendored engine this
+skill wraps — is **evidence before implementation**: capture what the page's GPU
+pipeline actually does (shaders, uniforms, pass order, textures, timing) and
+match it, rather than eyeballing the visual and hand-tuning a lookalike. A
+lookalike drifts; a capture-matched baseline is faithful and honest about its
+gaps.
+
+## This skill = intake adapter + a vendored evidence-gated engine
+
+The heavy machinery lives in **`vendor/web-shader-extractor/`** — an
+evidence-gated state machine (surface lock → source/runtime trace → capture →
+verified baseline → projectize) by lixiaolin94 (MIT; see `ATTRIBUTION.md`). Do
+not reimplement it. This wrapper does two things the vendored engine assumes were
+done elsewhere:
+
+1. **Intake** — accept a *pre-locked* surface from the luckiest-website-cloner coordinator so
+   you skip straight to capture instead of re-scouting the whole page.
+2. **Capture backends** — make the concrete, research-verified capture tools
+   explicit (`references/capture-backends.md`): **Spector.js** for WebGL1/2 and
+   **WebGPU Inspector** for WebGPU. These are what actually recover a frame; the
+   vendored policy files describe the *discipline*, these describe the *tools*.
+
+## Router: how you were invoked
+
+**Driven by luckiest-website-cloner (common):** you receive a locked surface — selector,
+bounding box, guessed driver (three.js / unicorn-studio / spline / regl / raw
+WebGL), and an output dir like `output/<host>/effects/<surface-id>/`. The surface
+is already attributed, so skip scouting. Go straight to:
+
+1. Read `vendor/web-shader-extractor/SKILL.md` and its `references/replay-policy.md`
+   — that is the operating manual for capture → baseline → projectize.
+2. Pick the capture backend by surface type (`references/capture-backends.md`):
+   WEBGL1/2 → Spector.js; WEBGPU → WebGPU Inspector.
+3. Run the vendored state flow from `CAPTURE_MINIMUM_TRUTH` onward, writing
+   evidence and the baseline into the given output dir.
+4. Return a **mount-contract module** (see below) plus the honesty label.
+
+**Standalone (user hands you a URL):** you must lock the surface first. Run the
+full vendored flow from `INTAKE` (read `vendor/web-shader-extractor/SKILL.md`).
+The `luckiest-website-cloner` script `scripts/surface-map.js` is a fast way to enumerate and
+classify canvases if you want a head start, but the vendored `TARGET_LOCK` gate
+is authoritative.
+
+## Non-negotiables (carried from the vendored engine)
+
+- **Honest labels.** Every implementation-critical fact is `SOURCE`, `PARTIAL`,
+  or `GUESS`; unlabeled = `GUESS`. The final module carries a fidelity verdict.
+  Never quietly upgrade a `BEHAVIOR_REBUILD` (lookalike) to sound like a source
+  replay.
+- **No compensation tuning.** Don't nudge brightness, speed, offsets, noise
+  scale, or color to mask missing pipeline evidence. A visible gap gets recorded
+  in `known-gaps.md`, not fudged away.
+- **Baseline before projectize.** Get a faithful, verified capture-baseline
+  running first; only then refactor it into an editable module. Don't overwrite a
+  verified baseline for cleanup.
+- **Cross-origin honesty.** If the canvas is cross-origin/tainted and pixel or
+  shader readback is blocked, say so and fall back to a captured poster frame —
+  don't invent a shader you couldn't read.
+
+## Output contract (so luckiest-website-cloner can mount it)
+
+Beyond the vendored `output/` layout (capture-baseline, editable-project,
+qa-report, known-gaps), expose the effect through the mount lifecycle the
+coordinator composites against:
+
+```js
+export function mount(canvasEl, opts) { /* start renderer + rAF loop */ return handle }
+export function unmount(handle)        { /* cancel rAF, loseContext, free GPU */ }
+export function resize(handle, w, h, dpr) { /* resize drawing buffer + viewport */ }
+```
+
+Also emit a **poster frame** (a captured still) as a fallback for reduced-motion
+and for the case where reconstruction only reached poster fidelity. Report the
+fidelity label so the coordinator carries it into the final clone report
+unchanged.
+
+## Where to read next
+
+- `references/capture-backends.md` — Spector.js (WebGL) and WebGPU Inspector
+  (WebGPU): what each captures, how to drive it, what's reliable vs guesswork.
+- `vendor/web-shader-extractor/SKILL.md` — the full state machine + reference
+  router (surface discovery, target lock, evidence policy, replay policy, QA,
+  Three.js/TSL reconstruction, Unicorn Studio / shaders.com adapters).
+- `ATTRIBUTION.md` — upstream authorship and MIT license.
+
+## 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.