@typeroll/mcp-server 0.29.0 → 0.32.0

package/skills/tr-migrate-wp.md

@@ -20,13 +20,43 @@ agency) reviews each step in their terminal.
 
 ## Preconditions
 
+**Run the readiness check FIRST — before touching any content:**
+
+```
+get_migration_readiness source_url="https://oldsite.com"
+```
+
+Pass `source_url` — that adds the checks on the site you're migrating FROM.
+An old host that answers 403/429 to server-side requests is a **blocker**: the
+import would produce empty pages, or pages containing the host's block page,
+which reads as real content and is worse. Whether `/wp-json` answers is a
+warning, since scraping is a real fallback (it just loses ACF/custom fields).
+
+If `ready` is false, STOP and report the blockers to the user. Do not start
+the import "and fix it after": every blocker is one whose failure is invisible
+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.
+
+Warnings are worth relaying but don't stop you: no verification origin (the
+pre-cutover parity check can't run), no AI reconstruction key, forms without a
+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`.
 - The source WP site has `/wp-json` reachable (Google for "wordpress
   REST API disabled" if not — common for hardened hosts).
-- The Typeroll target site exists. New, blank sites with the
-  starter design work best. 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.
+- The Typeroll target site exists **and already carries the design** —
+  settings, header/footer, one or two example pages. The migration rebuilds
+  old content in the NEW design; with nothing to imitate it inherits the old
+  site's look.
+- 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.
 
 ## Recipe
 
@@ -112,8 +142,43 @@ 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 in your notes (the customer
-should sign off on every dropped URL).
+intentionally dropped, mark it `excluded` via `update_migration_url` (the
+customer should sign off on every dropped URL).
+
+**Use wildcards for WordPress's URL families.** A WP site's dead URLs come in
+shapes, not as individuals — and the inventory only knows the ones it found,
+while the old site had more (paginated archives, feeds, attachment pages). One
+pattern rule retires the whole family:
+
+| WordPress shape | Rule |
+|---|---|
+| Category archives | `from_path="/category/*"` → `to_path="/blogg/:splat"` (or a single landing page) |
+| Tag archives | `from_path="/tag/*"` → `to_path="/blogg"` |
+| Author archives | `from_path="/author/*"` → `to_path="/om-oss"` |
+| Date-based permalinks | `from_path="/2019/*"` → `to_path="/blogg/:splat"` — one rule per year |
+| Old post prefix → new | `from_path="/blog/:slug"` → `to_path="/artiklar/:slug"` |
+| Feeds | `from_path="/feed/*"` → `to_path="/blogg"` |
+
+Rules:
+
+- **Trailing `*` only.** A mid-path splat (`/blog/*/comments`) is dropped
+  silently by Cloudflare — the platform refuses it at write time.
+- **`:splat`** carries the captured remainder; **`:name`** matches exactly one
+  segment and can be replayed by name.
+- **A pattern that would hide a live page is refused**, naming the pages. That
+  is the platform protecting you: redirects are applied before static files, so
+  `/blogg/*` would make every real article under `/blogg/` unreachable. Narrow
+  the prefix instead.
+- **Query-string URLs can't be matched.** WP's `/?p=123` has no path to key on;
+  those need handling at the source (or accept the loss and mark them excluded).
+- Rules are emitted most-specific-first, so a narrow rule always beats a broad
+  one — you can safely have `/blogg/recept/*` alongside `/blogg/*`.
+
+Then verify against reality before anything is cut over:
+
+```
+verify_migration_urls        # after trigger_deploy
+```
 
 ### 5. Preview + review with the user