@typeroll/mcp-server 0.45.60 → 0.45.61

package/dist/tools/page-blocks.js

@@ -31,6 +31,18 @@ const targetSchema = z.object({
 function v(version) {
     return version ? { version } : undefined;
 }
+/**
+ * Write tools answer compactly by default: the changed block, its parent id,
+ * slot index and position, has_unsaved_changes and any warnings, instead of
+ * the container's whole tree (tens of kB for an article). `response: "tree"`
+ * asks for the tree. Sent as a query parameter, which an older Core ignores
+ * and answers with the tree, where an unknown body key would be refused.
+ */
+const responseParam = z.enum(['summary', 'tree']).optional().describe('Answer shape. "summary" (default): the changed block, parent_id, slot_index, position, has_unsaved_changes and warnings. "tree": the whole block tree of the container.');
+function writeQuery(version, response) {
+    return { ...v(version), response: response ?? 'summary' };
+}
+const COMPACT_ANSWER = ' Answers with the changed block, `parent_id`, `slot_index`, `position` and `has_unsaved_changes` (the working copy differs from the saved content); pass `response: "tree"` for the whole tree, or call get_page_blocks.';
 /**
  * Resolve a (target | page_id) pair to a REST path prefix. Pages keep
  * routing through /pages/{id}/blocks for back-compat with older callers;
@@ -64,7 +76,7 @@ export const pageBlockTools = [
     },
     {
         name: 'add_block',
-        description: 'Insert a block into a container (page, partial, or page template). BUFFER MODEL: block mutations on pages/partials edit the unsaved DRAFT — commit_working_copy is the explicit save. With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into a slot for slot-containers). Position defaults to "end". Slot containers (core/columns, core/tabs — container: "slots"): slot_index picks the slot (0-based; defaults to 0) and works even if the parent instance has no slots array yet; a freshly added slot container gets its slots initialised to the type\'s arity. You can also pass the whole subtree inline via block.slots: [[...],[...]]. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand.',
+        description: 'Insert a block into a container (page, partial, or page template). BUFFER MODEL: block mutations on pages/partials edit the unsaved DRAFT — commit_working_copy is the explicit save. With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into a slot for slot-containers). Position defaults to "end". Slot containers (core/columns, core/tabs — container: "slots"): slot_index picks the slot (0-based; defaults to 0) and works even if the parent instance has no slots array yet; a freshly added slot container gets its slots initialised to the type\'s arity. You can also pass the whole subtree inline via block.slots: [[...],[...]]. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand. A `data` key that no field of the block\'s type declares (read_block_type) is rejected with 400 `unknown_field`, for the block and every child; nothing is written, and `unknown_fields[].suggestions` says where it belongs (e.g. `item_overrides.<key>` for an item-block field on a repeater or its aliases, or the closest field names).' + COMPACT_ANSWER + ' `added_id` is the new block\'s id.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -72,6 +84,7 @@ export const pageBlockTools = [
             parent_id: z.string().optional().nullable(),
             slot_index: z.number().int().min(0).optional(),
             position: z.number().int().min(0).optional(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -81,18 +94,18 @@ export const pageBlockTools = [
                 parent_id: args.parent_id,
                 slot_index: args.slot_index,
                 position: args.position,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         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. 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.',
+        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. Send values in the field\'s type (numbers as numbers); a value the block will not render comes back in `warnings` (`field_type_mismatch`) with its path. A `null` value removes that key from data (the field renders its default); use it to clean up a key stored by mistake. A written key that no field of the block\'s type declares is rejected with 400 `unknown_field` and nothing is written; `unknown_fields[].suggestions` says where it belongs: on core/repeater and its aliases (core/testimonials, core/page_list, ...) a field of the item block goes in `item_overrides.<key>`, otherwise the closest field names.' + COMPACT_ANSWER,
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
-            data: z.record(z.unknown()).optional(),
+            data: z.record(z.unknown()).optional().describe('Field values to merge into block.data. null removes the key.'),
             style_overrides: z.object({
                 spacing_before: z.string().optional(),
                 spacing_after: z.string().optional(),
@@ -100,6 +113,7 @@ export const pageBlockTools = [
                 custom_class: z.string().optional(),
                 html_id: z.string().optional(),
             }).optional(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -108,13 +122,13 @@ export const pageBlockTools = [
                 block_id: args.block_id,
                 data: args.data,
                 style_overrides: args.style_overrides,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         name: 'move_block',
-        description: 'Reparent or reorder a block inside its container. target_parent_id=null moves to top level. For slot containers, target_slot_index picks the slot. Cycles (moving a block into its own descendant) are rejected. Works for pages, partials, and templates.',
+        description: 'Reparent or reorder a block inside its container. target_parent_id=null moves to top level. For slot containers, target_slot_index picks the slot. Cycles (moving a block into its own descendant) are rejected. Works for pages, partials, and templates.' + COMPACT_ANSWER + ' The location is where the block now sits.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -122,6 +136,7 @@ export const pageBlockTools = [
             target_parent_id: z.string().optional().nullable(),
             target_slot_index: z.number().int().min(0).optional(),
             target_position: z.number().int().min(0).optional(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -131,61 +146,61 @@ export const pageBlockTools = [
                 target_parent_id: args.target_parent_id,
                 target_slot_index: args.target_slot_index,
                 target_position: args.target_position,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         name: 'remove_block',
-        description: 'Remove a block and everything inside it from its container. Works for pages, partials, and templates.',
+        description: 'Remove a block and everything inside it from its container. Works for pages, partials, and templates. Answers with `removed_id`, the `parent_id`, `slot_index` and `position` it was removed from and `has_unsaved_changes`; pass `response: "tree"` for the whole remaining tree.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
-            const query = { block_id: args.block_id };
-            if (args.version)
-                query.version = args.version;
-            const res = await client.del(siteId, path, query);
+            const res = await client.del(siteId, path, { block_id: args.block_id, ...writeQuery(args.version, args.response) });
             return ok(res);
         }),
     },
     {
         name: 'duplicate_block',
-        description: 'Clone a block (subtree included) and insert the copy directly after the original within the same container. Returns the duplicate\'s new id. Useful for "add another card to this feature grid" — duplicate the existing one and then `update_block` on the new id to change its data. Works for pages, partials, and templates.',
+        description: 'Clone a block (subtree included) and insert the copy directly after the original within the same container. Returns the duplicate\'s new id. Useful for "add another card to this feature grid" — duplicate the existing one and then `update_block` on the new id to change its data. Works for pages, partials, and templates.' + COMPACT_ANSWER + ' `duplicate_id` is the copy\'s id; `block` is the copy.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
             const res = await client.post(siteId, `${path}/duplicate`, {
                 block_id: args.block_id,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         name: 'set_block_responsive',
-        description: 'Set a per-breakpoint value on one responsive field of a block (in any container — page, partial, or template). The renderer reads { mobile, tablet, laptop, desktop, wide } objects on any field marked responsive in the BlockType schema (use read_block_type to see which). Mobile-first inheritance: missing breakpoints inherit upward. Pass a scalar value to clear responsive back to a single value. Example: setting `cols` on a feature_grid to { mobile: 1, tablet: 2, desktop: 3 } renders 1-col on phones, 2-col on tablets, 3-col on desktop+.',
+        description: 'Set a per-breakpoint value on one responsive field of a block (in any container — page, partial, or template). The renderer reads { mobile, tablet, laptop, desktop, wide } objects on any field marked responsive in the BlockType schema (use read_block_type to see which). Mobile-first inheritance: missing breakpoints inherit upward. Pass a scalar value to clear responsive back to a single value. Example: setting `cols` on a feature_grid to { mobile: 1, tablet: 2, desktop: 3 } renders 1-col on phones, 2-col on tablets, 3-col on desktop+. A field the block type does not declare is rejected with 400 `unknown_field`.' + COMPACT_ANSWER,
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
             field: z.string().describe('Field name (must be marked responsive in the BlockType schema).'),
             value: z.any().describe('Scalar (applies to all BPs) or { mobile?, tablet?, laptop?, desktop?, wide? }.'),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
             const res = await client.post(siteId, `${path}/responsive`, {
                 block_id: args.block_id, field: args.field, value: args.value,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },

package/dist/tools/pages.js

@@ -75,6 +75,10 @@ export const pageTools = [
             'and seeds the tree with a heading + prose block so the editor is never blank. ' +
             'Pass html_content (or content_mode="html") to opt into raw-HTML mode instead. ' +
             'Slug is derived from the title when omitted. Default status is "draft". ' +
+            'Address conflicts: an explicit slug or path that another page already uses (drafts and unsaved drafts included) ' +
+            'fails with 409 { code: "slug_in_use" | "path_in_use", details: { page_id, path } } — edit that page or choose another slug; ' +
+            'the address is never changed silently. Only a title-derived slug is numbered (e.g. "tack" → "tack-2"), and the response then ' +
+            'carries warnings: [{ code: "slug_adjusted", requested, slug, path, conflicting_page_id }]. ' +
             'Homepage convention: pass slug="" (empty string) or omit slug and set title to "Home"; ' +
             'the server stores it under id "home" with slug "". ' +
             'Slug must be a single path segment (no slashes). For nested URLs like ' +
@@ -88,7 +92,7 @@ export const pageTools = [
             title: z.string().min(1),
             content_type: z.string().optional().describe('Content type ID; defaults to page.'),
             fields: z.record(z.unknown()).optional().describe('Custom field values defined by the content type.'),
-            slug: z.string().optional().describe('URL slug — single path segment, no slashes (e.g. "about", "kontakt"). Empty string "" = homepage. For nested URLs set the `path` field explicitly — `slug` stays a leaf id.'),
+            slug: z.string().optional().describe('URL slug — single path segment, no slashes (e.g. "about", "kontakt"). Empty string "" = homepage. For nested URLs set the `path` field explicitly — `slug` stays a leaf id. Already in use → 409 slug_in_use naming the existing page; omit it to derive one from the title (numbered with a slug_adjusted warning on conflict).'),
             path: z.string().optional().describe('Optional explicit URL path for nested pages (e.g. "/erbjudanden/sommar-2026"). When set, takes precedence over slug for routing. Must start with "/", lowercase a-z/0-9/-/_/ only, no "..", no "//", no trailing slash. Slug is still required as the leaf id but two pages CAN share a slug under different paths.'),
             content_mode: z.enum(['blocks', 'html']).optional().describe('Default "blocks". "blocks" stores a Block[] tree (the modern default — supports the full ~40-block library, page templates, and the responsive system). "html" stores raw markup in html_content (legacy path, still fully supported for imported content or hand-written HTML). Passing html_content without content_mode also opts into "html".'),
             html_content: z.string().optional().describe('Body HTML — only used when content_mode="html".'),
@@ -224,11 +228,11 @@ export const pageTools = [
     },
     {
         name: 'clone_page',
-        description: 'Duplicate an existing page under a new title + slug. Use this when you want a near-copy of an existing page as the starting point (e.g. duplicate "Privatflytt" → "Privatflytt Härnösand"). The new page is created as a draft regardless of the source\'s status. Returns the created page.',
+        description: 'Duplicate an existing page under a new title + slug. Use this when you want a near-copy of an existing page as the starting point (e.g. duplicate "Privatflytt" → "Privatflytt Härnösand"). The new page is created as a draft regardless of the source\'s status. Returns the created page. Same address rule as create_page: a slug you pass that is already in use fails with 409 slug_in_use (details: { page_id, path }); a slug derived from the title is numbered and reported in warnings (code slug_adjusted).',
         inputSchema: {
             source_page_id: z.string(),
             title: z.string().min(1).describe('Title for the new page.'),
-            slug: z.string().optional().describe('Slug for the new page. Omit to auto-derive from title.'),
+            slug: z.string().optional().describe('Slug for the new page. Omit to derive it from the title. A slug already in use is refused (409 slug_in_use), never changed.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -268,7 +272,7 @@ export const pageTools = [
                 image_sizes_default: src.image_sizes_default,
                 status: 'draft',
             };
-            if (args.slug)
+            if (args.slug !== undefined)
                 body.slug = args.slug;
             if (typeof src.path === 'string' && src.path) {
                 // Keep an explicit route's directory, never its old final segment.
@@ -282,7 +286,9 @@ export const pageTools = [
                 segments.pop();
                 body.path = '/' + [...segments, slug.replace(/^\/+|\/+$/g, '')].join('/');
             }
-            // 3. Create. The API auto-uniques generated routes; explicit conflicts return 409.
+            // 3. Create. An explicit slug or path that is taken fails with 409
+            //    (slug_in_use / path_in_use); a title-derived slug is numbered and
+            //    reported in `warnings`.
             const created = await client.post(siteId, 'pages', body, v(args.version));
             return ok(created);
         }),

package/dist/tools/settings.js

@@ -76,8 +76,8 @@ export const settingsTools = [
             }).strict().nullable().optional().describe('Organization schema.org JSON-LD emitted on every page. Replaces the stored value as a whole; null (or all-empty) clears it.'),
             staging_url: z.string().nullable().optional().describe('URL of a staging environment for this site, reported as urls.staging. Stored on the Site, not per version. Trailing slashes are dropped; empty string or null clears.'),
             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(),
+            colors: z.record(z.string().nullable()).optional().describe('Palette: primary, secondary, accent, background, surface, text, text_light (shallow-merged). Optional on_primary, on_secondary, on_accent set the text colour on that theme colour (buttons, badges, tabs, call-to-action sections, styles using the on_* tokens) as a hex colour such as "#ffffff"; null returns to the automatic black or white (chosen by APCA from render version 8, by the WCAG 2 ratio before). A chosen on_* colour applies on every render version. The response lists `on_colors` with each one\'s APCA Lc and WCAG 2 ratio; a choice below APCA Lc 60 (button text, 16px/600) is kept and returned as a warning. Prefer the automatic choice unless the brand specifies a colour.'),
+            fonts: z.record(z.unknown()).optional().describe('heading, body (Google Fonts family or "system"), size_base (px) and smoothing: "auto" (browser default) or "antialiased" (thinner text on macOS, for light text on dark backgrounds); null clears smoothing. Unset smoothing is auto from render version 6.'),
             contact: z
                 .object({
                 email: z.string().optional(),

package/dist/tools/styles.js

@@ -7,7 +7,7 @@ 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 COLOR_HELP = 'A palette token (primary, secondary, accent, background, surface, text, text_light), the text colour for a palette background (on_primary, on_secondary, on_accent: the site\'s colors.on_* when set, else black or white, whichever reads better), 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({
@@ -55,13 +55,13 @@ const styleFields = {
 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.',
+        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, contrast/library problems and readability warnings (both APCA Lc and WCAG 2 ratio). 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.',
+        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 contrast against its background is measured with APCA by use, size and weight (body text Lc 75; secondary/small text Lc 60; headings, eyebrows and buttons Lc 60 from 16px at weight 600+, Lc 45 from 24px bold or 36px; smaller or lighter non-body text Lc 75) and with the WCAG 2 ratio. Text that fails both is refused; text below its APCA level that meets WCAG 2 AA (4.5:1, 3:1 for ≥24px or bold ≥18.7px) is saved and returned in `warnings`. 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,
@@ -101,7 +101,7 @@ export const styleTools = [
     },
     {
         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.',
+        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. A standard style whose palette colour is unreadable on the background is added with the body text colour instead; `adjusted` lists those and `warnings` says what changed, with the measures — tell the user.',
         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.60';
+export const VERSION = '0.45.61';

package/package.json

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

package/skills/tr-brand.md

@@ -51,6 +51,14 @@ A Typeroll site uses 7 color tokens:
 | `text` | Body copy. | ≥4.5:1 contrast ratio on `background`. |
 | `text_light` | Secondary labels, captions, placeholders. | ≥3:1 on `background`. |
 
+Text on `primary`, `secondary` and `accent` (buttons, badges, tabs,
+call-to-action sections, the `on_*` style tokens) is black or white
+automatically, chosen by APCA from render version 8. When the brand
+specifies it, set `colors.on_primary`, `colors.on_secondary` or
+`colors.on_accent` (a hex colour; `null` returns to automatic). The response
+lists `on_colors` with each one's APCA Lc and WCAG 2 ratio: button text needs
+Lc 60, body text Lc 75. Do not compensate with custom CSS.
+
 **Palette recipes by mood:**
 
 *Nordic / minimal:*

package/skills/tr-migrate-wp.md

@@ -73,6 +73,9 @@ Then the ordinary preconditions:
   appearance unless a redesign is explicitly requested.
 - If the target already has content, you must NOT clobber it — always
   `list_pages` first and only write to slugs that don't already exist.
+  Pass the slug explicitly: `create_page` then refuses an address that is
+  already in use (409 `slug_in_use` naming the existing page) instead of
+  numbering it.
 
 ## Recipe
 

package/skills/tr-migration-evidence.md

@@ -62,6 +62,41 @@ behavior or other semantics unsupported by the chosen block: record the gap
 and use a supported composition or stop for native support.
 Do not apply a template to hundreds of Pages until its prototype passes.
 
+## Report platform gaps, do not patch them
+
+Matching the source sometimes needs something the platform does not offer.
+Never close that with site or page `custom_css`, raw HTML or a generic custom
+block: the next site hits the same gap and the workaround breaks on the next
+Core change. Record it and report it instead. Check these five causes first,
+because each has looked like a site problem:
+
+1. **A platform default no setting reaches.** Compare computed text rendering
+   and base styles on `body`, links and headings (`-webkit-font-smoothing`,
+   `line-height`, `text-decoration`) with the source. If the difference comes
+   from Typeroll's base CSS, check Site settings and the render versions first
+   (`read_site_settings` → `render.upgrades`).
+2. **A replaced control ignores the block's settings.** A capability can swap a
+   field for a provider element (address suggestions). Compare that control
+   with a plain field in the same block: border, radius, height, background,
+   text colour, font, placeholder, icon and colour scheme in light and dark mode.
+3. **A missing part.** The source has a part (icon, badge, second label) the
+   block has no field for. Check `read_block_type` for a field before
+   concluding it is missing.
+4. **A value that is stored and ignored.** Read every write response's
+   `warnings` (`field_type_mismatch`, `unknown_style_override`): a wrong type or
+   key is saved and never rendered. Measure the computed result, not the
+   read-back.
+5. **Preview differs from the published page.** A setting that shows in preview
+   but not in a fresh hosted build is a publication gap; report both URLs.
+
+Report each gap with: site ID, Organization, Core version and render version;
+source and target URL; viewport (actual `innerWidth`), browser and DPR; the
+block ID and type or the setting; source and target computed values; what is
+missing, ignored or wrong; the proposed setting or fix; and acceptance
+criteria a reviewer can measure. State that no workaround CSS is in place.
+Mark the affected recipe `waiting_for_native_support`, continue independent
+work, and verify against the source again after the release.
+
 ## Separate files, addresses and business behavior
 
 Inventory both file bytes and every discovered historical asset URL, including

package/skills/tr-new-site.md

@@ -140,7 +140,9 @@ Set the site's look as named styles before building any page:
    `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.
+   palette tokens. Keep text readable: contrast is checked with APCA and
+   WCAG 2; text that fails both is refused, and text below its APCA level
+   comes back as a warning.
 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.