@typeroll/mcp-server 0.7.8 → 0.7.12

package/AGENTS.md

@@ -33,9 +33,13 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   - `html` — body lives in `html_content` as a single HTML string.
     Useful when you have hand-written markup to drop in directly.
 
-  Slug can contain slashes, so `2024/01/foo-bar` is a valid slug →
-  `/2024/01/foo-bar` URL. Encode hierarchy in the slug; the renderer
-  doesn't use `parent` for routing.
+  Slug is a single path segment — no slashes. `about` → `/about`,
+  `kontakt` → `/kontakt`, empty string `""` → homepage. The v1 API
+  rejects `services/design` and other slash-containing slugs with
+  "Invalid slug … slugs must not contain slashes." For nested URLs
+  like `/blog/{slug}` or `/services/{slug}`, the right primitive is a
+  **collection with `route_template`** (see the `tr-blog` and
+  `tr-directory` skills) — not a flat page with a slashed slug.
 
 - **Partials = global blocks.** Three kinds:
   - `header` — auto-injected at the top of every page.

package/dist/index.js

@@ -16,7 +16,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { TyperollClient } from './client.js';
 import { runInstallSkillsCli } from './install-skills.js';
 import { buildServer } from './server.js';
-const VERSION = '0.7.8';
+const VERSION = '0.7.12';
 async function resolveSiteId(client) {
     const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
     if (fromEnv)

package/dist/server.js

@@ -46,7 +46,7 @@ function effectFor(name) {
     }
     return 'write';
 }
-const DEFAULT_INFO = { name: 'typeroll', version: '0.7.8' };
+const DEFAULT_INFO = { name: 'typeroll', version: '0.7.12' };
 export function buildServer(options) {
     if (!options.fixedSiteId && !options.allowedSites) {
         throw new Error('buildServer: either fixedSiteId or allowedSites must be provided');

package/dist/tools/block-types.js

@@ -83,4 +83,84 @@ export const blockTypeTools = [
             return ok(res);
         }),
     },
+    // ─── BlockType authoring — CREATE / UPDATE / DELETE ──────────────────
+    // The chat AI surface intentionally omits the `script` field on these
+    // three tools. Scripts run with full DOM access in every visitor's
+    // browser; AI-authored blocks must not carry custom JS. A human can
+    // add a script later via the portal UI (consent gate) or via the
+    // cookie-auth API directly. Origin is stamped 'ai' so audit + UI
+    // distinguish these from human-authored types.
+    {
+        name: 'create_block_type',
+        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. **Custom JS is NOT exposed here** — if a script is genuinely needed, a human must add it later via the portal UI. Returns the created BlockType.",
+        inputSchema: {
+            name: z.string().describe('Machine name (lowercase kebab/underscore, 1-64 chars). Becomes the id.'),
+            label: z.string().optional().describe('Display label (defaults to name).'),
+            icon: z.string().optional().describe('Lucide icon name shown in the block picker.'),
+            category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
+            container: z.union([
+                z.literal(true), z.literal(false),
+                z.enum(['slots', 'repeater', 'conditional']),
+            ]).optional().describe('Container kind. Use slots for fixed named slots, repeater for looping over items, conditional for show-if blocks.'),
+            slot_count: z.number().optional().describe('Required when container="slots". 1-8.'),
+            slot_labels: z.array(z.string()).optional(),
+            item_compatible: z.boolean().optional().describe('Mark true if this block is designed to render as a repeater item (no outer padding, kernel layout).'),
+            expand_to: z.object({
+                target: z.string(),
+                defaults: z.record(z.unknown()),
+            }).optional().describe('Alias mechanism — render as another block type with these defaults merged under authored data.'),
+            schema: z.array(z.unknown()).optional().describe('FieldDefinition[]. Each field has name, type, label, optional required/default/options/responsive.'),
+            template: z.string().optional().describe('HTML with {{field}}, {{{field}}}, {{=tag}}, {{children}}, {{slot:NAME}} substitutions.'),
+            styles: z.string().optional().describe('Block-scoped CSS. Selectors should start with [data-block="<name>"].'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            // origin=ai is set via query so the API route can stamp it server-side
+            const query = { origin: 'ai' };
+            if (version)
+                query.version = version;
+            const res = await client.post(siteId, 'block-types', body, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_block_type',
+        description: "Update fields of an existing custom block type. Core blocks (id starts with 'core/') are read-only — they're managed in platform code. Schema/template/styles replace wholesale (no deep merge); other fields shallow-merge. **Custom JS is NOT exposed here** — to add or change a script, edit via portal UI.",
+        inputSchema: {
+            type_id: z.string().describe('Block type id (custom or third_party). Cannot be a core/* block.'),
+            label: z.string().optional(),
+            icon: z.string().optional(),
+            category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
+            container: z.union([
+                z.literal(true), z.literal(false),
+                z.enum(['slots', 'repeater', 'conditional']),
+            ]).optional(),
+            slot_count: z.number().optional(),
+            slot_labels: z.array(z.string()).optional(),
+            item_compatible: z.boolean().optional(),
+            expand_to: z.object({ target: z.string(), defaults: z.record(z.unknown()) }).optional(),
+            schema: z.array(z.unknown()).optional(),
+            template: z.string().optional(),
+            styles: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { type_id, version, ...body } = args;
+            const res = await client.patch(siteId, `block-types/${encodeURIComponent(type_id)}`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_block_type',
+        description: "Remove a custom block type. Core blocks (core/*) cannot be deleted. **Warning**: pages currently using this block type will render '<!-- unknown block type -->' comments instead. Call find_pages_using_block_type FIRST to see the blast radius; the AI should prompt the user before deleting if usage > 0.",
+        inputSchema: {
+            type_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `block-types/${encodeURIComponent(args.type_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
 ];

package/dist/tools/page-blocks.js

@@ -22,27 +22,55 @@ const blockSchema = z.object({
         html_id: z.string().optional(),
     }).optional(),
 }).passthrough();
+/**
+ * Generic container target. kind=page is the back-compat default — when
+ * `page_id` is provided without `target`, the dispatcher synthesises
+ * `{ kind: 'page', id: page_id }`.
+ */
+const targetSchema = z.object({
+    kind: z.enum(['page', 'partial', 'template', 'item_template']),
+    id: z.string(),
+}).describe('Address a container. kind=page|partial|template|item_template. Pages: id is the page id. Partials: id is "header"|"footer"|<free-block id>. Templates: id is the PageTemplate id. item_template: id is the COLLECTION NAME — the block tree is the collection\'s per-item layout (e.g. blog post body bound to {{item.title}}, {{item.body}}, etc.).');
 function v(version) {
     return version ? { version } : undefined;
 }
+/**
+ * Resolve a (target | page_id) pair to a REST path prefix. Pages keep
+ * routing through /pages/{id}/blocks for back-compat with older callers;
+ * partials and templates route through /containers/{kind}/{id}/blocks
+ * (the unified handler).
+ */
+function pathFor(target, pageId) {
+    const kind = target?.kind ?? 'page';
+    const id = target?.id ?? pageId;
+    if (!id)
+        throw new Error('Either target or page_id is required');
+    if (kind === 'page') {
+        return `pages/${encodeURIComponent(id)}/blocks`;
+    }
+    return `containers/${kind}/${encodeURIComponent(id)}/blocks`;
+}
 export const pageBlockTools = [
     {
         name: 'get_page_blocks',
-        description: 'Read a page\'s block tree. Returns content_mode (html or blocks) and the blocks array. Empty array for HTML-mode pages — those store body content in html_content instead. Use this before any block mutation so you know what you\'re modifying.',
+        description: 'Read the block tree of a container (page, partial, or page template). Use `target: { kind, id }` for partials/templates. For pages, `page_id` is the back-compat shorthand. Returns content_mode + blocks. Empty array for HTML-mode pages — those store body content in html_content instead. Always call this before any block mutation so you know what you\'re modifying.',
         inputSchema: {
-            page_id: z.string(),
+            target: targetSchema.optional(),
+            page_id: z.string().optional().describe('Shorthand for target={kind:"page", id:page_id}.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, v(args.version));
+            const path = pathFor(args.target, args.page_id);
+            const res = await client.get(siteId, path, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'add_block',
-        description: 'Insert a block into a page. With no parent_id, inserts at top level. Otherwise inserts as a child (or into the named slot for slot-containers). Position defaults to "end". For slot containers, slot_index picks the slot; for regular containers it\'s ignored.',
+        description: 'Insert a block into a container (page, partial, or page template). With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into the named slot for slot-containers). Position defaults to "end". For slot containers, slot_index picks the slot. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand.',
         inputSchema: {
-            page_id: z.string(),
+            target: targetSchema.optional(),
+            page_id: z.string().optional(),
             block: blockSchema,
             parent_id: z.string().optional().nullable(),
             slot_index: z.number().int().min(0).optional(),
@@ -50,7 +78,8 @@ export const pageBlockTools = [
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+            const path = pathFor(args.target, args.page_id);
+            const res = await client.post(siteId, path, {
                 block: args.block,
                 parent_id: args.parent_id,
                 slot_index: args.slot_index,
@@ -61,9 +90,10 @@ export const pageBlockTools = [
     },
     {
         name: 'update_block',
-        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. 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.',
         inputSchema: {
-            page_id: z.string(),
+            target: targetSchema.optional(),
+            page_id: z.string().optional(),
             block_id: z.string(),
             data: z.record(z.unknown()).optional(),
             style_overrides: z.object({
@@ -76,7 +106,8 @@ export const pageBlockTools = [
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+            const path = pathFor(args.target, args.page_id);
+            const res = await client.patch(siteId, path, {
                 block_id: args.block_id,
                 data: args.data,
                 style_overrides: args.style_overrides,
@@ -86,9 +117,10 @@ export const pageBlockTools = [
     },
     {
         name: 'move_block',
-        description: 'Reparent or reorder a block. 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.',
+        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.',
         inputSchema: {
-            page_id: z.string(),
+            target: targetSchema.optional(),
+            page_id: z.string().optional(),
             block_id: z.string(),
             target_parent_id: z.string().optional().nullable(),
             target_slot_index: z.number().int().min(0).optional(),
@@ -96,7 +128,8 @@ export const pageBlockTools = [
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+            const path = pathFor(args.target, args.page_id);
+            const res = await client.put(siteId, path, {
                 block_id: args.block_id,
                 target_parent_id: args.target_parent_id,
                 target_slot_index: args.target_slot_index,
@@ -107,17 +140,53 @@ export const pageBlockTools = [
     },
     {
         name: 'remove_block',
-        description: 'Remove a block and everything inside it from a page.',
+        description: 'Remove a block and everything inside it from its container. Works for pages, partials, and templates.',
         inputSchema: {
-            page_id: z.string(),
+            target: targetSchema.optional(),
+            page_id: z.string().optional(),
             block_id: z.string(),
             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, `pages/${encodeURIComponent(args.page_id)}/blocks`, query);
+            const res = await client.del(siteId, path, query);
+            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.',
+        inputSchema: {
+            target: targetSchema.optional(),
+            page_id: z.string().optional(),
+            block_id: z.string(),
+            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));
+            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+.',
+        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? }.'),
+            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));
             return ok(res);
         }),
     },

package/dist/tools/pages.js

@@ -61,16 +61,24 @@ export const pageTools = [
     },
     {
         name: 'create_page',
-        description: 'Create a new page. Defaults to html mode — pass html_content to set the body. ' +
+        description: 'Create a new page. Defaults to blocks mode (same as the portal UI\'s "New page" button) ' +
+            '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". ' +
             'Homepage convention: pass slug="" (empty string) or omit slug and set title to "Home"; ' +
             'the server stores it under id "home" with slug "". ' +
-            'Do NOT pass slug="/"; strip leading slashes from slugs (use "about", not "/about"). ' +
-            'Returns the created page including html_content.',
+            'Slug must be a single path segment (no slashes). For nested URLs like ' +
+            '/erbjudanden/sommar or /tjanster/design, set the optional `path` field explicitly — ' +
+            'e.g. path="/erbjudanden/sommar". For many similar items use a collection with route_template ' +
+            '(see tr-blog / tr-directory), but for a small group of bespoke pages sharing a URL prefix, ' +
+            '`path` is the right primitive. ' +
+            'Returns the created page (blocks for blocks-mode, html_content for html-mode) including ' +
+            '`url` (the resolved live URL).',
         inputSchema: {
             title: z.string().min(1),
-            slug: z.string().optional().describe('URL slug without leading slash (e.g. "about", "services/design"). Empty string "" = homepage.'),
-            content_mode: z.enum(['blocks', 'html']).optional().describe('Default "html". "html" stores body in html_content; "blocks" stores a Block[] tree (note: blocks mode pages render as empty until the block editor ships — use html mode for all real content).'),
+            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.'),
+            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".'),
             blocks: z.array(z.any()).optional().describe('Block tree — only used when content_mode="blocks". Omit to get the default heading+prose seed.'),
             status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.7.8",
+  "version": "0.7.12",
   "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": {

package/skills/tr-blog.md

@@ -154,7 +154,7 @@ Three calls. No per-article `create_page`. No HTML diffing by hand.
 
 ## Pitfalls
 
-- **Don't fall back to "one page per article".** That was the pre-`item_template_html` pattern. It works but it's strictly worse: design changes mean editing N pages, you lose `{{url}}` resolution in listings, sitemap doesn't include items, and previews can't surface a per-item URL. If you find yourself writing `create_page` with `slug: "blog/foo"`, stop and reconsider — the only legitimate reason is a one-off "about the editorial team" page that isn't an article.
+- **Don't fall back to "one page per article".** That was the pre-`item_template_html` pattern. It's strictly worse now: design changes mean editing N pages, you lose `{{url}}` resolution in listings, sitemap doesn't include items, previews can't surface a per-item URL — and the API will reject your attempt anyway. `create_page` rejects slugs containing slashes ("Invalid slug … slugs must not contain slashes"), so `slug: "blog/foo"` doesn't even get through. The collection's `route_template` is the only path to nested URLs.
 - **Slugs must be unique within the collection.** `regenerate_collection_listing` will silently drop items where `slug` is missing; the listing count will be lower than the item count.
 - **Don't use non-ASCII field names.** `datum` not `Datum`; `forfattare` not `författare` in the `name`. The `label` is free-form.
 - **Listing goes stale if you forget step 4.** Every item change needs `regenerate_collection_listing`. Add it to your mental checklist after every `create/update_collection_item`.

package/skills/tr-brand.md

@@ -141,6 +141,87 @@ a special border radius, or a branded highlight color — add them via
 
 Then reference `var(--brand-gradient)` etc. in page HTML and partials.
 
+## Step 4b — Section + layout design defaults
+
+These are non-negotiable defaults the rest of the platform skills inherit (`tr-new-site`, `tr-directory`, `tr-collection-template`). Apply them on every page that has visible sections — they're battle-tested across real customer migrations.
+
+### One signal per section boundary
+
+Use **either** a background-color shift **or** a horizontal divider line at a section transition — never both stacked. They serve the same purpose; stacking them looks busy.
+
+- Default: alternating `.section` / `.section.alt` with a bg shift is enough.
+- A standalone divider line (gradient/keyline) is reserved for the hero → body boundary, where the bg already shifts.
+
+### Sections are full-bleed; content is container-width
+
+The section element ALWAYS spans the full viewport (its bg, border, decorative line). Content inside is constrained by `.container` / `.container.narrow`.
+
+The renderer wraps `html_content` in `<main class="page-content">` with `max-width: var(--container-medium)` — so a section's bg-color rule alone gives a "1080px-wide stripe in the middle of the page", which is wrong. Every section that has a bg/border must apply the negative-margin escape:
+
+```css
+.my-page .section {
+  position: relative;
+  margin-left: calc(50% - 50vw);
+  margin-right: calc(50% - 50vw);
+  width: 100vw;
+  padding: 74px 0;
+}
+.my-page .section.alt { background: #fff }
+```
+
+The first section (hero) also wants `margin-top: -32px` to cancel `.page-content`'s top padding. Do NOT wrap the page in `overflow-x: clip` — it cancels the bleed.
+
+### Cards sit directly on the section bg — never on a matching bg
+
+A card with a white bg inside a white-bg section creates a redundant "white plate on white" effect. Two enforcement rules:
+
+1. Cards on the default page bg (`var(--color-background)`) can use `background: #fff` + border. ✓
+2. Cards on `.section.alt` (which has `background: #fff`) must drop their own bg:
+   - **Single-card section** (one card in a section): drop all chrome (bg, border, accent line). Just content; the section's bg is the only context.
+   - **Grid cards** (multiple side-by-side): keep border for grid separation, drop bg. The card becomes a transparent container with a hairline outline.
+
+   ```css
+   .my-page .section.alt .my-expert,
+   .my-page .section.alt .my-expert::before { background: transparent; border: 0; padding: 0; display: none }
+   .my-page .section.alt .my-grid-card { background: transparent }  /* grid cards keep border */
+   ```
+
+Mental model: bg shifts twice before you have a problem — body → section → card. Three shifts feels muddled.
+
+### Gradient-clipped headings need extra line-height for descenders
+
+When using `-webkit-background-clip: text` + `display: inline-block` to render a gradient-filled heading, the inline-block box is sized by `line-height`. With `line-height: 1` (a common "tight" value for display headings) the descenders of g/j/y/p get clipped.
+
+**Rule:** gradient-clipped headings use `line-height: 1.1` or higher, plus `padding-bottom: 0.05em` for belt-and-braces:
+
+```css
+.gradient-h1 {
+  display: inline-block;
+  background: var(--gradient-brand);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  line-height: 1.12;
+  padding-bottom: 0.05em;
+}
+```
+
+### Hero copy is not body copy
+
+When porting a page, identify the H1 + tagline pair and leave the body intro inside the body. Don't lift a body sentence up into the hero unless the source has it twice.
+
+Rule: hero gets at most **H1 + one tagline**. Body intro stays in the body. Repeating the same sentence in both places looks accidental.
+
+### Footer architecture: navigate by domain, not by content type
+
+Default footer columns should mirror the user's mental model of the BUSINESS, not the technical content shapes. Anti-pattern: separate "Podcast / Articles / Events / Offers" columns that just list content categories.
+
+Better default:
+- **Områden / Domains** — subject domains, what the user wants help with
+- **Företaget / Company** — about / services / legal, meta-information about the org
+
+Reserve a third column only when there's a genuinely different surface (locations, languages, partner pages). Don't pad the footer with content-type columns — navigation to those happens via top nav + topic pages.
+
 ## Step 7 — Preview
 
 ```
@@ -167,3 +248,13 @@ Open in browser. Check:
 - **Dark themes need dark surface too.** Setting `background: #0f0f0f`
   but leaving `surface: #f8fafc` (white) breaks every card/input. Always
   update all 7 tokens as a set.
+- **The renderer's `.page-content` layout shell.** The renderer wraps
+  `html_content` in `<main class="page-content">` with constrained
+  `max-width` and default typography. The typography defaults now sit
+  inside `:where()` so they have specificity 0 — a customer's class
+  rules trivially win. The layout shell (width + padding) is still at
+  normal specificity by design: it's what gives a brand-new page
+  reasonable margins out of the box. If a section needs to escape the
+  shell (full-bleed bg, full-width hero), apply the negative-margin
+  pattern shown in Step 4b. Don't fight the shell with `overflow-x`
+  hacks.

package/skills/tr-directory.md

@@ -178,6 +178,38 @@ get_deploy_status job_id=<id>
 Each published item gets its own URL in the static build, with
 `sitemap.xml` automatically including them all.
 
+## Patterns worth knowing
+
+### Conditional rendering without Mustache conditionals
+
+`item_template_html` substitution is plain `{{field}}` / `{{{field}}}` — no loops, no `{{#if}}` blocks. To hide a section/element when a field is empty, use a data-attribute that resolves to either the empty string or a non-empty value, plus a CSS selector:
+
+```html
+<aside class="podcast-guest" data-empty-if-blank="{{guest_name}}">
+  <h2>Om gästen</h2>
+  <p>{{guest_bio}}</p>
+</aside>
+```
+```css
+.podcast-detail [data-empty-if-blank=""] { display: none !important; }
+```
+
+When `guest_name` is empty, the attribute becomes `data-empty-if-blank=""` and the CSS matches and hides the block. When non-empty, the rule misses and the block renders. Works for optional images, optional audio, optional sub-sections — any "show only if this field has a value" need.
+
+### Pre-render list-typed source data into a richtext field
+
+For nested arrays in the source (e.g. `chapters: [{time, title}, …]`), pre-render to HTML during import and store in a dedicated `*_html` richtext field. The template just splats `{{{chapters_html}}}`. Three concrete recipes worth applying:
+
+1. **Podcast detail page:** `chapters_html`, `guest_links_html`.
+2. **Restaurant directory:** `hours_html` table.
+3. **Product directory:** `variants_html` grid.
+
+See `tr-collection-template` for full code examples.
+
+### Batch-import via subagent for large datasets
+
+22+ `create_collection_item` calls bloat the main agent's context with response payloads. Spawn a `general-purpose` subagent with the manifest path and a tight contract ("report ok/fail per item, end with a one-line summary"). The sub returns one line per item instead of a JSON blob per item back into the main turn.
+
 ## Pitfalls
 
 - **Slugs must be unique within the collection** — duplicates cause
@@ -195,9 +227,30 @@ Each published item gets its own URL in the static build, with
 - **Template too clever.** Substitution is plain `{{field}}` — no
   loops, no conditionals. If your design needs more, prefer flat
   fields (`star_html`, `rating_label`) prebuilt in the data step.
+  See the "Patterns worth knowing" section above.
 - **Field type changes drift data.** Adding a new field after import
   is fine; renaming one orphans the old data on every item. Plan the
   schema before import.
+- **Never derive display labels from slugs.** Slugs are ASCII-folded
+  for URL-safety. Computing the visible label as
+  `slug.replace("-", " ").capitalize()` produces **wrong words** in
+  languages with diacritics: `innehall` → `Innehall` (should be
+  `Innehåll`), `affarssystem` → `Affärssystem`. Always carry the
+  real title from the source and look it up by slug:
+
+  ```python
+  slug_to_title = {t["slug"]: t["title"] for t in topic_manifest}
+  label = slug_to_title.get(slug, slug.replace("-", " ").title())  # fallback only
+  ```
+
+  Caught during a real migration where 20 of 22 podcast detail pages
+  ended up with `Innehall` / `Prissattning` / `Affarssystem` in their
+  topic chips.
+- **Numeric `sort_field` sorts numerically** as of the 2026-05 fix —
+  episode 9 ranks below episode 23 under desc sort. Earlier versions
+  compared as strings (9 > 23), so if you're working against an older
+  portal deploy add a `sort_key` text field with zero-padded values
+  (`f"{episode:03d}"`) and set `sort_field: "sort_key"` instead.
 
 ## Mixing scraped + generated content
 

package/skills/tr-images.md

@@ -65,11 +65,18 @@ Body: <file bytes>
 In a shell:
 
 ```bash
-curl -X PUT "<upload_url>" \
-  -H "Content-Type: image/png" \
-  --data-binary @hero-services.png
+curl -sS -X PUT --data-binary @hero-services.png "$UPLOAD_URL"
 ```
 
+Optionally with `-H "Content-Type: image/png"` if you need to override what R2 will infer. **Nothing else.**
+
+> The signed URL embeds checksum-related query parameters
+> (`x-amz-checksum-crc32`, `x-amz-sdk-checksum-algorithm`) for legacy
+> SDK compatibility, but `X-Amz-SignedHeaders=host` — only the host
+> header is part of the signature. Sending the `x-amz-*` values as
+> request headers yields `403 SignatureDoesNotMatch`. Don't. Just
+> `--data-binary` the file at the URL.
+
 Or from JS (Claude Code can run a one-line script):
 
 ```js
@@ -80,6 +87,15 @@ await fetch(uploadUrl, {
 });
 ```
 
+Parallelise N uploads via shell `&` + `wait`:
+
+```bash
+while IFS=$'\t' read -r filename signed_url; do
+  curl -sS -X PUT --data-binary @"$filename" "$signed_url" &
+done < manifest.tsv
+wait
+```
+
 A 200 OK from R2 means the image is now live at `cdn_url`.
 
 ### 4. Patch metadata (alt text, etc.)

package/skills/tr-new-site.md

@@ -128,29 +128,62 @@ Use `replace_partial partial_id="footer" html_content="..."`.
 
 ```
 create_page title="Start" slug="" content_mode="html"
-            html_content="<full hero + intro HTML>"
+            html_content="<article class=\"home-page\">...full hero + intro HTML...</article>"
             status="published"
 ```
 
-`slug=""` creates the homepage under `page_id: "home"`. If it already
-exists, use `update_page page_id="home" patch={html_content: "..."}`.
+`slug=""` creates the homepage under `page_id: "home"`. If it already exists, use `update_page page_id="home" patch={html_content: "..."}`.
+
+**Always wrap the body in a page-scope `<article class="...-page">`.** The renderer's `.page-content` layout shell sets default max-width and padding; without a scope class, any selectors you write live in the same tree as the renderer defaults and you'll wonder why your `.hero h1` doesn't get the size you set. With `.home-page .hero h1` you're at specificity 0,2,1 and trivially win. Use `<article class="home-page">` for the homepage and `<article class="static-page">` (or page-specific names like `<article class="about-page">`) for inner pages.
 
 A minimal homepage structure:
-- Hero: full-width section with `<h1>`, tagline, one CTA button
+- Hero: **full-bleed** section (negative-margin escape) with `<h1>`, tagline, one CTA button
 - Intro: 2–3 sentences about what the company does
 - Services/features grid: 3 cards max
 - CTA band: "Kontakta oss" or similar
 
+Full-bleed hero recipe (matches the section conventions from `tr-brand`'s Step 4b):
+
+```css
+.home-page .home-hero {
+  position: relative;
+  margin-left: calc(50% - 50vw);
+  margin-right: calc(50% - 50vw);
+  margin-top: -32px;          /* cancels .page-content top padding */
+  width: 100vw;
+  padding: 80px 0 64px;
+  background: var(--gradient-soft), #fff;
+}
+```
+
+**Caveat:** never combine with `overflow-x: clip` on the page wrapper — the clip cancels the bleed.
+
 ### 6. Inner pages
 
-Create each page:
+Create each page (always with a page-scope class):
+
 ```
 create_page title="Om oss" slug="om-oss" content_mode="html"
-            html_content="..." status="published"
+            html_content="<article class=\"static-page\">...</article>"
+            status="published"
 ```
 
 Standard set: Om oss, Tjänster, Kontakt. Add more if the brief says so.
 
+### 6b. If the legacy site is still live, scrape canonical content
+
+When a page (privacy policy, terms, about) exists on the still-live previous site, use `WebFetch` to pull the canonical text directly rather than rewriting from memory or relying on placeholder copy.
+
+Pattern:
+
+```
+WebFetch url="https://www.olddomain.example/integritetspolicy"
+         prompt="Return full content as markdown, preserve Swedish characters,
+                 preserve hierarchy, don't summarize"
+```
+
+Then convert markdown → HTML for `html_content`. This keeps legal text exact and stops "polished" rewrites from drifting from the canonical version.
+
 ### 7. Preview + iterate
 
 ```
@@ -178,6 +211,24 @@ get_deploy_status job_id=<id>    # poll until status=succeeded
 - **Scoped styles.** Put `<style>` at the bottom of partial HTML.
   Styles apply to the whole page; prefix class names with the partial ID
   to avoid collisions (`site-header__*`, `site-footer__*`).
+- **Page-scope class on every page body.** Wrap `html_content` in
+  `<article class="my-page">` and prefix all your page-specific rules
+  with `.my-page`. The renderer's `.page-content` layout shell sets
+  width + padding at normal specificity, so a scope class keeps your
+  rules cleanly above the defaults and the next agent can refactor a
+  single page without bleed-through.
+- **Inherit `tr-brand`'s Step 4b section/layout defaults.** Full-bleed
+  sections via negative-margin escape, one signal per section boundary
+  (bg shift OR divider, not both), cards drop bg on `.section.alt`,
+  gradient-clipped headings use `line-height: 1.1+` to keep descenders
+  inside the box. See the brand skill for the full list — don't
+  re-derive.
+- **Don't simplify data during import.** When porting content from an
+  existing site, preserve full fidelity at the data layer. Don't
+  ASCII-fold slugs into display labels (`affärsutveckling` ≠
+  `affarsutveckling`), don't truncate descriptions, don't drop
+  metadata fields you "won't use yet". Carry titles verbatim from
+  source; derive slug-from-title only for the URL, not the label.
 - **Minimal JS.** The platform doesn't bundle JS. If you need interactions,
   write a small `<script>` inside the partial or page; keep it under 50
   lines. Avoid external CDN dependencies in page bodies.