@typeroll/mcp-server 0.45.76 → 0.45.79

package/workspace-templates/scripts/typeroll/compare_text.py

@@ -0,0 +1,59 @@
+"""Compare saved source HTML (or one WP REST record) to a captured target.
+Template titles are included exactly once by explicit source title/target selector.
+This reports differences, never rewrites content or approves a migration.
+"""
+import argparse
+import difflib
+from html.parser import HTMLParser
+import json
+from pathlib import Path
+import re
+
+
+class Text(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.words, self.skip = [], 0
+    def handle_starttag(self, tag, attrs):
+        if tag in ('script', 'style'):
+            self.skip += 1
+        elif tag in ('p', 'div', 'li', 'br', 'h1', 'h2', 'h3', 'h4'):
+            self.words.append(' ')
+    def handle_endtag(self, tag):
+        if tag in ('script', 'style'):
+            self.skip = max(0, self.skip - 1)
+        elif tag in ('p', 'div', 'li', 'h1', 'h2', 'h3', 'h4'):
+            self.words.append(' ')
+    def handle_data(self, value):
+        if not self.skip:
+            self.words.append(value)
+    # HTMLParser excludes comments. Do not strip tags with a regexp.
+
+
+def tokens(value):
+    parser = Text()
+    parser.feed(value)
+    return re.findall(r'\w+|[^\w\s]', ''.join(parser.words))
+
+
+def main():
+    args = argparse.ArgumentParser(description=__doc__)
+    args.add_argument('source', help='HTML fragment or one saved WP REST record (.json)')
+    args.add_argument('target', help='JSON from capture_text.cjs')
+    args.add_argument('--source-title', default='', help='For an HTML source whose title is template-owned')
+    opts = args.parse_args()
+    source = Path(opts.source).read_text()
+    if opts.source.endswith('.json'):
+        record = json.loads(source)
+        source = record['title']['rendered'] + ' ' + record['content']['rendered']
+    else:
+        source = opts.source_title + ' ' + source
+    target = json.loads(Path(opts.target).read_text())
+    before, after = tokens(source), re.findall(r'\w+|[^\w\s]', target['text'])
+    changes = [line for line in difflib.ndiff(before, after) if line.startswith(('+ ', '- '))]
+    print(json.dumps({'source_tokens': len(before), 'target_tokens': len(after), 'changes': changes}, ensure_ascii=False, indent=2))
+    return int(bool(changes))
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/workspace-templates/scripts/typeroll/contact_sheet.py

@@ -0,0 +1,20 @@
+"""Tile screenshots into contact sheets for fast visual review of many pages.
+usage: python3 contact_sheet.py <out-prefix> <cols> <tile-width> <png> [<png> ...]
+Each tile shows the top of a screenshot (height = 3.2 x width) labelled with its file name."""
+import sys, os
+from PIL import Image, ImageDraw
+out, cols, tw, files = sys.argv[1], int(sys.argv[2]), int(sys.argv[3]), sys.argv[4:]
+th = int(tw * 3.2)
+per = cols * 2
+for n, start in enumerate(range(0, len(files), per)):
+    chunk = files[start:start + per]
+    sheet = Image.new("RGB", (cols * tw, 2 * (th + 20)), "white")
+    d = ImageDraw.Draw(sheet)
+    for i, f in enumerate(chunk):
+        im = Image.open(f).convert("RGB")
+        im = im.resize((tw, int(im.height * tw / im.width))).crop((0, 0, tw, th))
+        x, y = (i % cols) * tw, (i // cols) * (th + 20)
+        sheet.paste(im, (x, y + 20))
+        d.text((x + 3, y + 3), os.path.basename(f)[:40], fill="red")
+    sheet.save(f"{out}-{n}.png")
+    print(f"{out}-{n}.png")

package/workspace-templates/scripts/typeroll/layout_trace.cjs

@@ -0,0 +1,33 @@
+// Explain vertical spacing: computed margin/padding/gap of every ancestor of a selector and of the next
+// section down to its first heading. Works on a signed preview link (reads the inner frame) or a public URL.
+// usage: node layout_trace.js <url> [width=390] [selector=h1]
+const qa = require('./browser.cjs');
+const { chromium } = qa;
+(async () => {
+  const [,, url, width = '390', sel = 'h1'] = process.argv;
+  const b = await chromium.launch();
+  const p = await b.newPage({viewport: {width: +width, height: 900}});
+  await qa.open(p, url);
+  const f = p.mainFrame();
+  try { console.log(await f.evaluate((sel) => {
+    const out = [];
+    const show = (lab, el) => {
+      if (!el) return;
+      const c = getComputedStyle(el), r = el.getBoundingClientRect();
+      out.push(`${lab} <${el.tagName.toLowerCase()} ${el.getAttribute('data-block') || String(el.className).slice(0, 40)}> top=${Math.round(r.top)} h=${Math.round(r.height)} margin=${c.marginTop}/${c.marginBottom} padding=${c.paddingTop}/${c.paddingBottom} gap=${c.rowGap} radius=${c.borderRadius}`);
+    };
+    const target = document.querySelector(sel);
+    if (!target) throw Error('Selector not found');
+    const sec = target.closest('[data-block="section"]') || target;
+    const chain = []; for (let a = target; a && a !== document.body; a = a.parentElement) chain.push(a);
+    chain.reverse().forEach((x, i) => show('ancestor' + i, x));
+    for (let s = sec.nextElementSibling; s; s = s.nextElementSibling) {
+      show('next', s);
+      const h = s.querySelector('h1,h2,h3');
+      if (h) { const ch = []; for (let q = h; q && q !== s; q = q.parentElement) ch.push(q); ch.reverse().forEach((x, i) => show('inside' + i, x)); break; }
+    }
+    show('header', document.querySelector('header'));
+    return out.join('\n');
+  }, sel));
+  } finally { await b.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/shoot_hosted.cjs

@@ -0,0 +1,26 @@
+const qa = require('./browser.cjs');
+const [origin, out, paths, ...args] = process.argv.slice(2);
+(async () => {
+  const browser = await qa.chromium.launch();
+  const report = [];
+  try {
+    for (const route of paths.split(',')) {
+      const url = new URL(route, origin);
+      if (url.origin !== new URL(origin).origin) throw Error('Paths must stay on the selected origin');
+      for (const width of qa.widths(args)) {
+        const page = await browser.newPage({ viewport: { width, height: 900 } });
+        const failed = [];
+        page.on('requestfailed', r => failed.push({ host: new URL(r.url()).hostname, kind: 'network' }));
+        page.on('response', r => { if (r.status() >= 400) failed.push({ host: new URL(r.url()).hostname, status: r.status() }); });
+        await qa.open(page, url.href); await qa.settle(page);
+        const result = { path: route, width, ...await qa.inspect(page), failed };
+        const name = require('node:crypto').createHash('sha256').update(route).digest('hex').slice(0, 12);
+        await qa.screenshot(page, `${out}/${name}-${width}.png`);
+        report.push(result);
+        await page.close();
+      }
+    }
+    console.log(JSON.stringify(report, null, 2));
+    if (report.some(r => r.overflow || r.incompleteImages.length || r.h1 !== 1 || r.failed.length || !r.scrollCoverageComplete)) process.exitCode = 1;
+  } finally { await browser.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/shootframe.cjs

@@ -0,0 +1,16 @@
+const qa = require('./browser.cjs');
+const [out, url, ...args] = process.argv.slice(2);
+(async () => {
+  const browser = await qa.chromium.launch();
+  try {
+    for (const width of qa.widths(args)) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      const hosts = new Set();
+      page.on('request', r => { try { hosts.add(new URL(r.url()).hostname); } catch {} });
+      await qa.open(page, url); await qa.settle(page);
+      await qa.screenshot(page, `${out}-${width}.png`);
+      console.log(JSON.stringify({ width, ...await qa.inspect(page), hosts: [...hosts] }));
+      await page.close();
+    }
+  } finally { await browser.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/sweep_blocks.example.py

@@ -0,0 +1,23 @@
+"""Pattern: change one kind of block on every Page, Page template and partial, then save.
+Example: set last_row "start" on every core/grid that centers its last row. Dry run lists; --apply writes.
+Copy and edit MATCH/PATCH for other sweeps. Templates save immediately; Pages and partials must be committed. Refuses existing unsaved work."""
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import trlib
+SITE = trlib.site_id()
+MATCH = lambda b: b.get("type") == "core/grid" and (b.get("data") or {}).get("last_row") == "center"
+PATCH = {"last_row": "start"}
+apply = "--apply" in sys.argv
+for tgt in trlib.containers():
+    tree = trlib.call("get_page_blocks", {"site_id": SITE, "target": tgt})
+    hits = [b for b in trlib.walk(tree.get("blocks", tree) if isinstance(tree, dict) else tree) if MATCH(b)]
+    if not hits:
+        continue
+    print(tgt["kind"], tgt["id"], len(hits))
+    if apply:
+        if tgt['kind'] != 'template' and trlib.call('read_working_copy', {'target': tgt}).get('working_copy'):
+            raise RuntimeError('Unsaved work exists; review it before this sweep')
+        for b in hits:
+            trlib.call("update_block", {"site_id": SITE, "target": tgt, "block_id": b["id"], "data": PATCH})
+        if tgt["kind"] in ("page", "partial"):
+            trlib.call("commit_working_copy", {"site_id": SITE, "target": tgt})

package/workspace-templates/scripts/typeroll/trlib.py

@@ -0,0 +1,212 @@
+"""Small, version-bound MCP helper. Credentials are injected, never persisted.
+No automatic retries for mutations. Run from the workspace root.
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None  # Never forward Authorization or signed PUTs to another URL.
+
+
+def workspace():
+    for directory in (Path.cwd(), *Path.cwd().parents):
+        file = directory / 'typeroll.json'
+        if file.is_file():
+            value = json.loads(file.read_text())
+            if not all(value.get(k) for k in ('portal', 'organization_id', 'site_id', 'version')):
+                raise ValueError('Complete portal, organization_id, site_id and version in typeroll.json first')
+            origin = urllib.parse.urlsplit(value['portal'])
+            if origin.username or origin.password or origin.query or origin.fragment or origin.path not in ('', '/'):
+                raise ValueError('portal must be a plain origin')
+            if origin.scheme != 'https' and not (origin.scheme == 'http' and origin.hostname in ('localhost', '127.0.0.1', '::1')):
+                raise ValueError('portal requires HTTPS (HTTP is allowed only on loopback)')
+            return value
+    raise ValueError('Run from a workspace containing typeroll.json')
+
+
+class Client:
+    def __init__(self, config=None):
+        self.config = config or workspace()
+        self.url = self.config['portal'].rstrip('/') + '/api/mcp?tools=full'
+        self.session = None
+        self.sequence = 0
+        self.tools = None
+        self.verified = False
+        self.opener = urllib.request.build_opener(NoRedirect)
+
+    def rpc(self, method, params=None, notify=False):
+        self.sequence += 1
+        body = {'jsonrpc': '2.0', 'method': method}
+        if params is not None:
+            body['params'] = params
+        if not notify:
+            body['id'] = self.sequence
+        key = os.environ.get('TYPEROLL_API_KEY')
+        if not key:
+            raise ValueError('Inject TYPEROLL_API_KEY privately before running')
+        headers = {'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json',
+                   'Accept': 'application/json, text/event-stream'}
+        if self.session:
+            headers['Mcp-Session-Id'] = self.session
+        request = urllib.request.Request(self.url, data=json.dumps(body).encode(), headers=headers)
+        try:
+            with self.opener.open(request, timeout=180) as response:
+                self.session = response.headers.get('Mcp-Session-Id') or self.session
+                raw = response.read().decode()
+        except urllib.error.HTTPError as error:
+            raise RuntimeError(f'MCP HTTP {error.code}; no mutation was retried') from None
+        if notify:
+            return None
+        result = decode_rpc(raw, self.sequence)
+        if 'error' in result:
+            raise RuntimeError(f"MCP RPC error {result['error'].get('code')}")
+        return result['result']
+
+    def initialize(self):
+        self.rpc('initialize', {'protocolVersion': '2025-03-26', 'capabilities': {},
+                              'clientInfo': {'name': 'typeroll-workspace', 'version': '1'}})
+        self.rpc('notifications/initialized', notify=True)
+        self.tools = {}
+        cursor = None
+        seen = set()
+        while True:
+            result = self.rpc('tools/list', {'cursor': cursor} if cursor else {})
+            self.tools.update({t['name']: t for t in result['tools']})
+            cursor = result.get('nextCursor')
+            if not cursor:
+                break
+            if cursor in seen:
+                raise RuntimeError('tools/list repeated its cursor')
+            seen.add(cursor)
+
+    def call(self, tool, args=None):
+        if self.tools is None:
+            self.initialize()
+        if tool not in self.tools:
+            raise ValueError(f'Tool unavailable: {tool}')
+        if not self.verified:
+            info = self.invoke('get_site', {})
+            if info.get('organization_id') != self.config['organization_id'] or info.get('id') != self.config['site_id']:
+                raise ValueError('Connected Organization/Site does not match typeroll.json; nothing was written')
+            self.verified = True
+        return self.invoke(tool, args or {})
+
+    def invoke(self, tool, args):
+        props = self.tools[tool]['inputSchema'].get('properties', {})
+        data = dict(args)
+        for key, wanted in [('site_id', self.config['site_id']), ('version', self.config['version'])]:
+            if key in data and data[key] != wanted:
+                raise ValueError(f'{key} differs from typeroll.json; change the binding explicitly')
+            if key in props:
+                data[key] = wanted
+        if 'version' not in props and self.config['version'] != 'main' and tool != 'get_site':
+            raise ValueError(f'{tool} has no version parameter; refusing an implicit main-version operation')
+        result = self.rpc('tools/call', {'name': tool, 'arguments': data})
+        if result.get('isError'):
+            raise RuntimeError(f'{tool} failed; inspect through your authenticated MCP client (no retry)')
+        if 'structuredContent' in result:
+            return result['structuredContent']
+        text = ''.join(c.get('text', '') for c in result.get('content', []) if c.get('type') == 'text')
+        return json.loads(text)
+
+
+def decode_rpc(raw, request_id):
+    if raw.lstrip().startswith('{'):
+        value = json.loads(raw)
+        if value.get('id') != request_id:
+            raise ValueError('MCP response did not contain the matching request ID')
+        return value
+    # Streamable HTTP may include notifications, multiline data, and keepalives.
+    for event in raw.replace('\r\n', '\n').split('\n\n'):
+        data = '\n'.join(line[5:].lstrip() for line in event.splitlines() if line.startswith('data:'))
+        if data:
+            value = json.loads(data)
+            if value.get('id') == request_id:
+                return value
+    raise ValueError('MCP response did not contain the matching request ID')
+
+
+_client = None
+
+
+def call(tool, args=None):
+    global _client
+    if _client is None:
+        _client = Client()
+    return _client.call(tool, args)
+
+
+def site_id():
+    return workspace()['site_id']
+
+
+def walk(blocks):
+    for block in blocks or []:
+        yield block
+        yield from walk(block.get('children'))
+        for slot in block.get('slots') or []:
+            yield from walk(slot)
+
+
+def all_pages():
+    cursor, seen = None, set()
+    while True:
+        args = {'limit': 200, **({'cursor': cursor} if cursor else {})}
+        result = call('list_pages', args)
+        yield from result['pages']
+        cursor = result.get('next_cursor')
+        if not cursor:
+            return
+        if cursor in seen:
+            raise RuntimeError('list_pages repeated its cursor')
+        seen.add(cursor)
+
+
+def all_migration_urls():
+    offset = 0
+    while True:
+        result = call('list_migration_urls', {'limit': 1000, 'offset': offset})
+        rows = result['urls']
+        yield from rows
+        offset += len(rows)
+        if not rows or offset >= result.get('total_matching', float('inf')):
+            return
+
+
+def containers():
+    for page in all_pages():
+        yield {'kind': 'page', 'id': page['id']}
+    for kind, tool, key in [('template', 'list_page_templates', 'templates'), ('partial', 'list_partials', 'partials')]:
+        result = call(tool)
+        rows = result if isinstance(result, list) else result.get(key, result.get('page_templates'))
+        if not isinstance(rows, list):
+            raise ValueError(f'Unexpected response from {tool}')
+        for row in rows:
+            yield {'kind': kind, 'id': row['id']}
+
+
+def upload(file, content_type, alt=''):
+    content = Path(file).read_bytes()
+    sha = hashlib.sha256(content).hexdigest()
+    mint = call('create_upload_url', {'filename': Path(file).name, 'content_type': content_type,
+                                    'size': len(content), 'alt_text': alt})
+    if urllib.parse.urlsplit(mint['upload_url']).scheme != 'https':
+        raise ValueError('Signed upload must use HTTPS')
+    request = urllib.request.Request(mint['upload_url'], data=content, method='PUT', headers={'Content-Type': content_type})
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=120) as response:
+            response.read()
+    except Exception:
+        raise RuntimeError('Signed upload failed; URL withheld; no automatic retry') from None
+    result = call('finalize_media', {'media_id': mint['media_id'], 'expected_sha256': sha})
+    evidence = result.get('result', result)
+    if evidence.get('sha256') != sha:
+        raise ValueError('Finalize did not confirm the source SHA-256; do not reference this asset')
+    return {'media_id': mint['media_id'], 'cdn_url': mint['cdn_url'], 'sha256': sha}

package/workspace-templates/workflows/design.md

@@ -0,0 +1,30 @@
+# Layout defaults and owner decisions
+
+Use current native composition starters and block schemas. These defaults are
+starting points, not permission to overwrite an approved design.
+
+- Keep incomplete grid rows left-aligned (`last_row: start`). Never enlarge one
+  peer card just to fill the gap. Center only on an explicit owner request.
+- Prefer `core/navigation_menu` with `core/navigation_links` desktop/mobile slots
+  for a header drawer (below 1024 px). Read tr-header-footer; test 1023/1024 px.
+- Separate dense footer about text from the link grid. Give it a readable width
+  and a larger gap; inspect 390/1024/1280/1536 px. Equal columns need equal density.
+- Sections own gutters. Do not erase side padding with `padding: 3rem 0` when
+  only vertical spacing is intended. Wrap column-slot contents in a flow
+  container with article rhythm when they need vertical block spacing.
+- Give cards one clear destination. Use whole_card_link without action_label
+  or download actions. Check excerpt, image, whitespace and keyboard activation.
+- Do not fade body text with opacity. Verify actual text/background contrast,
+  current links on light/dark navigation, and all states.
+- Preserve image subjects across widths. Choose contain/original sizing when
+  cropping or upscaling is not intended. Hero crop, text placement, plates,
+  corner treatment and category-page composition are project decisions in
+  brief/brand.md, not a universal design.
+- After migration, check heading hierarchy, unchanged preserved text, HTML
+  comments, links with ../, and the home SEO title/suffix. Shared headings and
+  titles must not be duplicated in body content.
+
+Record deliberate departures in decisions.md with scope and owner approval.
+Use a QA round per review: method, pages/viewports, expected differences, results,
+unverified items and remaining defects. Record platform findings in
+qa/typeroll-platform-feedback.md; do not bury them in workaround CSS.

package/workspace-templates/workflows/interview.md

@@ -0,0 +1,72 @@
+# Guided website interview
+
+## When to start or resume
+
+Use this routine when the owner asks for guidance or a material decision is missing
+from the brief. Read the existing briefs, decisions and brief/interview.md first.
+Do not restart an interview or ask questions already answered. If the brief is
+complete, summarize it and continue with the relevant routine. This is an agent
+conversation, not a portal wizard or a new API workflow.
+
+## How to conduct it
+
+- Use the owner's language. Ask one short question at a time; offer concrete
+  choices and allow a free answer or "not sure". Explain technical choices plainly.
+- Reuse explicit instructions already given. Distinguish confirmed answers,
+  proposals and unknowns. Never treat silence as approval.
+- If an answer is unknown, suggest an option with its consequences. Research and
+  reversible prototypes may continue; do not perform dependent CMS writes until
+  the necessary decision is confirmed.
+- Save each answer and its source/date in brief/interview.md, and the approved
+  decision in the relevant brief. Keep the next question and unresolved items so
+  another session can resume. Do not store credentials, personal contact lists
+  or raw private transcripts here. No MCP connection is needed to plan locally.
+- Reopen only affected questions when the owner changes direction. Record the
+  change in decisions.md; do not silently replace confirmed rules.
+
+## Interview stages
+
+1. **Goal and scope** — New website or migration? Purpose, audience, language,
+   desired visitor actions, source URL and what is in/out of scope.
+   Save to brief/site.md and brief/migration.md when relevant.
+2. **Target and access** — Existing or new Typeroll Site? Discover accessible
+   Organizations/Sites through MCP and confirm the exact target and Version before
+   writes. Explain any missing storage or access when it becomes relevant; never
+   ask for a secret in chat. Save non-secret IDs to typeroll.json only when known.
+3. **Text decision (migration)** — Preserve existing wording or renew it?
+   Preserve covers headings, body copy, CTA labels, captions and other authored
+   text. Record SEO titles/descriptions, alt text, legal text, translation and any
+   page-specific exceptions explicitly. Renewal needs an agreed editorial brief;
+   it is not permission to invent facts. Save text_intent in brief/migration.md.
+4. **Design and image decision (migration)** — Independently preserve or renew
+   layout, typography, colors and imagery? Offer all four text/design combinations.
+   For renewal, ask which existing assets must remain and which may be replaced
+   or generated. Clarify cropping, logos, credits and image rights. Optimization
+   alone must not change the motif. Save design_intent and asset exceptions in
+   brief/migration.md, and the direction in brief/brand.md. A fresh design never
+   grants permission to rewrite preserved text.
+5. **Content and behavior** — Page types, shared templates, navigation, forms,
+   downloads, integrations and who will edit them. Identify missing capabilities
+   before scaling up. Save to brief/content-model.md. New websites skip migration
+   preservation choices and establish their brand/content brief here.
+6. **SEO and continuity** — Markets, search intent, useful topics and existing
+   valuable URLs. Record evidence separately from hypotheses in brief/seo.md.
+   Confirm metadata policy; text preservation cannot be bypassed as "SEO cleanup".
+   Every old public URL must remain or redirect meaningfully regardless of the
+   two migration choices. Retiring a URL requires a separate agreed exception.
+7. **Owner rules and review** — Non-negotiable copy/design constraints, editing
+   roles and who approves prototypes, publication, DNS or messages. Save confirmed
+   rules to brief/rules.md. Keep technical access separate from user authorization.
+8. **Recap and next action** — Show the scope, both migration decisions (if any),
+   image exceptions, acceptance references, open questions and the next concrete
+   step. Ask the owner to correct/confirm the brief before dependent writes.
+   Reuse existing approval if it already covers that exact step. Brief approval
+   alone does not authorize publication, domain cutover or mail.
+
+## Completion
+
+Mark the interview ready for the agreed next step only when its blocking questions
+are answered; list deferred decisions explicitly. Continue with workflows/new-site.md
+or workflows/migration.md and load only the relevant MCP recipe. Confirm one
+prototype per distinct layout before bulk work. Review preserved dimensions
+against the source and renewed dimensions against the approved brief separately.

package/workspace-templates/workflows/migration.md

@@ -0,0 +1,84 @@
+# Migration kickoff
+
+If guidance is needed, start or resume workflows/interview.md. Otherwise fill in
+this prompt from the confirmed brief. The two preservation choices are independent.
+
+```text
+Migrate [source URL] to Typeroll, Organization [ID/name], Site [ID/name], Version [ID].
+Text: [preserve existing wording / renew against an agreed editorial brief].
+Design and images: [preserve / renew against an agreed design brief].
+Read AGENTS.md and use workflows/interview.md for missing decisions.
+Read tr-migration-evidence, then tr-migrate-wp (or the appropriate source recipe).
+Confirm the target and import readiness before writes. Inventory URLs, content,
+media, templates and integrations; record both choices and exceptions in brief/migration.md.
+Build and verify one prototype per distinct layout before bulk reconstruction.
+Use standard blocks first, editable custom types next, isolated HTML only for
+justified exceptions. Rebuild imported HTML with block tools; a mode switch does not convert it.
+Keep preserved text unchanged even when the design is new. Record which images
+may change. Preserve every old public URL or redirect to a relevant destination.
+Protect existing CMS edits. Review text and design/images against their own
+acceptance references, plus mobile/desktop behavior, downloads, forms and URL coverage.
+Report unverified items separately. Do not publish, switch DNS or send messages
+without explicit approval.
+```
+
+The managed importer stages cleaned HTML, media and shared references in Review.
+The external agent can then reconstruct those Pages; no manual editor conversion
+is required. An agent can also build block Pages directly from source material.
+Neither path includes an automatic HTML-to-blocks converter. Read and preserve the
+full source before switching modes, then save/read back and preview the rebuilt
+Page on the selected Version. Never publish an empty intermediate block Page.
+
+Track import, block reconstruction, separate text/design review, candidate
+publication and domain cutover as separate milestones. Import completion is not
+launch approval. All four text/design combinations use the same block hierarchy
+and URL continuity contract. Planning choices are not migration API fields.
+
+## Repeatable reconstruction and acceptance
+
+Read workflows/design.md and scripts/README.md. First check whether public
+WordPress REST + HTML covers the source; use tr-migrate-wp's access decision
+table before asking for a helper plugin. Inventory both Pages and posts plus
+internal links and known old slugs. A sitemap alone is not complete.
+
+Discard HTML comments before extracting text, resolve relative links against
+the source, and keep an explicit old URL map. Do not redirect deleted content
+to the home page merely to get a 200. Preserve/renew text and design separately.
+Use capture_text.cjs + compare_text.py for preserved text with explicit selectors.
+
+Before every authorized test deployment run check_unsaved.py (Pages and partials).
+Deploy saved content to the agreed protected test host, then run check_url_parity.py,
+check_assets.py and shoot_hosted.cjs. Check whole-card targets with
+card-stacking-check.cjs and inspect actual desktop/mobile screenshots. Record a
+QA round and platform findings. Review on the owner's phone when possible.
+Domain preparation/cutover and production indexing follow their own explicit
+approval scope and the platform's current guided flow; do not bypass readiness.
+Do not request a second approval for a step the owner has already authorized.
+
+
+## Native controls and publication checks
+
+On Core 0.2.103 / MCP 0.45.79 or later, discover the actual block schemas first.
+Use column `content_gap_px`, responsive section `padding_y`, heading-role
+`space_before`/`space_after`, hero focal/fit/text-position fields and image
+`never_upscale` instead of one-off CSS. Responsive block keys start at `mobile`,
+not `base`. For vertical-only spacing, do not reset horizontal padding with CSS
+shorthand. Optional `click_to_load` videos need an explicit poster if desired;
+choose a first-party poster to avoid early provider requests.
+
+`import_sitemap` can include public WordPress REST (`include_wordpress: true`)
+and a bounded crawl (`crawl_pages: 10`). Record truncation and access warnings.
+A `matched_draft` URL is accounted for in the CMS but not ready for launch.
+Resolve `unpublished_targets`, redirect loops/chains and actual deployed parity.
+
+A deploy with working copies returns `unsaved_content`; review the targets.
+Save explicitly or obtain approval to publish saved content only using
+`allow_unsaved: true`. Never silently save somebody else's work.
+
+Keep the bound Organization/Site/Version explicit. A site API key cannot switch
+to another Organization: use an authorized OAuth connection or a separate key.
+Read the schema for target envelopes and pagination; do not guess aliases.
+Page/partial block writes update working copies; check `saved` and use
+`commit_working_copy` with `target: {kind: "page"|"partial", id: "..."}`.
+Page templates save immediately and do not have working copies. REST read envelopes and
+MCP tool text are different layers; `call.py` returns the decoded tool result.

package/workspace-templates/workflows/new-site.md

@@ -0,0 +1,17 @@
+# New website kickoff
+
+Use this prompt only when the brief is already clear. Otherwise start or resume
+workflows/interview.md; the owner does not need to fill in every document alone.
+
+```text
+Create [website] for [audience and purpose] in Typeroll Organization [ID/name].
+Read AGENTS.md, confirm the Site and Version, and use workflows/interview.md for
+missing decisions. Record confirmed goals, brand, content model, owner rules and
+SEO strategy in brief/. Read tr-new-site and relevant tool schemas on demand.
+Build representative desktop/mobile layouts with editable blocks and shared templates.
+Share previews, record accepted decisions and keep unresolved items explicit.
+Do not publish, change DNS or send messages without explicit approval.
+```
+
+The CMS owns current content and settings. The repository owns the brief, rules,
+decisions and evidence. Load recipes when needed, not the whole manual.