@typeroll/mcp-server 0.45.32 → 0.45.34

package/dist/bundled-content.js

@@ -15,8 +15,8 @@ export const BUNDLED_SKILLS = {
     "tr-import-url": "---\nname: tr-import-url\ndescription: Use when the user wants to import or migrate content from a non-WordPress website — a Squarespace site, a Wix site, a static HTML site, a Webflow export, or any URL the user points at. Also triggers on \"copy content from\", \"rebuild this site\", \"import from Squarespace/Wix/Webflow\", or \"make it look like this site\". For WordPress sources use tr-migrate-wp instead.\n---\n\n# Import content from a non-WordPress site\n\n**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.\nComplete its source baseline and one verified prototype per active template.\nRead target content to protect edits, not to justify accidental target defaults.\nIts shared evidence record is required for visual acceptance.\n\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks and partials) lands in an unsaved per-doc\n> DRAFT — deploys and plain previews only see SAVED content. For recipe-style\n> build work, pass `save: true` on write calls (the work is pre-approved by\n> the task itself), or run `commit_working_copy` per doc before any\n> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.\n\n\n## When to use this vs tr-migrate-wp\n\n| Source | Use |\n|---|---|\n| WordPress with `/wp-json` accessible | `tr-migrate-wp` |\n| WordPress with REST disabled | This skill (scrape HTML) |\n| Squarespace, Wix, Webflow, static HTML | This skill |\n| CSV / spreadsheet data | This skill (skip scraping, just parse) |\n| Any URL the user points at | This skill |\n\n## Preconditions\n\n- Target Typeroll site exists with working header/footer.\n- Source URL(s) accessible (check with a quick `fetch`; if blocked, mention\n  it and ask the user for an HTML export or screenshot).\n\n## Recipe\n\n### 1. Inventory the source site\n\nFetch the homepage and build a URL list:\n\n```\nfetch <source-url>                    # root HTML\nfetch <source-url>/sitemap.xml        # XML sitemap if it exists\n```\n\nParse `<a href>` links to discover internal pages. Build a list:\n- Homepage\n- Top-level pages (About, Services, Contact, etc.)\n- Any sub-pages that look important\n\nExclude private/session/admin URLs deliberately. Inventory public pagination and\nquery routes; decide preservation or retirement from their actual purpose.\n\n### 2. Measure the source and protect existing target work\n\n```\nread_site_settings\nread_partial partial_id=\"header\"\nlist_pages limit=5\n```\n\nRead existing target data to avoid overwriting work. Establish source geometry\nand validate native prototypes using `tr-migration-evidence` before mass writes.\n\n### 3. Fetch and clean each source page\n\nFor each URL:\n\n**a. Fetch the HTML.**\n```\nfetch <page-url>\n```\n\nIf the site returns a bot-block (Cloudflare, 403, or clearly JS-only\nSPA output), note it. Tell the user: \"This page blocked direct fetching.\nCan you provide the page source or an HTML export?\"\n\n**b. Extract the main content.**\n\nInventory shared navigation/header/footer, consent and runtime features first;\nmap them to reusable partials or supported runtimes before excluding them from\nindividual Page bodies.\nKeep: `<main>`, `<article>`, the largest content region.\n\nClean the HTML:\n- Strip platform-specific classes: `sqsrte-*`, `wf-*`, `et_*`,\n  `elementor-*`, `fl-*`, `divi-*`, `vc_*`\n- Remove empty `<div>`, `<span>`, `<section>` wrappers (no class, no content)\n- Unwrap redundant nesting: `<div><p>text</p></div>` → `<p>text</p>`\n- Keep: `<h1>`–`<h6>`, `<p>`, `<ul>`, `<ol>`, `<img>`, `<a>`, `<table>`,\n  `<blockquote>`, `<figure>`, `<figcaption>`, `<strong>`, `<em>`\n- Fix headings: ensure exactly one `<h1>` per page (the page title)\n\n**c. Transfer images.** For each `<img src>`:\n```\nupload_media_from_url url=\"<source-img-url>\" alt=\"...\"\n```\nReplace the src with the returned CDN URL. Classify tracking pixels separately. Preserve meaningful decorative images and\nicons. A required file that fails transfer blocks acceptance; do not silently\nomit it. Inventory PDFs, download hrefs, srcsets and backgrounds as well.\n\n**d. Adapt to the target's design.**\nUse verified native fields from the source capability map. Preserve appearance\nby default; do not substitute target defaults or corrective tenant CSS.\n\n### 4. Create pages as drafts\n\n```\ncreate_page title=\"Om oss\" slug=\"om-oss\"\n            html_content=\"<cleaned, adapted HTML>\"\n            content_mode=\"html\" status=\"draft\"\n            seo_title=\"Om oss — Acme\"\n            seo_description=\"...\"\n```\n\nAlways draft first. The user signs off before publishing.\n\n### 5. Handle redirects\n\nIf the source URLs differ from the target slugs, create redirects:\n\n```\ncreate_redirect from_path=\"/about\" to_path=\"/om-oss\"\ncreate_redirect from_path=\"/services.html\" to_path=\"/tjanster\"\n```\n\n### 6. Preview with the user\n\n```\nget_preview_link\n```\n\nWalk through every imported page with the user. Common issues:\n- Heading hierarchy wrong (two H1s, or H3 used where H2 belongs)\n- Images missing alt text\n- Squarespace column layouts that don't work without their grid system\n- Embedded forms or maps that need re-setup\n\n### 7. Publish + deploy\n\nAfter approval:\n```\nbatch_update_pages updates=[\n  {page_id: \"om-oss\",  patch: {status: \"published\"}},\n  {page_id: \"tjanster\", patch: {status: \"published\"}}\n]\ntrigger_deploy\nget_deploy_status job_id=<id>\n```\n\n## Platform-specific notes\n\n### Squarespace\n- Main content is inside `.content-wrapper` or `[data-section-theme]` blocks\n- Portfolio images are usually high-resolution originals in `/universal/images/`\n- JSON-LD is Squarespace's own schema — strip it\n- Gallery blocks → convert to CSS grid with inline `<img>` tags\n\n### Wix\n- Wix sites are React SPAs — `fetch` returns an empty shell\n- Ask the user for the Wix site's \"Export to HTML\" (available in some plans)\n  or take screenshots for reference\n- Best path: get content from the user (text + image files), rebuild clean\n\n### Webflow\n- Usually fetchable; clean output\n- Classes like `w-container`, `w-row`, `w-col-*` can be stripped\n- Webflow CMS items are server-rendered — they appear in the HTML\n\n### Static HTML / old sites\n- Often the cleanest import. Fetch, strip nav/footer, keep body.\n- Watch for table-based layouts (pre-2010 sites) — convert to CSS grid\n\n## Pitfalls\n\n- **Don't import `<style>` blocks from the source site.** They reference\n  external fonts, resets, and classes that don't exist in the target.\n  Strip all `<style>` tags from source HTML and rewrite styles in the\n  target's conventions.\n- **Don't break the single-H1 rule.** Many source sites have no H1 or\n  several. Fix it.\n- **Squarespace/Wix forms.** They won't work after import — the backend\n  is vendor-locked. Create a Typeroll form instead: `create_form`.\n- **Analytics/tracking code.** If the source has GA4 or similar, don't\n  copy it into pages. Set it via `update_site_settings scripts_head=\"...\"`.\n- **Videos.** YouTube/Vimeo embeds are fine (`<iframe>` is allowed).\n  Hosted MP4s need re-uploading if the source URL won't persist.\n\n## Storage prerequisite\n\nBefore reading or importing source content, call `get_import_readiness` (Core\n0.1.95 / MCP 0.44.68 or later). If `ready` is false, stop the import and show the\nreturned message and Publishing settings link. The organization must connect\nand verify its own storage first. Do not fall back to draft storage, hotlink\nsource images, or use ordinary page-write tools to bypass the import gate.\nUse `upload_media_from_url` for referenced source images; the customer’s\nCloudflare transfer Worker copies and verifies them directly in R2, independently\nof the GitHub/Cloudflare build-provider choice.\n",
     "tr-migrate-astro": "---\nname: tr-migrate-astro\ndescription: Migrate an existing Astro site, including Astro Content Collections, to native Typeroll Pages and Content types while preserving routes, design and media.\n---\n\n# Migrate an Astro site\n\n**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.\nComplete its source baseline and one verified prototype per active template.\nRead target content to protect edits, not to justify accidental target defaults.\nIts shared evidence record is required for visual acceptance.\n\n\nAstro Content Collections are source data. In Typeroll, each source record\nbecomes a Page, and each source schema becomes a Content type. Static Astro\npages use that same Page model. Shared Astro layouts become Page templates,\npartials or reusable block types; no separate item storage is created.\n\n## Inventory before writing\n\nRead the source repository's routing, content loaders, schema, frontmatter,\nlayouts, components, styling and public assets. New Astro projects can define\nloaders in `src/content.config.ts`; older projects may use\n`src/content/config.ts` and files under `src/content/`. Follow what the actual\nproject uses, including generated route logic and trailing-slash policy.\n\nDiscover the target with `get_site`, `get_site_capabilities`, `list_pages`,\n`list_content_types`, `list_page_templates` and `list_block_types`. Existing target\ncontent remains out of scope unless the user authorized replacing it. Create a\nsite version for the migration and pass it consistently on all versioned calls.\nCall `get_migration_readiness` before import; connect verified customer storage\nbefore transferring any source content or media.\n\nRecord a URL inventory from the existing site and source routing. Use explicit\nPage paths to preserve nested routes or frontmatter-based permalinks. Do not\nassume that a filename alone determines the production URL.\n\n## Map the source\n\n- Common frontmatter such as title, slug, author, publication date and SEO maps\n  to top-level Page metadata.\n- Other schema fields become the Content type's custom fields and Page `fields`.\n  Preserve typed objects and arrays; use `page_ref`/`page_ref_list` for relations.\n- Markdown becomes native Page body blocks. First render Markdown to HTML using\n  the source project's parser, then review block conversion. MDX components\n  require explicit equivalents; never drop them as if they were plain Markdown.\n- A shared layout becomes a reusable Page template with `template_content_slot`.\n  Assign it as the type's default. Header/footer and reusable fragments can be\n  partials. Use native blocks before choosing a rare reviewed HTML/embed exception.\n- Browser scripts, integrations and server-rendered endpoints need separate\n  review. A static Page cannot inherit a private server runtime by copying its\n  source text. Configure the supported Forms/Extension runtime explicitly.\n\nCreate templates with `create_page_template`, types with `create_content_type`,\nthen one `create_page` per source record. Use returned Page IDs, not source IDs\nor slugs, for later updates and previews. For linked content, create the Pages\nfirst and resolve their reference fields in a second pass.\n\nUpload assets to connected storage and rewrite source-relative image references\nto returned media URLs. Use direct upload URLs for local bytes and the customer\ntransfer flow for remote media; do not relay large base64 payloads through the\nmodel. Preserve alt text, captions, dimensions, links and image variants.\n\n## Listing and verification\n\nAn archive is a Page with `core/page_list` filtered by `content_type`. Configure\nsorting and pagination from the block schema. It reads saved Pages at build\ntime; do not generate a second listing representation or call a regeneration tool.\n\nCheck representative long/short bodies, code, tables, images, captions, embedded\ncomponents and related links at desktop and mobile widths. Compare the source\nand Typeroll preview, then a fresh authorized static build. Verify every inventory\nURL and redirect, canonical/hreflang, sitemap inclusion, noindex state and assets.\nSave working copies before publication. Keep the source host and DNS in place\nuntil the candidate passes checks and the user authorizes its cutover.\n",
     "tr-migrate-multisite": "---\nname: tr-migrate-multisite\ndescription: 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.\n---\n\n# Migrate a multisite / multi-domain family to Typeroll\n\n**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.\nComplete its source baseline and one verified prototype per active template.\nRead target content to protect edits, not to justify accidental target defaults.\nIts shared evidence record is required for visual acceptance.\n\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks and partials) lands in an unsaved per-doc\n> DRAFT — deploys and plain previews only see SAVED content. For recipe-style\n> build work, pass `save: true` on write calls (the work is pre-approved by\n> the task itself), or run `commit_working_copy` per doc before any\n> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.\n\n## The first decision: one site or many?\n\n**One Typeroll site owns exactly one domain** (plus its apex/www sibling).\nSo:\n\n| The old family looks like | Build it as |\n|---|---|\n| `example.se`, `example.de`, `example.co.uk` — separate domains | **N Typeroll sites**, one per domain |\n| `example.com/se/`, `example.com/de/` — one domain, language folders | **One site**, using `path` on each page (`/se/om-oss`) |\n| A WP multisite on subdomains that the customer wants to consolidate onto one domain | **One site** + redirects from every old subdomain |\n\nConfirm this with the user before creating anything — it's the one decision\nthat is expensive to reverse (domains, deploys, and analytics all hang off\nit). The rest of this recipe assumes the common case: **N sites, one per\ndomain**, sharing a design.\n\nRequires an **org-scoped API key** (`create_site` needs it, and one key\nreaching every site is the whole point here). With MCP you pass `site_id`\nper call; over stdio you'll be re-pointing `TYPEROLL_SITE_ID` per site.\n\n## Phase 0 — Plan the batch (do this once, in writing)\n\nProduce a table and get the user to confirm it before touching the platform:\n\n| Old URL | Language | New Typeroll site | Domain | Notes |\n|---|---|---|---|---|\n\n**Check platform readiness before the plan is even agreed:**\n\n```\nget_migration_readiness site_id=<any existing site>\n```\n\nThen once per market, with that market's own source:\n\n```\nget_migration_readiness site_id=<de-site> source_url=\"https://example.de\"\n```\n\nThe blockers (media storage, hosting credentials) are **platform-level, not\nper-site** — if they fail for one site they fail for all ten, and finding out\nafter building three sites means redoing three sites' worth of image work.\nGet them fixed before Phase 1, and re-run the check per site once the sites\nexist (the warnings — verification URL, form email, design reference — are\nper-site).\n\nAsk explicitly:\n- Which site is the **design reference**? Build that one properly first.\n- Are the sites **translations of each other** (same page structure) or\n  independent? This decides whether hreflang clusters are mechanical or\n  hand-mapped.\n- Any domains being **retired or merged**? Those need HTTP redirects served by the old hostname; DNS itself is not\n  a redirect. Plan that hosting separately.\n\n## Phase 1 — Inventory EVERY old site, before building anything\n\nDo this for all sites up front. It's cheap, it's the only artefact that tells\nyou when you're done, and it stops you discovering an untouched 400-URL blog\nin week three.\n\nFor each source site, create the target site first (the inventory lives on\nit):\n\n```\ncreate_site name=\"Example DE\"\n```\n\nThen walk the source and post what you find:\n\n```\nfetch https://example.de/sitemap.xml            # follow sitemap-index children\nfetch https://example.de/wp-json/wp/v2/pages?per_page=100   # walk X-WP-TotalPages\n```\n\n```\nadd_migration_urls site_id=<de-site> source_origin=\"https://example.de\" source=\"sitemap\" urls=[\n  { url: \"https://example.de/ueber-uns\" },\n  { url: \"https://example.de/kontakt\" },\n  …\n]\n```\n\n**`source_origin` is not optional in a multisite job.** It rejects URLs from\nanother origin, which is the guard that stops domain B's `/kontakt` landing\nin domain A's inventory — where it would silently read as \"covered\" because\ndomain A happens to have a `/kontakt` too.\n\nAdd every source you have, each with its own label — they merge per URL:\n- `source=\"sitemap\"` — the sitemap(s)\n- `source=\"rest\"` — WP REST pages/posts/custom types\n- `source=\"gsc\"` — a Search Console export, **with `gsc_clicks`**. This is\n  what makes the coverage report prioritise itself: the 12 URLs carrying all\n  the traffic sort to the top.\n- `source=\"crawl\"` — anything you found by following internal links\n\nMark the obvious throwaways immediately, so the work list is real:\n\n```\nadd_migration_urls urls=[{ url: \"/wp-admin\", excluded: true }, { url: \"/tag/nyheter\", excluded: true }]\n```\n\nRead it back and note the starting number:\n\n```\nlist_migration_urls site_id=<de-site> status=\"unhandled\" limit=50\n```\n\n## Phase 2 — Build the reference site\n\nFollow `tr-migrate-wp` (or `tr-import-url`) for the ONE reference site:\ndesign, header/footer partials, page templates, block types. Get the user to\napprove it before replicating — every fix you make after this point costs\nN times as much.\n\n## Phase 3 — Replicate the design to the other sites\n\nReplicate only source-validated native recipes and brand settings. Confirm each\nmarket's template overrides and business workflows independently. Export/import\ncustom block types only for specifically reviewed source-specific exceptions,\nnot generic corrective blocks or copied tenant CSS.\n\nThen per site:\n- `read_site_settings` on the reference → `update_site_settings` on the\n  target with the same colors/fonts (translate `site_name`, `tagline`,\n  contact details — those are per-market, not shared).\n- Recreate header/footer partials with translated nav labels.\n- Page templates: rebuild with `add_block target={kind:'template', id:…}`.\n\nSet the language per site — it drives `<html lang>`, `og:locale` and\nalt-text generation:\n\n```\nupdate_site site_id=<de-site> language=\"de\"\n```\n\n## Phase 4 — Preserve each market's business functions\n\nUse the business-function inventory from `tr-migration-evidence`. Some markets\nuse native Forms, others an owned lead flow, affiliate destination or partner\niframe. Do not replace them all with a new contact form. Configure a Form only\nwhere it is the approved equivalent. Verify each market's recipient, destination,\nlanguage and attribution. Use authorized synthetic tests with a safe recipient;\nrecord delivery UNVERIFIED when it cannot be tested safely. Never create real\nleads or send mail to third parties as a routine migration test.\n\n## Phase 5 — Redirects for everything you didn't preserve\n\nWork the coverage report, not your memory:\n\n```\nlist_migration_urls site_id=<de-site> status=\"unhandled\"\n```\n\nFor each entry, one of three outcomes — no fourth option:\n\n- It moved → `create_redirect from_path=\"/alte-seite\" to_path=\"/neue-seite\"`\n- It's gone on purpose → `update_migration_url url_id=… excluded=true notes=\"Old campaign LP, signed off by <name>\"`\n- It should exist and doesn't → go back and migrate it\n\nRe-read the list. `unhandled` reaching zero is the exit condition for this\nphase.\n\nPattern redirects require verified source-to-destination content mappings.\nA category/tag/year shape alone is not proof of equivalent destinations. Check\nexpanded artifact size and provider limits, actual slash/query variants and\nthat no rule hides a preserved Page. A 200 at the wrong content fails.\n\n## Phase 6 — Wire the hreflang cluster\n\nThis is the step that only exists because the family is multi-domain, and the\none most likely to be skipped. Each page declares its siblings on the other\ndomains; the renderer adds the page's own self-reference.\n\n```\nupdate_page site_id=<se-site> page_id=\"om-oss\" patch={ alternates: [\n  { hreflang: \"de\", href: \"https://example.de/ueber-uns\" },\n  { hreflang: \"en-GB\", href: \"https://example.co.uk/about-us\" },\n  { hreflang: \"x-default\", href: \"https://example.com/about-us\" }\n]}\n```\n\nRules the search engines actually enforce:\n- **Reciprocal.** Every page in a cluster must list every other one. Write\n  all N sides or the cluster is ignored. `batch_update_pages` is the sane way\n  to do this once you have the mapping table.\n- **One `x-default`** per cluster, pointing at the language selector or the\n  fallback market. Optional, but useful when the family doesn't cover a\n  visitor's language.\n- **Absolute URLs on the final domain** — not the `*.typeroll` fallback\n  subdomain. The cluster is what you want live after cutover, and a fallback\n  URL in there is a leak you'll be cleaning up for months.\n- Invalid entries are **rejected at write time** with the reason. If a write\n  fails, fix the tag/href — don't strip the field to make it pass.\n\nPages that have no equivalent on the other domains get no alternates at all.\nA cluster of one is meaningless markup.\n\n## Phase 7 — Verify BEFORE touching DNS\n\nDeploy each site (`trigger_deploy`), then check what it actually serves:\n\n```\nverify_migration_urls site_id=<de-site> source_origin=\"https://example.de\" check_source=true\n```\n\nThis requests every inventory URL against the site's fallback subdomain —\nthe real domain still points at the old host, which is exactly why the check\nis possible at all. Verdicts:\n\n| Verdict | Meaning | Action |\n|---|---|---|\n| `ok` | 200 at the same path | none |\n| `ok_redirect` | redirects to a 200 | none; flatten if `hops` > 1 |\n| `missing` | 404/410 | **the gap** — redirect it or migrate it |\n| `broken_redirect` | loop, or chain ending on an error | fix the rule |\n| `error` | 5xx / timeout | inconclusive, re-run |\n\n`check_source=true` also requests the OLD site, so a URL that already 404s\nupstream needs a reviewed retention/retirement decision, including traffic and\nbacklinks. Never automatically mark source 404s `excluded`.\n\nSlash-equivalent source URLs are one inventory decision but remain separate\nverification requests through `observed_paths`. Therefore `checked` can exceed\nthe normalized inventory size, and a missing slash variant remains a launch\nblocker. Redirect builds cover both source spellings and send internal targets\nto the site's configured trailing-slash style.\n\nNote what the check does NOT catch: it verifies that a URL *resolves*, not\nthat the page at the other end is the right content. Review content and SEO\nparity, then record the exact dataset and result with\n`record_migration_seo_acceptance`.\n\nIterate until `missing` and `broken_redirect` are both zero **on every site**.\nOnly after explicit cutover authorization, per site (`add_domain` prepares a\nnew canonical build and is not an inventory-only operation):\n\n1. `add_domain` with the intended apex/www canonical; leave `auto_deploy` on\n2. Wait for that canonical/sitemap deploy to succeed, then point DNS\n3. `poll_domain` until verified — there is no separate activation step\n4. Re-run `verify_migration_urls target_origin=\"https://example.de\"` against\n   the real domain, to confirm the cutover kept what the pre-check proved\n5. Submit the new sitemap in Search Console; keep the old property open for\n   a few weeks and watch the 404 report\n6. Rerun the complete, unfiltered URL check and SEO review, then require\n   `get_migration_launch_report` to return `launch_ready: true`\n\n## Definition of done (per site)\n\n- [ ] `get_migration_readiness source_url=<this market's old site>` → `ready: true`, warnings reviewed\n- [ ] `list_migration_urls status=\"unhandled\"` → 0\n- [ ] Complete `verify_migration_urls` → 0 `missing`, 0 `broken_redirect`, 0 `error`, 0 untested variants\n- [ ] `record_migration_seo_acceptance` is accepted for the latest deploy\n- [ ] `get_migration_launch_report` → `launch_ready: true`\n- [ ] hreflang cluster written on both/all sides, absolute, final domains\n- [ ] `language` set on the site; `<html lang>` correct in the deployed HTML\n- [ ] Internal links rewritten (no lingering absolute links to the old domain)\n- [ ] Market-specific business functions mapped; authorized synthetic interaction/delivery verified or explicitly UNVERIFIED\n- [ ] Media uploaded to this site's own library (no cross-site `cdn_url`), alt text in this market's language\n- [ ] If cutover is authorized: domain declared, canonical deploy succeeded, DNS verified; sitemap submitted. Otherwise report pre-cutover complete separately.\n\n## Pitfalls specific to this job\n\n- **Don't share one inventory across domains.** Inventory entries key on\n  path; two markets both have `/kontakt`. One site, one inventory.\n- **Don't build all N sites in parallel from scratch.** Build one, approve,\n  replicate. Parallel building multiplies every design mistake by N.\n- **Don't skip the parity check because coverage says 100%.** Coverage is a\n  claim about the data; parity is a measurement of the server. They disagree\n  exactly when it matters — an unpublished target page, a typo'd path, a\n  redirect chain.\n- **Don't point DNS site-by-site on a whim.** Cutting over one market at a\n  time is fine and usually wise, but the hreflang cluster spans markets: a\n  page pointing at a domain that still serves the old site is pointing at\n  content that doesn't match. Either cut over close together, or write the\n  cluster after the last market lands.\n\n## Storage prerequisite\n\nBefore reading or importing source content, call `get_import_readiness` (Core\n0.1.95 / MCP 0.44.68 or later). If `ready` is false, stop the import and show the\nreturned message and Publishing settings link. The organization must connect\nand verify its own storage first. Do not fall back to draft storage, hotlink\nsource images, or use ordinary page-write tools to bypass the import gate.\nUse `upload_media_from_url` for referenced source images; the customer’s\nCloudflare transfer Worker copies and verifies them directly in R2, independently\nof the GitHub/Cloudflare build-provider choice.\n",
-    "tr-migrate-wp": "---\nname: tr-migrate-wp\ndescription: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, preserves content and shared references in editable blocks, transfers media, sets redirects, leaves everything as drafts for human review.\n---\n\n# Migrate from WordPress to Typeroll\n\n**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.\nComplete its source baseline and one verified prototype per active template.\nRead target content to protect edits, not to justify accidental target defaults.\nIts shared evidence record is required for visual acceptance.\n\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks and partials) lands in an unsaved per-doc\n> DRAFT — deploys and plain previews only see SAVED content. For recipe-style\n> build work, pass `save: true` on write calls (the work is pre-approved by\n> the task itself), or run `commit_working_copy` per doc before any\n> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.\n\n\nThe platform's in-portal migration workflow is the \"managed\" path for\ncustomers who want one-click. This skill is the \"power-user\" path: you\ndo it locally, mix data sources freely, and the user reviews each step in their terminal.\n\n## Preconditions\n\n**Run the readiness check FIRST — before touching any content:**\n\n```\nget_migration_readiness source_url=\"https://oldsite.com\"\n```\n\nWhen the migration includes reusable page/item layouts, include each proposed\nblock composition and its content type fields in this same call. A\n`waiting_for_native_support` result means leave that template intact and do\nnot replace the gap with generic custom blocks, raw HTML, or corrective site\nCSS. Independent content and SEO work may continue. Rerun the review after the\nrequired Core version is deployed, then verify preview and a fresh hosted\nbuild.\n\nPass `source_url` — that adds the checks on the site you're migrating FROM.\nAn old host that answers 403/429 to server-side requests is a **blocker**: the\nimport would produce empty pages, or pages containing the host's block page,\nwhich reads as real content and is worse. Whether `/wp-json` answers is a\nwarning, since scraping is a real fallback (it just loses ACF/custom fields).\n\nIf `ready` is false, STOP and report the blockers to the user. Do not start\nthe import \"and fix it after\": every blocker is one whose failure is invisible\nonce the work is done, so discovering it late means redoing the expensive part.\n\n- **Media storage** — without it, every `<img>` keeps its WordPress URL. The\n  new site looks perfect and is still served images by the old host. It breaks\n  the day the customer cancels that hosting, months later, all at once.\n- **Hosting adapter** — without credentials, deploys return a job id and\n  publish nothing, while reporting success.\n\nWarnings are worth relaying but don't stop you: no verification origin (the\npre-cutover parity check can't run), forms without a\nnotification address, or a target site with no design to rebuild INTO.\n\nThen the ordinary preconditions:\n\n- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.\n- The source WP site has `/wp-json` reachable (Google for \"wordpress\n  REST API disabled\" if not — common for hardened hosts).\n- The target exists. Establish the source design baseline first, then prove\n  representative target templates using `tr-migration-evidence`. Preserve\n  appearance unless a redesign is explicitly requested.\n- If the target already has content, you must NOT clobber it — always\n  `list_pages` first and only write to slugs that don't already exist.\n\n## Recipe\n\n### 1. Probe and inventory\n\n```\nfetch <wp-url>/wp-json                           # confirm REST is on\nfetch <wp-url>/wp-sitemap.xml or /sitemap.xml    # URL inventory\n```\n\nBuild a list of every URL you intend to migrate. WP custom post types\nneed their REST endpoint (e.g. `/wp-json/wp/v2/news?per_page=100`),\nwalking `X-WP-TotalPages` to paginate.\n\n### 2. Measure the source and protect existing target work\n\n```\nget_site\nread_site_settings                               # colors, fonts, voice cues\nlist_partials                                    # header / footer / shared\nread_partial partial_id=\"header\"                 # nav structure\nlist_pages limit=5\nbatch_read_pages page_ids=[<2-3 representative ids>]   # see actual conventions\n```\n\nDon't skip this. Imposing a stranger's design on a customer's site is\nthe biggest avoidable mistake.\n\n### 3. Normalize shared data before importing page bodies\n\nRead taxonomy definitions and paginated terms from the helper's `/taxonomies`\nand `/terms/{taxonomy}` (Helper 0.3.2), or WordPress REST. Create a Content type\nfor each taxonomy and one Page per term. Preserve term IDs in a stable source\nmapping, archive URLs, parents and custom fields such as icons/emoji.\n\nAdd `page_ref_list` fields to article Content types. Store term Page IDs, never\ncopied category names, emojis, slugs or sort values on every article. Category\narchives can list articles using `core/repeater` with `source_type: backlinks`.\nUse an explicit primary category for breadcrumbs when available; do not guess\namong multiple categories. A table of contents is a derived template block,\nnot a `toc_html` field.\n\nCategory and tag Pages have editable block bodies. Scaffold the source term\ndescription plus a reverse-reference listing, leaving room for unique editorial\ncontent. Multiple tag/category references do not give a Page multiple parents:\npreserve its source page parent, or use an unambiguous primary category. Tags do\nnot set its parent. `parent` controls breadcrumb ancestry, not URL generation;\npreserve the source `path` even when it differs from the chosen hierarchy.\n\nThe managed importer preserves existing imported Pages on retry and refuses\nURL/identity conflicts or dangling term references. An older flattened import\nrequires a separately reviewed mapping repair; do not re-import over edits.\n\n### 4. Import one page at a time, draft status\n\nFor each source URL:\n\na. Fetch from WP. Prefer the helper plugin's authenticated endpoint\n   (`/wp-json/typeroll/v1/...`) if available — it bypasses\n   `show_in_rest=false` and returns ACF + builder fields. Otherwise\n   fall back to `/wp-json/wp/v2/<post-type>?slug=<slug>`.\n\nb. Clean the HTML. Strip Elementor / Gutenberg / Breakdance class\n   soup. Drop empty `<div>` and `<span>` wrappers. Keep semantic tags,\n   tables, iframes from known hosts (YouTube / Vimeo / Calendly).\n\nc. Migrate referenced images with `upload_media_from_url`. The customer's\n   transfer Worker copies and verifies them directly in R2. Use the returned\n   media reference only after verification. Stop and report a failed required\n   transfer; do not silently hotlink the WordPress source.\n\nd. Preserve exact text, headings, anchors, links, media and semantic structure with native blocks first. Read the\n   available block types and map headings, prose, images, buttons and layout\n   into their typed fields. Use HTML mode only for source-specific markup that\n   has no native representation and has passed the composition preflight.\n\ne. Write the page as a draft:\n\n   ```\n   create_page title=\"...\" slug=\"<last-path-segment>\"\n               path=\"/<preserved-wordpress/path/>\"\n               blocks=[<native block tree>]\n               status=\"draft\" kind=\"article\" author=\"...\"\n               seo_title=\"...\" seo_description=\"...\"\n   ```\n\n   **Preserve the source URL.** WP post URLs like\n   `/2024/01/foo-bar/` uses `slug: \"foo-bar\"` and\n   `path: \"/2024/01/foo-bar/\"`. Slug is one segment; `path` preserves the\n   complete nested URL.\n\n### 5. Redirects\n\nAfter migration, every URL the agent didn't preserve verbatim needs a\nredirect:\n\n```\ncreate_redirect from_path=\"/old-services\" to_path=\"/services\"\n```\n\nWalk the inventory; for each URL: did it become a page with the same\npath? If yes, no redirect. If renamed, `create_redirect`. If\nintentionally dropped, mark it `excluded` via `update_migration_url` (the\ncustomer should sign off on every dropped URL).\n\nUse a pattern only after verifying every affected source-to-destination mapping.\nFor an explicitly approved prefix change, `/old-blog/:slug` → `/articles/:slug`\ncan preserve intent if each destination contains the corresponding article.\nDo not blanket-redirect category/tag/author/feed/year families to a home or blog\npage. Date paths need actual route mappings; stripping a year is not enough.\nReview source 404s rather than automatically excluding them.\n\nRules:\n\n- **Trailing `*` only.** A mid-path splat (`/blog/*/comments`) is dropped\n  silently by Cloudflare — the platform refuses it at write time.\n- **`:splat`** carries the captured remainder; **`:name`** matches exactly one\n  segment and can be replayed by name.\n- **A pattern that would hide a live page is refused**, naming the pages. That\n  is the platform protecting you: redirects are applied before static files, so\n  `/blogg/*` would make every real article under `/blogg/` unreachable. Narrow\n  the prefix instead.\n- **Query-string URLs can't be matched.** WP's `/?p=123` has no path to key on;\n  these require an explicit query-routing solution on the future host or a\n  reviewed retirement decision. The old host cannot handle requests after its\n  hostname moves.\n- Rules are emitted most-specific-first, so a narrow rule always beats a broad\n  one — you can safely have `/blogg/recept/*` alongside `/blogg/*`.\n\nThen verify against reality before anything is cut over:\n\n```\nimport_sitemap url=\"https://old.example.com/sitemap.xml\"\n# Optional: direct Search Console query (platform service account must have property access)\nimport_gsc_performance property=\"https://old.example.com/\" months=6\n# Or paste a Search Console Pages CSV via csv=\"...\" and source_origin.\ncheck_internal_links         # database preflight before deploy\nverify_migration_urls        # after trigger_deploy; compact exceptions by default\nrecord_migration_seo_acceptance  # after reviewing this exact deployment\nget_migration_launch_report      # final fail-closed launch gate\n```\n\nThe inventory merges slash-equivalent URLs into one work item but preserves\ntheir source spellings in `observed_paths`. Verification requests every one of\nthose spellings; treat a failing variant as a real gap even when coverage is\notherwise complete. Fresh builds expand redirect sources to both slash forms.\n\nFor a site imported before Typeroll normalized WordPress plain-text fields,\naudit and repair the legacy records before visual review:\n\n```\nrepair_migration_plain_text  # dry_run=true by default; returns exact field diffs\n```\n\nThis operation is deliberately limited to `title`, `seo_title`,\n`seo_description`, and schema-defined plain-text `excerpt` fields. It cannot\ntouch bodies, HTML, slugs, paths, or URLs. Show all returned diffs and\nconflicts to the user. Only after explicit approval, repeat the same scope and\nselectors with `dry_run=false save=true`. If `truncated=true`, narrow the\nselection or raise `diff_limit` and review the omitted diffs first. Never work\naround a `working_copy` conflict: that resource contains another edit which\nmust be resolved separately.\n\n### 6. Preview + review with the user\n\n```\nget_preview_link page_id=<id>                    # one URL the user can click\n```\n\nCompare the source and target at desktop and mobile widths. Review representative\narticles, an archive and the home page. Measure heading sizes, readable width,\nspacing, TOC placement and image/card proportions. Scroll below the fold: verify\nheadings after media, the TOC below a sticky header, anchor landing positions\nand related articles inside the intended content column. In Core 0.2.7+, use\n`rhythm: \"article\"` on the Page content slot and `appearance: \"card\"` on Post\nCards for these native presentation choices; no per-page corrective CSS. Check breadcrumbs and shared\ncategory references; test forms/Extensions. HTTP 200 and text presence do not\nprove visual fidelity. Document intentional improvements such as responsive video.\n\nRecord `fidelity: { desktop, mobile, shared_data, integrations, evidence }` with\n`record_migration_seo_acceptance`, based on real checks of the exact deployment.\nThe launch report requires this evidence in Core 0.2.5.\nNever mark an unavailable integration or uninspected screenshot as accepted.\n\n### 7. Ship\n\nWhen the user signs off:\n\n```\n# Bulk-publish drafts that look right\nbatch_update_pages updates=[{page_id, patch:{status:\"published\"}}, ...]\n\n# Deploy\ntrigger_deploy\nget_deploy_status job_id=<id>    # poll\n```\n\n## Pitfalls\n\n- **Don't publish during migration.** Always import as `draft`. Even\n  if the agent is confident, the customer needs the chance to spot-check.\n- **WP slugs sometimes drift.** A post saved with slug `foo-bar` may\n  have been served at `/2024/01/foo-bar/` due to the permalink\n  structure. The full URL is what users see in Google; preserve that,\n  not the bare slug.\n- **Image bandwidth.** R2 upload is metered. Use `find_pages_matching`\n  contains=\"<old-domain>\" on already-imported content to spot images\n  that weren't transferred.\n- **WP-specific JSON-LD** (Yoast, Rank Math) is usually wrong after a\n  redesign because it references old URLs. Strip it; let Typeroll\n  emit fresh Article/Page schemas via `kind: 'article'` + `author`.\n\n## When the source isn't WordPress\n\nThe same shape applies for any source — Squarespace export, custom\nCMS, scraped HTML, CSV. Replace step 1's \"WP REST\" probe with whatever\ndiscovery the source supports, and the rest of the recipe is unchanged.\n\n## Storage prerequisite\n\nBefore reading or importing source content, call `get_import_readiness` (Core\n0.1.95 / MCP 0.44.68 or later). If `ready` is false, stop the import and show the\nreturned message and Publishing settings link. The organization must connect\nand verify its own storage first. Do not fall back to draft storage, hotlink\nsource images, or use ordinary page-write tools to bypass the import gate.\nUse `upload_media_from_url` for referenced source images; the customer’s\nCloudflare transfer Worker copies and verifies them directly in R2, independently\nof the GitHub/Cloudflare build-provider choice.\n\n### Raw-source media order (Core 0.2.35+)\n\nPass raw body HTML into conversion before any parse/serialize round trip with\nanother parser. Core applies browser tree construction before lazy-media cleanup.\nAn image-only H2 becomes an image at that position, not a semantic heading.\nCompare ordered headings/text/media/CTAs, including malformed wrappers, lazy and\nnoscript images and related-content boundaries. Existing Pages are not rewritten;\nrepair confirmed placement errors against raw source without reimporting edits.\n",
-    "tr-migration-evidence": "---\nname: tr-migration-evidence\ndescription: Source-first design baseline, native capability mapping and evidence gates required before bulk website migration or visual acceptance.\n---\n\n# Migration evidence contract\n\nUse this shared contract with WordPress, Astro, URL and multisite recipes.\nDefault to preserving the source appearance and behavior. A redesign requires\nexplicit scope. A partly migrated target is not the design reference.\n\n## Gate 1: source baseline, before conversion\n\nRecord the authoritative source URL/date, scope, relevant Core version, active\nPage templates and overrides. Inventory home, category/archive, long/short\narticles, downloads, empty related lists and each distinct business surface.\nCapture screenshots and computed geometry at matching actual `innerWidth`\nvalues (320/390/768/1024/1280/1536 where relevant, plus both sides of actual\nbreakpoints). Record loaded font families/weights, color panels, logo/header,\nhero, gutters, article/sidebar widths, card anatomy/grid and footer. Inspect\nloaded images, menus, scrolled TOC, anchor landings and long links.\nInventory semantic CTA anchors/buttons, downloads and affiliate links before\ncopying prose: retain decoded labels, href paths, query parameters, fragments,\n`target` and meaningful `rel` tokens. A source CSS class may identify a CTA\nwhose appearance would disappear when copied into prose.\n\nBefore removing builder wrappers/classes, preserve the information they carry:\nanchors, lazy/srcset/background images, captions, tables, ordering, downloads,\nembeds and interactions. Content modernization is a separate decision.\n\n## Gate 2: one verified prototype per active recipe, before bulk writes\n\nCall `list_block_types` and `read_block_type` on the deployed runtime. Map each\nsource component to exact fields/bindings, defaults, minimum version and expected\ngeometry. A registry entry does not prove the capability works. Save and read\nback each prototype, then inspect its preview and an authorized static build.\n\nExample: a 48px heading uses `core/heading.font_size_px: 48` on Core 0.2.25+;\nread the saved block back and measure computed `fontSize` at 1280px. Writing\n`font_size_px` to `core/prose`, which does not declare it, is an unsupported\nmapping even if an API preserves that unknown key. Stop with\n`waiting_for_native_support` when required capability is absent or ignored;\ndo not hide the gap with tenant CSS or generic custom blocks.\n\nValidate shared Page references, item order, missing images and empty/unpublished\nreferences. Keep semantics separate from presentation: category emoji belongs\nto its shared Page field, not copied into every article or card excerpt.\nValidate actual field types, not just key names: number fields use JSON numbers\n(`16`, `1.6`, `1`), not strings (`\"16\"`, `\"1.6\"`, `\"1\"`); booleans use `true`/\n`false`. Check responsive map values too. Read-back retention is not enough:\nmeasure the resulting font size, line height and paragraph spacing. If an\nincorrect type is accepted but ignored, fix the prototype before bulk writes.\n\nMap standalone CTAs to `core/button` when its declared fields preserve the\nsource behavior, rather than leaving class-dependent anchors in prose.\nCore 0.2.25+ `new_tab: true` emits `target=\"_blank\"` and\n`rel=\"noopener noreferrer\"` in static HTML; false/unset keeps the same tab.\nVerify the rendered target/rel, preserved affiliate queries/fragments, keyboard\nactivation, actual tab opening and narrow-screen wrapping without requiring\nJavaScript. Do not silently discard source `sponsored`/`nofollow`, download\nbehavior or other semantics unsupported by the chosen block: record the gap\nand use a supported composition or stop for native support.\nDo not apply a template to hundreds of Pages until its prototype passes.\n\n## Separate files, addresses and business behavior\n\nInventory both file bytes and every discovered historical asset URL, including\nPDF/download hrefs, image click targets, srcsets and backgrounds. Verify transfer\nand rendering separately from old-address preservation. Deduplicate by content\nidentity, not similar filenames. Preflight expanded redirect artifact bytes and\nprovider rule limits. A 200 at an unrelated destination is a failure. A source\n404 is not permission to discard a URL with traffic/backlinks: record a decision.\nQuery URLs need explicit routing support at the future host; keeping the old\nserver does not preserve them when the same hostname moves.\n\nClassify each CTA: contact form, owned lead workflow, affiliate link, partner\niframe/script or other runtime. Preserve market, language, destinations and\nattribution. Never clone recipients or partner IDs across markets. Test loading,\ninteraction and conversion separately; only use an authorized synthetic mode and\nsafe recipient. Unavailable delivery remains UNVERIFIED. No real leads or mail\nto third parties merely to fill a checklist.\n\n## Evidence record (repeat per recipe, viewport and state)\n\n- Source URL/date and target URL; Page/template IDs; exact publication ID.\n- Runtime/Core version and saved content/config revision.\n- Actual viewport `innerWidth` and height; scroll/menu/anchor state.\n- Source and target screenshot paths; measured expected and actual geometry.\n- Capability mapping: block type, field, read-back value and computed result.\n- Separate PASS / FAIL / UNVERIFIED for routing, content, visual, assets,\n  keyboard/interaction and delivery; reviewer and timestamp.\n- Visible deviation, specific user benefit, accepted scope and rationale.\n\nFilled examples:\n\n| Observation | Technical result | Visual decision |\n| --- | --- | --- |\n| Source video overflows a 390px viewport; native video fits and shows the entire frame | Width 390px, original aspect preserved; captures reviewed | PASS: deliberate improvement in mobile usability |\n| Source has four cards and turquoise hero at 1280px; target has three plain cards and no color panel | HTTP 200, no overflow, all content is blocks | FAIL: brand/layout lost; those technical facts cannot attest visual fidelity |\n| Heading round-trip retains 48 but computed size stays 32 | Save succeeds | FAIL: find ignored field/cascade before bulk conversion |\n\nKeep imported, saved, locally checked, hosted-preview checked, published and\ntraffic-cut-over distinct. Template/theme changes invalidate affected acceptance;\nnever attach old evidence to a new publication. `record_migration_seo_acceptance`\nbooleans are reviewer attestations, not automated visual proof. Do not set them\nfrom HTTP status, native-block count or overflow alone. Report a completed\npre-cutover scope honestly when DNS or integrations remain out of scope.\n\n## Complete census and visual signoff\n\nThe initial route census must combine source sitemaps, internal links, archive\npagination, CMS inventory and known utility routes. Include homepage, archives,\n404/search behavior and routes outside the sitemap where present. Do not invent\nfeatures absent from the source. Assign every route a recipe, template override,\ncomposition or documented exception. Inventory the whole shell: content outside\n`main`, header, footer, service navigation and archive heroes are not optional.\n\nDerive required evidence from that census. Pair every in-scope source/target route\nat mobile and desktop; add each unique component, breakpoint and interaction\nstate. Inspect page-specific media, lists, tables, embeds, CTAs, anchors and related\ncontent. One representative article cannot attest every article's content.\n\nA coverage row records route, recipe, component, state, actual viewport dimensions,\nsource revision, target content/config/Core/publication revision, paired screenshot\nreferences, reviewer, review time and result. All rows start `UNVERIFIED`.\nKeep independent results for content, links, list cardinality, full membership,\nsequence, appearance, keyboard behavior and delivery. Screenshots must be inspected;\nimage diffs and contact sheets assist review and do not prove aesthetics.\n\nFor menus capture source and target closed, open and scrolled states, nested groups\nif present, short landscape, focus order, Escape, link activation and breakpoint\ntransitions. For TOCs capture top/middle/bottom and anchor landings. Include tabs,\naccordions and empty/loading/error/success states where applicable. Separate mobile\nand desktop menu compositions require separate evidence; shared links may be reused\nbut one variant's screenshots do not attest the other.\n\nReport denominators separately: routes/content, paired visual pages, recipes,\ncomponents and states. Missing an archive, open menu, footer or a unique embed leaves\ncoverage incomplete even if all captured screenshots pass. Shared block, theme,\npartial or template changes invalidate every dependent row; content changes\ninvalidate that route and dependent listings. An old revision cannot approve a new\none. Source availability failures remain `UNVERIFIED`, not silently excluded.\n\nVisual signoff requires zero uncovered required surfaces and zero unexplained\nregressions. `FAIL` or `UNVERIFIED` blocks that signoff, even when a separately scoped\ntechnical publication has approval. An intentional deviation needs exact before/\nafter evidence, specific user benefit and accepted scope; “cleaner” is not a reason.\n\nExamples from a moving-services migration:\n\n| Surface | Passing evidence | Separate visual result |\n| --- | --- | --- |\n| Mobile menu | Keyboard focus and Escape work | FAIL: header moves, source service group is missing, open-menu composition differs |\n| Category archive | Every destination URL exists | FAIL: source sequence, card anatomy and columns differ |\n| Article body | All text imported | UNVERIFIED: unique embed and footer were never compared |\n\nDo not report “all design checked” from a viewport or recipe sample. Keep source\nlink-order comparisons and paired contact sheets with the report. The same contract\napplies to WordPress, URL, Astro and multisite migration; do not create separate,\nweaker checklists for individual import mechanisms.\n",
+    "tr-migrate-wp": "---\nname: tr-migrate-wp\ndescription: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, preserves content and shared references in editable blocks, transfers media, sets redirects, leaves everything as drafts for human review.\n---\n\n# Migrate from WordPress to Typeroll\n\n**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.\nComplete its source baseline and one verified prototype per active template.\nRead target content to protect edits, not to justify accidental target defaults.\nIts shared evidence record is required for visual acceptance.\n\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks and partials) lands in an unsaved per-doc\n> DRAFT — deploys and plain previews only see SAVED content. For recipe-style\n> build work, pass `save: true` on write calls (the work is pre-approved by\n> the task itself), or run `commit_working_copy` per doc before any\n> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.\n\n\nThe platform's in-portal migration workflow is the \"managed\" path for\ncustomers who want one-click. This skill is the \"power-user\" path: you\ndo it locally, mix data sources freely, and the user reviews each step in their terminal.\n\n## Preconditions\n\n**Run the readiness check FIRST — before touching any content:**\n\n```\nget_migration_readiness source_url=\"https://oldsite.com\"\n```\n\nWhen the migration includes reusable page/item layouts, include each proposed\nblock composition and its content type fields in this same call. A\n`waiting_for_native_support` result means leave that template intact and do\nnot replace the gap with generic custom blocks, raw HTML, or corrective site\nCSS. Independent content and SEO work may continue. Rerun the review after the\nrequired Core version is deployed, then verify preview and a fresh hosted\nbuild.\n\nPass `source_url` — that adds the checks on the site you're migrating FROM.\nAn old host that answers 403/429 to server-side requests is a **blocker**: the\nimport would produce empty pages, or pages containing the host's block page,\nwhich reads as real content and is worse. Whether `/wp-json` answers is a\nwarning, since scraping is a real fallback (it just loses ACF/custom fields).\n\nIf `ready` is false, STOP and report the blockers to the user. Do not start\nthe import \"and fix it after\": every blocker is one whose failure is invisible\nonce the work is done, so discovering it late means redoing the expensive part.\n\n- **Media storage** — without it, every `<img>` keeps its WordPress URL. The\n  new site looks perfect and is still served images by the old host. It breaks\n  the day the customer cancels that hosting, months later, all at once.\n- **Hosting adapter** — without credentials, deploys return a job id and\n  publish nothing, while reporting success.\n\nWarnings are worth relaying but don't stop you: no verification origin (the\npre-cutover parity check can't run), forms without a\nnotification address, or a target site with no design to rebuild INTO.\n\nThen the ordinary preconditions:\n\n- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.\n- The source WP site has `/wp-json` reachable (Google for \"wordpress\n  REST API disabled\" if not — common for hardened hosts).\n- The target exists. Establish the source design baseline first, then prove\n  representative target templates using `tr-migration-evidence`. Preserve\n  appearance unless a redesign is explicitly requested.\n- If the target already has content, you must NOT clobber it — always\n  `list_pages` first and only write to slugs that don't already exist.\n\n## Recipe\n\n### 1. Probe and inventory\n\n```\nfetch <wp-url>/wp-json                           # confirm REST is on\nfetch <wp-url>/wp-sitemap.xml or /sitemap.xml    # URL inventory\n```\n\nBuild a list of every URL you intend to migrate. WP custom post types\nneed their REST endpoint (e.g. `/wp-json/wp/v2/news?per_page=100`),\nwalking `X-WP-TotalPages` to paginate.\n\n### 2. Measure the source and protect existing target work\n\n```\nget_site\nread_site_settings                               # colors, fonts, voice cues\nlist_partials                                    # header / footer / shared\nread_partial partial_id=\"header\"                 # nav structure\nlist_pages limit=5\nbatch_read_pages page_ids=[<2-3 representative ids>]   # see actual conventions\n```\n\nDon't skip this. Imposing a stranger's design on a customer's site is\nthe biggest avoidable mistake.\n\n### 3. Normalize shared data before importing page bodies\n\nRead taxonomy definitions and paginated terms from the helper's `/taxonomies`\nand `/terms/{taxonomy}` (Helper 0.3.2), or WordPress REST. Create a Content type\nfor each taxonomy and one Page per term. Preserve term IDs in a stable source\nmapping, archive URLs, parents and custom fields such as icons/emoji.\n\nAdd `page_ref_list` fields to article Content types. Store term Page IDs, never\ncopied category names, emojis, slugs or sort values on every article. Category\narchives can list articles using `core/repeater` with `source_type: backlinks`.\nUse an explicit primary category for breadcrumbs when available; do not guess\namong multiple categories. A table of contents is a derived template block,\nnot a `toc_html` field.\n\nCategory and tag Pages have editable block bodies. Scaffold the source term\ndescription plus a reverse-reference listing, leaving room for unique editorial\ncontent. Multiple tag/category references do not give a Page multiple parents:\npreserve its source page parent, or use an unambiguous primary category. Tags do\nnot set its parent. `parent` controls breadcrumb ancestry, not URL generation;\npreserve the source `path` even when it differs from the chosen hierarchy.\n\nThe managed importer preserves existing imported Pages on retry and refuses\nURL/identity conflicts or dangling term references. An older flattened import\nrequires a separately reviewed mapping repair; do not re-import over edits.\n\n### 4. Import one page at a time, draft status\n\nFor each source URL:\n\na. Fetch from WP. Prefer the helper plugin's authenticated endpoint\n   (`/wp-json/typeroll/v1/...`) if available — it bypasses\n   `show_in_rest=false` and returns ACF + builder fields. Otherwise\n   fall back to `/wp-json/wp/v2/<post-type>?slug=<slug>`.\n\nb. Clean the HTML. Strip Elementor / Gutenberg / Breakdance class\n   soup. Drop empty `<div>` and `<span>` wrappers. Keep semantic tags,\n   tables, iframes from known hosts (YouTube / Vimeo / Calendly).\n\nc. Migrate referenced images with `upload_media_from_url`. The customer's\n   transfer Worker copies and verifies them directly in R2. Use the returned\n   media reference only after verification. Stop and report a failed required\n   transfer; do not silently hotlink the WordPress source.\n\nd. Preserve exact text, headings, anchors, links, media and semantic structure with native blocks first. Read the\n   available block types and map headings, prose, images, buttons and layout\n   into their typed fields. Use HTML mode only for source-specific markup that\n   has no native representation and has passed the composition preflight.\n\ne. Write the page as a draft:\n\n   ```\n   create_page title=\"...\" slug=\"<last-path-segment>\"\n               path=\"/<preserved-wordpress/path/>\"\n               blocks=[<native block tree>]\n               status=\"draft\" kind=\"article\" author=\"...\"\n               seo_title=\"...\" seo_description=\"...\"\n   ```\n\n   **Preserve the source URL.** WP post URLs like\n   `/2024/01/foo-bar/` uses `slug: \"foo-bar\"` and\n   `path: \"/2024/01/foo-bar/\"`. Slug is one segment; `path` preserves the\n   complete nested URL.\n\n### 5. Redirects\n\nAfter migration, every URL the agent didn't preserve verbatim needs a\nredirect:\n\n```\ncreate_redirect from_path=\"/old-services\" to_path=\"/services\"\n```\n\nWalk the inventory; for each URL: did it become a page with the same\npath? If yes, no redirect. If renamed, `create_redirect`. If\nintentionally dropped, mark it `excluded` via `update_migration_url` (the\ncustomer should sign off on every dropped URL).\n\nUse a pattern only after verifying every affected source-to-destination mapping.\nFor an explicitly approved prefix change, `/old-blog/:slug` → `/articles/:slug`\ncan preserve intent if each destination contains the corresponding article.\nDo not blanket-redirect category/tag/author/feed/year families to a home or blog\npage. Date paths need actual route mappings; stripping a year is not enough.\nReview source 404s rather than automatically excluding them.\n\nRules:\n\n- **Trailing `*` only.** A mid-path splat (`/blog/*/comments`) is dropped\n  silently by Cloudflare — the platform refuses it at write time.\n- **`:splat`** carries the captured remainder; **`:name`** matches exactly one\n  segment and can be replayed by name.\n- **A pattern that would hide a live page is refused**, naming the pages. That\n  is the platform protecting you: redirects are applied before static files, so\n  `/blogg/*` would make every real article under `/blogg/` unreachable. Narrow\n  the prefix instead.\n- **Query-string URLs can't be matched.** WP's `/?p=123` has no path to key on;\n  these require an explicit query-routing solution on the future host or a\n  reviewed retirement decision. The old host cannot handle requests after its\n  hostname moves.\n- Rules are emitted most-specific-first, so a narrow rule always beats a broad\n  one — you can safely have `/blogg/recept/*` alongside `/blogg/*`.\n\nThen verify against reality before anything is cut over:\n\n```\nimport_sitemap url=\"https://old.example.com/sitemap.xml\"\n# Optional: direct Search Console query (platform service account must have property access)\nimport_gsc_performance property=\"https://old.example.com/\" months=6\n# Or paste a Search Console Pages CSV via csv=\"...\" and source_origin.\ncheck_internal_links         # database preflight before deploy\nverify_migration_urls        # after trigger_deploy; compact exceptions by default\nrecord_migration_seo_acceptance  # after reviewing this exact deployment\nget_migration_launch_report      # final fail-closed launch gate\n```\n\nThe inventory merges slash-equivalent URLs into one work item but preserves\ntheir source spellings in `observed_paths`. Verification requests every one of\nthose spellings; treat a failing variant as a real gap even when coverage is\notherwise complete. Fresh builds expand redirect sources to both slash forms.\n\nFor a site imported before Typeroll normalized WordPress plain-text fields,\naudit and repair the legacy records before visual review:\n\n```\nrepair_migration_plain_text  # dry_run=true by default; returns exact field diffs\n```\n\nThis operation is deliberately limited to `title`, `seo_title`,\n`seo_description`, and schema-defined plain-text `excerpt` fields. It cannot\ntouch bodies, HTML, slugs, paths, or URLs. Show all returned diffs and\nconflicts to the user. Only after explicit approval, repeat the same scope and\nselectors with `dry_run=false save=true`. If `truncated=true`, narrow the\nselection or raise `diff_limit` and review the omitted diffs first. Never work\naround a `working_copy` conflict: that resource contains another edit which\nmust be resolved separately.\n\n### 6. Preview + review with the user\n\n```\nget_preview_link page_id=<id>                    # one URL the user can click\n```\n\nCompare the source and target at desktop and mobile widths. Review representative\narticles, an archive and the home page. Measure heading sizes, readable width,\nspacing, TOC placement and image/card proportions. Scroll below the fold: verify\nheadings after media, the TOC below a sticky header, anchor landing positions\nand related articles inside the intended content column. In Core 0.2.7+, use\n`rhythm: \"article\"` on the Page content slot and `appearance: \"card\"` on Post\nCards for these native presentation choices; no per-page corrective CSS. Check breadcrumbs and shared\ncategory references; test forms/Extensions. HTTP 200 and text presence do not\nprove visual fidelity. Document intentional improvements such as responsive video.\n\nRecord `fidelity: { desktop, mobile, shared_data, integrations, evidence }` with\n`record_migration_seo_acceptance`, based on real checks of the exact deployment.\nThe launch report requires this evidence in Core 0.2.5.\nNever mark an unavailable integration or uninspected screenshot as accepted.\n\n### 7. Ship\n\nWhen the user signs off:\n\n```\n# Bulk-publish drafts that look right\nbatch_update_pages updates=[{page_id, patch:{status:\"published\"}}, ...]\n\n# Deploy\ntrigger_deploy\nget_deploy_status job_id=<id>    # poll\n```\n\n## Pitfalls\n\n- **Don't publish during migration.** Always import as `draft`. Even\n  if the agent is confident, the customer needs the chance to spot-check.\n- **WP slugs sometimes drift.** A post saved with slug `foo-bar` may\n  have been served at `/2024/01/foo-bar/` due to the permalink\n  structure. The full URL is what users see in Google; preserve that,\n  not the bare slug.\n- **Image bandwidth.** R2 upload is metered. Use `find_pages_matching`\n  contains=\"<old-domain>\" on already-imported content to spot images\n  that weren't transferred.\n- **WP-specific JSON-LD** (Yoast, Rank Math) is usually wrong after a\n  redesign because it references old URLs. Strip it; let Typeroll\n  emit fresh Article/Page schemas via `kind: 'article'` + `author`.\n\n## When the source isn't WordPress\n\nThe same shape applies for any source — Squarespace export, custom\nCMS, scraped HTML, CSV. Replace step 1's \"WP REST\" probe with whatever\ndiscovery the source supports, and the rest of the recipe is unchanged.\n\n## Storage prerequisite\n\nBefore reading or importing source content, call `get_import_readiness` (Core\n0.1.95 / MCP 0.44.68 or later). If `ready` is false, stop the import and show the\nreturned message and Publishing settings link. The organization must connect\nand verify its own storage first. Do not fall back to draft storage, hotlink\nsource images, or use ordinary page-write tools to bypass the import gate.\nUse `upload_media_from_url` for referenced source images; the customer’s\nCloudflare transfer Worker copies and verifies them directly in R2, independently\nof the GitHub/Cloudflare build-provider choice.\n\n### Raw-source media order (Core 0.2.35+)\n\nPass raw body HTML into conversion before any parse/serialize round trip with\nanother parser. Core applies browser tree construction before lazy-media cleanup.\nAn image-only H2 becomes an image at that position, not a semantic heading.\nCompare ordered headings/text/media/CTAs, including malformed wrappers, lazy and\nnoscript images and related-content boundaries. Existing Pages are not rewritten;\nrepair confirmed placement errors against raw source without reimporting edits.\n\n\n## Navigation and empty-media variants\n\nInventory first-step input banners independently of final submission providers.\nPreserve their fields, required/minimum validation, service tabs and direct links,\nmobile collapsed/open states and navigation even when the final integration is\ndeferred. Core 0.2.40 provides native `core/navigation_form` and mixed `core/tabs`.\nRead their schema instead of rebuilding them in HTML or reintroducing a provider\nblock. Defaults are same-origin and tab-scoped; never place addresses in URLs or\nclaim cross-origin prefill. The receiving form must explicitly accept the fields.\n\nCompare listing rows with both real and missing images. Use shared post-card\nplaceholder settings for theme decoration, preserving real featured images and\nexplicit `show_image: false`. Compare actual footer link height plus gap, wrapping,\nfocus and column breakpoints; compact navigation density is an intentional option.\nVerify native preview and static output on the agreed viewport boundaries.\n",
+    "tr-migration-evidence": "---\nname: tr-migration-evidence\ndescription: Source-first design baseline, native capability mapping and evidence gates required before bulk website migration or visual acceptance.\n---\n\n# Migration evidence contract\n\nUse this shared contract with WordPress, Astro, URL and multisite recipes.\nDefault to preserving the source appearance and behavior. A redesign requires\nexplicit scope. A partly migrated target is not the design reference.\n\n## Gate 1: source baseline, before conversion\n\nRecord the authoritative source URL/date, scope, relevant Core version, active\nPage templates and overrides. Inventory home, category/archive, long/short\narticles, downloads, empty related lists and each distinct business surface.\nCapture screenshots and computed geometry at matching actual `innerWidth`\nvalues (320/390/768/1024/1280/1536 where relevant, plus both sides of actual\nbreakpoints). Record loaded font families/weights, color panels, logo/header,\nhero, gutters, article/sidebar widths, card anatomy/grid and footer. Inspect\nloaded images, menus, scrolled TOC, anchor landings and long links.\nInventory semantic CTA anchors/buttons, downloads and affiliate links before\ncopying prose: retain decoded labels, href paths, query parameters, fragments,\n`target` and meaningful `rel` tokens. A source CSS class may identify a CTA\nwhose appearance would disappear when copied into prose.\n\nBefore removing builder wrappers/classes, preserve the information they carry:\nanchors, lazy/srcset/background images, captions, tables, ordering, downloads,\nembeds and interactions. Content modernization is a separate decision.\n\n## Gate 2: one verified prototype per active recipe, before bulk writes\n\nCall `list_block_types` and `read_block_type` on the deployed runtime. Map each\nsource component to exact fields/bindings, defaults, minimum version and expected\ngeometry. A registry entry does not prove the capability works. Save and read\nback each prototype, then inspect its preview and an authorized static build.\n\nExample: a 48px heading uses `core/heading.font_size_px: 48` on Core 0.2.25+;\nread the saved block back and measure computed `fontSize` at 1280px. Writing\n`font_size_px` to `core/prose`, which does not declare it, is an unsupported\nmapping even if an API preserves that unknown key. Stop with\n`waiting_for_native_support` when required capability is absent or ignored;\ndo not hide the gap with tenant CSS or generic custom blocks.\n\nValidate shared Page references, item order, missing images and empty/unpublished\nreferences. Keep semantics separate from presentation: category emoji belongs\nto its shared Page field, not copied into every article or card excerpt.\nValidate actual field types, not just key names: number fields use JSON numbers\n(`16`, `1.6`, `1`), not strings (`\"16\"`, `\"1.6\"`, `\"1\"`); booleans use `true`/\n`false`. Check responsive map values too. Read-back retention is not enough:\nmeasure the resulting font size, line height and paragraph spacing. If an\nincorrect type is accepted but ignored, fix the prototype before bulk writes.\n\nMap standalone CTAs to `core/button` when its declared fields preserve the\nsource behavior, rather than leaving class-dependent anchors in prose.\nCore 0.2.25+ `new_tab: true` emits `target=\"_blank\"` and\n`rel=\"noopener noreferrer\"` in static HTML; false/unset keeps the same tab.\nVerify the rendered target/rel, preserved affiliate queries/fragments, keyboard\nactivation, actual tab opening and narrow-screen wrapping without requiring\nJavaScript. Do not silently discard source `sponsored`/`nofollow`, download\nbehavior or other semantics unsupported by the chosen block: record the gap\nand use a supported composition or stop for native support.\nDo not apply a template to hundreds of Pages until its prototype passes.\n\n## Separate files, addresses and business behavior\n\nInventory both file bytes and every discovered historical asset URL, including\nPDF/download hrefs, image click targets, srcsets and backgrounds. Verify transfer\nand rendering separately from old-address preservation. Deduplicate by content\nidentity, not similar filenames. Preflight expanded redirect artifact bytes and\nprovider rule limits. A 200 at an unrelated destination is a failure. A source\n404 is not permission to discard a URL with traffic/backlinks: record a decision.\nQuery URLs need explicit routing support at the future host; keeping the old\nserver does not preserve them when the same hostname moves.\n\nClassify each CTA: contact form, owned lead workflow, affiliate link, partner\niframe/script or other runtime. Preserve market, language, destinations and\nattribution. Never clone recipients or partner IDs across markets. Test loading,\ninteraction and conversion separately; only use an authorized synthetic mode and\nsafe recipient. Unavailable delivery remains UNVERIFIED. No real leads or mail\nto third parties merely to fill a checklist.\n\n## Evidence record (repeat per recipe, viewport and state)\n\n- Source URL/date and target URL; Page/template IDs; exact publication ID.\n- Runtime/Core version and saved content/config revision.\n- Actual viewport `innerWidth` and height; scroll/menu/anchor state.\n- Source and target screenshot paths; measured expected and actual geometry.\n- Capability mapping: block type, field, read-back value and computed result.\n- Separate PASS / FAIL / UNVERIFIED for routing, content, visual, assets,\n  keyboard/interaction and delivery; reviewer and timestamp.\n- Visible deviation, specific user benefit, accepted scope and rationale.\n\nFilled examples:\n\n| Observation | Technical result | Visual decision |\n| --- | --- | --- |\n| Source video overflows a 390px viewport; native video fits and shows the entire frame | Width 390px, original aspect preserved; captures reviewed | PASS: deliberate improvement in mobile usability |\n| Source has four cards and turquoise hero at 1280px; target has three plain cards and no color panel | HTTP 200, no overflow, all content is blocks | FAIL: brand/layout lost; those technical facts cannot attest visual fidelity |\n| Heading round-trip retains 48 but computed size stays 32 | Save succeeds | FAIL: find ignored field/cascade before bulk conversion |\n\nKeep imported, saved, locally checked, hosted-preview checked, published and\ntraffic-cut-over distinct. Template/theme changes invalidate affected acceptance;\nnever attach old evidence to a new publication. `record_migration_seo_acceptance`\nbooleans are reviewer attestations, not automated visual proof. Do not set them\nfrom HTTP status, native-block count or overflow alone. Report a completed\npre-cutover scope honestly when DNS or integrations remain out of scope.\n\n## Complete census and visual signoff\n\nThe initial route census must combine source sitemaps, internal links, archive\npagination, CMS inventory and known utility routes. Include homepage, archives,\n404/search behavior and routes outside the sitemap where present. Do not invent\nfeatures absent from the source. Assign every route a recipe, template override,\ncomposition or documented exception. Inventory the whole shell: content outside\n`main`, header, footer, service navigation and archive heroes are not optional.\n\nDerive required evidence from that census. Pair every in-scope source/target route\nat mobile and desktop; add each unique component, breakpoint and interaction\nstate. Inspect page-specific media, lists, tables, embeds, CTAs, anchors and related\ncontent. One representative article cannot attest every article's content.\n\nA coverage row records route, recipe, component, state, actual viewport dimensions,\nsource revision, target content/config/Core/publication revision, paired screenshot\nreferences, reviewer, review time and result. All rows start `UNVERIFIED`.\nKeep independent results for content, links, list cardinality, full membership,\nsequence, appearance, keyboard behavior and delivery. Screenshots must be inspected;\nimage diffs and contact sheets assist review and do not prove aesthetics.\n\nFor menus capture source and target closed, open and scrolled states, nested groups\nif present, short landscape, focus order, Escape, link activation and breakpoint\ntransitions. For TOCs capture top/middle/bottom and anchor landings. Include tabs,\naccordions and empty/loading/error/success states where applicable. Separate mobile\nand desktop menu compositions require separate evidence; shared links may be reused\nbut one variant's screenshots do not attest the other.\n\nReport denominators separately: routes/content, paired visual pages, recipes,\ncomponents and states. Missing an archive, open menu, footer or a unique embed leaves\ncoverage incomplete even if all captured screenshots pass. Shared block, theme,\npartial or template changes invalidate every dependent row; content changes\ninvalidate that route and dependent listings. An old revision cannot approve a new\none. Source availability failures remain `UNVERIFIED`, not silently excluded.\n\nVisual signoff requires zero uncovered required surfaces and zero unexplained\nregressions. `FAIL` or `UNVERIFIED` blocks that signoff, even when a separately scoped\ntechnical publication has approval. An intentional deviation needs exact before/\nafter evidence, specific user benefit and accepted scope; “cleaner” is not a reason.\n\nExamples from a moving-services migration:\n\n| Surface | Passing evidence | Separate visual result |\n| --- | --- | --- |\n| Mobile menu | Keyboard focus and Escape work | FAIL: header moves, source service group is missing, open-menu composition differs |\n| Category archive | Every destination URL exists | FAIL: source sequence, card anatomy and columns differ |\n| Article body | All text imported | UNVERIFIED: unique embed and footer were never compared |\n\nDo not report “all design checked” from a viewport or recipe sample. Keep source\nlink-order comparisons and paired contact sheets with the report. The same contract\napplies to WordPress, URL, Astro and multisite migration; do not create separate,\nweaker checklists for individual import mechanisms.\n\n\n## Navigation and empty-media variants\n\nInventory first-step input banners independently of final submission providers.\nPreserve their fields, required/minimum validation, service tabs and direct links,\nmobile collapsed/open states and navigation even when the final integration is\ndeferred. Core 0.2.40 provides native `core/navigation_form` and mixed `core/tabs`.\nRead their schema instead of rebuilding them in HTML or reintroducing a provider\nblock. Defaults are same-origin and tab-scoped; never place addresses in URLs or\nclaim cross-origin prefill. The receiving form must explicitly accept the fields.\n\nCompare listing rows with both real and missing images. Use shared post-card\nplaceholder settings for theme decoration, preserving real featured images and\nexplicit `show_image: false`. Compare actual footer link height plus gap, wrapping,\nfocus and column breakpoints; compact navigation density is an intentional option.\nVerify native preview and static output on the agreed viewport boundaries.\n",
     "tr-new-site": "---\nname: tr-new-site\ndescription: Use when the user wants to create a new Typeroll site from scratch, set up the initial design, or bootstrap a blank site with working header/footer, brand colors, and a homepage. Also triggers on \"start a new site\", \"set up a site for\", or \"build a website for [company]\".\n---\n\n# Bootstrap a new Typeroll site\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks and partials) lands in an unsaved per-doc\n> DRAFT — deploys and plain previews only see SAVED content. For recipe-style\n> build work, pass `save: true` on write calls (the work is pre-approved by\n> the task itself), or run `commit_working_copy` per doc before any\n> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.\n\n\nStart here when the site already exists as a database record (created via\nthe portal UI or API) but has no design, no header/footer, and no pages.\nThe goal is to go from blank to a working 4-page site with correct brand\nidentity in a single session.\n\n**Pages are built in block mode** — the platform default. Blocks give\nstructured, per-field editing, native full-bleed sections, responsive\nbreakpoints, and templates. HTML mode is the secondary path for\nhand-crafted one-offs and migrated content (section at the end).\n\n## Workspace and context\n\nAn optional agent-neutral workspace stores the brief, decisions and QA. It does\nnot create a Site or replace CMS content. See the public Agent workspace guide.\nFor compact MCP: search_tools, describe_tool, then the appropriate read/write/admin\nwrapper. Load only the relevant guide section and recipe. Discover site apps with\nread_app_documentation when needed; do not bundle private app guides locally.\n\nNo Site yet? Use hosted MCP with an Organization key and create_site, or create it\nin the portal. Read back its ID before editing. Use one explicit Site/Version for\nrelated operations. Larger changes to an existing site should use a branch.\n\nBefore importing content or a media library, require get_import_readiness to pass.\nPublishing accounts may remain unconfigured while authoring new drafts and previews.\n\n## Preconditions\n\n- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.\n- The site exists (confirm with `get_site`).\n- You have the customer brief: company name, industry, 2–3 key brand colors,\n  tone of voice, and a list of initial pages.\n\n## Recipe\n\n### 1. Audit current state\n\n```\nget_site\nget_site_capabilities   # template_capabilities_version — what this deployment supports\nread_site_settings      # see what (if anything) is already configured\nlist_pages              # don't overwrite pages that already exist\nlist_partials           # check if header/footer already have content\nlist_block_types        # the per-site block palette — NEVER assume, always list\n```\n\n**Do not choose a content mode or file a platform gap before these calls\nreturn.** For every required visual/behavioral element, map it to an existing\nblock or composition first. If the summary suggests a match, use\n`read_block_type` to inspect the exact schema. Only call something “missing”\nafter checking capabilities, the complete palette, and custom block types.\n\nCommon requirements that are easy to misclassify:\n\n| Requirement | Existing Typeroll primitive |\n|---|---|\n| Full-bleed hero flush below the header | `core/section` + `core/hero`; block-mode sections already own the full width and have no page-shell padding |\n| Responsive icon/card grid | `core/grid` + `core/icon_box`, or `core/feature_grid`; set responsive fields with `set_block_responsive` |\n| Custom cards backed by Pages | `core/repeater` / `core/page_list` with a site-authored `item_compatible` block type as `item_block` |\n| Grouped Page listing | `core/repeater` with `group_by`; array-valued fields place an item in every matching group |\n| Breadcrumbs in a page template | `template/page_breadcrumbs`; page and item routes supply a server-rendered trail |\n| Shared article typography | Set `font_size`, `line_height` and `paragraph_spacing` on `template_content_slot`; blank values retain block defaults (Core 0.2.2+) |\n| Generated heading index | `core/table_of_contents`; choose heading levels; links always come from the current Page headings |\n| Previous/next Page links | `template/page_navigation`; defaults to content type sort order and can bind explicit neighbor fields |\n| Download CTA that disappears without a file | `template/show_if` around a context-bound `core/button`; a dedicated download block is only editor convenience |\n| Sticky/custom header and multi-column footer | Block-mode header/footer partials plus layout blocks, or one reusable custom block type |\n| Cookie notice | `settings.cookie_consent`, not a page block |\n| Consent copy owned by an installed Extension | `list_extension_installations` → `read_extension_installation` → `update_extension_installation_config`, using exact manifest schema keys; the update queues a production deploy by default |\n| One-off HTML + JavaScript embed | `core/embed`; reusable widgets use a custom block type with `script` |\n| CTA/button variants | `core/cta` and `core/button`, styled from site tokens or a narrowly scoped class |\n| Two-column image/text | `core/media_card`, `core/feature_row`, or `core/columns` |\n| Figures, captions and tables | `core/prose` / richtext; the sanitizer preserves these semantic tags |\n| Full-width block page without a content shell | Native block mode; top-level `core/section` is unconstrained |\n| Brand colors and typography | Site `colors`/`fonts` tokens consumed by core blocks |\n\nReal gaps should say what was checked and why the nearest primitive is not\nenough. “I did not see a dedicated block name” is not evidence by itself.\n\n### 2. Brand + settings\n\nOne `update_site_settings` call with every field you know:\n\n```json\n{\n  \"site_name\": \"Acme Studio\",\n  \"tagline\": \"Short, punchy tagline\",\n  \"language\": \"sv\",\n  \"trailing_slash\": \"always\",\n  \"colors\": {\n    \"primary\":    \"#1a1a2e\",\n    \"secondary\":  \"#16213e\",\n    \"accent\":     \"#e94560\",\n    \"background\": \"#f5f5f5\",\n    \"surface\":    \"#ffffff\",\n    \"text\":       \"#1a1a2e\",\n    \"text_light\": \"#6b7280\"\n  },\n  \"fonts\": { \"heading\": \"Playfair Display\", \"body\": \"Inter\", \"size_base\": 16 },\n  \"contact\": { \"email\": \"hej@acme.se\", \"phone\": \"+46 8 123 456\" },\n  \"social\": { \"instagram\": \"https://instagram.com/acme\" }\n}\n```\n\nRead it back with `read_site_settings`. Google Fonts names are\ncase-sensitive display names (\"Plus Jakarta Sans\", not \"plus jakarta\").\n\n**Site icons are part of brand setup** — upload favicon (32–64px), a\n180×180 apple touch icon, and a 192×192 app icon; set `favicon`,\n`apple_touch_icon`, and `icon_192`. No icon assets? Derive a proposal (see\n`tr-brand`). Also set `settings.logo` to the uploaded brand mark — it feeds\nOG/schema even if the header uses a different lockup.\n\nSet `iframe_allowed_hosts` when customer content embeds a provider outside\nthe built-in YouTube/Vimeo/Google Maps/Calendly set. Values are exact domain\nhostnames, never URLs or wildcards. Read the setting back before deciding that\nan iframe cannot be represented.\n\n### 3. Header + footer partials\n\n**Start from the native preset — don't hand-roll navigation.** Read\n`tr-header-footer` and use its `template/site_logo` + `core/navigation`\ncomposition. The server-rendered landmark, current-page state, no-JS links,\nmobile disclosure, focus treatment, and responsive behavior are Core\ncontracts rather than tenant CSS/JavaScript.\n\nStage the complete tree with `update_partial partial_id=\"header\"\npatch={blocks:[...]} save=true`, then call `set_partial_mode partial_id=\"header\"\nto=\"blocks\"`. Repeat for the footer and read both partials back. The inactive\nHTML representation is retained for rollback; changing `content_mode` through\nordinary PATCH/PUT is rejected intentionally.\n\nUse HTML mode only when preserving legacy authored markup that cannot yet be\nrepresented natively. Partials receive the same `{{site.*}}` render context as\npage blocks. Keep the first section and header backgrounds intentional; do not\nadd a decorative border merely to compensate for mismatched spacing.\n\n### 4. Homepage — block tree\n\n`create_page` with the whole tree in one call. Omit block `id`s — the\nplatform assigns them (`blk_…`); you read them back for later\n`update_block` calls.\n\n```\ncreate_page title=\"Start\" slug=\"\" status=\"draft\" content_mode=\"blocks\" blocks=[...]\n```\n\nA proven landing-page skeleton (every top-level block is a `core/section`\n— sections are **natively full-bleed**: the background runs edge-to-edge,\ncontent is constrained by the section's own inner container via the\n`width` field. NEVER use 100vw negative-margin hacks. Anchor ids and\ncustom classes via `style_overrides` are safe on sections from\ntemplate_capabilities_version ≥ 0.15.3; on 0.14.x–0.15.2 they wrap the\nsection in a div and silently break full-bleed — there, put the anchor\non a block *inside* the section instead):\n\n```json\n[\n  { \"type\": \"core/section\", \"data\": { \"background\": \"#ffffff\", \"padding_y\": \"lg\" }, \"children\": [\n    { \"type\": \"core/media_card\", \"data\": {\n        \"image\": \"MEDIA_URL\", \"image_alt\": \"…\", \"image_side\": \"right\",\n        \"heading\": \"Huvudrubriken\", \"heading_level\": \"h2\",\n        \"text\": \"<p>Ingress …</p>\",\n        \"button_label\": \"Kontakta oss\", \"button_url\": \"/#kontakt\"\n    } }\n  ] },\n  { \"type\": \"core/section\", \"data\": { \"padding_y\": \"lg\" }, \"children\": [\n    { \"type\": \"core/heading\", \"data\": { \"text\": \"Så funkar det\", \"level\": \"h2\", \"align\": \"center\" } },\n    { \"type\": \"core/grid\", \"data\": { \"cols\": { \"mobile\": 1, \"tablet\": 2, \"desktop\": 3 }, \"gap\": \"lg\" }, \"children\": [\n      { \"type\": \"core/step_card\", \"data\": { \"number\": \"1\", \"title\": \"…\", \"text\": \"<p>…</p>\" } },\n      { \"type\": \"core/step_card\", \"data\": { \"number\": \"2\", \"title\": \"…\", \"text\": \"<p>…</p>\" } },\n      { \"type\": \"core/step_card\", \"data\": { \"number\": \"3\", \"title\": \"…\", \"text\": \"<p>…</p>\" } }\n    ] }\n  ] },\n  { \"type\": \"core/cta\", \"data\": {\n      \"heading\": \"Redo att börja?\",\n      \"primary_label\": \"Kontakta oss\", \"primary_url\": \"/kontakt\"\n  } }\n]\n```\n\nBlock-palette guidance (verify against `list_block_types` — the source of\ntruth):\n\n- **Hero:** `core/media_card` inside a white section (image beside copy),\n  or `core/hero` (eyebrow/heading/subheading + `primary_*`/`secondary_*`\n  buttons — rendered server-side; `layout: split-right` puts the image\n  beside the text). For a plain text hero: section + heading + prose +\n  button.\n- **Alternating image+text rows (\"zig-zag\" feature/step lists):**\n  `core/feature_row` (template_capabilities_version ≥ 0.29.0) — balanced\n  halves that hug the center gutter so wide screens never open dead air,\n  natural-aspect image, `image_side: left|right` per row, mobile stack\n  order as a field. Prefer it over hand-building `core/columns` with an\n  unbalanced ratio + width-capped text (the classic dead-air trap). Use\n  `core/media_card` instead when you want a *boxed card* with a\n  filled/cropped image.\n- **`core/heading`** decouples `level` (h1–h6, semantics) from `size`\n  (visual) — exactly one `level: h1` per page.\n- **Images:** `core/image` with an uploaded media URL. The build pipeline\n  emits responsive output from prepared media. Upload through a signed direct\n  grant, finalize it, and use returned IDs/URLs. Follow media preparation status;\n  do not routinely regenerate unchanged images or use legacy maintenance tools. Use the\n  `radius` field for rounded corners.\n- **Repeaters/listings:** `core/page_list`, `gallery`,\n  `feature_grid` etc. — alias blocks over `core/repeater`. Use these for\n  Pages of a content type instead of hand-writing listing markup. The base\n  repeater also supports `group_by`, group ordering/headings, multi-valued\n  membership, filters, custom `item_block`, and `item_overrides`.\n- **Long-form navigation:** `core/table_of_contents` builds an anchor list\n  from page headings. Page templates use\n  `template/page_navigation` for deterministic previous/next links.\n- **Forms:** `create_form`, then place `core/form` with its `form_id`.\n  HTML-mode pages use `<x-form id=\"…\" />`; both paths render the same signed\n  shell and runtime. See `tr-forms`.\n- **`core/html`** is the escape hatch for the genuinely unique thing —\n  not a default. If you reach for it more than once or twice per page,\n  note why (that's block-library feedback).\n\nSlot containers (`core/columns`, `core/tabs`): populate them either by\npassing the whole tree inline (`block={ type: 'core/columns', slots:\n[[…],[…]] }`) or incrementally with `add_block parent_id=<columns-id>\nslot_index=0|1`. Requires template_capabilities_version ≥ 0.15.2 — on\nolder sites use `core/grid` (children flow into columns) instead.\n\nPartial last rows (template_capabilities_version ≥ 0.16.5): when N equal\ncards don't divide by the grid's column count (5 cards, 3 cols), set\n`last_row: 'center'` on the `core/grid` — the orphan row auto-centers.\nNEVER invent a \"wide\" variant of one peer card to fill the hole, and\ndon't hand-roll 6-column CSS tricks; both distort content to patch\nlayout. On older sites, pick a column count that divides N.\n\nIcons (template_capabilities_version ≥ 0.16.0): `type: 'icon'` fields on\n`core/icon`, `core/icon_box`, and `core/step_card` render inline SVG when\nthe value is a name from `get_site_capabilities → core_icon_names` (a\ncurated Lucide subset — `check`, `star`, `shield-check`, `mail`,\n`arrow-right`, `truck`, `chart-line`, …). Any other value (emoji, plain\ntext) renders as text, so emoji stand-ins keep working. Icons inherit\nsize from font-size and color from `currentColor`/the block's color\nfield. On older sites icons don't render — use emoji or CSS markers.\n\nEditor schemas (template_capabilities_version ≥ 0.39.0): labelled enum\noptions, newline-edited string lists, nested object/repeating-array fields,\nand internal-page pickers for URL fields are first-class. Do not flatten an\nExtension's `props_schema` merely to make it editable.\n\nFor an Extension placed in an HTML header or footer, require\n`supports_extension_html_partial_directive: true`. The broader\n`supports_extension_html_directive` flag covers HTML page bodies and is not\nproof that an older static build expands partial directives.\n\nFor a cross-page Extension flow, require both\n`supports_extension_site_navigation` and `supports_extension_storage`. Use\n`context.site.navigate(\"/path/\")` and installation-scoped\n`context.storage.session` rather than direct root-path navigation, Web Storage,\nor personal data in query parameters. This keeps navigation inside the current\npreview and preserves state without exposing it through URLs or referrers.\n\nKnown limitations (honest list — don't fight them):\n\n- **`core/tabs` label icons don't render** (the tab strip is built\n  client-side without the icon pipeline). Text labels only.\n\nTheming: block primitives render neutral. Brand color/typography comes\nfrom settings (step 2). For page-specific polish (e.g. a colored card\ntreatment), a single `core/html` block with a small `<style>` scoped to\n`[data-bid]`/section selectors is acceptable — keep it minimal and note\nit in your log.\n\n### 5. Inner pages\n\nSame pattern: `create_page` with `content_mode: \"blocks\"` and a section\ntree. Standard set: Om oss, Tjänster, Kontakt — or what the brief says.\nDefault new pages to `status: \"draft\"`; publish after review.\n\n### 5b. If the legacy site is still live, scrape canonical content\n\nFor pages with canonical text (privacy policy, terms, about), `WebFetch`\nthe live page and carry the text verbatim — don't rewrite legal copy\nfrom memory. Convert to prose blocks (or one `core/html` for complex\nlegacy markup).\n\n### 6. Preview + iterate\n\n```\nget_preview_link                  # signed URL for browser review\nget_page_preview page_id=\"home\"   # rendered HTML for structural checks\n```\n\n**Self-review the visuals before you call it done — appearance AND\nreadability, not just structure.** Screenshot the deployed/preview site at\ndesktop (~1440px) and mobile (~390px) and look: logo FULLY VISIBLE (not clipped by\na header's overflow:hidden) + legible + brand-compliant against its actual\nbackground — screenshot the header IN CONTEXT, not the logo element in isolation\n(an element shot hides layout clipping); a light wordmark must not sit bare on a\nlight surface. Text contrast everywhere, no horizontal scroll or mid-word\nbreaks, every image rendered, mobile layout actually collapsed. \"No overflow +\ncopy present\" is not a design review — never report a build as done/perfect off\nstructural metrics alone.\n\nShare the preview link. Iterate on feedback with `update_block` /\n`add_block` / `move_block` — that's the point of block mode: surgical\nedits, not full-page rewrites.\n\n### 7. Deploy\n\nWhen the user approves, verify read_publishing_readiness and save the intended\nVersion before deploying. A published CMS status is not a live deployment.\n```\ntrigger_deploy\nget_deploy_status job_id=<id>\n```\n\n## Secondary path: HTML mode\n\nFor migrated legacy pages or a hand-crafted one-off, `content_mode:\n\"html\"` still works. Rules that apply there (and only there):\n\n- Wrap the body in a page-scope `<article class=\"my-page\">` and prefix\n  selectors with it — the `.page-content` shell sets width/padding at\n  normal specificity.\n- HTML-mode bodies are container-constrained; full-bleed requires the\n  negative-margin escape (`margin-left: calc(50% - 50vw); width: 100vw`)\n  — never combine with `overflow-x: clip` on a wrapper.\n- `set_page_mode` flips a page between modes;\n  `convert_page_to_blocks` does a heuristic HTML→blocks conversion.\n\n## Pitfalls\n\n- **Don't create pages that already exist** — `list_pages` first; use\n  `update_page` if the slug is taken.\n- **`update_page` takes a `patch` object**, not flat fields.\n- **Don't hardcode block field names from memory** — schemas are\n  per-site (`list_block_types`/`read_block_type`).\n- **One `level: h1` per page** (core/heading) — SEO + screen readers.\n- **Don't simplify data during import** — preserve Swedish characters in\n  labels (`affärsutveckling`, not the ASCII-folded slug), keep titles\n  verbatim; slugs are derived for URLs only.\n- **Minimal JS.** Inline `<script>` in page content is stripped by the\n  sanitizer. One-off interactivity uses `core/embed`; reusable interactivity\n  uses a block-type `script`; site-wide code belongs in `scripts_body_end`.\n",
     "tr-page-template": "---\nname: tr-page-template\ndescription: Create or edit a reusable Page template for articles, checklists, products, directory entries or other Pages that share a layout.\n---\n\n# Share a layout across Pages\n\nRead capabilities, available block types, content types and Page templates first.\nUse a site version for substantial design changes. The Page owns its body blocks;\nthe template owns the shared layout around that body. The content type selects a\ndefault template, and an individual Page can override it.\n\n1. `create_page_template name=\"article-layout\" label=\"Article\" starter=\"article\" status=\"published\"`.\n   Alternatively supply `blocks` instead of `starter`. Presets include article,\n   blog, checklist, team, events, products, profile, landing and custom.\n2. `update_content_type name=\"articles\" patch={template:\"article-layout\"}`.\n   For a single-page override, `update_page page_id=... patch={template:\"article-layout\"} save=true`.\n3. Read and edit the template through `read_page_template` or block tools with\n   `target: { kind: \"template\", id: \"article-layout\" }`. Template edits save\n   immediately; content-type and template changes are isolated by `version`.\n4. Keep a `template_content_slot` where the Page's body belongs. Its `max_width`\n   can be full, narrow, normal or wide. Use native columns/containers for layout.\n5. Metadata blocks include `template/page_title`, `template/page_date`,\n   `template/page_featured_image`, `template/page_breadcrumbs` and\n   `template/page_navigation`. The outline block reads the rendered body headings.\n6. Use `{{page.title}}` or `{{page.custom_field}}` in template bindings.\n   A repeater's children use `{{item.title}}` for the current listed Page.\n   Custom fields can be typed objects, arrays or Page references; preserve those\n   structures instead of storing hand-generated list HTML.\n7. Preview several Pages using the template: long title, short body, missing\n   optional image, populated reference list. Inspect desktop and mobile output.\n   Verify the authorized static build as well as the live database preview.\n\nPrefer native image, table, list, heading and content blocks. A rare specialized\nwidget can use a reviewed HTML/embed block. Reusable custom behavior belongs in\none custom block type rather than repeated HTML bodies. Existing HTML-mode pages\nmay share fragments through partials and `<x-include>`, but use block templates\nfor new content families.\n\nHeader/footer partials are global and remain separate from content types. Keep\nsite-level design tokens in settings and shared layout changes in the template.\nPage body edits stay specific to that Page. Read the template before mutation;\nnever replace it with a starter merely because an import is being retried.\n\n\nContent types also own `sort_field`/`sort_dir` and optional `allowed_templates`.\nTypes define content; templates define presentation. Multiple compatible Page\ntemplates can be allowed, with `template` selecting the default. Null/absent\n`allowed_templates` is unrestricted, `[]` allows none, and a configured default\nmust be in an explicit allowed list. Page overrides must be allowed; null/empty\n`Page.template` restores inheritance. Page template changes use Save/Discard.\n\nListings inherit type sorting unless explicitly overridden. `Page.sort_order`\nis the manual numeric order; null clears it. Missing sort values come last and\nIDs break ties. Explicit ID lists keep their order. Typed `list_pages` queries\ninherit type sorting and accept `sort_by`/`sort_order`; unfiltered API lists\ndefault to stable IDs. See the public Content types guide for editor steps.\n\n## Structured fields without empty labels\n\nCheck `supports_page_field_list` before adding `core/field_list`. Configure\n`data.fields` as `{ field, label? }` rows, optional `title` and `layout`\n(`stack` or `two-column`). It omits empty rows and an entirely empty section,\nrespects `rendered: false`, uses select display labels and links Page references.\nZero is displayed. From Core 0.2.14, boolean rows hide false/unset by default; set `boolean_display: \"yes-no\"` to show both set values with `true_label` / `false_label` (defaults Yes/No). Stored false remains real data. Optional row `html` has only `{{label}}` and\n`{{value}}` slots; row `css` contains declarations, and `css_class` supports\nshared selectors. Values stay in Page.fields; never duplicate them into rich text.\nRead the current block schema and content type, and verify preview before publishing.\n\nFor checkbox lists, `item_html` decorates each selected option with the same\nlabel/value slots (for example a check icon). `item_links: [{ value, url }]`\nlinks only chosen stored options to listing URLs, retaining their schema labels.\nStyle list items via the row css_class and normal block Custom CSS.\n\n## Heading and field-list defaults (Core 0.2.13)\n\nA template H1 owns the Page title. Do not send body `core/heading` blocks with\n`level: \"h1\"` when the selected/default template supplies one. Use H2. Creation,\nPage writes and Save reject duplicates with a corrective error. Existing duplicate\nheadings render as H2 without mutating storage. A Page without a template H1 can\nkeep one body H1. The layout itself does not inject an additional title.\n`core/field_list` defaults to a 0.7rem row gap, weight-600 labels and values that\nwrap long URLs. Empty rows and entirely empty groups stay hidden.\n\n### Native precision (Core 0.2.25 candidate)\n\nRead current block schemas before relying on new controls. Heading/Page title\nsupport responsive `font_size_px`, unitless `line_height` and `color`. Sections\nseparate full-width background from `max_width_px`, `padding_x` and\n`content_gap_px`; Containers add `max_width_px`, `gap_px`, `padding_x_px` and\n`padding_y_px`. Two columns add `gap_px` and `right_width_px`. Use numeric values\nor `{mobile, tablet, laptop, desktop, wide}` overrides, not CSS strings.\nBreadcrumbs have `padding_before_px`, `padding_after_px`, `divider`; TOC has\n`padding_px`, `radius_px`, `border`, `shadow`, `link_color: neutral` and\n`list_style: chevron`. Keep TOC generated from headings. Icon box adds native\ncard dimensions and `whole_card_link`; map real Page URLs rather than freezing\ncustomer routes in HTML. Site logo accepts `height_px`. The `system` font family\nuses the device stack without a webfont request. Preserve complete images and\nvalidate actual mobile/desktop output, including scrolled outlines.\n\nColumns `stack_below` accepts the select strings `\"721\"` (default), `\"768\"`,\n`\"1024\"`, `\"1280\"`. A direct-slot TOC follows the selected stacked boundary: its\n`mobile_display: \"hidden\"` releases the otherwise empty slot; `\"visible\"` keeps\nit in flow. Use `\"1024\"` for full article width below laptop when justified by\nthe source comparison. Do not merely hide the TOC with `hidden_on` while leaving\na reserved two-column track, or duplicate body content for tablet/desktop.\n\nFor a sticky site header, use an outer semantic Container (`tag: \"header\"`,\n`sticky: true`, optional responsive `sticky_top_px`, 0–240) outside main. Keep\nits background opaque and its containing block tall enough; do not create a\nshort header wrapper or clip it with ancestor overflow. Sticky is opt-in.\nContainer `padding_top_px`/`padding_bottom_px` override `padding_y_px` per side\nand accept responsive maps. Grid/Repeater and repeater aliases expose responsive\n`gap_px` (0–240). Use these fields for exact source spacing rather than empty\nspacers or corrective CSS. TOC active-section feedback includes document scroll\npadding; remove obsolete duplicated tenant header offsets during migration.\n\n\n## Qualified composition starters (Core 0.2.32 / MCP 0.45.26 and later)\n\nCheck `supports_composition_starters` and `supports_default_presentation_contract`.\nUse `get_composition_starter` to read one editable `header`, `footer`, `archive`\nor Page-template starter without changing CMS data. An archive also requires\n`content_type`; optional `title` names its heading. Replace sample navigation,\nmap the Profile's empty field_list to real public fields, and save through the\nnormal version-aware tools. `create_page_template` accepts the same Page starter\nnames as Templates → New template. Starters are copies, never live links that\nreplace an existing design after an upgrade.\n\nSections own background/gutters, Containers default to no padding, and article\nflow owns heading rhythm. Inspect Appearance before Advanced settings. Reset\nrestores block defaults; don't mirror styles into canonical fields. Formatted\nheadings have typed responsive typography. Container `overflow: \"clip\"` and\nmenu `panel_padding: \"none\"` are deliberate opt-ins. Default PDF text links are\nunderlined theme links. Missing template image/date/excerpt/author emits no node.\n\nFor an existing Container whose padding was omitted, review the new zero-padding\noutput; explicitly set the former `md` values if they should remain (horizontal\n2rem, vertical 4rem). Never bulk-replace existing templates. Read\nhttps://typeroll.com/docs/tools/blocks/ for the full default/migration contract.\n\n\n## Native surface controls (Core 0.2.33 / MCP 0.45.27)\n\nCheck `supports_surface_feedback_and_gradients`. Section/Container\n`background_gradient: { from: \"#f8fbff\", to: \"#e8f4fc\", angle: 135 }` adds\nan opt-in two-stop gradient; remove the object to return to the solid/image\nbackground. Use real colors or simple theme variables, never CSS declarations.\nPost Card `hover_background`, `hover_border_color`, `hover_color` and outlined\nPDF `download_hover_background`/`download_hover_color` control pointer, pressed\nand keyboard feedback. Repeater/page_list item_overrides use the same schema.\nKeep focus visible and check contrasting color pairs; don't move the card.\nNavigation Links `density: \"compact-desktop\"` gives footer links a 24px minimum\non desktop with fine pointers; mobile/touch retains 44px. For dense taxonomy\nfooters use `direction: \"column\"`, `font_size_px: 14.4`, `line_height: 1.1`,\n`gap_px: 4` and `padding_y_px: 0`. Primary menus keep comfortable defaults. Verify both narrow and\nwide views and publish the intended version after saving; no automatic migration.\n\n\n## Publication fidelity (Core 0.2.34)\n\nStatic Repeater rows and aliases export the selected item block’s declared public\nfields, explicit card mappings and grouping labels. Use `title`/`href` for static\nPost Cards and `item_overrides` for common appearance; never place private data\nin public fields. `rendered: false` still excludes the field. `breadcrumb_label`\nis preserved separately from the Page title. Older public artifacts need a new\ndeployment; do not rewrite the saved rows to compensate. Native Heading and Page\nTitle wrap long words without shrinking authored type. Firestore history adds no\nextra Page nesting; an actual storage depth limit returns structured HTTP 422\n`storage_document_too_deep` with the offending field path.\n",
     "tr-redesign-branch": "---\nname: tr-redesign-branch\ndescription: Use when the user asks to redesign, modernize, or restructure a Typeroll site (or a section of it). Forces branch-isolated work so the live site stays untouched until the redesign is approved.\n---\n\n# Redesign a site without breaking the live one\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks and partials) lands in an unsaved per-doc\n> DRAFT — deploys and plain previews only see SAVED content. For recipe-style\n> build work, pass `save: true` on write calls (the work is pre-approved by\n> the task itself), or run `commit_working_copy` per doc before any\n> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.\n\n\nSite-wide changes are exactly where copy-on-write branches earn their\nkeep. This skill enforces the discipline: every redesign happens on a\nbranch, preview-checked end-to-end, merged only after user sign-off.\n\n**Copy comes from the LIVE page, not a local draft.** A redesign changes\nthe design, not the words. Read the existing copy from the live page\n(`read_page`/`batch_read_pages`) and carry it over verbatim. Local\n`sources/*.md` files are drafts — use them only if the user explicitly\nsays \"apply the copy in `<file>`\". Don't invent new headlines, drop\nsections, or \"restore\" text from an old draft; a draft that had drifted\nfrom the live page once sent a whole redesign off the approved wording.\nWhen you must change a word, change it on the live page too and keep the\ndraft file in sync.\n\n**Restraint beats decoration.** Default to clean, purposeful design. Don't reach\nfor decorative motifs (suns, blobs, glows, mascots, confetti) to look \"graphic\" —\nunless a motif *means something for this brand/page*, it reads as random, and it's\nusually the exact thing that clips, seams, and crops. These fragile patterns broke\na real build — avoid them:\n- **A shape divider (wave/curve) between two sections** → don't hand-roll it in\n  `core/html`; a separate stacked shape seams against the next section (a Chrome\n  sub-pixel hairline). Use `core/section`'s **`divider_top` / `divider_bottom`**\n  (`wave | curve | tilt`) — the platform paints it in the section's own colour and\n  overlaps the neighbour by 1px, so it's seam-free by construction. Put the divider\n  on the section whose colour should rise/dip into the neighbour.\n- **A glow/decoration inside an `overflow:hidden` box** → clipped to a hard edge.\n  Put it in a non-clipped layer, or size it to fade out before the box edge.\n- **`object-fit:cover` on a portrait inside a circle/frame** → crops heads and\n  faces. Use `contain`, reframe the source art, or size the frame to the art.\n- **A gradient \"fade\" at a section join** → reads as the design being cut off.\n  Make transitions deliberate (a clean shape or a solid edge), never a fade.\nThese are invisible in a small full-page thumbnail and only show at real size in\nthe actual browser — see the review gate in step 6.\n\n## Recipe\n\n### 1. Discover (always)\n\n```\nget_site\nread_site_settings\nread_partial partial_id=\"header\"\nread_partial partial_id=\"footer\"\nlist_pages limit=20\nbatch_read_pages page_ids=[<top 3-5 pages>]   # see actual conventions\nlist_partials                                  # what free blocks exist\nlist_content_types                               # any data we need to consider\n```\n\nWrite the user a short read-back: *\"This is a 12-page agency site\nusing CSS variables, primary color #1e40af, Inter heading + Source\nSans body. Existing pages are content-dense, single-column. Main nav\nhas 5 items including a CTA. I'd suggest...\"*\n\nConfirm direction before touching anything.\n\n### 2. Create a branch\n\n```\ncreate_branch name=\"<descriptive name>\"\n```\n\nSave the response's `id` — pass it as `version=<id>` on every\nsubsequent call. Branches default `robots_blocked: true` so a\nhalf-finished redesign won't be indexed.\n\n### 2b. Write the design spec (REQUIRED — before you build)\n\nEvery redesign branch MUST carry a written design spec. Without it the\ndesign choices live only in the agent's head, so a later \"just tweak the\nillustration style / palette\" means re-deriving everything by hand (this\ngap cost a real project a full reverse-engineering pass). Write it BEFORE\nbuilding so it guides the work, and keep it in sync as the design evolves.\n\nSave it as a markdown doc with the project (e.g. `design-spec.md`, or\n`prompts/design-system.md`) — or, if there's no local working dir, as an\nunlisted page on the branch. It must capture:\n\n- **Palette** — every role + hex (background, surface, primary, accent,\n  text, borders), and where the variant *diverges* from the brand and why.\n- **Typography** — fonts + weights/sizes per role.\n- **Illustration / imagery style** — the exact image-gen prompt prefix\n  (tone, palette, formspråk, framing rules), so the imagery can be\n  regenerated or restyled on its own without touching layout. State the\n  business/concept constraints the imagery must respect (a wrong-concept\n  image is worse than none).\n- **Section structure** — the page's sections in order + each one's\n  treatment (band colour, layout).\n- **Rationale** — one line per major choice: *why* this direction.\n\nWhen the user later says \"adjust just the illustrations\" or \"change the\npalette\", you edit the spec first, then apply — the spec is the source of\ntruth for the design intent.\n\n### 3. Iterate on the branch\n\nFor each redesign step:\n\na. Make the change with `?version=<branch-id>`. Updates here don't\n   touch main:\n\n   ```\n   update_partial partial_id=\"header\" patch={...} version=\"<branch>\"\n   update_page page_id=home patch={...} version=\"<branch>\"\n   ```\n\nb. Preview after every meaningful change:\n\n   ```\n   get_preview_link page_id=home version=\"<branch>\"\n   ```\n\n   Send the URL to the user. The preview navigates the whole branch\n   from one mint.\n\nc. Iterate on feedback. Common rounds: headline tightening, color\n   tweaks, swapping hero images.\n\n### 4. Site-wide changes through partials, not pages\n\nIf the redesign touches every page (e.g. new global header, new\nfooter, new CTA bar) — edit a partial, not 23 pages. Before editing a\nshared block, check the blast radius:\n\n```\nfind_pages_using_block partial_id=\"header\" version=\"<branch>\"\n```\n\nThis returns every page that would show the change. Communicate that\nto the user before the save.\n\n### 5. Bulk content cleanups via dry-run first\n\nIf the redesign requires content rewrites (e.g. \"remove every mention\nof the old company name\"), use the bulk tool with dry-run:\n\n```\nsearch_pages contains=\"OldCo\" version=\"<branch>\"\nbulk_replace_text pattern=\"OldCo\" replacement=\"NewCo\" dry_run=true version=\"<branch>\"\n# Show the user the sample_diffs\nbulk_replace_text pattern=\"OldCo\" replacement=\"NewCo\" dry_run=false version=\"<branch>\"\n```\n\n### 6. Approval round\n\n**Self-review is a multi-DIMENSION pass, not a glance — and most of it you\nMEASURE, not eyeball.** Structural checks (copy present, images return 200) are\nNOT a design review; never report \"approved\" off them. Don't just list the bugs\nyou happened to notice — walk every dimension below on the DB-live preview\n(a reused `get_preview_link`; browser tool + DOM reads), fix what you find,\nreload, re-check. No re-deploy between fixes — the preview renders from the DB.\n\n**Use `tr-design-review` (`read_skill tr-design-review`) for the HOW** — it has\nthe per-dimension measurement snippets (overflow ladder, computed contrast, touch\ntargets, the anti-lazy-load broken-image check) and the scorecard + verdict\nformat. The dimension summary below is the \"what\"; that skill is the runnable\nroutine. In particular: scroll-and-settle to trigger lazy images BEFORE any\nfull-page screenshot, or you'll report blank boxes that aren't real.\n\n1. **Responsive** — screenshot across a width ladder (mobile / tablet / laptop /\n   desktop / wide ≈390 / 768 / 1024 / 1440 / 1920px) AND sweep the page's own\n   `@media` breakpoints (read the page-scoped `<style>`; resize a few px below +\n   above each). At EVERY width: `document.documentElement.scrollWidth <=\n   clientWidth` (no horizontal scroll), grids flip cleanly, nothing squished /\n   orphaned / overlapping, no mid-word breaks. Two sizes is not enough — bugs hide\n   in between. Also check a short/landscape viewport and 200% browser zoom.\n2. **Visual & brand** — logo FULLY VISIBLE (not clipped by a header\n   `overflow:hidden` + overlap margin) and brand-compliant; screenshot the header\n   IN CONTEXT, never the logo element in isolation (that hides clipping).\n   Decoration robust at real size in the real browser: no hairline seam at a\n   divider (use `core/section` `divider_top`/`divider_bottom` — don't hand-roll a\n   band), no glow clipped to a hard edge, no `object-fit:cover` cropping faces, no\n   gradient fade-cutoff. Typography: body line-length ~45–75ch, consistent scale,\n   no awkward widows on headings. Palette adherence (no off-brand colours);\n   consistent spacing / alignment / radius / shadow.\n3. **Accessibility — MEASURE, don't eyeball** — compute actual contrast ratios\n   (WCAG AA: body ≥4.5:1, large/UI ≥3:1) and fix failures by deepening the\n   offending colour token; meaningful `alt` on every image; exactly one `<h1>` +\n   no skipped heading levels; visible `:focus-visible` on every interactive\n   element; every input has an associated `<label>`; touch targets ≥44px on\n   mobile; semantic landmarks (header/nav/main/footer) + nav `aria-label`; honour\n   `prefers-reduced-motion`.\n4. **Functional** — the form actually works (POST action correct, hidden token\n   non-empty, honeypot present + hidden; a long name/email doesn't break layout);\n   every link + in-page anchor resolves (each `#anchor` has a matching `id`; no\n   `href=\"#\"`/`\"\"`); ZERO console errors/warnings; interactions (menu toggle,\n   hover/focus/active) work.\n5. **Content** — no unrendered `{{…}}` tokens in the DOM; no placeholder/lorem;\n   copy still matches the source of truth (the live page) verbatim.\n6. **Findable (SEO/meta)** — `<title>` + meta description present + sensible;\n   `og:title`/`og:description`/`og:image`; canonical; favicon + apple-touch-icon;\n   `<html lang>`; `noindex` correct (branches must be noindex).\n7. **Fast (performance)** — images at sane sizes (not a 2048px file shown at\n   380px without a responsive variant), modern format (avif/webp), `width`/`height`\n   or aspect-ratio set (no layout shift), below-fold lazy / above-fold eager.\n8. **Cross-browser** — the same CSS renders differently per engine (the divider\n   seam was Chrome-only; WebKit/Firefox have their own). Re-check in another engine\n   if you can; if only Chromium is available, statically flag risky props\n   (`backdrop-filter` without fallback, `-webkit-`-only masks, `100vh` on mobile →\n   prefer `100svh`, `sticky` inside `overflow`).\n\nFix what you find and re-check before involving the user. \"Looks structurally\nfine\" ≠ \"looks good\", and \"looks good in Chrome at 1440\" ≠ \"works for everyone,\neverywhere\" — never report a design as approved/perfect off a glance or a partial\npass.\n\nThen give the user the **DB-live preview link** to review — and use the SAME\nlink for your own verification:\n\n- **While iterating (default):** a reused `get_preview_link` (mint once,\n  reuse — defaults to a 24h TTL). It renders from the database with NO build, so every\n  edit shows on reload, and one link navigates the whole branch (internal\n  links keep the token). The token URL is stable across edits — re-mint only\n  when the 24h lapses, never per edit. Do NOT deploy just to let the user (or\n  yourself) see a change.\n- **When they want the COMPILED static site** (a permanent bookmark, a\n  stakeholder link to the built output, or a final pre-merge check): deploy\n  the branch once (`trigger_deploy version=\"<branch>\"`) and share the stable\n  alias `https://<branch>.<project>.pages.dev` (the `<project>` is the part\n  after the hash in the returned `deploy_url`). Branch deploys are\n  `robots_blocked`, so it won't be indexed. The immutable per-deploy\n  `<hash>.pages.dev` is for your own one-off checks (a new hash each deploy).\n\nDefault: review/iterate on the reused DB-live preview; deploy only for the\ncompiled output or merge. Wait for an explicit \"looks good, ship it.\"\n\n### 7. Merge + deploy\n\n```\nmerge_branch version_id=\"<branch>\"        # branch's diffs land on main\ntrigger_deploy\nget_deploy_status job_id=<id>             # poll until succeeded\n```\n\nOptionally, after a successful deploy:\n\n```\ndelete_branch version_id=\"<branch>\"       # tidy up\n```\n\n(You can also leave the branch around as a record of the redesign;\ndisk cost is tiny.)\n\n## Pitfalls\n\n- **Forgetting `version=` on writes.** Every call you make on the\n  branch must include `version=<branch-id>`. A missing one writes\n  straight to main — silent and bad.\n- **Skipping discovery.** \"Modernize\" without first reading the site\n  produces a confidently-out-of-place result. Always sample existing\n  pages.\n- **Deploying to preview.** Don't `trigger_deploy` after every edit just to\n  see the change — that builds static pages and the URL is only as fresh as\n  the last build. Iterate on a reused DB-live `get_preview_link` (renders from\n  the DB, reflects edits on reload); deploy only for the compiled static\n  output or merge (steps 6–7).\n- **Auto-merge.** Don't `merge_branch` without explicit user sign-off.\n  Once merged, the only undo is another branch + reverse edits.\n- **Header rewrites that drop the brand block.** Even when the\n  redesign is dramatic, preserve the brand mark + the nav skeleton\n  unless the user said to redo them.\n\n## When to NOT use a branch\n\nTiny edits — \"fix the typo on the About page\" — don't need a branch.\nThe in-portal chat handles those directly on main. This skill is for\nwork where:\n\n- The user might want to walk away mid-redesign and come back later\n- Multiple changes need to ship together\n- The site is high-traffic and \"broken for an hour\" is unacceptable\n- Stakeholder review across multiple pages is expected\n\nIf none of those apply, edit main directly and move on.\n",

package/dist/version.js

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

package/package.json

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

package/skills/tr-migrate-wp.md

@@ -306,3 +306,20 @@ An image-only H2 becomes an image at that position, not a semantic heading.
 Compare ordered headings/text/media/CTAs, including malformed wrappers, lazy and
 noscript images and related-content boundaries. Existing Pages are not rewritten;
 repair confirmed placement errors against raw source without reimporting edits.
+
+
+## Navigation and empty-media variants
+
+Inventory first-step input banners independently of final submission providers.
+Preserve their fields, required/minimum validation, service tabs and direct links,
+mobile collapsed/open states and navigation even when the final integration is
+deferred. Core 0.2.40 provides native `core/navigation_form` and mixed `core/tabs`.
+Read their schema instead of rebuilding them in HTML or reintroducing a provider
+block. Defaults are same-origin and tab-scoped; never place addresses in URLs or
+claim cross-origin prefill. The receiving form must explicitly accept the fields.
+
+Compare listing rows with both real and missing images. Use shared post-card
+placeholder settings for theme decoration, preserving real featured images and
+explicit `show_image: false`. Compare actual footer link height plus gap, wrapping,
+focus and column breakpoints; compact navigation density is an intentional option.
+Verify native preview and static output on the agreed viewport boundaries.

package/skills/tr-migration-evidence.md

@@ -158,3 +158,20 @@ Do not report “all design checked” from a viewport or recipe sample. Keep so
 link-order comparisons and paired contact sheets with the report. The same contract
 applies to WordPress, URL, Astro and multisite migration; do not create separate,
 weaker checklists for individual import mechanisms.
+
+
+## Navigation and empty-media variants
+
+Inventory first-step input banners independently of final submission providers.
+Preserve their fields, required/minimum validation, service tabs and direct links,
+mobile collapsed/open states and navigation even when the final integration is
+deferred. Core 0.2.40 provides native `core/navigation_form` and mixed `core/tabs`.
+Read their schema instead of rebuilding them in HTML or reintroducing a provider
+block. Defaults are same-origin and tab-scoped; never place addresses in URLs or
+claim cross-origin prefill. The receiving form must explicitly accept the fields.
+
+Compare listing rows with both real and missing images. Use shared post-card
+placeholder settings for theme decoration, preserving real featured images and
+explicit `show_image: false`. Compare actual footer link height plus gap, wrapping,
+focus and column breakpoints; compact navigation density is an intentional option.
+Verify native preview and static output on the agreed viewport boundaries.