callman-mcp 0.2.0 → 0.4.0

package/dist-cjs/tools/diagrams.js

@@ -14,74 +14,375 @@ const pagination_js_1 = require("../lib/pagination.js");
 const lookups_js_1 = require("./lookups.js");
 const shared_js_1 = require("./shared.js");
 const directionArg = zod_1.z.enum(["DOWN", "RIGHT", "UP", "LEFT"]).optional().describe("Layout flow direction (default DOWN)");
+const sourceArg = zod_1.z
+    .object({
+    format: zod_1.z.enum(["mermaid", "bpmn", "database"]).describe('"mermaid": Mermaid text; "bpmn": a BPMN 2.0 XML file; "database": the JSON database model of a Database Diagram (get_diagram view "source" of one, or the desktop\'s schema export)'),
+    text: zod_1.z
+        .string()
+        .min(1)
+        .max(2_000_000)
+        .describe("Mermaid: a flowchart/graph becomes nodes and edges (laid out automatically) and stays attached as the diagram's source; any other Mermaid type is stored as source only. BPMN: the XML is the diagram (its shapes, flows, pools and lanes are derived from it with their positions)"),
+})
+    .strict()
+    .optional()
+    .describe("Create the diagram from Mermaid text, BPMN 2.0 XML or a database model instead of nodes/edges");
+// A BPMN diagram keeps its truth in BPMN 2.0 XML: the model is derived from it.
+const bpmnSource = (text) => ({ format: "bpmn", text, diagramType: "bpmn", grammar: callman_core_1.BPMN_GRAMMAR_VERSION });
+// Typed bpmn.* nodes → a BPMN diagram: the model becomes XML, the XML becomes
+// the diagram's source, and the shapes are derived back from it.
+const bpmnDocumentFromModel = (model, unpositionedNodeIds, base) => {
+    const placed = unpositionedNodeIds.length > 0 ? (0, callman_core_1.applyDiagramOps)(model, (0, callman_core_1.placeBpmnNodesOps)(model, unpositionedNodeIds)).doc : model;
+    const xml = (0, callman_core_1.bpmnXmlFromDocument)({ ...placed, source: undefined });
+    const document = (0, callman_core_1.applyDiagramOps)({ ...base, nodes: [], edges: [], source: undefined }, [{ op: "setSource", source: bpmnSource(xml), resync: true }], { now: now() }).doc;
+    return { document, layoutNote: unpositionedNodeIds.length > 0 ? `Written as BPMN 2.0 XML; ${unpositionedNodeIds.length} node(s) placed left to right after their predecessors.` : "Written as BPMN 2.0 XML with the positions given." };
+};
+// A database diagram keeps its truth in the JSON database model.
+const databaseSource = (text) => ({ format: "database", text, diagramType: "database", grammar: callman_core_1.DATABASE_GRAMMAR_VERSION, valid: true });
+const DATABASE_DIALECTS = ["postgres", "mysql", "mssql", "oracle", "mongo", "generic"];
+const toolErrorFromDatabaseEdit = (error) => {
+    if (error instanceof callman_core_1.DatabaseEditError)
+        throw new errors_js_1.ToolInputError(error.code, error.message);
+    throw error;
+};
+// A database model → a database diagram: the model becomes the source, the
+// tables are derived from it and laid out (unrelated tables packed in rows).
+const databaseDocumentFromModel = async (model, base, keepPositions = false) => {
+    const applied = (0, callman_core_1.applyDiagramOps)({ ...base, ...(keepPositions ? {} : { nodes: [], edges: [] }), source: undefined }, [{ op: "setSource", source: databaseSource((0, callman_core_1.serializeDatabaseModel)(model)), resync: true }], { now: now() });
+    let document = applied.doc;
+    if (keepPositions) {
+        const fresh = applied.added.nodes.filter((id) => document.nodes.some((node) => node.id === id));
+        if (fresh.length > 0)
+            document = (0, layout_js_1.placeDatabaseNodes)(document, fresh);
+        return { document, layoutNote: fresh.length > 0 ? `${fresh.length} new table(s) placed to the right of the existing ones.` : "Positions kept." };
+    }
+    if (document.nodes.length === 0)
+        return { document, layoutNote: "An empty database diagram." };
+    const laid = await (0, layout_js_1.layoutDocument)(document, { request: callman_core_1.DATABASE_LAYOUT_REQUEST });
+    return { document: laid.document, layoutNote: laid.warning ?? `${document.nodes.length} table(s) laid out with ${laid.engine} (relationships left to right).` };
+};
+// Tables + relationships as the create tool takes them → a model.
+const databaseModelFromInput = (tables, relationships, dialect) => {
+    const edits = [
+        ...tables.map((table) => ({ kind: "addTable", table: { ...table, ...(table.columns ? { columns: table.columns.map((column) => ({ ...column, defaultValue: column.defaultValue ?? undefined, comment: column.comment ?? undefined })) } : {}) } })),
+        ...relationships.map((relationship) => ({
+            kind: "addRelationship",
+            ...(relationship.id ? { id: relationship.id } : {}),
+            source: relationship.source,
+            target: relationship.target,
+            ...(relationship.cardinality ? { cardinality: relationship.cardinality } : {}),
+            ...(relationship.kind ? { relationshipKind: relationship.kind } : {}),
+            ...(relationship.name ? { name: relationship.name } : {}),
+            ...(relationship.label ? { label: relationship.label } : {}),
+        })),
+    ];
+    try {
+        return (0, callman_core_1.applyDatabaseEdits)((0, callman_core_1.emptyDatabaseModel)(dialect), edits).model;
+    }
+    catch (error) {
+        return toolErrorFromDatabaseEdit(error);
+    }
+};
+// A database connection by id or name, in one workspace or across all.
+const findDatabaseConnection = async (ctx, workspace, ref) => {
+    const wanted = ref.trim().toLowerCase();
+    const workspaces = await (0, lookups_js_1.workspacesForListing)(ctx, workspace);
+    const matches = [];
+    for (const ws of workspaces) {
+        for (const connection of await ctx.api.listConnections(ws.id, "database")) {
+            if (connection.id === ref.trim() || connection.name.trim().toLowerCase() === wanted)
+                matches.push({ ws, connection });
+        }
+    }
+    if (matches.length === 0)
+        throw new errors_js_1.ToolInputError("CONNECTION_NOT_FOUND", `No database connection "${ref}"${workspace ? ` in workspace ${workspace}` : " in your workspaces"}. list_connections shows them (type: database).`);
+    const exact = matches.filter((match) => match.connection.id === ref.trim());
+    if (exact.length === 1)
+        return exact[0];
+    if (matches.length > 1) {
+        throw new errors_js_1.ToolInputError("AMBIGUOUS_CONNECTION", `"${ref}" matches ${matches.length} database connections; pass its id or a \`workspace\`.`, {
+            candidates: matches.map((match) => ({ id: match.connection.id, name: match.connection.name, workspace: (0, lookups_js_1.workspaceTag)(match.ws) })),
+        });
+    }
+    return matches[0];
+};
+const schemaQuery = (options) => ({
+    ...(options.schemas && options.schemas.length > 0 ? { schemas: options.schemas.join(",") } : {}),
+    ...(options.tables && options.tables.length > 0 ? { tables: options.tables.join(",") } : {}),
+    ...(options.includeViews !== undefined ? { includeViews: String(options.includeViews) } : {}),
+    ...(options.objectsOnly ? { objectsOnly: "true" } : {}),
+    ...(options.maxTables !== undefined ? { maxTables: options.maxTables } : {}),
+});
+const PROVIDER_LABEL = { postgresql: "PostgreSQL", mysql: "MySQL", mssql: "SQL Server", oracle: "Oracle", mongodb: "MongoDB" };
+// Every document entering a tool goes through the shared gate (legacy fields
+// stripped, ids deduped, parents healed) — the same one the studio applies.
 const loadDocument = (diagram) => {
-    const parsed = (0, callman_core_1.safeParseDiagramDocument)(diagram.document);
+    const result = (0, callman_core_1.normalizeDocument)(diagram.document);
+    if (!result.document.nodes && !result.document.edges) {
+        throw new errors_js_1.ToolInputError("DIAGRAM_DOCUMENT_INVALID", `The stored diagram "${diagram.name}" is not a valid document.`);
+    }
+    return result.document;
+};
+const now = () => new Date().toISOString();
+// A source-backed diagram whose Mermaid type is not a flowchart has no model
+// to edit: structural tools refuse it clearly instead of guessing. (BPMN
+// diagrams are editable: their ops patch the XML.)
+const assertEditableStructure = (doc) => {
+    if (doc.source && doc.source.format === "mermaid" && doc.source.diagramType !== "flowchart") {
+        throw new errors_js_1.ToolInputError("DIAGRAM_SOURCE_UNSUPPORTED_TYPE", `This diagram is a Mermaid ${doc.source.diagramType} kept as source only; nodes and edges cannot be edited through ops. Update its source with update_diagram { source } or read it with get_diagram view:"source".`, { diagramType: doc.source.diagramType });
+    }
+};
+// Mermaid text → the document it describes: a flowchart is parsed into
+// nodes/edges (positions come from layout); anything else is kept as
+// source only (the desktop previews it, tools read it back).
+const documentFromSource = async (title, text, existing, direction, format = "mermaid") => {
+    if (format === "database") {
+        const parsed = (0, callman_core_1.parseDatabaseModel)(text);
+        if (!parsed.ok)
+            throw new errors_js_1.ToolInputError("DIAGRAM_SOURCE_INVALID", "The text is not a readable database model.", { errors: parsed.errors.slice(0, 20) });
+        const base = existing ?? (0, callman_core_1.createEmptyDocument)(title);
+        const keep = Boolean(existing && existing.source?.format === "database");
+        let built;
+        try {
+            built = await databaseDocumentFromModel(parsed.model, keep ? existing : { ...base, nodes: [], edges: [] }, keep);
+        }
+        catch (error) {
+            return (0, build_js_1.toToolError)(error);
+        }
+        return { document: built.document, layoutNote: built.layoutNote, warnings: parsed.warnings };
+    }
+    if (format === "bpmn") {
+        if (!(0, callman_core_1.looksLikeBpmn)(text))
+            throw new errors_js_1.ToolInputError("DIAGRAM_SOURCE_INVALID", "The text is not a BPMN 2.0 document (no <definitions> root).");
+        const parsed = (0, callman_core_1.parseBpmn)(text);
+        if (!parsed.ok) {
+            throw new errors_js_1.ToolInputError("DIAGRAM_SOURCE_INVALID", "The BPMN XML could not be read.", { diagnostics: parsed.structure.diagnostics.filter((entry) => entry.severity === "error").slice(0, 20) });
+        }
+        const base = existing ?? (0, callman_core_1.createEmptyDocument)(title);
+        let document;
+        try {
+            document = (0, callman_core_1.applyDiagramOps)(base, [{ op: "setSource", source: bpmnSource(text), resync: true }], { now: now() }).doc;
+        }
+        catch (error) {
+            return (0, build_js_1.toToolError)(error);
+        }
+        // Shapes the XML has no diagram interchange for are placed after their predecessors.
+        const unplaced = parsed.structure.nodes.filter((node) => !node.position).map((node) => node.id).filter((id) => document.nodes.some((node) => node.id === id));
+        if (unplaced.length > 0)
+            document = (0, callman_core_1.applyDiagramOps)(document, (0, callman_core_1.placeBpmnNodesOps)(document, unplaced), { now: now() }).doc;
+        const warnings = parsed.structure.diagnostics.filter((entry) => entry.severity !== "error").map((entry) => entry.message);
+        return { document, layoutNote: unplaced.length > 0 ? `Positions from the BPMN diagram interchange; ${unplaced.length} shape(s) without one were placed.` : "Positions from the BPMN diagram interchange.", warnings };
+    }
+    if (!(0, callman_core_1.looksLikeMermaid)(text)) {
+        throw new errors_js_1.ToolInputError("DIAGRAM_SOURCE_INVALID", "The text does not start with a Mermaid diagram header (flowchart, graph, sequenceDiagram, …).");
+    }
+    const base = existing ?? (0, callman_core_1.createEmptyDocument)(title);
+    if (!(0, callman_core_1.isMermaidFlowchart)(text)) {
+        const header = text.replace(/^---[\s\S]*?\n---\s*\n/, "").split("\n").map((line) => line.trim()).find((line) => line !== "" && !line.startsWith("%%")) ?? "";
+        const diagramType = header.split(/\s+/)[0] ?? "unknown";
+        const source = { format: "mermaid", text, diagramType, grammar: callman_core_1.MERMAID_GRAMMAR_VERSION, valid: true };
+        const doc = (0, callman_core_1.applyDiagramOps)(base, [{ op: "setSource", source, resync: false }], { now: now() }).doc;
+        return { document: doc, layoutNote: `Stored as Mermaid ${diagramType} source (no nodes to lay out).`, warnings: [] };
+    }
+    const parsed = (0, callman_core_1.parseMermaid)(text);
     if (!parsed.ok) {
-        throw new errors_js_1.ToolInputError("DIAGRAM_DOCUMENT_INVALID", `The stored diagram "${diagram.name}" is not a valid document: ${parsed.errors.join("; ")}`, { errors: parsed.errors });
+        throw new errors_js_1.ToolInputError("DIAGRAM_SOURCE_INVALID", "The Mermaid flowchart has syntax errors.", {
+            diagnostics: parsed.structure.diagnostics.filter((entry) => entry.severity === "error").slice(0, 20),
+        });
     }
-    return parsed.document;
+    const source = { format: "mermaid", text, diagramType: "flowchart", grammar: callman_core_1.MERMAID_GRAMMAR_VERSION };
+    let applied;
+    try {
+        applied = (0, callman_core_1.applyDiagramOps)(base, [{ op: "setSource", source }], { now: now() });
+    }
+    catch (error) {
+        return (0, build_js_1.toToolError)(error);
+    }
+    const warnings = parsed.structure.diagnostics.filter((entry) => entry.severity !== "error").map((entry) => entry.message);
+    const newIds = applied.added.nodes;
+    let document = applied.doc;
+    let layoutNote;
+    if (newIds.length > 0) {
+        if (existing && existing.nodes.length > 0) {
+            document = (0, layout_js_1.placeNewNodes)(document, newIds);
+            layoutNote = `Placed ${newIds.length} new node(s) below the existing ones.`;
+        }
+        else {
+            const laid = await (0, layout_js_1.layoutDocument)(document, { direction: direction ?? parsed.structure.direction });
+            document = laid.document;
+            layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+        }
+    }
+    return { document, layoutNote, warnings };
 };
+// Save with the revision we read; on a 409 the caller reloads and reapplies.
+const isConflict = (error) => error instanceof errors_js_1.CallmanApiError && error.status === 409;
 const registerDiagramTools = (server, ctx) => {
     server.registerTool("list_diagrams", {
         title: "List diagrams",
-        description: "List your system-design diagrams and the ones shared with you (owner, node/edge counts, whether you can edit). Diagrams belong to users and are shared into workspaces — not workspace-scoped.",
-        inputSchema: { query: zod_1.z.string().max(200).optional(), ...shared_js_1.cursorArgs },
+        description: "List your system-design diagrams and the ones shared with you (owner, node/edge counts, whether you can edit), with the folder tree of your library: `folders` are your own folders as paths (\"Architecture/Payments\"), each diagram carries its `folder` path (null = the top level; always null for a diagram shared with you — folders are private to their owner). Diagrams belong to users and are shared into workspaces — not workspace-scoped.",
+        inputSchema: {
+            query: zod_1.z.string().max(200).optional(),
+            folder: zod_1.z.string().max(300).optional().describe('Only the diagrams in this folder of your library (id, name or path such as "Architecture/Payments"); "/" = the top level only'),
+            ...shared_js_1.cursorArgs,
+        },
         annotations: shared_js_1.READ,
-    }, (0, shared_js_1.guarded)(async ({ query, cursor, limit }) => {
-        const all = await (0, lookups_js_1.loadDiagrams)(ctx);
+    }, (0, shared_js_1.guarded)(async ({ query, folder, cursor, limit }) => {
+        const [all, rows] = await Promise.all([(0, lookups_js_1.loadDiagrams)(ctx), (0, lookups_js_1.diagramFolderRows)(ctx)]);
         const needle = query?.trim().toLowerCase();
-        const filtered = needle ? all.filter((diagram) => diagram.name.toLowerCase().includes(needle)) : all;
-        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit, needle ?? "");
-        return (0, shared_js_1.ok)({ diagrams: page.items.map(summarize_js_1.diagramListView), total: page.total, nextCursor: page.nextCursor });
+        const scope = folder?.trim() === "/" ? { item: null, annotation: undefined } : folder ? await (0, lookups_js_1.resolveDiagramFolder)(ctx, folder) : undefined;
+        const filtered = all.filter((diagram) => {
+            if (needle && !diagram.name.toLowerCase().includes(needle))
+                return false;
+            if (scope === undefined)
+                return true;
+            return (diagram.folderId ?? null) === (scope.item?.id ?? null);
+        });
+        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit, `${needle ?? ""}|${scope?.item?.id ?? (scope ? "/" : "")}`);
+        return (0, shared_js_1.ok)({
+            diagrams: page.items.map((diagram) => ({ ...(0, summarize_js_1.diagramListView)(diagram), folder: (0, lookups_js_1.diagramFolderPath)(rows, diagram.folderId) })),
+            folders: rows.map((row) => ({ id: row.id, name: row.name, parentId: row.parentId, path: row.path })),
+            total: page.total,
+            nextCursor: page.nextCursor,
+            ...(scope?.item && scope.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(folder, scope)] } : {}),
+        });
     }));
     server.registerTool("get_diagram", {
         title: "Get a diagram",
-        description: "Read a diagram: `summary` (counts, owner, sharing), `graph` (default — nodes with type/label/parent/style and edges with semantic/color, in the same shape the write tools accept: enough to describe, restyle or edit it) or `full` (the complete stored DiagramDocument with positions, sizes and routes, up to 512 KB).",
-        inputSchema: { diagram: (0, shared_js_1.refArg)("Diagram"), view: zod_1.z.enum(["summary", "graph", "full"]).default("graph") },
+        description: "Read a diagram: `summary` (counts, owner, sharing), `graph` (default — nodes with type/label/parent/style and edges with semantic/color/routing/sides, in the same shape the write tools accept: enough to describe, restyle or edit it), `mermaid` (the diagram rendered as Mermaid flowchart text), `source` (the Mermaid text, BPMN 2.0 XML or JSON database model a source-backed diagram keeps), `schema` (a database diagram's tables with columns, keys and relationships as table.column pairs — read it before database ops) or `full` (the complete stored DiagramDocument with positions, sizes and routes, up to 512 KB).",
+        inputSchema: { diagram: (0, shared_js_1.refArg)("Diagram"), view: zod_1.z.enum(["summary", "graph", "mermaid", "source", "schema", "full"]).default("graph") },
         annotations: shared_js_1.READ,
     }, (0, shared_js_1.guarded)(async ({ diagram, view }) => {
         const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
         const doc = loadDocument(resolved.item);
         const summary = (0, summarize_js_1.diagramListView)(resolved.item);
-        const body = view === "summary" ? summary : view === "graph" ? { ...summary, ...(0, summarize_js_1.diagramGraphView)(doc) } : { ...summary, ...(0, summarize_js_1.diagramFullView)(doc) };
+        const summaryWithFolder = { ...summary, folder: (0, lookups_js_1.diagramFolderPath)(await (0, lookups_js_1.diagramFolderRows)(ctx), resolved.item.folderId) };
+        const body = view === "summary"
+            ? summaryWithFolder
+            : view === "graph"
+                ? { ...summary, ...(0, summarize_js_1.diagramGraphView)(doc) }
+                : view === "mermaid"
+                    ? { ...summary, ...(0, summarize_js_1.diagramMermaidView)(doc) }
+                    : view === "source"
+                        ? { ...summary, ...(0, summarize_js_1.diagramSourceView)(doc) }
+                        : view === "schema"
+                            ? { ...summary, schema: (0, callman_core_1.databaseSchemaView)(doc) }
+                            : { ...summary, ...(0, summarize_js_1.diagramFullView)(doc) };
         return (0, shared_js_1.ok)({ diagram: body, ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)] } : {}) });
     }));
     server.registerTool("create_diagram", {
-        title: "Create a system-design diagram",
-        description: "Create a diagram from typed nodes and edges. Node `type` must come from callman://diagram/components (e.g. net.service, net.api-gateway, db.postgres, mq.kafka, aws.lambda, flow.process); unknown types are rejected with suggestions unless strictTypes: false. Group nodes inside a container node — frame, pool.horizontal or pool.vertical — with `parent`. Style nodes with `style` (fill / stroke / textColor as CSS colors, strokeWidth, dashed, radius, bold, fontSize, opacity…) and edges with `semantic` (sync default, async, fallback, bus) plus an optional `color`. Layout is automatic when nodes have no positions. Read callman://docs/diagram-schema for every field. Keep it readable: 8–25 nodes, short labels.",
+        title: "Create a system-design, process or database diagram",
+        description: "Create a diagram from typed nodes and edges — or from Mermaid text / BPMN 2.0 XML / a database model (`source`). A BPMN process (`kind: \"bpmn\"`, or nodes typed bpmn.*) is stored as BPMN 2.0 XML the desktop opens in its BPMN editor. A DATABASE diagram (entity-relationship: `kind: \"database\"`, `tables` + `relationships`, nodes typed db.table/db.view/db.collection with the columns in data: { db: { columns } }, or `fromConnection` to read a real database's schema) is stored as the JSON database model the desktop opens on its ERD canvas — tables with columns and keys, relationships with cardinality, laid out left to right. Node `type` must come from callman://diagram/components (e.g. net.service, net.api-gateway, db.postgres, mq.kafka, aws.lambda, flow.process); unknown types are rejected with suggestions unless strictTypes: false. Group nodes inside a container node — frame, pool.horizontal or pool.vertical — with `parent`. Style nodes with `style` (fill / stroke / textColor as CSS colors, strokeWidth, dashed, radius, bold, fontSize, opacity…) and edges with `semantic` (sync default, async, fallback, bus), an optional `color`, `routing` and fixed `sourceSide`/`targetSide`. Layout is automatic when nodes have no positions. Read callman://docs/diagram-schema for every field. Keep it readable: 8–25 nodes, short labels.",
         inputSchema: {
             name: zod_1.z.string().min(1).max(200).describe("Diagram name (library entry)"),
-            ...build_js_1.diagramInputSchema.shape,
+            title: build_js_1.diagramInputSchema.shape.title.optional().describe("Diagram title (defaults to the name)"),
+            nodes: build_js_1.diagramInputSchema.shape.nodes.optional(),
+            edges: build_js_1.diagramInputSchema.shape.edges.optional(),
+            canvas: build_js_1.diagramInputSchema.shape.canvas,
+            source: sourceArg,
+            kind: zod_1.z.enum(["canvas", "bpmn", "database"]).optional().describe('"bpmn": model a business process — nodes use bpmn.* types and the diagram is stored as BPMN 2.0 XML; "database": an entity-relationship diagram stored as the JSON database model (default: canvas; inferred from the node types, from `tables` and from `fromConnection`)'),
+            tables: zod_1.z.array(patch_js_1.dbTableInputSchema).max(500).optional().describe("Database diagram: the tables (name, schema?, kind?, columns with dataType / primaryKey / nullable / unique / defaultValue / comment)"),
+            relationships: zod_1.z.array(patch_js_1.dbRelationshipInputSchema).max(2000).optional().describe('Database diagram: relationships between the tables — source is the child (foreign-key) side as "table.column", target the parent; cardinality source:target (default N:1)'),
+            dialect: zod_1.z.enum(DATABASE_DIALECTS).optional().describe("Database diagram: which database the types are written for"),
+            fromConnection: zod_1.z
+                .object({
+                connection: zod_1.z.string().min(1).max(200).describe("A database connection by id or name (list_connections, type: database)"),
+                schemas: zod_1.z.array(zod_1.z.string().min(1).max(120)).max(50).optional().describe("Schemas to read (default: every user schema; MySQL: the connection's database; Oracle: the current schema)"),
+                tables: zod_1.z.array(zod_1.z.string().min(1).max(240)).max(2000).optional().describe('Only these tables ("schema.table" or "table"); default: all'),
+                includeViews: zod_1.z.boolean().optional(),
+            })
+                .strict()
+                .optional()
+                .describe("Database diagram: read a real database's schema through one of the workspace's connections and draw it — tables, columns, keys and the relationships the database declares"),
+            workspace: shared_js_1.workspaceArg,
+            folder: zod_1.z.string().max(300).optional().describe('File it in a folder of your library (id, name or path such as "Architecture/Payments"; create one with create_diagram_folder). Default: the top level'),
             autoLayout: zod_1.z.boolean().optional().describe("Force layout even when positions were given"),
             direction: directionArg,
             strictTypes: zod_1.z.boolean().optional(),
             dryRun: shared_js_1.dryRunArg,
         },
         annotations: shared_js_1.WRITE,
-    }, (0, shared_js_1.guarded)(async ({ name, autoLayout, direction, strictTypes, dryRun, ...input }) => {
-        const built = (0, build_js_1.buildDiagramDocument)(input, { strictTypes });
-        let document = built.document;
+    }, (0, shared_js_1.guarded)(async ({ name, title, nodes, edges, canvas, source, kind, tables, relationships, dialect, fromConnection, workspace, folder, autoLayout, direction, strictTypes, dryRun }) => {
+        const targetFolder = folder ? await (0, lookups_js_1.resolveDiagramFolder)(ctx, folder) : null;
+        const inputs = [nodes ? "nodes" : null, source ? "source" : null, tables ? "tables" : null, fromConnection ? "fromConnection" : null].filter(Boolean);
+        if (inputs.length === 0)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_CREATE", 'Pass nodes (+ edges), source { format: "mermaid" | "bpmn" | "database", text }, tables (+ relationships) or fromConnection.');
+        if (inputs.length > 1)
+            throw new errors_js_1.ToolInputError("CONFLICTING_INPUT", `Pass one of nodes, source, tables or fromConnection — not ${inputs.join(" + ")}.`);
+        if (relationships && !tables)
+            throw new errors_js_1.ToolInputError("CONFLICTING_INPUT", "relationships go with tables.");
+        let document;
         let layoutNote;
-        if (autoLayout || built.unpositionedNodeIds.length > 0) {
-            const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
-            document = laid.document;
-            layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+        let warnings = [];
+        const bpmnKind = kind === "bpmn" || (kind === undefined && Boolean(nodes && nodes.length > 0 && nodes.every((node) => node.type.startsWith("bpmn."))));
+        const databaseKind = kind === "database" || Boolean(tables) || Boolean(fromConnection) || (kind === undefined && Boolean(nodes && nodes.length > 0 && nodes.every((node) => (0, callman_core_1.isDatabaseType)(node.type))));
+        let connectionNote = {};
+        if (source) {
+            const fromSource = await documentFromSource(title ?? name, source.text, null, direction, source.format);
+            document = canvas ? { ...fromSource.document, canvas: { ...fromSource.document.canvas, ...canvas } } : fromSource.document;
+            layoutNote = fromSource.layoutNote;
+            warnings = fromSource.warnings;
+        }
+        else if (fromConnection) {
+            const found = await findDatabaseConnection(ctx, workspace, fromConnection.connection);
+            const schema = await ctx.api.getConnectionSchema(found.ws.id, found.connection.id, schemaQuery(fromConnection));
+            const model = (0, callman_core_1.databaseModelFromSchema)(schema, { connection: { connectionId: found.connection.id, name: found.connection.name, provider: found.connection.provider } });
+            const built = await databaseDocumentFromModel(model, (0, callman_core_1.createEmptyDocument)(title ?? name));
+            document = built.document;
+            layoutNote = built.layoutNote;
+            warnings = [...schema.warnings, ...(schema.truncated ? ["The database has more tables than the cap; the list was cut."] : [])];
+            connectionNote = { connection: { id: found.connection.id, name: found.connection.name, provider: PROVIDER_LABEL[found.connection.provider] ?? found.connection.provider, workspace: (0, lookups_js_1.workspaceTag)(found.ws) }, tables: model.entities.length, relationships: model.relationships.length };
+        }
+        else if (tables) {
+            const model = databaseModelFromInput(tables, relationships ?? [], dialect);
+            const built = await databaseDocumentFromModel(model, (0, callman_core_1.createEmptyDocument)(title ?? name));
+            document = built.document;
+            layoutNote = built.layoutNote;
+        }
+        else if (databaseKind) {
+            const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? name, nodes: nodes ?? [], edges: edges ?? [], canvas }, { strictTypes, kind: "database" });
+            const model = (0, callman_core_1.databaseModelFromDocument)({ ...built.document, source: undefined }, dialect);
+            const database = await databaseDocumentFromModel(model, (0, callman_core_1.createEmptyDocument)(title ?? name));
+            document = database.document;
+            layoutNote = database.layoutNote;
+            warnings = built.warnings;
+        }
+        else if (bpmnKind) {
+            const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? name, nodes: nodes ?? [], edges: edges ?? [], canvas }, { strictTypes, kind: "bpmn" });
+            const bpmn = bpmnDocumentFromModel(built.document, built.unpositionedNodeIds, (0, callman_core_1.createEmptyDocument)(title ?? name));
+            document = bpmn.document;
+            layoutNote = bpmn.layoutNote;
+            warnings = built.warnings;
         }
+        else {
+            const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? name, nodes: nodes ?? [], edges: edges ?? [], canvas }, { strictTypes });
+            document = built.document;
+            warnings = built.warnings;
+            if (autoLayout || built.unpositionedNodeIds.length > 0) {
+                const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
+                document = laid.document;
+                layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+            }
+        }
+        if (document.source?.format === "database" && canvas && !source)
+            document = { ...document, canvas: { ...document.canvas, ...canvas } };
+        const view = document.source?.format === "database" ? { ...(0, summarize_js_1.diagramGraphView)(document), schema: (0, callman_core_1.databaseSchemaView)(document) } : (0, summarize_js_1.diagramGraphView)(document);
         if (dryRun) {
-            return (0, shared_js_1.ok)({ dryRun: true, diagram: { name, ...(0, summarize_js_1.diagramGraphView)(document) }, warnings: built.warnings, ...(layoutNote ? { layout: layoutNote } : {}) });
+            return (0, shared_js_1.ok)({ dryRun: true, diagram: { name, folder: targetFolder?.item.path ?? null, ...view }, warnings, ...connectionNote, ...(layoutNote ? { layout: layoutNote } : {}) });
         }
-        const created = await ctx.api.createDiagram({ name: name.trim(), document });
+        const created = await ctx.api.createDiagram({ name: name.trim(), document, ...(targetFolder ? { folderId: targetFolder.item.id } : {}) });
         ctx.invalidate("diagrams");
         return (0, shared_js_1.ok)({
-            diagram: { ...(0, summarize_js_1.diagramListView)(created), ...(0, summarize_js_1.diagramGraphView)(document) },
-            warnings: built.warnings,
+            diagram: { ...(0, summarize_js_1.diagramListView)(created), folder: targetFolder?.item.path ?? null, ...view },
+            warnings,
+            ...connectionNote,
             ...(layoutNote ? { layout: layoutNote } : {}),
-            note: "Saved. Open it in the desktop app (Diagrams → Refresh). Edit with patch_diagram; share with share_diagram.",
+            ...(targetFolder?.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(folder, targetFolder)] } : {}),
+            note: `Saved${targetFolder ? ` in ${targetFolder.item.path}` : ""}. Open it in the desktop app (Diagrams → Refresh). Edit with patch_diagram; share with share_diagram.`,
         });
     }));
     server.registerTool("update_diagram", {
         title: "Replace a diagram's content",
-        description: "Replace a diagram's whole document (nodes + edges, same fields as create_diagram) and/or rename it, retitle it or change its canvas, keeping its identity and sharing. Passing nodes replaces ALL nodes and edges (omitted edges are removed). For small edits — including restyling — prefer patch_diagram.",
+        description: "Replace a diagram's whole document (nodes + edges, same fields as create_diagram), replace or attach its Mermaid text, BPMN 2.0 XML or database-model `source`, rename it, retitle it, change its canvas and/or move it to a folder of your library (`folder`; null = the top level; only the owner can move) — keeping its identity and sharing. Passing nodes replaces ALL nodes and edges (omitted edges are removed). Passing `source` re-derives nodes and edges from the text (existing ones keep their place; new ones are placed). For small edits — including restyling — prefer patch_diagram.",
         inputSchema: {
             diagram: (0, shared_js_1.refArg)("Diagram"),
             name: zod_1.z.string().min(1).max(200).optional(),
@@ -89,15 +390,20 @@ const registerDiagramTools = (server, ctx) => {
             nodes: build_js_1.diagramInputSchema.shape.nodes.optional(),
             edges: build_js_1.diagramInputSchema.shape.edges.optional(),
             canvas: build_js_1.diagramInputSchema.shape.canvas,
+            source: sourceArg,
+            folder: zod_1.z.string().max(300).nullable().optional().describe('Move the diagram into this folder of your library (id, name or path); null = the top level'),
             autoLayout: zod_1.z.boolean().optional(),
             direction: directionArg,
             strictTypes: zod_1.z.boolean().optional(),
         },
         annotations: shared_js_1.IDEMPOTENT_WRITE,
-    }, (0, shared_js_1.guarded)(async ({ diagram, name, title, nodes, edges, canvas, autoLayout, direction, strictTypes }) => {
-        if (name === undefined && nodes === undefined && title === undefined && canvas === undefined) {
-            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name, title, canvas and/or nodes (+ edges).");
+    }, (0, shared_js_1.guarded)(async ({ diagram, name, title, nodes, edges, canvas, source, folder, autoLayout, direction, strictTypes }) => {
+        if (name === undefined && nodes === undefined && title === undefined && canvas === undefined && source === undefined && folder === undefined) {
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name, title, canvas, source, folder and/or nodes (+ edges).");
         }
+        if (nodes && source)
+            throw new errors_js_1.ToolInputError("CONFLICTING_INPUT", "Pass either nodes or source, not both.");
+        const targetFolder = folder ? await (0, lookups_js_1.resolveDiagramFolder)(ctx, folder) : null;
         const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
         if (!resolved.item.canEdit)
             throw new errors_js_1.ToolInputError("DIAGRAM_READ_ONLY", "You have read-only access to this diagram.");
@@ -105,33 +411,79 @@ const registerDiagramTools = (server, ctx) => {
         let document;
         let layoutNote;
         let warnings = [];
-        if (nodes) {
+        if (nodes && existing.source?.format === "database") {
+            // A database diagram stays one: the tables given become the new model.
+            const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? existing.meta.title, nodes, edges: edges ?? [], canvas: canvas ?? existing.canvas }, { strictTypes, existingId: existing.id, createdAt: existing.meta.createdAt, kind: "database" });
+            const previous = (0, callman_core_1.parseDatabaseModel)(existing.source.text).model;
+            const model = (0, callman_core_1.databaseModelFromDocument)({ ...built.document, source: undefined }, previous.dialect);
+            if (previous.connection)
+                model.connection = previous.connection;
+            const database = await databaseDocumentFromModel(model, existing, true);
+            document = database.document;
+            layoutNote = database.layoutNote;
+            warnings = [...built.warnings, "The database model was rewritten from the tables given; tables not in the input are gone. Prefer patch_diagram (addTable, addColumn, addRelationship …) for edits."];
+        }
+        else if (nodes && existing.source?.format === "bpmn") {
+            // A BPMN diagram stays BPMN: the new model is written as fresh XML.
+            const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? existing.meta.title, nodes, edges: edges ?? [], canvas: canvas ?? existing.canvas }, { strictTypes, existingId: existing.id, createdAt: existing.meta.createdAt, kind: "bpmn" });
+            const bpmn = bpmnDocumentFromModel(built.document, built.unpositionedNodeIds, existing);
+            document = bpmn.document;
+            layoutNote = bpmn.layoutNote;
+            warnings = [...built.warnings, "The BPMN XML was rewritten from the input; anything in the file that is not a flow node, flow, pool or lane was dropped. Prefer patch_diagram for edits."];
+        }
+        else if (nodes) {
+            assertEditableStructure(existing);
             const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? existing.meta.title, nodes, edges: edges ?? [], canvas: canvas ?? existing.canvas }, { strictTypes, existingId: existing.id, createdAt: existing.meta.createdAt });
             document = built.document;
             warnings = built.warnings;
             if (edges === undefined && existing.edges.length > 0) {
                 warnings.push(`edges was omitted, so the ${existing.edges.length} existing edge(s) were removed. Pass edges to keep connections, or use patch_diagram for partial edits.`);
             }
+            if (existing.source)
+                warnings.push(`The diagram's ${existing.source.format === "mermaid" ? "Mermaid" : existing.source.format} source was detached: nodes and edges were replaced from the input.`);
             if (autoLayout || built.unpositionedNodeIds.length > 0) {
                 const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
                 document = laid.document;
                 layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
             }
         }
+        else if (source) {
+            const fromSource = await documentFromSource(title ?? existing.meta.title, source.text, existing, direction, source.format);
+            document = fromSource.document;
+            layoutNote = fromSource.layoutNote;
+            warnings = fromSource.warnings;
+            if (title !== undefined || canvas !== undefined) {
+                document = {
+                    ...document,
+                    ...(canvas !== undefined ? { canvas: { ...document.canvas, ...canvas } } : {}),
+                    meta: { ...document.meta, ...(title !== undefined ? { title } : {}) },
+                };
+            }
+        }
         else if (title !== undefined || canvas !== undefined) {
             document = {
                 ...existing,
                 ...(canvas !== undefined ? { canvas: { ...existing.canvas, ...canvas } } : {}),
-                meta: { ...existing.meta, ...(title !== undefined ? { title } : {}), updatedAt: new Date().toISOString() },
+                meta: { ...existing.meta, ...(title !== undefined ? { title } : {}), updatedAt: now() },
             };
         }
-        const updated = await ctx.api.updateDiagram(resolved.item.id, { ...(name !== undefined ? { name: name.trim() } : {}), ...(document ? { document } : {}) });
+        const updated = await ctx.api.updateDiagram(resolved.item.id, {
+            ...(name !== undefined ? { name: name.trim() } : {}),
+            ...(document ? { document, ...(typeof existing.meta.revision === "number" ? { baseRevision: existing.meta.revision } : {}) } : {}),
+            ...(folder !== undefined ? { folderId: targetFolder?.item.id ?? null } : {}),
+        });
         ctx.invalidate("diagrams");
-        return (0, shared_js_1.ok)({ diagram: { ...(0, summarize_js_1.diagramListView)(updated), ...(0, summarize_js_1.diagramGraphView)(document ?? existing) }, warnings, ...(layoutNote ? { layout: layoutNote } : {}), resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)] });
+        const rows = await (0, lookups_js_1.diagramFolderRows)(ctx);
+        return (0, shared_js_1.ok)({
+            diagram: { ...(0, summarize_js_1.diagramListView)(updated), folder: (0, lookups_js_1.diagramFolderPath)(rows, updated.folderId), ...(0, summarize_js_1.diagramGraphView)(document ?? existing) },
+            warnings,
+            ...(layoutNote ? { layout: layoutNote } : {}),
+            resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved), ...(targetFolder?.annotation ? [(0, resolve_js_1.resolvedSummary)(folder, targetFolder)] : [])],
+        });
     }));
     server.registerTool("patch_diagram", {
         title: "Edit a diagram incrementally",
-        description: "Apply operations to a diagram without resending it: addNode, updateNode, removeNode (drops its edges), addEdge, updateEdge, removeEdge, setTitle. updateNode `changes` MERGE: style and data keys you pass change, a key set to null is removed. updateEdge can change semantic, color, label, arrows and ends. Moving a node (position/size/parent) re-routes its edges. `relayout`: none | new (place only new nodes, default) | all (re-run automatic layout). Call get_diagram (view: graph) first to see node ids and current styles.",
+        description: "Apply operations to a diagram without resending it: addNode, updateNode, removeNode (drops its edges, lifts its children out), addEdge, updateEdge, removeEdge, setTitle, moveNode, reparent, setEdgeRoute (routing, fixed sides, bends), reorder (stacking), setCanvas, group (wrap nodes in a container), ungroup, relayout (a hint: new | all). On a DATABASE diagram use the schema ops — addTable, renameTable, removeTable, setTableComment, addColumn, alterColumn, removeColumn, setPrimaryKey, addRelationship (source = child \"table.column\", target = parent), updateRelationship, removeRelationship, hideTable, showTable — read get_diagram view schema first. updateNode `changes` MERGE: style and data keys you pass change, a key set to null is removed. updateEdge can change semantic, color, label, arrows, sides and ends. Moving a node re-routes its edges. `relayout`: none | new (place only new nodes, default) | all (re-run automatic layout). Call get_diagram (view: graph) first to see node ids and current styles. Ops are documented in callman://docs/diagram-schema.",
         inputSchema: {
             diagram: (0, shared_js_1.refArg)("Diagram"),
             ops: zod_1.z.array(patch_js_1.diagramPatchOpSchema).min(1).max(200),
@@ -144,33 +496,169 @@ const registerDiagramTools = (server, ctx) => {
         const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
         if (!resolved.item.canEdit)
             throw new errors_js_1.ToolInputError("DIAGRAM_READ_ONLY", "You have read-only access to this diagram.");
-        const existing = loadDocument(resolved.item);
-        const patched = (0, patch_js_1.applyDiagramPatch)(existing, ops, { strictTypes });
-        let document = patched.document;
-        let layoutNote;
-        if (relayout === "all") {
-            const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
-            document = laid.document;
-            layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+        // Apply on the freshest copy; a 409 (someone saved meanwhile) reloads
+        // and reapplies once — ops describe intent, so they replay cleanly.
+        const attempt = async (record) => {
+            const existing = loadDocument(record);
+            assertEditableStructure(existing);
+            const patched = (0, patch_js_1.applyDiagramPatch)(existing, ops, { strictTypes });
+            let document = patched.document;
+            let layoutNote;
+            const wantsAll = relayout === "all" || patched.relayout?.scope === "all";
+            const layoutDirection = direction ?? patched.relayout?.direction;
+            const bpmn = document.source?.format === "bpmn";
+            const database = document.source?.format === "database";
+            if (wantsAll) {
+                // A process reads left to right; the BPMN XML follows the moves. An
+                // ERD packs unrelated tables into rows.
+                const laid = await (0, layout_js_1.layoutDocument)(document, { direction: layoutDirection ?? (bpmn || database ? "RIGHT" : undefined), ...(database ? { request: callman_core_1.DATABASE_LAYOUT_REQUEST } : {}) });
+                document = laid.document;
+                layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+            }
+            else if (relayout === "new" && patched.addedNodeIds.length > 0) {
+                const ids = patched.addedNodeIds.filter((id) => document.nodes.some((node) => node.id === id));
+                if (database) {
+                    document = (0, layout_js_1.placeDatabaseNodes)(document, ids);
+                    layoutNote = `Placed ${ids.length} new table(s) to the right of the existing ones.`;
+                }
+                else if (bpmn) {
+                    document = (0, callman_core_1.applyDiagramOps)(document, (0, callman_core_1.placeBpmnNodesOps)(document, ids), { now: now() }).doc;
+                    layoutNote = `Placed ${ids.length} new node(s) after their predecessors.`;
+                }
+                else {
+                    document = (0, layout_js_1.placeNewNodes)(document, ids);
+                    layoutNote = `Placed ${ids.length} new node(s) below the existing ones.`;
+                }
+            }
+            const updated = await ctx.api.updateDiagram(record.id, {
+                document,
+                ...(typeof existing.meta.revision === "number" ? { baseRevision: existing.meta.revision } : {}),
+            });
+            return { updated, document, patched, layoutNote };
+        };
+        let outcome;
+        let retried = false;
+        try {
+            outcome = await attempt(resolved.item);
         }
-        else if (relayout === "new" && patched.addedNodeIds.length > 0) {
-            document = (0, layout_js_1.placeNewNodes)(document, patched.addedNodeIds);
-            layoutNote = `Placed ${patched.addedNodeIds.length} new node(s) below the existing ones.`;
+        catch (error) {
+            if (!isConflict(error))
+                throw error;
+            retried = true;
+            outcome = await attempt(await ctx.api.getDiagram(resolved.item.id));
         }
-        const updated = await ctx.api.updateDiagram(resolved.item.id, { document });
         ctx.invalidate("diagrams");
+        const { updated, document, patched, layoutNote } = outcome;
         return (0, shared_js_1.ok)({
-            diagram: { ...(0, summarize_js_1.diagramListView)(updated), ...(0, summarize_js_1.diagramGraphView)(document) },
+            diagram: { ...(0, summarize_js_1.diagramListView)(updated), ...(0, summarize_js_1.diagramGraphView)(document), ...(document.source?.format === "database" ? { schema: (0, callman_core_1.databaseSchemaView)(document) } : {}) },
             applied: ops.length,
             added: patched.addedNodeIds,
             removedNodes: patched.removedNodeIds,
             removedEdges: patched.removedEdgeIds,
             ...(patched.reroutedEdgeIds.length > 0 ? { reroutedEdges: patched.reroutedEdgeIds } : {}),
-            warnings: patched.warnings,
+            ...(Object.keys(patched.idMap).length > 0 ? { idMap: patched.idMap } : {}),
+            warnings: [...patched.warnings, ...(retried ? ["The diagram had been saved by someone else meanwhile; your ops were re-applied on the newer version."] : [])],
             ...(layoutNote ? { layout: layoutNote } : {}),
             resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)],
         });
     }));
+    server.registerTool("introspect_database", {
+        title: "Read a database's schema through a connection",
+        description: "Read the database behind one of the workspace's database connections (list_connections, type: database): schemas, tables and views (MongoDB: collections with fields inferred from a sample), columns with types, nullability, defaults and comments, primary and unique keys, foreign keys with referential actions, indexes. Metadata only — never credentials, never data. Use `objectsOnly` to list names first, then read the tables you need; `create_diagram` with `fromConnection` draws the result as a Database Diagram in one step. Runs on the Callman backend, which must be able to reach the database.",
+        inputSchema: {
+            connection: zod_1.z.string().min(1).max(200).describe("Connection id or name"),
+            workspace: shared_js_1.workspaceArg,
+            schemas: zod_1.z.array(zod_1.z.string().min(1).max(120)).max(50).optional(),
+            tables: zod_1.z.array(zod_1.z.string().min(1).max(240)).max(2000).optional().describe('"schema.table" or "table"'),
+            includeViews: zod_1.z.boolean().optional(),
+            objectsOnly: zod_1.z.boolean().optional().describe("Names only (no columns / keys) — for a first look at a large database"),
+            maxTables: zod_1.z.number().int().min(1).max(20000).optional(),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ connection, workspace, schemas, tables, includeViews, objectsOnly, maxTables }) => {
+        const found = await findDatabaseConnection(ctx, workspace, connection);
+        const schema = await ctx.api.getConnectionSchema(found.ws.id, found.connection.id, schemaQuery({ schemas, tables, includeViews, objectsOnly, maxTables }));
+        return (0, shared_js_1.ok)({
+            connection: { id: found.connection.id, name: found.connection.name, provider: PROVIDER_LABEL[found.connection.provider] ?? found.connection.provider, workspace: (0, lookups_js_1.workspaceTag)(found.ws) },
+            schema,
+            ...(schema.truncated ? { note: "The database has more tables than the cap; pass schemas/tables to narrow the read or raise maxTables." } : {}),
+        });
+    }));
+    // ── library folders (private to the token's owner) ──────────────────
+    const folderView = (row) => ({ id: row.id, name: row.name, parentId: row.parentId, path: row.path });
+    server.registerTool("create_diagram_folder", {
+        title: "Create a diagram folder",
+        description: "Create a folder in your diagram library, optionally inside a parent folder (id, name or path). Folders are yours alone (nobody else sees them; a diagram you share shows at the top level for others), nest up to 8 levels, and sibling names are unique — an existing folder with that name is returned instead of a duplicate. File diagrams with create_diagram / update_diagram `folder`.",
+        inputSchema: {
+            name: zod_1.z.string().min(1).max(120),
+            parent: zod_1.z.string().max(300).optional().describe("Parent folder id, name or path; omit for the top level"),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ name, parent }) => {
+        const parentFolder = parent ? await (0, lookups_js_1.resolveDiagramFolder)(ctx, parent) : null;
+        const rows = await (0, lookups_js_1.diagramFolderRows)(ctx);
+        const trimmed = name.trim();
+        const sibling = rows.find((row) => row.parentId === (parentFolder?.item.id ?? null) && (0, ids_js_1.normalizeName)(row.name) === (0, ids_js_1.normalizeName)(trimmed));
+        if (sibling) {
+            return (0, shared_js_1.ok)({ folder: folderView(sibling), existed: true, note: "A folder with that name already exists there — returned instead of creating a duplicate." });
+        }
+        const created = await ctx.api.createDiagramFolder({ name: trimmed, parentId: parentFolder?.item.id ?? null });
+        ctx.invalidate("diagram-folders");
+        const path = parentFolder ? `${parentFolder.item.path}/${created.name}` : created.name;
+        return (0, shared_js_1.ok)({
+            folder: { id: created.id, name: created.name, parentId: created.parentId, path },
+            ...(parentFolder?.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(parent, parentFolder)] } : {}),
+        });
+    }));
+    server.registerTool("update_diagram_folder", {
+        title: "Rename or move a diagram folder",
+        description: "Rename a folder of your diagram library and/or move it under another folder (parent: null = the top level). A folder cannot be moved into itself or one of its subfolders.",
+        inputSchema: {
+            folder: (0, shared_js_1.refArg)("Diagram folder", "(or path)"),
+            name: zod_1.z.string().min(1).max(120).optional(),
+            parent: zod_1.z.string().max(300).nullable().optional().describe("New parent folder (id, name or path); null = the top level"),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ folder, name, parent }) => {
+        if (name === undefined && parent === undefined)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name and/or parent.");
+        const target = await (0, lookups_js_1.resolveDiagramFolder)(ctx, folder);
+        const parentFolder = parent ? await (0, lookups_js_1.resolveDiagramFolder)(ctx, parent) : null;
+        if (parentFolder && (parentFolder.item.id === target.item.id || parentFolder.item.path.startsWith(`${target.item.path}/`))) {
+            throw new errors_js_1.ToolInputError("FOLDER_CYCLE", "A folder cannot be moved into itself or one of its subfolders.");
+        }
+        const updated = await ctx.api.updateDiagramFolder(target.item.id, {
+            ...(name !== undefined ? { name: name.trim() } : {}),
+            ...(parent !== undefined ? { parentId: parentFolder?.item.id ?? null } : {}),
+        });
+        ctx.invalidate("diagram-folders");
+        const rows = await (0, lookups_js_1.diagramFolderRows)(ctx);
+        const row = rows.find((entry) => entry.id === updated.id);
+        return (0, shared_js_1.ok)({
+            folder: row ? folderView(row) : { id: updated.id, name: updated.name, parentId: updated.parentId, path: updated.name },
+            resolved: [(0, resolve_js_1.resolvedSummary)(folder, target), ...(parentFolder?.annotation ? [(0, resolve_js_1.resolvedSummary)(parent, parentFolder)] : [])],
+        });
+    }));
+    server.registerTool("delete_diagram_folder", {
+        title: "Delete a diagram folder",
+        description: "Delete a folder of your diagram library and its subfolders. No diagram is deleted: everything inside moves to the deleted folder's parent. Confirm with the user first.",
+        inputSchema: { folder: (0, shared_js_1.refArg)("Diagram folder", "(or path)"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ folder, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a diagram folder");
+        const target = await (0, lookups_js_1.resolveDiagramFolder)(ctx, folder, { exact: true });
+        const result = await ctx.api.deleteDiagramFolder(target.item.id);
+        ctx.invalidate("diagram-folders");
+        ctx.invalidate("diagrams");
+        const rows = await (0, lookups_js_1.diagramFolderRows)(ctx);
+        return (0, shared_js_1.ok)({
+            deleted: folderView(target.item),
+            deletedFolderCount: result.deletedFolderIds.length,
+            movedDiagramCount: result.movedDiagramCount,
+            movedTo: (0, lookups_js_1.diagramFolderPath)(rows, result.movedToFolderId) ?? "the top level",
+            resolved: [(0, resolve_js_1.resolvedSummary)(folder, target)],
+        });
+    }));
     server.registerTool("delete_diagram", {
         title: "Delete a diagram",
         description: "Delete a diagram you own. Permanent — confirm with the user first.",