@de-otio/epimethian-mcp 6.0.1 → 6.1.0

package/dist/cli/index.js

@@ -28993,6 +28993,75 @@ var init_page_cache = __esm({
   }
 });
 
+// src/server/config.ts
+function resolvePosture(settings) {
+  if (settings?.posture) return settings.posture;
+  if (settings?.readOnly === true) return "read-only";
+  if (settings?.readOnly === false) return "read-write";
+  const envVal = process.env.CONFLUENCE_READ_ONLY;
+  if (envVal === "true") return "read-only";
+  if (envVal === "false") return "read-write";
+  return "detect";
+}
+function resolveUnverifiedStatusFlag(settings) {
+  if (settings?.unverifiedStatus !== void 0) return settings.unverifiedStatus;
+  if (process.env.CONFLUENCE_UNVERIFIED_STATUS === "false") return false;
+  if (process.env.CONFLUENCE_UNVERIFIED_STATUS === "true") return true;
+  return true;
+}
+function resolveEffectivePosture(configured, probed) {
+  if (configured === "read-only") {
+    return { effective: "read-only", source: "profile" };
+  }
+  if (configured === "read-write") {
+    if (probed === "read-only") {
+      return {
+        effective: "read-write",
+        source: "profile",
+        warning: "configured read-write but probe indicates token is read-only; writes will likely fail"
+      };
+    }
+    return { effective: "read-write", source: "profile" };
+  }
+  if (probed === "write") {
+    return { effective: "read-write", source: "probe" };
+  }
+  if (probed === "read-only") {
+    return { effective: "read-only", source: "probe" };
+  }
+  return {
+    effective: "read-write",
+    source: "default",
+    warning: "capability probe was inconclusive \u2014 defaulting to read-write"
+  };
+}
+function resolveUnverifiedStatusLocale(settings) {
+  if (settings?.unverifiedStatusLocale) return settings.unverifiedStatusLocale;
+  if (process.env.CONFLUENCE_UNVERIFIED_STATUS_LOCALE) {
+    return process.env.CONFLUENCE_UNVERIFIED_STATUS_LOCALE;
+  }
+  return void 0;
+}
+var ProfileSettingsValidator;
+var init_config = __esm({
+  "src/server/config.ts"() {
+    "use strict";
+    init_zod();
+    ProfileSettingsValidator = external_exports.object({
+      readOnly: external_exports.boolean().optional(),
+      posture: external_exports.enum(["read-only", "read-write", "detect"]).optional(),
+      attribution: external_exports.boolean().optional(),
+      unverifiedStatus: external_exports.boolean().optional(),
+      unverifiedStatusLocale: external_exports.string().optional(),
+      unverifiedStatusName: external_exports.string().max(20).optional(),
+      unverifiedStatusColor: external_exports.enum(["#FFC400", "#2684FF", "#57D9A3", "#FF7452", "#8777D9"]).optional(),
+      allowed_tools: external_exports.array(external_exports.string()).optional(),
+      denied_tools: external_exports.array(external_exports.string()).optional(),
+      spaces: external_exports.array(external_exports.string()).optional()
+    }).strict();
+  }
+});
+
 // node_modules/he/he.js
 var require_he = __commonJS({
   "node_modules/he/he.js"(exports2, module2) {
@@ -34945,6 +35014,67 @@ var require_dist2 = __commonJS({
 });
 
 // src/server/confluence-client.ts
+var confluence_client_exports = {};
+__export(confluence_client_exports, {
+  CommentSchema: () => CommentSchema,
+  ConfluenceApiError: () => ConfluenceApiError,
+  ConfluenceAuthError: () => ConfluenceAuthError,
+  ConfluenceConflictError: () => ConfluenceConflictError,
+  ConfluenceNotFoundError: () => ConfluenceNotFoundError,
+  ConfluencePermissionError: () => ConfluencePermissionError,
+  ContentStateSchema: () => ContentStateSchema,
+  LabelSchema: () => LabelSchema,
+  PageSchema: () => PageSchema,
+  ProfileNotConfiguredError: () => ProfileNotConfiguredError,
+  _rawCreatePage: () => _rawCreatePage,
+  _rawUpdatePage: () => _rawUpdatePage,
+  addLabels: () => addLabels,
+  createFooterComment: () => createFooterComment,
+  createInlineComment: () => createInlineComment,
+  deleteFooterComment: () => deleteFooterComment,
+  deleteInlineComment: () => deleteInlineComment,
+  deletePage: () => deletePage,
+  ensureAttributionLabel: () => ensureAttributionLabel,
+  extractHeadings: () => extractHeadings,
+  extractSection: () => extractSection,
+  extractSectionBody: () => extractSectionBody,
+  formatPage: () => formatPage,
+  getAttachments: () => getAttachments,
+  getCommentReplies: () => getCommentReplies,
+  getConfig: () => getConfig,
+  getContentState: () => getContentState,
+  getFooterComments: () => getFooterComments,
+  getInlineComments: () => getInlineComments,
+  getLabels: () => getLabels,
+  getPage: () => getPage,
+  getPageByTitle: () => getPageByTitle,
+  getPageChildren: () => getPageChildren,
+  getPageVersionBody: () => getPageVersionBody,
+  getPageVersions: () => getPageVersions,
+  getSpaces: () => getSpaces,
+  listPages: () => listPages,
+  looksLikeMarkdown: () => looksLikeMarkdown,
+  normalizeBodyForSubmit: () => normalizeBodyForSubmit,
+  probeWriteCapability: () => probeWriteCapability,
+  removeContentState: () => removeContentState,
+  removeLabel: () => removeLabel,
+  replaceSection: () => replaceSection,
+  resolveComment: () => resolveComment,
+  resolveCredentials: () => resolveCredentials,
+  resolveSpaceId: () => resolveSpaceId,
+  sanitizeCommentBody: () => sanitizeCommentBody,
+  sanitizeError: () => sanitizeError,
+  searchPages: () => searchPages,
+  searchPagesByTitle: () => searchPagesByTitle,
+  searchUsers: () => searchUsers,
+  setClientLabel: () => setClientLabel,
+  setContentState: () => setContentState,
+  toMarkdownView: () => toMarkdownView,
+  toStorageFormat: () => toStorageFormat,
+  truncateStorageFormat: () => truncateStorageFormat,
+  uploadAttachment: () => uploadAttachment,
+  validateStartup: () => validateStartup
+});
 function setClientLabel(label) {
   if (!label) {
     _clientLabel = void 0;
@@ -35004,8 +35134,13 @@ async function getConfig() {
   if (_config) return _config;
   const { url, email: email2, apiToken, profile, sealedCloudId, sealedDisplayName } = await resolveCredentials();
   const registrySettings = profile ? await getProfileSettings(profile) : void 0;
-  const readOnly = registrySettings?.readOnly === true || process.env.CONFLUENCE_READ_ONLY === "true";
+  const posture = resolvePosture(registrySettings);
+  const readOnly = posture === "read-only";
   const attribution = registrySettings?.attribution !== false && process.env.CONFLUENCE_ATTRIBUTION !== "false";
+  const unverifiedStatus = resolveUnverifiedStatusFlag(registrySettings);
+  const unverifiedStatusLocale = resolveUnverifiedStatusLocale(registrySettings);
+  const unverifiedStatusName = registrySettings?.unverifiedStatusName;
+  const unverifiedStatusColor = registrySettings?.unverifiedStatusColor;
   const authHeader = "Basic " + Buffer.from(`${email2}:${apiToken}`).toString("base64");
   const jsonHeaders = Object.freeze({
     Authorization: authHeader,
@@ -35016,16 +35151,83 @@ async function getConfig() {
     email: email2,
     profile,
     readOnly,
+    posture,
     attribution,
+    unverifiedStatus,
+    unverifiedStatusLocale,
+    unverifiedStatusName,
+    unverifiedStatusColor,
     apiV2: `${url}/wiki/api/v2`,
     apiV1: `${url}/wiki/rest/api`,
     authHeader,
     jsonHeaders,
     sealedCloudId,
-    sealedDisplayName
+    sealedDisplayName,
+    // Placeholders — overwritten by validateStartup() once the probe runs.
+    // Until then, treat as read-write to preserve existing behavior.
+    effectivePosture: posture === "read-only" ? "read-only" : "read-write",
+    probedCapability: null,
+    postureSource: "default"
   });
   return _config;
 }
+async function probeWriteCapability() {
+  const cfg = await getConfig();
+  try {
+    const spaces = await getSpaces(1);
+    if (spaces.length > 0) {
+      const spaceKey = spaces[0].key;
+      const permUrl = new URL(
+        `${cfg.apiV1}/user/current/permission/space/${encodeURIComponent(spaceKey)}`
+      );
+      permUrl.searchParams.set("operationKey", "create");
+      permUrl.searchParams.set("targetType", "page");
+      try {
+        const res = await confluenceRequest(permUrl.toString());
+        const raw = await res.json();
+        if (raw && typeof raw === "object") {
+          const obj = raw;
+          if (obj.havePermission === true) return "write";
+          if (obj.havePermission === false) return "read-only";
+          if (Array.isArray(obj.permissions)) {
+            const perms = obj.permissions;
+            const hasCreate = perms.some((p) => {
+              const op = p.operation;
+              return op?.operation === "create" && op?.targetType === "page";
+            });
+            return hasCreate ? "write" : "read-only";
+          }
+        }
+      } catch (permErr) {
+        if (permErr instanceof ConfluenceAuthError) throw permErr;
+        if (permErr instanceof ConfluenceNotFoundError) {
+        } else if (permErr instanceof ConfluencePermissionError) {
+          return "read-only";
+        }
+      }
+    }
+  } catch (spacesErr) {
+    if (spacesErr instanceof ConfluenceAuthError) throw spacesErr;
+  }
+  try {
+    await confluenceRequest(`${cfg.apiV2}/pages/999999999999`, {
+      method: "PUT",
+      body: JSON.stringify({})
+    });
+    return "write";
+  } catch (err) {
+    if (err instanceof ConfluenceAuthError) throw err;
+    if (err instanceof ConfluencePermissionError) return "read-only";
+    if (err instanceof ConfluenceNotFoundError) return "write";
+    if (err instanceof ConfluenceApiError && err.status >= 400 && err.status < 500) {
+      return "write";
+    }
+    console.error(
+      `epimethian-mcp: warning \u2014 write-capability probe failed with unexpected error: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return "inconclusive";
+  }
+}
 async function validateStartup(config3) {
   const { url, email: email2, profile } = config3;
   const decoded = Buffer.from(
@@ -35058,12 +35260,38 @@ Expected user: ${email2}
   if (profile) {
     await verifyOrSealTenant(config3, apiToken);
   }
+  const configuredPosture = config3.posture ?? "detect";
+  let probedCapability = null;
+  if (configuredPosture === "detect") {
+    try {
+      probedCapability = await probeWriteCapability();
+    } catch (err) {
+      console.error(
+        `epimethian-mcp: warning \u2014 write-capability probe threw unexpectedly: ${err instanceof Error ? err.message : String(err)}`
+      );
+      probedCapability = "inconclusive";
+    }
+  }
+  const resolved = resolveEffectivePosture(configuredPosture, probedCapability);
+  _config = Object.freeze({
+    ..._config,
+    effectivePosture: resolved.effective,
+    probedCapability,
+    postureSource: resolved.source
+  });
   const profileLabel = profile ? `profile: ${profile}` : "env-var mode";
   const readOnlyLabel = config3.readOnly ? ", READ-ONLY" : "";
   const attributionLabel = config3.attribution ? "" : ", NO-ATTRIBUTION";
   console.error(
     `epimethian-mcp: connected to ${url} as ${email2} (${profileLabel}${readOnlyLabel}${attributionLabel})`
   );
+  const modeLabel = resolved.effective === "read-only" ? "read-only" : "read-write";
+  console.error(
+    `[epimethian-mcp] Profile "${profile ?? "env-var"}" \u2014 mode: ${modeLabel} (source: ${resolved.source}).`
+  );
+  if (resolved.warning) {
+    console.error(`[epimethian-mcp] Warning: ${resolved.warning}`);
+  }
 }
 async function verifyOrSealTenant(config3, apiToken) {
   const { url, email: email2, profile, sealedCloudId, sealedDisplayName } = config3;
@@ -35138,7 +35366,15 @@ async function confluenceRequest(url, options2 = {}) {
   if (!res.ok) {
     const body = await res.text();
     console.error(`Confluence API error (${res.status}): ${sanitizeError(body)}`);
-    throw new ConfluenceApiError(res.status, body);
+    if (res.status === 401) {
+      throw new ConfluenceAuthError(res.status, body);
+    } else if (res.status === 403) {
+      throw new ConfluencePermissionError(res.status, body);
+    } else if (res.status === 404) {
+      throw new ConfluenceNotFoundError(res.status, body);
+    } else {
+      throw new ConfluenceApiError(res.status, body);
+    }
   }
   return res;
 }
@@ -35206,7 +35442,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.0.1"}`;
+  const epimethianTag = `Epimethian v${"6.1.0"}`;
   const versionMsg = cfg.attribution && clientLabel ? `Created by ${clientLabel} (via ${epimethianTag})` : `Created by ${epimethianTag}`;
   const payload = {
     title,
@@ -35222,16 +35458,12 @@ async function _rawCreatePage(spaceId, title, body, parentId, clientLabel) {
   const raw = await v2Post("/pages", payload);
   const page = PageSchema.parse(raw);
   pageCache.set(page.id, page.version?.number ?? 1, pageBody);
-  try {
-    await ensureAttributionLabel(page.id);
-  } catch {
-  }
   return page;
 }
 async function _rawUpdatePage(pageId, opts) {
   const cfg = await getConfig();
   const newVersion = opts.version + 1;
-  const epimethianTag = `Epimethian v${"6.0.1"}`;
+  const epimethianTag = `Epimethian v${"6.1.0"}`;
   const effectiveClient = cfg.attribution ? opts.clientLabel : void 0;
   let versionMessage;
   if (opts.versionMessage && effectiveClient)
@@ -35276,10 +35508,6 @@ async function _rawUpdatePage(pageId, opts) {
   if (pageBody !== void 0) {
     pageCache.set(pageId, newVersion, pageBody);
   }
-  try {
-    await ensureAttributionLabel(page.id);
-  } catch {
-  }
   return { page, newVersion };
 }
 async function deletePage(pageId, expectedVersion) {
@@ -35448,10 +35676,20 @@ async function uploadAttachment(pageId, fileData, filename, comment2) {
   return { title: att.title, id: att.id, fileSize: att.extensions?.fileSize };
 }
 async function ensureAttributionLabel(pageId) {
-  await addLabels(pageId, [ATTRIBUTION_LABEL]);
-  const labels = await getLabels(pageId);
-  if (labels.some((l) => l.name === LEGACY_ATTRIBUTION_LABEL)) {
-    await removeLabel(pageId, LEGACY_ATTRIBUTION_LABEL);
+  try {
+    await addLabels(pageId, [ATTRIBUTION_LABEL]);
+    const labels = await getLabels(pageId);
+    if (labels.some((l) => l.name === LEGACY_ATTRIBUTION_LABEL)) {
+      await removeLabel(pageId, LEGACY_ATTRIBUTION_LABEL);
+    }
+    return {};
+  } catch (err) {
+    if (err instanceof ConfluencePermissionError) {
+      return {
+        warning: `Could not apply 'epimethian-edited' label (permission denied). Provenance label is missing for page ${pageId}.`
+      };
+    }
+    throw err;
   }
 }
 function stripAttributionFooter(body) {
@@ -35908,7 +36146,7 @@ async function formatPage(page, optionsOrIncludeBody) {
   }
   return lines.join("\n");
 }
-var import_turndown, CLIENT_LABEL_DISALLOWED_RE, _clientLabel, _config, ProfileNotConfiguredError, PageSchema, PagesResultSchema, SpaceSchema, SpacesResultSchema, AttachmentSchema, AttachmentsResultSchema, LabelSchema, LabelsResultSchema, ContentStateSchema, CommentSchema, CommentsResultSchema, UploadResultSchema, VersionMetadataSchema, VersionsResultSchema, V1PageVersionSchema, ConfluenceApiError, ConfluenceConflictError, UserSchema, UserSearchResultSchema, ATTRIBUTION_LABEL, LEGACY_ATTRIBUTION_LABEL, DANGEROUS_TAG_RE, HTML_TAG_RE, HTML_ENTITY_RE, SAFE_MACRO_PARAMS;
+var import_turndown, CLIENT_LABEL_DISALLOWED_RE, _clientLabel, _config, ProfileNotConfiguredError, PageSchema, PagesResultSchema, SpaceSchema, SpacesResultSchema, AttachmentSchema, AttachmentsResultSchema, LabelSchema, LabelsResultSchema, ContentStateSchema, CommentSchema, CommentsResultSchema, UploadResultSchema, VersionMetadataSchema, VersionsResultSchema, V1PageVersionSchema, ConfluenceApiError, ConfluenceAuthError, ConfluencePermissionError, ConfluenceNotFoundError, ConfluenceConflictError, UserSchema, UserSearchResultSchema, ATTRIBUTION_LABEL, LEGACY_ATTRIBUTION_LABEL, DANGEROUS_TAG_RE, HTML_TAG_RE, HTML_ENTITY_RE, SAFE_MACRO_PARAMS;
 var init_confluence_client = __esm({
   "src/server/confluence-client.ts"() {
     "use strict";
@@ -35920,6 +36158,7 @@ var init_confluence_client = __esm({
     init_escape();
     init_untrusted_fence();
     init_page_cache();
+    init_config();
     CLIENT_LABEL_DISALLOWED_RE = /[^A-Za-z0-9 _./()\-]/g;
     _config = null;
     ProfileNotConfiguredError = class extends Error {
@@ -36039,6 +36278,12 @@ var init_confluence_client = __esm({
         this.status = status;
       }
     };
+    ConfluenceAuthError = class extends ConfluenceApiError {
+    };
+    ConfluencePermissionError = class extends ConfluenceApiError {
+    };
+    ConfluenceNotFoundError = class extends ConfluenceApiError {
+    };
     ConfluenceConflictError = class extends Error {
       constructor(pageId) {
         super(
@@ -47375,6 +47620,62 @@ var init_safe_write = __esm({
   }
 });
 
+// src/server/check-permissions.ts
+var check_permissions_exports = {};
+__export(check_permissions_exports, {
+  buildCheckPermissionsPayload: () => buildCheckPermissionsPayload
+});
+function buildCheckPermissionsPayload(config3) {
+  const effective = config3.effectivePosture ?? "read-write";
+  const configured = config3.posture ?? config3.effectivePosture ?? "read-write";
+  const source = config3.postureSource ?? "default";
+  let writePages;
+  if (config3.probedCapability === "write") {
+    writePages = true;
+  } else if (config3.probedCapability === "read-only") {
+    writePages = false;
+  } else {
+    writePages = "unknown";
+  }
+  const notes = [];
+  if (effective === "read-only" && writePages === true) {
+    notes.push(
+      "This profile is pinned to read-only mode by user configuration. The underlying token has write access, but write tools are not exposed to the agent."
+    );
+  } else if (effective === "read-only" && writePages === false) {
+    notes.push("Both the profile and the token are read-only. Write tools are not exposed.");
+  } else if (effective === "read-write" && writePages === false) {
+    notes.push(
+      "WARNING: this profile is configured read-write but the token does not appear to have write access. Writes will likely fail."
+    );
+  }
+  return {
+    profile: config3.profile,
+    user: { email: config3.email },
+    posture: {
+      effective,
+      configured,
+      source
+    },
+    tokenCapability: {
+      authenticated: true,
+      listSpaces: true,
+      readPages: true,
+      writePages,
+      addLabels: "unknown",
+      setContentState: "unknown",
+      addAttachments: "unknown",
+      addComments: "unknown"
+    },
+    notes
+  };
+}
+var init_check_permissions = __esm({
+  "src/server/check-permissions.ts"() {
+    "use strict";
+  }
+});
+
 // src/shared/update-check.ts
 function parseSemVer(version2) {
   const match2 = version2.match(/^(\d+)\.(\d+)\.(\d+)$/);
@@ -47727,23 +48028,39 @@ Profile will be saved without a tenant seal. Cross-tenant verification at startu
     );
     if (profile) {
       await addToProfileRegistry(profile);
-      const args = process.argv.slice(2);
-      const explicitReadWrite = args.includes("--read-write");
-      let enableWrites = explicitReadWrite;
-      if (!explicitReadWrite && !args.includes("--read-only")) {
-        const rl2 = readline.createInterface({ input: import_node_process2.stdin, output: import_node_process2.stdout });
-        try {
-          const answer = await rl2.question("Enable writes for this profile? [y/N] ");
-          enableWrites = answer.trim().toLowerCase() === "y";
-        } finally {
-          rl2.close();
+      const rl2 = readline.createInterface({ input: import_node_process2.stdin, output: import_node_process2.stdout });
+      try {
+        let posture = "read-only";
+        let validInput = false;
+        while (!validInput) {
+          const answer = (await rl2.question(
+            `MCP access mode for this profile:
+  [1] Read-only \u2014 the agent cannot modify Confluence through this profile,
+                  regardless of what the API token can do. Recommended for
+                  untrusted agents, exploratory work, and defense-in-depth.
+  [2] Read-write \u2014 the agent can create, update, and delete pages.
+  [3] Detect at startup \u2014 infer from the token's actual permissions.
+Your choice [default: 1]: `
+          )).trim();
+          if (answer === "" || answer === "1") {
+            posture = "read-only";
+            validInput = true;
+          } else if (answer === "2") {
+            posture = "read-write";
+            validInput = true;
+          } else if (answer === "3") {
+            posture = "detect";
+            validInput = true;
+          } else {
+            console.log(`Invalid choice "${answer}". Please enter 1, 2, or 3.`);
+          }
         }
-      }
-      const readOnly = !enableWrites;
-      await setProfileSettings(profile, { readOnly });
-      const modeLabel = readOnly ? "read-only" : "read-write";
-      console.log(`Credentials saved to OS keychain (profile: ${profile}, ${modeLabel}).
+        await setProfileSettings(profile, { posture });
+        console.log(`Credentials saved to OS keychain (profile: ${profile}, posture: ${posture}).
 `);
+      } finally {
+        rl2.close();
+      }
     } else {
       console.log("Credentials saved to OS keychain.\n");
       console.log(
@@ -48012,6 +48329,41 @@ var init_status = __esm({
   }
 });
 
+// src/cli/permissions.ts
+var permissions_exports = {};
+__export(permissions_exports, {
+  runPermissions: () => runPermissions
+});
+async function runPermissions(profileArg) {
+  const profile = profileArg || process.env.CONFLUENCE_PROFILE;
+  if (!profile) {
+    console.error(
+      "Usage: epimethian-mcp permissions <profile>\nOr set CONFLUENCE_PROFILE in the environment."
+    );
+    process.exit(1);
+  }
+  if (!PROFILE_NAME_RE.test(profile)) {
+    console.error(
+      `Invalid profile name: "${profile}". Use lowercase alphanumeric and hyphens only (1-63 chars).`
+    );
+    process.exit(1);
+  }
+  process.env.CONFLUENCE_PROFILE = profile;
+  const { getConfig: getConfig2, validateStartup: validateStartup2 } = await Promise.resolve().then(() => (init_confluence_client(), confluence_client_exports));
+  const { buildCheckPermissionsPayload: buildCheckPermissionsPayload2 } = await Promise.resolve().then(() => (init_check_permissions(), check_permissions_exports));
+  const config3 = await getConfig2();
+  await validateStartup2(config3);
+  const resolved = await getConfig2();
+  const payload = buildCheckPermissionsPayload2(resolved);
+  console.log(JSON.stringify(payload, null, 2));
+}
+var init_permissions = __esm({
+  "src/cli/permissions.ts"() {
+    "use strict";
+    init_keychain();
+  }
+});
+
 // src/cli/fix-legacy-links.ts
 var fix_legacy_links_exports = {};
 __export(fix_legacy_links_exports, {
@@ -48324,7 +48676,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\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 (33)\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 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\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 (34)\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 |\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';
   }
 });
 
@@ -48349,7 +48701,7 @@ __export(upgrade_exports, {
   runUpgrade: () => runUpgrade
 });
 async function runUpgrade() {
-  const currentVersion = "6.0.1";
+  const currentVersion = "6.1.0";
   console.log(`epimethian-mcp upgrade: current version v${currentVersion}`);
   let pending = await getPendingUpdate();
   if (!pending) {
@@ -59162,6 +59514,81 @@ function storageToMarkdown(storage) {
 
 // src/server/index.ts
 init_mutation_log();
+
+// src/server/provenance.ts
+init_confluence_client();
+var UNVERIFIED_COLOR = "#FFC400";
+var UNVERIFIED_LABELS = {
+  en: "AI-edited",
+  fr: "Modifi\xE9 par IA",
+  de: "KI-bearbeitet",
+  es: "Editado por IA",
+  pt: "Editado por IA",
+  it: "Modificato da IA",
+  nl: "AI-bewerkt",
+  ja: "AI\u7DE8\u96C6\u6E08\u307F",
+  zh: "AI\u5DF2\u7F16\u8F91",
+  ko: "AI \uD3B8\uC9D1\uB428"
+};
+for (const [locale, label] of Object.entries(UNVERIFIED_LABELS)) {
+  const codePoints = [...label].length;
+  if (codePoints > 20) {
+    throw new Error(
+      `UNVERIFIED_LABELS["${locale}"] = "${label}" has ${codePoints} code points, exceeding the 20-code-point Confluence limit.`
+    );
+  }
+}
+var KNOWN_LABELS = new Set(Object.values(UNVERIFIED_LABELS));
+function isKnownUnverifiedLabel(name, customOverride) {
+  if (customOverride !== void 0 && name === customOverride) return true;
+  return KNOWN_LABELS.has(name);
+}
+function pickLocale(cfg) {
+  const raw = cfg.unverifiedStatusLocale || process.env.CONFLUENCE_UNVERIFIED_STATUS_LOCALE || Intl.DateTimeFormat().resolvedOptions().locale || "en";
+  return raw.split("-")[0].toLowerCase();
+}
+function resolveUnverifiedStatus(cfg) {
+  const color = cfg.unverifiedStatusColor ?? UNVERIFIED_COLOR;
+  if (cfg.unverifiedStatusName) {
+    return { name: cfg.unverifiedStatusName, color };
+  }
+  const locale = pickLocale(cfg);
+  const name = UNVERIFIED_LABELS[locale] ?? UNVERIFIED_LABELS["en"];
+  return { name, color };
+}
+async function markPageUnverified(pageId, cfg) {
+  if (cfg.unverifiedStatus === false) {
+    return {};
+  }
+  const target = resolveUnverifiedStatus(cfg);
+  let skipSet = false;
+  try {
+    const current = await getContentState(pageId);
+    if (current != null && current.color === target.color && isKnownUnverifiedLabel(current.name, cfg.unverifiedStatusName)) {
+      return {};
+    }
+  } catch (err) {
+    if (err instanceof ConfluencePermissionError) {
+    }
+  }
+  if (skipSet) return {};
+  try {
+    await setContentState(pageId, target.name, target.color);
+    return {};
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ConfluencePermissionError) {
+      return {
+        warning: `Could not apply 'AI-edited' status badge (permission denied). Provenance badge is missing for page ${pageId}.`
+      };
+    }
+    return {
+      warning: `Could not apply 'AI-edited' status badge: ${message}. Provenance badge is missing for page ${pageId}.`
+    };
+  }
+}
+
+// src/server/index.ts
 init_safe_write();
 
 // src/server/source-provenance.ts
@@ -59427,6 +59854,7 @@ async function assertSpaceAllowed(opts) {
 }
 
 // src/server/index.ts
+init_check_permissions();
 init_update_check();
 function getClientLabel(server) {
   const client = server.server.getClientVersion();
@@ -59481,7 +59909,16 @@ ${markdown}`;
 
 ${body}`;
 }
+var _sessionIsReadOnly = false;
+var _readOnlyNoteEmitted = false;
 function toolResult(text2) {
+  if (_sessionIsReadOnly && !_readOnlyNoteEmitted) {
+    _readOnlyNoteEmitted = true;
+    const note = "[epimethian-mcp] This profile is read-only; write tools are not exposed.";
+    return { content: [{ type: "text", text: `${note}
+
+${text2}` }] };
+  }
   return { content: [{ type: "text", text: text2 }] };
 }
 function toolError(err) {
@@ -59489,6 +59926,42 @@ function toolError(err) {
   const message = sanitizeError(raw);
   return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
 }
+function toolErrorWithContext(err, ctx) {
+  if (err instanceof ConfluenceAuthError) {
+    const profileName = ctx.profile ?? "<profile>";
+    return {
+      content: [{
+        type: "text",
+        text: `Error: Your Confluence API token is invalid or expired. Reauthenticate with 'epimethian-mcp login ${profileName}'.`
+      }],
+      isError: true
+    };
+  }
+  if (err instanceof ConfluencePermissionError) {
+    const resourcePart = ctx.resource ? ` on ${ctx.resource}` : "";
+    return {
+      content: [{
+        type: "text",
+        text: `Error: Your token lacks permission for ${ctx.operation}${resourcePart}. The operation was not performed.`
+      }],
+      isError: true
+    };
+  }
+  if (err instanceof ConfluenceNotFoundError) {
+    return {
+      content: [{
+        type: "text",
+        text: `Error: Resource not found. Confluence may return 'not found' when a token lacks permission to see the resource \u2014 verify the token has at least read access.`
+      }],
+      isError: true
+    };
+  }
+  return toolError(err);
+}
+function appendWarnings(primary, warnings) {
+  if (warnings.length === 0) return primary;
+  return primary + "\n\n" + warnings.map((w) => `\u26A0 ${w}`).join("\n");
+}
 function tenantEcho(config3) {
   const host = new URL(config3.url).hostname;
   const mode = config3.profile ? `profile: ${config3.profile}` : "env-var mode";
@@ -59517,6 +59990,24 @@ var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
   "lookup_user",
   "resolve_page_link"
 ]);
+var WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "create_page",
+  "update_page",
+  "append_to_page",
+  "prepend_to_page",
+  "update_page_section",
+  "delete_page",
+  "add_drawio_diagram",
+  "revert_page",
+  "add_attachment",
+  "add_label",
+  "remove_label",
+  "create_comment",
+  "delete_comment",
+  "resolve_comment",
+  "set_page_status",
+  "remove_page_status"
+]);
 function writeGuard(toolName, config3) {
   if (!config3.readOnly) return null;
   if (READ_ONLY_TOOLS.has(toolName)) return null;
@@ -59575,27 +60066,38 @@ function formatComments(footer, inline2, pageId) {
   }
   return lines.join("\n");
 }
-function formatCommentThreads(footer, inline2, pageId) {
+function formatCommentThreads(footer, inline2, pageId, failedFetches = 0, totalFetches = 0) {
   const lines = [`Comments on page ${pageId}:`, ""];
   if (footer.length > 0) {
     lines.push(`Footer comments (${footer.length}):`);
-    footer.forEach(({ comment: comment2, replies }) => {
+    footer.forEach(({ comment: comment2, replies, error: error2 }) => {
       lines.push(formatCommentLine(comment2));
-      replies.forEach((r) => lines.push(formatCommentLine(r, "  ")));
+      if (error2) {
+        lines.push(`  Error fetching replies: ${error2}`);
+      } else if (replies) {
+        replies.forEach((r) => lines.push(formatCommentLine(r, "  ")));
+      }
     });
     lines.push("");
   }
   if (inline2.length > 0) {
     lines.push(`Inline comments (${inline2.length}):`);
-    inline2.forEach(({ comment: comment2, replies }) => {
+    inline2.forEach(({ comment: comment2, replies, error: error2 }) => {
       lines.push(formatCommentLine(comment2));
-      replies.forEach((r) => lines.push(formatCommentLine(r, "  ")));
+      if (error2) {
+        lines.push(`  Error fetching replies: ${error2}`);
+      } else if (replies) {
+        replies.forEach((r) => lines.push(formatCommentLine(r, "  ")));
+      }
     });
     lines.push("");
   }
   if (footer.length === 0 && inline2.length === 0) {
     lines.push("No comments found.");
   }
+  if (failedFetches > 0 && totalFetches > 0) {
+    lines.push(`Note: ${failedFetches} of ${totalFetches} reply fetches failed \u2014 partial results shown.`);
+  }
   return lines.join("\n");
 }
 async function registerTools(server, config3) {
@@ -59604,11 +60106,30 @@ async function registerTools(server, config3) {
   const isToolEnabled = resolveToolFilter(settings);
   const allowedSpaces = settings?.spaces;
   const checkSpaceAllowed = (opts) => assertSpaceAllowed({ spaces: allowedSpaces, ...opts });
+  const effectivePosture = config3.effectivePosture ?? "read-write";
+  const isReadOnly = effectivePosture === "read-only";
+  const profileLabel = config3.profile ? `"${config3.profile}"` : `"env-var"`;
+  const sourceLabel = config3.postureSource ?? "default";
+  if (isReadOnly) {
+    console.error(
+      `[epimethian-mcp] Profile ${profileLabel} \u2014 mode: read-only (${sourceLabel}).
+  Write tools are not exposed. Set posture: "read-write" in the profile to enable writes.`
+    );
+  } else {
+    console.error(
+      `[epimethian-mcp] Profile ${profileLabel} \u2014 mode: read-write (${sourceLabel}).`
+    );
+  }
+  _sessionIsReadOnly = isReadOnly;
+  _readOnlyNoteEmitted = false;
   const originalRegisterTool = server.registerTool.bind(server);
   server.registerTool = function(name, ...rest) {
     if (!isToolEnabled(name)) {
       return server;
     }
+    if (isReadOnly && WRITE_TOOLS.has(name)) {
+      return server;
+    }
     return originalRegisterTool(name, ...rest);
   };
   const labelNameSchema = external_exports.string().min(1).max(255).regex(/^[a-z0-9][a-z0-9_-]*$/, "Label must be lowercase alphanumeric, hyphens, underscores only");
@@ -59698,9 +60219,14 @@ async function registerTools(server, config3) {
           deletedTokens: prepared.deletedTokens,
           clientLabel: getClientLabel(server)
         });
-        return toolResult(await formatPage(submitted.page, false) + echo);
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(submitted.page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        const badgeResult = await markPageUnverified(submitted.page.id, cfg);
+        if (badgeResult.warning) warnings.push(badgeResult.warning);
+        return toolResult(appendWarnings(await formatPage(submitted.page, false), warnings) + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "create_page", resource: `space ${space_key}`, profile: config3.profile });
       }
     }
   );
@@ -59895,17 +60421,22 @@ ${truncated}${truncationNote(origLen)}`
           source: effectiveSource
         });
         const isTitleOnly = prepared.finalStorage === void 0;
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(submitted.page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        const badgeResult = await markPageUnverified(submitted.page.id, cfg);
+        if (badgeResult.warning) warnings.push(badgeResult.warning);
         if (isTitleOnly) {
           return toolResult(
-            `Updated: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, title only, body unchanged)` + echo
+            appendWarnings(`Updated: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, title only, body unchanged)`, warnings) + echo
           );
         }
         const removalNote = submitted.deletedTokens.length > 0 ? `; removed ${submitted.deletedTokens.length} preserved macro${submitted.deletedTokens.length === 1 ? "" : "s"}: ${submitted.deletedTokens.map((t) => t.fingerprint).join(", ")}` : "";
         return toolResult(
-          `Updated: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, body: ${submitted.oldLen}\u2192${submitted.newLen} chars${removalNote})` + echo
+          appendWarnings(`Updated: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}, body: ${submitted.oldLen}\u2192${submitted.newLen} chars${removalNote})`, warnings) + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "update_page", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -59967,7 +60498,7 @@ ${truncated}${truncationNote(origLen)}`
         return toolResult(`Deleted page ${page_id}` + echo);
       } catch (err) {
         logMutation(errorRecord("delete_page", page_id, err));
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "delete_page", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60033,12 +60564,17 @@ ${truncated}${truncationNote(origLen)}`
           operation: "update_page_section",
           clientLabel: getClientLabel(server)
         });
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(submitted.page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        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(", ")}` : "";
         return toolResult(
-          `Updated section "${section}" in: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}${removalNote})` + echo
+          appendWarnings(`Updated section "${section}" in: ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion}${removalNote})`, warnings) + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "update_page_section", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60075,9 +60611,14 @@ ${truncated}${truncationNote(origLen)}`
           "prepend",
           { separator, versionMessage: version_message ?? "Prepend content", allowRawHtml: allow_raw_html, confluenceBaseUrl: confluence_base_url ?? cfg.url }
         );
-        return toolResult(`Prepended to: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${oldLen}\u2192${newLen} chars)` + echo);
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        const badgeResult = await markPageUnverified(page.id, cfg);
+        if (badgeResult.warning) warnings.push(badgeResult.warning);
+        return toolResult(appendWarnings(`Prepended to: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${oldLen}\u2192${newLen} chars)`, warnings) + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "prepend_to_page", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60114,9 +60655,14 @@ ${truncated}${truncationNote(origLen)}`
           "append",
           { separator, versionMessage: version_message ?? "Append content", allowRawHtml: allow_raw_html, confluenceBaseUrl: confluence_base_url ?? cfg.url }
         );
-        return toolResult(`Appended to: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${oldLen}\u2192${newLen} chars)` + echo);
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        const badgeResult = await markPageUnverified(page.id, cfg);
+        if (badgeResult.warning) warnings.push(badgeResult.warning);
+        return toolResult(appendWarnings(`Appended to: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${oldLen}\u2192${newLen} chars)`, warnings) + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "append_to_page", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60239,6 +60785,23 @@ ${truncated}${truncationNote(origLen)}`
       }
     }
   );
+  server.registerTool(
+    "check_permissions",
+    {
+      description: "Report the current profile's MCP access mode and the token's capabilities. Always available in every posture.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      try {
+        const cfg = await getConfig();
+        const payload = buildCheckPermissionsPayload(cfg);
+        return toolResult(JSON.stringify(payload, null, 2));
+      } catch (err) {
+        return toolError(err);
+      }
+    }
+  );
   server.registerTool(
     "get_page_by_title",
     {
@@ -60374,7 +60937,7 @@ ${truncated}`);
           `Attached: ${att.title} (ID: ${att.id}, size: ${att.fileSize ?? "unknown"} bytes) to page ${page_id}` + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "add_attachment", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60458,11 +61021,16 @@ ${macro}` : macro;
           clientLabel: getClientLabel(server),
           operation: "add_drawio_diagram"
         });
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(submitted.page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        const badgeResult = await markPageUnverified(submitted.page.id, config3);
+        if (badgeResult.warning) warnings.push(badgeResult.warning);
         return toolResult(
-          `Diagram "${filename}" added to page ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion})` + echo
+          appendWarnings(`Diagram "${filename}" added to page ${submitted.page.title} (ID: ${submitted.page.id}, version: ${submitted.newVersion})`, warnings) + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "add_drawio_diagram", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60543,7 +61111,7 @@ ${lines}`);
         await addLabels(page_id, labels);
         return toolResult(`Added ${labels.length} label(s) to page ${page_id}: ${labels.join(", ")}` + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "add_label", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60568,7 +61136,7 @@ ${lines}`);
         await removeLabel(page_id, label);
         return toolResult(`Removed label "${label}" from page ${page_id}` + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "remove_label", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60641,7 +61209,7 @@ Color: ${state.color}` + echo
         await setContentState(page_id, name, color);
         return toolResult(`Set status on page ${page_id}: "${name}" (${color})` + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "set_page_status", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60667,7 +61235,7 @@ Color: ${state.color}` + echo
         await removeContentState(page_id);
         return toolResult(`Removed status from page ${page_id}` + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "remove_page_status", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60692,17 +61260,34 @@ Color: ${state.color}` + echo
           type !== "footer" ? getInlineComments(page_id, resolution_status) : Promise.resolve([])
         ]);
         if (include_replies) {
-          const [fr, ir] = await Promise.all([
-            Promise.all(footerComments.map(async (c) => ({
+          const footerRepliesResults = await Promise.allSettled(
+            footerComments.map((c) => getCommentReplies(c.id, "footer"))
+          );
+          const inlineRepliesResults = await Promise.allSettled(
+            inlineComments.map((c) => getCommentReplies(c.id, "inline"))
+          );
+          const fr = footerComments.map((c, i) => {
+            const result = footerRepliesResults[i];
+            return {
               comment: c,
-              replies: await getCommentReplies(c.id, "footer")
-            }))),
-            Promise.all(inlineComments.map(async (c) => ({
+              ...result.status === "fulfilled" ? { replies: result.value } : { error: result.reason instanceof Error ? result.reason.message : String(result.reason) }
+            };
+          });
+          const ir = inlineComments.map((c, i) => {
+            const result = inlineRepliesResults[i];
+            return {
               comment: c,
-              replies: await getCommentReplies(c.id, "inline")
-            })))
-          ]);
-          return toolResult(formatCommentThreads(fr, ir, page_id));
+              ...result.status === "fulfilled" ? { replies: result.value } : { error: result.reason instanceof Error ? result.reason.message : String(result.reason) }
+            };
+          });
+          const totalFetches = footerRepliesResults.length + inlineRepliesResults.length;
+          const failedFetches = [
+            ...footerRepliesResults,
+            ...inlineRepliesResults
+          ].filter((r) => r.status === "rejected").length;
+          return toolResult(
+            formatCommentThreads(fr, ir, page_id, failedFetches, totalFetches)
+          );
         }
         return toolResult(formatComments(footerComments, inlineComments, page_id));
       } catch (err) {
@@ -60756,7 +61341,7 @@ Color: ${state.color}` + echo
           `Created ${type} comment ${comment2.id} on page ${page_id}` + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "create_comment", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -60785,7 +61370,7 @@ Color: ${state.color}` + echo
           `Comment ${comment_id} ${state} (version: ${comment2.version?.number ?? "??"})` + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "resolve_comment", resource: `comment ${comment_id}`, profile: config3.profile });
       }
     }
   );
@@ -60815,7 +61400,7 @@ Color: ${state.color}` + echo
         }
         return toolResult(`Deleted ${type} comment ${comment_id}` + echo);
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "delete_comment", resource: `comment ${comment_id}`, profile: config3.profile });
       }
     }
   );
@@ -61098,11 +61683,19 @@ ${sectionFenced}`
           // E2: thread validated source for the mutation log.
           source: effectiveSource
         });
+        const warnings = [];
+        const labelResult = await ensureAttributionLabel(submitted.page.id);
+        if (labelResult.warning) warnings.push(labelResult.warning);
+        const badgeResult = await markPageUnverified(submitted.page.id, config3);
+        if (badgeResult.warning) warnings.push(badgeResult.warning);
         return toolResult(
-          `Reverted: ${submitted.page.title} (ID: ${submitted.page.id}, v${target_version}\u2192v${submitted.newVersion}, body: ${submitted.oldLen}\u2192${submitted.newLen} chars)` + echo
+          appendWarnings(
+            `Reverted: ${submitted.page.title} (ID: ${submitted.page.id}, v${target_version}\u2192v${submitted.newVersion}, body: ${submitted.oldLen}\u2192${submitted.newLen} chars)`,
+            warnings
+          ) + echo
         );
       } catch (err) {
-        return toolError(err);
+        return toolErrorWithContext(err, { operation: "revert_page", resource: `page ${page_id}`, profile: config3.profile });
       }
     }
   );
@@ -61191,7 +61784,7 @@ ${titleFenced}${echo2}`
       inputSchema: {}
     },
     async () => {
-      let text2 = `epimethian-mcp v${"6.0.1"}`;
+      let text2 = `epimethian-mcp v${"6.1.0"}`;
       try {
         const pending = await getPendingUpdate();
         if (pending) {
@@ -61222,7 +61815,7 @@ ${label} update available: v${pending.current} \u2192 v${pending.latest}. Run \`
         const pending = await getPendingUpdate();
         if (!pending) {
           return toolResult(
-            `epimethian-mcp v${"6.0.1"} is already up to date.`
+            `epimethian-mcp v${"6.1.0"} is already up to date.`
           );
         }
         const output = await performUpgrade(pending.latest);
@@ -61244,7 +61837,7 @@ async function startRecoveryServer(profile) {
   const server = new McpServer(
     {
       name: `confluence-${profile}-setup-needed`,
-      version: "6.0.1"
+      version: "6.1.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.`
@@ -61295,21 +61888,21 @@ async function main() {
   const serverName = config3.profile ? `confluence-${config3.profile}` : "confluence";
   const server = new McpServer({
     name: serverName,
-    version: "6.0.1"
+    version: "6.1.0"
   });
   await registerTools(server, config3);
   const transport = new StdioServerTransport();
   await server.connect(transport);
   try {
     const pending = await getPendingUpdate();
-    if (pending && pending.current === "6.0.1") {
+    if (pending && pending.current === "6.1.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.0.1").catch(() => {
+  checkForUpdates("6.1.0").catch(() => {
   });
 }
 
@@ -61327,6 +61920,10 @@ async function run() {
   } else if (command === "status") {
     const { runStatus: runStatus2 } = await Promise.resolve().then(() => (init_status(), status_exports));
     await runStatus2();
+  } else if (command === "permissions") {
+    const profile = process.argv[3];
+    const { runPermissions: runPermissions2 } = await Promise.resolve().then(() => (init_permissions(), permissions_exports));
+    await runPermissions2(profile);
   } else if (command === "fix-legacy-links") {
     const { runFixLegacyLinks: runFixLegacyLinks2 } = await Promise.resolve().then(() => (init_fix_legacy_links(), fix_legacy_links_exports));
     await runFixLegacyLinks2(process.argv.slice(3));