@typeroll/mcp-server 0.45.42 → 0.45.43

package/dist/server.js

@@ -16,6 +16,8 @@ import { contentTypeTools } from './tools/content-types.js';
 import { pageTemplateTools } from './tools/page-templates.js';
 import { mediaTools } from './tools/media.js';
 import { redirectTools } from './tools/redirects.js';
+import { styleTools } from './tools/styles.js';
+import { reusableBlockTools } from './tools/reusable-blocks.js';
 import { migrationTools } from './tools/migration.js';
 import { formTools } from './tools/forms.js';
 import { searchTools } from './tools/search.js';
@@ -113,7 +115,17 @@ The full playbook ships with this server — use it:
 5. Pages default to block mode. Build with add_block/update_block; make layouts
    responsive per breakpoint with set_block_responsive (grid columns, icon-box
    layout, … take { mobile, tablet, laptop, desktop, wide } values).
-6. No site yet? With an org-scoped key, create_site bootstraps one.
+6. Appearance lives in named styles: list_styles before styling, reuse a
+   style through a block's style_id, and create_style for any look that could
+   recur. Use one-off block values only for something clearly unique, never
+   classed raw HTML. Text must meet WCAG AA contrast. A heading's small label
+   is its eyebrow field. For what styles cannot express, use page or site
+   custom_css on s-<style> or block custom_class selectors, not [data-block].
+7. Reuse: content that must stay identical on many pages is a global block
+   (make_block_global; core/global_block references it). A section people
+   start from and then adapt is a block template (list_block_templates,
+   insert_block_template copies it). Never duplicate shared content by hand.
+8. No site yet? With an org-scoped key, create_site bootstraps one.
 
 If anything here conflicts with what a tool returns, trust the tool. Every
 tool's own description carries its specifics.
@@ -142,6 +154,8 @@ export function buildServer(options) {
         ...pageTemplateTools,
         ...mediaTools,
         ...redirectTools,
+        ...styleTools,
+        ...reusableBlockTools,
         ...migrationTools,
         ...formTools,
         ...settingsTools,

package/dist/tools/page-blocks.js

@@ -89,7 +89,7 @@ export const pageBlockTools = [
     },
     {
         name: 'update_block',
-        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. Works on pages, partials, and page templates — use `target` to address non-page containers. Does not modify children or slots; use move/add/remove for structural changes.',
+        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. Works on pages, partials, and page templates — use `target` to address non-page containers. Does not modify children or slots; use move/add/remove for structural changes. For appearance, prefer a named style (`data.style_id`, see list_styles) over custom_class or custom_css. From render version 2, custom_class lands on the heading or button link element itself instead of the block wrapper.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -216,4 +216,18 @@ export const pageBlockTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'convert_prose_block',
+        description: 'Turn one text block (core/prose) into separate blocks: headings (a classed label above a heading becomes its eyebrow), paragraphs, lists, images and buttons. Use it when a text block holds headings, classed HTML or media that should be editable and styled with named styles. Call without `accept` to preview (nothing is written); review `converted`, `notes` and `unconverted`, then call again with `accept` set to the preview\'s `fingerprint`. Writes the page draft (working copy) like other block edits. Pages only.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            accept: z.string().optional().describe('The fingerprint from a preview of this same block. Omit to preview.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert-prose`, { block_id: args.block_id, ...(args.accept ? { accept: args.accept } : {}) }, v(args.version));
+            return ok(res);
+        }),
+    },
 ];

package/dist/tools/pages.js

@@ -107,7 +107,7 @@ export const pageTools = [
             sort_order: z.number().finite().optional().describe('Manual Page order; lower numbers come first in ascending lists. Content types and listings choose how to sort.'),
             template: z.string().nullable().optional().describe('Allowed Page template ID; null uses the content type default.'),
             image_sizes_default: z.string().optional().describe('Per-page default `sizes` for responsive images (e.g. "(max-width: 640px) 360px, 560px"). Overrides the site setting; a per-<img> `sizes` attr still wins. Set when this page\'s images render narrower than the generic default so the browser stops over-fetching.'),
-            custom_css: z.string().optional().describe('Per-page CSS, injected into <head> as a <style> AFTER the site-level custom_css (so it overrides site styling). This is the RIGHT home for page-specific styling — page metadata, not content. Put a page\'s <style> here instead of stuffing it into a core/html block (which is opaque and un-editable in the visual editor).'),
+            custom_css: z.string().optional().describe('Per-page CSS, injected into <head> as a <style> AFTER the site-level custom_css (so it overrides site styling). This is the RIGHT home for page-specific styling — page metadata, not content. Put a page\'s <style> here instead of stuffing it into a core/html block (which is opaque and un-editable in the visual editor). Syntax errors refuse the write; target s-<style> classes or block custom_class rather than [data-block]/.block-* platform markup.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/partials.js

@@ -89,11 +89,12 @@ export const partialTools = [
     },
     {
         name: 'create_free_block',
-        description: 'Create a new free (reusable) global block. Use a kebab-case id and embed it on pages with <x-include name="block-id" />.',
+        description: 'Create a new global block: one shared source that every page using it shows, so an edit updates them all. Pass `blocks` for a block global block, referenced from block pages with a `core/global_block` block (data: { global_block_id }); or `html_content` for HTML pages, embedded with <x-include name="block-id" />. To turn an existing page block into a global block, use make_block_global. For a starter that is copied and then edited per page, use save_block_template instead.',
         inputSchema: {
             id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/),
             name: z.string().optional(),
-            html_content: z.string(),
+            blocks: z.array(z.record(z.unknown())).optional().describe('Block tree for a block global block.'),
+            html_content: z.string().optional().describe('HTML for <x-include> in HTML pages. Send blocks or html_content.'),
             status: z.enum(['draft', 'published']).optional(),
             version: versionParam,
         },

package/dist/tools/preview.js

@@ -26,6 +26,12 @@ export const previewTools = [
                 .boolean()
                 .optional()
                 .describe('Render unsaved drafts (working copies) too — yours AND the editor\'s. Off by default (saved content only). Signed into the token, so a draft link needs its own mint. Use this for your own iteration loop; use a plain link when the user wants to see exactly what a deploy would ship.'),
+            render_version: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Render with this platform render version instead of the site\'s own, to preview an upgrade before applying it (read_site_settings returns render.version, render.latest and what each upgrade changes). Signed into the token. Compare against a plain link to see exactly what would change; apply with update_site_settings render_version.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/reusable-blocks.js

@@ -0,0 +1,98 @@
+// Reusable blocks: global blocks (one shared source, referenced) and block
+// templates (saved starters, copied in). Global blocks themselves are
+// partials; see partials.ts for list/read/update/delete.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const reusableBlockTools = [
+    {
+        name: 'make_block_global',
+        description: 'Turn a block on a page (with everything inside it) into a global block and put a reference in its place. Other pages then add the same block with add_block type "core/global_block" data { global_block_id }. Editing the global block (update_partial / update_block with target { kind: "partial", id }) changes every page that uses it. Use for content that must stay identical everywhere, such as a shared call to action. Writes the page draft.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            name: z.string().optional().describe('Name editors see; defaults to the block name.'),
+            global_block_id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/).optional().describe('Id for the new global block; derived from the name when omitted.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, version, ...body } = args;
+            return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/blocks/make-global`, body, v(version)));
+        }),
+    },
+    {
+        name: 'detach_global_block',
+        description: 'Replace a core/global_block reference on a page with an editable copy of the global block\'s blocks. Later edits to the global block no longer reach this page. Writes the page draft.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string().describe('The id of the core/global_block reference block.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, version, ...body } = args;
+            return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/blocks/detach`, body, v(version)));
+        }),
+    },
+    {
+        name: 'list_block_templates',
+        description: 'List the site\'s block templates: saved section starters (name, description, block count). Inserting one copies its blocks into a page, where they are then edited independently. Check here before building a common section from scratch.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'block-templates'))),
+    },
+    {
+        name: 'read_block_template',
+        description: 'Read one block template, including its block tree.',
+        inputSchema: { template_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, `block-templates/${encodeURIComponent(args.template_id)}`))),
+    },
+    {
+        name: 'save_block_template',
+        description: 'Save a block template: a section starter that editors and agents insert as an independent copy. Pass `from: { page_id, block_id }` to save a block from a page (its draft), or `blocks`. Prefer templates that use named styles (style_id) over one-off values, so copies stay consistent. Templates belong to the site, not a branch.',
+        inputSchema: {
+            name: z.string(),
+            description: z.string().optional().describe('When to use it.'),
+            id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/).optional(),
+            from: z.object({ page_id: z.string(), block_id: z.string() }).optional(),
+            blocks: z.array(z.record(z.unknown())).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'block-templates', args))),
+    },
+    {
+        name: 'update_block_template',
+        description: 'Rename a block template, change its description, or replace its blocks. Pages that already inserted it do not change.',
+        inputSchema: {
+            template_id: z.string(),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            blocks: z.array(z.record(z.unknown())).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { template_id, ...body } = args;
+            return ok(await client.patch(siteId, `block-templates/${encodeURIComponent(template_id)}`, body));
+        }),
+    },
+    {
+        name: 'delete_block_template',
+        description: 'Delete a block template. Pages that already inserted it keep their copies.',
+        inputSchema: { template_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.del(siteId, `block-templates/${encodeURIComponent(args.template_id)}`))),
+    },
+    {
+        name: 'insert_block_template',
+        description: 'Insert a copy of a block template into a page (new block ids), at the top level or inside parent_id (slot_index for column slots), at `position` (default: end). Returns added_ids. Writes the page draft.',
+        inputSchema: {
+            page_id: z.string(),
+            template_id: z.string(),
+            parent_id: z.string().optional().nullable(),
+            slot_index: z.number().int().min(0).optional(),
+            position: z.number().int().min(0).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, version, ...body } = args;
+            return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/blocks/insert-template`, body, v(version)));
+        }),
+    },
+];

package/dist/tools/settings.js

@@ -13,7 +13,7 @@ function v(version) {
 export const settingsTools = [
     {
         name: 'read_site_settings',
-        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css. Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
+        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
         inputSchema: {
             version: versionParam,
         },
@@ -53,7 +53,8 @@ export const settingsTools = [
             // Scriptable surfaces. Trusted because the caller has an API key.
             scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
             scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
-            custom_css: z.string().optional().describe('Global CSS in a <style> in <head>, after block CSS and before the page\'s own custom CSS and the template base stylesheet (reset + global). Base rules for :root tokens (spacing, radius, container widths), body font and line-height load after it, so override those with a more specific selector (for example html:root or body.page) rather than a bare :root/body rule. Preview uses the same order. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element.'),
+            custom_css: z.string().optional().describe('Global CSS in a <style> in <head>, after block CSS and before the page\'s own custom CSS and the template base stylesheet (reset + global). Base rules for :root tokens (spacing, radius, container widths), body font and line-height load after it, so override those with a more specific selector (for example html:root or body.page) rather than a bare :root/body rule. Preview uses the same order. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element. Prefer named styles (create_style) for anything a style can express. Syntax errors (unbalanced braces, unclosed comments or strings, expression()/javascript:) refuse the write; selectors on platform markup ([data-block], .block-*) come back as warnings because they can change between render versions — target s-<style> classes or block custom_class instead.'),
+            render_version: z.number().int().min(1).optional().describe('Platform render version. Platform output changes ship as new versions so existing sites never change look on their own. Upgrade only after previewing (get_preview_link render_version) and with the user\'s approval; the tr-upgrade-rendering skill compares every page. Lowering it returns to an earlier version.'),
             colors: z.record(z.string()).optional(),
             fonts: z.record(z.unknown()).optional(),
             contact: z

package/dist/tools/styles.js

@@ -0,0 +1,108 @@
+// Style library tools. A site's look is a library of NAMED styles
+// (SiteSettings.styles): element roles (body, h1–h6, link) style every
+// matching element, and every other style is chosen per block through the
+// block's `style_id` field. Reuse beats one-off values.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+const COLOR_HELP = 'A palette token (primary, secondary, accent, background, surface, text, text_light), a derived readable text colour for a palette background (on_primary, on_secondary, on_accent), or a hex/rgb/hsl colour. Prefer tokens so a palette change flows through.';
+const length = z.string().describe('CSS length: px, rem, em, %, vw, ch, or clamp()/min()/max()');
+const color = z.string().describe(COLOR_HELP);
+const propsSchema = z.object({
+    font: z.enum(['heading', 'body', 'mono', 'inherit']).optional(),
+    size: length.optional(),
+    weight: z.number().int().min(100).max(900).optional(),
+    line_height: z.string().optional().describe('Unitless number such as "1.5", or a length'),
+    letter_spacing: z.string().optional().describe('e.g. "0.08em" or "normal"'),
+    transform: z.enum(['none', 'uppercase', 'lowercase', 'capitalize']).optional(),
+    italic: z.boolean().optional(),
+    color: color.optional(),
+    background: color.optional(),
+    align: z.enum(['left', 'center', 'right', 'start', 'end', 'justify']).optional(),
+    decoration: z.enum(['none', 'underline']).optional(),
+    space_before: length.optional(),
+    space_after: length.optional(),
+    padding: z.string().optional().describe('One to four CSS lengths'),
+    max_width: length.optional(),
+    radius: length.optional(),
+    border: z.object({
+        width: length.optional(),
+        style: z.enum(['solid', 'dashed', 'dotted', 'none']).optional(),
+        color: color.optional(),
+        sides: z.enum(['all', 'top', 'right', 'bottom', 'left', 'block', 'inline']).optional(),
+    }).optional(),
+}).describe('Style properties. Mobile-first: `base` applies everywhere, `at.<breakpoint>` from that width up.');
+const atSchema = z.object({
+    tablet: propsSchema.optional(),
+    laptop: propsSchema.optional(),
+    desktop: propsSchema.optional(),
+    wide: propsSchema.optional(),
+}).describe('Overrides from each site breakpoint upward (tablet, laptop, desktop, wide).');
+const styleFields = {
+    name: z.string().describe('Author-facing name, in the site\'s language, e.g. "Överrubrik" or "Hero title".'),
+    role: z.enum(['body', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'link', 'lead', 'eyebrow', 'small', 'quote', 'button', 'button_secondary', 'section']).optional()
+        .describe('Standard role. body/h1–h6/link style every matching element on the site; the others mark the standard style for that purpose. One style per role.'),
+    targets: z.array(z.enum(['text', 'heading', 'list', 'button', 'container'])).optional()
+        .describe('Block kinds that can select this style via style_id (text = core/prose, heading = core/heading and core/rich_heading, list, button, container = core/section and core/container).'),
+    description: z.string().optional().describe('When to use it; shown to editors and agents.'),
+    base: propsSchema.optional(),
+    at: atSchema.optional(),
+    hover: z.object({ color: color.optional(), background: color.optional(), decoration: z.enum(['none', 'underline']).optional() }).optional(),
+    css: z.string().optional().describe('Advanced CSS scoped to the style: bare declarations, or rules where `&` is the style selector (e.g. "&::before { content: \'—\' }"). Prefer structured properties.'),
+};
+export const styleTools = [
+    {
+        name: 'list_styles',
+        description: 'List the site\'s named style library: element roles (body, h1–h6, link) that style every matching element, and the styles blocks select with `style_id`. Also returns missing_standard_roles and contrast/library problems. READ THIS BEFORE STYLING ANY PAGE: reuse an existing style for a recurring look (eyebrows, leads, card titles, buttons, section spacing) instead of per-block values, raw HTML classes or page CSS.',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'styles', v(args.version)))),
+    },
+    {
+        name: 'create_style',
+        description: 'Create a named style. Do this whenever a look could recur — an eyebrow, a lead paragraph, a card title, a quote, a button variant, a section rhythm — then apply it with the block\'s `style_id` field. Only a clearly unique one-off may use block settings instead. Set values for phones in `base` and grow them in `at.tablet`/`at.desktop`. Text must meet WCAG AA contrast (4.5:1, 3:1 for ≥24px or bold ≥18.7px) against its background; a failing style is refused. Never light grey on white.',
+        inputSchema: {
+            id: z.string().regex(/^[a-z][a-z0-9-]{0,47}$/).describe('Stable slug; the CSS class becomes s-<id>. Cannot change later.'),
+            ...styleFields,
+            name: styleFields.name,
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...style } = args;
+            return ok(await client.post(siteId, 'styles', { targets: [], base: {}, ...style }, v(version)));
+        }),
+    },
+    {
+        name: 'update_style',
+        description: 'Update a style. `base`, `hover` and each breakpoint in `at` merge property by property (pass null to remove one); name, targets, description and css replace. Every page using the style changes at once — tell the user which pages that affects when it matters.',
+        inputSchema: {
+            style_id: z.string(),
+            name: styleFields.name.optional(),
+            role: styleFields.role,
+            targets: styleFields.targets,
+            description: styleFields.description,
+            base: z.record(z.unknown()).optional().describe('Property patch for base; null removes a property.'),
+            at: z.record(z.unknown()).optional().describe('Per-breakpoint property patches; null removes a breakpoint or property.'),
+            hover: z.record(z.unknown()).optional(),
+            css: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, style_id, ...patch } = args;
+            return ok(await client.patch(siteId, `styles/${encodeURIComponent(style_id)}`, patch, v(version)));
+        }),
+    },
+    {
+        name: 'delete_style',
+        description: 'Delete a style. Blocks that still reference it fall back to their default look; reassign them first.',
+        inputSchema: { style_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.del(siteId, `styles/${encodeURIComponent(args.style_id)}`, v(args.version)))),
+    },
+    {
+        name: 'apply_standard_styles',
+        description: 'Add the standard styles the site is missing (body, H1–H6, link, lead, eyebrow, small text, quote, primary/secondary button, section), with considered sizes and spacing for phones, tablets and desktops. The natural first step when building a new site, before pages: then adjust them to the brand (fonts, colours, scale) with update_style. New sites already have them. overwrite:true resets the standard roles to the defaults and changes the site\'s look — ask first.',
+        inputSchema: { overwrite: z.boolean().optional(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'styles/standard', { overwrite: args.overwrite === true }, v(args.version)))),
+    },
+];

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // 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.45.42';
+export const VERSION = '0.45.43';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.42",
+  "version": "0.45.43",
   "description": "Typeroll CMS MCP server – connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {

package/skills/README.md

@@ -33,6 +33,7 @@ instructions. Read the relevant recipe when the task calls for it.
 | `tr-new-site.md`       | "create a new site", "bootstrap a site for…"        | Settings → header/footer partials → homepage → inner pages → deploy. Full setup recipe. |
 | `tr-brand.md`          | "create a brand", "choose colors", "design the look"| Palette recipes by mood, typography pairings, CSS variable setup, preview. |
 | `tr-redesign-branch.md`| "redesign", "modernize", anything site-wide-design   | Branch-isolated work with preview links, merge when approved. |
+| `tr-upgrade-rendering.md` | "upgrade rendering", render version behind latest | Screenshot-compares every page at the current and target render version, reports differences, upgrades with approval. |
 | `tr-content-write.md`  | "write a page about…", "draft copy for…"            | Discovery first (settings + sample pages), then drafts in the site's voice, previews, iterates. |
 | `tr-images.md`         | "make an image / hero / illustration", media uploads | Generates locally → signed upload URL → metadata patch → embed. |
 

package/skills/tr-brand.md

@@ -159,6 +159,16 @@ replace_partial partial_id="header" html_content="<updated HTML>"
 
 Same for footer.
 
+## Step 5b — Express the typography as styles
+
+Colours and fonts are only half the brand. Put the type scale, weights,
+spacing and recurring treatments into the site's named styles (`list_styles`,
+`update_style`, `create_style`): body text and H1–H6 apply everywhere; the
+eyebrow, lead, quote, buttons and section rhythm are chosen per block with
+`style_id`. Set phone values in `base` and grow them in `at.tablet` and
+`at.desktop`. Prefer this to custom CSS: editors can see and change styles,
+and every page follows.
+
 ## Step 6 — Custom CSS for advanced tokens (optional)
 
 If the brand needs things beyond the 7 base tokens — e.g. a gradient,

package/skills/tr-content-write.md

@@ -37,6 +37,23 @@ Read the actual HTML of an existing page. Note:
 - Length conventions (do existing pages run 200 words or 2000?)
 - Whether internal links use absolute or relative URLs
 
+`list_styles` too: use the site's named styles (`style_id` on heading, text,
+list, button and section blocks) for eyebrows, leads, quotes and buttons. If a
+treatment you need could recur and no style fits, create one rather than
+setting one-off values; ask first when it changes the site's look.
+
+A small label above a heading is the heading block's `eyebrow`, and a line
+below it is its `subtitle` (render version 2), each with its own style field.
+Never write them as separate text blocks with classed HTML. In text blocks,
+style whole paragraphs with site text styles (`<p class="s-lead">`); a text
+block that needs other classes, images or headings with parts is better split
+with `convert_prose_block`.
+
+`list_block_templates` and `list_partials` too. Start a common section from a
+block template (`insert_block_template`, then edit the copy). Use a global
+block (`core/global_block`) for content that must stay identical on every
+page, such as a shared call to action; don't paste copies of it.
+
 ### 2. Ask for the brief
 
 If the user hasn't told you, ask:

package/skills/tr-import-url.md

@@ -54,6 +54,16 @@ Parse `<a href>` links to discover internal pages. Build a list:
 Exclude private/session/admin URLs deliberately. Inventory public pagination and
 query routes; decide preservation or retirement from their actual purpose.
 
+**Map source styling to named styles.** A class the source uses for a
+recurring treatment (`.eyebrow`, `.lead`, `.btn-outline`, `.section-dark`)
+becomes a site style with `create_style` and is applied with `style_id`. A
+small label directly above a heading is an eyebrow style, not a heading of its
+own: put it in the heading block's `eyebrow` field (and a line under the
+heading in `subtitle`). Never carry classed raw HTML into text blocks to keep a
+look: the editor cannot edit it, and the next render version may not keep it.
+A text block that already holds such markup can be split with
+`convert_prose_block` (preview, then `accept`).
+
 ### 2. Measure the source and protect existing target work
 
 ```

package/skills/tr-migrate-wp.md

@@ -122,6 +122,11 @@ The managed importer preserves existing imported Pages on retry and refuses
 URL/identity conflicts or dangling term references. An older flattened import
 requires a separately reviewed mapping repair; do not re-import over edits.
 
+**Styles.** Recurring source treatments (theme classes for eyebrows, leads,
+button variants, highlighted sections) become named site styles
+(`create_style`) applied with `style_id`, so editors can change them in one
+place. Do not preserve them as classed raw HTML in text blocks.
+
 ### 4. Import one page at a time, draft status
 
 For each source URL:

package/skills/tr-new-site.md

@@ -129,6 +129,23 @@ the built-in YouTube/Vimeo/Google Maps/Calendly set. Values are exact domain
 hostnames, never URLs or wildcards. Read the setting back before deciding that
 an iframe cannot be represented.
 
+### 2b. Styles before pages
+
+Set the site's look as named styles before building any page:
+
+1. `list_styles`. New sites already have the standard set (body, H1–H6, link,
+   lead, eyebrow, small, quote, buttons, section). If roles are missing,
+   `apply_standard_styles`.
+2. Adjust them to the brand with `update_style`: the font, the type scale and
+   spacing for `base` (phones) and `at.tablet`/`at.desktop`, and colours from
+   palette tokens. Keep text at WCAG AA contrast; failing styles are refused.
+3. Add a named style for every look the design repeats: a card title, a price
+   note, a highlighted section, a CTA button variant. Use the site's language
+   for names.
+
+Pages then choose styles with each block's `style_id` field. A per-block
+font size, colour or class is only for something clearly unique.
+
 ### 3. Header + footer partials
 
 **Start from the native preset — don't hand-roll navigation.** Read
@@ -275,10 +292,10 @@ Known limitations (honest list — don't fight them):
   client-side without the icon pipeline). Text labels only.
 
 Theming: block primitives render neutral. Brand color/typography comes
-from settings (step 2). For page-specific polish (e.g. a colored card
-treatment), a single `core/html` block with a small `<style>` scoped to
-`[data-bid]`/section selectors is acceptable — keep it minimal and note
-it in your log.
+from settings (step 2) and named styles (step 2b). For page-specific polish
+(e.g. a colored card treatment) that no style covers, give the block a
+`custom_class` and write the rule in the page's `custom_css`. Never put a
+`<style>` in a `core/html` block or target `[data-bid]`/`[data-block]`.
 
 ### 5. Inner pages
 
@@ -286,6 +303,12 @@ Same pattern: `create_page` with `content_mode: "blocks"` and a section
 tree. Standard set: Om oss, Tjänster, Kontakt — or what the brief says.
 Default new pages to `status: "draft"`; publish after review.
 
+Sections that repeat across pages: a call to action or contact strip that
+must stay identical becomes a global block (`make_block_global`, then
+`core/global_block` on the other pages). A section shape you will reuse with
+different content (a pricing row, a feature trio) becomes a block template
+(`save_block_template`, then `insert_block_template`).
+
 ### 5b. If the legacy site is still live, scrape canonical content
 
 For pages with canonical text (privacy policy, terms, about), `WebFetch`

package/skills/tr-page-template.md

@@ -34,7 +34,7 @@ default template, and an individual Page can override it.
 Prefer native image, table, list, heading and content blocks. A rare specialized
 widget can use a reviewed HTML/embed block. Reusable custom behavior belongs in
 one custom block type rather than repeated HTML bodies. Existing HTML-mode pages
-may share fragments through partials and `<x-include>`, but use block templates
+may share fragments through partials and `<x-include>`, but use block-based page templates
 for new content families.
 
 Header/footer partials are global and remain separate from content types. Keep

package/skills/tr-upgrade-rendering.md

@@ -0,0 +1,71 @@
+---
+name: tr-upgrade-rendering
+description: Use when a site's platform render version is behind the latest (read_site_settings → render.version < render.latest), or the user asks to "upgrade rendering", "get the new block styles" or why a platform improvement doesn't show. Compares every page at the current and target version with screenshots, reports the differences and upgrades only with approval.
+---
+
+# Upgrade a site's render version
+
+Platform changes to block markup and shared CSS ship as numbered render
+versions. A site keeps its version until someone upgrades it, so its look
+never changes on its own. Upgrading is a single settings write, reversible by
+writing the previous number. The comparison happens here, in the agent; the
+server only renders previews.
+
+The user can also do this in the portal: Settings → Rendering → "Preview with
+version N", then "Upgrade". Offer this skill when they want a full-site visual
+comparison first.
+
+## Recipe
+
+1. **Read the gap.** `read_site_settings` returns `render`:
+   `{ version, latest, upgrades: [{ version, title, changes[] }] }`. If
+   `version === latest`, stop. Tell the user what each pending version
+   changes, in their words, before measuring anything.
+
+2. **List the pages to compare.** `list_pages` (published and unlisted), plus
+   the header/footer, which appear on every page. For a large site, compare
+   the home page, one page per content type and template, and every page
+   whose blocks use a component named in `upgrades[].changes`.
+
+3. **Mint two links per page set.** One `get_preview_link` without
+   `render_version` (current) and one with `render_version: latest` (target).
+   Both show saved content. Mint each once and reuse it; internal links keep
+   the token.
+
+4. **Screenshot both** at 390, 768 and 1440 px wide, full page, after fonts
+   and images have loaded (`document.fonts.ready`, scroll to the end to
+   trigger lazy images, then back to the top). Use a headless browser with a
+   fixed viewport and `reducedMotion: 'reduce'`.
+
+5. **Compare.** Pixel-diff each pair (same size, small per-pixel tolerance)
+   and record the changed area and the bounding boxes of changed regions.
+   Crop each region from both versions. Ignore differences confined to
+   embedded third-party frames (maps, booking widgets, video).
+
+6. **Report** per page and width: unchanged, or the cropped before/after
+   regions with a one-line description ("links in body text are underlined",
+   "section gap 8px larger"). Link each change to the version note that
+   explains it. Say plainly when a change looks like a regression.
+
+   Before screenshots, read the site and page custom CSS for selectors a
+   version note names. Version 2 moves a heading's or button's custom class
+   onto the `<h2>` or link, so `.my-class .block-heading-text` stops
+   matching; propose the rewrite (`.my-class`) or a named style.
+
+7. **Ask before upgrading.** Never upgrade on your own. If the user wants to
+   keep a specific old look, solve it with a site style or page CSS first and
+   compare again.
+
+8. **Upgrade** with `update_site_settings render_version: <latest>` (pass
+   `version` to do it on a branch first). The preview changes at once; the
+   live site changes at the next deploy. To undo, write the previous number.
+
+## Pitfalls
+
+- Comparing a draft against saved content shows content edits, not
+  rendering changes. Use the same content state for both links.
+- Lazy images and web fonts cause false differences. Wait for them in both
+  screenshots.
+- Comparing only the home page misses changes in components it doesn't use.
+- Don't encode a workaround in custom CSS to resist an upgrade without
+  telling the user; it becomes a hidden fork of the platform styles.