@typeroll/mcp-server 0.24.0 → 0.25.1

package/dist/server.js

@@ -27,6 +27,7 @@ import { siteTools } from './tools/sites.js';
 import { domainTools } from './tools/domain.js';
 import { skillTools } from './tools/skills.js';
 import { fail } from './tools/helpers.js';
+import { VERSION } from './version.js';
 const PERM_RANK = { read: 0, write: 1, admin: 2 };
 /**
  * Classify a tool by name into the minimum permission needed. We keep this
@@ -48,7 +49,7 @@ function effectFor(name) {
     }
     return 'write';
 }
-const DEFAULT_INFO = { name: 'typeroll', version: '0.22.0' };
+const DEFAULT_INFO = { name: 'typeroll', version: VERSION };
 /**
  * Server-level instructions — returned in the MCP `initialize` response and
  * surfaced to the model by every client (Claude Code stdio AND the hosted

package/dist/tools/pages.js

@@ -236,13 +236,20 @@ export const pageTools = [
     // the block-tree mutation tools (add/update/move/remove/convert).
     {
         name: 'get_page_preview',
-        description: 'Get rendered HTML for one page (header-authed read). Returns { rendered_html, internal_links[] }. For a clickable preview URL use get_preview_link instead.',
+        description: "Get the WHOLE page rendered as one self-contained HTML document — header partial + block-rendered body + footer partial, with the site's settings CSS variables, global styles, and the tree-shaken block-CSS bundle all inlined, exactly as deployed. This is the single artifact for UNDERSTANDING what a page looks like and how its CSS actually cascades (get_page_blocks gives the editable block tree; this gives the rendered result). Returns { rendered_html, internal_links[] }. Pass annotate:true to tag every element with data-block-id + data-block-type so you can map the rendered HTML back to the block to edit. For a clickable preview URL use get_preview_link instead.",
         inputSchema: {
             page_id: z.string(),
+            annotate: z
+                .boolean()
+                .optional()
+                .describe('Tag every block root with data-block-id (the authored block id) + data-block-type so you can map a rendered element back to the exact block to mutate. Off by default.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/preview`, v(args.version));
+            const query = { ...(v(args.version) ?? {}) };
+            if (args.annotate)
+                query.annotate = 'true';
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/preview`, query);
             return ok(res);
         }),
     },

package/dist/version.js

@@ -0,0 +1,11 @@
+// Server version reported in the MCP `initialize` handshake.
+//
+// MUST be a plain literal — NOT a runtime `require('../package.json')`. This
+// module is bundled into the portal's /api/mcp route (hosted MCP), where
+// `import.meta.url` points at the bundled file and `../package.json` does not
+// resolve — a require there throws at module load and 500s the whole route.
+// The literal works in every context (standalone npm package + bundled portal).
+//
+// Keep it in lockstep with package.json: tests/version.test.ts asserts
+// VERSION === package.json.version, so a bump that forgets this line fails CI.
+export const VERSION = '0.25.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {

package/skills/tr-design-review.md

@@ -0,0 +1,298 @@
+---
+name: tr-design-review
+description: Use to review a deployed/previewed Typeroll page like a designer — a MEASURED multi-dimension pass (responsive, a11y, functional, content, SEO, performance) that emits a per-dimension scorecard and an explicit OK verdict. Run it before telling the user a design is approved; it's the "how" for tr-redesign-branch's approval round.
+---
+
+# Review a design — measured, not glanced
+
+A design review is a MEASUREMENT, not a look. The failure mode is reporting
+"looks good" off a couple of screenshots — which silently misses overflow at
+untested widths, sub-AA contrast, broken/blank images, and small touch targets.
+This skill is the deterministic routine: per dimension, a check you RUN (a
+browser-eval snippet or a curl), and a scorecard you fill with PASS / FAIL /
+UNTESTED. Never report "approved" off a partial pass — list what you didn't test
+as caveats.
+
+`tr-redesign-branch` step 6 lists the dimensions (the "what"). This is the "how".
+
+## Cardinal rule: a screenshot is evidence, not proof
+
+**Full-page screenshots lie about lazy-loaded images.** A page with
+`loading="lazy"` images below the fold will screenshot with BLANK boxes where
+those images sit — they hadn't entered the viewport when the capture fired. If
+you trust that, you will report a non-existent "empty illustration box" gap.
+(This has happened — on a real review, across three variants at once.)
+
+So, always:
+
+- **Before any full-page capture**, scroll the whole page to trigger lazy loads
+  and let it settle (snippet in §5), THEN screenshot.
+- **Verify every suspected blank/broken image via the DOM** (`naturalWidth` after
+  scroll), never from the screenshot. A real broken image has `complete === true
+  && naturalWidth === 0`; a lazy one that just hasn't loaded has `complete ===
+  false` — scroll it into view and re-check before calling it broken.
+
+## Setup
+
+1. Get a stable URL for the version under review: `trigger_deploy version="<branch>"`
+   → poll `get_deploy_status` → use the immutable `deploy_url` (a Cloudflare Pages
+   hash URL — it never changes, so the URL you OK is bit-for-bit what ships if
+   merged). Or `get_preview_link` for an in-portal render. Review the SAME url end
+   to end.
+2. The snippets below run in a browser tool's "evaluate JavaScript" (Playwright /
+   chrome-devtools / puppeteer MCP). **One origin per eval:** the iframe trick
+   needs same-origin, so run each variant's snippet on its own page (different
+   `*.pages.dev` hashes are cross-origin → `contentDocument` is null).
+3. If you run several variants with one shared browser profile, do them
+   SEQUENTIALLY — parallel browser agents on one profile contaminate each other's
+   tabs/screenshots.
+
+## The dimensions — run each, record the result
+
+### 1. Responsive — width ladder 390/768/1024/1440/1920, zero overflow
+
+Measure horizontal overflow at every width in ONE eval using same-origin iframes
+(each iframe is its own layout viewport, so `@media` fires correctly — no 15
+resizes):
+
+```js
+async () => {
+  const url = location.href, out = [];
+  for (const w of [390,768,1024,1440,1920]) {
+    const f = document.createElement('iframe');
+    f.style.cssText = `width:${w}px;height:2400px;border:0;position:fixed;left:-99999px;top:0`;
+    document.body.appendChild(f);
+    await new Promise(r => { f.onload = r; f.src = url; });
+    await new Promise(r => setTimeout(r, 700));
+    const d = f.contentDocument, culprits = [];
+    for (const el of d.body.querySelectorAll('*')) {
+      const r = el.getBoundingClientRect();
+      if (r.right > w + 1 && r.width <= w + 40 && r.width > 4)
+        culprits.push(el.tagName.toLowerCase() + '.' + (el.className||'').toString().slice(0,40));
+    }
+    out.push({ w, hOverflow: d.documentElement.scrollWidth - w, n: culprits.length, sample: [...new Set(culprits)].slice(0,6) });
+    f.remove();
+  }
+  return out;
+}
+```
+
+PASS = `hOverflow <= 0` at every width. A decorative element flagged while
+`hOverflow` is 0 is clipped by an `overflow:hidden` parent (no scrollbar) — a
+non-issue. Then eyeball one tablet (768) capture for stacking — but capture
+AFTER the scroll-settle in §5.
+
+### 2. Accessibility — compute contrast, don't eyeball
+
+```js
+() => {
+  const L = c => { const a = c.map(v => (v/=255, v<=.03928?v/12.92:((v+.055)/1.055)**2.4)); return .2126*a[0]+.7152*a[1]+.0722*a[2]; };
+  const P = c => { const m = c.match(/rgba?\(([^)]+)\)/); if(!m) return null; const p = m[1].split(',').map(parseFloat); return {rgb:[p[0],p[1],p[2]], a:p[3]??1}; };
+  const R = (f,b) => { const x=L(f),y=L(b),h=Math.max(x,y),l=Math.min(x,y); return (h+.05)/(l+.05); };
+  const bg = el => { let e=el; while(e){ const s=getComputedStyle(e); if(s.backgroundImage!=='none') return {img:1}; const c=P(s.backgroundColor); if(c&&c.a>.5) return {rgb:c.rgb}; e=e.parentElement; } return {rgb:[255,255,255]}; };
+  const bad=[], seen=new Set();
+  for (const el of document.body.querySelectorAll('*')) {
+    const t=[...el.childNodes].filter(n=>n.nodeType===3&&n.textContent.trim()).map(n=>n.textContent.trim()).join(' ');
+    if(!t) continue;
+    const r=el.getBoundingClientRect(); if(r.width<2||r.height<2) continue;
+    const s=getComputedStyle(el); if(s.visibility==='hidden'||s.display==='none'||+s.opacity<.1) continue;
+    const fg=P(s.color); if(!fg) continue;
+    const b=bg(el); if(b.img) continue; // can't compute over an image — eyeball hero text separately
+    const cr=R(fg.rgb,b.rgb), fs=parseFloat(s.fontSize), fw=+s.fontWeight||400;
+    const need = (fs>=24||(fs>=18.66&&fw>=700)) ? 3 : 4.5;
+    if (cr<need) { const k=t.slice(0,30)+cr.toFixed(2); if(seen.has(k))continue; seen.add(k);
+      bad.push({txt:t.slice(0,45), ratio:+cr.toFixed(2), need, fs:Math.round(fs), fw, color:s.color, bg:'rgb('+b.rgb.join(',')+')'}); }
+  }
+  return { failures: bad.length, items: bad.slice(0,15) };
+}
+```
+
+PASS = 0 failures (AA: body ≥4.5:1, large/UI ≥3:1). Fix a failure by deepening
+the offending colour token. Text over an image background is skipped — eyeball
+those (hero overlays) for legibility separately.
+
+Structure + alt + landmarks, same eval session:
+
+```js
+() => {
+  const h=[...document.querySelectorAll('h1,h2,h3,h4')].map(e=>+e.tagName[1]);
+  const skips=h.map((v,i)=>i&&v-h[i-1]>1?`${h[i-1]}->${v}`:0).filter(Boolean);
+  const imgs=[...document.querySelectorAll('img')];
+  const inputs=[...document.querySelectorAll('input:not([type=hidden]),textarea,select')];
+  const labelFor=new Set([...document.querySelectorAll('label[for]')].map(l=>l.getAttribute('for')));
+  return {
+    h1: h.filter(x=>x===1).length, levelSkips: skips,
+    imgsMissingAlt: imgs.filter(i=>i.getAttribute('alt')===null).length,
+    landmarks: ['header','nav','main','footer'].filter(t=>document.querySelector(t)),
+    unlabeledInputs: inputs.filter(i=>!(i.id&&labelFor.has(i.id))&&!i.getAttribute('aria-label')).map(i=>i.name||i.id),
+  };
+}
+```
+
+PASS = exactly one `h1`, `levelSkips` empty, `imgsMissingAlt` 0, all four
+landmarks present, `unlabeledInputs` empty. (Decorative images SHOULD have
+`alt=""` — that's not "missing".)
+
+Touch targets — interactive elements ≥44px at mobile. Run in a 390px iframe;
+EXCLUDE `aria-hidden` (the form honeypot is a visible-sized but hidden input —
+counting it is a false positive) and inline text links inside `p`/`li`:
+
+```js
+async () => {
+  const f=document.createElement('iframe');
+  f.style.cssText='width:390px;height:2400px;border:0;position:fixed;left:-99999px;top:0';
+  document.body.appendChild(f);
+  await new Promise(r=>{ f.onload=r; setTimeout(r,3000); f.src=location.href; });
+  await new Promise(r=>setTimeout(r,700));
+  const d=f.contentDocument, small=[];
+  if(d) for (const el of d.querySelectorAll('a,button,input:not([type=hidden]),textarea,select,[role=button]')) {
+    const r=el.getBoundingClientRect(); if(r.width<2||r.height<2) continue;
+    const s=getComputedStyle(el); if(s.display==='none'||s.visibility==='hidden'||+s.opacity<.1) continue;
+    if(el.getAttribute('aria-hidden')==='true') continue;
+    if(el.tagName==='A'&&el.closest('p,li')) continue;
+    if(r.height<44||r.width<44) small.push({tag:el.tagName.toLowerCase(), txt:(el.innerText||el.value||el.getAttribute('aria-label')||'').trim().slice(0,24), w:Math.round(r.width), h:Math.round(r.height)});
+  }
+  f.remove(); return { undersized: small };
+}
+```
+
+Also confirm `:focus-visible` and `prefers-reduced-motion` exist (grep the page
+HTML: `grep -c 'focus-visible' page.html`, `grep -c 'prefers-reduced-motion'`).
+Note honestly: presence in CSS ≠ verified per-element — tab through live if you
+claim keyboard focus works.
+
+### 3. Functional — console, links, form
+
+- **Console:** read the browser tool's console messages after load. PASS = 0
+  errors/warnings.
+- **Links:** PASS = no `href="#"`/empty; every in-page `#anchor` has a matching
+  `id`.
+- **Form (markup — does NOT prove a live submit):** curl the page and verify the
+  `<form>` `action` is the real submit endpoint, the hidden `_token` is
+  non-empty, the honeypot is present + `aria-hidden`, required fields have
+  `required`, the email field is `type="email"`. State explicitly that you did
+  NOT submit (a live POST creates a real submission) unless you actually did.
+
+### 4. Content — verbatim, no placeholders
+
+`grep -Ei 'lorem|ipsum|\{\{|placeholder|TODO|FIXME' page.html` → 0. Copy matches
+the live page (the source of truth) verbatim.
+
+### 5. Broken / blank images (the anti-lazy-load check — run THIS before trusting any screenshot)
+
+```js
+async () => {
+  const H=document.body.scrollHeight;
+  for(let y=0;y<=H;y+=400){ window.scrollTo(0,y); await new Promise(r=>setTimeout(r,120)); }
+  window.scrollTo(0,0); await new Promise(r=>setTimeout(r,1500));
+  const imgs=[...document.querySelectorAll('img')];
+  const empty=[]; // genuinely empty boxes: large, no text/img/svg/bg-image
+  for (const el of document.querySelectorAll('div,section,figure')) {
+    const r=el.getBoundingClientRect(); if(r.width<160||r.height<140) continue;
+    if((el.innerText||'').trim()||el.querySelector('img,svg,picture,canvas,video')) continue;
+    if(getComputedStyle(el).backgroundImage!=='none') continue;
+    empty.push({cls:(el.className||'').toString().slice(0,36), w:Math.round(r.width), h:Math.round(r.height)});
+  }
+  return {
+    broken: imgs.filter(i=>i.complete&&i.naturalWidth===0).map(i=>i.src.slice(-45)), // real failures
+    stillLoading: imgs.filter(i=>!i.complete).map(i=>i.src.slice(-45)),               // lazy, scroll first
+    emptyBoxes: empty.slice(0,8),                                                     // true placeholders
+  };
+}
+```
+
+PASS = `broken` empty, `emptyBoxes` empty. A non-empty `emptyBoxes` is a genuine
+unfilled illustration slot (fill it — pages shouldn't be text deserts). NOW
+capture screenshots (the page is scrolled-and-settled, images loaded).
+
+### 5b. Clipped artwork — the logo (and any brand image) cut off by its own frame
+
+The single most-repeated visual bug: the header logo rendered with its top/edges
+sliced. It produces ZERO page overflow (§1 misses it), the image isn't broken
+(§5 misses it), and at full-page screenshot scale a few clipped pixels are easy
+to glance past. So MEASURE it: does the artwork's rendered content touch the edge
+of its own box on any side? Content flush against the frame (gap ≈ 0) = clipped
+or about-to-clip. Don't just check the logo — check it, then trust the number.
+
+For a raster/`<img>` logo, draw it to a same-origin canvas and scan the border
+rows/cols for opaque pixels (cross-origin taints the canvas — fetch the asset to
+a localhost file first, as in §setup, or measure on the asset directly):
+
+```js
+async (url) => { // url = the logo's currentSrc, served same-origin
+  const img = new Image(); await new Promise((r,e)=>{img.onload=r;img.onerror=e;img.src=url;});
+  const h = 64, w = Math.round(h*img.naturalWidth/img.naturalHeight);
+  const c = document.createElement('canvas'); c.width=w; c.height=h;
+  const x = c.getContext('2d'); x.drawImage(img,0,0,w,h);
+  const d = x.getImageData(0,0,w,h).data, op=(px)=>d[px*4+3]>20;
+  let top=h,bot=0,left=w,right=0;
+  for(let y=0;y<h;y++)for(let xx=0;xx<w;xx++)if(op(y*w+xx)){top=Math.min(top,y);bot=Math.max(bot,y);left=Math.min(left,xx);right=Math.max(right,xx);}
+  return { topGap:top, bottomGap:h-1-bot, leftGap:left, rightGap:right }; // any 0 → flush/clipped
+}
+```
+
+PASS = every gap ≥ ~2% of the dimension. A `0` on any side means the artwork (or
+its stroke) sits on the frame — for an SVG that's a viewBox trimmed flush to the
+art (look for `-trim`/`-tight` in the filename); the fix is to re-export the SVG
+with viewBox padding (e.g. widen `viewBox` by ~8% each side) so the stroke never
+touches the edge. Verify the fix by re-running this with the patched asset. (A
+heavy `stroke-width` + `paint-order="stroke"` outline makes a flush viewBox clip
+visibly — and small header renders make it worse, so also check the logo isn't
+shrunk below ~64–72px in the header.)
+
+Also confirm no ANCESTOR clips the logo: walk the logo's parents for
+`overflow:hidden|clip` combined with a fixed height or negative/overlap margin —
+and always judge the logo from a screenshot of the header REGION in context,
+never the logo element in isolation (an element screenshot re-renders the full
+art and hides the clip).
+
+**The inverse bug — an image FLOATING inside its frame (don't blame the file).**
+A full-bleed illustration that renders with a margin of empty frame around it
+usually isn't a bad asset — it's CSS. In blocks-mode the site-template's global
+`:where(.page-content) img{ margin:1rem 0 }` (and a default `border-radius`)
+leaks onto any `<img>` you didn't reset, so a framed hero/figure gets a 1rem gap
+inside its frame and looks like it "floats". Before re-cropping or regenerating,
+**open the actual image file** (`curl` the `.avif`/`.png`) — if the motif fills
+the file edge-to-edge, the float is CSS: set `margin:0` (and `border-radius:0`)
+on the framed `<img>` (e.g. `.your-frame img{margin:0}` or a blanket
+`.your-scope img{margin:0}`). Measure it: the `<img>`'s `getBoundingClientRect`
+should equal its frame's inner box (no gap). Only when the *file itself* has
+built-in background margin (motif ≪ frame) is cropping the right fix.
+
+### 6. Findable (SEO/meta) — curl, fast
+
+`<title>` (≤60 chars) + meta description present + sensible; `og:title/description/image`;
+`canonical`; `favicon` + `apple-touch-icon`; `<html lang>`; branches must be
+`noindex`. One curl + greps covers it.
+
+### 7. Fast (performance)
+
+PASS signals: no render-blocking JS you didn't add; responsive variants
+(`srcset` + AVIF/WebP) so a 1024px asset isn't shipped to a 380px slot;
+`width`/`height` or aspect-ratio set (no layout shift); **below-fold images
+`loading="lazy"`, above-fold `eager`**. Flag a section that eager-loads every
+image, or a multi-hundred-KB original served when a small AVIF variant exists.
+
+### 8. Cross-browser
+
+The same CSS renders differently per engine. Re-check in another engine if you
+can. If only Chromium is available, say so as UNTESTED and statically flag risky
+props: `backdrop-filter` without fallback, `-webkit-`-only masks, `100vh` on
+mobile (prefer `100svh`), `position:sticky` inside `overflow`.
+
+## Deliver a scorecard + an explicit verdict
+
+Report a table — one row per dimension, value PASS / FAIL(detail) / UNTESTED —
+then a one-line verdict. Rules:
+
+- "Approved" requires PASS on responsive, a11y, functional, content, SEO,
+  performance. Untested dimensions (commonly cross-browser, live form submit) are
+  listed as CAVEATS, not silently dropped — an OK with caveats is honest; an
+  unqualified "approved" off a partial pass is not.
+- Brand FIT (palette/voice matching `brand.md`) is a direction judgment, not a
+  pass/fail defect — call it out separately so the user decides direction.
+- If you fixed anything mid-review, re-deploy and re-run the affected dimension
+  before signing off.
+
+See `tr-redesign-branch` for the surrounding branch → preview → approve → merge
+flow; this skill is its measured approval round.

package/skills/tr-redesign-branch.md

@@ -71,6 +71,34 @@ Save the response's `id` — pass it as `version=<id>` on every
 subsequent call. Branches default `robots_blocked: true` so a
 half-finished redesign won't be indexed.
 
+### 2b. Write the design spec (REQUIRED — before you build)
+
+Every redesign branch MUST carry a written design spec. Without it the
+design choices live only in the agent's head, so a later "just tweak the
+illustration style / palette" means re-deriving everything by hand (this
+gap cost a real project a full reverse-engineering pass). Write it BEFORE
+building so it guides the work, and keep it in sync as the design evolves.
+
+Save it as a markdown doc with the project (e.g. `design-spec.md`, or
+`prompts/design-system.md`) — or, if there's no local working dir, as an
+unlisted page on the branch. It must capture:
+
+- **Palette** — every role + hex (background, surface, primary, accent,
+  text, borders), and where the variant *diverges* from the brand and why.
+- **Typography** — fonts + weights/sizes per role.
+- **Illustration / imagery style** — the exact image-gen prompt prefix
+  (tone, palette, formspråk, framing rules), so the imagery can be
+  regenerated or restyled on its own without touching layout. State the
+  business/concept constraints the imagery must respect (a wrong-concept
+  image is worse than none).
+- **Section structure** — the page's sections in order + each one's
+  treatment (band colour, layout).
+- **Rationale** — one line per major choice: *why* this direction.
+
+When the user later says "adjust just the illustrations" or "change the
+palette", you edit the spec first, then apply — the spec is the source of
+truth for the design intent.
+
 ### 3. Iterate on the branch
 
 For each redesign step:
@@ -122,43 +150,84 @@ bulk_replace_text pattern="OldCo" replacement="NewCo" dry_run=false version="<br
 
 ### 6. Approval round
 
-**First, self-review the visuals — appearance AND readability.** Structural
-checks (copy present, no overflow, images return 200) are NOT a design review
-and must never be reported as "approved". Screenshot the deployed branch at
-desktop (~1440px) AND mobile (~390px) and actually look:
-
-- **Logo & brand marks:** fully visible (not cut off by a header's
-  `overflow:hidden` + an overlap/negative margin), legible with real contrast
-  against their *actual* background, and brand-compliant — e.g. a light/yellow
-  wordmark must not sit bare on a light surface (give it its plate/backing).
-  Screenshot the rendered HEADER REGION **in page context** — never the logo
-  element in isolation: an element screenshot renders the full SVG and hides
-  layout clipping, so a logo that's cut in half on the page looks perfect.
-- **Contrast & readability:** every text-on-background pairing (headings, body,
-  buttons, cards on colored bands), not just the obvious ones.
-- **Layout:** no horizontal scroll (`scrollWidth === clientWidth` at 360–390px),
-  no mid-word breaks, nothing clipped or overflowing, clean alignment / spacing /
-  hierarchy. Confirm every image rendered (scroll lazy ones into view first).
-- **Both breakpoints:** a grid fine on desktop can fail to collapse on mobile
-  (see `tr-responsive` gotchas). Check mobile explicitly.
-- **Decoration robustness, in the real browser:** every decorative shape / glow /
-  gradient is clean at real size in the actual target browser (Chrome) — no
-  hairline seam between a shape divider and its section, no glow clipped to a hard
-  edge, no faces cropped by a frame, no gradient fade-cutoff at a section join.
-  These don't show in a thumbnail (see "Restraint beats decoration" above).
+**Self-review is a multi-DIMENSION pass, not a glance — and most of it you
+MEASURE, not eyeball.** Structural checks (copy present, images return 200) are
+NOT a design review; never report "approved" off them. Don't just list the bugs
+you happened to notice — walk every dimension below on the deployed branch
+(browser tool + DOM reads), fix what you find, re-deploy, re-check.
+
+**Use `tr-design-review` (`read_skill tr-design-review`) for the HOW** — it has
+the per-dimension measurement snippets (overflow ladder, computed contrast, touch
+targets, the anti-lazy-load broken-image check) and the scorecard + verdict
+format. The dimension summary below is the "what"; that skill is the runnable
+routine. In particular: scroll-and-settle to trigger lazy images BEFORE any
+full-page screenshot, or you'll report blank boxes that aren't real.
+
+1. **Responsive** — screenshot across a width ladder (mobile / tablet / laptop /
+   desktop / wide ≈390 / 768 / 1024 / 1440 / 1920px) AND sweep the page's own
+   `@media` breakpoints (read the page-scoped `<style>`; resize a few px below +
+   above each). At EVERY width: `document.documentElement.scrollWidth <=
+   clientWidth` (no horizontal scroll), grids flip cleanly, nothing squished /
+   orphaned / overlapping, no mid-word breaks. Two sizes is not enough — bugs hide
+   in between. Also check a short/landscape viewport and 200% browser zoom.
+2. **Visual & brand** — logo FULLY VISIBLE (not clipped by a header
+   `overflow:hidden` + overlap margin) and brand-compliant; screenshot the header
+   IN CONTEXT, never the logo element in isolation (that hides clipping).
+   Decoration robust at real size in the real browser: no hairline seam at a
+   divider (use `core/section` `divider_top`/`divider_bottom` — don't hand-roll a
+   band), no glow clipped to a hard edge, no `object-fit:cover` cropping faces, no
+   gradient fade-cutoff. Typography: body line-length ~45–75ch, consistent scale,
+   no awkward widows on headings. Palette adherence (no off-brand colours);
+   consistent spacing / alignment / radius / shadow.
+3. **Accessibility — MEASURE, don't eyeball** — compute actual contrast ratios
+   (WCAG AA: body ≥4.5:1, large/UI ≥3:1) and fix failures by deepening the
+   offending colour token; meaningful `alt` on every image; exactly one `<h1>` +
+   no skipped heading levels; visible `:focus-visible` on every interactive
+   element; every input has an associated `<label>`; touch targets ≥44px on
+   mobile; semantic landmarks (header/nav/main/footer) + nav `aria-label`; honour
+   `prefers-reduced-motion`.
+4. **Functional** — the form actually works (POST action correct, hidden token
+   non-empty, honeypot present + hidden; a long name/email doesn't break layout);
+   every link + in-page anchor resolves (each `#anchor` has a matching `id`; no
+   `href="#"`/`""`); ZERO console errors/warnings; interactions (menu toggle,
+   hover/focus/active) work.
+5. **Content** — no unrendered `{{…}}` tokens in the DOM; no placeholder/lorem;
+   copy still matches the source of truth (the live page) verbatim.
+6. **Findable (SEO/meta)** — `<title>` + meta description present + sensible;
+   `og:title`/`og:description`/`og:image`; canonical; favicon + apple-touch-icon;
+   `<html lang>`; `noindex` correct (branches must be noindex).
+7. **Fast (performance)** — images at sane sizes (not a 2048px file shown at
+   380px without a responsive variant), modern format (avif/webp), `width`/`height`
+   or aspect-ratio set (no layout shift), below-fold lazy / above-fold eager.
+8. **Cross-browser** — the same CSS renders differently per engine (the divider
+   seam was Chrome-only; WebKit/Firefox have their own). Re-check in another engine
+   if you can; if only Chromium is available, statically flag risky props
+   (`backdrop-filter` without fallback, `-webkit-`-only masks, `100vh` on mobile →
+   prefer `100svh`, `sticky` inside `overflow`).
 
 Fix what you find and re-check before involving the user. "Looks structurally
-fine" ≠ "looks good" — never tell the user a design is approved/perfect off
-metrics alone.
-
-Then send the user a final preview link:
-
-```
-get_preview_link page_id=home version="<branch>" ttl_seconds=86400
-```
-
-The 24h TTL gives them time to share with stakeholders. Wait for an
-explicit "looks good, ship it."
+fine" ≠ "looks good", and "looks good in Chrome at 1440" ≠ "works for everyone,
+everywhere" — never report a design as approved/perfect off a glance or a partial
+pass.
+
+Then send the user a **stable preview URL** — and ALWAYS prefer a stable
+one over a link that goes stale:
+
+- **Stable (use this for sharing / repeat viewing):** the deployed branch's
+  alias URL, `https://<branch>.<project>.pages.dev`. It always serves that
+  branch's *latest* deploy, so the same link keeps working across every
+  re-deploy. Get it by deploying the branch once (`trigger_deploy
+  version="<branch>"`); the `<project>` segment is the part after the hash
+  in the returned `deploy_url` (e.g. `abc123.<project>.pages.dev`). Curl it
+  once to confirm it resolves. (Branch deploys are `robots_blocked`, so it
+  won't be indexed.)
+- **Avoid as the shared link:** the immutable per-deploy hash URL (a new
+  hash every deploy — the user's bookmark dies) and a `get_preview_link`
+  token (expires). Those are fine for your own one-off in-editor checks,
+  not as the canonical link you hand the user.
+
+Default rule: when the user will look more than once, give the stable alias.
+Wait for an explicit "looks good, ship it."
 
 ### 7. Merge + deploy
 
@@ -185,9 +254,11 @@ disk cost is tiny.)
 - **Skipping discovery.** "Modernize" without first reading the site
   produces a confidently-out-of-place result. Always sample existing
   pages.
-- **Editing the in-portal preview URL by mistake.** That's the user's
-  own preview, not yours. `get_preview_link` returns a signed
-  external URL — always use that for sharing.
+- **Handing out a link that goes stale.** Don't give the user the
+  immutable per-deploy hash URL or an expiring `get_preview_link` token as
+  the canonical link — share the stable branch alias
+  `https://<branch>.<project>.pages.dev` (see step 6). `get_preview_link`
+  is for your own one-off in-editor checks.
 - **Auto-merge.** Don't `merge_branch` without explicit user sign-off.
   Once merged, the only undo is another branch + reverse edits.
 - **Header rewrites that drop the brand block.** Even when the