---
name: snappy-review-pages
description: Local HTML review pages with provenance cards and a copy-back feedback loop. Applies whenever Robert asks for an HTML doc/page to review or approve work.
---

# snappy-review-pages — Agent Loader

When Robert asks for an HTML page to review anything, build a machine, not a
document. Three mandatory defaults:

1. **Pipeline order** — deciding artifact first (video work: thumbnail on top,
   then spine, then storyboard). Label stages STAGE 1/2/….
2. **Provenance card on every AI-generated artifact** — service, model,
   settings, ref images (as thumbnails), output path, full verbatim prompt,
   "Copy recreate command" + "Copy prompt only" buttons. Recover real commands
   from the transcript (`~/.claude/projects/<dir>/*.jsonl`); never reconstruct
   from memory.
3. **Feedback machine** — every reviewable item gets
   `<div class="fb" data-id="…" data-label="…"></div>` (✓ Good / ✎ Change +
   notes, localStorage-persisted); exclusive picks via `[data-pick]` buttons
   inside `<figure id="fig-<pickId>">`, independent groups via `data-group`
   (one pick per group); sticky bottom bar with **Copy all
   feedback** exporting markdown to paste back into chat.

Approval gates on visual work: show the page FIRST, then ask via picker.

## API

```typescript
import { feedbackKit, provenanceCard, type Provenance } from "~/.claude/skills/snappy-review-pages/api.ts";
```

| Function | Purpose |
|---|---|
| `feedbackKit(pageKey, exportTitle)` | full embeddable block (styles + sticky bar + JS) — append once before `</body>` |
| `provenanceCard(p: Provenance)` | HTML for one provenance card; needs the kit on the page for `[data-copy]` + styles |

## CLI

```bash
npx tsx ~/.claude/skills/snappy-review-pages/api.ts kit <pageKey> "<export title>"
npx tsx ~/.claude/skills/snappy-review-pages/api.ts provenance '<Provenance json>'
```

## Rules

- Credentials via `env("KEY")` from `../snappy-settings/load.ts`
- Direct API calls only — no Xano proxying unless this IS a Xano DB skill
- No hardcoded tokens, no bash fallbacks
- Every exported function returns a real value or throws; no silent "TODO"s
- file:// gotchas: no remote iframes (YouTube = Error 153; use linked poster
  jpg); clipboard via execCommand fallback (the kit does this); assets in a
  sibling dir with relative paths
- Splicing sections into an existing page programmatically: anchor on unique
  HTML comment markers (`<!-- ===== STAGE N ===== -->`), never on the next
  `</div>`/`</figure>` — figcaptions contain nested closing tags and the
  section you insert contains them too (2026-07-07: both failure modes hit)
- Verify with agent-browser (screenshots + simulated feedback click) before
  opening for Robert, then clear the test key
  (`localStorage.removeItem('fb:<pageKey>:v1')`)
- Reference implementation:
  `~/Projects/whiteboard-beat-bakeoff/videos/dollar-video-sample/storyboard-preview.html`

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `kit` | `page-key`, `title` | `draft` | `npx tsx ~/.claude/skills/snappy-review-pages/api.ts kit <page-key> "<title>"` |
| `provenance` | — | `write-reversible` | `npx tsx ~/.claude/skills/snappy-review-pages/api.ts provenance` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---

## Self-correcting loader (PID feedback)

The system spec lives at `~/.claude/skills/snappy-settings/skill-spec.md`. It defines the entire Snappy operating system. You enforce it.

### Before you finish, do two things:

**1. Fix gaps (P — proportional). MANDATORY.** If this AGENTS.md didn't cover your case — if you had to read another file, run a command not documented here, work around a wrong selector, or discover a quirk — you MUST attempt an `Edit` before you can log.

- **Default action: edit this AGENTS.md.** Surgical. Add the missing line, table row, or code example where it belongs. No restructuring.
- **Only LOGGED is allowed when:** the fix needs >10 lines, spans multiple files, or requires a structural rewrite (in which case the drain-skill-regen.sh queue picks it up).
- "I didn't have time" / "it's minor" / "the next agent will figure it out" are NOT valid reasons to skip the Edit. The whole point of this loop is that minor gaps compound.
- Concrete example of a valid P-fix: lesson-2 ship agent discovered `agent-browser screenshot <path>` takes path positionally, not as `--output <path>`. That's one line in a table. Edit it in. Do not just log it.
- The goal: the next agent never has to leave the loader.

**2. Validate structure.** Check this skill against the spec:
- `api.ts` exists with typed exports, CLI mode, `import { env } from "../snappy-settings/load.ts"`
- `api.ts` calls APIs directly (no Xano proxy, unless this skill IS a Xano DB skill)
- `AGENTS.md` has API module section with import + function table + CLI
- No bash fallbacks, no hardcoded tokens anywhere
- **Every action row carries a `certificate:` block** (premises / action / trace / evidence / conclusion). Same-session toasts are NOT evidence — must be a fresh independent read. Missing or weak certificates are a gap: P-fix them inline and log to `~/.claude/logs/verification-gaps.log`.
- **DRY:** before you add a new function or new skill, run `~/.claude/skills/snappy-settings/scripts/dry-check.sh <name-or-keyword>`. If it matches an existing skill, extend that one instead. Fragmentation is the enemy.
- If any check fails → fix it or log it

**2b. If you just reported an action as successful, verify your certificate.** You may not claim PASS unless the `evidence:` line is a fresh independent read (reload, new session, server round-trip). If your evidence is a toast, a return value, or a same-session DOM read, downgrade the claim to INCONCLUSIVE and log to `verification-gaps.log`.

**3. Log always.**
```bash
echo "[$(date -u +%FT%TZ)] <skill-name>: <what was missing or fixed> [FIXED|LOGGED]" >> ~/.claude/logs/agents-md-feedback.log
```
`FIXED` = you patched it. `LOGGED` = too large for inline fix, queued for drain-skill-regen.sh.

**Do not skip this.** Every agent run must leave the system better than it found it.


Show produced work with `snappy-faces`: call `draw` for image channels or `lang` for MCP Apps.

<!-- SKILL-INDEX-START -->
[snappy-review-pages Index]|root: ~/.claude/skills/snappy-review-pages|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md}
<!-- SKILL-INDEX-END -->

---
name: snappy-review-pages
instruction-only: true
description: >
  Local HTML review pages with provenance and a copy-back feedback loop.
  Whenever Robert asks for an HTML doc/page to review work (storyboards,
  thumbnails, analyses, comparisons), build it with: pipeline ordering,
  provenance cards for every AI-generated artifact (refs, prompt, service,
  settings, one-click recreate command), and per-item feedback widgets whose
  notes export as markdown via one Copy-all button for pasting back into chat.
  Triggers on: html page, review page, html doc, storyboard preview, show me
  on a page, provenance, feedback page, snappy-review-pages, review-pages.
---

# snappy-review-pages

## Purpose

Turn every "make me an HTML page" request into a working review machine, not
a static document. Born 2026-07-07 when Robert rejected a plain storyboard
preview: *"I want it to mirror the pipeline... show the provenance of
everything... built in a way that's easy for me to leave feedback... hit the
copy button and bring it back here... so it becomes a machine."*

Three defaults, applied whenever a review/working HTML page is requested:

1. **Pipeline ordering.** If the page mirrors a workflow, sections run in
   pipeline order — the deciding artifact first. For video work that means
   thumbnail at the top (thumbnail-first rule), then the spine/script derived
   from it, then the storyboard, then build status. Label stages explicitly
   (STAGE 1 / STAGE 2 / …).
2. **Provenance on every AI-generated artifact.** A card showing: service,
   model, settings, reference images (rendered as thumbnails with captions),
   output path, the full verbatim prompt, and two copy buttons — "Copy
   recreate command" (the exact shell command, one click = full reproduction)
   and "Copy prompt only". Recover real commands from the transcript/logs;
   never reconstruct provenance from memory.
3. **Feedback machine.** Every reviewable item (a frame, a script line, a
   thumbnail variant, a caption treatment) gets a `.fb` widget: ✓ Good /
   ✎ Change toggles + a notes textarea. State persists in localStorage keyed
   per page. A sticky bottom bar shows the live count and a **Copy all
   feedback** button that exports everything as markdown (item label, verdict,
   notes, plus any exclusive picks) for pasting straight back into the chat.
   Exclusive choices (pick variant A/B) use `[data-pick]` buttons; multiple
   independent pick groups on one page via `data-group` (e.g. one base-vs-face
   choice per video). Legacy single-pick state auto-migrates.

## When to Use This Skill

- Robert asks for an HTML page/doc to review, compare, approve, or annotate
  anything: storyboards, thumbnails, analysis pages, bake-off comparisons.
- An approval gate on visual work — never ask for approval of visual
  artifacts via text tables; show the page first, then ask.
- Any page presenting AI-generated images/video/audio → provenance cards are
  mandatory, not optional.

## Quick Start

```bash
# print the embeddable feedback block (styles + sticky bar + JS)
npx tsx ~/.claude/skills/snappy-review-pages/api.ts kit dollar-video-sample "THE $1 VIDEO production page"

# print a provenance card
npx tsx ~/.claude/skills/snappy-review-pages/api.ts provenance '{"title":"Provenance — thumbnail","service":"fal.ai (gpt-image-2 /edit) via image.sh","model":"gpt-image-2","settings":"--size landscape_16_9 --quality high --n 2","output":"/tmp/out/{0,1}.jpg","prompt":"...","command":"image.sh --model gpt-image-2 ...","refs":[{"src":"assets/ref.jpg","caption":"ref: headshot (real photo)"}],"id":"thumb"}'
```

Typical build: write the page HTML with `.fb` placeholders and provenance
cards (use `provenanceCard()`), append `feedbackKit(pageKey, title)` once
before `</body>`.

## Page markup contract

```html
<!-- reviewable item: widget renders itself into this div -->
<div class="fb" data-id="frame-3" data-label="Frame 3 — The receipt"></div>

<!-- exclusive pick: figure id must be fig-<pickId>. Omitting data-group puts
     the button in the default "pick" group; buttons sharing a data-group are
     mutually exclusive, distinct groups are independent (one pick per group,
     exported as "**Pick (<group>):** <pickId>"). -->
<figure id="fig-v3-face"> ... <button class="btn" data-pick="v3-face" data-group="v3">Pick this one</button>
  <span class="picked-tag">✓ PICKED</span> ... </figure>

<!-- copy source: button copies textarea value or element textContent -->
<button class="btn" data-copy="cmd-thumb">Copy recreate command</button>
<textarea id="cmd-thumb" style="display:none">exact shell command…</textarea>
```

## file:// constraints (hard-earned)

- No remote iframes: YouTube embeds throw Error 153 on file:// origin — use
  a linked poster image (curl the maxresdefault.jpg) instead.
- Clipboard: `navigator.clipboard` is unreliable on file:// — the kit uses
  the hidden-textarea `document.execCommand("copy")` fallback.
- Assets live in a sibling directory next to the page (relative paths); copy
  ref images there so provenance cards render offline.
- Verify with agent-browser (screenshot top/middle/bottom, simulate a
  feedback click, check the localStorage state) BEFORE opening for Robert,
  then clear the test key: `localStorage.removeItem('fb:<pageKey>:v1')`.

## Workflow

**Inputs**
- The artifacts under review + their generation commands (grep the session
  transcript `~/.claude/projects/<dir>/*.jsonl` if provenance wasn't saved)
- `snappy-settings` — env() loader (unused today; kept per spec)

**Outputs**
- A self-contained HTML page + sibling assets dir, verified in agent-browser,
  opened locally for Robert
- Robert's pasted-back markdown feedback drives the next iteration

**Orchestrator**
- The main session, at any review/approval gate; also usable by frame-worker
  or bake-off sub-agents producing review surfaces

## Reference implementation

`~/Projects/whiteboard-beat-bakeoff/videos/dollar-video-sample/storyboard-preview.html`
— thumbnail (STAGE 1, with provenance) → spine (7 lines, per-line feedback) →
storyboard (7 frames, per-frame feedback) → pilot-thumbnail pick (data-pick +
shared provenance card).

## Related Skills

| Skill | Why |
|---|---|
| `snappy-settings` | credential loader (spec requirement) |
| `snappy-image` / `snappy-ai-models` | the generation runs whose provenance these pages display |
| `snappy-browse` | agent-browser verification of the page before delivery |
| `snappy-positioning` | voice rules if page copy will be published |

## Near neighbours

Skills whose description overlaps this one enough that a reader could pick the
wrong door. Each row is that skill's own first sentence about itself, so the
choice is made on its words, not on a summary written here.

| Skill | Reach for it instead when |
|---|---|
| `snappy-artifact-loop` | Build published Artifacts as I/O devices where the AGENT is the backend, not as static output… |
| `snappy-docs` | THE DEFAULT for writing to Notion -- the Snappy stack's Notion primitive over the REST API (a… |
| `snappy-gmail` | Gmail as the machine's own hands -- read the inbox, threads and one message straight from Gma… |
| `snappy-nightshift` | The overnight orchestration operating system: one orchestrator drives a repo toward 100% all… |
| `snappy-sync` | Cross-machine file sharing between MacBook Pro and Mac Mini. |
| `snappy-telegram` | Telegram Bot API channel for Snappy: direct calls to api.telegram.org (no Xano middleware) to… |
| `snappy-watchtower` | Standing error monitors and the probes that lie: arm live typecheck, build, and test monitors… |
| `snappy-website` | Snappy website (snappy.ai) operations -- Next.js + Vercel marketing site, VSL conversion funn… |

#!/usr/bin/env npx tsx
/**
 * snappy-review-pages/api.ts — local HTML review pages with provenance +
 * a copy-back feedback loop. Two verbs: feedbackKit() returns the embeddable
 * CSS+JS block; provenanceCard() renders a provenance card for an
 * AI-generated artifact. No credentials needed; env import kept per spec.
 */
import { realpathSync } from "fs";
import { env } from "../snappy-settings/load.ts";
import { annotationsForClass } from "../snappy-settings/tool-annotations.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";
void env;

export interface Provenance {
  title: string; // e.g. "Provenance — pilot thumbnail v2"
  service: string; // e.g. "fal.ai (gpt-image-2 /edit) via ~/.claude/skills/snappy-ai-models/openai/image.sh"
  model: string;
  settings: string; // e.g. "--size landscape_16_9 · --quality high · --n 2"
  output: string; // where the artifact landed on disk
  prompt: string; // the full generation prompt, verbatim
  command: string; // the exact shell command that recreates the artifact
  refs?: { src: string; caption: string }[]; // reference images, relative paths
  id?: string; // unique per card on the page; defaults to "prov"
}

const esc = (s: string) =>
  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

/** HTML for one provenance card. Page must also embed feedbackKit() once
 *  (it provides the [data-copy] handler and .btn/.prov styles). */
export function provenanceCard(p: Provenance): string {
  const id = p.id ?? "prov";
  const refs = (p.refs ?? [])
    .map(
      (r) =>
        `      <figure><img src="${esc(r.src)}" alt="${esc(r.caption)}"><figcaption>${esc(r.caption)}</figcaption></figure>`,
    )
    .join("\n");
  return `<div class="prov">
  <h3>${esc(p.title)} <span class="tag">AI-generated</span></h3>
  <div class="kv">
    <div class="k">service</div><div class="v">${esc(p.service)}</div>
    <div class="k">model</div><div class="v">${esc(p.model)}</div>
    <div class="k">settings</div><div class="v">${esc(p.settings)}</div>
    <div class="k">references</div><div class="v">${p.refs?.length ?? 0} (below)</div>
    <div class="k">output</div><div class="v">${esc(p.output)}</div>
  </div>
  <div class="refs">
${refs}
  </div>
  <pre id="prompt-${id}">${esc(p.prompt)}</pre>
  <div class="pickrow">
    <button class="btn" data-copy="cmd-${id}">Copy recreate command</button>
    <button class="btn" data-copy="prompt-${id}">Copy prompt only</button>
  </div>
  <textarea id="cmd-${id}" style="display:none">${esc(p.command)}</textarea>
</div>`;
}

/** The whole feedback machine as one embeddable block: styles + sticky bar + JS.
 *  Drop it before </body>. Reviewable items are marked in the page HTML as
 *  `<div class="fb" data-id="frame-3" data-label="Frame 3 — The receipt"></div>`;
 *  optional exclusive picks as `<button class="btn" data-pick="v1">` inside a
 *  `<figure id="fig-v1">`, with independent pick groups via `data-group`
 *  (buttons sharing a group are exclusive; default group is "pick").
 *  pageKey namespaces localStorage; exportTitle heads
 *  the copied markdown. Uses execCommand copy so it works on file:// pages. */
export function feedbackKit(pageKey: string, exportTitle: string): string {
  return `<style>
  .prov { background:#161b22; border:1px solid #30363d; border-radius:12px; padding:18px 20px; margin-top:14px; }
  .prov h3 { margin:0 0 10px; font-size:14px; color:#c9d1d9; }
  .prov h3 .tag { background:#1f6feb33; color:#79c0ff; border:1px solid #1f6feb66; border-radius:5px; font-size:11px; padding:2px 7px; margin-left:8px; font-weight:400; }
  .prov .kv { display:grid; grid-template-columns:130px 1fr; gap:5px 14px; font-size:13px; }
  .prov .k { color:#8b949e; } .prov .v { color:#c9d1d9; word-break:break-all; }
  .prov pre { background:#0d1117; border:1px solid #30363d; border-radius:8px; padding:12px 14px; font-size:12.5px; line-height:1.6; white-space:pre-wrap; color:#c9d1d9; margin:12px 0 0; }
  .prov .refs { display:flex; gap:12px; margin-top:12px; }
  .prov .refs figure { margin:0; text-align:center; }
  .prov .refs img { height:84px; border-radius:6px; border:1px solid #30363d; display:block; }
  .prov .refs figcaption { color:#8b949e; font-size:11px; margin-top:4px; max-width:130px; }
  .pickrow { display:flex; align-items:center; gap:10px; margin-top:8px; }
  .btn { cursor:pointer; background:#21262d; color:#c9d1d9; border:1px solid #30363d; border-radius:7px; font:inherit; font-size:12.5px; padding:7px 13px; }
  .btn:hover { border-color:#ffa657; color:#ffa657; }
  .btn.primary { background:#ffa657; color:#000; border-color:#ffa657; font-weight:700; }
  .btn.copied { background:#3fb950; color:#000; border-color:#3fb950; }
  figure.picked { border-color:#3fb950 !important; }
  .picked-tag { color:#3fb950; font-weight:700; font-size:12.5px; display:none; }
  figure.picked .picked-tag { display:inline; }
  .fb { margin-top:10px; border-top:1px dashed #30363d; padding-top:10px; }
  .fb .row1 { display:flex; gap:8px; align-items:center; }
  .fb button.v { cursor:pointer; background:#21262d; color:#8b949e; border:1px solid #30363d; border-radius:6px; font:inherit; font-size:12px; padding:4px 11px; }
  .fb button.v.on-good { background:#3fb950; border-color:#3fb950; color:#000; font-weight:700; }
  .fb button.v.on-chg  { background:#f0883e; border-color:#f0883e; color:#000; font-weight:700; }
  .fb textarea { width:100%; margin-top:8px; background:#0d1117; color:#c9d1d9; border:1px solid #30363d; border-radius:6px; font:inherit; font-size:12.5px; padding:7px 10px; min-height:34px; resize:vertical; }
  .fb textarea::placeholder { color:#484f58; }
  .fbar { position:fixed; left:0; right:0; bottom:0; background:#161b22ee; border-top:1px solid #30363d; backdrop-filter:blur(6px); z-index:50; }
  .fbar .in { max-width:1320px; margin:0 auto; padding:12px 32px; display:flex; align-items:center; gap:16px; }
  .fbar .cnt { color:#8b949e; font-size:13px; flex:1; }
  .fbar .cnt b { color:#c9d1d9; }
</style>
<div class="fbar"><div class="in">
  <div class="cnt" id="fb-count">No feedback yet — mark items above, then copy.</div>
  <button class="btn" id="fb-clear">Clear all</button>
  <button class="btn primary" id="fb-copy">Copy all feedback</button>
</div></div>
<script>
(function(){
  var KEY = ${JSON.stringify("fb:" + pageKey + ":v1")};
  var TITLE = ${JSON.stringify(exportTitle)};
  var state = {};
  try { state = JSON.parse(localStorage.getItem(KEY) || "{}"); } catch(e) {}
  function save(){ localStorage.setItem(KEY, JSON.stringify(state)); renderCount(); }
  function copyText(t, btn){
    var ta = document.createElement("textarea");
    ta.value = t; ta.style.position = "fixed"; ta.style.opacity = "0";
    document.body.appendChild(ta); ta.select();
    try { document.execCommand("copy"); } catch(e) {}
    document.body.removeChild(ta);
    if (btn) {
      var old = btn.textContent;
      btn.classList.add("copied"); btn.textContent = "Copied ✓";
      setTimeout(function(){ btn.classList.remove("copied"); btn.textContent = old; }, 1400);
    }
  }
  document.querySelectorAll(".fb").forEach(function(el){
    var id = el.dataset.id;
    state[id] = state[id] || { verdict:"", notes:"" };
    state[id].label = el.dataset.label;
    var row = document.createElement("div"); row.className = "row1";
    var bGood = document.createElement("button"); bGood.className = "v"; bGood.textContent = "✓ Good";
    var bChg  = document.createElement("button"); bChg.className  = "v"; bChg.textContent  = "✎ Change";
    var ta = document.createElement("textarea"); ta.placeholder = "notes… (what to change, questions, ideas)";
    ta.value = state[id].notes || "";
    function paint(){
      bGood.classList.toggle("on-good", state[id].verdict === "good");
      bChg.classList.toggle("on-chg",  state[id].verdict === "change");
    }
    bGood.onclick = function(){ state[id].verdict = state[id].verdict === "good" ? "" : "good"; paint(); save(); };
    bChg.onclick  = function(){ state[id].verdict = state[id].verdict === "change" ? "" : "change"; paint(); save(); };
    ta.oninput = function(){ state[id].notes = ta.value; save(); };
    row.appendChild(bGood); row.appendChild(bChg);
    el.appendChild(row); el.appendChild(ta);
    paint();
  });
  state.picks = state.picks || {};
  if (state.pick) { state.picks.pick = state.pick; delete state.pick; }
  var pickBtns = document.querySelectorAll("[data-pick]");
  function paintPick(){
    pickBtns.forEach(function(b){
      var g = b.dataset.group || "pick";
      var fig = document.getElementById("fig-" + b.dataset.pick);
      if (fig) fig.classList.toggle("picked", state.picks[g] === b.dataset.pick);
    });
  }
  pickBtns.forEach(function(btn){
    btn.onclick = function(){
      var g = btn.dataset.group || "pick";
      state.picks[g] = (state.picks[g] === btn.dataset.pick) ? "" : btn.dataset.pick;
      paintPick(); save();
    };
  });
  paintPick();
  document.querySelectorAll("[data-copy]").forEach(function(btn){
    btn.onclick = function(){
      var src = document.getElementById(btn.dataset.copy);
      copyText(src.tagName === "TEXTAREA" ? src.value : src.textContent, btn);
    };
  });
  function entries(){
    return Object.keys(state).filter(function(k){
      return k !== "pick" && k !== "picks" && state[k] && (state[k].verdict || (state[k].notes || "").trim());
    });
  }
  function pickGroups(){
    return Object.keys(state.picks || {}).filter(function(g){ return state.picks[g]; });
  }
  function renderCount(){
    var n = entries().length + pickGroups().length;
    document.getElementById("fb-count").innerHTML = n
      ? "<b>" + n + "</b> feedback item" + (n === 1 ? "" : "s") + " ready to copy."
      : "No feedback yet — mark items above, then copy.";
  }
  renderCount();
  document.getElementById("fb-copy").onclick = function(){
    var lines = ["# Feedback — " + TITLE, "_" + new Date().toISOString() + "_", ""];
    var pg = pickGroups();
    pg.forEach(function(g){
      lines.push("**Pick" + (g === "pick" ? "" : " (" + g + ")") + ":** " + state.picks[g]);
    });
    if (pg.length) lines.push("");
    entries().forEach(function(k){
      var e = state[k];
      lines.push("## " + e.label);
      if (e.verdict) lines.push("- verdict: " + (e.verdict === "good" ? "GOOD ✓" : "CHANGE ✎"));
      if ((e.notes || "").trim()) lines.push("- notes: " + e.notes.trim());
      lines.push("");
    });
    if (!pg.length && !entries().length) lines.push("(no items marked)");
    copyText(lines.join("\\n"), this);
  };
  document.getElementById("fb-clear").onclick = function(){
    if (!confirm("Clear all feedback on this page?")) return;
    localStorage.removeItem(KEY);
    location.reload();
  };
})();
</script>`;
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
/** THE HOST-FACING FACTS ⟨lane CONTRACTS N–Z, 2026-09-09⟩. `class` is the
 *  closed effect set snappy-tool-design rule 18 grades; `annotations` are
 *  DERIVED from it by the ONE derivation in
 *  `snappy-settings/tool-annotations.ts`, never written per verb, so a class
 *  and its published hints cannot disagree; `refusals` projects the ONE closed
 *  table in `snappy-settings/refusal-codes.ts`; `requires` is exactly the
 *  credential keys this file's own executable reads name, and nothing else. */
export const HAND_CONTRACT = {
  skill: "snappy-review-pages",
  description: "Local HTML review pages with provenance and a copy-back feedback loop. Whenever Robert asks for an HTML doc/page to review work (storyboards, thumbnails, analyses, comparisons), build it with: pipeline ordering, provenance cards for every AI-generated artifact (refs, prompt, service, settings, one-click recreate command), and per-item feedback widgets whose notes export as markdown via one Copy-all button for pasting back into chat. Triggers on: html page, review page, html doc, storyboard preview, show me on a page, provenance, feedback page, snappy-review-pages, review-pages.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("missing_argument", "unknown_verb"),
  verbs: {
    kit: {
      args: ["page-key","title"], effect: "draft", class: "additive-write", openWorld: false,
      annotations: annotationsForClass("additive-write", { openWorld: false }),
      inputSchema: { properties: { "page-key": { type: "string", description: "Page key from the review-pages registry" }, title: { type: "string", description: "Human-readable title" } } },
    },
    provenance: {
      args: [], effect: "write-reversible", class: "additive-write", openWorld: false,
      annotations: annotationsForClass("additive-write", { openWorld: false }),
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}

if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  const [, , cmd, ...rest] = process.argv;
  if (!cmd || cmd === "help") {
    console.log("Usage:");
    console.log('  npx tsx api.ts kit <pageKey> "<export title>"   # print embeddable feedback block');
    console.log("  npx tsx api.ts provenance '<json>'              # print provenance card HTML");
    process.exit(0);
  }
  if (cmd === "kit") {
    const [pageKey, title] = rest;
    if (!pageKey || !title) { console.error("kit needs <pageKey> and <title>"); process.exit(1); }
    console.log(feedbackKit(pageKey, title));
    process.exit(0);
  }
  if (cmd === "provenance") {
    if (!rest[0]) { console.error("provenance needs a JSON argument"); process.exit(1); }
    console.log(provenanceCard(JSON.parse(rest[0]) as Provenance));
    process.exit(0);
  }
  console.error(`Unknown: ${cmd}`);
  process.exit(1);
}

/**
 * COVERAGE FOR SNAPPY-REVIEW-PAGES'S DECLARED REFUSAL CODES
 * (snappy-tool-design rule 33: "refusal codes form one closed table and each
 * row has coverage").
 *
 * Two things are graded here, and the second is the one that matters. The
 * first is that the hand's table is a PROJECTION of the collection's one
 * closed table in snappy-settings/refusal-codes.ts — same object, not a copy
 * that can drift. The second is that every declared code is GROUNDED: the
 * evidence that justified declaring it is re-checked here, because a refusal
 * code with no path that emits it is a branch the reader waits for and never
 * sees, and a table of those passes a lint while teaching a lie.
 *
 * The code list is spelled out rather than read from the contract: a test that
 * iterates the thing it grades passes for an empty table.
 */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES } from "../snappy-settings/refusal-codes.ts";

const SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "api.ts"), "utf8");

/** Every refusal code snappy-review-pages declares. */
const DECLARED = [
  "missing_argument",
  "unknown_verb",
] as const;

test("snappy-review-pages declares exactly these refusal codes", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals).sort(), [...DECLARED].sort());
});

test("every declared code is the SAME row as the one closed table's, never a copy", () => {
  const table = HAND_CONTRACT.refusals as Record<string, unknown>;
  for (const code of DECLARED) {
    assert.equal(table[code], REFUSAL_CODES[code], `${code} is not the shared row`);
  }
});

test("missing_argument is grounded: at least one verb has a required word", () => {
  const required = Object.values(HAND_CONTRACT.verbs as Record<string, { args?: readonly string[] }>)
    .flatMap((v) => (v.args ?? []).filter((a) => !a.endsWith("?")));
  assert.ok(required.length > 0, "no verb has a required argument, so missing_argument can never fire");
});

test("unknown_verb is grounded: the contract closes the verb set, so a word outside it is refusable", () => {
  assert.ok(Object.keys(HAND_CONTRACT.verbs).length >= 0);
  assert.ok(!Object.keys(HAND_CONTRACT.verbs).includes("no-such-verb"));
});