@typeroll/mcp-server 0.37.0 → 0.38.1

package/AGENTS.md

@@ -268,8 +268,8 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
     styles (form-scoped CSS), kind and partial_ttl_days. On HTML-mode
     pages, `<x-form id="…" />` is expanded server-side through the same
     renderer and supports the same initial state and multi-step runtime.
-  - **Connector form bindings** (template_capabilities_version ≥ 0.37.0): a
-    trusted native Connector component can declare `form_bindings` and submit
+  - **Extension form bindings** (template_capabilities_version ≥ 0.38.0): a
+    trusted native Extension component can declare `form_bindings` and submit
     through `context.forms.submit(bindingId, data)`. Typeroll signs only the
     explicitly bound form, stores submissions in the ordinary Forms module,
     and calls the cloud or self-hosted Forms API directly. No Function is

package/README.md

@@ -86,10 +86,10 @@ client using it stops working immediately.
 | `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token. |
 | `TYPEROLL_SITE_ID`  | sometimes | Pin to a specific site. Required when using an org-scoped key over stdio (the install can only target one site at a time); auto-detected for site-scoped keys. |
 
-## Connector developer CLI
+## Extension developer CLI
 
 The package also installs `typeroll`. With an organization-scoped API key,
-an external Connector repository can use the same developer and installation
+an external Extension repository can use the same developer and installation
 APIs as the portal:
 
 ```sh

package/dist/bundled-content.js

@@ -14,7 +14,7 @@ export const BUNDLED_SKILLS = {
     "tr-header-footer": "---\nname: tr-header-footer\ndescription: Vetted, robust header and footer presets to drop into the header/footer partials. Use when building or restyling a site's site-wide header or footer — start from a preset and restyle it instead of hand-rolling layout + overflow (the usual source of clipped logos and broken mobile menus).\n---\n\n# Header & footer presets\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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\nHeaders and footers are the two partials every page shows, and hand-rolling them\nis where logos get clipped and mobile menus break. **Start from a preset below,\nfill the placeholders, restyle with the site's colours — don't build the layout\nfrom scratch.** Each preset is deliberately robust; the \"why\" notes call out the\ntraps it avoids.\n\n## How to use\n\n1. `read_site_settings` — grab `logo`, `site_name`, `tagline`, `contact.email`,\n   and the colour palette.\n2. `read_partial partial_id=\"header\"` (and `footer`) — see what's already there;\n   don't blow away a working one without reason.\n3. Pick a preset, replace every `{{PLACEHOLDER}}`, adjust colours to the palette\n   (the presets already read `--color-*` / `--font-heading` with fallbacks).\n4. `update_partial partial_id=\"header\" patch={ html_content: \"…\" } version=\"…\"`.\n5. **Preview and self-review in context** (see `tr-redesign-branch` step 6):\n   the logo must be FULLY VISIBLE (not clipped), legible against its background,\n   and the mobile layout must work at 390px. Screenshot the header region in\n   context — never the logo element in isolation (that hides clipping).\n\nPlaceholders: `{{SITE_NAME}}`, `{{LOGO_URL}}`, `{{TAGLINE}}`, `{{EMAIL}}`, `{{YEAR}}`.\n\n---\n\n## Header A — Centered logo (minimal; landing pages)\n\n```html\n<header class=\"tr-hdr tr-hdr--center\">\n  <a class=\"tr-hdr-logo\" href=\"/\" aria-label=\"{{SITE_NAME}} — till startsidan\">\n    <img src=\"{{LOGO_URL}}\" alt=\"{{SITE_NAME}}\" />\n  </a>\n</header>\n<style>\n.tr-hdr--center{background:var(--color-surface,#fff);display:flex;justify-content:center;padding:clamp(1rem,2.5vw,1.6rem) 1.5rem}\n.tr-hdr-logo{display:inline-block;line-height:0;transition:transform .15s ease}\n.tr-hdr-logo:hover{transform:translateY(-1px)}\n.tr-hdr-logo img{height:clamp(40px,6vw,58px);width:auto;display:block}\n</style>\n```\n\n**Why it's robust:** no `overflow:hidden` anywhere near the logo (the #1 cause of a\nclipped wordmark); the logo sizes by `height` with `width:auto` so it never\ndistorts and never gets cropped; symmetric padding so it can't collide with the\nsection below. If you want a tinted header, set a solid `background` — don't add a\nglow that has to be clipped.\n\n## Header B — Logo left + links right (no-JS responsive menu)\n\n```html\n<header class=\"tr-hdr tr-hdr--nav\">\n  <div class=\"tr-hdr-inner\">\n    <a class=\"tr-hdr-logo\" href=\"/\" aria-label=\"{{SITE_NAME}} — till startsidan\">\n      <img src=\"{{LOGO_URL}}\" alt=\"{{SITE_NAME}}\" />\n    </a>\n    <input type=\"checkbox\" id=\"tr-nav-toggle\" class=\"tr-nav-toggle\" aria-hidden=\"true\" />\n    <label for=\"tr-nav-toggle\" class=\"tr-nav-burger\" aria-label=\"Meny\"><span></span><span></span><span></span></label>\n    <nav class=\"tr-hdr-nav\" aria-label=\"Huvudmeny\">\n      <a href=\"/\">Start</a>\n      <a href=\"#\">Sidan ett</a>\n      <a href=\"#\">Sidan två</a>\n      <a class=\"tr-hdr-cta\" href=\"#kontakt\">Kontakta oss</a>\n    </nav>\n  </div>\n</header>\n<style>\n.tr-hdr--nav{background:var(--color-surface,#fff);border-bottom:1px solid rgba(0,0,0,.06)}\n.tr-hdr-inner{max-width:1160px;margin:0 auto;padding:.9rem 1.5rem;display:flex;align-items:center;justify-content:space-between;gap:1rem;flex-wrap:wrap}\n.tr-hdr-logo{line-height:0}\n.tr-hdr-logo img{height:clamp(36px,4.6vw,50px);width:auto;display:block}\n.tr-hdr-nav{display:flex;align-items:center;gap:clamp(1rem,2.4vw,2rem);font-family:var(--font-heading),sans-serif;font-weight:600}\n.tr-hdr-nav a{color:var(--color-text,#1a1a1a);text-decoration:none}\n.tr-hdr-nav a:hover{color:var(--color-primary,#1F4FB8)}\n.tr-hdr-cta{background:var(--color-primary,#1F4FB8);color:var(--color-primary-fg,#fff);padding:.6rem 1.2rem;border-radius:999px}\n.tr-hdr-cta:hover{filter:brightness(1.05);color:var(--color-primary-fg,#fff)}\n.tr-nav-toggle{display:none}\n.tr-nav-burger{display:none;flex-direction:column;gap:5px;cursor:pointer;padding:.4rem}\n.tr-nav-burger span{width:24px;height:2px;background:var(--color-text,#1a1a1a);border-radius:2px}\n@media(max-width:760px){\n  .tr-nav-burger{display:flex}\n  .tr-hdr-nav{flex-basis:100%;flex-direction:column;align-items:stretch;gap:.2rem;max-height:0;overflow:hidden;transition:max-height .25s ease}\n  .tr-hdr-nav a{padding:.7rem .2rem}\n  .tr-nav-toggle:checked ~ .tr-hdr-nav{max-height:60vh}\n}\n</style>\n```\n\n**Why it's robust:** the mobile menu is a pure-CSS checkbox toggle — no JS to break,\nno library. The `overflow:hidden` is ONLY on the collapsing nav list (never on the\nheader or the logo), so the logo is always fully visible. Links use site colour\nvariables so it matches the brand automatically. The header wraps (`flex-wrap`) so\nnothing overflows the viewport on narrow screens.\n\n---\n\n## Footer A — Centered minimal\n\n```html\n<footer class=\"tr-ftr tr-ftr--center\">\n  <div class=\"tr-ftr-inner\">\n    <div class=\"tr-ftr-brand\">{{SITE_NAME}}</div>\n    <p class=\"tr-ftr-tag\">{{TAGLINE}}</p>\n    <p class=\"tr-ftr-contact\"><a href=\"mailto:{{EMAIL}}\">{{EMAIL}}</a></p>\n    <p class=\"tr-ftr-copy\">© {{YEAR}} {{SITE_NAME}}</p>\n  </div>\n</footer>\n<style>\n.tr-ftr--center{background:var(--color-primary,#163C8C);color:rgba(255,255,255,.78)}\n.tr-ftr--center .tr-ftr-inner{max-width:1120px;margin:0 auto;padding:2.6rem 1.5rem;text-align:center;display:grid;gap:.45rem}\n.tr-ftr-brand{font-family:var(--font-heading),sans-serif;font-weight:800;font-size:1.35rem;color:#fff}\n.tr-ftr-tag{margin:0;font-size:1rem;color:rgba(255,255,255,.85)}\n.tr-ftr-contact{margin:.15rem 0 0}\n.tr-ftr-contact a{color:#fff;text-decoration:none;font-weight:600}\n.tr-ftr-contact a:hover{text-decoration:underline}\n.tr-ftr-copy{margin:.8rem 0 0;font-size:.85rem;color:rgba(255,255,255,.55)}\n</style>\n```\n\n## Footer B — Three columns (brand · links · contact)\n\n```html\n<footer class=\"tr-ftr tr-ftr--cols\">\n  <div class=\"tr-ftr-grid\">\n    <div class=\"tr-ftr-col\">\n      <div class=\"tr-ftr-brand\">{{SITE_NAME}}</div>\n      <p class=\"tr-ftr-tag\">{{TAGLINE}}</p>\n    </div>\n    <nav class=\"tr-ftr-col\" aria-label=\"Sidfot\">\n      <a href=\"/\">Start</a>\n      <a href=\"#\">Sidan ett</a>\n      <a href=\"#\">Sidan två</a>\n    </nav>\n    <div class=\"tr-ftr-col\">\n      <p class=\"tr-ftr-contact\"><a href=\"mailto:{{EMAIL}}\">{{EMAIL}}</a></p>\n    </div>\n  </div>\n  <p class=\"tr-ftr-copy\">© {{YEAR}} {{SITE_NAME}}</p>\n</footer>\n<style>\n.tr-ftr--cols{background:var(--color-primary,#163C8C);color:rgba(255,255,255,.78)}\n.tr-ftr--cols .tr-ftr-grid{max-width:1120px;margin:0 auto;padding:3rem 1.5rem 1.4rem;display:grid;grid-template-columns:1.4fr 1fr 1fr;gap:2rem}\n.tr-ftr--cols .tr-ftr-brand{font-family:var(--font-heading),sans-serif;font-weight:800;font-size:1.35rem;color:#fff;margin-bottom:.4rem}\n.tr-ftr--cols .tr-ftr-tag{margin:0;color:rgba(255,255,255,.8);max-width:34ch}\n.tr-ftr--cols .tr-ftr-col{display:grid;gap:.5rem;align-content:start}\n.tr-ftr--cols nav a{color:rgba(255,255,255,.85);text-decoration:none}\n.tr-ftr--cols nav a:hover{color:#fff;text-decoration:underline}\n.tr-ftr-contact a{color:#fff;text-decoration:none;font-weight:600}\n.tr-ftr--cols .tr-ftr-copy{max-width:1120px;margin:0 auto;padding:0 1.5rem 2.4rem;font-size:.85rem;color:rgba(255,255,255,.55)}\n@media(max-width:680px){.tr-ftr--cols .tr-ftr-grid{grid-template-columns:1fr;gap:1.4rem}}\n</style>\n```\n\n**Why these footers are robust:** the columns collapse to one at 680px (no\nhorizontal scroll); all colours come from `--color-*` with fallbacks; the contact\nis a real `mailto:` link; nothing relies on fixed heights. Swap `--color-primary`\nfor a custom dark if the brand's primary is too light for white text.\n\n---\n\n## Restyling notes\n\n- The logo always comes from `read_site_settings → logo`. If it's `null`, set it\n  first (upload + `update_site_settings`) — don't hard-code a path.\n- For a **shaped transition** from the header/footer into the page, don't build a\n  wave band by hand — that belongs to the adjacent `core/section` via its\n  `divider_top` / `divider_bottom` (see `tr-redesign-branch`).\n- Keep the brand mark + a way home. Even a dramatic redesign keeps the logo\n  linking to `/`.\n",
     "tr-imagegen": "---\nname: tr-imagegen\ndescription: Use when the user wants to generate images for a Typeroll site with AI models (Gemini, OpenAI, Higgsfield) — hero images, illustrations, section backgrounds, og-images. Triggers on \"generera bilder\", \"generate images\", \"skapa en hero-bild\", \"AI-bilder\", \"bildgenerering\", or when a brief calls for imagery that doesn't exist in assets/. Covers the local lab loop (generate → review → pick) and uploading winners to the Typeroll media library.\n---\n\n# Generate images for a Typeroll site (local lab → media library)\n\nImage generation runs **locally** in the site workdir — provider API keys\nlive in the folder's `.env`, candidates land in `images/lab/`, and only\nthe picked winners are uploaded to the Typeroll media library via the\nregular media tools (see `tr-images` for the upload/variants half).\n\nWhy local: you can look at the candidates (Read the files), iterate on\nprompts cheaply, and never ship a key or a reject anywhere.\n\n## Folder convention\n\n```\n<site>/\n├── .env                  # provider keys — GITIGNORED, never committed\n├── prompts/\n│   └── image-style.md    # the site's image style profile (see below)\n└── images/\n    └── lab/              # generated candidates — gitignored, disposable\n```\n\n`.env` keys (only the ones the user has — check before assuming):\n\n```\nGEMINI_API_KEY=...\nOPENAI_API_KEY=...\n```\n\n(Higgsfield needs no key here — it connects as an MCP server, see below.)\n\nLoad them per-command (`source .env` doesn't persist between Bash calls):\n\n```bash\nexport $(grep -v '^#' .env | xargs)   # prepend to each generation command\n```\n\n## The style profile — prompts/image-style.md\n\nEvery site gets ONE style profile that you **prepend to every image\nprompt**. This is what keeps 20 images generated across 5 sessions\nlooking like one site. Derive it from `assets/brand.md` + the brief if\nit doesn't exist yet, and confirm it with the user before generating at\nscale. Keep it short (5–10 lines): art direction, palette, mood,\nphotography vs illustration, what to avoid.\n\nExample shape:\n\n```markdown\n# Bildstil — <Sajtnamn>\nVarm, folklig illustration med mjuka rundade former. Platt 2D med\nsubtila skuggor — ingen 3D, ingen fotorealism. Palett: kobolt #1F4FB8,\nsol #FFC83D, grädde #FFF8EC; accenter sparsamt. Människor: enkla,\ninkluderande, glada — inga karikatyrer. Undvik: stockfoto-känsla, text\ni bilden, logotyper, watermarks.\n```\n\n## Generate candidates\n\nName candidates descriptively: `images/lab/<motiv>-<modell>-<n>.png`.\nGenerate 3–6 candidates per slot (mix models when several keys exist),\nthen **Read the files to actually look at them** before showing the\nuser your shortlist.\n\n### Gemini (gemini-2.5-flash-image)\n\n```bash\ncurl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent\" \\\n  -H \"x-goog-api-key: $GEMINI_API_KEY\" -H 'Content-Type: application/json' \\\n  -d '{\n    \"contents\": [{\"parts\": [{\"text\": \"<STYLE PROFILE>\\n\\n<MOTIF PROMPT>\"}]}],\n    \"generationConfig\": {\"imageConfig\": {\"aspectRatio\": \"16:9\"}}\n  }' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \\\n  | base64 -d > images/lab/hero-gemini-1.png\n```\n\nAspect ratios: `1:1`, `16:9`, `4:3`, `3:4`, `9:16`. Gemini also does\nimage *editing* — pass an existing image as an `inlineData` part plus an\ninstruction to restyle/extend it (useful for \"same illustration but\nwinter\").\n\n### OpenAI (gpt-image-1)\n\n```bash\ncurl -s https://api.openai.com/v1/images/generations \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" -H 'Content-Type: application/json' \\\n  -d '{\n    \"model\": \"gpt-image-1\",\n    \"prompt\": \"<STYLE PROFILE>\\n\\n<MOTIF PROMPT>\",\n    \"size\": \"1536x1024\",\n    \"quality\": \"high\"\n  }' | jq -r '.data[0].b64_json' | base64 -d > images/lab/hero-openai-1.png\n```\n\nSizes: `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait).\n\n### Higgsfield (MCP server — no API key)\n\nHiggsfield exposes its models through a hosted MCP server at\n`https://mcp.higgsfield.ai/mcp` (OAuth-protected — first connect opens a\nbrowser login; no secret lands in any file). Add it next to the\ntyperoll server in the site folder's `.mcp.json`:\n\n```json\n\"higgsfield\": { \"type\": \"http\", \"url\": \"https://mcp.higgsfield.ai/mcp\" }\n```\n\nThen use its tools directly — list what's available rather than\nassuming tool names. Save/download outputs into `images/lab/` with the\nsame naming convention, and prepend the style profile to prompts here\ntoo. **Headless caveat:** OAuth-protected MCP servers need an existing\nlogin session on the machine — connect once interactively before\nrelying on it in a headless run. (The same URL works as a custom\nconnector in Claude Desktop, for editors who don't use Claude Code.)\n\n## Review → pick → upload\n\n1. **Look at every candidate** (Read the image files) and write one line\n   per candidate in `build-log.md` (keep/reject + why).\n2. Show the user the shortlist (file paths) and let them pick — unless\n   they've delegated the pick to you.\n3. Upload winners with the regular media tools (see `tr-images`):\n   - small files → `upload_media_inline` (base64);\n   - larger → `create_upload_url` + HTTP PUT + `finalize_media`.\n   Give real `alt` text and a descriptive filename at upload time.\n4. `generate_image_variants` for responsive sizes when the image is\n   placed full-width.\n5. Place via `update_block` (`core/image`, hero fields, …) or page HTML.\n6. `images/lab/` is disposable — leave rejects there; never upload them.\n\n## Pitfalls\n\n- **Never put text in generated images** (headlines, buttons) — text is\n  HTML's job; generated text renders as gibberish in non-English. And\n  models sneak text onto surfaces where it \"feels natural\" — jerseys,\n  signs, banners, packages — even when the prompt doesn't ask for any.\n  Forbid it explicitly in the prompt (\"plain unmarked clothing, no\n  text, no letters, no numbers anywhere in the image\") and make the\n  same rule part of every site's style profile.\n- **Don't commit `.env` or `images/lab/`** — both are gitignored by the\n  kit convention; keep it that way.\n- **Cost discipline:** generation costs real money per image. Batch\n  thoughtfully (3–6 per slot, not 20), and reuse via Gemini's\n  edit-an-image mode instead of regenerating from scratch.\n- **Licensing/provenance:** AI-generated imagery is fine for site\n  decoration, but never generate fake \"photos\" of real people, products\n  the customer doesn't sell, or anything presented as documentary fact.\n- **The style profile is the contract.** If the user rejects a batch on\n  style grounds, fix `prompts/image-style.md` first, then regenerate —\n  don't just tweak one prompt.\n",
     "tr-images": "---\nname: tr-images\ndescription: Use when the user asks for an image, hero, illustration, or logo to be created and embedded in a Typeroll page. Covers the two-step signed-URL upload flow so the agent doesn't try to POST bytes through the CMS API (it can't).\n---\n\n# Add images to a Typeroll site\n\nThe Typeroll API does NOT accept image bytes directly. Uploads go\nthrough a signed PUT URL straight to Cloudflare R2, and the API only\nsees the metadata. Two-step flow:\n\n## Recipe\n\n### 1. Get an image\n\nOptions, in order of preference:\n\na. **Reuse an existing one.** `list_media` returns CDN URLs for every\n   image already on this site. Search the list before generating\n   anything — saves bandwidth and keeps the visual catalog tight.\n\nb. **Generate locally.** The user's Claude Code installation has\n   access to whatever image-gen tools they've configured (DALL-E,\n   Midjourney, Stable Diffusion, Replicate, etc.). Generate and save\n   to a tempfile.\n\nc. **Source from the web** with appropriate licensing (the user is\n   responsible for clearing rights). Save locally before upload.\n\n### 2. Mint a signed upload URL\n\n```\ncreate_upload_url filename=\"hero-services.png\"\n                  content_type=\"image/png\"\n                  size=<bytes>\n                  alt_text=\"Office worker reviewing documents at a desk\"\n```\n\nReturns:\n\n```json\n{\n  \"upload_url\": \"https://...r2.cloudflarestorage.com/.../signed-...\",\n  \"cdn_url\": \"https://cdn.example.com/orgs/.../images/...png\",\n  \"key\": \"orgs/.../images/...png\",\n  \"media_id\": \"abc123\",\n  \"expires_in\": 300\n}\n```\n\nThe signed URL is valid for 5 minutes. The media doc is already\nregistered — even before the upload completes — so it'll show in\n`list_media` immediately.\n\n### 3. PUT the bytes\n\nOutside the MCP, hit the signed URL directly:\n\n```\nPUT <upload_url>\nContent-Type: <same content_type as in step 2>\nBody: <file bytes>\n```\n\nIn a shell:\n\n```bash\ncurl -sS -X PUT --data-binary @hero-services.png \"$UPLOAD_URL\"\n```\n\nOptionally with `-H \"Content-Type: image/png\"` if you need to override what R2 will infer. **Nothing else.**\n\n> The signed URL embeds checksum-related query parameters\n> (`x-amz-checksum-crc32`, `x-amz-sdk-checksum-algorithm`) for legacy\n> SDK compatibility, but `X-Amz-SignedHeaders=host` — only the host\n> header is part of the signature. Sending the `x-amz-*` values as\n> request headers yields `403 SignatureDoesNotMatch`. Don't. Just\n> `--data-binary` the file at the URL.\n\nOr from JS (Claude Code can run a one-line script):\n\n```js\nawait fetch(uploadUrl, {\n  method: 'PUT',\n  headers: { 'Content-Type': contentType },\n  body: await fs.readFile(path),\n});\n```\n\nParallelise N uploads via shell `&` + `wait`:\n\n```bash\nwhile IFS=$'\\t' read -r filename signed_url; do\n  curl -sS -X PUT --data-binary @\"$filename\" \"$signed_url\" &\ndone < manifest.tsv\nwait\n```\n\nA 200 OK from R2 means the image is now live at `cdn_url`.\n\n### 4. Patch metadata (alt text, etc.)\n\nYou set `alt_text` at create time, but if you generate the image first\nand only THEN realize what to caption it as, patch later:\n\n```\nupdate_media media_id=<id> alt_text=\"...\" filename=\"hero-services-v2.png\"\n```\n\n### 4b. Fill missing alt-text on existing media\n\nWhen a customer has uploaded a bunch of images without alt-text (very\ncommon after a WP migration), don't make it up — use vision:\n\n```\nlist_media                                 → find items with empty alt_text\nsuggest_alt_text_context media_id=<id>     → returns { image_url, suggested_prompt,\n                                              language, used_on_pages, current_alt_text }\n# Pass image_url + the returned suggested_prompt to YOUR OWN vision\n# capability (you can fetch the URL and pass bytes to vision).\nupdate_media media_id=<id> alt_text=\"<what vision returned>\"\n```\n\nThe prompt is tuned for SEO-grade output: short (5-15 words), no \"image\nof / picture of\" filler, written in the site's content language,\ndecorative images return empty string. Run it sequentially on a\nlist_media batch and you can fix alt-text gaps across a whole site\nwithout burning your context on prompt design. The platform does NOT\nrun vision on your behalf — your model does, your usage.\n\n### 5. Embed in a page\n\n`read_page` the target, insert `<img>` in the right spot:\n\n```html\n<img src=\"<cdn_url>\"\n     alt=\"<alt_text>\"\n     style=\"width: 100%; height: auto; display: block; margin: 2rem 0;\" />\n```\n\nThen `update_page` with the new HTML. Or, if you're generating a hero\nfor a brand-new page, include the `<img>` directly in `create_page`'s\n`html_content`.\n\n## Pitfalls\n\n- **Always set `alt_text`.** Empty alt is bad for SEO + accessibility.\n  Default to a one-sentence description of what's in the image.\n- **`<script>` etc. in SVGs.** The page sanitizer drops `<script>`\n  inside SVG, so an icon set that includes script-based animations\n  won't render correctly. Use static SVG or a JPG/PNG export.\n- **CSS background-image references aren't dedup'd.** If you set the\n  same image as a CSS background on multiple pages, the alt-text +\n  metadata are page-irrelevant. The sanitizer allows\n  `background-image: url(...)` in inline styles, but think about\n  whether an `<img>` is actually better.\n- **Source URL leakage.** If you generated the image from a prompt\n  that contains internal info, don't bake that prompt into the\n  filename. Use a descriptive but generic filename.\n\n## Format choice\n\n- **PNG** for logos, icons with hard edges, anything with text.\n- **JPG** for photos. Smaller file, better for big hero images.\n- **WebP** if the target audience runs modern browsers (95%+ in 2026).\n- **SVG** for icons + simple illustrations. Vector scales perfectly.\n- **PDF** is supported by `create_upload_url` for document downloads;\n  link with `<a href>`, not `<img>`.\n",
-    "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> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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\nAvoid: pagination URLs, session URLs, `/wp-admin`, `/cdn-cgi/`, query strings.\n\n### 2. Learn the target's design\n\n```\nread_site_settings\nread_partial partial_id=\"header\"\nlist_pages limit=5\n```\n\nThe goal is to understand what CSS variables, class names, and structural\nconventions the target site uses so the imported content looks native.\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\nDiscard: nav, header, footer, cookie banners, chat widgets, scripts.\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. Skip tracking pixels\n(1×1 images), decorative SVGs that are just icons, and anything\nthat 404s.\n\n**d. Adapt to the target's design.**\nReplace source-specific CSS classes with target conventions.\nUse `var(--color-*)` for colors, `var(--font-*)` for type.\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",
+    "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> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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\nAvoid: pagination URLs, session URLs, `/wp-admin`, `/cdn-cgi/`, query strings.\n\n### 2. Learn the target's design\n\n```\nread_site_settings\nread_partial partial_id=\"header\"\nlist_pages limit=5\n```\n\nThe goal is to understand what CSS variables, class names, and structural\nconventions the target site uses so the imported content looks native.\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\nDiscard: nav, header, footer, cookie banners, chat widgets, scripts.\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. Skip tracking pixels\n(1×1 images), decorative SVGs that are just icons, and anything\nthat 404s.\n\n**d. Adapt to the target's design.**\nReplace source-specific CSS classes with target conventions.\nUse `var(--color-*)` for colors, `var(--font-*)` for type.\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",
     "tr-migrate-astro": "---\nname: tr-migrate-astro\ndescription: Use when the user wants to migrate an Astro site — particularly an Astro Content Collections-backed site — to Typeroll. Walks `src/content/<collection>/*.md(x)`, lifts frontmatter into Typeroll collection schemas, converts markdown bodies into richtext fields, batch-imports items, then maps `src/pages/*` into Typeroll pages/partials. Triggers on \"migrate an Astro site\", \"import from src/content\", \"convert content collections\", or when the user names a local Astro repo as the source.\n---\n\n# Migrate an Astro site to Typeroll\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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\nAstro's [Content Collections](https://docs.astro.build/en/guides/content-collections/) and Typeroll's `Collection` + `CollectionItem` map one-to-one. A collection in Astro is a directory of frontmatter-bearing files under `src/content/<name>/`; in Typeroll it's a schema + items doc set under `organizations/{org}/sites/{site}/collections/{name}/`. The Astro schema (`zod.object(...)` in `src/content/config.ts`) is your field list. The frontmatter values are field values. The markdown bodies are richtext fields.\n\nThis skill walks the migration from a checked-out Astro repo on the user's machine to a target Typeroll site. You run it locally — the source repo is on disk, the MCP just receives the final shape.\n\n## Preconditions\n\n- The Astro repo is checked out locally and `npm install`d (so we can read `src/content/config.ts` to extract the schemas).\n- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY` pointing at the target site (or org-scoped key + a `site_id` argument per call).\n- Target Typeroll site exists. **Empty starter site is best.** If non-empty, treat existing pages and collections as off-limits unless the user explicitly says otherwise.\n- The Astro design / theme is **not** being migrated — Typeroll has its own design layer. We migrate content; the user re-skins on the Typeroll side.\n\n## Recipe\n\n### 1. Map the source\n\nFrom the Astro repo root:\n\n```bash\nls src/content/                  # which collections exist?\ncat src/content/config.ts        # collection schemas (zod)\nls src/pages/                    # standalone pages\nls public/                       # static assets and images\n```\n\nBuild a working manifest:\n\n| Astro source | Typeroll target |\n|---|---|\n| `src/content/blog/*.md` | Collection `blog` with items |\n| `src/content/projects/*.mdx` | Collection `projects` with items |\n| `src/pages/about.astro` | Page with slug `about` |\n| `src/pages/services/[slug].astro` | If dynamic from a collection → that collection's `route_template`. If genuinely per-page → individual Typeroll pages. |\n| `public/og/*.png`, `public/images/*` | Upload to Typeroll media via `upload_media_from_url` (after staging them on a temporary public URL) or via local upload if the MCP supports it. |\n| `src/layouts/*.astro` | Header / footer / shared chunks → Typeroll partials. The rest of the layout is the site design, owned by the target site. |\n| `src/components/*.astro` | Either become partials (if reused across pages) or get inlined into the page that uses them. |\n\n### 2. Learn the target's design (don't skip)\n\n```\nget_site\nread_site_settings           # colours, fonts, voice\nlist_partials\nread_partial partial_id=\"header\"\nlist_pages limit=5\n```\n\nSame rule as in `tr-migrate-wp`: you're moving content into the *target's* visual language, not preserving the source's. Note the existing fonts, colour vars, header structure.\n\n### 3. Translate one collection schema\n\nPick the most representative collection first (usually `blog`). Read its zod schema:\n\n```ts\n// src/content/config.ts\nconst blog = defineCollection({\n  type: 'content',\n  schema: z.object({\n    title: z.string(),\n    description: z.string(),\n    pubDate: z.coerce.date(),\n    updatedDate: z.coerce.date().optional(),\n    heroImage: z.string().optional(),\n    author: z.string().default('Editorial'),\n    tags: z.array(z.string()).default([]),\n    draft: z.boolean().default(false),\n  }),\n});\n```\n\nMap zod types to Typeroll field types:\n\n| Astro zod | Typeroll field type |\n|---|---|\n| `z.string()` | `text` (or `textarea` if it's a description/excerpt — judge by typical length) |\n| `z.string().long()` / a description field | `textarea` |\n| `z.coerce.date()` / `z.date()` | `date` |\n| `z.number()` | `number` |\n| `z.boolean()` | `boolean` |\n| `z.string()` with image path / `image()` helper | `image` |\n| `z.array(z.string())` | `text` (comma-joined) or `tags` if you have a tags field type |\n| `z.enum([...])` | `text` with a comment about the allowed values; the model writes the listing logic |\n| `z.object({...})` (nested) | Flatten into prefixed fields, or pre-render into a `*_html` field (see `tr-collection-template`) |\n| Markdown body | `body: richtext` (the markdown content of the file, converted to HTML — see §4) |\n\nCreate the collection with the design template baked in (this is the new pattern — read `tr-blog` if you haven't yet):\n\n```\ncreate_collection {\n  \"name\": \"blog\",\n  \"label_singular\": \"Article\",\n  \"label_plural\": \"Articles\",\n  \"slug_field\": \"slug\",\n  \"sort_field\": \"date\",\n  \"sort_dir\": \"desc\",\n  \"route_template\": \"/blog/{slug}\",\n  \"fields\": [\n    {\"name\":\"title\",       \"type\":\"text\",     \"required\":true},\n    {\"name\":\"slug\",        \"type\":\"text\",     \"required\":true},\n    {\"name\":\"description\", \"type\":\"textarea\"},\n    {\"name\":\"date\",        \"type\":\"date\",     \"required\":true},\n    {\"name\":\"updated_date\",\"type\":\"date\"},\n    {\"name\":\"hero_image\",  \"type\":\"image\"},\n    {\"name\":\"author\",      \"type\":\"text\"},\n    {\"name\":\"tags\",        \"type\":\"text\"},\n    {\"name\":\"body\",        \"type\":\"richtext\"}\n  ],\n  \"item_template_html\": \"<article class=\\\"post\\\">...</article>\"\n}\n```\n\nField-name rules: ASCII, lowercase, `[a-z][a-z0-9_-]*`. The Astro source `pubDate` → Typeroll `date`. `updatedDate` → `updated_date` (snake_case is fine; camelCase isn't).\n\n### 4. Convert markdown bodies → richtext\n\nAstro stores the markdown body as the file content after the `---` frontmatter fence. Typeroll's `body: richtext` wants HTML. Pick one of:\n\n**Option A — use Astro's own markdown renderer (preferred when the repo already builds):**\n\n```js\nimport { unified } from 'unified';\nimport remarkParse from 'remark-parse';\nimport remarkRehype from 'remark-rehype';\nimport rehypeStringify from 'rehype-stringify';\n\nconst md2html = async (md) => {\n  const file = await unified()\n    .use(remarkParse)\n    .use(remarkRehype, { allowDangerousHtml: true })\n    .use(rehypeStringify, { allowDangerousHtml: true })\n    .process(md);\n  return String(file);\n};\n```\n\nRun this on the body of every collection file. Image references inside the markdown (`![alt](./hero.png)`) need their `src` rewritten to the uploaded Typeroll CDN URLs after step 6.\n\n**Option B — convert ad-hoc:** `marked`, `markdown-it`, or any other parser. Just stay consistent across files so the HTML output looks uniform.\n\nTyperoll's sanitiser will strip `<script>` and event handlers from the output regardless. If the markdown carried embedded raw HTML you want to keep (iframes for video, etc.), check the sanitiser config in `packages/site-template/src/lib/sanitize.ts` for the whitelist.\n\n### 5. Resolve and upload images\n\nFor every image referenced by an item (`heroImage`, images inside the markdown body):\n\n1. Stage the local file at a temporary public URL (or use a local-upload MCP tool if one is configured).\n2. `upload_media_from_url url=<staged-url> alt=<from frontmatter or filename>` — record the returned CDN URL.\n3. Substitute the CDN URL into both the `hero_image` field value AND the markdown-converted HTML body (regex replace `src=` references).\n\nKeep a local map (`./astro-migration-state.json`):\n\n```json\n{\n  \"media\": {\n    \"./hero.png\": \"https://cdn.typeroll.com/<orgId>/<siteId>/abc123.png\"\n  }\n}\n```\n\nSo a partial run is resumable and you don't re-upload the same image twice.\n\n### 6. Batch-import items\n\nFor each file in `src/content/<collection>/`:\n\n```js\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport matter from 'gray-matter';\n\nconst files = fs.readdirSync('src/content/blog').filter(f => /\\.mdx?$/.test(f));\nfor (const file of files) {\n  const raw = fs.readFileSync(`src/content/blog/${file}`, 'utf8');\n  const { data, content } = matter(raw);\n  const slug = file.replace(/\\.mdx?$/, '');\n  const body = await md2html(content);\n\n  // create_collection_item via the MCP\n  await mcp.callTool('create_collection_item', {\n    collection: 'blog',\n    status: data.draft ? 'draft' : 'published',\n    fields: {\n      title:        data.title,\n      slug,\n      description:  data.description,\n      date:         data.pubDate ? new Date(data.pubDate).toISOString().slice(0, 10) : null,\n      updated_date: data.updatedDate ? new Date(data.updatedDate).toISOString().slice(0, 10) : null,\n      hero_image:   mediaMap[data.heroImage] || data.heroImage,\n      author:       data.author,\n      tags:         (data.tags || []).join(', '),\n      body,\n    },\n  });\n}\n```\n\nRate-limit awareness: spawn at most 5 parallel `create_collection_item` calls; the API caps at ~60 writes/minute and responds with 429 + `Retry-After` if exceeded.\n\nSet `status: 'draft'` (or honour Astro's `draft: true` frontmatter) for items the user should review before publishing. Only published items get static pages.\n\n### 7. Build the listing page\n\n```\ncreate_page title=\"Blog\" slug=\"blog\" status=\"published\" content_mode=\"html\"\n  html_content=\"<section><h1>Blog</h1>\n  <!-- typeroll:listing:blog -->\n  <!-- /typeroll:listing:blog -->\n</section>\"\n\nregenerate_collection_listing\n  collection=\"blog\"\n  page_id=\"blog\"\n  item_template=\"<article class=\\\"blog-card\\\"><a href=\\\"{{url}}\\\"><h2>{{title}}</h2><p>{{description}}</p><time>{{date}}</time></a></article>\"\n  wrap_open=\"<div class=\\\"blog-grid\\\">\"\n  wrap_close=\"</div>\"\n```\n\nSee `tr-blog` for full styling and post-import update flow.\n\n### 8. Translate standalone pages\n\nFor each non-dynamic `.astro` page under `src/pages/`:\n\n```\nread_partial partial_id=\"header\"          # learn target's nav style\n# Re-skin the page content using target site's CSS variables and partials.\ncreate_page title=\"About\" slug=\"about\" status=\"draft\" content_mode=\"html\"\n  html_content=\"...\"\n```\n\nDefault to **draft** — the user reviews each page before publishing.\n\nFor dynamic Astro pages (`[slug].astro` that consume a collection), you're already done: the matching Typeroll collection's `route_template` produces the same URLs at build time.\n\n### 9. Add redirects for URL changes\n\nIf Astro's slugs differed from what you derived for Typeroll (e.g. Astro had `/posts/my-article` but you want `/blog/my-article`), bulk-add redirects:\n\n```\nadd_redirect from=\"/posts/my-article\" to=\"/blog/my-article\" status=301\n```\n\nOr build a redirect map from the `astro-migration-state.json` and apply it in one pass.\n\n### 10. Deploy\n\n```\ntrigger_deploy\nget_deploy_status job_id=<id>\n```\n\nBrowse the resulting site, compare against the Astro source, surface anything that drifted.\n\n## Astro-specific gotchas\n\n- **`.mdx` files with custom components.** Components inside MDX (`<MyCustom prop=\"...\" />`) will not render in Typeroll because the component definitions don't migrate. Two options: (1) replace each component with its rendered HTML output (run the Astro build, scrape the rendered HTML, use that as `body`); (2) if the component is a reusable visual element used across many items, factor it into a Typeroll partial and replace MDX usages with `<x-include name=\"...\" />` calls. See `tr-page-template` for the partial-include pattern.\n- **`src/content/config.ts` typed `image()` helper.** Astro resolves `image()` fields at build time to optimised assets. After migration the Typeroll `hero_image` field carries the original source URL — re-upload via step 5 to get it onto the Typeroll CDN.\n- **`getCollection` filters at runtime.** If `src/pages/blog/index.astro` does `getCollection('blog', ({ data }) => !data.draft)`, Typeroll handles this via `status` on the item. Don't translate the filter — set `status: 'draft'` on items where `data.draft === true`.\n- **Per-tag pages (`/blog/tag/[tag].astro`).** Typeroll doesn't auto-generate these. Either (a) drop tag pages and use a client-side filter in the blog listing JS, (b) generate them by enumerating unique tags and calling `create_page` per tag with a server-side-pre-filtered listing. (a) is preferable for ≤dozens of tags.\n- **`rehype-pretty-code` / shiki / fenced code with syntax highlighting.** The HTML output of these contains inline styles that the Typeroll sanitiser preserves. The colours match the Astro site's theme at import time; redoing the target design later means re-running the highlighter against the same markdown source. Keep a copy of the raw markdown if you might.\n- **`og:image` per page from `astro-og-image` style plugins.** Typeroll has its own SEO surface (`seo_title`, `seo_description`, `seo_og_image`). Set them explicitly on each page during step 8.\n- **i18n via `src/content/<lang>/<collection>/`.** Typeroll's site-level `default_language` + per-page `language` field cover this (capabilities: `supports_language_per_page: true`). Map each language directory to per-item `language: 'sv-SE' | 'en-US' | …` instead of separate collections.\n\n## Mixing imported + new content\n\nHalf-migrate, leave drafts, let the user inspect, iterate. You can:\n\n- Import only collections, skip standalone pages, let the user rebuild those from scratch.\n- Import everything as `status: 'draft'`, treat publishing as a per-item human review pass.\n- Mix sources: pull article bodies from Astro markdown, use Claude to generate fresh excerpts/SEO metadata before writing the item.\n\nKeep the local `astro-migration-state.json` honest — it's the only way to make a partial run resumable when the API rate-limits or a markdown parser trips on an edge case file.\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> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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 redirects at the DNS\n  level, not just inside a site.\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\" domain=\"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\nDesign travels as a block-type package, not by hand:\n\n```\nexport_block_types site_id=<reference>                 # → .tcblocks JSON\nimport_block_types site_id=<other> package=<that JSON>\n```\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 — Migrate content, preserving paths\n\nPer site, per URL, follow `tr-migrate-wp` §3. Two rules that matter more here\nthan in a single-site migration:\n\n1. **Preserve the path verbatim** unless there's a reason not to. Use\n   `path` for anything nested: `create_page title=\"Über uns\" slug=\"ueber-uns\"\n   path=\"/ueber-uns\"`. A preserved path needs no redirect and loses nothing.\n2. **Rewrite internal links to the NEW paths.** Imported HTML is full of\n   absolute links to the old domain. Sweep them per site:\n\n```\nbulk_replace_text site_id=<de-site> find=\"https://example.de/\" replace=\"/\" dry_run=true\n```\n\nCheck the dry-run count against what you expect before running it for real.\nCross-domain links between sister sites stay absolute — only the site's own\ndomain becomes relative.\n\n### Media: per site, not shared\n\nEvery Typeroll site has its own media library, so a shared asset (the group\nlogo, a product shot used in all markets) is uploaded once **per site** and\ngets a different CDN URL in each. That's correct — the sites are independent\nand one market's deploy must not depend on another's assets — but it means:\n\n- Don't try to reuse a `cdn_url` from site A inside site B's HTML. It will\n  render, and it will break the day site A is deleted or moved.\n- Do write alt text per market, in that market's language:\n  `update_media media_id=… alt_text=\"…\"`. The alt text is content, not\n  metadata, and a Swedish alt on a German page is a real accessibility defect.\n\nImages referenced only from a stylesheet or from unrendered page-builder JSON\nare NOT found by an HTML scan. Spot-check the hero/background images of the\ntop pages in the preview before you call a site done.\n\n### Forms are NOT migrated — plan to rebuild them\n\nThe HTML cleaner strips `<form>`, `<input>`, `<select>` and `<button>`\nentirely, on purpose: a Contact Form 7 / Gravity / Elementor form posts to\nWordPress endpoints that no longer exist, so importing the markup would give\nyou a form that looks alive and silently drops every submission.\n\nSo, per site:\n\n```\ncreate_form name=\"Kontakt\" fields=[…]         # or steps=[…] for a funnel\nadd_block target={kind:'page', id:'kontakt'} block={type:'core/form', data:{form_id:'<id>'}}\n```\n\nThen, still per site:\n\n- **Recipient address per market** — the German enquiries rarely go to the\n  Swedish inbox. Check this explicitly; it is the single most common thing\n  to get wrong in a batch of ten.\n- **Email delivery is configured per site** by an admin in the portal\n  (Settings → Integrations), not through this API. Flag it to the user as a\n  manual step — a form that saves submissions but sends no notification looks\n  fine in testing and loses leads in production.\n- **Submit a real test through every form** after deploy, and confirm both the\n  stored submission and the notification email.\n\nCount the old site's forms during Phase 1 and put them in the plan table.\nTen sites × three forms is thirty forms, and it is the part of the job that\nnever shows up in a URL inventory.\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\n**Clear the URL families with one rule each**, per site — a WP network\nmultiplies the same dead shapes across every market:\n\n```\ncreate_redirect site_id=<de-site> from_path=\"/category/*\" to_path=\"/blogg/:splat\"\ncreate_redirect site_id=<de-site> from_path=\"/tag/*\"      to_path=\"/blogg\"\ncreate_redirect site_id=<de-site> from_path=\"/2019/*\"     to_path=\"/blogg/:splat\"\n```\n\nOnly a TRAILING `*` is supported (`:splat` replays the remainder); `:name`\nmatches one segment. Pattern-covered inventory URLs count as `redirected`, so\nthe work list actually empties. A pattern that would hide a live page is\nrefused, naming the pages — narrow the prefix rather than working around it.\n\nWatch the per-market prefixes: the German site's archive base is `/kategorie/`,\nnot `/category/`. Write the rules from each site's own inventory, never by\ncopying the reference site's.\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 shows up as noise in the inventory rather than as a migration\nfailure — mark those `excluded`.\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. Spot-check the top\n`gsc_clicks` URLs by eye.\n\nIterate until `missing` and `broken_redirect` are both zero **on every site**.\nThen, per site:\n\n1. `add_domain` / follow the DNS instructions the platform returns\n2. Point DNS\n3. `poll_domain` until verified → `activate_domain`\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\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- [ ] `verify_migration_urls` → 0 `missing`, 0 `broken_redirect`\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- [ ] Forms rebuilt, recipient address correct for THIS market, test submission sent and received\n- [ ] Media uploaded to this site's own library (no cross-site `cdn_url`), alt text in this market's language\n- [ ] Domain verified + activated; sitemap submitted\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",
     "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, rebuilds pages in the target site's design, transfers media, sets redirects, leaves everything as drafts for human review.\n---\n\n# Migrate from WordPress to Typeroll\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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 (consultant /\nagency) 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\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), no AI reconstruction key, 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 Typeroll target site exists **and already carries the design** —\n  settings, header/footer, one or two example pages. The migration rebuilds\n  old content in the NEW design; with nothing to imitate it inherits the old\n  site's look.\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. Learn the target's design\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. Migrate 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:\n   - For each `<img src>` and CSS `background-image: url()`:\n     1. Download the source image locally.\n     2. `create_upload_url filename=... content_type=...` → returns\n        `{ upload_url, cdn_url, media_id }`.\n     3. PUT the bytes to `upload_url` (curl or fetch with the same\n        content type).\n     4. Replace the `src` with `cdn_url` in the rewritten HTML.\n   - Use `update_media media_id=... alt_text=\"...\"` to set a real alt\n     text (existing WP `alt` attribute or `aria-label`; fall back to\n     filename only as a last resort).\n\nd. Reconstruct in the target's design. The cleaned HTML is rarely\n   ready to ship — typical fixes: replace WP `wp-block-*` classes\n   with the target's CSS variables; turn Elementor sections into\n   plain `<section>` with the target's spacing; fix headings so the\n   page has exactly one `<h1>`. If you're confident, batch these\n   through `bulk_replace_text` with `dry_run: true` first.\n\ne. Write the page as a draft:\n\n   ```\n   create_page title=\"...\" slug=\"<preserved-from-wp>\"\n               html_content=\"<reconstructed>\"\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/` go in as `slug: \"2024/01/foo-bar\"`. The\n   slug supports slashes; encode the WP permalink structure verbatim\n   when the customer wants existing links to keep working.\n\n### 4. 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\n**Use wildcards for WordPress's URL families.** A WP site's dead URLs come in\nshapes, not as individuals — and the inventory only knows the ones it found,\nwhile the old site had more (paginated archives, feeds, attachment pages). One\npattern rule retires the whole family:\n\n| WordPress shape | Rule |\n|---|---|\n| Category archives | `from_path=\"/category/*\"` → `to_path=\"/blogg/:splat\"` (or a single landing page) |\n| Tag archives | `from_path=\"/tag/*\"` → `to_path=\"/blogg\"` |\n| Author archives | `from_path=\"/author/*\"` → `to_path=\"/om-oss\"` |\n| Date-based permalinks | `from_path=\"/2019/*\"` → `to_path=\"/blogg/:splat\"` — one rule per year |\n| Old post prefix → new | `from_path=\"/blog/:slug\"` → `to_path=\"/artiklar/:slug\"` |\n| Feeds | `from_path=\"/feed/*\"` → `to_path=\"/blogg\"` |\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  those need handling at the source (or accept the loss and mark them excluded).\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```\nverify_migration_urls        # after trigger_deploy\n```\n\n### 5. Preview + review with the user\n\n```\nget_preview_link page_id=<id>                    # one URL the user can click\n```\n\nOpen in the user's browser. The preview navigates the whole site from\none mint. Iterate on feedback: pages, header, footer.\n\n### 6. 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",
@@ -25,6 +25,6 @@ export const BUNDLED_SKILLS = {
     "tr-seo": "---\nname: tr-seo\ndescription: Use when the user asks to improve SEO, fix meta tags, add structured data, check page titles, or audit the site's search visibility. Triggers on \"SEO\", \"meta descriptions\", \"Google ranking\", \"structured data\", \"JSON-LD\", \"sitemap\", \"sökoptimering\", or \"hjälp mig synas på Google\".\n---\n\n# SEO audit and improvements for a Typeroll site\n\n> **The buffer model (draft writes).** Every content write in this recipe\n> (pages, blocks, partials, collection items) 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## What Typeroll handles automatically\n\n- `<html lang>` from site `language` setting (per-page override via `language` field)\n- `<title>` = `page.seo_title || page.title + settings.default_seo_suffix`\n- `<meta name=\"description\">` from `page.seo_description`\n- `<meta name=\"robots\">` from `page.noindex`\n- `<meta property=\"og:*\">` Open Graph tags from seo_title, seo_description, og_image\n- `<link rel=\"canonical\">` from `page.canonical_url` (falls back to the page's own URL)\n- Article schema from `kind: \"article\"` + `author` + `date_published`\n- Page schema from `kind: \"page\"` (default)\n- `robots.txt` from `settings.robots_txt`\n- Sanitized HTML that preserves semantic structure\n\n## Recipe\n\n### 1. Audit current state\n\n```\nlist_pages status=\"all\"\nread_site_settings\n```\n\nFor each page, check:\n- Is `seo_title` set? (if not, Google uses `title` + suffix — often fine)\n- Is `seo_description` set? (150–160 chars, unique per page, includes keywords)\n- Is `og_image` set for the homepage and key landing pages?\n- Does the page have exactly one `<h1>`?\n\n### 2. Fix missing meta descriptions\n\n```\nbatch_update_pages updates=[\n  {page_id: \"home\",     patch: {seo_description: \"Acme designar rum...\"}},\n  {page_id: \"om-oss\",   patch: {seo_description: \"Vi är ett...\"}},\n  {page_id: \"tjanster\", patch: {seo_description: \"Våra tjänster...\"}}\n]\n```\n\nGuidelines:\n- 150–160 characters\n- Include the most important keyword naturally\n- Make it a compelling reason to click, not a summary of the page's nav\n\n### 3. Fix page titles\n\nSEO title = what Google shows in search results.\n\nIf `settings.default_seo_suffix` is set (e.g. \" — Acme Studio\"), every\npage whose `seo_title` is empty will show `title + suffix`. That's usually\nfine for inner pages; set an explicit `seo_title` only when you want\nsomething different.\n\n```\nupdate_site_settings {\"default_seo_suffix\": \" — Acme Studio\"}\n\nupdate_page page_id=\"home\" patch={\n  \"seo_title\": \"Acme Studio — Inredningsdesign i Stockholm\"\n}\n```\n\n### 4. Add Open Graph images\n\nSet `og_image` on pages that get shared on social media. If the site has\na branded hero image, upload it:\n\n```\nupload_media_from_url url=\"https://...\" alt=\"Acme Studio — Inredningsdesign\"\n# → returns cdn_url\n\nbatch_update_pages updates=[\n  {page_id: \"home\",     patch: {og_image: \"<cdn_url>\"}},\n  {page_id: \"om-oss\",   patch: {og_image: \"<cdn_url>\"}}\n]\n```\n\nOG image dimensions: 1200×630px ideal. The platform doesn't resize —\nuse a correctly-sized source image.\n\n### 5. Add structured data (JSON-LD)\n\nTyperoll auto-generates Article and Page schema, but you can override or\nextend with custom JSON-LD per page. Example: LocalBusiness on the homepage.\n\n```\nupdate_page page_id=\"home\" patch={\n  \"json_ld\": \"{\\\"@context\\\":\\\"https://schema.org\\\",\\\"@type\\\":\\\"LocalBusiness\\\",\\\"name\\\":\\\"Acme Studio\\\",\\\"url\\\":\\\"https://acme.se\\\",\\\"telephone\\\":\\\"+46812345\\\",\\\"address\\\":{\\\"@type\\\":\\\"PostalAddress\\\",\\\"streetAddress\\\":\\\"Drottninggatan 1\\\",\\\"addressLocality\\\":\\\"Stockholm\\\",\\\"postalCode\\\":\\\"111 51\\\",\\\"addressCountry\\\":\\\"SE\\\"}}\"\n}\n```\n\n**Important:** JSON-LD goes in the `json_ld` field as a JSON *string*\n(not a nested object). The renderer injects it inside\n`<script type=\"application/ld+json\">`.\n\nCommon schemas worth adding:\n- Homepage: `LocalBusiness` or `Organization`\n- About: `AboutPage`\n- Contact: `ContactPage`\n- Blog articles: auto-generated from `kind:\"article\"` + `author`\n- Events: `Event` with `startDate`, `location`\n- Products: `Product` with `offers`\n\n### 6. robots.txt\n\nThe default robots.txt allows all crawlers. Update if needed:\n\n```\nupdate_site_settings {\n  \"robots_txt\": \"User-agent: *\\nAllow: /\\nSitemap: https://acme.se/sitemap.xml\"\n}\n```\n\nTyperoll doesn't generate a sitemap automatically in phase 1. If the\ncustomer needs one, create a `/sitemap` page with HTML that lists all\npublished pages, or write a static `sitemap.xml` as a page with\n`slug: \"sitemap.xml\"` and HTML-encoded XML (not recommended for large sites).\n\n### 7. Canonical URLs\n\nSet `canonical_url` when a page has a duplicate (e.g. the same content\naccessible via two slugs after a migration):\n\n```\nupdate_page page_id=\"tjansterna\" patch={\n  \"canonical_url\": \"https://acme.se/tjanster\",\n  \"noindex\": true\n}\n```\n\n### 8. Language settings\n\n```\nupdate_site_settings {\"language\": \"sv\"}\n```\n\nPer-page override for multilingual content:\n```\nupdate_page page_id=\"about-en\" patch={\"language\": \"en\"}\n```\n\n### 9. Heading audit\n\nUse `search_pages` to find structural problems:\n\n```\nsearch_pages contains=\"<h1\"      # pages that have at least one H1\n```\n\nThen `read_page` on pages that seem to have none or multiple. Fix via\n`update_page patch={html_content: \"<corrected HTML>\"}`.\n\n### 10. Deploy\n\n```\ntrigger_deploy\nget_deploy_status job_id=<id>\n```\n\n## Pitfalls\n\n- **Don't stuff keywords.** Write descriptions for humans. Google ignores\n  `<meta name=\"keywords\">` (not a field in Typeroll anyway).\n- **JSON-LD is a string, not a nested field.** Pass the entire schema as\n  a JSON-encoded string in `json_ld`. The server escapes `</script` before\n  injection.\n- **OG images need absolute URLs.** The `cdn.typeroll.com` URLs are always\n  absolute — use those.\n- **`canonical_url` + `noindex` together.** If you noindex a page AND set\n  canonical, the canonical is redundant (noindexed pages don't pass equity).\n  Use one or the other.\n- **Default suffix on homepage looks odd.** \"Acme Studio — Acme Studio\"\n  happens when title=\"Acme Studio\" and suffix=\" — Acme Studio\". Set an\n  explicit `seo_title` for the homepage.\n"
 };
 export const BUNDLED_DOCS = {
-    "agents": "# AGENTS.md — Working on a Typeroll site\n\nYou are connected to a Typeroll site through `@typeroll/mcp-server`.\nThis file is your briefing: what the system is, what conventions matter,\nwhat tools to reach for first.\n\nIf anything below conflicts with what you observe in the tools, trust the\ntools — the platform may have moved since this was written.\n\n**Start here for site-shaped tasks.** When the user wants to build,\nmigrate, redesign, or brand a site, call `list_skills` first — the server\nadvertises its own step-by-step playbook (`tr-new-site`, `tr-migrate-wp`,\n`tr-brand`, …). Then `read_skill name=…` loads the full recipe. These are\nlocal reads; no API key or site context required.\n\n**Branch first for anything larger than a small edit.** Before a redesign,\na multi-page change, or trying out a new design direction, run\n`create_branch name=\"…\"` and pass the returned id as `version=<id>` on every\nsubsequent read/write. The work stays off the live `main` version until you\n`merge_branch` it — nothing ships until you decide it should. Branches default\n`robots_blocked:true` and get their own deploy URL for stakeholder review.\nIt's the cheapest insurance there is; when in doubt, branch. The\n`tr-redesign-branch` skill walks the whole flow. (Small, low-risk single edits\ncan go straight to main.)\n\n## What this is\n\nTyperoll is a static-site CMS: content lives in a database, the user\nedits it through an in-app editor, and a deploy step compiles everything\nto a fast static site hosted on Cloudflare Pages. The in-app chat handles\nsingle-page or single-block edits by the editor audience. You — through\nthis MCP — handle the work that doesn't fit there: site-wide redesigns,\nbulk content updates, structural migrations, directory imports.\n\nThe MCP server is a thin wrapper around the public REST API. Each tool\nmaps to one HTTP endpoint; the actual logic runs in the customer's portal\n(SaaS or self-hosted).\n\n## The data model in 90 seconds\n\n- **Pages.** Title, slug, status (`draft | review | unlisted | published`),\n  body content + SEO fields. Two body shapes selectable per page via\n  `content_mode`:\n  - `blocks` (DEFAULT for new pages) — `blocks: Block[]` tree of typed\n    blocks (heading, prose, section, columns, image, button, plus any\n    user/third-party block types installed on the site). Use the\n    block-mutation tools (`add_block`, `update_block`, `move_block`,\n    `remove_block`) for structural changes.\n  - `html` — body lives in `html_content` as a single HTML string.\n    Useful when you have hand-written markup to drop in directly.\n\n  Slug is a single path segment — no slashes. `about` → `/about`,\n  `kontakt` → `/kontakt`, empty string `\"\"` → homepage. The v1 API\n  rejects `services/design` and other slash-containing slugs with\n  \"Invalid slug … slugs must not contain slashes.\" For nested URLs\n  like `/blog/{slug}` or `/services/{slug}`, the right primitive is a\n  **collection with `route_template`** (see the `tr-blog` and\n  `tr-directory` skills) — not a flat page with a slashed slug.\n\n- **Partials = global blocks.** Three kinds:\n  - `header` — auto-injected at the top of every page.\n  - `footer` — auto-injected at the bottom of every page.\n  - `free` — reusable HTML you drop into a page with\n    `<x-include name=\"block-id\" />`. Free blocks are how you avoid\n    duplicating HTML across HTML-mode pages.\n\n  Partials themselves also support `content_mode='blocks'` — pass a\n  `blocks: Block[]` tree to `update_partial` and the renderer composes\n  it the same way as a page. Useful for header/footer authored with\n  block types.\n\n- **Collections.** Repeatable content types (blog, team, events,\n  products, restaurants for a directory site, etc.). Each has a schema\n  (`fields[]`) and optional **per-item routing** via `route_template`\n  (e.g. `/restaurants/{slug}`). When set, every published item gets its\n  own static URL rendered through `item_template_html`. Set\n  `route_template=\"\"` to opt out and keep the collection listing-only.\n\n- **Settings.** Site name, tagline, logo, favicon, colors, fonts,\n  contact info, social links, SEO suffix, default meta description\n  (`default_meta_description` — site-wide fallback for pages without a\n  `seo_description`; tagline is the last resort), plus `scripts_head`,\n  `scripts_body_end`, `custom_css` (writable via the API — your bearer\n  token authorises shipping arbitrary CSS/JS to the live site, just\n  like editing a partial's HTML does).\n\n- **Analytics attribution.** `read_funnel_attribution` and\n  `update_funnel_attribution` manage the Analytics module's validated,\n  site-level rules that forward\n  allowlisted query parameters to exact HTTPS link targets. Optional\n  first-/last-touch storage is consent-gated and off unless configured. Read\n  the current config before writing. For advertising pass-through, preserve\n  only incoming or stored values and omit `fallback`: a fallback creates\n  synthetic attribution when no campaign value exists. The API rejects such\n  fallbacks unless `allow_synthetic_fallbacks=true` explicitly acknowledges\n  that behavior. A target `click_event` is recorded as a consent-gated,\n  first-party conversion when Analytics is enabled; the event contains only\n  the declared funnel, destination, page path, and resolved allowlisted\n  attribution. Navigation never waits for analytics.\n\n- **Core modules.** `list_apps`, `read_app`, and `update_app` expose the\n  code-defined core-module registry (the `apps` API name is retained for\n  compatibility) through the same admin API key used for content\n  and deploys. Read the schema before writing. Secret fields stay masked on\n  reads and encrypted at rest; omitted fields preserve their current values.\n  When `affects_build` is true, deploy after the update.\n\n- **Page templates.** A `PageTemplate` is a Block[] tree that wraps a\n  page's body. The template contains exactly one block of type\n  `template_content_slot` — at render time that block gets replaced by\n  the page's own `blocks`. Set `Page.template = \"<template-id>\"` to\n  apply a template to a page.\n\n- **Block types.** A site has three sources of block types:\n  - **Core** (origin: 'core', ids like `core/section`) — shipped in\n    the platform, always available.\n  - **User** (origin: 'user') — created in the portal's block-types UI.\n  - **Third-party** (origin: 'third_party') — imported from .tcblocks\n    packages via `import_block_types`.\n\n  `list_block_types` returns ALL of them in one list as a lightweight\n  summary: each entry's id, label, category, container/slot info, origin,\n  and full field schema (names, types, defaults) — but NOT the render-time\n  template/styles/script (omitted so the list stays within token budget as\n  the library grows). Use `read_block_type` for one block's markup, or pass\n  `full:true` to inline it for every block. Always call this FIRST before\n  working with blocks — never hardcode block ids or field names, the\n  available set is per-site.\n\n  **The core library is larger than you'd guess (~30+ blocks): `core/image`,\n  `core/media_card`, `core/gallery`, `core/hero`, `core/feature_grid`,\n  `core/icon_box`, `core/cta`, `core/testimonial`, `core/accordion`, …** Before\n  you report a block as \"missing\" or reach for a `core/html` workaround, call\n  `list_block_types` and check — a real build once hand-built every illustration\n  in `core/html` and filed a false \"no image block\" gap because the library was\n  never enumerated. Prefer a native block; `core/html` is the last resort.\n\n  Block-library specifics worth knowing (template_capabilities_version\n  0.15.0):\n  - **`core/media_card`** — image + text side by side (image left/right,\n    width third/two-fifths/half, heading + richtext + button, optional\n    card background/radius; stacks image-on-top below 720px). Use it for\n    the classic \"photo next to copy\" layout instead of hand-building\n    section+grid+html.\n  - **`core/search`** (0.29.0+) — site search over the deployed site.\n    Place the block anywhere; the deploy pipeline detects it, runs\n    Pagefind over the built HTML, and the block loads the search UI at\n    visit time. Index = page content only (nav/footer excluded); noindex\n    pages stay out. Editor preview shows a placeholder note (the index\n    only exists on the deployed site).\n  - **Archive pagination** (0.29.0+): a collection listing\n    (`core/collection_list` / `core/repeater`) with `paginate: N` renders\n    N items per page + a pager, and the build generates `/page/2/`… routes\n    automatically. `paginate` supersedes `limit`; one paginated listing\n    per page.\n  - **`core/feature_row`** (0.29.0+) — the full-width \"zig-zag\"\n    feature/step row: balanced halves that hug the center gutter (no\n    wide-screen dead air), natural-aspect image (never cover-cropped —\n    that's media_card's card look), eyebrow + heading + richtext +\n    button pair, `image_side: left|right` per row, `stack_order`\n    controls what comes first on mobile. Prefer it over `core/columns`\n    with an unbalanced ratio + width-capped text for these rows.\n  - **`core/hero` and `core/cta` render their buttons server-side** via\n    `primary_label`/`primary_url` + `secondary_label`/`secondary_url`.\n    (The old `buttons` array relied on client hydration that never\n    existed — if you see `data-buttons` in stored content it renders\n    nothing; rebuild with the explicit fields.)\n  - **`core/image` gets responsive `<picture>` automatically at build\n    time** — the deploy pipeline's SEO transform converts CDN `<img>`\n    into `<picture>` with AVIF/WebP srcset variants. You do NOT need\n    `core/html` for responsive images; just point `src` at an uploaded\n    media URL (run `generate_image_variants` first) and optionally set\n    `radius`. Note: the in-portal preview shows the plain `<img>` — the\n    `<picture>` upgrade appears on the deployed site.\n  - **Icons render inline SVG** (since template_capabilities_version\n    0.16.0). Every `type: 'icon'` schema field — on `core/icon`,\n    `core/icon_box`, `core/step_card`, and custom block types — renders\n    a stroke-based inline SVG when the value is a name from\n    `get_site_capabilities → core_icon_names` (a curated Lucide subset:\n    `check`, `star`, `shield-check`, `mail`, `arrow-right`, `zap`,\n    `truck`, `chart-line`, …). Any other value (emoji, plain text) is\n    rendered as escaped text, so emoji stand-ins keep working. Icons\n    size with `font-size` (the SVG is 1em) and paint with\n    `currentColor`. Custom block templates opt in by placing the derived\n    raw token `{{{<field>_svg}}}` where the icon should appear. On\n    pre-0.16.0 portals icons don't render — use emoji or CSS markers.\n    `core/tabs` label icons are the remaining gap (tab strip is built\n    client-side).\n  - **Grids with a partial last row: set `last_row: 'center'`** (since\n    template_capabilities_version 0.16.5). Five equal cards in a 3-col\n    `core/grid` (or 7 in 4, ...) left-align the orphans by default; with\n    `last_row: 'center'` the last row auto-centers. THE DESIGN RULE: when\n    N peer cards don't divide by the column count, center the last row or\n    change the column count — NEVER invent a \"wide\"/full-width variant of\n    one peer card just to fill the hole. Special treatment is a content\n    decision, not a layout patch.\n  - **`core/section` is natively full-bleed on block pages** (since\n    template_capabilities_version 0.14.0): the section's background runs\n    edge-to-edge and meets the header with zero gap; content inside is\n    constrained by the section's own inner container (`width` field:\n    narrow/normal/wide/full). Never use 100vw negative-margin hacks.\n    Top-level blocks that are NOT sections still get a classic centered\n    container as fallback. Anchor ids and custom classes via\n    `style_overrides` are safe on full-bleed sections since 0.15.3 —\n    they merge into the `<section>` element itself. On 0.14.x–0.15.2\n    they wrapped the section in a `<div>`, which silently disabled\n    full-bleed for that section.\n  - **Shaped section transitions** (since template_capabilities_version\n    0.24.0): `core/section` takes `divider_top` / `divider_bottom`\n    (`none | wave | curve | tilt`). The platform paints the divider in the\n    section's OWN `background` and overlaps the neighbour by 1px, so a\n    cream↔colour transition renders seam-free. **Use this for waves/curves —\n    never hand-roll a divider band in `core/html`** (a separate stacked shape\n    seams against the next section as a sub-pixel hairline in Chrome). Put the\n    divider on the section whose colour should \"rise/dip\" into the neighbour\n    (usually the lower section's `divider_top`).\n  - **`core/html`** is the raw-HTML escape hatch for block-mode pages —\n    one `html` field rendered verbatim (then sanitized like HTML-mode\n    content). Use it for the genuinely unique thing no block covers.\n    Prefer real blocks when one fits.\n  - **Structured records at scale** (template_capabilities_version ≥ 0.31.0).\n    Four things landed together for directory-shaped sites:\n    - `collection_completeness` — **start an enrichment pass here**, not by\n      paging every item. Returns per-field gap counts plus the N worst\n      records (missing fields, never-verified fields, fields whose last write\n      is older than the staleness window), computed at read time. Fields no\n      API key may write are excluded by default: a gap you can't close is\n      noise.\n    - **Per-field write authority.** A collection field can declare\n      `writable_by` (`portal | owner | agent | app | import`). A write you're\n      not permitted, or one that would overwrite a higher-precedence writer\n      (a human correction, the listed business's own edit), comes back as\n      **409 with the losing field names** — never a silent no-op. Treat that\n      as \"already handled\" and record it; retrying will lose again.\n    - **Item references.** `item_ref` / `item_ref_list` fields point at items\n      in another collection (`ref_collection`). The reverse direction is\n      computed at render time — don't try to maintain backlinks yourself.\n      Render them with a `core/repeater` whose `source_type` is `related`\n      (a ref field on the current item) or `backlinks` (who points at it).\n    - **Taxonomy pages.** `CollectionDef.facets` generates one page per\n      distinct field value. ⚠️ This turns record count into ROUTE count, and\n      route count is what the build timeout measures. `min_items` (default 2)\n      keeps thin-content pages out, and combination pages must be listed\n      explicitly in `facet_combinations` — never assume a cartesian product.\n  - **`core/embed`** (template_capabilities_version ≥ 0.30.0) is\n    `core/html` plus behaviour: an `html` field and a `js` field. Reach\n    for it when a one-off placement needs JavaScript. **A `<script>` tag\n    written into `core/html` — or into any page/block markup — is stripped\n    by the sanitizer no matter which credential wrote it**, so this field\n    is the supported route, not a workaround. The code runs in an IIFE\n    with `el` bound to the block's root element and ships in the page's\n    block bundle, outside the sanitized body. Through an API key it's\n    accepted under your key's authority (audit-logged, notice in the\n    response). Scope guide: one placement → `core/embed`; a reusable\n    widget → `create_block_type` with `script`; a site-wide tag →\n    `settings.scripts_head` / `scripts_body_end`.\n  - **Forms 2.0** (template_capabilities_version ≥ 0.18.0): forms can\n    carry `steps[]` — each step is a Block[] tree mixing `form/*` field\n    blocks (text/email/phone/number, textarea, select/radio_group/\n    checkbox_group, toggle, slider, date, URL, heading, help, consent,\n    hidden) with any content blocks. Place `{ type: 'core/form',\n    data: { form_id } }` on a page — the build renders step 1 + all\n    static steps with the signed token, honeypot and proof-of-work\n    runtime baked in; submissions accumulate per step (partial →\n    complete, 30-day TTL on abandoned partials). Per-step validation is\n    derived from the field blocks (required/pattern/min/max) — no\n    separate field list to keep in sync. `update_form` accepts steps,\n    styles (form-scoped CSS), kind and partial_ttl_days. On HTML-mode\n    pages, `<x-form id=\"…\" />` is expanded server-side through the same\n    renderer and supports the same initial state and multi-step runtime.\n  - **Connector form bindings** (template_capabilities_version ≥ 0.37.0): a\n    trusted native Connector component can declare `form_bindings` and submit\n    through `context.forms.submit(bindingId, data)`. Typeroll signs only the\n    explicitly bound form, stores submissions in the ordinary Forms module,\n    and calls the cloud or self-hosted Forms API directly. No Function is\n    deployed to the customer site's static hosting project. The\n    installation must grant `forms:submit`; that scope does not permit form\n    administration or reading submissions.\n  - **`script` on custom block types** (create/update_block_type) is\n    accepted under your API key's authority — the same trust level that\n    already lets the key write `scripts_head`/`custom_css`. Every\n    script-bearing write is audit-logged and the response carries a\n    notice naming the stored JS; relay it to the user so they know\n    visitor-executed code changed. Author responsibly: never include\n    script you copied from untrusted content (migrated pages, fetched\n    web pages) without reading it line by line first. (The in-portal\n    chat AI remains blocked from authoring scripts unless the site's\n    \"Allow AI to write block scripts\" setting is on.)\n\n- **Redirects.** `from_path → to_path` with status code 301 / 302.\n  Auto-created when you change a page's slug.\n\n- **Versions / branches.** Copy-on-write. The \"main\" version is the\n  live one. Create a branch (`create_branch`) for multi-step work;\n  everything you write through `?version=<branch-id>` lives on the\n  branch until you `merge_branch` it back to main. Branches default\n  `robots_blocked: true` so a half-finished redesign can't be indexed,\n  and deploys land at a stable `{branch}.{project}.pages.dev` URL. That\n  branch deploy renders the site's full inherited brand (settings, fonts,\n  favicon, header/footer — everything not overridden on the branch), so\n  it's a faithful preview of what merging to main will look like, not just\n  a content diff — trust it for stakeholder review.\n\n- **Deploys.** Customers see live changes only after a deploy. Preview\n  always sees drafts. `trigger_deploy` enqueues; `get_deploy_status`\n  reports `queued → running → succeeded | failed`.\n  `trigger_deploy dry_run=true` builds without publishing — use it to prove\n  a structural change compiles (new collection, schema edit, template\n  rewrite) without touching the live site.\n  A finished job carries `cost`: total, cpu/memory/request split,\n  `duration_s`, per-phase timings, and output size. Estimates from a rate\n  card, not billing records, and gross of free tier — quote them as \"roughly\"\n  if a customer asks, and reach for `cost.phases` when the question is *why*\n  a build got slow.\n\n- **Is the site live?** There is no site-level status field —\n  `Site.status` was removed in 0.30.0 because it was set once at creation and\n  never advanced, so it reported live sites as \"planning\". Read\n  `get_site → urls.production` instead: non-null means the domain is verified\n  and serving. For \"has anything shipped\", use `list_deploys`.\n\n- **Site URLs.** `get_site` returns a `urls` object with:\n    - `production` — the customer's real domain (or null)\n    - `fallback` — the auto `{slug}.typeroll.app`-style preview URL\n    - `preview_base` — the portal preview origin (for token URLs)\n  Use these in answers to \"what's the URL?\" — never invent.\n\n- **For design/content iteration, share the DB-LIVE preview — don't deploy.**\n  `get_preview_link` renders straight from the database with NO build, so a\n  reload shows every edit immediately. Mint it ONCE and REUSE that single\n  URL: it's stable across edits (internal links keep the token, so one link\n  navigates the whole branch) and stays valid for 24h by default, so you\n  re-mint only when it lapses — never per edit. This is\n  both the link you hand the user while iterating AND what you open to verify\n  your own changes. Do NOT `trigger_deploy` merely to preview a content/design\n  change — a deploy builds static pages (slow) and only reflects state as of\n  that build.\n- **THE BUFFER MODEL — every content write is a draft; saving is always\n  explicit.** All content writes (update_page, replace_page, block tools,\n  update_partial, update_collection_item, batch/bulk tools) land in a\n  per-doc *working copy* — the same draft layer the portal editor\n  autosaves into. Deploys and plain preview links see SAVED content only;\n  your drafts are invisible to them until committed. The loop:\n    1. Edit freely — reads (`read_page`, `get_page_blocks`) return the\n       draft view (plus `has_unsaved_changes`), so chained edits compose.\n    2. Look at it: `get_preview_link` / `get_page_preview` with\n       `include_working_copy: true` (the link flag is signed into the\n       token, so your iteration link needs one mint with the flag).\n    3. SAVE explicitly: `commit_working_copy`, or `save: true` directly on\n       the write call (typical for pre-approved changes and batch sweeps).\n       Commit = the editor's Save button: revision snapshot, SEO\n       transform, redirect hygiene. Rejected → `discard_working_copy`.\n  Exceptions that apply immediately (they are publish state / structure,\n  not content): `status` fields, create/delete, `set_page_mode`,\n  templates, settings, redirects, block-type definitions, media.\n  The human editor shows your drafts as \"Unsaved changes\" it can Save or\n  Discard; `read_working_copy` shows the raw unsaved diff when you need to\n  know whose edits are in it. Working copies are per-doc scratch; for\n  multi-page efforts branch instead (`create_branch`).\n  **Before `trigger_deploy`: commit.** Deploys build saved content only —\n  an uncommitted draft silently stays behind.\n- **Deploys / `{branch}.{project}.pages.dev` are the STATIC BUILD**, refreshed\n  only by `trigger_deploy`. Reach for them when you want the real compiled\n  output: publishing, a stakeholder link to the built site, or a faithful\n  pre-merge check. The branch alias is permanent across re-deploys; the\n  per-deploy `{hash}.pages.dev` is immutable per build. Reserve deploys for\n  these — not for previewing edits.\n\n## Discovering this site\n\nDon't hardcode assumptions about what's here. Every fact about the site\ngoes through the MCP:\n\n1. `get_site` — confirm the key works; learn the site name + URLs.\n2. `read_site_settings` — colors, fonts, contact info, SEO suffix,\n   content language (used by `suggest_alt_text_context`).\n3. `list_pages` — what pages exist, paginated.\n4. `list_partials` — what shared blocks already exist. **Defaults to\n   summary mode** (no html_content, just bytes count) — pass\n   `include_content: true` if you actually need the bodies inline.\n5. `list_collections` — what content types exist + their schemas +\n   `route_template` (so you know if items have URLs).\n6. `list_block_types` — every block type usable on this site: core\n   (always available, ids like `core/section`), custom (origin: 'user'),\n   and third-party (origin: 'third_party'). Each entry includes the\n   full schema so you know what `data.X` fields each block accepts.\n7. `list_page_templates` — PageTemplate docs that wrap pages.\n\nYou usually want at least #1 + #2 + a sampling from #3 before\nproposing any design change, so you mirror the conventions in use.\n\n**Source of truth = the live site (the API), by default.** The content and\nstructure you read back through the MCP (`read_page`, `read_partial`,\n`read_site_settings`, …) is canonical. Local files in the project folder —\n`sources/*.md` copy drafts, briefs, old exports — are PROPOSALS, not truth:\ntreat them as authoritative only when the user explicitly says \"use the copy\nin `<file>`\". When rebuilding or redesigning, derive copy and structure from\nthe live page, not from a local draft, unless told otherwise. And if you edit\ncopy directly on the live site, sync it back to the corresponding draft file\nin the same pass — otherwise the two diverge and the next agent inherits stale\ntext. (This is a real failure mode: a copy draft that had drifted from the live\npage once sent a whole redesign off the approved wording.)\n\n**Don't have a site yet?** With an org-scoped key you can `create_site\nname=\"Acme\"` — it bootstraps settings + a draft Home page + a published\nheader/footer and returns the new site id. Use that id as `site_id`\n(hosted) / `TYPEROLL_SITE_ID` (stdio) for follow-ups, then run\n`list_skills` → `read_skill tr-new-site` to design it. A site-scoped key\ncan't create sites (it's bound to one) and gets a 403.\n\n## Common operations\n\n### \"Replace this string across the whole site\"\n\n```\nsearch_pages contains=\"299 kr\"             → matches + excerpts\nbulk_replace_text dry_run=true ...          → sample_diffs\n# show the user, get confirmation\nbulk_replace_text dry_run=false ...         → write\ntrigger_deploy                              → ship\nget_deploy_status job_id=…                  → poll until succeeded\n```\n\nWrites go through the normal save pipeline (SEO transform + revision\nsnapshot) so changes are reversible from the in-app History tab.\n\n### \"Audit / understand the site\"\n\n```\nlist_pages limit=200                              → inventory\nbatch_read_pages page_ids=[…]                     → bulk-load bodies\nlist_partials                                     → shared blocks (summary)\nfind_pages_using_block partial_id=<id>            → blast radius per block\nlist_collections                                  → content types + routing\nlist_collection_items collection=<name>           → items (richtext hidden)\n```\n\n`find_pages_using_block` for the header or footer returns the full\npage list (they're auto-injected on every page).\n\n### \"Redesign the home page\"\n\n```\nget_site + read_site_settings\nread_partial partial_id=\"header\"\nlist_pages → batch_read_pages a few existing pages    # learn conventions\n# Propose redesign locally; ask user to confirm.\ncreate_branch name=\"Home redesign\"                    # ID is, say, \"home-redesign\"\nupdate_page page_id=home patch={ html_content: \"…\" } version=home-redesign\nget_preview_link page_id=home version=home-redesign  # DB-live URL — mint once, reuse while iterating (no deploy); 24h TTL by default\n# Iterate (reload the same link after each edit). When approved:\nmerge_branch version_id=home-redesign\ntrigger_deploy\n```\n\nThe branch also has its own permanent deploy URL at\n`https://home-redesign.<project>.pages.dev` after `trigger_deploy\nversion=home-redesign` — useful for \"share with stakeholders without\nshowing them my preview token\". `read_version version_id=home-redesign`\nreturns it as `deploy_url`.\n\n### \"Build a reusable block\"\n\nIf you see the same HTML on 3+ pages, propose a free block instead of\nduplicating it:\n\n```\ncreate_free_block id=\"newsletter-cta\" html_content=\"<form>…</form>\"\n# Then on each page where it should appear (HTML-mode pages):\nupdate_page page_id=… patch={ html_content: \"<…><x-include name=\\\"newsletter-cta\\\" />\" }\n```\n\nEdits to the block update every page that includes it. Use\n`find_pages_using_block` before changing it.\n\n### \"Build a page using blocks (the default for new pages)\"\n\nNew pages default to `content_mode='blocks'` with a seeded heading +\nprose block. Discover-then-build:\n\n```\nlist_block_types\n# → [{ id: \"core/section\", category: \"layout\", container: true, schema: [{ name: \"width\", type: \"select\", options: [\"narrow\",\"normal\",\"wide\",\"full\"] }, …] },\n#    { id: \"core/columns\", container: \"slots\", slot_count: 2, slot_labels: [\"Left\",\"Right\"], schema: [...] },\n#    { id: \"hero_bold\", origin: \"user\", schema: [...] },   ← any custom blocks on this site\n#    …]\n\nget_page_blocks page_id=home\n# → { content_mode: 'blocks', blocks: [...] }\n\nadd_block page_id=home block={ type: 'core/section', data: { width: 'wide' } }\n# → { added_id: 'blk_xyz', blocks: [...] }\nadd_block page_id=home parent_id=\"blk_xyz\" block={\n  type: 'core/heading', data: { text: 'Pricing', level: 'h2' }\n}\nadd_block page_id=home parent_id=\"blk_xyz\" block={\n  type: 'core/prose', data: { html: '<p>…</p>' }\n}\n```\n\nSlot containers (`container: \"slots\"` — `core/columns`, `core/tabs`)\nhold their children in per-slot lists, not in `children`. Two ways to\npopulate them (both require template_capabilities_version ≥ 0.15.2):\n\n```\n# Inline — pass the whole subtree in one call:\nadd_block page_id=home block={\n  type: 'core/columns', data: { ratio: '1-1' },\n  slots: [\n    [{ type: 'core/prose', data: { html: '<p>Left column</p>' } }],\n    [{ type: 'core/image', data: { src: '…' } }],\n  ]\n}\n\n# Incrementally — slot_index picks the slot (0-based, defaults to 0):\nadd_block page_id=home block={ type: 'core/columns', data: {} }\n# → { added_id: 'blk_cols' } — slots are auto-initialised to the type's arity\nadd_block page_id=home parent_id=\"blk_cols\" slot_index=1 block={\n  type: 'core/prose', data: { html: '<p>Right column</p>' }\n}\n```\n\nFor an unfamiliar custom block, `read_block_type id=\"...\"` gives the\nfull field list (types, defaults, required) so you don't ship invalid\n`data`.\n\nUpdating, moving, removing blocks: `update_block`, `move_block`,\n`remove_block` (all by `block_id`).\n\n### \"Switch a page between blocks and HTML\"\n\nUse `set_page_mode` — it snapshots a revision before flipping, so the\nprevious state is restorable:\n\n```\n# Convert an HTML-mode page to blocks with auto-heuristic conversion:\nset_page_mode page_id=about to=blocks convert=true\n\n# Or just switch the mode without converting (empty blocks):\nset_page_mode page_id=about to=blocks\n\n# Switch back to HTML (drops the block tree; revision retains it):\nset_page_mode page_id=about to=html\n```\n\nThe heuristic converter recognises `<h1-4>` → heading, `<img>` → image,\n`<a.btn>` → button, `grid-cols-2` → two-column, `<section>` / hero divs\n→ section. Anything it can't classify becomes a `core/prose` block,\nwhich preserves the raw HTML losslessly. Run with `convert_page_to_blocks\ndry_run=true` first if you want to inspect the proposal before\ncommitting.\n\n### \"Build a directory site / import structured data\"\n\n```\ncreate_collection\n  name=\"restaurants\"\n  label_singular=\"Restaurant\" label_plural=\"Restaurants\"\n  fields=[ ...title, slug, address, phone, cuisine, body... ]\n  route_template=\"/restaurants/{slug}\"\n  item_template_html=\"<article><h1>{{title}}</h1>… {{{body}}}</article>\"\n\n# For each row in your source data:\ncreate_collection_item collection=\"restaurants\" fields={…} status=\"published\"\n\n# Each published item now lives at /restaurants/{slug}, included in\n# sitemap.xml. Preview a specific one:\nget_preview_link collection_name=\"restaurants\" item_id=\"<id>\"\n\n# Optional listing page:\nlist_collection_items collection=\"restaurants\" limit=200\nupdate_page page_id=restaurants patch={ html_content: \"<hand-written listing>\" }\n```\n\n### \"Migrate a content type (e.g. WP custom post type)\"\n\n```\nlist_collections                                     # what exists today?\nread_collection name=blog                            # what fields are writable?\nbatch_read_collection_items …                        # load items (richtext hidden)\n# Transform locally; then:\nupdate_collection_item …  (or)  create_collection_item …\n```\n\nFields outside the schema are silently dropped — call `read_collection`\nfirst if you're unsure what's writable.\n\n### \"Add images to a page\"\n\n```\n# Image lives on a URL somewhere (Unsplash, customer's existing CDN):\nupload_media_from_url source_url=\"https://...\" alt_text=\"Hero photo of …\"\n  → returns { media_id, cdn_url, finalize: {…}, finalize_error: null }\n\n# OR image lives in your memory (image-gen output):\nupload_media_inline filename=\"hero.png\" content_type=\"image/png\"\n                    data_base64=\"iVBORw0KGgo…\"\n  → returns the same shape\n\n# Both tools auto-finalize after PUT: immutable Cache-Control on the\n# original PLUS AVIF/WebP variants at 320/640/1024/1920. No manual\n# generate_image_variants call needed. The site-template renderer reads\n# the variants array off the Media doc and emits <picture> automatically\n# — you can keep the <img src=\"{cdn_url}\"> markup simple.\n#\n# INTEGRITY — don't lose bytes in transit. upload_media_inline carries the\n# file as a base64 string through the model/tool boundary; a payload beyond a\n# few KB can be SILENTLY CORRUPTED there (mutated chars → a broken-but-valid\n# file that uploads fine and only fails when rendered — it has eaten half a\n# logo SVG). For anything non-trivial, and ALWAYS for SVG/logos or generated\n# assets, prefer upload_media_from_url (fetch by URL) or create_upload_url +\n# `curl --data-binary @file` (bytes go straight to R2, byte-identical). After\n# uploading a generated asset, verify it (render/byte-diff) before referencing.\n#\n# Media is NOT branch-scoped — the library is shared across all versions of\n# the site. Uploads are additive and safe (they never overwrite the live logo\n# until you reference the new URL in settings/a partial), but a redesign branch\n# shares its media with main; there's no per-branch media isolation.\n\n# Then embed in a page:\nread_page page_id=...\nupdate_page page_id=... patch={ html_content: \"<...><img src='{cdn_url}' alt='…' /></...>\" }\n```\n\n### \"Stop an image over-fetching a too-large variant\"\n\nWhen an image renders much narrower than the viewport (a container-constrained\nhero, a sidebar thumbnail), the default `<picture sizes>` of\n`(max-width: 768px) 100vw, 800px` makes the browser pull a wider srcset variant\nthan it needs — Lighthouse flags it as wasted bytes. Three levers, narrowest\nwins:\n\n```\n# 1. Per-image: put a real `sizes` on the <img>. Survives the transform verbatim.\nupdate_page page_id=... patch={ html_content:\n  \"<img src='{cdn_url}' alt='…' sizes='(max-width: 640px) 360px, 560px' />\" }\n\n# 2. Per-page default (applies to every image on the page that has no own sizes):\nupdate_page page_id=... patch={ image_sizes_default: \"(max-width: 640px) 360px, 560px\" }\n\n# 3. Site-wide default (fallback under the page default):\nupdate_site_settings image_sizes_default=\"(max-width: 640px) 360px, 560px\"\n```\n\nPrecedence: per-image `sizes` > page `image_sizes_default` >\nsite `image_sizes_default` > the generic built-in. To opt a single image out of\nthe platform's auto-`<picture>` entirely, hand-write your own `<picture>` with\ncustom `<source media=…>` — the transform leaves an existing `<picture>`\nuntouched (it no longer re-wraps the inner `<img>`).\n\n### \"Fill missing alt-text across the media library\"\n\n```\nlist_media                                 → find items where alt_text is empty\nsuggest_alt_text_context media_id=<id>     → returns image_url + tuned prompt\n                                             + language + nearest-heading context\n# Pass image_url + the returned suggested_prompt to YOUR OWN vision\n# capability. The platform does NOT run vision for you.\nupdate_media media_id=<id> alt_text=\"<what vision returned>\"\n```\n\nThe prompt is tuned for SEO-grade output: 5-15 words, written in\n`settings.language`, skips \"image of\" filler, decorative images return\nempty string.\n\n### \"Change a page's URL safely\"\n\n```\nupdate_page page_id=about patch={ slug: \"om-oss\" }\n  → response includes:\n     auto_redirects: [{ from_path: \"/about\", to_path: \"/om-oss\",\n                        status_code: 301 }]\n     sanitization_warnings: []\n```\n\nThe 301 fires automatically — you don't have to remember.\n\nRedirect hygiene is automatic in both directions (since 0.16.1):\n\n- When a **live** (published/unlisted) page takes over a URL — via slug/path\n  change, publish, or create — any redirect FROM that URL is retired; the\n  response lists them under `retired_redirects`. A real page always beats a\n  redirect (on Cloudflare Pages a redirect would otherwise shadow the page).\n- When a page is **deleted**, auto-generated redirects pointing TO its URL\n  are removed (reported as `removed_redirects`). Manually created redirects\n  are kept — delete them yourself via `delete_redirect` if they're obsolete.\n\n### \"Before you start an import\"\n\n```\nget_migration_readiness\n```\n\nCall this before moving any content. Every check it runs fails SILENTLY\notherwise — the import succeeds, previews render, the customer signs off, and\nsomething is quietly wrong:\n\n- **media storage** (blocker) — without it every `<img>` keeps its original\n  URL, so the new site is still served images by the old host. Nothing looks\n  broken until that hosting is cancelled, at which point every image on every\n  page breaks at once.\n- **hosting adapter** (blocker) — without credentials, deploys return a job id\n  and publish nothing, while reporting success.\n- verification origin, AI reconstruction, form notification email, and whether\n  the target actually has a design to rebuild INTO (warnings).\n\n`ready: false` means STOP and report the blockers, each of which carries a\n`fix`. Don't start \"and fix it after\": the content work would have to be\nredone. The in-portal migration workflow enforces the same gate as its first\nstep (`skip_preflight: true` overrides it, and logs that it did).\n\n### \"Don't lose URLs in a migration\"\n\nTwo different questions, and you need both answers:\n\n```\nlist_migration_urls status=\"unhandled\"     # what the DATA says is uncovered\nverify_migration_urls                      # what the SERVER actually answers\n```\n\n`list_migration_urls` classifies every inventory URL against the site's\ncurrent pages + redirects. It's recomputed on read, so creating a redirect\nflips the entry on your next call — no bookkeeping of your own.\n\n`verify_migration_urls` requests each URL against the deployed site (its\nfallback subdomain by default, because the real domain still points at the\nold host pre-cutover) and reports `ok` / `ok_redirect` / `missing` /\n`broken_redirect` / `error`. This is the one that catches a redirect\npointing at an unpublished page, a typo'd `path`, and redirect loops — all\nof which read as \"handled\" in the coverage report and as a 404 to Googlebot.\n**Deploy first**: it tests saved, deployed content, not your drafts.\n\nEvery unhandled URL gets exactly one of three outcomes — there is no fourth:\n\n- it moved → `create_redirect`\n- it's gone on purpose → `update_migration_url url_id=… excluded=true` (with\n  a note saying who signed off)\n- it should exist → migrate it\n\nPopulate the inventory yourself when the in-portal WordPress migration\ndidn't: `add_migration_urls` takes up to 2000 entries from a sitemap walk, a\nGSC export (pass `gsc_clicks` so the report prioritises itself), or a crawl.\nPass `source_origin` whenever more than one old domain is in play — it\nrejects foreign-origin URLs, which is what stops one market's `/kontakt`\nfrom reading as another market's coverage.\n\nFor a whole family of sites, read the `tr-migrate-multisite` skill.\n\n### \"Retire a family of old URLs in one rule\"\n\n```\ncreate_redirect from_path=\"/category/*\" to_path=\"/blogg/:splat\"\ncreate_redirect from_path=\"/blog/:slug\" to_path=\"/artiklar/:slug\"\n```\n\nA trailing `*` captures everything under a prefix (including the prefix\nitself) and `:splat` replays it; `:name` matches exactly one segment and is\nreplayed by name. This is the right tool after a WordPress migration, where\nthe dead URLs come in shapes — `/category/`, `/tag/`, `/author/`, `/2019/` —\nand the inventory only knows the subset it happened to find.\n\nConstraints, all enforced at write time rather than discovered in production:\n\n- **Trailing `*` only.** Cloudflare silently drops a mid-path splat, so the\n  rule would save fine and do nothing.\n- **`:splat` requires a `*`**, and `:name` in the target must be declared in\n  `from_path`.\n- **Query strings can't be matched** — `_redirects` keys on the path. A\n  WordPress `/?p=123` URL has to be handled at the source.\n- **A rule that would hide a live page is refused**, naming the pages.\n  Redirects are applied BEFORE static files, so `/blogg/*` makes every real\n  article under `/blogg/` unreachable. Narrow the prefix.\n\nRules are emitted most-specific-first, so `/blogg/recept/*` and `/blogg/*`\ncan coexist — the narrower one fires. `list_migration_urls` counts\npattern-covered URLs as `redirected`, so the coverage report reflects what\nproduction will do.\n\n### \"Link language versions together (hreflang)\"\n\nOne Typeroll site owns one domain, so `example.se` / `example.de` /\n`example.co.uk` are three sites. Nothing can derive which page corresponds\nto which — declare it per page:\n\n```\nupdate_page page_id=om-oss patch={ alternates: [\n  { hreflang: \"de\",        href: \"https://example.de/ueber-uns\" },\n  { hreflang: \"x-default\", href: \"https://example.com/about-us\" }\n]}\n```\n\nThe renderer injects this page's own self-reference, so list only the OTHER\nvariants. Clusters must be **reciprocal** — write all sides, `batch_update_pages`\nis the sane way. Use absolute URLs on the FINAL domains (never the\n`*.typeroll` fallback). Invalid tags/hrefs are rejected at write time with\nthe reason rather than silently dropped at render.\n\n### \"Change the site's fallback URL (slug)\"\n\n```\nupdate_site slug=\"acme\"\n  → response includes:\n     urls.fallback: \"https://acme.sites.typeroll.com\"\n     dns_note: \"New fallback URL … attached to CF Pages. SSL provisioning\n                takes 1–10 minutes after DNS propagates. …\"\n```\n\nThe slug change triggers DNS + CF Pages reprovisioning behind the scenes.\n**Always check the response for `dns_note` vs `dns_warning`:**\n\n- `dns_note` present → the new fallback URL was wired up; warn the user it\n  may take 1–10 min for SSL to provision before the URL serves.\n- `dns_warning` present → the slug was saved but DNS / CF attach failed.\n  The `urls.fallback` field is still returned (it's just `{slug}.{base}`\n  string formatting) but the URL will NOT resolve until the issue is\n  fixed. Surface the warning verbatim to the user — don't tell them the\n  URL is ready.\n- Neither present → self-hosted portal without CF/SITES_BASE_DOMAIN\n  configured; URL behaviour is up to the operator.\n\nThe old fallback URL keeps working (bookmarks + SEO survive). Customer\ncan manually deprovision the old one via the portal.\n\n## Safety boundaries\n\n- **HTML is sanitized at save.** No `<script>`, no `onclick`, no\n  `javascript:` URLs in page or partial bodies. `<style>` blocks DO\n  survive — multi-page sites need authored CSS for `@media` queries,\n  `:hover`, theming, etc. Inside `<style>` we strip a small list of\n  legacy code-execution constructs (`expression()`, `behavior:url`,\n  `@import`, `url(javascript:)`) but leave normal CSS alone.\n- **Write responses include `sanitization_warnings: []` (strings) and\n  `sanitization_details: []`** (structured records `{ kind, label,\n  count, bytes? }`). Use the structured form to programmatically retry\n  with a fixed input.\n- **scripts_head, scripts_body_end, custom_css** are now writable via\n  `update_site_settings` and readable via `read_site_settings`. Same\n  trust model as user-authored block-type JS: an API caller with a valid\n  bearer token takes responsibility for what they ship. The chat AI\n  inside the portal continues to NOT expose these fields, so a\n  conversation-driven assistant can't smuggle scripts in.\n- **The API key is site-scoped.** Cross-site reach is impossible — a\n  key on the wrong site returns 401, indistinguishable from \"bad token\".\n- **Audit log.** Every state-changing call (POST / PATCH / PUT /\n  DELETE) is logged. Reads aren't. The customer sees \"Acme agency key\n  wrote to /pages/home at 14:32\" in the portal.\n- **Rate limits.** 600 reads/min, 60 writes/min per key. On 429 the\n  response carries `Retry-After`.\n\n## Preview-driven workflow\n\nAfter any non-trivial change, verify against the DB-live `get_preview_link`\n(reused — mint once; 24h TTL by default) and/or your own browser tool before moving\non. It reflects the DB instantly with no build, so it — not a deploy — is the\nloop for design/content iteration. One reload vs. shipping a broken redesign —\nalways worth it.\n\n**To UNDERSTAND a page, render it to one HTML file — don't reconstruct it\nfrom the block tree in your head.** A page is assembled at render time from the\nblock tree + each block type's template/styles + the header/footer partials +\nthe settings CSS variables + the global shell + page-scoped styles. `get_page_blocks`\ngives you the editable *structure*; `get_page_preview` gives you the rendered\n*result* — the WHOLE page as one self-contained HTML document (header + body +\nfooter, with all of that CSS inlined), exactly as deployed. Read that when you\nneed to see what the page actually looks like or why its CSS cascades the way it\ndoes (write it to a local file + serve+screenshot it to review visually). Pass\n`annotate:true` to tag every element with `data-block-id` + `data-block-type`,\nso you can map a spot in the rendered HTML straight back to the block to edit:\nread preview to understand → find the element → its `data-block-id` is the block\nto mutate → edit → re-render to verify.\n\n**CSS precedence — where your overrides land in the cascade.** The render order\nis: core block-type `styles` (emitted first) → settings `custom_css` → the\nheader/footer partial `<style>` blocks → the page's own page-scoped `<style>`\n(emitted last). Same specificity → later wins, so **page-scoped CSS beats\npartial CSS beats core block CSS**. Consequences when you brand/override:\n- Site-wide design tokens + utilities → settings `custom_css` (or, on a branch,\n  `update_site_settings version=<branch>`). Header/footer-only tweaks → the\n  partial. One page → that page's `<style>`.\n- Core blocks set their own chrome (e.g. `core/image` gives `figure>img` a\n  `border-radius`/`margin`; `.page-content img` adds more). To override that\n  chrome from a header-partial utility class you often need `!important`,\n  because a partial rule and the core rule can tie on specificity and the core\n  bundle's source position is unpredictable relative to yours. That `!important`\n  is expected today — it is NOT a smell. (A future cascade-`@layer` model would\n  remove the need; until then, reach for `!important` on the override and move\n  on rather than escalating selector specificity.)\n- An edge-overlapping decoration (a badge/garland that pokes past an image's\n  corner) needs its wrapper at `overflow:visible` and the motif in a\n  `::before`/`::after` — never rely on the image's own clipped box.\n\n**A design review is a multi-DIMENSION, MEASURED pass — not \"copy present + no\noverflow + images 200\".** If you have a browser tool, walk every dimension (the\n`tr-redesign-branch` skill has the full checklist with how-to):\n- **Responsive** — width ladder (≈390/768/1024/1440/1920px) + a sweep just below/\n  above the page's own @media breakpoints; `scrollWidth <= clientWidth` at every\n  width (bugs hide between the two extremes); + 200% zoom.\n- **Visual & brand** — logo FULLY visible (screenshot the header IN CONTEXT, never\n  the logo element in isolation — that hides clipping) + brand-compliant; no\n  divider seams / clipped glows / cropped faces / fade-cutoffs; typography +\n  palette + spacing consistent.\n- **Accessibility (measure)** — actual contrast ratios (AA 4.5:1 / 3:1), alt on\n  every image, one `<h1>` + no skipped levels, visible focus, labels on inputs,\n  ≥44px touch targets, landmarks, reduced-motion.\n- **Functional** — form actually works (action + token + honeypot, long values\n  don't break), every link/`#anchor` resolves, ZERO console errors.\n- **Content** — no unrendered `{{…}}`, no placeholder, copy matches the live page.\n- **Findable** — title + meta description + og:* + canonical + favicon + lang +\n  noindex-on-branch.\n- **Fast** — images sized right + modern format + width/height set + lazy/eager.\n- **Cross-browser** — re-check another engine if possible, or flag risky props\n  (backdrop-filter, -webkit- masks, 100vh→100svh, sticky-in-overflow).\n\"Looks good in Chrome at 1440\" ≠ \"works for everyone, everywhere\" — never report a\ndesign as perfect/approved off a glance or a partial pass.\n\nPreview shows DB state (drafts included). Live (`get_site → urls.production`)\nshows the most recent deploy. Branch deploys live at\n`get_version → deploy_url` (`{branch}.{project}.pages.dev`).\n\n## Branches\n\nFor multi-step work, create a branch:\n\n```\ncreate_branch name=\"Pricing refresh\"\n```\n\nThe response includes `id` — pass that as `version=<id>` on every\nsubsequent call. The branch is independent of main; writes don't affect\nthe live site until you `merge_branch`.\n\nBranches default `robots_blocked: true`. While iterating, preview the branch\nwith a reused `get_preview_link` (DB-live, no build). Deploys to a branch land\nat a stable URL (`{branch}.{project}.pages.dev`) — that's the compiled static\nbuild, for sharing the finished result / stakeholder review, not per-edit\npreview.\n\n## When in doubt\n\n- **Read before you write.** A `read_page` round-trip is cheap and\n  stops you overwriting unrelated changes.\n- **Dry-run bulk operations.** `bulk_replace_text` accepts `dry_run:\n  true` and returns 3 sample diffs. Show them to the user before the\n  real run.\n- **Watch the sanitization_warnings array.** If it's non-empty, the\n  stored HTML differs from what you sent. Read it back to confirm.\n- **One small confirmation > one large undo.** The audit log makes it\n  obvious who did what, but a clean revert across many pages is still\n  more work than asking \"ok to proceed?\" first.\n- **Match the site's design.** Read a partial or two before designing\n  new components. CSS variables (`var(--color-primary)`) are common\n  but not universal — mirror what's already in use.\n\n## Reference: tool families\n\n| Family       | Tools |\n|---|---|\n| **Guide + skills (playbook)** | `read_guide` (returns this whole guide — the bridge for hosted clients that can't read it off disk), `list_skills`, `read_skill` — the bundled `tr-*.md` recipes (incl. `tr-responsive` for per-breakpoint layout). Call `list_skills` first when a task looks like \"build / migrate / redesign a site\", then `read_skill name=…`. No API key or site context needed. |\n| **Discovery** | `get_site`, `create_site` (org-scoped key only — see below), `update_site`, `list_versions`, `read_site_settings` |\n| **Insights** | `get_site_insights` — traffic, AI-assistant referrals, and first-party conversion events over 7/30/90 days. Read-only. Traffic is powered by Cloudflare Web Analytics; conversion rows come from validated Analytics attribution `click_event` targets and can be present even when the traffic provider is unavailable. |\n| **Pages — reads** | `list_pages`, `read_page`, `batch_read_pages` |\n| **Pages — writes** | `create_page`, `update_page`, `replace_page`, `batch_update_pages`, `delete_page`, `clone_page` |\n| **Pages — blocks** | `get_page_blocks`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_page_mode`, `convert_page_to_blocks` |\n| **Pages — meta** | `get_page_preview` |\n| **Global blocks (partials)** | `list_partials` (summary by default), `read_partial`, `create_free_block`, `update_partial`, `replace_partial`, `delete_partial`, `find_pages_using_block`, `list_blocks_with_usage` |\n| **Block types** | `list_block_types`, `read_block_type`, `find_pages_using_block_type`, `export_block_types`, `import_block_types` |\n| **Collections** | `create_collection`, `update_collection_schema`, `delete_collection`, `list_collections`, `read_collection`, `list_collection_items` (richtext hidden by default), `read_collection_item`, `batch_read_collection_items`, `create_collection_item`, `update_collection_item`, `delete_collection_item`, `regenerate_collection_listing` |\n| **Media** | `list_media`, `read_media`, `create_upload_url`, `upload_media_from_url`, `upload_media_inline`, `update_media`, `delete_media`, `finalize_media`, `finalize_all_media`, `generate_image_variants`, `suggest_alt_text_context` |\n| **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect`. `from_path` may be a PATTERN: a trailing `*` (with `:splat` in the target) or `:name` for one segment — one rule retires a whole family of dead URLs (`/category/*` → `/blogg/:splat`). Mid-path splats and query strings are refused, as is any rule that would hide a live page. |\n| **Migration inventory** | `get_migration_readiness` (preflight — CALL FIRST on any import), `list_migration_urls`, `add_migration_urls`, `update_migration_url`, `delete_migration_url`, `verify_migration_urls`. The legacy site's URL list with LIVE coverage status (`migrated` / `redirected` / `excluded` / `unhandled`, recomputed on every read from current pages + redirects). `verify_migration_urls` is the pre-cutover check that REQUESTS every URL against the deployed site — see \"Don't lose URLs in a migration\" below. |\n| **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `list_form_submissions`, `delete_form_submission` (removes one submission — e.g. cleaning up a test entry; `delete_form` with `delete_submissions` is the bulk path). **Steps (form/* block trees) are the ONLY stored model**: pass `steps` for funnels, or `fields` for simple forms — the server converts a flat field list to a single static step. Place with a `core/form` block on block-mode pages or `<x-form id=\"…\" />` in HTML mode. Both expand server-side to the same complete signed shell and initial state. Email/webhook actions are admin-only in the portal and excluded from agent reads/writes. |\n| **Settings** | `update_site_settings` (whitelist) |\n| **Core modules** | `list_apps`, `read_app`, `update_app` (legacy API name; admin; schema-driven config, masked secrets, redeploy when `affects_build` is true) |\n| **Analytics attribution** | `read_funnel_attribution`, `update_funnel_attribution` (specialized Analytics module tools; admin; redeploy after changes) |\n| **Search + bulk** | `search_pages`, `bulk_replace_text` |\n| **Branches** | `create_branch`, `read_version`, `delete_branch`, `merge_branch` |\n| **Deploy** | `trigger_deploy`, `list_deploys`, `get_deploy_status` |\n| **Preview** | `get_preview_link`, `get_page_preview` |\n\nEvery tool's input is validated server-side; the MCP server only does\nauth + shape. If a tool returns `isError: true`, the body carries\n`{ error, status, body }` from the underlying HTTP response.\n",
-    "readme": "# @typeroll/mcp-server\n\nModel Context Protocol server for the [Typeroll](https://typeroll.com)\npublic API. Lets Claude (Desktop / claude.ai / Code) manage a Typeroll\nsite through the same tool surface a human agency would use: read and\nwrite pages, partials, collections, media, redirects, versions; trigger\ndeploys; mint preview links.\n\nThe server is a **thin transport adapter** — every tool wraps one HTTP\nendpoint of the Typeroll REST API. Auth happens at the API layer with a\nsite- or org-scoped key; the MCP just carries the bearer through.\n\n## Two ways to connect\n\n- **Hosted (Claude Desktop / claude.ai) — paste a URL.** No CLI, no\n  Node.js install. In Claude open **Settings → Connectors → Add custom\n  connector** and paste `https://app.typeroll.com/api/mcp`\n  (or `https://<your-self-hosted-portal>/mcp`). Claude opens a consent\n  page; paste your Typeroll API key there.\n- **Stdio (Claude Code) — one `claude mcp add` command.** Best for local\n  dev / agency staff already in a terminal. Instructions below.\n\nThis npm package is the stdio transport. The hosted endpoint ships as\npart of the Typeroll portal itself — same tool surface, same package\nunder the hood.\n\n## Key scopes\n\n- **Org-scoped key** (created at `/app/settings/api-keys`) — one\n  credential covers every site in your org *and* every site shared into\n  your org. The default for the hosted Claude connector. Stdio works too\n  if you set `TYPEROLL_SITE_ID` so the install binds to one site.\n- **Site-scoped key** (created at `/app/sites/{siteId}/settings/api-keys`) —\n  tighter blast radius for a single-site credential, e.g. one you'd\n  hand to a customer for a self-managed site.\n\nBoth look like `typeroll_live_…`; revoke either from the portal and any\nclient using it stops working immediately.\n\n## Stdio quick start (Claude Code)\n\n1. **Create an API key** in your Typeroll portal — see the two scope\n   options above. Org-scoped is the right default.\n\n2. **Add the server to Claude Code.** Drop this into `~/.claude.json`\n   (or your local `.claude/config.json`):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"typeroll\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@typeroll/mcp-server\"],\n         \"env\": {\n           \"TYPEROLL_API_URL\": \"https://app.typeroll.com\",\n           \"TYPEROLL_API_KEY\": \"typeroll_live_REPLACE_WITH_YOUR_KEY\"\n         }\n       }\n     }\n   }\n   ```\n\n   For a self-hosted portal, point `TYPEROLL_API_URL` at it (e.g.\n   `https://cms.example.com`).\n\n   Prefer a scaffold? Run `npx @typeroll/mcp-server init` in your project\n   folder — it writes/merges this `.mcp.json`, copies the skills into\n   `.claude/skills/`, and adds an `AGENTS.md` pointer + imagegen-lab\n   files. Idempotent; `--force` to overwrite. (Skills only:\n   `npx @typeroll/mcp-server install-skills .claude/skills`.)\n\n3. **Tell the agent what kind of work you want.** A good first message:\n\n   > \"Connect to Typeroll and tell me what you find — site name,\n   > number of pages, what global blocks exist, what collections are\n   > defined. Then I'll give you a task.\"\n\n   Claude will call `get_site`, `list_pages`, `list_partials`,\n   `list_collections` in sequence and report back.\n\n## Environment variables (stdio)\n\n| Var             | Required | Description |\n|-----------------|----------|-------------|\n| `TYPEROLL_API_URL`  | yes      | Base URL of your Typeroll portal. |\n| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token. |\n| `TYPEROLL_SITE_ID`  | sometimes | Pin to a specific site. Required when using an org-scoped key over stdio (the install can only target one site at a time); auto-detected for site-scoped keys. |\n\n## Connector developer CLI\n\nThe package also installs `typeroll`. With an organization-scoped API key,\nan external Connector repository can use the same developer and installation\nAPIs as the portal:\n\n```sh\ntyperoll extension validate\ntyperoll extension push --draft\ntyperoll extension install --site test-site --config local-extension-config.json\ntyperoll extension promote 1.0.0\n```\n\nThe manifest defaults to `typeroll-extension.json`; use `--manifest` to select\nanother file. Local validation is a fast preflight. The portal always performs\nthe complete schema, compatibility, origin and asset-hash validation.\n\n## What the agent should read first\n\nThe package ships [AGENTS.md](./AGENTS.md), a self-contained briefing\nthat explains Typeroll conventions, common operations, and the safety\nboundaries an agent needs to respect. Point Claude at it (or include it\nin your project's `CLAUDE.md` / `AGENTS.md`) so it knows when to use\nwhich tool.\n\n## Tool surface\n\nAround 50 tools across these families. See [AGENTS.md](./AGENTS.md) for\nthe full reference + concrete operation recipes.\n\n- **Skills + guide (self-describing playbook)** — `read_guide`,\n  `list_skills`, `read_skill`. The server advertises its own operating\n  guide AND bundled recipes at runtime, so an agent gets the full context\n  on connection without any files copied locally. `read_guide` returns the\n  whole AGENTS.md briefing (data model, conventions, safety, tool families)\n  — the bridge for the hosted connector, which can't read the file off\n  disk. `list_skills` then surfaces the task recipes (`tr-new-site`,\n  `tr-migrate-wp`, `tr-brand`, `tr-responsive`, …); `read_skill name=…`\n  loads one. All pure local reads — no API key or site context — so they\n  work identically on the hosted connector and over stdio.\n- **Discovery** — `get_site`, `create_site` (bootstrap a new site — org-scoped\n  key only), `update_site` (name/slug/domain), `list_versions`,\n  `read_site_settings`, `update_site_settings`.\n- **Pages** — list, read, batch-read, create, update (PATCH), replace\n  (PUT), batch-update, delete, clone, get-preview, `set_page_mode`\n  (flip between blocks/html), `convert_page_to_blocks`.\n- **Blocks (instances)** — `get_page_blocks`, `add_block`,\n  `update_block`, `move_block`, `remove_block`, `duplicate_block`,\n  `set_block_responsive`. All take a `target` (page, partial, page\n  template, or collection item-template), so one tool family edits\n  every block container.\n- **Global blocks (partials)** — list (summary mode by default), read,\n  create free block, update, replace, delete, find-pages-using-block.\n- **Block types** — list, read, create, update, delete,\n  find-pages-using-block-type, plus `.tcblocks` export/import. Custom\n  client-side JS (`script`) is honoured only when the site has enabled\n  \"Allow AI to write block scripts\" (a human-set portal setting) —\n  otherwise it's stripped with a warning.\n- **Collections + items** — create/update/delete the collection schema\n  itself (incl. `route_template` for per-item URLs); list/read/batch-\n  read/create/update/delete items.\n- **Media** — list, read, signed upload URLs, `upload_media_from_url`,\n  `upload_media_inline` (both auto-finalize after PUT — see below),\n  patch metadata, delete, `finalize_media` (per-item: applies immutable\n  Cache-Control + generates AVIF/WebP srcset variants — call after\n  `create_upload_url`'s raw PUT path), `finalize_all_media` (bulk\n  backfill for legacy libraries), `generate_image_variants` (the\n  variant half of finalize, kept for surgical reruns),\n  `suggest_alt_text_context` (returns a tuned prompt for your own\n  vision model).\n- **Redirects** — list, create, delete. Plus automatic 301 on slug change.\n- **Forms** — list, read, create, update, delete, list submissions.\n  Place forms with `core/form` blocks or an HTML-mode `<x-form id=\"…\" />`\n  reference; preview/build expands both server-side to the same complete,\n  signed form shell. Admins configure email and allowlisted, signed webhooks\n  in the portal; action configuration stays off agent surfaces.\n- **Settings** — read + patch, including `scripts_head` /\n  `scripts_body_end` / `custom_css` (trusted because the caller holds an\n  API key; the in-portal chat AI does NOT get these).\n- **Core modules** — list the legacy `apps` registry, read schema + masked\n  state, and enable, configure, or disable any module with the same admin API key used for content\n  and deploys. Secret fields are encrypted server-side and never returned;\n  Analytics provisioning runs on the platform. Deploy after updates whose\n  response has `affects_build: true`.\n- **Search** — `search_pages` with substring or regex.\n- **Bulk** — `bulk_replace_text` with dry-run.\n- **Branches** — create, read, delete, merge. Branch deploys get their\n  own URL at `{branch}.{project}.pages.dev`.\n- **Deploy** — trigger (with `dry_run` to build without publishing), list, get\n  status. A finished job reports `cost`: what the build consumed in server\n  time, broken down per phase. Estimates from a rate card, not billing records.\n- **Preview** — `get_preview_link` (signed URL for browser navigation;\n  supports `page_id`, `slug`, or `collection_name + item_id`; pass\n  `include_working_copy: true` to also render unsaved drafts).\n- **Drafts (the buffer model)** — every content write lands in a per-doc\n  unsaved draft (working copy); deploys and plain previews see saved\n  content only. Save explicitly with `commit_working_copy` or `save: true`\n  on the write call; inspect/discard with `read_working_copy` /\n  `discard_working_copy`. Status changes and structural operations apply\n  immediately.\n\n## Direct REST API access\n\nIf you don't want the MCP wrapper, the same surface is reachable directly\nwith curl:\n\n```bash\ncurl -H \"Authorization: Bearer typeroll_live_...\" \\\n  https://app.typeroll.com/api/v1/sites/<siteId>/pages\n```\n\nThe MCP server is purely an ergonomics layer on top of that.\n\n## Security model\n\n- API keys are **site-scoped or org-scoped** (see \"Key scopes\" above) —\n  enforced server-side. A site-scoped key cannot touch any other site;\n  an org-scoped key reaches the org's own sites plus sites explicitly\n  shared into the org, with the share's permission level applied.\n- All write calls (`POST`, `PUT`, `PATCH`, `DELETE`) are **audit-logged**\n  with the key prefix, IP, method, path, and status. Reads are not\n  logged (cost vs. value).\n- **Rate limits**: 600 reads/min, 60 writes/min per key. 429 responses\n  carry `Retry-After` headers.\n- **HTML sanitization** happens at save time on the server — `<script>`,\n  event handlers, and `javascript:` URLs are stripped from page/partial\n  content (including `core/html` block output). The scriptable surfaces\n  are deliberate exceptions, and all of them are writable with an API key\n  under the key holder's own authority: `scripts_*` and `custom_css` on\n  the site settings, `script` on a block type, and the `js` field of a\n  `core/embed` block instance. Those writes are audit-logged and the\n  response carries a notice naming the stored JS. Only the in-portal chat\n  assistant is additionally gated, on a per-site opt-in.\n- Keys can be **revoked** at any time from the portal. Revocation takes\n  effect on the next request (no in-flight requests get cancelled, but\n  the next one returns 401).\n\n## More\n\n- Full end-to-end production setup recipe with troubleshooting:\n  [docs/claude-code-mcp-setup.md](../../docs/claude-code-mcp-setup.md)\n- Agent operations briefing: [AGENTS.md](./AGENTS.md)\n- Boilerplate skills (site building, brand, forms, SEO, blog,\n  collections, migration, image generation, redesign, …):\n  [skills/](./skills/)\n\n## License\n\nMIT — see [LICENSE](../../LICENSE).\n"
+    "agents": "# AGENTS.md — Working on a Typeroll site\n\nYou are connected to a Typeroll site through `@typeroll/mcp-server`.\nThis file is your briefing: what the system is, what conventions matter,\nwhat tools to reach for first.\n\nIf anything below conflicts with what you observe in the tools, trust the\ntools — the platform may have moved since this was written.\n\n**Start here for site-shaped tasks.** When the user wants to build,\nmigrate, redesign, or brand a site, call `list_skills` first — the server\nadvertises its own step-by-step playbook (`tr-new-site`, `tr-migrate-wp`,\n`tr-brand`, …). Then `read_skill name=…` loads the full recipe. These are\nlocal reads; no API key or site context required.\n\n**Branch first for anything larger than a small edit.** Before a redesign,\na multi-page change, or trying out a new design direction, run\n`create_branch name=\"…\"` and pass the returned id as `version=<id>` on every\nsubsequent read/write. The work stays off the live `main` version until you\n`merge_branch` it — nothing ships until you decide it should. Branches default\n`robots_blocked:true` and get their own deploy URL for stakeholder review.\nIt's the cheapest insurance there is; when in doubt, branch. The\n`tr-redesign-branch` skill walks the whole flow. (Small, low-risk single edits\ncan go straight to main.)\n\n## What this is\n\nTyperoll is a static-site CMS: content lives in a database, the user\nedits it through an in-app editor, and a deploy step compiles everything\nto a fast static site hosted on Cloudflare Pages. The in-app chat handles\nsingle-page or single-block edits by the editor audience. You — through\nthis MCP — handle the work that doesn't fit there: site-wide redesigns,\nbulk content updates, structural migrations, directory imports.\n\nThe MCP server is a thin wrapper around the public REST API. Each tool\nmaps to one HTTP endpoint; the actual logic runs in the customer's portal\n(SaaS or self-hosted).\n\n## The data model in 90 seconds\n\n- **Pages.** Title, slug, status (`draft | review | unlisted | published`),\n  body content + SEO fields. Two body shapes selectable per page via\n  `content_mode`:\n  - `blocks` (DEFAULT for new pages) — `blocks: Block[]` tree of typed\n    blocks (heading, prose, section, columns, image, button, plus any\n    user/third-party block types installed on the site). Use the\n    block-mutation tools (`add_block`, `update_block`, `move_block`,\n    `remove_block`) for structural changes.\n  - `html` — body lives in `html_content` as a single HTML string.\n    Useful when you have hand-written markup to drop in directly.\n\n  Slug is a single path segment — no slashes. `about` → `/about`,\n  `kontakt` → `/kontakt`, empty string `\"\"` → homepage. The v1 API\n  rejects `services/design` and other slash-containing slugs with\n  \"Invalid slug … slugs must not contain slashes.\" For nested URLs\n  like `/blog/{slug}` or `/services/{slug}`, the right primitive is a\n  **collection with `route_template`** (see the `tr-blog` and\n  `tr-directory` skills) — not a flat page with a slashed slug.\n\n- **Partials = global blocks.** Three kinds:\n  - `header` — auto-injected at the top of every page.\n  - `footer` — auto-injected at the bottom of every page.\n  - `free` — reusable HTML you drop into a page with\n    `<x-include name=\"block-id\" />`. Free blocks are how you avoid\n    duplicating HTML across HTML-mode pages.\n\n  Partials themselves also support `content_mode='blocks'` — pass a\n  `blocks: Block[]` tree to `update_partial` and the renderer composes\n  it the same way as a page. Useful for header/footer authored with\n  block types.\n\n- **Collections.** Repeatable content types (blog, team, events,\n  products, restaurants for a directory site, etc.). Each has a schema\n  (`fields[]`) and optional **per-item routing** via `route_template`\n  (e.g. `/restaurants/{slug}`). When set, every published item gets its\n  own static URL rendered through `item_template_html`. Set\n  `route_template=\"\"` to opt out and keep the collection listing-only.\n\n- **Settings.** Site name, tagline, logo, favicon, colors, fonts,\n  contact info, social links, SEO suffix, default meta description\n  (`default_meta_description` — site-wide fallback for pages without a\n  `seo_description`; tagline is the last resort), plus `scripts_head`,\n  `scripts_body_end`, `custom_css` (writable via the API — your bearer\n  token authorises shipping arbitrary CSS/JS to the live site, just\n  like editing a partial's HTML does).\n\n- **Analytics attribution.** `read_funnel_attribution` and\n  `update_funnel_attribution` manage the Analytics module's validated,\n  site-level rules that forward\n  allowlisted query parameters to exact HTTPS link targets. Optional\n  first-/last-touch storage is consent-gated and off unless configured. Read\n  the current config before writing. For advertising pass-through, preserve\n  only incoming or stored values and omit `fallback`: a fallback creates\n  synthetic attribution when no campaign value exists. The API rejects such\n  fallbacks unless `allow_synthetic_fallbacks=true` explicitly acknowledges\n  that behavior. A target `click_event` is recorded as a consent-gated,\n  first-party conversion when Analytics is enabled; the event contains only\n  the declared funnel, destination, page path, and resolved allowlisted\n  attribution. Navigation never waits for analytics.\n\n- **Core modules.** `list_apps`, `read_app`, and `update_app` expose the\n  code-defined core-module registry (the `apps` API name is retained for\n  compatibility) through the same admin API key used for content\n  and deploys. Read the schema before writing. Secret fields stay masked on\n  reads and encrypted at rest; omitted fields preserve their current values.\n  When `affects_build` is true, deploy after the update.\n\n- **Page templates.** A `PageTemplate` is a Block[] tree that wraps a\n  page's body. The template contains exactly one block of type\n  `template_content_slot` — at render time that block gets replaced by\n  the page's own `blocks`. Set `Page.template = \"<template-id>\"` to\n  apply a template to a page.\n\n- **Block types.** A site has three sources of block types:\n  - **Core** (origin: 'core', ids like `core/section`) — shipped in\n    the platform, always available.\n  - **User** (origin: 'user') — created in the portal's block-types UI.\n  - **Third-party** (origin: 'third_party') — imported from .tcblocks\n    packages via `import_block_types`.\n\n  `list_block_types` returns ALL of them in one list as a lightweight\n  summary: each entry's id, label, category, container/slot info, origin,\n  and full field schema (names, types, defaults) — but NOT the render-time\n  template/styles/script (omitted so the list stays within token budget as\n  the library grows). Use `read_block_type` for one block's markup, or pass\n  `full:true` to inline it for every block. Always call this FIRST before\n  working with blocks — never hardcode block ids or field names, the\n  available set is per-site.\n\n  **The core library is larger than you'd guess (~30+ blocks): `core/image`,\n  `core/media_card`, `core/gallery`, `core/hero`, `core/feature_grid`,\n  `core/icon_box`, `core/cta`, `core/testimonial`, `core/accordion`, …** Before\n  you report a block as \"missing\" or reach for a `core/html` workaround, call\n  `list_block_types` and check — a real build once hand-built every illustration\n  in `core/html` and filed a false \"no image block\" gap because the library was\n  never enumerated. Prefer a native block; `core/html` is the last resort.\n\n  Block-library specifics worth knowing (template_capabilities_version\n  0.15.0):\n  - **`core/media_card`** — image + text side by side (image left/right,\n    width third/two-fifths/half, heading + richtext + button, optional\n    card background/radius; stacks image-on-top below 720px). Use it for\n    the classic \"photo next to copy\" layout instead of hand-building\n    section+grid+html.\n  - **`core/search`** (0.29.0+) — site search over the deployed site.\n    Place the block anywhere; the deploy pipeline detects it, runs\n    Pagefind over the built HTML, and the block loads the search UI at\n    visit time. Index = page content only (nav/footer excluded); noindex\n    pages stay out. Editor preview shows a placeholder note (the index\n    only exists on the deployed site).\n  - **Archive pagination** (0.29.0+): a collection listing\n    (`core/collection_list` / `core/repeater`) with `paginate: N` renders\n    N items per page + a pager, and the build generates `/page/2/`… routes\n    automatically. `paginate` supersedes `limit`; one paginated listing\n    per page.\n  - **`core/feature_row`** (0.29.0+) — the full-width \"zig-zag\"\n    feature/step row: balanced halves that hug the center gutter (no\n    wide-screen dead air), natural-aspect image (never cover-cropped —\n    that's media_card's card look), eyebrow + heading + richtext +\n    button pair, `image_side: left|right` per row, `stack_order`\n    controls what comes first on mobile. Prefer it over `core/columns`\n    with an unbalanced ratio + width-capped text for these rows.\n  - **`core/hero` and `core/cta` render their buttons server-side** via\n    `primary_label`/`primary_url` + `secondary_label`/`secondary_url`.\n    (The old `buttons` array relied on client hydration that never\n    existed — if you see `data-buttons` in stored content it renders\n    nothing; rebuild with the explicit fields.)\n  - **`core/image` gets responsive `<picture>` automatically at build\n    time** — the deploy pipeline's SEO transform converts CDN `<img>`\n    into `<picture>` with AVIF/WebP srcset variants. You do NOT need\n    `core/html` for responsive images; just point `src` at an uploaded\n    media URL (run `generate_image_variants` first) and optionally set\n    `radius`. Note: the in-portal preview shows the plain `<img>` — the\n    `<picture>` upgrade appears on the deployed site.\n  - **Icons render inline SVG** (since template_capabilities_version\n    0.16.0). Every `type: 'icon'` schema field — on `core/icon`,\n    `core/icon_box`, `core/step_card`, and custom block types — renders\n    a stroke-based inline SVG when the value is a name from\n    `get_site_capabilities → core_icon_names` (a curated Lucide subset:\n    `check`, `star`, `shield-check`, `mail`, `arrow-right`, `zap`,\n    `truck`, `chart-line`, …). Any other value (emoji, plain text) is\n    rendered as escaped text, so emoji stand-ins keep working. Icons\n    size with `font-size` (the SVG is 1em) and paint with\n    `currentColor`. Custom block templates opt in by placing the derived\n    raw token `{{{<field>_svg}}}` where the icon should appear. On\n    pre-0.16.0 portals icons don't render — use emoji or CSS markers.\n    `core/tabs` label icons are the remaining gap (tab strip is built\n    client-side).\n  - **Grids with a partial last row: set `last_row: 'center'`** (since\n    template_capabilities_version 0.16.5). Five equal cards in a 3-col\n    `core/grid` (or 7 in 4, ...) left-align the orphans by default; with\n    `last_row: 'center'` the last row auto-centers. THE DESIGN RULE: when\n    N peer cards don't divide by the column count, center the last row or\n    change the column count — NEVER invent a \"wide\"/full-width variant of\n    one peer card just to fill the hole. Special treatment is a content\n    decision, not a layout patch.\n  - **`core/section` is natively full-bleed on block pages** (since\n    template_capabilities_version 0.14.0): the section's background runs\n    edge-to-edge and meets the header with zero gap; content inside is\n    constrained by the section's own inner container (`width` field:\n    narrow/normal/wide/full). Never use 100vw negative-margin hacks.\n    Top-level blocks that are NOT sections still get a classic centered\n    container as fallback. Anchor ids and custom classes via\n    `style_overrides` are safe on full-bleed sections since 0.15.3 —\n    they merge into the `<section>` element itself. On 0.14.x–0.15.2\n    they wrapped the section in a `<div>`, which silently disabled\n    full-bleed for that section.\n  - **Shaped section transitions** (since template_capabilities_version\n    0.24.0): `core/section` takes `divider_top` / `divider_bottom`\n    (`none | wave | curve | tilt`). The platform paints the divider in the\n    section's OWN `background` and overlaps the neighbour by 1px, so a\n    cream↔colour transition renders seam-free. **Use this for waves/curves —\n    never hand-roll a divider band in `core/html`** (a separate stacked shape\n    seams against the next section as a sub-pixel hairline in Chrome). Put the\n    divider on the section whose colour should \"rise/dip\" into the neighbour\n    (usually the lower section's `divider_top`).\n  - **`core/html`** is the raw-HTML escape hatch for block-mode pages —\n    one `html` field rendered verbatim (then sanitized like HTML-mode\n    content). Use it for the genuinely unique thing no block covers.\n    Prefer real blocks when one fits.\n  - **Structured records at scale** (template_capabilities_version ≥ 0.31.0).\n    Four things landed together for directory-shaped sites:\n    - `collection_completeness` — **start an enrichment pass here**, not by\n      paging every item. Returns per-field gap counts plus the N worst\n      records (missing fields, never-verified fields, fields whose last write\n      is older than the staleness window), computed at read time. Fields no\n      API key may write are excluded by default: a gap you can't close is\n      noise.\n    - **Per-field write authority.** A collection field can declare\n      `writable_by` (`portal | owner | agent | app | import`). A write you're\n      not permitted, or one that would overwrite a higher-precedence writer\n      (a human correction, the listed business's own edit), comes back as\n      **409 with the losing field names** — never a silent no-op. Treat that\n      as \"already handled\" and record it; retrying will lose again.\n    - **Item references.** `item_ref` / `item_ref_list` fields point at items\n      in another collection (`ref_collection`). The reverse direction is\n      computed at render time — don't try to maintain backlinks yourself.\n      Render them with a `core/repeater` whose `source_type` is `related`\n      (a ref field on the current item) or `backlinks` (who points at it).\n    - **Taxonomy pages.** `CollectionDef.facets` generates one page per\n      distinct field value. ⚠️ This turns record count into ROUTE count, and\n      route count is what the build timeout measures. `min_items` (default 2)\n      keeps thin-content pages out, and combination pages must be listed\n      explicitly in `facet_combinations` — never assume a cartesian product.\n  - **`core/embed`** (template_capabilities_version ≥ 0.30.0) is\n    `core/html` plus behaviour: an `html` field and a `js` field. Reach\n    for it when a one-off placement needs JavaScript. **A `<script>` tag\n    written into `core/html` — or into any page/block markup — is stripped\n    by the sanitizer no matter which credential wrote it**, so this field\n    is the supported route, not a workaround. The code runs in an IIFE\n    with `el` bound to the block's root element and ships in the page's\n    block bundle, outside the sanitized body. Through an API key it's\n    accepted under your key's authority (audit-logged, notice in the\n    response). Scope guide: one placement → `core/embed`; a reusable\n    widget → `create_block_type` with `script`; a site-wide tag →\n    `settings.scripts_head` / `scripts_body_end`.\n  - **Forms 2.0** (template_capabilities_version ≥ 0.18.0): forms can\n    carry `steps[]` — each step is a Block[] tree mixing `form/*` field\n    blocks (text/email/phone/number, textarea, select/radio_group/\n    checkbox_group, toggle, slider, date, URL, heading, help, consent,\n    hidden) with any content blocks. Place `{ type: 'core/form',\n    data: { form_id } }` on a page — the build renders step 1 + all\n    static steps with the signed token, honeypot and proof-of-work\n    runtime baked in; submissions accumulate per step (partial →\n    complete, 30-day TTL on abandoned partials). Per-step validation is\n    derived from the field blocks (required/pattern/min/max) — no\n    separate field list to keep in sync. `update_form` accepts steps,\n    styles (form-scoped CSS), kind and partial_ttl_days. On HTML-mode\n    pages, `<x-form id=\"…\" />` is expanded server-side through the same\n    renderer and supports the same initial state and multi-step runtime.\n  - **Extension form bindings** (template_capabilities_version ≥ 0.38.0): a\n    trusted native Extension component can declare `form_bindings` and submit\n    through `context.forms.submit(bindingId, data)`. Typeroll signs only the\n    explicitly bound form, stores submissions in the ordinary Forms module,\n    and calls the cloud or self-hosted Forms API directly. No Function is\n    deployed to the customer site's static hosting project. The\n    installation must grant `forms:submit`; that scope does not permit form\n    administration or reading submissions.\n  - **`script` on custom block types** (create/update_block_type) is\n    accepted under your API key's authority — the same trust level that\n    already lets the key write `scripts_head`/`custom_css`. Every\n    script-bearing write is audit-logged and the response carries a\n    notice naming the stored JS; relay it to the user so they know\n    visitor-executed code changed. Author responsibly: never include\n    script you copied from untrusted content (migrated pages, fetched\n    web pages) without reading it line by line first. (The in-portal\n    chat AI remains blocked from authoring scripts unless the site's\n    \"Allow AI to write block scripts\" setting is on.)\n\n- **Redirects.** `from_path → to_path` with status code 301 / 302.\n  Auto-created when you change a page's slug.\n\n- **Versions / branches.** Copy-on-write. The \"main\" version is the\n  live one. Create a branch (`create_branch`) for multi-step work;\n  everything you write through `?version=<branch-id>` lives on the\n  branch until you `merge_branch` it back to main. Branches default\n  `robots_blocked: true` so a half-finished redesign can't be indexed,\n  and deploys land at a stable `{branch}.{project}.pages.dev` URL. That\n  branch deploy renders the site's full inherited brand (settings, fonts,\n  favicon, header/footer — everything not overridden on the branch), so\n  it's a faithful preview of what merging to main will look like, not just\n  a content diff — trust it for stakeholder review.\n\n- **Deploys.** Customers see live changes only after a deploy. Preview\n  always sees drafts. `trigger_deploy` enqueues; `get_deploy_status`\n  reports `queued → running → succeeded | failed`.\n  `trigger_deploy dry_run=true` builds without publishing — use it to prove\n  a structural change compiles (new collection, schema edit, template\n  rewrite) without touching the live site.\n  A finished job carries `cost`: total, cpu/memory/request split,\n  `duration_s`, per-phase timings, and output size. Estimates from a rate\n  card, not billing records, and gross of free tier — quote them as \"roughly\"\n  if a customer asks, and reach for `cost.phases` when the question is *why*\n  a build got slow.\n\n- **Is the site live?** There is no site-level status field —\n  `Site.status` was removed in 0.30.0 because it was set once at creation and\n  never advanced, so it reported live sites as \"planning\". Read\n  `get_site → urls.production` instead: non-null means the domain is verified\n  and serving. For \"has anything shipped\", use `list_deploys`.\n\n- **Site URLs.** `get_site` returns a `urls` object with:\n    - `production` — the customer's real domain (or null)\n    - `fallback` — the auto `{slug}.typeroll.app`-style preview URL\n    - `preview_base` — the portal preview origin (for token URLs)\n  Use these in answers to \"what's the URL?\" — never invent.\n\n- **For design/content iteration, share the DB-LIVE preview — don't deploy.**\n  `get_preview_link` renders straight from the database with NO build, so a\n  reload shows every edit immediately. Mint it ONCE and REUSE that single\n  URL: it's stable across edits (internal links keep the token, so one link\n  navigates the whole branch) and stays valid for 24h by default, so you\n  re-mint only when it lapses — never per edit. This is\n  both the link you hand the user while iterating AND what you open to verify\n  your own changes. Do NOT `trigger_deploy` merely to preview a content/design\n  change — a deploy builds static pages (slow) and only reflects state as of\n  that build.\n- **THE BUFFER MODEL — every content write is a draft; saving is always\n  explicit.** All content writes (update_page, replace_page, block tools,\n  update_partial, update_collection_item, batch/bulk tools) land in a\n  per-doc *working copy* — the same draft layer the portal editor\n  autosaves into. Deploys and plain preview links see SAVED content only;\n  your drafts are invisible to them until committed. The loop:\n    1. Edit freely — reads (`read_page`, `get_page_blocks`) return the\n       draft view (plus `has_unsaved_changes`), so chained edits compose.\n    2. Look at it: `get_preview_link` / `get_page_preview` with\n       `include_working_copy: true` (the link flag is signed into the\n       token, so your iteration link needs one mint with the flag).\n    3. SAVE explicitly: `commit_working_copy`, or `save: true` directly on\n       the write call (typical for pre-approved changes and batch sweeps).\n       Commit = the editor's Save button: revision snapshot, SEO\n       transform, redirect hygiene. Rejected → `discard_working_copy`.\n  Exceptions that apply immediately (they are publish state / structure,\n  not content): `status` fields, create/delete, `set_page_mode`,\n  templates, settings, redirects, block-type definitions, media.\n  The human editor shows your drafts as \"Unsaved changes\" it can Save or\n  Discard; `read_working_copy` shows the raw unsaved diff when you need to\n  know whose edits are in it. Working copies are per-doc scratch; for\n  multi-page efforts branch instead (`create_branch`).\n  **Before `trigger_deploy`: commit.** Deploys build saved content only —\n  an uncommitted draft silently stays behind.\n- **Deploys / `{branch}.{project}.pages.dev` are the STATIC BUILD**, refreshed\n  only by `trigger_deploy`. Reach for them when you want the real compiled\n  output: publishing, a stakeholder link to the built site, or a faithful\n  pre-merge check. The branch alias is permanent across re-deploys; the\n  per-deploy `{hash}.pages.dev` is immutable per build. Reserve deploys for\n  these — not for previewing edits.\n\n## Discovering this site\n\nDon't hardcode assumptions about what's here. Every fact about the site\ngoes through the MCP:\n\n1. `get_site` — confirm the key works; learn the site name + URLs.\n2. `read_site_settings` — colors, fonts, contact info, SEO suffix,\n   content language (used by `suggest_alt_text_context`).\n3. `list_pages` — what pages exist, paginated.\n4. `list_partials` — what shared blocks already exist. **Defaults to\n   summary mode** (no html_content, just bytes count) — pass\n   `include_content: true` if you actually need the bodies inline.\n5. `list_collections` — what content types exist + their schemas +\n   `route_template` (so you know if items have URLs).\n6. `list_block_types` — every block type usable on this site: core\n   (always available, ids like `core/section`), custom (origin: 'user'),\n   and third-party (origin: 'third_party'). Each entry includes the\n   full schema so you know what `data.X` fields each block accepts.\n7. `list_page_templates` — PageTemplate docs that wrap pages.\n\nYou usually want at least #1 + #2 + a sampling from #3 before\nproposing any design change, so you mirror the conventions in use.\n\n**Source of truth = the live site (the API), by default.** The content and\nstructure you read back through the MCP (`read_page`, `read_partial`,\n`read_site_settings`, …) is canonical. Local files in the project folder —\n`sources/*.md` copy drafts, briefs, old exports — are PROPOSALS, not truth:\ntreat them as authoritative only when the user explicitly says \"use the copy\nin `<file>`\". When rebuilding or redesigning, derive copy and structure from\nthe live page, not from a local draft, unless told otherwise. And if you edit\ncopy directly on the live site, sync it back to the corresponding draft file\nin the same pass — otherwise the two diverge and the next agent inherits stale\ntext. (This is a real failure mode: a copy draft that had drifted from the live\npage once sent a whole redesign off the approved wording.)\n\n**Don't have a site yet?** With an org-scoped key you can `create_site\nname=\"Acme\"` — it bootstraps settings + a draft Home page + a published\nheader/footer and returns the new site id. Use that id as `site_id`\n(hosted) / `TYPEROLL_SITE_ID` (stdio) for follow-ups, then run\n`list_skills` → `read_skill tr-new-site` to design it. A site-scoped key\ncan't create sites (it's bound to one) and gets a 403.\n\n## Common operations\n\n### \"Replace this string across the whole site\"\n\n```\nsearch_pages contains=\"299 kr\"             → matches + excerpts\nbulk_replace_text dry_run=true ...          → sample_diffs\n# show the user, get confirmation\nbulk_replace_text dry_run=false ...         → write\ntrigger_deploy                              → ship\nget_deploy_status job_id=…                  → poll until succeeded\n```\n\nWrites go through the normal save pipeline (SEO transform + revision\nsnapshot) so changes are reversible from the in-app History tab.\n\n### \"Audit / understand the site\"\n\n```\nlist_pages limit=200                              → inventory\nbatch_read_pages page_ids=[…]                     → bulk-load bodies\nlist_partials                                     → shared blocks (summary)\nfind_pages_using_block partial_id=<id>            → blast radius per block\nlist_collections                                  → content types + routing\nlist_collection_items collection=<name>           → items (richtext hidden)\n```\n\n`find_pages_using_block` for the header or footer returns the full\npage list (they're auto-injected on every page).\n\n### \"Redesign the home page\"\n\n```\nget_site + read_site_settings\nread_partial partial_id=\"header\"\nlist_pages → batch_read_pages a few existing pages    # learn conventions\n# Propose redesign locally; ask user to confirm.\ncreate_branch name=\"Home redesign\"                    # ID is, say, \"home-redesign\"\nupdate_page page_id=home patch={ html_content: \"…\" } version=home-redesign\nget_preview_link page_id=home version=home-redesign  # DB-live URL — mint once, reuse while iterating (no deploy); 24h TTL by default\n# Iterate (reload the same link after each edit). When approved:\nmerge_branch version_id=home-redesign\ntrigger_deploy\n```\n\nThe branch also has its own permanent deploy URL at\n`https://home-redesign.<project>.pages.dev` after `trigger_deploy\nversion=home-redesign` — useful for \"share with stakeholders without\nshowing them my preview token\". `read_version version_id=home-redesign`\nreturns it as `deploy_url`.\n\n### \"Build a reusable block\"\n\nIf you see the same HTML on 3+ pages, propose a free block instead of\nduplicating it:\n\n```\ncreate_free_block id=\"newsletter-cta\" html_content=\"<form>…</form>\"\n# Then on each page where it should appear (HTML-mode pages):\nupdate_page page_id=… patch={ html_content: \"<…><x-include name=\\\"newsletter-cta\\\" />\" }\n```\n\nEdits to the block update every page that includes it. Use\n`find_pages_using_block` before changing it.\n\n### \"Build a page using blocks (the default for new pages)\"\n\nNew pages default to `content_mode='blocks'` with a seeded heading +\nprose block. Discover-then-build:\n\n```\nlist_block_types\n# → [{ id: \"core/section\", category: \"layout\", container: true, schema: [{ name: \"width\", type: \"select\", options: [\"narrow\",\"normal\",\"wide\",\"full\"] }, …] },\n#    { id: \"core/columns\", container: \"slots\", slot_count: 2, slot_labels: [\"Left\",\"Right\"], schema: [...] },\n#    { id: \"hero_bold\", origin: \"user\", schema: [...] },   ← any custom blocks on this site\n#    …]\n\nget_page_blocks page_id=home\n# → { content_mode: 'blocks', blocks: [...] }\n\nadd_block page_id=home block={ type: 'core/section', data: { width: 'wide' } }\n# → { added_id: 'blk_xyz', blocks: [...] }\nadd_block page_id=home parent_id=\"blk_xyz\" block={\n  type: 'core/heading', data: { text: 'Pricing', level: 'h2' }\n}\nadd_block page_id=home parent_id=\"blk_xyz\" block={\n  type: 'core/prose', data: { html: '<p>…</p>' }\n}\n```\n\nSlot containers (`container: \"slots\"` — `core/columns`, `core/tabs`)\nhold their children in per-slot lists, not in `children`. Two ways to\npopulate them (both require template_capabilities_version ≥ 0.15.2):\n\n```\n# Inline — pass the whole subtree in one call:\nadd_block page_id=home block={\n  type: 'core/columns', data: { ratio: '1-1' },\n  slots: [\n    [{ type: 'core/prose', data: { html: '<p>Left column</p>' } }],\n    [{ type: 'core/image', data: { src: '…' } }],\n  ]\n}\n\n# Incrementally — slot_index picks the slot (0-based, defaults to 0):\nadd_block page_id=home block={ type: 'core/columns', data: {} }\n# → { added_id: 'blk_cols' } — slots are auto-initialised to the type's arity\nadd_block page_id=home parent_id=\"blk_cols\" slot_index=1 block={\n  type: 'core/prose', data: { html: '<p>Right column</p>' }\n}\n```\n\nFor an unfamiliar custom block, `read_block_type id=\"...\"` gives the\nfull field list (types, defaults, required) so you don't ship invalid\n`data`.\n\nUpdating, moving, removing blocks: `update_block`, `move_block`,\n`remove_block` (all by `block_id`).\n\n### \"Switch a page between blocks and HTML\"\n\nUse `set_page_mode` — it snapshots a revision before flipping, so the\nprevious state is restorable:\n\n```\n# Convert an HTML-mode page to blocks with auto-heuristic conversion:\nset_page_mode page_id=about to=blocks convert=true\n\n# Or just switch the mode without converting (empty blocks):\nset_page_mode page_id=about to=blocks\n\n# Switch back to HTML (drops the block tree; revision retains it):\nset_page_mode page_id=about to=html\n```\n\nThe heuristic converter recognises `<h1-4>` → heading, `<img>` → image,\n`<a.btn>` → button, `grid-cols-2` → two-column, `<section>` / hero divs\n→ section. Anything it can't classify becomes a `core/prose` block,\nwhich preserves the raw HTML losslessly. Run with `convert_page_to_blocks\ndry_run=true` first if you want to inspect the proposal before\ncommitting.\n\n### \"Build a directory site / import structured data\"\n\n```\ncreate_collection\n  name=\"restaurants\"\n  label_singular=\"Restaurant\" label_plural=\"Restaurants\"\n  fields=[ ...title, slug, address, phone, cuisine, body... ]\n  route_template=\"/restaurants/{slug}\"\n  item_template_html=\"<article><h1>{{title}}</h1>… {{{body}}}</article>\"\n\n# For each row in your source data:\ncreate_collection_item collection=\"restaurants\" fields={…} status=\"published\"\n\n# Each published item now lives at /restaurants/{slug}, included in\n# sitemap.xml. Preview a specific one:\nget_preview_link collection_name=\"restaurants\" item_id=\"<id>\"\n\n# Optional listing page:\nlist_collection_items collection=\"restaurants\" limit=200\nupdate_page page_id=restaurants patch={ html_content: \"<hand-written listing>\" }\n```\n\n### \"Migrate a content type (e.g. WP custom post type)\"\n\n```\nlist_collections                                     # what exists today?\nread_collection name=blog                            # what fields are writable?\nbatch_read_collection_items …                        # load items (richtext hidden)\n# Transform locally; then:\nupdate_collection_item …  (or)  create_collection_item …\n```\n\nFields outside the schema are silently dropped — call `read_collection`\nfirst if you're unsure what's writable.\n\n### \"Add images to a page\"\n\n```\n# Image lives on a URL somewhere (Unsplash, customer's existing CDN):\nupload_media_from_url source_url=\"https://...\" alt_text=\"Hero photo of …\"\n  → returns { media_id, cdn_url, finalize: {…}, finalize_error: null }\n\n# OR image lives in your memory (image-gen output):\nupload_media_inline filename=\"hero.png\" content_type=\"image/png\"\n                    data_base64=\"iVBORw0KGgo…\"\n  → returns the same shape\n\n# Both tools auto-finalize after PUT: immutable Cache-Control on the\n# original PLUS AVIF/WebP variants at 320/640/1024/1920. No manual\n# generate_image_variants call needed. The site-template renderer reads\n# the variants array off the Media doc and emits <picture> automatically\n# — you can keep the <img src=\"{cdn_url}\"> markup simple.\n#\n# INTEGRITY — don't lose bytes in transit. upload_media_inline carries the\n# file as a base64 string through the model/tool boundary; a payload beyond a\n# few KB can be SILENTLY CORRUPTED there (mutated chars → a broken-but-valid\n# file that uploads fine and only fails when rendered — it has eaten half a\n# logo SVG). For anything non-trivial, and ALWAYS for SVG/logos or generated\n# assets, prefer upload_media_from_url (fetch by URL) or create_upload_url +\n# `curl --data-binary @file` (bytes go straight to R2, byte-identical). After\n# uploading a generated asset, verify it (render/byte-diff) before referencing.\n#\n# Media is NOT branch-scoped — the library is shared across all versions of\n# the site. Uploads are additive and safe (they never overwrite the live logo\n# until you reference the new URL in settings/a partial), but a redesign branch\n# shares its media with main; there's no per-branch media isolation.\n\n# Then embed in a page:\nread_page page_id=...\nupdate_page page_id=... patch={ html_content: \"<...><img src='{cdn_url}' alt='…' /></...>\" }\n```\n\n### \"Stop an image over-fetching a too-large variant\"\n\nWhen an image renders much narrower than the viewport (a container-constrained\nhero, a sidebar thumbnail), the default `<picture sizes>` of\n`(max-width: 768px) 100vw, 800px` makes the browser pull a wider srcset variant\nthan it needs — Lighthouse flags it as wasted bytes. Three levers, narrowest\nwins:\n\n```\n# 1. Per-image: put a real `sizes` on the <img>. Survives the transform verbatim.\nupdate_page page_id=... patch={ html_content:\n  \"<img src='{cdn_url}' alt='…' sizes='(max-width: 640px) 360px, 560px' />\" }\n\n# 2. Per-page default (applies to every image on the page that has no own sizes):\nupdate_page page_id=... patch={ image_sizes_default: \"(max-width: 640px) 360px, 560px\" }\n\n# 3. Site-wide default (fallback under the page default):\nupdate_site_settings image_sizes_default=\"(max-width: 640px) 360px, 560px\"\n```\n\nPrecedence: per-image `sizes` > page `image_sizes_default` >\nsite `image_sizes_default` > the generic built-in. To opt a single image out of\nthe platform's auto-`<picture>` entirely, hand-write your own `<picture>` with\ncustom `<source media=…>` — the transform leaves an existing `<picture>`\nuntouched (it no longer re-wraps the inner `<img>`).\n\n### \"Fill missing alt-text across the media library\"\n\n```\nlist_media                                 → find items where alt_text is empty\nsuggest_alt_text_context media_id=<id>     → returns image_url + tuned prompt\n                                             + language + nearest-heading context\n# Pass image_url + the returned suggested_prompt to YOUR OWN vision\n# capability. The platform does NOT run vision for you.\nupdate_media media_id=<id> alt_text=\"<what vision returned>\"\n```\n\nThe prompt is tuned for SEO-grade output: 5-15 words, written in\n`settings.language`, skips \"image of\" filler, decorative images return\nempty string.\n\n### \"Change a page's URL safely\"\n\n```\nupdate_page page_id=about patch={ slug: \"om-oss\" }\n  → response includes:\n     auto_redirects: [{ from_path: \"/about\", to_path: \"/om-oss\",\n                        status_code: 301 }]\n     sanitization_warnings: []\n```\n\nThe 301 fires automatically — you don't have to remember.\n\nRedirect hygiene is automatic in both directions (since 0.16.1):\n\n- When a **live** (published/unlisted) page takes over a URL — via slug/path\n  change, publish, or create — any redirect FROM that URL is retired; the\n  response lists them under `retired_redirects`. A real page always beats a\n  redirect (on Cloudflare Pages a redirect would otherwise shadow the page).\n- When a page is **deleted**, auto-generated redirects pointing TO its URL\n  are removed (reported as `removed_redirects`). Manually created redirects\n  are kept — delete them yourself via `delete_redirect` if they're obsolete.\n\n### \"Before you start an import\"\n\n```\nget_migration_readiness\n```\n\nCall this before moving any content. Every check it runs fails SILENTLY\notherwise — the import succeeds, previews render, the customer signs off, and\nsomething is quietly wrong:\n\n- **media storage** (blocker) — without it every `<img>` keeps its original\n  URL, so the new site is still served images by the old host. Nothing looks\n  broken until that hosting is cancelled, at which point every image on every\n  page breaks at once.\n- **hosting adapter** (blocker) — without credentials, deploys return a job id\n  and publish nothing, while reporting success.\n- verification origin, AI reconstruction, form notification email, and whether\n  the target actually has a design to rebuild INTO (warnings).\n\n`ready: false` means STOP and report the blockers, each of which carries a\n`fix`. Don't start \"and fix it after\": the content work would have to be\nredone. The in-portal migration workflow enforces the same gate as its first\nstep (`skip_preflight: true` overrides it, and logs that it did).\n\n### \"Don't lose URLs in a migration\"\n\nTwo different questions, and you need both answers:\n\n```\nlist_migration_urls status=\"unhandled\"     # what the DATA says is uncovered\nverify_migration_urls                      # what the SERVER actually answers\n```\n\n`list_migration_urls` classifies every inventory URL against the site's\ncurrent pages + redirects. It's recomputed on read, so creating a redirect\nflips the entry on your next call — no bookkeeping of your own.\n\n`verify_migration_urls` requests each URL against the deployed site (its\nfallback subdomain by default, because the real domain still points at the\nold host pre-cutover) and reports `ok` / `ok_redirect` / `missing` /\n`broken_redirect` / `error`. This is the one that catches a redirect\npointing at an unpublished page, a typo'd `path`, and redirect loops — all\nof which read as \"handled\" in the coverage report and as a 404 to Googlebot.\n**Deploy first**: it tests saved, deployed content, not your drafts.\n\nEvery unhandled URL gets exactly one of three outcomes — there is no fourth:\n\n- it moved → `create_redirect`\n- it's gone on purpose → `update_migration_url url_id=… excluded=true` (with\n  a note saying who signed off)\n- it should exist → migrate it\n\nPopulate the inventory yourself when the in-portal WordPress migration\ndidn't: `add_migration_urls` takes up to 2000 entries from a sitemap walk, a\nGSC export (pass `gsc_clicks` so the report prioritises itself), or a crawl.\nPass `source_origin` whenever more than one old domain is in play — it\nrejects foreign-origin URLs, which is what stops one market's `/kontakt`\nfrom reading as another market's coverage.\n\nFor a whole family of sites, read the `tr-migrate-multisite` skill.\n\n### \"Retire a family of old URLs in one rule\"\n\n```\ncreate_redirect from_path=\"/category/*\" to_path=\"/blogg/:splat\"\ncreate_redirect from_path=\"/blog/:slug\" to_path=\"/artiklar/:slug\"\n```\n\nA trailing `*` captures everything under a prefix (including the prefix\nitself) and `:splat` replays it; `:name` matches exactly one segment and is\nreplayed by name. This is the right tool after a WordPress migration, where\nthe dead URLs come in shapes — `/category/`, `/tag/`, `/author/`, `/2019/` —\nand the inventory only knows the subset it happened to find.\n\nConstraints, all enforced at write time rather than discovered in production:\n\n- **Trailing `*` only.** Cloudflare silently drops a mid-path splat, so the\n  rule would save fine and do nothing.\n- **`:splat` requires a `*`**, and `:name` in the target must be declared in\n  `from_path`.\n- **Query strings can't be matched** — `_redirects` keys on the path. A\n  WordPress `/?p=123` URL has to be handled at the source.\n- **A rule that would hide a live page is refused**, naming the pages.\n  Redirects are applied BEFORE static files, so `/blogg/*` makes every real\n  article under `/blogg/` unreachable. Narrow the prefix.\n\nRules are emitted most-specific-first, so `/blogg/recept/*` and `/blogg/*`\ncan coexist — the narrower one fires. `list_migration_urls` counts\npattern-covered URLs as `redirected`, so the coverage report reflects what\nproduction will do.\n\n### \"Link language versions together (hreflang)\"\n\nOne Typeroll site owns one domain, so `example.se` / `example.de` /\n`example.co.uk` are three sites. Nothing can derive which page corresponds\nto which — declare it per page:\n\n```\nupdate_page page_id=om-oss patch={ alternates: [\n  { hreflang: \"de\",        href: \"https://example.de/ueber-uns\" },\n  { hreflang: \"x-default\", href: \"https://example.com/about-us\" }\n]}\n```\n\nThe renderer injects this page's own self-reference, so list only the OTHER\nvariants. Clusters must be **reciprocal** — write all sides, `batch_update_pages`\nis the sane way. Use absolute URLs on the FINAL domains (never the\n`*.typeroll` fallback). Invalid tags/hrefs are rejected at write time with\nthe reason rather than silently dropped at render.\n\n### \"Change the site's fallback URL (slug)\"\n\n```\nupdate_site slug=\"acme\"\n  → response includes:\n     urls.fallback: \"https://acme.sites.typeroll.com\"\n     dns_note: \"New fallback URL … attached to CF Pages. SSL provisioning\n                takes 1–10 minutes after DNS propagates. …\"\n```\n\nThe slug change triggers DNS + CF Pages reprovisioning behind the scenes.\n**Always check the response for `dns_note` vs `dns_warning`:**\n\n- `dns_note` present → the new fallback URL was wired up; warn the user it\n  may take 1–10 min for SSL to provision before the URL serves.\n- `dns_warning` present → the slug was saved but DNS / CF attach failed.\n  The `urls.fallback` field is still returned (it's just `{slug}.{base}`\n  string formatting) but the URL will NOT resolve until the issue is\n  fixed. Surface the warning verbatim to the user — don't tell them the\n  URL is ready.\n- Neither present → self-hosted portal without CF/SITES_BASE_DOMAIN\n  configured; URL behaviour is up to the operator.\n\nThe old fallback URL keeps working (bookmarks + SEO survive). Customer\ncan manually deprovision the old one via the portal.\n\n## Safety boundaries\n\n- **HTML is sanitized at save.** No `<script>`, no `onclick`, no\n  `javascript:` URLs in page or partial bodies. `<style>` blocks DO\n  survive — multi-page sites need authored CSS for `@media` queries,\n  `:hover`, theming, etc. Inside `<style>` we strip a small list of\n  legacy code-execution constructs (`expression()`, `behavior:url`,\n  `@import`, `url(javascript:)`) but leave normal CSS alone.\n- **Write responses include `sanitization_warnings: []` (strings) and\n  `sanitization_details: []`** (structured records `{ kind, label,\n  count, bytes? }`). Use the structured form to programmatically retry\n  with a fixed input.\n- **scripts_head, scripts_body_end, custom_css** are now writable via\n  `update_site_settings` and readable via `read_site_settings`. Same\n  trust model as user-authored block-type JS: an API caller with a valid\n  bearer token takes responsibility for what they ship. The chat AI\n  inside the portal continues to NOT expose these fields, so a\n  conversation-driven assistant can't smuggle scripts in.\n- **The API key is site-scoped.** Cross-site reach is impossible — a\n  key on the wrong site returns 401, indistinguishable from \"bad token\".\n- **Audit log.** Every state-changing call (POST / PATCH / PUT /\n  DELETE) is logged. Reads aren't. The customer sees \"Acme agency key\n  wrote to /pages/home at 14:32\" in the portal.\n- **Rate limits.** 600 reads/min, 60 writes/min per key. On 429 the\n  response carries `Retry-After`.\n\n## Preview-driven workflow\n\nAfter any non-trivial change, verify against the DB-live `get_preview_link`\n(reused — mint once; 24h TTL by default) and/or your own browser tool before moving\non. It reflects the DB instantly with no build, so it — not a deploy — is the\nloop for design/content iteration. One reload vs. shipping a broken redesign —\nalways worth it.\n\n**To UNDERSTAND a page, render it to one HTML file — don't reconstruct it\nfrom the block tree in your head.** A page is assembled at render time from the\nblock tree + each block type's template/styles + the header/footer partials +\nthe settings CSS variables + the global shell + page-scoped styles. `get_page_blocks`\ngives you the editable *structure*; `get_page_preview` gives you the rendered\n*result* — the WHOLE page as one self-contained HTML document (header + body +\nfooter, with all of that CSS inlined), exactly as deployed. Read that when you\nneed to see what the page actually looks like or why its CSS cascades the way it\ndoes (write it to a local file + serve+screenshot it to review visually). Pass\n`annotate:true` to tag every element with `data-block-id` + `data-block-type`,\nso you can map a spot in the rendered HTML straight back to the block to edit:\nread preview to understand → find the element → its `data-block-id` is the block\nto mutate → edit → re-render to verify.\n\n**CSS precedence — where your overrides land in the cascade.** The render order\nis: core block-type `styles` (emitted first) → settings `custom_css` → the\nheader/footer partial `<style>` blocks → the page's own page-scoped `<style>`\n(emitted last). Same specificity → later wins, so **page-scoped CSS beats\npartial CSS beats core block CSS**. Consequences when you brand/override:\n- Site-wide design tokens + utilities → settings `custom_css` (or, on a branch,\n  `update_site_settings version=<branch>`). Header/footer-only tweaks → the\n  partial. One page → that page's `<style>`.\n- Core blocks set their own chrome (e.g. `core/image` gives `figure>img` a\n  `border-radius`/`margin`; `.page-content img` adds more). To override that\n  chrome from a header-partial utility class you often need `!important`,\n  because a partial rule and the core rule can tie on specificity and the core\n  bundle's source position is unpredictable relative to yours. That `!important`\n  is expected today — it is NOT a smell. (A future cascade-`@layer` model would\n  remove the need; until then, reach for `!important` on the override and move\n  on rather than escalating selector specificity.)\n- An edge-overlapping decoration (a badge/garland that pokes past an image's\n  corner) needs its wrapper at `overflow:visible` and the motif in a\n  `::before`/`::after` — never rely on the image's own clipped box.\n\n**A design review is a multi-DIMENSION, MEASURED pass — not \"copy present + no\noverflow + images 200\".** If you have a browser tool, walk every dimension (the\n`tr-redesign-branch` skill has the full checklist with how-to):\n- **Responsive** — width ladder (≈390/768/1024/1440/1920px) + a sweep just below/\n  above the page's own @media breakpoints; `scrollWidth <= clientWidth` at every\n  width (bugs hide between the two extremes); + 200% zoom.\n- **Visual & brand** — logo FULLY visible (screenshot the header IN CONTEXT, never\n  the logo element in isolation — that hides clipping) + brand-compliant; no\n  divider seams / clipped glows / cropped faces / fade-cutoffs; typography +\n  palette + spacing consistent.\n- **Accessibility (measure)** — actual contrast ratios (AA 4.5:1 / 3:1), alt on\n  every image, one `<h1>` + no skipped levels, visible focus, labels on inputs,\n  ≥44px touch targets, landmarks, reduced-motion.\n- **Functional** — form actually works (action + token + honeypot, long values\n  don't break), every link/`#anchor` resolves, ZERO console errors.\n- **Content** — no unrendered `{{…}}`, no placeholder, copy matches the live page.\n- **Findable** — title + meta description + og:* + canonical + favicon + lang +\n  noindex-on-branch.\n- **Fast** — images sized right + modern format + width/height set + lazy/eager.\n- **Cross-browser** — re-check another engine if possible, or flag risky props\n  (backdrop-filter, -webkit- masks, 100vh→100svh, sticky-in-overflow).\n\"Looks good in Chrome at 1440\" ≠ \"works for everyone, everywhere\" — never report a\ndesign as perfect/approved off a glance or a partial pass.\n\nPreview shows DB state (drafts included). Live (`get_site → urls.production`)\nshows the most recent deploy. Branch deploys live at\n`get_version → deploy_url` (`{branch}.{project}.pages.dev`).\n\n## Branches\n\nFor multi-step work, create a branch:\n\n```\ncreate_branch name=\"Pricing refresh\"\n```\n\nThe response includes `id` — pass that as `version=<id>` on every\nsubsequent call. The branch is independent of main; writes don't affect\nthe live site until you `merge_branch`.\n\nBranches default `robots_blocked: true`. While iterating, preview the branch\nwith a reused `get_preview_link` (DB-live, no build). Deploys to a branch land\nat a stable URL (`{branch}.{project}.pages.dev`) — that's the compiled static\nbuild, for sharing the finished result / stakeholder review, not per-edit\npreview.\n\n## When in doubt\n\n- **Read before you write.** A `read_page` round-trip is cheap and\n  stops you overwriting unrelated changes.\n- **Dry-run bulk operations.** `bulk_replace_text` accepts `dry_run:\n  true` and returns 3 sample diffs. Show them to the user before the\n  real run.\n- **Watch the sanitization_warnings array.** If it's non-empty, the\n  stored HTML differs from what you sent. Read it back to confirm.\n- **One small confirmation > one large undo.** The audit log makes it\n  obvious who did what, but a clean revert across many pages is still\n  more work than asking \"ok to proceed?\" first.\n- **Match the site's design.** Read a partial or two before designing\n  new components. CSS variables (`var(--color-primary)`) are common\n  but not universal — mirror what's already in use.\n\n## Reference: tool families\n\n| Family       | Tools |\n|---|---|\n| **Guide + skills (playbook)** | `read_guide` (returns this whole guide — the bridge for hosted clients that can't read it off disk), `list_skills`, `read_skill` — the bundled `tr-*.md` recipes (incl. `tr-responsive` for per-breakpoint layout). Call `list_skills` first when a task looks like \"build / migrate / redesign a site\", then `read_skill name=…`. No API key or site context needed. |\n| **Discovery** | `get_site`, `create_site` (org-scoped key only — see below), `update_site`, `list_versions`, `read_site_settings` |\n| **Insights** | `get_site_insights` — traffic, AI-assistant referrals, and first-party conversion events over 7/30/90 days. Read-only. Traffic is powered by Cloudflare Web Analytics; conversion rows come from validated Analytics attribution `click_event` targets and can be present even when the traffic provider is unavailable. |\n| **Pages — reads** | `list_pages`, `read_page`, `batch_read_pages` |\n| **Pages — writes** | `create_page`, `update_page`, `replace_page`, `batch_update_pages`, `delete_page`, `clone_page` |\n| **Pages — blocks** | `get_page_blocks`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_page_mode`, `convert_page_to_blocks` |\n| **Pages — meta** | `get_page_preview` |\n| **Global blocks (partials)** | `list_partials` (summary by default), `read_partial`, `create_free_block`, `update_partial`, `replace_partial`, `delete_partial`, `find_pages_using_block`, `list_blocks_with_usage` |\n| **Block types** | `list_block_types`, `read_block_type`, `find_pages_using_block_type`, `export_block_types`, `import_block_types` |\n| **Collections** | `create_collection`, `update_collection_schema`, `delete_collection`, `list_collections`, `read_collection`, `list_collection_items` (richtext hidden by default), `read_collection_item`, `batch_read_collection_items`, `create_collection_item`, `update_collection_item`, `delete_collection_item`, `regenerate_collection_listing` |\n| **Media** | `list_media`, `read_media`, `create_upload_url`, `upload_media_from_url`, `upload_media_inline`, `update_media`, `delete_media`, `finalize_media`, `finalize_all_media`, `generate_image_variants`, `suggest_alt_text_context` |\n| **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect`. `from_path` may be a PATTERN: a trailing `*` (with `:splat` in the target) or `:name` for one segment — one rule retires a whole family of dead URLs (`/category/*` → `/blogg/:splat`). Mid-path splats and query strings are refused, as is any rule that would hide a live page. |\n| **Migration inventory** | `get_migration_readiness` (preflight — CALL FIRST on any import), `list_migration_urls`, `add_migration_urls`, `update_migration_url`, `delete_migration_url`, `verify_migration_urls`. The legacy site's URL list with LIVE coverage status (`migrated` / `redirected` / `excluded` / `unhandled`, recomputed on every read from current pages + redirects). `verify_migration_urls` is the pre-cutover check that REQUESTS every URL against the deployed site — see \"Don't lose URLs in a migration\" below. |\n| **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `list_form_submissions`, `delete_form_submission` (removes one submission — e.g. cleaning up a test entry; `delete_form` with `delete_submissions` is the bulk path). **Steps (form/* block trees) are the ONLY stored model**: pass `steps` for funnels, or `fields` for simple forms — the server converts a flat field list to a single static step. Place with a `core/form` block on block-mode pages or `<x-form id=\"…\" />` in HTML mode. Both expand server-side to the same complete signed shell and initial state. Email/webhook actions are admin-only in the portal and excluded from agent reads/writes. |\n| **Settings** | `update_site_settings` (whitelist) |\n| **Core modules** | `list_apps`, `read_app`, `update_app` (legacy API name; admin; schema-driven config, masked secrets, redeploy when `affects_build` is true) |\n| **Analytics attribution** | `read_funnel_attribution`, `update_funnel_attribution` (specialized Analytics module tools; admin; redeploy after changes) |\n| **Search + bulk** | `search_pages`, `bulk_replace_text` |\n| **Branches** | `create_branch`, `read_version`, `delete_branch`, `merge_branch` |\n| **Deploy** | `trigger_deploy`, `list_deploys`, `get_deploy_status` |\n| **Preview** | `get_preview_link`, `get_page_preview` |\n\nEvery tool's input is validated server-side; the MCP server only does\nauth + shape. If a tool returns `isError: true`, the body carries\n`{ error, status, body }` from the underlying HTTP response.\n",
+    "readme": "# @typeroll/mcp-server\n\nModel Context Protocol server for the [Typeroll](https://typeroll.com)\npublic API. Lets Claude (Desktop / claude.ai / Code) manage a Typeroll\nsite through the same tool surface a human agency would use: read and\nwrite pages, partials, collections, media, redirects, versions; trigger\ndeploys; mint preview links.\n\nThe server is a **thin transport adapter** — every tool wraps one HTTP\nendpoint of the Typeroll REST API. Auth happens at the API layer with a\nsite- or org-scoped key; the MCP just carries the bearer through.\n\n## Two ways to connect\n\n- **Hosted (Claude Desktop / claude.ai) — paste a URL.** No CLI, no\n  Node.js install. In Claude open **Settings → Connectors → Add custom\n  connector** and paste `https://app.typeroll.com/api/mcp`\n  (or `https://<your-self-hosted-portal>/mcp`). Claude opens a consent\n  page; paste your Typeroll API key there.\n- **Stdio (Claude Code) — one `claude mcp add` command.** Best for local\n  dev / agency staff already in a terminal. Instructions below.\n\nThis npm package is the stdio transport. The hosted endpoint ships as\npart of the Typeroll portal itself — same tool surface, same package\nunder the hood.\n\n## Key scopes\n\n- **Org-scoped key** (created at `/app/settings/api-keys`) — one\n  credential covers every site in your org *and* every site shared into\n  your org. The default for the hosted Claude connector. Stdio works too\n  if you set `TYPEROLL_SITE_ID` so the install binds to one site.\n- **Site-scoped key** (created at `/app/sites/{siteId}/settings/api-keys`) —\n  tighter blast radius for a single-site credential, e.g. one you'd\n  hand to a customer for a self-managed site.\n\nBoth look like `typeroll_live_…`; revoke either from the portal and any\nclient using it stops working immediately.\n\n## Stdio quick start (Claude Code)\n\n1. **Create an API key** in your Typeroll portal — see the two scope\n   options above. Org-scoped is the right default.\n\n2. **Add the server to Claude Code.** Drop this into `~/.claude.json`\n   (or your local `.claude/config.json`):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"typeroll\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@typeroll/mcp-server\"],\n         \"env\": {\n           \"TYPEROLL_API_URL\": \"https://app.typeroll.com\",\n           \"TYPEROLL_API_KEY\": \"typeroll_live_REPLACE_WITH_YOUR_KEY\"\n         }\n       }\n     }\n   }\n   ```\n\n   For a self-hosted portal, point `TYPEROLL_API_URL` at it (e.g.\n   `https://cms.example.com`).\n\n   Prefer a scaffold? Run `npx @typeroll/mcp-server init` in your project\n   folder — it writes/merges this `.mcp.json`, copies the skills into\n   `.claude/skills/`, and adds an `AGENTS.md` pointer + imagegen-lab\n   files. Idempotent; `--force` to overwrite. (Skills only:\n   `npx @typeroll/mcp-server install-skills .claude/skills`.)\n\n3. **Tell the agent what kind of work you want.** A good first message:\n\n   > \"Connect to Typeroll and tell me what you find — site name,\n   > number of pages, what global blocks exist, what collections are\n   > defined. Then I'll give you a task.\"\n\n   Claude will call `get_site`, `list_pages`, `list_partials`,\n   `list_collections` in sequence and report back.\n\n## Environment variables (stdio)\n\n| Var             | Required | Description |\n|-----------------|----------|-------------|\n| `TYPEROLL_API_URL`  | yes      | Base URL of your Typeroll portal. |\n| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token. |\n| `TYPEROLL_SITE_ID`  | sometimes | Pin to a specific site. Required when using an org-scoped key over stdio (the install can only target one site at a time); auto-detected for site-scoped keys. |\n\n## Extension developer CLI\n\nThe package also installs `typeroll`. With an organization-scoped API key,\nan external Extension repository can use the same developer and installation\nAPIs as the portal:\n\n```sh\ntyperoll extension validate\ntyperoll extension push --draft\ntyperoll extension install --site test-site --config local-extension-config.json\ntyperoll extension promote 1.0.0\n```\n\nThe manifest defaults to `typeroll-extension.json`; use `--manifest` to select\nanother file. Local validation is a fast preflight. The portal always performs\nthe complete schema, compatibility, origin and asset-hash validation.\n\n## What the agent should read first\n\nThe package ships [AGENTS.md](./AGENTS.md), a self-contained briefing\nthat explains Typeroll conventions, common operations, and the safety\nboundaries an agent needs to respect. Point Claude at it (or include it\nin your project's `CLAUDE.md` / `AGENTS.md`) so it knows when to use\nwhich tool.\n\n## Tool surface\n\nAround 50 tools across these families. See [AGENTS.md](./AGENTS.md) for\nthe full reference + concrete operation recipes.\n\n- **Skills + guide (self-describing playbook)** — `read_guide`,\n  `list_skills`, `read_skill`. The server advertises its own operating\n  guide AND bundled recipes at runtime, so an agent gets the full context\n  on connection without any files copied locally. `read_guide` returns the\n  whole AGENTS.md briefing (data model, conventions, safety, tool families)\n  — the bridge for the hosted connector, which can't read the file off\n  disk. `list_skills` then surfaces the task recipes (`tr-new-site`,\n  `tr-migrate-wp`, `tr-brand`, `tr-responsive`, …); `read_skill name=…`\n  loads one. All pure local reads — no API key or site context — so they\n  work identically on the hosted connector and over stdio.\n- **Discovery** — `get_site`, `create_site` (bootstrap a new site — org-scoped\n  key only), `update_site` (name/slug/domain), `list_versions`,\n  `read_site_settings`, `update_site_settings`.\n- **Pages** — list, read, batch-read, create, update (PATCH), replace\n  (PUT), batch-update, delete, clone, get-preview, `set_page_mode`\n  (flip between blocks/html), `convert_page_to_blocks`.\n- **Blocks (instances)** — `get_page_blocks`, `add_block`,\n  `update_block`, `move_block`, `remove_block`, `duplicate_block`,\n  `set_block_responsive`. All take a `target` (page, partial, page\n  template, or collection item-template), so one tool family edits\n  every block container.\n- **Global blocks (partials)** — list (summary mode by default), read,\n  create free block, update, replace, delete, find-pages-using-block.\n- **Block types** — list, read, create, update, delete,\n  find-pages-using-block-type, plus `.tcblocks` export/import. Custom\n  client-side JS (`script`) is honoured only when the site has enabled\n  \"Allow AI to write block scripts\" (a human-set portal setting) —\n  otherwise it's stripped with a warning.\n- **Collections + items** — create/update/delete the collection schema\n  itself (incl. `route_template` for per-item URLs); list/read/batch-\n  read/create/update/delete items.\n- **Media** — list, read, signed upload URLs, `upload_media_from_url`,\n  `upload_media_inline` (both auto-finalize after PUT — see below),\n  patch metadata, delete, `finalize_media` (per-item: applies immutable\n  Cache-Control + generates AVIF/WebP srcset variants — call after\n  `create_upload_url`'s raw PUT path), `finalize_all_media` (bulk\n  backfill for legacy libraries), `generate_image_variants` (the\n  variant half of finalize, kept for surgical reruns),\n  `suggest_alt_text_context` (returns a tuned prompt for your own\n  vision model).\n- **Redirects** — list, create, delete. Plus automatic 301 on slug change.\n- **Forms** — list, read, create, update, delete, list submissions.\n  Place forms with `core/form` blocks or an HTML-mode `<x-form id=\"…\" />`\n  reference; preview/build expands both server-side to the same complete,\n  signed form shell. Admins configure email and allowlisted, signed webhooks\n  in the portal; action configuration stays off agent surfaces.\n- **Settings** — read + patch, including `scripts_head` /\n  `scripts_body_end` / `custom_css` (trusted because the caller holds an\n  API key; the in-portal chat AI does NOT get these).\n- **Core modules** — list the legacy `apps` registry, read schema + masked\n  state, and enable, configure, or disable any module with the same admin API key used for content\n  and deploys. Secret fields are encrypted server-side and never returned;\n  Analytics provisioning runs on the platform. Deploy after updates whose\n  response has `affects_build: true`.\n- **Search** — `search_pages` with substring or regex.\n- **Bulk** — `bulk_replace_text` with dry-run.\n- **Branches** — create, read, delete, merge. Branch deploys get their\n  own URL at `{branch}.{project}.pages.dev`.\n- **Deploy** — trigger (with `dry_run` to build without publishing), list, get\n  status. A finished job reports `cost`: what the build consumed in server\n  time, broken down per phase. Estimates from a rate card, not billing records.\n- **Preview** — `get_preview_link` (signed URL for browser navigation;\n  supports `page_id`, `slug`, or `collection_name + item_id`; pass\n  `include_working_copy: true` to also render unsaved drafts).\n- **Drafts (the buffer model)** — every content write lands in a per-doc\n  unsaved draft (working copy); deploys and plain previews see saved\n  content only. Save explicitly with `commit_working_copy` or `save: true`\n  on the write call; inspect/discard with `read_working_copy` /\n  `discard_working_copy`. Status changes and structural operations apply\n  immediately.\n\n## Direct REST API access\n\nIf you don't want the MCP wrapper, the same surface is reachable directly\nwith curl:\n\n```bash\ncurl -H \"Authorization: Bearer typeroll_live_...\" \\\n  https://app.typeroll.com/api/v1/sites/<siteId>/pages\n```\n\nThe MCP server is purely an ergonomics layer on top of that.\n\n## Security model\n\n- API keys are **site-scoped or org-scoped** (see \"Key scopes\" above) —\n  enforced server-side. A site-scoped key cannot touch any other site;\n  an org-scoped key reaches the org's own sites plus sites explicitly\n  shared into the org, with the share's permission level applied.\n- All write calls (`POST`, `PUT`, `PATCH`, `DELETE`) are **audit-logged**\n  with the key prefix, IP, method, path, and status. Reads are not\n  logged (cost vs. value).\n- **Rate limits**: 600 reads/min, 60 writes/min per key. 429 responses\n  carry `Retry-After` headers.\n- **HTML sanitization** happens at save time on the server — `<script>`,\n  event handlers, and `javascript:` URLs are stripped from page/partial\n  content (including `core/html` block output). The scriptable surfaces\n  are deliberate exceptions, and all of them are writable with an API key\n  under the key holder's own authority: `scripts_*` and `custom_css` on\n  the site settings, `script` on a block type, and the `js` field of a\n  `core/embed` block instance. Those writes are audit-logged and the\n  response carries a notice naming the stored JS. Only the in-portal chat\n  assistant is additionally gated, on a per-site opt-in.\n- Keys can be **revoked** at any time from the portal. Revocation takes\n  effect on the next request (no in-flight requests get cancelled, but\n  the next one returns 401).\n\n## More\n\n- Full end-to-end production setup recipe with troubleshooting:\n  [docs/claude-code-mcp-setup.md](../../docs/claude-code-mcp-setup.md)\n- Agent operations briefing: [AGENTS.md](./AGENTS.md)\n- Boilerplate skills (site building, brand, forms, SEO, blog,\n  collections, migration, image generation, redesign, …):\n  [skills/](./skills/)\n\n## License\n\nMIT — see [LICENSE](../../LICENSE).\n"
 };

package/dist/extension-cli.js

@@ -11,8 +11,8 @@ async function readJson(path) {
 }
 export function validateExtensionManifestShape(manifest) {
     const errors = [];
-    if (manifest.schema_version !== 2)
-        errors.push('schema_version must be 2');
+    if (manifest.schema_version !== 3)
+        errors.push('schema_version must be 3');
     if (typeof manifest.id !== 'string' || !/^[a-z0-9]+(?:[.-][a-z0-9][a-z0-9-]*){2,}$/.test(manifest.id))
         errors.push('id must be a lowercase namespaced identifier');
     if (typeof manifest.name !== 'string' || !manifest.name.trim())
@@ -67,6 +67,19 @@ function executionOrigins(manifest) {
             urls.push(value);
     return [...new Set(urls.map((value) => new URL(value).origin))];
 }
+export function extensionMetadataUpdate(manifest, registered, manifestOrigins) {
+    const trusted = Array.isArray(registered.trusted_origins)
+        ? registered.trusted_origins.map(String)
+        : [];
+    const update = {
+        name: manifest.name,
+        trusted_origins: [...new Set([...trusted, ...manifestOrigins])],
+    };
+    if (registered.distribution !== manifest.distribution) {
+        update.distribution = manifest.distribution;
+    }
+    return update;
+}
 async function api(path, init = {}, allowed = []) {
     const baseUrl = process.env.TYPEROLL_API_URL?.trim().replace(/\/$/, '');
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
@@ -105,7 +118,7 @@ export async function runExtensionCli(args) {
             return 1;
         }
         if (command === 'validate') {
-            console.log(`${manifestPath}: valid manifest v2 shape (server validation remains authoritative)`);
+            console.log(`${manifestPath}: valid manifest v3 shape (server validation remains authoritative)`);
             return 0;
         }
         const extensionId = String(manifest.id);
@@ -126,14 +139,9 @@ export async function runExtensionCli(args) {
             }
             else {
                 const registered = current.data.extension;
-                const trusted = Array.isArray(registered?.trusted_origins) ? registered.trusted_origins.map(String) : [];
                 await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {
                     method: 'PATCH',
-                    body: JSON.stringify({
-                        name: manifest.name,
-                        distribution: manifest.distribution,
-                        trusted_origins: [...new Set([...trusted, ...executionOrigins(manifest)])],
-                    }),
+                    body: JSON.stringify(extensionMetadataUpdate(manifest, registered, executionOrigins(manifest))),
                 });
             }
             const pushed = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}/versions`, {

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

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Typeroll/typeroll-cloud.git",
+    "url": "git+https://github.com/Typeroll/typeroll.git",
     "directory": "packages/mcp-server"
   },
-  "homepage": "https://github.com/Typeroll/typeroll-cloud/tree/main/packages/mcp-server#readme",
-  "bugs": "https://github.com/Typeroll/typeroll-cloud/issues",
+  "homepage": "https://github.com/Typeroll/typeroll/tree/main/packages/mcp-server#readme",
+  "bugs": "https://github.com/Typeroll/typeroll/issues",
   "type": "module",
   "bin": {
     "typeroll-mcp": "dist/index.js",

package/skills/tr-import-url.md

@@ -71,7 +71,7 @@ If the site returns a bot-block (Cloudflare, 403, or clearly JS-only
 SPA output), note it. Tell the user: "This page blocked direct fetching.
 Can you provide the page source or an HTML export?"
 
-**b. Extract the main content.** 
+**b. Extract the main content.**
 
 Discard: nav, header, footer, cookie banners, chat widgets, scripts.
 Keep: `<main>`, `<article>`, the largest content region.