@kezlahd/atlas-mcp 0.2.1 → 0.3.0

package/dist/index.js

@@ -48,7 +48,7 @@ const TOOLS = [
     },
     {
         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).",
+        description: "Create a new doc. For a structured doc, prefer atlas_create_doc_from_preset — it stamps a cover + relevant section skeleton. For a hand-rolled doc, pass template_content: { cover: { subtitle }, sections: [...] }; a cover is strongly recommended as the first element. Returns { id, etag, ... }; pipe into atlas_update_section / atlas_build_moodboard / atlas_add_products_to_doc / atlas_add_section / atlas_update_cover etc. to fill sections one at a time (safer than another full-template PUT, which fights the web editor's autosave).",
         inputSchema: {
             type: "object",
             properties: {
@@ -173,7 +173,7 @@ const TOOLS = [
     },
     {
         name: "atlas_update_section",
-        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.",
+        description: "Edit ONE existing section by id — this tool cannot create sections. Use atlas_add_section, atlas_update_template, or a dedicated add-tool (atlas_build_moodboard, atlas_add_products_to_doc, …) to create. Fields: `data` REPLACES the section's data object (per-key merge is ambiguous for arrays); `style` merges over existing style keys; `hidden: true/false` toggles visibility (hidden sections stay in the doc but are omitted from the printed output — use this instead of deleting a section the user might want back). On concurrent edit the tool auto-retries once (re-GET → re-apply → re-PATCH); if the second attempt also races, bubble the error so the user can decide whether to force.",
         inputSchema: {
             type: "object",
             properties: {
@@ -213,7 +213,7 @@ const TOOLS = [
     },
     {
         name: "atlas_describe_section_type",
-        description: "Look up what fields a section type takes. Use this before atlas_update_section so you send the right shape. If called with no `type`, returns the full catalogue of known section types.",
+        description: "Look up a section type's shape BEFORE calling atlas_update_section / atlas_add_section. Returns { type, purpose, data_shape, common_fields, hidden_supported: true }. Every section accepts a top-level `hidden: boolean`. Image/asset fields (moodboard images[].url, cover bgImageUrl, cover presentedBy.logoUrl, people-link photoUrl) require a SIGNED URL, not a storage key — pass storage keys through atlas_get_file_url first. Call with no `type` for the full catalogue of known types.",
         inputSchema: {
             type: "object",
             properties: {
@@ -241,7 +241,7 @@ const TOOLS = [
     },
     {
         name: "atlas_upload_file",
-        description: "Upload a local file (path on the user's machine) to the workspace bucket. Three-step signed-URL flow. Returns the storage path + a 1-hour signed URL. Extension whitelist enforced (images/video/audio/pdf/txt/md/json/csv); executables/archives refused.",
+        description: "Upload a local file (path on the user's machine) to the workspace bucket. Three-step signed-URL flow. Returns the storage path AND a long-lived (1-year) signed URL — drop the signed URL straight into section fields (moodboard images[].url, cover bgImageUrl, people-link photoUrl, …) that need a URL rather than a storage key. Extension whitelist enforced (images/video/audio/pdf/txt/md/json/csv); executables/archives refused.",
         inputSchema: {
             type: "object",
             properties: {
@@ -967,7 +967,7 @@ const TOOLS = [
     },
     {
         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'.",
+        description: "Build a moodboard section wired to real images. Uploads any local paths through the signed-URL flow, re-uses already-uploaded storage keys, SIGNS every storage key into a 1-year signed URL before storing it on the section (raw storage keys render as 404s), and appends (or inserts at `position`) a moodboard section with the shape { title, rows, cols, aspect, spacing, radius, images: [{ id, alt?, url (signed) } | null] }. images.length === rows*cols; empty slots are null. Default 3×3 square. 20 MB per-file limit. For colour extraction, follow with atlas_extract_palette.",
         inputSchema: {
             type: "object",
             properties: {
@@ -997,7 +997,7 @@ const TOOLS = [
     },
     {
         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[] }.",
+        description: "Append a palette section wired to a moodboard. The moodboard must already contain at least one image (storage keys are re-signed server-side for extraction). Writes { title, sourceId, rows, cols, numColors: rows*cols, extractedColours: [{ hex, weight }] } and inserts the palette right below the source moodboard. Returns { palette_section_id, colours }. If called twice on the same moodboard the existing palette section is patched in place.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1116,6 +1116,96 @@ const TOOLS = [
             required: ["doc_id", "shot_ids"],
         },
     },
+    {
+        name: "atlas_add_calendar_event_to_doc",
+        description: "Schedule a shoot AND wire its id into a calendar-event section in one call. Creates the event via /api/v1/events, then either appends the new event id to section_id's `eventIds` (must be a calendar-event section) or creates a new calendar-event section with it. Use when a doc needs to reference a shoot that doesn't exist yet — calendar-event sections only embed already-scheduled shoots, atlas_create_event on its own won't surface in the doc.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                section_id: {
+                    type: "string",
+                    description: "Append to this existing calendar-event section. Omit to create a new section at the end of the doc.",
+                },
+                title: {
+                    type: "string",
+                    description: "Section title when creating a new section (default 'Schedule').",
+                },
+                layout: {
+                    type: "string",
+                    enum: ["card", "table", "banner"],
+                    description: "Section layout when creating. Default 'card'.",
+                },
+                event: {
+                    type: "object",
+                    description: "Shoot payload — same shape as atlas_create_event. `title` + `starts_at` required.",
+                    properties: {
+                        title: { type: "string" },
+                        starts_at: { type: "string", description: "ISO 8601 start." },
+                        ends_at: { type: "string", description: "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: ["title", "starts_at"],
+                },
+            },
+            required: ["doc_id", "event"],
+        },
+    },
+    {
+        name: "atlas_add_section",
+        description: "Generic 'create section' for any type that doesn't have a dedicated add-tool (text, notes, table, code-block, calendar-event, people-link, toc, …). Uses the scoped append endpoint — doesn't fight the web editor's autosave the way a full-template PUT does. Call atlas_describe_section_type first to learn the data shape for your target type.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                type: {
+                    type: "string",
+                    description: "Section type — e.g. 'text', 'notes', 'table', 'code-block', 'calendar-event', 'people-link', 'toc'. See atlas_describe_section_type for the full list.",
+                },
+                data: {
+                    type: "object",
+                    description: "section.data payload matching the type's shape. Use atlas_describe_section_type for field names.",
+                },
+                position: {
+                    type: "number",
+                    description: "Insert at this section index. Omit to append.",
+                },
+                hidden: {
+                    type: "boolean",
+                    description: "Mark the new section hidden (dimmed in editor, omitted from printed output). Default false.",
+                },
+            },
+            required: ["doc_id", "type", "data"],
+        },
+    },
+    {
+        name: "atlas_update_cover",
+        description: "Scoped merge-update of the doc cover (title, subtitle, bg image, presentedBy lockup, …). Cover lives on template_content.cover — not in sections[] — so atlas_update_section can't touch it. The server shallow-merges the fields you send, so passing `{ cover: { subtitle: 'x' } }` just updates subtitle. Image fields (bgImageUrl, presentedBy.logoUrl) require a SIGNED URL — pass storage keys through atlas_get_file_url first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                doc_id: { type: "string" },
+                cover: {
+                    type: "object",
+                    description: "Partial cover payload — any subset of { subtitle, date, bgImageUrl, titlePosition, accentColor, presentedBy, ... }.",
+                },
+            },
+            required: ["doc_id", "cover"],
+        },
+    },
     {
         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`).",
@@ -1437,7 +1527,7 @@ const TOOLS = [
     },
 ];
 /* ─── Server setup ─────────────────────────────────────────────────── */
-const server = new Server({ name: "atlas-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "atlas-mcp", version: "0.3.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,
 }));
@@ -1590,6 +1680,12 @@ async function dispatch(name, args) {
             return addGearToDoc(args);
         case "atlas_add_shots_to_doc":
             return addShotsToDoc(args);
+        case "atlas_add_calendar_event_to_doc":
+            return addCalendarEventToDoc(args);
+        case "atlas_add_section":
+            return addSection(args);
+        case "atlas_update_cover":
+            return updateCover(args);
         case "read_achievements":
             return readAchievements();
         case "atlas_list_mindmaps":
@@ -1669,36 +1765,54 @@ async function updateSection(args) {
     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.`);
+    const body = {
+        ...(newData !== undefined ? { data: newData } : {}),
+        ...(newStyle !== undefined ? { style: newStyle } : {}),
+        ...(hidden !== undefined ? { hidden } : {}),
+    };
+    // Retry on precondition failure. The web editor's autosave bumps
+    // updated_at every few seconds, so a GET → PATCH window that spans
+    // one autosave will 412 even when nothing conflicts. The user's
+    // patch intent is the same shape regardless of what the editor
+    // wrote, so re-applying it against the fresh state is safe.
+    const MAX_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        const current = await getTemplate({ docId });
+        try {
+            const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template/sections/${sectionId}`, {
+                method: "PATCH",
+                body,
+                ifMatch: current.etag,
+            });
+            return {
+                updated_section: sectionId,
+                section: data.section,
+                etag: data.etag,
+                updated_at: data.updated_at,
+                ...(attempt > 1 ? { retried: true } : {}),
+            };
         }
-        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 === 404) {
+                throw new Error(`Section '${sectionId}' not found in doc '${docId}'. Call atlas_list_sections to see current section ids.`);
+            }
+            // Server now returns 412 for If-Match failures (RFC 7232); legacy
+            // deployments may still return 409 with the same message, so
+            // treat both as precondition failures.
+            if (e instanceof ApiError &&
+                (e.status === 412 || e.status === 409) &&
+                attempt < MAX_ATTEMPTS) {
+                process.stderr.write(`[atlas-mcp] updateSection ${sectionId}: ${e.status} on attempt ${attempt}, re-fetching + retrying\n`);
+                continue;
+            }
+            if (e instanceof ApiError && (e.status === 412 || e.status === 409)) {
+                throw new Error(`Doc kept racing after ${MAX_ATTEMPTS} attempts — someone else is actively editing. Pause the web editor (or hand off) and retry, or ask the user to make this edit themselves.`);
+            }
+            throw e;
         }
-        throw e;
     }
+    // Unreachable — the loop always either returns or throws.
+    throw new Error("updateSection: unreachable retry fallthrough");
 }
 async function createDoc(args) {
     const cfg = resolveConfig();
@@ -1785,27 +1899,41 @@ async function updateTemplate(args) {
         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,
-            title: data.title,
-            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 — re-run atlas_get_template to pick up the concurrent change, then retry.");
+    // Get-then-put with one retry on concurrent-edit race. The caller
+    // passed us an explicit template_content, so unlike patchTemplateSections
+    // we can't re-apply "the user's intent against fresh state" — the
+    // intent IS the full template. We just re-check the etag and retry.
+    const MAX_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        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,
+                title: data.title,
+                etag: data.etag,
+                updated_at: data.updated_at,
+                ...(attempt > 1 ? { retried: true } : {}),
+            };
+        }
+        catch (e) {
+            if (e instanceof ApiError &&
+                (e.status === 412 || e.status === 409) &&
+                attempt < MAX_ATTEMPTS) {
+                process.stderr.write(`[atlas-mcp] updateTemplate ${docId}: ${e.status} on attempt ${attempt}, re-fetching + retrying\n`);
+                continue;
+            }
+            if (e instanceof ApiError && (e.status === 412 || e.status === 409)) {
+                throw new Error(`Doc kept racing after ${MAX_ATTEMPTS} attempts — someone else is actively editing. Pause the web editor and retry, or ask the user to make this edit themselves.`);
+            }
+            throw e;
         }
-        throw e;
     }
+    throw new Error("updateTemplate: unreachable retry fallthrough");
 }
 async function describeSectionType(args) {
     const type = args.type;
@@ -1871,8 +1999,22 @@ async function uploadFile(args) {
         method: "POST",
         body: { path: signRes.path, alt },
     });
+    // Step 4: mint a long-lived signed URL so the caller can drop it
+    // straight into a section field (moodboard images[].url, cover
+    // bgImageUrl, people-link photoUrl, …) that needs a URL rather than a
+    // storage key.
+    let signedUrl = null;
+    try {
+        const { data: signed } = await apiRequest(cfg, "/api/v1/files/sign", { method: "POST", body: { path: signRes.path } });
+        signedUrl = signed.signed_url;
+    }
+    catch {
+        // Non-fatal — the file is uploaded + registered, caller can mint a
+        // signed URL later with atlas_get_file_url.
+    }
     return {
         path: signRes.path,
+        signed_url: signedUrl,
         size: info.size,
         content_type: contentType,
         metadata: reg.file,
@@ -2436,7 +2578,7 @@ async function uploadWorkspaceLogo(args) {
         headers: {
             Authorization: `Bearer ${cfg.token}`,
             Accept: "application/json",
-            "User-Agent": "atlas-mcp/0.1.0",
+            "User-Agent": "atlas-mcp/0.3.0",
         },
         body: form,
     });
@@ -2469,7 +2611,7 @@ async function exportDocTool(args) {
         headers: {
             Authorization: `Bearer ${cfg.token}`,
             Accept: "text/plain",
-            "User-Agent": "atlas-mcp/0.1.0",
+            "User-Agent": "atlas-mcp/0.3.0",
         },
     });
     if (!res.ok || !res.body) {
@@ -2544,6 +2686,14 @@ async function exportDocTool(args) {
     return { out_path: outPath, pages: done.pages, bytes: bytes.length };
 }
 /* ─── Moodboard, palette, products, locations, gear, shots helpers ─── */
+/** Mint a 1-year signed URL for a storage key. Mirrors the browser
+ * upload path (lib/doc-image-upload.ts), which signs for the same
+ * duration so a doc's images keep rendering across normal lifetimes.
+ * Returns the signed URL (or throws if the API rejects). */
+async function signStorageKey(cfg, path) {
+    const { data } = await apiRequest(cfg, "/api/v1/files/sign", { method: "POST", body: { path } });
+    return data.signed_url;
+}
 async function uploadLocalImage(cfg, localPath) {
     const { readFile, stat } = await import("node:fs/promises");
     const { basename, extname, isAbsolute, resolve: resolvePath } = await import("node:path");
@@ -2596,31 +2746,46 @@ function looksLikeStorageKey(input) {
 function randId(prefix) {
     return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
 }
-/** Shared get-template → mutate sections → put-template flow. */
+/** Shared get-template → mutate sections → put-template flow.
+ *
+ * Retries once on precondition failure (412 — or legacy 409 — from a
+ * concurrent web-editor autosave). The mutate callback is re-run against
+ * the freshly-fetched state so append/insert operations land on top of
+ * whatever the autosave wrote. */
 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.");
+    const MAX_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        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 === 412 || e.status === 409) &&
+                attempt < MAX_ATTEMPTS) {
+                process.stderr.write(`[atlas-mcp] patchTemplateSections ${docId}: ${e.status} on attempt ${attempt}, re-fetching + retrying\n`);
+                continue;
+            }
+            if (e instanceof ApiError && (e.status === 412 || e.status === 409)) {
+                throw new Error(`Doc kept racing after ${MAX_ATTEMPTS} attempts — someone else is actively editing. Pause the web editor and retry.`);
+            }
+            throw e;
         }
-        throw e;
     }
+    throw new Error("patchTemplateSections: unreachable retry fallthrough");
 }
 async function buildMoodboard(args) {
     const cfg = resolveConfig();
@@ -2635,24 +2800,41 @@ async function buildMoodboard(args) {
     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;
+    // For every image — whether we just uploaded it or the caller handed
+    // us a pre-existing storage key — mint a 1-year signed URL. Storing
+    // raw storage keys here would render as 404s (storage objects are
+    // private; the renderer uses `<img src>` with no server rewrite).
     let uploadedCount = 0;
-    const storageKeys = [];
+    const resolved = [];
     for (const p of paths) {
         if (typeof p !== "string" || !p)
             continue;
+        let key;
         if (looksLikeStorageKey(p)) {
-            storageKeys.push(p);
+            key = p;
         }
         else {
-            const key = await uploadLocalImage(cfg, p);
-            storageKeys.push(key);
+            key = await uploadLocalImage(cfg, p);
             uploadedCount++;
         }
+        const signedUrl = await signStorageKey(cfg, key);
+        resolved.push({ key, signedUrl });
     }
     const total = rows * cols;
     const images = [];
     for (let i = 0; i < total; i++) {
-        images.push(storageKeys[i] ? { url: storageKeys[i] } : null);
+        const r = resolved[i];
+        if (r) {
+            images.push({
+                id: randId("img"),
+                url: r.signedUrl,
+                // No per-image alt input yet — tool caller sets alts via the
+                // web editor or atlas_set_file_alt.
+            });
+        }
+        else {
+            images.push(null);
+        }
     }
     const sectionId = randId("sec");
     const result = await patchTemplateSections(cfg, docId, (sections) => {
@@ -2937,6 +3119,171 @@ async function addShotsToDoc(args) {
     });
     return { section_id: targetId, added: rows.length, missing, etag: res.etag };
 }
+/** Schedule a shoot AND wire its id into a calendar-event section in one
+ * call. Mirrors addProductsToDoc's shape: POST to /api/v1/events, then
+ * patchTemplateSections to either append the new id to an existing
+ * calendar-event section or create a fresh one. */
+async function addCalendarEventToDoc(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const sectionId = typeof args.section_id === "string" ? args.section_id : null;
+    const title = typeof args.title === "string" ? args.title : "Schedule";
+    const layout = typeof args.layout === "string" && ["card", "table", "banner"].includes(args.layout)
+        ? args.layout
+        : "card";
+    if (!isRecord(args.event)) {
+        throw new Error("`event` must be an object with at least { title, starts_at }.");
+    }
+    const eventBody = args.event;
+    if (typeof eventBody.title !== "string" || !eventBody.title.trim()) {
+        throw new Error("`event.title` is required.");
+    }
+    if (typeof eventBody.starts_at !== "string" || !eventBody.starts_at.trim()) {
+        throw new Error("`event.starts_at` is required (ISO 8601).");
+    }
+    // Step 1: create the shoot.
+    const { data: eventRes } = await apiRequest(cfg, "/api/v1/events", { method: "POST", body: eventBody });
+    const eventId = eventRes.event?.id;
+    if (!eventId) {
+        throw new Error("Event creation returned no id — cannot wire into section.");
+    }
+    // Step 2: wire the id into a calendar-event section (append to
+    // existing, or create a new one).
+    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 !== "calendar-event") {
+                throw new Error(`Section '${targetId}' is '${sections[idx].type}', not 'calendar-event'`);
+            }
+            const existing = (sections[idx].data ?? {});
+            const prev = Array.isArray(existing.eventIds)
+                ? existing.eventIds.filter((v) => typeof v === "string")
+                : [];
+            sections[idx] = {
+                ...sections[idx],
+                data: {
+                    ...(sections[idx].data ?? {}),
+                    eventIds: [...prev, eventId],
+                },
+            };
+        }
+        else {
+            targetId = randId("sec");
+            sections.push({
+                id: targetId,
+                type: "calendar-event",
+                data: {
+                    title,
+                    eventIds: [eventId],
+                    layout,
+                    showAttendees: true,
+                    showLocation: true,
+                    showDescription: true,
+                },
+            });
+        }
+        return { sections, message: "Add calendar event to doc" };
+    });
+    return {
+        section_id: targetId,
+        event_id: eventId,
+        etag: res.etag,
+    };
+}
+/** Append (or insert at `position`) a new section of any supported type.
+ * Uses the scoped append endpoint so the write doesn't fight the web
+ * editor's autosave. Retries once on precondition failure. */
+async function addSection(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    const type = requireString(args, "type");
+    if (!isRecord(args.data)) {
+        throw new Error("`data` must be an object matching the target section type's shape.");
+    }
+    const data = args.data;
+    const position = typeof args.position === "number" ? Math.round(args.position) : undefined;
+    const hidden = typeof args.hidden === "boolean" ? args.hidden : undefined;
+    // Fetch etag so If-Match survives a concurrent autosave.
+    const MAX_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        const current = await getTemplate({ docId });
+        try {
+            const { data: res } = await apiRequest(cfg, `/api/v1/docs/${docId}/template/sections`, {
+                method: "POST",
+                body: {
+                    type,
+                    data,
+                    ...(hidden !== undefined ? { hidden } : {}),
+                    ...(position !== undefined ? { position } : {}),
+                },
+                ifMatch: current.etag,
+            });
+            return {
+                section: res.section,
+                section_id: res.section.id,
+                etag: res.etag,
+                updated_at: res.updated_at,
+                ...(attempt > 1 ? { retried: true } : {}),
+            };
+        }
+        catch (e) {
+            if (e instanceof ApiError &&
+                (e.status === 412 || e.status === 409) &&
+                attempt < MAX_ATTEMPTS) {
+                process.stderr.write(`[atlas-mcp] addSection ${docId}: ${e.status} on attempt ${attempt}, re-fetching + retrying\n`);
+                continue;
+            }
+            if (e instanceof ApiError && (e.status === 412 || e.status === 409)) {
+                throw new Error(`Doc kept racing after ${MAX_ATTEMPTS} attempts — someone else is actively editing. Pause the web editor and retry.`);
+            }
+            throw e;
+        }
+    }
+    throw new Error("addSection: unreachable retry fallthrough");
+}
+/** Scoped merge-update of template_content.cover. Uses the dedicated
+ * cover PATCH endpoint — doesn't touch sections[] or docSettings. */
+async function updateCover(args) {
+    const cfg = resolveConfig();
+    const docId = requireString(args, "doc_id");
+    if (!isRecord(args.cover)) {
+        throw new Error("`cover` must be an object of fields to merge onto template_content.cover.");
+    }
+    const cover = args.cover;
+    const MAX_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        const current = await getTemplate({ docId });
+        try {
+            const { data } = await apiRequest(cfg, `/api/v1/docs/${docId}/template/cover`, {
+                method: "PATCH",
+                body: { cover },
+                ifMatch: current.etag,
+            });
+            return {
+                cover: data.cover,
+                etag: data.etag,
+                updated_at: data.updated_at,
+                ...(attempt > 1 ? { retried: true } : {}),
+            };
+        }
+        catch (e) {
+            if (e instanceof ApiError &&
+                (e.status === 412 || e.status === 409) &&
+                attempt < MAX_ATTEMPTS) {
+                process.stderr.write(`[atlas-mcp] updateCover ${docId}: ${e.status} on attempt ${attempt}, re-fetching + retrying\n`);
+                continue;
+            }
+            if (e instanceof ApiError && (e.status === 412 || e.status === 409)) {
+                throw new Error(`Doc kept racing after ${MAX_ATTEMPTS} attempts — someone else is actively editing. Pause the web editor and retry.`);
+            }
+            throw e;
+        }
+    }
+    throw new Error("updateCover: unreachable retry fallthrough");
+}
 /* ─── Mindmap tools ────────────────────────────────────────────────── */
 async function listMindmaps_(args) {
     const cfg = resolveConfig();
@@ -3175,7 +3522,7 @@ async function exportMindmapTool(args) {
             headers: {
                 Authorization: `Bearer ${cfg.token}`,
                 Accept: "image/svg+xml",
-                "User-Agent": "atlas-mcp/0.1.0",
+                "User-Agent": "atlas-mcp/0.3.0",
             },
         });
         if (!res.ok) {
@@ -3200,7 +3547,7 @@ async function exportMindmapTool(args) {
         headers: {
             Authorization: `Bearer ${cfg.token}`,
             Accept: "application/json",
-            "User-Agent": "atlas-mcp/0.1.0",
+            "User-Agent": "atlas-mcp/0.3.0",
         },
     });
     if (!tokRes.ok) {