clay-server 3.1.0 → 3.2.0

package/lib/project-connection.js

@@ -316,6 +316,7 @@ function attachConnection(ctx) {
     }
     tm.detachAll(ws);
     clients.delete(ws);
+    stopFileWatch(ws);
     if (clients.size === 0) {
       stopFileWatch();
       stopAllDirWatches();

package/lib/project-file-watch.js

@@ -5,56 +5,93 @@ var path = require("path");
  * Attach file/directory watcher engine to a project context.
  *
  * ctx fields:
- *   cwd, send, safePath, BINARY_EXTS, FS_MAX_SIZE, IGNORED_DIRS
+ *   cwd, send, sendTo, safePath, BINARY_EXTS, FS_MAX_SIZE, IGNORED_DIRS
  */
 function attachFileWatch(ctx) {
   var cwd = ctx.cwd;
   var send = ctx.send;
+  var sendTo = ctx.sendTo;
   var safePath = ctx.safePath;
   var BINARY_EXTS = ctx.BINARY_EXTS;
   var FS_MAX_SIZE = ctx.FS_MAX_SIZE;
   var IGNORED_DIRS = ctx.IGNORED_DIRS;
 
   // --- File watcher ---
-  var fileWatcher = null;
-  var watchedPath = null;
-  var watchDebounce = null;
+  // One open file per websocket client. A project-wide singleton watcher made
+  // one browser tab silently replace another tab's live preview subscription.
+  var fileWatchers = new Map();
 
-  function startFileWatch(relPath) {
+  function closeFileWatch(key) {
+    var entry = fileWatchers.get(key);
+    if (!entry) return;
+    clearTimeout(entry.debounce);
+    try { entry.watcher.close(); } catch (e) {}
+    fileWatchers.delete(key);
+  }
+
+  function sendFileChanged(client, message) {
+    if (client && typeof sendTo === "function") {
+      sendTo(client, message);
+    } else {
+      send(message);
+    }
+  }
+
+  function startFileWatch(client, relPath) {
+    // Preserve the old single-argument API for callers outside the websocket
+    // file browser. They share one legacy subscription.
+    if (typeof relPath !== "string") {
+      relPath = client;
+      client = null;
+    }
     var absPath = safePath(cwd, relPath);
     if (!absPath) return;
-    if (watchedPath === relPath) return;
-    stopFileWatch();
-    watchedPath = relPath;
+    var key = client || "_legacy";
+    var existing = fileWatchers.get(key);
+    if (existing && existing.relPath === relPath) return;
+    closeFileWatch(key);
+
+    // Watch the parent directory rather than the file inode. Editors and agent
+    // tools commonly save with write-temp + rename; watching the old inode then
+    // misses later edits even though the path still exists.
+    var parentPath = path.dirname(absPath);
+    var baseName = path.basename(absPath);
     try {
-      fileWatcher = fs.watch(absPath, function () {
-        clearTimeout(watchDebounce);
-        watchDebounce = setTimeout(function () {
+      var watcher = fs.watch(parentPath, function (eventType, filename) {
+        if (filename && String(filename) !== baseName) return;
+        var active = fileWatchers.get(key);
+        if (!active || active.relPath !== relPath) return;
+        clearTimeout(active.debounce);
+        active.debounce = setTimeout(function () {
+          var latest = fileWatchers.get(key);
+          if (!latest || latest.relPath !== relPath) return;
           try {
             var stat = fs.statSync(absPath);
             var ext = path.extname(absPath).toLowerCase();
             if (stat.size > FS_MAX_SIZE || BINARY_EXTS.has(ext)) return;
             var content = fs.readFileSync(absPath, "utf8");
-            send({ type: "fs_file_changed", path: relPath, content: content, size: stat.size });
+            sendFileChanged(client, { type: "fs_file_changed", path: relPath, content: content, size: stat.size });
           } catch (e) {
-            stopFileWatch();
+            // Atomic saves can briefly remove the destination path between
+            // rename events. Keep the parent watcher alive for the next event.
+            if (e.code !== "ENOENT") closeFileWatch(key);
           }
         }, 200);
       });
-      fileWatcher.on("error", function () { stopFileWatch(); });
+      fileWatchers.set(key, { watcher: watcher, relPath: relPath, debounce: null });
+      watcher.on("error", function () { closeFileWatch(key); });
     } catch (e) {
-      watchedPath = null;
+      closeFileWatch(key);
     }
   }
 
-  function stopFileWatch() {
-    if (fileWatcher) {
-      try { fileWatcher.close(); } catch (e) {}
-      fileWatcher = null;
+  function stopFileWatch(client) {
+    if (arguments.length > 0) {
+      closeFileWatch(client || "_legacy");
+      return;
     }
-    clearTimeout(watchDebounce);
-    watchDebounce = null;
-    watchedPath = null;
+    var keys = Array.from(fileWatchers.keys());
+    for (var i = 0; i < keys.length; i++) closeFileWatch(keys[i]);
   }
 
   // --- Directory watcher ---

package/lib/project-filesystem.js

@@ -317,12 +317,12 @@ function attachFilesystem(ctx) {
 
     // --- File watcher ---
     if (msg.type === "fs_watch") {
-      if (msg.path) startFileWatch(msg.path);
+      if (msg.path) startFileWatch(ws, msg.path);
       return true;
     }
 
     if (msg.type === "fs_unwatch") {
-      stopFileWatch();
+      stopFileWatch(ws);
       return true;
     }
 

package/lib/project-session-document.js

@@ -0,0 +1,107 @@
+var fs = require("fs");
+var path = require("path");
+var sessionDocumentMcp = require("./session-document-mcp-server");
+
+var DOCUMENT_PROMPT = "When the user's primary request is to create or revise Markdown, call present_markdown_edit once per targeted document with its resolved .md/.mdx path, immediately before that document's first Edit or Write. Do not call it for incidental Markdown changes during coding, maintenance, tests, or refactoring.";
+
+function toolResult(value) {
+  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
+}
+
+function toolError(message) {
+  return Promise.resolve({
+    content: [{ type: "text", text: "Error: " + message }],
+    isError: true,
+  });
+}
+
+function isInside(root, target) {
+  return target === root || target.startsWith(root + path.sep);
+}
+
+function attachSessionDocument(ctx) {
+  var cwd = fs.realpathSync(ctx.cwd);
+  var isMate = ctx.isMate;
+  var sendToSession = ctx.sendToSession;
+  var fsMaxSize = ctx.FS_MAX_SIZE || 512 * 1024;
+  var getOsUserInfoForSession = ctx.getOsUserInfoForSession || function () { return null; };
+  var fsAsUser = ctx.fsAsUser;
+
+  function resolveMarkdownPath(requested) {
+    if (typeof requested !== "string" || !requested.trim()) return null;
+    var target = path.resolve(cwd, requested.trim());
+    if (!isInside(cwd, target) || !/\.mdx?$/i.test(target)) return null;
+    try {
+      var realTarget = fs.realpathSync(target);
+      return isInside(cwd, realTarget) ? realTarget : null;
+    } catch (e) {
+      try {
+        var realParent = fs.realpathSync(path.dirname(target));
+        return isInside(cwd, realParent) ? path.join(realParent, path.basename(target)) : null;
+      } catch (parentError) {
+        return null;
+      }
+    }
+  }
+
+  function readSnapshot(target, caller) {
+    if (!fs.existsSync(target)) return { content: "", exists: false, size: 0 };
+    var osUserInfo = getOsUserInfoForSession(caller);
+    if (osUserInfo && typeof fsAsUser === "function") {
+      var statResult = fsAsUser("stat", { file: target }, osUserInfo);
+      if (statResult.size > fsMaxSize) throw new Error("Markdown file is too large to present live");
+      var readResult = fsAsUser("read", { file: target, readContent: true }, osUserInfo);
+      return { content: readResult.content || "", exists: true, size: statResult.size };
+    }
+    var stat = fs.statSync(target);
+    if (stat.size > fsMaxSize) throw new Error("Markdown file is too large to present live");
+    return { content: fs.readFileSync(target, "utf8"), exists: true, size: stat.size };
+  }
+
+  function present(args, caller) {
+    if (!caller) return toolError("present_markdown_edit requires a session-bound tool server");
+    var target = resolveMarkdownPath(args.path);
+    if (!target) return toolError("path must be a .md or .mdx file inside the project");
+    try {
+      var snapshot = readSnapshot(target, caller);
+      var relativePath = path.relative(cwd, target).split(path.sep).join("/");
+      sendToSession(caller.localId, {
+        type: "markdown_edit_present",
+        path: relativePath,
+        content: snapshot.content,
+        exists: snapshot.exists,
+        size: snapshot.size,
+      });
+      return toolResult({ ready: true, path: relativePath });
+    } catch (e) {
+      return toolError(e.message || String(e));
+    }
+  }
+
+  function getToolDefs(boundSession) {
+    if (isMate) return [];
+    return sessionDocumentMcp.getToolDefs({
+      present: function (args) { return present(args, boundSession || null); },
+    });
+  }
+
+  function createMcpServer(adapter, boundSession) {
+    if (isMate || !adapter || typeof adapter.createToolServer !== "function") return null;
+    return adapter.createToolServer({
+      name: "clay-documents",
+      version: "1.0.0",
+      tools: getToolDefs(boundSession || null),
+    });
+  }
+
+  return {
+    createMcpServer: createMcpServer,
+    getSystemPrompt: function () { return isMate ? "" : DOCUMENT_PROMPT; },
+    getToolDefs: getToolDefs,
+  };
+}
+
+module.exports = {
+  DOCUMENT_PROMPT: DOCUMENT_PROMPT,
+  attachSessionDocument: attachSessionDocument,
+};

package/lib/project-session-notes.js

@@ -6,7 +6,7 @@ var MAX_PROMPT_CHARS = 4000;
 var MAX_NOTE_PROMPT_CHARS = 800;
 var NOTES_LABEL = "--- Project sticky notes (cross-session work memory; manage via clay-notes tools) ---";
 var NOTES_HINT = "- More notes are available; call list_notes for the rest.";
-var PROACTIVE_POLICY = "The board persists across sessions and is shared with the user and every Clay agent working on this project. People may use it freely. As a Clay agent, use it specifically as cross-session work memory: checklists and to-do lists, work goals, handoffs, unfinished work, durable decisions and constraints, and knowledge that should remain available after this session ends. Create or update a note proactively when the user asks for a handoff, establishes something future sessions must remember, or when preserving the current goal and next actions would make continuation easier. Put a concise plain-text title on the first line. Add a detailed body with the relevant background, rationale, decisions, completed work, current state, validation, next steps, blockers, and references. If an injected preview is relevant or truncated, call list_notes and read the full note before acting. Do not use notes as a transcript, routine progress log, or self-announcement. Keep one coherent topic per note and consolidate or remove stale notes instead of creating duplicates.";
+var PROACTIVE_POLICY = sessionNotesMcp.MEMORY_CONTRACT + " If an injected preview is relevant or truncated, call list_notes before acting or writing so you do not create a duplicate.";
 var NOTE_COLORS = ["yellow", "blue", "green", "pink", "orange", "purple"];
 
 function toolResult(value) {

package/lib/project.js

@@ -33,6 +33,7 @@ var { attachEmail: attachEmailModule } = require("./project-email");
 var { attachSessionSpawn } = require("./project-session-spawn");
 var { attachSessionPair } = require("./project-session-pair");
 var { attachSessionNotes, composeSystemPrompts } = require("./project-session-notes");
+var { attachSessionDocument } = require("./project-session-document");
 var { attachSplitGroups } = require("./session-split-groups");
 // project-notifications is attached globally in server.js, passed via opts.notificationsModule
 
@@ -385,6 +386,7 @@ function createProjectContext(opts) {
   var _fileWatch = attachFileWatch({
     cwd: cwd,
     send: send,
+    sendTo: sendTo,
     safePath: safePath,
     BINARY_EXTS: BINARY_EXTS,
     FS_MAX_SIZE: FS_MAX_SIZE,
@@ -507,6 +509,17 @@ function createProjectContext(opts) {
       }
     },
   });
+  var _sessionDocument = attachSessionDocument({
+    cwd: cwd,
+    isMate: isMate,
+    sendToSession: sendToSession,
+    FS_MAX_SIZE: FS_MAX_SIZE,
+    getOsUserInfoForSession: function (session) {
+      var linuxUser = getLinuxUserForSession(session);
+      return linuxUser ? resolveOsUserInfo(linuxUser) : null;
+    },
+    fsAsUser: fsAsUser,
+  });
 
   // The SDK bridge is created after local MCP servers. Session spawning uses
   // a getter so tool handlers see the initialized bridge when they run.
@@ -565,6 +578,16 @@ function createProjectContext(opts) {
       }
     }
 
+    // Explicit agent signal for user-requested Markdown presentation.
+    if (!isMate) {
+      try {
+        var sessionDocumentMcpConfig = _sessionDocument.createMcpServer(adapter);
+        if (sessionDocumentMcpConfig) servers[sessionDocumentMcpConfig.name || "clay-documents"] = sessionDocumentMcpConfig;
+      } catch (e) {
+        console.error("[project] Failed to create session document MCP server:", e.message);
+      }
+    }
+
     // Debate MCP server (available to both mates and main project)
     try {
       var debateMcp = require("./debate-mcp-server");
@@ -728,9 +751,9 @@ function createProjectContext(opts) {
   //   clay-email   -> only when the user has an account or server SMTP
   //
   // forSession (optional): the session whose query these servers are mounted
-  // into. clay-sessions and clay-notes must know their caller for depth and
-  // ownership rules, so they are re-instantiated bound to that session; the
-  // static instances only serve descriptor listing and fail closed on calls.
+  // into. Session, notes, and document tools must know their caller, so they
+  // are re-instantiated bound to that session; static instances only serve
+  // descriptor listing and fail closed on calls.
   function getLocalMcpServers(forSession) {
     var extWs = browserState._extensionWs;
     var extConnected = !!(extWs && extWs.readyState === 1);
@@ -760,6 +783,15 @@ function createProjectContext(opts) {
         }
         continue;
       }
+      if (name === "clay-documents" && forSession) {
+        try {
+          var boundDocuments = _sessionDocument.createMcpServer(adapter, forSession);
+          if (boundDocuments) { filtered[name] = boundDocuments; hasAny = true; }
+        } catch (e) {
+          console.error("[project] Failed to bind session document MCP server:", e.message);
+        }
+        continue;
+      }
       filtered[name] = mcpServers[name];
       hasAny = true;
     }
@@ -807,10 +839,13 @@ function createProjectContext(opts) {
       return composeSystemPrompts([
         _sessionPair.getSystemPrompt(session),
         _sessionNotes.getSystemPrompt(session),
+        _sessionDocument.getSystemPrompt(session),
       ]);
     },
     getSessionToolDefs: function (session) {
-      return _sessionPair.getToolDefs(session).concat(_sessionNotes.getToolDefs(session));
+      return _sessionPair.getToolDefs(session)
+        .concat(_sessionNotes.getToolDefs(session))
+        .concat(_sessionDocument.getToolDefs(session));
     },
   });
 
@@ -1482,6 +1517,15 @@ function createProjectContext(opts) {
               inputSchema: normalizeToolSchema(noteTools[nti].inputSchema),
             });
           }
+          var documentTools = _sessionDocument.getToolDefs(boundSession);
+          for (var dti = 0; dti < documentTools.length; dti++) {
+            tools.push({
+              server: "clay-documents",
+              name: documentTools[dti].name,
+              description: documentTools[dti].description || documentTools[dti].name,
+              inputSchema: normalizeToolSchema(documentTools[dti].inputSchema),
+            });
+          }
         }
 
         if (sessionOnly) return Promise.resolve(tools);
@@ -1493,6 +1537,7 @@ function createProjectContext(opts) {
         if (localMcp) {
           var inAppNames = Object.keys(localMcp);
           for (var i = 0; i < inAppNames.length; i++) {
+            if (inAppNames[i] === "clay-sessions" || inAppNames[i] === "clay-notes" || inAppNames[i] === "clay-documents") continue;
             extractServerTools(inAppNames[i], localMcp[inAppNames[i]]);
           }
         }
@@ -1527,6 +1572,17 @@ function createProjectContext(opts) {
             }
           }
         }
+        if (boundSession && serverName === "clay-documents") {
+          var documentTools = _sessionDocument.getToolDefs(boundSession);
+          for (var dti = 0; dti < documentTools.length; dti++) {
+            if (documentTools[dti].name === toolName && typeof documentTools[dti].handler === "function") {
+              return Promise.resolve(documentTools[dti].handler(args || {}));
+            }
+          }
+        }
+        if (serverName === "clay-sessions" || serverName === "clay-notes" || serverName === "clay-documents") {
+          return Promise.reject(new Error("Session-bound tool requires a valid Clay session: " + serverName + "/" + toolName));
+        }
         if (sessionOnly) return Promise.reject(new Error("Session tool not found: " + serverName + "/" + toolName));
         // Try in-app servers first (gated by extension connectivity for clay-browser).
         var localMcp = getLocalMcpServers();

package/lib/public/css/filebrowser.css

@@ -1036,6 +1036,41 @@
 .file-viewer-btn.hidden { display: none; }
 .file-viewer-btn .lucide { width: 16px; height: 16px; }
 
+.file-viewer-live-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex-shrink: 0;
+  padding: 4px 8px;
+  border: 1px solid var(--accent-25);
+  border-radius: 999px;
+  background: var(--accent-8);
+  color: var(--accent);
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+
+.file-viewer-live-status.hidden { display: none; }
+
+.file-viewer-live-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: currentColor;
+  box-shadow: 0 0 0 0 var(--accent-25);
+}
+
+.file-viewer-live-status.editing .file-viewer-live-dot {
+  animation: markdown-live-pulse 1.15s ease-out infinite;
+}
+
+.file-viewer-live-status.updated {
+  border-color: var(--success-25);
+  background: var(--success-8);
+  color: var(--success);
+}
+
 /* --- Markdown rendered view --- */
 .file-viewer-markdown {
   padding: 20px 24px;
@@ -1113,6 +1148,84 @@
 
 .file-viewer-markdown img { max-width: 100%; border-radius: 8px; }
 
+.file-viewer-markdown > .markdown-live-added,
+.file-viewer-markdown > .markdown-live-changed {
+  position: relative;
+  margin-left: -10px;
+  margin-right: -10px;
+  padding-left: 10px;
+  padding-right: 10px;
+  border-radius: 6px;
+  background: var(--success-12);
+  box-shadow: inset 2px 0 0 var(--success);
+  animation: markdown-live-arrive 0.46s cubic-bezier(0.2, 0.8, 0.2, 1) both;
+  transition: background 0.3s ease, box-shadow 0.3s ease, opacity 0.3s ease;
+}
+
+.file-viewer-markdown > .markdown-live-removed {
+  margin-left: -10px;
+  margin-right: -10px;
+  padding-left: 10px;
+  padding-right: 10px;
+  border-radius: 6px;
+  background: var(--error-8);
+  box-shadow: inset 2px 0 0 var(--error);
+  color: color-mix(in srgb, var(--text-secondary) 72%, transparent);
+  text-decoration-color: var(--error);
+  transition: background 0.3s ease, box-shadow 0.3s ease, opacity 0.3s ease;
+}
+
+.file-viewer-markdown > .markdown-live-focus {
+  z-index: 1;
+  opacity: 1;
+  box-shadow: 0 10px 30px rgba(var(--shadow-rgb), 0.22);
+}
+
+.file-viewer-markdown > .markdown-live-focus.markdown-live-added,
+.file-viewer-markdown > .markdown-live-focus.markdown-live-changed {
+  box-shadow: inset 3px 0 0 var(--success), 0 0 0 1px var(--success), 0 10px 30px rgba(var(--shadow-rgb), 0.22);
+}
+
+.file-viewer-markdown > .markdown-live-focus.markdown-live-removed {
+  box-shadow: inset 3px 0 0 var(--error), 0 0 0 1px var(--error), 0 10px 30px rgba(var(--shadow-rgb), 0.22);
+}
+
+.file-viewer-markdown > .markdown-live-seen.markdown-live-added,
+.file-viewer-markdown > .markdown-live-seen.markdown-live-changed {
+  background: var(--success-8);
+  box-shadow: inset 2px 0 0 var(--success-25);
+}
+
+.file-viewer-markdown > .markdown-live-seen.markdown-live-removed {
+  animation: markdown-live-depart 0.42s ease both;
+}
+
+@keyframes markdown-live-pulse {
+  0% { box-shadow: 0 0 0 0 var(--accent-25); }
+  70% { box-shadow: 0 0 0 5px transparent; }
+  100% { box-shadow: 0 0 0 0 transparent; }
+}
+
+@keyframes markdown-live-arrive {
+  from { opacity: 0; transform: translateY(5px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes markdown-live-depart {
+  0%, 58% { opacity: 0.82; max-height: 800px; }
+  100% { opacity: 0; max-height: 0; margin-top: 0; margin-bottom: 0; overflow: hidden; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .file-viewer-live-status.editing .file-viewer-live-dot,
+  .file-viewer-markdown > .markdown-live-added,
+  .file-viewer-markdown > .markdown-live-changed,
+  .file-viewer-markdown > .markdown-live-removed,
+  .file-viewer-markdown > .markdown-live-seen.markdown-live-removed {
+    animation: none;
+  }
+}
+
 .file-viewer-body {
   flex: 1;
   overflow: auto;

package/lib/public/index.html

@@ -636,11 +636,16 @@
   <div id="file-viewer" class="hidden">
     <div class="file-viewer-header">
       <span class="file-viewer-path" id="file-viewer-path"></span>
+      <span class="file-viewer-live-status hidden" id="file-viewer-live-status" aria-live="polite">
+        <span class="file-viewer-live-dot"></span>
+        <span class="file-viewer-live-label">Editing</span>
+      </span>
       <button class="file-viewer-btn hidden" id="file-viewer-render" title="Toggle rendered view"><i data-lucide="book-open"></i></button>
       <button class="file-viewer-btn hidden" id="file-viewer-pdf" title="Export PDF"><i data-lucide="file-down"></i></button>
       <button class="file-viewer-btn hidden" id="file-viewer-history" title="Edit history"><i data-lucide="clock"></i></button>
       <button class="file-viewer-btn" id="file-viewer-refresh" title="Refresh"><i data-lucide="refresh-cw"></i></button>
-      <button class="file-viewer-btn" id="file-viewer-copy" title="Copy contents"><i data-lucide="copy"></i></button>
+      <button class="file-viewer-btn" id="file-viewer-copy" title="Copy contents" aria-label="Copy contents"><i data-lucide="copy"></i></button>
+      <button class="file-viewer-btn hidden" id="file-viewer-copy-formatted" title="Copy Markdown formatting" aria-label="Copy Markdown formatting"><i data-lucide="clipboard-copy"></i></button>
       <button class="file-viewer-btn" id="file-viewer-fullscreen" title="Toggle fullscreen"><i data-lucide="maximize-2"></i></button>
       <button class="file-viewer-btn" id="file-viewer-close" title="Close"><i data-lucide="x"></i></button>
     </div>

package/lib/public/modules/app-messages.js

@@ -24,7 +24,8 @@ import { showPairDialog, handlePairCreated, handleSplitDelegation, showWorkerDel
 import { handleInputSync, autoResize, builtinCommands, setScheduleBtnDisabled } from './input.js';
 import { startThinking, appendThinking, stopThinking, resetThinkingGroup, createToolItem, updateToolExecuting, updateToolResult, markAllToolsDone, closeToolGroup, removeToolFromGroup, resetToolState, getTools, getPlanContent, setPlanContent, renderPlanBanner, renderPlanCard, getTodoTools, handleTodoWrite, handleTaskCreate, handleTaskUpdate, applyDeadSessionTodoCompaction, isPlanFilePath, enableMainInput, addTurnMeta, updateSubagentActivity, addSubagentToolEntry, markSubagentDone, initSubagentStop, updateSubagentProgress, updateSubagentTaskStatus, renderAskUserQuestion, markAskUserAnswered, renderPermissionRequest, markPermissionCancelled, markPermissionResolved, renderElicitationRequest, markElicitationResolved, renderUserDialogRequest, markUserDialogResolved, updateThinkingTokens } from './tools.js';
 import { showDoneNotification, playDoneSound, isNotifAlertEnabled, isNotifSoundEnabled } from './notifications.js';
-import { handleFsList, handleFsRead, handleFileChanged, handleDirChanged, handleFileHistory, handleGitDiff, handleFileAt, refreshIfOpen, getPendingNavigate, handleFsSearch } from './filebrowser.js';
+import { handleFsList, handleFsRead, handleFileChanged, handleDirChanged, handleFileHistory, handleGitDiff, handleFileAt, refreshIfOpen, getPendingNavigate, handleFsSearch, presentMarkdownEdit } from './filebrowser.js';
+import { beginMarkdownTurn, finishMarkdownTurn, markdownPathFromToolInput } from './markdown-live-edit.js';
 import { isProjectSettingsOpen, handleInstructionsRead, handleInstructionsWrite, handleProjectEnv, handleProjectEnvSaved, handleProjectSharedEnv, handleProjectSharedEnvSaved, handleProjectOwnerChanged } from './project-settings.js';
 import { updateSettingsModels, updateSettingsStats, updateDaemonConfig, handleSetPinResult, handleKeepAwakeChanged, handleInheritGroupsChanged, handleAutoContinueChanged, handleRestartResult, handleShutdownResult, handleSharedEnv, handleSharedEnvSaved, handleGlobalClaudeMdRead, handleGlobalClaudeMdWrite } from './server-settings.js';
 import { handleTermList, handleTermCreated, sendTerminalCommand, handleTermOutput, handleTermResized, handleTermExited, handleTermClosed } from './terminal.js';
@@ -783,6 +784,7 @@ export function processMessage(msg) {
 
       case "user_message":
         if (msg._internal) break;
+        if (!store.get('replayingHistory')) beginMarkdownTurn();
         resetThinkingGroup();
         if (msg.planContent) {
           setPlanContent(msg.planContent);
@@ -934,6 +936,8 @@ export function processMessage(msg) {
           getTools()[msg.id] = { el: null, name: msg.name, input: null, done: true, hidden: true };
         } else if (msg.name === "ask_user_questions") {
           getTools()[msg.id] = { el: null, name: msg.name, input: null, done: true, hidden: true };
+        } else if (msg.name === "present_markdown_edit" || (msg.name && msg.name.indexOf("present_markdown_edit") !== -1)) {
+          getTools()[msg.id] = { el: null, name: msg.name, input: null, done: true, hidden: true };
         } else if (getTodoTools()[msg.name]) {
           getTools()[msg.id] = { el: null, name: msg.name, input: null, done: true, hidden: true };
         } else {
@@ -997,9 +1001,12 @@ export function processMessage(msg) {
           if (msg.content != null || msg.images || (tr && tr.name === "Edit" && tr.input && tr.input.old_string)) {
             updateToolResult(msg.id, msg.content || "", msg.is_error || false, msg.images);
           }
-          // Refresh file browser if an Edit/Write tool modified the open file
-          if (!msg.is_error && tr && (tr.name === "Edit" || tr.name === "Write") && tr.input && tr.input.file_path) {
-            refreshIfOpen(tr.input.file_path);
+          // Refresh file browser if an Edit/Write tool modified the open file.
+          // Multi-file Codex changes expose file_paths instead of file_path.
+          var changedMarkdownPath = tr && tr.input ? markdownPathFromToolInput(tr.input) : null;
+          var changedFilePath = tr && tr.input ? (tr.input.file_path || changedMarkdownPath) : null;
+          if (!msg.is_error && tr && (tr.name === "Edit" || tr.name === "Write") && changedFilePath) {
+            refreshIfOpen(changedFilePath);
           }
         }
         break;
@@ -1121,6 +1128,7 @@ export function processMessage(msg) {
         setStatus("connected");
         if (!store.get('loopActive')) enableMainInput();
         resetToolState();
+        finishMarkdownTurn();
         stopUrgentBlink();
         if (document.hidden) {
           if (isNotifAlertEnabled() && !window._pushSubscription) showDoneNotification();
@@ -1326,6 +1334,10 @@ export function processMessage(msg) {
         handleFileChanged(msg);
         break;
 
+      case "markdown_edit_present":
+        if (!store.get('replayingHistory') && !store.get('dmMode')) presentMarkdownEdit(msg);
+        break;
+
       case "fs_dir_changed":
         handleDirChanged(msg);
         break;

package/lib/public/modules/filebrowser.js

@@ -5,6 +5,8 @@ import { closeSidebar } from './sidebar.js';
 import { closeTerminal } from './terminal.js';
 import { renderUnifiedDiff, renderSplitDiff } from './diff.js';
 import { initFileIcons, getFileIconSvg, getFolderIconSvg } from './fileicons.js';
+import { copyMarkdownFormatting } from './rich-clipboard.js';
+import { animateMarkdownChange, beginMarkdownPresentation, cancelMarkdownFollow, isFollowingMarkdown } from './markdown-live-edit.js';
 
 var ctx;
 var showDropHint = function () {};
@@ -147,10 +149,18 @@ export function initFileBrowser(_ctx) {
     if (currentContent) copyToClipboard(currentContent);
   });
 
+  document.getElementById("file-viewer-copy-formatted").addEventListener("click", function () {
+    if (!isRendered || !currentIsMarkdown) return;
+    copyMarkdownFormatting(currentContent).catch(function (err) {
+      console.error("Markdown formatting copy failed:", err);
+    });
+  });
+
   // Markdown render toggle
   document.getElementById("file-viewer-render").addEventListener("click", function () {
     if (!currentContent || !currentIsMarkdown) return;
     isRendered = !isRendered;
+    if (!isRendered && isFollowingMarkdown(currentFilePath)) cancelMarkdownFollow();
     renderBody();
   });
 
@@ -172,6 +182,7 @@ export function initFileBrowser(_ctx) {
   // History button
   document.getElementById("file-viewer-history").addEventListener("click", function () {
     if (currentHistoryEntries.length === 0) return;
+    if (isFollowingMarkdown(currentFilePath)) cancelMarkdownFollow();
     historyVisible = !historyVisible;
     inlineDiffActive = false;
     compareMode = false;
@@ -191,6 +202,9 @@ export function initFileBrowser(_ctx) {
       if (!currentFilePath) return;
       viewerRefreshBtn.classList.add("spinning");
       setTimeout(function () { viewerRefreshBtn.classList.remove("spinning"); }, 500);
+      // Refresh the content without kicking a rendered Markdown document back
+      // to source mode. Automatic watcher refreshes use the same state path.
+      pendingRefresh = true;
       requestFileContent(currentFilePath);
     });
   }
@@ -395,6 +409,7 @@ function sendUnwatch() {
 }
 
 export function closeFileViewer() {
+  if (currentFilePath && isFollowingMarkdown(currentFilePath)) cancelMarkdownFollow();
   sendUnwatch();
   inlineDiffActive = false;
   ctx.fileViewerEl.classList.remove("file-viewer-wide");
@@ -439,9 +454,14 @@ export function resetFileBrowser() {
 }
 
 var pendingOpenMode = null; // { type: "diff", oldStr, newStr } or null
+var pendingRenderedOpen = false;
 
 export function openFile(filePath, opts) {
   if (!filePath) return;
+  if (followedFileChanged(filePath) || (opts && opts.diff && isFollowingMarkdown(filePath))) {
+    cancelMarkdownFollow();
+  }
+  pendingRenderedOpen = !!(opts && opts.rendered);
   if (opts && opts.diff) {
     pendingOpenMode = { type: "diff", oldStr: opts.diff.oldStr, newStr: opts.diff.newStr };
   } else {
@@ -450,10 +470,27 @@ export function openFile(filePath, opts) {
   requestFileContent(filePath);
 }
 
-function renderBody() {
+export function presentMarkdownEdit(msg) {
+  if (!msg || !beginMarkdownPresentation(msg.path)) return;
+  pendingOpenMode = null;
+  pendingRenderedOpen = true;
+  pendingRefresh = false;
+  showFileContent({
+    path: msg.path,
+    content: typeof msg.content === "string" ? msg.content : "",
+    size: msg.size || 0,
+  });
+}
+
+function followedFileChanged(filePath) {
+  return currentFilePath && isFollowingMarkdown(currentFilePath) && !isFollowingMarkdown(filePath);
+}
+
+function renderBody(previousMarkdown) {
   var bodyEl = document.getElementById("file-viewer-body");
   var renderBtn = document.getElementById("file-viewer-render");
   var pdfBtn = document.getElementById("file-viewer-pdf");
+  var formattedCopyBtn = document.getElementById("file-viewer-copy-formatted");
 
   if (isRendered) {
     bodyEl.innerHTML = '<div class="file-viewer-markdown">' + renderMarkdown(currentContent) + '</div>';
@@ -467,11 +504,16 @@ function renderBody() {
         imgs[i].src = "api/file?path=" + encodeURIComponent(resolvedPath);
       }
     }
+    var markdownEl = bodyEl.querySelector(".file-viewer-markdown");
+    if (previousMarkdown != null && isFollowingMarkdown(currentFilePath)) {
+      animateMarkdownChange(markdownEl, previousMarkdown, currentContent, renderMarkdown);
+    }
     highlightCodeBlocks(bodyEl);
     renderMermaidBlocks(bodyEl);
     renderBtn.classList.add("active");
     renderBtn.title = "Show raw";
     pdfBtn.classList.remove("hidden");
+    formattedCopyBtn.classList.remove("hidden");
   } else {
     var pre = document.createElement("pre");
     var code = document.createElement("code");
@@ -486,6 +528,7 @@ function renderBody() {
     renderBtn.classList.remove("active");
     renderBtn.title = "Render markdown";
     pdfBtn.classList.add("hidden");
+    formattedCopyBtn.classList.add("hidden");
   }
   refreshIcons();
 }
@@ -661,6 +704,7 @@ function renderFilteredTree(container, tree, depth, query) {
       (function (filePath, rowEl) {
         rowEl.addEventListener("click", function (e) {
           e.stopPropagation();
+          if (followedFileChanged(filePath)) cancelMarkdownFollow();
           var prev = ctx.fileTreeEl.querySelector(".file-tree-item.active");
           if (prev) prev.classList.remove("active");
           rowEl.classList.add("active");
@@ -891,6 +935,7 @@ function renderEntries(container, entries, depth) {
       (function (filePath, rowEl) {
         rowEl.addEventListener("click", function (e) {
           e.stopPropagation();
+          if (followedFileChanged(filePath)) cancelMarkdownFollow();
           // Mark active
           var prev = ctx.fileTreeEl.querySelector(".file-tree-item.active");
           if (prev) prev.classList.remove("active");
@@ -915,6 +960,10 @@ function showFileContent(msg) {
   var pathEl = document.getElementById("file-viewer-path");
   var bodyEl = document.getElementById("file-viewer-body");
   var renderBtn = document.getElementById("file-viewer-render");
+  var copyBtn = document.getElementById("file-viewer-copy");
+  var previousContent = currentContent;
+  var previousPath = currentFilePath;
+  var previousWasMarkdown = currentIsMarkdown;
 
   pathEl.textContent = msg.path;
   var keepRenderState = pendingRefresh && msg.path === currentFilePath;
@@ -924,9 +973,15 @@ function showFileContent(msg) {
   currentFilePath = msg.path;
   currentIsMarkdown = false;
   if (!keepRenderState) isRendered = false;
+  var requestedExt = msg.path.split(".").pop().toLowerCase();
+  if (pendingRenderedOpen && (requestedExt === "md" || requestedExt === "mdx")) {
+    currentIsMarkdown = true;
+    isRendered = true;
+  }
   renderBtn.classList.add("hidden");
   renderBtn.classList.remove("active");
   document.getElementById("file-viewer-pdf").classList.add("hidden");
+  document.getElementById("file-viewer-copy-formatted").classList.add("hidden");
 
   if (msg.error) {
     bodyEl.innerHTML = '<div class="file-tree-error">' + escapeHtml(msg.error) + '</div>';
@@ -938,17 +993,25 @@ function showFileContent(msg) {
     }
   } else {
     currentContent = msg.content;
-    var ext = msg.path.split(".").pop().toLowerCase();
+    var ext = requestedExt;
     currentIsMarkdown = (ext === "md" || ext === "mdx");
+    if (pendingRenderedOpen && currentIsMarkdown) isRendered = true;
 
     if (currentIsMarkdown) {
       renderBtn.classList.remove("hidden");
       renderBtn.title = "Render markdown";
+      copyBtn.title = "Copy Markdown source";
+    } else {
+      copyBtn.title = "Copy contents";
     }
 
     // Show raw by default, use renderBody for markdown toggle
     if (currentIsMarkdown) {
-      renderBody();
+      var transitionFrom = keepRenderState && prevRendered && previousWasMarkdown &&
+        isFollowingMarkdown(msg.path) && pathsReferToSameFile(previousPath, msg.path)
+        ? (previousContent == null ? "" : previousContent)
+        : null;
+      renderBody(transitionFrom);
     } else {
       renderCodeWithLineNumbers(bodyEl, msg.content, ext);
     }
@@ -974,9 +1037,11 @@ function showFileContent(msg) {
     historyBtn2.classList.remove("active");
     requestFileHistory(msg.path);
     showInlineDiff(diffOpts.oldStr, diffOpts.newStr);
+    pendingRenderedOpen = false;
     return;
   }
   pendingOpenMode = null;
+  pendingRenderedOpen = false;
 
   // Request edit history for this file (skip on auto-refresh)
   if (!keepRenderState) {
@@ -993,6 +1058,13 @@ function showFileContent(msg) {
   }
 }
 
+function pathsReferToSameFile(left, right) {
+  if (!left || !right) return false;
+  var a = String(left).replace(/\\/g, "/");
+  var b = String(right).replace(/\\/g, "/");
+  return a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
+}
+
 export function handleFileChanged(msg) {
   if (!msg.path || msg.path !== currentFilePath) return;
   if (ctx.fileViewerEl.classList.contains("hidden")) return;

package/lib/public/modules/markdown-live-edit.js

@@ -0,0 +1,305 @@
+var followedPath = null;
+var suppressedForTurn = false;
+var cleanupTimer = null;
+var tourTimer = null;
+var statusTimer = null;
+var followExpiryTimer = null;
+var sawChange = false;
+var tourVersion = 0;
+var touring = false;
+var tourViewer = null;
+
+function normalizedPath(filePath) {
+  return String(filePath || "").replace(/\\/g, "/");
+}
+
+export function isMarkdownPath(filePath) {
+  return /\.mdx?$/i.test(normalizedPath(filePath));
+}
+
+export function markdownPathFromToolInput(input) {
+  if (!input || typeof input !== "object") return null;
+  if (isMarkdownPath(input.file_path)) return input.file_path;
+  var paths = Array.isArray(input.file_paths) ? input.file_paths : [];
+  for (var i = 0; i < paths.length; i++) {
+    if (isMarkdownPath(paths[i])) return paths[i];
+  }
+  return null;
+}
+
+export function pathsMatch(left, right) {
+  var a = normalizedPath(left);
+  var b = normalizedPath(right);
+  if (!a || !b) return false;
+  return a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
+}
+
+function statusElement() {
+  return document.getElementById("file-viewer-live-status");
+}
+
+function setStatus(state, label) {
+  var el = statusElement();
+  if (!el) return;
+  clearTimeout(statusTimer);
+  el.classList.remove("hidden", "editing", "updated");
+  el.classList.add(state);
+  var labelEl = el.querySelector(".file-viewer-live-label");
+  if (labelEl) labelEl.textContent = label;
+}
+
+function hideStatusSoon() {
+  clearTimeout(statusTimer);
+  statusTimer = setTimeout(function () {
+    var el = statusElement();
+    if (el) el.classList.add("hidden");
+  }, 1800);
+}
+
+export function beginMarkdownTurn() {
+  stopChangeTour();
+  clearTimeout(cleanupTimer);
+  clearLiveClasses();
+  suppressedForTurn = false;
+  followedPath = null;
+  sawChange = false;
+  clearTimeout(followExpiryTimer);
+  clearTimeout(statusTimer);
+  var el = statusElement();
+  if (el) el.classList.add("hidden");
+}
+
+export function beginMarkdownPresentation(filePath) {
+  if (suppressedForTurn || !isMarkdownPath(filePath)) return false;
+  clearTimeout(followExpiryTimer);
+  if (!pathsMatch(followedPath, filePath)) sawChange = false;
+  followedPath = normalizedPath(filePath);
+  setStatus("editing", "Editing");
+  return true;
+}
+
+export function isFollowingMarkdown(filePath) {
+  return !suppressedForTurn && pathsMatch(followedPath, filePath);
+}
+
+export function cancelMarkdownFollow() {
+  followedPath = null;
+  suppressedForTurn = true;
+  clearTimeout(cleanupTimer);
+  stopChangeTour();
+  clearTimeout(statusTimer);
+  clearTimeout(followExpiryTimer);
+  var status = statusElement();
+  if (status) status.classList.add("hidden");
+  clearLiveClasses();
+}
+
+export function finishMarkdownTurn() {
+  if (!followedPath || suppressedForTurn) return;
+  if (sawChange && !touring) {
+    setStatus("updated", "Updated");
+    hideStatusSoon();
+  } else {
+    var el = statusElement();
+    if (el) el.classList.add("hidden");
+  }
+  clearTimeout(followExpiryTimer);
+  followExpiryTimer = setTimeout(function () { followedPath = null; }, 4000);
+}
+
+function blockSignature(node) {
+  return node.outerHTML.replace(/\s+/g, " ").trim();
+}
+
+export function diffBlockSignatures(oldSignatures, newSignatures) {
+  var oldLength = oldSignatures.length;
+  var newLength = newSignatures.length;
+  var rows = new Array(oldLength + 1);
+  var i;
+  var j;
+  for (i = 0; i <= oldLength; i++) rows[i] = new Uint32Array(newLength + 1);
+
+  for (i = oldLength - 1; i >= 0; i--) {
+    for (j = newLength - 1; j >= 0; j--) {
+      rows[i][j] = oldSignatures[i] === newSignatures[j]
+        ? rows[i + 1][j + 1] + 1
+        : Math.max(rows[i + 1][j], rows[i][j + 1]);
+    }
+  }
+
+  var matches = [];
+  i = 0;
+  j = 0;
+  while (i < oldLength && j < newLength) {
+    if (oldSignatures[i] === newSignatures[j]) {
+      matches.push({ oldIndex: i, newIndex: j });
+      i++;
+      j++;
+    } else if (rows[i + 1][j] >= rows[i][j + 1]) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  return matches;
+}
+
+function clearLiveClasses() {
+  var viewer = document.getElementById("file-viewer-body");
+  if (!viewer) return;
+  var removed = viewer.querySelectorAll(".markdown-live-removed");
+  for (var i = 0; i < removed.length; i++) removed[i].remove();
+  var active = viewer.querySelectorAll(".markdown-live-added, .markdown-live-changed, .markdown-live-focus, .markdown-live-seen");
+  for (var j = 0; j < active.length; j++) {
+    active[j].classList.remove("markdown-live-added", "markdown-live-changed", "markdown-live-focus", "markdown-live-seen");
+  }
+}
+
+function detachTourInterruption() {
+  if (tourViewer) {
+    tourViewer.removeEventListener("wheel", interruptChangeTour);
+    tourViewer.removeEventListener("pointerdown", interruptChangeTour);
+    tourViewer.removeEventListener("touchstart", interruptChangeTour);
+  }
+  document.removeEventListener("keydown", interruptChangeTour);
+  tourViewer = null;
+}
+
+function stopChangeTour() {
+  tourVersion++;
+  touring = false;
+  clearTimeout(tourTimer);
+  detachTourInterruption();
+  var focused = document.querySelectorAll(".markdown-live-focus");
+  for (var i = 0; i < focused.length; i++) focused[i].classList.remove("markdown-live-focus");
+}
+
+function interruptChangeTour() {
+  if (!touring) return;
+  stopChangeTour();
+  setStatus("updated", "Updated");
+  clearTimeout(cleanupTimer);
+  cleanupTimer = setTimeout(function () {
+    clearLiveClasses();
+    hideStatusSoon();
+  }, 1800);
+}
+
+function attachTourInterruption(viewer) {
+  tourViewer = viewer;
+  viewer.addEventListener("wheel", interruptChangeTour, { passive: true });
+  viewer.addEventListener("pointerdown", interruptChangeTour);
+  viewer.addEventListener("touchstart", interruptChangeTour, { passive: true });
+  document.addEventListener("keydown", interruptChangeTour);
+}
+
+export function changeTourDelay(text) {
+  var length = String(text || "").trim().length;
+  return Math.min(1800, Math.max(850, 700 + length * 3));
+}
+
+function startChangeTour(viewer, targets) {
+  stopChangeTour();
+  touring = true;
+  attachTourInterruption(viewer);
+  var version = tourVersion;
+  var index = 0;
+  var reduceMotion = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  function visitNext() {
+    if (!touring || version !== tourVersion) return;
+    if (index >= targets.length) {
+      var last = targets[targets.length - 1];
+      if (last && last.isConnected) {
+        last.classList.remove("markdown-live-focus");
+        last.classList.add("markdown-live-seen");
+      }
+      touring = false;
+      detachTourInterruption();
+      setStatus("updated", "Updated");
+      clearTimeout(cleanupTimer);
+      cleanupTimer = setTimeout(function () {
+        clearLiveClasses();
+        hideStatusSoon();
+      }, 1400);
+      return;
+    }
+
+    var previous = index > 0 ? targets[index - 1] : null;
+    if (previous && previous.isConnected) {
+      previous.classList.remove("markdown-live-focus");
+      previous.classList.add("markdown-live-seen");
+    }
+    var target = targets[index];
+    index++;
+    if (!target || !target.isConnected) {
+      visitNext();
+      return;
+    }
+    target.classList.add("markdown-live-focus");
+    setStatus("editing", "Change " + index + " of " + targets.length);
+    target.scrollIntoView({ behavior: reduceMotion ? "auto" : "smooth", block: "center" });
+    tourTimer = setTimeout(visitNext, reduceMotion ? 250 : changeTourDelay(target.textContent));
+  }
+
+  requestAnimationFrame(visitNext);
+}
+
+function changedRegionStart(matches, oldIndex) {
+  var newIndex = 0;
+  for (var i = 0; i < matches.length; i++) {
+    if (matches[i].oldIndex >= oldIndex) break;
+    newIndex = matches[i].newIndex + 1;
+  }
+  return newIndex;
+}
+
+export function animateMarkdownChange(markdownEl, oldMarkdown, newMarkdown, renderFn) {
+  if (!markdownEl || oldMarkdown === newMarkdown) return false;
+  clearLiveClasses();
+
+  var oldRoot = document.createElement("div");
+  var newRoot = document.createElement("div");
+  oldRoot.innerHTML = renderFn(oldMarkdown);
+  newRoot.innerHTML = renderFn(newMarkdown);
+
+  var oldBlocks = Array.from(oldRoot.children);
+  var newBlocks = Array.from(newRoot.children);
+  var liveBlocks = Array.from(markdownEl.children);
+  var oldSignatures = oldBlocks.map(blockSignature);
+  var newSignatures = newBlocks.map(blockSignature);
+  var matches = diffBlockSignatures(oldSignatures, newSignatures);
+  var matchedOld = new Set(matches.map(function (match) { return match.oldIndex; }));
+  var matchedNew = new Set(matches.map(function (match) { return match.newIndex; }));
+  for (var i = 0; i < liveBlocks.length; i++) {
+    if (matchedNew.has(i)) continue;
+    liveBlocks[i].classList.add("markdown-live-added");
+  }
+
+  for (var j = 0; j < oldBlocks.length; j++) {
+    if (matchedOld.has(j)) continue;
+    var clone = oldBlocks[j].cloneNode(true);
+    clone.classList.add("markdown-live-removed");
+    clone.setAttribute("aria-hidden", "true");
+    var insertionIndex = changedRegionStart(matches, j);
+    var anchor = insertionIndex < liveBlocks.length ? liveBlocks[insertionIndex] : null;
+    markdownEl.insertBefore(clone, anchor);
+  }
+
+  var changedTargets = Array.from(markdownEl.children).filter(function (element) {
+    return element.classList.contains("markdown-live-added") || element.classList.contains("markdown-live-removed");
+  });
+  if (changedTargets.length === 0) return false;
+  sawChange = true;
+  var hasRemoved = oldBlocks.length !== matchedOld.size;
+  var hasAdded = newBlocks.length !== matchedNew.size;
+  if (hasRemoved && hasAdded) {
+    for (var k = 0; k < liveBlocks.length; k++) {
+      if (!matchedNew.has(k)) liveBlocks[k].classList.add("markdown-live-changed");
+    }
+  }
+
+  clearTimeout(cleanupTimer);
+  startChangeTour(document.getElementById("file-viewer-body"), changedTargets);
+  return true;
+}

package/lib/public/modules/rich-clipboard.js

@@ -0,0 +1,83 @@
+import { renderMarkdown } from './markdown.js';
+import { showToast } from './utils.js';
+
+// Rich-text clipboards use HTML as their transport, but this payload contains
+// only Markdown semantics. Clay's rendered DOM, theme, syntax highlighting,
+// spacing, and typography never enter the clipboard.
+export function buildMarkdownClipboardContent(markdown) {
+  var container = document.createElement("div");
+  container.innerHTML = renderMarkdown(markdown || "");
+
+  var elements = container.querySelectorAll("*");
+  for (var i = 0; i < elements.length; i++) {
+    var el = elements[i];
+    el.removeAttribute("class");
+    el.removeAttribute("style");
+    el.removeAttribute("id");
+    el.removeAttribute("contenteditable");
+    el.removeAttribute("target");
+    el.removeAttribute("rel");
+    var dataNames = [];
+    for (var ai = 0; ai < el.attributes.length; ai++) {
+      if (el.attributes[ai].name.indexOf("data-") === 0) dataNames.push(el.attributes[ai].name);
+    }
+    for (var di = 0; di < dataNames.length; di++) el.removeAttribute(dataNames[di]);
+  }
+
+  return {
+    html: '<meta charset="utf-8">' + container.innerHTML,
+    text: container.innerText || container.textContent || "",
+  };
+}
+
+function legacyCopyHtml(html) {
+  var container = document.createElement("div");
+  container.contentEditable = "true";
+  container.style.cssText = "position:fixed;left:-10000px;top:0;width:1px;height:1px;overflow:hidden";
+  container.innerHTML = html;
+  document.body.appendChild(container);
+
+  var selection = window.getSelection();
+  var savedRanges = [];
+  for (var i = 0; selection && i < selection.rangeCount; i++) {
+    savedRanges.push(selection.getRangeAt(i).cloneRange());
+  }
+  var range = document.createRange();
+  range.selectNodeContents(container);
+  if (selection) {
+    selection.removeAllRanges();
+    selection.addRange(range);
+  }
+  var copied = document.execCommand("copy");
+  if (selection) {
+    selection.removeAllRanges();
+    for (var ri = 0; ri < savedRanges.length; ri++) selection.addRange(savedRanges[ri]);
+  }
+  container.remove();
+  if (!copied) return Promise.reject(new Error("Formatted copy is not supported by this browser"));
+  return Promise.resolve();
+}
+
+export function copyMarkdownFormatting(markdown) {
+  var content = buildMarkdownClipboardContent(markdown);
+  var copyPromise;
+
+  if (navigator.clipboard && navigator.clipboard.write && typeof ClipboardItem !== "undefined") {
+    var item = new ClipboardItem({
+      "text/html": new Blob([content.html], { type: "text/html" }),
+      "text/plain": new Blob([content.text], { type: "text/plain" }),
+    });
+    copyPromise = navigator.clipboard.write([item]).catch(function () {
+      return legacyCopyHtml(content.html);
+    });
+  } else {
+    copyPromise = legacyCopyHtml(content.html);
+  }
+
+  return copyPromise.then(function () {
+    showToast("Copied Markdown formatting");
+  }).catch(function (err) {
+    showToast("Could not copy Markdown formatting", "warn");
+    throw err;
+  });
+}

package/lib/sdk-bridge.js

@@ -577,6 +577,14 @@ function createSDKBridge(opts) {
       return { behavior: "allow", updatedInput: input };
     }
 
+    // This tool only prepares a read-only UI projection for the document the
+    // agent is about to edit. The subsequent Edit/Write keeps its own normal
+    // permission behavior.
+    if (toolName.indexOf("mcp__clay-documents__present_markdown_edit") === 0 ||
+        toolName.indexOf("clay-documents__present_markdown_edit") !== -1) {
+      return { behavior: "allow", updatedInput: input };
+    }
+
     // Auto-approve read-only email MCP tools.
     // These only read data from accounts the user explicitly checked.
     // Write operations (send, reply, mark_read) still require permission.

package/lib/session-document-mcp-server.js

@@ -0,0 +1,16 @@
+// Live Markdown presentation tool for project sessions.
+
+var buildShape = require("./session-spawn-mcp-server").buildShape;
+
+function getToolDefs(handlers) {
+  return [{
+    name: "present_markdown_edit",
+    description: "Call once per targeted document, immediately before its first Edit or Write, when the user's primary request is to create or revise Markdown. Pass the resolved .md or .mdx path. Do not call for incidental documentation changes made as part of coding, maintenance, tests, or refactoring. This prepares Clay's rendered document view so the user can watch every change.",
+    inputSchema: buildShape({
+      path: { type: "string", description: "Project-relative or absolute path to the Markdown document that will be edited." },
+    }, ["path"]),
+    handler: function (args) { return handlers.present(args || {}); },
+  }];
+}
+
+module.exports = { getToolDefs: getToolDefs };

package/lib/session-notes-mcp-server.js

@@ -2,7 +2,7 @@
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
 
-var MEMORY_CONTRACT = "Shared project memory that persists across sessions and is visible to the user and other Clay agents. People may use the board freely. As a Clay agent, use notes specifically for actionable or durable work memory: checklists and to-do lists, work goals, handoffs, unfinished work, durable decisions and constraints, and knowledge that should still be available after the current session ends. Every note starts with a concise plain-text title on the first line. Add a detailed body whenever another worker would otherwise need to reconstruct the context. Keep one coherent topic per note, update an existing note instead of adding a near-duplicate, and delete notes that stop being true. Do not use notes as a transcript, a routine progress log, or an announcement of your own activity.";
+var MEMORY_CONTRACT = "The sticky-note board persists across sessions and is a user-facing artifact shared with people and Clay agents, not private agent scratch space. Default to not writing. Create a note proactively only when the user explicitly asks to remember or track something, or when all of these are true: it will remain useful after the current task and session, it is not already adequately recorded in the repository or another note, and the user would likely be glad to find it on the board a week later. Good notes capture an unresolved commitment, durable product decision, user preference, constraint, or handoff that will materially change future work. Never create a note merely because work is important, lengthy, spans agents or restarts, or might help another agent. Do not record completed work, implementation details, test results, investigation logs, transient blockers, conversation summaries, or announcements of your own activity. When uncertain, do not write. Updates are visible too: update only when durable state materially changes, and remove a note created by your session when it stops being useful instead of turning it into a completion log. Put a concise plain-text title on the first line, stay focused on one topic, and include only the context needed for future action.";
 
 function getToolDefs(handlers) {
   return [
@@ -14,10 +14,10 @@ function getToolDefs(handlers) {
     },
     {
       name: "write_note",
-      description: MEMORY_CONTRACT + " Create a new note, or update an existing note by id. Long task and handoff notes are allowed, with a generous 20000-character abuse guard.",
+      description: MEMORY_CONTRACT + " Create a new note, or update an existing note by id. Before creating, apply this test: would the user likely choose to keep this visible on their board next week? If the answer is unclear, do not call this tool. The 20000-character limit is an abuse guard, not a target.",
       inputSchema: buildShape({
         id: { type: "string", description: "Existing note id to update. Omit to create a note." },
-        text: { type: "string", description: "Sticky-note text. Put the title on the first line, followed by the detailed handoff body. The board permits up to 20000 characters." },
+        text: { type: "string", description: "User-facing sticky-note text with a concise title on the first line and only durable, action-relevant context below it." },
         color: { type: "string", enum: ["yellow", "blue", "green", "pink", "orange", "purple"], description: "Optional sticky-note color." },
       }, ["text"]),
       handler: function (args) { return handlers.write(args || {}); },

package/lib/ws-schema.js

@@ -106,6 +106,7 @@ var schema = {
   "subagent_done":            { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Subagent task completed" },
   "task_started":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Background task started" },
   "task_progress":            { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Background task progress update" },
+  "markdown_edit_present":    { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Open a user-requested Markdown edit with a before snapshot" },
 
   // -----------------------------------------------------------------------
   // Permissions

package/lib/yoke/adapters/codex.js

@@ -470,6 +470,7 @@ function flattenEvent(notification, state) {
           toolName: "Edit",
           input: {
             changes: changeDesc,
+            file_paths: changes.map(function(c) { return c.path; }).filter(Boolean),
             file_path: primaryPath || undefined,
           },
         });
@@ -842,6 +843,8 @@ function createCodexQueryHandle(appServer, queryOpts) {
         permissionToolName = "mcp__clay-notes__" + permissionToolName;
       } else if (permissionToolName === "send_to_partner" || permissionToolName === "read_partner") {
         permissionToolName = "mcp__clay-sessions__" + permissionToolName;
+      } else if (permissionToolName === "present_markdown_edit") {
+        permissionToolName = "mcp__clay-documents__" + permissionToolName;
       }
       var permission = canUseTool
         ? Promise.resolve(canUseTool(permissionToolName, dynamicParams.arguments || {}, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js",