@typeroll/mcp-server 0.29.0 → 0.32.0

package/dist/tools/block-types.js

@@ -122,7 +122,7 @@ export const blockTypeTools = [
     // audit + UI distinguish agent-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 via `script` is accepted under your API key's authority (audit-logged; the response carries a notice) — review before deploy. Returns the created BlockType. Responsive fields: mark a schema field `responsive: true` and expose it as style=\"--{field}:{{field}}\" on the outermost element so it can vary per breakpoint. If the value is directly usable CSS, read var(--{field}); if it's a token that maps to CSS (e.g. layout 'icon-left' → flex-direction:row) add a `responsive_css` map on the field ({ 'icon-left': '--dir: row;' }), otherwise per-breakpoint overrides won't take effect.",
+        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 via `script` is accepted under your API key's authority (audit-logged; the response carries a notice) — review before deploy. This is the supported way to ship per-page JS: `<script>` written into page or block MARKUP is stripped by the renderer's sanitizer no matter which credential wrote it, so package the behaviour as a block type instead. Site-wide tags belong in settings.scripts_head / scripts_body_end. Returns the created BlockType. Responsive fields: mark a schema field `responsive: true` and expose it as style=\"--{field}:{{field}}\" on the outermost element so it can vary per breakpoint. If the value is directly usable CSS, read var(--{field}); if it's a token that maps to CSS (e.g. layout 'icon-left' → flex-direction:row) add a `responsive_css` map on the field ({ 'icon-left': '--dir: row;' }), otherwise per-breakpoint overrides won't take effect.",
         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).'),
@@ -142,7 +142,7 @@ export const blockTypeTools = [
             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>"].'),
-            script: z.string().optional().describe('Client-side JS shipped with the block (runs on the published site). Only honoured when the site has enabled AI block scripts; otherwise stripped with a warning in the response.'),
+            script: z.string().optional().describe("Client-side JS shipped with the block (runs on the published site). Accepted under your API key's authority — the write is audit-logged and the response carries a notice naming the stored JS. It runs on the published site's own origin, which shares nothing with the Typeroll portal."),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -157,7 +157,7 @@ export const blockTypeTools = [
     },
     {
         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. The `script` field follows the same site-setting gate as create_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. The `script` field follows the same policy as create_block_type — accepted under your key's authority, audit-logged, notice in the response.",
         inputSchema: {
             type_id: z.string().describe('Block type id (custom or third_party). Cannot be a core/* block.'),
             label: z.string().optional(),
@@ -174,7 +174,7 @@ export const blockTypeTools = [
             schema: z.array(z.unknown()).optional(),
             template: z.string().optional(),
             styles: z.string().optional(),
-            script: z.string().optional().describe('Only honoured when the site has enabled AI block scripts; otherwise stripped with a warning.'),
+            script: z.string().optional().describe("Accepted under your API key's authority; audit-logged, and the response carries a notice naming the stored JS."),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/collections.js

@@ -100,6 +100,22 @@ export const collectionTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'collection_completeness',
+        description: "Which records in a collection need work, worst first. Returns per-field gap counts across the whole collection plus the N worst items (missing fields, never-verified fields, and fields whose last write is older than the staleness window). Use this INSTEAD of paging every item and diffing client-side — it's the intended entry point for an enrichment pass. Computed at read time, so it's never stale. By default only fields an API key may actually write are counted, since a gap you're forbidden to close is noise; pass all_fields: true for a human audit.",
+        inputSchema: {
+            collection: z.string(),
+            limit: z.number().int().min(1).max(500).optional().describe('Worst-N items to return. Default 50.'),
+            stale_after_days: z.number().int().min(1).optional().describe('A field untouched for longer than this is reported stale. Default 180.'),
+            all_fields: z.boolean().optional().describe('Include fields no API key may write. Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, ...query } = args;
+            const res = await client.get(siteId, `collections/${encodeURIComponent(collection)}/completeness`, { ...query, ...v(version) });
+            return ok(res);
+        }),
+    },
     {
         name: 'list_collection_items',
         description: 'List items in a collection with status filter + cursor pagination (cap 200 per page). Defaults to summary mode (richtext/textarea fields replaced with a byte-count hint) so a 200-item directory listing stays compact; pass include_richtext: true if you actually need full bodies.',

package/dist/tools/migration.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+const STATUS = z.enum(['migrated', 'redirected', 'excluded', 'unhandled']);
+export const migrationTools = [
+    {
+        name: 'get_migration_readiness',
+        description: "Preflight for an import: is this site actually ready to receive a migration? CALL THIS FIRST, before moving any content. Every check exists because its failure is INVISIBLE afterwards — the pages import, the previews render, the customer signs off, and something is quietly wrong. The blockers: media storage (without it every <img> keeps its original URL, so the shiny new site is still served images by the old host, and the day that hosting is cancelled every image breaks at once) and the hosting adapter (without credentials, deploys return a job id and publish nothing while reporting success). Warnings cover the pre-cutover verification URL, AI reconstruction, form notification email and whether the target has a design to rebuild INTO. Returns { ready, blockers[], warnings[], checks[] } — each with a `fix`. If `ready` is false, stop and report the blockers to the user rather than starting the import; the content work would have to be redone.",
+        inputSchema: {
+            source_url: z
+                .string()
+                .optional()
+                .describe('The site you are migrating FROM, e.g. "https://oldsite.com". When given, the source is probed too: unreachable or bot-blocked (403/429) is a BLOCKER because an import from a host that refuses our requests produces empty pages, and whether /wp-json answers is reported as a warning (without it the importer must scrape HTML and loses ACF/custom fields).'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'migration-preflight', args.source_url ? { source_url: args.source_url } : undefined);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_migration_urls',
+        description: "The legacy site's URL inventory with LIVE coverage status. Every entry is classified on read against the site's current pages + redirects: `migrated` (a page/collection item answers at that path), `redirected` (a redirect rule covers it), `excluded` (signed off as an intentional 404), `unhandled` (nothing covers it — the work list). Returns a summary over the whole inventory plus a page of entries, sorted worst-first then by GSC clicks. Use `status: \"unhandled\"` to get exactly what's left to do before cutover. Coverage is computed, never stored, so it's current the moment you create a redirect.",
+        inputSchema: {
+            status: STATUS.optional().describe('Only return entries with this coverage status.'),
+            limit: z.number().int().positive().max(1000).optional().describe('Default 200.'),
+            offset: z.number().int().min(0).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'migration-urls', {
+                status: args.status,
+                limit: args.limit,
+                offset: args.offset,
+            });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'add_migration_urls',
+        description: "Add old-site URLs to the inventory in bulk (up to 2000 per call). This is how the inventory gets populated outside the in-portal WordPress migration: walk the old sitemap.xml, a GSC export, or a crawl, and post what you found. Idempotent — re-posting a known URL merges its `source` label instead of duplicating. Pass `source_origin` when the site you're inventorying has its own domain: absolute URLs from a different origin are then REJECTED rather than silently folded in, which is what keeps a ten-domain multisite migration from pouring domain B's `/kontakt` into domain A's inventory. Rejected entries come back with a reason — nothing is dropped silently.",
+        inputSchema: {
+            urls: z
+                .array(z.object({
+                url: z.string().describe('Absolute URL (preferred) or a bare path like "/om-oss".'),
+                source: z.string().optional().describe('Where you found it: "sitemap", "gsc", "crawl", "manual", …'),
+                notes: z.string().optional(),
+                gsc_clicks: z.number().optional().describe('Search Console clicks — drives prioritisation in the coverage report.'),
+                gsc_impressions: z.number().optional(),
+                excluded: z.boolean().optional().describe('Mark immediately as an intentional 404 (e.g. /wp-admin, tag archives you are dropping).'),
+            }))
+                .min(1)
+                .max(2000),
+            source: z.string().optional().describe('Default source label for entries that omit one.'),
+            source_origin: z
+                .string()
+                .optional()
+                .describe('Origin of the old site, e.g. "https://old.example.com". Rejects absolute URLs from other origins.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'migration-urls', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_migration_url',
+        description: 'Annotate one inventory entry. `excluded: true` is the sign-off that this URL is MEANT to 404 after cutover — it moves the entry out of the "unhandled" work list without inventing a redirect for it. Also accepts notes and GSC metrics. The url_id is the entry id from list_migration_urls (the path with slashes replaced by underscores).',
+        inputSchema: {
+            url_id: z.string(),
+            excluded: z.boolean().optional(),
+            notes: z.string().optional(),
+            gsc_clicks: z.number().optional(),
+            gsc_impressions: z.number().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { url_id, ...patch } = args;
+            const res = await client.patch(siteId, `migration-urls/${encodeURIComponent(url_id)}`, patch);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_migration_url',
+        description: 'Remove an entry from the inventory entirely. Use for junk the crawl picked up (session URLs, faceted duplicates). To record a deliberate 404 instead, prefer update_migration_url with excluded: true — that keeps the decision visible in the coverage report.',
+        inputSchema: { url_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `migration-urls/${encodeURIComponent(args.url_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'verify_migration_urls',
+        description: "Pre-cutover parity check: actually REQUEST every inventory URL against the new site and report what it answers. list_migration_urls tells you what the data says; this tells you what the server does — a redirect pointing at an unpublished page, a typo'd path, or a redirect loop all read as \"handled\" in coverage and as a 404 to Googlebot. Runs against the site's fallback subdomain by default, which is the right target while the real domain still points at the old host. Verdicts: `ok` (200 at the same path), `ok_redirect` (redirects to a 200), `missing` (404/410 — the gap), `broken_redirect` (loop or chain ending badly), `error` (5xx/timeout, inconclusive). Also stamps verified/last_checked on the redirect rules it exercised. Deploy before running this — it tests the DEPLOYED site, not your drafts.",
+        inputSchema: {
+            target_origin: z
+                .string()
+                .optional()
+                .describe('Origin to test, e.g. "https://acme.sites.typeroll.com". Defaults to the site\'s fallback subdomain, then its live domain.'),
+            source_origin: z.string().optional().describe('Old site origin, e.g. "https://old.example.com".'),
+            check_source: z
+                .boolean()
+                .optional()
+                .describe('Also request each path on the OLD site (requires source_origin), so a URL that already 404s upstream is distinguishable from one the migration lost. Doubles the request count.'),
+            statuses: z
+                .array(STATUS)
+                .optional()
+                .describe('Only check entries with these coverage statuses. Default: all — "migrated" is exactly the claim this check exists to falsify.'),
+            limit: z.number().int().positive().max(500).optional().describe('Max URLs per run (default 150). `truncated: true` in the response means there are more.'),
+            concurrency: z.number().int().positive().max(12).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'migration-urls/verify', args);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/pages.js

@@ -85,6 +85,10 @@ export const pageTools = [
             seo_title: z.string().optional(),
             seo_description: z.string().optional(),
             seo_image_alt: z.string().optional(),
+            alternates: z
+                .array(z.object({ hreflang: z.string(), href: z.string() }))
+                .optional()
+                .describe('Cross-domain hreflang cluster: the equivalents of THIS page on sister language sites, as [{ hreflang, href }]. One Typeroll site owns one domain, so a multi-language family (example.se / example.de / example.co.uk) is several sites and the mapping can\'t be derived — declare it here. List only the OTHER variants; the renderer injects this page\'s self-reference automatically. hreflang is a BCP-47 tag ("sv", "en-GB") or "x-default"; href must be an absolute http(s) URL. Invalid entries are rejected at write time with the reason, so a half-written cluster never ships. Every page in a cluster must link every other one — write all sides.'),
             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(),
@@ -123,7 +127,13 @@ export const pageTools = [
                 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(),
+                path: z.string().optional().describe('Explicit URL path for nested pages (e.g. "/erbjudanden/sommar-2026"). Takes precedence over slug for routing; changing it auto-creates a 301 from the old URL on save.'),
                 noindex: z.boolean().optional(),
+                alternates: z
+                    .array(z.object({ hreflang: z.string(), href: z.string() }))
+                    .nullable()
+                    .optional()
+                    .describe('Cross-domain hreflang cluster: the equivalents of THIS page on sister language sites, as [{ hreflang, href }]. One Typeroll site owns one domain, so a multi-language family (example.se / example.de / example.co.uk) is several sites and the mapping can\'t be derived — declare it here. List only the OTHER variants; the renderer injects this page\'s self-reference automatically. hreflang is a BCP-47 tag ("sv", "en-GB") or "x-default"; href must be an absolute http(s) URL. Invalid entries are rejected at write time with the reason, so a half-written cluster never ships. Every page in a cluster must link every other one — write all sides. Pass null to clear the cluster.'),
                 lastmod_override: z.string().optional().describe('Override the sitemap <lastmod>. Empty string suppresses lastmod for this page entirely.'),
                 image_sizes_default: z.string().optional().describe('Per-page default `sizes` for responsive images (e.g. "(max-width: 640px) 360px, 560px"). Overrides the site setting; a per-<img> `sizes` attr still wins. Set when this page\'s images render narrower than the generic default so the browser stops over-fetching the larger variant.'),
                 custom_css: z.string().optional().describe('Per-page CSS, injected into <head> as a <style> AFTER the site-level custom_css (so it overrides site styling). The RIGHT home for page-specific styling — put a page\'s <style> here instead of stuffing it into a core/html block.'),

package/dist/tools/redirects.js

@@ -15,10 +15,16 @@ export const redirectTools = [
     },
     {
         name: 'create_redirect',
-        description: 'Create a redirect rule. Defaults to 301; pass status_code=302 for a temporary redirect.',
+        description: 'Create a redirect rule. Defaults to 301; pass status_code=302 for a temporary redirect. ' +
+            'WILDCARDS: a trailing "*" captures everything under a prefix and ":splat" replays it into the ' +
+            'target — `from_path="/category/*", to_path="/blogg/:splat"` retires an entire WordPress taxonomy ' +
+            'in one rule. `:name` matches exactly one segment (`"/blog/:slug"` → `"/artiklar/:slug"`). ' +
+            'Rules that would hide a live page are refused (Cloudflare applies redirects before serving files, ' +
+            'so the page would become unreachable) — narrow the pattern. Query strings cannot be matched: an ' +
+            'old `/?p=123` URL has no path to key on.',
         inputSchema: {
-            from_path: z.string().describe('Old path, leading slash (e.g. "/old-about")'),
-            to_path: z.string().describe('Target path or absolute URL'),
+            from_path: z.string().describe('Old path, leading slash (e.g. "/old-about"). May be a pattern: "/category/*" (trailing splat only) or "/blog/:slug" (one segment).'),
+            to_path: z.string().describe('Target path or absolute URL. May reference ":splat" (requires a "*" in from_path) or any ":name" from_path declares.'),
             status_code: z.union([z.literal(301), z.literal(302)]).optional(),
             version: versionParam,
         },

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.29.0';
+export const VERSION = '0.32.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.29.0",
+  "version": "0.32.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/README.md

@@ -58,6 +58,7 @@ ln -s "$PWD/skills/tr-migrate-wp.md" ~/.claude/skills/
 | File | When it triggers | What it does |
 |---|---|---|
 | `tr-migrate-wp.md`     | "migrate from WordPress", a wp-json URL is mentioned     | Walks the WP REST, rebuilds each page in the target's design, transfers media, sets redirects, leaves everything as drafts for review. |
+| `tr-migrate-multisite.md` | "multisite", "our .se/.de/.co.uk sites", migrating several sites at once | One site per domain; per-site URL inventory, design replicated via `.tcblocks`, path preservation, hreflang clusters, and a parity check against the deployed site before DNS moves. |
 | `tr-migrate-astro.md`  | "migrate an Astro site", "import from src/content"       | Lifts Astro Content Collections (`src/content/*`) into Typeroll collections — zod schema → field list, frontmatter → field values, markdown body → richtext field. Translates standalone `src/pages/*` into Typeroll pages, maps `src/layouts` chunks into partials. |
 | `tr-import-url.md`     | "import from Squarespace/Wix/Webflow", any non-WP URL    | Fetch → clean → adapt to target design → media transfer → draft pages → redirects → deploy. |
 

package/skills/tr-migrate-multisite.md

@@ -0,0 +1,348 @@
+---
+name: tr-migrate-multisite
+description: Use when migrating SEVERAL sites at once — a WordPress multisite network, a group of country/language sites on different top-level domains, or any batch of related sites moving to Typeroll together. Triggers on "multisite", "network of sites", "10 sites", "our .se/.de/.co.uk sites", "language versions", "migrate all our sites". For a single WordPress site use tr-migrate-wp; for a single non-WP source use tr-import-url.
+---
+
+# Migrate a multisite / multi-domain family to Typeroll
+
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+## The first decision: one site or many?
+
+**One Typeroll site owns exactly one domain** (plus its apex/www sibling).
+So:
+
+| The old family looks like | Build it as |
+|---|---|
+| `example.se`, `example.de`, `example.co.uk` — separate domains | **N Typeroll sites**, one per domain |
+| `example.com/se/`, `example.com/de/` — one domain, language folders | **One site**, using `path` on each page (`/se/om-oss`) |
+| A WP multisite on subdomains that the customer wants to consolidate onto one domain | **One site** + redirects from every old subdomain |
+
+Confirm this with the user before creating anything — it's the one decision
+that is expensive to reverse (domains, deploys, and analytics all hang off
+it). The rest of this recipe assumes the common case: **N sites, one per
+domain**, sharing a design.
+
+Requires an **org-scoped API key** (`create_site` needs it, and one key
+reaching every site is the whole point here). With MCP you pass `site_id`
+per call; over stdio you'll be re-pointing `TYPEROLL_SITE_ID` per site.
+
+## Phase 0 — Plan the batch (do this once, in writing)
+
+Produce a table and get the user to confirm it before touching the platform:
+
+| Old URL | Language | New Typeroll site | Domain | Notes |
+|---|---|---|---|---|
+
+**Check platform readiness before the plan is even agreed:**
+
+```
+get_migration_readiness site_id=<any existing site>
+```
+
+Then once per market, with that market's own source:
+
+```
+get_migration_readiness site_id=<de-site> source_url="https://example.de"
+```
+
+The blockers (media storage, hosting credentials) are **platform-level, not
+per-site** — if they fail for one site they fail for all ten, and finding out
+after building three sites means redoing three sites' worth of image work.
+Get them fixed before Phase 1, and re-run the check per site once the sites
+exist (the warnings — verification URL, form email, design reference — are
+per-site).
+
+Ask explicitly:
+- Which site is the **design reference**? Build that one properly first.
+- Are the sites **translations of each other** (same page structure) or
+  independent? This decides whether hreflang clusters are mechanical or
+  hand-mapped.
+- Any domains being **retired or merged**? Those need redirects at the DNS
+  level, not just inside a site.
+
+## Phase 1 — Inventory EVERY old site, before building anything
+
+Do this for all sites up front. It's cheap, it's the only artefact that tells
+you when you're done, and it stops you discovering an untouched 400-URL blog
+in week three.
+
+For each source site, create the target site first (the inventory lives on
+it):
+
+```
+create_site name="Example DE" domain="example.de"
+```
+
+Then walk the source and post what you find:
+
+```
+fetch https://example.de/sitemap.xml            # follow sitemap-index children
+fetch https://example.de/wp-json/wp/v2/pages?per_page=100   # walk X-WP-TotalPages
+```
+
+```
+add_migration_urls site_id=<de-site> source_origin="https://example.de" source="sitemap" urls=[
+  { url: "https://example.de/ueber-uns" },
+  { url: "https://example.de/kontakt" },
+  …
+]
+```
+
+**`source_origin` is not optional in a multisite job.** It rejects URLs from
+another origin, which is the guard that stops domain B's `/kontakt` landing
+in domain A's inventory — where it would silently read as "covered" because
+domain A happens to have a `/kontakt` too.
+
+Add every source you have, each with its own label — they merge per URL:
+- `source="sitemap"` — the sitemap(s)
+- `source="rest"` — WP REST pages/posts/custom types
+- `source="gsc"` — a Search Console export, **with `gsc_clicks`**. This is
+  what makes the coverage report prioritise itself: the 12 URLs carrying all
+  the traffic sort to the top.
+- `source="crawl"` — anything you found by following internal links
+
+Mark the obvious throwaways immediately, so the work list is real:
+
+```
+add_migration_urls urls=[{ url: "/wp-admin", excluded: true }, { url: "/tag/nyheter", excluded: true }]
+```
+
+Read it back and note the starting number:
+
+```
+list_migration_urls site_id=<de-site> status="unhandled" limit=50
+```
+
+## Phase 2 — Build the reference site
+
+Follow `tr-migrate-wp` (or `tr-import-url`) for the ONE reference site:
+design, header/footer partials, page templates, block types. Get the user to
+approve it before replicating — every fix you make after this point costs
+N times as much.
+
+## Phase 3 — Replicate the design to the other sites
+
+Design travels as a block-type package, not by hand:
+
+```
+export_block_types site_id=<reference>                 # → .tcblocks JSON
+import_block_types site_id=<other> package=<that JSON>
+```
+
+Then per site:
+- `read_site_settings` on the reference → `update_site_settings` on the
+  target with the same colors/fonts (translate `site_name`, `tagline`,
+  contact details — those are per-market, not shared).
+- Recreate header/footer partials with translated nav labels.
+- Page templates: rebuild with `add_block target={kind:'template', id:…}`.
+
+Set the language per site — it drives `<html lang>`, `og:locale` and
+alt-text generation:
+
+```
+update_site site_id=<de-site> language="de"
+```
+
+## Phase 4 — Migrate content, preserving paths
+
+Per site, per URL, follow `tr-migrate-wp` §3. Two rules that matter more here
+than in a single-site migration:
+
+1. **Preserve the path verbatim** unless there's a reason not to. Use
+   `path` for anything nested: `create_page title="Über uns" slug="ueber-uns"
+   path="/ueber-uns"`. A preserved path needs no redirect and loses nothing.
+2. **Rewrite internal links to the NEW paths.** Imported HTML is full of
+   absolute links to the old domain. Sweep them per site:
+
+```
+bulk_replace_text site_id=<de-site> find="https://example.de/" replace="/" dry_run=true
+```
+
+Check the dry-run count against what you expect before running it for real.
+Cross-domain links between sister sites stay absolute — only the site's own
+domain becomes relative.
+
+### Media: per site, not shared
+
+Every Typeroll site has its own media library, so a shared asset (the group
+logo, a product shot used in all markets) is uploaded once **per site** and
+gets a different CDN URL in each. That's correct — the sites are independent
+and one market's deploy must not depend on another's assets — but it means:
+
+- Don't try to reuse a `cdn_url` from site A inside site B's HTML. It will
+  render, and it will break the day site A is deleted or moved.
+- Do write alt text per market, in that market's language:
+  `update_media media_id=… alt_text="…"`. The alt text is content, not
+  metadata, and a Swedish alt on a German page is a real accessibility defect.
+
+Images referenced only from a stylesheet or from unrendered page-builder JSON
+are NOT found by an HTML scan. Spot-check the hero/background images of the
+top pages in the preview before you call a site done.
+
+### Forms are NOT migrated — plan to rebuild them
+
+The HTML cleaner strips `<form>`, `<input>`, `<select>` and `<button>`
+entirely, on purpose: a Contact Form 7 / Gravity / Elementor form posts to
+WordPress endpoints that no longer exist, so importing the markup would give
+you a form that looks alive and silently drops every submission.
+
+So, per site:
+
+```
+create_form name="Kontakt" fields=[…]         # or steps=[…] for a funnel
+add_block target={kind:'page', id:'kontakt'} block={type:'core/form', data:{form_id:'<id>'}}
+```
+
+Then, still per site:
+
+- **Recipient address per market** — the German enquiries rarely go to the
+  Swedish inbox. Check this explicitly; it is the single most common thing
+  to get wrong in a batch of ten.
+- **Email delivery is configured per site** by an admin in the portal
+  (Settings → Integrations), not through this API. Flag it to the user as a
+  manual step — a form that saves submissions but sends no notification looks
+  fine in testing and loses leads in production.
+- **Submit a real test through every form** after deploy, and confirm both the
+  stored submission and the notification email.
+
+Count the old site's forms during Phase 1 and put them in the plan table.
+Ten sites × three forms is thirty forms, and it is the part of the job that
+never shows up in a URL inventory.
+
+## Phase 5 — Redirects for everything you didn't preserve
+
+Work the coverage report, not your memory:
+
+```
+list_migration_urls site_id=<de-site> status="unhandled"
+```
+
+For each entry, one of three outcomes — no fourth option:
+
+- It moved → `create_redirect from_path="/alte-seite" to_path="/neue-seite"`
+- It's gone on purpose → `update_migration_url url_id=… excluded=true notes="Old campaign LP, signed off by <name>"`
+- It should exist and doesn't → go back and migrate it
+
+Re-read the list. `unhandled` reaching zero is the exit condition for this
+phase.
+
+**Clear the URL families with one rule each**, per site — a WP network
+multiplies the same dead shapes across every market:
+
+```
+create_redirect site_id=<de-site> from_path="/category/*" to_path="/blogg/:splat"
+create_redirect site_id=<de-site> from_path="/tag/*"      to_path="/blogg"
+create_redirect site_id=<de-site> from_path="/2019/*"     to_path="/blogg/:splat"
+```
+
+Only a TRAILING `*` is supported (`:splat` replays the remainder); `:name`
+matches one segment. Pattern-covered inventory URLs count as `redirected`, so
+the work list actually empties. A pattern that would hide a live page is
+refused, naming the pages — narrow the prefix rather than working around it.
+
+Watch the per-market prefixes: the German site's archive base is `/kategorie/`,
+not `/category/`. Write the rules from each site's own inventory, never by
+copying the reference site's.
+
+## Phase 6 — Wire the hreflang cluster
+
+This is the step that only exists because the family is multi-domain, and the
+one most likely to be skipped. Each page declares its siblings on the other
+domains; the renderer adds the page's own self-reference.
+
+```
+update_page site_id=<se-site> page_id="om-oss" patch={ alternates: [
+  { hreflang: "de", href: "https://example.de/ueber-uns" },
+  { hreflang: "en-GB", href: "https://example.co.uk/about-us" },
+  { hreflang: "x-default", href: "https://example.com/about-us" }
+]}
+```
+
+Rules the search engines actually enforce:
+- **Reciprocal.** Every page in a cluster must list every other one. Write
+  all N sides or the cluster is ignored. `batch_update_pages` is the sane way
+  to do this once you have the mapping table.
+- **One `x-default`** per cluster, pointing at the language selector or the
+  fallback market. Optional, but useful when the family doesn't cover a
+  visitor's language.
+- **Absolute URLs on the final domain** — not the `*.typeroll` fallback
+  subdomain. The cluster is what you want live after cutover, and a fallback
+  URL in there is a leak you'll be cleaning up for months.
+- Invalid entries are **rejected at write time** with the reason. If a write
+  fails, fix the tag/href — don't strip the field to make it pass.
+
+Pages that have no equivalent on the other domains get no alternates at all.
+A cluster of one is meaningless markup.
+
+## Phase 7 — Verify BEFORE touching DNS
+
+Deploy each site (`trigger_deploy`), then check what it actually serves:
+
+```
+verify_migration_urls site_id=<de-site> source_origin="https://example.de" check_source=true
+```
+
+This requests every inventory URL against the site's fallback subdomain —
+the real domain still points at the old host, which is exactly why the check
+is possible at all. Verdicts:
+
+| Verdict | Meaning | Action |
+|---|---|---|
+| `ok` | 200 at the same path | none |
+| `ok_redirect` | redirects to a 200 | none; flatten if `hops` > 1 |
+| `missing` | 404/410 | **the gap** — redirect it or migrate it |
+| `broken_redirect` | loop, or chain ending on an error | fix the rule |
+| `error` | 5xx / timeout | inconclusive, re-run |
+
+`check_source=true` also requests the OLD site, so a URL that already 404s
+upstream shows up as noise in the inventory rather than as a migration
+failure — mark those `excluded`.
+
+Note what the check does NOT catch: it verifies that a URL *resolves*, not
+that the page at the other end is the right content. Spot-check the top
+`gsc_clicks` URLs by eye.
+
+Iterate until `missing` and `broken_redirect` are both zero **on every site**.
+Then, per site:
+
+1. `add_domain` / follow the DNS instructions the platform returns
+2. Point DNS
+3. `poll_domain` until verified → `activate_domain`
+4. Re-run `verify_migration_urls target_origin="https://example.de"` against
+   the real domain, to confirm the cutover kept what the pre-check proved
+5. Submit the new sitemap in Search Console; keep the old property open for
+   a few weeks and watch the 404 report
+
+## Definition of done (per site)
+
+- [ ] `get_migration_readiness source_url=<this market's old site>` → `ready: true`, warnings reviewed
+- [ ] `list_migration_urls status="unhandled"` → 0
+- [ ] `verify_migration_urls` → 0 `missing`, 0 `broken_redirect`
+- [ ] hreflang cluster written on both/all sides, absolute, final domains
+- [ ] `language` set on the site; `<html lang>` correct in the deployed HTML
+- [ ] Internal links rewritten (no lingering absolute links to the old domain)
+- [ ] Forms rebuilt, recipient address correct for THIS market, test submission sent and received
+- [ ] Media uploaded to this site's own library (no cross-site `cdn_url`), alt text in this market's language
+- [ ] Domain verified + activated; sitemap submitted
+
+## Pitfalls specific to this job
+
+- **Don't share one inventory across domains.** Inventory entries key on
+  path; two markets both have `/kontakt`. One site, one inventory.
+- **Don't build all N sites in parallel from scratch.** Build one, approve,
+  replicate. Parallel building multiplies every design mistake by N.
+- **Don't skip the parity check because coverage says 100%.** Coverage is a
+  claim about the data; parity is a measurement of the server. They disagree
+  exactly when it matters — an unpublished target page, a typo'd path, a
+  redirect chain.
+- **Don't point DNS site-by-site on a whim.** Cutting over one market at a
+  time is fine and usually wise, but the hreflang cluster spans markets: a
+  page pointing at a domain that still serves the old site is pointing at
+  content that doesn't match. Either cut over close together, or write the
+  cluster after the last market lands.