@de-otio/epimethian-mcp 6.7.1 → 6.9.0

package/dist/cli/index.js

@@ -35481,7 +35481,7 @@ async function getPage(pageId, includeBody) {
 async function _rawCreatePage(spaceId, title, body, parentId, clientLabel) {
   const cfg = await getConfig();
   const pageBody = normalizeBodyForSubmit(body);
-  const epimethianTag = `Epimethian v${"6.7.1"}`;
+  const epimethianTag = `Epimethian v${"6.9.0"}`;
   const versionMsg = cfg.attribution && clientLabel ? `Created by ${clientLabel} (via ${epimethianTag})` : `Created by ${epimethianTag}`;
   const payload = {
     title,
@@ -35502,7 +35502,7 @@ async function _rawCreatePage(spaceId, title, body, parentId, clientLabel) {
 async function _rawUpdatePage(pageId, opts) {
   const cfg = await getConfig();
   const newVersion = opts.version + 1;
-  const epimethianTag = `Epimethian v${"6.7.1"}`;
+  const epimethianTag = `Epimethian v${"6.9.0"}`;
   const effectiveClient = cfg.attribution ? opts.clientLabel : void 0;
   let versionMessage;
   if (opts.versionMessage && effectiveClient)
@@ -36879,6 +36879,295 @@ var init_confirmation_tokens = __esm({
   }
 });
 
+// src/server/batch-tokens.ts
+function clampTtlSeconds(seconds) {
+  if (!Number.isFinite(seconds)) return DEFAULT_BATCH_TTL_SECONDS;
+  if (seconds < TTL_MIN_SECONDS) return TTL_MIN_SECONDS;
+  if (seconds > TTL_MAX_SECONDS) return TTL_MAX_SECONDS;
+  return Math.floor(seconds);
+}
+function getMintLimit2() {
+  const raw = process.env.EPIMETHIAN_BATCH_MINT_LIMIT;
+  if (raw === void 0) return MAX_BATCH_MINTS_PER_15_MIN;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 0) return MAX_BATCH_MINTS_PER_15_MIN;
+  return n;
+}
+function emitMint2(meta) {
+  for (const h of mintHandlers2) {
+    try {
+      h(meta);
+    } catch {
+    }
+  }
+}
+function emitValidate2(meta) {
+  for (const h of validateHandlers2) {
+    try {
+      h(meta);
+    } catch {
+    }
+  }
+}
+function emitRefund(meta) {
+  for (const h of refundHandlers) {
+    try {
+      h(meta);
+    } catch {
+    }
+  }
+}
+function sleepUntil2(targetWallClockMs) {
+  return new Promise((resolve2) => {
+    const remaining = targetWallClockMs - Date.now();
+    if (remaining <= 0) {
+      resolve2();
+      return;
+    }
+    setTimeout(resolve2, remaining);
+  });
+}
+function pruneMintTimestamps2(now) {
+  const cutoff = now - MINT_WINDOW_MS2;
+  if (mintTimestamps2.length === 0) return;
+  if (mintTimestamps2[0] >= cutoff) return;
+  mintTimestamps2 = mintTimestamps2.filter((ts) => ts >= cutoff);
+}
+function evictOldest2() {
+  let oldestKey;
+  let oldestSeq = Infinity;
+  for (const [k, v] of store2.entries()) {
+    if (v.insertSeq < oldestSeq) {
+      oldestSeq = v.insertSeq;
+      oldestKey = k;
+    }
+  }
+  if (oldestKey === void 0) return;
+  const entry = store2.get(oldestKey);
+  store2.delete(oldestKey);
+  for (const reservationId of entry.reservations.keys()) {
+    reservationIndex.delete(reservationId);
+  }
+  emitValidate2({
+    auditId: entry.auditId,
+    cloudId: entry.cloudId,
+    pageId: entry.pageIdsList[0] ?? "",
+    outcome: "evicted"
+  });
+}
+function mintBatchToken(args) {
+  if (typeof args.cloudId !== "string" || args.cloudId.length === 0) {
+    throw new Error("mintBatchToken: cloudId is required and must be a non-empty string.");
+  }
+  if (!Array.isArray(args.pageIds) || args.pageIds.length === 0) {
+    throw new Error("mintBatchToken: pageIds must be a non-empty array.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const dedupedPageIds = [];
+  for (const id of args.pageIds) {
+    if (typeof id !== "string" || id.length === 0) {
+      throw new Error("mintBatchToken: every page_id must be a non-empty string.");
+    }
+    if (!seen.has(id)) {
+      seen.add(id);
+      dedupedPageIds.push(id);
+    }
+  }
+  if (dedupedPageIds.length > MAX_PAGE_IDS_PER_BATCH) {
+    throw new Error(
+      `mintBatchToken: page_ids list exceeds MAX_PAGE_IDS_PER_BATCH=${MAX_PAGE_IDS_PER_BATCH}.`
+    );
+  }
+  const ttlSeconds = clampTtlSeconds(args.ttlSeconds ?? DEFAULT_BATCH_TTL_SECONDS);
+  const ttlMs = ttlSeconds * 1e3;
+  const N = dedupedPageIds.length;
+  const requestedMax = args.maxOperations === void 0 ? N : Math.floor(args.maxOperations);
+  if (!Number.isFinite(requestedMax) || requestedMax < 1) {
+    throw new Error("mintBatchToken: max_operations must be a positive integer.");
+  }
+  const maxOperations = Math.min(requestedMax, N * 2);
+  const now = Date.now();
+  pruneMintTimestamps2(now);
+  const limit = getMintLimit2();
+  if (limit > 0 && mintTimestamps2.length >= limit) {
+    const oldest = mintTimestamps2[0];
+    const waitMs = Math.max(0, oldest + MINT_WINDOW_MS2 - now);
+    throw new BatchMintRateLimitedError(mintTimestamps2.length, limit, waitMs);
+  }
+  while (store2.size >= MAX_OUTSTANDING_BATCH_TOKENS) {
+    evictOldest2();
+  }
+  const expiresAt = now + ttlMs;
+  const auditId = (0, import_node_crypto5.randomUUID)();
+  const tokenStr = `btk_${(0, import_node_crypto5.randomBytes)(32).toString("hex")}`;
+  const entry = {
+    auditId,
+    cloudId: args.cloudId,
+    pageIds: new Set(dedupedPageIds),
+    pageIdsList: dedupedPageIds,
+    expiresAt,
+    maxOperations,
+    remainingOperations: maxOperations,
+    reservations: /* @__PURE__ */ new Map(),
+    insertSeq: ++insertSeqCounter2
+  };
+  store2.set(tokenStr, entry);
+  mintTimestamps2.push(now);
+  emitMint2({
+    auditId,
+    cloudId: args.cloudId,
+    pageIds: dedupedPageIds,
+    ttlMs,
+    maxOperations,
+    expiresAt,
+    outstanding: store2.size
+  });
+  return {
+    token: tokenStr,
+    auditId,
+    expiresAt,
+    authorisedPageIds: dedupedPageIds,
+    remainingOperations: maxOperations
+  };
+}
+async function validateBatchToken(args) {
+  const floorTarget = Date.now() + MIN_VALIDATE_FLOOR_MS2;
+  let outcome;
+  let auditId;
+  let result = { valid: false };
+  let remainingAfter;
+  const entry = store2.get(args.token);
+  if (!entry) {
+    outcome = "unknown";
+  } else {
+    auditId = entry.auditId;
+    const now = Date.now();
+    if (now >= entry.expiresAt) {
+      store2.delete(args.token);
+      for (const reservationId of entry.reservations.keys()) {
+        reservationIndex.delete(reservationId);
+      }
+      outcome = "expired";
+    } else if (entry.cloudId !== args.cloudId) {
+      outcome = "cloudid_mismatch";
+    } else if (!entry.pageIds.has(args.pageId)) {
+      outcome = "page_id_not_authorised";
+    } else if (entry.remainingOperations <= 0) {
+      outcome = "exhausted";
+    } else {
+      entry.remainingOperations -= 1;
+      remainingAfter = entry.remainingOperations;
+      const reservationId = (0, import_node_crypto5.randomUUID)();
+      entry.reservations.set(reservationId, {
+        pageId: args.pageId,
+        refunded: false
+      });
+      reservationIndex.set(reservationId, args.token);
+      outcome = "ok";
+      result = { valid: true, reservationId };
+    }
+  }
+  emitValidate2({
+    auditId,
+    cloudId: args.cloudId,
+    pageId: args.pageId,
+    outcome,
+    ...remainingAfter !== void 0 ? { remainingAfter } : {}
+  });
+  await sleepUntil2(floorTarget);
+  return result;
+}
+function refundReservation(reservationId) {
+  const tokenStr = reservationIndex.get(reservationId);
+  if (tokenStr === void 0) return false;
+  const entry = store2.get(tokenStr);
+  if (!entry) {
+    reservationIndex.delete(reservationId);
+    return false;
+  }
+  const reservation = entry.reservations.get(reservationId);
+  if (!reservation) return false;
+  if (reservation.refunded) {
+    emitRefund({
+      auditId: entry.auditId,
+      cloudId: entry.cloudId,
+      pageId: reservation.pageId,
+      refunded: false,
+      remainingAfter: entry.remainingOperations
+    });
+    return false;
+  }
+  reservation.refunded = true;
+  entry.remainingOperations += 1;
+  emitRefund({
+    auditId: entry.auditId,
+    cloudId: entry.cloudId,
+    pageId: reservation.pageId,
+    refunded: true,
+    remainingAfter: entry.remainingOperations
+  });
+  return true;
+}
+function finaliseReservation(reservationId) {
+  const tokenStr = reservationIndex.get(reservationId);
+  reservationIndex.delete(reservationId);
+  if (tokenStr === void 0) return;
+  const entry = store2.get(tokenStr);
+  if (!entry) return;
+  entry.reservations.delete(reservationId);
+}
+function isBatchTokenShape(token) {
+  if (typeof token !== "string") return false;
+  if (!token.startsWith("btk_")) return false;
+  if (token.length !== "btk_".length + 64) return false;
+  for (let i = 4; i < token.length; i++) {
+    const c = token.charCodeAt(i);
+    const isHex = c >= 48 && c <= 57 || // 0-9
+    c >= 97 && c <= 102 || // a-f
+    c >= 65 && c <= 70;
+    if (!isHex) return false;
+  }
+  return true;
+}
+var import_node_crypto5, DEFAULT_BATCH_TTL_SECONDS, TTL_MIN_SECONDS, TTL_MAX_SECONDS, MAX_PAGE_IDS_PER_BATCH, MAX_OUTSTANDING_BATCH_TOKENS, MAX_BATCH_MINTS_PER_15_MIN, MINT_WINDOW_MS2, MIN_VALIDATE_FLOOR_MS2, BATCH_MINT_RATE_LIMITED, BatchMintRateLimitedError, store2, reservationIndex, mintTimestamps2, insertSeqCounter2, mintHandlers2, validateHandlers2, refundHandlers;
+var init_batch_tokens = __esm({
+  "src/server/batch-tokens.ts"() {
+    "use strict";
+    import_node_crypto5 = require("node:crypto");
+    DEFAULT_BATCH_TTL_SECONDS = 15 * 60;
+    TTL_MIN_SECONDS = 60;
+    TTL_MAX_SECONDS = 60 * 60;
+    MAX_PAGE_IDS_PER_BATCH = 50;
+    MAX_OUTSTANDING_BATCH_TOKENS = 25;
+    MAX_BATCH_MINTS_PER_15_MIN = 25;
+    MINT_WINDOW_MS2 = 15 * 60 * 1e3;
+    MIN_VALIDATE_FLOOR_MS2 = 5;
+    BATCH_MINT_RATE_LIMITED = "BATCH_MINT_RATE_LIMITED";
+    BatchMintRateLimitedError = class extends Error {
+      code = BATCH_MINT_RATE_LIMITED;
+      current;
+      limit;
+      waitMs;
+      constructor(current, limit, waitMs) {
+        super(
+          `Batch authorisation mint cap exhausted: ${current} mints in the last 15 min, limit ${limit}. Window opens again in ~${Math.ceil(waitMs / 6e4)} min. Override via EPIMETHIAN_BATCH_MINT_LIMIT (set "0" to disable).`
+        );
+        this.name = "BatchMintRateLimitedError";
+        this.current = current;
+        this.limit = limit;
+        this.waitMs = waitMs;
+      }
+    };
+    store2 = /* @__PURE__ */ new Map();
+    reservationIndex = /* @__PURE__ */ new Map();
+    mintTimestamps2 = [];
+    insertSeqCounter2 = 0;
+    mintHandlers2 = [];
+    validateHandlers2 = [];
+    refundHandlers = [];
+  }
+});
+
 // node_modules/mdurl/lib/decode.mjs
 function getDecodeCache(exclude) {
   let cache = decodeCache[exclude];
@@ -47426,7 +47715,7 @@ function enforceContentSafetyGuards(input) {
   if (oldLen > SHRINKAGE_GUARD_MIN_OLD_LEN && newLen < oldLen * SHRINKAGE_GUARD_MAX_RATIO && !confirmShrinkage) {
     const pct = Math.round((1 - newLen / oldLen) * 100);
     throw new ConverterError(
-      `Body would shrink from ${oldLen} to ${newLen} characters (${pct}% reduction). This may indicate accidental content loss. Re-submit with confirm_shrinkage: true to proceed, or omit replace_body to use token-aware preservation.`,
+      `Body would shrink from ${oldLen} to ${newLen} characters (${pct}% reduction). This may indicate accidental content loss. Re-submit with confirm_shrinkage: true to proceed (accepted by update_page, update_page_section, and update_page_sections).`,
       SHRINKAGE_NOT_CONFIRMED
     );
   }
@@ -47901,6 +48190,21 @@ async function maybeConsumeConfirmToken(args) {
   });
   return outcome;
 }
+async function tryBatchTokenForWrite(args) {
+  const { batch_token, cloudId, pageId } = args;
+  if (batch_token === void 0 || cloudId === void 0 || !isBatchTokenShape(batch_token)) {
+    return { batchReservationId: void 0 };
+  }
+  const result = await validateBatchToken({
+    token: batch_token,
+    cloudId,
+    pageId
+  });
+  if (result.valid) {
+    return { batchReservationId: result.reservationId };
+  }
+  return { batchReservationId: void 0 };
+}
 function formatSoftConfirmationResult(err, params) {
   const last8 = err.token.slice(-8);
   const isoExpires = new Date(err.expiresAt).toISOString();
@@ -47919,10 +48223,10 @@ Token tail: ...${last8}    Expires: ${isoExpires}    Audit ID: ${err.auditId}
 The token is single-use, bound to this exact diff and page version,
 and invalidated by any competing write to this page. If validation
 fails, mint a new one by re-calling without \`confirm_token\`.`;
-  const tokenInText = process.env.EPIMETHIAN_TOKEN_IN_TEXT === "true";
-  const finalText = tokenInText ? text2 + `
+  const explicitlyHidden = process.env.EPIMETHIAN_HIDE_TOKEN_IN_TEXT === "true" || process.env.EPIMETHIAN_TOKEN_IN_TEXT === "false";
+  const finalText = explicitlyHidden ? text2 : text2 + `
 
-[FALLBACK] Full token (EPIMETHIAN_TOKEN_IN_TEXT=true): ${err.token}` : text2;
+[FALLBACK] Full token: ${err.token}`;
   const structuredContent = {
     kind: "confirmation_required",
     confirm_token: err.token,
@@ -48124,6 +48428,7 @@ async function safePrepareBody(input) {
     confirmDeletions,
     confirmShrinkage,
     confirmStructureLoss,
+    fullPageBody,
     replaceBody,
     allowRawHtml,
     confluenceBaseUrl
@@ -48252,9 +48557,15 @@ Pick one path:
     assertDeletionAckMatches(confirmDeletions, deletedTokens);
   }
   if (scope !== "additive" && currentBody !== void 0) {
+    let guardOld = currentBody;
+    let guardNew = finalStorage;
+    if (scope === "section" && fullPageBody !== void 0 && fullPageBody.includes(currentBody)) {
+      guardOld = fullPageBody;
+      guardNew = fullPageBody.replace(currentBody, () => finalStorage);
+    }
     enforceContentSafetyGuards({
-      oldStorage: currentBody,
-      newStorage: finalStorage,
+      oldStorage: guardOld,
+      newStorage: guardNew,
       confirmShrinkage,
       confirmStructureLoss: confirmStructureLoss || replaceBody === true,
       // confirmDeletions (any truthy form, incl. a non-empty string[]) OR
@@ -48518,6 +48829,8 @@ async function safePrepareMultiSectionBody(input) {
     currentStorage,
     sections,
     confirmDeletions,
+    confirmShrinkage,
+    confirmStructureLoss,
     allowRawHtml,
     confluenceBaseUrl
   } = input;
@@ -48600,6 +48913,10 @@ async function safePrepareMultiSectionBody(input) {
         currentBody: loc.body,
         scope: "section",
         confirmDeletions: confirmDeletions ? true : void 0,
+        confirmShrinkage,
+        confirmStructureLoss,
+        // Measure each section's guards page-relative (see safePrepareBody).
+        fullPageBody: currentStorage,
         ...allowRawHtml !== void 0 ? { allowRawHtml } : {},
         ...confluenceBaseUrl !== void 0 ? { confluenceBaseUrl } : {}
       });
@@ -48658,6 +48975,7 @@ var init_safe_write = __esm({
     "use strict";
     init_confluence_client();
     init_confirmation_tokens();
+    init_batch_tokens();
     init_md_to_storage();
     init_update_orchestrator();
     init_content_safety_guards();
@@ -48785,7 +49103,7 @@ async function writeCheckState(state) {
   const data = JSON.stringify(state, null, 2) + "\n";
   const tmpFile = (0, import_node_path3.join)(
     CONFIG_DIR2,
-    `.update-check.${(0, import_node_crypto5.randomBytes)(4).toString("hex")}.tmp`
+    `.update-check.${(0, import_node_crypto6.randomBytes)(4).toString("hex")}.tmp`
   );
   await (0, import_promises3.writeFile)(tmpFile, data, { mode: 384 });
   await (0, import_promises3.rename)(tmpFile, UPDATE_CHECK_FILE);
@@ -48926,14 +49244,14 @@ async function checkForUpdates(currentVersion) {
     return null;
   }
 }
-var import_promises3, import_node_path3, import_node_os2, import_node_crypto5, import_node_child_process2, import_node_util, execFileAsync, CONFIG_DIR2, UPDATE_CHECK_FILE, ONE_DAY_MS, NPM_REGISTRY_URL, PACKAGE_NAME;
+var import_promises3, import_node_path3, import_node_os2, import_node_crypto6, import_node_child_process2, import_node_util, execFileAsync, CONFIG_DIR2, UPDATE_CHECK_FILE, ONE_DAY_MS, NPM_REGISTRY_URL, PACKAGE_NAME;
 var init_update_check = __esm({
   "src/shared/update-check.ts"() {
     "use strict";
     import_promises3 = require("node:fs/promises");
     import_node_path3 = require("node:path");
     import_node_os2 = require("node:os");
-    import_node_crypto5 = require("node:crypto");
+    import_node_crypto6 = require("node:crypto");
     import_node_child_process2 = require("node:child_process");
     import_node_util = require("node:util");
     init_safe_fs();
@@ -49022,7 +49340,7 @@ var init_client_configs = __esm({
           null,
           2
         ),
-        warning: "VS Code extension \u2264 2.1.123 does not honour elicitation requests; if write tools fail with NO_USER_RESPONSE, set `EPIMETHIAN_BYPASS_ELICITATION=true`.\n\nv6.6.2 declares an `outputSchema` on every write tool, so a spec-compliant client should now surface the soft-confirm `structuredContent` to the agent. If your version of Claude Code drops content blocks when structuredContent is present (issue #15412), set `EPIMETHIAN_TOKEN_IN_TEXT=true` as a fallback \u2014 this restores the human-readable explanation by also putting the full token in the text block."
+        warning: "VS Code extension \u2264 2.1.123 does not honour elicitation requests; if write tools fail with NO_USER_RESPONSE, set `EPIMETHIAN_BYPASS_ELICITATION=true`.\n\nSoft-confirm tokens are surfaced in the text content by default (v6.7.2+) so Claude Code can read them even when it drops `structuredContent` (issue #15412). To opt out for a client that does forward `structuredContent` reliably, set `EPIMETHIAN_HIDE_TOKEN_IN_TEXT=true`."
       },
       {
         id: "cursor",
@@ -49948,7 +50266,7 @@ Informational:
 var install_agent_default;
 var init_install_agent = __esm({
   "install-agent.md"() {
-    install_agent_default = '# Epimethian MCP - Agent Installation Guide\n\n> This document is for AI agents installing and configuring the Epimethian MCP server on behalf of a user.\n\n## Verification\n\nThe official package is **`@de-otio/epimethian-mcp`** (scoped under `@de-otio`).\n\nDo NOT install unscoped alternatives like `epimethian-mcp` \u2014 these are unofficial and potentially unsafe.\n\n## Prerequisites\n\n- Node.js 18 or later\n- npm on PATH\n\n## Step 1: Install\n\n```bash\nnpm install -g @de-otio/epimethian-mcp\n```\n\nVerify the installation:\n\n```bash\nepimethian-mcp --version 2>/dev/null || which epimethian-mcp\n```\n\n## Step 2: Resolve the absolute path\n\nIDE-hosted agents may not resolve PATH correctly. Always use the absolute path in MCP configuration:\n\n```bash\nwhich epimethian-mcp\n```\n\nUse the output as the `command` value in the MCP config below.\n\n## Step 3: Collect configuration\n\nAsk the user for:\n1. **Profile name** \u2014 a short identifier for this Confluence instance (e.g., `globex`, `acme-corp`). Lowercase alphanumeric and hyphens only.\n2. **Confluence Cloud URL** \u2014 e.g., `https://yoursite.atlassian.net`\n3. **Email address** \u2014 the email associated with their Atlassian account\n\n## Step 4: Write MCP configuration\n\nRun `epimethian-mcp setup --profile <name> --client <client-id>` after Step 5 (credential setup) \u2014 it prints the exact config snippet for your MCP host. Supported clients: `claude-code`, `claude-desktop`, `claude-code-vscode`, `cursor`, `windsurf`, `zed`, `opencode`. Keep the fallback hand-typed examples below for cases where the CLI is unavailable.\n\nAdd the server to the user\'s MCP client config. The exact file and shape depend on the client:\n\n**Claude Code, Claude Desktop, Cursor, Windsurf, Zed** \u2014 `.mcp.json` (or the\nequivalent client-specific config). The standard `mcpServers` shape:\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path from Step 2>",\n      "env": {\n        "CONFLUENCE_PROFILE": "<profile name from Step 3>"\n      }\n    }\n  }\n}\n```\n\n**OpenCode** \u2014 `opencode.json` at the project root or\n`~/.config/opencode/opencode.json`. Different shape (`mcp` block, `type:\n"local"`, `command` is an array, `environment` not `env`):\n\n```jsonc\n{\n  "$schema": "https://opencode.ai/config.json",\n  "mcp": {\n    "confluence": {\n      "type": "local",\n      "command": ["<absolute path from Step 2>"],\n      "enabled": true,\n      "environment": {\n        "CONFLUENCE_PROFILE": "<profile name from Step 3>",\n        "EPIMETHIAN_ALLOW_UNGATED_WRITES": "true"\n      }\n    }\n  }\n}\n```\n\nOpenCode does not support MCP elicitation (the in-protocol confirmation\nprompts), so write tools that fire the elicitation gate fail unless\n`EPIMETHIAN_ALLOW_UNGATED_WRITES=true` is set. See "MCP client\ncompatibility" below for the trade-off.\n\n**IMPORTANT:** The only required env var is `CONFLUENCE_PROFILE`. The URL,\nemail, and API token are stored securely in the OS keychain \u2014 they should\nNOT appear in config files.\n\n## Step 5: Credential setup\n\nTell the user to run this command in their terminal:\n\n```\nepimethian-mcp setup --profile <profile name from Step 3>\n```\n\nThis interactive command will:\n1. Prompt for the Confluence URL, email, and API token (masked input)\n2. Test the connection\n3. Store all credentials securely in the OS keychain under the named profile\n\nThe API token is generated at: https://id.atlassian.com/manage-profile/security/api-tokens\n\n**Do NOT ask the user for the API token yourself.** The token must go directly from the user into the interactive setup command to avoid appearing in conversation logs.\n\n## Step 6: User must restart the MCP client\n\n**IMPORTANT:** The user must restart their MCP client (e.g., restart Claude Code, reload VS Code, restart Claude Desktop) for the new server configuration to take effect. The MCP client reads `.mcp.json` at startup and does not detect changes while running.\n\nTell the user:\n> Please restart your MCP client now to activate the Confluence tools.\n\n## Step 7: Validation\n\nAfter the user restarts, verify the server is working by listing available Confluence tools or running a simple operation like listing spaces.\n\n## Adding Additional Tenants\n\nTo add a second Confluence instance (e.g., for a different customer):\n\n1. Run `epimethian-mcp setup --profile <new-profile-name>` with the new credentials\n2. In the project that uses the new tenant, update `.mcp.json` to set `CONFLUENCE_PROFILE` to the new profile name\n3. Restart the MCP client\n\nEach VS Code window / Claude Code session uses the profile specified in its `.mcp.json`. Profiles are fully isolated \u2014 different OS keychain entries, different Confluence instances.\n\n## Managing Profiles\n\n- List all profiles: `epimethian-mcp profiles`\n- Show details: `epimethian-mcp profiles --verbose`\n- Check connection: `CONFLUENCE_PROFILE=<name> epimethian-mcp status`\n- Set read-only: `epimethian-mcp profiles --set-read-only <name>`\n- Set read-write: `epimethian-mcp profiles --set-read-write <name>`\n\n### Read-Only Mode\n\nNew profiles default to **read-only**. When read-only, all write tools are blocked and return an error. To enable writes for a profile:\n\n```bash\nepimethian-mcp profiles --set-read-write <name>\n```\n\nOr during setup: `epimethian-mcp setup --profile <name> --read-write`\n\n**Important:** Restart any running MCP servers after changing the read-only flag.\n\n### Removing a Profile\n\nTo delete a profile and its credentials, run:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\n**Agents must pass `--force`** because the command normally prompts for interactive confirmation (`Remove profile "<name>" and delete its credentials? [y/N]`), which will fail in non-TTY environments like agent shell sessions. The `--force` flag skips the confirmation prompt when stdin is not a TTY.\n\nThis command:\n1. Deletes the credential entry (URL, email, API token) from the OS keychain\n2. Removes the profile from the registry at `~/.config/epimethian-mcp/profiles.json`\n3. Writes an entry to the audit log at `~/.config/epimethian-mcp/audit.log`\n\nAfter removing a profile, also remove or update any `.mcp.json` files that reference it \u2014 otherwise the MCP server will fail to start with a missing-profile error.\n\n**Errors:**\n- If the profile name is invalid (not matching lowercase alphanumeric/hyphens, 1\u201363 chars), the command exits with code 1\n- If the profile does not exist in the keychain, the keychain deletion is silently skipped \u2014 the registry entry is still removed\n\n## Accessing This Guide Post-Install\n\nOnce installed, this guide is available locally via:\n\n```bash\nepimethian-mcp agent-guide\n```\n\nThis prints the full agent guide to stdout \u2014 no web fetch required.\n\n## Uninstallation\n\nWhen a user asks to uninstall Epimethian MCP, follow these steps:\n\n### Step 1: Check for existing profiles\n\n```bash\nepimethian-mcp profiles\n```\n\n### Step 2: Ask the user about credential cleanup\n\nIf profiles exist, ask the user:\n\n> You have Epimethian profiles configured: [list the profile names]. Would you like to delete all stored credentials before uninstalling? (This removes API tokens from your OS keychain.)\n\n### Step 3: Delete credentials (if the user agrees)\n\nFor each profile the user wants removed:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\nOr to remove all profiles:\n\n```bash\nfor name in $(epimethian-mcp profiles | grep \'^ \'); do epimethian-mcp profiles --remove "$name" --force; done\n```\n\n### Step 4: Remove MCP configuration\n\nDelete the `confluence` entry (or the tenant-specific entry like `confluence-globex`) from the project\'s `.mcp.json`.\n\n### Step 5: Uninstall the package\n\n```bash\nnpm uninstall -g @de-otio/epimethian-mcp\n```\n\n### Step 6: Restart the MCP client\n\nTell the user to restart their MCP client so it stops trying to launch the removed server.\n\n## CI/CD (No Keychain)\n\nFor environments where the OS keychain is unavailable (Docker, CI), set all three env vars directly:\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path>",\n      "env": {\n        "CONFLUENCE_URL": "<url>",\n        "CONFLUENCE_EMAIL": "<email>",\n        "CONFLUENCE_API_TOKEN": "<token>"\n      }\n    }\n  }\n}\n```\n\n**Warning:** This exposes the API token in the process environment. Use profile-based auth whenever possible.\n\n## Troubleshooting\n\nIf **npm install fails**:\n- Verify Node.js 18+ is installed: `node --version`\n- Verify npm is on PATH: `npm --version`\n- If permission errors occur, the user may need to fix their npm prefix or use a Node version manager (nvm, fnm)\n\nIf **`epimethian-mcp setup` fails**:\n- "Connection failed": Verify the Confluence URL is correct and accessible\n- "Token is invalid or expired": The user needs to generate a new API token at https://id.atlassian.com/manage-profile/security/api-tokens\n- Keychain errors on Linux: The user may need to install `libsecret` / `gnome-keyring` (`apt install libsecret-tools` or equivalent)\n\nIf **the server doesn\'t appear after restart**:\n- Verify the `.mcp.json` path is correct for the user\'s MCP client\n- Verify the `command` value is an absolute path (run `which epimethian-mcp` to confirm)\n- Check that `.mcp.json` contains valid JSON (no trailing commas, correct quoting)\n\n## Write budget (safety cap on writes)\n\nepimethian-mcp enforces two write-rate caps per server process:\n\n- **Session cap** (default 250): total writes since the server started.\n- **Rolling cap** (default 75 per 15-minute window): catches bursts.\n\nThese are local safety nets, not Confluence limits. They exist because an\nautonomous agent in a retry loop or with a bad plan can issue hundreds of writes\nvery quickly, and most users would rather have a brief pause to confirm than\ndiscover the result an hour later.\n\n### What to do when you (the agent) hit `WRITE_BUDGET_EXCEEDED`\n\n1. **Stop and check.** Was the in-progress work user-requested and going as\n   planned? If unsure, ask the user before continuing.\n2. **Explain to the user, in your own words:**\n   - The safety budget has been hit (which scope, current vs. limit).\n   - What the budget is for: a guard against runaway agents.\n   - Whether the work-in-progress is legitimate (your judgement).\n   - The two ways forward: wait for the rolling window to reopen, or raise the cap.\n3. **If the user wants to raise the cap**, give them this snippet to add to the\n   `env` block of the epimethian-mcp entry in their MCP config (`.mcp.json` or\n   equivalent \u2014 see Step 4 above for the layout):\n\n   ```json\n   "EPIMETHIAN_WRITE_BUDGET_ROLLING": "200",\n   "EPIMETHIAN_WRITE_BUDGET_SESSION": "1000"\n   ```\n\n   Set either value to `"0"` to disable that scope. **Confirm with the user\n   before recommending a raise** \u2014 the budget exists precisely to create a\n   pause-and-check moment. The user must restart the MCP server (re-open the\n   MCP client) for changes to take effect.\n4. **If the user gets a deprecation warning** about `EPIMETHIAN_WRITE_BUDGET_HOURLY`,\n   tell them to rename it to `EPIMETHIAN_WRITE_BUDGET_ROLLING` in the same\n   config file. The old name still works but will be removed in version 7.\n\n### Operator-side defaults\n\n- **`EPIMETHIAN_WRITE_BUDGET_SESSION`** \u2014 default 250; set to "0" to disable.\n- **`EPIMETHIAN_WRITE_BUDGET_ROLLING`** \u2014 default 75 per 15-minute window; set to "0" to disable.\n- **`EPIMETHIAN_WRITE_BUDGET_HOURLY`** \u2014 deprecated alias for `EPIMETHIAN_WRITE_BUDGET_ROLLING`; will be removed in version 7.\n\n## Soft confirmation (clients without working elicitation)\n\nSome MCP clients (OpenCode, the Claude Code VS Code extension, and\nothers) don\'t implement the in-protocol confirmation prompt \u2014 either\nthey don\'t advertise the capability, or they advertise it and never\nhonour the request (the SDK transport silently returns\n`{action: "decline"}` without showing the user a UI). Starting in\nv6.6.0, epimethian-mcp routes those confirmations through your\nagent\'s normal chat surface instead.\n\nThe implementation evolved across v6.6.0 \u2192 v6.6.3:\n\n- **v6.6.0** introduced soft elicitation for clients that don\'t\n  *advertise* the capability \u2014 token-bound, single-use, diff-bound.\n- **v6.6.1** added **fast-decline auto-detection**: if the client\n  advertises elicitation but the decline arrives in <50 ms (well below\n  human reaction time), the session is flagged as fake and the call\n  is re-routed through the soft-confirm path automatically. Threshold\n  is overridable via `EPIMETHIAN_FAST_DECLINE_THRESHOLD_MS=<10..5000>`.\n  No env-var configuration needed for the Claude Code VS Code\n  extension\'s "fakes elicitation" bug \u2014 it Just Works.\n- **v6.6.2** declared `outputSchema` on every mutating tool so\n  spec-compliant clients are obliged to forward `structuredContent`\n  (where the token lives) to the agent. Added an opt-in\n  `EPIMETHIAN_TOKEN_IN_TEXT=true` fallback that appends the full\n  token to `content[0].text` for clients that drop `content` blocks\n  on `isError: true` results (Claude Code issues #15412 / #9962 /\n  #39976).\n- **v6.6.3** swapped the `outputSchema` from `z.discriminatedUnion`\n  to `z.object` so the MCP SDK\'s `normalizeObjectSchema` (which only\n  accepts schemas with `.shape`) can route the structured payload\n  through `validateToolOutput` without throwing `_zod` undefined\n  after the write commits. Hotfix; data-integrity-critical.\n\n### What you (the agent) see\n\nWhen a destructive write is requested against a client without working\nelicitation, the tool returns an error with a confirmation token:\n\n```\nisError: true\nstructuredContent:\n  {\n    "kind": "confirmation_required",\n    "confirm_token": "<opaque token>",\n    "audit_id": "<UUID for correlation>",\n    "expires_at": "<ISO timestamp>",\n    "page_id": "<pageId>",\n    "human_summary": "<one-line description for the user>",\n    "deletion_summary": { ... numeric counts only ... }   // optional\n  }\ncontent[0].text:\n  \u26A0\uFE0F  Confirmation required (SOFT_CONFIRMATION_REQUIRED)\n\n  {human_summary}\n\n  Please ask the user before retrying. If approved, re-call with the\n  same parameters plus "confirm_token" from structuredContent.\n\n  Token tail: ...<last 8 chars>    Expires: <timestamp>    Audit ID: <uuid>\n\n  [FALLBACK] Full token (EPIMETHIAN_TOKEN_IN_TEXT=true): <full token>\n  \u2190 only present when EPIMETHIAN_TOKEN_IN_TEXT=true is set\n```\n\nThe `kind` discriminator distinguishes this `"confirmation_required"`\narm from the success arm (`"written"` or `"deleted"`) on the same\ntool. Successful writes return:\n\n```\nstructuredContent:\n  { "kind": "written", "page_id": "...", "new_version": 12, ... }\n```\n\n\u2026or `"kind": "deleted"` for `delete_page`.\n\n### What to do\n\n1. STOP. Don\'t retry blindly.\n2. Show the user, in their language, what\'s about to happen \u2014 use the\n   `human_summary` field from `structuredContent`, or the\n   human-readable text in `content[0].text` if your client doesn\'t\n   forward `structuredContent`. **Never echo the token bytes to the\n   user** \u2014 the token is meant to flow agent \u2192 server, not user \u2192 eye.\n3. Ask the user explicitly. Wait for their answer.\n4. If approved: re-call the tool with the SAME parameters plus\n   `confirm_token`. Read the token from `structuredContent.confirm_token`\n   when available; if your client doesn\'t surface that, the token\'s\n   full bytes are in the `[FALLBACK] Full token: \u2026` line of\n   `content[0].text` whenever `EPIMETHIAN_TOKEN_IN_TEXT=true` is set\n   on the server. The 8-character "Token tail: \u2026" line in the prose\n   is for human inspection only \u2014 it is **not** the token.\n5. If denied: tell the user the operation has been cancelled.\n\n### Token semantics\n\n- Single-use: a successful retry consumes the token. Replays fail.\n- 5-minute TTL by default.\n- Invalidated by any competing write to the same page (stale).\n- Bound to the specific diff and tenant: changing the body, page version, or\n  tenant invalidates the token.\n\n### Operator opt-outs\n\nThese environment variables control soft confirmation behavior:\n\n- **`EPIMETHIAN_ALLOW_UNGATED_WRITES=true`** \u2014 bypasses soft confirmation\n  entirely (no prompt; useful for headless / CI). Removes the\n  human-in-the-loop gate; the harness\'s tool allow-list still applies.\n- **`EPIMETHIAN_DISABLE_SOFT_CONFIRM=true`** \u2014 keeps the legacy\n  `ELICITATION_REQUIRED_BUT_UNAVAILABLE` failure mode for clients without\n  elicitation support.\n- **`EPIMETHIAN_SOFT_CONFIRM_TTL_MS=300000`** \u2014 override the default 5-minute\n  TTL (clamped to 60 seconds minimum, 15 minutes maximum).\n- **`EPIMETHIAN_SOFT_CONFIRM_MINT_LIMIT=100`** \u2014 override the per-15-minute\n  mint cap (default 100; "0" disables the cap entirely).\n\n#### v6.6.1+ fast-decline auto-detection (Claude Code VS Code et al.)\n\n- **`EPIMETHIAN_TREAT_ELICITATION_AS_UNSUPPORTED=true`** \u2014 deterministic\n  counterpart to fast-decline auto-detection. Use when your client is\n  known to advertise elicitation but never honour it (e.g. the Claude\n  Code VS Code extension \u2264 2.1.123) and you want to skip the timing\n  probe on the first call. Distinct from `EPIMETHIAN_BYPASS_ELICITATION`:\n  this routes through the soft-confirmation gate; bypass removes the\n  gate entirely.\n- **`EPIMETHIAN_FAST_DECLINE_THRESHOLD_MS=<10..5000>`** \u2014 override the\n  fast-decline threshold (default 50 ms). Raise this if a slow MCP\n  transport is mis-classifying real declines as fake.\n- **`EPIMETHIAN_DISABLE_FAST_DECLINE_DETECTION=true`** \u2014 total\n  off-switch for the auto-detection; restores exactly v6.6.0 behaviour.\n\n#### v6.6.2+ structured-content fallback\n\n- **`EPIMETHIAN_TOKEN_IN_TEXT=true`** \u2014 opt-in fallback for clients that\n  drop `content` blocks on `isError: true` results, or that ignore the\n  `outputSchema` declaration and never surface `structuredContent`\n  to the agent. When set, the soft-confirm result text appends a\n  `[FALLBACK] Full token (EPIMETHIAN_TOKEN_IN_TEXT=true): <token>`\n  line so the agent can still extract the token. The structured\n  payload is unchanged. Trade-off: the token is visible in the agent\n  transcript (the security choice v6.6.0 explicitly avoided), so use\n  only when needed. Today this is required for Claude Code (the VS\n  Code extension and possibly the CLI) \u2014 see the per-client matrix\n  below.\n\n### Multi-process deployments\n\nTokens are process-local in-memory. If you\'re running multiple MCP server\nprocesses for one tenant (e.g. a load-balanced fleet or separate processes\nper IDE window), a soft confirmation minted by process P1 will fail validation\nin process P2 (the load balancer routes the retry to a different process).\nThis is not a bug \u2014 it\'s the safe failure mode \u2014 but it means the user needs\nto mint a new token if the retry lands on a different process.\n\n**Recommendation:** Pin a single MCP server process per agent or IDE window.\nPre-seal profiles upgraded from versions before v5.5.0 must run `epimethian-mcp\nsetup` once to acquire a sealed cloudId before soft confirmation is available.\n\n## MCP client compatibility\n\nepimethian-mcp uses MCP **elicitation** (the in-protocol confirmation\nprompt added to MCP in 2025) as the human-in-the-loop gate for destructive\noperations. Different MCP clients support elicitation differently \u2014 some\nfully, some not at all, and some advertise the capability without honouring\nit. The compatibility matrix below tells you which env-var workaround to\nrecommend, if any.\n\n| Client | Elicitation? | What to do (v6.6.3+) |\n|---|---|---|\n| **Claude Code (CLI)** | Yes \u2014 full support | No special config needed. |\n| **Claude Desktop** | Yes \u2014 full support | No special config needed. |\n| **Claude Code VS Code extension** (all versions tested through 2.1.x) | Fakes it (advertises capability, never honours) | v6.6.1\'s fast-decline auto-detection routes the call through soft-confirm automatically. **Plus** set `EPIMETHIAN_TOKEN_IN_TEXT=true` in the server\'s env so the agent can read the full token from `content[0].text` \u2014 Claude Code does not currently surface `structuredContent` on `isError: true` responses (issue #15412). No `EPIMETHIAN_BYPASS_ELICITATION` needed; the gate works through the soft-confirm token flow. |\n| **OpenCode** | No \u2014 capability not advertised | v6.6.0+ soft-confirmation token flow is automatic when the client lacks elicitation. The Vercel AI SDK forwards `structuredContent` to the model when `outputSchema` is declared (which v6.6.2 added) \u2014 the agent should be able to read `confirm_token` directly. If your build of OpenCode/AI-SDK doesn\'t honour `outputSchema`, set `EPIMETHIAN_TOKEN_IN_TEXT=true` as a fallback. `EPIMETHIAN_ALLOW_UNGATED_WRITES=true` remains an escape hatch for headless / CI runs where no human is in the loop. |\n| **Cursor / Windsurf / Zed / others** | Varies | If write tools fail with `ELICITATION_REQUIRED_BUT_UNAVAILABLE`, the client doesn\'t advertise the capability \u2014 soft-confirm should kick in automatically; use `EPIMETHIAN_ALLOW_UNGATED_WRITES=true` only if no human is in the loop. If write tools succeed at the gate but the agent can\'t see the token in the response, set `EPIMETHIAN_TOKEN_IN_TEXT=true`. If the client *advertises* elicitation but always fails fast (decline arrives in <50 ms), v6.6.1\'s auto-detection re-routes through soft-confirm. Set `EPIMETHIAN_TREAT_ELICITATION_AS_UNSUPPORTED=true` to skip the timing probe on the first call when the client is known to fake it. |\n\n### Three configuration paths \u2014 pick the one that matches your client\n\nThese flags are **not interchangeable**. The newer (v6.6.x) flags\npreserve the human-in-the-loop gate; the older bypass flags remove it.\nDefault to preserving the gate.\n\n- **(Recommended) Soft-confirm token flow.** No env-var bypass needed.\n  v6.6.0 + v6.6.1 + v6.6.3 give you a working soft-confirm round-trip\n  for any client whose host can put a "do you approve?" prompt in front\n  of the user (chat surface, tool-result UI, etc.). For clients with\n  rendering quirks, layer on `EPIMETHIAN_TOKEN_IN_TEXT=true`\n  (additive \u2014 keeps the gate, just exposes the token in\n  `content[0].text` too).\n- **`EPIMETHIAN_ALLOW_UNGATED_WRITES=true`** \u2014 for clients that *don\'t\n  advertise* elicitation AND have no other way to surface a\n  confirmation prompt (e.g. headless / CI runs). Removes the gate\n  entirely; only the harness allow-list and server-side guards remain.\n  Pre-v6.6.0 escape hatch; rarely needed today.\n- **`EPIMETHIAN_BYPASS_ELICITATION=true`** \u2014 unconditional bypass,\n  regardless of whether the client advertises elicitation. Original\n  v6.4.1 escape hatch for Claude Code VS Code\'s "fakes elicitation"\n  bug. **In v6.6.1+ this is no longer needed** for that bug \u2014 the\n  fast-decline detector routes around it. Use only if you specifically\n  want to remove the gate.\n\n### Trade-off: what you give up by setting `ALLOW_UNGATED_WRITES` or `BYPASS_ELICITATION`\n\nThese two flags **disable the human-in-the-loop confirmation gate\nentirely**. Writes still go through the harness\'s tool allow-list (so\nusers can still block the tool in their permission settings) and\nthrough every server-side guard (provenance, source-policy,\nwrite-budget, byte-equivalence) \u2014 but the user no longer gets a\nprompt before each destructive operation. Recommend this only when:\n\n1. The user is aware of and accepts the trade-off, AND\n2. The user\'s MCP client provides some other interaction model where they\n   can intervene (e.g. they review tool calls before approval), OR\n3. The work is read-mostly and only occasional, additive writes happen.\n\n**Do NOT set either flag silently.** If you (the agent) need to recommend\none, explain to the user what the gate is for, why their client can\'t\nhonour it, and what alternative protections remain.\n\n`EPIMETHIAN_TREAT_ELICITATION_AS_UNSUPPORTED` and\n`EPIMETHIAN_TOKEN_IN_TEXT` (v6.6.1+ / v6.6.2+) are different \u2014 they\n**preserve** the gate by routing through the soft-confirm token flow.\nThey affect how the prompt reaches the user, not whether one happens.\nPrefer these to the bypass flags whenever the client supports any\nform of agent \u2194 user dialogue.\n\n## Other operator-side environment variables\n\nThese are off by default and only relevant in specific scenarios:\n\n- **`EPIMETHIAN_SUPPRESS_EQUIVALENT_DELETIONS`** \u2014 opt-in (default OFF).\n  When set to `true`, suppresses the `confirm_deletions` gate for token\n  deletion+creation pairs that canonicalise to byte-equivalent XML\n  (e.g. re-rendering the same `<ac:link>` macros with different attribute\n  order, or regenerating an `<ac:structured-macro>` whose parameters and\n  CDATA body are identical after sort). Genuine semantic deletions still\n  fire the gate. Every suppressed pair is recorded in the mutation log\n  for postmortem. Useful for spaces with lots of cross-link rewrites\n  where the gate fires repeatedly on no-op churn.\n- **`EPIMETHIAN_REQUIRE_SOURCE`** \u2014 opt-in (default OFF). When `true`,\n  every write tool call must include a `source` parameter (one of\n  `user_request` / `file_or_cli_input` / `chained_tool_output` /\n  `elicitation_response`). Calls without an explicit source are rejected\n  with `SOURCE_POLICY_BLOCKED`. Useful in audit-heavy environments where\n  every write must declare provenance.\n- **`EPIMETHIAN_AUTO_UPGRADE`** \u2014 opt-in (default OFF). When `true`, the\n  server checks for and applies updates on startup. Useful for managed\n  fleets; usually you want explicit `epimethian-mcp upgrade` runs instead.\n- **`CONFLUENCE_READ_ONLY`** \u2014 opt-in (default OFF). When `true`, all\n  write tools are disabled regardless of MCP client config. Useful for\n  read-only profiles or sandbox environments.\n\n## Available Tools (35)\n\n| Tool | Description |\n|------|-------------|\n| `check_permissions` | Report the current profile\'s MCP access mode and the token\'s capabilities |\n| `create_page` | Create a new Confluence page |\n| `get_page` | Read a page by ID (use `headings_only` to preview structure first) |\n| `get_page_by_title` | Look up a page by title (use `headings_only` to preview structure first) |\n| `update_page` | Update an existing page |\n| `update_page_section` | Update a single section by heading name (supports `body` replacement OR `find_replace` literal substitutions) |\n| `update_page_sections` | Atomically update multiple sections in one version bump (all-or-nothing) |\n| `prepend_to_page` | Insert content at the beginning of an existing page (additive, safe) |\n| `append_to_page` | Insert content at the end of an existing page (additive, safe) |\n| `delete_page` | Delete a page |\n| `revert_page` | Revert a page to a previous version |\n| `list_pages` | List pages in a space |\n| `get_page_children` | Get child pages of a page |\n| `search_pages` | Search pages using CQL (Confluence Query Language) |\n| `get_spaces` | List available Confluence spaces |\n| `add_attachment` | Upload a file attachment to a page |\n| `get_attachments` | List attachments on a page |\n| `add_drawio_diagram` | Add a draw.io diagram to a page |\n| `get_labels` | Get all labels on a Confluence page |\n| `add_label` | Add one or more labels to a Confluence page |\n| `remove_label` | Remove a label from a Confluence page |\n| `get_page_status` | Get the content status badge on a page |\n| `set_page_status` | Set the content status badge on a page |\n| `remove_page_status` | Remove the content status badge from a page |\n| `get_comments` | Get footer and/or inline comments on a page |\n| `create_comment` | Create a footer or inline comment on a page |\n| `resolve_comment` | Resolve or reopen an inline comment |\n| `delete_comment` | Permanently delete a comment |\n| `get_page_versions` | List version history for a page |\n| `get_page_version` | Get page content at a specific historical version |\n| `diff_page_versions` | Compare two versions of a page |\n| `lookup_user` | Search for Atlassian users by name or email to resolve accountId for inline mentions |\n| `resolve_page_link` | Resolve a page title + space key to a stable contentId and URL for page links |\n| `get_version` | Return the epimethian-mcp server version and report available updates |\n| `upgrade` | Upgrade epimethian-mcp to the latest available version (restart required after) |\n';
+    install_agent_default = '# Epimethian MCP - Agent Installation Guide\n\n> This document is for AI agents installing and configuring the Epimethian MCP server on behalf of a user.\n\n## Verification\n\nThe official package is **`@de-otio/epimethian-mcp`** (scoped under `@de-otio`).\n\nDo NOT install unscoped alternatives like `epimethian-mcp` \u2014 these are unofficial and potentially unsafe.\n\n## Prerequisites\n\n- Node.js 18 or later\n- npm on PATH\n\n## Step 1: Install\n\n```bash\nnpm install -g @de-otio/epimethian-mcp\n```\n\nVerify the installation:\n\n```bash\nepimethian-mcp --version 2>/dev/null || which epimethian-mcp\n```\n\n## Step 2: Resolve the absolute path\n\nIDE-hosted agents may not resolve PATH correctly. Always use the absolute path in MCP configuration:\n\n```bash\nwhich epimethian-mcp\n```\n\nUse the output as the `command` value in the MCP config below.\n\n## Step 3: Collect configuration\n\nAsk the user for:\n1. **Profile name** \u2014 a short identifier for this Confluence instance (e.g., `globex`, `acme-corp`). Lowercase alphanumeric and hyphens only.\n2. **Confluence Cloud URL** \u2014 e.g., `https://yoursite.atlassian.net`\n3. **Email address** \u2014 the email associated with their Atlassian account\n\n## Step 4: Write MCP configuration\n\nRun `epimethian-mcp setup --profile <name> --client <client-id>` after Step 5 (credential setup) \u2014 it prints the exact config snippet for your MCP host. Supported clients: `claude-code`, `claude-desktop`, `claude-code-vscode`, `cursor`, `windsurf`, `zed`, `opencode`. Keep the fallback hand-typed examples below for cases where the CLI is unavailable.\n\nAdd the server to the user\'s MCP client config. The exact file and shape depend on the client:\n\n**Claude Code, Claude Desktop, Cursor, Windsurf, Zed** \u2014 `.mcp.json` (or the\nequivalent client-specific config). The standard `mcpServers` shape:\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path from Step 2>",\n      "env": {\n        "CONFLUENCE_PROFILE": "<profile name from Step 3>"\n      }\n    }\n  }\n}\n```\n\n**OpenCode** \u2014 `opencode.json` at the project root or\n`~/.config/opencode/opencode.json`. Different shape (`mcp` block, `type:\n"local"`, `command` is an array, `environment` not `env`):\n\n```jsonc\n{\n  "$schema": "https://opencode.ai/config.json",\n  "mcp": {\n    "confluence": {\n      "type": "local",\n      "command": ["<absolute path from Step 2>"],\n      "enabled": true,\n      "environment": {\n        "CONFLUENCE_PROFILE": "<profile name from Step 3>",\n        "EPIMETHIAN_ALLOW_UNGATED_WRITES": "true"\n      }\n    }\n  }\n}\n```\n\nOpenCode does not support MCP elicitation (the in-protocol confirmation\nprompts), so write tools that fire the elicitation gate fail unless\n`EPIMETHIAN_ALLOW_UNGATED_WRITES=true` is set. See "MCP client\ncompatibility" below for the trade-off.\n\n**IMPORTANT:** The only required env var is `CONFLUENCE_PROFILE`. The URL,\nemail, and API token are stored securely in the OS keychain \u2014 they should\nNOT appear in config files.\n\n## Step 5: Credential setup\n\nTell the user to run this command in their terminal:\n\n```\nepimethian-mcp setup --profile <profile name from Step 3>\n```\n\nThis interactive command will:\n1. Prompt for the Confluence URL, email, and API token (masked input)\n2. Test the connection\n3. Store all credentials securely in the OS keychain under the named profile\n\nThe API token is generated at: https://id.atlassian.com/manage-profile/security/api-tokens\n\n**Do NOT ask the user for the API token yourself.** The token must go directly from the user into the interactive setup command to avoid appearing in conversation logs.\n\n## Step 6: User must restart the MCP client\n\n**IMPORTANT:** The user must restart their MCP client (e.g., restart Claude Code, reload VS Code, restart Claude Desktop) for the new server configuration to take effect. The MCP client reads `.mcp.json` at startup and does not detect changes while running.\n\nTell the user:\n> Please restart your MCP client now to activate the Confluence tools.\n\n## Step 7: Validation\n\nAfter the user restarts, verify the server is working by listing available Confluence tools or running a simple operation like listing spaces.\n\n## Adding Additional Tenants\n\nTo add a second Confluence instance (e.g., for a different customer):\n\n1. Run `epimethian-mcp setup --profile <new-profile-name>` with the new credentials\n2. In the project that uses the new tenant, update `.mcp.json` to set `CONFLUENCE_PROFILE` to the new profile name\n3. Restart the MCP client\n\nEach VS Code window / Claude Code session uses the profile specified in its `.mcp.json`. Profiles are fully isolated \u2014 different OS keychain entries, different Confluence instances.\n\n## Managing Profiles\n\n- List all profiles: `epimethian-mcp profiles`\n- Show details: `epimethian-mcp profiles --verbose`\n- Check connection: `CONFLUENCE_PROFILE=<name> epimethian-mcp status`\n- Set read-only: `epimethian-mcp profiles --set-read-only <name>`\n- Set read-write: `epimethian-mcp profiles --set-read-write <name>`\n\n### Read-Only Mode\n\nNew profiles default to **read-only**. When read-only, all write tools are blocked and return an error. To enable writes for a profile:\n\n```bash\nepimethian-mcp profiles --set-read-write <name>\n```\n\nOr during setup: `epimethian-mcp setup --profile <name> --read-write`\n\n**Important:** Restart any running MCP servers after changing the read-only flag.\n\n### Removing a Profile\n\nTo delete a profile and its credentials, run:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\n**Agents must pass `--force`** because the command normally prompts for interactive confirmation (`Remove profile "<name>" and delete its credentials? [y/N]`), which will fail in non-TTY environments like agent shell sessions. The `--force` flag skips the confirmation prompt when stdin is not a TTY.\n\nThis command:\n1. Deletes the credential entry (URL, email, API token) from the OS keychain\n2. Removes the profile from the registry at `~/.config/epimethian-mcp/profiles.json`\n3. Writes an entry to the audit log at `~/.config/epimethian-mcp/audit.log`\n\nAfter removing a profile, also remove or update any `.mcp.json` files that reference it \u2014 otherwise the MCP server will fail to start with a missing-profile error.\n\n**Errors:**\n- If the profile name is invalid (not matching lowercase alphanumeric/hyphens, 1\u201363 chars), the command exits with code 1\n- If the profile does not exist in the keychain, the keychain deletion is silently skipped \u2014 the registry entry is still removed\n\n## Accessing This Guide Post-Install\n\nOnce installed, this guide is available locally via:\n\n```bash\nepimethian-mcp agent-guide\n```\n\nThis prints the full agent guide to stdout \u2014 no web fetch required.\n\n## Uninstallation\n\nWhen a user asks to uninstall Epimethian MCP, follow these steps:\n\n### Step 1: Check for existing profiles\n\n```bash\nepimethian-mcp profiles\n```\n\n### Step 2: Ask the user about credential cleanup\n\nIf profiles exist, ask the user:\n\n> You have Epimethian profiles configured: [list the profile names]. Would you like to delete all stored credentials before uninstalling? (This removes API tokens from your OS keychain.)\n\n### Step 3: Delete credentials (if the user agrees)\n\nFor each profile the user wants removed:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\nOr to remove all profiles:\n\n```bash\nfor name in $(epimethian-mcp profiles | grep \'^ \'); do epimethian-mcp profiles --remove "$name" --force; done\n```\n\n### Step 4: Remove MCP configuration\n\nDelete the `confluence` entry (or the tenant-specific entry like `confluence-globex`) from the project\'s `.mcp.json`.\n\n### Step 5: Uninstall the package\n\n```bash\nnpm uninstall -g @de-otio/epimethian-mcp\n```\n\n### Step 6: Restart the MCP client\n\nTell the user to restart their MCP client so it stops trying to launch the removed server.\n\n## CI/CD (No Keychain)\n\nFor environments where the OS keychain is unavailable (Docker, CI), set all three env vars directly:\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path>",\n      "env": {\n        "CONFLUENCE_URL": "<url>",\n        "CONFLUENCE_EMAIL": "<email>",\n        "CONFLUENCE_API_TOKEN": "<token>"\n      }\n    }\n  }\n}\n```\n\n**Warning:** This exposes the API token in the process environment. Use profile-based auth whenever possible.\n\n## Troubleshooting\n\nIf **npm install fails**:\n- Verify Node.js 18+ is installed: `node --version`\n- Verify npm is on PATH: `npm --version`\n- If permission errors occur, the user may need to fix their npm prefix or use a Node version manager (nvm, fnm)\n\nIf **`epimethian-mcp setup` fails**:\n- "Connection failed": Verify the Confluence URL is correct and accessible\n- "Token is invalid or expired": The user needs to generate a new API token at https://id.atlassian.com/manage-profile/security/api-tokens\n- Keychain errors on Linux: The user may need to install `libsecret` / `gnome-keyring` (`apt install libsecret-tools` or equivalent)\n\nIf **the server doesn\'t appear after restart**:\n- Verify the `.mcp.json` path is correct for the user\'s MCP client\n- Verify the `command` value is an absolute path (run `which epimethian-mcp` to confirm)\n- Check that `.mcp.json` contains valid JSON (no trailing commas, correct quoting)\n\n## Write budget (safety cap on writes)\n\nepimethian-mcp enforces two write-rate caps per server process:\n\n- **Session cap** (default 250): total writes since the server started.\n- **Rolling cap** (default 75 per 15-minute window): catches bursts.\n\nThese are local safety nets, not Confluence limits. They exist because an\nautonomous agent in a retry loop or with a bad plan can issue hundreds of writes\nvery quickly, and most users would rather have a brief pause to confirm than\ndiscover the result an hour later.\n\n### What to do when you (the agent) hit `WRITE_BUDGET_EXCEEDED`\n\n1. **Stop and check.** Was the in-progress work user-requested and going as\n   planned? If unsure, ask the user before continuing.\n2. **Explain to the user, in your own words:**\n   - The safety budget has been hit (which scope, current vs. limit).\n   - What the budget is for: a guard against runaway agents.\n   - Whether the work-in-progress is legitimate (your judgement).\n   - The two ways forward: wait for the rolling window to reopen, or raise the cap.\n3. **If the user wants to raise the cap**, give them this snippet to add to the\n   `env` block of the epimethian-mcp entry in their MCP config (`.mcp.json` or\n   equivalent \u2014 see Step 4 above for the layout):\n\n   ```json\n   "EPIMETHIAN_WRITE_BUDGET_ROLLING": "200",\n   "EPIMETHIAN_WRITE_BUDGET_SESSION": "1000"\n   ```\n\n   Set either value to `"0"` to disable that scope. **Confirm with the user\n   before recommending a raise** \u2014 the budget exists precisely to create a\n   pause-and-check moment. The user must restart the MCP server (re-open the\n   MCP client) for changes to take effect.\n4. **If the user gets a deprecation warning** about `EPIMETHIAN_WRITE_BUDGET_HOURLY`,\n   tell them to rename it to `EPIMETHIAN_WRITE_BUDGET_ROLLING` in the same\n   config file. The old name still works but will be removed in version 7.\n\n### Operator-side defaults\n\n- **`EPIMETHIAN_WRITE_BUDGET_SESSION`** \u2014 default 250; set to "0" to disable.\n- **`EPIMETHIAN_WRITE_BUDGET_ROLLING`** \u2014 default 75 per 15-minute window; set to "0" to disable.\n- **`EPIMETHIAN_WRITE_BUDGET_HOURLY`** \u2014 deprecated alias for `EPIMETHIAN_WRITE_BUDGET_ROLLING`; will be removed in version 7.\n\n## Soft confirmation (clients without working elicitation)\n\nSome MCP clients (OpenCode, the Claude Code VS Code extension, and\nothers) don\'t implement the in-protocol confirmation prompt \u2014 either\nthey don\'t advertise the capability, or they advertise it and never\nhonour the request (the SDK transport silently returns\n`{action: "decline"}` without showing the user a UI). Starting in\nv6.6.0, epimethian-mcp routes those confirmations through your\nagent\'s normal chat surface instead.\n\nThe implementation evolved across v6.6.0 \u2192 v6.6.3:\n\n- **v6.6.0** introduced soft elicitation for clients that don\'t\n  *advertise* the capability \u2014 token-bound, single-use, diff-bound.\n- **v6.6.1** added **fast-decline auto-detection**: if the client\n  advertises elicitation but the decline arrives in <50 ms (well below\n  human reaction time), the session is flagged as fake and the call\n  is re-routed through the soft-confirm path automatically. Threshold\n  is overridable via `EPIMETHIAN_FAST_DECLINE_THRESHOLD_MS=<10..5000>`.\n  No env-var configuration needed for the Claude Code VS Code\n  extension\'s "fakes elicitation" bug \u2014 it Just Works.\n- **v6.6.2** declared `outputSchema` on every mutating tool so\n  spec-compliant clients are obliged to forward `structuredContent`\n  (where the token lives) to the agent. Added an opt-in\n  `EPIMETHIAN_TOKEN_IN_TEXT=true` fallback that appends the full\n  token to `content[0].text` for clients that drop `content` blocks\n  on `isError: true` results (Claude Code issues #15412 / #9962 /\n  #39976).\n- **v6.6.3** swapped the `outputSchema` from `z.discriminatedUnion`\n  to `z.object` so the MCP SDK\'s `normalizeObjectSchema` (which only\n  accepts schemas with `.shape`) can route the structured payload\n  through `validateToolOutput` without throwing `_zod` undefined\n  after the write commits. Hotfix; data-integrity-critical.\n- **v6.7.2** flipped the token-in-text fallback to default-on: the\n  full token now appears in `content[0].text` without needing an env\n  var, since most clients we care about (Claude Code in particular)\n  drop `structuredContent` on `isError: true` results. Set\n  `EPIMETHIAN_HIDE_TOKEN_IN_TEXT=true` to opt out for clients that\n  reliably forward `structuredContent` (or to keep the token out of\n  the agent transcript on principle). The legacy\n  `EPIMETHIAN_TOKEN_IN_TEXT=false` spelling is also honoured for\n  back-compat.\n\n### What you (the agent) see\n\nWhen a destructive write is requested against a client without working\nelicitation, the tool returns an error with a confirmation token:\n\n```\nisError: true\nstructuredContent:\n  {\n    "kind": "confirmation_required",\n    "confirm_token": "<opaque token>",\n    "audit_id": "<UUID for correlation>",\n    "expires_at": "<ISO timestamp>",\n    "page_id": "<pageId>",\n    "human_summary": "<one-line description for the user>",\n    "deletion_summary": { ... numeric counts only ... }   // optional\n  }\ncontent[0].text:\n  \u26A0\uFE0F  Confirmation required (SOFT_CONFIRMATION_REQUIRED)\n\n  {human_summary}\n\n  Please ask the user before retrying. If approved, re-call with the\n  same parameters plus "confirm_token" from structuredContent.\n\n  Token tail: ...<last 8 chars>    Expires: <timestamp>    Audit ID: <uuid>\n\n  [FALLBACK] Full token: <full token>\n  \u2190 present by default in v6.7.2+; suppressed when\n     EPIMETHIAN_HIDE_TOKEN_IN_TEXT=true (or the legacy\n     EPIMETHIAN_TOKEN_IN_TEXT=false) is set\n```\n\nThe `kind` discriminator distinguishes this `"confirmation_required"`\narm from the success arm (`"written"` or `"deleted"`) on the same\ntool. Successful writes return:\n\n```\nstructuredContent:\n  { "kind": "written", "page_id": "...", "new_version": 12, ... }\n```\n\n\u2026or `"kind": "deleted"` for `delete_page`.\n\n### What to do\n\n1. STOP. Don\'t retry blindly.\n2. Show the user, in their language, what\'s about to happen \u2014 use the\n   `human_summary` field from `structuredContent`, or the\n   human-readable text in `content[0].text` if your client doesn\'t\n   forward `structuredContent`. **Never echo the token bytes to the\n   user** \u2014 the token is meant to flow agent \u2192 server, not user \u2192 eye.\n3. Ask the user explicitly. Wait for their answer.\n4. If approved: re-call the tool with the SAME parameters plus\n   `confirm_token`. Read the token from `structuredContent.confirm_token`\n   when available; otherwise the token\'s full bytes are in the\n   `[FALLBACK] Full token: \u2026` line of `content[0].text` (present by\n   default in v6.7.2+, suppressed by `EPIMETHIAN_HIDE_TOKEN_IN_TEXT=true`).\n   The 8-character "Token tail: \u2026" line in the prose is for human\n   inspection only \u2014 it is **not** the token.\n5. If denied: tell the user the operation has been cancelled.\n\n### Token semantics\n\n- Single-use: a successful retry consumes the token. Replays fail.\n- 5-minute TTL by default.\n- Invalidated by any competing write to the same page (stale).\n- Bound to the specific diff and tenant: changing the body, page version, or\n  tenant invalidates the token.\n\n### Operator opt-outs\n\nThese environment variables control soft confirmation behavior:\n\n- **`EPIMETHIAN_ALLOW_UNGATED_WRITES=true`** \u2014 bypasses soft confirmation\n  entirely (no prompt; useful for headless / CI). Removes the\n  human-in-the-loop gate; the harness\'s tool allow-list still applies.\n- **`EPIMETHIAN_DISABLE_SOFT_CONFIRM=true`** \u2014 keeps the legacy\n  `ELICITATION_REQUIRED_BUT_UNAVAILABLE` failure mode for clients without\n  elicitation support.\n- **`EPIMETHIAN_SOFT_CONFIRM_TTL_MS=300000`** \u2014 override the default 5-minute\n  TTL (clamped to 60 seconds minimum, 15 minutes maximum).\n- **`EPIMETHIAN_SOFT_CONFIRM_MINT_LIMIT=100`** \u2014 override the per-15-minute\n  mint cap (default 100; "0" disables the cap entirely).\n\n#### v6.6.1+ fast-decline auto-detection (Claude Code VS Code et al.)\n\n- **`EPIMETHIAN_TREAT_ELICITATION_AS_UNSUPPORTED=true`** \u2014 deterministic\n  counterpart to fast-decline auto-detection. Use when your client is\n  known to advertise elicitation but never honour it (e.g. the Claude\n  Code VS Code extension \u2264 2.1.123) and you want to skip the timing\n  probe on the first call. Distinct from `EPIMETHIAN_BYPASS_ELICITATION`:\n  this routes through the soft-confirmation gate; bypass removes the\n  gate entirely.\n- **`EPIMETHIAN_FAST_DECLINE_THRESHOLD_MS=<10..5000>`** \u2014 override the\n  fast-decline threshold (default 50 ms). Raise this if a slow MCP\n  transport is mis-classifying real declines as fake.\n- **`EPIMETHIAN_DISABLE_FAST_DECLINE_DETECTION=true`** \u2014 total\n  off-switch for the auto-detection; restores exactly v6.6.0 behaviour.\n\n#### v6.7.2+ token-in-text default\n\nThe soft-confirm result text appends a `[FALLBACK] Full token: <token>`\nline by default, so the token is visible to the agent even when the\nclient drops `structuredContent` on `isError: true` (Claude Code issues\n#15412 / #9962 / #39976). This matches the configuration most clients\nneed; making it the default closes the under-configured-install gap.\nThe structured payload is unchanged.\n\n- **`EPIMETHIAN_HIDE_TOKEN_IN_TEXT=true`** \u2014 opt out of the in-text\n  fallback. Use when your client reliably forwards `structuredContent`\n  to the agent and you\'d rather keep the token out of the transcript\n  (the security choice v6.6.0 originally optimised for).\n- **`EPIMETHIAN_TOKEN_IN_TEXT=false`** \u2014 legacy spelling for the same\n  opt-out, honoured for back-compat with v6.6.x configs that pinned\n  the env var to a disabled value. Any other value (unset, "true",\n  "1", typos) leaves the default-on behaviour in place.\n\n#### v6.8.0+ batch authorisation tokens\n\nWhen you need to fan out destructive writes across many pages \u2014 bulk\ndoc refreshes, post-migration cleanups, sub-agent fan-out \u2014 use\n`authorise_destructive_writes` once to get a `batch_token`, then pass\nit to every subsequent `update_page` / `update_page_section` /\n`update_page_sections` / `delete_page` call. ONE user prompt covers\nthe entire batch.\n\n```\n[parent agent]\n  \u2192 AskUserQuestion("Rewrite these 13 pages?")     \u2190 agent harness UX\n  \u2192 user approves\n  \u2192 mcp.authorise_destructive_writes({\n      page_ids: [...13 IDs...],\n      ttl_seconds: 3600,\n      max_operations: 13,\n      reason: "Refresh all runbook pages with v6.8.0 release notes"\n    })\n  \u2192 server fires soft-confirm OR live elicitation (ONE prompt)\n  \u2192 batch_token returned to parent\n  \u2193\n[parent dispatches 13 sub-agents, each given the batch_token]\n  \u2193\n[sub-agent N]\n  \u2192 reads sources, drafts page N\n  \u2192 mcp.update_page({\n      page_id, body, replace_body: true,\n      source: "user_request",\n      batch_token  // \u2190 bypasses the per-call gate\n    })\n  \u2192 server validates batch_token; on match, decrements the operation\n    counter and writes; on any failure (wrong page, expired,\n    exhausted, cloud mismatch), falls through to the per-call\n    confirmation gate transparently\n```\n\n**What the agent should know:**\n\n- The `batch_token` is page-id-scoped. A call to a page outside the\n  approved list looks like a normal first-call destructive write \u2014\n  the agent gets `SOFT_CONFIRMATION_REQUIRED`, NOT a different error\n  class (this is the validation-failure invariant: granular reasons\n  never leak). The fall-through is the right ergonomics; the agent\n  can recover by handling the per-call confirm_token round-trip.\n- The token is NOT diff-bound. The user approved which pages may be\n  written to and how many times \u2014 not the exact bytes of each write.\n  This is a real reduction in defence vs. the per-call `confirm_token`\n  flow: a poisoned page can make the agent draft adversarial content,\n  but only for pages already in the allowlist (the injection cannot\n  redirect the write target). Don\'t request a batch token for pages\n  the agent discovered autonomously.\n- The token has a maximum TTL of 1 hour and a maximum operation cap\n  of `page_ids.length \xD7 2` (network-retry headroom \u2014 not an\n  application-level retry budget). Defaults are 15 min and `N \xD7 1`.\n- The token covers `update_page`, `update_page_section`,\n  `update_page_sections`, and `delete_page`. It does NOT cover\n  `create_page` (no target page_id), `prepend_to_page` /\n  `append_to_page` (use the per-call gate; these are non-destructive\n  by default), or `find_replace` mode of `update_page_section` (also\n  non-destructive).\n- Tokens are process-local. Multi-process deployments hit the same\n  caveat as `confirm_token` \u2014 pin one process per agent.\n\n**Operator opt-outs / strict mode:**\n\n- **`EPIMETHIAN_BATCH_REQUIRES_ELICITATION=true`** \u2014 refuse to mint a\n  batch token via the soft-confirm fallback. Forces the user to\n  approve via real (in-protocol) elicitation. Use when you want to\n  preserve the strong per-call diff-binding and only allow batch\n  authorisation through clients that can render a real confirmation\n  UI.\n- **`EPIMETHIAN_BATCH_MINT_LIMIT=<n>`** \u2014 override the rolling\n  15-minute mint cap (default 25; "0" disables). Distinct from the\n  `confirm_token` mint budget.\n\n### Multi-process deployments\n\nTokens are process-local in-memory. If you\'re running multiple MCP server\nprocesses for one tenant (e.g. a load-balanced fleet or separate processes\nper IDE window), a soft confirmation minted by process P1 will fail validation\nin process P2 (the load balancer routes the retry to a different process).\nThis is not a bug \u2014 it\'s the safe failure mode \u2014 but it means the user needs\nto mint a new token if the retry lands on a different process.\n\n**Recommendation:** Pin a single MCP server process per agent or IDE window.\nPre-seal profiles upgraded from versions before v5.5.0 must run `epimethian-mcp\nsetup` once to acquire a sealed cloudId before soft confirmation is available.\n\n## MCP client compatibility\n\nepimethian-mcp uses MCP **elicitation** (the in-protocol confirmation\nprompt added to MCP in 2025) as the human-in-the-loop gate for destructive\noperations. Different MCP clients support elicitation differently \u2014 some\nfully, some not at all, and some advertise the capability without honouring\nit. The compatibility matrix below tells you which env-var workaround to\nrecommend, if any.\n\n| Client | Elicitation? | What to do (v6.6.3+) |\n|---|---|---|\n| **Claude Code (CLI)** | Yes \u2014 full support | No special config needed. |\n| **Claude Desktop** | Yes \u2014 full support | No special config needed. |\n| **Claude Code VS Code extension** (all versions tested through 2.1.x) | Fakes it (advertises capability, never honours) | v6.6.1\'s fast-decline auto-detection routes the call through soft-confirm automatically. v6.7.2+ surfaces the full token in `content[0].text` by default (Claude Code does not forward `structuredContent` on `isError: true` \u2014 issue #15412), so no env-var configuration is needed. No `EPIMETHIAN_BYPASS_ELICITATION` either; the gate works through the soft-confirm token flow. |\n| **OpenCode** | No \u2014 capability not advertised | v6.6.0+ soft-confirmation token flow is automatic when the client lacks elicitation. The Vercel AI SDK forwards `structuredContent` when `outputSchema` is declared (v6.6.2+); v6.7.2+ also surfaces the token in `content[0].text` by default as a defence-in-depth fallback. Set `EPIMETHIAN_HIDE_TOKEN_IN_TEXT=true` if you\'d rather keep the token out of the transcript on a build that does forward `structuredContent` reliably. `EPIMETHIAN_ALLOW_UNGATED_WRITES=true` remains an escape hatch for headless / CI runs where no human is in the loop. |\n| **Cursor / Windsurf / Zed / others** | Varies | If write tools fail with `ELICITATION_REQUIRED_BUT_UNAVAILABLE`, the client doesn\'t advertise the capability \u2014 soft-confirm should kick in automatically; use `EPIMETHIAN_ALLOW_UNGATED_WRITES=true` only if no human is in the loop. v6.7.2+ ships the full token in `content[0].text` by default, so the agent should always be able to read it. If the client *advertises* elicitation but always fails fast (decline arrives in <50 ms), v6.6.1\'s auto-detection re-routes through soft-confirm. Set `EPIMETHIAN_TREAT_ELICITATION_AS_UNSUPPORTED=true` to skip the timing probe on the first call when the client is known to fake it. |\n\n### Three configuration paths \u2014 pick the one that matches your client\n\nThese flags are **not interchangeable**. The newer (v6.6.x) flags\npreserve the human-in-the-loop gate; the older bypass flags remove it.\nDefault to preserving the gate.\n\n- **(Recommended) Soft-confirm token flow.** No env-var bypass needed.\n  v6.6.0 + v6.6.1 + v6.6.3 give you a working soft-confirm round-trip\n  for any client whose host can put a "do you approve?" prompt in front\n  of the user (chat surface, tool-result UI, etc.). For clients with\n  rendering quirks, layer on `EPIMETHIAN_TOKEN_IN_TEXT=true`\n  (additive \u2014 keeps the gate, just exposes the token in\n  `content[0].text` too).\n- **`EPIMETHIAN_ALLOW_UNGATED_WRITES=true`** \u2014 for clients that *don\'t\n  advertise* elicitation AND have no other way to surface a\n  confirmation prompt (e.g. headless / CI runs). Removes the gate\n  entirely; only the harness allow-list and server-side guards remain.\n  Pre-v6.6.0 escape hatch; rarely needed today.\n- **`EPIMETHIAN_BYPASS_ELICITATION=true`** \u2014 unconditional bypass,\n  regardless of whether the client advertises elicitation. Original\n  v6.4.1 escape hatch for Claude Code VS Code\'s "fakes elicitation"\n  bug. **In v6.6.1+ this is no longer needed** for that bug \u2014 the\n  fast-decline detector routes around it. Use only if you specifically\n  want to remove the gate.\n\n### Trade-off: what you give up by setting `ALLOW_UNGATED_WRITES` or `BYPASS_ELICITATION`\n\nThese two flags **disable the human-in-the-loop confirmation gate\nentirely**. Writes still go through the harness\'s tool allow-list (so\nusers can still block the tool in their permission settings) and\nthrough every server-side guard (provenance, source-policy,\nwrite-budget, byte-equivalence) \u2014 but the user no longer gets a\nprompt before each destructive operation. Recommend this only when:\n\n1. The user is aware of and accepts the trade-off, AND\n2. The user\'s MCP client provides some other interaction model where they\n   can intervene (e.g. they review tool calls before approval), OR\n3. The work is read-mostly and only occasional, additive writes happen.\n\n**Do NOT set either flag silently.** If you (the agent) need to recommend\none, explain to the user what the gate is for, why their client can\'t\nhonour it, and what alternative protections remain.\n\n`EPIMETHIAN_TREAT_ELICITATION_AS_UNSUPPORTED` and\n`EPIMETHIAN_TOKEN_IN_TEXT` (v6.6.1+ / v6.6.2+) are different \u2014 they\n**preserve** the gate by routing through the soft-confirm token flow.\nThey affect how the prompt reaches the user, not whether one happens.\nPrefer these to the bypass flags whenever the client supports any\nform of agent \u2194 user dialogue.\n\n## Other operator-side environment variables\n\nThese are off by default and only relevant in specific scenarios:\n\n- **`EPIMETHIAN_SUPPRESS_EQUIVALENT_DELETIONS`** \u2014 opt-in (default OFF).\n  When set to `true`, suppresses the `confirm_deletions` gate for token\n  deletion+creation pairs that canonicalise to byte-equivalent XML\n  (e.g. re-rendering the same `<ac:link>` macros with different attribute\n  order, or regenerating an `<ac:structured-macro>` whose parameters and\n  CDATA body are identical after sort). Genuine semantic deletions still\n  fire the gate. Every suppressed pair is recorded in the mutation log\n  for postmortem. Useful for spaces with lots of cross-link rewrites\n  where the gate fires repeatedly on no-op churn.\n- **`EPIMETHIAN_REQUIRE_SOURCE`** \u2014 opt-in (default OFF). When `true`,\n  every write tool call must include a `source` parameter (one of\n  `user_request` / `file_or_cli_input` / `chained_tool_output` /\n  `elicitation_response`). Calls without an explicit source are rejected\n  with `SOURCE_POLICY_BLOCKED`. Useful in audit-heavy environments where\n  every write must declare provenance.\n- **`EPIMETHIAN_AUTO_UPGRADE`** \u2014 opt-in (default OFF). When `true`, the\n  server checks for and applies updates on startup. Useful for managed\n  fleets; usually you want explicit `epimethian-mcp upgrade` runs instead.\n- **`CONFLUENCE_READ_ONLY`** \u2014 opt-in (default OFF). When `true`, all\n  write tools are disabled regardless of MCP client config. Useful for\n  read-only profiles or sandbox environments.\n\n## Available Tools (36)\n\n| Tool | Description |\n|------|-------------|\n| `check_permissions` | Report the current profile\'s MCP access mode and the token\'s capabilities |\n| `create_page` | Create a new Confluence page |\n| `get_page` | Read a page by ID (use `headings_only` to preview structure first) |\n| `get_page_by_title` | Look up a page by title (use `headings_only` to preview structure first) |\n| `update_page` | Update an existing page |\n| `update_page_section` | Update a single section by heading name (supports `body` replacement OR `find_replace` literal substitutions) |\n| `update_page_sections` | Atomically update multiple sections in one version bump (all-or-nothing) |\n| `prepend_to_page` | Insert content at the beginning of an existing page (additive, safe) |\n| `append_to_page` | Insert content at the end of an existing page (additive, safe) |\n| `delete_page` | Delete a page |\n| `authorise_destructive_writes` | Pre-authorise a batch of destructive writes (returns `batch_token` consumed by subsequent update / delete calls) |\n| `revert_page` | Revert a page to a previous version |\n| `list_pages` | List pages in a space |\n| `get_page_children` | Get child pages of a page |\n| `search_pages` | Search pages using CQL (Confluence Query Language) |\n| `get_spaces` | List available Confluence spaces |\n| `add_attachment` | Upload a file attachment to a page |\n| `get_attachments` | List attachments on a page |\n| `add_drawio_diagram` | Add a draw.io diagram to a page |\n| `get_labels` | Get all labels on a Confluence page |\n| `add_label` | Add one or more labels to a Confluence page |\n| `remove_label` | Remove a label from a Confluence page |\n| `get_page_status` | Get the content status badge on a page |\n| `set_page_status` | Set the content status badge on a page |\n| `remove_page_status` | Remove the content status badge from a page |\n| `get_comments` | Get footer and/or inline comments on a page |\n| `create_comment` | Create a footer or inline comment on a page |\n| `resolve_comment` | Resolve or reopen an inline comment |\n| `delete_comment` | Permanently delete a comment |\n| `get_page_versions` | List version history for a page |\n| `get_page_version` | Get page content at a specific historical version |\n| `diff_page_versions` | Compare two versions of a page |\n| `lookup_user` | Search for Atlassian users by name or email to resolve accountId for inline mentions |\n| `resolve_page_link` | Resolve a page title + space key to a stable contentId and URL for page links |\n| `get_version` | Return the epimethian-mcp server version and report available updates |\n| `upgrade` | Upgrade epimethian-mcp to the latest available version (restart required after) |\n';
   }
 });
 
@@ -49973,7 +50291,7 @@ __export(upgrade_exports, {
   runUpgrade: () => runUpgrade
 });
 async function runUpgrade() {
-  const currentVersion = "6.7.1";
+  const currentVersion = "6.9.0";
   console.log(`epimethian-mcp upgrade: current version v${currentVersion}`);
   let pending = await getPendingUpdate();
   if (!pending) {
@@ -60223,6 +60541,7 @@ init_zod();
 var import_promises4 = require("node:fs/promises");
 var import_node_os3 = require("node:os");
 var import_node_path4 = require("node:path");
+var import_node_crypto7 = require("node:crypto");
 init_confluence_client();
 
 // node_modules/diff/libesm/diff/base.js
@@ -60866,6 +61185,7 @@ async function markPageUnverified(pageId, cfg) {
 
 // src/server/index.ts
 init_safe_write();
+init_batch_tokens();
 
 // src/server/source-provenance.ts
 init_zod();
@@ -61206,6 +61526,29 @@ var deleteOutputSchema = external_exports.object({
   human_summary: external_exports.string().optional(),
   deletion_summary: deletionSummarySchema.optional()
 });
+var batchAuthorisedArm = external_exports.object({
+  kind: external_exports.literal("batch_authorised"),
+  batch_token: external_exports.string().min(1),
+  audit_id: external_exports.string().min(1),
+  expires_at: external_exports.string().min(1),
+  authorised_page_ids: external_exports.array(external_exports.string().min(1)).min(1),
+  remaining_operations: external_exports.number().int().nonnegative()
+});
+var batchAuthOutputSchema = external_exports.object({
+  kind: external_exports.enum(["batch_authorised", "confirmation_required"]),
+  // shared (audit_id and expires_at appear on both arms)
+  audit_id: external_exports.string().min(1).optional(),
+  expires_at: external_exports.string().min(1).optional(),
+  // batch_authorised arm fields
+  batch_token: external_exports.string().min(1).optional(),
+  authorised_page_ids: external_exports.array(external_exports.string().min(1)).optional(),
+  remaining_operations: external_exports.number().int().nonnegative().optional(),
+  // confirmation_required arm fields
+  confirm_token: external_exports.string().min(1).optional(),
+  page_id: external_exports.string().min(1).optional(),
+  human_summary: external_exports.string().optional(),
+  deletion_summary: deletionSummarySchema.optional()
+});
 
 // src/server/index.ts
 init_update_orchestrator();
@@ -61943,6 +62286,148 @@ ${truncated}${truncationNote(origLen)}`
       }
     }
   );
+  server.registerTool(
+    "authorise_destructive_writes",
+    {
+      description: describeWithLock(
+        withDestructiveWarning(
+          'Pre-authorise a batch of destructive Confluence write operations. Returns a `batch_token` that can be passed to subsequent `update_page` / `update_page_section` / `update_page_sections` / `delete_page` calls in place of `confirm_token`. A SINGLE user prompt covers the entire batch.\n\nUse this when fanning out destructive writes across multiple pages \u2014 sub-agent fan-outs, bulk doc refreshes, post-migration cleanups. The token is page-id-scoped: calls to pages outside the `page_ids` allowlist fall through to the per-call confirmation gate (no different error class than a normal destructive write would produce).\n\nTrade-off vs. per-call `confirm_token`: a batch_token is NOT diff-bound. The user approves which pages may be written to and how many times, but not the exact bytes of each write. This weakens the defence against page-content-driven prompt injection that targets the same page being viewed. Use only when the user has explicitly authorised the batch (e.g. "rewrite these 13 runbook pages") \u2014 never for content the agent discovered autonomously.\n\nIf your MCP client does not support in-protocol confirmation, this tool returns `SOFT_CONFIRMATION_REQUIRED` on the first call. STOP and ask the user. If approved, re-call with the same parameters plus `confirm_token`. The `batch_token` returned then covers all subsequent destructive writes within `page_ids` until `ttl_seconds` elapse or `max_operations` are exhausted.'
+        ),
+        config3
+      ),
+      inputSchema: {
+        page_ids: external_exports.array(external_exports.string().min(1)).min(1).max(50).describe(
+          "Explicit list of page IDs the batch_token will be valid for. 1..50 entries. Duplicates are silently deduplicated. Wildcards are NOT supported \u2014 by design, to prevent injection-redirected writes."
+        ),
+        ttl_seconds: external_exports.number().int().min(60).max(3600).default(900).describe(
+          "Token lifetime in seconds. Clamped to [60, 3600]. Default 900 (15 min)."
+        ),
+        max_operations: external_exports.number().int().min(1).max(100).optional().describe(
+          "Total operations the token authorises across all pages. Defaults to `page_ids.length` (one successful write per page). Maximum is `page_ids.length \xD7 2` \u2014 headroom for network-level retries the server cannot distinguish from real conflicts; do NOT rely on it for application-level retry budgets."
+        ),
+        reason: external_exports.string().min(10).max(500).describe(
+          'Human-readable purpose, shown to the user during the confirmation prompt (e.g. "Bulk doc refresh: rewrite N runbook pages with v6.8.0 release notes"). Required so the user can make an informed authorisation decision.'
+        ),
+        source: sourceSchema,
+        confirm_token: external_exports.string().optional().describe(
+          "Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response on this same tool. Single-use; bound to the exact {page_ids, ttl_seconds, max_operations, reason} tuple."
+        )
+      },
+      // v6.8.0 — declared so spec-compliant clients forward
+      // structuredContent (which carries the batch_token) to the agent.
+      // Same rationale as v6.6.2 §3.1 for the other write tools.
+      outputSchema: batchAuthOutputSchema,
+      annotations: { destructiveHint: true, idempotentHint: false }
+    },
+    async ({ page_ids, ttl_seconds, max_operations, reason, source, confirm_token }) => {
+      const blocked = writeGuard("authorise_destructive_writes", config3);
+      if (blocked) return blocked;
+      try {
+        const effectiveSource = validateSource(source, ["authorise_destructive_writes"]);
+        const requireLiveElicitation = process.env.EPIMETHIAN_BATCH_REQUIRES_ELICITATION === "true";
+        const cfg = await getConfig();
+        const cloudId = cfg.sealedCloudId;
+        if (cloudId === void 0) {
+          throw new Error(
+            "authorise_destructive_writes requires a sealed cloudId. Run `epimethian-mcp setup` once to acquire one."
+          );
+        }
+        for (const pageId of page_ids) {
+          await checkSpaceAllowed({ pageId });
+        }
+        const dedupedPageIds = Array.from(new Set(page_ids));
+        const resolvedTtl = Math.min(3600, Math.max(60, Math.floor(ttl_seconds)));
+        const N = dedupedPageIds.length;
+        const resolvedMax = Math.min(N * 2, max_operations ?? N);
+        const requestDigestSrc = JSON.stringify({
+          tool: "authorise_destructive_writes",
+          cloudId,
+          page_ids: [...dedupedPageIds].sort(),
+          ttl_seconds: resolvedTtl,
+          max_operations: resolvedMax,
+          reason
+        });
+        const diffHash = (0, import_node_crypto7.createHash)("sha256").update(requestDigestSrc).digest("hex");
+        const SYNTH_PAGE_ID = "__batch_authorisation__";
+        const SYNTH_PAGE_VERSION = 1;
+        const tokenResult = await maybeConsumeConfirmToken({
+          confirm_token,
+          tool: "authorise_destructive_writes",
+          cloudId,
+          pageId: SYNTH_PAGE_ID,
+          pageVersion: SYNTH_PAGE_VERSION,
+          diffHash
+        });
+        if (tokenResult === "invalid") {
+          throw new ConverterError(
+            "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
+            "CONFIRMATION_TOKEN_INVALID"
+          );
+        } else if (tokenResult === "no_token") {
+          const idsList = dedupedPageIds.join(", ");
+          const summary = `Pre-authorise destructive writes to ${N} page${N === 1 ? "" : "s"}: ${idsList}. Up to ${resolvedMax} operation${resolvedMax === 1 ? "" : "s"} within ${resolvedTtl} seconds. Reason: ${reason}. Source: ${effectiveSource}.`;
+          if (requireLiveElicitation && !effectiveSupportsElicitation(server)) {
+            throw new Error(
+              "EPIMETHIAN_BATCH_REQUIRES_ELICITATION=true: refusing to mint a batch token via the soft-confirm fallback. The connected client must support in-protocol elicitation. Either enable elicitation on the client, fall back to per-page confirm_token, or unset EPIMETHIAN_BATCH_REQUIRES_ELICITATION."
+            );
+          }
+          await gateOperation(server, {
+            tool: "authorise_destructive_writes",
+            summary,
+            details: {
+              page_count: N,
+              max_operations: resolvedMax,
+              ttl_seconds: resolvedTtl,
+              source: effectiveSource
+            },
+            cloudId,
+            pageId: SYNTH_PAGE_ID,
+            pageVersion: SYNTH_PAGE_VERSION,
+            diffHash
+          });
+        }
+        const batch = mintBatchToken({
+          cloudId,
+          pageIds: dedupedPageIds,
+          ttlSeconds: resolvedTtl,
+          maxOperations: resolvedMax
+        });
+        const expiresIso = new Date(batch.expiresAt).toISOString();
+        const idsLine = dedupedPageIds.join(", ");
+        const text2 = `Authorised batch destructive writes for ${N} page${N === 1 ? "" : "s"}.
+Pages: ${idsLine}
+Max operations: ${resolvedMax}
+Expires: ${expiresIso}
+Audit ID: ${batch.auditId}
+
+Pass the batch_token below to subsequent update_page / update_page_section / update_page_sections / delete_page calls. Validation failures (wrong page, expired, exhausted, etc.) fall through to the per-call confirmation flow.
+
+batch_token: ${batch.token}` + echo;
+        return {
+          content: [{ type: "text", text: text2 }],
+          structuredContent: {
+            kind: "batch_authorised",
+            batch_token: batch.token,
+            audit_id: batch.auditId,
+            expires_at: expiresIso,
+            authorised_page_ids: batch.authorisedPageIds,
+            remaining_operations: batch.remainingOperations
+          }
+        };
+      } catch (err) {
+        if (err instanceof SoftConfirmationRequiredError) {
+          return formatSoftConfirmationResult(err, { pageId: err.pageId });
+        }
+        if (err instanceof BatchMintRateLimitedError) {
+          return toolError(err);
+        }
+        return toolErrorWithContext(err, {
+          operation: "authorise_destructive_writes",
+          profile: config3.profile
+        });
+      }
+    }
+  );
   server.registerTool(
     "update_page",
     {
@@ -61971,7 +62456,10 @@ ${truncated}${truncationNote(origLen)}`
         allow_raw_html: external_exports.boolean().default(false).describe("Allow raw HTML passthrough inside markdown bodies (disabled by default)."),
         confluence_base_url: external_exports.string().url().optional().describe("Override the Confluence base URL used by the link rewriter. Defaults to the configured Confluence URL."),
         source: sourceSchema,
-        confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact diff and page version.")
+        confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact diff and page version."),
+        batch_token: external_exports.string().optional().describe(
+          "Batch authorisation token from a prior authorise_destructive_writes call. Bypasses the per-call confirmation gate when valid for this page_id. Validation failures fall through to the per-call confirm_token / soft-confirm flow."
+        )
       },
       // v6.6.2 §3.1 — declared so spec-compliant clients forward our
       // structuredContent payload to the agent (the soft-confirmation
@@ -61980,9 +62468,11 @@ ${truncated}${truncationNote(origLen)}`
       outputSchema: writeOutputSchema,
       annotations: { destructiveHint: false, idempotentHint: false }
     },
-    async ({ page_id, title, version: version2, body, version_message, confirm_deletions, replace_body, confirm_shrinkage, confirm_structure_loss, allow_raw_html, confluence_base_url, source, confirm_token }) => {
+    async ({ page_id, title, version: version2, body, version_message, confirm_deletions, replace_body, confirm_shrinkage, confirm_structure_loss, allow_raw_html, confluence_base_url, source, confirm_token, batch_token }) => {
       const blocked = writeGuard("update_page", config3);
       if (blocked) return blocked;
+      let batchReservationId;
+      let dispatched = false;
       try {
         await checkSpaceAllowed({ pageId: page_id });
         const flagsSet = listDestructiveFlagsSet({
@@ -61999,36 +62489,44 @@ ${truncated}${truncationNote(origLen)}`
         const pageVersion = currentPage.version?.number ?? 0;
         if (flagsSet.length > 0) {
           const deletionSummary = confirm_deletions && body ? tryForecastDeletions(currentStorage, body, confluence_base_url ?? cfg.url) : null;
-          const diffHash = cloudId && pageVersion > 0 ? computeDiffHash(body ?? currentStorage, pageVersion) : void 0;
-          const tokenResult = await maybeConsumeConfirmToken({
-            confirm_token,
-            tool: "update_page",
+          const batchAttempt = await tryBatchTokenForWrite({
+            batch_token,
             cloudId,
-            pageId: page_id,
-            pageVersion,
-            diffHash
+            pageId: page_id
           });
-          if (tokenResult === "invalid") {
-            throw new ConverterError(
-              "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
-              "CONFIRMATION_TOKEN_INVALID"
-            );
-          } else if (tokenResult === "no_token") {
-            await gateOperation(server, {
+          batchReservationId = batchAttempt.batchReservationId;
+          if (batchReservationId === void 0) {
+            const diffHash = cloudId && pageVersion > 0 ? computeDiffHash(body ?? currentStorage, pageVersion) : void 0;
+            const tokenResult = await maybeConsumeConfirmToken({
+              confirm_token,
               tool: "update_page",
-              summary: `Update page ${page_id} with destructive flags?`,
-              details: {
-                page_id,
-                flags: flagsSet.join(","),
-                source: effectiveSource,
-                version: version2,
-                ...deletionSummary ? { deletionSummary } : {}
-              },
               cloudId,
               pageId: page_id,
               pageVersion,
               diffHash
             });
+            if (tokenResult === "invalid") {
+              throw new ConverterError(
+                "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
+                "CONFIRMATION_TOKEN_INVALID"
+              );
+            } else if (tokenResult === "no_token") {
+              await gateOperation(server, {
+                tool: "update_page",
+                summary: `Update page ${page_id} with destructive flags?`,
+                details: {
+                  page_id,
+                  flags: flagsSet.join(","),
+                  source: effectiveSource,
+                  version: version2,
+                  ...deletionSummary ? { deletionSummary } : {}
+                },
+                cloudId,
+                pageId: page_id,
+                pageVersion,
+                diffHash
+              });
+            }
           }
         }
         const resolvedVersion = version2 === "current" ? currentPage.version?.number ?? 0 : version2;
@@ -62048,6 +62546,7 @@ ${truncated}${truncationNote(origLen)}`
           confluenceBaseUrl: confluence_base_url ?? cfg.url
         });
         const mergedVersionMessage = prepared.versionMessage && version_message ? `${version_message}; ${prepared.versionMessage}` : prepared.versionMessage || version_message || "";
+        dispatched = true;
         const submitted = await safeSubmitPage({
           pageId: page_id,
           title,
@@ -62074,6 +62573,9 @@ ${truncated}${truncationNote(origLen)}`
         const badgeResult = await markPageUnverified(submitted.page.id, cfg);
         if (badgeResult.warning) warnings.push(badgeResult.warning);
         if (isTitleOnly) {
+          if (batchReservationId !== void 0) {
+            finaliseReservation(batchReservationId);
+          }
           const titleOnlyResult = toolResult(
             appendWarnings(`Updated: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, title only, body unchanged)`, warnings) + echo
           );
@@ -62088,6 +62590,9 @@ ${truncated}${truncationNote(origLen)}`
           };
         }
         const removalNote = submitted.deletedTokens.length > 0 ? `; removed ${submitted.deletedTokens.length} preserved macro${submitted.deletedTokens.length === 1 ? "" : "s"}: ${submitted.deletedTokens.map((t) => t.fingerprint).join(", ")}` : "";
+        if (batchReservationId !== void 0) {
+          finaliseReservation(batchReservationId);
+        }
         const bodyUpdateResult = toolResult(
           appendWarnings(`Updated: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, body: ${submitted.oldLen}\u2192${submitted.newLen} chars${removalNote})`, warnings) + echo
         );
@@ -62103,6 +62608,9 @@ ${truncated}${truncationNote(origLen)}`
           }
         };
       } catch (err) {
+        if (batchReservationId !== void 0 && !dispatched) {
+          refundReservation(batchReservationId);
+        }
         if (err instanceof SoftConfirmationRequiredError) {
           return formatSoftConfirmationResult(err, { pageId: page_id });
         }
@@ -62125,7 +62633,10 @@ ${truncated}${truncationNote(origLen)}`
           "The page version number from your most recent get_page call. Required unless EPIMETHIAN_LEGACY_DELETE_WITHOUT_VERSION=true is set; omitting it under the legacy flag emits a stderr warning."
         ),
         source: sourceSchema,
-        confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact page version.")
+        confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact page version."),
+        batch_token: external_exports.string().optional().describe(
+          "Batch authorisation token from a prior authorise_destructive_writes call. Bypasses the per-call confirmation gate when valid for this page_id. Validation failures fall through to the per-call confirm_token / soft-confirm flow."
+        )
       },
       // v6.6.2 §3.1 — declared so spec-compliant clients forward our
       // structuredContent payload (especially the soft-confirm token)
@@ -62133,9 +62644,11 @@ ${truncated}${truncationNote(origLen)}`
       outputSchema: deleteOutputSchema,
       annotations: { destructiveHint: true, idempotentHint: true }
     },
-    async ({ page_id, version: version2, source, confirm_token }) => {
+    async ({ page_id, version: version2, source, confirm_token, batch_token }) => {
       const blocked = writeGuard("delete_page", config3);
       if (blocked) return blocked;
+      let batchReservationId;
+      let dispatched = false;
       try {
         await checkSpaceAllowed({ pageId: page_id });
         const effectiveSource = validateSource(source, ["delete_page"]);
@@ -62156,35 +62669,44 @@ ${truncated}${truncationNote(origLen)}`
         const cloudId = cfg.sealedCloudId;
         const pageVersion = version2 ?? 0;
         const diffHash = cloudId && pageVersion > 0 ? computeDiffHash("", pageVersion) : void 0;
-        const tokenResult = await maybeConsumeConfirmToken({
-          confirm_token,
-          tool: "delete_page",
+        const batchAttempt = await tryBatchTokenForWrite({
+          batch_token,
           cloudId,
-          pageId: page_id,
-          pageVersion,
-          diffHash
+          pageId: page_id
         });
-        if (tokenResult === "invalid") {
-          throw new ConverterError(
-            "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
-            "CONFIRMATION_TOKEN_INVALID"
-          );
-        } else if (tokenResult === "no_token") {
-          await gateOperation(server, {
+        batchReservationId = batchAttempt.batchReservationId;
+        if (batchReservationId === void 0) {
+          const tokenResult = await maybeConsumeConfirmToken({
+            confirm_token,
             tool: "delete_page",
-            summary: `Delete page ${page_id}?`,
-            details: {
-              page_id,
-              version: version2 ?? "(legacy: unversioned)",
-              source: effectiveSource
-            },
             cloudId,
             pageId: page_id,
             pageVersion,
             diffHash
           });
+          if (tokenResult === "invalid") {
+            throw new ConverterError(
+              "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
+              "CONFIRMATION_TOKEN_INVALID"
+            );
+          } else if (tokenResult === "no_token") {
+            await gateOperation(server, {
+              tool: "delete_page",
+              summary: `Delete page ${page_id}?`,
+              details: {
+                page_id,
+                version: version2 ?? "(legacy: unversioned)",
+                source: effectiveSource
+              },
+              cloudId,
+              pageId: page_id,
+              pageVersion,
+              diffHash
+            });
+          }
         }
         writeBudget.consume();
+        dispatched = true;
         await deletePage(page_id, version2);
         if (cloudId !== void 0) {
           invalidateForPage(cloudId, page_id);
@@ -62196,6 +62718,9 @@ ${truncated}${truncationNote(origLen)}`
           ...version2 !== void 0 ? { oldVersion: version2 } : {},
           source: effectiveSource
         });
+        if (batchReservationId !== void 0) {
+          finaliseReservation(batchReservationId);
+        }
         const deletedResult = toolResult(`Deleted page ${page_id}` + echo);
         return {
           ...deletedResult,
@@ -62206,6 +62731,9 @@ ${truncated}${truncationNote(origLen)}`
           }
         };
       } catch (err) {
+        if (batchReservationId !== void 0 && !dispatched) {
+          refundReservation(batchReservationId);
+        }
         if (err instanceof SoftConfirmationRequiredError) {
           return formatSoftConfirmationResult(err, { pageId: page_id });
         }
@@ -62246,16 +62774,23 @@ ${truncated}${truncationNote(origLen)}`
         ),
         version_message: external_exports.string().optional().describe("Optional version comment"),
         confirm_deletions: external_exports.boolean().default(false).describe("Set to true to acknowledge that your markdown removes preserved macros, emoticons, or rich elements from this section. Required when any preserved element would be deleted."),
-        confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact diff and page version.")
+        confirm_shrinkage: external_exports.boolean().default(false).describe("Set to true to acknowledge a large body reduction. The shrinkage guard is measured against the WHOLE page (not the isolated section), so a small edit to a short section will not trip it; this flag is only needed for a genuinely large page-level reduction."),
+        confirm_structure_loss: external_exports.boolean().default(false).describe("Set to true to acknowledge a large drop in heading count, measured against the whole page."),
+        confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact diff and page version."),
+        batch_token: external_exports.string().optional().describe(
+          "Batch authorisation token from a prior authorise_destructive_writes call. Bypasses the per-call confirmation gate when valid for this page_id. Validation failures fall through to the per-call confirm_token / soft-confirm flow."
+        )
       },
       // v6.6.2 §3.1 — declared so spec-compliant clients forward our
       // structuredContent payload to the agent.
       outputSchema: writeOutputSchema,
       annotations: { destructiveHint: false, idempotentHint: false }
     },
-    async ({ page_id, section, body, find_replace, version: version2, version_message, confirm_deletions, confirm_token }) => {
+    async ({ page_id, section, body, find_replace, version: version2, version_message, confirm_deletions, confirm_shrinkage, confirm_structure_loss, confirm_token, batch_token }) => {
       const blocked = writeGuard("update_page_section", config3);
       if (blocked) return blocked;
+      let batchReservationId;
+      let dispatched = false;
       try {
         const hasBody = body !== void 0;
         const hasFindReplace = find_replace !== void 0 && find_replace.length > 0;
@@ -62306,6 +62841,7 @@ ${truncated}${truncationNote(origLen)}`
               )
             );
           }
+          dispatched = true;
           const submitted2 = await safeSubmitPage({
             pageId: page_id,
             title: page.title,
@@ -62342,37 +62878,50 @@ ${truncated}${truncationNote(origLen)}`
             }
           };
         }
-        if (confirm_deletions) {
-          const deletionSummary = tryForecastDeletions(currentSectionBody, body, cfg.url);
-          const diffHash = cloudId && pageVersion > 0 ? computeDiffHash(body ?? currentSectionBody, pageVersion) : void 0;
-          const tokenResult = await maybeConsumeConfirmToken({
-            confirm_token,
-            tool: "update_page_section",
+        const sectionFlagsSet = listDestructiveFlagsSet({
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss,
+          confirmDeletions: confirm_deletions
+        });
+        if (sectionFlagsSet.length > 0) {
+          const batchAttempt = await tryBatchTokenForWrite({
+            batch_token,
             cloudId,
-            pageId: page_id,
-            pageVersion,
-            diffHash
+            pageId: page_id
           });
-          if (tokenResult === "invalid") {
-            throw new ConverterError(
-              "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
-              "CONFIRMATION_TOKEN_INVALID"
-            );
-          } else if (tokenResult === "no_token") {
-            await gateOperation(server, {
+          batchReservationId = batchAttempt.batchReservationId;
+          if (batchReservationId === void 0) {
+            const deletionSummary = confirm_deletions && body ? tryForecastDeletions(currentSectionBody, body, cfg.url) : null;
+            const diffHash = cloudId && pageVersion > 0 ? computeDiffHash(body ?? currentSectionBody, pageVersion) : void 0;
+            const tokenResult = await maybeConsumeConfirmToken({
+              confirm_token,
               tool: "update_page_section",
-              summary: `Update section "${section}" in page ${page_id} with confirm_deletions?`,
-              details: {
-                page_id,
-                section,
-                source: "confirm_deletions",
-                ...deletionSummary ? { deletionSummary } : {}
-              },
               cloudId,
               pageId: page_id,
               pageVersion,
               diffHash
             });
+            if (tokenResult === "invalid") {
+              throw new ConverterError(
+                "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
+                "CONFIRMATION_TOKEN_INVALID"
+              );
+            } else if (tokenResult === "no_token") {
+              await gateOperation(server, {
+                tool: "update_page_section",
+                summary: `Update section "${section}" in page ${page_id} with ${sectionFlagsSet.join(", ")}?`,
+                details: {
+                  page_id,
+                  section,
+                  flags: sectionFlagsSet.join(","),
+                  ...deletionSummary ? { deletionSummary } : {}
+                },
+                cloudId,
+                pageId: page_id,
+                pageVersion,
+                diffHash
+              });
+            }
           }
         }
         const prepared = await safePrepareBody({
@@ -62380,6 +62929,10 @@ ${truncated}${truncationNote(origLen)}`
           currentBody: currentSectionBody,
           scope: "section",
           confirmDeletions: confirm_deletions || void 0,
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss,
+          // Measure shrink/structure/floor guards against the whole page.
+          fullPageBody: fullBody,
           confluenceBaseUrl: cfg.url
         });
         const newFullBody = replaceSection(fullBody, section, prepared.finalStorage);
@@ -62391,6 +62944,7 @@ ${truncated}${truncationNote(origLen)}`
           );
         }
         const mergedVersionMessage = prepared.versionMessage && version_message ? `${version_message}; ${prepared.versionMessage}` : prepared.versionMessage || version_message || "";
+        dispatched = true;
         const submitted = await safeSubmitPage({
           pageId: page_id,
           title: page.title,
@@ -62401,6 +62955,11 @@ ${truncated}${truncationNote(origLen)}`
           deletedTokens: prepared.deletedTokens,
           operation: "update_page_section",
           clientLabel: getClientLabel(server),
+          // Recorded for the destructive-flag audit / version-message suffix;
+          // guards already ran in safePrepareBody (page-relative).
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss,
+          confirmDeletions: confirm_deletions || void 0,
           cloudId
         });
         const warnings = [];
@@ -62409,6 +62968,9 @@ ${truncated}${truncationNote(origLen)}`
         const badgeResult = await markPageUnverified(submitted.page.id, cfg);
         if (badgeResult.warning) warnings.push(badgeResult.warning);
         const removalNote = submitted.deletedTokens.length > 0 ? `; removed ${submitted.deletedTokens.length} preserved macro${submitted.deletedTokens.length === 1 ? "" : "s"}: ${submitted.deletedTokens.map((t) => t.fingerprint).join(", ")}` : "";
+        if (batchReservationId !== void 0) {
+          finaliseReservation(batchReservationId);
+        }
         const sectionBodyResult = toolResult(
           appendWarnings(`Updated section "${section}" in: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}${removalNote})`, warnings) + echo
         );
@@ -62424,6 +62986,9 @@ ${truncated}${truncationNote(origLen)}`
           }
         };
       } catch (err) {
+        if (batchReservationId !== void 0 && !dispatched) {
+          refundReservation(batchReservationId);
+        }
         if (err instanceof SoftConfirmationRequiredError) {
           return formatSoftConfirmationResult(err, { pageId: page_id });
         }
@@ -62449,7 +63014,12 @@ ${truncated}${truncationNote(origLen)}`
         confirm_deletions: external_exports.boolean().default(false).describe(
           "Set to true to acknowledge that the aggregated set of sections removes preserved macros, emoticons, or rich elements. Required when ANY section would delete a preserved element. The deletion-summary gate fires once on the AGGREGATE \u2014 a caller cannot bypass the gate by spreading deletions across sections."
         ),
+        confirm_shrinkage: external_exports.boolean().default(false).describe("Set to true to acknowledge a large body reduction. Each section's shrinkage is measured against the WHOLE page, so small edits to short sections will not trip it; needed only for a genuinely large page-level reduction."),
+        confirm_structure_loss: external_exports.boolean().default(false).describe("Set to true to acknowledge a large drop in heading count, measured against the whole page."),
         confirm_token: external_exports.string().optional().describe("Soft-confirmation token from a prior SOFT_CONFIRMATION_REQUIRED response. Single-use; bound to this exact diff and page version."),
+        batch_token: external_exports.string().optional().describe(
+          "Batch authorisation token from a prior authorise_destructive_writes call. Bypasses the per-call confirmation gate when valid for this page_id. Validation failures fall through to the per-call confirm_token / soft-confirm flow."
+        ),
         sections: external_exports.array(
           external_exports.object({
             section: external_exports.string().describe("Heading text identifying the section to replace"),
@@ -62463,9 +63033,11 @@ ${truncated}${truncationNote(origLen)}`
       },
       annotations: { destructiveHint: false, idempotentHint: false }
     },
-    async ({ page_id, version: version2, version_message, confirm_deletions, sections, confirm_token }) => {
+    async ({ page_id, version: version2, version_message, confirm_deletions, confirm_shrinkage, confirm_structure_loss, sections, confirm_token, batch_token }) => {
       const blocked = writeGuard("update_page_sections", config3);
       if (blocked) return blocked;
+      let batchReservationId;
+      let dispatched = false;
       try {
         await checkSpaceAllowed({ pageId: page_id });
         const cfg = await getConfig();
@@ -62479,78 +63051,96 @@ ${truncated}${truncationNote(origLen)}`
             `Could not resolve current version for page ${page_id} (server returned no version metadata)`
           );
         }
-        if (confirm_deletions) {
-          const summed = {
-            tocs: 0,
-            links: 0,
-            structuredMacros: 0,
-            codeMacros: 0,
-            plainElements: 0,
-            other: 0
-          };
-          let any = false;
-          for (const s of sections) {
-            let currentSectionBody = null;
-            try {
-              currentSectionBody = extractSectionBody(fullBody, s.section);
-            } catch {
-              currentSectionBody = null;
-            }
-            if (currentSectionBody === null) continue;
-            const summary = tryForecastDeletions(
-              currentSectionBody,
-              s.body,
-              cfg.url
-            );
-            if (summary !== null) {
-              summed.tocs += summary.tocs;
-              summed.links += summary.links;
-              summed.structuredMacros += summary.structuredMacros;
-              summed.codeMacros += summary.codeMacros;
-              summed.plainElements += summary.plainElements;
-              summed.other += summary.other;
-              any = true;
-            }
-          }
-          const aggregateBody = sections.map((s) => s.body).join("\n");
-          const diffHash = cloudId && pageVersion > 0 ? computeDiffHash(aggregateBody, pageVersion) : void 0;
-          const tokenResult = await maybeConsumeConfirmToken({
-            confirm_token,
-            tool: "update_page_sections",
+        const sectionsFlagsSet = listDestructiveFlagsSet({
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss,
+          confirmDeletions: confirm_deletions
+        });
+        if (sectionsFlagsSet.length > 0) {
+          const batchAttempt = await tryBatchTokenForWrite({
+            batch_token,
             cloudId,
-            pageId: page_id,
-            pageVersion,
-            diffHash
+            pageId: page_id
           });
-          if (tokenResult === "invalid") {
-            throw new ConverterError(
-              "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
-              "CONFIRMATION_TOKEN_INVALID"
-            );
-          } else if (tokenResult === "no_token") {
-            await gateOperation(server, {
+          batchReservationId = batchAttempt.batchReservationId;
+          if (batchReservationId === void 0) {
+            const summed = {
+              tocs: 0,
+              links: 0,
+              structuredMacros: 0,
+              codeMacros: 0,
+              plainElements: 0,
+              other: 0
+            };
+            let any = false;
+            if (confirm_deletions) {
+              for (const s of sections) {
+                let currentSectionBody = null;
+                try {
+                  currentSectionBody = extractSectionBody(fullBody, s.section);
+                } catch {
+                  currentSectionBody = null;
+                }
+                if (currentSectionBody === null) continue;
+                const summary = tryForecastDeletions(
+                  currentSectionBody,
+                  s.body,
+                  cfg.url
+                );
+                if (summary !== null) {
+                  summed.tocs += summary.tocs;
+                  summed.links += summary.links;
+                  summed.structuredMacros += summary.structuredMacros;
+                  summed.codeMacros += summary.codeMacros;
+                  summed.plainElements += summary.plainElements;
+                  summed.other += summary.other;
+                  any = true;
+                }
+              }
+            }
+            const aggregateBody = sections.map((s) => s.body).join("\n");
+            const diffHash = cloudId && pageVersion > 0 ? computeDiffHash(aggregateBody, pageVersion) : void 0;
+            const tokenResult = await maybeConsumeConfirmToken({
+              confirm_token,
               tool: "update_page_sections",
-              summary: `Update ${sections.length} section${sections.length === 1 ? "" : "s"} in page ${page_id} with confirm_deletions?`,
-              details: {
-                page_id,
-                section_count: sections.length,
-                source: "confirm_deletions",
-                ...any ? { deletionSummary: summed } : {}
-              },
               cloudId,
               pageId: page_id,
               pageVersion,
               diffHash
             });
+            if (tokenResult === "invalid") {
+              throw new ConverterError(
+                "The confirmation token is no longer valid. Mint a new one by re-calling this tool without confirm_token, ask the user again, then retry with the new token.",
+                "CONFIRMATION_TOKEN_INVALID"
+              );
+            } else if (tokenResult === "no_token") {
+              await gateOperation(server, {
+                tool: "update_page_sections",
+                summary: `Update ${sections.length} section${sections.length === 1 ? "" : "s"} in page ${page_id} with ${sectionsFlagsSet.join(", ")}?`,
+                details: {
+                  page_id,
+                  section_count: sections.length,
+                  flags: sectionsFlagsSet.join(","),
+                  ...any ? { deletionSummary: summed } : {}
+                },
+                cloudId,
+                pageId: page_id,
+                pageVersion,
+                diffHash
+              });
+            }
           }
         }
         const prepared = await safePrepareMultiSectionBody({
           currentStorage: fullBody,
           sections,
           confirmDeletions: confirm_deletions,
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss,
           confluenceBaseUrl: cfg.url
         });
         const mergedVersionMessage = prepared.versionMessage && version_message ? `${version_message}; ${prepared.versionMessage}` : prepared.versionMessage || version_message || "";
+        dispatched = true;
         const submitted = await safeSubmitPage({
           pageId: page_id,
           title: page.title,
@@ -62563,6 +63153,8 @@ ${truncated}${truncationNote(origLen)}`
           operation: "update_page_section",
           clientLabel: getClientLabel(server),
           confirmDeletions: confirm_deletions,
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss,
           cloudId
         });
         const warnings = [];
@@ -62572,6 +63164,9 @@ ${truncated}${truncationNote(origLen)}`
         if (badgeResult.warning) warnings.push(badgeResult.warning);
         const removalNote = submitted.deletedTokens.length > 0 ? `; removed ${submitted.deletedTokens.length} preserved macro${submitted.deletedTokens.length === 1 ? "" : "s"}: ${submitted.deletedTokens.map((t) => t.fingerprint).join(", ")}` : "";
         const sectionList = prepared.perSectionResults.map((r) => `"${r.section}"`).join(", ");
+        if (batchReservationId !== void 0) {
+          finaliseReservation(batchReservationId);
+        }
         return toolResult(
           appendWarnings(
             `Updated ${prepared.perSectionResults.length} section${prepared.perSectionResults.length === 1 ? "" : "s"} (${sectionList}) in: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}${removalNote})`,
@@ -62579,6 +63174,9 @@ ${truncated}${truncationNote(origLen)}`
           ) + echo
         );
       } catch (err) {
+        if (batchReservationId !== void 0 && !dispatched) {
+          refundReservation(batchReservationId);
+        }
         if (err instanceof SoftConfirmationRequiredError) {
           return formatSoftConfirmationResult(err, { pageId: page_id });
         }
@@ -63013,12 +63611,18 @@ ${truncated}`);
           "Name for the diagram file (e.g., 'architecture.drawio'). Will have .drawio appended if not present."
         ),
         append: external_exports.boolean().default(true).describe(
-          "If true, appends the diagram to existing page content. If false, replaces the page body."
+          "If true, appends the diagram to the end of the page. If false, replaces the page body. Ignored when after_section or return_macro_only is set."
+        ),
+        after_section: external_exports.string().optional().describe(
+          "Heading text of a section to place the diagram in. The diagram is inserted at the END of that section's content (before the next heading) instead of at the end of the page. Use headings_only / get_page to find section names. Takes precedence over `append`."
+        ),
+        return_macro_only: external_exports.boolean().default(false).describe(
+          "If true, upload the diagram as an attachment but DO NOT modify the page body; instead return the draw.io macro storage markup so you can place it yourself with update_page / update_page_section. Use this when you need precise positioning the other options can't express. Takes precedence over `after_section` and `append`. (The attachment is created either way; if you never embed the returned macro it is left orphaned.)"
         )
       },
       annotations: { destructiveHint: false, idempotentHint: false }
     },
-    async ({ page_id, diagram_xml, diagram_name, append }) => {
+    async ({ page_id, diagram_xml, diagram_name, append, after_section, return_macro_only }) => {
       const blocked = writeGuard("add_drawio_diagram", config3);
       if (blocked) return blocked;
       try {
@@ -63053,15 +63657,47 @@ ${truncated}`);
         ].join("\n");
         const current = await getPage(page_id, true);
         const existingBody = current.body?.storage?.value ?? current.body?.value ?? "";
-        const newBody = append ? `${existingBody}
+        if (return_macro_only) {
+          return toolResult(
+            `Diagram "${filename}" uploaded to page ${current.title} (ID: ${page_id}, attachment ID: ${attachmentId}, macro ID: ${macroId}). The page body was NOT modified. Embed the diagram by inserting this macro where you want it (its baseUrl/pageId/diagramName are bound to this page):
+
+${macro}${echo}`
+          );
+        }
+        let newBody;
+        let placementNote = "";
+        if (after_section !== void 0) {
+          const sectionBody = extractSectionBody(existingBody, after_section);
+          if (sectionBody === null) {
+            return toolError(
+              new Error(
+                `Section "${after_section}" not found. Use headings_only to see available sections.`
+              )
+            );
+          }
+          const spliced = replaceSection(
+            existingBody,
+            after_section,
+            `${sectionBody}
+${macro}`
+          );
+          if (spliced === null) {
+            return toolError(
+              new Error(
+                `Section "${after_section}" not found. Use headings_only to see available sections.`
+              )
+            );
+          }
+          newBody = spliced;
+          placementNote = ` in section "${after_section}"`;
+        } else {
+          newBody = append ? `${existingBody}
 ${macro}` : macro;
+        }
         const prepared = await safePrepareBody({
           body: newBody,
           currentBody: existingBody,
           scope: "full"
-          // append=true is additive but newBody already contains the concat,
-          // so "full" is correct: guards compare existingBody vs the complete
-          // new body, which is what we want for both branches.
         });
         const submitted = await safeSubmitPage({
           pageId: page_id,
@@ -63080,7 +63716,7 @@ ${macro}` : macro;
         const badgeResult = await markPageUnverified(submitted.page.id, config3);
         if (badgeResult.warning) warnings.push(badgeResult.warning);
         return toolResult(
-          appendWarnings(`Diagram "${filename}" added to page ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, attachment ID: ${attachmentId}, macro ID: ${macroId})`, warnings) + echo
+          appendWarnings(`Diagram "${filename}" added to page ${submitted.page.title}${placementNote} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, attachment ID: ${attachmentId}, macro ID: ${macroId})`, warnings) + echo
         );
       } catch (err) {
         return toolErrorWithContext(err, { operation: "add_drawio_diagram", resource: `page ${page_id}`, profile: config3.profile });
@@ -63867,7 +64503,7 @@ ${titleFenced}${echo2}`
       inputSchema: {}
     },
     async () => {
-      let text2 = `epimethian-mcp v${"6.7.1"}`;
+      let text2 = `epimethian-mcp v${"6.9.0"}`;
       try {
         const pending = await getPendingUpdate();
         if (pending) {
@@ -63898,7 +64534,7 @@ ${label} update available: v${pending.current} \u2192 v${pending.latest}. Run \`
         const pending = await getPendingUpdate();
         if (!pending) {
           return toolResult(
-            `epimethian-mcp v${"6.7.1"} is already up to date.`
+            `epimethian-mcp v${"6.9.0"} is already up to date.`
           );
         }
         const output = await performUpgrade(pending.latest);
@@ -63920,7 +64556,7 @@ async function startRecoveryServer(profile) {
   const server = new McpServer(
     {
       name: `confluence-${profile}-setup-needed`,
-      version: "6.7.1"
+      version: "6.9.0"
     },
     {
       instructions: `The Confluence profile "${profile}" referenced by CONFLUENCE_PROFILE has no keychain entry, so no Confluence tools are available. Call the setup_profile tool for instructions to create it.`
@@ -63971,21 +64607,21 @@ async function main() {
   const serverName = config3.profile ? `confluence-${config3.profile}` : "confluence";
   const server = new McpServer({
     name: serverName,
-    version: "6.7.1"
+    version: "6.9.0"
   });
   await registerTools(server, config3);
   const transport = new StdioServerTransport();
   await server.connect(transport);
   try {
     const pending = await getPendingUpdate();
-    if (pending && pending.current === "6.7.1") {
+    if (pending && pending.current === "6.9.0") {
       console.error(
         `epimethian-mcp: update available: v${pending.current} \u2192 v${pending.latest} (${pending.type}). Run \`epimethian-mcp upgrade\` to install.`
       );
     }
   } catch {
   }
-  checkForUpdates("6.7.1").catch(() => {
+  checkForUpdates("6.9.0").catch(() => {
   });
 }