@typeroll/mcp-server 0.25.0 → 0.25.2

package/dist/tools/deploy.js

@@ -6,7 +6,7 @@ function v(version) {
 export const deployTools = [
     {
         name: 'trigger_deploy',
-        description: "Enqueue a deploy of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running. With `dry_run: true`, the deploy runs through every step EXCEPT the hosting-adapter upload — useful for validating a structural change (new collection routes, schema bump, mode switch) without risking the live site. A dry_run job that succeeds proves the build is clean; one that fails returns the same astro stack-trace in get_deploy_status.error as a real deploy would.",
+        description: "Enqueue a deploy (static-page build → hosting) of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running. NOT for previewing iterative design/content edits — that's what get_preview_link is for (it renders live from the DB with no build). Reserve trigger_deploy for publishing, a stakeholder link to the compiled site, or pre-merge validation. With `dry_run: true`, the deploy runs through every step EXCEPT the hosting-adapter upload — useful for validating a structural change (new collection routes, schema bump, mode switch) without risking the live site. A dry_run job that succeeds proves the build is clean; one that fails returns the same astro stack-trace in get_deploy_status.error as a real deploy would.",
         inputSchema: {
             environment: z.enum(['production', 'staging']).optional(),
             dry_run: z.boolean().optional().describe('Run the build but skip the CDN upload. The job ends in succeeded/failed the same way a real deploy does.'),

package/dist/tools/preview.js

@@ -6,7 +6,7 @@ function v(version) {
 export const previewTools = [
     {
         name: 'get_preview_link',
-        description: 'Mint a short-lived signed URL the user (or your own browser tool) can open to SEE the rendered preview. Internal links inside the preview keep the same token attached, so the agent can navigate the whole site from one mint. Default TTL 15 min, max 24h. Target the preview at a page (page_id), a collection item (collection_name + item_id, resolves via route_template), or a raw slug. Omit all to land on the home page.',
+        description: 'Mint a signed URL the user (or your own browser tool) can open to SEE the rendered preview. Renders LIVE from the database with NO build, so reloading shows every edit immediately — this is the PREFERRED way to preview design/content changes as you iterate (and to verify your own edits); reach for this, not trigger_deploy, when previewing. Mint it ONCE with the long TTL (ttl_seconds: 86400 = 24h max) and REUSE that single URL across edits — internal links keep the token so it navigates the whole branch, and it stays valid until the TTL lapses (re-mint only then, never per edit). Default TTL 15 min, max 24h. Target a page (page_id), a collection item (collection_name + item_id, resolves via route_template), or a raw slug; omit all to land on the home page. (For a permanently-bookmarkable link to the COMPILED static site, deploy and share the {branch}.{project}.pages.dev alias instead — that only refreshes on trigger_deploy.)',
         inputSchema: {
             page_id: z.string().optional(),
             slug: z.string().optional(),

package/dist/version.js

@@ -1,7 +1,11 @@
-// Single source of truth for the server version reported in the MCP
-// `initialize` handshake. Derived from package.json at runtime so it can
-// never drift from the published version (bumping package.json is enough).
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-export const VERSION = pkg.version;
+// 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.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "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,301 @@
+---
+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 URL for the version under review. While iterating, use the DB-live
+   `get_preview_link` (mint once at `ttl_seconds: 86400`, reuse) — it renders
+   from the DB with no build, so fixes show on reload without re-deploying, and
+   it's the loop for the review-fix-recheck cycle. For a FINAL bit-for-bit check
+   of the compiled output before merge, deploy once (`trigger_deploy
+   version="<branch>"` → poll `get_deploy_status` → use the immutable
+   `deploy_url`, a Cloudflare Pages hash URL). 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, just reload the DB-live preview and re-run
+  the affected dimension before signing off — no re-deploy needed (deploy only
+  for the final compiled-output check, if any).
+
+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,86 @@ 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 DB-live preview
+(a reused `get_preview_link`; browser tool + DOM reads), fix what you find,
+reload, re-check. No re-deploy between fixes — the preview renders from the DB.
+
+**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 give the user the **DB-live preview link** to review — and use the SAME
+link for your own verification:
+
+- **While iterating (default):** a reused `get_preview_link` (mint once at
+  `ttl_seconds: 86400`). It renders from the database with NO build, so every
+  edit shows on reload, and one link navigates the whole branch (internal
+  links keep the token). The token URL is stable across edits — re-mint only
+  when the 24h lapses, never per edit. Do NOT deploy just to let the user (or
+  yourself) see a change.
+- **When they want the COMPILED static site** (a permanent bookmark, a
+  stakeholder link to the built output, or a final pre-merge check): deploy
+  the branch once (`trigger_deploy version="<branch>"`) and share the stable
+  alias `https://<branch>.<project>.pages.dev` (the `<project>` is the part
+  after the hash in the returned `deploy_url`). Branch deploys are
+  `robots_blocked`, so it won't be indexed. The immutable per-deploy
+  `<hash>.pages.dev` is for your own one-off checks (a new hash each deploy).
+
+Default: review/iterate on the reused DB-live preview; deploy only for the
+compiled output or merge. Wait for an explicit "looks good, ship it."
 
 ### 7. Merge + deploy
 
@@ -185,9 +256,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.
+- **Deploying to preview.** Don't `trigger_deploy` after every edit just to
+  see the change — that builds static pages and the URL is only as fresh as
+  the last build. Iterate on a reused DB-live `get_preview_link` (renders from
+  the DB, reflects edits on reload); deploy only for the compiled static
+  output or merge (steps 6–7).
 - **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