@typeroll/mcp-server 0.45.81 → 0.45.83

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/extension-cli.js

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { apiUrlProblem } from './api-url.js';
 function option(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -83,11 +84,32 @@ export function extensionMetadataUpdate(manifest, registered, manifestOrigins) {
     }
     return update;
 }
+/** One id segment, by the same rule the portal applies to allowed_site_ids. */
+function isIdSegment(value) {
+    return value.length >= 1 && value.length <= 128 && value !== '.' && value !== '..' && !/[/\\\s\x00-\x1f\x7f]/.test(value);
+}
+/**
+ * Parse `install --site`. `org/site` names a site of any organization and is
+ * written to allowed_site_ids in that form; a bare site id only ever matches
+ * a site of the developer organization itself.
+ */
+export function parseInstallSite(value) {
+    const parts = value.split('/');
+    if (parts.length === 1 && isIdSegment(value))
+        return { siteId: value, ownerOrgId: null, allowEntry: value };
+    if (parts.length === 2 && isIdSegment(parts[0]) && isIdSegment(parts[1])) {
+        return { siteId: parts[1], ownerOrgId: parts[0], allowEntry: value };
+    }
+    throw new Error('--site must be <site-id> or <organization-id>/<site-id>');
+}
 async function api(path, init = {}, allowed = []) {
     const baseUrl = process.env.TYPEROLL_API_URL?.trim().replace(/\/$/, '');
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
     if (!baseUrl || !apiKey)
         throw new Error('TYPEROLL_API_URL and TYPEROLL_API_KEY are required');
+    const apiUrlError = apiUrlProblem(baseUrl);
+    if (apiUrlError)
+        throw new Error(apiUrlError);
     const headers = new Headers(init.headers);
     headers.set('Authorization', `Bearer ${apiKey}`);
     if (init.body)
@@ -102,7 +124,7 @@ function help() {
     console.error('Usage:');
     console.error('  typeroll extension validate [manifest]');
     console.error('  typeroll extension push --draft [--manifest path]');
-    console.error('  typeroll extension install --site <site-id> [--manifest path] [--config config.json]');
+    console.error('  typeroll extension install --site <site-id | organization-id/site-id> [--manifest path] [--config config.json]');
     console.error('  typeroll extension configure --site <site-id> --installation <installation-id> --config config.json [--no-deploy]');
     console.error('  typeroll extension promote <version> [--manifest path]');
 }
@@ -193,24 +215,32 @@ export async function runExtensionCli(args) {
             return 0;
         }
         if (command === 'install') {
-            const siteId = option(args, '--site');
-            if (!siteId)
-                throw new Error('install requires --site <site-id>');
+            const siteOption = option(args, '--site');
+            if (!siteOption)
+                throw new Error('install requires --site <site-id> or --site <organization-id>/<site-id>');
+            const site = parseInstallSite(siteOption);
             const configPath = option(args, '--config');
             const config = configPath ? await readJson(configPath) : {};
             const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : [];
             if (manifest.distribution === 'private') {
+                if (!site.ownerOrgId) {
+                    console.error(`Note: allowed_site_ids entry "${site.allowEntry}" only allows a site of your developer organization. `
+                        + 'To allow a site of another organization, pass --site <organization-id>/<site-id>.');
+                }
                 const current = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`);
                 const registered = current.data.extension;
                 const allowed = Array.isArray(registered?.allowed_site_ids) ? registered.allowed_site_ids.map(String) : [];
-                if (!allowed.includes(siteId)) {
+                if (!allowed.includes(site.allowEntry)) {
                     await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {
-                        method: 'PATCH', body: JSON.stringify({ allowed_site_ids: [...allowed, siteId] }),
+                        method: 'PATCH', body: JSON.stringify({ allowed_site_ids: [...allowed, site.allowEntry] }),
                     });
                 }
             }
-            const installed = await api(`/api/v1/sites/${encodeURIComponent(siteId)}/extensions`, {
+            // With `org/site`, declare the owner so the server refuses to resolve the
+            // id to a different organization's site of the same name.
+            const installed = await api(`/api/v1/sites/${encodeURIComponent(site.siteId)}/extensions`, {
                 method: 'POST',
+                headers: site.ownerOrgId ? { 'Typeroll-Organization': site.ownerOrgId } : undefined,
                 body: JSON.stringify({
                     extension_id: extensionId,
                     version: manifest.version,

package/dist/index.js

@@ -20,6 +20,7 @@ import { resolveSiteId } from './resolve-site-id.js';
 import { buildServer } from './server.js';
 import { VERSION } from './version.js';
 import { runExtensionCli } from './extension-cli.js';
+import { apiUrlProblem } from './api-url.js';
 import { doctor, readWorkspace, workspaceClient, verifyWorkspaceBinding } from './workspace.js';
 function bail(message) {
     console.error(`typeroll-mcp: ${message}`);
@@ -85,6 +86,9 @@ async function main() {
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
     if (!apiUrl)
         bail('TYPEROLL_API_URL is not set. Point it at your Typeroll portal (e.g. https://app.typeroll.com).');
+    const apiUrlError = apiUrlProblem(apiUrl);
+    if (apiUrlError)
+        bail(apiUrlError);
     if (!apiKey)
         bail('TYPEROLL_API_KEY is not set. Create a key in /app/sites/{siteId}/settings/api-keys and copy it once.');
     if (!apiKey.startsWith('typeroll_live_')) {

package/dist/server.js

@@ -97,6 +97,7 @@ function effectFor(name) {
         || name === 'revoke_site_share'
         || name === 'revoke_organization_api_key'
         || name === 'create_organization_invite'
+        || name === 'revoke_organization_invite'
         || name === 'set_organization_ai_key'
         || name === 'remove_organization_ai_key'
         || name === 'set_organization_ai_site_access'
@@ -327,7 +328,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/access.js

@@ -6,10 +6,11 @@
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 const keyId = z.string().regex(/^[a-f0-9]{12}$/).describe('Key id (the 12-hex prefix) from list_api_keys / list_organization_api_keys.');
+const inviteId = z.string().regex(/^[A-Za-z0-9_-]{16,64}$/).describe('Invite id from create_organization_invite or list_organization_invites.');
 export const accessTools = [
     {
         name: 'list_api_keys',
-        description: 'List this Site\'s site-scoped API keys: id (prefix), name, created_at/created_by, last_used_at/last_used_ip and revoked_at. Never returns secrets or hashes. Any key that reaches the Site may list, as in Site settings → API keys.',
+        description: 'List this Site\'s site-scoped API keys: id (prefix), name, created_at/created_by, last_used_at/last_used_ip and revoked_at. Never returns secrets or hashes. Requires admin on the Site, as in Site settings → API keys.',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'api-keys'))),
     },
@@ -69,10 +70,28 @@ export const accessTools = [
     {
         name: 'create_organization_invite',
         noSite: true,
-        description: 'Create a signed invite link to the Organization (organization API key required). The invited person opens invite_url, signs in and joins as an editor; the link works until expires_at (ttl_days 1–30, default 7) and cannot be revoked early. Send it only to the person the user named.',
-        inputSchema: { ttl_days: z.number().int().min(1).max(30).optional() },
+        description: 'Create a signed invite link to the Organization (organization API key required). The invited person opens invite_url, signs in and joins as an editor. The link works until expires_at (ttl_days 1–30, default 7) for max_uses people (1–50, default 1: single use); with email set, only a person signed in with that address can redeem it. Returns the invite id; list_organization_invites shows its state and revoke_organization_invite (or DELETE /api/v1/organization/invites/{id}) stops the link immediately. Send the link only to the person the user named.',
+        inputSchema: {
+            ttl_days: z.number().int().min(1).max(30).optional(),
+            max_uses: z.number().int().min(1).max(50).optional().describe('How many people may redeem the link. Default 1 (single use).'),
+            email: z.string().email().max(320).optional().describe('Bind the invite to this email address: only a person signed in with it can redeem the link.'),
+        },
         handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('organization/invites', args))),
     },
+    {
+        name: 'list_organization_invites',
+        noSite: true,
+        description: 'List the Organization\'s invites, newest first, without their links: id, state (active | used | expired | revoked), role, email (when bound), created_by, created_at, expires_at, max_uses, used_count and revoked_at. Requires an organization API key; site-scoped keys get 403.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('organization/invites'))),
+    },
+    {
+        name: 'revoke_organization_invite',
+        noSite: true,
+        description: 'Revoke an Organization invite by id (from create_organization_invite or list_organization_invites). Its link stops working immediately; people who already joined keep their membership. Requires an organization API key.',
+        inputSchema: { invite_id: inviteId },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootDelete(`organization/invites/${encodeURIComponent(args.invite_id)}`))),
+    },
     {
         name: 'read_organization_ai_settings',
         noSite: true,

package/dist/tools/extensions.js

@@ -148,15 +148,15 @@ export const developerExtensionTools = [
     },
     {
         name: 'update_developer_extension', noSite: true,
-        description: 'Update an Extension\'s name, status (active/suspended), distribution (only while every release is a draft), trusted origins or private allow-lists. Requires an organization API key.',
+        description: 'Update an Extension\'s name, status (active/suspended), distribution (only while every release is a draft), trusted origins or private allow-lists. Each list replaces the saved one: allowed_org_ids allows every Site of those Organizations; allowed_site_ids entries are "<organization-id>/<site-id>" for a Site of another Organization, while a bare site id only matches a Site of your own developer Organization. Requires an organization API key.',
         inputSchema: {
             extension_id: z.string().min(1),
             name: z.string().optional(),
             status: z.enum(['active', 'suspended']).optional(),
             distribution: z.enum(['private', 'unlisted', 'public']).optional(),
             trusted_origins: z.array(z.string()).optional(),
-            allowed_org_ids: z.array(z.string()).optional(),
-            allowed_site_ids: z.array(z.string()).optional(),
+            allowed_org_ids: z.array(z.string()).optional().describe('Organization ids whose every Site may install this private Extension. Replaces the saved list.'),
+            allowed_site_ids: z.array(z.string().max(257)).max(500).optional().describe('Sites that may install this private Extension, replacing the saved list: "<organization-id>/<site-id>" for another Organization\'s Site, or a bare site id for a Site of your own developer Organization.'),
         },
         handler: withErrorBoundary(async (args, { client }) => {
             const { extension_id, ...patch } = args;

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

package/dist/workspace.js

@@ -5,12 +5,12 @@ import { z } from 'zod';
 import { VERSION } from './version.js';
 import { BUNDLED_WORKSPACE_TEMPLATES } from './bundled-content.js';
 import { ApiError, TyperollClient } from './client.js';
+import { isSecureApiUrl } from './api-url.js';
 export const workspaceSchema = z.object({
     schema_version: z.literal(1),
     portal: z.string().url().refine(value => {
         const url = new URL(value);
-        return !url.username && !url.password && !url.search && !url.hash && url.pathname === '/' &&
-            (url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)));
+        return !url.username && !url.password && !url.search && !url.hash && url.pathname === '/' && isSecureApiUrl(url);
     }, 'Use an HTTPS portal origin (HTTP is allowed only on loopback).'),
     organization_id: z.string().min(1).nullable(), site_id: z.string().min(1).nullable(),
     version: z.string().min(1), tool_mode: z.enum(['compact', 'full']),
@@ -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',
 };
@@ -184,11 +186,32 @@ export async function writeWorkspaceFiles(dir, templates, update) {
     await fs.writeFile(lockFile, JSON.stringify({ schema_version: 1, generator_version: VERSION, files }, null, 2) + '\n');
     return results;
 }
+/** The hosted Typeroll Cloud portal: the only origin trusted from typeroll.json alone. */
+export const OFFICIAL_PORTAL_ORIGIN = 'https://app.typeroll.com';
+/** Raised before any credential is sent when the committed portal is not confirmed by the environment. */
+export class UntrustedPortalError extends Error {
+}
+/**
+ * typeroll.json is committed and can be changed by anyone who can open a pull
+ * request, so its portal alone never receives the injected API key. Another
+ * origin must be confirmed through the private TYPEROLL_API_URL setting.
+ */
+export function assertTrustedPortal(config, env) {
+    const portal = config.portal.replace(/\/$/, '');
+    const confirmed = env.TYPEROLL_API_URL?.trim().replace(/\/$/, '');
+    if (confirmed) {
+        if (confirmed !== portal)
+            throw new Error('TYPEROLL_API_URL conflicts with typeroll.json.');
+        return;
+    }
+    if (portal !== OFFICIAL_PORTAL_ORIGIN) {
+        throw new UntrustedPortalError(`typeroll.json names the portal ${portal}. The API key is sent only to ${OFFICIAL_PORTAL_ORIGIN} unless you confirm another portal: set TYPEROLL_API_URL=${portal} in your private client settings or environment.`);
+    }
+}
 export function workspaceClient(config, env, fetchImpl) {
     if (!env.TYPEROLL_API_KEY)
         throw new Error('Inject TYPEROLL_API_KEY through private client settings or the environment.');
-    if (env.TYPEROLL_API_URL && env.TYPEROLL_API_URL.replace(/\/$/, '') !== config.portal.replace(/\/$/, ''))
-        throw new Error('TYPEROLL_API_URL conflicts with typeroll.json.');
+    assertTrustedPortal(config, env);
     if (env.TYPEROLL_SITE_ID && env.TYPEROLL_SITE_ID !== config.site_id)
         throw new Error('TYPEROLL_SITE_ID conflicts with typeroll.json.');
     return new TyperollClient({ baseUrl: config.portal, apiKey: env.TYPEROLL_API_KEY, defaultVersion: config.version, fetchImpl });
@@ -227,7 +250,7 @@ export async function doctor(dir, offline, env = process.env, fetchImpl) {
             checks.push({ check: 'writes_and_publishing', status: 'not_checked', message: 'Read-only doctor. No edits, media transfer, app activation or publication was attempted; check publishing/import readiness for those tasks.' });
         }
         catch (error) {
-            checks.push({ check: 'connection', status: 'required', message: error instanceof ApiError ? `Portal HTTP ${error.status}. Check credential scope, portal and Site/Version.` : 'Could not verify the connection. Check injected credentials, matching environment, network and Site/Version.' });
+            checks.push({ check: 'connection', status: 'required', message: error instanceof ApiError ? `Portal HTTP ${error.status}. Check credential scope, portal and Site/Version.` : error instanceof UntrustedPortalError ? error.message : 'Could not verify the connection. Check injected credentials, matching environment, network and Site/Version.' });
         }
     }
     return { passed: !checks.some(check => check.status === 'required'), generator_version: VERSION, checks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.81",
+  "version": "0.45.83",
   "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/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

@@ -13,7 +13,8 @@ npx playwright install chromium
 Run the commands below from the **workspace root**. Inject TYPEROLL_API_KEY through
 your private credential manager. Never put it in a file or command argument.
 trlib.py reads portal, organization_id, site_id and version from typeroll.json,
-checks the connected Site/Organization, discovers the live tool schema, and
+sends the key only to https://app.typeroll.com or to a portal you confirm by
+setting TYPEROLL_API_URL to the same origin privately, checks the connected Site/Organization, discovers the live tool schema, and
 passes the Version where supported. It refuses unversioned operations on a
 non-main binding; use the explicit interactive API workflow for organization or
 shared media operations instead. It is a small hosted MCP helper for API keys,
@@ -109,3 +110,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

@@ -31,6 +31,28 @@ def workspace():
     raise ValueError('Run from a workspace containing typeroll.json')
 
 
+OFFICIAL_PORTAL = 'https://app.typeroll.com'
+
+
+def trusted_portal(config):
+    """Return the portal origin that may receive the API key.
+
+    typeroll.json is committed, so its portal alone is trusted only when it is
+    the hosted portal. Another origin must be confirmed by TYPEROLL_API_URL.
+    """
+    portal = config['portal'].rstrip('/')
+    confirmed = (os.environ.get('TYPEROLL_API_URL') or '').strip().rstrip('/')
+    if confirmed:
+        if confirmed != portal:
+            raise ValueError('TYPEROLL_API_URL conflicts with typeroll.json')
+        return portal
+    if portal != OFFICIAL_PORTAL:
+        raise ValueError(f'typeroll.json names the portal {portal}. The API key is sent only to '
+                         f'{OFFICIAL_PORTAL} unless you confirm another portal: set '
+                         f'TYPEROLL_API_URL={portal} in your private environment')
+    return portal
+
+
 class Client:
     def __init__(self, config=None):
         self.config = config or workspace()
@@ -51,6 +73,8 @@ class Client:
         key = os.environ.get('TYPEROLL_API_KEY')
         if not key:
             raise ValueError('Inject TYPEROLL_API_KEY privately before running')
+        if trusted_portal(self.config) + '/api/mcp?tools=full' != self.url:
+            raise ValueError('Workspace portal changed after the client was created')
         headers = {'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json',
                    'Accept': 'application/json, text/event-stream'}
         if self.session:
@@ -155,10 +179,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.