@typeroll/mcp-server 0.21.0 → 0.24.0

package/dist/tools/block-types.js

@@ -5,6 +5,32 @@ import { ok, withErrorBoundary, versionParam } from './helpers.js';
 function v(version) {
     return version ? { version } : undefined;
 }
+// The per-block markup. These three fields dominate the payload size (a few
+// dozen blocks of template HTML + scoped CSS can exceed an agent's token
+// budget and get truncated), and an agent enumerating the library rarely
+// needs them — read_block_type fetches them for one block on demand. So
+// list_block_types omits them by default and returns a lightweight summary.
+const HEAVY_BLOCK_TYPE_FIELDS = ['template', 'styles', 'script'];
+/** Strip the heavy markup fields from each block type in a `block-types`
+ *  response, preserving the field `schema` and all light metadata. Defensive:
+ *  if the shape isn't the expected `{ block_types: [...] }`, pass it through. */
+function summariseBlockTypes(res) {
+    if (!res || typeof res !== 'object')
+        return res;
+    const envelope = res;
+    const list = envelope.block_types;
+    if (!Array.isArray(list))
+        return res;
+    const slim = list.map((bt) => {
+        if (!bt || typeof bt !== 'object')
+            return bt;
+        const copy = { ...bt };
+        for (const field of HEAVY_BLOCK_TYPE_FIELDS)
+            delete copy[field];
+        return copy;
+    });
+    return { ...envelope, block_types: slim };
+}
 export const blockTypeTools = [
     {
         name: 'export_block_types',
@@ -44,9 +70,13 @@ export const blockTypeTools = [
     },
     {
         name: 'list_block_types',
-        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), custom blocks (origin: "user", created in the portal), and third-party blocks (origin: "third_party", imported from .tcblocks packages). Each entry includes id, label, category, container/slot info, origin, and the full schema (fields with name/type/label/required/options/default). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site.',
+        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), custom blocks (origin: "user", created in the portal), and third-party blocks (origin: "third_party", imported from .tcblocks packages). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site. By default this is a LIGHTWEIGHT SUMMARY: each entry has id, label, category, icon, container/slot info, origin, and the full field schema (name/type/label/required/options/default) — everything you need to pick a block and call add_block — but NOT the render-time markup. The per-block template HTML, scoped styles, and script are omitted so the list stays within token budget no matter how large the library grows; fetch them for a single block with read_block_type, or pass full:true to inline them for every block (can be very large).',
         inputSchema: {
             include_core: z.boolean().optional().describe('Default true. Set false to get only custom + third-party (rarely needed).'),
+            full: z
+                .boolean()
+                .optional()
+                .describe("Default false. When true, include each block type's template HTML, styles CSS, and script inline — the full doc. Large; prefer read_block_type for one block's markup."),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -56,7 +86,7 @@ export const blockTypeTools = [
             if (args.include_core === false)
                 query.include_core = 'false';
             const res = await client.get(siteId, 'block-types', query);
-            return ok(res);
+            return ok(args.full ? res : summariseBlockTypes(res));
         }),
     },
     {

package/dist/tools/skills.js

@@ -1,32 +1,34 @@
 // Skill-discovery tools — the self-describing playbook layer.
 //
-// The package bundles a set of `tr-*.md` skill recipes under `skills/`. Until
-// now they were only useful if the operator happened to copy them into
-// `.claude/skills/` (see install-skills.ts) — the running MCP server never
-// advertised them, so an agent had no way to learn that e.g. `tr-new-site`
-// exists. These two tools fix that by exposing the bundled skills directly
-// on the tool surface, identically over stdio and the hosted HTTP transport.
+// The package bundles a set of `tr-*.md` skill recipes under `skills/` plus an
+// AGENTS.md operating guide at the package root. These tools expose that
+// content directly on the tool surface so an agent discovers the platform's
+// playbook at connection time — over stdio AND the hosted HTTP transport.
 //
-// Both are pure LOCAL file reads: they do NOT touch the REST API and need
-// neither TYPEROLL_API_KEY nor TYPEROLL_API_URL nor a site context. That's
-// why they're flagged `noSite: true` — in multi-site (hosted) mode the
-// server skips the usual `site_id` injection/validation for them.
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
+// IMPORTANT: the content is read from the EMBEDDED module (bundled-content.ts,
+// generated by scripts/embed-content.mjs), NOT from disk. The hosted endpoint
+// runs inside the portal, which bundles this package — after bundling a runtime
+// `fs.readFile('../skills/…')` resolves into the portal's build output and
+// fails with ENOENT, so disk reads crash list_skills/read_skill/read_guide on
+// hosted. Embedded string lookups survive bundling. (The install-skills/init
+// CLI still copies the physical files — but that only runs locally, where the
+// files exist.)
+//
+// All three tools are pure in-memory lookups: no REST API, no API key, no site
+// context — hence `noSite: true` (multi-site mode skips site_id for them).
 import { z } from 'zod';
-import { skillsDir } from '../install-skills.js';
+import { BUNDLED_SKILLS, BUNDLED_DOCS } from '../bundled-content.js';
 import { ok, withErrorBoundary } from './helpers.js';
-/** The only basenames `read_skill` will resolve. Matches the install-skills
- *  copy filter (`tr-*.md`) and, because it forbids slashes and dots, is also
- *  the primary defence against path traversal. */
+/** The only names `read_skill` will resolve. Matches the `tr-*.md` convention
+ *  and, by forbidding slashes/dots, doubles as input hygiene. */
 export const SKILL_NAME_RE = /^tr-[a-z0-9-]+$/;
 /**
  * Pull `name:` / `description:` out of a skill file's YAML frontmatter.
  *
  * The frontmatter is a flat block we author by hand (two single-line keys),
  * so a deliberately tiny regex parse beats pulling in a YAML dependency.
- * Falls back to the filename-derived name when `name:` is absent and to an
- * empty description when `description:` is.
+ * Falls back to the given name when `name:` is absent and to an empty
+ * description when `description:` is.
  */
 export function parseSkillFrontmatter(markdown, fallbackName) {
     let name = fallbackName;
@@ -43,62 +45,63 @@ export function parseSkillFrontmatter(markdown, fallbackName) {
     }
     return { name, description };
 }
-/** List the bundled skills (name + description) from `sourceDir`. Pure read;
- *  `sourceDir` defaults to the bundled `skills/` dir but is injectable for
- *  tests. */
-export async function listBundledSkills(sourceDir = skillsDir()) {
-    const entries = await fs.readdir(sourceDir);
-    const files = entries.filter((f) => f.startsWith('tr-') && f.endsWith('.md')).sort();
-    const skills = [];
-    for (const file of files) {
-        const raw = await fs.readFile(path.join(sourceDir, file), 'utf8');
-        skills.push(parseSkillFrontmatter(raw, file.replace(/\.md$/, '')));
-    }
-    return skills;
+/** List the bundled skills (name + description) from the embedded content. */
+export function listBundledSkills() {
+    return Object.keys(BUNDLED_SKILLS)
+        .sort()
+        .map((key) => parseSkillFrontmatter(BUNDLED_SKILLS[key], key));
 }
-/** Read one bundled skill's markdown by name. Rejects anything that isn't a
- *  `tr-<kebab>` basename and, belt-and-suspenders, verifies the resolved path
- *  stays inside `sourceDir`. */
-export async function readBundledSkill(name, sourceDir = skillsDir()) {
+/** Return one bundled skill's markdown by name. Rejects anything that isn't a
+ *  `tr-<kebab>` name or isn't a known skill. */
+export function readBundledSkill(name) {
     if (!SKILL_NAME_RE.test(name)) {
         throw new Error(`invalid skill name "${name}" — expected tr-<kebab-case>, e.g. tr-new-site. Use list_skills to see available skills.`);
     }
-    const root = path.resolve(sourceDir);
-    const target = path.resolve(root, `${name}.md`);
-    // The regex already blocks `/` and `.`, so traversal can't get here — but
-    // confirm the join landed exactly where we expect before touching disk.
-    if (path.dirname(target) !== root) {
-        throw new Error(`refusing to read outside the skills directory: ${name}`);
-    }
-    try {
-        return await fs.readFile(target, 'utf8');
-    }
-    catch {
+    const content = BUNDLED_SKILLS[name];
+    if (content === undefined) {
         throw new Error(`skill "${name}" not found. Use list_skills to see available skills.`);
     }
+    return content;
+}
+/** Return a bundled package doc by whitelisted key (`agents` | `readme`). */
+export function readPackageDoc(key) {
+    const content = BUNDLED_DOCS[key];
+    if (content === undefined) {
+        throw new Error(`unknown guide "${key}". Available: ${Object.keys(BUNDLED_DOCS).join(', ')}.`);
+    }
+    return content;
 }
 export const skillTools = [
+    {
+        name: 'read_guide',
+        description: "Return the full Typeroll agent guide (the bundled AGENTS.md): platform conventions, the data model in 90 seconds, common operations with worked recipes, safety boundaries, and the tool-family reference. Read it once at the start of a session for the complete operating context — especially on the hosted connector, where the file isn't on disk for the client to fold in. Pass doc='readme' for the package README instead. Pure in-memory read: no API key or site required.",
+        inputSchema: {
+            doc: z
+                .enum(['agents', 'readme'])
+                .optional()
+                .describe("Which guide to return: 'agents' (default — the full operating briefing) or 'readme'."),
+        },
+        noSite: true,
+        handler: withErrorBoundary(async (args) => ok(readPackageDoc(args.doc ?? 'agents'))),
+    },
     {
         name: 'list_skills',
-        description: 'List the bundled Typeroll playbook skills (name + description). Call this EARLY — the moment the user wants to build, migrate, redesign, brand, or otherwise design a site — to discover the step-by-step recipe that fits (e.g. tr-new-site, tr-migrate-wp, tr-brand, tr-blog), then read_skill the most relevant one before acting. Pure local read: no API key and no site required, so it works on the hosted connector and stdio alike.',
+        description: 'List the bundled Typeroll playbook skills (name + description). Call this EARLY — the moment the user wants to build, migrate, redesign, brand, or otherwise design a site — to discover the step-by-step recipe that fits (e.g. tr-new-site, tr-migrate-wp, tr-brand, tr-blog, tr-responsive), then read_skill the most relevant one before acting. Pure in-memory read: no API key and no site required, so it works on the hosted connector and stdio alike.',
         noSite: true,
         handler: withErrorBoundary(async () => {
-            const skills = await listBundledSkills();
+            const skills = listBundledSkills();
             return ok({ skills, count: skills.length });
         }),
     },
     {
         name: 'read_skill',
-        description: 'Return the full markdown of one bundled skill by name (e.g. "tr-new-site"). Use it after list_skills to load the playbook for the task at hand. Pure local read: no API key and no site required.',
+        description: 'Return the full markdown of one bundled skill by name (e.g. "tr-new-site"). Use it after list_skills to load the playbook for the task at hand. Pure in-memory read: no API key and no site required.',
         inputSchema: {
             name: z
                 .string()
                 .describe('Skill name without the .md extension, e.g. "tr-new-site". Must match /^tr-[a-z0-9-]+$/.'),
         },
         noSite: true,
-        handler: withErrorBoundary(async (args) => {
-            const content = await readBundledSkill(args.name);
-            return ok(content);
-        }),
+        handler: withErrorBoundary(async (args) => ok(readBundledSkill(args.name))),
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "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": {
@@ -28,6 +28,8 @@
     "skills"
   ],
   "scripts": {
+    "gen": "node scripts/embed-content.mjs",
+    "prebuild": "node scripts/embed-content.mjs",
     "build": "tsc -p .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

package/skills/tr-header-footer.md

@@ -0,0 +1,174 @@
+---
+name: tr-header-footer
+description: Vetted, robust header and footer presets to drop into the header/footer partials. Use when building or restyling a site's site-wide header or footer — start from a preset and restyle it instead of hand-rolling layout + overflow (the usual source of clipped logos and broken mobile menus).
+---
+
+# Header & footer presets
+
+Headers and footers are the two partials every page shows, and hand-rolling them
+is where logos get clipped and mobile menus break. **Start from a preset below,
+fill the placeholders, restyle with the site's colours — don't build the layout
+from scratch.** Each preset is deliberately robust; the "why" notes call out the
+traps it avoids.
+
+## How to use
+
+1. `read_site_settings` — grab `logo`, `site_name`, `tagline`, `contact.email`,
+   and the colour palette.
+2. `read_partial partial_id="header"` (and `footer`) — see what's already there;
+   don't blow away a working one without reason.
+3. Pick a preset, replace every `{{PLACEHOLDER}}`, adjust colours to the palette
+   (the presets already read `--color-*` / `--font-heading` with fallbacks).
+4. `update_partial partial_id="header" patch={ html_content: "…" } version="…"`.
+5. **Preview and self-review in context** (see `tr-redesign-branch` step 6):
+   the logo must be FULLY VISIBLE (not clipped), legible against its background,
+   and the mobile layout must work at 390px. Screenshot the header region in
+   context — never the logo element in isolation (that hides clipping).
+
+Placeholders: `{{SITE_NAME}}`, `{{LOGO_URL}}`, `{{TAGLINE}}`, `{{EMAIL}}`, `{{YEAR}}`.
+
+---
+
+## Header A — Centered logo (minimal; landing pages)
+
+```html
+<header class="tr-hdr tr-hdr--center">
+  <a class="tr-hdr-logo" href="/" aria-label="{{SITE_NAME}} — till startsidan">
+    <img src="{{LOGO_URL}}" alt="{{SITE_NAME}}" />
+  </a>
+</header>
+<style>
+.tr-hdr--center{background:var(--color-surface,#fff);display:flex;justify-content:center;padding:clamp(1rem,2.5vw,1.6rem) 1.5rem}
+.tr-hdr-logo{display:inline-block;line-height:0;transition:transform .15s ease}
+.tr-hdr-logo:hover{transform:translateY(-1px)}
+.tr-hdr-logo img{height:clamp(40px,6vw,58px);width:auto;display:block}
+</style>
+```
+
+**Why it's robust:** no `overflow:hidden` anywhere near the logo (the #1 cause of a
+clipped wordmark); the logo sizes by `height` with `width:auto` so it never
+distorts and never gets cropped; symmetric padding so it can't collide with the
+section below. If you want a tinted header, set a solid `background` — don't add a
+glow that has to be clipped.
+
+## Header B — Logo left + links right (no-JS responsive menu)
+
+```html
+<header class="tr-hdr tr-hdr--nav">
+  <div class="tr-hdr-inner">
+    <a class="tr-hdr-logo" href="/" aria-label="{{SITE_NAME}} — till startsidan">
+      <img src="{{LOGO_URL}}" alt="{{SITE_NAME}}" />
+    </a>
+    <input type="checkbox" id="tr-nav-toggle" class="tr-nav-toggle" aria-hidden="true" />
+    <label for="tr-nav-toggle" class="tr-nav-burger" aria-label="Meny"><span></span><span></span><span></span></label>
+    <nav class="tr-hdr-nav" aria-label="Huvudmeny">
+      <a href="/">Start</a>
+      <a href="#">Sidan ett</a>
+      <a href="#">Sidan två</a>
+      <a class="tr-hdr-cta" href="#kontakt">Kontakta oss</a>
+    </nav>
+  </div>
+</header>
+<style>
+.tr-hdr--nav{background:var(--color-surface,#fff);border-bottom:1px solid rgba(0,0,0,.06)}
+.tr-hdr-inner{max-width:1160px;margin:0 auto;padding:.9rem 1.5rem;display:flex;align-items:center;justify-content:space-between;gap:1rem;flex-wrap:wrap}
+.tr-hdr-logo{line-height:0}
+.tr-hdr-logo img{height:clamp(36px,4.6vw,50px);width:auto;display:block}
+.tr-hdr-nav{display:flex;align-items:center;gap:clamp(1rem,2.4vw,2rem);font-family:var(--font-heading),sans-serif;font-weight:600}
+.tr-hdr-nav a{color:var(--color-text,#1a1a1a);text-decoration:none}
+.tr-hdr-nav a:hover{color:var(--color-primary,#1F4FB8)}
+.tr-hdr-cta{background:var(--color-primary,#1F4FB8);color:var(--color-primary-fg,#fff);padding:.6rem 1.2rem;border-radius:999px}
+.tr-hdr-cta:hover{filter:brightness(1.05);color:var(--color-primary-fg,#fff)}
+.tr-nav-toggle{display:none}
+.tr-nav-burger{display:none;flex-direction:column;gap:5px;cursor:pointer;padding:.4rem}
+.tr-nav-burger span{width:24px;height:2px;background:var(--color-text,#1a1a1a);border-radius:2px}
+@media(max-width:760px){
+  .tr-nav-burger{display:flex}
+  .tr-hdr-nav{flex-basis:100%;flex-direction:column;align-items:stretch;gap:.2rem;max-height:0;overflow:hidden;transition:max-height .25s ease}
+  .tr-hdr-nav a{padding:.7rem .2rem}
+  .tr-nav-toggle:checked ~ .tr-hdr-nav{max-height:60vh}
+}
+</style>
+```
+
+**Why it's robust:** the mobile menu is a pure-CSS checkbox toggle — no JS to break,
+no library. The `overflow:hidden` is ONLY on the collapsing nav list (never on the
+header or the logo), so the logo is always fully visible. Links use site colour
+variables so it matches the brand automatically. The header wraps (`flex-wrap`) so
+nothing overflows the viewport on narrow screens.
+
+---
+
+## Footer A — Centered minimal
+
+```html
+<footer class="tr-ftr tr-ftr--center">
+  <div class="tr-ftr-inner">
+    <div class="tr-ftr-brand">{{SITE_NAME}}</div>
+    <p class="tr-ftr-tag">{{TAGLINE}}</p>
+    <p class="tr-ftr-contact"><a href="mailto:{{EMAIL}}">{{EMAIL}}</a></p>
+    <p class="tr-ftr-copy">© {{YEAR}} {{SITE_NAME}}</p>
+  </div>
+</footer>
+<style>
+.tr-ftr--center{background:var(--color-primary,#163C8C);color:rgba(255,255,255,.78)}
+.tr-ftr--center .tr-ftr-inner{max-width:1120px;margin:0 auto;padding:2.6rem 1.5rem;text-align:center;display:grid;gap:.45rem}
+.tr-ftr-brand{font-family:var(--font-heading),sans-serif;font-weight:800;font-size:1.35rem;color:#fff}
+.tr-ftr-tag{margin:0;font-size:1rem;color:rgba(255,255,255,.85)}
+.tr-ftr-contact{margin:.15rem 0 0}
+.tr-ftr-contact a{color:#fff;text-decoration:none;font-weight:600}
+.tr-ftr-contact a:hover{text-decoration:underline}
+.tr-ftr-copy{margin:.8rem 0 0;font-size:.85rem;color:rgba(255,255,255,.55)}
+</style>
+```
+
+## Footer B — Three columns (brand · links · contact)
+
+```html
+<footer class="tr-ftr tr-ftr--cols">
+  <div class="tr-ftr-grid">
+    <div class="tr-ftr-col">
+      <div class="tr-ftr-brand">{{SITE_NAME}}</div>
+      <p class="tr-ftr-tag">{{TAGLINE}}</p>
+    </div>
+    <nav class="tr-ftr-col" aria-label="Sidfot">
+      <a href="/">Start</a>
+      <a href="#">Sidan ett</a>
+      <a href="#">Sidan två</a>
+    </nav>
+    <div class="tr-ftr-col">
+      <p class="tr-ftr-contact"><a href="mailto:{{EMAIL}}">{{EMAIL}}</a></p>
+    </div>
+  </div>
+  <p class="tr-ftr-copy">© {{YEAR}} {{SITE_NAME}}</p>
+</footer>
+<style>
+.tr-ftr--cols{background:var(--color-primary,#163C8C);color:rgba(255,255,255,.78)}
+.tr-ftr--cols .tr-ftr-grid{max-width:1120px;margin:0 auto;padding:3rem 1.5rem 1.4rem;display:grid;grid-template-columns:1.4fr 1fr 1fr;gap:2rem}
+.tr-ftr--cols .tr-ftr-brand{font-family:var(--font-heading),sans-serif;font-weight:800;font-size:1.35rem;color:#fff;margin-bottom:.4rem}
+.tr-ftr--cols .tr-ftr-tag{margin:0;color:rgba(255,255,255,.8);max-width:34ch}
+.tr-ftr--cols .tr-ftr-col{display:grid;gap:.5rem;align-content:start}
+.tr-ftr--cols nav a{color:rgba(255,255,255,.85);text-decoration:none}
+.tr-ftr--cols nav a:hover{color:#fff;text-decoration:underline}
+.tr-ftr-contact a{color:#fff;text-decoration:none;font-weight:600}
+.tr-ftr--cols .tr-ftr-copy{max-width:1120px;margin:0 auto;padding:0 1.5rem 2.4rem;font-size:.85rem;color:rgba(255,255,255,.55)}
+@media(max-width:680px){.tr-ftr--cols .tr-ftr-grid{grid-template-columns:1fr;gap:1.4rem}}
+</style>
+```
+
+**Why these footers are robust:** the columns collapse to one at 680px (no
+horizontal scroll); all colours come from `--color-*` with fallbacks; the contact
+is a real `mailto:` link; nothing relies on fixed heights. Swap `--color-primary`
+for a custom dark if the brand's primary is too light for white text.
+
+---
+
+## Restyling notes
+
+- The logo always comes from `read_site_settings → logo`. If it's `null`, set it
+  first (upload + `update_site_settings`) — don't hard-code a path.
+- For a **shaped transition** from the header/footer into the page, don't build a
+  wave band by hand — that belongs to the adjacent `core/section` via its
+  `divider_top` / `divider_bottom` (see `tr-redesign-branch`).
+- Keep the brand mark + a way home. Even a dramatic redesign keeps the logo
+  linking to `/`.

package/skills/tr-new-site.md

@@ -70,6 +70,13 @@ different lockup.
 
 ### 3. Header + footer partials
 
+**Start from a vetted preset — don't hand-roll the layout.** `read_skill
+tr-header-footer` has robust header + footer presets (centered logo, logo+nav
+with a no-JS mobile menu, centered + 3-column footers) that avoid the usual
+traps: clipped logos (no `overflow:hidden` near the logo), distorted logos
+(`height` + `width:auto`), and broken mobile menus. Fill the placeholders and
+restyle to the palette.
+
 Partials are usually simplest in HTML mode (one nav, a few links — no
 per-field editing needed). Keep them lean; literal site name (no template
 engine in partials):
@@ -219,6 +226,17 @@ get_preview_link                  # signed URL for browser review
 get_page_preview page_id="home"   # rendered HTML for structural checks
 ```
 
+**Self-review the visuals before you call it done — appearance AND
+readability, not just structure.** Screenshot the deployed/preview site at
+desktop (~1440px) and mobile (~390px) and look: logo FULLY VISIBLE (not clipped by
+a header's overflow:hidden) + legible + brand-compliant against its actual
+background — screenshot the header IN CONTEXT, not the logo element in isolation
+(an element shot hides layout clipping); a light wordmark must not sit bare on a
+light surface. Text contrast everywhere, no horizontal scroll or mid-word
+breaks, every image rendered, mobile layout actually collapsed. "No overflow +
+copy present" is not a design review — never report a build as done/perfect off
+structural metrics alone.
+
 Share the preview link. Iterate on feedback with `update_block` /
 `add_block` / `move_block` — that's the point of block mode: surgical
 edits, not full-page rewrites.

package/skills/tr-redesign-branch.md

@@ -9,6 +9,36 @@ Site-wide changes are exactly where copy-on-write branches earn their
 keep. This skill enforces the discipline: every redesign happens on a
 branch, preview-checked end-to-end, merged only after user sign-off.
 
+**Copy comes from the LIVE page, not a local draft.** A redesign changes
+the design, not the words. Read the existing copy from the live page
+(`read_page`/`batch_read_pages`) and carry it over verbatim. Local
+`sources/*.md` files are drafts — use them only if the user explicitly
+says "apply the copy in `<file>`". Don't invent new headlines, drop
+sections, or "restore" text from an old draft; a draft that had drifted
+from the live page once sent a whole redesign off the approved wording.
+When you must change a word, change it on the live page too and keep the
+draft file in sync.
+
+**Restraint beats decoration.** Default to clean, purposeful design. Don't reach
+for decorative motifs (suns, blobs, glows, mascots, confetti) to look "graphic" —
+unless a motif *means something for this brand/page*, it reads as random, and it's
+usually the exact thing that clips, seams, and crops. These fragile patterns broke
+a real build — avoid them:
+- **A shape divider (wave/curve) between two sections** → don't hand-roll it in
+  `core/html`; a separate stacked shape seams against the next section (a Chrome
+  sub-pixel hairline). Use `core/section`'s **`divider_top` / `divider_bottom`**
+  (`wave | curve | tilt`) — the platform paints it in the section's own colour and
+  overlaps the neighbour by 1px, so it's seam-free by construction. Put the divider
+  on the section whose colour should rise/dip into the neighbour.
+- **A glow/decoration inside an `overflow:hidden` box** → clipped to a hard edge.
+  Put it in a non-clipped layer, or size it to fade out before the box edge.
+- **`object-fit:cover` on a portrait inside a circle/frame** → crops heads and
+  faces. Use `contain`, reframe the source art, or size the frame to the art.
+- **A gradient "fade" at a section join** → reads as the design being cut off.
+  Make transitions deliberate (a clean shape or a solid edge), never a fade.
+These are invisible in a small full-page thumbnail and only show at real size in
+the actual browser — see the review gate in step 6.
+
 ## Recipe
 
 ### 1. Discover (always)
@@ -92,7 +122,36 @@ bulk_replace_text pattern="OldCo" replacement="NewCo" dry_run=false version="<br
 
 ### 6. Approval round
 
-Send the user a final preview link:
+**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).
+
+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

package/skills/tr-responsive.md

@@ -0,0 +1,112 @@
+---
+name: tr-responsive
+description: Use when a layout must behave differently at different screen sizes — different grid columns per breakpoint, an icon-box that's icon-on-top on mobile but icon-left on tablet, hiding a block on small screens, fluid type. Triggers on "responsive", "mobile/tablet/desktop layout", "stack on mobile", "X columns on desktop and Y on mobile", "olika på mobil/surfplatta", "responsivt".
+---
+
+# Make a Typeroll block layout responsive
+
+Typeroll has a built-in five-breakpoint system. You almost never hand-write
+media queries — you set per-breakpoint values on responsive fields and the
+renderer compiles the `@media` rules per block instance.
+
+## The five breakpoints (mobile-first)
+
+`mobile (<640) · tablet (≥640) · laptop (≥1024) · desktop (≥1280) · wide (≥1536)`
+
+A responsive field takes either a scalar (applies everywhere) or a sparse
+object `{ mobile?, tablet?, laptop?, desktop?, wide? }`. Missing breakpoints
+inherit from the next smaller one. So you only set the breakpoints that change.
+
+## Setting per-breakpoint values
+
+Use `set_block_responsive` (or pass the object form directly in `add_block` /
+`update_block` data). `read_block_type <id>` tells you which fields are
+`responsive`.
+
+```
+# 4 columns on desktop, 2 on tablet, 1 on mobile:
+set_block_responsive target={kind:page,id:home} block_id=<grid-id>
+  field=cols value={ mobile: 1, tablet: 2, desktop: 4 }
+
+# icon-box: icon on top on phones, beside the text on tablet+:
+set_block_responsive ... block_id=<iconbox-id>
+  field=layout value={ mobile: "icon-top", tablet: "icon-left" }
+```
+
+Pass a scalar to collapse a field back to one value everywhere.
+
+### Worked example — the classic feature grid
+
+"4 cards/row with icon-on-top on desktop, 2/row with icon-left on a landscape
+iPad, 1/row icon-on-top on a phone":
+
+1. `core/grid` containing `core/icon_box` cards (or a `core/repeater` with
+   `item_block: core/icon_box` for a collection-driven list).
+2. On the grid: `cols = { mobile: 1, tablet: 2, desktop: 4 }`.
+3. On each icon_box (or the repeater's item defaults):
+   `layout = { mobile: "icon-top", tablet: "icon-left", desktop: "icon-top" }`.
+
+No media queries authored — the build emits per-instance `@media` blocks and
+the editor preview honours them. Flip the device toggle in the editor header
+(Mobil / Mobil-liggande / iPad / iPad-liggande / Desktop) to author and verify
+each breakpoint.
+
+## Hiding a block at some sizes
+
+`Block.hidden_on: Breakpoint[]` is universal — no per-block opt-in. E.g.
+`hidden_on: ["mobile"]` drops the block below 640px. Use it instead of building
+a "mobile-only" duplicate.
+
+## Authoring a CUSTOM block type that's responsive
+
+Two halves, BOTH required (`create_block_type` / `update_block_type`):
+
+1. Mark the field `responsive: true`.
+2. Expose it on the **outermost** template element as a CSS variable:
+   `style="--{field}:{{field}}"`, then read `var(--{field})` in the block CSS.
+
+If the field's value is directly usable CSS (e.g. `direction: row|column` →
+`flex-direction: var(--direction)`), you're done.
+
+If it's a friendly **token** that maps to CSS (e.g. `layout: icon-left` →
+`flex-direction: row`), add a `responsive_css` map on the field — otherwise the
+per-breakpoint overrides silently do nothing (a `[style*="--field:token"]`
+selector can't see a `@media` override):
+
+```
+{ name: "layout", type: "select", options: ["icon-top","icon-left"],
+  default: "icon-top", responsive: true,
+  responsive_css: { "icon-top": "--dir: column;", "icon-left": "--dir: row;" } }
+```
+
+Then the block CSS reads `flex-direction: var(--dir, column)`.
+
+## Fluid type — usually automatic
+
+`core/heading` and prose already use `clamp()` to scale smoothly between mobile
+and desktop. `core/heading` separates semantic `level` (h1–h6, for SEO) from
+visual `size` (sm–3xl/auto) — "h1 but only as big as an h3" is one field, no
+breakpoints needed.
+
+## Gotchas
+
+- Setting a value only at `desktop` leaves smaller screens on the field
+  *default*, not on your value — set `mobile` too if you want a non-default
+  baseline (mobile-first).
+- The editor preview width is approximate on a narrow panel, but the breakpoint
+  you're editing is exact. Trust the deployed site / a wider window for `wide`.
+- **Never paper over horizontal overflow with `html,body{overflow-x:hidden}`.**
+  Setting `overflow-x:hidden` on `html` forces `overflow-y` to compute as `auto`
+  (CSS spec), turning `<html>` into a fixed-height nested scroller — the page
+  then won't scroll normally (`window.scrollY` sticks at 0) and renders blank
+  below the fold. Instead, find the element that overflows (a fixed width, a
+  `transform:rotate` card poking out, a decorative `::before`/`::after`, a grid
+  that didn't collapse) and fix THAT element's width / clip it with
+  `overflow:hidden` on its own section. Verify with
+  `document.documentElement.scrollWidth === clientWidth` at 360–390px.
+- **`core/grid` `stack_at` may not collapse on mobile** (a known platform bug):
+  the block writes `style="--cols:N"` inline, and an inline custom property beats
+  the media query that tries to set `--cols:1`, so the grid stays N-up and text
+  wraps a letter per line. Workaround until fixed: in page-scoped CSS override the
+  real property, e.g. `@media(max-width:640px){.my-section [data-block="grid"]{grid-template-columns:1fr!important}}`.
+- Background design reference: `docs/responsive-blocks.md` in the platform repo.