@typeroll/mcp-server 0.24.0 → 0.25.1

package/AGENTS.md

@@ -106,6 +106,14 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   working with blocks — never hardcode block ids or field names, the
   available set is per-site.
 
+  **The core library is larger than you'd guess (~30+ blocks): `core/image`,
+  `core/media_card`, `core/gallery`, `core/hero`, `core/feature_grid`,
+  `core/icon_box`, `core/cta`, `core/testimonial`, `core/accordion`, …** Before
+  you report a block as "missing" or reach for a `core/html` workaround, call
+  `list_block_types` and check — a real build once hand-built every illustration
+  in `core/html` and filed a false "no image block" gap because the library was
+  never enumerated. Prefer a native block; `core/html` is the last resort.
+
   Block-library specifics worth knowing (template_capabilities_version
   0.15.0):
   - **`core/media_card`** — image + text side by side (image left/right,
@@ -204,7 +212,11 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   everything you write through `?version=<branch-id>` lives on the
   branch until you `merge_branch` it back to main. Branches default
   `robots_blocked: true` so a half-finished redesign can't be indexed,
-  and deploys land at a stable `{branch}.{project}.pages.dev` URL.
+  and deploys land at a stable `{branch}.{project}.pages.dev` URL. That
+  branch deploy renders the site's full inherited brand (settings, fonts,
+  favicon, header/footer — everything not overridden on the branch), so
+  it's a faithful preview of what merging to main will look like, not just
+  a content diff — trust it for stakeholder review.
 
 - **Deploys.** Customers see live changes only after a deploy. Preview
   always sees drafts. `trigger_deploy` enqueues; `get_deploy_status`
@@ -216,6 +228,16 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
     - `preview_base` — the portal preview origin (for token URLs)
   Use these in answers to "what's the URL?" — never invent.
 
+- **Share STABLE preview URLs, never throwaway ones.** When you give the
+  user a link they'll open more than once (a branch preview, a redesign to
+  review), give the **stable branch alias** `https://{branch}.{project}.pages.dev`
+  — it always serves that branch's latest deploy, so the link survives every
+  re-deploy. The immutable per-deploy hash URL (`{hash}.{project}.pages.dev`,
+  a new hash each deploy) and an expiring `get_preview_link` token are for
+  your OWN one-off checks — handing them to the user means their bookmark
+  dies on the next deploy. Default: user will look more than once → stable
+  alias.
+
 ## Discovering this site
 
 Don't hardcode assumptions about what's here. Every fact about the site
@@ -579,18 +601,43 @@ After any non-trivial change, call `get_preview_link` and ask the user
 (or your own browser tool) to confirm the result before moving on. One
 HTTP call vs. shipping a broken redesign — always worth it.
 
-**A design review covers appearance AND readability — not just structure.**
-If you have a browser tool, screenshot at desktop (~1440px) and mobile (~390px)
-and actually judge the visuals before telling the user it's done: logo fully
-visible (not cut off by a header's overflow:hidden + overlap margin) + legible +
-brand-compliant against its real background — screenshot the header in page
-context, NOT the logo element in isolation (an element shot renders the full SVG
-and hides layout clipping); a light/yellow wordmark must not sit bare on a light
-surface without its plate. Text contrast on every
-band, no horizontal scroll (`scrollWidth === clientWidth` at 360–390px), no
-mid-word breaks, all images rendered, mobile layout actually collapsed. "Copy
-present + no overflow + images 200" is a structural check, NOT a design review —
-never report a design as perfect/approved off structural metrics alone.
+**To UNDERSTAND a page, render it to one HTML file — don't reconstruct it
+from the block tree in your head.** A page is assembled at render time from the
+block tree + each block type's template/styles + the header/footer partials +
+the settings CSS variables + the global shell + page-scoped styles. `get_page_blocks`
+gives you the editable *structure*; `get_page_preview` gives you the rendered
+*result* — the WHOLE page as one self-contained HTML document (header + body +
+footer, with all of that CSS inlined), exactly as deployed. Read that when you
+need to see what the page actually looks like or why its CSS cascades the way it
+does (write it to a local file + serve+screenshot it to review visually). Pass
+`annotate:true` to tag every element with `data-block-id` + `data-block-type`,
+so you can map a spot in the rendered HTML straight back to the block to edit:
+read preview to understand → find the element → its `data-block-id` is the block
+to mutate → edit → re-render to verify.
+
+**A design review is a multi-DIMENSION, MEASURED pass — not "copy present + no
+overflow + images 200".** If you have a browser tool, walk every dimension (the
+`tr-redesign-branch` skill has the full checklist with how-to):
+- **Responsive** — width ladder (≈390/768/1024/1440/1920px) + a sweep just below/
+  above the page's own @media breakpoints; `scrollWidth <= clientWidth` at every
+  width (bugs hide between the two extremes); + 200% zoom.
+- **Visual & brand** — logo FULLY visible (screenshot the header IN CONTEXT, never
+  the logo element in isolation — that hides clipping) + brand-compliant; no
+  divider seams / clipped glows / cropped faces / fade-cutoffs; typography +
+  palette + spacing consistent.
+- **Accessibility (measure)** — actual contrast ratios (AA 4.5:1 / 3:1), alt on
+  every image, one `<h1>` + no skipped levels, visible focus, labels on inputs,
+  ≥44px touch targets, landmarks, reduced-motion.
+- **Functional** — form actually works (action + token + honeypot, long values
+  don't break), every link/`#anchor` resolves, ZERO console errors.
+- **Content** — no unrendered `{{…}}`, no placeholder, copy matches the live page.
+- **Findable** — title + meta description + og:* + canonical + favicon + lang +
+  noindex-on-branch.
+- **Fast** — images sized right + modern format + width/height set + lazy/eager.
+- **Cross-browser** — re-check another engine if possible, or flag risky props
+  (backdrop-filter, -webkit- masks, 100vh→100svh, sticky-in-overflow).
+"Looks good in Chrome at 1440" ≠ "works for everyone, everywhere" — never report a
+design as perfect/approved off a glance or a partial pass.
 
 Preview shows DB state (drafts included). Live (`get_site → urls.production`)
 shows the most recent deploy. Branch deploys live at