pixel-perfect-kit 0.1.0

package/CLONE-ALOYOGA-HEADER.md

@@ -0,0 +1,76 @@
+# Prompt — clone the aloyoga.com header, pixel-perfect
+
+Hand this to an agent that has this kit's `tools/` available and a browser it can
+drive (or DevTools access). It is self-contained.
+
+---
+
+Build a **pixel-perfect clone of the header at https://www.aloyoga.com/**, measured
+at **1728px** viewport width, as a component in my project (`components/Header.tsx`;
+create it from scratch). This is a study/clone build — header **typography and
+iconography** are the target.
+
+**Before writing any code, read these and follow them exactly:**
+`PLAYBOOK.md`, `tools/RUNBOOK.md`, `README.md`, and `LEARNINGS.md`. The rules there
+override any assumption you have.
+
+**Method — measure the LIVE site, match what it actually renders:**
+
+1. **Discover the fonts — don't assume any family.** First read the live DOM to find
+   what the header actually uses: on aloyoga.com's DevTools console inspect the
+   computed `font-family` of the header text elements (e.g.
+   `getComputedStyle(document.querySelector('header a')).fontFamily`) and list the
+   `@font-face` families the page loads. Then extract exactly those:
+   `extractFonts(/<family-you-found>/i)` (or `extractFonts()` for all, then keep the
+   header ones). Do not hard-code a font name from memory — the family is whatever the
+   live site reports.
+
+2. **Extract the rest of the real assets (never redraw or retype).** Run
+   `extractIcons('header')`; capture the logo/wordmark `<svg>` and any header rasters
+   by their real URLs. Self-host the woff2s; use the icons' **exact** captured
+   data-URIs. If a header element renders a `font-weight` **heavier than any real face
+   the site shipped** (a synthesized/faux-bold), reproduce that synthesis over the
+   real max-weight face — do not substitute a different/heavier font.
+
+3. **Measure the live DOM, not a spec doc.** Capture every header element's complete
+   box at 1728px: geometry; the **text-glyph box via `Range`** (not the element box);
+   the **painted glyph** for icons/logo (SVG bbox, or the background element **plus
+   its `background-position`** — never the clickable wrapper); the full box-model; and
+   the font **including `line-height`, `letter-spacing`, `color`, and `underline`**.
+   The visible marks don't co-center — measure where each one actually paints.
+
+4. **Build to those measurements**, then verify — never from a screenshot.
+
+**Verification is the gate (this is what "done" means):**
+
+- Capture both pages at the **same 1728px width** (see `tools/RUNBOOK.md` for the fast
+  sequence: clone → `pxSend`; live CSP → inject source directly + `pxStash`/`pxRead`,
+  never `fetch`+`eval`).
+- Loop:
+  ```sh
+  node tools/pixel-diff.js live.json clone.json --visual
+  ```
+  Fix each ❌ and re-run **until it exits 0**. Then run strict
+  (`node tools/pixel-diff.js live.json clone.json`) and **fix or explicitly document**
+  every structural delta (Ground rule 4) — a colour / `underline` / `visibility` row
+  is never "structural."
+- **Close coverage:** auto-enumerate every painted element in the header band (own
+  text, background-image, or `<svg>`) and add a `pxTargets` entry for each one that
+  has none; re-diff. Exclude off-screen (x<0), `display:none`, and flyout panels below
+  the bar. The coverage list must end **empty** — a green table only proves the
+  elements you measured.
+
+**If a human (or you) later spots something off** — a wrong colour, a missing
+underline, a shifted glyph — do **not** guess the property. Run the human-flagged
+loop from `PLAYBOOK.md` Phase 6:
+```sh
+# pxInspect({text:"..."}) on live + clone → el_live.json / el_clone.json
+node tools/pixel-diff.js --inspect el_live.json el_clone.json
+```
+The **PAINT** bucket is the exact fix list; apply those values and re-run until the
+paint bucket is empty (exit 0).
+
+**Definition of done — paste the proof:** `--visual` exits 0 with every header
+element covered, the strict run's structural deltas are each fixed or documented, and
+you paste the final passing diff output (real measured numbers, not prose). Do not
+claim "pixel-perfect" from anything but a diff that exits 0.

package/CLONE-ANY-HEADER.md

@@ -0,0 +1,106 @@
+# Prompt template — clone any site's header, pixel-perfect
+
+Reusable template. Fill in the three placeholders below (or tell the agent their
+values), then hand the file to an agent that has this kit's `tools/` available and a
+browser it can drive (or DevTools access). It is otherwise self-contained.
+
+**Fill in:**
+- `{{URL}}` — the live page to clone, e.g. `https://www.example.com/`
+- `{{WIDTH}}` — the measurement viewport width in px, e.g. `1728`
+- `{{OUTPUT_PATH}}` — where to create the component, e.g. `components/Header.tsx`
+
+---
+
+Build a **pixel-perfect clone of the header at {{URL}}**, measured at **{{WIDTH}}px**
+viewport width, as `{{OUTPUT_PATH}}` (create it from scratch). This is a study/clone
+build — header **typography and iconography** are the target.
+
+> **Pick the build strategy first (LEARNINGS #19).** If `{{OUTPUT_PATH}}` is a standalone
+> clone page (e.g. `targets/<name>/clone/index.html`), **build by capture** — capture the
+> settled live DOM (`pxSendDom`) and run `ppk capture-build <name>`; it inherits live's
+> doctype and drawing techniques by construction, then verify with the gates below as
+> usual. The measured-rebuild method that follows is for when the output is a **component
+> in your own stack** (like a `.tsx` file) that capture can't express.
+
+**Before writing any code, read these and follow them exactly:**
+`PLAYBOOK.md`, `tools/RUNBOOK.md`, `README.md`, and `LEARNINGS.md`. The rules there
+override any assumption you have.
+
+**Method — measure the LIVE site, match what it actually renders:**
+
+1. **Discover the fonts — don't assume any family.** First read the live DOM to find
+   what the header actually uses: on {{URL}}'s DevTools console inspect the computed
+   `font-family` of the header text elements (e.g.
+   `getComputedStyle(document.querySelector('header a')).fontFamily`) and list the
+   `@font-face` families the page loads. Then extract exactly those:
+   `extractFonts(/<family-you-found>/i)` (or `extractFonts()` for all, then keep the
+   header ones). Do not hard-code a font name from memory — the family is whatever the
+   live site reports.
+
+2. **Extract the rest of the real assets (never redraw or retype).** Run
+   `extractIcons('header')`; capture the logo/wordmark `<svg>` and any header rasters
+   by their real URLs. Self-host the woff2s; use the icons' **exact** captured
+   data-URIs. If a header element renders a `font-weight` **heavier than any real face
+   the site shipped** (a synthesized/faux-bold), reproduce that synthesis over the
+   real max-weight face — do not substitute a different/heavier font.
+
+3. **Measure the live DOM, not a spec doc.** Capture every header element's complete
+   box at {{WIDTH}}px: geometry; the **text-glyph box via `Range`** (not the element
+   box); the **painted glyph** for icons/logo (SVG bbox, or the background element
+   **plus its `background-position`** — never the clickable wrapper); the full
+   box-model; and the font **including `line-height`, `letter-spacing`, `color`,
+   `-webkit-font-smoothing`, and `underline`**. The visible marks don't co-center —
+   measure where each one paints. The diff engine already captures the two marks that
+   used to slip a green sweep — **`font.smoothing`** (`-webkit-font-smoothing`:
+   `antialiased` vs `auto` changes perceived weight while `font-weight` matches) and the
+   **underline as a box** (`underline.{thickness,x,width,top,bottom}`, taken off whichever
+   element draws it — often an **ancestor** `border-bottom`, not the text) — and
+   `--visual` compares both; trust the diff on them. Set your clone root to
+   `antialiased`/`grayscale`. What you still own: **reproduce the drawing technique**
+   (redraw the underline as that same `border-bottom` on a same-sized box so its Y
+   *emerges* from the box model — never a hand-tuned offset, which rasterises unlike a
+   real border and fails a flicker compare even at ~0.01px), and apply the same
+   box-not-boolean principle by hand to any mark the tool doesn't special-case
+   (`box-shadow`, `outline`).
+
+4. **Build to those measurements**, then verify — never from a screenshot.
+
+**Verification is the gate (this is what "done" means):**
+
+- Capture both pages at the **same {{WIDTH}}px width** (see `tools/RUNBOOK.md` for the
+  fast sequence: clone → `pxSend`; live CSP → inject source directly + `pxStash`/`pxRead`,
+  never `fetch`+`eval`).
+- Loop:
+  ```sh
+  node tools/pixel-diff.js live.json clone.json --visual
+  ```
+  Fix each ❌ and re-run **until it exits 0**. Then run strict
+  (`node tools/pixel-diff.js live.json clone.json`) and **fix or explicitly document**
+  every structural delta (Ground rule 4) — a colour / `underline` / `visibility` row
+  is never "structural."
+- **Close coverage:** auto-enumerate every painted element in the header band (own
+  text, background-image, or `<svg>`) and add a `pxTargets` entry for each one that
+  has none; re-diff. Exclude off-screen (x<0), `display:none`, and flyout panels below
+  the bar. The coverage list must end **empty** — a green table only proves the
+  elements you measured.
+
+**If a human (or you) later spots something off** — a wrong colour, a missing
+underline, a shifted glyph — do **not** guess the property. Run the human-flagged
+loop from `PLAYBOOK.md` Phase 6:
+```sh
+# pxInspect({text:"..."}) on live + clone → el_live.json / el_clone.json
+node tools/pixel-diff.js --inspect el_live.json el_clone.json
+```
+The **PAINT** bucket is the exact fix list; apply those values and re-run until the
+paint bucket is empty (exit 0). Two rules that turn a multi-round flag into one fix:
+**resolve the element that actually *paints* the mark** (if the paint bucket is empty
+but it still looks wrong, you inspected the text when an **ancestor** draws it — inspect
+the ancestor's box: `top`/`height`/`box-sizing`/`border-bottom`), and **fix the whole
+mark by reproducing its box model + technique in one shot** (a decoration's thickness,
+width, offset, and drawing element together) rather than nudging the one facet named.
+Then flicker/overlay the two at 1:1 — a technique mismatch survives a green number.
+
+**Definition of done — paste the proof:** `--visual` exits 0 with every header
+element covered, the strict run's structural deltas are each fixed or documented, and
+you paste the final passing diff output (real measured numbers, not prose). Do not
+claim "pixel-perfect" from anything but a diff that exits 0.

package/CLONE-ANY-SITE.md

@@ -0,0 +1,120 @@
+# Prompt template — clone a whole site (or page), one shot, human-approved
+
+The ONE-SHOT pipeline: hand this to an agent and wait; the deliverable comes back
+pixel-perfect **with receipts** — every gate green, in order, and a real human's
+approval recorded as the `human` phase. The operator's only job is to have run
+`npx cpyany setup` once (PingHumans auth) and have `cloudflared` installed.
+
+**Fill in:**
+- `{{URL}}` — the live page to clone, e.g. `https://www.example.com/`
+- `{{WIDTH}}` — the measurement viewport width in px, e.g. `1512`
+- `{{NAME}}` — the target name, e.g. `example`
+
+---
+
+Produce a **pixel-perfect, human-approved clone of the page at {{URL}}** at
+**{{WIDTH}}px**, as the standalone target `targets/{{NAME}}/clone/`. Work
+unattended until `ppk gate {{NAME}} done` exits 0 — that is the definition of
+done, and it now includes a PingHumans human approval. Do not stop at "the
+numbers match": stop when the receipts say a human agreed.
+
+**Before writing any code, read and follow exactly:** `PLAYBOOK.md`,
+`tools/RUNBOOK.md`, `LEARNINGS.md`, `WORKFLOW.md`. Their rules override any
+assumption you have.
+
+**Work the FAST loop (RUNBOOK "The fast fix loop") — the reviewer answers in
+minutes, so the agent is the bottleneck, not the human:**
+- Start `node tools/sink.js` and `node harness/tunnel.js --sink` (background)
+  FIRST — every capture (pxSend/pxSendDom/pxBehaviorSend) then delivers in one
+  call through the sink tunnel; stash/chunked-read is a last resort.
+- After a scoped fix, re-capture only the affected targets and fold them in with
+  `node tools/merge-snapshot.js` — full N-target re-captures are for the final
+  pass only (the done gate enforces one clean full capture at the end).
+- When a fix's acceptability is uncertain (contested content, blur quality,
+  "is this what they meant?"), spend a ~$0.05 micro-poll —
+  `ppk human {{NAME}} poll "…" --choices "Yes,No"` — BEFORE burning a full test
+  round on it. Polls advise; only full rounds satisfy the human gate.
+- **On every REFILE, pass `--changelog "what changed since the last review"`** —
+  a reviewer who isn't told what changed reviews blind ("did you fix
+  anything?" is a wasted round). And **never escalate a reviewer's comment
+  out of the loop**: respond with a fix or an in-round explanation and
+  refile — the verdict is the only decision channel.
+- **ALL human contact goes through `ppk human {{NAME}} …` — NEVER call the
+  PingHumans/cpyany MCP tools directly.** Direct calls are invisible to the
+  workflow (no recorded round → the human gate can't verify the answer) and
+  skip the kit's template. And know the two shapes: **a poll may reference ONE
+  side only** (a live-observation or taste question — "on the real page, does
+  X scrub?"); any question naming BOTH the clone and the live page is a
+  COMPARISON and must be a **filed test** (`ppk human {{NAME}} file
+  [--region "…"]`) so the reviewer gets the side-by-side + align view +
+  pinned comments. The poll command refuses comparison-shaped questions.
+- Before every `human file`: self-QA the dynamics (overlay/flicker-compare the
+  clone vs live at 2–3 rotation/reveal states) — a defect you catch yourself
+  costs seconds; one the reviewer catches costs a round.
+
+**The sequence (each step's gate must pass before the next — `ppk status {{NAME}}`
+always tells you what's next):**
+
+1. **Scaffold + pin the target.** `ppk new {{NAME}} {{URL}} {{WIDTH}}` → advance
+   `target`. If your browser can't reach exactly {{WIDTH}}px, record the real
+   width in `target.json` and measure everything at that width.
+
+2. **Build by capture — never hand-rebuild** (LEARNINGS #19; PLAYBOOK Phase 4).
+   Settle the live page (load, scroll bottom-and-back, confirm stable
+   scrollHeight + node count twice), capture the doctype-exact DOM
+   (`pxSendDom('http://localhost:7799/dom.html')`, sink running in
+   `targets/{{NAME}}/`), then `ppk capture-build {{NAME}} --qa-toolbar`.
+   Delivery blocked? Fall back per RUNBOOK (stash/chunked `pxRead`; or curl the
+   SSR HTML **only after verifying** its structure matches the hydrated DOM —
+   element-count comparison minimum). Attest `assets` with real evidence.
+
+3. **Measure BOTH pages at the same width** (RUNBOOK). Full-page `pxTargets`:
+   every distinct painted element; for long repeats (cards, rows) sample
+   first + last + a spread (the 37signals precedent) and say so in NOTES.md.
+   Enumerate coverage with `element.checkVisibility({checkVisibilityCSS:true,
+   checkOpacity:true})` — per-node `getComputedStyle` lies inside closed
+   `<details>` (opendesign lesson).
+
+4. **Gate loop:** `--visual` until 0 fails → close `coverage` → `strict` (fix or
+   document every structural delta — a colour/underline row is NEVER structural).
+
+5. **Reproduce the dynamics (`behavior` phase — PLAYBOOK Phase 5c).** Inject
+   `tools/behavior-capture.js` on the live tab, name the marquees/hover triggers you
+   can see, and run the discovery pass (`pxBehaviorSend` → `behaviors-live.json`) —
+   it greps `@keyframes` + markers for candidates, then a MutationObserver +
+   scripted scroll sweep confirms and MEASURES what actually fires. Reproduce each
+   inventoried behavior in one vanilla `clone/fixes.js` (values from the
+   measurements, never eyeballed), rebuild with `ppk capture-build {{NAME}}
+   --fixes`, run the same discovery on the clone (`behaviors-clone.json`), and loop
+   until `ppk gate {{NAME}} behavior` passes. Genuinely irreproducible content
+   (WebGL/canvas generative) is documented in `behavior-deviations.json` — never
+   silently frozen. Re-run the pixel gates after: `done` re-verifies everything.
+
+6. **Human rounds — driven by you, judged by them.** `ppk serve {{NAME}}` →
+   `ppk tunnel {{NAME}}` (it refuses to record a tunnel that isn't serving the
+   clone byte-identically — trust that check) → `ppk human {{NAME}} file`
+   (scope-pinned template auto-generated from your coverage list; the draft url
+   defaults to the verified tunnel). Wake on results with
+   `npx cpyany wait <ping_id>` as a background task. On flags: run the
+   PLAYBOOK Phase 6 `--inspect` drill-down on the element that PAINTS the
+   flagged mark, fix the whole mark in one shot, re-run the gates, then
+   `ppk human {{NAME}} file` again — the refile loop is the product working,
+   not a failure. The gate passes only on an explicit approving verdict pick;
+   comments alone never pass, however positive.
+
+7. **Finish.** `ppk advance {{NAME}} human`, then `ppk advance {{NAME}} done` —
+   done re-runs every gate against the artifacts on disk. Paste the final
+   `ppk status {{NAME}}` table, the passing `--visual` output, the behavior gate's
+   verified-inventory line, and the approving round from
+   `targets/{{NAME}}/human-qa.json` in your report.
+
+**Dynamics honesty:** the captured HTML/CSS stay byte-exact; `fixes.js` is the ONLY
+script and only re-drives what discovery measured. Anything excused in
+`behavior-deviations.json` must also be noted in NOTES.md — the human test template
+marks behavior steps INFORMATIONAL as a backstop for taste/feel and documented
+deviations, not as a substitute for the behavior gate.
+
+**Keep `targets/{{NAME}}/NOTES.md` current** (iteration-log table: what was
+flagged, whether the gate caught it, the fix, the kit-change candidate). A miss
+the gates didn't catch is the most valuable output of the run — flag it loudly
+in your final report (DEVELOP.md meta-loop).

package/DEVELOP.md

@@ -0,0 +1,144 @@
+# DEVELOP — how to make the kit better by cloning real sites
+
+This is the **meta-loop**: you clone real sites to *exercise* the kit, and every miss
+you hit becomes a permanent improvement to the kit — a tool check, a regression fixture,
+and a generalized instruction. The **kit** (`tools/` + the `.md` instructions) is the
+product; **targets** (`targets/<name>/`) are disposable instances you build and throw
+away. Site B inherits everything site A taught, because the lessons live in the shared
+kit, not in a per-site checklist.
+
+Two nested loops:
+
+```
+OUTER (improve the kit) ── for each target site ──▶ INNER (clone it to green)
+        ▲                                                   │
+        └──────── every MISS the gate didn't catch ─────────┘
+                  becomes: tool check + fixture + generalized instruction
+```
+
+---
+
+## Inner loop — clone one site to green
+
+Per target, this is just PLAYBOOK.md + RUNBOOK.md, made turn-key:
+
+```sh
+node harness/new-target.js siteA https://www.example.com/ 1728   # scaffold targets/siteA/
+node tools/sink.js &                                             # snapshot receiver :7799
+node harness/serve.js siteA                                      # serve clone + /tools :8080
+```
+
+Then, driven by measurements (never guesses):
+1. **Measure the live site** at the target width (RUNBOOK) → save `targets/siteA/live.json`.
+2. **Build** `targets/siteA/clone/` — **default: by capture** (LEARNINGS #19):
+   `pxSendDom('http://localhost:7799/dom.html')` on the live tab, then
+   `node harness/capture-build.js siteA` (self-hosted CSS/fonts, doctype preserved).
+   Hand-rebuild to measurements only when exercising the rebuild path is the point of
+   the run — that's where the technique-mismatch lessons came from.
+3. **Capture** the clone → `targets/siteA/clone.json`, then score:
+   ```sh
+   node harness/score.js siteA      # visual PASS/FAIL, fix list, and Δ vs the last run
+   ```
+4. Fix each ❌, re-capture, re-score. `score.js` records every run to `scores.jsonl` and
+   prints whether you got **better** (visual fails ↓). Done = `--visual` green **and**
+   coverage empty (every painted leaf has a target) **and** strict deltas fixed-or-documented.
+
+`score.js` turns "is this iteration better?" into a number instead of a vibe — that's the
+inner-loop progress signal.
+
+---
+
+## Outer loop — the miss protocol (this is the engine)
+
+The valuable event is a human (or your own eyes) flagging something **that a green
+`--visual` did not catch**. Don't just patch that one clone — that's how you iterate once
+per site forever. Convert the miss into a kit improvement so it's caught *everywhere, next
+time, automatically*:
+
+1. **Localize the element that actually *paints* the mark** — it may be an ancestor.
+   `node tools/pixel-diff.js --inspect el_live.json el_clone.json`. If the paint bucket is
+   empty but it still looks wrong, you inspected the wrong element (PLAYBOOK Phase 6).
+2. **Make it a MEASURED failure.** Teach the capture to record it as a number/box
+   (`tools/browser-capture.js` **and** `tools/pixel-diff.js`, kept schema-identical) and
+   `--visual` to compare it. The test: would the sweep now fail on the defect? (This is
+   how `font.smoothing` and the underline **box** were added — LEARNINGS #12/#13.)
+3. **Lock it in with a fixture — and score the change.** Add `harness/fixtures/NN-name.js`
+   that fails *without* your tool change (see `harness/fixtures/README.md`); now it can
+   never silently return. Then add the defect **and any false-positive it risks** to
+   `harness/benchmarks/battery.js` and prove the change is a real improvement:
+   `node harness/benchmarks/detection-power.js --vs HEAD` — the bar is **+N defect classes
+   caught, 0 regressions** (0 missed defects, 0 new false positives). A change that
+   false-positives a control is *not* an improvement, even if it catches the new defect.
+   (The `bg` backdrop gate — #16 — was adopted exactly this way: the naive version
+   false-positived on translucent/whitespace controls; the battery caught it *before*
+   commit, and the gate was narrowed to opaque-only until the A/B came back clean.)
+4. **Re-score every existing target.** `node harness/score.js siteA` (and siteB, …) — a
+   tool change must not regress a clone that was already green. And
+   `node harness/regression.js` must stay green.
+5. **Generalize the instruction.** Write the durable lesson in `LEARNINGS.md`, tagged
+   🔒 (gate-enforced — trust the diff) or 👁 (judgment — the diff can't see it). Compress
+   the how-to in `PLAYBOOK.md` / `RUNBOOK.md` to "the gate checks this; your job is the
+   technique." **Grow the tool, not a per-site checklist.**
+
+If a miss genuinely *can't* be measured (a taste/technique call — e.g. "reproduce the
+drawing technique so it rasterises identically"), it stays a 👁 judgment lesson. Name it
+explicitly in LEARNINGS' "gate vs your eyes" list so it isn't forgotten — but prefer
+pushing misses down into 🔒 whenever they can be measured.
+
+---
+
+## Cloning site B (and C, …)
+
+Run the **same inner loop** on a new target. Because A's misses became tool checks, B
+starts with a stronger gate — a wrong-thickness underline or a heavier smoothing fails on
+B's first score without anyone re-noticing. B's *new* misses feed the same outer loop.
+Over several sites the pattern converges: fewer human rounds per site, because the gate
+keeps absorbing what used to need eyes.
+
+Pick diverse targets on purpose — a site with `text-decoration` underlines, one with
+`box-shadow` dividers, one with a sticky/scrolled header, one RTL — each stresses a
+different corner and surfaces a different class of miss to absorb.
+
+---
+
+## What "better" means (the scoreboard)
+
+- **Per target:** `scores.jsonl` — `visualFails` trending to 0, then coverage empty, then
+  strict deltas each fixed-or-documented. A later run with fewer visual fails is better.
+- **Per kit:** `node harness/regression.js` stays green (no known class of miss can
+  recur), and the **number of human rounds to green trends down** across successive
+  targets. That downward trend *is* the kit getting better.
+- **Per gate change:** `node harness/benchmarks/detection-power.js` scores the gate at
+  **all-defects-caught / 0-false-positives** (absolute mode, run by regression), and a
+  *proposed* change is judged by `--vs HEAD` — **+N caught, 0 regressions** or it's not
+  adopted. This turns "does this gate change help?" into a number, the same way `score.js`
+  does for a clone. See `harness/benchmarks/README.md`.
+- **Guardrail:** a kit change that makes any previously-green target regress, or turns
+  regression red, is not an improvement — revert or fix.
+
+---
+
+## Layout
+
+```
+pixel-perfect-kit/
+├── README.md PLAYBOOK.md LEARNINGS.md CLONE-ANY-HEADER.md   ← the product: instructions
+├── DEVELOP.md                                               ← you are here (the meta-loop)
+├── tools/            pixel-diff.js browser-capture.js extract-*.js sink.js
+│   └── selftest.js   guards the gate's guarantees (underline box + smoothing)
+├── harness/          the dev framework
+│   ├── new-target.js  scaffold targets/<name>/
+│   ├── capture-build.js  DEFAULT build: clone from the captured live DOM (LEARNINGS #19)
+│   ├── human-qa.js    the human phase: scope-pinned PingHumans rounds as a gate
+│   ├── serve.js       static server (clone + /tools)
+│   ├── score.js       score live-vs-clone, compare to last run
+│   ├── regression.js  selftest + every fixture + the detection battery
+│   ├── fixtures/      one file per class-of-miss (can never recur)
+│   └── benchmarks/    detection-power battery — score a gate change old-vs-new (--vs HEAD)
+└── targets/          ← DISPOSABLE per-site instances (git-ignored); the kit is the product
+    └── <name>/  target.json  clone/  live.json  clone.json  scores.jsonl  NOTES.md
+```
+
+Rule of thumb: if a change only helps one site, it belongs in `targets/<name>/`. If it
+helps the *next* site, it belongs in the kit — as a tool check first, an instruction
+second.

package/LAUNCH-PROMPT.md

@@ -0,0 +1,66 @@
+# Launch prompt — hand a fresh agent a ppk clone run
+
+Fill the three values and give this to any agent with browser automation + shell access.
+The kit's docs carry the method; this wrapper carries only what lives outside the repo
+(the environment) and the run contract. Refined across the astryx + iphone17 runs.
+
+---
+
+You are driving the pixel-perfect-kit (`ppk` on PATH; run `ppk where` to locate the
+installed kit's directory — every doc referenced below lives there; run `ppk doctor`
+first and surface any failure to the user before starting). Targets are created under
+the CURRENT working directory (`targets/<name>/`).
+
+Your task: follow the kit's one-shot template at <KIT>/CLONE-ANY-SITE.md with these values:
+- {{URL}} = <the page to replicate>
+- {{WIDTH}} = <fixed measurement viewport width, e.g. 1512>
+- {{NAME}} = <target name, e.g. acme>
+
+The template names the docs to read first (PLAYBOOK.md, tools/RUNBOOK.md, LEARNINGS.md,
+WORKFLOW.md — their rules override any assumption you have) and defines done:
+`node harness/workflow.js gate {{NAME}} done` exits 0 — which includes the `behavior`
+phase (every JS-driven dynamic reproduced with measured values or excused with a
+reviewer-readable reason) and the `human` phase (a real reviewer's approving verdict,
+filed and verified through the kit's tooling). The reviewer answers within minutes —
+keep the loop tight and act on every verdict immediately.
+
+Environment notes (operational, not workflow):
+- Use your browser-automation tooling (e.g. the claude-in-chrome MCP — load the core
+  set in ONE ToolSearch call). Fresh tabs; verify innerWidth/devicePixelRatio before
+  every capture; if the requested width is unreachable, record the actual width in
+  target.json and measure everything at that width.
+- Long-running processes (sink, serve, tunnels, `npx cpyany wait`) run as background
+  Bash tasks. Sandboxed Bash may need the sandbox disabled for network commands.
+- Delivery: start `node tools/sink.js` and `node harness/tunnel.js --sink` FIRST — the
+  automation extension blocks page→localhost fetch (a clean ~4s abort), and the sink
+  tunnel restores one-call delivery for every capture (pxSend / pxSendDom /
+  pxBehaviorSend). A `text/plain` form POST to the sink also works when the site's CSP
+  has no form-action directive. Stash + chunked pxRead is the LAST resort.
+- Do the work directly — NO sub-agents (their results orphan when you stop). If a
+  session limit kills you, the receipts carry the state: your successor orients from
+  disk, so keep NOTES.md, FINDERS.md, and the ledgers current as you go.
+
+Rules the kit ENFORCES — don't fight the refusals, they are the method:
+- ALL human contact through `ppk human {{NAME}} …` (the MCP contact tools are
+  permission-denied). Polls may reference ONE side only; anything naming both clone and
+  live is a comparison and must be a filed test. Filing requires every pre-human gate
+  green. Every refile carries `--changelog "what changed since your last review"`.
+- Never --force. Never invent: values come from measurements, mechanisms from the
+  site's own captured CSS/markup/config (a guessed attribute value is an invention; an
+  honest static frame beats fabricated motion). When a behavior's mechanism is
+  unknowable from artifacts, the worksheet prints the question to ask the human —
+  ask it before you build.
+- Screenshots triage and smoke-check; they never certify a match. Numbers certify what
+  numbers reach; the reviewer certifies the rest — through the platform, never out of
+  band.
+
+If {{NAME}} already exists (resuming): orient from disk before touching anything —
+`ppk status {{NAME}}`, run the pre-human gates read-only, read NOTES.md fully (history,
+protocols, environment findings), FINDERS.md (persisted selectors + decoys), and
+human-qa.json (round history). Trust receipts over any prior agent's claims.
+
+Your final message is a factual run report: each phase with its real gate output, the
+behavior worksheet summary (observed/declared/how disposed), human round history
+(ping ids, verdicts, what you fixed), kit friction — a flag the gates MISSED is the
+most valuable output of the whole run — and the exact commands a reviewer runs to
+re-verify. Raw facts over prose polish.