@typeroll/mcp-server 0.45.80 → 0.45.82

package/dist/compact-tools.js

@@ -17,7 +17,7 @@ export function compactTools(catalog) {
         }),
         local('describe_tool', 'Read one tool’s complete description, effect and JSON input schema before calling it.', { name: z.string().max(100) }, async (args) => {
             const tool = byName.get(String(args.name));
-            return tool ? ok({ name: tool.name, effect: tool.effect, description: tool.description, inputSchema: z.toJSONSchema(z.object(tool.schema).meta({ additionalProperties: false }), { target: 'draft-7', io: 'input' }) }) : fail(new Error('Unknown tool. Use search_tools.'));
+            return tool ? ok({ name: tool.name, effect: tool.effect, description: tool.description, inputSchema: z.toJSONSchema(z.object(tool.schema).strict(), { target: 'draft-7', io: 'input' }) }) : fail(new Error('Unknown tool. Use search_tools.'));
         }),
         ...['read', 'write', 'admin'].map(effect => ({
             name: `call_${effect}_tool`, effect,
@@ -28,7 +28,7 @@ export function compactTools(catalog) {
                 if (!tool || tool.effect !== effect)
                     return fail(new Error(`This endpoint accepts only ${effect} tools. Use describe_tool to check the required effect.`));
                 try {
-                    return await tool.invoke(z.object(tool.schema).parse(args.arguments));
+                    return await tool.invoke(z.object(tool.schema).strict().parse(args.arguments));
                 }
                 catch (error) {
                     return fail(error);

package/dist/server.js

@@ -57,7 +57,9 @@ const PERM_RANK = { read: 0, write: 1, admin: 2 };
 function effectFor(name) {
     if (name === 'page_completeness' || name === 'resolve_page_url')
         return 'read';
-    if (name === 'retry_deploy_verification'
+    if (name === 'guide_publishing_domain_change'
+        || name === 'onboard_publishing_domain_zone'
+        || name === 'retry_deploy_verification'
         || name === 'list_apps'
         || name === 'read_app'
         || name === 'update_app'
@@ -325,7 +327,7 @@ export function buildServer(options) {
     }
     for (const tool of options.toolMode === 'compact' ? compactTools(catalog) : catalog) {
         register(tool.name, {
-            description: tool.description, inputSchema: z.object(tool.schema).meta({ additionalProperties: false }),
+            description: tool.description, inputSchema: z.object(tool.schema).strict(),
             annotations: { readOnlyHint: tool.effect === 'read', destructiveHint: tool.effect !== 'read', openWorldHint: true },
         }, tool.invoke);
     }

package/dist/tools/domain.js

@@ -16,6 +16,25 @@
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 export const domainTools = [
+    {
+        name: 'onboard_publishing_domain_zone', noSite: true,
+        description: 'Organization-admin DNS onboarding for a site owned by that organization. Create a zone in its Hosting Group account, start a Cloudflare DNS scan, review the discovered records against current public DNS and existing zone records, then apply a reviewed plan as DNS only. Nameservers are returned for the human registrar step; never changed automatically. A scan is incomplete: confirm the full old-provider inventory, especially MX/SPF/DKIM/DMARC, before applying. Existing conflicting records are never replaced. Only pending zones can import records; active zones use normal domain management.',
+        inputSchema: { site_id: z.string(), zone_name: z.string(), action: z.enum(['create_zone', 'scan_dns', 'review_dns', 'apply_dns']), plan_revision: z.string().optional(), confirm_inventory: z.boolean().optional() },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('publishing/domain-onboarding', args))),
+    },
+    {
+        name: 'guide_publishing_domain_change',
+        description: 'Guide a site domain move. Start with check: returns hosting, zone, nameserver, certificate, permission, publishing, redirect capacity and candidate checks, current phase, next action and an explicit switch summary. Preview proposed hosts before save; confirm_rebuild is required if an existing candidate would be replaced. Prepare freezes the last published content, not current CMS edits. Adding redirect hosts preserves the content candidate. Approve requires explicit user approval of the switch summary and any validation interruption. Automatic DNS is journaled and rolled back after a failed check or the agreed deadline; later external edits require manual attention. Rollback requests restoration through the serialized publication chain. External DNS remains the caller’s responsibility.',
+        inputSchema: {
+            action: z.enum(['check', 'preview', 'save', 'prepare', 'approve', 'rollback']),
+            revision: z.string().optional(), candidate_id: z.string().optional(),
+            website_host: z.string().nullable().optional(), media_host: z.string().nullable().optional(), media_path_prefix: z.string().optional(),
+            redirect_hosts: z.array(z.string()).max(4).optional(), dns_mode: z.enum(['automatic', 'external']).optional(),
+            confirm_rebuild: z.boolean().optional(), accept_validation_window: z.boolean().optional(),
+            validation_timeout_minutes: z.number().int().min(5).max(45).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'publishing/domain-guide', args))),
+    },
     {
         name: 'check_managed_site_migration',
         description: 'Verify migration of an existing static managed Pages site to connected Git publishing. Checks the original hosting account, project, domain and shared build engine. Returns a revision and previous live deployment; does not migrate or deploy.',
@@ -193,6 +212,7 @@ export const domainTools = [
         description: 'Approve switching website traffic to the verified frozen deployment. Read publishing domains first and review DNS requirements, certificate readiness and redirect_preparations. Existing traffic is preserved until validation succeeds. With automatic DNS, redirect hosts switch after the website host: Typeroll ensures their zone redirect rule, then changes their reviewed record to a proxied placeholder. The publication goes live only after every redirect host answers 301 to the website host with the same path and query. When preparation.validation_blocker.resolution is accept_validation_window, Cloudflare can validate the website host only after its one existing record points at Pages: approving with accept_validation_window: true lets Typeroll change that record, and the host does not answer until Cloudflare validates it (Cloudflare does not document how long; previous_records holds the rollback). Get the user\'s explicit go-ahead for that window and choose a quiet time. External DNS management remains the caller’s responsibility.',
         inputSchema: {
             revision: z.string(), candidate_id: z.string(),
+            validation_timeout_minutes: z.number().int().min(5).max(45).optional(),
             accept_validation_window: z.boolean().optional().describe('Accept the interruption until Cloudflare validates the website host after its single reviewed record changes. Only valid when preparation.validation_blocker.resolution is accept_validation_window.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'publishing/cutover', args))),
@@ -208,6 +228,7 @@ export const domainTools = [
         description: 'Save future website, redirect and media hosts before preparing a deployment. Normal trigger_deploy continues updating the current or temporary address, even while future hosts await validation. Shortly before changing DNS, explicitly call prepare_publishing_domain_change to prepare the last published snapshot for these hosts. A newer normal publication makes the older candidate outdated; prepare again before cutover. Requires the current revision from read_publishing_domains. This does not publish content or change traffic DNS. Choose external DNS when your agent manages Cloudflare independently. redirect_hosts (for example www.example.com when example.com is the website host) answer 301 to the website host, keeping path and query, through a Single Redirect rule in the host\'s Cloudflare zone; they are switched and verified with the website. The response includes host_checks: resolve its blockers before preparing.',
         inputSchema: {
             revision: z.string(), website_host: z.string().nullable(), media_host: z.string().nullable(),
+            confirm_rebuild: z.boolean().optional().describe('Confirm replacing a prepared content candidate after reviewing domain_rebuild_confirmation_required or the guide preview.'),
             media_path_prefix: z.string().optional().describe('Empty on a separate media host; /media when using the website host.'),
             redirect_hosts: z.array(z.string()).max(4).optional().describe('Hostnames that redirect permanently to website_host, such as www.example.com. Omit or send [] for none.'),
             dns_mode: z.enum(['automatic', 'external']),

package/dist/tools/settings.js

@@ -40,7 +40,7 @@ export const settingsTools = [
     {
         name: 'update_site_settings',
         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. ' +
+            'Pass fields at the TOP LEVEL of the object — do NOT wrap in a "settings" or "patch" 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. ' +
@@ -118,6 +118,8 @@ export const settingsTools = [
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const { version, ...body } = args;
+            if (!Object.keys(body).some(key => body[key] !== undefined))
+                throw new Error('No settings supplied. Pass at least one setting at the top level, for example {tagline: "New tagline"}; do not wrap fields in patch or settings.');
             const res = await client.patch(siteId, 'settings', body, v(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.80';
+export const VERSION = '0.45.82';

package/dist/workspace.js

@@ -51,6 +51,8 @@ Public documentation: https://typeroll.com/docs/llms.txt
 ## Edit and verify
 
 - Read current Pages, Content types, templates, partials and relevant block schemas.
+- Read pages/ notes before editing; follow workflows/page-notes.md for sources,
+  dated logs, external-link review and archiving. Keep internal notes out of public output.
 - Use native editable blocks; document necessary exceptions and design decisions.
 - Configure palette/font roles and design scales in site settings. Read workflows/design.md
   before styling blocks; run lint_design_tokens and document hardcoded exceptions.
@@ -115,7 +117,7 @@ export const workspaceTemplates = {
     '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/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",
+    '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, pages/ notes and the relevant Page | tr-edit-site |\n| Page notes and review | workflows/page-notes.md, pages/README.md, pages/index.md | Read before edits; update logs afterward |\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. For design-token exceptions include the source/block, fixed value, reason (e.g. white text on a photograph) and review criteria.\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',
 };

package/package.json

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

package/skills/tr-edit-site.md

@@ -19,7 +19,11 @@ description: Edit or create Typeroll pages with a person’s usual AI assistant.
    content types, or `search_pages` for words in saved content. Ask the user to
    choose when several pages fit their description. A different host requires
    confirming a site switch and selecting a new context; never silently switch.
-4. Read the page and relevant Page template, block types and reusable sections.
+4. When a project repository is available, read its pages/<page-id>.md note and
+   relevant decisions before editing. Follow workflows/page-notes.md: update the
+   dated log afterward, check external links during reviews, and archive notes
+   for confirmed removed Pages. Do not store private notes in public CMS fields.
+   Read the page and relevant Page template, block types and reusable sections.
    Prefer existing native blocks and shared styles. Editors may create custom
    block types and shared Page templates when needed. Read `tr-custom-blocks`
    or `tr-page-template` only when that work is relevant. Before changing a

package/skills/tr-migration-evidence.md

@@ -339,3 +339,27 @@ placeholder settings for theme decoration, preserving real featured images and
 explicit `show_image: false`. Compare actual footer link height plus gap, wrapping,
 focus and column breakpoints; compact navigation density is an intentional option.
 Verify native preview and static output on the agreed viewport boundaries.
+
+## Domain migration and redirect capacity
+
+Use `guide_publishing_domain_change` when advertised by this installation. Read
+its checklist, preview settings impact before replacing a candidate, preserve
+verified content when only redirect hosts change, and obtain explicit approval
+for the traffic summary and any interruption. A saved future hostname is not live.
+Organization-admin `onboard_publishing_domain_zone` can create a pending zone and
+review a DNS scan; copy records DNS only and verify the full inventory (especially
+mail and DKIM) before the human registrar step. Never infer completeness from a scan.
+
+Core 0.2.107 checks Pages capacity during dry-run and final upload:
+2,000 static, 100 dynamic, 1,000 characters per line, with generated slash variants
+and hostname aliases included. `_redirects` has a bounded 10 MiB transport envelope;
+`_headers` keeps 128 KiB. Source preflight counts configured rules conservatively;
+final output excludes redirects shadowing built pages. Remove obsolete shadowed
+rules at source when close to capacity. Never split `_redirects` into multiple files.
+After publication, run `verify_migration_urls` against the agreed full inventory.
+Do not delete old provider redirect lists without separate explicit approval.
+
+Record render/media reuse and actual preparation duration separately. A cache
+format, renderer, indexing or content change may require one full baseline build;
+a synthetic cache test does not prove a customer site's timing target. Media
+transfer timeouts retry the same frozen job with checkpoints, not a new publication.

package/workspace-templates/pages/README.md

@@ -0,0 +1,40 @@
+# Internal Page notes
+
+Keep internal sources, decisions, comments and dated history in this repository,
+not in public CMS fields. The CMS remains the source of current content; notes
+are editorial context, never a second content copy. Keep this workspace private
+if notes contain private information. Never put credentials or signed URLs here.
+Do not include pages/ in static output, content imports or public source bundles.
+
+One file per stable Page ID: pages/<encoded-page-id>.md. The helper percent-encodes
+IDs that contain path characters. URLs and titles can change without renaming notes.
+Use a separate workspace/Git branch for another Site or Version; the generated
+facts are bound to portal, Organization, Site and Version and reject mismatches.
+
+Each note has review, next_review (YYYY-MM or YYYY-MM-DD), last_checked and
+responsible metadata, followed by Purpose, Sources (including date and whether an
+owner statement), Publishing considerations, Open questions and Log. Use dated
+change, decision, comment and check entries; keep the newest first. Site-wide
+rules belong in decisions.md, referenced from the relevant notes.
+
+Choose a review cadence for the project, for example quarterly, annual, event-led
+or when source facts change. There is no default season or automatic review date.
+Refreshing facts never changes last_checked or next_review. Set those only after
+an actual review. index.md sorts scheduled reviews first, then unscheduled Pages.
+
+The generated block contains saved CMS metadata and candidate links from the saved
+body. It does not inspect template/partial links, JavaScript or final rendering;
+query-bearing URLs are omitted to avoid copying credentials. Check the rendered
+Page and every external link during review. Sources, historical import statistics
+and their dates belong in the human sections, not invented by the script.
+
+Run scripts/typeroll/page_notes.py --dry-run, inspect, then omit --dry-run to refresh.
+--migration-inventory optionally includes recorded redirect sources. Run from the
+workspace root with a privately injected TYPEROLL_API_KEY. No CMS writes occur.
+Only the generated markers and index.md are refreshed; malformed markers fail
+without overwriting notes. Reconcile existing notes manually before adopting the
+new marker/scope format; do not replace an established project's editorial history.
+
+Notes without a Page are reported, never deleted automatically. Confirm deletion
+and any redirect, add a final log entry, then move the note to pages/archived/.
+Do not archive just because an API call failed or access changed.

package/workspace-templates/qa/checklist.md

@@ -50,3 +50,10 @@ indexing have distinct effects but do not require repeated approval if covered.
   updates, future-host candidates and explicit traffic approval.
 - [ ] Inspect the frozen candidate's noindex/robots output, not only current CMS settings.
 - [ ] Review owner facts and dates against the chosen preserve/renew text policy.
+
+## Internal Page notes
+
+Follow workflows/page-notes.md and pages/README.md. Create notes during migration,
+read before edits, update afterward, check external links at each editorial review,
+and archive notes for confirmed removed Pages under pages/archived/. Refreshing
+generated facts never counts as a completed review. Keep notes out of public output.

package/workspace-templates/scripts/README.md

@@ -109,3 +109,10 @@ uploading or changing CMS content. Missing CMYK profiles, transparency, multiple
 frames and existing output files stop with an error. `--assume-srgb` is only for
 reviewed unprofiled RGB/gray; `--source-profile FILE.icc` supplies the actual profile.
 See workflows/source-media.md for archive verification and original preservation.
+
+## Internal Page notes
+
+`page_notes.py --dry-run` previews local note creation/fact refresh and index updates.
+Omit --dry-run to write local files; --migration-inventory adds recorded redirect
+sources. It never writes to the CMS, marks a Page reviewed or deletes notes. Read
+pages/README.md and workflows/page-notes.md before first use.

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

@@ -0,0 +1,144 @@
+"""Refresh repository-only Page facts; never edit CMS content or human notes.
+
+Run from the workspace root. --dry-run previews local changes. Optional
+--migration-inventory adds saved migration URL facts. Credentials use trlib.
+"""
+import argparse
+from datetime import date
+import hashlib
+from html.parser import HTMLParser
+import json
+from pathlib import Path
+import re
+from urllib.parse import quote, urlsplit
+import trlib
+
+START = '<!-- generated:start (page_notes.py; do not edit by hand) -->'
+END = '<!-- generated:end -->'
+
+
+def filename(page_id):
+    if not isinstance(page_id, str) or not page_id or page_id.lower() in ('readme', 'index', 'archived', '.', '..'):
+        raise ValueError('Page ID is empty or conflicts with a reserved notes path')
+    return quote(page_id, safe='-_') + '.md'
+
+
+def cell(value):
+    return str(value if value is not None else '').replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('|', '&#124;').replace('\n', ' ').replace('\r', ' ')
+
+
+class Links(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.urls = set()
+
+    def handle_starttag(self, tag, attrs):
+        if tag == 'a':
+            self.urls.update(v for k, v in attrs if k == 'href' and v)
+
+
+def body_links(page, blocks):
+    parser = Links()
+    parser.feed(page.get('html_content') or '')
+
+    def visit(value, key=''):
+        if isinstance(value, dict):
+            for k, v in value.items():
+                visit(v, k)
+        elif isinstance(value, list):
+            for v in value:
+                visit(v, key)
+        elif isinstance(value, str):
+            if key in ('href', 'link', 'url', 'button_url', 'link_url'):
+                parser.urls.add(value)
+            if '<a' in value.lower():
+                parser.feed(value)
+    for block in trlib.walk(blocks):
+        visit(block.get('data') or {})
+    # Do not persist signed preview links or query credentials in repository notes.
+    return sorted(u for u in parser.urls if not urlsplit(u).query and not urlsplit(u).username
+                  and urlsplit(u).scheme in ('', 'http', 'https'))
+
+
+def scope(config):
+    return hashlib.sha256(json.dumps([config[k] for k in ('portal', 'organization_id', 'site_id', 'version')]).encode()).hexdigest()
+
+
+def refresh(root, config, pages, links, migration=(), dry_run=False):
+    """Read all inputs before writing. Preserve every byte outside owned markers."""
+    out = root / 'pages'
+    if out.is_symlink():
+        raise ValueError('The notes directory must not be a symlink')
+    names = [filename(p['id']) for p in pages]
+    if len({n.lower() for n in names}) != len(names):
+        raise ValueError('Page IDs collide on a case-insensitive filesystem')
+    identity = '<!-- scope: ' + scope(config) + ' -->'
+    planned, rows = {}, []
+    for p, name in zip(pages, names):
+        file = out / name
+        if file.is_symlink():
+            raise ValueError('A note must not be a symlink')
+        text = file.read_text() if file.exists() else (
+            '---\nreview: unset\nnext_review: \nlast_checked: \nresponsible: \n---\n\n# ' + cell(p['title']) + '\n\n'
+            + START + '\n' + identity + '\n' + END
+            + '\n\n## Purpose\n\nTODO\n\n## Sources\n\nTODO\n\n## Publishing considerations\n\nTODO\n\n'
+              '## Open questions\n\n- Set a review cadence and next review date.\n\n## Log\n\n- '
+            + date.today().isoformat() + ' · comment · Note created; editorial review has not been performed.\n')
+        if text.count(START) != 1 or text.count(END) != 1 or text.index(START) >= text.index(END):
+            raise ValueError('Missing or ambiguous generated markers in ' + name + '; reconcile manually')
+        old = text.split(START)[1].split(END)[0]
+        if identity not in old:
+            raise ValueError('Note scope differs from the selected Organization/Site/Version: ' + name)
+        facts = [START, identity, '', '| Fact | Value |', '| --- | --- |']
+        for label, value in [('Page ID', p['id']), ('URL', p.get('url')), ('Title', p['title']),
+                             ('Status', p.get('status')), ('Content type', p.get('content_type')),
+                             ('Template', p.get('template')), ('Last saved', p.get('date_updated'))]:
+            facts.append('| ' + label + ' | ' + cell(value) + ' |')
+        aliases = [m['path'] for m in migration if m.get('status') == 'redirected' and m.get('target', '').rstrip('/') == p.get('url', '').rstrip('/')]
+        if aliases:
+            facts.append('| Recorded old URLs | ' + cell(', '.join(sorted(aliases))) + ' |')
+        facts += ['', 'Saved body link candidates (not a complete rendered-link audit; query URLs omitted):', '']
+        facts += ['- ' + cell(u) for u in links.get(p['id'], [])] or ['- None found.']
+        facts += ['', END]
+        new = text[:text.index(START)] + '\n'.join(facts) + text[text.index(END) + len(END):]
+        if new != text:
+            planned[file] = new
+        elif not file.exists():
+            planned[file] = new
+        fm = dict(re.findall(r'^(review|next_review|last_checked|responsible):[ \t]*([^\n]*)', new.split('---', 2)[1], re.M)) if new.startswith('---\n') else {}
+        nxt = fm.get('next_review', '').strip()
+        if nxt and not re.fullmatch(r'\d{4}-\d{2}(?:-\d{2})?', nxt):
+            raise ValueError('Use YYYY-MM or YYYY-MM-DD for next_review in ' + name)
+        rows.append((nxt or '9999', name, '| ' + (nxt or 'Not scheduled') + ' | [' + cell(p['title']).replace('[', '&#91;').replace(']', '&#93;') + '](' + name + ') | ' + cell(fm.get('review', 'unset')) + ' | ' + cell(fm.get('last_checked', '')) + ' |'))
+    index = out / 'index.md'
+    if index.is_symlink():
+        raise ValueError('The notes index must not be a symlink')
+    index_text = '# Page notes index\n\nGenerated from local notes; dates are editorial decisions, not CMS save dates.\n\n| Next review | Page | Cadence | Last checked |\n| --- | --- | --- | --- |\n' + '\n'.join(r[2] for r in sorted(rows)) + '\n'
+    if not index.exists() or index.read_text() != index_text:
+        planned[index] = index_text
+    orphans = sorted(f.name for f in out.glob('*.md') if f.name not in {*names, 'README.md', 'index.md'})
+    if not dry_run:
+        out.mkdir(parents=True, exist_ok=True)
+        for file, text in planned.items():
+            file.write_text(text)
+    return {'changed': [str(f.relative_to(root)) for f in planned], 'notes_without_page': orphans, 'dry_run': dry_run}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--dry-run', action='store_true')
+    parser.add_argument('--migration-inventory', action='store_true')
+    args = parser.parse_args()
+    root = Path.cwd()
+    if not (root / 'typeroll.json').is_file():
+        parser.error('Run from the workspace root containing typeroll.json')
+    config = trlib.workspace()
+    # list_pages(full=True) reads saved content, unlike read_page's draft overlay.
+    pages = list(trlib.all_pages(full=True))
+    links = {p['id']: body_links(p, p.get('blocks') or []) for p in pages}
+    migration = list(trlib.all_migration_urls()) if args.migration_inventory else []
+    print(json.dumps(refresh(root, config, pages, links, migration, args.dry_run), indent=2))
+
+
+if __name__ == '__main__':
+    main()

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

@@ -155,10 +155,10 @@ def walk(blocks):
             yield from walk(slot)
 
 
-def all_pages():
+def all_pages(full=False):
     cursor, seen = None, set()
     while True:
-        args = {'limit': 200, **({'cursor': cursor} if cursor else {})}
+        args = {'limit': 200, **({'full': True} if full else {}), **({'cursor': cursor} if cursor else {})}
         result = call('list_pages', args)
         yield from result['pages']
         cursor = result.get('next_cursor')

package/workspace-templates/workflows/migration.md

@@ -127,3 +127,10 @@ recurring-event wording only when a source supports recurrence. Flag uncertain
 facts for review or keep new Pages in draft; missing evidence does not prove that
 an event stopped. Link to the actual organiser when relevant. Upload approved
 photos with SHA-256 verification and review focal points at mobile/desktop widths.
+
+## Internal Page notes
+
+Follow workflows/page-notes.md and pages/README.md. Create notes during migration,
+read before edits, update afterward, check external links at each editorial review,
+and archive notes for confirmed removed Pages under pages/archived/. Refreshing
+generated facts never counts as a completed review. Keep notes out of public output.

package/workspace-templates/workflows/page-notes.md

@@ -0,0 +1,20 @@
+# Page notes and editorial review
+
+1. During migration or creation, create pages/<page-id>.md using pages/README.md.
+   Record sources, preservation choices, owner decisions and open questions.
+2. Before editing a Page, read its note and relevant decisions.md entries. Missing
+   notes mean missing context, not permission to invent facts. Read current CMS
+   content too; do not overwrite newer edits from repository snapshots.
+3. After an authorized edit, append a dated change/decision/comment entry, update
+   sources and open questions, and refresh generated facts with page_notes.py.
+   Saving or refreshing is not editorial review and must not advance last_checked.
+4. At each review, inspect the current rendered Page and follow every external
+   link, including template links. Verify destination and relevance, not just HTTP
+   status. Record redirects, failures and uncertain checks; propose corrections
+   instead of inventing replacements. Record actual review date and next review.
+5. For a confirmed removed Page, log deletion, replacement/redirect and archive
+   location, then move its note into pages/archived/. Keep its history in Git.
+
+Use index.md as a review queue; no scheduler or mail is enabled by this routine.
+Publication and DNS changes still require their normal authorization. These notes
+are repository-only; no new MCP Page-notes fields or portal storage are implied.