@typeroll/mcp-server 0.26.2 → 0.28.0

package/dist/server.js

@@ -22,6 +22,7 @@ import { deployTools } from './tools/deploy.js';
 import { previewTools } from './tools/preview.js';
 import { blockTypeTools } from './tools/block-types.js';
 import { pageBlockTools } from './tools/page-blocks.js';
+import { workingCopyTools } from './tools/working-copy.js';
 import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
 import { domainTools } from './tools/domain.js';
@@ -72,13 +73,19 @@ playbook ships with this server — use it:
    the canonical how-to; don't improvise what a skill already covers.
 2. Discover before you write: get_site, read_site_settings, list_pages,
    list_block_types. Never hardcode block ids or field names — they're per-site.
-3. Branch first for anything larger than a small edit: create_branch, pass
+3. THE BUFFER MODEL: every content write (pages, blocks, partials,
+   collection items) lands in an unsaved per-doc DRAFT — deploys and plain
+   previews see saved content only. Iterate freely, view your drafts with
+   include_working_copy on the preview tools, then SAVE explicitly:
+   commit_working_copy (or save:true on the write call) when the user
+   approves. Status changes and structural ops apply immediately.
+4. Branch first for anything larger than a small edit: create_branch, pass
    version=<id> on every subsequent call, merge_branch once approved. Nothing
    touches the live site until then.
-4. Pages default to block mode. Build with add_block/update_block; make layouts
+5. Pages default to block mode. Build with add_block/update_block; make layouts
    responsive per breakpoint with set_block_responsive (grid columns, icon-box
    layout, … take { mobile, tablet, laptop, desktop, wide } values).
-5. No site yet? With an org-scoped key, create_site bootstraps one.
+6. No site yet? With an org-scoped key, create_site bootstraps one.
 
 If anything here conflicts with what a tool returns, trust the tool. Every
 tool's own description carries its specifics.
@@ -101,6 +108,7 @@ export function buildServer(options) {
         ...partialTools,
         ...blockTypeTools,
         ...pageBlockTools,
+        ...workingCopyTools,
         ...collectionTools,
         ...mediaTools,
         ...redirectTools,

package/dist/tools/bulk.js

@@ -6,13 +6,14 @@ function v(version) {
 export const bulkTools = [
     {
         name: 'bulk_replace_text',
-        description: 'Replace a literal substring or regex across pages in one call. ALWAYS run with dry_run=true first and show the sample_diffs to the user before running the real call. Writes go through the normal pipeline (SEO transforms + revision snapshots). Response shape: { dry_run, updated, total_matches, pages_with_matches, sample_diffs_shown, additional_pages_with_matches, sample_diffs[], skipped (deprecated) }.',
+        description: 'Replace a literal substring or regex across pages in one call. ALWAYS run with dry_run=true first and show the sample_diffs to the user before running the real call. BUFFER MODEL: replacements land in each page\'s unsaved DRAFT; after the user approves the diffs, run with save:true to commit each touched page (revision snapshots + SEO transforms included). Response: { dry_run, updated, saved, total_matches, pages_with_matches, sample_diffs_shown, additional_pages_with_matches, sample_diffs[], skipped (deprecated) }.',
         inputSchema: {
             pattern: z.string().min(1).describe('Literal substring (default) or JS regex source if regex=true.'),
             replacement: z.string(),
             regex: z.boolean().optional().describe('Treat pattern as a regex source. Always case-insensitive + global.'),
             page_ids: z.array(z.string()).optional().describe('Restrict to these page ids. Omit to apply to every matching page.'),
             dry_run: z.boolean().optional(),
+            save: z.boolean().optional().describe('Commit every touched page\'s draft in the same call — the usual choice after the user approved the dry-run diffs.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/collections.js

@@ -156,12 +156,13 @@ export const collectionTools = [
     },
     {
         name: 'update_collection_item',
-        description: 'Update a collection item. Fields outside the schema are dropped.',
+        description: 'Update a collection item. Fields outside the schema are dropped. BUFFER MODEL: field values land in the item\'s unsaved DRAFT (status applies immediately); pass save:true to commit in the same call, or commit_working_copy later.',
         inputSchema: {
             collection: z.string(),
             item_id: z.string(),
             fields: z.record(z.unknown()).optional(),
             status: z.enum(['draft', 'published']).optional(),
+            save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/deploy.js

@@ -6,7 +6,7 @@ function v(version) {
 export const deployTools = [
     {
         name: 'trigger_deploy',
-        description: "Enqueue a deploy (static-page build → hosting) of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running. NOT for previewing iterative design/content edits — that's what get_preview_link is for (it renders live from the DB with no build). Reserve trigger_deploy for publishing, a stakeholder link to the compiled site, or pre-merge validation. With `dry_run: true`, the deploy runs through every step EXCEPT the hosting-adapter upload — useful for validating a structural change (new collection routes, schema bump, mode switch) without risking the live site. A dry_run job that succeeds proves the build is clean; one that fails returns the same astro stack-trace in get_deploy_status.error as a real deploy would.",
+        description: "Enqueue a deploy (static-page build → hosting) of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running. NOT for previewing iterative design/content edits — that's what get_preview_link is for (it renders live from the DB with no build). Reserve trigger_deploy for publishing, a stakeholder link to the compiled site, or pre-merge validation. Deploys build SAVED content only — unsaved drafts (working copies) are excluded, so commit_working_copy (or save:true on your writes) before deploying, or your changes won't ship. With `dry_run: true`, the deploy runs through every step EXCEPT the hosting-adapter upload — useful for validating a structural change (new collection routes, schema bump, mode switch) without risking the live site. A dry_run job that succeeds proves the build is clean; one that fails returns the same astro stack-trace in get_deploy_status.error as a real deploy would.",
         inputSchema: {
             environment: z.enum(['production', 'staging']).optional(),
             dry_run: z.boolean().optional().describe('Run the build but skip the CDN upload. The job ends in succeeded/failed the same way a real deploy does.'),

package/dist/tools/page-blocks.js

@@ -53,7 +53,7 @@ function pathFor(target, pageId) {
 export const pageBlockTools = [
     {
         name: 'get_page_blocks',
-        description: 'Read the block tree of a container (page, partial, or page template). Use `target: { kind, id }` for partials/templates. For pages, `page_id` is the back-compat shorthand. Returns content_mode + blocks. Empty array for HTML-mode pages — those store body content in html_content instead. Always call this before any block mutation so you know what you\'re modifying.',
+        description: 'Read the block tree of a container (page, partial, or page template). Use `target: { kind, id }` for partials/templates. For pages, `page_id` is the back-compat shorthand. Returns the DRAFT VIEW — the tree with any unsaved edits (yours or the editor\'s) included, i.e. exactly what the next mutation operates on. Empty array for HTML-mode pages. Always call this before any block mutation so you know what you\'re modifying.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional().describe('Shorthand for target={kind:"page", id:page_id}.'),
@@ -67,7 +67,7 @@ export const pageBlockTools = [
     },
     {
         name: 'add_block',
-        description: 'Insert a block into a container (page, partial, or page template). With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into a slot for slot-containers). Position defaults to "end". Slot containers (core/columns, core/tabs — container: "slots"): slot_index picks the slot (0-based; defaults to 0) and works even if the parent instance has no slots array yet; a freshly added slot container gets its slots initialised to the type\'s arity. You can also pass the whole subtree inline via block.slots: [[...],[...]]. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand.',
+        description: 'Insert a block into a container (page, partial, or page template). BUFFER MODEL: block mutations on pages/partials edit the unsaved DRAFT — commit_working_copy is the explicit save. With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into a slot for slot-containers). Position defaults to "end". Slot containers (core/columns, core/tabs — container: "slots"): slot_index picks the slot (0-based; defaults to 0) and works even if the parent instance has no slots array yet; a freshly added slot container gets its slots initialised to the type\'s arity. You can also pass the whole subtree inline via block.slots: [[...],[...]]. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -167,7 +167,9 @@ export const pageBlockTools = [
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
-            const res = await client.post(siteId, `${path}/duplicate`, { block_id: args.block_id }, v(args.version));
+            const res = await client.post(siteId, `${path}/duplicate`, {
+                block_id: args.block_id,
+            }, v(args.version));
             return ok(res);
         }),
     },

package/dist/tools/pages.js

@@ -28,7 +28,7 @@ export const pageTools = [
     },
     {
         name: 'read_page',
-        description: 'Fetch one page in full — title, slug, status, html_content, SEO fields.',
+        description: 'Fetch one page in full — title, slug, status, html_content, SEO fields. Returns the DRAFT VIEW: the saved page with any unsaved draft (working copy) overlaid, plus has_unsaved_changes.',
         inputSchema: {
             page_id: z.string(),
             version: versionParam,
@@ -102,7 +102,7 @@ export const pageTools = [
     },
     {
         name: 'update_page',
-        description: 'Shallow-merge update on a page (only the fields you pass change). Returns the updated page. For "replace this page entirely", use replace_page instead. To switch content_mode safely with a revision snapshot + optional auto-conversion, prefer `set_page_mode`.',
+        description: 'Shallow-merge update on a page (only the fields you pass change). BUFFER MODEL: content fields land in the page\'s unsaved DRAFT (working copy) — invisible to deploys and default previews until saved; `status`/`date_published` apply immediately. Pass save:true to commit in the same call, or commit_working_copy later after the user approves. Returns the draft view of the page. For "replace this page entirely", use replace_page. To switch content_mode safely, prefer `set_page_mode`.',
         inputSchema: {
             page_id: z.string(),
             patch: z
@@ -139,41 +139,48 @@ export const pageTools = [
                 template: z.string().optional(),
             })
                 .passthrough(),
+            save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call — use for pre-approved or batch changes. Without it, changes stay in the unsaved draft until commit_working_copy.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, args.patch, v(args.version));
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.patch, ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'replace_page',
-        description: 'Full replace of a page\'s writable fields (PUT). Omitted fields are reset to undefined; use update_page if you want shallow merge.',
+        description: 'Full replace of a page\'s writable content fields (PUT) — omitted fields are cleared. BUFFER MODEL: the replacement is an unsaved DRAFT until committed; pass save:true to commit in the same call. Use update_page for shallow merge.',
         inputSchema: {
             page_id: z.string(),
             page: z.object({ title: z.string().min(1) }).passthrough(),
+            save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call — use for pre-approved or batch changes. Without it, changes stay in the unsaved draft until commit_working_copy.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, args.page, v(args.version));
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.page, ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'batch_update_pages',
-        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch }; failures are reported per-row, the rest still apply.',
+        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch, save? }; failures are reported per-row, the rest still apply. BUFFER MODEL: content patches land in each page\'s unsaved draft; per-entry save:true (or the top-level save flag) commits — typical for a user-approved sweep.',
         inputSchema: {
             updates: z
                 .array(z.object({
                 page_id: z.string(),
                 patch: z.record(z.unknown()),
+                save: z.boolean().optional(),
             }))
                 .min(1)
                 .max(200),
+            save: z.boolean().optional().describe('Commit every entry\'s draft (shorthand for save:true on each).'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, 'pages/batch-write', args.updates, v(args.version));
+            const updates = args.save
+                ? args.updates.map((u) => ({ ...u, save: true }))
+                : args.updates;
+            const res = await client.post(siteId, 'pages/batch-write', updates, v(args.version));
             return ok(res);
         }),
     },
@@ -245,12 +252,18 @@ export const pageTools = [
                 .boolean()
                 .optional()
                 .describe('Tag every block root with data-block-id (the authored block id) + data-block-type so you can map a rendered element back to the exact block to mutate. Off by default.'),
+            include_working_copy: z
+                .boolean()
+                .optional()
+                .describe('Overlay unsaved drafts (working copies) on the render — yours and the editor\'s. Off by default (saved content only). Pass true to inspect your own uncommitted edits.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const query = { ...(v(args.version) ?? {}) };
             if (args.annotate)
                 query.annotate = 'true';
+            if (args.include_working_copy)
+                query.working_copy = 'true';
             const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/preview`, query);
             return ok(res);
         }),

package/dist/tools/partials.js

@@ -34,7 +34,7 @@ export const partialTools = [
     },
     {
         name: 'update_partial',
-        description: 'Shallow-merge update on a global block. Use partial_id "header" or "footer" for the auto-injected layout blocks, or a kebab-case id for a free block. HTML is sanitized server-side.',
+        description: 'Shallow-merge update on a global block. Use partial_id "header" or "footer" for the auto-injected layout blocks, or a kebab-case id for a free block. HTML is sanitized server-side. BUFFER MODEL: content lands in the partial\'s unsaved DRAFT (status applies immediately); pass save:true to commit in the same call, or commit_working_copy later.',
         inputSchema: {
             partial_id: z.string(),
             patch: z
@@ -45,10 +45,11 @@ export const partialTools = [
                 kind: z.enum(['header', 'footer', 'free']).optional(),
             })
                 .passthrough(),
+            save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.patch(siteId, `partials/${encodeURIComponent(args.partial_id)}`, args.patch, v(args.version));
+            const res = await client.patch(siteId, `partials/${encodeURIComponent(args.partial_id)}`, { ...args.patch, ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -56,12 +57,14 @@ export const partialTools = [
         name: 'replace_partial',
         description: 'Full replace of a global block (PUT). Pass html_content (and optionally name/status) directly — no wrapper object needed. ' +
             'kind is auto-inferred from partial_id ("header" → header, "footer" → footer, anything else → free). ' +
-            'For incremental edits (changing one field without replacing the whole block) use update_partial instead.',
+            'For incremental edits (changing one field without replacing the whole block) use update_partial instead. ' +
+            'BUFFER MODEL: content lands in the partial\'s unsaved DRAFT; pass save:true to commit in the same call.',
         inputSchema: {
             partial_id: z.string().describe('"header", "footer", or a free-block kebab-id.'),
             html_content: z.string().describe('Full HTML for the block. Replaces any existing content.'),
             name: z.string().optional().describe('Human-readable label shown in the UI.'),
             status: z.enum(['draft', 'published']).optional(),
+            save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/preview.js

@@ -6,13 +6,17 @@ function v(version) {
 export const previewTools = [
     {
         name: 'get_preview_link',
-        description: 'Mint a signed URL the user (or your own browser tool) can open to SEE the rendered preview. Renders LIVE from the database with NO build, so reloading shows every edit immediately — this is the PREFERRED way to preview design/content changes as you iterate (and to verify your own edits); reach for this, not trigger_deploy, when previewing. Mint it ONCE and REUSE that single URL across edits — internal links keep the token so it navigates the whole branch, and it stays valid until the TTL lapses (re-mint only then, never per edit). The TTL defaults to 24h (also the max); pass a smaller ttl_seconds only if you specifically want a shorter-lived link. Target a page (page_id), a collection item (collection_name + item_id, resolves via route_template), or a raw slug; omit all to land on the home page. (For a permanently-bookmarkable link to the COMPILED static site, deploy and share the {branch}.{project}.pages.dev alias instead — that only refreshes on trigger_deploy.)',
+        description: 'Mint a signed URL the user (or your own browser tool) can open to SEE the rendered preview. Renders LIVE from the database with NO build — this is the PREFERRED way to preview design/content changes as you iterate; reach for this, not trigger_deploy, when previewing. BUFFER MODEL: your edits are unsaved drafts, so for the iteration loop mint the link with include_working_copy:true (drafts visible); a plain link shows SAVED content only — right for stakeholders reviewing what will deploy. Mint ONCE and REUSE that single URL across edits — internal links keep the token so it navigates the whole branch, and it stays valid until the TTL lapses (24h default and max). Target a page (page_id), a collection item (collection_name + item_id), or a raw slug; omit all for the home page. (For a permanently-bookmarkable link to the COMPILED static site, deploy and share the {branch}.{project}.pages.dev alias instead.)',
         inputSchema: {
             page_id: z.string().optional(),
             slug: z.string().optional(),
             collection_name: z.string().optional(),
             item_id: z.string().optional(),
             ttl_seconds: z.number().int().min(60).max(86_400).optional(),
+            include_working_copy: z
+                .boolean()
+                .optional()
+                .describe('Render unsaved drafts (working copies) too — yours AND the editor\'s. Off by default (saved content only). Signed into the token, so a draft link needs its own mint. Use this for your own iteration loop; use a plain link when the user wants to see exactly what a deploy would ship.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/working-copy.js

@@ -0,0 +1,69 @@
+// Draft-layer (working copy) tools — the explicit-save half of the buffer
+// model. Every content write on this platform (yours, other agents', the
+// human editor's) lands in a per-doc DRAFT; deploys and default previews
+// see saved content only. These tools read, save, and discard that draft:
+//
+//   edits (update_page / block tools / …)  →  unsaved draft
+//   get_preview_link include_working_copy  →  look at the draft
+//   commit_working_copy                    →  SAVE (same op as the editor's
+//                                              Save button)
+//   discard_working_copy                   →  throw the draft away
+//
+// The portal editor shows any agent-written draft as "Unsaved changes", so
+// the human can also Save or Discard it from the UI.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+const wcTargetSchema = z.object({
+    kind: z.enum(['page', 'partial', 'item']),
+    id: z.string(),
+    collection: z.string().optional().describe('Required when kind="item": the collection name.'),
+}).describe('Which doc\'s draft: page {id}, partial {id}, or collection item ({collection} + {id}). Templates/item templates have no drafts (their writes apply directly).');
+function wcPath(t) {
+    if (t.kind === 'item') {
+        if (!t.collection)
+            throw new Error('collection is required when kind="item"');
+        return `working-copy/item/${encodeURIComponent(t.collection)}/${encodeURIComponent(t.id)}`;
+    }
+    return `working-copy/${t.kind}/${encodeURIComponent(t.id)}`;
+}
+export const workingCopyTools = [
+    {
+        name: 'read_working_copy',
+        description: 'Read a doc\'s unsaved draft (working copy) as a raw field diff — { working_copy: null } means everything is saved. read_page/get_page_blocks already return the draft VIEW; use this when you need to know exactly WHICH fields are unsaved, e.g. before discarding (the draft may hold the user\'s in-progress editor work, not just yours).',
+        inputSchema: {
+            target: wcTargetSchema,
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, wcPath(args.target), v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'commit_working_copy',
+        description: 'SAVE a doc\'s unsaved draft: promote it onto the saved doc through the canonical write path (revision snapshot, SEO transform, redirect hygiene) and delete the draft. Identical to the Save button in the portal editor. Returns { committed, seo_warnings, auto_redirects, retired_redirects }. Never changes publish status. Deploys only ship saved content, so commit before trigger_deploy. Equivalent shortcut: save:true on the write tools.',
+        inputSchema: {
+            target: wcTargetSchema,
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, wcPath(args.target), {}, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'discard_working_copy',
+        description: 'Throw away a doc\'s unsaved draft — the saved doc is untouched. Use when the user rejects the previewed change. CAUTION: the draft is shared with the human editor; read_working_copy first if you\'re not sure whose edits are in it.',
+        inputSchema: {
+            target: wcTargetSchema,
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, wcPath(args.target), v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {

package/skills/README.md

@@ -5,6 +5,11 @@ Each one is a self-contained markdown file the agent reads when its
 description matches the user's request. Recipes call MCP tools; the agent
 adapts them to the specific job.
 
+**The buffer model:** every content write is an unsaved per-doc draft until
+explicitly saved (`commit_working_copy` or `save: true` on the write call).
+Deploys ship saved content only — recipes that end in `trigger_deploy` must
+save first.
+
 ## Installation
 
 Copy whichever skills you need into your Claude Code skills directory.

package/skills/tr-blog.md

@@ -5,6 +5,14 @@ description: Use when the user wants to set up a blog, news section, podcast fee
 
 # Set up a blog / news section
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 A blog in Typeroll is a **collection with `item_template_html` + `route_template`**. Every published item materialises as its own static page at build time — there is **no need to call `create_page` per article**. The detail design lives once in `item_template_html`; the listing lives once in a page with a `<!-- typeroll:listing -->` marker that `regenerate_collection_listing` refreshes.
 
 If you find yourself about to create 20 pages for 20 articles, stop — you're using the old pattern. The recipe below is the right one.

package/skills/tr-brand.md

@@ -5,6 +5,14 @@ description: Use when the user asks to create a brand identity, design system, o
 
 # Design a brand identity for a Typeroll site
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 This skill turns a brief (or a reference URL/screenshot) into a complete
 visual design system applied to the site's settings and partials.
 

package/skills/tr-content-write.md

@@ -5,6 +5,14 @@ description: Use when the user asks to write, draft, or rewrite a page on a Type
 
 # Write a page that fits the site
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 The default failure mode for an AI writing a page is "good generic
 HTML in the wrong voice." This skill makes the discovery step
 non-optional.

package/skills/tr-directory.md

@@ -5,6 +5,14 @@ description: Use when the user wants to build a directory site or import a struc
 
 # Build a directory site from external data
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 Typeroll collections support per-item URLs: every published item
 in a collection with a `route_template` materialises as its own static
 page at build time. This is the right pattern when you have hundreds

package/skills/tr-header-footer.md

@@ -5,6 +5,14 @@ description: Vetted, robust header and footer presets to drop into the header/fo
 
 # Header & footer presets
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 Headers and footers are the two partials every page shows, and hand-rolling them
 is where logos get clipped and mobile menus break. **Start from a preset below,
 fill the placeholders, restyle with the site's colours — don't build the layout

package/skills/tr-import-url.md

@@ -5,6 +5,14 @@ description: Use when the user wants to import or migrate content from a non-Wor
 
 # Import content from a non-WordPress site
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 ## When to use this vs tr-migrate-wp
 
 | Source | Use |

package/skills/tr-migrate-astro.md

@@ -5,6 +5,14 @@ description: Use when the user wants to migrate an Astro site — particularly a
 
 # Migrate an Astro site to Typeroll
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 Astro's [Content Collections](https://docs.astro.build/en/guides/content-collections/) and Typeroll's `Collection` + `CollectionItem` map one-to-one. A collection in Astro is a directory of frontmatter-bearing files under `src/content/<name>/`; in Typeroll it's a schema + items doc set under `organizations/{org}/sites/{site}/collections/{name}/`. The Astro schema (`zod.object(...)` in `src/content/config.ts`) is your field list. The frontmatter values are field values. The markdown bodies are richtext fields.
 
 This skill walks the migration from a checked-out Astro repo on the user's machine to a target Typeroll site. You run it locally — the source repo is on disk, the MCP just receives the final shape.

package/skills/tr-migrate-wp.md

@@ -5,6 +5,14 @@ description: Use when the user asks to migrate a WordPress site to Typeroll, men
 
 # Migrate from WordPress to Typeroll
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 The platform's in-portal migration workflow is the "managed" path for
 customers who want one-click. This skill is the "power-user" path: you
 do it locally, mix data sources freely, and the user (consultant /

package/skills/tr-new-site.md

@@ -5,6 +5,14 @@ description: Use when the user wants to create a new Typeroll site from scratch,
 
 # Bootstrap a new Typeroll site
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 Start here when the site already exists as a database record (created via
 the portal UI or API) but has no design, no header/footer, and no pages.
 The goal is to go from blank to a working 4-page site with correct brand

package/skills/tr-redesign-branch.md

@@ -5,6 +5,14 @@ description: Use when the user asks to redesign, modernize, or restructure a Typ
 
 # Redesign a site without breaking the live one
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 Site-wide changes are exactly where copy-on-write branches earn their
 keep. This skill enforces the discipline: every redesign happens on a
 branch, preview-checked end-to-end, merged only after user sign-off.

package/skills/tr-seo.md

@@ -5,6 +5,14 @@ description: Use when the user asks to improve SEO, fix meta tags, add structure
 
 # SEO audit and improvements for a Typeroll site
 
+> **The buffer model (draft writes).** Every content write in this recipe
+> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
+> build work, pass `save: true` on write calls (the work is pre-approved by
+> the task itself), or run `commit_working_copy` per doc before any
+> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
+
+
 ## What Typeroll handles automatically
 
 - `<html lang>` from site `language` setting (per-page override via `language` field)