@typeroll/mcp-server 0.45.68 → 0.45.69

package/dist/tools/migration.js

@@ -45,11 +45,17 @@ export const migrationTools = [
                 fields: z.array(z.object({ name: z.string().min(1), type: z.string().optional() })).optional(),
                 blocks: z.array(z.any()),
                 business_specific_block_types: z.array(z.string()).optional(),
+                reviewed_custom_block_types: z.array(z.object({
+                    type: z.string().trim().min(1), reason: z.string().trim().min(1).max(2000),
+                })).max(100).optional(),
+                reviewed_html_blocks: z.array(z.object({
+                    block_id: z.string().trim().min(1), reason: z.string().trim().min(1).max(2000),
+                })).max(100).optional(),
             }))
                 .min(1)
                 .max(50)
                 .optional()
-                .describe('Proposed block compositions to review before build. Include fields when you want missing schema bindings detected. Explicitly list only genuinely business-specific custom block types.'),
+                .describe('Proposed block compositions before build. Standard blocks first, reviewed reusable custom types next, raw HTML only as a documented last resort. reviewed_custom_block_types and reviewed_html_blocks record exact choices and reasons, not proof of visual quality. Missing types/fields still block readiness.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = args.compositions
@@ -207,7 +213,7 @@ export const migrationTools = [
     },
     {
         name: 'record_migration_seo_acceptance',
-        description: 'Record the reviewed SEO/content parity evidence used by the launch report. This does not run the audit. Supply the exact source/target origins, checked timestamp, dataset description, page count and difference counts. Also supply fidelity: desktop/mobile visual comparisons, shared-data checks, integration checks and evidence notes. HTTP 200 is not visual acceptance. status=accepted requires unresolved=0. Re-run and record new evidence after every deploy.',
+        description: 'Record the reviewed SEO/content parity evidence used by the launch report. This does not run the audit. Supply the exact source/target origins, checked timestamp, dataset description, page count and difference counts. Also supply fidelity: desktop/mobile review against the source (preserve) or approved design (renew), shared-data checks, integration checks and evidence notes identifying the intent and approved differences. HTTP 200 is not visual acceptance. status=accepted requires unresolved=0. Re-run and record new evidence after every deploy.',
         inputSchema: {
             status: z.enum(['accepted', 'rejected']),
             checked_at: z.string().datetime(),

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.68';
+export const VERSION = '0.45.69';

package/dist/workspace.js

@@ -57,6 +57,16 @@ Public documentation: https://typeroll.com/docs/llms.txt
 - Never edit generated publishing source to change CMS content. Do not overwrite
   current CMS or owner answers from an old local snapshot.
 
+## Migrations
+
+Read tr-migration-evidence, then the source-specific recipe (tr-migrate-wp,
+tr-import-url, tr-migrate-astro or tr-migrate-multisite). Record preserve or renew
+intent in brief/migration.md; ask if unclear. Standard blocks first, reviewed
+custom types next, documented HTML exceptions last. Preserve or meaningfully
+redirect every old public URL. Import completion is not block reconstruction
+or launch acceptance. Compare preserve work to the source, renew work to the
+approved design/content brief. Discover tools and recipes on demand.
+
 ## Everyday requests
 
 - Links, images, menus, settings, analytics and site-wide changes: read the
@@ -77,6 +87,7 @@ export const workspaceTemplates = {
     'brief/site.md': '# Site brief\n\n## Purpose and audience\n\n## Languages and scope\n\n## Primary user journeys\n\n## Content authority and sources\n\n## Editorial constraints and forbidden internal markers\n',
     'brief/brand.md': '# Brand\n\n## Voice and tone\n\n## Visual direction and references\n\n## Typography, colors and image policy\n\n## Desktop and mobile navigation\n\nRecord intent here; current design tokens belong in CMS settings.\n',
     'brief/content-model.md': '# Content model\n\n## Page types and routes\n\n## Fields and references\n\n## Shared templates and partials\n\n## Taxonomy and navigation\n\nUse the current CMS schema. This document describes decisions, not a second schema store.\n',
+    'brief/migration.md': '# Migration brief (when applicable)\n\n## Intent: preserve or renew\n\n## Source URLs, date and agreed scope\n\n## Design and content acceptance reference\n\n## Retained facts and approved content changes\n\n## Standard blocks, custom types and HTML exceptions\n\n## Old URL to preserved path or relevant redirect\n\n## Prototype and verification evidence\n\nKeep private extracts in sources/private/ and screenshots in qa/reports/.\n',
     'decisions.md': '# Decisions\n\nRecord date, decision, reason, approved scope and alternatives when useful.\n',
     'sources/README.md': '# Sources\n\nStore research references and copy proposals. Record source URLs and dates.\nPrivate extracts belong in ignored private/ or an approved external store.\nDo not treat local drafts as current CMS content or commit media libraries.\n',
     'scripts/README.md': '# Project automation\n\nKeep repeatable imports and QA scripts here. Use the authenticated REST API\nfor scripted work; keep credentials outside files and inject them at runtime.\nMCP remains the interactive interface. Typeroll currently has no general site CRUD CLI.\n',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.68",
+  "version": "0.45.69",
   "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-edit-site.md

@@ -49,8 +49,9 @@ drafts and unpublished pages. Mint one link and reuse it while iterating.
 a local file with `create_upload_url` (see `tr-images`); `list_media` finds
 existing ones. Use the returned CDN URL exactly. With a named target, place it
 there (`add_block` with `core/image` on a block page; an `<img>` with `alt` in
-`html_content` on an HTML page). Without one, ask what the image is for. Ask
-for alt text when none was given. Afterwards say in one sentence where it
+`html_content` on an HTML page). Without one, ask what the image is for. Preserve meaningful alt text or describe the image’s function; decorative images
+may have empty alt, while linked images need an accessible name. Ask when the
+intended purpose is unclear. Afterwards say in one sentence where it
 landed; to answer "has it been added?", read the page again rather than
 trusting the conversation.
 

package/skills/tr-import-url.md

@@ -9,10 +9,12 @@ description: Use when the user wants to import or migrate content from a non-Wor
 another MCP client) working through MCP and the public API. The portal's built-in
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
-**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.
-Complete its source baseline and one verified prototype per active template.
-Read target content to protect edits, not to justify accidental target defaults.
-Its shared evidence record is required for visual acceptance.
+**Before import or reconstruction:** read `tr-migration-evidence` with
+`read_skill`. Choose preserve (platform change) or renew (new design/content),
+record the brief and verify one prototype per active template before bulk writes.
+Use standard blocks first, reviewed custom types next, rare documented HTML last.
+Both paths must preserve or meaningfully redirect every old public URL. That
+shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
 > **The buffer model (draft writes).** Every content write in this recipe
@@ -35,7 +37,9 @@ Its shared evidence record is required for visual acceptance.
 
 ## Preconditions
 
-- Target Typeroll site exists with working header/footer.
+- Target Site and Version are selected through OAuth or a scoped API key.
+- Run `get_import_readiness` before importing content or media; verify the
+  Organization storage first. Build shared header/footer against the chosen brief.
 - Source URL(s) accessible (check with a quick `fetch`; if blocked, mention
   it and ask the user for an HTML export or screenshot).
 
@@ -56,7 +60,7 @@ Parse `<a href>` links to discover internal pages. Build a list:
 - Any sub-pages that look important
 
 Exclude private/session/admin URLs deliberately. Inventory public pagination and
-query routes; decide preservation or retirement from their actual purpose.
+query routes and keep them working or map relevant redirects. Do not silently retire public routes.
 
 **Map source styling to named styles.** A class the source uses for a
 recurring treatment (`.eyebrow`, `.lead`, `.btn-outline`, `.section-dark`)
@@ -76,8 +80,9 @@ read_partial partial_id="header"
 list_pages limit=5
 ```
 
-Read existing target data to avoid overwriting work. Establish source geometry
-and validate native prototypes using `tr-migration-evidence` before mass writes.
+Read existing target data to avoid overwriting work. Compare prototypes to the
+source in preserve mode, or to the agreed new design in renew mode. Validate
+standard/custom blocks using `tr-migration-evidence` before mass writes.
 
 ### 3. Fetch and clean each source page
 
@@ -117,15 +122,16 @@ icons. A required file that fails transfer blocks acceptance; do not silently
 omit it. Inventory PDFs, download hrefs, srcsets and backgrounds as well.
 
 **d. Adapt to the target's design.**
-Use verified native fields from the source capability map. Preserve appearance
-by default; do not substitute target defaults or corrective tenant CSS.
+Use standard blocks first, then reusable custom types with editable fields.
+Preserve source appearance/text in preserve mode; use the approved new design
+and content plan in renew mode. Raw HTML is the documented last resort.
 
 ### 4. Create pages as drafts
 
 ```
 create_page title="Om oss" slug="om-oss"
-            html_content="<cleaned, adapted HTML>"
-            content_mode="html" status="draft"
+            path="/om-oss/" blocks=[<reviewed block tree>]
+            content_mode="blocks" status="draft"
             seo_title="Om oss — Acme"
             seo_description="..."
 ```
@@ -155,7 +161,7 @@ Walk through every imported page with the user. Common issues:
 
 ### 7. Publish + deploy
 
-After approval:
+After approval, save working copies and confirm publishing readiness:
 ```
 batch_update_pages updates=[
   {page_id: "om-oss",  patch: {status: "published"}},
@@ -163,15 +169,20 @@ batch_update_pages updates=[
 ]
 trigger_deploy
 get_deploy_status job_id=<id>
+verify_migration_urls
+get_migration_launch_report
 ```
 
+This is candidate verification, not permission to change traffic DNS. Every old
+public URL must serve its content or a relevant redirect before cutover.
+
 ## Platform-specific notes
 
 ### Squarespace
 - Main content is inside `.content-wrapper` or `[data-section-theme]` blocks
 - Portfolio images are usually high-resolution originals in `/universal/images/`
 - JSON-LD is Squarespace's own schema — strip it
-- Gallery blocks → convert to CSS grid with inline `<img>` tags
+- Gallery blocks → standard image/gallery layouts, or a reusable custom type
 
 ### Wix
 - Wix sites are React SPAs — `fetch` returns an empty shell
@@ -186,7 +197,7 @@ get_deploy_status job_id=<id>
 
 ### Static HTML / old sites
 - Often the cleanest import. Fetch, strip nav/footer, keep body.
-- Watch for table-based layouts (pre-2010 sites) — convert to CSS grid
+- Rebuild table-based layouts with layout blocks; keep actual tabular data as tables
 
 ## Pitfalls
 

package/skills/tr-migrate-astro.md

@@ -9,10 +9,12 @@ description: Migrate an existing Astro site, including Astro Content Collections
 another MCP client) working through MCP and the public API. The portal's built-in
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
-**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.
-Complete its source baseline and one verified prototype per active template.
-Read target content to protect edits, not to justify accidental target defaults.
-Its shared evidence record is required for visual acceptance.
+**Before import or reconstruction:** read `tr-migration-evidence` with
+`read_skill`. Choose preserve (platform change) or renew (new design/content),
+record the brief and verify one prototype per active template before bulk writes.
+Use standard blocks first, reviewed custom types next, rare documented HTML last.
+Both paths must preserve or meaningfully redirect every old public URL. That
+shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
 Astro Content Collections are source data. In Typeroll, each source record

package/skills/tr-migrate-multisite.md

@@ -9,10 +9,12 @@ description: Use when migrating SEVERAL sites at once — a WordPress multisite
 another MCP client) working through MCP and the public API. The portal's built-in
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
-**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.
-Complete its source baseline and one verified prototype per active template.
-Read target content to protect edits, not to justify accidental target defaults.
-Its shared evidence record is required for visual acceptance.
+**Before import or reconstruction:** read `tr-migration-evidence` with
+`read_skill`. Choose preserve (platform change) or renew (new design/content),
+record the brief and verify one prototype per active template before bulk writes.
+Use standard blocks first, reviewed custom types next, rare documented HTML last.
+Both paths must preserve or meaningfully redirect every old public URL. That
+shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
 > **The buffer model (draft writes).** Every content write in this recipe
@@ -38,9 +40,9 @@ that is expensive to reverse (domains, deploys, and analytics all hang off
 it). The rest of this recipe assumes the common case: **N sites, one per
 domain**, sharing a design.
 
-Requires an **org-scoped API key** (`create_site` needs it, and one key
-reaching every site is the whole point here). With MCP you pass `site_id`
-per call; over stdio you'll be re-pointing `TYPEROLL_SITE_ID` per site.
+Use personal OAuth with the required Organization permissions or an org-scoped
+API key. Select each Site explicitly and use its returned context; never reuse
+another Site's OAuth context. Keep Site and Version explicit on batch calls.
 
 ## Phase 0 — Plan the batch (do this once, in writing)
 
@@ -61,15 +63,14 @@ Then once per market, with that market's own source:
 get_migration_readiness site_id=<de-site> source_url="https://example.de"
 ```
 
-The blockers (media storage, hosting credentials) are **platform-level, not
-per-site** — if they fail for one site they fail for all ten, and finding out
-after building three sites means redoing three sites' worth of image work.
-Get them fixed before Phase 1, and re-run the check per site once the sites
-exist (the warnings — verification URL, form email, design reference — are
-per-site).
+Check each target Site: storage is shared per Organization, but Hosting Groups,
+permissions and verification origins can differ. Verified customer storage is
+required before import; GitHub/build/domain readiness is checked separately for
+publication. Do not infer that every Site shares the same blockers.
 
 Ask explicitly:
-- Which site is the **design reference**? Build that one properly first.
+- Which intent applies per Site: preserve or renew? Which source or approved
+  prototype is the **design reference**? Build that one properly first.
 - Are the sites **translations of each other** (same page structure) or
   independent? This decides whether hreflang clusters are mechanical or
   hand-mapped.
@@ -117,10 +118,11 @@ Add every source you have, each with its own label — they merge per URL:
   the traffic sort to the top.
 - `source="crawl"` — anything you found by following internal links
 
-Mark the obvious throwaways immediately, so the work list is real:
+Exclude only private/admin/session noise, with reasons. Public tags and archives
+need working routes or relevant redirects, even when omitted from new navigation:
 
 ```
-add_migration_urls urls=[{ url: "/wp-admin", excluded: true }, { url: "/tag/nyheter", excluded: true }]
+add_migration_urls urls=[{ url: "/wp-admin", excluded: true, notes: "Private source administration" }, { url: "/wp-login.php", excluded: true, notes: "Private source login; not public content" }]
 ```
 
 Read it back and note the starting number:
@@ -183,7 +185,7 @@ list_migration_urls site_id=<de-site> status="unhandled"
 For each entry, one of three outcomes — no fourth option:
 
 - It moved → `create_redirect from_path="/alte-seite" to_path="/neue-seite"`
-- It's gone on purpose → `update_migration_url url_id=… excluded=true notes="Old campaign LP, signed off by <name>"`
+- It was merged → redirect to the relevant replacement, not the homepage
 - It should exist and doesn't → go back and migrate it
 
 Re-read the list. `unhandled` reaching zero is the exit condition for this

package/skills/tr-migrate-wp.md

@@ -9,10 +9,12 @@ description: Use when the user asks to migrate a WordPress site to Typeroll, men
 another MCP client) working through MCP and the public API. The portal's built-in
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
-**Before bulk conversion:** read `tr-migration-evidence` with `read_skill`.
-Complete its source baseline and one verified prototype per active template.
-Read target content to protect edits, not to justify accidental target defaults.
-Its shared evidence record is required for visual acceptance.
+**Before import or reconstruction:** read `tr-migration-evidence` with
+`read_skill`. Choose preserve (platform change) or renew (new design/content),
+record the brief and verify one prototype per active template before bulk writes.
+Use standard blocks first, reviewed custom types next, rare documented HTML last.
+Both paths must preserve or meaningfully redirect every old public URL. That
+shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
 > **The buffer model (draft writes).** Every content write in this recipe
@@ -41,9 +43,9 @@ get_migration_readiness source_url="https://oldsite.com"
 
 When the migration includes reusable page/item layouts, include each proposed
 block composition and its content type fields in this same call. A
-`waiting_for_native_support` result means leave that template intact and do
-not replace the gap with generic custom blocks, raw HTML, or corrective site
-CSS. Independent content and SEO work may continue. Rerun the review after the
+`waiting_for_native_support` result means inspect the actual blocker. Review
+intentional custom types and rare HTML exceptions using `tr-migration-evidence`;
+fix missing types/fields and report renderer defects rather than masking them. Independent content and SEO work may continue. Rerun the review after the
 required Core version is deployed, then verify preview and a fresh hosted
 build.
 
@@ -60,8 +62,11 @@ once the work is done, so discovering it late means redoing the expensive part.
 - **Media storage** — without it, every `<img>` keeps its WordPress URL. The
   new site looks perfect and is still served images by the old host. It breaks
   the day the customer cancels that hosting, months later, all at once.
-- **Hosting adapter** — without credentials, deploys return a job id and
-  publish nothing, while reporting success.
+- **Publishing** — with verified Organization storage, customer publishing can
+  import and preview before GitHub, builds or website domains are connected.
+  Publishing readiness is a separate gate before a hosted build/cutover. Legacy
+  self-hosted configurations may report a missing hosting adapter; follow the
+  returned blocker rather than assuming all installations have the same setup.
 
 Warnings are worth relaying but don't stop you: no verification origin (the
 pre-cutover parity check can't run), forms without a
@@ -69,12 +74,13 @@ notification address, or a target site with no design to rebuild INTO.
 
 Then the ordinary preconditions:
 
-- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.
+- MCP connected through personal OAuth or an appropriately scoped API key.
+  Select and confirm the Site/Version before writes; do not request pasted secrets.
 - The source WP site has `/wp-json` reachable (Google for "wordpress
   REST API disabled" if not — common for hardened hosts).
 - The target exists. Establish the source design baseline first, then prove
   representative target templates using `tr-migration-evidence`. Preserve
-  appearance unless a redesign is explicitly requested.
+  appearance in preserve mode; use the approved design/content brief in renew mode.
 - If the target already has content, you must NOT clobber it — always
   `list_pages` first and only write to slugs that don't already exist.
   Pass the slug explicitly: `create_page` then refuses an address that is
@@ -161,10 +167,11 @@ c. Migrate referenced images with `upload_media_from_url`. The customer's
 
 The managed importer stores cleaned HTML. Typeroll does not convert HTML into blocks, and `set_page_mode` never rewrites HTML. Pages move to blocks only when someone rebuilds them with blocks.
 
-d. Preserve exact text, headings, anchors, links, media and semantic structure with native blocks first. Read the
-   available block types and map headings, prose, images, buttons and layout
-   into their typed fields. Use HTML mode only for source-specific markup that
-   has no native representation and has passed the composition preflight.
+d. Rebuild into editable blocks according to the selected intent. Preserve exact
+   wording in preserve mode; track approved changes in renew mode. Map headings,
+   prose, images, buttons and layout to standard fields first, then create
+   reviewed custom types where needed. Use raw HTML only for a documented,
+   exceptional fragment. Preserve anchors and map every old URL in either mode.
 
 e. Write the page as a draft:
 
@@ -192,8 +199,10 @@ create_redirect from_path="/old-services" to_path="/services"
 
 Walk the inventory; for each URL: did it become a page with the same
 path? If yes, no redirect. If renamed, `create_redirect`. If
-intentionally dropped, mark it `excluded` via `update_migration_url` (the
-customer should sign off on every dropped URL).
+combined with another page, redirect to the relevant combined content. Do not
+mark a public page excluded just because the new design omits it. Public URL
+retirement requires a separately agreed exception; admin/session noise can be
+excluded with a recorded reason.
 
 Use a pattern only after verifying every affected source-to-destination mapping.
 For an explicitly approved prefix change, `/old-blog/:slug` → `/articles/:slug`

package/skills/tr-migration-evidence.md

@@ -1,6 +1,6 @@
 ---
 name: tr-migration-evidence
-description: Source-first design baseline, native capability mapping and evidence gates required before bulk website migration or visual acceptance.
+description: Choose preserve or renew intent, map standard and custom blocks, preserve old URLs, and verify content, design and behavior before migration acceptance.
 ---
 
 # Migration evidence contract
@@ -10,15 +10,88 @@ another MCP client) working through MCP and the public API. The portal's built-i
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
 Use this shared contract with WordPress, Astro, URL and multisite recipes.
-Default to preserving the source appearance and behavior. A redesign requires
-explicit scope. A partly migrated target is not the design reference.
+## Choose the migration intent before writes
+
+Record `preserve` or `renew` in the workspace's `brief/migration.md` (or the
+project's equivalent brief), with scope, source URLs and the user's decision.
+These are planning labels, not fields accepted by the migration API. Ask when
+the intent is unclear; do not infer redesign permission from “migrate”.
+
+| Intent | Source material | Acceptance reference |
+| --- | --- | --- |
+| Preserve: change publishing platform | Keep text, images, structure, visual identity and behavior as closely as practical. | The original site. Record deliberate deviations and their agreed benefit. |
+| Renew: improve design and content | Use source text, images, structure and graphic design as raw material. Agree what to retain, rewrite, combine or replace. | The agreed brief, content plan and approved prototypes, not visual similarity to the old site. |
+
+Both paths preserve facts, ownership, required business behavior and historical
+URL continuity. Renewal does not authorize invented claims, removal of useful
+content or an unapproved domain switch. Do not use a partly migrated target as
+an accidental design reference. Protect existing target edits in either path.
+
+## Use editable blocks in both paths
+
+1. Inspect standard block schemas, composition starters, named styles and Page
+   templates. Prefer these when they fit.
+2. When they do not fit, read `tr-custom-blocks` and create a reusable Site block
+   type with meaningful editable fields. Prefer a composition of standard blocks;
+   a field-driven template type is appropriate when composition cannot express it.
+   Validate the type, preview it, save/read it back and test a representative use
+   in static output. Do not store a whole page as an opaque HTML field.
+3. Raw HTML is a last resort for a small, exceptional fragment. Record the exact
+   block/Page, why neither standard nor custom types fit, editing limitations and
+   verification. Keep the surrounding page block-based whenever possible.
+
+A justified HTML exception is a unique art-directed hero: layered imagery,
+animation and text placed precisely over a background at different breakpoints.
+Prefer a field-driven custom type when editors need to change its text, images
+or links repeatedly; a one-off hero may remain an isolated HTML block. Verify
+actual breakpoints, cropping, keyboard access, contrast and reduced motion. Keep
+essential copy and links usable without animation. Do not copy source-platform
+scripts; any custom script needs explicit scope and the supported runtime.
+
+On Core 0.2.89 / MCP 0.45.69+, composition preflight accepts reviewed custom types in
+`reviewed_custom_block_types: [{type, reason}]` and rare HTML blocks in
+`reviewed_html_blocks: [{block_id, reason}]`. Inspect the deployed schema first on older installations. These are reviewer
+attestations, not proof of quality. They only acknowledge those specific choices; missing
+block types/fields and unreviewed workarounds still block readiness. Do not call
+something business-specific just to bypass a check. A confirmed renderer bug
+still needs a platform fix, not a disguised HTML/CSS workaround.
+
+## Import is not block reconstruction
+
+The managed WordPress importer deterministically stores cleaned HTML and shared
+references, without AI rewriting. That is a source-preserving intermediate step.
+The external agent rebuilds it into reviewed blocks/templates for either intent;
+`set_page_mode` does not perform conversion. Keep the complete source, map every
+in-scope content element, and do not silently truncate long pages. In preserve
+mode retain wording; in renew mode track approved rewrites and source facts.
+An import finishing does not mean design, block reconstruction or launch is done.
+
+## Old URLs must continue to work
+
+Inventory public URLs from sitemaps, CMS records, internal links, pagination and
+available traffic/backlink exports, including important assets and anchors.
+Record each old URL as preserved or redirected to a relevant working destination.
+Renewal may merge pages, but every old address still needs a meaningful mapping.
+Never blanket-redirect to the homepage or mark public content `excluded` merely
+to make coverage green. Private/admin/session noise can be excluded with a reason;
+retiring a public URL requires a separately agreed exception to this contract.
+
+Use `add_migration_urls` with `source_origin`, keep a per-URL mapping, and run
+`verify_migration_urls` against the authorized deployed candidate, then
+`get_migration_launch_report`. Check both slash forms, redirect chains/loops,
+query routes and fragments with their actual routing mechanism. DNS is not an
+HTTP redirect: changed hostnames need a host that continues serving redirects.
+A missing route or a 200 at unrelated content fails continuity in either path.
+Do not switch traffic until these checks pass and cutover is authorized.
 
 ## Gate 1: source baseline, before conversion
 
-Record the authoritative source URL/date, scope, relevant Core version, active
+Record the chosen intent, authoritative source URL/date, scope, relevant Core version, active
 Page templates and overrides. Inventory home, category/archive, long/short
 articles, downloads, empty related lists and each distinct business surface.
-Capture screenshots and computed geometry at matching actual `innerWidth`
+For preserve, capture source and target geometry; for renew, compare the target
+with the approved design while retaining source coverage evidence. Capture
+screenshots and computed geometry at matching actual `innerWidth`
 values (320/390/768/1024/1280/1536 where relevant, plus both sides of actual
 breakpoints). Record loaded font families/weights, color panels, logo/header,
 hero, gutters, article/sidebar widths, card anatomy/grid and footer. Inspect
@@ -42,9 +115,10 @@ back each prototype, then inspect its preview and an authorized static build.
 Example: a 48px heading uses `core/heading.font_size_px: 48` on Core 0.2.25+;
 read the saved block back and measure computed `fontSize` at 1280px. Writing
 `font_size_px` to `core/prose`, which does not declare it, is an unsupported
-mapping even if an API preserves that unknown key. Stop with
-`waiting_for_native_support` when required capability is absent or ignored;
-do not hide the gap with tenant CSS or generic custom blocks.
+mapping even if an API preserves that unknown key. A new presentation may use
+a reviewed custom type as described above. Missing or ignored declared behavior
+is a platform defect: stop that recipe with `waiting_for_native_support` and do
+not disguise the failure with tenant CSS.
 
 Validate shared Page references, item order, missing images and empty/unpublished
 references. Keep semantics separate from presentation: category emoji belongs
@@ -66,13 +140,12 @@ behavior or other semantics unsupported by the chosen block: record the gap
 and use a supported composition or stop for native support.
 Do not apply a template to hundreds of Pages until its prototype passes.
 
-## Report platform gaps, do not patch them
+## Distinguish custom presentation from platform defects
 
-Matching the source sometimes needs something the platform does not offer.
-Never close that with site or page `custom_css`, raw HTML or a generic custom
-block: the next site hits the same gap and the workaround breaks on the next
-Core change. Record it and report it instead. Check these five causes first,
-because each has looked like a site problem:
+A new layout or reusable visual component is a legitimate custom block, not
+necessarily a Core defect. Use the block hierarchy above. When a declared Core
+feature fails, do not cover it with site/page CSS, raw HTML or a replacement
+block. Record and report it. Check these five causes first:
 
 1. **A platform default no setting reaches.** Compare computed text rendering
    and base styles on `body`, links and headings (`-webkit-font-smoothing`,
@@ -99,7 +172,7 @@ block ID and type or the setting; source and target computed values; what is
 missing, ignored or wrong; the proposed setting or fix; and acceptance
 criteria a reviewer can measure. State that no workaround CSS is in place.
 Mark the affected recipe `waiting_for_native_support`, continue independent
-work, and verify against the source again after the release.
+work, and verify against the chosen acceptance reference after the release.
 
 ## Separate files, addresses and business behavior
 
@@ -176,13 +249,14 @@ pre-cutover scope honestly when DNS or integrations remain out of scope.
 
 The initial route census must combine source sitemaps, internal links, archive
 pagination, CMS inventory and known utility routes. Include homepage, archives,
-404/search behavior and routes outside the sitemap where present. Do not invent
-features absent from the source. Assign every route a recipe, template override,
+404/search behavior and routes outside the sitemap where present. In preserve mode, do not invent
+features absent from the source. In renew mode, include additions in the agreed brief. Assign every route a recipe, template override,
 composition or documented exception. Inventory the whole shell: content outside
 `main`, header, footer, service navigation and archive heroes are not optional.
 
-Derive required evidence from that census. Pair every in-scope source/target route
-at mobile and desktop; add each unique component, breakpoint and interaction
+Derive required evidence from that census. For preserve, pair every in-scope source/target route
+at mobile and desktop; for renew, compare every target route to its approved
+prototype and account for the source content/URL mapping; add each unique component, breakpoint and interaction
 state. Inspect page-specific media, lists, tables, embeds, CTAs, anchors and related
 content. One representative article cannot attest every article's content.
 
@@ -207,12 +281,13 @@ partial or template changes invalidate every dependent row; content changes
 invalidate that route and dependent listings. An old revision cannot approve a new
 one. Source availability failures remain `UNVERIFIED`, not silently excluded.
 
-Visual signoff requires zero uncovered required surfaces and zero unexplained
-regressions. `FAIL` or `UNVERIFIED` blocks that signoff, even when a separately scoped
+Visual signoff is against the chosen intent: source fidelity for preserve,
+approved design/content for renew. It requires zero uncovered required surfaces
+and zero unexplained regressions against that reference. `FAIL` or `UNVERIFIED` blocks that signoff, even when a separately scoped
 technical publication has approval. An intentional deviation needs exact before/
 after evidence, specific user benefit and accepted scope; “cleaner” is not a reason.
 
-Examples from a moving-services migration:
+Preserve-mode examples from a moving-services migration:
 
 | Surface | Passing evidence | Separate visual result |
 | --- | --- | --- |

package/skills/tr-seo.md

@@ -36,9 +36,10 @@ read_site_settings
 ```
 
 For each page, check:
-- Is `seo_title` set? (if not, Google uses `title` + suffix — often fine;
-  aim for 50–60 characters, longer gets truncated)
-- Is `seo_description` set? (150–160 chars, unique per page, includes keywords)
+- Does the rendered title accurately identify the page, including any suffix?
+- Is the description useful, specific and supported by the page's content?
+  Search snippets may be rewritten or truncated; fixed character counts are
+  not acceptance rules and must not cause padding or lost meaning.
 - Is `og_image` set for the homepage and key landing pages?
 - Does the page have exactly one `<h1>`?
 
@@ -53,7 +54,7 @@ batch_update_pages updates=[
 ```
 
 Guidelines:
-- 150–160 characters
+- Use the length needed for a clear, accurate summary; avoid padding
 - Include the most important keyword naturally
 - Make it a compelling reason to click, not a summary of the page's nav