@typeroll/mcp-server 0.45.42 → 0.45.44

package/skills/tr-forms.md

@@ -6,8 +6,8 @@ description: Use when the user wants to add a contact form, newsletter signup, b
 # Add a form to a Typeroll site
 
 Typeroll forms are server-backed. The platform renders the form shell, accepts
-signed submissions, validates declared fields, stores submissions, and can run
-admin-configured email or webhook actions.
+signed submissions, validates declared fields, stores submissions, and runs
+email and webhook actions configured in the portal or through MCP/API.
 
 ## Choose the placement
 
@@ -97,9 +97,23 @@ actions in the form editor:
   `X-Typeroll-Signature`, sends an idempotency key, retries transient failures,
   and stores delivery status.
 
-Actions are deliberately excluded from MCP/API-key writes and reads because
-they can exfiltrate submitted data. Direct the user to the portal form editor
-to configure them.
+Agents manage the same actions with `read_form` (actions with secrets masked)
+and `update_form patch={ actions: [...] }`, with admin permission as in the
+portal. `actions` replaces the whole list: read the form, change what you need
+and send the list back. Examples:
+
+```
+update_form form_id=contact patch={ actions: [
+  { type: "email", config: { to: "hello@example.com", subject: "New lead: {{name}}",
+    body: "<p>{{message}}</p>", include_all: true, reply_to: "{{email}}" } },
+  { type: "email", config: { to: "{{email}}", subject: "Thanks, {{name}}",
+    body: "<p>We will get back to you within a day.</p>" } }
+] }
+```
+
+A webhook needs `url` (https), an explicit `fields` allowlist and a signing
+`secret`; send the masked value back to keep a stored secret. `list_form_submissions`
+reads what visitors sent.
 
 ## Verify
 
@@ -143,7 +157,7 @@ Booking request:
 
 - Do not hand-write a form, token, honeypot, or submit script.
 - Do not put a raw `<script>` in page HTML; the sanitizer removes it.
-- Do not expose action configuration through agent surfaces.
+- Do not drop existing actions by accident: `actions` replaces the list.
 - Do not send every submitted field to a webhook by default; choose the
   smallest allowlist the external register needs.
 - `submit_token` is stable until the platform rotates its form-signing secret;

package/skills/tr-import-url.md

@@ -54,6 +54,16 @@ Parse `<a href>` links to discover internal pages. Build a list:
 Exclude private/session/admin URLs deliberately. Inventory public pagination and
 query routes; decide preservation or retirement from their actual purpose.
 
+**Map source styling to named styles.** A class the source uses for a
+recurring treatment (`.eyebrow`, `.lead`, `.btn-outline`, `.section-dark`)
+becomes a site style with `create_style` and is applied with `style_id`. A
+small label directly above a heading is an eyebrow style, not a heading of its
+own: put it in the heading block's `eyebrow` field (and a line under the
+heading in `subtitle`). Never carry classed raw HTML into text blocks to keep a
+look: the editor cannot edit it, and the next render version may not keep it.
+Build such sections with heading, text, image and button blocks; Typeroll does
+not convert HTML into blocks.
+
 ### 2. Measure the source and protect existing target work
 
 ```

package/skills/tr-migrate-wp.md

@@ -1,6 +1,6 @@
 ---
 name: tr-migrate-wp
-description: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, preserves cleaned HTML and shared references, transfers media, sets redirects, and leaves everything as drafts for human review. Do not apply automatic HTML-to-blocks conversion.
+description: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, preserves cleaned HTML and shared references, transfers media, sets redirects, and leaves everything as drafts for human review. Typeroll does not convert HTML into blocks.
 ---
 
 # Migrate from WordPress to Typeroll
@@ -122,6 +122,11 @@ The managed importer preserves existing imported Pages on retry and refuses
 URL/identity conflicts or dangling term references. An older flattened import
 requires a separately reviewed mapping repair; do not re-import over edits.
 
+**Styles.** Recurring source treatments (theme classes for eyebrows, leads,
+button variants, highlighted sections) become named site styles
+(`create_style`) applied with `style_id`, so editors can change them in one
+place. Do not preserve them as classed raw HTML in text blocks.
+
 ### 4. Import one page at a time, draft status
 
 For each source URL:
@@ -140,7 +145,7 @@ c. Migrate referenced images with `upload_media_from_url`. The customer's
    media reference only after verification. Stop and report a failed required
    transfer; do not silently hotlink the WordPress source.
 
-The managed importer stores cleaned HTML and does not run HTML-to-blocks conversion. Do not call `convert_page_to_blocks` or `set_page_mode` to rewrite that HTML. A person previews and accepts a conversion in the page editor.
+The managed importer stores cleaned HTML. Typeroll does not convert HTML into blocks, and `set_page_mode` never rewrites HTML. Pages move to blocks only when someone rebuilds them with blocks.
 
 d. Preserve exact text, headings, anchors, links, media and semantic structure with native blocks first. Read the
    available block types and map headings, prose, images, buttons and layout

package/skills/tr-new-site.md

@@ -129,6 +129,23 @@ the built-in YouTube/Vimeo/Google Maps/Calendly set. Values are exact domain
 hostnames, never URLs or wildcards. Read the setting back before deciding that
 an iframe cannot be represented.
 
+### 2b. Styles before pages
+
+Set the site's look as named styles before building any page:
+
+1. `list_styles`. New sites already have the standard set (body, H1–H6, link,
+   lead, eyebrow, small, quote, buttons, section). If roles are missing,
+   `apply_standard_styles`.
+2. Adjust them to the brand with `update_style`: the font, the type scale and
+   spacing for `base` (phones) and `at.tablet`/`at.desktop`, and colours from
+   palette tokens. Keep text at WCAG AA contrast; failing styles are refused.
+3. Add a named style for every look the design repeats: a card title, a price
+   note, a highlighted section, a CTA button variant. Use the site's language
+   for names.
+
+Pages then choose styles with each block's `style_id` field. A per-block
+font size, colour or class is only for something clearly unique.
+
 ### 3. Header + footer partials
 
 **Start from the native preset — don't hand-roll navigation.** Read
@@ -275,10 +292,10 @@ Known limitations (honest list — don't fight them):
   client-side without the icon pipeline). Text labels only.
 
 Theming: block primitives render neutral. Brand color/typography comes
-from settings (step 2). For page-specific polish (e.g. a colored card
-treatment), a single `core/html` block with a small `<style>` scoped to
-`[data-bid]`/section selectors is acceptable — keep it minimal and note
-it in your log.
+from settings (step 2) and named styles (step 2b). For page-specific polish
+(e.g. a colored card treatment) that no style covers, give the block a
+`custom_class` and write the rule in the page's `custom_css`. Never put a
+`<style>` in a `core/html` block or target `[data-bid]`/`[data-block]`.
 
 ### 5. Inner pages
 
@@ -286,6 +303,12 @@ Same pattern: `create_page` with `content_mode: "blocks"` and a section
 tree. Standard set: Om oss, Tjänster, Kontakt — or what the brief says.
 Default new pages to `status: "draft"`; publish after review.
 
+Sections that repeat across pages: a call to action or contact strip that
+must stay identical becomes a global block (`make_block_global`, then
+`core/global_block` on the other pages). A section shape you will reuse with
+different content (a pricing row, a feature trio) becomes a block template
+(`save_block_template`, then `insert_block_template`).
+
 ### 5b. If the legacy site is still live, scrape canonical content
 
 For pages with canonical text (privacy policy, terms, about), `WebFetch`
@@ -336,9 +359,8 @@ For migrated legacy pages or a hand-crafted one-off, `content_mode:
   negative-margin escape (`margin-left: calc(50% - 50vw); width: 100vw`)
   — never combine with `overflow-x: clip` on a wrapper.
 - `set_page_mode` flips a page between modes and does not convert HTML.
-  `convert_page_to_blocks` previews a heuristic conversion, including
-  what it could not convert, and does not write. A person accepts that
-  preview in the page editor.
+  Typeroll has no HTML-to-blocks conversion: to move a page to blocks,
+  build its content with blocks.
 
 ## Pitfalls
 

package/skills/tr-page-template.md

@@ -34,7 +34,7 @@ default template, and an individual Page can override it.
 Prefer native image, table, list, heading and content blocks. A rare specialized
 widget can use a reviewed HTML/embed block. Reusable custom behavior belongs in
 one custom block type rather than repeated HTML bodies. Existing HTML-mode pages
-may share fragments through partials and `<x-include>`, but use block templates
+may share fragments through partials and `<x-include>`, but use block-based page templates
 for new content families.
 
 Header/footer partials are global and remain separate from content types. Keep

package/skills/tr-upgrade-rendering.md

@@ -0,0 +1,71 @@
+---
+name: tr-upgrade-rendering
+description: Use when a site's platform render version is behind the latest (read_site_settings → render.version < render.latest), or the user asks to "upgrade rendering", "get the new block styles" or why a platform improvement doesn't show. Compares every page at the current and target version with screenshots, reports the differences and upgrades only with approval.
+---
+
+# Upgrade a site's render version
+
+Platform changes to block markup and shared CSS ship as numbered render
+versions. A site keeps its version until someone upgrades it, so its look
+never changes on its own. Upgrading is a single settings write, reversible by
+writing the previous number. The comparison happens here, in the agent; the
+server only renders previews.
+
+The user can also do this in the portal: Settings → Rendering → "Preview with
+version N", then "Upgrade". Offer this skill when they want a full-site visual
+comparison first.
+
+## Recipe
+
+1. **Read the gap.** `read_site_settings` returns `render`:
+   `{ version, latest, upgrades: [{ version, title, changes[] }] }`. If
+   `version === latest`, stop. Tell the user what each pending version
+   changes, in their words, before measuring anything.
+
+2. **List the pages to compare.** `list_pages` (published and unlisted), plus
+   the header/footer, which appear on every page. For a large site, compare
+   the home page, one page per content type and template, and every page
+   whose blocks use a component named in `upgrades[].changes`.
+
+3. **Mint two links per page set.** One `get_preview_link` without
+   `render_version` (current) and one with `render_version: latest` (target).
+   Both show saved content. Mint each once and reuse it; internal links keep
+   the token.
+
+4. **Screenshot both** at 390, 768 and 1440 px wide, full page, after fonts
+   and images have loaded (`document.fonts.ready`, scroll to the end to
+   trigger lazy images, then back to the top). Use a headless browser with a
+   fixed viewport and `reducedMotion: 'reduce'`.
+
+5. **Compare.** Pixel-diff each pair (same size, small per-pixel tolerance)
+   and record the changed area and the bounding boxes of changed regions.
+   Crop each region from both versions. Ignore differences confined to
+   embedded third-party frames (maps, booking widgets, video).
+
+6. **Report** per page and width: unchanged, or the cropped before/after
+   regions with a one-line description ("links in body text are underlined",
+   "section gap 8px larger"). Link each change to the version note that
+   explains it. Say plainly when a change looks like a regression.
+
+   Before screenshots, read the site and page custom CSS for selectors a
+   version note names. Version 2 moves a heading's or button's custom class
+   onto the `<h2>` or link, so `.my-class .block-heading-text` stops
+   matching; propose the rewrite (`.my-class`) or a named style.
+
+7. **Ask before upgrading.** Never upgrade on your own. If the user wants to
+   keep a specific old look, solve it with a site style or page CSS first and
+   compare again.
+
+8. **Upgrade** with `update_site_settings render_version: <latest>` (pass
+   `version` to do it on a branch first). The preview changes at once; the
+   live site changes at the next deploy. To undo, write the previous number.
+
+## Pitfalls
+
+- Comparing a draft against saved content shows content edits, not
+  rendering changes. Use the same content state for both links.
+- Lazy images and web fonts cause false differences. Wait for them in both
+  screenshots.
+- Comparing only the home page misses changes in components it doesn't use.
+- Don't encode a workaround in custom CSS to resist an upgrade without
+  telling the user; it becomes a hidden fork of the platform styles.