@typeroll/mcp-server 0.25.0 → 0.25.2

package/AGENTS.md

@@ -212,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`
@@ -224,6 +228,23 @@ 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.
 
+- **For design/content iteration, share the DB-LIVE preview — don't deploy.**
+  `get_preview_link` renders straight from the database with NO build, so a
+  reload shows every edit immediately. Mint it ONCE with the long TTL
+  (`ttl_seconds: 86400`, the 24h max) and REUSE that single URL: it's stable
+  across edits (internal links keep the token, so one link navigates the whole
+  branch), and you only re-mint when the 24h lapses — never per edit. This is
+  both the link you hand the user while iterating AND what you open to verify
+  your own changes. Do NOT `trigger_deploy` merely to preview a content/design
+  change — a deploy builds static pages (slow) and only reflects state as of
+  that build.
+- **Deploys / `{branch}.{project}.pages.dev` are the STATIC BUILD**, refreshed
+  only by `trigger_deploy`. Reach for them when you want the real compiled
+  output: publishing, a stakeholder link to the built site, or a faithful
+  pre-merge check. The branch alias is permanent across re-deploys; the
+  per-deploy `{hash}.pages.dev` is immutable per build. Reserve deploys for
+  these — not for previewing edits.
+
 ## Discovering this site
 
 Don't hardcode assumptions about what's here. Every fact about the site
@@ -305,8 +326,8 @@ list_pages → batch_read_pages a few existing pages    # learn conventions
 # Propose redesign locally; ask user to confirm.
 create_branch name="Home redesign"                    # ID is, say, "home-redesign"
 update_page page_id=home patch={ html_content: "…" } version=home-redesign
-get_preview_link page_id=home version=home-redesign   # signed clickable URL
-# Iterate. When approved:
+get_preview_link page_id=home version=home-redesign ttl_seconds=86400  # DB-live URL — mint once, reuse while iterating (no deploy)
+# Iterate (reload the same link after each edit). When approved:
 merge_branch version_id=home-redesign
 trigger_deploy
 ```
@@ -583,9 +604,11 @@ can manually deprovision the old one via the portal.
 
 ## Preview-driven workflow
 
-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.
+After any non-trivial change, verify against the DB-live `get_preview_link`
+(reused — mint once at the 24h TTL) and/or your own browser tool before moving
+on. It reflects the DB instantly with no build, so it — not a deploy — is the
+loop for design/content iteration. One reload vs. shipping a broken redesign —
+always worth it.
 
 **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
@@ -601,18 +624,29 @@ 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 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.
+**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
@@ -630,9 +664,11 @@ The response includes `id` — pass that as `version=<id>` on every
 subsequent call. The branch is independent of main; writes don't affect
 the live site until you `merge_branch`.
 
-Branches default `robots_blocked: true`. Deploys to a branch land at a
-stable, share-able URL (`{branch}.{project}.pages.dev`); use that for
-stakeholder review.
+Branches default `robots_blocked: true`. While iterating, preview the branch
+with a reused `get_preview_link` (DB-live, no build). Deploys to a branch land
+at a stable URL (`{branch}.{project}.pages.dev`) — that's the compiled static
+build, for sharing the finished result / stakeholder review, not per-edit
+preview.
 
 ## When in doubt