@typeroll/mcp-server 0.7.9 → 0.9.0

package/AGENTS.md

@@ -287,22 +287,22 @@ first if you're unsure what's writable.
 ```
 # Image lives on a URL somewhere (Unsplash, customer's existing CDN):
 upload_media_from_url source_url="https://..." alt_text="Hero photo of …"
-  → returns { media_id, cdn_url, … }
+  → returns { media_id, cdn_url, finalize: {…}, finalize_error: null }
 
 # OR image lives in your memory (image-gen output):
 upload_media_inline filename="hero.png" content_type="image/png"
                     data_base64="iVBORw0KGgo…"
   → returns the same shape
 
-# OPTIONAL but recommended: produce srcset variants for responsive <img>:
-generate_image_variants media_id=<id>
-  → returns webp + avif variants at 320/640/1024/1920 widths
-    (skips upscales; sub-5s per image)
+# Both tools auto-finalize after PUT: immutable Cache-Control on the
+# original PLUS AVIF/WebP variants at 320/640/1024/1920. No manual
+# generate_image_variants call needed. The site-template renderer reads
+# the variants array off the Media doc and emits <picture> automatically
+# — you can keep the <img src="{cdn_url}"> markup simple.
 
 # Then embed in a page:
 read_page page_id=...
-# Build <picture> or <img srcset="..."> using variants[*].cdn_url
-update_page page_id=... patch={ html_content: "<...><img src='{cdn_url}' .../>" }
+update_page page_id=... patch={ html_content: "<...><img src='{cdn_url}' alt='…' /></...>" }
 ```
 
 ### "Fill missing alt-text across the media library"
@@ -438,7 +438,7 @@ stakeholder review.
 | **Global blocks (partials)** | `list_partials` (summary by default), `read_partial`, `create_free_block`, `update_partial`, `replace_partial`, `delete_partial`, `find_pages_using_block`, `list_blocks_with_usage` |
 | **Block types** | `list_block_types`, `read_block_type`, `find_pages_using_block_type`, `export_block_types`, `import_block_types` |
 | **Collections** | `create_collection`, `update_collection_schema`, `delete_collection`, `list_collections`, `read_collection`, `list_collection_items` (richtext hidden by default), `read_collection_item`, `batch_read_collection_items`, `create_collection_item`, `update_collection_item`, `delete_collection_item`, `regenerate_collection_listing` |
-| **Media** | `list_media`, `read_media`, `create_upload_url`, `upload_media_from_url`, `upload_media_inline`, `update_media`, `delete_media`, `generate_image_variants`, `suggest_alt_text_context` |
+| **Media** | `list_media`, `read_media`, `create_upload_url`, `upload_media_from_url`, `upload_media_inline`, `update_media`, `delete_media`, `finalize_media`, `finalize_all_media`, `generate_image_variants`, `suggest_alt_text_context` |
 | **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect` |
 | **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `list_form_submissions` |
 | **Settings** | `update_site_settings` (whitelist) |

package/README.md

@@ -105,9 +105,14 @@ the full reference + concrete operation recipes.
   itself (incl. `route_template` for per-item URLs); list/read/batch-
   read/create/update/delete items.
 - **Media** — list, read, signed upload URLs, `upload_media_from_url`,
-  `upload_media_inline`, patch metadata, delete, `generate_image_variants`
-  (build-time srcset pipeline), `suggest_alt_text_context` (returns a
-  tuned prompt for your own vision model).
+  `upload_media_inline` (both auto-finalize after PUT — see below),
+  patch metadata, delete, `finalize_media` (per-item: applies immutable
+  Cache-Control + generates AVIF/WebP srcset variants — call after
+  `create_upload_url`'s raw PUT path), `finalize_all_media` (bulk
+  backfill for legacy libraries), `generate_image_variants` (the
+  variant half of finalize, kept for surgical reruns),
+  `suggest_alt_text_context` (returns a tuned prompt for your own
+  vision model).
 - **Redirects** — list, create, delete. Plus automatic 301 on slug change.
 - **Forms** — list, read, create, update, delete, list submissions.
 - **Settings** — read + patch (scripts and custom CSS not exposed).

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.9';
+const VERSION = '0.7.12';
 async function resolveSiteId(client) {
     const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
     if (fromEnv)

package/dist/server.js

@@ -24,6 +24,7 @@ import { blockTypeTools } from './tools/block-types.js';
 import { pageBlockTools } from './tools/page-blocks.js';
 import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
+import { domainTools } from './tools/domain.js';
 import { fail } from './tools/helpers.js';
 const PERM_RANK = { read: 0, write: 1, admin: 2 };
 /**
@@ -46,7 +47,7 @@ function effectFor(name) {
     }
     return 'write';
 }
-const DEFAULT_INFO = { name: 'typeroll', version: '0.7.9' };
+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');
@@ -73,6 +74,7 @@ export function buildServer(options) {
         ...versionTools,
         ...deployTools,
         ...previewTools,
+        ...domainTools,
     ];
     // SDK's registerTool has deeply-nested generics we can't unify across a
     // heterogeneous tool list at compile time — same shrug as stdio's index.ts.

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/collections.js

@@ -52,6 +52,14 @@ export const collectionTools = [
                 sort_dir: z.enum(['asc', 'desc']).optional(),
                 route_template: z.string().optional(),
                 item_template_html: z.string().optional(),
+                schema_type: z
+                    .string()
+                    .optional()
+                    .describe('Free-form Schema.org type for auto JSON-LD on every item route ("BlogPosting", "PodcastEpisode", "Product", "Event", "Recipe", "Course", …). Pair with schema_field_map when item field names differ from the schema property names.'),
+                schema_field_map: z
+                    .record(z.string())
+                    .optional()
+                    .describe('Override the default field→schema-property mapping. Example: { "audio_url": "contentUrl", "show_notes": "description" }. Values use camelCase (Schema.org convention).'),
             })
                 .passthrough(),
             version: versionParam,

package/dist/tools/domain.js

@@ -0,0 +1,98 @@
+// Custom-domain lifecycle tools. Wrap the four /api/v1/sites/{id}/domain/*
+// routes so an agent can read, attach, poll, activate, or remove a
+// custom domain through MCP. Admin-only on the server side; site-scoped
+// keys are implicitly admin, org-scoped keys forward the share's
+// permission.
+//
+// State machine recap (see docs/domain-lifecycle-plan.md):
+//
+//   no domain   ──add_domain──▶  pending
+//   pending     ──poll_domain──▶ pending | verified | failed
+//   verified    ──activate_domain──▶ live
+//   any state   ──remove_domain──▶ no domain
+//
+// `production_url` on the site response (list_sites / read_site) only
+// reflects the custom domain when status === 'live'. Until then,
+// agents should send users to the fallback URL.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const domainTools = [
+    {
+        name: 'read_domain',
+        description: "Read the current state of the site's custom domain. Returns " +
+            '`{ hostname, status, dns_target, verified_at, failure_reason }` ' +
+            "or `null` when no domain is attached. Status is one of 'pending' " +
+            "(DNS not yet verified), 'verified' (DNS + cert OK, awaiting customer " +
+            "activation), 'live' (production URL is now the custom domain), " +
+            "'failed' (Cloudflare returned an error — see failure_reason).",
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'domain');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'add_domain',
+        description: "Attach a custom domain to this site. The site MUST NOT already have " +
+            "a domain set — remove the existing one first. Returns the new state, " +
+            "including the CNAME target the customer must point DNS at. Status " +
+            "starts as 'pending'; once DNS is correct + cert is issued, " +
+            "`poll_domain` will flip it to 'verified', then `activate_domain` " +
+            "makes it production.",
+        inputSchema: {
+            hostname: z
+                .string()
+                .describe('Hostname to attach, e.g. "www.example.com". Leading https:// and trailing slashes are stripped.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'domain', { hostname: args.hostname });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'poll_domain',
+        description: "Ask Cloudflare for the current state of the attached domain and " +
+            "update the site doc accordingly. Idempotent — call after DNS " +
+            "changes propagate. Returns the new state; status may have advanced " +
+            "from 'pending' to 'verified' or 'failed'.",
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.post(siteId, 'domain/poll');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'activate_domain',
+        description: "Make the verified domain the production URL. Precondition: status " +
+            "must be 'verified' (or already 'live' — idempotent). After this " +
+            "call, the site's `production_url` switches from the fallback URL " +
+            "to https://<hostname>. " +
+            "By default also enqueues a production deploy so the canonical URL, " +
+            "sitemap, and JSON-LD update to reflect the new hostname — the " +
+            "response includes `deploy.job_id` you can poll. Pass " +
+            "`auto_deploy: false` to skip the deploy (the canonical stays at " +
+            "the previous URL until the customer deploys manually).",
+        inputSchema: {
+            auto_deploy: z
+                .boolean()
+                .optional()
+                .describe('Default true. Enqueue a production deploy after activation so canonical URLs update.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'domain/activate', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'remove_domain',
+        description: "Detach the custom domain from this site. Removes it from Cloudflare " +
+            "Pages and clears the site doc. The fallback subdomain remains. " +
+            "Use this when the customer wants to start over with a different " +
+            "hostname or move the site to a different domain provider.",
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.del(siteId, 'domain');
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/media.js

@@ -59,7 +59,7 @@ export const mediaTools = [
     },
     {
         name: 'create_upload_url',
-        description: 'Mint a 5-min signed PUT URL for direct-to-R2 upload. After the upload completes, the CDN url is what you reference in <img src="…">. The media doc is pre-created so a follow-up update_media can attach alt_text.',
+        description: 'Mint a 5-min signed PUT URL for direct-to-R2 upload. After the upload completes, the CDN url is what you reference in <img src="…">. REQUIRED follow-up: call `finalize_media` after the PUT succeeds — without it the original ships with no Cache-Control (Lighthouse will flag it) and no responsive variants get generated. The response carries `finalize_url` as a reminder. Prefer `upload_media_from_url` or `upload_media_inline` if you have the bytes in hand — they do the PUT + finalize for you in one call.',
         inputSchema: {
             filename: z.string().min(1),
             content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
@@ -108,12 +108,27 @@ export const mediaTools = [
             if (!putRes.ok) {
                 throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
             }
+            // 4. Auto-finalize: set immutable Cache-Control on the original and
+            //    generate AVIF/WebP responsive variants. Best-effort — if it
+            //    fails (variant pipeline 500, missing env var on the server),
+            //    the upload itself still succeeded so we return ok with a
+            //    `finalize_error` flag instead of throwing.
+            let finalizeResult = null;
+            let finalizeError = null;
+            try {
+                finalizeResult = await client.post(siteId, `media/${encodeURIComponent(mint.media_id)}/finalize`);
+            }
+            catch (e) {
+                finalizeError = e instanceof Error ? e.message : String(e);
+            }
             return ok({
                 media_id: mint.media_id,
                 cdn_url: mint.cdn_url,
                 filename,
                 content_type: contentType,
                 size_bytes: buf.byteLength,
+                finalize: finalizeResult,
+                finalize_error: finalizeError,
             });
         }),
     },
@@ -149,12 +164,24 @@ export const mediaTools = [
             if (!putRes.ok) {
                 throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
             }
+            // Auto-finalize (cache headers + AVIF/WebP variants). See
+            // upload_media_from_url for the same pattern + rationale.
+            let finalizeResult = null;
+            let finalizeError = null;
+            try {
+                finalizeResult = await client.post(siteId, `media/${encodeURIComponent(mint.media_id)}/finalize`);
+            }
+            catch (e) {
+                finalizeError = e instanceof Error ? e.message : String(e);
+            }
             return ok({
                 media_id: mint.media_id,
                 cdn_url: mint.cdn_url,
                 filename: args.filename,
                 content_type: args.content_type,
                 size_bytes: buf.byteLength,
+                finalize: finalizeResult,
+                finalize_error: finalizeError,
             });
         }),
     },
@@ -174,13 +201,31 @@ export const mediaTools = [
     },
     {
         name: 'generate_image_variants',
-        description: 'Run the build-time srcset pipeline for one image: produces webp + avif variants at 320 / 640 / 1024 / 1920 (skipping upscales), uploads them to R2 alongside the original, and patches the media doc with a variants[] array. Synchronous; takes ~1-5s per image. Skips PDFs and non-image media without erroring. Loop this over list_media to rebuild an existing library; call once per image right after upload to keep new media current.',
+        description: 'Run the build-time srcset pipeline for one image: produces webp + avif variants at 320 / 640 / 1024 / 1920 (skipping upscales), uploads them to R2 alongside the original, and patches the media doc with a variants[] array. Synchronous; takes ~1-5s per image. Skips PDFs and non-image media without erroring. NOTE: prefer `finalize_media` for new uploads — it does this PLUS sets immutable Cache-Control on the original. Use this tool only for surgical variant reruns.',
         inputSchema: { media_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.post(siteId, `media/${encodeURIComponent(args.media_id)}/generate-variants`);
             return ok(res);
         }),
     },
+    {
+        name: 'finalize_media',
+        description: 'Post-upload finalize for a single image: (1) applies immutable Cache-Control (public, max-age=31536000) to the R2 original via in-place CopyObject so the CDN caches it for a year, and (2) generates AVIF/WebP responsive variants if not already present. Call this immediately after a successful upload (the presigned PUT does NOT set cache headers — without finalize, Cloudflare defaults to ~4h and every visit re-fetches the original). Idempotent: safe to call twice. Skips variant work when variants already exist on the doc.',
+        inputSchema: { media_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `media/${encodeURIComponent(args.media_id)}/finalize`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'finalize_all_media',
+        description: 'Backfill version of finalize_media: walks the entire media library, applies cache headers + variant generation to every item missing them. Use this once on legacy sites to fix Lighthouse "cache lifetimes" + "image delivery" warnings in one go. Synchronous, can take minutes on large libraries (~1-5s per image needing variants, ~50ms for cache-only). Idempotent.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.post(siteId, 'media/finalize-all');
+            return ok(res);
+        }),
+    },
     {
         name: 'suggest_alt_text_context',
         description: 'Get everything you need to generate good alt-text for a media item: the image URL, a tuned SEO/accessibility prompt, the site\'s content language, and the list of pages where the image is used (with the nearest heading per use site). YOU run the actual vision call with your own model — this endpoint does NOT generate text. After you decide on alt-text, save it with update_media.',

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,23 +61,31 @@ 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 "". ' +
-            'Slug must be a single path segment — no leading/trailing slashes, no internal slashes. ' +
-            'For nested URLs like /blog/{slug} or /services/{slug}, use a collection with a ' +
-            'route_template (see the tr-blog and tr-directory skills) — NOT a page slug with a slash. ' +
-            '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 — single path segment, no slashes (e.g. "about", "kontakt"). Empty string "" = homepage. For nested URLs use a collection with route_template, not a slug like "services/design" — the API rejects internal slashes.'),
-            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(),
             seo_title: z.string().optional(),
             seo_description: z.string().optional(),
+            seo_image_alt: z.string().optional(),
+            schema_type: z.string().optional().describe('Free-form Schema.org type ("Service", "Course", "Product", …) for auto JSON-LD.'),
             kind: z.enum(['page', 'article']).optional(),
             author: z.string().optional(),
             language: z.string().optional().describe('BCP-47 tag overriding the site default (e.g. "en" on an otherwise Swedish site).'),
@@ -109,9 +117,21 @@ export const pageTools = [
                 seo_title: z.string().optional(),
                 seo_description: z.string().optional(),
                 og_image: z.string().optional(),
+                seo_image_alt: z.string().optional().describe('Alt text for og:image/twitter:image. Falls back to first <img alt> on the page when unset.'),
                 canonical_url: z.string().optional(),
                 noindex: z.boolean().optional(),
+                lastmod_override: z.string().optional().describe('Override the sitemap <lastmod>. Empty string suppresses lastmod for this page entirely.'),
                 json_ld: z.string().optional(),
+                schema_type: z.string().optional().describe('Free-form Schema.org type ("Service", "Course", "Product", …) used for auto JSON-LD emission. Use service.* for Service-specific fields.'),
+                service: z
+                    .object({
+                    price: z.union([z.number(), z.string()]).optional(),
+                    price_currency: z.string().optional().describe('ISO 4217 (SEK, EUR, USD).'),
+                    duration: z.string().optional(),
+                    description: z.string().optional(),
+                    url: z.string().optional(),
+                })
+                    .optional(),
                 template: z.string().optional(),
             })
                 .passthrough(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.7.9",
+  "version": "0.9.0",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {

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.