affine-mcp-server 1.12.0 → 2.0.0

package/dist/tools/docs.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
-import { text } from "../util/mcp.js";
+import { generateKeyBetween } from "fractional-indexing";
+import { receipt, text } from "../util/mcp.js";
 import { wsUrlFromGraphQLEndpoint, connectWorkspaceSocket, joinWorkspace, loadDoc, pushDocUpdate, deleteDoc as wsDeleteDoc } from "../ws.js";
 import * as Y from "yjs";
 import { parseMarkdownToOperations } from "../markdown/parse.js";
 import { renderBlocksToMarkdown } from "../markdown/render.js";
+import { DEFAULT_NOTE_XYWH, DEFAULT_STACK_GAP_HORIZONTAL, DEFAULT_STACK_GAP_VERTICAL, SIDE_TO_NORMALIZED_POSITION, encloseBounds, estimateConnectorLabelXYWH, estimateNoteHeightForMarkdown, formatXywhString, parseXywhString, pickConnectorSides, pickFurthestInDirection, sortByFractionalIndex, stackRelativeTo, } from "../edgeless/layout.js";
 const WorkspaceId = z.string().min(1, "workspaceId required");
 const DocId = z.string().min(1, "docId required");
 const MarkdownContent = z.string().min(1, "markdown required");
@@ -55,6 +57,54 @@ const APPEND_BLOCK_BOOKMARK_STYLE_VALUES = [
 const AppendBlockBookmarkStyle = z.enum(APPEND_BLOCK_BOOKMARK_STYLE_VALUES);
 const APPEND_BLOCK_DATA_VIEW_MODE_VALUES = ["table", "kanban"];
 const AppendBlockDataViewMode = z.enum(APPEND_BLOCK_DATA_VIEW_MODE_VALUES);
+const DATABASE_INTENT_VALUES = ["task_board", "issue_tracker"];
+const DatabaseIntent = z.enum(DATABASE_INTENT_VALUES);
+const DATABASE_COLUMN_TYPE_VALUES = ["rich-text", "select", "multi-select", "number", "checkbox", "link", "date"];
+const MARKDOWN_EXPORT_SUPPORTED_FLAVOURS = new Set([
+    "affine:paragraph",
+    "affine:list",
+    "affine:code",
+    "affine:divider",
+    "affine:bookmark",
+    "affine:embed-youtube",
+    "affine:embed-github",
+    "affine:embed-figma",
+    "affine:embed-loom",
+    "affine:embed-iframe",
+    "affine:image",
+    "affine:table",
+    "affine:callout",
+    "affine:note",
+    "affine:page",
+    "affine:surface",
+]);
+const KNOWN_BLOCK_FLAVOURS = new Set([
+    "affine:page",
+    "affine:surface",
+    "affine:paragraph",
+    "affine:list",
+    "affine:code",
+    "affine:divider",
+    "affine:callout",
+    "affine:latex",
+    "affine:table",
+    "affine:bookmark",
+    "affine:image",
+    "affine:attachment",
+    "affine:embed-youtube",
+    "affine:embed-github",
+    "affine:embed-figma",
+    "affine:embed-loom",
+    "affine:embed-html",
+    "affine:embed-linked-doc",
+    "affine:embed-synced-doc",
+    "affine:embed-iframe",
+    "affine:database",
+    "affine:surface-ref",
+    "affine:frame",
+    "affine:edgeless-text",
+    "affine:note",
+]);
 function blockVersion(flavour) {
     switch (flavour) {
         case "affine:page":
@@ -471,6 +521,24 @@ export function registerDocTools(server, gql, defaults) {
         }
         return null;
     }
+    function pruneFromFrameChildElementIds(blocks, deletedIds) {
+        if (deletedIds.length === 0)
+            return;
+        const idSet = new Set(deletedIds);
+        for (const [, value] of blocks) {
+            if (!(value instanceof Y.Map))
+                continue;
+            if (value.get("sys:flavour") !== "affine:frame")
+                continue;
+            const owned = value.get("prop:childElementIds");
+            if (!(owned instanceof Y.Map))
+                continue;
+            for (const id of idSet) {
+                if (owned.has(id))
+                    owned.delete(id);
+            }
+        }
+    }
     function ensureNoteBlock(blocks) {
         const existingNoteId = findBlockIdByFlavour(blocks, "affine:note");
         if (existingNoteId) {
@@ -480,20 +548,29 @@ export function registerDocTools(server, gql, defaults) {
         if (!pageId) {
             throw new Error("Document has no page block; unable to insert content.");
         }
+        // Mirror BlockSuite's createDefaultDoc shape so the editor doesn't re-seed
+        // its own default note alongside ours.
         const noteId = generateId();
         const note = new Y.Map();
         setSysFields(note, noteId, "affine:note");
         note.set("sys:parent", null);
-        note.set("sys:children", new Y.Array());
-        note.set("prop:xywh", "[0,0,800,95]");
+        const noteChildren = new Y.Array();
+        note.set("sys:children", noteChildren);
+        note.set("prop:xywh", DEFAULT_NOTE_XYWH);
         note.set("prop:index", "a0");
         note.set("prop:hidden", false);
         note.set("prop:displayMode", "both");
-        const background = new Y.Map();
-        background.set("light", "#ffffff");
-        background.set("dark", "#252525");
-        note.set("prop:background", background);
+        note.set("prop:background", buildDefaultNoteBackground());
         blocks.set(noteId, note);
+        const paragraphId = generateId();
+        const paragraph = new Y.Map();
+        setSysFields(paragraph, paragraphId, "affine:paragraph");
+        paragraph.set("sys:parent", null);
+        paragraph.set("sys:children", new Y.Array());
+        paragraph.set("prop:type", "text");
+        paragraph.set("prop:text", makeText(""));
+        blocks.set(paragraphId, paragraph);
+        noteChildren.push([paragraphId]);
         const page = blocks.get(pageId);
         let pageChildren = page.get("sys:children");
         if (!(pageChildren instanceof Y.Array)) {
@@ -503,6 +580,12 @@ export function registerDocTools(server, gql, defaults) {
         pageChildren.push([noteId]);
         return noteId;
     }
+    function buildDefaultNoteBackground() {
+        const map = new Y.Map();
+        map.set("light", "#ffffff");
+        map.set("dark", "#252525");
+        return map;
+    }
     function ensureSurfaceBlock(blocks) {
         const existingSurfaceId = findBlockIdByFlavour(blocks, "affine:surface");
         if (existingSurfaceId) {
@@ -786,9 +869,20 @@ export function registerDocTools(server, gql, defaults) {
         const design = parsed.design ?? "";
         const reference = (parsed.reference ?? "").trim();
         const refFlavour = (parsed.refFlavour ?? "").trim();
-        const width = Number.isFinite(parsed.width) ? Math.max(1, Math.floor(parsed.width)) : 100;
-        const height = Number.isFinite(parsed.height) ? Math.max(1, Math.floor(parsed.height)) : 100;
-        const background = (parsed.background ?? "transparent").trim() || "transparent";
+        const x = Number.isFinite(parsed.x) ? Math.floor(parsed.x) : 0;
+        const y = Number.isFinite(parsed.y) ? Math.floor(parsed.y) : 0;
+        const widthProvided = Number.isFinite(parsed.width);
+        const heightProvided = Number.isFinite(parsed.height);
+        const width = widthProvided ? Math.max(1, Math.floor(parsed.width)) : 100;
+        let height = heightProvided ? Math.max(1, Math.floor(parsed.height)) : 100;
+        // Pre-inflate the stored height so stackAfter'd siblings don't overlap the
+        // note before the editor's ResizeObserver corrects it on first render.
+        if (typeInfo.type === "note" && !heightProvided && typeof parsed.markdown === "string" && parsed.markdown.length > 0) {
+            height = Math.max(height, estimateNoteHeightForMarkdown(parsed.markdown, widthProvided ? width : 400));
+        }
+        const background = typeof parsed.background === "string"
+            ? (parsed.background.trim() || "transparent")
+            : (parsed.background && typeof parsed.background === "object" ? parsed.background : "transparent");
         const sourceId = (parsed.sourceId ?? "").trim();
         const name = (parsed.name ?? "attachment").trim() || "attachment";
         const mimeType = (parsed.mimeType ?? "application/octet-stream").trim() || "application/octet-stream";
@@ -812,6 +906,8 @@ export function registerDocTools(server, gql, defaults) {
             design,
             reference,
             refFlavour,
+            x,
+            y,
             width,
             height,
             background,
@@ -834,6 +930,14 @@ export function registerDocTools(server, gql, defaults) {
             tableData,
             deltas: parsed.deltas,
             tableCellDeltas,
+            childElementIds: Array.isArray(parsed.childElementIds) ? parsed.childElementIds : undefined,
+            stackAfter: parsed.stackAfter,
+            padding: Number.isFinite(parsed.padding) ? Math.max(0, Math.floor(parsed.padding)) : undefined,
+            xProvided: Number.isFinite(parsed.x),
+            yProvided: Number.isFinite(parsed.y),
+            widthProvided,
+            heightProvided,
+            markdown: typeof parsed.markdown === "string" ? parsed.markdown : undefined,
         };
         validateNormalizedAppendBlockInput(normalized, parsed);
         return normalized;
@@ -991,6 +1095,28 @@ export function registerDocTools(server, gql, defaults) {
         column.set("hide", hide);
         return column;
     }
+    function replaceSelectColumnOptions(column, options) {
+        let data = column.get("data");
+        if (!(data instanceof Y.Map)) {
+            data = new Y.Map();
+            column.set("data", data);
+        }
+        let rawOptions = data.get("options");
+        if (!(rawOptions instanceof Y.Array)) {
+            rawOptions = new Y.Array();
+            data.set("options", rawOptions);
+        }
+        else if (rawOptions.length > 0) {
+            rawOptions.delete(0, rawOptions.length);
+        }
+        options.forEach((value, index) => {
+            const option = new Y.Map();
+            option.set("id", generateId());
+            option.set("value", value);
+            option.set("color", SELECT_COLORS[index % SELECT_COLORS.length]);
+            rawOptions.push([option]);
+        });
+    }
     function createDatabaseColumnDefinition(input) {
         const column = new Y.Map();
         column.set("id", input.id);
@@ -1012,6 +1138,46 @@ export function registerDocTools(server, gql, defaults) {
         }
         return column;
     }
+    function addDatabaseColumnToBlock(dbBlock, spec) {
+        const columns = dbBlock.get("prop:columns");
+        if (!(columns instanceof Y.Array)) {
+            throw new Error("Database has no columns array");
+        }
+        const currentDefs = readColumnDefs(dbBlock);
+        const existing = currentDefs.find(column => column.name === spec.name);
+        if (existing) {
+            if (existing.type !== spec.type) {
+                throw new Error(`Column '${spec.name}' already exists with type '${existing.type}'`);
+            }
+            return existing.id;
+        }
+        const columnId = generateId();
+        columns.push([createDatabaseColumnDefinition({
+                id: columnId,
+                name: spec.name,
+                type: spec.type,
+                width: spec.width,
+                options: spec.options,
+            })]);
+        const views = dbBlock.get("prop:views");
+        if (views instanceof Y.Array) {
+            views.forEach((view) => {
+                if (!(view instanceof Y.Map)) {
+                    return;
+                }
+                const viewColumns = view.get("columns");
+                if (!(viewColumns instanceof Y.Array)) {
+                    return;
+                }
+                const viewColumn = new Y.Map();
+                viewColumn.set("id", columnId);
+                viewColumn.set("hide", false);
+                viewColumn.set("width", spec.width ?? 200);
+                viewColumns.push([viewColumn]);
+            });
+        }
+        return columnId;
+    }
     function createPresetBackedDataViewBlock(blockId, titleText, viewMode, blockType) {
         const block = new Y.Map();
         setSysFields(block, blockId, "affine:database");
@@ -1098,7 +1264,7 @@ export function registerDocTools(server, gql, defaults) {
                         ? "quote"
                         : "text";
                 block.set("prop:type", blockType);
-                block.set("prop:text", makeText(content));
+                block.set("prop:text", makeText(normalized.deltas ?? content));
                 return { blockId, block, flavour: "affine:paragraph", blockType };
             }
             case "list": {
@@ -1137,7 +1303,7 @@ export function registerDocTools(server, gql, defaults) {
                 textBlock.set("sys:parent", null);
                 textBlock.set("sys:children", new Y.Array());
                 textBlock.set("prop:type", "text");
-                textBlock.set("prop:text", makeText(content));
+                textBlock.set("prop:text", makeText(normalized.deltas ?? content));
                 calloutChildren.push([textBlockId]);
                 block.set("sys:children", calloutChildren);
                 block.set("prop:icon", { type: "emoji", unicode: "💡" });
@@ -1455,10 +1621,15 @@ export function registerDocTools(server, gql, defaults) {
                 block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:title", makeText(content || "Frame"));
-                block.set("prop:background", normalized.background);
-                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                // 'transparent' matches FrameBlockSchema; any other value renders as a
+                // solid fill (the border is separate).
+                block.set("prop:background", normalized.background ?? "transparent");
+                block.set("prop:xywh", `[${normalized.x},${normalized.y},${normalized.width},${normalized.height}]`);
                 block.set("prop:index", "a0");
-                block.set("prop:childElementIds", new Y.Map());
+                const childIds = new Y.Map();
+                for (const id of normalized._frameOwnedIds ?? [])
+                    childIds.set(id, true);
+                block.set("prop:childElementIds", childIds);
                 block.set("prop:presentationIndex", "a0");
                 block.set("prop:lockedBySelf", false);
                 return { blockId, block, flavour: "affine:frame" };
@@ -1466,27 +1637,54 @@ export function registerDocTools(server, gql, defaults) {
             case "edgeless_text": {
                 setSysFields(block, blockId, "affine:edgeless-text");
                 block.set("sys:parent", null);
-                block.set("sys:children", new Y.Array());
-                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                const edgelessTextChildren = new Y.Array();
+                block.set("prop:xywh", `[${normalized.x},${normalized.y},${normalized.width},${normalized.height}]`);
                 block.set("prop:index", "a0");
                 block.set("prop:lockedBySelf", false);
                 block.set("prop:scale", 1);
                 block.set("prop:rotate", 0);
                 block.set("prop:hasMaxWidth", false);
                 block.set("prop:comments", undefined);
-                block.set("prop:color", "black");
+                // Theme-adaptive token so canvas text stays legible in dark mode.
+                block.set("prop:color", "--affine-text-primary-color");
                 block.set("prop:fontFamily", "Inter");
                 block.set("prop:fontStyle", "normal");
                 block.set("prop:fontWeight", "regular");
                 block.set("prop:textAlign", "left");
-                return { blockId, block, flavour: "affine:edgeless-text" };
+                const edgelessTextExtraBlocks = [];
+                if (content) {
+                    const paraId = generateId();
+                    const para = new Y.Map();
+                    setSysFields(para, paraId, "affine:paragraph");
+                    para.set("sys:parent", null);
+                    para.set("sys:children", new Y.Array());
+                    para.set("prop:type", "text");
+                    para.set("prop:text", makeText(normalized.deltas ?? content));
+                    edgelessTextChildren.push([paraId]);
+                    edgelessTextExtraBlocks.push({ blockId: paraId, block: para });
+                }
+                block.set("sys:children", edgelessTextChildren);
+                return { blockId, block, flavour: "affine:edgeless-text", extraBlocks: edgelessTextExtraBlocks };
             }
             case "note": {
                 setSysFields(block, blockId, "affine:note");
                 block.set("sys:parent", null);
-                block.set("sys:children", new Y.Array());
-                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
-                block.set("prop:background", normalized.background);
+                const noteChildren = new Y.Array();
+                block.set("prop:xywh", `[${normalized.x},${normalized.y},${normalized.width},${normalized.height}]`);
+                // BlockSuite reads the adaptive-bg case as a Y.Map; a plain JS object
+                // would serialize to a JSON string and break theme switching.
+                const bg = normalized.background;
+                if (bg && typeof bg === "object" && !Array.isArray(bg) && ("light" in bg || "dark" in bg)) {
+                    const bgMap = new Y.Map();
+                    if (typeof bg.light === "string")
+                        bgMap.set("light", bg.light);
+                    if (typeof bg.dark === "string")
+                        bgMap.set("dark", bg.dark);
+                    block.set("prop:background", bgMap);
+                }
+                else {
+                    block.set("prop:background", bg);
+                }
                 block.set("prop:index", "a0");
                 block.set("prop:lockedBySelf", false);
                 block.set("prop:hidden", false);
@@ -1500,7 +1698,152 @@ export function registerDocTools(server, gql, defaults) {
                 edgeless.set("style", style);
                 block.set("prop:edgeless", edgeless);
                 block.set("prop:comments", undefined);
-                return { blockId, block, flavour: "affine:note" };
+                const noteExtraBlocks = [];
+                if (content) {
+                    const paraId = generateId();
+                    const para = new Y.Map();
+                    setSysFields(para, paraId, "affine:paragraph");
+                    para.set("sys:parent", null);
+                    para.set("sys:children", new Y.Array());
+                    para.set("prop:type", "text");
+                    para.set("prop:text", makeText(normalized.deltas ?? content));
+                    noteChildren.push([paraId]);
+                    noteExtraBlocks.push({ blockId: paraId, block: para });
+                }
+                block.set("sys:children", noteChildren);
+                return { blockId, block, flavour: "affine:note", extraBlocks: noteExtraBlocks };
+            }
+        }
+    }
+    function resolveBlockBoundAsBound(blocks, blockId) {
+        const b = blocks.get(blockId);
+        if (b instanceof Y.Map) {
+            const xywh = parseXywhString(b.get("prop:xywh"));
+            if (xywh)
+                return { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height };
+        }
+        return null;
+    }
+    function resolveEdgelessLayoutHints(blocks, normalized) {
+        const defaultPadding = normalized.padding ?? 40;
+        let placed = false;
+        if (normalized.stackAfter) {
+            const idList = Array.isArray(normalized.stackAfter.blockId)
+                ? normalized.stackAfter.blockId
+                : [normalized.stackAfter.blockId];
+            const direction = normalized.stackAfter.direction ?? "down";
+            const missing = [];
+            const bounds = [];
+            for (const id of idList) {
+                const b = resolveBlockBoundAsBound(blocks, id);
+                if (!b)
+                    missing.push(id);
+                else
+                    bounds.push(b);
+            }
+            const ref = pickFurthestInDirection(bounds, direction);
+            if (!ref) {
+                throw new Error(`stackAfter: no blockIds resolved to xywh. Missing: ${JSON.stringify(missing)}`);
+            }
+            // Gap precedence: explicit `gap` > explicit `padding` > direction default
+            // (horizontal larger because notes are wide-short and tight sideways).
+            const isHorizontal = direction === "left" || direction === "right";
+            const directionDefaultGap = isHorizontal ? DEFAULT_STACK_GAP_HORIZONTAL : DEFAULT_STACK_GAP_VERTICAL;
+            const gap = normalized.stackAfter.gap
+                ?? (normalized.padding !== undefined ? normalized.padding : directionDefaultGap);
+            // Center on the anchor group's orthogonal-axis union; caller x/y wins.
+            const isVertical = direction === "down" || direction === "up";
+            let preserveX;
+            let preserveY;
+            if (normalized.xProvided === true) {
+                preserveX = normalized.x;
+            }
+            else if (isVertical) {
+                const minX = bounds.reduce((m, b) => Math.min(m, b.x), Infinity);
+                const maxX = bounds.reduce((m, b) => Math.max(m, b.x + b.w), -Infinity);
+                preserveX = Math.round((minX + maxX) / 2 - normalized.width / 2);
+            }
+            if (normalized.yProvided === true) {
+                preserveY = normalized.y;
+            }
+            else if (!isVertical) {
+                const minY = bounds.reduce((m, b) => Math.min(m, b.y), Infinity);
+                const maxY = bounds.reduce((m, b) => Math.max(m, b.y + b.h), -Infinity);
+                preserveY = Math.round((minY + maxY) / 2 - normalized.height / 2);
+            }
+            const { x, y } = stackRelativeTo(ref, { w: normalized.width, h: normalized.height }, { direction, gap, preserveX, preserveY });
+            normalized.x = x;
+            normalized.y = y;
+            placed = true;
+        }
+        // prop:childElementIds accepts both surface-element ids and block ids —
+        // that's what the editor writes when you drag a note into a frame.
+        if (normalized.type === "frame" && normalized.childElementIds && normalized.childElementIds.length > 0) {
+            const surfaceCtx = getSurfaceElementsValueMap(blocks, { create: false });
+            const surfaceValueMap = surfaceCtx?.value ?? new Y.Map();
+            const ownedIds = [];
+            const missing = [];
+            const kids = [];
+            for (const id of normalized.childElementIds) {
+                const resolved = resolveChildBound(surfaceValueMap, blocks, id);
+                if (resolved.kind === "missing") {
+                    missing.push(id);
+                }
+                else {
+                    ownedIds.push(id);
+                    if (resolved.bound)
+                        kids.push(resolved.bound);
+                }
+            }
+            if (ownedIds.length === 0) {
+                throw new Error(`None of the ids in childElementIds were found: ${JSON.stringify(missing)}.`);
+            }
+            normalized._frameOwnedIds = ownedIds;
+            normalized._frameMissing = missing;
+            if (!normalized.widthProvided || !normalized.heightProvided || !normalized.xProvided || !normalized.yProvided) {
+                const wrapped = encloseBounds(kids, { padding: defaultPadding, titleBand: 60 });
+                if (wrapped) {
+                    if (!normalized.xProvided)
+                        normalized.x = wrapped.x;
+                    if (!normalized.yProvided)
+                        normalized.y = wrapped.y;
+                    if (!normalized.widthProvided)
+                        normalized.width = wrapped.w;
+                    if (!normalized.heightProvided)
+                        normalized.height = wrapped.h;
+                    placed = true;
+                }
+            }
+        }
+        // Auto-stack-below fallback: avoids dropping new edgeless blocks on top of
+        // the seeded default note at [0,0,…] when the caller gave no placement.
+        const isEdgelessBlock = normalized.type === "frame" ||
+            normalized.type === "note" ||
+            normalized.type === "edgeless_text";
+        if (!placed && isEdgelessBlock && !normalized.yProvided) {
+            const existing = [];
+            for (const [, b] of blocks.entries()) {
+                if (!(b instanceof Y.Map))
+                    continue;
+                const flavour = b.get("sys:flavour");
+                if (flavour !== "affine:note" &&
+                    flavour !== "affine:frame" &&
+                    flavour !== "affine:edgeless-text")
+                    continue;
+                const xywh = parseXywhString(b.get("prop:xywh"));
+                if (!xywh)
+                    continue;
+                existing.push({ x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height });
+            }
+            const ref = pickFurthestInDirection(existing, "down");
+            if (ref) {
+                const { x, y } = stackRelativeTo(ref, { w: normalized.width, h: normalized.height }, {
+                    direction: "down",
+                    gap: defaultPadding,
+                    preserveX: normalized.xProvided === true ? normalized.x : undefined,
+                });
+                normalized.x = x;
+                normalized.y = y;
             }
         }
     }
@@ -1521,6 +1864,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             const prevSV = Y.encodeStateVector(doc);
             const blocks = doc.getMap("blocks");
+            resolveEdgelessLayoutHints(blocks, normalized);
             const context = resolveInsertContext(blocks, normalized);
             const { blockId, block, flavour, blockType, extraBlocks } = createBlock(normalized);
             blocks.set(blockId, block);
@@ -1537,7 +1881,16 @@ export function registerDocTools(server, gql, defaults) {
             }
             const delta = Y.encodeStateAsUpdate(doc, prevSV);
             await pushDocUpdate(socket, workspaceId, normalized.docId, Buffer.from(delta).toString("base64"));
-            return { appended: true, blockId, flavour, blockType, normalizedType: normalized.type, legacyType: normalized.legacyType || null };
+            return {
+                appended: true,
+                blockId,
+                flavour,
+                blockType,
+                normalizedType: normalized.type,
+                legacyType: normalized.legacyType || null,
+                ownedIds: normalized._frameOwnedIds,
+                missing: normalized._frameMissing,
+            };
         }
         finally {
             socket.disconnect();
@@ -1561,6 +1914,7 @@ export function registerDocTools(server, gql, defaults) {
                     type: "heading",
                     text: operation.text,
                     level: operation.level,
+                    deltas: operation.deltas,
                     strict,
                     placement,
                 };
@@ -1570,6 +1924,7 @@ export function registerDocTools(server, gql, defaults) {
                     docId,
                     type: "paragraph",
                     text: operation.text,
+                    deltas: operation.deltas,
                     strict,
                     placement,
                 };
@@ -1579,6 +1934,7 @@ export function registerDocTools(server, gql, defaults) {
                     docId,
                     type: "quote",
                     text: operation.text,
+                    deltas: operation.deltas,
                     strict,
                     placement,
                 };
@@ -1588,6 +1944,7 @@ export function registerDocTools(server, gql, defaults) {
                     docId,
                     type: "callout",
                     text: operation.text,
+                    deltas: operation.deltas,
                     strict,
                     placement,
                 };
@@ -1862,6 +2219,330 @@ export function registerDocTools(server, gql, defaults) {
             blocksById,
         };
     }
+    function collectDocBlockRows(doc) {
+        const blocks = doc.getMap("blocks");
+        const rows = [];
+        for (const [id, raw] of blocks) {
+            if (!(raw instanceof Y.Map)) {
+                continue;
+            }
+            const textValue = asText(raw.get("prop:text"));
+            rows.push({
+                id: String(id),
+                flavour: asStringOrNull(raw.get("sys:flavour")),
+                type: asStringOrNull(raw.get("prop:type")),
+                hasText: textValue.length > 0,
+                hasUrl: asText(raw.get("prop:url")).trim().length > 0,
+                hasSourceId: asText(raw.get("prop:sourceId")).trim().length > 0,
+                childCount: childIdsFrom(raw.get("sys:children")).length,
+            });
+        }
+        return rows;
+    }
+    function summarizeDocFidelity(doc, tagOptionsById = new Map()) {
+        const collected = collectDocForMarkdown(doc, tagOptionsById);
+        const rendered = renderBlocksToMarkdown({
+            rootBlockIds: collected.rootBlockIds,
+            blocksById: collected.blocksById,
+        });
+        const blockRows = collectDocBlockRows(doc);
+        const flavourCounts = {};
+        const unsupportedBlocks = [];
+        const conditionallyRiskyBlocks = [];
+        for (const block of blockRows) {
+            const flavourKey = block.flavour || "unknown";
+            flavourCounts[flavourKey] = (flavourCounts[flavourKey] ?? 0) + 1;
+            if (!block.flavour) {
+                unsupportedBlocks.push({ id: block.id, flavour: null, reason: "Block flavour is missing." });
+                continue;
+            }
+            if (!KNOWN_BLOCK_FLAVOURS.has(block.flavour)) {
+                unsupportedBlocks.push({
+                    id: block.id,
+                    flavour: block.flavour,
+                    reason: "Block flavour is unknown to this MCP build.",
+                });
+                continue;
+            }
+            if (!MARKDOWN_EXPORT_SUPPORTED_FLAVOURS.has(block.flavour)) {
+                unsupportedBlocks.push({
+                    id: block.id,
+                    flavour: block.flavour,
+                    reason: "Markdown export does not have a native renderer for this flavour.",
+                });
+                continue;
+            }
+            if (block.flavour === "affine:image" && !block.hasSourceId) {
+                conditionallyRiskyBlocks.push({
+                    id: block.id,
+                    flavour: block.flavour,
+                    reason: "Image block has no sourceId; markdown export will skip it.",
+                });
+            }
+            if ((block.flavour === "affine:bookmark" ||
+                block.flavour === "affine:embed-youtube" ||
+                block.flavour === "affine:embed-github" ||
+                block.flavour === "affine:embed-figma" ||
+                block.flavour === "affine:embed-loom" ||
+                block.flavour === "affine:embed-iframe") &&
+                !block.hasUrl) {
+                conditionallyRiskyBlocks.push({
+                    id: block.id,
+                    flavour: block.flavour,
+                    reason: "Embed/bookmark block has no URL; markdown export will skip it.",
+                });
+            }
+        }
+        const overallRisk = unsupportedBlocks.length > 0
+            ? "high"
+            : conditionallyRiskyBlocks.length > 0 || rendered.lossy
+                ? "medium"
+                : "low";
+        return {
+            title: collected.title || null,
+            tags: collected.tags,
+            rootBlockIds: collected.rootBlockIds,
+            markdown: rendered.markdown,
+            markdownWarnings: rendered.warnings,
+            markdownLossy: rendered.lossy,
+            flavourCounts,
+            unsupportedBlocks,
+            conditionallyRiskyBlocks,
+            overallRisk,
+            recommendedPath: overallRisk === "low"
+                ? "markdown_export_ok"
+                : overallRisk === "medium"
+                    ? "markdown_export_with_review"
+                    : "prefer_native_read_or_clone",
+            stats: {
+                blockCount: blockRows.length,
+                markdownUnsupportedCount: rendered.stats.unsupportedCount,
+                unsupportedBlockCount: unsupportedBlocks.length,
+                conditionallyRiskyBlockCount: conditionallyRiskyBlocks.length,
+            },
+        };
+    }
+    function truncateTemplatePreview(text, maxLength = 140) {
+        if (text.length <= maxLength) {
+            return text;
+        }
+        return `${text.slice(0, maxLength - 1)}…`;
+    }
+    function substituteTemplateVariables(input, ctx) {
+        return input.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (match, key) => {
+            const value = ctx.variables[key];
+            if (value === undefined) {
+                ctx.unresolvedVariables.add(match);
+                return match;
+            }
+            ctx.replacedVariableCount += 1;
+            return value;
+        });
+    }
+    function remapTemplateString(value, ctx) {
+        const remapped = ctx.blockIdMap.get(value) ?? (value === ctx.sourceDocId ? ctx.targetDocId : value);
+        return substituteTemplateVariables(remapped, ctx);
+    }
+    function cloneNativeTemplateValue(value, ctx, path) {
+        if (typeof value === "string") {
+            return remapTemplateString(value, ctx);
+        }
+        if (typeof value === "number" || typeof value === "boolean" || value === null || value === undefined) {
+            return value;
+        }
+        if (value instanceof Y.Text) {
+            const next = new Y.Text();
+            let offset = 0;
+            value.toDelta().forEach((delta) => {
+                const insert = typeof delta?.insert === "string"
+                    ? substituteTemplateVariables(delta.insert, ctx)
+                    : delta?.insert;
+                const attributes = delta?.attributes ? cloneNativeTemplateValue(delta.attributes, ctx, `${path}.attributes`) : undefined;
+                if (typeof insert === "string") {
+                    next.insert(offset, insert, (attributes && typeof attributes === "object") ? attributes : {});
+                    offset += insert.length;
+                }
+                else if (insert !== undefined) {
+                    const text = String(insert);
+                    next.insert(offset, text, (attributes && typeof attributes === "object") ? attributes : {});
+                    offset += text.length;
+                }
+            });
+            return next;
+        }
+        if (value instanceof Y.Array) {
+            const next = new Y.Array();
+            value.forEach((entry) => {
+                next.push([cloneNativeTemplateValue(entry, ctx, `${path}[]`)]);
+            });
+            return next;
+        }
+        if (value instanceof Y.Map) {
+            const next = new Y.Map();
+            for (const [key, entry] of value) {
+                next.set(String(key), cloneNativeTemplateValue(entry, ctx, `${path}.${String(key)}`));
+            }
+            return next;
+        }
+        if (Array.isArray(value)) {
+            return value.map((entry, index) => cloneNativeTemplateValue(entry, ctx, `${path}[${index}]`));
+        }
+        if (value instanceof Date) {
+            return new Date(value.getTime());
+        }
+        if (value instanceof RegExp) {
+            return new RegExp(value.source, value.flags);
+        }
+        if (typeof value === "object") {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                const next = {};
+                for (const [key, entry] of Object.entries(value)) {
+                    next[key] = cloneNativeTemplateValue(entry, ctx, `${path}.${key}`);
+                }
+                return next;
+            }
+            throw new Error(`Unsupported native template value at ${path}: ${value.constructor?.name || "unknown"}.`);
+        }
+        return value;
+    }
+    function scanNativeTemplateValue(value, path, issues, seen) {
+        if (value === null || value === undefined) {
+            return;
+        }
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return;
+        }
+        if (value instanceof Y.Text) {
+            for (const delta of value.toDelta()) {
+                if (delta?.attributes && typeof delta.attributes === "object") {
+                    scanNativeTemplateValue(delta.attributes, `${path}.attributes`, issues, seen);
+                }
+            }
+            return;
+        }
+        if (value instanceof Y.Array) {
+            if (seen.has(value)) {
+                return;
+            }
+            seen.add(value);
+            let index = 0;
+            value.forEach((entry) => {
+                scanNativeTemplateValue(entry, `${path}[${index}]`, issues, seen);
+                index += 1;
+            });
+            return;
+        }
+        if (value instanceof Y.Map) {
+            if (seen.has(value)) {
+                return;
+            }
+            seen.add(value);
+            for (const [key, entry] of value) {
+                scanNativeTemplateValue(entry, `${path}.${String(key)}`, issues, seen);
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            if (seen.has(value)) {
+                return;
+            }
+            seen.add(value);
+            value.forEach((entry, index) => {
+                scanNativeTemplateValue(entry, `${path}[${index}]`, issues, seen);
+            });
+            return;
+        }
+        if (value instanceof Date || value instanceof RegExp) {
+            return;
+        }
+        if (typeof value === "object") {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                if (seen.has(value)) {
+                    return;
+                }
+                seen.add(value);
+                for (const [key, entry] of Object.entries(value)) {
+                    scanNativeTemplateValue(entry, `${path}.${key}`, issues, seen);
+                }
+                return;
+            }
+            issues.push({
+                path,
+                reason: `Unsupported native template value type: ${value.constructor?.name || "unknown"}.`,
+            });
+        }
+    }
+    function summarizeNativeTemplateStructure(doc, workspaceId, templateDocId, tagLabels, supportIssues) {
+        const meta = doc.getMap("meta");
+        const blocks = doc.getMap("blocks");
+        const pageId = findBlockIdByFlavour(blocks, "affine:page");
+        const surfaceId = findBlockIdByFlavour(blocks, "affine:surface");
+        const noteId = findBlockIdByFlavour(blocks, "affine:note");
+        const visited = new Set();
+        const summaries = [];
+        const rootBlockIds = [];
+        if (pageId) {
+            const pageBlock = findBlockById(blocks, pageId);
+            if (pageBlock) {
+                rootBlockIds.push(...childIdsFrom(pageBlock.get("sys:children")));
+            }
+        }
+        else if (noteId) {
+            rootBlockIds.push(noteId);
+        }
+        if (rootBlockIds.length === 0) {
+            for (const [id] of blocks) {
+                rootBlockIds.push(String(id));
+            }
+        }
+        const visit = (blockId) => {
+            if (visited.has(blockId)) {
+                return;
+            }
+            visited.add(blockId);
+            const block = findBlockById(blocks, blockId);
+            if (!block) {
+                return;
+            }
+            const childIds = childIdsFrom(block.get("sys:children"));
+            const textValue = asText(block.get("prop:text"));
+            summaries.push({
+                id: blockId,
+                parentId: resolveBlockParentId(blocks, blockId),
+                flavour: asStringOrNull(block.get("sys:flavour")),
+                type: asStringOrNull(block.get("prop:type")),
+                textPreview: textValue.length > 0 ? truncateTemplatePreview(textValue) : null,
+                textLength: textValue.length,
+                childIds,
+            });
+            for (const childId of childIds) {
+                visit(childId);
+            }
+        };
+        for (const rootId of rootBlockIds) {
+            visit(rootId);
+        }
+        for (const [id] of blocks) {
+            visit(String(id));
+        }
+        const title = asText(meta.get("title")) || "Untitled";
+        return {
+            workspaceId,
+            templateDocId,
+            title,
+            tags: tagLabels,
+            pageId,
+            surfaceId,
+            noteId,
+            rootBlockIds,
+            blockCount: summaries.length,
+            blocks: summaries,
+            nativeCloneSupported: supportIssues.length === 0,
+            fallbackReasons: supportIssues.map(issue => `${issue.path}: ${issue.reason}`),
+        };
+    }
     async function applyMarkdownOperationsInternal(parsed) {
         const strict = parsed.strict !== false;
         const replaceExisting = parsed.replaceExisting === true;
@@ -1982,30 +2663,26 @@ export function registerDocTools(server, gql, defaults) {
             setSysFields(note, noteId, "affine:note");
             note.set("sys:parent", null);
             note.set("prop:displayMode", "both");
-            note.set("prop:xywh", "[0,0,800,95]");
+            note.set("prop:xywh", DEFAULT_NOTE_XYWH);
             note.set("prop:index", "a0");
             note.set("prop:hidden", false);
-            const background = new Y.Map();
-            background.set("light", "#ffffff");
-            background.set("dark", "#252525");
-            note.set("prop:background", background);
+            note.set("prop:background", buildDefaultNoteBackground());
             const noteChildren = new Y.Array();
             note.set("sys:children", noteChildren);
             blocks.set(noteId, note);
             children.push([noteId]);
-            if (parsed.content) {
-                const paraId = generateId();
-                const para = new Y.Map();
-                setSysFields(para, paraId, "affine:paragraph");
-                para.set("sys:parent", null);
-                para.set("sys:children", new Y.Array());
-                para.set("prop:type", "text");
-                const paragraphText = new Y.Text();
+            const paraId = generateId();
+            const para = new Y.Map();
+            setSysFields(para, paraId, "affine:paragraph");
+            para.set("sys:parent", null);
+            para.set("sys:children", new Y.Array());
+            para.set("prop:type", "text");
+            const paragraphText = new Y.Text();
+            if (parsed.content)
                 paragraphText.insert(0, parsed.content);
-                para.set("prop:text", paragraphText);
-                blocks.set(paraId, para);
-                noteChildren.push([paraId]);
-            }
+            para.set("prop:text", paragraphText);
+            blocks.set(paraId, para);
+            noteChildren.push([paraId]);
             const meta = ydoc.getMap("meta");
             meta.set("id", docId);
             meta.set("title", title);
@@ -2035,62 +2712,443 @@ export function registerDocTools(server, gql, defaults) {
             const wsDelta = Y.encodeStateAsUpdate(wsDoc, prevSV);
             const wsDeltaBase64 = Buffer.from(wsDelta).toString("base64");
             await pushDocUpdate(socket, workspaceId, workspaceId, wsDeltaBase64);
-            return { workspaceId, docId, title };
+            return {
+                workspaceId,
+                docId,
+                title,
+                parentDocId: null,
+                linkedToParent: false,
+                warnings: [],
+            };
         }
         finally {
             socket.disconnect();
         }
     }
-    const listDocsHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId) {
-            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+    async function finalizeDocPlacement(parsed) {
+        const parentDocId = parsed.parentDocId?.trim();
+        if (!parentDocId) {
+            return { parentDocId: null, linkedToParent: false, warnings: [] };
         }
-        const query = `query ListDocs($workspaceId: String!, $first: Int, $offset: Int, $after: String){ workspace(id:$workspaceId){ docs(pagination:{first:$first, offset:$offset, after:$after}){ totalCount pageInfo{ hasNextPage endCursor } edges{ cursor node{ id workspaceId title summary public defaultRole createdAt updatedAt } } } } }`;
-        const data = await gql.request(query, { workspaceId, first: parsed.first, offset: parsed.offset, after: parsed.after });
-        const docs = data.workspace.docs;
-        const tagsByDocId = new Map();
-        const titlesByDocId = new Map();
-        let workspacePageCount = null;
-        let workspacePageIds = null;
-        const deletedDocIds = new Set();
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
-            const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-            const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-            const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-            try {
-                await joinWorkspace(socket, workspaceId);
-                const snapshot = await loadDoc(socket, workspaceId, workspaceId);
-                if (snapshot.missing) {
-                    const wsDoc = new Y.Doc();
-                    Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
-                    const meta = wsDoc.getMap("meta");
-                    const pages = getWorkspacePageEntries(meta);
-                    workspacePageCount = pages.length;
-                    workspacePageIds = new Set(pages.map(page => page.id));
-                    const { byId } = getWorkspaceTagOptionMaps(meta);
-                    for (const page of pages) {
-                        if (page.title) {
-                            titlesByDocId.set(page.id, page.title);
-                        }
-                        const tagEntries = getStringArray(page.tagsArray);
-                        tagsByDocId.set(page.id, resolveTagLabels(tagEntries, byId));
-                    }
-                }
-                const graphEdges = Array.isArray(docs?.edges) ? docs.edges : [];
-                if (workspacePageIds && graphEdges.length > workspacePageIds.size) {
-                    for (const edge of graphEdges) {
-                        const nodeId = edge?.node?.id;
-                        if (typeof nodeId !== "string" || workspacePageIds.has(nodeId)) {
-                            continue;
-                        }
-                        const edgeSnapshot = await loadDoc(socket, workspaceId, nodeId);
-                        const edgeExists = Boolean(edgeSnapshot.missing || edgeSnapshot.state || edgeSnapshot.timestamp);
-                        if (!edgeExists) {
-                            deletedDocIds.add(nodeId);
-                        }
-                    }
-                }
+            await joinWorkspace(socket, parsed.workspaceId);
+            const workspaceSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.workspaceId);
+            if (!workspaceSnapshot.missing) {
+                return {
+                    parentDocId,
+                    linkedToParent: false,
+                    warnings: [`${parsed.context}: workspace metadata could not be loaded to verify parent doc "${parentDocId}". Link it manually.`],
+                };
+            }
+            const workspaceDoc = new Y.Doc();
+            Y.applyUpdate(workspaceDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+            const parentExists = getWorkspacePageEntries(workspaceDoc.getMap("meta")).some(page => page.id === parentDocId);
+            if (!parentExists) {
+                return {
+                    parentDocId,
+                    linkedToParent: false,
+                    warnings: [`${parsed.context}: parent doc "${parentDocId}" was not found in workspace "${parsed.workspaceId}". Doc was left at the workspace root.`],
+                };
+            }
+            try {
+                await appendBlockInternal({
+                    workspaceId: parsed.workspaceId,
+                    docId: parentDocId,
+                    type: "embed_linked_doc",
+                    pageId: parsed.docId,
+                });
+                return { parentDocId, linkedToParent: true, warnings: [] };
+            }
+            catch {
+                return {
+                    parentDocId,
+                    linkedToParent: false,
+                    warnings: [`${parsed.context}: doc created but could not be linked to parent doc "${parentDocId}". Link it manually.`],
+                };
+            }
+        }
+        finally {
+            socket.disconnect();
+        }
+    }
+    function createDocSkeleton(title, docId) {
+        const doc = new Y.Doc();
+        const blocks = doc.getMap("blocks");
+        const pageId = generateId();
+        const page = new Y.Map();
+        setSysFields(page, pageId, "affine:page");
+        const titleText = new Y.Text();
+        titleText.insert(0, title);
+        page.set("prop:title", titleText);
+        page.set("sys:children", new Y.Array());
+        blocks.set(pageId, page);
+        const surfaceId = generateId();
+        const surface = new Y.Map();
+        setSysFields(surface, surfaceId, "affine:surface");
+        surface.set("sys:parent", null);
+        surface.set("sys:children", new Y.Array());
+        const elements = new Y.Map();
+        elements.set("type", "$blocksuite:internal:native$");
+        elements.set("value", new Y.Map());
+        surface.set("prop:elements", elements);
+        blocks.set(surfaceId, surface);
+        page.get("sys:children").push([surfaceId]);
+        const noteId = generateId();
+        const note = new Y.Map();
+        setSysFields(note, noteId, "affine:note");
+        note.set("sys:parent", null);
+        note.set("prop:displayMode", "both");
+        note.set("prop:xywh", DEFAULT_NOTE_XYWH);
+        note.set("prop:index", "a0");
+        note.set("prop:hidden", false);
+        note.set("prop:background", buildDefaultNoteBackground());
+        const skeletonNoteChildren = new Y.Array();
+        note.set("sys:children", skeletonNoteChildren);
+        blocks.set(noteId, note);
+        page.get("sys:children").push([noteId]);
+        const skeletonParaId = generateId();
+        const skeletonPara = new Y.Map();
+        setSysFields(skeletonPara, skeletonParaId, "affine:paragraph");
+        skeletonPara.set("sys:parent", null);
+        skeletonPara.set("sys:children", new Y.Array());
+        skeletonPara.set("prop:type", "text");
+        skeletonPara.set("prop:text", new Y.Text());
+        blocks.set(skeletonParaId, skeletonPara);
+        skeletonNoteChildren.push([skeletonParaId]);
+        const meta = doc.getMap("meta");
+        meta.set("id", docId);
+        meta.set("title", title);
+        meta.set("createDate", Date.now());
+        meta.set("tags", new Y.Array());
+        return { doc, blocks, pageId, surfaceId, noteId };
+    }
+    function makeWorkspacePageEntry(docId, title) {
+        const entry = new Y.Map();
+        entry.set("id", docId);
+        entry.set("title", title);
+        entry.set("createDate", Date.now());
+        entry.set("tags", new Y.Array());
+        return entry;
+    }
+    function defaultSemanticSections(pageType) {
+        switch (pageType) {
+            case "meeting_notes":
+                return [
+                    { title: "Attendees" },
+                    { title: "Agenda" },
+                    { title: "Notes" },
+                    { title: "Action Items" },
+                ];
+            case "project_hub":
+                return [
+                    { title: "Overview" },
+                    { title: "Milestones" },
+                    { title: "Risks" },
+                    { title: "References" },
+                ];
+            case "spec_page":
+                return [
+                    { title: "Context" },
+                    { title: "Goals" },
+                    { title: "Non-Goals" },
+                    { title: "Proposal" },
+                    { title: "Open Questions" },
+                ];
+            case "wiki_page":
+            default:
+                return [
+                    { title: "Summary" },
+                    { title: "Details" },
+                    { title: "Related Resources" },
+                ];
+        }
+    }
+    function normalizeSemanticSections(pageType, sections) {
+        const source = sections?.length ? sections : defaultSemanticSections(pageType ?? "wiki_page");
+        return source.map((section) => ({
+            title: section.title.trim(),
+            paragraphs: section.paragraphs?.map((paragraph) => paragraph.trim()).filter(Boolean),
+            bullets: section.bullets?.map((bullet) => bullet.trim()).filter(Boolean),
+            callouts: section.callouts?.map((callout) => callout.trim()).filter(Boolean),
+        }));
+    }
+    function semanticSectionToAppendInputs(section) {
+        const inputs = [
+            {
+                type: "heading",
+                text: section.title,
+                level: 2,
+            },
+        ];
+        for (const paragraph of section.paragraphs ?? []) {
+            inputs.push({
+                type: "paragraph",
+                text: paragraph,
+            });
+        }
+        for (const bullet of section.bullets ?? []) {
+            inputs.push({
+                type: "list",
+                text: bullet,
+                style: "bulleted",
+            });
+        }
+        for (const callout of section.callouts ?? []) {
+            inputs.push({
+                type: "callout",
+                text: callout,
+            });
+        }
+        return inputs;
+    }
+    function appendNativeBlocks(blocks, parentId, inputs, workspaceId, docId, strict = true, initialPlacement) {
+        const parentBlock = findBlockById(blocks, parentId);
+        if (!parentBlock) {
+            throw new Error(`Target parent block '${parentId}' was not found.`);
+        }
+        let anchorPlacement = initialPlacement ?? { parentId };
+        const blockIds = [];
+        const headingIds = [];
+        for (const input of inputs) {
+            const normalized = normalizeAppendBlockInput({
+                workspaceId,
+                docId,
+                strict,
+                placement: anchorPlacement,
+                ...input,
+            });
+            const context = resolveInsertContext(blocks, normalized);
+            const { blockId, block, extraBlocks } = createBlock(normalized);
+            blocks.set(blockId, block);
+            if (Array.isArray(extraBlocks)) {
+                for (const extra of extraBlocks) {
+                    blocks.set(extra.blockId, extra.block);
+                }
+            }
+            if (context.insertIndex >= context.children.length) {
+                context.children.push([blockId]);
+            }
+            else {
+                context.children.insert(context.insertIndex, [blockId]);
+            }
+            blockIds.push(blockId);
+            if (normalized.type === "heading") {
+                headingIds.push(blockId);
+            }
+            anchorPlacement = { afterBlockId: blockId };
+        }
+        return { blockIds, headingIds };
+    }
+    function isHeadingBlock(block) {
+        return block.get("sys:flavour") === "affine:paragraph" && /^h[1-6]$/.test(String(block.get("prop:type") || ""));
+    }
+    function getHeadingLevel(block) {
+        const type = String(block.get("prop:type") || "");
+        const match = type.match(/^h([1-6])$/);
+        return match ? Number(match[1]) : null;
+    }
+    function normalizedText(value) {
+        return richTextValueToString(value).trim().toLocaleLowerCase();
+    }
+    function findSectionInsertionIndex(blocks, noteId, sectionTitle) {
+        const noteBlock = findBlockById(blocks, noteId);
+        if (!noteBlock) {
+            throw new Error(`Note block '${noteId}' was not found.`);
+        }
+        const children = childIdsFrom(noteBlock.get("sys:children"));
+        const target = normalizedText(sectionTitle);
+        for (let i = 0; i < children.length; i += 1) {
+            const childBlock = findBlockById(blocks, children[i]);
+            if (!childBlock || !isHeadingBlock(childBlock)) {
+                continue;
+            }
+            if (normalizedText(childBlock.get("prop:text")) !== target) {
+                continue;
+            }
+            const targetLevel = getHeadingLevel(childBlock) ?? 2;
+            let endIndex = i + 1;
+            while (endIndex < children.length) {
+                const nextBlock = findBlockById(blocks, children[endIndex]);
+                if (nextBlock && isHeadingBlock(nextBlock)) {
+                    const nextLevel = getHeadingLevel(nextBlock) ?? 2;
+                    if (nextLevel <= targetLevel) {
+                        break;
+                    }
+                }
+                endIndex += 1;
+            }
+            return endIndex;
+        }
+        throw new Error(`Section heading '${sectionTitle}' was not found.`);
+    }
+    async function commitNewDocument(socket, workspaceId, docId, title, doc) {
+        const updateFull = Y.encodeStateAsUpdate(doc);
+        await pushDocUpdate(socket, workspaceId, docId, Buffer.from(updateFull).toString("base64"));
+        const wsDoc = new Y.Doc();
+        const snapshot = await loadDoc(socket, workspaceId, workspaceId);
+        if (snapshot.missing) {
+            Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
+        }
+        const prevSV = Y.encodeStateVector(wsDoc);
+        const wsMeta = wsDoc.getMap("meta");
+        let pages = wsMeta.get("pages");
+        if (!pages) {
+            pages = new Y.Array();
+            wsMeta.set("pages", pages);
+        }
+        pages.push([makeWorkspacePageEntry(docId, title)]);
+        const wsDelta = Y.encodeStateAsUpdate(wsDoc, prevSV);
+        await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString("base64"));
+    }
+    async function createSemanticPageInternal(parsed) {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it or set AFFINE_WORKSPACE_ID.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const docId = generateId();
+            const title = parsed.title || "Untitled";
+            const pageType = parsed.pageType ?? "wiki_page";
+            const sections = normalizeSemanticSections(pageType, parsed.sections);
+            const docShell = createDocSkeleton(title, docId);
+            const { blockIds, headingIds } = appendNativeBlocks(docShell.blocks, docShell.noteId, sections.flatMap(semanticSectionToAppendInputs), workspaceId, docId);
+            await commitNewDocument(socket, workspaceId, docId, title, docShell.doc);
+            let parentLinked = false;
+            const warnings = [];
+            if (parsed.parentDocId) {
+                try {
+                    await appendBlockInternal({
+                        workspaceId,
+                        docId: parsed.parentDocId,
+                        type: "embed_linked_doc",
+                        pageId: docId,
+                    });
+                    parentLinked = true;
+                }
+                catch {
+                    warnings.push(`Semantic page created but could not be linked to parent doc "${parsed.parentDocId}". Link it manually.`);
+                }
+            }
+            return {
+                workspaceId,
+                docId,
+                title,
+                pageType,
+                noteId: docShell.noteId,
+                pageId: docShell.pageId,
+                sectionHeadingIds: headingIds,
+                blockIds,
+                parentLinked,
+                warnings,
+            };
+        }
+        finally {
+            socket.disconnect();
+        }
+    }
+    async function appendSemanticSectionInternal(parsed) {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it or set AFFINE_WORKSPACE_ID.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document ${parsed.docId} was not found in workspace ${workspaceId}.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const noteId = ensureNoteBlock(blocks);
+            const insertionIndex = parsed.afterSectionTitle
+                ? findSectionInsertionIndex(blocks, noteId, parsed.afterSectionTitle)
+                : childIdsFrom(findBlockById(blocks, noteId)?.get("sys:children")).length;
+            const { blockIds, headingIds } = appendNativeBlocks(blocks, noteId, semanticSectionToAppendInputs({
+                title: parsed.sectionTitle,
+                paragraphs: parsed.paragraphs,
+                bullets: parsed.bullets,
+                callouts: parsed.callouts,
+            }), workspaceId, parsed.docId, true, { parentId: noteId, index: insertionIndex });
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
+            return {
+                workspaceId,
+                docId: parsed.docId,
+                noteId,
+                sectionTitle: parsed.sectionTitle,
+                sectionHeadingId: headingIds[0] || blockIds[0],
+                afterSectionTitle: parsed.afterSectionTitle ?? null,
+                blockIds,
+            };
+        }
+        finally {
+            socket.disconnect();
+        }
+    }
+    const listDocsHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const query = `query ListDocs($workspaceId: String!, $first: Int, $offset: Int, $after: String){ workspace(id:$workspaceId){ docs(pagination:{first:$first, offset:$offset, after:$after}){ totalCount pageInfo{ hasNextPage endCursor } edges{ cursor node{ id workspaceId title summary public defaultRole createdAt updatedAt } } } } }`;
+        const data = await gql.request(query, { workspaceId, first: parsed.first, offset: parsed.offset, after: parsed.after });
+        const docs = data.workspace.docs;
+        const tagsByDocId = new Map();
+        const titlesByDocId = new Map();
+        let workspacePageCount = null;
+        let workspacePageIds = null;
+        const deletedDocIds = new Set();
+        try {
+            const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+            const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+            const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+            try {
+                await joinWorkspace(socket, workspaceId);
+                const snapshot = await loadDoc(socket, workspaceId, workspaceId);
+                if (snapshot.missing) {
+                    const wsDoc = new Y.Doc();
+                    Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
+                    const meta = wsDoc.getMap("meta");
+                    const pages = getWorkspacePageEntries(meta);
+                    workspacePageCount = pages.length;
+                    workspacePageIds = new Set(pages.map(page => page.id));
+                    const { byId } = getWorkspaceTagOptionMaps(meta);
+                    for (const page of pages) {
+                        if (page.title) {
+                            titlesByDocId.set(page.id, page.title);
+                        }
+                        const tagEntries = getStringArray(page.tagsArray);
+                        tagsByDocId.set(page.id, resolveTagLabels(tagEntries, byId));
+                    }
+                }
+                const graphEdges = Array.isArray(docs?.edges) ? docs.edges : [];
+                if (workspacePageIds && graphEdges.length > workspacePageIds.size) {
+                    for (const edge of graphEdges) {
+                        const nodeId = edge?.node?.id;
+                        if (typeof nodeId !== "string" || workspacePageIds.has(nodeId)) {
+                            continue;
+                        }
+                        const edgeSnapshot = await loadDoc(socket, workspaceId, nodeId);
+                        // Treat timestamp-only responses as deleted tombstones so list_docs can
+                        // hide stale GraphQL edges after delete_doc eventually converges.
+                        const edgeExists = Boolean(edgeSnapshot.missing || edgeSnapshot.state);
+                        if (!edgeExists) {
+                            deletedDocIds.add(nodeId);
+                        }
+                    }
+                }
             }
             finally {
                 socket.disconnect();
@@ -2717,6 +3775,123 @@ export function registerDocTools(server, gql, defaults) {
             includeMarkdown: z.boolean().optional().describe("If true, includes rendered markdown in the response. Equivalent to also calling export_doc_markdown."),
         },
     }, readDocHandler);
+    const getCapabilitiesHandler = async () => {
+        return text({
+            server: {
+                name: "affine-mcp",
+                capabilityVersion: 1,
+            },
+            docs: {
+                canonicalBlockTypes: [...APPEND_BLOCK_CANONICAL_TYPE_VALUES],
+                legacyBlockAliases: Object.keys(APPEND_BLOCK_LEGACY_ALIAS_MAP),
+                markdownImport: {
+                    supported: true,
+                    lossy: true,
+                    knownLosses: [
+                        "Nested markdown lists are flattened during import.",
+                        "Markdown images are converted into bookmark blocks unless blobs are uploaded separately.",
+                        "HTML blocks are imported as plain paragraph text.",
+                    ],
+                },
+                markdownExport: {
+                    supportedFlavours: [...MARKDOWN_EXPORT_SUPPORTED_FLAVOURS].sort(),
+                    lossyForUnsupportedFlavours: true,
+                    knownUnsupportedFlavours: [...KNOWN_BLOCK_FLAVOURS].filter(flavour => !MARKDOWN_EXPORT_SUPPORTED_FLAVOURS.has(flavour)).sort(),
+                },
+                highLevelAuthoring: {
+                    semanticPageComposer: true,
+                    nativeTemplateInstantiation: true,
+                    createDocWithPlacement: true,
+                    semanticSectionEditing: true,
+                },
+                edgelessCanvas: {
+                    blockMutation: true,
+                    surfaceElementMutation: true,
+                    canvasReadback: true,
+                    frameOwnershipMutation: true,
+                },
+            },
+            database: {
+                supported: true,
+                columnTypes: [...DATABASE_COLUMN_TYPE_VALUES],
+                initialViewModes: [...APPEND_BLOCK_DATA_VIEW_MODE_VALUES],
+                advancedViewMutation: true,
+                intentDrivenComposition: true,
+                linkedDocRows: true,
+            },
+            workspace: {
+                organizeToolsExperimental: true,
+                ruleBackedCollections: true,
+                workspaceBlueprints: true,
+            },
+            collaboration: {
+                docComments: true,
+                repliesListed: true,
+                replyCreation: false,
+                anchoredComments: false,
+                selectionRangeComments: false,
+                sharePolicyManagement: false,
+            },
+            export: {
+                markdown: true,
+                html: false,
+                fidelityReport: true,
+                snapshotBundle: false,
+            },
+        });
+    };
+    server.registerTool("get_capabilities", {
+        title: "Get Capabilities",
+        description: "Return machine-readable capability flags for this MCP server, including block, database, collaboration, and export support.",
+        inputSchema: {},
+    }, getCapabilitiesHandler);
+    const analyzeDocFidelityHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            let tagOptionsById = new Map();
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (workspaceSnapshot.missing) {
+                const workspaceDoc = new Y.Doc();
+                Y.applyUpdate(workspaceDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+                tagOptionsById = getWorkspaceTagOptionMaps(workspaceDoc.getMap("meta")).byId;
+            }
+            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: parsed.docId,
+                    exists: false,
+                    unsupportedBlocks: [],
+                    conditionallyRiskyBlocks: [],
+                });
+            }
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const summary = summarizeDocFidelity(doc, tagOptionsById);
+            return text({
+                docId: parsed.docId,
+                exists: true,
+                ...summary,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("analyze_doc_fidelity", {
+        title: "Analyze Document Fidelity",
+        description: "Inspect a document for markdown export fidelity risk, including unsupported AFFiNE block flavours and risky content paths.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+        },
+    }, analyzeDocFidelityHandler);
     // move_doc: move a doc in the sidebar by removing its embed_linked_doc from the old parent
     // and adding it to the new parent. fromParentDocId is optional — if omitted, only adds to new parent.
     const moveDocHandler = async (parsed) => {
@@ -2784,7 +3959,13 @@ export function registerDocTools(server, gql, defaults) {
                 type: "embed_linked_doc",
                 pageId: parsed.docId,
             });
-            return text({ moved: true, docId: parsed.docId, toParentDocId: parsed.toParentDocId, removedFromParent });
+            return receipt("doc.move", {
+                workspaceId,
+                moved: true,
+                docId: parsed.docId,
+                toParentDocId: parsed.toParentDocId,
+                removedFromParent,
+            });
         }
         finally {
             socket.disconnect();
@@ -2807,9 +3988,13 @@ export function registerDocTools(server, gql, defaults) {
         }
         const mutation = `mutation PublishDoc($workspaceId:String!,$docId:String!,$mode:PublicDocMode){ publishDoc(workspaceId:$workspaceId, docId:$docId, mode:$mode){ id workspaceId public mode } }`;
         const data = await gql.request(mutation, { workspaceId, docId: parsed.docId, mode: parsed.mode });
-        return text(data.publishDoc);
-    };
-    server.registerTool("publish_doc", {
+        return receipt("doc.publish", {
+            workspaceId,
+            docId: parsed.docId,
+            ...data.publishDoc,
+        });
+    };
+    server.registerTool("publish_doc", {
         title: "Publish Document",
         description: "Publish a doc (make public).",
         inputSchema: {
@@ -2825,7 +4010,11 @@ export function registerDocTools(server, gql, defaults) {
         }
         const mutation = `mutation RevokeDoc($workspaceId:String!,$docId:String!){ revokePublicDoc(workspaceId:$workspaceId, docId:$docId){ id workspaceId public } }`;
         const data = await gql.request(mutation, { workspaceId, docId: parsed.docId });
-        return text(data.revokePublicDoc);
+        return receipt("doc.revoke_public", {
+            workspaceId,
+            docId: parsed.docId,
+            ...data.revokePublicDoc,
+        });
     };
     server.registerTool("revoke_doc", {
         title: "Revoke Document",
@@ -2838,45 +4027,128 @@ export function registerDocTools(server, gql, defaults) {
     // CREATE DOC (high-level)
     const createDocHandler = async (parsed) => {
         const created = await createDocInternal(parsed);
-        return text({ docId: created.docId, title: created.title });
+        const placement = await finalizeDocPlacement({
+            workspaceId: created.workspaceId,
+            docId: created.docId,
+            parentDocId: parsed.parentDocId,
+            context: "create_doc",
+        });
+        return receipt("doc.create", {
+            workspaceId: created.workspaceId,
+            docId: created.docId,
+            title: created.title,
+            parentDocId: placement.parentDocId,
+            linkedToParent: placement.linkedToParent,
+            warnings: mergeWarnings(created.warnings ?? [], placement.warnings),
+        });
     };
     server.registerTool('create_doc', {
         title: 'Create Document',
-        description: 'Create a new AFFiNE document with optional content',
+        description: 'Create a new AFFiNE document with optional content. If parentDocId is provided, the new doc is linked into the sidebar tree immediately.',
         inputSchema: {
             workspaceId: z.string().optional(),
             title: z.string().optional(),
             content: z.string().optional(),
+            parentDocId: z.string().optional().describe("Optional parent doc to link the new doc under in the sidebar."),
         },
     }, createDocHandler);
-    // APPEND PARAGRAPH
-    const appendParagraphHandler = async (parsed) => {
-        const result = await appendBlockInternal({
-            workspaceId: parsed.workspaceId,
-            docId: parsed.docId,
-            type: "paragraph",
-            text: parsed.text,
+    const semanticSectionSchema = z.object({
+        title: z.string().min(1).describe("Semantic section title."),
+        paragraphs: z.array(z.string().min(1)).optional().describe("Paragraphs to append under the section heading."),
+        bullets: z.array(z.string().min(1)).optional().describe("Bulleted items to append under the section heading."),
+        callouts: z.array(z.string().min(1)).optional().describe("Callout blocks to append under the section heading."),
+    });
+    const createSemanticPageHandler = async (parsed) => {
+        const created = await createSemanticPageInternal(parsed);
+        return text({
+            workspaceId: created.workspaceId,
+            docId: created.docId,
+            title: created.title,
+            pageType: created.pageType,
+            pageId: created.pageId,
+            noteId: created.noteId,
+            sectionCount: created.sectionHeadingIds.length,
+            sectionHeadingIds: created.sectionHeadingIds,
+            blockIds: created.blockIds,
+            parentLinked: created.parentLinked,
+            warnings: created.warnings,
         });
-        return text({ appended: result.appended, paragraphId: result.blockId });
     };
-    server.registerTool('append_paragraph', {
-        title: 'Append Paragraph',
-        description: 'Append a text paragraph block to a document',
+    server.registerTool("create_semantic_page", {
+        title: "Create Semantic Page",
+        description: "Create an AFFiNE-native page with intentional section structure and native block composition.",
         inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string(),
-            text: z.string(),
+            workspaceId: WorkspaceId.optional(),
+            title: z.string().optional().describe("Page title."),
+            pageType: z.enum(["meeting_notes", "project_hub", "spec_page", "wiki_page"]).optional().describe("Semantic page template to seed default sections."),
+            parentDocId: z.string().optional().describe("Optional parent doc to link the new page under in the sidebar."),
+            sections: z.array(semanticSectionSchema).optional().describe("Optional explicit section structure. If omitted, the page type defaults are used."),
         },
-    }, appendParagraphHandler);
-    const appendBlockHandler = async (parsed) => {
-        const result = await appendBlockInternal(parsed);
+    }, createSemanticPageHandler);
+    const appendSemanticSectionHandler = async (parsed) => {
+        const result = await appendSemanticSectionInternal(parsed);
         return text({
+            workspaceId: result.workspaceId,
+            docId: result.docId,
+            noteId: result.noteId,
+            sectionTitle: result.sectionTitle,
+            sectionHeadingId: result.sectionHeadingId,
+            afterSectionTitle: result.afterSectionTitle,
+            blockIds: result.blockIds,
+            appendedCount: result.blockIds.length,
+        });
+    };
+    server.registerTool("append_semantic_section", {
+        title: "Append Semantic Section",
+        description: "Append a semantic section to an existing AFFiNE document by heading title and native block composition.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+            sectionTitle: z.string().min(1).describe("Heading text for the new semantic section."),
+            afterSectionTitle: z.string().optional().describe("Optional existing section heading to append after."),
+            paragraphs: z.array(z.string().min(1)).optional().describe("Paragraphs to append under the new section."),
+            bullets: z.array(z.string().min(1)).optional().describe("Bulleted items to append under the new section."),
+            callouts: z.array(z.string().min(1)).optional().describe("Callout blocks to append under the new section."),
+        },
+    }, appendSemanticSectionHandler);
+    const appendBlockHandler = async (parsed) => {
+        // Drop `text` when `markdown` is set so markdown-parsed children don't
+        // sit next to a stale one-paragraph echo.
+        const shouldApplyMarkdown = parsed.type === "note" && !!parsed.markdown;
+        const coreParsed = shouldApplyMarkdown ? { ...parsed, text: undefined } : parsed;
+        const result = await appendBlockInternal(coreParsed);
+        let markdownApplied;
+        if (shouldApplyMarkdown && result.appended && result.blockId) {
+            const parsedMd = parseMarkdownToOperations(parsed.markdown);
+            if (parsedMd.operations.length > 0) {
+                const applied = await applyMarkdownOperationsInternal({
+                    workspaceId: parsed.workspaceId || defaults.workspaceId,
+                    docId: parsed.docId,
+                    operations: parsedMd.operations,
+                    strict: parsed.strict,
+                    placement: { parentId: result.blockId },
+                });
+                markdownApplied = {
+                    appendedCount: applied.appendedCount,
+                    skippedCount: applied.skippedCount,
+                    blockIds: applied.blockIds,
+                    warnings: parsedMd.warnings,
+                };
+            }
+        }
+        return receipt("doc.append_block", {
+            workspaceId: parsed.workspaceId || defaults.workspaceId || null,
+            docId: parsed.docId,
             appended: result.appended,
             blockId: result.blockId,
             flavour: result.flavour,
             type: result.blockType || null,
+            blockType: result.blockType || null,
             normalizedType: result.normalizedType,
             legacyType: result.legacyType,
+            ...(result.ownedIds ? { ownedIds: result.ownedIds } : {}),
+            ...(result.missing ? { missing: result.missing } : {}),
+            ...(markdownApplied ? { markdown: markdownApplied } : {}),
         });
     };
     server.registerTool("append_block", {
@@ -2894,9 +4166,19 @@ export function registerDocTools(server, gql, defaults) {
             design: z.string().optional().describe("Design payload for embed_html"),
             reference: z.string().optional().describe("Target id for surface_ref"),
             refFlavour: z.string().optional().describe("Target flavour for surface_ref (e.g. affine:frame)"),
-            width: z.number().int().min(1).max(10000).optional().describe("Width for frame/edgeless_text/note"),
-            height: z.number().int().min(1).max(10000).optional().describe("Height for frame/edgeless_text/note"),
-            background: z.string().optional().describe("Background for frame/note"),
+            x: z.number().int().optional().describe("X position on the edgeless canvas for frame/edgeless_text/note (default 0). Prefer ≥40px between sibling bounds; BlockSuite does not auto-arrange."),
+            y: z.number().int().optional().describe("Y position on the edgeless canvas for frame/edgeless_text/note (default 0)."),
+            width: z.number().int().min(1).max(10000).optional().describe("Width for frame/edgeless_text/note."),
+            height: z.number().int().min(1).max(10000).optional().describe("Height for frame/edgeless_text/note. When `markdown` is set and height is omitted, an over-estimate is computed from the content — AFFiNE's render-time ResizeObserver corrects `prop:xywh` to the true DOM-measured height on first browser open."),
+            background: z.any().optional().describe("Background for frame/note. Frame default 'transparent'. For notes, prefer AFFiNE's adaptive `--affine-note-background-<color>` family — `blue` / `purple` / `yellow` / `green` / `teal` / `red` / `orange` / `magenta` / `grey` / `white` / `black`. For specific per-theme colors, pass a `{light, dark}` hex object like `{light:'#fff', dark:'#252525'}`."),
+            markdown: z.string().optional().describe("When type='note', parse this markdown into heading/paragraph/list/code child blocks inside the note (BlockSuite-native: mirrors what happens when you paste markdown into an edgeless note). Takes precedence over 'text' for note children. Ignored for other block types."),
+            childElementIds: z.array(z.string()).optional().describe("For type='frame' only. The frame's contents. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — BlockSuite's prop:childElementIds holds both, matching what the editor writes when you drag a note into a frame. Dragging the frame drags every owned member. Ids that don't resolve come back under 'missing'. When width/height are omitted the frame is sized to the union of resolvable child bounds + padding + a 30px title band."),
+            stackAfter: z.object({
+                blockId: z.union([z.string(), z.array(z.string())]).describe("Block(s) to stack relative to. String = a single anchor; array = pick whichever is furthest in the stack direction (bottommost for 'down', rightmost for 'right', etc.)."),
+                direction: z.enum(["down", "up", "right", "left"]).optional().describe("Direction (default 'down')"),
+                gap: z.number().int().optional().describe("Gap in px between the anchor and the new block. Default is direction-aware: 80 for left/right, 40 for down/up — mirrors native-flowchart spacing where the flow axis gets more breathing room than the cross axis. Explicit `padding` on the block overrides this default; explicit `gap` wins over both."),
+            }).optional().describe("Layout helper — position this block relative to one or more existing edgeless blocks. Picks the furthest anchor in `direction` for the stack axis, and centers the new block on the anchor group's union on the orthogonal axis (matches how BlockSuite aligns selection-derived blocks; reduces to inherit-anchor-x when widths match). Caller-provided x/y on the orthogonal axis still wins. Works for frame/note/edgeless_text. Example: `stackAfter: { blockId: [f1, f2, f3], gap: 80 }` stacks below whichever column frame ends lowest, centered across all three. Note heights shift at first render (page-root grows with the title, content notes shrink/grow with their children); give extra gap and fix up with `update_edgeless_block` if the down/right chain drifts."),
+            padding: z.number().int().optional().describe("Default padding (px) for `childElementIds` auto-sizing on frames (each side, plus +30px title band) and fallback gap for `stackAfter` (default 40)."),
             sourceId: z.string().optional().describe("Blob source id for image/attachment"),
             name: z.string().optional().describe("Attachment file name"),
             mimeType: z.string().optional().describe("Attachment mime type"),
@@ -3002,8 +4284,86 @@ export function registerDocTools(server, gql, defaults) {
             includeFrontmatter: z.boolean().optional(),
         },
     }, exportDocMarkdownHandler);
+    const exportWithFidelityReportHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            let tagOptionsById = new Map();
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (workspaceSnapshot.missing) {
+                const wsDoc = new Y.Doc();
+                Y.applyUpdate(wsDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+                tagOptionsById = getWorkspaceTagOptionMaps(wsDoc.getMap("meta")).byId;
+            }
+            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: parsed.docId,
+                    exists: false,
+                    markdown: "",
+                    fidelity: {
+                        overallRisk: "high",
+                        recommendedPath: "prefer_native_read_or_clone",
+                        unsupportedBlocks: [],
+                        conditionallyRiskyBlocks: [],
+                    },
+                });
+            }
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const summary = summarizeDocFidelity(doc, tagOptionsById);
+            let markdown = summary.markdown;
+            if (parsed.includeFrontmatter) {
+                const escapedTitle = (summary.title || "Untitled").replace(/\"/g, "\\\"");
+                const frontmatterLines = [
+                    "---",
+                    `docId: \"${parsed.docId}\"`,
+                    `title: \"${escapedTitle}\"`,
+                    "tags:",
+                    ...(summary.tags.length > 0 ? summary.tags.map(tag => `  - \"${tag.replace(/\"/g, "\\\"")}\"`) : ["  -"]),
+                    `lossy: ${summary.markdownLossy ? "true" : "false"}`,
+                    `fidelityRisk: \"${summary.overallRisk}\"`,
+                    "---",
+                ];
+                markdown = `${frontmatterLines.join("\n")}\n\n${markdown}`;
+            }
+            return text({
+                docId: parsed.docId,
+                exists: true,
+                markdown,
+                fidelity: {
+                    overallRisk: summary.overallRisk,
+                    recommendedPath: summary.recommendedPath,
+                    unsupportedBlocks: summary.unsupportedBlocks,
+                    conditionallyRiskyBlocks: summary.conditionallyRiskyBlocks,
+                    markdownWarnings: summary.markdownWarnings,
+                    markdownLossy: summary.markdownLossy,
+                    flavourCounts: summary.flavourCounts,
+                    stats: summary.stats,
+                },
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("export_with_fidelity_report", {
+        title: "Export With Fidelity Report",
+        description: "Export document markdown together with a structured fidelity report that highlights markdown loss risk and unsupported AFFiNE-native content.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+            includeFrontmatter: z.boolean().optional(),
+        },
+    }, exportWithFidelityReportHandler);
     // Core logic for creating a doc from markdown — returns structured data, no MCP envelope.
-    // Used by both createDocFromMarkdownHandler and batchCreateDocsHandler.
+    // Used by createDocFromMarkdownHandler and internal markdown-based flows.
     const createDocFromMarkdownCore = async (parsed) => {
         const parsedMarkdown = parseMarkdownToOperations(parsed.markdown);
         let operations = [...parsedMarkdown.operations];
@@ -3035,36 +4395,23 @@ export function registerDocTools(server, gql, defaults) {
                 strict: parsed.strict,
             });
         }
-        // If parentDocId is provided, embed the new doc into the parent so it
-        // appears in the sidebar as a child instead of being an orphan.
-        let linkedToParent = false;
-        if (parsed.parentDocId) {
-            try {
-                await appendBlockInternal({
-                    workspaceId: created.workspaceId,
-                    docId: parsed.parentDocId,
-                    type: "embed_linked_doc",
-                    pageId: created.docId,
-                });
-                linkedToParent = true;
-            }
-            catch {
-                // Non-fatal: doc was created, just not linked. Warn below.
-            }
-        }
+        const placement = await finalizeDocPlacement({
+            workspaceId: created.workspaceId,
+            docId: created.docId,
+            parentDocId: parsed.parentDocId,
+            context: "create_doc_from_markdown",
+        });
         const applyWarnings = [];
         if (applied.skippedCount > 0) {
             applyWarnings.push(`${applied.skippedCount} markdown block(s) could not be applied to AFFiNE and were skipped.`);
         }
-        if (parsed.parentDocId && !linkedToParent) {
-            applyWarnings.push(`Doc created but could not be linked to parent doc "${parsed.parentDocId}". Link it manually.`);
-        }
         return {
             workspaceId: created.workspaceId,
             docId: created.docId,
             title: created.title,
-            linkedToParent,
-            warnings: mergeWarnings(parsedMarkdown.warnings, applyWarnings),
+            parentDocId: placement.parentDocId,
+            linkedToParent: placement.linkedToParent,
+            warnings: mergeWarnings(parsedMarkdown.warnings, applyWarnings, placement.warnings),
             lossy: parsedMarkdown.lossy || applied.skippedCount > 0,
             stats: {
                 parsedBlocks: parsedMarkdown.operations.length,
@@ -3074,7 +4421,7 @@ export function registerDocTools(server, gql, defaults) {
         };
     };
     const createDocFromMarkdownHandler = async (parsed) => {
-        return text(await createDocFromMarkdownCore(parsed));
+        return receipt("doc.create_from_markdown", await createDocFromMarkdownCore(parsed));
     };
     server.registerTool("create_doc_from_markdown", {
         title: "Create Document From Markdown",
@@ -3087,51 +4434,53 @@ export function registerDocTools(server, gql, defaults) {
             parentDocId: z.string().optional().describe("If provided, the new doc is automatically embedded into this parent doc as a linked child (visible in sidebar)."),
         },
     }, createDocFromMarkdownHandler);
-    // batch_create_docs: create up to 20 docs in one call
-    const batchCreateDocsHandler = async (parsed) => {
+    const createDocFromTemplateCore = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId)
             throw new Error("workspaceId is required.");
-        if (!Array.isArray(parsed.docs) || parsed.docs.length === 0)
-            throw new Error("docs array is required.");
-        if (parsed.docs.length > 20)
-            throw new Error("Maximum 20 docs per batch.");
-        const results = [];
-        for (const item of parsed.docs) {
-            try {
-                const d = await createDocFromMarkdownCore({ workspaceId, title: item.title, markdown: item.markdown });
-                // Link to parent if provided
-                let linkedToParent = false;
-                if (item.parentDocId) {
-                    try {
-                        await appendBlockInternal({ workspaceId, docId: item.parentDocId, type: "embed_linked_doc", pageId: d.docId });
-                        linkedToParent = true;
-                    }
-                    catch {
-                        d.warnings?.push(`Doc created but could not be linked to parent "${item.parentDocId}". Link it manually.`);
-                    }
-                }
-                results.push({ title: d.title, docId: d.docId, linkedToParent, warnings: d.warnings ?? [] });
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const snap = await loadDoc(socket, workspaceId, parsed.templateDocId);
+            if (!snap.missing)
+                throw new Error(`Template doc ${parsed.templateDocId} not found.`);
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
+            const collected = collectDocForMarkdown(doc, new Map());
+            const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
+            let markdown = rendered.markdown;
+            const vars = parsed.variables ?? {};
+            for (const [key, value] of Object.entries(vars)) {
+                const pattern = new RegExp(`\\{\\{\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\}}`, "g");
+                markdown = markdown.replace(pattern, value);
             }
-            catch (err) {
-                results.push({ title: item.title, docId: "", linkedToParent: false, warnings: [`Failed: ${err?.message ?? String(err)}`] });
+            const unfilled = [...markdown.matchAll(/\{\{\s*[\w.-]+\s*\}\}/g)].map(match => match[0]);
+            socket.disconnect();
+            const created = await createDocFromMarkdownCore({ workspaceId, title: parsed.title, markdown, parentDocId: parsed.parentDocId });
+            return {
+                workspaceId,
+                sourceTemplateDocId: parsed.templateDocId,
+                docId: created.docId,
+                title: created.title,
+                parentDocId: created.parentDocId,
+                linkedToParent: created.linkedToParent,
+                cloneMode: "markdown-roundtrip",
+                lossy: Boolean(created.lossy ?? (created.warnings?.length ?? 0) > 0),
+                warnings: created.warnings ?? [],
+                stats: created.stats ?? null,
+                unfilledVariables: unfilled,
+            };
+        }
+        catch (err) {
+            try {
+                socket.disconnect();
             }
+            catch { /* already disconnected */ }
+            throw err;
         }
-        const failed = results.filter(r => !r.docId).length;
-        return text({ created: results.length - failed, failed, results });
     };
-    server.registerTool("batch_create_docs", {
-        title: "Batch Create Documents",
-        description: "Create multiple AFFiNE documents in a single call. Each doc can optionally be linked to a parent (parentDocId) to appear in the sidebar. Max 20 docs per batch.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docs: z.array(z.object({
-                title: z.string().describe("Document title."),
-                markdown: z.string().describe("Markdown content."),
-                parentDocId: z.string().optional().describe("Parent doc ID — if provided, the new doc is embedded under this parent in the sidebar."),
-            })).min(1).max(20).describe("Array of docs to create (max 20)."),
-        },
-    }, batchCreateDocsHandler);
     const appendMarkdownHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId) {
@@ -3148,7 +4497,7 @@ export function registerDocTools(server, gql, defaults) {
         const applyWarnings = applied.skippedCount > 0
             ? [`${applied.skippedCount} markdown block(s) could not be applied to AFFiNE and were skipped.`]
             : [];
-        return text({
+        return receipt("doc.append_markdown", {
             workspaceId,
             docId: parsed.docId,
             appended: applied.appendedCount > 0,
@@ -3198,7 +4547,7 @@ export function registerDocTools(server, gql, defaults) {
         const applyWarnings = applied.skippedCount > 0
             ? [`${applied.skippedCount} markdown block(s) could not be applied to AFFiNE and were skipped.`]
             : [];
-        return text({
+        return receipt("doc.replace_with_markdown", {
             workspaceId,
             docId: parsed.docId,
             replaced: true,
@@ -3255,7 +4604,11 @@ export function registerDocTools(server, gql, defaults) {
             await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString('base64'));
             // delete doc content
             wsDeleteDoc(socket, workspaceId, parsed.docId);
-            return text({ deleted: true });
+            return receipt("doc.delete", {
+                workspaceId,
+                docId: parsed.docId,
+                deleted: true,
+            });
         }
         finally {
             socket.disconnect();
@@ -3266,194 +4619,6 @@ export function registerDocTools(server, gql, defaults) {
         description: 'Delete a document and remove from workspace list',
         inputSchema: { workspaceId: z.string().optional(), docId: z.string() },
     }, deleteDocHandler);
-    // ─── cleanup_orphan_embeds ──────────────────────────────────────────────────
-    const cleanupOrphanEmbedsHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snap.missing)
-                throw new Error(`Doc ${parsed.docId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const blocks = doc.getMap("blocks");
-            const orphans = [];
-            for (const [blockId, raw] of blocks) {
-                if (!(raw instanceof Y.Map))
-                    continue;
-                if (raw.get("sys:flavour") !== "affine:embed-linked-doc")
-                    continue;
-                const targetId = raw.get("prop:pageId");
-                if (typeof targetId !== "string" || !targetId) {
-                    orphans.push({ blockId, targetDocId: targetId ?? "" });
-                    continue;
-                }
-                const targetSnap = await loadDoc(socket, workspaceId, targetId);
-                if (!targetSnap.missing)
-                    orphans.push({ blockId, targetDocId: targetId });
-            }
-            if (parsed.dryRun || orphans.length === 0) {
-                return text({ docId: parsed.docId, dryRun: parsed.dryRun ?? false, orphansFound: orphans.length, orphans });
-            }
-            const prevSV = Y.encodeStateVector(doc);
-            for (const { blockId } of orphans) {
-                for (const [, parentRaw] of blocks) {
-                    if (!(parentRaw instanceof Y.Map))
-                        continue;
-                    const children = parentRaw.get("sys:children");
-                    if (!(children instanceof Y.Array))
-                        continue;
-                    const ids = childIdsFrom(children);
-                    const idx = ids.indexOf(blockId);
-                    if (idx !== -1) {
-                        children.delete(idx, 1);
-                        break;
-                    }
-                }
-                blocks.delete(blockId);
-            }
-            const delta = Y.encodeStateAsUpdate(doc, prevSV);
-            await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-            return text({ docId: parsed.docId, dryRun: false, orphansRemoved: orphans.length, orphans });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("cleanup_orphan_embeds", {
-        title: "Cleanup Orphan Embed Links",
-        description: "Remove embed_linked_doc blocks that point to deleted/non-existent docs. Use dryRun=true to preview without making changes.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The doc to clean up orphan embeds from."),
-            dryRun: z.boolean().optional().describe("If true, only report orphans without deleting (default: false)."),
-        },
-    }, cleanupOrphanEmbedsHandler);
-    // ─── find_and_replace ───────────────────────────────────────────────────────
-    const findAndReplaceHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snap.missing)
-                throw new Error(`Doc ${parsed.docId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const blocks = doc.getMap("blocks");
-            let totalMatches = 0;
-            const matchLog = [];
-            const matchAll = parsed.matchAll !== false;
-            for (const [blockId, raw] of blocks) {
-                if (!(raw instanceof Y.Map))
-                    continue;
-                const flavour = raw.get("sys:flavour");
-                for (const [, val] of raw) {
-                    if (!(val instanceof Y.Text))
-                        continue;
-                    const original = val.toString();
-                    if (!original.includes(parsed.search))
-                        continue;
-                    const replaced = matchAll
-                        ? original.split(parsed.search).join(parsed.replace)
-                        : original.replace(parsed.search, parsed.replace);
-                    const count = matchAll ? original.split(parsed.search).length - 1 : 1;
-                    totalMatches += count;
-                    matchLog.push({ blockId, flavour: flavour ?? "unknown", original, replaced });
-                    if (!parsed.dryRun) {
-                        const prevSV = Y.encodeStateVector(doc);
-                        val.delete(0, val.length);
-                        val.insert(0, replaced);
-                        const delta = Y.encodeStateAsUpdate(doc, prevSV);
-                        await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-                    }
-                }
-            }
-            return text({
-                docId: parsed.docId, search: parsed.search, replace: parsed.replace,
-                dryRun: parsed.dryRun ?? false, totalMatches, blocksAffected: matchLog.length, matches: matchLog,
-            });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("find_and_replace", {
-        title: "Find and Replace in Document",
-        description: "Find and replace text across all Y.Text fields in a document (paragraphs, headings, titles). matchAll defaults to true. Use dryRun=true to preview before applying.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The doc to search in."),
-            search: z.string().min(1).describe("Text to find (must not be empty)."),
-            replace: z.string().describe("Replacement text."),
-            matchAll: z.boolean().optional().describe("Replace all occurrences (default: true)."),
-            dryRun: z.boolean().optional().describe("If true, only report matches without replacing (default: false)."),
-        },
-    }, findAndReplaceHandler);
-    // ─── get_docs_by_tag ────────────────────────────────────────────────────────
-    const getDocsByTagHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
-            if (!wsSnap.missing)
-                return text({ tag: parsed.tag, count: 0, docs: [] });
-            const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
-            const meta = wsDoc.getMap("meta");
-            const { byId, options } = getWorkspaceTagOptionMaps(meta);
-            const q = parsed.tag.toLowerCase();
-            const matchingTagIds = new Set(options.filter(o => o.value.toLowerCase().includes(q)).map(o => o.id));
-            if (matchingTagIds.size === 0) {
-                return text({
-                    tag: parsed.tag,
-                    count: 0,
-                    docs: [],
-                    availableTags: options.map(o => o.value),
-                });
-            }
-            const pages = getWorkspacePageEntries(meta);
-            const baseUrl = (process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '');
-            const matched = pages
-                .map(p => {
-                const rawTagIds = getStringArray(p.tagsArray);
-                return { p, rawTagIds };
-            })
-                .filter(({ rawTagIds }) => rawTagIds.some(tid => matchingTagIds.has(tid)))
-                .map(({ p, rawTagIds }) => ({
-                docId: p.id,
-                title: p.title ?? "Untitled",
-                tags: resolveTagLabels(rawTagIds, byId),
-                url: `${baseUrl}/workspace/${workspaceId}/${p.id}`,
-            }));
-            return text({ tag: parsed.tag, count: matched.length, docs: matched });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("get_docs_by_tag", {
-        title: "Get Documents by Tag",
-        description: "Filter documents by tag name (case-insensitive substring match). Returns matching docs with their full tag list. If no match, also returns availableTags for discoverability.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            tag: z.string().describe("Tag name to filter by (substring match, case-insensitive)."),
-        },
-    }, getDocsByTagHandler);
     // ─── list_workspace_tree ────────────────────────────────────────────────────
     const listWorkspaceTreeHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
@@ -3668,7 +4833,12 @@ export function registerDocTools(server, gql, defaults) {
                 const delta = Y.encodeStateAsUpdate(doc, prevSV);
                 await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
             }
-            return text({ updated: true, docId: parsed.docId, title: newTitle });
+            return receipt("doc.update_title", {
+                workspaceId,
+                updated: true,
+                docId: parsed.docId,
+                title: newTitle,
+            });
         }
         finally {
             socket.disconnect();
@@ -3683,212 +4853,344 @@ export function registerDocTools(server, gql, defaults) {
             title: z.string().describe("New title."),
         },
     }, updateDocTitleHandler);
-    // ─── get_doc_by_title ────────────────────────────────────────────────────────
-    const getDocByTitleHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
+    async function syncRawTagsToDoc(parsed) {
+        if (parsed.tags.length === 0) {
+            return;
+        }
         const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
         const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
-            await joinWorkspace(socket, workspaceId);
-            const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
-            if (!wsSnap.missing)
-                return text({ query: parsed.query, found: false, results: [] });
+            await joinWorkspace(socket, parsed.workspaceId);
+            const workspaceSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.workspaceId);
+            if (!workspaceSnapshot.missing) {
+                throw new Error(`Workspace root document not found for workspace ${parsed.workspaceId}`);
+            }
             const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
-            const q = parsed.query.toLowerCase();
-            const limit = parsed.limit ?? 1;
-            const matches = getWorkspacePageEntries(wsDoc.getMap("meta"))
-                .filter(p => p.title && p.title.toLowerCase().includes(q)).slice(0, limit);
-            if (matches.length === 0)
-                return text({ query: parsed.query, found: false, results: [] });
-            const results = [];
-            for (const match of matches) {
-                const snap = await loadDoc(socket, workspaceId, match.id);
-                if (!snap.missing) {
-                    results.push({ docId: match.id, title: match.title, found: false });
-                    continue;
-                }
-                const doc = new Y.Doc();
-                Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-                const collected = collectDocForMarkdown(doc, new Map());
-                const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
-                results.push({ docId: match.id, title: match.title, found: true, markdown: rendered.markdown,
-                    url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${match.id}` });
+            Y.applyUpdate(wsDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+            const wsPrevSV = Y.encodeStateVector(wsDoc);
+            const wsMeta = wsDoc.getMap("meta");
+            const page = getWorkspacePageEntries(wsMeta).find(entry => entry.id === parsed.docId);
+            if (!page) {
+                throw new Error(`docId ${parsed.docId} is not present in workspace ${parsed.workspaceId}`);
+            }
+            const pageTags = ensureTagArray(page.entry);
+            pageTags.delete(0, pageTags.length);
+            for (const tag of parsed.tags) {
+                pageTags.push([tag]);
+            }
+            const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
+            await pushDocUpdate(socket, parsed.workspaceId, parsed.workspaceId, Buffer.from(wsDelta).toString("base64"));
+            const docSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.docId);
+            if (!docSnapshot.missing) {
+                throw new Error(`Document ${parsed.docId} not found in workspace ${parsed.workspaceId}`);
             }
-            return text({ query: parsed.query, found: results.some(r => r.found), results });
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(docSnapshot.missing, "base64"));
+            const docPrevSV = Y.encodeStateVector(doc);
+            const docMeta = doc.getMap("meta");
+            const docTags = ensureTagArray(docMeta);
+            docTags.delete(0, docTags.length);
+            for (const tag of parsed.tags) {
+                docTags.push([tag]);
+            }
+            const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
+            await pushDocUpdate(socket, parsed.workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
         }
         finally {
             socket.disconnect();
         }
-    };
-    server.registerTool("get_doc_by_title", {
-        title: "Get Document by Title",
-        description: "Find a document by title and return its content as markdown in a single call. Combines search_docs + export_doc_markdown. Returns the first match by default; use limit for multiple.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            query: z.string().describe("Title search query (case-insensitive substring match)."),
-            limit: z.number().optional().describe("Max docs to return with content (default: 1)."),
-        },
-    }, getDocByTitleHandler);
-    // ─── list_backlinks ──────────────────────────────────────────────────────────
-    const listBacklinksHandler = async (parsed) => {
+    }
+    const inspectTemplateStructureHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID.");
+        }
         const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
         const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
             await joinWorkspace(socket, workspaceId);
-            const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
-            if (!wsSnap.missing)
-                return text({ docId: parsed.docId, count: 0, backlinks: [] });
-            const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
-            const pages = getWorkspacePageEntries(wsDoc.getMap("meta"));
-            const titleById = new Map(pages.map(p => [p.id, p.title]));
-            const backlinks = [];
-            for (const page of pages) {
-                if (page.id === parsed.docId)
-                    continue;
-                const snap = await loadDoc(socket, workspaceId, page.id);
-                if (!snap.missing)
-                    continue;
-                const doc = new Y.Doc();
-                Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-                const blocks = doc.getMap("blocks");
-                for (const [, raw] of blocks) {
-                    if (!(raw instanceof Y.Map))
-                        continue;
-                    if (raw.get("sys:flavour") === "affine:embed-linked-doc" && raw.get("prop:pageId") === parsed.docId) {
-                        backlinks.push({ docId: page.id, title: titleById.get(page.id) ?? null,
-                            url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${page.id}` });
-                        break;
-                    }
-                }
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (!workspaceSnapshot.missing) {
+                throw new Error(`Workspace root document not found for workspace ${workspaceId}`);
             }
-            return text({ docId: parsed.docId, count: backlinks.length, backlinks });
+            const workspaceDoc = new Y.Doc();
+            Y.applyUpdate(workspaceDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+            const tagOptionsById = getWorkspaceTagOptionMaps(workspaceDoc.getMap("meta")).byId;
+            const templateSnapshot = await loadDoc(socket, workspaceId, parsed.templateDocId);
+            if (!templateSnapshot.missing) {
+                throw new Error(`Template doc ${parsed.templateDocId} not found.`);
+            }
+            const templateDoc = new Y.Doc();
+            Y.applyUpdate(templateDoc, Buffer.from(templateSnapshot.missing, "base64"));
+            const meta = templateDoc.getMap("meta");
+            const rawTags = getStringArray(getTagArray(meta));
+            const resolvedTags = resolveTagLabels(rawTags, tagOptionsById);
+            const supportIssues = [];
+            scanNativeTemplateValue(meta, "meta", supportIssues, new WeakSet());
+            scanNativeTemplateValue(templateDoc.getMap("blocks"), "blocks", supportIssues, new WeakSet());
+            return text(summarizeNativeTemplateStructure(templateDoc, workspaceId, parsed.templateDocId, resolvedTags, supportIssues));
         }
         finally {
             socket.disconnect();
         }
     };
-    server.registerTool("list_backlinks", {
-        title: "List Document Backlinks",
-        description: "Find all documents that embed-link to a given doc (its parents/references in the sidebar). Scans all docs — may be slow on large workspaces.",
+    server.registerTool("inspect_template_structure", {
+        title: "Inspect Template Structure",
+        description: "Inspect a template doc's native structure, tags, and fallback risk before instantiation.",
         inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The doc to find backlinks for."),
+            workspaceId: WorkspaceId.optional(),
+            templateDocId: z.string().describe("The template doc to inspect."),
         },
-    }, listBacklinksHandler);
-    // ─── duplicate_doc ───────────────────────────────────────────────────────────
-    const duplicateDocHandler = async (parsed) => {
+    }, inspectTemplateStructureHandler);
+    const instantiateTemplateNativeHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID.");
+        }
+        const allowFallback = parsed.allowFallback !== false;
+        const preserveTags = parsed.preserveTags !== false;
         const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
         const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
             await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snap.missing)
-                throw new Error(`Doc ${parsed.docId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const collected = collectDocForMarkdown(doc, new Map());
-            const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
-            const newTitle = (parsed.title ?? `${collected.title || "Untitled"} (copy)`).trim();
-            socket.disconnect();
-            const r = await createDocFromMarkdownHandler({ workspaceId, title: newTitle, markdown: rendered.markdown });
-            const created = JSON.parse(r.content[0].text);
-            let linkedToParent = false;
-            if (parsed.parentDocId && created.docId) {
-                try {
-                    await appendBlockInternal({ workspaceId, docId: parsed.parentDocId, type: "embed_linked_doc", pageId: created.docId });
-                    linkedToParent = true;
-                }
-                catch { /* non-fatal */ }
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (!workspaceSnapshot.missing) {
+                throw new Error(`Workspace root document not found for workspace ${workspaceId}`);
             }
-            return text({ sourceDocId: parsed.docId, docId: created.docId, title: created.title, linkedToParent, warnings: created.warnings ?? [] });
-        }
-        catch (err) {
-            try {
-                socket.disconnect();
+            const workspaceDoc = new Y.Doc();
+            Y.applyUpdate(workspaceDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+            const workspaceMeta = workspaceDoc.getMap("meta");
+            const tagOptionById = getWorkspaceTagOptionMaps(workspaceMeta).byId;
+            const sourcePage = getWorkspacePageEntries(workspaceMeta).find(entry => entry.id === parsed.templateDocId);
+            if (!sourcePage) {
+                throw new Error(`Template doc ${parsed.templateDocId} was not found in workspace ${workspaceId}.`);
             }
-            catch { /* already disconnected */ }
-            throw err;
-        }
-    };
-    server.registerTool("duplicate_doc", {
-        title: "Duplicate Document",
-        description: "Clone a document by copying its markdown content into a new doc. Optionally set a new title and/or parentDocId to place it in the sidebar.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The source doc to duplicate."),
-            title: z.string().optional().describe("Title for the new doc. Defaults to '<original title> (copy)'."),
-            parentDocId: z.string().optional().describe("Parent doc to link the new doc under in the sidebar."),
-        },
-    }, duplicateDocHandler);
-    // ─── create_doc_from_template ───────────────────────────────────────────────
-    const createDocFromTemplateHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.templateDocId);
-            if (!snap.missing)
+            const templateSnapshot = await loadDoc(socket, workspaceId, parsed.templateDocId);
+            if (!templateSnapshot.missing) {
                 throw new Error(`Template doc ${parsed.templateDocId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const collected = collectDocForMarkdown(doc, new Map());
-            const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
-            let markdown = rendered.markdown;
-            const vars = parsed.variables ?? {};
-            for (const [key, value] of Object.entries(vars)) {
-                const pattern = new RegExp(`\\{\\{\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\}}`, "g");
-                markdown = markdown.replace(pattern, value);
             }
-            const unfilled = [...markdown.matchAll(/\{\{\s*[\w.-]+\s*\}\}/g)].map(match => match[0]);
-            socket.disconnect();
-            const result = await createDocFromMarkdownHandler({ workspaceId, title: parsed.title, markdown });
-            const created = JSON.parse(result.content[0].text);
+            const templateDoc = new Y.Doc();
+            Y.applyUpdate(templateDoc, Buffer.from(templateSnapshot.missing, "base64"));
+            const templateMeta = templateDoc.getMap("meta");
+            const templateBlocks = templateDoc.getMap("blocks");
+            const rawTags = getStringArray(sourcePage.tagsArray);
+            const resolvedTags = resolveTagLabels(rawTags, tagOptionById);
+            const supportIssues = [];
+            scanNativeTemplateValue(templateMeta, "meta", supportIssues, new WeakSet());
+            scanNativeTemplateValue(templateBlocks, "blocks", supportIssues, new WeakSet());
+            const nativeSummary = summarizeNativeTemplateStructure(templateDoc, workspaceId, parsed.templateDocId, resolvedTags, supportIssues);
+            const sourceTitle = nativeSummary.title || sourcePage.title || "Untitled";
+            const targetTitle = (parsed.title ?? sourceTitle).trim() || sourceTitle;
+            if (!nativeSummary.nativeCloneSupported) {
+                if (!allowFallback) {
+                    throw new Error(`Native template instantiation is not supported: ${nativeSummary.fallbackReasons.join(" | ")}`);
+                }
+                const created = await createDocFromTemplateCore({
+                    workspaceId,
+                    templateDocId: parsed.templateDocId,
+                    title: targetTitle,
+                    variables: parsed.variables,
+                    parentDocId: parsed.parentDocId,
+                });
+                return text({
+                    ...created,
+                    mode: "markdown_fallback",
+                    nativeCloneSupported: false,
+                    warnings: mergeWarnings(created.warnings ?? [], nativeSummary.fallbackReasons, ["Native template instantiation fell back to markdown materialization."]),
+                });
+            }
+            const created = await createDocInternal({
+                workspaceId,
+                title: targetTitle,
+            });
+            const targetSnapshot = await loadDoc(socket, workspaceId, created.docId);
+            if (!targetSnapshot.missing) {
+                throw new Error(`Created doc ${created.docId} was not found for native template instantiation.`);
+            }
+            const targetDoc = new Y.Doc();
+            Y.applyUpdate(targetDoc, Buffer.from(targetSnapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(targetDoc);
+            const targetMeta = targetDoc.getMap("meta");
+            const targetBlocks = targetDoc.getMap("blocks");
+            const blockIdMap = new Map();
+            for (const [sourceBlockId] of templateBlocks) {
+                blockIdMap.set(String(sourceBlockId), generateId());
+            }
+            const cloneContext = {
+                sourceDocId: parsed.templateDocId,
+                targetDocId: created.docId,
+                blockIdMap,
+                variables: parsed.variables ?? {},
+                unresolvedVariables: new Set(),
+                replacedVariableCount: 0,
+            };
+            for (const [existingBlockId] of targetBlocks) {
+                targetBlocks.delete(String(existingBlockId));
+            }
+            for (const [sourceBlockId, rawBlock] of templateBlocks) {
+                if (!(rawBlock instanceof Y.Map)) {
+                    continue;
+                }
+                const nextBlockId = blockIdMap.get(String(sourceBlockId));
+                const cloned = cloneNativeTemplateValue(rawBlock, cloneContext, `blocks.${String(sourceBlockId)}`);
+                cloned.set("sys:id", nextBlockId);
+                targetBlocks.set(nextBlockId, cloned);
+            }
+            targetMeta.set("id", created.docId);
+            targetMeta.set("title", targetTitle);
+            if (preserveTags) {
+                const targetMetaTags = ensureTagArray(targetMeta);
+                targetMetaTags.delete(0, targetMetaTags.length);
+                for (const tag of rawTags) {
+                    targetMetaTags.push([tag]);
+                }
+            }
+            const pageId = findBlockIdByFlavour(targetBlocks, "affine:page");
+            if (pageId) {
+                const pageBlock = findBlockById(targetBlocks, pageId);
+                if (pageBlock) {
+                    pageBlock.set("prop:title", makeText(targetTitle));
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(targetDoc, prevSV);
+            await pushDocUpdate(socket, workspaceId, created.docId, Buffer.from(delta).toString("base64"));
+            if (preserveTags && rawTags.length > 0) {
+                await syncRawTagsToDoc({
+                    workspaceId,
+                    docId: created.docId,
+                    tags: rawTags,
+                });
+            }
             let linkedToParent = false;
-            if (parsed.parentDocId && created.docId) {
+            const warnings = [];
+            if (parsed.parentDocId) {
                 try {
-                    await appendBlockInternal({ workspaceId, docId: parsed.parentDocId, type: "embed_linked_doc", pageId: created.docId });
+                    await appendBlockInternal({
+                        workspaceId,
+                        docId: parsed.parentDocId,
+                        type: "embed_linked_doc",
+                        pageId: created.docId,
+                    });
                     linkedToParent = true;
                 }
-                catch { /* non-fatal */ }
+                catch (err) {
+                    warnings.push(`Doc created but could not be linked to parent "${parsed.parentDocId}": ${err?.message ?? "unknown error"}`);
+                }
             }
-            return text({ ...created, sourceTemplateDocId: parsed.templateDocId, linkedToParent, unfilledVariables: unfilled });
+            return text({
+                workspaceId,
+                sourceTemplateDocId: parsed.templateDocId,
+                docId: created.docId,
+                title: targetTitle,
+                mode: "native",
+                nativeCloneSupported: true,
+                linkedToParent,
+                preservedTags: preserveTags ? resolvedTags : [],
+                replacedVariableCount: cloneContext.replacedVariableCount,
+                unresolvedVariables: Array.from(cloneContext.unresolvedVariables),
+                warnings,
+                blockCount: nativeSummary.blockCount,
+                rootBlockIds: nativeSummary.rootBlockIds.map(blockId => blockIdMap.get(blockId) ?? blockId),
+            });
         }
-        catch (err) {
-            try {
-                socket.disconnect();
-            }
-            catch { /* already disconnected */ }
-            throw err;
+        finally {
+            socket.disconnect();
         }
     };
-    server.registerTool("create_doc_from_template", {
-        title: "Create Document from Template",
-        description: "Clone a template doc and substitute {{variable}} placeholders. Returns a warning for any unfilled variables. Optionally link to a parent doc in the sidebar.",
+    server.registerTool("instantiate_template_native", {
+        title: "Instantiate Template Natively",
+        description: "Instantiate a template using native AFFiNE block cloning when supported, falling back to markdown materialization only when necessary.",
         inputSchema: {
-            workspaceId: z.string().optional(),
-            templateDocId: z.string().describe("The template doc to clone from."),
-            title: z.string().describe("Title for the new doc."),
-            variables: z.record(z.string(), z.string()).optional().describe("Key-value map of {{variable}} substitutions."),
-            parentDocId: z.string().optional().describe("Parent doc to link the new doc under in the sidebar."),
+            workspaceId: WorkspaceId.optional(),
+            templateDocId: z.string().describe("The template doc to instantiate."),
+            title: z.string().optional().describe("Optional title for the new document. Defaults to the template title."),
+            variables: z.record(z.string(), z.string()).optional().describe("Key-value map of {{variable}} substitutions applied during cloning."),
+            parentDocId: z.string().optional().describe("Optional parent doc to link the instantiated doc under in the sidebar."),
+            allowFallback: z.boolean().optional().describe("If false, fail instead of falling back to markdown materialization when native cloning is unsupported."),
+            preserveTags: z.boolean().optional().describe("If true (default), copy the template's tags onto the instantiated doc."),
         },
-    }, createDocFromTemplateHandler);
+    }, instantiateTemplateNativeHandler);
+    function buildDatabaseIntentPreset(intent) {
+        switch (intent) {
+            case "task_board":
+                return {
+                    title: "Task Board",
+                    viewName: "Task Board",
+                    statusOptions: ["Todo", "In Progress", "Blocked", "Done"],
+                    extraColumns: [
+                        { name: "Type", type: "select", options: ["Task", "Bug", "Chore"], width: 140 },
+                        { name: "Priority", type: "select", options: ["P0", "P1", "P2", "P3"], width: 120 },
+                        { name: "Owner", type: "rich-text", width: 180 },
+                        { name: "Due Date", type: "date", width: 160 },
+                    ],
+                    starterRows: [
+                        {
+                            title: "Define the scope",
+                            Status: "Todo",
+                            Type: "Task",
+                            Priority: "P1",
+                            Owner: "Product",
+                        },
+                        {
+                            title: "Build the first pass",
+                            Status: "In Progress",
+                            Type: "Task",
+                            Priority: "P1",
+                            Owner: "Engineering",
+                        },
+                        {
+                            title: "Review and ship",
+                            Status: "Done",
+                            Type: "Chore",
+                            Priority: "P2",
+                            Owner: "Delivery",
+                        },
+                    ],
+                };
+            case "issue_tracker":
+                return {
+                    title: "Issue Tracker",
+                    viewName: "Issue Tracker",
+                    statusOptions: ["Open", "In Progress", "In Review", "Blocked", "Resolved", "Closed"],
+                    extraColumns: [
+                        { name: "Type", type: "select", options: ["Bug", "Feature", "Task", "Incident"], width: 140 },
+                        { name: "Priority", type: "select", options: ["P0", "P1", "P2", "P3"], width: 120 },
+                        { name: "Assignee", type: "rich-text", width: 180 },
+                        { name: "Due Date", type: "date", width: 160 },
+                    ],
+                    starterRows: [
+                        {
+                            title: "Document reproduction steps",
+                            Status: "Open",
+                            Type: "Bug",
+                            Priority: "P0",
+                            Assignee: "Unassigned",
+                        },
+                        {
+                            title: "Fix the regression",
+                            Status: "In Progress",
+                            Type: "Bug",
+                            Priority: "P1",
+                            Assignee: "Engineering",
+                        },
+                        {
+                            title: "Verify the release candidate",
+                            Status: "Resolved",
+                            Type: "Task",
+                            Priority: "P2",
+                            Assignee: "QA",
+                        },
+                    ],
+                };
+            default: {
+                const exhaustiveCheck = intent;
+                throw new Error(`Unsupported database intent '${exhaustiveCheck}'`);
+            }
+        }
+    }
     /** Read column definitions including select options from a database block */
     function readColumnDefs(dbBlock) {
         const columnsRaw = dbBlock.get("prop:columns");
@@ -4043,6 +5345,36 @@ export function registerDocTools(server, gql, defaults) {
         cellsMap.set(rowBlockId, rowCells);
         return rowCells;
     }
+    function addDatabaseRowToBlock(parsed) {
+        const rowBlockId = generateId();
+        const rowBlock = new Y.Map();
+        setSysFields(rowBlock, rowBlockId, "affine:paragraph");
+        rowBlock.set("sys:parent", parsed.databaseBlockId);
+        rowBlock.set("sys:children", new Y.Array());
+        rowBlock.set("prop:type", "text");
+        if (parsed.linkedDocId) {
+            rowBlock.set("prop:text", makeLinkedDocText(parsed.linkedDocId));
+        }
+        else {
+            const titleValue = resolveDatabaseTitleValue(parsed.cells, parsed.lookup);
+            rowBlock.set("prop:text", makeText(String(titleValue)));
+        }
+        parsed.blocks.set(rowBlockId, rowBlock);
+        const dbChildren = ensureChildrenArray(parsed.dbBlock);
+        dbChildren.push([rowBlockId]);
+        const rowCells = ensureDatabaseRowCells(parsed.cellsMap, rowBlockId);
+        for (const [key, value] of Object.entries(parsed.cells)) {
+            const col = findDatabaseColumn(key, parsed.lookup);
+            if (!col) {
+                if (isTitleAliasKey(key)) {
+                    continue;
+                }
+                throw new Error(`Column '${key}' not found. Available columns: ${availableDatabaseColumns(parsed.lookup)}`);
+            }
+            writeDatabaseCellValue(rowCells, col, value, true);
+        }
+        return rowBlockId;
+    }
     function getDatabaseRowBlock(blocks, dbBlock, databaseBlockId, rowBlockId) {
         const rowBlock = findBlockById(blocks, rowBlockId);
         if (!rowBlock) {
@@ -4465,56 +5797,6 @@ export function registerDocTools(server, gql, defaults) {
             databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
         },
     }, readDatabaseColumnsHandler);
-    const updateDatabaseCellHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required");
-        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
-        try {
-            const rowBlock = getDatabaseRowBlock(ctx.blocks, ctx.dbBlock, parsed.databaseBlockId, parsed.rowBlockId);
-            const rowCells = ensureDatabaseRowCells(ctx.cellsMap, parsed.rowBlockId);
-            const col = findDatabaseColumn(parsed.column, ctx);
-            if (!col) {
-                if (!isTitleAliasKey(parsed.column)) {
-                    throw new Error(`Column '${parsed.column}' not found. Available columns: ${availableDatabaseColumns(ctx)}`);
-                }
-            }
-            else {
-                writeDatabaseCellValue(rowCells, col, parsed.value, parsed.createOption ?? true);
-            }
-            if (parsed.linkedDocId) {
-                rowBlock.set("prop:text", makeLinkedDocText(parsed.linkedDocId));
-            }
-            else if (isTitleAliasKey(parsed.column) || (col && (col.type === "title" || isTitleAliasKey(col.name)))) {
-                rowBlock.set("prop:text", makeText(String(parsed.value ?? "")));
-            }
-            const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
-            await pushDocUpdate(ctx.socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-            return text({
-                updated: true,
-                rowBlockId: parsed.rowBlockId,
-                column: parsed.column,
-                value: parsed.value ?? null,
-            });
-        }
-        finally {
-            ctx.socket.disconnect();
-        }
-    };
-    server.registerTool("update_database_cell", {
-        title: "Update Database Cell",
-        description: "Update a single cell on an existing AFFiNE database row. Use `title` to update the row title shown in Kanban card headers.",
-        inputSchema: {
-            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
-            docId: DocId.describe("Document ID containing the database"),
-            databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
-            rowBlockId: z.string().min(1).describe("Row paragraph block ID"),
-            column: z.string().min(1).describe("Column name or ID. Use `title` for the built-in row title."),
-            value: z.unknown().describe("New cell value"),
-            createOption: z.boolean().optional().describe("For select and multi-select columns, create the option label if it does not exist (default true)"),
-            linkedDocId: z.string().optional().describe("Link this row to an existing doc by ID. Replaces any existing title with a linked doc reference."),
-        },
-    }, updateDatabaseCellHandler);
     const updateDatabaseRowHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId)
@@ -4569,6 +5851,109 @@ export function registerDocTools(server, gql, defaults) {
             linkedDocId: z.string().optional().describe("Link this row to an existing doc by ID. The row will open the linked doc in center peek when clicked."),
         },
     }, updateDatabaseRowHandler);
+    const composeDatabaseFromIntentCore = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required");
+        }
+        const preset = buildDatabaseIntentPreset(parsed.intent);
+        const title = (parsed.title ?? preset.title).trim() || preset.title;
+        const starterRows = Array.isArray(parsed.seedRows) ? parsed.seedRows : preset.starterRows;
+        const creation = await appendBlockInternal({
+            workspaceId,
+            docId: parsed.docId,
+            type: "data_view",
+            viewMode: "kanban",
+            text: title,
+            placement: parsed.placement,
+        });
+        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, creation.blockId);
+        try {
+            const warnings = [];
+            const statusLookup = buildDatabaseColumnLookup(readColumnDefs(ctx.dbBlock));
+            const statusColumn = statusLookup.colByNameLower.get("status");
+            if (statusColumn?.raw instanceof Y.Map) {
+                replaceSelectColumnOptions(statusColumn.raw, preset.statusOptions);
+            }
+            else {
+                warnings.push("Status column was not found after database creation.");
+            }
+            const addedColumnIds = [];
+            for (const columnSpec of preset.extraColumns) {
+                addedColumnIds.push(addDatabaseColumnToBlock(ctx.dbBlock, columnSpec));
+            }
+            const viewEntries = ctx.dbBlock.get("prop:views");
+            if (viewEntries instanceof Y.Array) {
+                const primaryView = viewEntries.get(0);
+                if (primaryView instanceof Y.Map) {
+                    primaryView.set("name", preset.viewName);
+                }
+            }
+            const rowBlockIds = [];
+            for (const rowInput of starterRows) {
+                rowBlockIds.push(addDatabaseRowToBlock({
+                    blocks: ctx.blocks,
+                    dbBlock: ctx.dbBlock,
+                    cellsMap: ctx.cellsMap,
+                    databaseBlockId: creation.blockId,
+                    lookup: buildDatabaseColumnLookup(readColumnDefs(ctx.dbBlock)),
+                    cells: rowInput,
+                }));
+            }
+            const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
+            await pushDocUpdate(ctx.socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
+            const finalLookup = buildDatabaseColumnLookup(readColumnDefs(ctx.dbBlock));
+            const finalViews = readDatabaseViewDefs(ctx.dbBlock, finalLookup);
+            const columnSummary = finalLookup.columnDefs.map(column => ({
+                id: column.id,
+                name: column.name || null,
+                type: column.type,
+                options: column.options,
+            }));
+            return {
+                workspaceId,
+                docId: parsed.docId,
+                intent: parsed.intent,
+                title,
+                databaseBlockId: creation.blockId,
+                primaryViewId: finalViews[0]?.id || null,
+                viewIds: finalViews.map(view => view.id),
+                columnIds: finalLookup.columnDefs.map(column => column.id),
+                rowBlockIds: getDatabaseRowIds(ctx.dbBlock),
+                columns: columnSummary,
+                views: finalViews,
+                warnings: mergeWarnings(warnings),
+                lossy: false,
+                stats: {
+                    columnCount: columnSummary.length,
+                    viewCount: finalViews.length,
+                    rowCount: getDatabaseRowIds(ctx.dbBlock).length,
+                    addedColumnCount: addedColumnIds.length,
+                    seededRowCount: rowBlockIds.length,
+                },
+            };
+        }
+        finally {
+            ctx.socket.disconnect();
+        }
+    };
+    server.registerTool("compose_database_from_intent", {
+        title: "Compose Database From Intent",
+        description: "Create a useful AFFiNE database/data-view from declarative intent. Supports task_board and issue_tracker presets with starter schema, kanban view, and optional starter rows.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID containing the database"),
+            intent: DatabaseIntent.describe("Declarative database intent to compose."),
+            title: z.string().optional().describe("Optional database title. Defaults to the intent preset title."),
+            seedRows: z.array(z.record(z.unknown())).optional().describe("Optional starter rows. If omitted, the preset starter rows are used."),
+            placement: z.object({
+                parentId: z.string().optional(),
+                afterBlockId: z.string().optional(),
+                beforeBlockId: z.string().optional(),
+                index: z.number().int().min(0).optional(),
+            }).optional().describe("Optional insertion target/position"),
+        },
+    }, async (parsed) => text(await composeDatabaseFromIntentCore(parsed)));
     // ADD DATABASE COLUMN
     const addDatabaseColumnHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
@@ -4663,4 +6048,1256 @@ export function registerDocTools(server, gql, defaults) {
             width: z.number().optional().describe("Column width in pixels (default 200)"),
         },
     }, addDatabaseColumnHandler);
+    function resolveSurfaceNewlines(s) {
+        return s.replace(/\\n/g, "\n");
+    }
+    function getSurfaceElementsValueMap(blocks, options) {
+        let surfaceId = findBlockIdByFlavour(blocks, "affine:surface");
+        if (!surfaceId) {
+            if (!options.create)
+                return null;
+            surfaceId = ensureSurfaceBlock(blocks);
+        }
+        const surface = blocks.get(surfaceId);
+        let elements = surface.get("prop:elements");
+        if (!(elements instanceof Y.Map)) {
+            if (!options.create)
+                return null;
+            elements = new Y.Map();
+            elements.set("type", "$blocksuite:internal:native$");
+            elements.set("value", new Y.Map());
+            surface.set("prop:elements", elements);
+        }
+        let value = elements.get("value");
+        if (!(value instanceof Y.Map)) {
+            if (!options.create)
+                return null;
+            value = new Y.Map();
+            elements.set("value", value);
+        }
+        return { surfaceId, value };
+    }
+    function serializeSurfaceElement(elementId, el) {
+        const out = { id: elementId };
+        for (const [k, v] of el.entries()) {
+            if (v instanceof Y.Text) {
+                out[k] = v.toString();
+            }
+            else if (v instanceof Y.Map) {
+                out[k] = v.toJSON();
+            }
+            else if (v instanceof Y.Array) {
+                out[k] = v.toArray();
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        const xywh = parseXywhString(out.xywh);
+        if (xywh)
+            out.bounds = xywh;
+        return out;
+    }
+    function buildShapeElementData(elementId, seed, index, input) {
+        const x = input.x ?? 0;
+        const y = input.y ?? 0;
+        const w = input.width ?? 100;
+        const h = input.height ?? 100;
+        const data = {
+            type: "shape",
+            id: elementId,
+            index,
+            seed,
+            xywh: formatXywhString(x, y, w, h),
+            rotate: 0,
+            shapeType: input.shapeType ?? "rect",
+            shapeStyle: "General",
+            radius: input.radius ?? 0,
+            filled: input.filled ?? true,
+            fillColor: input.fillColor ?? "--affine-palette-shape-yellow",
+            strokeWidth: input.strokeWidth ?? 2,
+            strokeColor: input.strokeColor ?? "--affine-palette-line-yellow",
+            strokeStyle: input.strokeStyle ?? "solid",
+            roughness: 1.4,
+            // Fixed #000000 matches BlockSuite's shape tool: shape fills don't
+            // theme-adapt, so label color stays pinned too. Override for dark fills.
+            color: input.color ?? "#000000",
+            fontFamily: "blocksuite:surface:Inter",
+            fontSize: input.fontSize ?? 20,
+            fontStyle: "normal",
+            fontWeight: input.fontWeight ?? "600",
+            textAlign: "center",
+            textHorizontalAlign: "center",
+            textVerticalAlign: "center",
+            textResizing: 1,
+            maxWidth: false,
+            padding: [10, 20],
+            shadow: null,
+        };
+        if (input.text) {
+            const yText = new Y.Text();
+            yText.insert(0, resolveSurfaceNewlines(input.text));
+            data.text = yText;
+        }
+        return data;
+    }
+    function resolveConnectorEndpointBoundAsBound(surfaceValueMap, blocks, endpointId) {
+        if (!endpointId)
+            return null;
+        const surfaceEl = surfaceValueMap.get(endpointId);
+        if (surfaceEl instanceof Y.Map) {
+            const xywh = parseXywhString(surfaceEl.get("xywh"));
+            if (xywh)
+                return { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height };
+        }
+        const block = blocks.get(endpointId);
+        if (block instanceof Y.Map) {
+            const xywh = parseXywhString(block.get("prop:xywh"));
+            if (xywh)
+                return { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height };
+        }
+        return null;
+    }
+    function resolveChildBound(surfaceValueMap, blocks, id) {
+        const surfaceEl = surfaceValueMap.get(id);
+        if (surfaceEl instanceof Y.Map) {
+            const xywh = parseXywhString(surfaceEl.get("xywh"));
+            return {
+                kind: "surface",
+                bound: xywh ? { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height } : null,
+            };
+        }
+        const block = blocks.get(id);
+        if (block instanceof Y.Map) {
+            const xywh = parseXywhString(block.get("prop:xywh"));
+            return {
+                kind: "block",
+                bound: xywh ? { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height } : null,
+            };
+        }
+        return { kind: "missing", bound: null };
+    }
+    function resolveConnectorEndpointCenter(surfaceValueMap, blocks, endpointId, endpointPosition) {
+        if (endpointPosition && Array.isArray(endpointPosition) && endpointPosition.length === 2) {
+            return { x: endpointPosition[0], y: endpointPosition[1] };
+        }
+        if (!endpointId)
+            return null;
+        const surfaceEl = surfaceValueMap.get(endpointId);
+        if (surfaceEl instanceof Y.Map) {
+            const xywh = parseXywhString(surfaceEl.get("xywh"));
+            if (xywh)
+                return { x: xywh.x + xywh.width / 2, y: xywh.y + xywh.height / 2 };
+        }
+        const block = blocks.get(endpointId);
+        if (block instanceof Y.Map) {
+            const xywh = parseXywhString(block.get("prop:xywh"));
+            if (xywh)
+                return { x: xywh.x + xywh.width / 2, y: xywh.y + xywh.height / 2 };
+        }
+        return null;
+    }
+    function buildConnectorElementData(elementId, seed, index, input) {
+        const source = {};
+        if (input.sourceId) {
+            source.id = input.sourceId;
+            if (input.sourcePosition)
+                source.position = input.sourcePosition;
+        }
+        else if (input.sourcePosition) {
+            source.position = input.sourcePosition;
+        }
+        const target = {};
+        if (input.targetId) {
+            target.id = input.targetId;
+            if (input.targetPosition)
+                target.position = input.targetPosition;
+        }
+        else if (input.targetPosition) {
+            target.position = input.targetPosition;
+        }
+        const data = {
+            type: "connector",
+            id: elementId,
+            index,
+            seed,
+            mode: input.mode ?? 2,
+            // Theme-adaptive token so connectors stay legible in dark mode.
+            stroke: input.stroke ?? "--affine-text-primary-color",
+            strokeWidth: input.strokeWidth ?? 2,
+            strokeStyle: input.strokeStyle ?? "solid",
+            roughness: 1.4,
+            frontEndpointStyle: input.frontEndpointStyle ?? "None",
+            rearEndpointStyle: input.rearEndpointStyle ?? "Arrow",
+            source,
+            target,
+            labelDisplay: true,
+            labelOffset: { distance: 0.5, anchor: "center" },
+            labelStyle: {
+                color: "--affine-text-primary-color",
+                fontFamily: "blocksuite:surface:Inter",
+                fontSize: 16,
+                fontStyle: "normal",
+                fontWeight: "400",
+                textAlign: "center",
+            },
+            labelConstraints: { hasMaxWidth: true, maxWidth: 280 },
+        };
+        if (input.label) {
+            const yText = new Y.Text();
+            yText.insert(0, resolveSurfaceNewlines(input.label));
+            data.text = yText;
+        }
+        return data;
+    }
+    function buildTextElementData(elementId, seed, index, input) {
+        const x = input.x ?? 0;
+        const y = input.y ?? 0;
+        const w = input.width ?? 200;
+        const h = input.height ?? 30;
+        const yText = new Y.Text();
+        if (input.text)
+            yText.insert(0, resolveSurfaceNewlines(input.text));
+        return {
+            type: "text",
+            id: elementId,
+            index,
+            seed,
+            xywh: formatXywhString(x, y, w, h),
+            rotate: 0,
+            text: yText,
+            color: input.color ?? "--affine-text-primary-color",
+            fontFamily: "blocksuite:surface:Inter",
+            fontSize: input.fontSize ?? 16,
+            fontStyle: "normal",
+            fontWeight: input.fontWeight ?? "400",
+            textAlign: "center",
+            hasMaxWidth: false,
+        };
+    }
+    function buildGroupElementData(elementId, seed, index, input) {
+        const childMap = new Y.Map();
+        for (const childId of input.children ?? []) {
+            childMap.set(childId, true);
+        }
+        const yTitle = new Y.Text();
+        if (input.title)
+            yTitle.insert(0, input.title);
+        return {
+            type: "group",
+            id: elementId,
+            index,
+            seed,
+            children: childMap,
+            title: yTitle,
+        };
+    }
+    function nextSurfaceElementIndex(valueMap) {
+        let maxIndex = null;
+        for (const [, el] of valueMap.entries()) {
+            if (!(el instanceof Y.Map))
+                continue;
+            const idx = el.get("index");
+            if (typeof idx !== "string")
+                continue;
+            if (maxIndex === null || idx > maxIndex)
+                maxIndex = idx;
+        }
+        return generateKeyBetween(maxIndex, null);
+    }
+    function buildSurfaceElementData(type, index, input) {
+        const elementId = generateId();
+        const seed = Math.floor(Math.random() * 2 ** 31);
+        switch (type) {
+            case "shape":
+                return { elementId, data: buildShapeElementData(elementId, seed, index, input) };
+            case "connector":
+                return { elementId, data: buildConnectorElementData(elementId, seed, index, input) };
+            case "text":
+                return { elementId, data: buildTextElementData(elementId, seed, index, input) };
+            case "group":
+                return { elementId, data: buildGroupElementData(elementId, seed, index, input) };
+        }
+    }
+    function writeSurfaceElement(valueMap, elementId, data) {
+        const el = new Y.Map();
+        for (const [k, v] of Object.entries(data)) {
+            el.set(k, v);
+        }
+        valueMap.set(elementId, el);
+    }
+    const addSurfaceElementHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (snapshot.missing) {
+                Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            }
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: true });
+            const index = params.index ?? nextSurfaceElementIndex(ctx.value);
+            // Mirror updateSurfaceElementHandler: report inapplicable gated fields
+            // in `ignored` instead of silently dropping them at the per-type builder.
+            const ignored = [];
+            for (const [field, applicable] of Object.entries(FIELD_APPLICABILITY)) {
+                if (params[field] === undefined)
+                    continue;
+                if (!applicable.includes(params.type))
+                    ignored.push(field);
+            }
+            const { elementId, data } = buildSurfaceElementData(params.type, index, params);
+            if (params.type === "connector") {
+                const srcBounds = resolveConnectorEndpointBoundAsBound(ctx.value, blocks, params.sourceId);
+                const tgtBounds = resolveConnectorEndpointBoundAsBound(ctx.value, blocks, params.targetId);
+                // Auto-snap to the four tangent-carrying sides when the caller only
+                // supplied ids — the renderer needs tangents to draw arrow heads.
+                if (srcBounds && tgtBounds && !params.sourcePosition && !params.targetPosition) {
+                    const natural = pickConnectorSides(srcBounds, tgtBounds);
+                    data.source = { ...data.source, position: SIDE_TO_NORMALIZED_POSITION[natural.from] };
+                    data.target = { ...data.target, position: SIDE_TO_NORMALIZED_POSITION[natural.to] };
+                }
+                if (params.label) {
+                    const srcCenter = srcBounds
+                        ? { x: srcBounds.x + srcBounds.w / 2, y: srcBounds.y + srcBounds.h / 2 }
+                        : resolveConnectorEndpointCenter(ctx.value, blocks, params.sourceId, params.sourcePosition);
+                    const tgtCenter = tgtBounds
+                        ? { x: tgtBounds.x + tgtBounds.w / 2, y: tgtBounds.y + tgtBounds.h / 2 }
+                        : resolveConnectorEndpointCenter(ctx.value, blocks, params.targetId, params.targetPosition);
+                    const midpoint = srcCenter && tgtCenter
+                        ? { x: (srcCenter.x + tgtCenter.x) / 2, y: (srcCenter.y + tgtCenter.y) / 2 }
+                        : (srcCenter ?? tgtCenter);
+                    data.labelXYWH = estimateConnectorLabelXYWH(params.label, 16, midpoint, 280);
+                }
+            }
+            writeSurfaceElement(ctx.value, elementId, data);
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                added: true,
+                elementId,
+                type: params.type,
+                surfaceBlockId: ctx.surfaceId,
+                ignored,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const listSurfaceElementsHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: params.docId,
+                    exists: false,
+                    surfaceBlockId: null,
+                    count: 0,
+                    elements: [],
+                });
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            if (!ctx) {
+                return text({
+                    docId: params.docId,
+                    exists: true,
+                    surfaceBlockId: null,
+                    count: 0,
+                    elements: [],
+                });
+            }
+            const elements = [];
+            for (const [id, value] of ctx.value.entries()) {
+                const entryId = String(id);
+                if (params.elementId && entryId !== params.elementId)
+                    continue;
+                if (!(value instanceof Y.Map))
+                    continue;
+                const serialized = serializeSurfaceElement(entryId, value);
+                if (params.type && serialized.type !== params.type)
+                    continue;
+                elements.push(serialized);
+            }
+            const sorted = sortByFractionalIndex(elements);
+            return text({
+                docId: params.docId,
+                exists: true,
+                surfaceBlockId: ctx.surfaceId,
+                count: sorted.length,
+                elements: sorted,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    // Also parsed by scripts/verify-surface-element-gating.mjs — adding a styling
+    // field to surfaceElementFieldSchemas without a row here fails that gate.
+    // Per-type rows mirror blocksuite's @field decorators (toeverything/blocksuite@5cb5cb6
+    // packages/affine/model/src/elements/{connector,shape}.ts).
+    const FIELD_APPLICABILITY = {
+        shapeType: ["shape"],
+        radius: ["shape"],
+        filled: ["shape"],
+        fillColor: ["shape"],
+        strokeColor: ["shape"], // connectors use top-level `stroke`
+        strokeWidth: ["shape", "connector"],
+        strokeStyle: ["shape", "connector"],
+        color: ["shape", "text"], // connectors use labelStyle.*
+        fontSize: ["shape", "text"],
+        fontWeight: ["shape", "text"],
+        stroke: ["connector"],
+        mode: ["connector"],
+        frontEndpointStyle: ["connector"],
+        rearEndpointStyle: ["connector"],
+    };
+    const updateSurfaceElementHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            if (!ctx)
+                throw new Error("Document has no surface elements to update.");
+            const el = ctx.value.get(params.elementId);
+            if (!(el instanceof Y.Map)) {
+                throw new Error(`Surface element '${params.elementId}' not found.`);
+            }
+            const elementType = el.get("type");
+            const changed = [];
+            const ignored = [];
+            const geomProvided = params.x !== undefined ||
+                params.y !== undefined ||
+                params.width !== undefined ||
+                params.height !== undefined;
+            if (geomProvided) {
+                if (elementType === "shape" || elementType === "text") {
+                    const current = parseXywhString(el.get("xywh")) ?? {
+                        x: 0,
+                        y: 0,
+                        width: 100,
+                        height: 100,
+                    };
+                    const nx = params.x ?? current.x;
+                    const ny = params.y ?? current.y;
+                    const nw = params.width ?? current.width;
+                    const nh = params.height ?? current.height;
+                    el.set("xywh", formatXywhString(nx, ny, nw, nh));
+                    changed.push("xywh");
+                }
+                else {
+                    if (params.x !== undefined)
+                        ignored.push("x");
+                    if (params.y !== undefined)
+                        ignored.push("y");
+                    if (params.width !== undefined)
+                        ignored.push("width");
+                    if (params.height !== undefined)
+                        ignored.push("height");
+                }
+            }
+            const setYText = (key, value) => {
+                const yText = new Y.Text();
+                yText.insert(0, resolveSurfaceNewlines(value));
+                el.set(key, yText);
+                changed.push(key);
+            };
+            if (params.text !== undefined) {
+                if (elementType === "shape" || elementType === "text" || elementType === "connector") {
+                    setYText("text", params.text);
+                }
+                else {
+                    ignored.push("text");
+                }
+            }
+            if (params.label !== undefined) {
+                if (elementType === "connector") {
+                    setYText("text", params.label);
+                }
+                else {
+                    ignored.push("label");
+                }
+            }
+            if (params.title !== undefined) {
+                if (elementType === "group") {
+                    setYText("title", params.title);
+                }
+                else {
+                    ignored.push("title");
+                }
+            }
+            for (const [field, applicable] of Object.entries(FIELD_APPLICABILITY)) {
+                const key = field;
+                if (params[key] === undefined)
+                    continue;
+                if (applicable.includes(elementType)) {
+                    el.set(field, params[key]);
+                    changed.push(field);
+                }
+                else {
+                    ignored.push(field);
+                }
+            }
+            if (params.index !== undefined) {
+                el.set("index", params.index);
+                changed.push("index");
+            }
+            if (params.sourceId !== undefined || params.sourcePosition !== undefined) {
+                if (elementType === "connector") {
+                    const source = {};
+                    if (params.sourceId)
+                        source.id = params.sourceId;
+                    if (params.sourcePosition)
+                        source.position = params.sourcePosition;
+                    el.set("source", source);
+                    changed.push("source");
+                }
+                else {
+                    if (params.sourceId !== undefined)
+                        ignored.push("sourceId");
+                    if (params.sourcePosition !== undefined)
+                        ignored.push("sourcePosition");
+                }
+            }
+            if (params.targetId !== undefined || params.targetPosition !== undefined) {
+                if (elementType === "connector") {
+                    const target = {};
+                    if (params.targetId)
+                        target.id = params.targetId;
+                    if (params.targetPosition)
+                        target.position = params.targetPosition;
+                    el.set("target", target);
+                    changed.push("target");
+                }
+                else {
+                    if (params.targetId !== undefined)
+                        ignored.push("targetId");
+                    if (params.targetPosition !== undefined)
+                        ignored.push("targetPosition");
+                }
+            }
+            if (params.children !== undefined) {
+                if (elementType === "group") {
+                    const childMap = new Y.Map();
+                    for (const childId of params.children)
+                        childMap.set(childId, true);
+                    el.set("children", childMap);
+                    changed.push("children");
+                }
+                else {
+                    ignored.push("children");
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                updated: changed.length > 0,
+                elementId: params.elementId,
+                type: typeof elementType === "string" ? elementType : null,
+                changed,
+                ignored,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const deleteSurfaceElementHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            if (!ctx) {
+                return text({
+                    deleted: false,
+                    elementId: params.elementId,
+                    reason: "no-surface",
+                    prunedConnectors: [],
+                });
+            }
+            const existing = ctx.value.get(params.elementId);
+            if (!(existing instanceof Y.Map)) {
+                return text({
+                    deleted: false,
+                    elementId: params.elementId,
+                    reason: "not-found",
+                    prunedConnectors: [],
+                });
+            }
+            ctx.value.delete(params.elementId);
+            const prunedConnectors = [];
+            if (params.pruneConnectors) {
+                const toDelete = [];
+                for (const [otherId, otherVal] of ctx.value.entries()) {
+                    if (!(otherVal instanceof Y.Map))
+                        continue;
+                    if (otherVal.get("type") !== "connector")
+                        continue;
+                    const source = otherVal.get("source");
+                    const target = otherVal.get("target");
+                    const srcId = source && typeof source === "object" ? source.id : undefined;
+                    const tgtId = target && typeof target === "object" ? target.id : undefined;
+                    if (srcId === params.elementId || tgtId === params.elementId) {
+                        toDelete.push(String(otherId));
+                    }
+                }
+                for (const id of toDelete) {
+                    ctx.value.delete(id);
+                    prunedConnectors.push(id);
+                }
+            }
+            pruneFromFrameChildElementIds(blocks, [params.elementId, ...prunedConnectors]);
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({ deleted: true, elementId: params.elementId, prunedConnectors });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const updateFrameChildrenHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const frameBlock = blocks.get(params.blockId);
+            if (!(frameBlock instanceof Y.Map) || frameBlock.get("sys:flavour") !== "affine:frame") {
+                throw new Error(`Frame block '${params.blockId}' not found.`);
+            }
+            // All-missing is legit here: it's how callers clear ownership.
+            const surfaceCtx = getSurfaceElementsValueMap(blocks, { create: false });
+            const surfaceValueMap = surfaceCtx?.value ?? new Y.Map();
+            const ownedIds = [];
+            const missing = [];
+            const kids = [];
+            for (const id of params.childElementIds) {
+                const resolved = resolveChildBound(surfaceValueMap, blocks, id);
+                if (resolved.kind === "missing") {
+                    missing.push(id);
+                }
+                else {
+                    ownedIds.push(id);
+                    if (resolved.bound)
+                        kids.push(resolved.bound);
+                }
+            }
+            const childMap = new Y.Map();
+            for (const id of ownedIds)
+                childMap.set(id, true);
+            frameBlock.set("prop:childElementIds", childMap);
+            // Resize-to-fit is default; skip on all-missing so clear-ownership
+            // doesn't collapse the frame to zero.
+            const resize = params.resizeToFit !== false;
+            const padding = Number.isFinite(params.padding)
+                ? Math.max(0, Math.floor(params.padding))
+                : 40;
+            let xywh = null;
+            if (resize && kids.length > 0) {
+                const wrapped = encloseBounds(kids, { padding, titleBand: 60 });
+                if (wrapped) {
+                    xywh = { x: wrapped.x, y: wrapped.y, width: wrapped.w, height: wrapped.h };
+                    frameBlock.set("prop:xywh", formatXywhString(xywh.x, xywh.y, xywh.width, xywh.height));
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                updated: true,
+                blockId: params.blockId,
+                flavour: "affine:frame",
+                ownedIds,
+                missing,
+                resized: xywh !== null,
+                ...(xywh ? { xywh } : {}),
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const updateEdgelessBlockHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const block = blocks.get(params.blockId);
+            if (!(block instanceof Y.Map)) {
+                throw new Error(`Block '${params.blockId}' not found.`);
+            }
+            const flavour = block.get("sys:flavour");
+            if (flavour !== "affine:note" && flavour !== "affine:frame" && flavour !== "affine:edgeless-text") {
+                throw new Error(`Block '${params.blockId}' has flavour '${String(flavour)}' — update_edgeless_block only mutates note/frame/edgeless-text blocks.`);
+            }
+            const changed = [];
+            const ignored = [];
+            if (params.x !== undefined || params.y !== undefined || params.width !== undefined || params.height !== undefined) {
+                const prev = parseXywhString(block.get("prop:xywh")) ?? { x: 0, y: 0, width: 0, height: 0 };
+                block.set("prop:xywh", formatXywhString(params.x ?? prev.x, params.y ?? prev.y, params.width ?? prev.width, params.height ?? prev.height));
+                changed.push("xywh");
+            }
+            if (params.background !== undefined) {
+                if (flavour === "affine:edgeless-text") {
+                    ignored.push("background"); // edgeless-text has no prop:background
+                }
+                else {
+                    const bg = params.background;
+                    if (bg && typeof bg === "object" && !Array.isArray(bg) && ("light" in bg || "dark" in bg)) {
+                        const bgMap = new Y.Map();
+                        if (typeof bg.light === "string")
+                            bgMap.set("light", bg.light);
+                        if (typeof bg.dark === "string")
+                            bgMap.set("dark", bg.dark);
+                        block.set("prop:background", bgMap);
+                    }
+                    else {
+                        block.set("prop:background", bg);
+                    }
+                    changed.push("background");
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({ updated: changed.length > 0, blockId: params.blockId, flavour, changed, ignored });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const deleteBlockHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const block = blocks.get(params.blockId);
+            if (!(block instanceof Y.Map)) {
+                return text({ deleted: false, blockId: params.blockId, reason: "not-found" });
+            }
+            const flavour = block.get("sys:flavour");
+            if (flavour === "affine:page") {
+                throw new Error(`Refusing to delete page-root block '${params.blockId}' — use delete_doc for whole-doc removal.`);
+            }
+            const deletedIds = [];
+            const deleteRecursive = params.deleteChildren !== false;
+            const walk = (id) => {
+                const b = blocks.get(id);
+                if (!(b instanceof Y.Map))
+                    return;
+                if (deleteRecursive) {
+                    const children = b.get("sys:children");
+                    if (children instanceof Y.Array) {
+                        for (const c of children.toArray()) {
+                            if (typeof c === "string")
+                                walk(c);
+                        }
+                    }
+                }
+                blocks.delete(id);
+                deletedIds.push(id);
+            };
+            walk(params.blockId);
+            for (const [, maybeParent] of blocks.entries()) {
+                if (!(maybeParent instanceof Y.Map))
+                    continue;
+                const kids = maybeParent.get("sys:children");
+                if (!(kids instanceof Y.Array))
+                    continue;
+                const arr = kids.toArray();
+                for (let i = arr.length - 1; i >= 0; i--) {
+                    if (typeof arr[i] === "string" && deletedIds.includes(arr[i])) {
+                        kids.delete(i, 1);
+                    }
+                }
+            }
+            // Mirror delete_surface_element's pruneConnectors semantics.
+            const prunedConnectors = [];
+            if (params.pruneConnectors) {
+                const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+                if (ctx) {
+                    const toDelete = [];
+                    for (const [otherId, otherVal] of ctx.value.entries()) {
+                        if (!(otherVal instanceof Y.Map))
+                            continue;
+                        if (otherVal.get("type") !== "connector")
+                            continue;
+                        const source = otherVal.get("source");
+                        const target = otherVal.get("target");
+                        const srcId = source && typeof source === "object" ? source.id : undefined;
+                        const tgtId = target && typeof target === "object" ? target.id : undefined;
+                        if ((typeof srcId === "string" && deletedIds.includes(srcId)) ||
+                            (typeof tgtId === "string" && deletedIds.includes(tgtId))) {
+                            toDelete.push(String(otherId));
+                        }
+                    }
+                    for (const id of toDelete) {
+                        ctx.value.delete(id);
+                        prunedConnectors.push(id);
+                    }
+                }
+            }
+            pruneFromFrameChildElementIds(blocks, [...deletedIds, ...prunedConnectors]);
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({ deleted: true, blockId: params.blockId, deletedIds, prunedConnectors });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const getEdgelessCanvasHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: params.docId,
+                    exists: false,
+                    surfaceBlockId: null,
+                    edgelessBlocks: [],
+                    surfaceElements: [],
+                    bounds: null,
+                    elementCounts: { shape: 0, connector: 0, text: 0, group: 0 },
+                });
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const blocks = doc.getMap("blocks");
+            const edgelessFlavours = new Set([
+                "affine:frame",
+                "affine:edgeless-text",
+                "affine:note",
+            ]);
+            const collectNoteText = (rootId) => {
+                const out = [];
+                const seen = new Set();
+                const visit = (id) => {
+                    if (seen.has(id))
+                        return;
+                    seen.add(id);
+                    const b = blocks.get(id);
+                    if (!(b instanceof Y.Map))
+                        return;
+                    const t = asText(b.get("prop:text"));
+                    if (t)
+                        out.push(t);
+                    for (const childId of childIdsFrom(b.get("sys:children"))) {
+                        visit(childId);
+                    }
+                };
+                const root = blocks.get(rootId);
+                if (root instanceof Y.Map) {
+                    for (const childId of childIdsFrom(root.get("sys:children"))) {
+                        visit(childId);
+                    }
+                }
+                return out;
+            };
+            // Structured tree rather than flat-joined text so markdown-seeded notes
+            // round-trip with heading/paragraph/list structure intact.
+            const collectNoteChildren = (rootId) => {
+                const result = [];
+                const seen = new Set();
+                const visit = (id) => {
+                    if (seen.has(id))
+                        return null;
+                    seen.add(id);
+                    const b = blocks.get(id);
+                    if (!(b instanceof Y.Map))
+                        return null;
+                    const childFlavour = b.get("sys:flavour");
+                    if (typeof childFlavour !== "string")
+                        return null;
+                    const entry = { id, flavour: childFlavour };
+                    const t = asText(b.get("prop:text"));
+                    if (t)
+                        entry.text = t;
+                    const propType = b.get("prop:type");
+                    if (typeof propType === "string")
+                        entry.type = propType;
+                    const checked = b.get("prop:checked");
+                    if (typeof checked === "boolean")
+                        entry.checked = checked;
+                    const language = b.get("prop:language");
+                    if (typeof language === "string" && language.length > 0)
+                        entry.language = language;
+                    const subChildren = [];
+                    for (const childId of childIdsFrom(b.get("sys:children"))) {
+                        const c = visit(childId);
+                        if (c)
+                            subChildren.push(c);
+                    }
+                    if (subChildren.length)
+                        entry.children = subChildren;
+                    return entry;
+                };
+                const root = blocks.get(rootId);
+                if (root instanceof Y.Map) {
+                    for (const childId of childIdsFrom(root.get("sys:children"))) {
+                        const c = visit(childId);
+                        if (c)
+                            result.push(c);
+                    }
+                }
+                return result;
+            };
+            const edgelessBlocks = [];
+            for (const [id, raw] of blocks.entries()) {
+                if (!(raw instanceof Y.Map))
+                    continue;
+                const flavour = raw.get("sys:flavour");
+                if (typeof flavour !== "string" || !edgelessFlavours.has(flavour))
+                    continue;
+                const xywhRaw = raw.get("prop:xywh");
+                const bounds = parseXywhString(xywhRaw);
+                const propIndex = raw.get("prop:index");
+                const entry = {
+                    id: String(id),
+                    flavour,
+                    xywh: typeof xywhRaw === "string" ? xywhRaw : null,
+                    bounds,
+                    index: typeof propIndex === "string" ? propIndex : null,
+                };
+                if (flavour === "affine:frame") {
+                    entry.title = asText(raw.get("prop:title")) || null;
+                    const bg = raw.get("prop:background");
+                    entry.background = bg instanceof Y.Map ? bg.toJSON() : bg ?? null;
+                    const owned = raw.get("prop:childElementIds");
+                    entry.childElementIds = owned instanceof Y.Map ? Object.keys(owned.toJSON()) : [];
+                }
+                else if (flavour === "affine:edgeless-text") {
+                    const lines = collectNoteText(String(id));
+                    entry.text = lines.length ? lines.join("\n") : null;
+                    entry.color = raw.get("prop:color") ?? null;
+                }
+                else if (flavour === "affine:note") {
+                    const lines = collectNoteText(String(id));
+                    entry.text = lines.length ? lines.join("\n") : null;
+                    // `text` is the flat-join legacy view; `children` carries structure.
+                    entry.children = collectNoteChildren(String(id));
+                    entry.displayMode = raw.get("prop:displayMode") ?? null;
+                    const bg = raw.get("prop:background");
+                    entry.background = bg instanceof Y.Map ? bg.toJSON() : bg ?? null;
+                }
+                edgelessBlocks.push(entry);
+            }
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            const surfaceElements = [];
+            const counts = {
+                shape: 0,
+                connector: 0,
+                text: 0,
+                group: 0,
+            };
+            if (ctx) {
+                for (const [elId, val] of ctx.value.entries()) {
+                    if (!(val instanceof Y.Map))
+                        continue;
+                    const serialized = serializeSurfaceElement(String(elId), val);
+                    surfaceElements.push(serialized);
+                    const t = serialized.type;
+                    if (t && t in counts)
+                        counts[t]++;
+                }
+            }
+            const sortedSurfaceElements = sortByFractionalIndex(surfaceElements);
+            let minX = Infinity;
+            let minY = Infinity;
+            let maxX = -Infinity;
+            let maxY = -Infinity;
+            let hasAny = false;
+            const include = (b) => {
+                if (!b)
+                    return;
+                hasAny = true;
+                minX = Math.min(minX, b.x);
+                minY = Math.min(minY, b.y);
+                maxX = Math.max(maxX, b.x + b.width);
+                maxY = Math.max(maxY, b.y + b.height);
+            };
+            const sortedEdgelessBlocks = sortByFractionalIndex(edgelessBlocks);
+            for (const eb of sortedEdgelessBlocks)
+                include(eb.bounds);
+            for (const se of sortedSurfaceElements)
+                include(se.bounds);
+            return text({
+                docId: params.docId,
+                exists: true,
+                surfaceBlockId: ctx?.surfaceId ?? null,
+                edgelessBlocks: sortedEdgelessBlocks,
+                surfaceElements: sortedSurfaceElements,
+                elementCounts: counts,
+                bounds: hasAny
+                    ? { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY }
+                    : null,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const surfaceElementFieldSchemas = {
+        x: z.number().optional().describe("X position on canvas (shape/text; default 0)."),
+        y: z.number().optional().describe("Y position on canvas (shape/text; default 0)."),
+        width: z.number().optional().describe("Width (shape default 100, text default 200)."),
+        height: z.number().optional().describe("Height (shape default 100, text default 30)."),
+        shapeType: z
+            .enum(["rect", "ellipse", "diamond", "triangle"])
+            .optional()
+            .describe("Shape type (default rect). Shape only."),
+        radius: z.number().optional().describe("Corner radius for rect (0.1 = rounded). Shape only."),
+        filled: z.boolean().optional().describe("Whether shape is filled (default true). Shape only."),
+        fillColor: z
+            .string()
+            .optional()
+            .describe("Fill color. Prefer the `--affine-palette-shape-<color>` family (yellow/orange/red/magenta/purple/navy/blue/green/teal/grey/white/black). These are fixed colors — AFFiNE shape colors are not theme-adaptive by design. Shape only."),
+        strokeColor: z.string().optional().describe("Stroke color. Prefer the `--affine-palette-line-<color>` family (same color names as fillColor). Fixed colors, not theme-adaptive. Shape only."),
+        strokeWidth: z.number().optional().describe("Stroke width (default 2). Shape/connector."),
+        strokeStyle: z
+            .enum(["solid", "dash", "none"])
+            .optional()
+            .describe("Stroke style. Shape/connector."),
+        text: z
+            .string()
+            .optional()
+            .describe("Text content (shape/text) or connector label. Replaces existing Y.Text on update."),
+        color: z.string().optional().describe("Text color. Shape default `#000000` — keep unless the fill is dark, then pass a contrasting hex. Canvas text default `--affine-text-primary-color` (theme-adaptive). Shape/text."),
+        fontSize: z
+            .number()
+            .optional()
+            .describe("Font size (shape default 20, text default 16). Shape/text."),
+        fontWeight: z
+            .string()
+            .optional()
+            .describe("Font weight (shape default 600, text default 400). Shape/text."),
+        sourceId: z.string().optional().describe("Connector source element id. Connector only."),
+        targetId: z.string().optional().describe("Connector target element id. Connector only."),
+        sourcePosition: z
+            .array(z.number())
+            .length(2)
+            .optional()
+            .describe("Source [x,y]: relative [0-1] if sourceId set, absolute otherwise. Connector only."),
+        targetPosition: z
+            .array(z.number())
+            .length(2)
+            .optional()
+            .describe("Target [x,y]: relative [0-1] if targetId set, absolute otherwise. Connector only. When both source/target are bound by id and neither position is provided, endpoints snap to the BlockSuite side-midpoint facing the other endpoint so connectors flow in a clear direction. Pass [0.5,0] top, [0.5,1] bottom, [0,0.5] left, [1,0.5] right to force a specific side."),
+        mode: z
+            .number()
+            .optional()
+            .describe("Connector mode: 0=straight, 1=orthogonal (elbow), 2=curve (default 2). Connector only."),
+        frontEndpointStyle: z
+            .enum(["None", "Arrow", "Triangle", "Circle", "Diamond"])
+            .optional()
+            .describe("Front endpoint style (default None). Connector only."),
+        rearEndpointStyle: z
+            .enum(["None", "Arrow", "Triangle", "Circle", "Diamond"])
+            .optional()
+            .describe("Rear endpoint style (default Arrow). Connector only."),
+        stroke: z.string().optional().describe("Connector stroke color (default '--affine-text-primary-color' — theme-adaptive, near-black in light / near-white in dark). Accepts any CSS color or AFFiNE palette token. Connector only."),
+        label: z.string().optional().describe("Connector label (stored as text on the connector). Connector only."),
+        children: z.array(z.string()).optional().describe("Child element ids. Group only."),
+        title: z.string().optional().describe("Group title. Group only."),
+        index: z
+            .string()
+            .optional()
+            .describe("BlockSuite fractional-index string controlling z-order. On add, defaults to a key above every existing element's index (new elements render on top). On update, replaces the stored value — pass a key less than some existing index to send-to-back, or greater to bring-to-front. Use the value returned by list_surface_elements to pick a specific position."),
+    };
+    server.registerTool("add_surface_element", {
+        title: "Add Surface Element",
+        description: "Add a shape, connector, text, or group to the AFFiNE edgeless canvas surface. Shapes support rect/ellipse/diamond/triangle with fill, stroke, and text. Connectors draw arrows between shapes (by id) or between absolute points. Use for building diagrams programmatically. Style fields that don't apply to the chosen element type are reported in the response 'ignored' list (mirrors update_surface_element).",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            type: z.enum(["shape", "connector", "text", "group"]).describe("Element type"),
+            ...surfaceElementFieldSchemas,
+        },
+    }, addSurfaceElementHandler);
+    server.registerTool("list_surface_elements", {
+        title: "List Surface Elements",
+        description: "List all shape/connector/text/group elements on the AFFiNE edgeless canvas surface. Returns raw xywh strings plus parsed {x,y,width,height} bounds, with Y.Text fields serialized to plain strings. Optional filters by element type or id.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            type: z
+                .enum(["shape", "connector", "text", "group"])
+                .optional()
+                .describe("Filter by element type"),
+            elementId: z.string().optional().describe("Filter to a single element id"),
+        },
+    }, listSurfaceElementsHandler);
+    server.registerTool("update_surface_element", {
+        title: "Update Surface Element",
+        description: "Partially update a surface element by id. x/y/width/height merge with the element's current xywh (move without resizing, or vice versa). text/label/title replace their Y.Text wholesale. Fields that don't apply to the element's type are reported in the response 'ignored' list.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            elementId: z.string().min(1).describe("Element ID to update"),
+            ...surfaceElementFieldSchemas,
+        },
+    }, updateSurfaceElementHandler);
+    server.registerTool("delete_surface_element", {
+        title: "Delete Surface Element",
+        description: "Delete a surface element by id. Set pruneConnectors=true to also delete any connectors whose source or target referenced the deleted element.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            elementId: z.string().min(1).describe("Element ID to delete"),
+            pruneConnectors: z
+                .boolean()
+                .optional()
+                .describe("Also delete connectors referencing this element (default false)"),
+        },
+    }, deleteSurfaceElementHandler);
+    server.registerTool("update_frame_children", {
+        title: "Update Frame Children",
+        description: "Replace a frame block's contents wholesale. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — all go into BlockSuite's prop:childElementIds map, matching what the editor writes when you drag members into a frame. Dragging the frame drags every owned member. Ids that don't resolve come back under 'missing'. By default the frame is resized to fit its new contents (plus padding + title band); set resizeToFit=false to leave xywh untouched. Pass `[]` to clear ownership (resize is skipped in that case).",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            blockId: z.string().min(1).describe("Frame block id (flavour affine:frame)."),
+            childElementIds: z
+                .array(z.string())
+                .describe("Full list of ids the frame should own/contain. Replaces any existing ownership."),
+            resizeToFit: z
+                .boolean()
+                .optional()
+                .describe("If true (default), recompute xywh from the union of resolvable child bounds + padding + title band. Set to false to preserve the frame's current box (useful when you want ownership-only edits or manual positioning)."),
+            padding: z
+                .number()
+                .int()
+                .optional()
+                .describe("Padding (px) used when resizeToFit is true (default 40). Ignored when resizeToFit=false."),
+        },
+    }, updateFrameChildrenHandler);
+    server.registerTool("update_edgeless_block", {
+        title: "Update Edgeless Block",
+        description: "Partially update a note/frame/edgeless-text block by id. x/y/width/height merge with current prop:xywh (move without resizing, or vice versa). background replaces prop:background (AFFiNE token or `{light, dark}` hex object). Fields that don't apply to the block's flavour come back under `ignored`.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            blockId: z.string().min(1).describe("Block id (flavour affine:note/affine:frame/affine:edgeless-text)."),
+            x: z.number().optional(),
+            y: z.number().optional(),
+            width: z.number().optional(),
+            height: z.number().optional(),
+            background: z
+                .union([
+                z.string(),
+                z.object({ light: z.string().optional(), dark: z.string().optional() }),
+            ])
+                .optional()
+                .describe("Note/frame only. Prefer `--affine-note-background-<color>` or `{light, dark}` hex."),
+        },
+    }, updateEdgelessBlockHandler);
+    server.registerTool("delete_block", {
+        title: "Delete Block",
+        description: "Delete a block by id. Removes descendants and unlinks from the parent's sys:children by default; set deleteChildren=false to keep descendants orphaned (for re-parenting), or pruneConnectors=true to also drop surface connectors referencing any deleted id. Refuses affine:page — use delete_doc for whole docs.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            blockId: z.string().min(1).describe("Block id to delete."),
+            deleteChildren: z.boolean().optional().describe("Also delete descendants (default true)."),
+            pruneConnectors: z.boolean().optional().describe("Also delete connectors bound to any deleted id (default false)."),
+        },
+    }, deleteBlockHandler);
+    server.registerTool("get_edgeless_canvas", {
+        title: "Get Edgeless Canvas",
+        description: "Read the full edgeless canvas: all edgeless-positioned blocks (notes, frames, edgeless-text) with their xywh, plus all surface elements (shapes, connectors, text, groups). Includes aggregate bounding box and per-type element counts. Use this when you need to understand canvas layout end-to-end before placing new elements.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+        },
+    }, getEdgelessCanvasHandler);
 }