@de-otio/epimethian-mcp 5.0.0 → 5.1.0

package/dist/cli/index.js

@@ -24073,14 +24073,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self, node);
         }
-        return join3(output, replacement);
+        return join4(output, replacement);
       }, "");
     }
     function postProcess3(output) {
       var self = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join3(output, rule.append(self.options));
+          output = join4(output, rule.append(self.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -24092,7 +24092,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join3(output, replacement) {
+    function join4(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -34605,7 +34605,7 @@ var init_status = __esm({
 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\nAdd the server to `.mcp.json` (or the equivalent config file for the user\'s MCP client):\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**IMPORTANT:** The only env var needed is `CONFLUENCE_PROFILE`. The URL, email, and API token are stored securely in the OS keychain \u2014 they should NOT 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## Available Tools (29)\n\n| Tool | Description |\n|------|-------------|\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 |\n| `delete_page` | Delete a page |\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 |\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\nAdd the server to `.mcp.json` (or the equivalent config file for the user\'s MCP client):\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**IMPORTANT:** The only env var needed is `CONFLUENCE_PROFILE`. The URL, email, and API token are stored securely in the OS keychain \u2014 they should NOT 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## Available Tools (32)\n\n| Tool | Description |\n|------|-------------|\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 |\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 |\n';
   }
 });
 
@@ -48842,7 +48842,7 @@ var StdioServerTransport = class {
 // src/server/index.ts
 var import_promises2 = require("node:fs/promises");
 var import_node_os2 = require("node:os");
-var import_node_path2 = require("node:path");
+var import_node_path3 = require("node:path");
 
 // src/server/confluence-client.ts
 var import_turndown = __toESM(require_turndown_cjs());
@@ -48853,9 +48853,13 @@ init_test_connection();
 // src/server/page-cache.ts
 var PageCache = class {
   cache = /* @__PURE__ */ new Map();
+  /** Separate map for pre-write snapshots to avoid eviction pressure (Finding 10). */
+  snapshots = /* @__PURE__ */ new Map();
   maxSize;
-  constructor(maxSize = 50) {
+  maxSnapshotSize;
+  constructor(maxSize = 50, maxSnapshotSize = 30) {
     this.maxSize = maxSize;
+    this.maxSnapshotSize = maxSnapshotSize;
   }
   /** Return cached body if page_id exists and version matches. */
   get(pageId, version2) {
@@ -48913,13 +48917,44 @@ var PageCache = class {
   delete(pageId) {
     this.cache.delete(pageId);
   }
+  /**
+   * Store a pre-write snapshot of the page body before a mutation.
+   * Uses a separate map from the main cache to avoid eviction pressure
+   * and key-collision attacks (Finding 10).
+   */
+  setSnapshot(pageId, version2, body) {
+    const key = `${pageId}:${version2}`;
+    this.snapshots.delete(key);
+    if (this.snapshots.size >= this.maxSnapshotSize) {
+      const oldest = this.snapshots.keys().next().value;
+      this.snapshots.delete(oldest);
+    }
+    this.snapshots.set(key, { version: version2, body });
+  }
+  /**
+   * Retrieve a pre-write snapshot for a specific page and version.
+   */
+  getSnapshot(pageId, version2) {
+    const key = `${pageId}:${version2}`;
+    const entry = this.snapshots.get(key);
+    if (entry) {
+      this.snapshots.delete(key);
+      this.snapshots.set(key, entry);
+      return entry.body;
+    }
+    return void 0;
+  }
   /** Empty the cache. */
   clear() {
     this.cache.clear();
+    this.snapshots.clear();
   }
   get size() {
     return this.cache.size;
   }
+  get snapshotSize() {
+    return this.snapshots.size;
+  }
 };
 var pageCache = new PageCache();
 
@@ -49239,7 +49274,7 @@ async function createPage(spaceId, title, body, parentId) {
       representation: "storage",
       value: pageBody
     },
-    version: { message: `Created by Epimethian v${"5.0.0"}` }
+    version: { message: `Created by Epimethian v${"5.1.0"}` }
   };
   if (parentId) payload.parentId = parentId;
   const raw = await v2Post("/pages", payload);
@@ -49254,7 +49289,7 @@ async function createPage(spaceId, title, body, parentId) {
 async function updatePage(pageId, opts) {
   const cfg = await getConfig();
   const newVersion = opts.version + 1;
-  const versionMessage = opts.versionMessage ? `${opts.versionMessage} (via Epimethian v${"5.0.0"})` : `Updated by Epimethian v${"5.0.0"}`;
+  const versionMessage = opts.versionMessage ? `${opts.versionMessage} (via Epimethian v${"5.1.0"})` : `Updated by Epimethian v${"5.1.0"}`;
   const payload = {
     id: pageId,
     status: "current",
@@ -49269,6 +49304,9 @@ async function updatePage(pageId, opts) {
       value: pageBody
     };
   }
+  if (opts.previousBody !== void 0) {
+    pageCache.setSnapshot(pageId, opts.version, opts.previousBody);
+  }
   let raw;
   try {
     raw = await v2Put(`/pages/${pageId}`, payload);
@@ -49462,7 +49500,7 @@ var ATTRIBUTION_LABEL = "epimethian-managed";
 var ATTRIBUTION_START = "<!-- epimethian-attribution-start -->";
 var ATTRIBUTION_END = "<!-- epimethian-attribution-end -->";
 function buildAttributionFooter(action) {
-  return ATTRIBUTION_START + `<p style="font-size:9px;color:#999;margin-top:2em;"><em>This page was ${action} with <a href="${GITHUB_URL}">Epimethian</a> v${"5.0.0"}.</em></p>` + ATTRIBUTION_END;
+  return ATTRIBUTION_START + `<p style="font-size:9px;color:#999;margin-top:2em;"><em>This page was ${action} with <a href="${GITHUB_URL}">Epimethian</a> v${"5.1.0"}.</em></p>` + ATTRIBUTION_END;
 }
 function stripAttributionFooter(body) {
   return body.replace(
@@ -55842,6 +55880,9 @@ var ConverterError = class extends Error {
     this.name = "ConverterError";
   }
 };
+var SHRINKAGE_NOT_CONFIRMED = "SHRINKAGE_NOT_CONFIRMED";
+var STRUCTURE_LOSS_NOT_CONFIRMED = "STRUCTURE_LOSS_NOT_CONFIRMED";
+var EMPTY_BODY_REJECTED = "EMPTY_BODY_REJECTED";
 
 // src/server/converter/md-to-storage.ts
 var MAX_INPUT_BYTES = 1048576;
@@ -56688,6 +56729,49 @@ function planUpdate(params) {
   };
 }
 
+// src/server/converter/content-safety-guards.ts
+var SHRINKAGE_GUARD_MIN_OLD_LEN = 500;
+var SHRINKAGE_GUARD_MAX_RATIO = 0.5;
+var STRUCTURE_GUARD_MIN_OLD_HEADINGS = 3;
+var STRUCTURE_GUARD_MAX_RATIO = 0.5;
+var EMPTY_BODY_MIN_OLD_LEN = 500;
+var EMPTY_BODY_MIN_TEXT_LEN = 100;
+var HEADING_RE = /<h[1-6][^>]*>/gi;
+function countHeadings(storage) {
+  const cleaned = storage.replace(/<ac:plain-text-body>[\s\S]*?<\/ac:plain-text-body>/g, "").replace(/<!--[\s\S]*?-->/g, "");
+  return (cleaned.match(HEADING_RE) || []).length;
+}
+function extractTextContent(storage) {
+  return storage.replace(/<!--[\s\S]*?-->/g, "").replace(/<[^>]*>/g, "").replace(/&[a-zA-Z]+;/g, " ").replace(/&#x?[0-9a-fA-F]+;/g, " ").trim();
+}
+function enforceContentSafetyGuards(input) {
+  const { oldStorage, newStorage, confirmShrinkage, confirmStructureLoss } = input;
+  const oldLen = oldStorage.length;
+  const newLen = newStorage.length;
+  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.`,
+      SHRINKAGE_NOT_CONFIRMED
+    );
+  }
+  const oldHeadings = countHeadings(oldStorage);
+  const newHeadings = countHeadings(newStorage);
+  if (oldHeadings >= STRUCTURE_GUARD_MIN_OLD_HEADINGS && newHeadings < oldHeadings * STRUCTURE_GUARD_MAX_RATIO && !confirmStructureLoss) {
+    throw new ConverterError(
+      `Heading count would drop from ${oldHeadings} to ${newHeadings}. This may indicate accidental content loss. Re-submit with confirm_structure_loss: true to proceed.`,
+      STRUCTURE_LOSS_NOT_CONFIRMED
+    );
+  }
+  const textContent = extractTextContent(newStorage);
+  if (oldLen > EMPTY_BODY_MIN_OLD_LEN && textContent.length < EMPTY_BODY_MIN_TEXT_LEN) {
+    throw new ConverterError(
+      `New body contains only ${textContent.length} characters of text content (old body: ${oldLen} characters). This almost certainly indicates accidental content loss. To intentionally clear a page, use delete_page and re-create it.`,
+      EMPTY_BODY_REJECTED
+    );
+  }
+}
+
 // src/server/converter/storage-to-md.ts
 var import_turndown2 = __toESM(require_turndown_cjs());
 function makeTurndown() {
@@ -56713,6 +56797,73 @@ function storageToMarkdown(storage) {
   return { markdown, sidecar };
 }
 
+// src/server/mutation-log.ts
+var import_node_fs = require("node:fs");
+var import_node_path2 = require("node:path");
+var MAX_LOG_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+var MAX_ERROR_LEN = 200;
+var logPath = null;
+var logFd = null;
+function sanitizeErrorMessage(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  const firstLine = msg.split("\n")[0];
+  return firstLine.length > MAX_ERROR_LEN ? firstLine.slice(0, MAX_ERROR_LEN) + "..." : firstLine;
+}
+function sweepOldLogs(dir) {
+  try {
+    const now = Date.now();
+    for (const name of (0, import_node_fs.readdirSync)(dir)) {
+      if (!name.startsWith("mutations-") || !name.endsWith(".jsonl")) continue;
+      const filePath = (0, import_node_path2.join)(dir, name);
+      try {
+        const stat2 = (0, import_node_fs.statSync)(filePath);
+        if (now - stat2.mtimeMs > MAX_LOG_AGE_MS) {
+          (0, import_node_fs.unlinkSync)(filePath);
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+function initMutationLog(dir) {
+  if (!(0, import_node_fs.existsSync)(dir)) {
+    (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
+  } else {
+    const stat2 = (0, import_node_fs.lstatSync)(dir);
+    if (stat2.isSymbolicLink()) {
+      throw new Error(
+        `Mutation log directory ${dir} is a symlink \u2014 refusing to write. Remove the symlink and restart.`
+      );
+    }
+  }
+  sweepOldLogs(dir);
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  logPath = (0, import_node_path2.join)(dir, `mutations-${ts}.jsonl`);
+  try {
+    logFd = (0, import_node_fs.openSync)(logPath, "ax", 384);
+  } catch {
+    logFd = (0, import_node_fs.openSync)(logPath, "a", 384);
+  }
+}
+function logMutation(record2) {
+  if (logFd === null) return;
+  try {
+    const line = JSON.stringify(record2) + "\n";
+    (0, import_node_fs.writeSync)(logFd, line);
+  } catch {
+  }
+}
+function errorRecord(operation, pageId, err, extra) {
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    operation,
+    pageId,
+    error: sanitizeErrorMessage(err),
+    ...extra
+  };
+}
+
 // src/server/index.ts
 function escapeXml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
@@ -56845,6 +56996,38 @@ function registerTools(server, config3) {
     "Labels with the 'epimethian-' prefix are system-managed and cannot be modified directly"
   );
   const pageIdSchema = external_exports.string().regex(/^\d+$/, "Page ID must be numeric");
+  async function concatPageContent(page_id, version2, newContent, position, opts = {}) {
+    const currentPage = await getPage(page_id, true);
+    const currentStorage = currentPage.body?.storage?.value ?? currentPage.body?.value ?? "";
+    const isMarkdown = looksLikeMarkdown(newContent);
+    const contentStorage = isMarkdown ? markdownToStorage(newContent, {
+      allowRawHtml: opts.allowRawHtml,
+      confluenceBaseUrl: opts.confluenceBaseUrl
+    }) : newContent;
+    let sep;
+    if (opts.separator !== void 0) {
+      sep = opts.separator;
+    } else {
+      sep = isMarkdown ? "\n\n" : "";
+    }
+    if (sep.length > 100) {
+      throw new Error("separator must be 100 characters or fewer");
+    }
+    if (sep.includes("<")) {
+      throw new Error("separator must not contain XML/HTML tags (no '<' characters)");
+    }
+    if (currentStorage.length + contentStorage.length + sep.length > 2e6) {
+      throw new Error("Combined body exceeds 2MB limit");
+    }
+    const newBody = position === "prepend" ? contentStorage + sep + currentStorage : currentStorage + sep + contentStorage;
+    const { page, newVersion } = await updatePage(page_id, {
+      title: currentPage.title,
+      body: newBody,
+      version: version2,
+      versionMessage: opts.versionMessage
+    });
+    return { page, newVersion, oldLen: currentStorage.length, newLen: newBody.length };
+  }
   server.registerTool(
     "create_page",
     {
@@ -56878,11 +57061,20 @@ function registerTools(server, config3) {
         }
         const spaceId = await resolveSpaceId(space_key);
         const page = await createPage(spaceId, title, finalBody, parent_id);
+        logMutation({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          operation: "create_page",
+          pageId: page.id,
+          newVersion: page.version?.number ?? 1,
+          newBodyLen: finalBody.length
+        });
         return toolResult(await formatPage(page, false) + echo);
       } catch (err) {
         if (err instanceof ConverterError) {
+          logMutation(errorRecord("create_page", "unknown", err));
           return toolError(err);
         }
+        logMutation(errorRecord("create_page", "unknown", err));
         return toolError(err);
       }
     }
@@ -56977,7 +57169,7 @@ ${truncated}`);
     "update_page",
     {
       description: describeWithLock(
-        "Update an existing Confluence page. Accepts GFM markdown or Confluence storage format \u2014 markdown is automatically converted via the token-aware write path, which preserves all existing macros and rich elements. You must provide the version number from your most recent get_page call. If the page was modified by someone else since then, this will return a conflict error \u2014 re-read the page and retry.\n\nFor narrow changes to a single section, prefer update_page_section \u2014 it leaves the rest of the page untouched and is safer for targeted edits.\n\nMarkdown update flags:\n- confirm_deletions: set to true to acknowledge removing preserved macros/elements (default false \u2014 any deletion errors until confirmed).\n- replace_body: set to true for a wholesale rewrite that skips preservation (default false).\n- allow_raw_html: allow raw HTML inside markdown bodies (default false).\n- confluence_base_url: override the URL used by the link rewriter.",
+        "Update an existing Confluence page. Accepts GFM markdown or Confluence storage format \u2014 markdown is automatically converted via the token-aware write path, which preserves all existing macros and rich elements. You must provide the version number from your most recent get_page call. If the page was modified by someone else since then, this will return a conflict error \u2014 re-read the page and retry.\n\nFor narrow changes to a single section, prefer update_page_section \u2014 it leaves the rest of the page untouched and is safer for targeted edits.\n\nMarkdown update flags:\n- confirm_deletions: set to true to acknowledge removing preserved macros/elements (default false \u2014 any deletion errors until confirmed).\n- replace_body: set to true for a wholesale rewrite that skips preservation (default false).\n- confirm_shrinkage: set to true to acknowledge a >50% body size reduction (default false).\n- confirm_structure_loss: set to true to acknowledge a >50% heading count drop (default false).\n- allow_raw_html: allow raw HTML inside markdown bodies (default false).\n- confluence_base_url: override the URL used by the link rewriter.\n\nreplace_body skips all safety nets (token preservation, deletion confirmation). When delegating update_page to a subagent, ensure the agent includes the full existing body \u2014 replace_body replaces ALL content with only what you provide.",
         config3
       ),
       inputSchema: {
@@ -56988,19 +57180,27 @@ ${truncated}`);
         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 or rich elements. Required when any preserved element would be deleted."),
         replace_body: external_exports.boolean().default(false).describe("Set to true for a wholesale page rewrite that skips token preservation. All existing macros will be lost. Use only when intentionally replacing the full body."),
+        confirm_shrinkage: external_exports.boolean().default(false).describe(
+          "Set to true to acknowledge that the new body is significantly smaller than the existing body. Required when the body would shrink by more than 50%."
+        ),
+        confirm_structure_loss: external_exports.boolean().default(false).describe(
+          "Set to true to acknowledge that the new body has significantly fewer headings than the existing body. Required when heading count would drop by more than 50%."
+        ),
         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.")
       },
       annotations: { destructiveHint: false, idempotentHint: false }
     },
-    async ({ page_id, title, version: version2, body, version_message, confirm_deletions, replace_body, allow_raw_html, confluence_base_url }) => {
+    async ({ page_id, title, version: version2, body, version_message, confirm_deletions, replace_body, confirm_shrinkage, confirm_structure_loss, allow_raw_html, confluence_base_url }) => {
       const blocked = writeGuard("update_page", config3);
       if (blocked) return blocked;
       try {
+        const cfg = await getConfig();
+        const currentPage = await getPage(page_id, true);
+        const currentStorage = currentPage.body?.storage?.value ?? currentPage.body?.value ?? "";
+        let finalStorage;
+        let effectiveVersionMessage = version_message;
         if (body && looksLikeMarkdown(body)) {
-          const cfg = await getConfig();
-          const currentPage = await getPage(page_id, true);
-          const currentStorage = currentPage.body?.storage?.value ?? currentPage.body?.value ?? "";
           const plan = planUpdate({
             currentStorage,
             callerMarkdown: body,
@@ -57011,30 +57211,42 @@ ${truncated}`);
               confluenceBaseUrl: confluence_base_url ?? cfg.url
             }
           });
-          const effectiveVersionMessage = plan.versionMessage && version_message ? `${version_message}; ${plan.versionMessage}` : plan.versionMessage ?? version_message;
-          const { page: page2, newVersion: newVersion2 } = await updatePage(page_id, {
-            title,
-            body: plan.newStorage,
-            version: version2,
-            versionMessage: effectiveVersionMessage
-          });
-          return toolResult(
-            `Updated: ${page2.title} (ID: ${page2.id}, version: ${newVersion2})` + echo
-          );
+          finalStorage = plan.newStorage;
+          effectiveVersionMessage = plan.versionMessage && version_message ? `${version_message}; ${plan.versionMessage}` : plan.versionMessage ?? version_message;
+        } else {
+          finalStorage = body ?? "";
         }
+        enforceContentSafetyGuards({
+          oldStorage: currentStorage,
+          newStorage: finalStorage,
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss
+        });
         const { page, newVersion } = await updatePage(page_id, {
           title,
-          body,
+          body: finalStorage,
           version: version2,
-          versionMessage: version_message
+          versionMessage: effectiveVersionMessage,
+          previousBody: currentStorage
+        });
+        logMutation({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          operation: "update_page",
+          pageId: page_id,
+          oldVersion: version2,
+          newVersion,
+          oldBodyLen: currentStorage.length,
+          newBodyLen: finalStorage.length,
+          replaceBody: replace_body || void 0
         });
         return toolResult(
-          `Updated: ${page.title} (ID: ${page.id}, version: ${newVersion})` + echo
+          `Updated: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${currentStorage.length}\u2192${finalStorage.length} chars)` + echo
         );
       } catch (err) {
-        if (err instanceof ConverterError) {
-          return toolError(err);
-        }
+        logMutation(errorRecord("update_page", page_id, err, {
+          oldVersion: version2,
+          replaceBody: replace_body || void 0
+        }));
         return toolError(err);
       }
     }
@@ -57053,8 +57265,14 @@ ${truncated}`);
       if (blocked) return blocked;
       try {
         await deletePage(page_id);
+        logMutation({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          operation: "delete_page",
+          pageId: page_id
+        });
         return toolResult(`Deleted page ${page_id}` + echo);
       } catch (err) {
+        logMutation(errorRecord("delete_page", page_id, err));
         return toolError(err);
       }
     }
@@ -57091,12 +57309,99 @@ ${truncated}`);
           title: page.title,
           body: newFullBody,
           version: version2,
-          versionMessage: version_message
+          versionMessage: version_message,
+          previousBody: fullBody
+        });
+        logMutation({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          operation: "update_page",
+          pageId: page_id,
+          oldVersion: version2,
+          newVersion,
+          oldBodyLen: fullBody.length,
+          newBodyLen: newFullBody.length
         });
         return toolResult(
           `Updated section "${section}" in: ${updated.title} (ID: ${updated.id}, version: ${newVersion})` + echo
         );
       } catch (err) {
+        logMutation(errorRecord("update_page", page_id, err, { oldVersion: version2 }));
+        return toolError(err);
+      }
+    }
+  );
+  server.registerTool(
+    "prepend_to_page",
+    {
+      description: describeWithLock(
+        "Insert content at the beginning of an existing Confluence page. The caller provides only the new content \u2014 the server fetches the existing body and handles concatenation. Safer than update_page with replace_body for additive operations.\n\nContent can be GFM markdown or Confluence storage format (auto-detected).",
+        config3
+      ),
+      inputSchema: {
+        page_id: external_exports.string().describe("The Confluence page ID"),
+        version: external_exports.number().int().positive().describe("Page version from your most recent get_page call"),
+        content: external_exports.string().describe("Content to insert before the existing body. GFM markdown or storage format (auto-detected)."),
+        separator: external_exports.string().optional().describe("Separator between new and existing content. Max 100 chars, no XML tags. Defaults to blank line (markdown) or empty (storage)."),
+        version_message: external_exports.string().optional().describe("Optional version comment"),
+        allow_raw_html: external_exports.boolean().default(false).describe("Allow raw HTML inside markdown content (default false)."),
+        confluence_base_url: external_exports.string().url().optional().describe("Override the Confluence base URL used by the link rewriter.")
+      },
+      annotations: { destructiveHint: false, idempotentHint: false }
+    },
+    async ({ page_id, version: version2, content, separator, version_message, allow_raw_html, confluence_base_url }) => {
+      const blocked = writeGuard("prepend_to_page", config3);
+      if (blocked) return blocked;
+      try {
+        const cfg = await getConfig();
+        const { page, newVersion, oldLen, newLen } = await concatPageContent(
+          page_id,
+          version2,
+          content,
+          "prepend",
+          { separator, versionMessage: version_message ?? "Prepend content", allowRawHtml: allow_raw_html, confluenceBaseUrl: confluence_base_url ?? cfg.url }
+        );
+        logMutation({ timestamp: (/* @__PURE__ */ new Date()).toISOString(), operation: "prepend_to_page", pageId: page_id, oldVersion: version2, newVersion, oldBodyLen: oldLen, newBodyLen: newLen });
+        return toolResult(`Prepended to: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${oldLen}\u2192${newLen} chars)` + echo);
+      } catch (err) {
+        logMutation(errorRecord("prepend_to_page", page_id, err, { oldVersion: version2 }));
+        return toolError(err);
+      }
+    }
+  );
+  server.registerTool(
+    "append_to_page",
+    {
+      description: describeWithLock(
+        "Insert content at the end of an existing Confluence page. The caller provides only the new content \u2014 the server fetches the existing body and handles concatenation. Safer than update_page with replace_body for additive operations.\n\nContent can be GFM markdown or Confluence storage format (auto-detected).",
+        config3
+      ),
+      inputSchema: {
+        page_id: external_exports.string().describe("The Confluence page ID"),
+        version: external_exports.number().int().positive().describe("Page version from your most recent get_page call"),
+        content: external_exports.string().describe("Content to insert after the existing body. GFM markdown or storage format (auto-detected)."),
+        separator: external_exports.string().optional().describe("Separator between existing and new content. Max 100 chars, no XML tags. Defaults to blank line (markdown) or empty (storage)."),
+        version_message: external_exports.string().optional().describe("Optional version comment"),
+        allow_raw_html: external_exports.boolean().default(false).describe("Allow raw HTML inside markdown content (default false)."),
+        confluence_base_url: external_exports.string().url().optional().describe("Override the Confluence base URL used by the link rewriter.")
+      },
+      annotations: { destructiveHint: false, idempotentHint: false }
+    },
+    async ({ page_id, version: version2, content, separator, version_message, allow_raw_html, confluence_base_url }) => {
+      const blocked = writeGuard("append_to_page", config3);
+      if (blocked) return blocked;
+      try {
+        const cfg = await getConfig();
+        const { page, newVersion, oldLen, newLen } = await concatPageContent(
+          page_id,
+          version2,
+          content,
+          "append",
+          { separator, versionMessage: version_message ?? "Append content", allowRawHtml: allow_raw_html, confluenceBaseUrl: confluence_base_url ?? cfg.url }
+        );
+        logMutation({ timestamp: (/* @__PURE__ */ new Date()).toISOString(), operation: "append_to_page", pageId: page_id, oldVersion: version2, newVersion, oldBodyLen: oldLen, newBodyLen: newLen });
+        return toolResult(`Appended to: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${oldLen}\u2192${newLen} chars)` + echo);
+      } catch (err) {
+        logMutation(errorRecord("append_to_page", page_id, err, { oldVersion: version2 }));
         return toolError(err);
       }
     }
@@ -57327,7 +57632,7 @@ ${truncated}`);
       const blocked = writeGuard("add_attachment", config3);
       if (blocked) return blocked;
       try {
-        const resolved = await (0, import_promises2.realpath)((0, import_node_path2.resolve)(file_path));
+        const resolved = await (0, import_promises2.realpath)((0, import_node_path3.resolve)(file_path));
         const cwd = await (0, import_promises2.realpath)(process.cwd());
         if (!resolved.startsWith(cwd + "/") && resolved !== cwd) {
           return toolError(
@@ -57376,9 +57681,9 @@ ${truncated}`);
       if (blocked) return blocked;
       try {
         const filename = diagram_name.endsWith(".drawio") ? diagram_name : `${diagram_name}.drawio`;
-        const tmpDir = await (0, import_promises2.mkdtemp)((0, import_node_path2.join)((0, import_node_os2.tmpdir)(), "drawio-"));
+        const tmpDir = await (0, import_promises2.mkdtemp)((0, import_node_path3.join)((0, import_node_os2.tmpdir)(), "drawio-"));
         try {
-          const tmpPath = (0, import_node_path2.join)(tmpDir, filename);
+          const tmpPath = (0, import_node_path3.join)(tmpDir, filename);
           await (0, import_promises2.writeFile)(tmpPath, diagram_xml, "utf-8");
           const fileData = await (0, import_promises2.readFile)(tmpPath);
           await uploadAttachment(page_id, fileData, filename);
@@ -57763,7 +58068,7 @@ ${lines}`);
   server.registerTool(
     "get_page_version",
     {
-      description: "Get the content of a Confluence page at a specific historical version. Returns sanitized markdown (macros replaced with placeholders). Note: historical versions may contain content that was intentionally deleted. Costs 1 API call.",
+      description: "Get the content of a Confluence page at a specific historical version. Returns sanitized markdown (macros replaced with placeholders). Note: historical versions may contain content that was intentionally deleted. Costs 1 API call.\n\nReturns sanitized read-only markdown, NOT raw Confluence storage format. Macros are replaced with placeholders. This content is NOT suitable for round-trip updates via update_page \u2014 the conversion is lossy. To revert a page to a previous version, use revert_page instead.",
       inputSchema: {
         page_id: pageIdSchema.describe("Confluence page ID"),
         version: external_exports.number().int().min(1).describe("Version number to retrieve")
@@ -57868,6 +58173,89 @@ ${result.diff}${truncNote}` + echo
       }
     }
   );
+  server.registerTool(
+    "revert_page",
+    {
+      description: describeWithLock(
+        "Revert a Confluence page to a previous version. Fetches the exact storage-format body from the historical version and pushes it as a new version. This is a lossless revert \u2014 unlike reading get_page_version (which returns sanitized markdown) and passing it to update_page, this preserves all macros, formatting, and rich elements exactly.\n\nThe shrinkage guard applies: if the reverted content is significantly smaller than the current content, you will be asked to confirm.",
+        config3
+      ),
+      inputSchema: {
+        page_id: pageIdSchema.describe("The Confluence page ID"),
+        target_version: external_exports.number().int().positive().describe(
+          "The version number to revert to. Must be less than the current version."
+        ),
+        current_version: external_exports.number().int().positive().describe(
+          "The current page version from your most recent get_page call (for optimistic locking)."
+        ),
+        confirm_shrinkage: external_exports.boolean().default(false).describe(
+          "Set to true if the historical version is expected to be significantly smaller than the current version."
+        ),
+        confirm_structure_loss: external_exports.boolean().default(false).describe(
+          "Set to true if the historical version has fewer headings than the current version."
+        ),
+        version_message: external_exports.string().optional().describe(
+          "Optional version comment. Defaults to 'Revert to version N'."
+        )
+      },
+      annotations: { destructiveHint: false, idempotentHint: false }
+    },
+    async ({
+      page_id,
+      target_version,
+      current_version,
+      confirm_shrinkage,
+      confirm_structure_loss,
+      version_message
+    }) => {
+      const blocked = writeGuard("revert_page", config3);
+      if (blocked) return blocked;
+      try {
+        const currentPage = await getPage(page_id, true);
+        const currentStorage = currentPage.body?.storage?.value ?? currentPage.body?.value ?? "";
+        const actualVersion = currentPage.version?.number;
+        if (actualVersion !== void 0 && actualVersion !== current_version) {
+          return toolError(
+            new Error(
+              `Version mismatch: expected ${current_version}, but page is at version ${actualVersion}. Re-read the page with get_page and retry with the current version number.`
+            )
+          );
+        }
+        const historical = await getPageVersionBody(page_id, target_version);
+        enforceContentSafetyGuards({
+          oldStorage: currentStorage,
+          newStorage: historical.rawBody,
+          confirmShrinkage: confirm_shrinkage,
+          confirmStructureLoss: confirm_structure_loss
+        });
+        const { page, newVersion } = await updatePage(page_id, {
+          title: currentPage.title,
+          body: historical.rawBody,
+          version: current_version,
+          versionMessage: version_message ?? `Revert to version ${target_version}`
+        });
+        logMutation({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          operation: "revert_page",
+          pageId: page_id,
+          oldVersion: current_version,
+          newVersion,
+          oldBodyLen: currentStorage.length,
+          newBodyLen: historical.rawBody.length
+        });
+        return toolResult(
+          `Reverted: ${page.title} (ID: ${page.id}, v${target_version}\u2192v${newVersion}, body: ${currentStorage.length}\u2192${historical.rawBody.length} chars)` + echo
+        );
+      } catch (err) {
+        logMutation(
+          errorRecord("revert_page", page_id, err, {
+            oldVersion: current_version
+          })
+        );
+        return toolError(err);
+      }
+    }
+  );
   server.registerTool(
     "lookup_user",
     {
@@ -57935,16 +58323,20 @@ ${lines.join("\n")}${echo2}`
       description: "Return the epimethian-mcp server version.",
       inputSchema: {}
     },
-    async () => toolResult(`epimethian-mcp v${"5.0.0"}`)
+    async () => toolResult(`epimethian-mcp v${"5.1.0"}`)
   );
 }
 async function main() {
   const config3 = await getConfig();
   await validateStartup(config3);
+  if (process.env.EPIMETHIAN_MUTATION_LOG === "true") {
+    const logDir = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".epimethian", "logs");
+    initMutationLog(logDir);
+  }
   const serverName = config3.profile ? `confluence-${config3.profile}` : "confluence";
   const server = new McpServer({
     name: serverName,
-    version: "5.0.0"
+    version: "5.1.0"
   });
   registerTools(server, config3);
   const transport = new StdioServerTransport();