@kezlahd/atlas-mcp 0.2.1 → 0.4.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 (drops / shoot plans / campaigns / lookbooks / any of the catalogue in atlas_list_doc_presets), prefer atlas_create_doc_from_preset — pass the brief as the cover subtitle and then read the preset's `agent_guidance` for the next-step fill order. For a BESPOKE one-off doc, use this tool and build sections manually: 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: {
@@ -80,7 +80,7 @@ const TOOLS = [
     },
     {
         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.",
+        description: "List every doc preset available in Atlas (shoot-day, deliverable, planning, narrative-first templates). Returns the full catalogue with each preset's id, label, blurb, category, estimated fill time, default title, ordered section list, and (where present) an `agent_guidance` runbook explaining how to fill the skeleton. Design principle to carry across every doc: docs follow a NARRATIVE — start with cover + story, then supporting evidence (moodboards, palettes), then concrete deliverables (products, shots, dates, people), then logistics (notes, call sheets). Pick the preset whose section order already matches that arc rather than reshuffling after creation.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -88,7 +88,7 @@ const TOOLS = [
     },
     {
         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).",
+        description: "Create a new doc from a preset. Choose a preset based on the doc's purpose (list via atlas_list_doc_presets — each entry includes a one-line blurb). After creation, the doc has EMPTY sections in the right narrative order; fill each with the appropriate tool: atlas_update_cover for the cover subtitle + date, atlas_build_moodboard for moodboard images, atlas_extract_palette for the palette (points at a moodboard section), atlas_add_products_to_doc for product rows, atlas_add_shots_to_doc for the shot list, atlas_add_calendar_event_to_doc for dates, atlas_update_section for text/notes/table bodies. Each preset's `agent_guidance` field (fetched via atlas_list_doc_presets) tells you how to fill it — read it before filling. Fill the cover subtitle + section copy from the conversation context you already have (brand voice, brief, references); don't ask the user for anything already in the conversation. 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: {
@@ -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`).",
@@ -1404,6 +1494,62 @@ const TOOLS = [
             required: ["entryId"],
         },
     },
+    {
+        name: "atlas_list_pending_bugs",
+        description: "List pending (or otherwise unresolved) MCP bug reports in the current Atlas workspace. Requires bugs:read. Call this BEFORE atlas_report_bug to avoid filing duplicates — if a similar bug already exists in pending/triaged/in_progress state, DON'T file a new one. Returns { items, next_cursor } with each item carrying title, description, mcp_tool, severity, status, created_at. If a similar bug exists, note it in your reply to the user rather than filing again (there is no comment surface yet — just skip).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mcp_tool: {
+                    type: "string",
+                    description: "Optional — filter to bugs filed against this exact MCP tool name (e.g. 'atlas_build_moodboard').",
+                },
+                status: {
+                    type: "string",
+                    description: "Optional CSV filter. Defaults to 'pending,triaged,in_progress' (unresolved). Pass 'fixed,closed,duplicate' to see resolved bugs.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max rows to return (default 50, max 500).",
+                },
+                cursor: {
+                    type: "string",
+                    description: "Opaque next_cursor from a previous response. Omit for the first page.",
+                },
+            },
+        },
+    },
+    {
+        name: "atlas_report_bug",
+        description: "File a bug report against the Atlas MCP. Call this whenever an MCP tool returns an unexpected error, a false success, or silently produces broken output. The developer (Kieran) reads these to prioritise fixes. REQUIREMENT: Check atlas_list_pending_bugs FIRST to avoid duplicates — if a similar bug already exists in pending/triaged/in_progress state, DON'T file a new one (just mention the existing bug id in your reply). Requires bugs:write. Returns the created row (id, title, status, created_at…). Severity defaults to 'medium'; use 'critical' only for data-loss / corruption / repro-every-time issues. Keep `description` concrete: what you called, with what args, what you got back, what you expected.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Short title (3–160 chars). Lead with the broken tool / symptom.",
+                },
+                description: {
+                    type: "string",
+                    description: "What happened (10–8000 chars). Include the tool name, arguments passed, the error / wrong output, and what you expected. Precise > verbose.",
+                },
+                mcp_tool: {
+                    type: "string",
+                    description: "The MCP tool that misbehaved (e.g. 'atlas_build_moodboard'). Omit for cross-cutting bugs that aren't tied to one tool.",
+                },
+                reproduction: {
+                    type: "string",
+                    description: "Optional repro steps or the minimum repro args payload. Helps triage faster.",
+                },
+                severity: {
+                    type: "string",
+                    enum: ["low", "medium", "high", "critical"],
+                    description: "Default 'medium'. 'critical' = data loss / corruption / repros every time; 'high' = blocks a real workflow; 'low' = cosmetic / nice-to-have.",
+                },
+            },
+            required: ["title", "description"],
+        },
+    },
     {
         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.",
@@ -1437,7 +1583,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.4.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,
 }));
@@ -1590,6 +1736,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":
@@ -1618,6 +1770,10 @@ async function dispatch(name, args) {
             return listActivity_(args);
         case "atlas_get_activity":
             return getActivity_(args);
+        case "atlas_list_pending_bugs":
+            return listPendingBugs_(args);
+        case "atlas_report_bug":
+            return reportBug_(args);
         case "export_mindmap":
             return exportMindmapTool(args);
         default:
@@ -1669,36 +1825,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 +1959,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 +2059,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 +2638,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.4.0",
         },
         body: form,
     });
@@ -2469,7 +2671,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.4.0",
         },
     });
     if (!res.ok || !res.body) {
@@ -2544,6 +2746,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 +2806,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 +2860,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 +3179,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();
@@ -3155,6 +3562,48 @@ async function getActivity_(args) {
     const { data } = await apiRequest(cfg, `/api/v1/activity/${entryId}`);
     return data;
 }
+/* ─── Bug reports ──────────────────────────────────────────────────── */
+/** List pending (or otherwise unresolved) bugs so an agent can dedupe
+ * before filing a new one. Default filter: pending + triaged +
+ * in_progress — the three "we haven't fixed this yet" statuses. */
+async function listPendingBugs_(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.mcp_tool === "string" && args.mcp_tool) {
+        query.mcp_tool = args.mcp_tool;
+    }
+    query.status =
+        typeof args.status === "string" && args.status.trim()
+            ? args.status
+            : "pending,triaged,in_progress";
+    const { data } = await apiRequest(cfg, "/api/v1/bugs", { query });
+    return data;
+}
+async function reportBug_(args) {
+    const cfg = resolveConfig();
+    const body = {
+        title: requireString(args, "title"),
+        description: requireString(args, "description"),
+    };
+    if (typeof args.mcp_tool === "string" && args.mcp_tool) {
+        body.mcp_tool = args.mcp_tool;
+    }
+    if (typeof args.reproduction === "string" && args.reproduction) {
+        body.reproduction = args.reproduction;
+    }
+    if (typeof args.severity === "string" && args.severity) {
+        body.severity = args.severity;
+    }
+    const { data } = await apiRequest(cfg, "/api/v1/bugs", {
+        method: "POST",
+        body,
+    });
+    return data;
+}
 /* ─── Mindmap export (PDF / PNG / SVG) ───────────────────────────── */
 async function exportMindmapTool(args) {
     const cfg = resolveConfig();
@@ -3175,7 +3624,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.4.0",
             },
         });
         if (!res.ok) {
@@ -3200,7 +3649,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.4.0",
         },
     });
     if (!tokRes.ok) {