@typeroll/mcp-server 0.45.76 → 0.45.79

package/dist/init.js

@@ -48,7 +48,7 @@ export async function runInitCli(args) {
     try {
         const result = await runInit({ dir, update, recipes, client });
         console.log(JSON.stringify(result, null, 2));
-        console.log('Next: fill brief/, connect hosted MCP at https://app.typeroll.com/api/mcp?tools=compact, create/select your Site, record its IDs/Version in typeroll.json, then run typeroll doctor. Local MCP uses an injected TYPEROLL_API_KEY; no key is stored by init. See README.md.');
+        console.log('Next: read AGENTS.md. For guidance, start/resume workflows/interview.md; otherwise use workflows/new-site.md or workflows/migration.md. Record decisions in brief/, connect hosted MCP at https://app.typeroll.com/api/mcp?tools=compact, create/select your Site, record its IDs/Version in typeroll.json, then run typeroll doctor. Local MCP uses an injected TYPEROLL_API_KEY; no key is stored by init. See README.md.');
         return 0;
     }
     catch {

package/dist/tools/deploy.js

@@ -15,6 +15,7 @@ export const deployTools = [
         description: "Enqueue a deploy (static-page build → hosting) of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running. NOT for previewing iterative design/content edits — that's what get_preview_link is for (it renders live from the DB with no build). Reserve trigger_deploy for publishing, a stakeholder link to the compiled site, or pre-merge validation. Deploys build SAVED content only — unsaved drafts (working copies) are excluded, so commit_working_copy (or save:true on your writes) before deploying, or your changes won't ship. Customer publishing freezes a consistent saved source, then resumes source/Git/build-dispatch checkpoints without recapturing later edits. GitHub or Cloudflare performs rendering and media work. With dry_run:true, customer publishing validates frozen source without a Git push or external build; it does not prove an Astro build succeeds. Other self-hosted adapters may build locally without upload. Check the reported phase.",
         inputSchema: {
             environment: z.enum(['production', 'staging']).optional(),
+            allow_unsaved: z.boolean().optional().describe('Explicitly publish saved content while leaving the reported unsaved Pages/partials untouched. Only after owner confirmation.'),
             dry_run: z.boolean().optional().describe('Validate without publishing. Customer publishing checks frozen source only; other adapters may build locally without upload.'),
             version: versionParam,
         },
@@ -40,7 +41,7 @@ export const deployTools = [
     },
     {
         name: 'get_deploy_status',
-        description: "Status of a single deploy job. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
+        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
         inputSchema: { job_id: z.string(), include_provider: z.boolean().optional().describe('Also read the exact Git commit and Cloudflare build stages for a customer Git publication. Does not return build secrets.') },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `deploys/${encodeURIComponent(args.job_id)}`);

package/dist/tools/media.js

@@ -206,7 +206,7 @@ export const mediaTools = [
     },
     {
         name: 'finalize_media',
-        description: 'Post-upload finalize for a single image: (1) applies immutable Cache-Control (public, max-age=31536000) to the R2 original via in-place CopyObject so the CDN caches it for a year, and (2) generates AVIF/WebP responsive variants if not already present. Call this immediately after a successful upload (the presigned PUT does NOT set cache headers — without finalize, Cloudflare defaults to ~4h and every visit re-fetches the original). Idempotent: safe to call twice. Skips variant work when variants already exist on the doc. INTEGRITY: the result always includes the stored original\'s sha256 + size_bytes — compare against your source file to catch transit corruption before referencing the asset. Better: pass expected_sha256 (hash the file yourself first, e.g. `shasum -a 256 file`) and the server rejects a mismatch with a 422 so corrupted bytes never get blessed with immutable cache headers. Truncated SVGs are rejected outright.',
+        description: 'Post-upload finalize for a single image: (1) applies immutable Cache-Control (public, max-age=31536000) to the R2 original via in-place CopyObject so the CDN caches it for a year, and (2) generates AVIF/WebP responsive variants if not already present. Call this immediately after a successful upload (the presigned PUT does NOT set cache headers — without finalize, Cloudflare defaults to ~4h and every visit re-fetches the original). Idempotent: safe to call twice. Skips variant work when variants already exist on the doc. INTEGRITY: the response is { ok, result: { sha256, size_bytes, ... } }; read result.sha256 and result.size_bytes for the stored original — compare against your source file to catch transit corruption before referencing the asset. Better: pass expected_sha256 (hash the file yourself first, e.g. `shasum -a 256 file`) and the server rejects a mismatch with a 422 so corrupted bytes never get blessed with immutable cache headers. Truncated SVGs are rejected outright.',
         inputSchema: {
             media_id: z.string(),
             expected_sha256: z.string().regex(/^[0-9a-fA-F]{64}$/).optional()

package/dist/tools/migration.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
-const STATUS = z.enum(['migrated', 'redirected', 'excluded', 'unhandled']);
+const STATUS = z.enum(['migrated', 'redirected', 'excluded', 'unhandled', 'matched_draft']);
 const PLAIN_TEXT_REPAIR_FIELD = z.enum(['title', 'seo_title', 'seo_description', 'excerpt']);
 export const migrationTools = [
     {
@@ -8,6 +8,8 @@ export const migrationTools = [
         description: 'Import an explicit sitemap URL into the migration URL inventory. Sitemap indexes are followed recursively; URLs outside source_origin are rejected and reported.',
         inputSchema: {
             url: z.string().url().describe('Absolute URL of a sitemap or sitemap index.'),
+            include_wordpress: z.boolean().optional().describe('Also enumerate public WordPress REST pages/posts/types. No helper installation required; incomplete discovery is reported.'),
+            crawl_pages: z.number().int().min(0).max(50).optional().describe('With include_wordpress, crawl up to this many source pages for same-origin legacy links. Default 0; bounded discovery is not an authoritative old-slug export.'),
             source_origin: z.string().url().optional().describe('Expected legacy-site origin. Defaults to the sitemap origin.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -69,7 +71,7 @@ export const migrationTools = [
     },
     {
         name: 'list_migration_urls',
-        description: "The legacy site's URL inventory with LIVE coverage status. Every entry is classified on read against the site's current pages + redirects: `migrated` (a Page answers at that path), `redirected` (a redirect rule covers it), `excluded` (signed off as an intentional 404), `unhandled` (nothing covers it — the work list). Returns a summary over the whole inventory plus a page of entries, sorted worst-first then by GSC clicks. Use `status: \"unhandled\"` to get exactly what's left to do before cutover. Coverage is computed, never stored, so it's current the moment you create a redirect.",
+        description: "The legacy site's URL inventory with LIVE coverage status. Every entry is classified on read against the site's current pages + redirects: `migrated` (a Page answers at that path), `redirected` (a redirect rule covers it), `excluded` (signed off as an intentional 404), `matched_draft` (a saved but unpublished Page owns the path; not launch-ready), `unhandled` (nothing covers it — the work list). Returns a summary over the whole inventory plus a page of entries, sorted worst-first then by GSC clicks. Use `status: \"unhandled\"` to get exactly what's left to do before cutover. Coverage is computed, never stored, so it's current the moment you create a redirect.",
         inputSchema: {
             status: STATUS.optional().describe('Only return entries with this coverage status.'),
             limit: z.number().int().positive().max(1000).optional().describe('Default 200.'),

package/dist/tools/pages.js

@@ -223,7 +223,7 @@ export const pageTools = [
     },
     {
         name: 'batch_update_pages',
-        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch, save?, answer_sources? }; failures are reported per-row, the rest still apply. BUFFER MODEL: content patches land in each page\'s unsaved draft; per-entry save:true (or the top-level save flag) commits — typical for a user-approved sweep. content_mode is rejected per-row; switch each page with set_page_mode.',
+        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch, save?, answer_sources? }; failures are reported per-row, the rest still apply. BUFFER MODEL: content patches land in each page\'s unsaved draft; per-entry save:true (or the top-level save flag) commits — typical for a user-approved sweep. Returns results with saved (whether this patch reached saved storage), staged (draft field names), and applied_immediately (status/schedule field names). A status-only patch is saved immediately and does not commit earlier drafts. content_mode is rejected per-row; switch each page with set_page_mode.',
         inputSchema: {
             updates: z
                 .array(z.object({

package/dist/tools/preview.js

@@ -17,7 +17,7 @@ export const previewTools = [
     },
     {
         name: 'get_preview_link',
-        description: 'Mint a signed URL the user (or your own browser tool) can open to SEE the rendered preview. Renders LIVE from the database with NO build — this is the PREFERRED way to preview design/content changes as you iterate; reach for this, not trigger_deploy, when previewing. BUFFER MODEL: your edits are unsaved drafts, so for the iteration loop mint the link with include_working_copy:true (drafts visible); a plain link shows SAVED content only — right for stakeholders reviewing what will deploy. Mint ONCE and REUSE that single URL across edits — internal links keep the token so it navigates the whole branch, and it stays valid until the TTL lapses (24h default and max). Target a page (page_id), or a raw slug; omit all for the home page. Forms on the page can be clicked through end to end — validation, steps, success message or the named redirect target — without creating submissions or running actions ("Preview – nothing is sent"). (For a permanent public link, complete Publishing setup and wait for a verified deployment on the organization or site domain.)',
+        description: 'Returns url (normal wrapper) and frame_url (signed sandboxed frame for rendering-only QA; use the wrapper for Extension host interactions). Mint a signed URL the user (or your own browser tool) can open to SEE the rendered preview. Renders LIVE from the database with NO build — this is the PREFERRED way to preview design/content changes as you iterate; reach for this, not trigger_deploy, when previewing. BUFFER MODEL: your edits are unsaved drafts, so for the iteration loop mint the link with include_working_copy:true (drafts visible); a plain link shows SAVED content only — right for stakeholders reviewing what will deploy. Mint ONCE and REUSE that single URL across edits — internal links keep the token so it navigates the whole branch, and it stays valid until the TTL lapses (24h default and max). Target a page (page_id), or a raw slug; omit all for the home page. Forms on the page can be clicked through end to end — validation, steps, success message or the named redirect target — without creating submissions or running actions ("Preview – nothing is sent"). (For a permanent public link, complete Publishing setup and wait for a verified deployment on the organization or site domain.)',
         inputSchema: {
             page_id: z.string().optional(),
             slug: z.string().optional(),

package/dist/tools/working-copy.js

@@ -29,7 +29,7 @@ function wcPath(t) {
 export const workingCopyTools = [
     {
         name: 'read_working_copy',
-        description: 'Read a doc\'s unsaved draft (working copy) as a raw field diff — { working_copy: null } means everything is saved. read_page/get_page_blocks already return the draft VIEW; use this when you need to know exactly WHICH fields are unsaved, e.g. before discarding (the draft may hold the user\'s in-progress editor work, not just yours).',
+        description: 'Templates save immediately and do not use this tool. Use target: {kind: page|partial, id: ...}, not page_id. Read a doc\'s unsaved draft (working copy) as a raw field diff — { working_copy: null } means everything is saved. read_page/get_page_blocks already return the draft VIEW; use this when you need to know exactly WHICH fields are unsaved, e.g. before discarding (the draft may hold the user\'s in-progress editor work, not just yours).',
         inputSchema: {
             target: wcTargetSchema,
             version: versionParam,

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

package/dist/workspace.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import { VERSION } from './version.js';
+import { BUNDLED_WORKSPACE_TEMPLATES } from './bundled-content.js';
 import { ApiError, TyperollClient } from './client.js';
 export const workspaceSchema = z.object({
     schema_version: z.literal(1),
@@ -17,14 +18,24 @@ export const workspaceSchema = z.object({
 export const defaultWorkspace = { schema_version: 1, portal: 'https://app.typeroll.com', organization_id: null, site_id: null, version: 'main', tool_mode: 'compact' };
 const lockSchema = z.object({ schema_version: z.literal(1), generator_version: z.string(), files: z.record(z.string(), z.string().regex(/^[a-f0-9]{64}$/)) }).strict();
 const hash = (value) => createHash('sha256').update(value).digest('hex');
-export const ignores = ['.typeroll/', '.env', '.env.*', '!.env.example', '.mcp.json', '.cursor/mcp.json', '.vscode/mcp.json', 'qa/reports/', 'sources/private/'];
+export const ignores = ['.typeroll/', '.env', '.env.*', '!.env.example', '.mcp.json', '.cursor/mcp.json', '.vscode/mcp.json', 'qa/reports/', 'sources/private/', '**/__pycache__/', 'scripts/typeroll/node_modules/'];
 export const agentInstructions = `# Working on this website
 
-Read typeroll.json, brief/ and decisions.md. Confirm the portal, Organization,
+Read typeroll.json, brief/site.md, brief/rules.md and decisions.md first. Read
+other brief/ files and workflows/ only when relevant. Confirm the portal, Organization,
 Site and working Version before writes. This workspace is not the generated
 publication repository. The CMS owns current content and configuration; local
 sources are proposals unless the user explicitly adopts them.
 
+## Guided start
+
+When the owner needs guidance or a material decision is missing, start or resume
+workflows/interview.md. Read brief/interview.md and existing answers first; ask
+one short question at a time and save progress. Do not repeat confirmed questions
+or treat silence as approval. For a complete brief, proceed directly to
+workflows/new-site.md or workflows/migration.md. All kickoff prompts live here
+in the workspace; public docs explain the flow and link to these source files.
+
 ## Discover only what the task needs
 
 With compact MCP, search_tools then describe_tool; call_read_tool,
@@ -60,12 +71,24 @@ Public documentation: https://typeroll.com/docs/llms.txt
 ## Migrations
 
 Read tr-migration-evidence, then the source-specific recipe (tr-migrate-wp,
-tr-import-url, tr-migrate-astro or tr-migrate-multisite). Record preserve or renew
-intent in brief/migration.md; ask if unclear. Standard blocks first, reviewed
+tr-import-url, tr-migrate-astro or tr-migrate-multisite). Record text_intent and design_intent separately as preserve or renew
+in brief/migration.md; design includes images. Ask if either is unclear. Standard blocks first, reviewed
 custom types next, documented HTML exceptions last. Preserve or meaningfully
 redirect every old public URL. Import completion is not block reconstruction
-or launch acceptance. Compare preserve work to the source, renew work to the
-approved design/content brief. Discover tools and recipes on demand.
+or launch acceptance. Compare text and design/images separately: preserved dimensions to the source,
+renewed dimensions to their approved brief. New design never permits rewriting preserved text. Start with workflows/migration.md for the kickoff
+prompt. The agent rebuilds imported HTML using ordinary block tools; the owner
+does not need to manually convert each Page. No automatic converter is available.
+Discover tools and recipes on demand. Read scripts/README.md for version-bound
+pre-deploy and hosted QA tools. Follow workflows/design.md for layout defaults.
+
+## Project rules and search strategy
+
+Record the owner's preferences and durable constraints in brief/rules.md; put
+approved search intent, topic coverage and URL/indexing strategy in brief/seo.md.
+These are project decisions, not CMS settings or permission to publish. If a
+request conflicts with an agreed rule, ask and record the resulting decision.
+Use workflows/README.md to find the relevant routine, not load every recipe.
 
 ## Everyday requests
 
@@ -82,16 +105,17 @@ Store credentials in the client's private settings or injected environment.
 Run the workspace doctor after setup and after changing the binding.
 `;
 export const workspaceTemplates = {
+    ...BUNDLED_WORKSPACE_TEMPLATES,
     'AGENTS.md': agentInstructions,
-    'README.md': `# Website workspace\n\nKeep project intent here; edit the website through Typeroll CMS.\n\n1. Fill in brief/site.md and brief/brand.md.\n2. Connect hosted MCP at https://app.typeroll.com/api/mcp?tools=compact.\n3. Use an Organization key to create a site, or select an existing one.\n4. Record its IDs and working version in typeroll.json. No secrets belong there.\n5. Run npx @typeroll/mcp-server doctor . (inject TYPEROLL_API_KEY privately).\n\nStart guide: https://typeroll.com/docs/getting-started/agent-workspace/\n\nUpdate the generated scaffold with npx @typeroll/mcp-server init . --update.\nEdited files are preserved and reported for manual reconciliation. Optional local\nrecipes: init . --recipes. They are reference Markdown, not automatically loaded.\n`,
+    'README.md': `# Website workspace\n\nKeep project intent here; edit the website through Typeroll CMS.\n\n1. Read AGENTS.md. For guidance, ask your agent to start or resume workflows/interview.md. Otherwise use workflows/new-site.md or workflows/migration.md. Save confirmed goals, rules and SEO strategy in brief/; record text and design/image choices separately for migrations.\n2. Connect hosted MCP at https://app.typeroll.com/api/mcp?tools=compact.\n3. Use an Organization key to create a site, or select an existing one.\n4. Record its IDs and working version in typeroll.json. No secrets belong there.\n5. Run npx @typeroll/mcp-server doctor . (inject TYPEROLL_API_KEY privately).\n\nStart guide: https://typeroll.com/docs/getting-started/agent-workspace/\n\nUpdate the generated scaffold with npx @typeroll/mcp-server init . --update.\nEdited files are preserved and reported for manual reconciliation. Optional local\nrecipes: init . --recipes. They are reference Markdown, not automatically loaded.\n`,
     'brief/site.md': '# Site brief\n\n## Purpose and audience\n\n## Languages and scope\n\n## Primary user journeys\n\n## Content authority and sources\n\n## Editorial constraints and forbidden internal markers\n',
     'brief/brand.md': '# Brand\n\n## Voice and tone\n\n## Visual direction and references\n\n## Typography, colors and image policy\n\n## Desktop and mobile navigation\n\nRecord intent here; current design tokens belong in CMS settings.\n',
     'brief/content-model.md': '# Content model\n\n## Page types and routes\n\n## Fields and references\n\n## Shared templates and partials\n\n## Taxonomy and navigation\n\nUse the current CMS schema. This document describes decisions, not a second schema store.\n',
-    'brief/migration.md': '# Migration brief (when applicable)\n\n## Intent: preserve or renew\n\n## Source URLs, date and agreed scope\n\n## Design and content acceptance reference\n\n## Retained facts and approved content changes\n\n## Standard blocks, custom types and HTML exceptions\n\n## Old URL to preserved path or relevant redirect\n\n## Prototype and verification evidence\n\nKeep private extracts in sources/private/ and screenshots in qa/reports/.\n',
+    'brief/rules.md': "# Owner preferences and project rules\n\n## Confirmed rules\n\nRecord each rule, its scope, who approved it and the date. Separate confirmed rules from proposals.\n\n## Writing and factual accuracy\n\nVoice, terminology, prohibited claims, source requirements and legal copy that must not be rewritten.\n\n## Design and editing\n\nBrand constraints, accessibility, editable content, standard/custom blocks and documented HTML exceptions.\n\n## Operations and approval\n\nWho may approve content, publication, DNS changes and messages? Credentials stay outside this repository.\n\n## Exceptions and superseded rules\n\nLink decisions.md; do not silently override a confirmed rule. Project notes do not grant permissions beyond the user's authorization or account access.\n",
+    'brief/seo.md': "# SEO strategy\n\n## Business goals, audience, markets and languages\n\n## Search intent and topic coverage\n\nRecord research sources and dates. Distinguish evidence from assumptions; do not invent traffic or ranking forecasts.\n\n## Page roles and URL plan\n\nContent types, useful landing pages, taxonomy, internal links and routes to preserve or redirect. Avoid near-duplicate pages created only for keyword variants.\n\n## Indexing and canonical policy\n\nWhich pages should be indexable, public noindex, or private? Record deliberate canonical overrides and sitemap policy; actual values live in the CMS.\n\n## Editorial standards and structured data\n\nUnique useful copy, supported claims, descriptive titles and links, accessible image text, schema matching visible content. No fixed title length or word count is a hard SEO rule.\n\n## Measurement and review\n\nBaseline, analytics/consent decisions, measures of success and review dates. Never store credentials or private analytics exports here.\n",
+    'workflows/README.md': "# Project routines\n\nRead only the relevant routine and discover current tool schemas through MCP.\nProject files record intent; the CMS owns current content and configuration.\n\n| Task | Project context | On-demand recipe |\n| --- | --- | --- |\n| Guided start | workflows/interview.md, brief/interview.md | Ask one question at a time; resume confirmed answers |\n| New website | workflows/new-site.md, brief/site.md, brief/brand.md, brief/content-model.md | tr-new-site, tr-starter-design |\n| Migration | workflows/migration.md, brief/migration.md | tr-migration-evidence, then tr-migrate-wp or the matching source recipe |\n| Everyday editing | brief/rules.md and the relevant Page | tr-edit-site |\n| SEO | brief/seo.md and current site settings | tr-seo |\n| New reusable block | brief/brand.md and recorded editing needs | tr-custom-blocks |\n| Verification and publication | qa/checklist.md, decisions.md | Current preview/deploy tools and publishing readiness |\n\nAdd project-specific routines here with inputs, steps, acceptance evidence and approval boundaries. Do not copy the complete Typeroll manual or private app guides. Discover enabled app guidance with read_app_documentation. Load a recipe when needed so instructions stay current and context stays small.\n",
     'decisions.md': '# Decisions\n\nRecord date, decision, reason, approved scope and alternatives when useful.\n',
     'sources/README.md': '# Sources\n\nStore research references and copy proposals. Record source URLs and dates.\nPrivate extracts belong in ignored private/ or an approved external store.\nDo not treat local drafts as current CMS content or commit media libraries.\n',
-    'scripts/README.md': '# Project automation\n\nKeep repeatable imports and QA scripts here. Use the authenticated REST API\nfor scripted work; keep credentials outside files and inject them at runtime.\nMCP remains the interactive interface. Typeroll currently has no general site CRUD CLI.\n',
-    'qa/checklist.md': '# Verification\n\n- Confirm Site, Version and deployed/source identity.\n- Read back saved content and inspect desktop/mobile previews.\n- Exercise menus, keyboard focus, links and enabled app states.\n- Verify routes, metadata, media and publishing readiness before launch.\n- Check that structured data (FAQ, recipe, event) matches what each page shows.\n- Record tested pages, viewports, results and unresolved issues.\n- Store screenshots and private runtime reports in ignored reports/.\n- Publishing validation does not prove visual or editorial completeness.\n',
 };
 export async function readWorkspace(dir) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.76",
+  "version": "0.45.79",
   "description": "Typeroll CMS MCP server – connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,8 @@
     "dist",
     "AGENTS.md",
     "README.md",
-    "skills"
+    "skills",
+    "workspace-templates"
   ],
   "scripts": {
     "gen": "node scripts/embed-content.mjs",

package/skills/tr-header-footer.md

@@ -5,11 +5,10 @@ description: Build accessible native header and footer partials with the site lo
 
 # Native header and footer compositions
 
-Use block-mode partials for new work. Core 0.1.8 / capability contract 0.43.0
-ships `template/site_logo`, `core/navigation`, layout primitives, and a
-revision-safe partial mode operation. HTML partials remain supported for
-legacy markup, but generic navigation and responsive layout no longer require
-tenant HTML, CSS, or JavaScript.
+Use block-mode partials for new work. Prefer `get_composition_starter`
+for the current native header tree: `template/site_logo`, `core/navigation_menu`
+and `core/navigation_links`. Use the menu's dialog/drawer rather than an inline
+mobile expansion that moves the logo. Existing `core/navigation` remains supported.
 
 ## Preconditions
 
@@ -31,51 +30,106 @@ read it back. Localize both accessible labels and every link label.
 [
   {
     "type": "core/section",
-    "data": { "width": "wide", "padding_y": "sm" },
-    "children": [{
-      "type": "core/container",
-      "data": {
-        "direction": { "mobile": "column", "tablet": "row" },
-        "align_main": "space-between",
-        "align_cross": "center",
-        "gap": "md",
-        "width": "wide",
-        "padding_y": "none",
-        "padding_x": "none"
-      },
-      "children": [
-        { "type": "template/site_logo", "data": { "height": "md", "link_to_home": true } },
-        {
-          "type": "core/navigation",
-          "data": {
-            "aria_label": "Main navigation",
-            "menu_label": "Menu",
-            "links": [
-              { "label": "Home", "href": "/" },
-              { "label": "About", "href": "/about/" },
-              { "label": "Contact", "href": "/contact/" }
+    "data": {
+      "width": "wide",
+      "padding_y": "compact"
+    },
+    "children": [
+      {
+        "type": "core/container",
+        "data": {
+          "direction": "row",
+          "wrap": "nowrap",
+          "align_main": "space-between",
+          "align_cross": "center",
+          "width": "full"
+        },
+        "children": [
+          {
+            "type": "template/site_logo",
+            "data": {
+              "height": "md",
+              "link_to_home": true
+            }
+          },
+          {
+            "type": "core/navigation_menu",
+            "data": {
+              "aria_label": "Main navigation",
+              "menu_label": "Open menu",
+              "close_label": "Close menu",
+              "collapse_below": "1024"
+            },
+            "slots": [
+              [
+                {
+                  "type": "core/navigation_links",
+                  "data": {
+                    "direction": "row",
+                    "links": [
+                      {
+                        "label": "Home",
+                        "href": "/"
+                      },
+                      {
+                        "label": "About",
+                        "href": "/about/"
+                      },
+                      {
+                        "label": "Contact",
+                        "href": "/contact/"
+                      }
+                    ]
+                  }
+                }
+              ],
+              [
+                {
+                  "type": "core/navigation_links",
+                  "data": {
+                    "direction": "column",
+                    "links": [
+                      {
+                        "label": "Home",
+                        "href": "/"
+                      },
+                      {
+                        "label": "About",
+                        "href": "/about/"
+                      },
+                      {
+                        "label": "Contact",
+                        "href": "/contact/"
+                      }
+                    ]
+                  }
+                }
+              ]
             ]
           }
-        }
-      ]
-    }]
+        ]
+      }
+    ]
   }
 ]
 ```
 
-`core/navigation` emits a real `nav` and list in initial HTML, marks the
-matching page with `aria-current="page"`, and progressively enhances to a
-button-controlled mobile menu. Verify Tab and Shift-Tab order, Enter/Space,
-Escape returning focus to the disclosure, visible focus, long translated
-labels, and no horizontal overflow. Without JavaScript the links remain
-visible and usable.
+The first slot is desktop; the second is the optional mobile composition.
+The default is drawer below 1024 px and inline from 1024 px. For responsive
+link fields use matching `responsive_breakpoints` (tablet 768, laptop 1024,
+desktop 1280, wide 1536); do not independently hide all links at the menu boundary.
+Verify 1023/1024 px, Tab/Shift-Tab, Enter/Space, Escape returning focus,
+visible focus, long labels, no-JavaScript links and no horizontal overflow.
 
 ## Footer tree and consent
 
-Use the same tree for `footer`, normally with `padding_y: "lg"`, a small site
-logo, localized footer navigation, and optional contact/prose blocks. The
-footer navigation gets its own accessible label; it is not the main
-navigation landmark.
+Use an accessible footer navigation landmark and `core/navigation_links`, not
+a second header drawer. If the footer has running about text, give it a separate,
+wider column beside a nested link grid. An equal four-column grid is rarely a
+good fit for one dense paragraph and three short link lists. Start with
+`core/columns` ratio `1-2`, put flow containers inside the slots, and tune the
+gap and readable text width to the actual content. Stack on mobile. Inspect at
+390, 1024, 1280 and 1536 px; do not copy one site's pixel values blindly.
 
 Cookie consent is a site feature, not a footer widget. Configure it separately:
 

package/skills/tr-import-url.md

@@ -10,10 +10,10 @@ another MCP client) working through MCP and the public API. The portal's built-i
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
 **Before import or reconstruction:** read `tr-migration-evidence` with
-`read_skill`. Choose preserve (platform change) or renew (new design/content),
-record the brief and verify one prototype per active template before bulk writes.
+`read_skill`. Choose preserve or renew independently for text and design/images,
+record text_intent and design_intent in the brief and verify one prototype per active template before bulk writes.
 Use standard blocks first, reviewed custom types next, rare documented HTML last.
-Both paths must preserve or meaningfully redirect every old public URL. That
+All four combinations must preserve or meaningfully redirect every old public URL. That
 shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
@@ -81,7 +81,7 @@ list_pages limit=5
 ```
 
 Read existing target data to avoid overwriting work. Compare prototypes to the
-source in preserve mode, or to the agreed new design in renew mode. Validate
+source when design_intent is preserve, or to the agreed new design when it is renew. Review text separately. Validate
 standard/custom blocks using `tr-migration-evidence` before mass writes.
 
 ### 3. Fetch and clean each source page
@@ -123,8 +123,8 @@ omit it. Inventory PDFs, download hrefs, srcsets and backgrounds as well.
 
 **d. Adapt to the target's design.**
 Use standard blocks first, then reusable custom types with editable fields.
-Preserve source appearance/text in preserve mode; use the approved new design
-and content plan in renew mode. Raw HTML is the documented last resort.
+Review appearance and text independently according to design_intent and text_intent;
+compare each preserved dimension to the source and each renewed dimension to its approved brief. Raw HTML is the documented last resort.
 
 ### 4. Create pages as drafts
 

package/skills/tr-migrate-astro.md

@@ -10,10 +10,10 @@ another MCP client) working through MCP and the public API. The portal's built-i
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
 **Before import or reconstruction:** read `tr-migration-evidence` with
-`read_skill`. Choose preserve (platform change) or renew (new design/content),
-record the brief and verify one prototype per active template before bulk writes.
+`read_skill`. Choose preserve or renew independently for text and design/images,
+record text_intent and design_intent in the brief and verify one prototype per active template before bulk writes.
 Use standard blocks first, reviewed custom types next, rare documented HTML last.
-Both paths must preserve or meaningfully redirect every old public URL. That
+All four combinations must preserve or meaningfully redirect every old public URL. That
 shared contract defines acceptance; this recipe only adds source-specific steps.
 
 

package/skills/tr-migrate-multisite.md

@@ -10,10 +10,10 @@ another MCP client) working through MCP and the public API. The portal's built-i
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
 **Before import or reconstruction:** read `tr-migration-evidence` with
-`read_skill`. Choose preserve (platform change) or renew (new design/content),
-record the brief and verify one prototype per active template before bulk writes.
+`read_skill`. Choose preserve or renew independently for text and design/images,
+record text_intent and design_intent in the brief and verify one prototype per active template before bulk writes.
 Use standard blocks first, reviewed custom types next, rare documented HTML last.
-Both paths must preserve or meaningfully redirect every old public URL. That
+All four combinations must preserve or meaningfully redirect every old public URL. That
 shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
@@ -69,7 +69,7 @@ required before import; GitHub/build/domain readiness is checked separately for
 publication. Do not infer that every Site shares the same blockers.
 
 Ask explicitly:
-- Which intent applies per Site: preserve or renew? Which source or approved
+- Which text_intent and design_intent apply per Site, each preserve or renew? Which source or approved
   prototype is the **design reference**? Build that one properly first.
 - Are the sites **translations of each other** (same page structure) or
   independent? This decides whether hreflang clusters are mechanical or

package/skills/tr-migrate-wp.md

@@ -10,10 +10,10 @@ another MCP client) working through MCP and the public API. The portal's built-i
 AI assistant has no migration tools: it does not import, convert or verify sites.
 
 **Before import or reconstruction:** read `tr-migration-evidence` with
-`read_skill`. Choose preserve (platform change) or renew (new design/content),
-record the brief and verify one prototype per active template before bulk writes.
+`read_skill`. Choose preserve or renew independently for text and design/images,
+record text_intent and design_intent in the brief and verify one prototype per active template before bulk writes.
 Use standard blocks first, reviewed custom types next, rare documented HTML last.
-Both paths must preserve or meaningfully redirect every old public URL. That
+All four combinations must preserve or meaningfully redirect every old public URL. That
 shared contract defines acceptance; this recipe only adds source-specific steps.
 
 
@@ -80,7 +80,7 @@ Then the ordinary preconditions:
   REST API disabled" if not — common for hardened hosts).
 - The target exists. Establish the source design baseline first, then prove
   representative target templates using `tr-migration-evidence`. Preserve
-  appearance in preserve mode; use the approved design/content brief in renew mode.
+  appearance when design_intent is preserve; use the approved design brief when it is renew. Review text against its separate choice.
 - If the target already has content, you must NOT clobber it — always
   `list_pages` first and only write to slugs that don't already exist.
   Pass the slug explicitly: `create_page` then refuses an address that is
@@ -148,12 +148,28 @@ place. Do not preserve them as classed raw HTML in text blocks.
 
 For each source URL:
 
-a. Fetch from WP. Prefer the helper plugin's authenticated endpoint
-   (`/wp-json/typeroll/v1/...`) if available — it bypasses
-   `show_in_rest=false` and returns ACF + builder fields. Otherwise
-   fall back to `/wp-json/wp/v2/<post-type>?slug=<slug>`.
-
-b. Clean the HTML. Strip Elementor / Gutenberg / Breakdance class
+a. Choose access based on missing evidence, not a mandatory plugin install:
+
+   | Source requirement | Access path |
+   | --- | --- |
+   | Public Pages, posts, media and rendered builder content exposed in REST | Public paginated `/wp-json/wp/v2/pages`, `/posts`, `/media` and rendered HTML can suffice |
+   | SEO exposed in `yoast_head_json`, visible menus/backgrounds | Public REST + rendered HTML/CSS; verify actual coverage |
+   | Private/draft content, REST-hidden types, ACF/custom fields, exact menus | Authenticated helper/export when available and authorized |
+   | REST blocked by security policy | Owner-approved helper/export; do not bypass access controls |
+   | Authoritative old slugs or plugin redirects | Owner export/helper **if supported**; a public crawl only approximates them |
+
+   Do not ask the owner to install the helper when public sources cover the scope.
+   Inventory both Pages and posts (including sitemap-excluded public records),
+   crawl internal links and inspect redirects, menus and CSS background images.
+   Do not claim the helper exports a field without reading its current contract.
+   The helper is distributed through Typeroll's documented package; do not claim
+   WordPress.org availability. Listing it there is separate publication work.
+
+b. Clean the HTML. Parse HTML and discard comments before extracting text or
+   constructing blocks (comments may contain old phone-plugin metadata). Do not
+   use regex tag removal as a text parser. Resolve relative `../` links against
+   the source URL; preserve query strings and fragments. Report missing targets
+   instead of pointing everything at the home page. Strip Elementor / Gutenberg / Breakdance class
    soup. Drop empty `<div>` and `<span>` wrappers. Keep semantic tags,
    tables, iframes from known hosts (YouTube / Vimeo / Calendly).
    Remove every `<script>`: plugin and theme JavaScript is never copied.
@@ -165,10 +181,10 @@ 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. 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.
+The managed importer stores cleaned HTML. Typeroll does not convert HTML into blocks, and `set_page_mode` never rewrites HTML. You, the external agent, rebuild the imported content with ordinary block tools. The owner does not need to convert every Page manually. There is no editor conversion preview; it was removed in Core 0.2.58. Preserve the complete source before switching modes and never publish the empty intermediate Page.
 
 d. Rebuild into editable blocks according to the selected intent. Preserve exact
-   wording in preserve mode; track approved changes in renew mode. Map headings,
+   wording when text_intent is preserve; track approved changes when it is renew, independently of design. Map headings,
    prose, images, buttons and layout to standard fields first, then create
    reviewed custom types where needed. Use raw HTML only for a documented,
    exceptional fragment. Preserve anchors and map every old URL in either mode.