@typeroll/mcp-server 0.26.2 → 0.27.0

package/AGENTS.md

@@ -238,6 +238,30 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   your own changes. Do NOT `trigger_deploy` merely to preview a content/design
   change — a deploy builds static pages (slow) and only reflects state as of
   that build.
+- **THE BUFFER MODEL — every content write is a draft; saving is always
+  explicit.** All content writes (update_page, replace_page, block tools,
+  update_partial, update_collection_item, batch/bulk tools) land in a
+  per-doc *working copy* — the same draft layer the portal editor
+  autosaves into. Deploys and plain preview links see SAVED content only;
+  your drafts are invisible to them until committed. The loop:
+    1. Edit freely — reads (`read_page`, `get_page_blocks`) return the
+       draft view (plus `has_unsaved_changes`), so chained edits compose.
+    2. Look at it: `get_preview_link` / `get_page_preview` with
+       `include_working_copy: true` (the link flag is signed into the
+       token, so your iteration link needs one mint with the flag).
+    3. SAVE explicitly: `commit_working_copy`, or `save: true` directly on
+       the write call (typical for pre-approved changes and batch sweeps).
+       Commit = the editor's Save button: revision snapshot, SEO
+       transform, redirect hygiene. Rejected → `discard_working_copy`.
+  Exceptions that apply immediately (they are publish state / structure,
+  not content): `status` fields, create/delete, `set_page_mode`,
+  templates, settings, redirects, block-type definitions, media.
+  The human editor shows your drafts as "Unsaved changes" it can Save or
+  Discard; `read_working_copy` shows the raw unsaved diff when you need to
+  know whose edits are in it. Working copies are per-doc scratch; for
+  multi-page efforts branch instead (`create_branch`).
+  **Before `trigger_deploy`: commit.** Deploys build saved content only —
+  an uncommitted draft silently stays behind.
 - **Deploys / `{branch}.{project}.pages.dev` are the STATIC BUILD**, refreshed
   only by `trigger_deploy`. Reach for them when you want the real compiled
   output: publishing, a stakeholder link to the built site, or a faithful

package/README.md

@@ -154,7 +154,14 @@ the full reference + concrete operation recipes.
   own URL at `{branch}.{project}.pages.dev`.
 - **Deploy** — trigger, list, get status.
 - **Preview** — `get_preview_link` (signed URL for browser navigation;
-  supports `page_id`, `slug`, or `collection_name + item_id`).
+  supports `page_id`, `slug`, or `collection_name + item_id`; pass
+  `include_working_copy: true` to also render unsaved drafts).
+- **Drafts (the buffer model)** — every content write lands in a per-doc
+  unsaved draft (working copy); deploys and plain previews see saved
+  content only. Save explicitly with `commit_working_copy` or `save: true`
+  on the write call; inspect/discard with `read_working_copy` /
+  `discard_working_copy`. Status changes and structural operations apply
+  immediately.
 
 ## Direct REST API access