@typeroll/mcp-server 0.45.44 → 0.45.45

package/dist/tools/settings.js

@@ -1,10 +1,10 @@
-// Settings tools. scripts_head, scripts_body_end, and custom_css ARE
-// writable via the public API (as of mcp-server 0.4.x) — the v1 route
-// accepts them and they round-trip through read_site_settings. Same
-// trust model as user-authored block-type JS: a bearer-token caller
-// takes responsibility for what they ship. The portal chat AI still
-// doesn't expose these fields, so conversation-driven assistants can't
-// smuggle scripts in.
+// Settings tools. update_site_settings accepts every field the portal
+// Settings form does — including scripts_head, scripts_body_end,
+// custom_css, cookie-consent scripts, default_og_image, twitter_handle,
+// organization (JSON-LD) and staging_url — with the same admin permission
+// the portal requires. A bearer-token caller takes responsibility for what
+// it ships, exactly as a site admin in the portal does. (The in-portal chat
+// assistant has its own, narrower settings tool; that is unrelated to MCP.)
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 function v(version) {
@@ -13,7 +13,7 @@ function v(version) {
 export const settingsTools = [
     {
         name: 'read_site_settings',
-        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
+        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, default_og_image, twitter_handle, organization (JSON-LD), language, robots_txt, image_sizes_default, cookie_consent, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, `urls` (including `urls.staging`, the site's staging_url) and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
         inputSchema: {
             version: versionParam,
         },
@@ -24,12 +24,14 @@ export const settingsTools = [
     },
     {
         name: 'update_site_settings',
-        description: 'Patch site settings, including responsive breakpoints for block layouts and visibility. Only the fields you pass change. ' +
+        description: 'Patch site settings, including responsive breakpoints for block layouts and visibility. Accepts everything the portal Settings form does. Requires admin permission on the site, as in the portal. Only the fields you pass change. ' +
             'Pass fields at the TOP LEVEL of the object — do NOT wrap in a "settings" key. ' +
             'Example: {"site_name": "Acme", "colors": {"primary": "#ff0"}} not {"settings": {...}}. ' +
             'Nested objects (colors, fonts, contact, social) are shallow-merged into the existing value. ' +
             'Unknown top-level keys return a 400 error listing the valid fields. ' +
-            'scripts_head / scripts_body_end / custom_css ARE writable here — useful for a global stylesheet across all pages. ' +
+            'scripts_head / scripts_body_end / custom_css and cookie_consent scripts ARE writable here — useful for a global stylesheet or analytics tag across all pages. ' +
+            'Social sharing and structured data: default_og_image, twitter_handle, organization ({name, logo, same_as[]}, replaced as a whole; null clears). ' +
+            'staging_url is stored on the Site (not per version), so it applies whichever `version` you pass. ' +
             'Pass `version` to scope the write to a branch (copy-on-write) instead of main — the right way to brand/recolor a site inside a redesign branch (colors, fonts, logo, custom_css) without touching the live settings. Omit it to write main.',
         inputSchema: {
             version: versionParam,
@@ -54,6 +56,14 @@ export const settingsTools = [
             scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
             scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
             custom_css: z.string().optional().describe('Global CSS in a <style> in <head>, after block CSS and before the page\'s own custom CSS and the template base stylesheet (reset + global). Base rules for :root tokens (spacing, radius, container widths), body font and line-height load after it, so override those with a more specific selector (for example html:root or body.page) rather than a bare :root/body rule. Preview uses the same order. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element. Prefer named styles (create_style) for anything a style can express. Syntax errors (unbalanced braces, unclosed comments or strings, expression()/javascript:) refuse the write; selectors on platform markup ([data-block], .block-*) come back as warnings because they can change between render versions — target s-<style> classes or block custom_class instead.'),
+            default_og_image: z.string().optional().describe('Site-wide fallback og:image URL for pages without their own social image. Empty string clears.'),
+            twitter_handle: z.string().optional().describe('Twitter/X handle for twitter:site, with or without the leading @ (stored without it). Empty string clears.'),
+            organization: z.object({
+                name: z.string().optional(),
+                logo: z.string().optional().describe('Absolute logo URL for the Organization JSON-LD.'),
+                same_as: z.array(z.string()).max(50).optional().describe('Profile URLs (LinkedIn, X, Facebook, …) emitted as sameAs.'),
+            }).strict().nullable().optional().describe('Organization schema.org JSON-LD emitted on every page. Replaces the stored value as a whole; null (or all-empty) clears it.'),
+            staging_url: z.string().nullable().optional().describe('URL of a staging environment for this site, reported as urls.staging. Stored on the Site, not per version. Trailing slashes are dropped; empty string or null clears.'),
             render_version: z.number().int().min(1).optional().describe('Platform render version. Platform output changes ship as new versions so existing sites never change look on their own. Upgrade only after previewing (get_preview_link render_version) and with the user\'s approval; the tr-upgrade-rendering skill compares every page. Lowering it returns to an earlier version.'),
             colors: z.record(z.string()).optional(),
             fonts: z.record(z.unknown()).optional(),

package/dist/tools/sites.js

@@ -1,4 +1,6 @@
-// Sites tools — discovery + Site-level identity edits.
+// Sites tools — discovery, Site-level identity edits and the site lifecycle
+// (archive / restore). Each maps to a v1 route with the same permission
+// check as the corresponding portal action.
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 export const siteTools = [
@@ -30,7 +32,7 @@ export const siteTools = [
     },
     {
         name: 'get_site',
-        description: 'Read this site\'s metadata (id, name, slug, domain, active version) + a urls object covering the production / fallback / preview_base URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',
+        description: 'Read this site\'s metadata (id, name, slug, domain, language, ai_scripts_enabled, lifecycle {status: active|archived}, active version) + a urls object covering the production / fallback / preview_base / staging URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',
         handler: withErrorBoundary(async (_args, { client, siteId }) => {
             const res = await client.get(siteId, '');
             return ok(res);
@@ -65,16 +67,36 @@ export const siteTools = [
     },
     {
         name: 'update_site',
-        description: 'Edit Site-level identity fields: name (display), slug (drives the {slug}.typeroll-fallback subdomain — kebab-case, 3-48 chars, unique across the org), domain (the customer\'s real hostname; pass "" to clear). For colors / fonts / contact info / tagline use update_site_settings instead.',
+        description: 'Edit Site-level fields: name (display), slug (drives the {slug}.typeroll-fallback subdomain — kebab-case, 3-48 chars, unique across the org), domain (the customer\'s real hostname; pass "" to clear), language, and ai_scripts_enabled (the portal\'s "Allow AI to write block scripts" toggle; requires admin permission, as in the portal). For colors / fonts / contact info / tagline / staging_url use update_site_settings instead.',
         inputSchema: {
             name: z.string().min(1).optional(),
             slug: z.string().optional().describe('Kebab-case identifier, 3-48 chars [a-z0-9-]. Empty string clears.'),
             domain: z.string().optional().describe('Bare hostname e.g. "example.com". Empty string clears.'),
             language: z.string().optional().describe('Default content language as a BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> and the default for alt-text generation. Empty string clears.'),
+            ai_scripts_enabled: z.boolean().optional().describe('"Allow AI to write block scripts": lets the in-portal chat assistant author block JavaScript for this site. API keys and MCP are not gated by it — they can always write block `script` and core/embed `js`. Requires admin permission.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.patch(siteId, '', args);
             return ok(res);
         }),
     },
+    {
+        name: 'archive_site',
+        description: 'Archive (retire) this site, the same action as Settings → Archive site in the portal. An archived site stays readable but refuses every write and publish until restored; the last published output keeps serving. Refused with 409 while a custom domain is still live or verified — move or remove the domain first. Requires an admin key of the organization that OWNS the site (a site-scoped key or the owner organization\'s org key); a key that reaches the site through a share is refused. Idempotent. Confirm with the user before calling.',
+        inputSchema: {
+            reason: z.string().max(500).optional().describe('Why the site is retired; shown in the portal.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'lifecycle', { action: 'archive', ...(args.reason ? { reason: args.reason } : {}) });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'restore_site',
+        description: 'Restore an archived site so it accepts writes and publishing again, the same action as Restore in the portal. Same permission as archive_site (owner-organization admin). Idempotent: restoring an active site succeeds without change.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.post(siteId, 'lifecycle', { action: 'restore' });
+            return ok(res);
+        }),
+    },
 ];

package/dist/tools/versions.js

@@ -12,7 +12,7 @@ export const versionTools = [
     },
     {
         name: 'create_branch',
-        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own stable deploy address for stakeholder review: after the branch's first trigger_deploy, read it from deploy_url in list_versions or read_version (the publishing setup decides the host: under a Hosting Group it is a v-… host under that group's site address base, otherwise the address the host reported; never construct it yourself). Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow.",
+        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own stable deploy address for stakeholder review: after the branch's first trigger_deploy, read it from deploy_url in list_versions or read_version (the publishing setup decides the host: under a Hosting Group it is a v-… host under that group's site address base, otherwise the address the host reported; never construct it yourself). Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow. Admin permission on the site is required, as in the portal.",
         inputSchema: {
             name: z.string().min(1),
             base: z.string().optional().describe('Source version id; defaults to main.'),
@@ -33,16 +33,34 @@ export const versionTools = [
     },
     {
         name: 'delete_branch',
-        description: 'Discard a branch (main cannot be deleted).',
+        description: 'Discard a branch with its overrides, tombstones and revision history (main cannot be deleted). Admin permission required.',
         inputSchema: { version_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.del(siteId, `versions/${encodeURIComponent(args.version_id)}`);
             return ok(res);
         }),
     },
+    {
+        name: 'diff_version',
+        description: 'Read-only: what a branch changes relative to main, per collection (pages, partials, redirects, contentTypes, pageTemplates, blockTypes): ids it adds, modifies and deletes, plus whether it overrides site settings and totalChanges. This is exactly what merge_branch would land on main and what reset_version would discard. Use it to summarise a branch for review before asking for merge approval.',
+        inputSchema: { version_id: z.string().describe('Branch id (main has nothing to diff).') },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `versions/${encodeURIComponent(args.version_id)}/diff`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'reset_version',
+        description: 'Discard EVERY change on a branch (all overrides and deletions), so it reads straight through to main again. The branch itself, its deploy address and its revision history are kept. Destructive for the branch\'s work: run diff_version first and get explicit user approval. Returns { cleared } — the diff that was discarded. Admin permission required. Main cannot be reset.',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `versions/${encodeURIComponent(args.version_id)}/reset`);
+            return ok(res);
+        }),
+    },
     {
         name: 'merge_branch',
-        description: 'Promote a branch\'s overrides + tombstones onto main. The branch is left in place so you can keep iterating; delete_branch removes it when you\'re done.',
+        description: 'Promote a branch\'s overrides + tombstones onto main (diff_version shows exactly what will land). The branch is left in place so you can keep iterating; delete_branch removes it when you\'re done. Admin permission required.',
         inputSchema: { version_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.post(siteId, `versions/${encodeURIComponent(args.version_id)}/merge`);

package/dist/tools/workflows.js

@@ -0,0 +1,61 @@
+// Workflow tools — the portal's server-side workflows (WordPress migration,
+// AI site planning, SEO / link / performance audits, content generation and
+// improvement, schema markup, URL parity, rebuild & deploy) and creating a
+// Site together with its first workflow.
+import { z } from 'zod';
+import { ok, versionParam, withErrorBoundary } from './helpers.js';
+const WORKFLOW_TYPES = [
+    'migration', 'site_planning', 'seo_audit', 'content_improvement', 'link_check',
+    'performance_audit', 'content_generation', 'schema_markup', 'url_parity', 'rebuild_deploy',
+];
+export const workflowTools = [
+    {
+        name: 'list_workflows',
+        description: 'List the workflow types this Site can run (label, description, steps, required_permission) and its most recent runs with status. Read only. Migration, site planning and URL parity pause for review; check get_workflow for paused_for_review.',
+        inputSchema: { limit: z.number().int().min(1).max(100).optional() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'workflows', args.limit ? { limit: args.limit } : undefined))),
+    },
+    {
+        name: 'start_workflow',
+        description: 'Start a server-side workflow on this Site; it runs in the background and returns workflow_id. Poll get_workflow. Config per type (same fields as the portal form): migration { wp_url, helper_api_key? } (needs verified organization import storage); site_planning { business_description }; content_generation { topic, tone?, audience? }; content_improvement { limit? }; url_parity { target_origin?, source_origin?, check_source?, statuses? }; rebuild_deploy { environment: staging | production }; seo_audit, link_check, performance_audit and schema_markup take none. Needs write permission; rebuild_deploy publishes and needs admin. Workflows that change content write to the given version (default main) — get the user\'s agreement first.',
+        inputSchema: {
+            type: z.enum(WORKFLOW_TYPES),
+            config: z.record(z.unknown()).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'workflows', { type: args.type, config: args.config }, args.version ? { version: args.version } : undefined))),
+    },
+    {
+        name: 'get_workflow',
+        description: 'Read one workflow run: status (pending | running | paused_for_review | completed | failed), current step, progress, log, review_message/review_data when paused, results and failure_reason. Credential config is masked.',
+        inputSchema: { workflow_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, `workflows/${encodeURIComponent(args.workflow_id)}`))),
+    },
+    {
+        name: 'approve_workflow',
+        description: 'Approve the review gate of a run that is paused_for_review; it resumes from the next step in the background. Show the user review_message and review_data from get_workflow and get their approval first — approval is theirs to give, not the tool\'s. Write permission; any other status returns 409.',
+        inputSchema: { workflow_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, `workflows/${encodeURIComponent(args.workflow_id)}/approve`))),
+    },
+    {
+        name: 'create_site_and_migrate',
+        noSite: true,
+        description: 'Create a new Site in the Organization and start a WordPress migration into it, like "Migrate from WordPress" on the portal\'s New site page. Requires an organization API key and verified organization import storage (409 import_storage_required otherwise — nothing is created). Returns site and workflow ids; poll get_workflow with that site_id. Run get_migration_readiness on the new Site if you need the preflight first.',
+        inputSchema: {
+            name: z.string().min(1).describe('Site display name; slugified into the Site id.'),
+            wp_url: z.string().url().describe('Public WordPress address, e.g. https://oldsite.example.'),
+            helper_api_key: z.string().optional().describe('Typeroll Helper plugin key from the WordPress admin, if installed. Stored for the run and never returned.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('sites/create-and-migrate', args))),
+    },
+    {
+        name: 'create_site_and_plan',
+        noSite: true,
+        description: 'Create a new Site in the Organization and start AI site planning from a business description, like "Plan a new site with AI" on the New site page. Requires an organization API key. The plan pauses for review: read it with get_workflow and approve_workflow only after the user agrees.',
+        inputSchema: {
+            name: z.string().min(1),
+            business_description: z.string().min(1).describe('What the business does, for whom, and what sets it apart.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('sites/create-and-plan', args))),
+    },
+];

package/dist/tools/working-copy.js

@@ -9,6 +9,8 @@
 //                                              Save button)
 //   discard_working_copy                   →  throw the draft away
 //   list/read/restore_page_revision        →  saved-state history (undo)
+//   preview_page_revision                  →  render a saved state
+//   list/read/restore_partial_revision     →  the same for partials
 //
 // The portal editor shows any agent-written draft as "Unsaved changes", so
 // the human can also Save or Discard it from the UI.
@@ -118,4 +120,64 @@ export const workingCopyTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'preview_page_revision',
+        description: 'Render one saved page revision as the whole preview document (header, body, footer, site CSS and block scripts), exactly what the editor\'s History panel shows before a restore. Read-only. The revision\'s fields are laid over the current page; the current header, footer and settings give context. Returns { page_id, revision_id, slug, title, rendered_html, internal_links }. Pass annotate:true to tag block roots with data-block-id + data-block-type. Compare with get_page_preview before restore_page_revision.',
+        inputSchema: {
+            page_id: z.string(),
+            revision_id: z.string(),
+            annotate: z.boolean().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { ...(v(args.version) ?? {}) };
+            if (args.annotate)
+                query.annotate = 'true';
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}/preview`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_partial_revisions',
+        description: "Saved-state history of a partial (header, footer or global block) on this version, newest first. Every save snapshots the partial as it was BEFORE the save. Returns { revisions: [{ id, created_at, created_by, note, name, content_mode, date_updated }], total }. Use read_partial_revision for the full document and restore_partial_revision to undo.",
+        inputSchema: {
+            partial_id: z.string(),
+            limit: z.number().int().min(1).max(100).optional().describe('Newest N entries (default 50).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { ...(v(args.version) ?? {}) };
+            if (args.limit)
+                query.limit = String(args.limit);
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}/revisions`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_partial_revision',
+        description: 'Read one partial revision with the full saved document (name, kind, html_content or blocks, status) — compare it with read_partial before restoring.',
+        inputSchema: {
+            partial_id: z.string(),
+            revision_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}/revisions/${encodeURIComponent(args.revision_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'restore_partial_revision',
+        description: "Restore a partial revision's name and content (HTML or block tree) into the partial's DRAFT, replacing the current draft. Pass save:true to save it at once; the save snapshots the current partial first, so the restore is itself undoable. Status and kind are kept. A revision from the other content mode is refused (409) — switch mode first. Returns { restored_revision, saved, has_unsaved_changes, staged_fields, sanitization_warnings }.",
+        inputSchema: {
+            partial_id: z.string(),
+            revision_id: z.string(),
+            save: z.boolean().optional().describe('Save immediately (default false: leave it as an unsaved draft to preview).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `partials/${encodeURIComponent(args.partial_id)}/revisions/${encodeURIComponent(args.revision_id)}/restore`, { save: args.save === true }, v(args.version));
+            return ok(res);
+        }),
+    },
 ];

package/dist/version.js

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

package/package.json

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

package/skills/tr-forms.md

@@ -112,8 +112,19 @@ update_form form_id=contact patch={ actions: [
 ```
 
 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.
+`secret`; send the masked value back to keep a stored secret.
+`get_form_capabilities` lists every action type the site offers, including
+types from installed apps, with the config fields each one takes.
+
+Email actions send through the site's email provider. Check it with
+`get_email_settings`; if `email` is null, connect one with `set_email_settings`
+(for example `type: "postmark"`, `from`, `config: { server_token }`) and confirm
+with `send_test_email`. Without a provider, submissions are stored but nobody is
+notified. These tools need admin permission, like Settings → Email & notifications.
+
+`list_form_submissions` reads what visitors sent, `read_form_submission` reads
+one entry (admins also see webhook delivery status) and `delete_form_submission`
+removes one.
 
 ## Verify
 
@@ -121,8 +132,11 @@ reads what visitors sent.
 2. Preview the page and confirm the authoring reference has expanded to a form
    with `data-tr-form-el`, a signed token, and the platform runtime.
 3. Submit a test entry and confirm it appears in Forms → Submissions.
-4. If a webhook is configured, confirm its delivery status and the receiving
-   system's idempotency key before deploying.
+4. If a webhook is configured, confirm its delivery status
+   (`read_form_submission`) and the receiving system's idempotency key before
+   deploying.
+5. If an email action is configured, confirm `get_email_settings` shows a
+   provider and the test message arrived.
 
 ## Common patterns
 

package/skills/tr-migrate-wp.md

@@ -19,9 +19,13 @@ Its shared evidence record is required for visual acceptance.
 > `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
 
 
-The platform's in-portal migration workflow is the "managed" path for
-customers who want one-click. This skill is the "power-user" path: you
-do it locally, mix data sources freely, and the user reviews each step in their terminal.
+The platform's migration workflow is the "managed" path for customers who
+want one-click. It runs on the server and is also available to you:
+`start_workflow type="migration" config={ wp_url }` on an existing site, or
+`create_site_and_migrate` (organization key) for a new one; poll `get_workflow`
+and approve its review gate only with the user's consent. This skill is the
+"power-user" path: you do it locally, mix data sources freely, and the user
+reviews each step in their terminal.
 
 ## Preconditions
 

package/skills/tr-new-site.md

@@ -32,7 +32,9 @@ wrapper. Load only the relevant guide section and recipe. Discover site apps wit
 read_app_documentation when needed; do not bundle private app guides locally.
 
 No Site yet? Use hosted MCP with an Organization key and create_site, or create it
-in the portal. Read back its ID before editing. Use one explicit Site/Version for
+in the portal. To start from an AI site plan instead of a blank Site, use
+create_site_and_plan, poll get_workflow and approve its structure review only
+with the user's consent. Read back its ID before editing. Use one explicit Site/Version for
 related operations. Larger changes to an existing site should use a branch.
 
 Before importing content or a media library, require get_import_readiness to pass.

package/skills/tr-redesign-branch.md

@@ -245,6 +245,15 @@ compiled output or merge. Wait for an explicit "looks good, ship it."
 
 ### 7. Merge + deploy
 
+Before asking for sign-off, summarise exactly what will land:
+
+```
+diff_version version_id="<branch>"        # added / modified / deleted per collection
+```
+
+Then, once approved (creating and merging branches need site admin
+permission):
+
 ```
 merge_branch version_id="<branch>"        # branch's diffs land on main
 trigger_deploy
@@ -274,7 +283,12 @@ disk cost is tiny.)
   the DB, reflects edits on reload); deploy only for the compiled static
   output or merge (steps 6–7).
 - **Auto-merge.** Don't `merge_branch` without explicit user sign-off.
-  Once merged, the only undo is another branch + reverse edits.
+  Once merged, the only undo is another branch + reverse edits (or
+  restoring individual saved states with `restore_page_revision` /
+  `restore_partial_revision` on main).
+- **Starting over.** To abandon a direction but keep the branch and its
+  address, `reset_version version_id="<branch>"` discards every change on it
+  (check `diff_version` and ask first); `delete_branch` removes it entirely.
 - **Header rewrites that drop the brand block.** Even when the
   redesign is dramatic, preserve the brand mark + the nav skeleton
   unless the user said to redo them.

package/skills/tr-seo.md

@@ -97,11 +97,25 @@ batch_update_pages updates=[
 OG image dimensions: 1200×630px ideal. The platform doesn't resize —
 use a correctly-sized source image.
 
+For pages without their own image, set a site-wide fallback and the X/Twitter
+handle (admin permission, as in the portal Settings form):
+
+```
+update_site_settings default_og_image="<cdn_url>" twitter_handle="@acmestudio"
+```
+
 ### 5. Add structured data (JSON-LD)
 
 Typeroll auto-generates Article and Page schema, but you can override or
 extend with custom JSON-LD per page. Example: LocalBusiness on the homepage.
 
+The site-wide Organization schema comes from settings — set it once instead of
+repeating it on every page (`null` clears it):
+
+```
+update_site_settings organization={"name":"Acme Studio","logo":"<cdn_url>","same_as":["https://www.linkedin.com/company/acme"]}
+```
+
 ```
 update_page page_id="home" patch={
   "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\"}}"