@kezlahd/atlas-mcp 0.1.0 → 0.2.0

package/dist/index.js

@@ -20,11 +20,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { apiRequest, ApiError, resolveConfig } from "./api.js";
 import { SECTION_CATALOG, findSection } from "./section-catalog.js";
+import { READ_ACHIEVEMENTS_TOOL, readAchievements, } from "./tools/read-achievements.js";
 /* ─── Tool definitions ─────────────────────────────────────────────── */
 const TOOLS = [
     {
         name: "atlas_list_docs",
-        description: "List docs in the current Atlas workspace. Returns { docs, next_cursor }. Use this to find a docId before pulling a template. To page through more, pass the previous next_cursor back in as `cursor`.",
+        description: "List docs in the current Atlas workspace. Returns { docs, next_cursor }. Use this to find a docId before pulling a template. To page through more, pass the previous next_cursor back in as `cursor`. Pass `deleted: true` to list the Recently deleted bucket instead of live docs.",
         inputSchema: {
             type: "object",
             properties: {
@@ -38,7 +39,114 @@ const TOOLS = [
                     type: "string",
                     description: "Opaque next_cursor from a previous response. Omit for the first page.",
                 },
+                deleted: {
+                    type: "boolean",
+                    description: "When true, list ONLY soft-deleted docs (the Recently deleted bucket). Default: false — live docs only.",
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_doc_create",
+        description: "Create a new doc in the current workspace. Returns the fresh doc's id + etag so you can pipe straight into atlas_update_section / atlas_update_template. Default kind is 'template' (the doc-crafter surface); pass 'freeform' for a Tiptap doc. Optional folder_id / shoot_id slot the doc into the same tree the web UI uses. Pass `preset_id` to stamp a server-side preset skeleton (see atlas_list_doc_presets for the catalogue) — mutually exclusive with hand-rolled template_content (template_content wins if both are set).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Human-readable title (≤ 200 chars)." },
+                doc_kind: {
+                    type: "string",
+                    enum: ["template", "freeform"],
+                    description: "Defaults to 'template' if omitted.",
+                },
+                folder_id: {
+                    type: "string",
+                    description: "Optional doc_folders id to nest under.",
+                },
+                shoot_id: {
+                    type: "string",
+                    description: "Optional shoots id — attach the doc to a shoot.",
+                },
+                template_content: {
+                    type: "object",
+                    description: "Optional starter { cover?, docSettings?, sections: [] } payload. Omit to create empty and fill later.",
+                },
+                preset_id: {
+                    type: "string",
+                    description: "Optional preset id from atlas_list_doc_presets. Stamps that preset's section skeleton into the new doc. Ignored when template_content is also supplied.",
+                },
+            },
+            required: ["title"],
+        },
+    },
+    {
+        name: "atlas_list_doc_presets",
+        description: "List every doc preset available in Atlas (shoot-day, deliverable, planning templates). Returns the full catalogue with each preset's id, label, blurb, category, estimated fill time, default title, and the ordered list of sections it'll stamp. Use this to show the user options before calling atlas_create_doc or atlas_create_doc_from_preset.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "atlas_create_doc_from_preset",
+        description: "Convenience wrapper over atlas_doc_create — creates a new doc and stamps the chosen preset's section skeleton in one call. Use when the user says 'create me a model shoot day doc' or similar. Title defaults to the preset's defaultTitle; override to taste. Returns the created doc record (same shape as atlas_doc_create).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                preset_id: {
+                    type: "string",
+                    description: "Preset id from atlas_list_doc_presets (e.g. 'model-shoot-day', 'brand-narrative-drop').",
+                },
+                title: {
+                    type: "string",
+                    description: "Override for the doc title. Defaults to the preset's defaultTitle when omitted.",
+                },
+                folder_id: {
+                    type: "string",
+                    description: "Optional doc_folders id to nest under.",
+                },
+                shoot_id: {
+                    type: "string",
+                    description: "Optional shoots id — attach the doc to a shoot.",
+                },
+            },
+            required: ["preset_id"],
+        },
+    },
+    {
+        name: "atlas_doc_delete",
+        description: "Soft-delete a doc — moves it to the workspace's Recently deleted bucket for 30 days. Reversible with atlas_restore_doc. Pass `purge: true` to hard-delete forever instead (requires the doc is already soft-deleted). Destructive — always confirm with the user before calling. Returns { ok, id, title, deleted, recoverable_until? } or { ok, id, purged: true }.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docId: { type: "string", description: "Doc id from atlas_list_docs." },
+                purge: {
+                    type: "boolean",
+                    description: "When true, hard-delete forever (requires the doc is already soft-deleted). Default: false — soft-delete only.",
+                },
+            },
+            required: ["docId"],
+        },
+    },
+    {
+        name: "atlas_restore_doc",
+        description: "Restore a soft-deleted doc from the Recently deleted bucket. Requires templates:update. Silent no-op on a live doc (responds with restored:false).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docId: { type: "string", description: "Doc id from atlas_list_docs?deleted=1." },
+            },
+            required: ["docId"],
+        },
+    },
+    {
+        name: "atlas_purge_doc",
+        description: "Hard-delete a soft-deleted doc — permanent, no 30-day undo. Requires the doc is already in the trash (returns 409 otherwise, prompting you to atlas_doc_delete first). Always double-confirm with the user before calling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docId: { type: "string", description: "Doc id (must already be soft-deleted)." },
             },
+            required: ["docId"],
         },
     },
     {
@@ -65,7 +173,7 @@ const TOOLS = [
     },
     {
         name: "atlas_update_section",
-        description: "Edit a single section by id. Fetches current template, splices in the new section.data (and optionally style), writes back with the fresh etag. Safer than atlas_update_template for scoped edits — won't touch other sections.",
+        description: "Edit a single section by id. Uses the section-scoped PATCH endpoint — the server merges just this section into template_content, so concurrent Claude sessions editing different sections no longer clobber each other. `data` replaces the section's data object; `style` merges over existing style keys.",
         inputSchema: {
             type: "object",
             properties: {
@@ -79,8 +187,12 @@ const TOOLS = [
                     type: "object",
                     description: "Optional section.style overrides (titleFont, titleSize, breakBefore, etc). Merged into existing style.",
                 },
+                hidden: {
+                    type: "boolean",
+                    description: "Optional — mark section hidden or visible.",
+                },
             },
-            required: ["docId", "sectionId", "data"],
+            required: ["docId", "sectionId"],
         },
     },
     {
@@ -178,7 +290,7 @@ const TOOLS = [
     },
     {
         name: "atlas_list_gear",
-        description: "List gear items (brand, name, quantity, photo) in the workspace. Returns { items, next_cursor }. Each item has a 1-hour signed image_url when it has an image. To page through more, pass the previous next_cursor back in as `cursor`.",
+        description: "List gear items (brand, name, quantity, photo) in the workspace. Returns { items, next_cursor }. Each item has a 1-hour signed image_url when it has an image. To page through more, pass the previous next_cursor back in as `cursor`. Pass `deleted: true` to list the Recently deleted bucket instead of live gear.",
         inputSchema: {
             type: "object",
             properties: {
@@ -187,6 +299,10 @@ const TOOLS = [
                     type: "string",
                     description: "Opaque next_cursor from a previous response. Omit for the first page.",
                 },
+                deleted: {
+                    type: "boolean",
+                    description: "When true, list ONLY soft-deleted gear (the Recently deleted bucket). Default: false — live gear only.",
+                },
             },
         },
     },
@@ -234,7 +350,33 @@ const TOOLS = [
     },
     {
         name: "atlas_delete_gear",
-        description: "Delete a gear item by id.",
+        description: "Soft-delete a gear item — moves it to the Recently deleted bucket for 30 days. Reversible with atlas_restore_gear. Pass `purge: true` to hard-delete forever (requires the item is already soft-deleted). Always confirm with the user before calling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                gearId: { type: "string" },
+                purge: {
+                    type: "boolean",
+                    description: "When true, hard-delete forever (requires the item is already soft-deleted). Default: false — soft-delete only.",
+                },
+            },
+            required: ["gearId"],
+        },
+    },
+    {
+        name: "atlas_restore_gear",
+        description: "Restore a soft-deleted gear item from the Recently deleted bucket. Requires gear:update.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                gearId: { type: "string", description: "Gear id (from atlas_list_gear with deleted:true)." },
+            },
+            required: ["gearId"],
+        },
+    },
+    {
+        name: "atlas_purge_gear",
+        description: "Hard-delete a soft-deleted gear item — permanent, no undo. Requires the item is already in the trash (409 otherwise). Always double-confirm with the user.",
         inputSchema: {
             type: "object",
             properties: {
@@ -262,188 +404,1394 @@ const TOOLS = [
         },
     },
     {
-        name: "atlas_rename_file",
-        description: "Rename a workspace file. Requires files:rename. Pass just the new filename — the workspace prefix + folder are preserved. Extension changes are refused server-side.",
+        name: "atlas_list_shots",
+        description: "List shot items (still/video with reference photo + linked gear) in the workspace. Requires shots:list. Returns { items, next_cursor }. Each item has a 1-hour signed image_url when it has an image and a gear_ids array of gear_items UUIDs. To page through more, pass the previous next_cursor back in as `cursor`. Pass `deleted: true` to list the Recently deleted bucket instead of live shots.",
         inputSchema: {
             type: "object",
             properties: {
-                path: { type: "string", description: "Full storage key returned by atlas_list_files." },
-                new_name: { type: "string", description: "New filename only, no folder path. Keep the same extension." },
+                limit: { type: "number", description: "Default 50, max 500." },
+                cursor: {
+                    type: "string",
+                    description: "Opaque next_cursor from a previous response. Omit for the first page.",
+                },
+                deleted: {
+                    type: "boolean",
+                    description: "When true, list ONLY soft-deleted shots (the Recently deleted bucket). Default: false — live shots only.",
+                },
             },
-            required: ["path", "new_name"],
         },
     },
     {
-        name: "atlas_list_revisions",
-        description: "List revision history for a doc template. Requires templates:list-revisions. Returns revisions newest first with id, source (ui/api/cli), author, based_on_updated_at, created_at.",
+        name: "atlas_add_shot",
+        description: "Add a single shot item. Requires shots:add. For many items at once, use atlas_import_shots. `gear_ids` must resolve to gear_items in this workspace — unknown ids surface as a 400 with the offending ids listed.",
         inputSchema: {
             type: "object",
             properties: {
-                docId: { type: "string", description: "Doc id from atlas_list_docs." },
-                limit: { type: "number", description: "Max rows (default 50, max 200)." },
+                name: { type: "string", description: "Required. ≤ 160 chars." },
+                kind: {
+                    type: "string",
+                    enum: ["still", "video"],
+                    description: "Defaults to 'still' when omitted.",
+                },
+                notes: { type: "string", description: "Optional library-general notes. ≤ 2000 chars." },
+                image_path: {
+                    type: "string",
+                    description: "Optional. Storage key from atlas_upload_file. Must be in this workspace's prefix.",
+                },
+                gear_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional. gear_items UUIDs to link to this shot (from atlas_list_gear).",
+                },
             },
-            required: ["docId"],
+            required: ["name"],
         },
     },
     {
-        name: "atlas_restore_revision",
-        description: "Restore a doc template to an earlier revision. Requires templates:restore-revision. Overwrites the current template_content. The pre-restore state is journaled first so the restore is itself reversible.",
+        name: "atlas_update_shot",
+        description: "Update an existing shot item. Requires shots:update. Only provided fields are patched — send just the fields you want to change. Empty string on `image_path` or `notes` clears them. `gear_ids` replaces the existing link array (pass [] to clear all links).",
         inputSchema: {
             type: "object",
             properties: {
-                docId: { type: "string", description: "Doc id from atlas_list_docs." },
-                revisionId: { type: "string", description: "Revision id from atlas_list_revisions." },
+                shotId: { type: "string", description: "Shot item id from atlas_list_shots." },
+                name: { type: "string", description: "New shot name (≤ 160 chars)." },
+                kind: {
+                    type: "string",
+                    enum: ["still", "video"],
+                },
+                notes: {
+                    type: "string",
+                    description: "New library-general notes (≤ 2000 chars). Empty string clears.",
+                },
+                image_path: {
+                    type: "string",
+                    description: "Storage path from atlas_upload_file. Must live in this workspace's prefix. Empty string clears the image.",
+                },
+                gear_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Full replacement array of gear_items UUIDs. Unknown ids for the workspace return a 400.",
+                },
             },
-            required: ["docId", "revisionId"],
+            required: ["shotId"],
         },
     },
-];
-/* ─── Server setup ─────────────────────────────────────────────────── */
-const server = new Server({ name: "atlas-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: TOOLS,
-}));
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    const name = req.params.name;
-    const args = (req.params.arguments ?? {});
-    try {
-        const result = await dispatch(name, args);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        return {
-            isError: true,
-            content: [{ type: "text", text: `error: ${msg}` }],
-        };
-    }
-});
-async function dispatch(name, args) {
-    switch (name) {
-        case "atlas_list_docs":
-            return listDocs(args);
-        case "atlas_get_template":
-            return getTemplate(args);
-        case "atlas_list_sections":
-            return listSections(args);
-        case "atlas_update_section":
-            return updateSection(args);
-        case "atlas_list_files":
-            return listFiles(args);
-        case "atlas_upload_file":
-            return uploadFile(args);
-        case "atlas_get_file_url":
-            return getFileUrl(args);
-        case "atlas_set_file_alt":
-            return setFileAlt(args);
-        case "atlas_delete_file":
-            return deleteFile(args);
-        case "atlas_list_gear":
-            return listGear(args);
-        case "atlas_add_gear":
-            return addGear(args);
-        case "atlas_import_gear":
-            return importGear(args);
-        case "atlas_delete_gear":
-            return deleteGear(args);
-        case "atlas_update_template":
-            return updateTemplate(args);
-        case "atlas_describe_section_type":
-            return describeSectionType(args);
-        case "atlas_update_gear":
-            return updateGear(args);
-        case "atlas_rename_file":
-            return renameFile(args);
-        case "atlas_list_revisions":
-            return listRevisions(args);
-        case "atlas_restore_revision":
-            return restoreRevision(args);
-        default:
-            throw new Error(`Unknown tool: ${name}`);
-    }
-}
-/* ─── Tool implementations ─────────────────────────────────────────── */
-async function listDocs(args) {
-    const cfg = resolveConfig();
-    const query = {};
-    if (typeof args.kind === "string")
-        query.kind = args.kind;
-    if (typeof args.limit === "number")
-        query.limit = args.limit;
-    if (typeof args.cursor === "string")
-        query.cursor = args.cursor;
-    const { data } = await apiRequest(cfg, "/api/v1/docs", { query });
-    return data;
-}
-async function getTemplate(args) {
-    const cfg = resolveConfig();
-    const docId = requireString(args, "docId");
-    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`);
-    return data;
-}
-async function listSections(args) {
-    const tpl = await getTemplate(args);
-    const sections = tpl.template_content?.sections ?? [];
-    const summary = sections.map((s) => ({
-        id: s.id,
-        type: s.type,
-        // Best-effort title extraction — most sections stash a title on data.title.
-        title: (s.data && typeof s.data.title === "string"
-            ? s.data.title
-            : null) ?? "",
-        hidden: !!s.hidden,
-    }));
-    return { docId: tpl.id, title: tpl.title, section_count: summary.length, sections: summary };
-}
-async function updateSection(args) {
-    const cfg = resolveConfig();
-    const docId = requireString(args, "docId");
-    const sectionId = requireString(args, "sectionId");
-    const newData = args.data;
-    if (!isRecord(newData))
-        throw new Error("`data` must be an object.");
-    const newStyle = isRecord(args.style) ? args.style : null;
-    const current = await getTemplate({ docId });
-    const template = current.template_content;
-    const sections = template.sections ?? [];
-    const idx = sections.findIndex((s) => s.id === sectionId);
-    if (idx === -1) {
-        throw new Error(`Section '${sectionId}' not found in doc '${docId}'. Call atlas_list_sections to see current section ids.`);
-    }
-    const patched = { ...sections[idx], data: newData };
-    if (newStyle) {
-        patched.style = { ...(sections[idx].style ?? {}), ...newStyle };
-    }
-    const nextSections = [...sections];
-    nextSections[idx] = patched;
-    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`, {
-        method: "PUT",
-        body: { template_content: { ...template, sections: nextSections } },
-        ifMatch: current.etag,
-    });
-    return {
-        updated_section: sectionId,
-        etag: data.etag,
-        updated_at: data.updated_at,
-    };
-}
-async function updateTemplate(args) {
-    const cfg = resolveConfig();
-    const docId = requireString(args, "docId");
-    const templateContent = args.template_content;
-    if (!isRecord(templateContent)) {
-        throw new Error("`template_content` must be an object matching TemplateContent shape.");
-    }
-    const title = typeof args.title === "string" ? args.title : undefined;
-    // Get-then-put for etag freshness.
-    const current = await getTemplate({ docId });
-    try {
-        const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`, {
-            method: "PUT",
-            body: { template_content: templateContent, ...(title ? { title } : {}) },
-            ifMatch: current.etag,
+    {
+        name: "atlas_delete_shot",
+        description: "Soft-delete a shot item — moves it to the Recently deleted bucket for 30 days. Reversible with atlas_restore_shot. Pass `purge: true` to hard-delete forever (requires the item is already soft-deleted). Reference image in workspace-photos is preserved. Requires shots:delete. Always confirm with the user.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shotId: { type: "string" },
+                purge: {
+                    type: "boolean",
+                    description: "When true, hard-delete forever (requires the item is already soft-deleted). Default: false — soft-delete only.",
+                },
+            },
+            required: ["shotId"],
+        },
+    },
+    {
+        name: "atlas_restore_shot",
+        description: "Restore a soft-deleted shot item from the Recently deleted bucket. Requires shots:update.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shotId: { type: "string" },
+            },
+            required: ["shotId"],
+        },
+    },
+    {
+        name: "atlas_purge_shot",
+        description: "Hard-delete a soft-deleted shot item — permanent, no undo. Requires the item is already in the trash (409 otherwise). Always double-confirm with the user.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shotId: { type: "string" },
+            },
+            required: ["shotId"],
+        },
+    },
+    {
+        name: "atlas_import_shots",
+        description: "Bulk-import shot rows in one shot. Requires shots:import. Faster than calling atlas_add_shot per item. `mode: 'replace'` clears the workspace's shot library before inserting; `'append'` (default) adds on top. The endpoint only imports name/kind/notes — wire gear links up per-row via atlas_update_shot after the bulk insert.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mode: { type: "string", enum: ["append", "replace"] },
+                rows: {
+                    type: "array",
+                    description: "Up to 2000 rows. Each: { name (required), kind?, notes? }.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            kind: { type: "string", enum: ["still", "video"] },
+                            notes: { type: "string" },
+                        },
+                        required: ["name"],
+                    },
+                },
+            },
+            required: ["rows"],
+        },
+    },
+    {
+        name: "atlas_list_events",
+        description: "List calendar events (shoots) in the workspace. Requires events:list. Returns { items, next_cursor }. Each item is a ShootSummary: id, title, starts_at, ends_at, all_day, location, shoot_type, colour_key, colour_hex, status, team_count, objectives_total/done. Filter by date range with `from`/`to` (ISO 8601), by status, or by colour_key. To page through more, pass the previous next_cursor back in as `cursor`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Default 50, max 500." },
+                cursor: {
+                    type: "string",
+                    description: "Opaque next_cursor from a previous response. Omit for the first page.",
+                },
+                from: {
+                    type: "string",
+                    description: "ISO 8601 lower bound on starts_at (inclusive).",
+                },
+                to: {
+                    type: "string",
+                    description: "ISO 8601 upper bound on starts_at (inclusive).",
+                },
+                status: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: ["planned", "confirmed", "wrapped", "cancelled"],
+                    },
+                    description: "Filter to these statuses only.",
+                },
+                colour: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: ["rose", "amber", "sky", "violet", "lime", "stone"],
+                    },
+                    description: "Filter to these colour keys only.",
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_get_event",
+        description: "Fetch a single calendar event + its crew assignments. Requires events:get. Returns { event, assignments }. Each assignment carries the workspace member's display_name, email, shoot_role, responsibilities[] and per-assignment notes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "Event id from atlas_list_events.",
+                },
+            },
+            required: ["eventId"],
+        },
+    },
+    {
+        name: "atlas_create_event",
+        description: "Schedule a new calendar event. Requires events:create. `title` and `starts_at` (ISO 8601) are required. Timed events must be at least 30 minutes — the API rejects shorter durations. Defaults: `status` = 'planned', `all_day` = false. Returns { event: ShootSummary }.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Event title. Required." },
+                starts_at: {
+                    type: "string",
+                    description: "ISO 8601 start timestamp. Required.",
+                },
+                ends_at: { type: "string", description: "ISO 8601 end timestamp." },
+                all_day: { type: "boolean", description: "Mark as an all-day event." },
+                location: { type: "string" },
+                shoot_type: {
+                    type: "string",
+                    description: "Free-form shoot type label.",
+                },
+                colour_key: {
+                    type: "string",
+                    enum: ["rose", "amber", "sky", "violet", "lime", "stone"],
+                },
+                colour_hex: {
+                    type: "string",
+                    description: "Custom colour hex, e.g. #ff8899.",
+                },
+                status: {
+                    type: "string",
+                    enum: ["planned", "confirmed", "wrapped", "cancelled"],
+                },
+                notes: { type: "string", description: "Internal notes." },
+                description: { type: "string", description: "Public description." },
+            },
+            required: ["title", "starts_at"],
+        },
+    },
+    {
+        name: "atlas_update_event",
+        description: "Patch a calendar event. Requires events:update. Only provided fields are updated — send just the fields you want to change. Same validation as create (timed events ≥ 30 minutes).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "Event id from atlas_list_events.",
+                },
+                title: { type: "string" },
+                starts_at: { type: "string", description: "New ISO 8601 start." },
+                ends_at: { type: "string", description: "New ISO 8601 end." },
+                all_day: { type: "boolean" },
+                location: { type: "string" },
+                shoot_type: { type: "string" },
+                colour_key: {
+                    type: "string",
+                    enum: ["rose", "amber", "sky", "violet", "lime", "stone"],
+                },
+                colour_hex: { type: "string" },
+                status: {
+                    type: "string",
+                    enum: ["planned", "confirmed", "wrapped", "cancelled"],
+                },
+                notes: { type: "string" },
+                description: { type: "string" },
+            },
+            required: ["eventId"],
+        },
+    },
+    {
+        name: "atlas_delete_event",
+        description: "Permanently delete a calendar event. Requires events:delete. Permanent — no trash for events, no atlas_restore_event. Always confirm with the user before calling; there is no undo.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "Event id from atlas_list_events.",
+                },
+            },
+            required: ["eventId"],
+        },
+    },
+    {
+        name: "atlas_assign_event",
+        description: "Assign a workspace member to a calendar event. Requires events:assign. Idempotent — assigning the same user twice returns the existing assignment row rather than duplicating. Returns { assignment }.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "Event id from atlas_list_events.",
+                },
+                user_id: {
+                    type: "string",
+                    description: "Workspace member user id. Required.",
+                },
+                shoot_role: {
+                    type: "string",
+                    description: "Role label (e.g. Photographer, Assistant).",
+                },
+                responsibilities: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Responsibility bullets for this assignment.",
+                },
+                notes: {
+                    type: "string",
+                    description: "Per-assignment notes.",
+                },
+            },
+            required: ["eventId", "user_id"],
+        },
+    },
+    {
+        name: "atlas_unassign_event",
+        description: "Remove a crew assignment from a calendar event. Requires events:assign. Confirm with the user before calling — unassigning is immediate.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "Event id from atlas_list_events.",
+                },
+                assignmentId: {
+                    type: "string",
+                    description: "Assignment id from atlas_get_event's assignments[].",
+                },
+            },
+            required: ["eventId", "assignmentId"],
+        },
+    },
+    {
+        name: "atlas_rename_file",
+        description: "Rename a workspace file. Requires files:rename. Pass just the new filename — the workspace prefix + folder are preserved. Extension changes are refused server-side.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Full storage key returned by atlas_list_files." },
+                new_name: { type: "string", description: "New filename only, no folder path. Keep the same extension." },
+            },
+            required: ["path", "new_name"],
+        },
+    },
+    {
+        name: "atlas_list_revisions",
+        description: "List revision history for a doc template. Requires templates:list-revisions. Returns revisions newest first with id, source (ui/api/cli), author, based_on_updated_at, created_at.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docId: { type: "string", description: "Doc id from atlas_list_docs." },
+                limit: { type: "number", description: "Max rows (default 50, max 200)." },
+            },
+            required: ["docId"],
+        },
+    },
+    {
+        name: "atlas_restore_revision",
+        description: "Restore a doc template to an earlier revision. Requires templates:restore-revision. Overwrites the current template_content. The pre-restore state is journaled first so the restore is itself reversible.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docId: { type: "string", description: "Doc id from atlas_list_docs." },
+                revisionId: { type: "string", description: "Revision id from atlas_list_revisions." },
+            },
+            required: ["docId", "revisionId"],
+        },
+    },
+    {
+        name: "atlas_whoami",
+        description: "Describe the current token — workspace, user, granted scopes, expiry. Requires no specific scope. Call this before attempting a mutation if you're unsure which capabilities the token has; a missing scope will surface as an obvious gap in the returned scopes array rather than a 403 mid-flight.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "atlas_verify_connection",
+        description: "Prove to Atlas that the Claude Desktop MCP config actually works — call this ONCE at the end of the onboarding walkthrough. Stamps workspace_members.onboarding.mcp_verified_at for the caller so the home page's Connect-Claude step auto-completes. Distinct from atlas_whoami: only this endpoint ticks the walkthrough's final phase, so accidental whoami calls won't false-positive the setup flow.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_list_metafield_definitions",
+        description: "List every metafield display definition in the workspace. Definitions tell Atlas how to render each Shopify metafield on the product page. Returns { definitions: [{ id, namespace, key, label, description, section, display_style, ... }] }.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_suggest_metafields",
+        description: "Return the shipped preset library — a curated set of Shopify metafields worth adding to a store (secondary gallery, size chart, composition, care, drop badge, etc.) with sensible display style + section pre-picked. Use this to see the full menu before deciding what to create.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_scan_shopify_metafields",
+        description: "Scan the workspace's live Shopify store (first 40 products) and return every unique metafield actually present with a sample value + product count. Great to call before creating definitions so you know what real data exists.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_create_metafield_definition",
+        description: "Create or upsert a metafield display definition. Two modes: (a) fast path — pass `preset` set to an id from atlas_suggest_metafields; (b) manual — pass namespace, key, label, section, display_style. Upserts on (workspace, namespace, key) so calling with the same coordinates edits the existing row.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                preset: {
+                    type: "string",
+                    description: "Preset id from atlas_suggest_metafields (fast path).",
+                },
+                namespace: { type: "string", description: "Shopify namespace (e.g. custom)." },
+                key: { type: "string", description: "Shopify key (e.g. size_chart)." },
+                label: { type: "string", description: "Display label shown to team members." },
+                description: { type: "string", description: "Optional helper text." },
+                section: {
+                    type: "string",
+                    enum: ["overview", "gallery", "sizing", "care", "details", "specs", "custom"],
+                    description: "Where on the product page this metafield renders.",
+                },
+                display_style: {
+                    type: "string",
+                    enum: [
+                        "text",
+                        "rich_text",
+                        "bullet_list",
+                        "image",
+                        "image_gallery",
+                        "video",
+                        "file_download",
+                        "badge",
+                        "badge_list",
+                        "key_value_table",
+                        "measurement_table",
+                        "specs_grid",
+                        "number_with_unit",
+                        "rating",
+                        "link",
+                        "link_list",
+                        "color_swatches",
+                        "product_reference",
+                    ],
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_delete_metafield_definition",
+        description: "Delete a metafield definition by id (from atlas_list_metafield_definitions). Shopify data unaffected — this only removes Atlas' display rule for the metafield.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+        },
+    },
+    {
+        name: "atlas_list_loyalty_tiers",
+        description: "Return the current loyalty tier ladder (Diamond / Gold / Silver / Bronze or workspace-custom). Sorted highest sort_order first; `source: \"defaults\"` when the workspace inherits the Atlas ladder. Safe read-only call — no confirmation needed before invoking.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_set_loyalty_tiers",
+        description: "Atomically replace the workspace loyalty tier ladder. **Destructive** — server deletes every existing tier for the workspace and inserts the payload, so a partial or wrong payload wipes real merchant config. ALWAYS call atlas_list_loyalty_tiers first, show the user a diff (old vs. new), and only PUT after they confirm. Requires an API token minted by an admin/owner.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tiers: {
+                    type: "array",
+                    description: "Full replacement array. Each entry: { key: string (unique), name: string, minSpendCents: int (>=0), minOrders: int|null, metallic: 'diamond'|'gold'|'silver'|'bronze'|null, sortOrder: int (higher = higher priority) }. Pass [] to clear the ladder — but prefer atlas_reset_loyalty_tiers for that.",
+                    items: { type: "object" },
+                },
+            },
+            required: ["tiers"],
+        },
+    },
+    {
+        name: "atlas_reset_loyalty_tiers",
+        description: "Clear the workspace's tier ladder so it falls back to Atlas defaults. Destructive — confirm with the user first. Requires admin/owner.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_get_analytics_prefs",
+        description: "Read the workspace analytics defaults — excluded order tags, excluded Shopify financial statuses, excluded customer-level tags, and the three customer-level boolean flags (exclude_non_subscribers, exclude_guest_checkouts, exclude_unverified_emails). Applied to every roll-up on the customer intelligence page. Safe read-only call.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "atlas_set_analytics_prefs",
+        description: "Update the workspace analytics defaults. Patch semantics — omitted fields are unchanged; pass an empty array or explicit `false` to clear. Common flow: user says 'exclude non-subscribers from analytics' → call atlas_get_analytics_prefs, show current state, then PUT with exclude_non_subscribers=true after confirmation. Requires admin/owner. Financial statuses must be Shopify's canonical set: voided, refunded, partially_refunded, pending, paid.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                excluded_tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Order tags to strip from analytics (e.g. ['PR', 'UGC']).",
+                },
+                excluded_statuses: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Shopify financial statuses to strip. Typical: voided, refunded, partially_refunded, pending.",
+                },
+                excluded_customer_tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Shopify customer-level tags to hide (e.g. ['wholesale', 'staff']). Distinct from order tags — matches on the customer record.",
+                },
+                exclude_non_subscribers: {
+                    type: "boolean",
+                    description: "Hide customers not opted in to email marketing (reads email_marketing_consent.state, falls back to accepts_marketing).",
+                },
+                exclude_guest_checkouts: {
+                    type: "boolean",
+                    description: "Hide customers whose Shopify state is 'disabled' — i.e. they checked out without creating an account.",
+                },
+                exclude_unverified_emails: {
+                    type: "boolean",
+                    description: "Hide customers where verified_email is false.",
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_get_workspace",
+        description: "Fetch the current workspace's identity — id, name, slug, logo_url (storage path), logo_bg (hex/rgba/transparent/null), theme_json (HSL triplets + `_raw` hex block), and a signed logo URL. Requires workspace:read. The `logo_signed_url` expires in 1 hour — re-call this tool to refresh it if you need to render the logo again later.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "atlas_update_workspace",
+        description: "Patch the current workspace. Only the fields you send are updated — omitted fields are untouched. Slug renames cascade across every URL under the workspace, so double-check with the user before changing it. Theme changes are merged over the existing `_raw` block (so passing just `theme.accent` keeps bg/primary/radius/font). Requires workspace:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "New workspace name (1..80 chars, trimmed)." },
+                slug: {
+                    type: "string",
+                    description: "New workspace slug — lowercase letters, digits, hyphens (2..48, must start + end alnum). Rejected if reserved or already taken.",
+                },
+                logo_bg: {
+                    type: ["string", "null"],
+                    description: "Tile background behind the logo. Accepts `#rrggbb`, `rgba(r, g, b, a)`, the literal `\"transparent\"`, or `null` to clear.",
+                },
+                theme: {
+                    type: "object",
+                    description: "Brand theme partial. Any provided field is merged over the existing `_raw` block; omitted fields keep their current values.",
+                    properties: {
+                        bg: { type: "string", description: "Brand background (#rrggbb)." },
+                        primary: { type: "string", description: "Brand primary (#rrggbb)." },
+                        accent: { type: "string", description: "Brand accent (#rrggbb)." },
+                        radiusPx: {
+                            type: "number",
+                            description: "Border-radius in px — integer 0..24.",
+                        },
+                        font: {
+                            type: "string",
+                            description: "Brand font family — must match one of the shipped families in lib/fonts.ts (Inter, Manrope, DM Sans, IBM Plex Sans, Space Grotesk, Bricolage Grotesque, Instrument Serif, Fraunces, Playfair Display, JetBrains Mono).",
+                        },
+                    },
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_export_doc",
+        description: "Render a doc to PDF via the PAT-auth export endpoint and write it to a local file on the machine running this MCP server. Streams the same NDJSON pipeline the CLI uses (status / warn / done events). On success returns { out_path, pages, bytes } and, when `open` is true (default), spawns the OS default PDF viewer. Use for 'export this doc' / 'save as PDF' requests. The file lives at `out_path` (resolved relative to cwd when not absolute).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string", description: "Doc id from atlas_list_docs." },
+                out_path: {
+                    type: "string",
+                    description: "Where to write the PDF. Defaults to '<sanitised-title>.pdf' in the MCP's cwd.",
+                },
+                open: {
+                    type: "boolean",
+                    description: "Open the file in the OS default viewer after writing. Default true.",
+                },
+            },
+            required: ["doc_id"],
+        },
+    },
+    {
+        name: "atlas_build_moodboard",
+        description: "Assemble a moodboard section in one call. Uploads any local image paths through the signed-URL flow, re-uses already-uploaded storage keys, builds a rows×cols grid padded with nulls, and appends (or inserts at `position`) a new moodboard section. Returns { section_id, uploaded_count, total_slots }. Default grid 3×3, aspect 'square'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                image_paths: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Local file paths OR already-uploaded storage keys (e.g. '<workspace-uuid>/files/...').",
+                },
+                rows: { type: "number", description: "Default 3." },
+                cols: { type: "number", description: "Default 3." },
+                aspect: {
+                    type: "string",
+                    enum: ["square", "portrait", "landscape"],
+                    description: "Default 'square'.",
+                },
+                title: { type: "string", description: "Section title. Default 'Moodboard'." },
+                position: {
+                    type: "number",
+                    description: "Insert at this section index. Omit to append.",
+                },
+                spacing: { type: "number", description: "Cell spacing in px. Default 8." },
+                radius: { type: "number", description: "Cell corner radius in px. Default 8." },
+            },
+            required: ["doc_id", "image_paths"],
+        },
+    },
+    {
+        name: "atlas_extract_palette",
+        description: "Extract a colour palette from a moodboard section via server-side node-vibrant. Pulls each image, extracts up to 6 swatches per image, aggregates + perceptually de-dupes to rows×cols colours, and either patches an existing palette section wired to that moodboard (sourceSectionId match) or appends a new one right below it. Returns { palette_section_id, colours: string[] }.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                moodboard_section_id: {
+                    type: "string",
+                    description: "Section id of the moodboard to extract from.",
+                },
+                rows: { type: "number", description: "Default 3." },
+                cols: { type: "number", description: "Default 3." },
+            },
+            required: ["doc_id", "moodboard_section_id"],
+        },
+    },
+    {
+        name: "atlas_search_products",
+        description: "Search the workspace's connected Shopify catalogue by free-form text (title / handle / vendor / tags). Returns up to `limit` matches, each with { shopifyProductId, title, handle, vendor, price, imageUrl, status }. Requires the products:search scope AND an active Shopify connection.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search text. Empty = most recent 'any' status." },
+                limit: { type: "number", description: "Default 25, max 100." },
+            },
+        },
+    },
+    {
+        name: "atlas_add_products_to_doc",
+        description: "Snapshot a list of Shopify products into a Products section. Each product's title/handle/price/image/vendor is embedded so the tile renders even if the Shopify connection later drops. If `section_id` is provided and refers to an existing Products section, items are appended; otherwise a new section is created and appended to the doc.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                shopify_product_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Shopify product ids (string form).",
+                },
+                section_id: {
+                    type: "string",
+                    description: "Append to this existing products section if set.",
+                },
+                title: {
+                    type: "string",
+                    description: "Section title when creating a new section (default 'Products').",
+                },
+            },
+            required: ["doc_id", "shopify_product_ids"],
+        },
+    },
+    {
+        name: "atlas_resolve_location",
+        description: "Resolve a free-form address or place name via Google Places Text Search (server-side). Returns up to 5 matches: { place_id, text, lat, lng, verified: true }.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search text, e.g. 'Bondi Icebergs' or '123 George St'." },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "atlas_add_location_to_doc",
+        description: "Resolve an address (via place_id or free-form text) and append it to a Locations section. Creates a new section if `section_id` is omitted. Captures place_id + lat/lng so the Atlas map preview can render without a second geocode on the next doc open.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                address: { type: "string", description: "Free-form address." },
+                place_id: { type: "string", description: "Google Places place_id (preferred when known)." },
+                nickname: { type: "string", description: "Display name for the card." },
+                notes: { type: "string", description: "Per-location notes." },
+                section_id: { type: "string", description: "Append to this existing locations section." },
+                title: { type: "string", description: "Section title when creating a new section." },
+            },
+            required: ["doc_id"],
+        },
+    },
+    {
+        name: "atlas_add_gear_to_doc",
+        description: "Add existing gear library items to a gear section by referencing their gear_items UUIDs. Gear sections store `itemIds` only (the renderer joins against the workspace gear library at open time), so this is a thin append to that array. If `section_id` is omitted a new gear section is appended.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                gear_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "gear_items UUIDs from atlas_list_gear.",
+                },
+                section_id: { type: "string", description: "Append to this existing gear section." },
+                title: { type: "string", description: "Section title when creating (default 'Gear')." },
+                format: {
+                    type: "string",
+                    enum: ["table", "bullets", "images"],
+                    description: "Section layout when creating. Default 'table'.",
+                },
+            },
+            required: ["doc_id", "gear_ids"],
+        },
+    },
+    {
+        name: "atlas_add_shots_to_doc",
+        description: "Snapshot shots from the workspace library into a shot-list section. Each snapshot copies name + kind + notes into a row; the referenced library shot can later diverge without affecting the doc. If `section_id` is omitted a new shot-list section is appended.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                shot_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "shot library ids from atlas_list_shots.",
+                },
+                section_id: { type: "string", description: "Append to this existing shot-list section." },
+                title: { type: "string", description: "Section title when creating (default 'Shot list')." },
+            },
+            required: ["doc_id", "shot_ids"],
+        },
+    },
+    {
+        name: "atlas_upload_workspace_logo",
+        description: "Upload a local image file as the workspace's logo. Multipart POST — reads the file at `path` and streams it to /api/v1/workspace/logo. Accepts PNG, JPG, or WebP up to 2 MB. Returns the new `logo_url` + a 1-hour signed URL. Requires workspace:write. `path` is a local file path (same shape as atlas_upload_file's `local_path`).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute or CWD-relative path to a PNG/JPG/WebP file on the machine running this MCP server.",
+                },
+            },
+            required: ["path"],
+        },
+    },
+    READ_ACHIEVEMENTS_TOOL,
+    {
+        name: "atlas_list_mindmaps",
+        description: "List mindmaps (planning boards) in the current Atlas workspace. Requires mindmaps:list. Returns { items, next_cursor } — each item is a MindmapSummary (id, title, description, shoot_id, node_count, node_done_count, created_at, updated_at). Pass `cursor` to page.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Default 50, max 500." },
+                cursor: {
+                    type: "string",
+                    description: "Opaque next_cursor from a previous response. Omit for the first page.",
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_get_mindmap",
+        description: "Fetch a full mindmap — metadata + every node + every edge. Requires mindmaps:read. Returns { mindmap, nodes[], edges[] }. Nodes carry x/y/title/kind/colour_key; edges connect two node ids. Use before atlas_update_mindmap_node / atlas_delete_mindmap_node so you have fresh ids.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string", description: "Mindmap id from atlas_list_mindmaps." },
+            },
+            required: ["mindmapId"],
+        },
+    },
+    {
+        name: "atlas_create_mindmap",
+        description: "Create a new mindmap. Requires mindmaps:write. `title` is required; `description` and `shoot_id` are optional. Optional `nodes[]` and `edges[]` seed the canvas atomically — edges may reference node ids supplied inline (we remap client-provided ids to the generated UUIDs). Returns the new mindmap record.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Mindmap title (≤ 200 chars)." },
+                description: { type: "string", description: "Optional description (≤ 2000 chars)." },
+                shoot_id: {
+                    type: "string",
+                    description: "Optional shoots id to attach the mindmap to.",
+                },
+                nodes: {
+                    type: "array",
+                    description: "Optional seed nodes. Each: { title (required) | label, x?, y?, width?, height?, kind?, shape?, colour_key?, description?, image_url?, image_alt?, font_size?, text_color?, bg_color?, id? (used to wire inline edges) }.",
+                    items: { type: "object" },
+                },
+                edges: {
+                    type: "array",
+                    description: "Optional seed edges. Each: { from_node_id, to_node_id, label? }. Ids may reference either existing nodes OR the `id` field of a node in the inline `nodes` array.",
+                    items: { type: "object" },
+                },
+            },
+            required: ["title"],
+        },
+    },
+    {
+        name: "atlas_update_mindmap",
+        description: "Patch a mindmap's metadata (title / description / shoot link). Requires mindmaps:write. Only the fields you send are updated. Pass `shoot_id: null` to detach the current shoot link.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string", description: "Mindmap id." },
+                title: { type: "string", description: "New title (≤ 200 chars)." },
+                description: {
+                    type: ["string", "null"],
+                    description: "New description (≤ 2000 chars). Pass null to clear.",
+                },
+                shoot_id: {
+                    type: ["string", "null"],
+                    description: "shoots id to attach, or null to detach.",
+                },
+            },
+            required: ["mindmapId"],
+        },
+    },
+    {
+        name: "atlas_delete_mindmap",
+        description: "Hard-delete a mindmap. Requires mindmaps:delete. Nodes, edges, and freehand strokes cascade via FK — no undo. Always confirm with the user before calling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string", description: "Mindmap id from atlas_list_mindmaps." },
+            },
+            required: ["mindmapId"],
+        },
+    },
+    {
+        name: "atlas_add_mindmap_node",
+        description: "Append a single node to a mindmap. Requires mindmaps:write. `label` (or `title`) is required; everything else defaults. Returns the inserted node row. order_index is auto-computed as max+1 so the node lands at the end of the canvas.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string", description: "Mindmap id." },
+                label: { type: "string", description: "Node label (synonym for title). One of label/title required." },
+                title: { type: "string", description: "Node title. One of label/title required." },
+                x: { type: "number", description: "Canvas x coordinate (default 0)." },
+                y: { type: "number", description: "Canvas y coordinate (default 0)." },
+                width: { type: "number", description: "Node width (default 200)." },
+                height: { type: "number", description: "Node height (default 120)." },
+                kind: {
+                    type: "string",
+                    enum: ["text", "shape", "image", "textbox"],
+                    description: "Node kind. Default 'text'.",
+                },
+                shape: {
+                    type: "string",
+                    enum: ["rect", "circle", "diamond", "ellipse", "triangle", "rounded"],
+                    description: "Required when kind='shape'.",
+                },
+                colour_key: {
+                    type: "string",
+                    enum: ["rose", "amber", "sky", "violet", "lime", "stone"],
+                },
+                description: { type: "string" },
+                image_url: { type: "string", description: "https: URL (image nodes only)." },
+                image_alt: { type: "string" },
+                font_size: { type: "number", description: "8..96" },
+                text_color: { type: "string", description: "Hex colour #rrggbb (or #rgb / with alpha)." },
+                bg_color: { type: "string", description: "Hex colour #rrggbb." },
+            },
+            required: ["mindmapId"],
+        },
+    },
+    {
+        name: "atlas_update_mindmap_node",
+        description: "Patch a mindmap node. Requires mindmaps:write. Only the fields you send are updated. `label` is a synonym for `title`. Set `completed: true` to mark a node done.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string" },
+                nodeId: { type: "string" },
+                label: { type: "string" },
+                title: { type: "string" },
+                x: { type: "number" },
+                y: { type: "number" },
+                width: { type: "number" },
+                height: { type: "number" },
+                kind: {
+                    type: "string",
+                    enum: ["text", "shape", "image", "textbox"],
+                },
+                shape: {
+                    type: "string",
+                    enum: ["rect", "circle", "diamond", "ellipse", "triangle", "rounded"],
+                },
+                colour_key: {
+                    type: "string",
+                    enum: ["rose", "amber", "sky", "violet", "lime", "stone"],
+                },
+                description: { type: "string" },
+                completed: { type: "boolean" },
+                image_url: { type: "string" },
+                image_alt: { type: "string" },
+                font_size: { type: "number" },
+                text_color: { type: "string" },
+                bg_color: { type: "string" },
+                order_index: { type: "number" },
+            },
+            required: ["mindmapId", "nodeId"],
+        },
+    },
+    {
+        name: "atlas_delete_mindmap_node",
+        description: "Delete one node from a mindmap. Requires mindmaps:delete. Edges touching this node cascade-delete via FK. Confirm with the user before calling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string" },
+                nodeId: { type: "string" },
+            },
+            required: ["mindmapId", "nodeId"],
+        },
+    },
+    {
+        name: "atlas_add_mindmap_edge",
+        description: "Create an edge between two nodes in a mindmap. Requires mindmaps:write. Both nodes must belong to the same mindmap. The DB enforces UNIQUE(mindmap_id, from_node_id, to_node_id) — duplicates return 409.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string" },
+                from_node_id: { type: "string" },
+                to_node_id: { type: "string" },
+                label: { type: "string", description: "Optional edge label (≤ 200 chars)." },
+            },
+            required: ["mindmapId", "from_node_id", "to_node_id"],
+        },
+    },
+    {
+        name: "atlas_delete_mindmap_edge",
+        description: "Delete a mindmap edge. Requires mindmaps:delete. Nodes untouched. Confirm with the user before calling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string" },
+                edgeId: { type: "string" },
+            },
+            required: ["mindmapId", "edgeId"],
+        },
+    },
+    {
+        name: "atlas_create_mindmap_group",
+        description: "Create a mindmap group — stamps a shared `group_id` onto a set of existing nodes (and optional edges) and writes a row to mindmap_groups carrying the group's inspector-pane metadata (name, bg colour, outline, radius, padding, custom CSS). Requires mindmaps:write. All referenced ids must live in this mindmap.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmapId: { type: "string", description: "Mindmap id." },
+                name: { type: "string", description: "Group display name (≤ 200 chars). Synonym: title." },
+                title: { type: "string", description: "Alias for name." },
+                nodes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "mindmap_nodes UUIDs to tag with the new group id. Non-empty.",
+                },
+                edges: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional mindmap_edges UUIDs to tag with the new group id.",
+                },
+                bg_color: { type: "string", description: "Group background colour (#rrggbb / #rrggbbaa)." },
+                outline_color: { type: "string", description: "Group outline colour (#rrggbb / #rrggbbaa)." },
+                outline_width: { type: "number", description: "Outline width in px (0–32)." },
+                corner_radius: { type: "number", description: "Corner radius in px (0–128)." },
+                padding: { type: "number", description: "Padding in px (0–256)." },
+                custom_css: { type: "string", description: "Arbitrary CSS block (≤ 4000 chars)." },
+            },
+            required: ["mindmapId", "nodes"],
+        },
+    },
+    {
+        name: "atlas_list_activity",
+        description: "List workspace activity-log entries, newest first. Requires activity:list. Returns { items, next_cursor }. Each item: { id, workspace_id, actor_user_id, source (ui|cli|mcp|system), action, resource_type, resource_id, summary, meta, created_at }. Optional filters: `since`/`until` (ISO 8601), `user` (uuid OR email), `source` (csv of ui,cli,mcp,system), `action` (exact verb like doc.create), `resource_type` (exact kind like doc, gear, mindmap).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Default 50, max 500." },
+                cursor: {
+                    type: "string",
+                    description: "Opaque next_cursor from a previous response. Omit for the first page.",
+                },
+                since: {
+                    type: "string",
+                    description: "ISO 8601 lower bound on created_at (inclusive).",
+                },
+                until: {
+                    type: "string",
+                    description: "ISO 8601 upper bound on created_at (exclusive).",
+                },
+                user: {
+                    type: "string",
+                    description: "Restrict to this actor — accepts a user uuid OR an email address.",
+                },
+                source: {
+                    type: "string",
+                    description: "Comma-separated source filter: any of ui, cli, mcp, system.",
+                },
+                action: {
+                    type: "string",
+                    description: "Exact-match verb filter, e.g. 'doc.create', 'mindmap.update'.",
+                },
+                resource_type: {
+                    type: "string",
+                    description: "Exact-match on resource_type: 'doc', 'gear', 'mindmap', etc.",
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_get_activity",
+        description: "Fetch a single workspace activity-log entry plus the (best-effort) hydrated actor record. Requires activity:read. Returns { entry, actor } where actor may be null (system events, deleted users).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entryId: { type: "string", description: "Activity-log entry id." },
+            },
+            required: ["entryId"],
+        },
+    },
+    {
+        name: "export_mindmap",
+        description: "Export an Atlas mindmap to PDF, PNG, or SVG. SVG is server-rendered vector output (fastest, retains ink as paths). PDF + PNG spawn local Chromium via playwright-core on the machine running this MCP server. Returns { out_path, format, bytes }. Requires mindmaps:export.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mindmap_id: { type: "string" },
+                format: {
+                    type: "string",
+                    enum: ["pdf", "png", "svg"],
+                    description: "Output format. Default pdf.",
+                },
+                out_path: {
+                    type: "string",
+                    description: "Absolute path to write the file to. Default: '<title>.<ext>' in cwd.",
+                },
+                dpi: {
+                    type: "number",
+                    enum: [1, 2, 3],
+                    description: "Device scale factor for PNG. Default 2.",
+                },
+                w: { type: "number", description: "Canvas width in CSS pixels. Default 1920." },
+                h: { type: "number", description: "Canvas height in CSS pixels. Default 1080." },
+                open: {
+                    type: "boolean",
+                    description: "Open the file in the OS default viewer after writing. Default true.",
+                },
+            },
+            required: ["mindmap_id"],
+        },
+    },
+];
+/* ─── Server setup ─────────────────────────────────────────────────── */
+const server = new Server({ name: "atlas-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = (req.params.arguments ?? {});
+    try {
+        const result = await dispatch(name, args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            isError: true,
+            content: [{ type: "text", text: `error: ${msg}` }],
+        };
+    }
+});
+async function dispatch(name, args) {
+    switch (name) {
+        case "atlas_doc_create":
+            return createDoc(args);
+        case "atlas_list_doc_presets":
+            return listDocPresets();
+        case "atlas_create_doc_from_preset":
+            return createDocFromPreset(args);
+        case "atlas_doc_delete":
+            return deleteDoc(args);
+        case "atlas_restore_doc":
+            return restoreDoc(args);
+        case "atlas_purge_doc":
+            return purgeDoc(args);
+        case "atlas_list_docs":
+            return listDocs(args);
+        case "atlas_get_template":
+            return getTemplate(args);
+        case "atlas_list_sections":
+            return listSections(args);
+        case "atlas_update_section":
+            return updateSection(args);
+        case "atlas_list_files":
+            return listFiles(args);
+        case "atlas_upload_file":
+            return uploadFile(args);
+        case "atlas_get_file_url":
+            return getFileUrl(args);
+        case "atlas_set_file_alt":
+            return setFileAlt(args);
+        case "atlas_delete_file":
+            return deleteFile(args);
+        case "atlas_list_gear":
+            return listGear(args);
+        case "atlas_add_gear":
+            return addGear(args);
+        case "atlas_import_gear":
+            return importGear(args);
+        case "atlas_delete_gear":
+            return deleteGear(args);
+        case "atlas_restore_gear":
+            return restoreGear(args);
+        case "atlas_purge_gear":
+            return purgeGear(args);
+        case "atlas_update_template":
+            return updateTemplate(args);
+        case "atlas_describe_section_type":
+            return describeSectionType(args);
+        case "atlas_update_gear":
+            return updateGear(args);
+        case "atlas_list_shots":
+            return listShots(args);
+        case "atlas_add_shot":
+            return addShot(args);
+        case "atlas_update_shot":
+            return updateShot(args);
+        case "atlas_delete_shot":
+            return deleteShot(args);
+        case "atlas_restore_shot":
+            return restoreShot(args);
+        case "atlas_purge_shot":
+            return purgeShot(args);
+        case "atlas_import_shots":
+            return importShots(args);
+        case "atlas_list_events":
+            return listEvents(args);
+        case "atlas_get_event":
+            return getEvent(args);
+        case "atlas_create_event":
+            return createEvent(args);
+        case "atlas_update_event":
+            return updateEvent(args);
+        case "atlas_delete_event":
+            return deleteEvent(args);
+        case "atlas_assign_event":
+            return assignEvent(args);
+        case "atlas_unassign_event":
+            return unassignEvent(args);
+        case "atlas_rename_file":
+            return renameFile(args);
+        case "atlas_list_revisions":
+            return listRevisions(args);
+        case "atlas_restore_revision":
+            return restoreRevision(args);
+        case "atlas_whoami":
+            return whoami();
+        case "atlas_verify_connection":
+            return verifyConnection();
+        case "atlas_list_metafield_definitions":
+            return listMetafieldDefinitions();
+        case "atlas_suggest_metafields":
+            return suggestMetafields();
+        case "atlas_scan_shopify_metafields":
+            return scanShopifyMetafields();
+        case "atlas_create_metafield_definition":
+            return createMetafieldDefinition(args);
+        case "atlas_delete_metafield_definition":
+            return deleteMetafieldDefinition(args);
+        case "atlas_list_loyalty_tiers":
+            return listLoyaltyTiers();
+        case "atlas_set_loyalty_tiers":
+            return setLoyaltyTiers(args);
+        case "atlas_reset_loyalty_tiers":
+            return resetLoyaltyTiers();
+        case "atlas_get_analytics_prefs":
+            return getAnalyticsPrefs();
+        case "atlas_set_analytics_prefs":
+            return setAnalyticsPrefs(args);
+        case "atlas_get_workspace":
+            return getWorkspace();
+        case "atlas_update_workspace":
+            return updateWorkspace(args);
+        case "atlas_upload_workspace_logo":
+            return uploadWorkspaceLogo(args);
+        case "atlas_export_doc":
+            return exportDocTool(args);
+        case "atlas_build_moodboard":
+            return buildMoodboard(args);
+        case "atlas_extract_palette":
+            return extractPaletteTool(args);
+        case "atlas_search_products":
+            return searchProducts(args);
+        case "atlas_add_products_to_doc":
+            return addProductsToDoc(args);
+        case "atlas_resolve_location":
+            return resolveLocationTool(args);
+        case "atlas_add_location_to_doc":
+            return addLocationToDoc(args);
+        case "atlas_add_gear_to_doc":
+            return addGearToDoc(args);
+        case "atlas_add_shots_to_doc":
+            return addShotsToDoc(args);
+        case "read_achievements":
+            return readAchievements();
+        case "atlas_list_mindmaps":
+            return listMindmaps_(args);
+        case "atlas_get_mindmap":
+            return getMindmap_(args);
+        case "atlas_create_mindmap":
+            return createMindmap_(args);
+        case "atlas_update_mindmap":
+            return updateMindmap_(args);
+        case "atlas_delete_mindmap":
+            return deleteMindmap_(args);
+        case "atlas_add_mindmap_node":
+            return addMindmapNode_(args);
+        case "atlas_update_mindmap_node":
+            return updateMindmapNode_(args);
+        case "atlas_delete_mindmap_node":
+            return deleteMindmapNode_(args);
+        case "atlas_add_mindmap_edge":
+            return addMindmapEdge_(args);
+        case "atlas_delete_mindmap_edge":
+            return deleteMindmapEdge_(args);
+        case "atlas_create_mindmap_group":
+            return createMindmapGroup_(args);
+        case "atlas_list_activity":
+            return listActivity_(args);
+        case "atlas_get_activity":
+            return getActivity_(args);
+        case "export_mindmap":
+            return exportMindmapTool(args);
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+/* ─── Tool implementations ─────────────────────────────────────────── */
+async function listDocs(args) {
+    const cfg = resolveConfig();
+    const query = {};
+    if (typeof args.kind === "string")
+        query.kind = args.kind;
+    if (typeof args.limit === "number")
+        query.limit = args.limit;
+    if (typeof args.cursor === "string")
+        query.cursor = args.cursor;
+    if (args.deleted === true)
+        query.deleted = 1;
+    const { data } = await apiRequest(cfg, "/api/v1/docs", { query });
+    return data;
+}
+async function getTemplate(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`);
+    return data;
+}
+async function listSections(args) {
+    const tpl = await getTemplate(args);
+    const sections = tpl.template_content?.sections ?? [];
+    const summary = sections.map((s) => ({
+        id: s.id,
+        type: s.type,
+        // Best-effort title extraction — most sections stash a title on data.title.
+        title: (s.data && typeof s.data.title === "string"
+            ? s.data.title
+            : null) ?? "",
+        hidden: !!s.hidden,
+    }));
+    return { docId: tpl.id, title: tpl.title, section_count: summary.length, sections: summary };
+}
+async function updateSection(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const sectionId = requireString(args, "sectionId");
+    const newData = isRecord(args.data) ? args.data : undefined;
+    const newStyle = isRecord(args.style) ? args.style : undefined;
+    const hidden = typeof args.hidden === "boolean" ? args.hidden : undefined;
+    if (newData === undefined && newStyle === undefined && hidden === undefined) {
+        throw new Error("Provide at least one of: data, style, hidden.");
+    }
+    // Fetch current etag first so the PATCH's If-Match survives a concurrent
+    // web edit. On 409 we surface the message so the model can re-fetch and
+    // retry.
+    const current = await getTemplate({ docId });
+    try {
+        const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template/sections/${sectionId}`, {
+            method: "PATCH",
+            body: {
+                ...(newData !== undefined ? { data: newData } : {}),
+                ...(newStyle !== undefined ? { style: newStyle } : {}),
+                ...(hidden !== undefined ? { hidden } : {}),
+            },
+            ifMatch: current.etag,
+        });
+        return {
+            updated_section: sectionId,
+            section: data.section,
+            etag: data.etag,
+            updated_at: data.updated_at,
+        };
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 404) {
+            throw new Error(`Section '${sectionId}' not found in doc '${docId}'. Call atlas_list_sections to see current section ids.`);
+        }
+        if (e instanceof ApiError && e.status === 409) {
+            throw new Error("Doc was modified since we fetched it — re-run atlas_get_template to pick up the concurrent change, then retry.");
+        }
+        throw e;
+    }
+}
+async function createDoc(args) {
+    const cfg = resolveConfig();
+    const title = requireString(args, "title");
+    const body = { title };
+    if (typeof args.doc_kind === "string")
+        body.doc_kind = args.doc_kind;
+    if (typeof args.folder_id === "string")
+        body.folder_id = args.folder_id;
+    if (typeof args.shoot_id === "string")
+        body.shoot_id = args.shoot_id;
+    if (isRecord(args.template_content))
+        body.template_content = args.template_content;
+    if (typeof args.preset_id === "string")
+        body.preset_id = args.preset_id;
+    const { data } = await apiRequest(cfg, "/api/v1/docs", { method: "POST", body });
+    return data;
+}
+/** List the server-side preset catalogue. One GET → the full
+ * `{ presets: DocPreset[] }` payload the web picker also uses. */
+async function listDocPresets() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/presets", { method: "GET" });
+    return data;
+}
+/** Convenience wrapper — resolves the preset-id defaulted title on the
+ * client so Claude doesn't have to list presets first just to grab the
+ * default string. API still validates the preset_id. */
+async function createDocFromPreset(args) {
+    const presetId = requireString(args, "preset_id");
+    // Resolve the default title client-side so Claude can create docs
+    // without a second round-trip to list presets. The API validates
+    // preset_id again (and 404s on unknown ids) regardless.
+    let defaultTitle = presetId;
+    try {
+        const list = (await listDocPresets());
+        const found = list.presets?.find((p) => p.id === presetId);
+        if (found?.defaultTitle)
+            defaultTitle = found.defaultTitle;
+    }
+    catch {
+        // Non-fatal — fall through to presetId as the title. API still
+        // validates preset_id below.
+    }
+    const title = typeof args.title === "string" && args.title.trim().length > 0
+        ? args.title
+        : defaultTitle;
+    return createDoc({
+        title,
+        preset_id: presetId,
+        ...(typeof args.folder_id === "string" ? { folder_id: args.folder_id } : {}),
+        ...(typeof args.shoot_id === "string" ? { shoot_id: args.shoot_id } : {}),
+    });
+}
+async function deleteDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const purge = args.purge === true;
+    const path = purge ? `/api/v1/docs/${docId}?purge=1` : `/api/v1/docs/${docId}`;
+    const { data } = await apiRequest(cfg, path, { method: "DELETE" });
+    return data;
+}
+async function restoreDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/restore`, {
+        method: "POST",
+    });
+    return data;
+}
+async function purgeDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}?purge=1`, {
+        method: "DELETE",
+    });
+    return data;
+}
+async function updateTemplate(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const templateContent = args.template_content;
+    if (!isRecord(templateContent)) {
+        throw new Error("`template_content` must be an object matching TemplateContent shape.");
+    }
+    const title = typeof args.title === "string" ? args.title : undefined;
+    // Get-then-put for etag freshness.
+    const current = await getTemplate({ docId });
+    try {
+        const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`, {
+            method: "PUT",
+            body: { template_content: templateContent, ...(title ? { title } : {}) },
+            ifMatch: current.etag,
         });
         return {
             docId: data.id,
@@ -452,224 +1800,1494 @@ async function updateTemplate(args) {
             updated_at: data.updated_at,
         };
     }
-    catch (e) {
-        if (e instanceof ApiError && e.status === 409) {
-            throw new Error("Doc was modified since we fetched it — re-run atlas_get_template to pick up the concurrent change, then retry.");
+    catch (e) {
+        if (e instanceof ApiError && e.status === 409) {
+            throw new Error("Doc was modified since we fetched it — re-run atlas_get_template to pick up the concurrent change, then retry.");
+        }
+        throw e;
+    }
+}
+async function describeSectionType(args) {
+    const type = args.type;
+    if (typeof type === "string") {
+        const entry = findSection(type);
+        if (!entry) {
+            throw new Error(`Unknown section type '${type}'. Known types: ${SECTION_CATALOG.map((s) => s.type).join(", ")}.`);
+        }
+        return entry;
+    }
+    return { types: SECTION_CATALOG };
+}
+/* ─── Files tools ──────────────────────────────────────────────────── */
+async function listFiles(args) {
+    const cfg = resolveConfig();
+    const query = {};
+    if (typeof args.folder_id === "string")
+        query.folder_id = args.folder_id;
+    if (typeof args.limit === "number")
+        query.limit = args.limit;
+    if (typeof args.cursor === "string")
+        query.cursor = args.cursor;
+    const { data } = await apiRequest(cfg, "/api/v1/files", { query });
+    return data;
+}
+async function uploadFile(args) {
+    const cfg = resolveConfig();
+    const localPath = requireString(args, "local_path");
+    const alt = typeof args.alt === "string" ? args.alt : undefined;
+    const { readFile, stat } = await import("node:fs/promises");
+    const { basename, extname } = await import("node:path");
+    const info = await stat(localPath);
+    if (!info.isFile())
+        throw new Error(`Not a file: ${localPath}`);
+    const filename = basename(localPath);
+    const ext = extname(filename).toLowerCase();
+    const contentTypes = {
+        ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+        ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+        ".mp4": "video/mp4", ".mov": "video/quicktime", ".pdf": "application/pdf",
+        ".txt": "text/plain", ".md": "text/markdown", ".json": "application/json",
+        ".csv": "text/csv",
+    };
+    const contentType = contentTypes[ext] ?? "application/octet-stream";
+    // Step 1: signed URL
+    const { data: signRes } = await apiRequest(cfg, "/api/v1/files/upload-url", {
+        method: "POST",
+        body: { filename },
+    });
+    // Step 2: PUT bytes
+    const bytes = await readFile(localPath);
+    const putRes = await fetch(signRes.upload_url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType, "x-upsert": "false" },
+        body: bytes,
+    });
+    if (!putRes.ok) {
+        const text = await putRes.text().catch(() => "");
+        throw new Error(`Storage upload failed (HTTP ${putRes.status}): ${text.slice(0, 200)}`);
+    }
+    // Step 3: register metadata
+    const { data: reg } = await apiRequest(cfg, "/api/v1/files", {
+        method: "POST",
+        body: { path: signRes.path, alt },
+    });
+    return {
+        path: signRes.path,
+        size: info.size,
+        content_type: contentType,
+        metadata: reg.file,
+    };
+}
+async function getFileUrl(args) {
+    const cfg = resolveConfig();
+    const path = requireString(args, "path");
+    const { data } = await apiRequest(cfg, "/api/v1/files", { query: { limit: 500 } });
+    const match = data.files.find((f) => f.path === path);
+    if (!match)
+        throw new Error(`File not found or no metadata row: ${path}`);
+    return { path: match.path, url: match.signed_url, alt: match.alt };
+}
+async function setFileAlt(args) {
+    const cfg = resolveConfig();
+    const path = requireString(args, "path");
+    const alt = typeof args.alt === "string" ? args.alt : null;
+    const { data } = await apiRequest(cfg, "/api/v1/files/alt", {
+        method: "POST",
+        body: { path, alt },
+    });
+    return data;
+}
+async function deleteFile(args) {
+    const cfg = resolveConfig();
+    const path = requireString(args, "path");
+    const { data } = await apiRequest(cfg, "/api/v1/files", {
+        method: "DELETE",
+        query: { path },
+    });
+    return data;
+}
+/* ─── Gear tools ───────────────────────────────────────────────────── */
+async function listGear(args) {
+    const cfg = resolveConfig();
+    const query = {};
+    if (typeof args.limit === "number")
+        query.limit = args.limit;
+    if (typeof args.cursor === "string")
+        query.cursor = args.cursor;
+    if (args.deleted === true)
+        query.deleted = 1;
+    const { data } = await apiRequest(cfg, "/api/v1/gear", { query });
+    return data;
+}
+async function addGear(args) {
+    const cfg = resolveConfig();
+    const body = { name: requireString(args, "name") };
+    if (typeof args.brand === "string")
+        body.brand = args.brand;
+    if (typeof args.quantity === "number")
+        body.quantity = args.quantity;
+    if (typeof args.image_path === "string")
+        body.image_path = args.image_path;
+    const { data } = await apiRequest(cfg, "/api/v1/gear", {
+        method: "POST",
+        body,
+    });
+    return data;
+}
+async function importGear(args) {
+    const cfg = resolveConfig();
+    const rows = args.rows;
+    if (!Array.isArray(rows))
+        throw new Error("`rows` must be an array.");
+    const mode = args.mode === "replace" ? "replace" : "append";
+    const { data } = await apiRequest(cfg, "/api/v1/gear/import", {
+        method: "POST",
+        body: { mode, rows },
+    });
+    return data;
+}
+async function deleteGear(args) {
+    const cfg = resolveConfig();
+    const gearId = requireString(args, "gearId");
+    const purge = args.purge === true;
+    const path = purge ? `/api/v1/gear/${gearId}?purge=1` : `/api/v1/gear/${gearId}`;
+    const { data } = await apiRequest(cfg, path, { method: "DELETE" });
+    return data;
+}
+async function restoreGear(args) {
+    const cfg = resolveConfig();
+    const gearId = requireString(args, "gearId");
+    const { data } = await apiRequest(cfg, `/api/v1/gear/${gearId}/restore`, {
+        method: "POST",
+    });
+    return data;
+}
+async function purgeGear(args) {
+    const cfg = resolveConfig();
+    const gearId = requireString(args, "gearId");
+    const { data } = await apiRequest(cfg, `/api/v1/gear/${gearId}?purge=1`, {
+        method: "DELETE",
+    });
+    return data;
+}
+async function updateGear(args) {
+    const cfg = resolveConfig();
+    const gearId = requireString(args, "gearId");
+    const body = {};
+    if (typeof args.name === "string")
+        body.name = args.name;
+    if (typeof args.brand === "string")
+        body.brand = args.brand;
+    if (typeof args.quantity === "number")
+        body.quantity = args.quantity;
+    if (typeof args.image_path === "string")
+        body.image_path = args.image_path;
+    if (Object.keys(body).length === 0) {
+        throw new Error("At least one of name, brand, quantity, image_path is required.");
+    }
+    const { data } = await apiRequest(cfg, `/api/v1/gear/${gearId}`, {
+        method: "PUT",
+        body,
+    });
+    return data;
+}
+/* ─── Shot list tools ──────────────────────────────────────────────── */
+async function listShots(args) {
+    const cfg = resolveConfig();
+    const query = {};
+    if (typeof args.limit === "number")
+        query.limit = args.limit;
+    if (typeof args.cursor === "string")
+        query.cursor = args.cursor;
+    if (args.deleted === true)
+        query.deleted = 1;
+    const { data } = await apiRequest(cfg, "/api/v1/shots", { query });
+    return data;
+}
+async function addShot(args) {
+    const cfg = resolveConfig();
+    const body = { name: requireString(args, "name") };
+    if (typeof args.kind === "string")
+        body.kind = args.kind;
+    if (typeof args.notes === "string")
+        body.notes = args.notes;
+    if (typeof args.image_path === "string")
+        body.image_path = args.image_path;
+    if (Array.isArray(args.gear_ids))
+        body.gear_ids = args.gear_ids;
+    const { data } = await apiRequest(cfg, "/api/v1/shots", {
+        method: "POST",
+        body,
+    });
+    return data;
+}
+async function updateShot(args) {
+    const cfg = resolveConfig();
+    const shotId = requireString(args, "shotId");
+    const body = {};
+    if (typeof args.name === "string")
+        body.name = args.name;
+    if (typeof args.kind === "string")
+        body.kind = args.kind;
+    if (typeof args.notes === "string")
+        body.notes = args.notes;
+    if (typeof args.image_path === "string")
+        body.image_path = args.image_path;
+    if (Array.isArray(args.gear_ids))
+        body.gear_ids = args.gear_ids;
+    if (Object.keys(body).length === 0) {
+        throw new Error("At least one of name, kind, notes, image_path, gear_ids is required.");
+    }
+    const { data } = await apiRequest(cfg, `/api/v1/shots/${shotId}`, {
+        method: "PATCH",
+        body,
+    });
+    return data;
+}
+async function deleteShot(args) {
+    const cfg = resolveConfig();
+    const shotId = requireString(args, "shotId");
+    const purge = args.purge === true;
+    const path = purge ? `/api/v1/shots/${shotId}?purge=1` : `/api/v1/shots/${shotId}`;
+    const { data } = await apiRequest(cfg, path, { method: "DELETE" });
+    return data;
+}
+async function restoreShot(args) {
+    const cfg = resolveConfig();
+    const shotId = requireString(args, "shotId");
+    const { data } = await apiRequest(cfg, `/api/v1/shots/${shotId}/restore`, {
+        method: "POST",
+    });
+    return data;
+}
+async function purgeShot(args) {
+    const cfg = resolveConfig();
+    const shotId = requireString(args, "shotId");
+    const { data } = await apiRequest(cfg, `/api/v1/shots/${shotId}?purge=1`, {
+        method: "DELETE",
+    });
+    return data;
+}
+async function importShots(args) {
+    const cfg = resolveConfig();
+    const rows = args.rows;
+    if (!Array.isArray(rows))
+        throw new Error("`rows` must be an array.");
+    const mode = args.mode === "replace" ? "replace" : "append";
+    const { data } = await apiRequest(cfg, "/api/v1/shots/import", {
+        method: "POST",
+        body: { mode, rows },
+    });
+    return data;
+}
+/* ─── Events (calendar shoots) ─────────────────────────────────────── */
+async function listEvents(args) {
+    const cfg = resolveConfig();
+    const query = {};
+    if (typeof args.limit === "number")
+        query.limit = args.limit;
+    if (typeof args.cursor === "string")
+        query.cursor = args.cursor;
+    if (typeof args.from === "string")
+        query.from = args.from;
+    if (typeof args.to === "string")
+        query.to = args.to;
+    if (Array.isArray(args.status) && args.status.length > 0) {
+        query.status = args.status.filter((s) => typeof s === "string").join(",");
+    }
+    if (Array.isArray(args.colour) && args.colour.length > 0) {
+        query.colour = args.colour.filter((s) => typeof s === "string").join(",");
+    }
+    const { data } = await apiRequest(cfg, "/api/v1/events", { query });
+    return data;
+}
+async function getEvent(args) {
+    const cfg = resolveConfig();
+    const eventId = requireString(args, "eventId");
+    const { data } = await apiRequest(cfg, `/api/v1/events/${eventId}`);
+    return data;
+}
+async function createEvent(args) {
+    const cfg = resolveConfig();
+    const body = {
+        title: requireString(args, "title"),
+        starts_at: requireString(args, "starts_at"),
+    };
+    if (typeof args.ends_at === "string")
+        body.ends_at = args.ends_at;
+    if (typeof args.all_day === "boolean")
+        body.all_day = args.all_day;
+    if (typeof args.location === "string")
+        body.location = args.location;
+    if (typeof args.shoot_type === "string")
+        body.shoot_type = args.shoot_type;
+    if (typeof args.colour_key === "string")
+        body.colour_key = args.colour_key;
+    if (typeof args.colour_hex === "string")
+        body.colour_hex = args.colour_hex;
+    if (typeof args.status === "string")
+        body.status = args.status;
+    if (typeof args.notes === "string")
+        body.notes = args.notes;
+    if (typeof args.description === "string")
+        body.description = args.description;
+    const { data } = await apiRequest(cfg, "/api/v1/events", {
+        method: "POST",
+        body,
+    });
+    return data;
+}
+async function updateEvent(args) {
+    const cfg = resolveConfig();
+    const eventId = requireString(args, "eventId");
+    const body = {};
+    if (typeof args.title === "string")
+        body.title = args.title;
+    if (typeof args.starts_at === "string")
+        body.starts_at = args.starts_at;
+    if (typeof args.ends_at === "string")
+        body.ends_at = args.ends_at;
+    if (typeof args.all_day === "boolean")
+        body.all_day = args.all_day;
+    if (typeof args.location === "string")
+        body.location = args.location;
+    if (typeof args.shoot_type === "string")
+        body.shoot_type = args.shoot_type;
+    if (typeof args.colour_key === "string")
+        body.colour_key = args.colour_key;
+    if (typeof args.colour_hex === "string")
+        body.colour_hex = args.colour_hex;
+    if (typeof args.status === "string")
+        body.status = args.status;
+    if (typeof args.notes === "string")
+        body.notes = args.notes;
+    if (typeof args.description === "string")
+        body.description = args.description;
+    if (Object.keys(body).length === 0) {
+        throw new Error("At least one writable field (title, starts_at, ends_at, all_day, location, shoot_type, colour_key, colour_hex, status, notes, description) is required.");
+    }
+    const { data } = await apiRequest(cfg, `/api/v1/events/${eventId}`, { method: "PATCH", body });
+    return data;
+}
+async function deleteEvent(args) {
+    const cfg = resolveConfig();
+    const eventId = requireString(args, "eventId");
+    const { data } = await apiRequest(cfg, `/api/v1/events/${eventId}`, {
+        method: "DELETE",
+    });
+    return data;
+}
+async function assignEvent(args) {
+    const cfg = resolveConfig();
+    const eventId = requireString(args, "eventId");
+    const body = {
+        user_id: requireString(args, "user_id"),
+    };
+    if (typeof args.shoot_role === "string")
+        body.shoot_role = args.shoot_role;
+    if (Array.isArray(args.responsibilities)) {
+        body.responsibilities = args.responsibilities;
+    }
+    if (typeof args.notes === "string")
+        body.notes = args.notes;
+    const { data } = await apiRequest(cfg, `/api/v1/events/${eventId}/assignments`, { method: "POST", body });
+    return data;
+}
+async function unassignEvent(args) {
+    const cfg = resolveConfig();
+    const eventId = requireString(args, "eventId");
+    const assignmentId = requireString(args, "assignmentId");
+    const { data } = await apiRequest(cfg, `/api/v1/events/${eventId}/assignments/${assignmentId}`, { method: "DELETE" });
+    return data;
+}
+/* ─── Files rename ─────────────────────────────────────────────────── */
+async function renameFile(args) {
+    const cfg = resolveConfig();
+    const path = requireString(args, "path");
+    const newName = requireString(args, "new_name");
+    const { data } = await apiRequest(cfg, "/api/v1/files/rename", {
+        method: "POST",
+        body: { path, new_name: newName },
+    });
+    return data;
+}
+/* ─── Revisions ────────────────────────────────────────────────────── */
+async function listRevisions(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const query = {};
+    if (typeof args.limit === "number")
+        query.limit = args.limit;
+    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/revisions`, { query });
+    return data;
+}
+async function restoreRevision(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "docId");
+    const revisionId = requireString(args, "revisionId");
+    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/revisions/${revisionId}/restore`, {
+        method: "POST",
+    });
+    return {
+        docId: data.id,
+        title: data.title,
+        updated_at: data.updated_at,
+        etag: data.etag,
+        restored_from: data.restored_from,
+    };
+}
+async function whoami() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/whoami");
+    return data;
+}
+/** The dedicated "prove Claude Desktop MCP is wired up" call. Only
+ * this endpoint stamps workspace_members.onboarding.mcp_verified_at,
+ * which is the signal the onboarding walkthrough's phase 4 waits for.
+ * Kept intentionally distinct from whoami so accidental introspection
+ * calls can't false-positive the setup flow. */
+async function verifyConnection() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/verify", { method: "POST" });
+    return data;
+}
+/* ─── Metafield definitions ────────────────────────────────────────── */
+async function listMetafieldDefinitions() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/metafields");
+    return data;
+}
+async function suggestMetafields() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/metafields", { query: { suggest: "1" } });
+    return data;
+}
+async function scanShopifyMetafields() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/metafields/scan");
+    return data;
+}
+async function createMetafieldDefinition(args) {
+    const cfg = resolveConfig();
+    const body = {};
+    if (typeof args.preset === "string")
+        body.preset = args.preset;
+    if (typeof args.namespace === "string")
+        body.namespace = args.namespace;
+    if (typeof args.key === "string")
+        body.key = args.key;
+    if (typeof args.label === "string")
+        body.label = args.label;
+    if (typeof args.description === "string")
+        body.description = args.description;
+    if (typeof args.section === "string")
+        body.section = args.section;
+    if (typeof args.display_style === "string")
+        body.display_style = args.display_style;
+    const { data } = await apiRequest(cfg, "/api/v1/metafields", { method: "POST", body });
+    return data;
+}
+async function deleteMetafieldDefinition(args) {
+    const cfg = resolveConfig();
+    const id = requireString(args, "id");
+    await apiRequest(cfg, `/api/v1/metafields/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+    });
+    return { ok: true };
+}
+/* ─── Helpers ──────────────────────────────────────────────────────── */
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== "string" || !v)
+        throw new Error(`\`${key}\` is required.`);
+    return v;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null;
+}
+/* ─── Loyalty + analytics tools ────────────────────────────────────── */
+async function listLoyaltyTiers() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/loyalty/tiers");
+    return data;
+}
+async function setLoyaltyTiers(args) {
+    const cfg = resolveConfig();
+    const tiers = args.tiers;
+    if (!Array.isArray(tiers))
+        throw new Error("`tiers` must be an array. See atlas_set_loyalty_tiers for the shape.");
+    const { data } = await apiRequest(cfg, "/api/v1/loyalty/tiers", { method: "PUT", body: { tiers } });
+    return data;
+}
+async function resetLoyaltyTiers() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/loyalty/tiers", { method: "DELETE" });
+    return data;
+}
+async function getAnalyticsPrefs() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/analytics/prefs");
+    return data;
+}
+async function setAnalyticsPrefs(args) {
+    const cfg = resolveConfig();
+    const body = {};
+    if (Array.isArray(args.excluded_tags))
+        body.excluded_tags = args.excluded_tags;
+    else if (Array.isArray(args.excludedTags))
+        body.excluded_tags = args.excludedTags;
+    if (Array.isArray(args.excluded_statuses))
+        body.excluded_statuses = args.excluded_statuses;
+    else if (Array.isArray(args.excludedStatuses))
+        body.excluded_statuses = args.excludedStatuses;
+    if (Array.isArray(args.excluded_customer_tags))
+        body.excluded_customer_tags = args.excluded_customer_tags;
+    else if (Array.isArray(args.excludedCustomerTags))
+        body.excluded_customer_tags = args.excludedCustomerTags;
+    if (typeof args.exclude_non_subscribers === "boolean")
+        body.exclude_non_subscribers = args.exclude_non_subscribers;
+    else if (typeof args.excludeNonSubscribers === "boolean")
+        body.exclude_non_subscribers = args.excludeNonSubscribers;
+    if (typeof args.exclude_guest_checkouts === "boolean")
+        body.exclude_guest_checkouts = args.exclude_guest_checkouts;
+    else if (typeof args.excludeGuestCheckouts === "boolean")
+        body.exclude_guest_checkouts = args.excludeGuestCheckouts;
+    if (typeof args.exclude_unverified_emails === "boolean")
+        body.exclude_unverified_emails = args.exclude_unverified_emails;
+    else if (typeof args.excludeUnverifiedEmails === "boolean")
+        body.exclude_unverified_emails = args.excludeUnverifiedEmails;
+    if (Object.keys(body).length === 0)
+        throw new Error("Pass at least one exclusion field (tags, statuses, customer tags, or a customer-level boolean flag).");
+    const { data } = await apiRequest(cfg, "/api/v1/analytics/prefs", {
+        method: "PUT",
+        body,
+    });
+    return data;
+}
+/* ─── Workspace tools ──────────────────────────────────────────────── */
+async function getWorkspace() {
+    const cfg = resolveConfig();
+    const { data } = await apiRequest(cfg, "/api/v1/workspace");
+    return data;
+}
+async function updateWorkspace(args) {
+    const cfg = resolveConfig();
+    const body = {};
+    if (typeof args.name === "string")
+        body.name = args.name;
+    if (typeof args.slug === "string")
+        body.slug = args.slug;
+    // logo_bg can be a string OR explicit null; anything else means "leave alone".
+    if (typeof args.logo_bg === "string" || args.logo_bg === null) {
+        body.logo_bg = args.logo_bg;
+    }
+    if (isRecord(args.theme)) {
+        const theme = {};
+        if (typeof args.theme.bg === "string")
+            theme.bg = args.theme.bg;
+        if (typeof args.theme.primary === "string")
+            theme.primary = args.theme.primary;
+        if (typeof args.theme.accent === "string")
+            theme.accent = args.theme.accent;
+        if (typeof args.theme.radiusPx === "number")
+            theme.radiusPx = args.theme.radiusPx;
+        if (typeof args.theme.font === "string")
+            theme.font = args.theme.font;
+        if (Object.keys(theme).length > 0)
+            body.theme = theme;
+    }
+    if (Object.keys(body).length === 0) {
+        throw new Error("Provide at least one of: name, slug, logo_bg, theme.{bg,primary,accent,radiusPx,font}.");
+    }
+    const { data } = await apiRequest(cfg, "/api/v1/workspace", { method: "PATCH", body });
+    return data;
+}
+async function uploadWorkspaceLogo(args) {
+    const cfg = resolveConfig();
+    const localPath = requireString(args, "path");
+    const { readFile, stat } = await import("node:fs/promises");
+    const { basename, extname } = await import("node:path");
+    const info = await stat(localPath);
+    if (!info.isFile())
+        throw new Error(`Not a file: ${localPath}`);
+    const MAX = 2 * 1024 * 1024;
+    if (info.size > MAX) {
+        throw new Error(`Logo is ${(info.size / 1024 / 1024).toFixed(1)} MB — exceeds the 2 MB cap.`);
+    }
+    const filename = basename(localPath);
+    const ext = extname(filename).toLowerCase();
+    const contentTypes = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+    };
+    const contentType = contentTypes[ext];
+    if (!contentType) {
+        throw new Error(`Logo must be a PNG, JPG, or WebP image. Got ${ext || "(no extension)"}.`);
+    }
+    const bytes = await readFile(localPath);
+    const form = new FormData();
+    const blob = new Blob([new Uint8Array(bytes)], { type: contentType });
+    form.set("file", blob, filename);
+    const url = new URL("/api/v1/workspace/logo", cfg.apiUrl);
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${cfg.token}`,
+            Accept: "application/json",
+            "User-Agent": "atlas-mcp/0.1.0",
+        },
+        body: form,
+    });
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = text;
+    }
+    if (!res.ok) {
+        const message = (isRecord(body) && typeof body.error === "string" && body.error) ||
+            `HTTP ${res.status}`;
+        throw new ApiError(res.status, body, message);
+    }
+    return body;
+}
+/* ─── Export (PDF) ─────────────────────────────────────────────────── */
+async function exportDocTool(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const open = args.open !== false;
+    // Stream the NDJSON endpoint. We don't surface intermediate status
+    // events to the model — the MCP returns a single JSON blob when done
+    // (or throws on error). Matches the CLI's --json contract.
+    const url = new URL(`/api/v1/docs/${docId}/export`, cfg.apiUrl);
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${cfg.token}`,
+            Accept: "text/plain",
+            "User-Agent": "atlas-mcp/0.1.0",
+        },
+    });
+    if (!res.ok || !res.body) {
+        const text = await res.text().catch(() => "");
+        throw new ApiError(res.status, text, text || `HTTP ${res.status}`);
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let done = null;
+    while (true) {
+        const { value, done: finished } = await reader.read();
+        if (finished)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (ev.type === "error") {
+                throw new Error(typeof ev.message === "string" ? ev.message : "Export failed");
+            }
+            if (ev.type === "done") {
+                done = ev;
+            }
+        }
+    }
+    if (buffer.trim()) {
+        try {
+            const ev = JSON.parse(buffer.trim());
+            if (ev.type === "done")
+                done = ev;
         }
-        throw e;
+        catch { /* ignore */ }
     }
-}
-async function describeSectionType(args) {
-    const type = args.type;
-    if (typeof type === "string") {
-        const entry = findSection(type);
-        if (!entry) {
-            throw new Error(`Unknown section type '${type}'. Known types: ${SECTION_CATALOG.map((s) => s.type).join(", ")}.`);
+    if (!done)
+        throw new Error("Export stream ended without a `done` event");
+    const { writeFile } = await import("node:fs/promises");
+    const { resolve: resolvePath, isAbsolute } = await import("node:path");
+    const outPathRaw = typeof args.out_path === "string" && args.out_path.trim()
+        ? args.out_path
+        : done.filename;
+    const outPath = isAbsolute(outPathRaw)
+        ? outPathRaw
+        : resolvePath(process.cwd(), outPathRaw);
+    const bytes = Buffer.from(done.pdfBase64, "base64");
+    await writeFile(outPath, bytes);
+    if (open) {
+        const { spawn } = await import("node:child_process");
+        try {
+            if (process.platform === "win32") {
+                spawn("cmd", ["/c", "start", "", outPath], { detached: true, stdio: "ignore" }).unref();
+            }
+            else if (process.platform === "darwin") {
+                spawn("open", [outPath], { detached: true, stdio: "ignore" }).unref();
+            }
+            else {
+                spawn("xdg-open", [outPath], { detached: true, stdio: "ignore" }).unref();
+            }
         }
-        return entry;
+        catch { /* non-fatal */ }
     }
-    return { types: SECTION_CATALOG };
-}
-/* ─── Files tools ──────────────────────────────────────────────────── */
-async function listFiles(args) {
-    const cfg = resolveConfig();
-    const query = {};
-    if (typeof args.folder_id === "string")
-        query.folder_id = args.folder_id;
-    if (typeof args.limit === "number")
-        query.limit = args.limit;
-    if (typeof args.cursor === "string")
-        query.cursor = args.cursor;
-    const { data } = await apiRequest(cfg, "/api/v1/files", { query });
-    return data;
+    return { out_path: outPath, pages: done.pages, bytes: bytes.length };
 }
-async function uploadFile(args) {
-    const cfg = resolveConfig();
-    const localPath = requireString(args, "local_path");
-    const alt = typeof args.alt === "string" ? args.alt : undefined;
+/* ─── Moodboard, palette, products, locations, gear, shots helpers ─── */
+async function uploadLocalImage(cfg, localPath) {
     const { readFile, stat } = await import("node:fs/promises");
-    const { basename, extname } = await import("node:path");
-    const info = await stat(localPath);
+    const { basename, extname, isAbsolute, resolve: resolvePath } = await import("node:path");
+    const abs = isAbsolute(localPath) ? localPath : resolvePath(process.cwd(), localPath);
+    const info = await stat(abs);
     if (!info.isFile())
         throw new Error(`Not a file: ${localPath}`);
-    const filename = basename(localPath);
+    const filename = basename(abs);
     const ext = extname(filename).toLowerCase();
     const contentTypes = {
         ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
         ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
-        ".mp4": "video/mp4", ".mov": "video/quicktime", ".pdf": "application/pdf",
-        ".txt": "text/plain", ".md": "text/markdown", ".json": "application/json",
-        ".csv": "text/csv",
+        ".heic": "image/heic", ".heif": "image/heif", ".avif": "image/avif",
     };
     const contentType = contentTypes[ext] ?? "application/octet-stream";
-    // Step 1: signed URL
-    const { data: signRes } = await apiRequest(cfg, "/api/v1/files/upload-url", {
-        method: "POST",
-        body: { filename },
-    });
-    // Step 2: PUT bytes
-    const bytes = await readFile(localPath);
+    const { data: signRes } = await apiRequest(cfg, "/api/v1/files/upload-url", { method: "POST", body: { filename } });
+    const bytes = await readFile(abs);
     const putRes = await fetch(signRes.upload_url, {
         method: "PUT",
         headers: { "Content-Type": contentType, "x-upsert": "false" },
         body: bytes,
     });
     if (!putRes.ok) {
-        const text = await putRes.text().catch(() => "");
-        throw new Error(`Storage upload failed (HTTP ${putRes.status}): ${text.slice(0, 200)}`);
+        throw new Error(`Storage upload failed (HTTP ${putRes.status}) for ${localPath}`);
     }
-    // Step 3: register metadata
-    const { data: reg } = await apiRequest(cfg, "/api/v1/files", {
-        method: "POST",
-        body: { path: signRes.path, alt },
+    try {
+        await apiRequest(cfg, "/api/v1/files", {
+            method: "POST",
+            body: { path: signRes.path },
+        });
+    }
+    catch { /* metadata optional */ }
+    return signRes.path;
+}
+function looksLikeStorageKey(input) {
+    if (/^https?:\/\//.test(input))
+        return false;
+    if (/^[a-zA-Z]:\\/.test(input))
+        return false; // Windows absolute
+    if (input.startsWith("/"))
+        return false; // POSIX absolute
+    if (input.startsWith("./") || input.startsWith("../"))
+        return false;
+    if (/^[a-f0-9]{8}-[a-f0-9]{4}/i.test(input))
+        return true;
+    if (input.includes("/files/") || input.includes("/photos/"))
+        return true;
+    return false;
+}
+function randId(prefix) {
+    return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/** Shared get-template → mutate sections → put-template flow. */
+async function patchTemplateSections(cfg, docId, mutate) {
+    const { data: current } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`);
+    const existingSections = Array.isArray(current.template_content?.sections)
+        ? current.template_content.sections
+        : [];
+    const { sections: nextSections, message } = mutate([...existingSections]);
+    const nextContent = {
+        ...(current.template_content ?? { sections: [] }),
+        sections: nextSections,
+    };
+    try {
+        const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template`, {
+            method: "PUT",
+            body: { template_content: nextContent, ...(message ? { message } : {}) },
+            ifMatch: current.etag,
+        });
+        return { etag: data.etag, updated_at: data.updated_at };
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 409) {
+            throw new Error("Doc was modified since we fetched it — rerun to pick up concurrent edits.");
+        }
+        throw e;
+    }
+}
+async function buildMoodboard(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const paths = args.image_paths;
+    if (!Array.isArray(paths))
+        throw new Error("`image_paths` must be an array of strings.");
+    const rows = typeof args.rows === "number" ? Math.max(1, Math.round(args.rows)) : 3;
+    const cols = typeof args.cols === "number" ? Math.max(1, Math.round(args.cols)) : 3;
+    const aspect = typeof args.aspect === "string" ? args.aspect : "square";
+    const title = typeof args.title === "string" ? args.title : "Moodboard";
+    const spacing = typeof args.spacing === "number" ? args.spacing : 8;
+    const radius = typeof args.radius === "number" ? args.radius : 8;
+    const position = typeof args.position === "number" ? Math.round(args.position) : null;
+    let uploadedCount = 0;
+    const storageKeys = [];
+    for (const p of paths) {
+        if (typeof p !== "string" || !p)
+            continue;
+        if (looksLikeStorageKey(p)) {
+            storageKeys.push(p);
+        }
+        else {
+            const key = await uploadLocalImage(cfg, p);
+            storageKeys.push(key);
+            uploadedCount++;
+        }
+    }
+    const total = rows * cols;
+    const images = [];
+    for (let i = 0; i < total; i++) {
+        images.push(storageKeys[i] ? { url: storageKeys[i] } : null);
+    }
+    const sectionId = randId("sec");
+    const result = await patchTemplateSections(cfg, docId, (sections) => {
+        const section = {
+            id: sectionId,
+            type: "moodboard",
+            data: { title, rows, cols, aspect, spacing, radius, images },
+        };
+        const next = [...sections];
+        if (position !== null && Number.isFinite(position)) {
+            next.splice(Math.max(0, Math.min(position, next.length)), 0, section);
+        }
+        else {
+            next.push(section);
+        }
+        return { sections: next, message: "Add moodboard section" };
     });
     return {
-        path: signRes.path,
-        size: info.size,
-        content_type: contentType,
-        metadata: reg.file,
+        section_id: sectionId,
+        uploaded_count: uploadedCount,
+        total_slots: total,
+        etag: result.etag,
     };
 }
-async function getFileUrl(args) {
+async function extractPaletteTool(args) {
     const cfg = resolveConfig();
-    const path = requireString(args, "path");
-    const { data } = await apiRequest(cfg, "/api/v1/files", { query: { limit: 500 } });
-    const match = data.files.find((f) => f.path === path);
-    if (!match)
-        throw new Error(`File not found or no metadata row: ${path}`);
-    return { path: match.path, url: match.signed_url, alt: match.alt };
+    const docId = requireString(args, "doc_id");
+    const sectionId = requireString(args, "moodboard_section_id");
+    const body = {};
+    if (typeof args.rows === "number")
+        body.rows = args.rows;
+    if (typeof args.cols === "number")
+        body.cols = args.cols;
+    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/sections/${sectionId}/extract-palette`, { method: "POST", body });
+    return {
+        palette_section_id: data.palette_section.id,
+        colours: data.extracted.map((c) => c.hex),
+        etag: data.etag,
+    };
 }
-async function setFileAlt(args) {
+async function searchProducts(args) {
     const cfg = resolveConfig();
-    const path = requireString(args, "path");
-    const alt = typeof args.alt === "string" ? args.alt : null;
-    const { data } = await apiRequest(cfg, "/api/v1/files/alt", {
-        method: "POST",
-        body: { path, alt },
-    });
+    const query = typeof args.query === "string" ? args.query : "";
+    const limit = typeof args.limit === "number" ? args.limit : 25;
+    const { data } = await apiRequest(cfg, "/api/v1/products/search", { query: { q: query, limit } });
     return data;
 }
-async function deleteFile(args) {
+async function addProductsToDoc(args) {
     const cfg = resolveConfig();
-    const path = requireString(args, "path");
-    const { data } = await apiRequest(cfg, "/api/v1/files", {
-        method: "DELETE",
-        query: { path },
+    const docId = requireString(args, "doc_id");
+    const ids = args.shopify_product_ids;
+    if (!Array.isArray(ids) || ids.length === 0) {
+        throw new Error("`shopify_product_ids` must be a non-empty array of strings.");
+    }
+    const sectionId = typeof args.section_id === "string" ? args.section_id : null;
+    const title = typeof args.title === "string" ? args.title : "Products";
+    // Pull a wide window of live products and filter by id client-side.
+    // Keeps the API surface small (no per-id endpoint yet) and the search
+    // response already carries the full snapshot shape.
+    const { data: searchRes } = await apiRequest(cfg, "/api/v1/products/search", { query: { q: "", limit: 100 } });
+    const byId = new Map(searchRes.products.map((p) => [p.shopifyProductId, p]));
+    const items = [];
+    const missing = [];
+    for (const id of ids) {
+        if (typeof id !== "string")
+            continue;
+        const hit = byId.get(id);
+        if (!hit) {
+            missing.push(id);
+            continue;
+        }
+        items.push({
+            id: randId("prod"),
+            source: "shopify",
+            title: hit.title,
+            ...(hit.price ? { price: hit.price } : {}),
+            ...(hit.imageUrl ? { imageUrl: hit.imageUrl } : {}),
+            handle: hit.handle,
+            shopifyProductId: hit.shopifyProductId,
+            vendor: hit.vendor,
+            status: hit.status,
+        });
+    }
+    if (items.length === 0) {
+        throw new Error(`None of the requested product ids are in the first 100 live products. Missing: ${missing.join(", ")}`);
+    }
+    let targetId = sectionId;
+    const res = await patchTemplateSections(cfg, docId, (sections) => {
+        if (targetId) {
+            const idx = sections.findIndex((s) => s.id === targetId);
+            if (idx === -1)
+                throw new Error(`Section '${targetId}' not found`);
+            if (sections[idx].type !== "products") {
+                throw new Error(`Section '${targetId}' is '${sections[idx].type}', not 'products'`);
+            }
+            const existing = (sections[idx].data ?? {});
+            const prevItems = Array.isArray(existing.items) ? existing.items : [];
+            sections[idx] = {
+                ...sections[idx],
+                data: { ...(sections[idx].data ?? {}), items: [...prevItems, ...items] },
+            };
+        }
+        else {
+            targetId = randId("sec");
+            sections.push({
+                id: targetId,
+                type: "products",
+                data: { title, items },
+            });
+        }
+        return { sections, message: "Add products to doc" };
     });
+    return { section_id: targetId, added: items.length, missing, etag: res.etag };
+}
+async function resolveLocationTool(args) {
+    const cfg = resolveConfig();
+    const query = requireString(args, "query");
+    const { data } = await apiRequest(cfg, "/api/v1/locations/resolve", { query: { query } });
     return data;
 }
-/* ─── Gear tools ───────────────────────────────────────────────────── */
-async function listGear(args) {
+async function addLocationToDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const address = typeof args.address === "string" ? args.address : null;
+    const placeId = typeof args.place_id === "string" ? args.place_id : null;
+    if (!address && !placeId) {
+        throw new Error("Provide `address` or `place_id`.");
+    }
+    const nickname = typeof args.nickname === "string" ? args.nickname : null;
+    const notes = typeof args.notes === "string" ? args.notes : null;
+    const sectionId = typeof args.section_id === "string" ? args.section_id : null;
+    const title = typeof args.title === "string" ? args.title : "Locations";
+    const q = address ?? placeId;
+    const { data: resolved } = await apiRequest(cfg, "/api/v1/locations/resolve", { query: { query: q } });
+    let hit = resolved.results[0] ?? null;
+    if (placeId) {
+        hit = resolved.results.find((r) => r.place_id === placeId) ?? hit;
+    }
+    if (!hit)
+        throw new Error(`No Google Places match for '${q}'`);
+    const item = {
+        id: randId("loc"),
+        mode: "auto",
+        nickname: nickname ?? hit.text,
+        ...(notes ? { notes } : {}),
+        location: {
+            place_id: hit.place_id,
+            text: hit.text,
+            lat: hit.lat,
+            lng: hit.lng,
+            verified: true,
+        },
+    };
+    let targetId = sectionId;
+    const res = await patchTemplateSections(cfg, docId, (sections) => {
+        if (targetId) {
+            const idx = sections.findIndex((s) => s.id === targetId);
+            if (idx === -1)
+                throw new Error(`Section '${targetId}' not found`);
+            if (sections[idx].type !== "locations") {
+                throw new Error(`Section '${targetId}' is '${sections[idx].type}', not 'locations'`);
+            }
+            const existing = (sections[idx].data ?? {});
+            const prevItems = Array.isArray(existing.items) ? existing.items : [];
+            sections[idx] = {
+                ...sections[idx],
+                data: { ...(sections[idx].data ?? {}), items: [...prevItems, item] },
+            };
+        }
+        else {
+            targetId = randId("sec");
+            sections.push({
+                id: targetId,
+                type: "locations",
+                data: { title, items: [item] },
+            });
+        }
+        return { sections, message: "Add location to doc" };
+    });
+    return { section_id: targetId, item, etag: res.etag };
+}
+async function addGearToDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const ids = args.gear_ids;
+    if (!Array.isArray(ids) || ids.length === 0) {
+        throw new Error("`gear_ids` must be a non-empty array of UUIDs.");
+    }
+    const gearIds = ids.filter((v) => typeof v === "string" && !!v);
+    const sectionId = typeof args.section_id === "string" ? args.section_id : null;
+    const title = typeof args.title === "string" ? args.title : "Gear";
+    const format = typeof args.format === "string" ? args.format : "table";
+    let targetId = sectionId;
+    const res = await patchTemplateSections(cfg, docId, (sections) => {
+        if (targetId) {
+            const idx = sections.findIndex((s) => s.id === targetId);
+            if (idx === -1)
+                throw new Error(`Section '${targetId}' not found`);
+            if (sections[idx].type !== "gear") {
+                throw new Error(`Section '${targetId}' is '${sections[idx].type}', not 'gear'`);
+            }
+            const existing = (sections[idx].data ?? {});
+            const prev = Array.isArray(existing.itemIds)
+                ? existing.itemIds
+                : [];
+            const merged = Array.from(new Set([...prev, ...gearIds]));
+            sections[idx] = {
+                ...sections[idx],
+                data: { ...(sections[idx].data ?? {}), itemIds: merged },
+            };
+        }
+        else {
+            targetId = randId("sec");
+            sections.push({
+                id: targetId,
+                type: "gear",
+                data: { title, itemIds: gearIds, format },
+            });
+        }
+        return { sections, message: "Add gear to doc" };
+    });
+    return { section_id: targetId, added: gearIds.length, etag: res.etag };
+}
+async function addShotsToDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const ids = args.shot_ids;
+    if (!Array.isArray(ids) || ids.length === 0) {
+        throw new Error("`shot_ids` must be a non-empty array of UUIDs.");
+    }
+    const shotIds = ids.filter((v) => typeof v === "string" && !!v);
+    const sectionId = typeof args.section_id === "string" ? args.section_id : null;
+    const title = typeof args.title === "string" ? args.title : "Shot list";
+    // Pull a wide shot-library window and snapshot name/kind/notes into
+    // rows. Matches the shot-list section's row shape in doc-presets.ts.
+    const { data } = await apiRequest(cfg, "/api/v1/shots", { query: { limit: 500 } });
+    const byId = new Map(data.items.map((s) => [s.id, s]));
+    const rows = [];
+    const missing = [];
+    for (const id of shotIds) {
+        const hit = byId.get(id);
+        if (!hit) {
+            missing.push(id);
+            continue;
+        }
+        rows.push({
+            id: randId("sr"),
+            name: hit.name,
+            kind: hit.kind ?? "",
+            lens: "",
+            notes: hit.notes ?? "",
+        });
+    }
+    if (rows.length === 0) {
+        throw new Error(`None of the shot ids were found. Missing: ${missing.join(", ")}`);
+    }
+    let targetId = sectionId;
+    const res = await patchTemplateSections(cfg, docId, (sections) => {
+        if (targetId) {
+            const idx = sections.findIndex((s) => s.id === targetId);
+            if (idx === -1)
+                throw new Error(`Section '${targetId}' not found`);
+            if (sections[idx].type !== "shot-list") {
+                throw new Error(`Section '${targetId}' is '${sections[idx].type}', not 'shot-list'`);
+            }
+            const existing = (sections[idx].data ?? {});
+            const prev = Array.isArray(existing.rows) ? existing.rows : [];
+            sections[idx] = {
+                ...sections[idx],
+                data: { ...(sections[idx].data ?? {}), rows: [...prev, ...rows] },
+            };
+        }
+        else {
+            targetId = randId("sec");
+            sections.push({
+                id: targetId,
+                type: "shot-list",
+                data: { title, rows },
+            });
+        }
+        return { sections, message: "Add shots to doc" };
+    });
+    return { section_id: targetId, added: rows.length, missing, etag: res.etag };
+}
+/* ─── Mindmap tools ────────────────────────────────────────────────── */
+async function listMindmaps_(args) {
     const cfg = resolveConfig();
     const query = {};
     if (typeof args.limit === "number")
         query.limit = args.limit;
     if (typeof args.cursor === "string")
         query.cursor = args.cursor;
-    const { data } = await apiRequest(cfg, "/api/v1/gear", { query });
+    const { data } = await apiRequest(cfg, "/api/v1/mindmaps", { query });
     return data;
 }
-async function addGear(args) {
+async function getMindmap_(args) {
     const cfg = resolveConfig();
-    const body = { name: requireString(args, "name") };
-    if (typeof args.brand === "string")
-        body.brand = args.brand;
-    if (typeof args.quantity === "number")
-        body.quantity = args.quantity;
-    if (typeof args.image_path === "string")
-        body.image_path = args.image_path;
-    const { data } = await apiRequest(cfg, "/api/v1/gear", {
-        method: "POST",
-        body,
-    });
+    const mindmapId = requireString(args, "mindmapId");
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}`);
     return data;
 }
-async function importGear(args) {
+async function createMindmap_(args) {
     const cfg = resolveConfig();
-    const rows = args.rows;
-    if (!Array.isArray(rows))
-        throw new Error("`rows` must be an array.");
-    const mode = args.mode === "replace" ? "replace" : "append";
-    const { data } = await apiRequest(cfg, "/api/v1/gear/import", {
+    const title = requireString(args, "title");
+    const body = { title };
+    if (typeof args.description === "string")
+        body.description = args.description;
+    if (typeof args.shoot_id === "string")
+        body.shoot_id = args.shoot_id;
+    if (Array.isArray(args.nodes))
+        body.nodes = args.nodes;
+    if (Array.isArray(args.edges))
+        body.edges = args.edges;
+    const { data } = await apiRequest(cfg, "/api/v1/mindmaps", {
         method: "POST",
-        body: { mode, rows },
+        body,
     });
     return data;
 }
-async function deleteGear(args) {
+async function deleteMindmap_(args) {
     const cfg = resolveConfig();
-    const gearId = requireString(args, "gearId");
-    const { data } = await apiRequest(cfg, `/api/v1/gear/${gearId}`, {
+    const mindmapId = requireString(args, "mindmapId");
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}`, {
         method: "DELETE",
     });
     return data;
 }
-async function updateGear(args) {
+async function updateMindmap_(args) {
     const cfg = resolveConfig();
-    const gearId = requireString(args, "gearId");
+    const mindmapId = requireString(args, "mindmapId");
     const body = {};
-    if (typeof args.name === "string")
-        body.name = args.name;
-    if (typeof args.brand === "string")
-        body.brand = args.brand;
-    if (typeof args.quantity === "number")
-        body.quantity = args.quantity;
-    if (typeof args.image_path === "string")
-        body.image_path = args.image_path;
+    if (typeof args.title === "string")
+        body.title = args.title;
+    if (args.description === null || typeof args.description === "string") {
+        body.description = args.description;
+    }
+    if (args.shoot_id === null || typeof args.shoot_id === "string") {
+        body.shoot_id = args.shoot_id;
+    }
     if (Object.keys(body).length === 0) {
-        throw new Error("At least one of name, brand, quantity, image_path is required.");
+        throw new Error("Provide at least one of title, description, shoot_id.");
     }
-    const { data } = await apiRequest(cfg, `/api/v1/gear/${gearId}`, {
-        method: "PUT",
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}`, {
+        method: "PATCH",
         body,
     });
     return data;
 }
-/* ─── Files rename ─────────────────────────────────────────────────── */
-async function renameFile(args) {
+async function addMindmapNode_(args) {
     const cfg = resolveConfig();
-    const path = requireString(args, "path");
-    const newName = requireString(args, "new_name");
-    const { data } = await apiRequest(cfg, "/api/v1/files/rename", {
+    const mindmapId = requireString(args, "mindmapId");
+    const body = {};
+    for (const key of [
+        "label",
+        "title",
+        "description",
+        "shape",
+        "kind",
+        "colour_key",
+        "image_url",
+        "image_alt",
+        "text_color",
+        "bg_color",
+    ]) {
+        if (typeof args[key] === "string")
+            body[key] = args[key];
+    }
+    for (const key of ["x", "y", "width", "height", "font_size", "order_index"]) {
+        if (typeof args[key] === "number")
+            body[key] = args[key];
+    }
+    if (typeof args.completed === "boolean")
+        body.completed = args.completed;
+    if (!body.label && !body.title) {
+        throw new Error("`label` or `title` is required.");
+    }
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}/nodes`, {
         method: "POST",
-        body: { path, new_name: newName },
+        body,
     });
     return data;
 }
-/* ─── Revisions ────────────────────────────────────────────────────── */
-async function listRevisions(args) {
+async function updateMindmapNode_(args) {
+    const cfg = resolveConfig();
+    const mindmapId = requireString(args, "mindmapId");
+    const nodeId = requireString(args, "nodeId");
+    const body = {};
+    for (const key of [
+        "label",
+        "title",
+        "description",
+        "shape",
+        "kind",
+        "colour_key",
+        "image_url",
+        "image_alt",
+        "text_color",
+        "bg_color",
+    ]) {
+        if (typeof args[key] === "string")
+            body[key] = args[key];
+    }
+    for (const key of ["x", "y", "width", "height", "font_size", "order_index"]) {
+        if (typeof args[key] === "number")
+            body[key] = args[key];
+    }
+    if (typeof args.completed === "boolean")
+        body.completed = args.completed;
+    if (Object.keys(body).length === 0) {
+        throw new Error("Provide at least one field to patch.");
+    }
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}/nodes/${nodeId}`, { method: "PATCH", body });
+    return data;
+}
+async function deleteMindmapNode_(args) {
+    const cfg = resolveConfig();
+    const mindmapId = requireString(args, "mindmapId");
+    const nodeId = requireString(args, "nodeId");
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}/nodes/${nodeId}`, { method: "DELETE" });
+    return data;
+}
+async function addMindmapEdge_(args) {
+    const cfg = resolveConfig();
+    const mindmapId = requireString(args, "mindmapId");
+    const from_node_id = requireString(args, "from_node_id");
+    const to_node_id = requireString(args, "to_node_id");
+    const body = { from_node_id, to_node_id };
+    if (typeof args.label === "string")
+        body.label = args.label;
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}/edges`, { method: "POST", body });
+    return data;
+}
+async function deleteMindmapEdge_(args) {
+    const cfg = resolveConfig();
+    const mindmapId = requireString(args, "mindmapId");
+    const edgeId = requireString(args, "edgeId");
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}/edges/${edgeId}`, { method: "DELETE" });
+    return data;
+}
+async function createMindmapGroup_(args) {
+    const cfg = resolveConfig();
+    const mindmapId = requireString(args, "mindmapId");
+    const nodes = Array.isArray(args.nodes)
+        ? args.nodes.filter((v) => typeof v === "string" && !!v)
+        : [];
+    if (nodes.length === 0) {
+        throw new Error("`nodes` must be a non-empty array of node ids.");
+    }
+    const edges = Array.isArray(args.edges)
+        ? args.edges.filter((v) => typeof v === "string" && !!v)
+        : [];
+    const body = { nodes };
+    if (edges.length > 0)
+        body.edges = edges;
+    if (typeof args.name === "string")
+        body.name = args.name;
+    else if (typeof args.title === "string")
+        body.name = args.title;
+    if (typeof args.bg_color === "string")
+        body.bg_color = args.bg_color;
+    if (typeof args.outline_color === "string")
+        body.outline_color = args.outline_color;
+    if (typeof args.outline_width === "number")
+        body.outline_width = args.outline_width;
+    if (typeof args.corner_radius === "number")
+        body.corner_radius = args.corner_radius;
+    if (typeof args.padding === "number")
+        body.padding = args.padding;
+    if (typeof args.custom_css === "string")
+        body.custom_css = args.custom_css;
+    const { data } = await apiRequest(cfg, `/api/v1/mindmaps/${mindmapId}/groups`, { method: "POST", body });
+    return data;
+}
+/* ─── Activity log ─────────────────────────────────────────────────── */
+async function listActivity_(args) {
     const cfg = resolveConfig();
-    const docId = requireString(args, "docId");
     const query = {};
     if (typeof args.limit === "number")
         query.limit = args.limit;
-    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/revisions`, { query });
+    if (typeof args.cursor === "string")
+        query.cursor = args.cursor;
+    if (typeof args.since === "string")
+        query.since = args.since;
+    if (typeof args.until === "string")
+        query.until = args.until;
+    if (typeof args.user === "string")
+        query.user = args.user;
+    if (typeof args.source === "string")
+        query.source = args.source;
+    if (typeof args.action === "string")
+        query.action = args.action;
+    if (typeof args.resource_type === "string")
+        query.resource_type = args.resource_type;
+    const { data } = await apiRequest(cfg, "/api/v1/activity", { query });
     return data;
 }
-async function restoreRevision(args) {
+async function getActivity_(args) {
     const cfg = resolveConfig();
-    const docId = requireString(args, "docId");
-    const revisionId = requireString(args, "revisionId");
-    const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/revisions/${revisionId}/restore`, {
+    const entryId = requireString(args, "entryId");
+    const { data } = await apiRequest(cfg, `/api/v1/activity/${entryId}`);
+    return data;
+}
+/* ─── Mindmap export (PDF / PNG / SVG) ───────────────────────────── */
+async function exportMindmapTool(args) {
+    const cfg = resolveConfig();
+    const mindmapId = requireString(args, "mindmap_id");
+    const formatRaw = typeof args.format === "string" ? args.format.toLowerCase() : "pdf";
+    const format = (formatRaw === "svg" || formatRaw === "png" || formatRaw === "pdf" ? formatRaw : "pdf");
+    const openFile = args.open !== false;
+    const dpi = Math.max(1, Math.min(3, Number(args.dpi ?? 2)));
+    const w = Math.max(320, Math.min(7680, Number(args.w ?? 1920)));
+    const h = Math.max(240, Math.min(7680, Number(args.h ?? 1080)));
+    // Shared out-path resolver.
+    const { resolve: resolvePath, isAbsolute } = await import("node:path");
+    const { writeFile } = await import("node:fs/promises");
+    if (format === "svg") {
+        const url = new URL(`/api/v1/mindmaps/${mindmapId}/export`, cfg.apiUrl);
+        url.searchParams.set("format", "svg");
+        const res = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${cfg.token}`,
+                Accept: "image/svg+xml",
+                "User-Agent": "atlas-mcp/0.1.0",
+            },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`SVG export failed (${res.status}): ${text}`);
+        }
+        const bytes = Buffer.from(await res.arrayBuffer());
+        const stub = `mindmap-${mindmapId.slice(0, 8)}`;
+        const outPathRaw = typeof args.out_path === "string" && args.out_path.trim()
+            ? args.out_path
+            : `${stub}.svg`;
+        const outPath = isAbsolute(outPathRaw) ? outPathRaw : resolvePath(process.cwd(), outPathRaw);
+        await writeFile(outPath, bytes);
+        if (openFile)
+            openWithOs(outPath);
+        return { out_path: outPath, format: "svg", bytes: bytes.length };
+    }
+    // PDF / PNG — mint a token, drive Playwright.
+    const tokenUrl = new URL(`/api/v1/mindmaps/${mindmapId}/export-token`, cfg.apiUrl);
+    const tokRes = await fetch(tokenUrl, {
         method: "POST",
+        headers: {
+            Authorization: `Bearer ${cfg.token}`,
+            Accept: "application/json",
+            "User-Agent": "atlas-mcp/0.1.0",
+        },
     });
-    return {
-        docId: data.id,
-        title: data.title,
-        updated_at: data.updated_at,
-        etag: data.etag,
-        restored_from: data.restored_from,
-    };
-}
-/* ─── Helpers ──────────────────────────────────────────────────────── */
-function requireString(args, key) {
-    const v = args[key];
-    if (typeof v !== "string" || !v)
-        throw new Error(`\`${key}\` is required.`);
-    return v;
+    if (!tokRes.ok) {
+        const text = await tokRes.text().catch(() => "");
+        throw new Error(`Export-token request failed (${tokRes.status}): ${text}`);
+    }
+    const tok = (await tokRes.json());
+    const { chromium } = await import("playwright-core");
+    const browser = await chromium.launch({ headless: true });
+    let outBuffer;
+    try {
+        const context = await browser.newContext({
+            viewport: { width: w, height: h },
+            deviceScaleFactor: dpi,
+            locale: "en-AU",
+        });
+        await context.addCookies([
+            {
+                name: tok.cookieName,
+                value: tok.token,
+                url: new URL(tok.mindmapUrl).origin,
+                httpOnly: true,
+                secure: tok.mindmapUrl.startsWith("https:"),
+                sameSite: "Lax",
+            },
+        ]);
+        const page = await context.newPage();
+        const url = new URL(tok.mindmapUrl);
+        url.searchParams.set("w", String(w));
+        url.searchParams.set("h", String(h));
+        await page.goto(url.toString(), { waitUntil: "domcontentloaded", timeout: 60_000 });
+        await page.waitForSelector(".mindmap-export-ready", { timeout: 30_000 });
+        if (format === "pdf") {
+            outBuffer = Buffer.from(await page.pdf({
+                width: `${w}px`,
+                height: `${h}px`,
+                printBackground: true,
+                margin: { top: "0mm", right: "0mm", bottom: "0mm", left: "0mm" },
+            }));
+        }
+        else {
+            outBuffer = Buffer.from(await page.screenshot({
+                type: "png",
+                clip: { x: 0, y: 0, width: w, height: h },
+                omitBackground: false,
+            }));
+        }
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+    const safeTitle = (tok.title || "mindmap")
+        .replace(/[^\w\s.-]+/g, "")
+        .replace(/\s+/g, "-")
+        .slice(0, 60) || "mindmap";
+    const outPathRaw = typeof args.out_path === "string" && args.out_path.trim()
+        ? args.out_path
+        : `${safeTitle}.${format}`;
+    const outPath = isAbsolute(outPathRaw) ? outPathRaw : resolvePath(process.cwd(), outPathRaw);
+    await writeFile(outPath, outBuffer);
+    if (openFile)
+        openWithOs(outPath);
+    return { out_path: outPath, format, bytes: outBuffer.length };
 }
-function isRecord(v) {
-    return typeof v === "object" && v !== null;
+function openWithOs(path) {
+    // Non-blocking OS "open" — ignores failures (file is already on disk).
+    import("node:child_process").then(({ spawn }) => {
+        try {
+            if (process.platform === "win32") {
+                spawn("cmd", ["/c", "start", "", path], { detached: true, stdio: "ignore" }).unref();
+            }
+            else if (process.platform === "darwin") {
+                spawn("open", [path], { detached: true, stdio: "ignore" }).unref();
+            }
+            else {
+                spawn("xdg-open", [path], { detached: true, stdio: "ignore" }).unref();
+            }
+        }
+        catch {
+            /* non-fatal */
+        }
+    });
 }
 /* ─── Boot ─────────────────────────────────────────────────────────── */
 async function main() {