drafted 1.7.17 → 1.7.19

package/mcp/server.mjs

@@ -10,15 +10,17 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { execFile } from 'child_process';
 import { createHash } from 'node:crypto';
-import { readFileSync, existsSync, realpathSync } from 'fs';
+import { readFileSync, existsSync, realpathSync, writeFileSync, mkdirSync, unlinkSync, appendFileSync } from 'fs';
 import { join, dirname, basename, extname, resolve } from 'path';
-import { homedir } from 'os';
+import { homedir, platform, release as osRelease, arch as osArch } from 'os';
 import { fileURLToPath } from 'url';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
 import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 import WebSocket from 'ws';
 import { LAYERS } from '../src/shared/constants.mjs';
+import { emptyExcalidrawScene, excalidrawSceneFromMermaid, stringifyExcalidrawScene } from '../src/shared/excalidraw.mjs';
+import { UMAMI_EVENTS, trackUmamiEvent } from '../server/lib/umami.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -41,8 +43,8 @@ const PACKAGE_VERSION = (() => {
 const requestState = new AsyncLocalStorage();
 const standaloneState = { sessionId: null, projectId: null, projectMeta: null };
 
-// Per-MCP-session sticky state. Keyed by Clerk sessionId (HTTP /mcp route)
-// or '__stdio__' for the long-lived stdio process. Holds active-project,
+// Per-MCP-session sticky state. Keyed by the Drafted session id bound to
+// this MCP instance, or '__stdio__' for the long-lived stdio process. Holds active-project,
 // loaded-skill, and cached-org state that must persist across HTTP request
 // boundaries so a `project open` followed by `frame.read` in a separate
 // request still has an active project.
@@ -63,6 +65,7 @@ function getOrCreateSessionState(sid) {
       cachedOrgId: null,
       cachedOrgIdTime: 0,
       wsSessionId: null,
+      pendingDeviceCode: null,
     };
     sessionStates.set(key, s);
   }
@@ -99,6 +102,7 @@ export function runWithRequestState(initial, fn) {
 // Stdio mode uses the `mcpServer` singleton (built once at module load).
 
 export function createMcpServer() {
+trackUmamiEvent(UMAMI_EVENTS.MCP_CONNECTED, { source: 'mcp' });
 const server = new McpServer({
   name: 'drafted',
   version: PACKAGE_VERSION,
@@ -112,6 +116,9 @@ SKILLS: Drafted has a skill library -- reusable agent instructions stored as SKI
 
 BREADCRUMBS: When a frame you write or read corresponds to a file in the user's codebase (a component spec, wireframe for a route, design doc for a module), leave a comment in that code file using the canonical token "drafted:<frameId>" wrapped in the file's comment syntax (e.g. "// drafted:abc-123..." for JS/TS, "# drafted:abc-123..." for Python/YAML, "<!-- drafted:abc-123... -->" for HTML/Markdown). Project-level references use "drafted-project:<projectId>" in the project README or CLAUDE.md. Future agents grepping for "drafted:" will discover the link and can pull the frame via read(<frameId>). One line per related frame. Skip for throwaway or exploratory frames.
 
+CONTEXT RULES (follow these before every action):
+  - WIKI CHECK: Before acting on any request, search the org wiki for relevant conventions, existing designs, and prior decisions. Use wiki(action="search") with relevant keywords.
+  - LAYER CONTEXT: Before reading or mutating a frame, read all anchored frames in the same layer. Anchored frames are per-layer required reading (style guides, design systems, conventions). The server enforces this mechanically for writes/edits/deletes/moves — but proactively reading anchored frames before any frame operation prevents wasted work.
 IMPORTANT: Any URL containing /f/{uuid} is a Drafted frame link — ALWAYS use read(path=URL) to get frame content, focus(target=URL) to pan the canvas to it. Never curl or WebFetch Drafted URLs.`,
 });
 
@@ -129,11 +136,11 @@ const layerKeys = Object.keys(LAYERS);
 
 const TOOL_ANNOTATIONS = {
   // Auth — initiates external browser / email flows
-  auth:                { title: 'Sign in',             readOnlyHint: false, destructiveHint: false, openWorldHint: true,  description: 'Sign in to Drafted. `action=get_link` returns a URL for manual sign-in (SSH/headless); `action=login` opens a browser and polls for approval.' },
+  auth:                { title: 'Sign in',             readOnlyHint: false, destructiveHint: false, openWorldHint: true,  description: 'Sign in to Drafted. `action=get_link` returns a URL immediately and starts background approval polling; after the user opens the link, later Drafted tool calls also auto-consume the approved login. `action=login` opens a browser when needed and explicitly waits/polls for approval.' },
 
   // Projects
   project:             { title: 'Projects',            readOnlyHint: false, destructiveHint: false, openWorldHint: false, widgetUri: 'ui://widget/drafted-canvas-overview.html', description: 'Manage projects: list (start here), open (switch active project), create, update, move to another org.' },
-  get_org:             { title: 'Organization',        readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Get the active organization (action="get", default) or switch to a different org (action="switch", orgId=...). Use switch when you need wiki/skill work in an org that has no projects — opening a project also switches, but is unavailable in empty orgs.' },
+  get_org:             { title: 'Organization',        readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Get the active organization (action="get", default), Google Drive availability, or switch to a different org (action="switch", orgId=...). Use switch when you need wiki/skill work in an org that has no projects — opening a project also switches, but is unavailable in empty orgs. When googleDrive.connected is true, strongly prefer Google Workspace frames for documents, sheets, and slides.' },
 
   // Templates
   template:            { title: 'Templates',            readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage project templates: list, create, update, delete, fork.' },
@@ -143,7 +150,7 @@ const TOOL_ANNOTATIONS = {
 
   // Frames — filesystem
   ls:                  { title: 'List frames',         readOnlyHint: true,  destructiveHint: false, openWorldHint: false, widgetUri: 'ui://widget/drafted-canvas-overview.html' },
-  frame:               { title: 'Frames',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, widgetUri: 'ui://widget/drafted-frame-preview.html', description: 'Read, write, edit, move, anchor, or search frames in the ACTIVE PROJECT. Dispatch by `action`. Use `ls` to browse, `rm` to delete.' },
+  frame:               { title: 'Frames',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, widgetUri: 'ui://widget/drafted-frame-preview.html', description: 'Read, write, edit, move, anchor, search, or restore frame versions in the ACTIVE PROJECT. Dispatch by `action`. Use `ls` to browse, `rm` to delete.' },
   rm:                  { title: 'Delete frame',        readOnlyHint: false, destructiveHint: true,  openWorldHint: false },
   // batch:               { title: 'Batch operations',   readOnlyHint: false, destructiveHint: true,  openWorldHint: false },
 
@@ -193,7 +200,18 @@ function tool(name, descOrSchema, schemaOrHandler, handler) {
   if (ann.widgetUri) {
     config._meta = { 'ui': { resourceUri: ann.widgetUri } };
   }
-  return server.registerTool(name, config, cb);
+  return server.registerTool(name, config, async (...args) => {
+    const state = getState();
+    const previousTool = state.currentTool;
+    state.currentTool = name;
+    trackUmamiEvent(UMAMI_EVENTS.MCP_TOOL_CALLED, { tool: name, projectId: state.projectId || undefined, source: 'mcp' });
+    reportInstallationEvent(UMAMI_EVENTS.DRAFTED_MCP_REQUEST, { tool: name });
+    try {
+      return await cb(...args);
+    } finally {
+      state.currentTool = previousTool;
+    }
+  });
 }
 
 // ── ChatGPT Apps SDK widgets ──────────────────────────────────────
@@ -255,20 +273,147 @@ registerAppResource(
 // ── Config ────────────────────────────────────────────────────────
 
 const AUTH_FILE = process.env.DRAFTED_AUTH_FILE || join(homedir(), '.drafted', 'auth.json');
+const PENDING_AUTH_FILE = process.env.DRAFTED_PENDING_AUTH_FILE || `${AUTH_FILE}.pending`;
 
 function getServerUrl() {
   if (process.env.DRAFTED_SERVER) return process.env.DRAFTED_SERVER.replace(/\/$/, '');
+  if (getState().publicUrl) return getState().publicUrl.replace(/\/$/, '');
+  if (process.env.DRAFTED_PUBLIC_URL) return process.env.DRAFTED_PUBLIC_URL.replace(/\/$/, '');
+  if (process.env.BASE_URL) return process.env.BASE_URL.replace(/\/$/, '');
+  if (process.env.APP_URL) return process.env.APP_URL.replace(/\/$/, '');
   // Read from config.json next to auth.json (written by install-mcp.sh)
   try {
     const cfgPath = join(homedir(), '.drafted', 'config.json');
     if (existsSync(cfgPath)) {
       const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
       if (cfg.server) return cfg.server.replace(/\/$/, '');
+      if (cfg.publicUrl) return cfg.publicUrl.replace(/\/$/, '');
     }
   } catch { /* fall through */ }
   return `http://localhost:${process.env.DRAFTED_PORT || 3477}`;
 }
 
+function getInstallInfo() {
+  if (process.env.DRAFTED_TELEMETRY === '0') return null;
+  try {
+    const installPath = join(homedir(), '.drafted', 'install.json');
+    if (!existsSync(installPath)) return null;
+    const info = JSON.parse(readFileSync(installPath, 'utf8'));
+    if (info.telemetry === false) return null;
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(info.installId || ''))) return null;
+    return info;
+  } catch {
+    return null;
+  }
+}
+
+
+function osFamily() {
+  const p = platform();
+  if (p === 'darwin') return 'macos';
+  if (p === 'win32') return 'windows';
+  if (p === 'linux') return 'linux';
+  return 'unknown';
+}
+
+function normalizedArch() {
+  const a = osArch();
+  return ['x64', 'arm64', 'arm', 'ia32'].includes(a) ? a : 'unknown';
+}
+
+function mcpMode() {
+  return process.argv.includes('--http') ? 'http' : 'stdio';
+}
+
+function reportInstallationEvent(event, extra = {}) {
+  const info = getInstallInfo();
+  if (!info) return;
+  fetch(`${getServerUrl()}/api/installations/report`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'User-Agent': `Drafted MCP/${PACKAGE_VERSION}` },
+    body: JSON.stringify({
+      installId: info.installId,
+      event,
+      schemaVersion: 1,
+      cliVersion: PACKAGE_VERSION,
+      osFamily: osFamily(),
+      osVersion: osRelease().slice(0, 60),
+      arch: normalizedArch(),
+      nodeVersion: process.version,
+      mcpMode: mcpMode(),
+      source: 'mcp',
+      ...extra,
+    }),
+  }).catch(() => {});
+}
+
+function classifyMcpError(error) {
+  const msg = String(error?.message || error || '').toLowerCase();
+  const causeCode = String(error?.cause?.code || error?.code || '').toLowerCase();
+  if (causeCode) return causeCode.slice(0, 80);
+  if (msg.includes('fetch failed')) return 'fetch_failed';
+  if (msg.includes('failed to fetch')) return 'fetch_failed';
+  if (msg.includes('network')) return 'network_error';
+  if (msg.includes('timeout') || msg.includes('timed out')) return 'timeout';
+  const httpMatch = msg.match(/http\s+(\d{3})/);
+  if (httpMatch) return `http_${httpMatch[1]}`;
+  if (msg.includes('unauthorized') || msg.includes('401')) return 'auth_401';
+  if (msg.includes('forbidden') || msg.includes('403')) return 'auth_403';
+  return 'tool_error';
+}
+
+function scrubLogValue(value) {
+  if (typeof value !== 'string') return value;
+  return value
+    .replace(/([?&](?:token|code|dci|session|auth|password|secret)=)[^&\s]+/gi, '$1[Filtered]')
+    .replace(/(Bearer\s+)[A-Za-z0-9._~+\/-]+=*/gi, '$1[Filtered]')
+    .replace(/(gc_session=)[^;\s]+/gi, '$1[Filtered]')
+    .slice(0, 500);
+}
+
+function serverOriginForLog() {
+  try { return new URL(getServerUrl()).origin; } catch { return 'invalid_server_url'; }
+}
+
+function writeMcpClientLog(tool, error) {
+  const entry = {
+    ts: new Date().toISOString(),
+    level: 'error',
+    component: 'drafted-mcp-client',
+    version: PACKAGE_VERSION,
+    tool: String(tool || 'unknown').slice(0, 80),
+    errorCode: classifyMcpError(error),
+    message: scrubLogValue(error?.message || String(error)),
+    causeCode: scrubLogValue(error?.cause?.code || error?.code || ''),
+    causeMessage: scrubLogValue(error?.cause?.message || ''),
+    server: serverOriginForLog(),
+    osFamily: osFamily(),
+    nodeVersion: process.version,
+    mcpMode: mcpMode(),
+  };
+  const line = `[Drafted MCP] ${JSON.stringify(entry)}\n`;
+  try { console.error(line.trimEnd()); } catch { /* ignore */ }
+  try {
+    const logPath = join(homedir(), '.drafted', 'mcp-client.log');
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, line, { mode: 0o600 });
+  } catch { /* best effort */ }
+}
+
+function reportMcpToolError(tool, error) {
+  writeMcpClientLog(tool, error);
+  reportInstallationEvent(UMAMI_EVENTS.DRAFTED_MCP_ERROR, {
+    tool: String(tool || 'unknown').slice(0, 80),
+    errorCode: classifyMcpError(error),
+  });
+}
+
+function wikiBrowserUrl(path = '') {
+  const normalized = normalizeWikiPath(path || '');
+  if (!normalized) return `${getServerUrl()}/wiki`;
+  return `${getServerUrl()}/wiki/${normalized.split('/').map(encodeURIComponent).join('/')}`;
+}
+
 function getBootstrapSessionId() {
   try {
     if (existsSync(AUTH_FILE)) {
@@ -279,6 +424,87 @@ function getBootstrapSessionId() {
   return null;
 }
 
+function persistAuthSession(data) {
+  mkdirSync(dirname(AUTH_FILE), { recursive: true });
+  writeFileSync(AUTH_FILE, JSON.stringify({
+    sessionId: data.sessionId,
+    userId: data.userId || null,
+    orgId: data.orgId || null,
+    server: getServerUrl(),
+    updatedAt: new Date().toISOString(),
+  }, null, 2), { mode: 0o600 });
+}
+
+function persistPendingDeviceCode(data) {
+  if (!data?.deviceCode) return;
+  const pending = {
+    ...data,
+    server: getServerUrl(),
+    createdAt: Date.now(),
+    expiresAt: Date.now() + (Number(data.expiresIn || 900) * 1000),
+  };
+  getSessionState().pendingDeviceCode = pending;
+  try {
+    mkdirSync(dirname(PENDING_AUTH_FILE), { recursive: true });
+    writeFileSync(PENDING_AUTH_FILE, JSON.stringify(pending, null, 2), { mode: 0o600 });
+  } catch { /* best effort; in-memory state still works for long-lived stdio */ }
+  schedulePendingAuthPoll(2000);
+}
+
+function clearPendingDeviceCode() {
+  stopPendingAuthPoll();
+  getSessionState().pendingDeviceCode = null;
+  try { if (existsSync(PENDING_AUTH_FILE)) unlinkSync(PENDING_AUTH_FILE); } catch { /* ignore */ }
+}
+
+function getPendingDeviceCode() {
+  const inMemory = getSessionState().pendingDeviceCode;
+  if (inMemory?.deviceCode) return inMemory;
+  try {
+    if (!existsSync(PENDING_AUTH_FILE)) return null;
+    const pending = JSON.parse(readFileSync(PENDING_AUTH_FILE, 'utf8'));
+    if (!pending?.deviceCode) return null;
+    if (pending.server && pending.server !== getServerUrl()) return null;
+    if (pending.expiresAt && Date.now() > Number(pending.expiresAt)) {
+      clearPendingDeviceCode();
+      return null;
+    }
+    getSessionState().pendingDeviceCode = pending;
+    return pending;
+  } catch {
+    return null;
+  }
+}
+
+
+let pendingAuthPollTimer = null;
+
+function stopPendingAuthPoll() {
+  if (pendingAuthPollTimer) clearTimeout(pendingAuthPollTimer);
+  pendingAuthPollTimer = null;
+}
+
+function schedulePendingAuthPoll(delayMs = 2000) {
+  stopPendingAuthPoll();
+  pendingAuthPollTimer = setTimeout(async () => {
+    pendingAuthPollTimer = null;
+    const pending = getPendingDeviceCode();
+    if (!pending?.deviceCode) return;
+    const approved = await consumePendingDeviceCode();
+    if (approved) {
+      try { connectAgentWs().catch(() => {}); } catch { /* ignore */ }
+      return;
+    }
+    const expiresAt = Number(pending.expiresAt || 0);
+    if (expiresAt && Date.now() >= expiresAt) {
+      clearPendingDeviceCode();
+      return;
+    }
+    schedulePendingAuthPoll(2000);
+  }, delayMs);
+  if (typeof pendingAuthPollTimer.unref === 'function') pendingAuthPollTimer.unref();
+}
+
 function getAuthHeaders() {
   const sid = getState().sessionId || getBootstrapSessionId();
   if (sid) return { Cookie: `gc_session=${sid}` };
@@ -304,6 +530,8 @@ async function cloneSession() {
 }
 
 async function ensureSession() {
+  if (getState().sessionId) return;
+  await consumePendingDeviceCode();
   if (getState().sessionId) return;
   await cloneSession();
 }
@@ -335,10 +563,13 @@ async function api(method, path, body, _retried) {
   const res = await fetch(url, opts);
   const text = await res.text();
 
-  // Session expired after server restart — re-clone and retry once
+  // Session expired after server restart, or a browser approval just completed
+  // for auth(action="get_link"). First try to consume any pending device code,
+  // then fall back to cloning the saved browser session, and retry once.
   if (res.status === 401 && !_retried) {
     getState().sessionId = null;
-    await cloneSession();
+    const approved = await consumePendingDeviceCode();
+    if (!approved) await cloneSession();
     return api(method, path, body, true);
   }
 
@@ -398,6 +629,22 @@ function ok(text, opts) {
   return result;
 }
 
+function summarizeSkillForSearch(skill) {
+  if (!skill || typeof skill !== 'object') return skill;
+  return {
+    id: skill.id,
+    orgId: skill.orgId ?? null,
+    name: skill.name,
+    slug: skill.slug,
+    description: skill.description,
+    tags: skill.tags || [],
+    triggerPatterns: skill.triggerPatterns || [],
+    version: skill.version,
+    updatedAt: skill.updatedAt,
+    fileCount: Array.isArray(skill.files) ? skill.files.length : undefined,
+  };
+}
+
 // Build the structuredContent shape that the frame-preview widget reads.
 // Tools that produce or return a frame (read/write/edit) call this so the
 // model and widget see the same metadata view.
@@ -545,6 +792,7 @@ if (!globalThis.__draftedAgentWsBootstrapped) {
 }
 
 function err(error) {
+  reportMcpToolError(getState().currentTool, error);
   return { content: [{ type: 'text', text: error.message || String(error) }], isError: true };
 }
 
@@ -694,7 +942,7 @@ function applyHashlineOps(content, operations) {
   let lines = content.split('\n');
   const lineToHash = {};
   for (let i = 0; i < lines.length; i++) {
-    lineToHash[i] = createHash('sha256').update(lines[i] || '').digest('hex').slice(0, 4);
+    lineToHash[i] = createHash('sha256').update(lines[i] || '').digest('hex').slice(0, 12);
   }
   const sorted = [...operations].reverse();
   for (const op of sorted) {
@@ -744,10 +992,49 @@ function runCLI(command, args = [], options = {}) {
 
 // ── Login tools ─────────────────────────────────────────────────────
 
-// Shared pending device code — auth(action=get_link) stores it, auth(action=login) reuses it
-let pendingDeviceCode = null;
+// Per-session pending device code — auth(action=get_link) stores it, and
+// auth(action=login) or a later tool call can consume it.
+//
+// This prevents the "I already authed" loop after get_link: once the user
+// finishes the browser step, the next tool call can exchange the approved
+// device code for a Drafted session automatically.
+//
+// SCOPE: This `auth` tool is for the stdio path only — when drafted-mcp runs
+// as a local Node process (npm-installed `drafted-mcp` for self-hosters,
+// Cursor/VS Code one-click installs that use stdio). The Claude Code plugin
+// has used HTTP MCP since v1.7.17 and authenticates via Clerk OAuth at the
+// MCP protocol layer (handled by Claude Code itself, see src/middleware/oauth.ts).
+// HTTP-mode callers never reach this tool because Clerk gates all /mcp tool
+// calls before authentication. Don't add new auth flows here — add them to
+// src/auth/clerk.ts instead.
+
+async function consumePendingDeviceCode() {
+  const pending = getPendingDeviceCode();
+  if (!pending?.deviceCode) return false;
 
-tool('auth', 'Sign in to Drafted. `action=get_link` returns a verification URL immediately (use for SSH/headless/tmux where a browser may not open). `action=login` opens a browser and polls for approval — run this if other tools return auth errors or "fetch failed". If get_link was called first, login reuses that pending code instead of opening a new browser.', {
+  try {
+    const res = await fetch(`${getServerUrl()}/auth/device/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ deviceCode: pending.deviceCode }),
+    });
+    if (!res.ok) return false;
+    const data = await res.json();
+    if (data.status === 'approved' && data.sessionId) {
+      persistAuthSession(data);
+      getState().sessionId = data.sessionId;
+      clearPendingDeviceCode();
+      return true;
+    }
+    if (data.status === 'expired') {
+      clearPendingDeviceCode();
+    }
+  } catch { /* ignore and fall through */ }
+
+  return false;
+}
+
+tool('auth', 'Sign in to Drafted. `action=get_link` returns a verification URL immediately (use for SSH/headless/tmux where a browser may not open) and starts background polling; after the user opens the link, later Drafted tool calls also auto-consume the approved login. `action=login` opens a browser when needed and explicitly waits/polls for approval. If get_link was called first, login reuses that pending code instead of opening a new browser.', {
   action: z.enum(['get_link', 'login']).describe('Operation to perform.'),
 }, async ({ action }) => {
   try {
@@ -755,7 +1042,7 @@ tool('auth', 'Sign in to Drafted. `action=get_link` returns a verification URL i
       const codeRes = await fetch(`${getServerUrl()}/auth/device/code`, { method: 'POST' });
       if (!codeRes.ok) throw new Error(`Failed to start device authorization (HTTP ${codeRes.status})`);
       const data = await codeRes.json();
-      pendingDeviceCode = data;
+      persistPendingDeviceCode(data);
       return ok(data.verificationUrl);
     }
     if (action === 'login') {
@@ -775,9 +1062,9 @@ tool('auth', 'Sign in to Drafted. `action=get_link` returns a verification URL i
       let deviceCode, verificationUrl, expiresIn;
       let reusingPending = false;
 
-      if (pendingDeviceCode) {
-        ({ deviceCode, verificationUrl, expiresIn } = pendingDeviceCode);
-        pendingDeviceCode = null;
+      const pending = getPendingDeviceCode();
+      if (pending) {
+        ({ deviceCode, verificationUrl, expiresIn } = pending);
         reusingPending = true;
       } else {
         const codeRes = await fetch(`${getServerUrl()}/auth/device/code`, { method: 'POST' });
@@ -813,16 +1100,8 @@ tool('auth', 'Sign in to Drafted. `action=get_link` returns a verification URL i
         const data = await res.json();
 
         if (data.status === 'approved') {
-          const { writeFileSync, mkdirSync } = await import('fs');
-          const { dirname } = await import('path');
-          mkdirSync(dirname(AUTH_FILE), { recursive: true });
-          writeFileSync(AUTH_FILE, JSON.stringify({
-            sessionId: data.sessionId,
-            userId: data.userId || null,
-            orgId: data.orgId || null,
-            server: getServerUrl(),
-            updatedAt: new Date().toISOString(),
-          }, null, 2));
+          persistAuthSession(data);
+          clearPendingDeviceCode();
 
           getState().sessionId = null;
           await cloneSession();
@@ -1171,7 +1450,7 @@ tool('layer', 'Manage layers in a project. Dispatch by `action`: add/update/remo
           const listing = await api('GET', `/api/fs?path=/${key}&projectId=${projectId}&recursive=true`);
           const entries = listing.entries || [];
           const frames = entries.filter(e => e.type === 'frame');
-          const realFrames = frames.filter(f => !f.path.endsWith('/_meta/_context.md') && !f.path.endsWith('/instructions/context.md'));
+          const realFrames = frames.filter(f => !f.path.endsWith('/_meta/_context.md') && !f.path.endsWith('/instructions/context.md') && !f.path.endsWith('/instructions/AGENTS.md') && !f.path.endsWith('/AGENTS.md'));
           const frameCount = realFrames.length;
           if (frameCount > 0) {
             throw new Error(`Layer "${key}" contains ${frameCount} frame(s). Use force: true to confirm deletion.`);
@@ -1209,6 +1488,32 @@ tool('layer', 'Manage layers in a project. Dispatch by `action`: add/update/remo
   } catch (error) { return err(error); }
 });
 
+
+async function getGoogleDriveAvailability() {
+  try {
+    const status = await api('GET', '/api/google/status');
+    return {
+      connected: !!status?.connected,
+      syncEnabled: !!status?.syncEnabled,
+      driveRootFolderId: status?.driveRootFolderId || null,
+      driveRootFolderName: status?.driveRootFolderName || null,
+      workspaceFramesAvailable: !!status?.connected,
+      preference: status?.connected
+        ? 'Strongly prefer Google Workspace frames for docs, sheets, and slides in this org.'
+        : 'Google Drive is not connected; use normal Drafted frames.',
+    };
+  } catch {
+    return {
+      connected: false,
+      syncEnabled: false,
+      driveRootFolderId: null,
+      driveRootFolderName: null,
+      workspaceFramesAvailable: false,
+      preference: 'Google Drive status unavailable; use normal Drafted frames unless a Google Workspace frame succeeds.',
+    };
+  }
+}
+
 tool('get_org', {
   action: z.enum(['get', 'switch']).optional().describe('Default: "get" returns active org and member info. Use "switch" with orgId to change the active org without opening a project.'),
   orgId: z.string().optional().describe('[switch] target org ID to switch to. Must be one of the orgs the user is a member of.'),
@@ -1229,7 +1534,8 @@ tool('get_org', {
       const me = await api('GET', '/auth/me');
       const orgs = (await api('GET', '/api/orgs')).orgs || [];
       const activeOrg = (orgs || []).map(o => ({ id: o.orgId || o.id, name: o.orgName || o.name })).find(o => o.id === me?.orgId) || null;
-      return ok({ switched: true, activeOrg, note: 'Active org switched. Wiki and skill calls now target this org. Active project cleared — open a project (or stay org-scoped for wiki/skill).' });
+      const googleDrive = await getGoogleDriveAvailability();
+      return ok({ switched: true, activeOrg, googleDrive, note: 'Active org switched. Wiki and skill calls now target this org. Active project cleared — open a project (or stay org-scoped for wiki/skill). If googleDrive.connected is true, prefer Google Workspace frames for docs, sheets, and slides.' });
     }
 
     // Source of truth = THIS MCP session's bound org (what mutations will actually
@@ -1242,6 +1548,8 @@ tool('get_org', {
     const orgs = (data.orgs || data || []).map(o => ({ id: o.orgId || o.id, name: o.orgName || o.name }));
     const activeOrg = sessionOrgId ? (orgs.find(o => o.id === sessionOrgId) || null) : null;
 
+    const googleDrive = await getGoogleDriveAvailability();
+
     let members = [];
     if (sessionOrgId) {
       try {
@@ -1253,27 +1561,34 @@ tool('get_org', {
       activeOrg,
       orgs,
       members: members.map(m => ({ id: m.userId, name: m.username, email: m.email, role: m.role })),
+      googleDrive,
       mcpVersion: PACKAGE_VERSION,
-      note: "activeOrg is the org bound to THIS MCP session — what mutations will actually target. To switch orgs without creating a project, call get_org(action=\"switch\", orgId=\"...\"). Browser tabs and other MCP sessions for the same user can be on different orgs.",
+      note: "activeOrg is the org bound to THIS MCP session — what mutations will actually target. To switch orgs without creating a project, call get_org(action=\"switch\", orgId=\"...\"). Browser tabs and other MCP sessions for the same user can be on different orgs. If googleDrive.connected is true, strongly prefer Google Workspace frames for docs, sheets, and slides.",
     });
   } catch (error) { return err(error); }
 });
 
 // ── Filesystem tools (direct HTTP to /api/fs) ─────────────────────
 
-tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by path, frame URL, or UUID), write (new frame or overwrite), edit (hashline ops), mv (rename/move), anchor (mark as required-read for the layer), search (match frame names). Use project(action="open") first. For listing use `ls`, for deletion use `rm`.\n\n**Write — content or file:** Provide `content` (HTML/markdown/text) OR `file_path` (absolute path to a local file like a PNG screenshot). For binary files (images, PDFs), use `file_path` — uploaded to storage and displayed as an asset frame.\n\n**Write — dimensions:** By default, frames use the layer\'s default size (e.g. 1440×900 for designs, 1440×3000 for wireframes). Often too large for small content. Use `autoSize: true` to measure HTML content and size to fit, or pass explicit `width`/`height`.', {
-  action: z.enum(['read', 'write', 'edit', 'mv', 'anchor', 'search']).describe('Operation to perform.'),
+tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by path, frame URL, or UUID), write (new frame or overwrite), write_excalidraw (native editable Excalidraw diagram), edit (hashline ops), mv (rename/move), anchor (mark as required-read for the layer), search (match frame names). Use project(action="open") first. For listing use `ls`, for deletion use `rm`.\n\n**Write — content, file, or Google Workspace frame:** Provide `content` (HTML/markdown/text), `file_path` (absolute path to a local file), `googleType` (`google-doc`, `google-sheet`, `google-slide`), OR `write_excalidraw` with `excalidraw_data` or `mermaid`. Call get_org first; when `googleDrive.connected` is true, strongly prefer Google Workspace frames for business artifacts: use `google-doc` for memos/reports/briefs/SOPs/proposals, `google-sheet` for tables/trackers/budgets/research matrices/models, and `google-slide` for decks/presentation outlines. For inline content, filename extension matters: use `.html` for complete HTML documents and `.md` for Markdown. Never place a full HTML document in a `.md` or extensionless frame. For a new Google file, pass `googleType` and optional `title`; for an existing Google file, pass `googleType` plus `url` or `googleId`. For binary files (images, PDFs), use `file_path` — uploaded to storage and displayed as an asset frame.\n\n**Write — dimensions:** By default, frames use the layer\'s default size (e.g. 1440×900 for designs, 1440×3000 for wireframes). Often too large for small content. Use `autoSize: true` to measure HTML content and size to fit, or pass explicit `width`/`height`.', {
+  action: z.enum(['read', 'write', 'write_excalidraw', 'edit', 'mv', 'anchor', 'search', 'versions', 'read_version', 'restore_version']).describe('Operation to perform.'),
   path: z.string().optional().describe('[read] /{layer}/{lane}/{filename}, frame URL, or UUID. [write|edit|anchor] /{layer}/{lane}/{filename}.'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50"). Omit to read all.'),
-  content: z.string().optional().describe('[write] HTML/markdown/text. Mutually exclusive with file_path.'),
+  content: z.string().optional().describe('[write] HTML/markdown/text. Mutually exclusive with file_path. Use a .html path for complete HTML documents and a .md path for Markdown.'),
+  excalidraw_data: z.any().optional().describe('[write_excalidraw] Excalidraw scene JSON object or JSON string. Defaults to an empty scene.'),
+  mermaid: z.string().optional().describe('[write_excalidraw] Mermaid source to convert into an editable Excalidraw scene.'),
   file_path: z.string().optional().describe('[write] absolute path to a local file to upload. Mutually exclusive with content.'),
+  googleType: z.enum(['google-doc', 'google-sheet', 'google-slide']).optional().describe('[write] Create or attach a native Google Workspace frame. Use with title to create new, or url/googleId to attach existing.'),
+  title: z.string().optional().describe('[write + googleType] Title for a new Google Doc/Sheet/Slide. Defaults to filename from path.'),
+  url: z.string().optional().describe('[write + googleType] Existing Google Doc/Sheet/Slide URL to attach.'),
+  googleId: z.string().optional().describe('[write + googleType] Existing Google file ID to attach.'),
   autoSize: z.boolean().optional().describe('[write] measure HTML content and size frame to fit. Content only, not file_path.'),
   width: z.number().optional().describe('[write] explicit width in pixels. Overrides layer default. Ignored if autoSize=true.'),
   height: z.number().optional().describe('[write] explicit height in pixels. Overrides layer default. Ignored if autoSize=true.'),
   color: z.string().optional().describe('[write] CSS color for frame border (e.g. #ff0000, red).'),
   operations: z.array(z.object({
     type: z.enum(['replace', 'delete', 'insertAfter', 'insertBefore']).describe('Edit type'),
-    lineHash: z.string().describe('4-char hash of the target line (from read output). Each line has a unique hash.'),
+    lineHash: z.string().describe('Hash of the target line (from read output). Use the full hash to avoid ambiguity in large frames.'),
     newContent: z.string().optional().describe('New content (for replace, insertAfter, insertBefore)'),
   })).optional().describe('[edit] hashline edit operations'),
   from: z.string().optional().describe('[mv] source path /{layer}/{lane}/{filename}'),
@@ -1283,6 +1598,8 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
   query: z.string().optional().describe('[search] term to match against frame names'),
   projectId: z.string().optional().describe('[search] limit to a specific project (optional)'),
   limit: z.number().optional().describe('[search] max results (default 50, max 200)'),
+  versionId: z.string().optional().describe('[read_version|restore_version] version id'),
+  reason: z.string().optional().describe('[restore_version] reason recorded on the snapshot of current content'),
 }, async (args) => {
   try {
     const { action } = args;
@@ -1330,28 +1647,55 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
         });
       }
       case 'write': {
-        const { path, content, file_path, autoSize, width, height, color } = args;
+        const { path, content, file_path, autoSize, width, height, color, googleType, title, url, googleId } = args;
         if (!path) throw new Error('path required for action=write');
-        if (content != null && file_path) throw new Error('Provide content OR file_path, not both');
-        if (content == null && !file_path) throw new Error('Provide content or file_path');
+        const writeSources = [content != null, !!file_path, !!googleType].filter(Boolean).length;
+        if (writeSources > 1) throw new Error('Provide only one of content, file_path, or googleType');
+        if (writeSources === 0) throw new Error('Provide content, file_path, or googleType');
         const skillErr = await checkProjectSkills(getState().projectId);
         if (skillErr) return err(new Error(skillErr));
         const anchorErr = await checkAnchors(parseLayer(path));
         if (anchorErr) return err(new Error(anchorErr));
         const parts = path.replace(/^\/+/, '').split('/');
         if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}');
+        if (googleType) {
+          const projectId = getState().projectId;
+          if (!projectId) throw new Error('Open a project first with project(action="open") before creating Google Workspace frames');
+          const label = basename(parts[2], extname(parts[2])) || parts[2];
+          const body = {
+            projectId,
+            layer: parts[0],
+            lane: parts[1],
+            label,
+            type: googleType,
+            width,
+            height,
+          };
+          const result = url || googleId
+            ? await api('POST', '/api/google/workspace/frame', { ...body, url, googleId })
+            : await api('POST', '/api/google/workspace/create-frame', { ...body, title: title || label });
+          return ok(withProject(withFrameBreadcrumb({
+            ...result,
+            path,
+            label,
+            contentType: 'text/html',
+            sourceType: googleType,
+          }, { hint: true })), {
+            structuredContent: frameStructuredContent({ ...result, path, label, contentType: 'text/html' }, projectCtx),
+          });
+        }
         let body;
         if (file_path) {
           const resolved = resolve(file_path);
           if (!existsSync(resolved)) throw new Error(`File not found: ${resolved}`);
           const ext = extname(resolved).toLowerCase();
-          const TEXT_EXTS = ['.html', '.htm', '.svg', '.md', '.markdown', '.txt', '.css', '.js', '.mjs', '.json', '.xml'];
+          const TEXT_EXTS = ['.html', '.htm', '.md', '.markdown', '.txt', '.css', '.js', '.mjs', '.json', '.xml', '.excalidraw'];
           if (TEXT_EXTS.includes(ext)) {
             body = { content: readFileSync(resolved, 'utf8') };
             if (autoSize) body.autoSize = true;
           } else {
             const buffer = readFileSync(resolved);
-            const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.pdf': 'application/pdf' };
+            const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf', '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.m4v': 'video/x-m4v' };
             body = { base64: buffer.toString('base64'), contentType: MIME[ext] || 'application/octet-stream' };
           }
         } else {
@@ -1367,6 +1711,28 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
           _meta: body.content ? { frameHtml: body.content } : undefined,
         });
       }
+      case 'write_excalidraw': {
+        const { path, excalidraw_data, mermaid, width, height, color } = args;
+        if (!path) throw new Error('path required for action=write_excalidraw');
+        if (excalidraw_data != null && mermaid) throw new Error('Provide only one of excalidraw_data or mermaid');
+        const skillErr = await checkProjectSkills(getState().projectId);
+        if (skillErr) return err(new Error(skillErr));
+        const anchorErr = await checkAnchors(parseLayer(path));
+        if (anchorErr) return err(new Error(anchorErr));
+        const parts = path.replace(/^\/+/, '').split('/');
+        if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}');
+        const filename = parts[2].toLowerCase().endsWith('.excalidraw') ? parts[2] : parts[2] + '.excalidraw';
+        const scene = mermaid ? await excalidrawSceneFromMermaid(mermaid) : (excalidraw_data ?? emptyExcalidrawScene());
+        const body = { content: stringifyExcalidrawScene(scene) };
+        if (width) body.width = width;
+        if (height) body.height = height;
+        if (color) body.color = color;
+        const result = await api('PUT', `/api/fs/${parts[0]}/${parts[1]}/${filename}`, body);
+        return ok(withProject(withFrameBreadcrumb(result, { hint: true })), {
+          structuredContent: frameStructuredContent(result, projectCtx),
+          _meta: { frameHtml: body.content },
+        });
+      }
       case 'edit': {
         const { path, operations } = args;
         if (!path) throw new Error('path required for action=edit');
@@ -1412,6 +1778,27 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
         if (skillErr) return err(new Error(skillErr));
         return ok(withProject(await api('POST', '/api/fs/anchor', { path, anchored })));
       }
+
+      case 'versions': {
+        const { path } = args;
+        if (!path) throw new Error('path required for action=versions');
+        const result = await api('GET', `/api/fs/versions?path=${encodeURIComponent(path)}`);
+        return ok(withProject(result));
+      }
+      case 'read_version': {
+        const { versionId } = args;
+        if (!versionId) throw new Error('versionId required for action=read_version');
+        const result = await api('GET', `/api/fs/versions/${versionId}`);
+        return ok(withProject(result));
+      }
+      case 'restore_version': {
+        const { versionId, reason } = args;
+        if (!versionId) throw new Error('versionId required for action=restore_version');
+        const skillErr = await checkProjectSkills(getState().projectId);
+        if (skillErr) return err(new Error(skillErr));
+        const result = await api('POST', '/api/fs/restore-version', { versionId, reason });
+        return ok(withProject(result));
+      }
       case 'search': {
         const { query, projectId, limit = 50 } = args;
         if (!query) throw new Error('query required for action=search');
@@ -1587,7 +1974,7 @@ tool('batch', 'Batch operations on the ACTIVE PROJECT. Response includes "projec
 
     // Handle frame operations via the batch API
     if (frameOps.length > 0) {
-      const TEXT_EXTS = ['.html', '.htm', '.svg', '.md', '.markdown', '.txt', '.css', '.js', '.mjs', '.json', '.xml'];
+      const TEXT_EXTS = ['.html', '.htm', '.md', '.markdown', '.txt', '.css', '.js', '.mjs', '.json', '.xml', '.excalidraw'];
       const resolvedOps = frameOps.map(op => {
         if (op.tool === 'write' && op.file_path) {
           const resolved = resolve(op.file_path);
@@ -1805,7 +2192,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
   ]).describe('Operation to perform.'),
   query: z.string().optional().describe('[search] term to match against name/description/content'),
   tags: z.array(z.string()).optional().describe('[search] filter by tags; [add|update] tag list'),
-  scope: z.enum(['all', 'org', 'global']).optional().describe('[search] scope (default: all)'),
+  scope: z.enum(['all', 'org', 'global']).optional().describe('[search|list] library scope (default: all for search; when provided to list, lists the library instead of project/org attachments)'),
   limit: z.number().optional().describe('[search] max results (default 25, max 100)'),
   skill: z.string().optional().describe('[load] skill ID (UUID) or slug'),
   skillId: z.string().optional().describe('[update|remove|attach|detach|favorite|unfavorite|read_file|update_file] skill ID'),
@@ -1829,10 +2216,14 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         const endpoint = query ? '/api/skills/search' : '/api/skills';
         const result = await api('GET', `${endpoint}${qs ? '?' + qs : ''}`);
         const cap = Math.min(Math.max(1, limit || 25), 100);
-        if (Array.isArray(result?.skills) && result.skills.length > cap) {
-          result.totalAvailable = result.skills.length;
-          result.truncated = true;
-          result.skills = result.skills.slice(0, cap);
+        if (Array.isArray(result?.skills)) {
+          if (result.skills.length > cap) {
+            result.totalAvailable = result.skills.length;
+            result.truncated = true;
+            result.skills = result.skills.slice(0, cap);
+          }
+          result.skills = result.skills.map(summarizeSkillForSearch);
+          result.note = 'Search/list returns skill summaries only. Use skill(action="load", skill="<slug-or-id>") to read full SKILL.md content and supporting file list.';
         }
         return ok(result);
       }
@@ -1846,6 +2237,18 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         return ok(result);
       }
       case 'list': {
+        if (args.scope || args.tags?.length) {
+          const params = new URLSearchParams();
+          params.set('scope', args.scope || 'all');
+          if (args.tags?.length) params.set('tags', args.tags.join(','));
+          const result = await api('GET', `/api/skills?${params.toString()}`);
+          if (Array.isArray(result?.skills)) {
+            result.skills = result.skills.map(summarizeSkillForSearch);
+            result.note = 'Library list returns skill summaries only. Use skill(action="load", skill="<slug-or-id>") to read full SKILL.md content and supporting file list.';
+          }
+          return ok(result);
+        }
+
         // Prefer the explicit projectId param; otherwise the active project;
         // otherwise fall back to org-attached skills so list works in
         // empty-org / wiki-only sessions where there's no project to bind to.
@@ -1951,7 +2354,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
   frontmatter: z.any().optional().describe('[write] frontmatter object'),
   operations: z.array(z.object({
     type: z.enum(['replace', 'delete', 'insertAfter', 'insertBefore']).describe('Edit type'),
-    lineHash: z.string().describe('4-char hash of the target line (from read output)'),
+    lineHash: z.string().describe('Hash of the target line (from read output)'),
     newContent: z.string().optional().describe('New content (for replace, insertAfter, insertBefore)'),
   })).optional().describe('[edit] hashline edit operations — same shape as frame.edit'),
   from: z.string().optional().describe('[mv] source path'),
@@ -2006,6 +2409,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
             title: p.title,
             type: p.type,
             id: p.id,
+            url: wikiBrowserUrl(p.path),
           }));
           return ok({ tree });
         }
@@ -2021,8 +2425,8 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
           }
           return ok({
             tree: [
-              ...Array.from(dirs).sort().map(d => ({ type: 'directory', name: d })),
-              ...rootPages.map(p => ({ type: 'page', path: p.path, title: p.title, id: p.id })),
+              ...Array.from(dirs).sort().map(d => ({ type: 'directory', name: d, url: wikiBrowserUrl(d) })),
+              ...rootPages.map(p => ({ type: 'page', path: p.path, title: p.title, id: p.id, url: wikiBrowserUrl(p.path) })),
             ],
           });
         }
@@ -2033,14 +2437,14 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         const prefix = parent + '/';
         for (const p of pages) {
           if (p.path === parent) {
-            children.push({ type: 'page', path: p.path, title: p.title, id: p.id });
+            children.push({ type: 'page', path: p.path, title: p.title, id: p.id, url: wikiBrowserUrl(p.path) });
           } else if (p.path.startsWith(prefix)) {
             const rest = p.path.slice(prefix.length);
             if (rest.includes('/')) {
               const sub = rest.split('/')[0];
-              if (!seenDirs.has(sub)) { seenDirs.add(sub); children.push({ type: 'directory', name: parent + '/' + sub }); }
+              if (!seenDirs.has(sub)) { seenDirs.add(sub); children.push({ type: 'directory', name: parent + '/' + sub, url: wikiBrowserUrl(parent + '/' + sub) }); }
             } else {
-              children.push({ type: 'page', path: p.path, title: p.title, id: p.id });
+              children.push({ type: 'page', path: p.path, title: p.title, id: p.id, url: wikiBrowserUrl(p.path) });
             }
           }
         }
@@ -2055,12 +2459,12 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
           .filter(p => p.updatedAt)
           .sort((a, b) => new Date(b.updatedAt) - new Date(a.updatedAt))
           .slice(0, Math.max(1, recentLimit))
-          .map(p => ({ path: p.path, title: p.title, updatedAt: p.updatedAt }));
+          .map(p => ({ path: p.path, title: p.title, updatedAt: p.updatedAt, url: wikiBrowserUrl(p.path) }));
         return ok({ pages: recent });
       }
 
       // ── read ────────────────────────────────────────────────────
-      // Returns content in hashline format (`lineNum:hash|content`) so the
+      // Returns content in hashline format (`LINE+ID|content`) so the
       // agent can produce hashline edit operations. Mirrors frame.read.
       case 'read': {
         const { path: readPath, lines: readLines } = args;
@@ -2088,6 +2492,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
           lastEditedBy: page.updatedBy,
           lastEditedAt: page.updatedAt,
           backlinkCount,
+          url: wikiBrowserUrl(page.path),
         });
       }
 
@@ -2096,7 +2501,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         const { query: searchQuery, limit: searchLimit = 25 } = args;
         if (!searchQuery) throw new Error('query required for action=search');
         const result = await api('GET', `/api/wiki/search?q=${encodeURIComponent(searchQuery)}&limit=${searchLimit}`);
-        const hits = (result.hits || []).map(h => ({ path: h.path, title: h.title }));
+        const hits = (result.hits || []).map(h => ({ path: h.path, title: h.title, url: wikiBrowserUrl(h.path) }));
         return ok({ hits });
       }
 
@@ -2131,13 +2536,13 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
             title: 'Log',
             content: entry + '\n',
           });
-          return ok(withOrg({ appended: true, created: true, pageId: created.id }));
+          return ok(withOrg({ appended: true, created: true, pageId: created.id, path: 'log', url: wikiBrowserUrl('log') }));
         }
 
         // Append to existing log
         const updatedContent = (existingContent.endsWith('\n') ? existingContent : existingContent + '\n') + entry + '\n';
         await api('PATCH', `/api/wiki/pages/${existingId}`, { content: updatedContent });
-        return ok(withOrg({ appended: true }));
+        return ok(withOrg({ appended: true, path: 'log', url: wikiBrowserUrl('log') }));
       }
 
       // ── health ──────────────────────────────────────────────────
@@ -2160,17 +2565,39 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         try {
           const existing = await api('GET', `/api/wiki/page?path=${encodeURIComponent(normalized)}`);
           const result = await api('PATCH', `/api/wiki/pages/${existing.id}`, body);
-          return ok(withOrg({ path: result.path, title: result.title, id: result.id, updated: true }));
+          return ok(withOrg({ path: result.path, title: result.title, id: result.id, updated: true, url: wikiBrowserUrl(result.path) }));
         } catch {
           const result = await api('POST', '/api/wiki/pages', body);
-          return ok(withOrg({ path: result.path, title: result.title, id: result.id, created: true }));
+          return ok(withOrg({ path: result.path, title: result.title, id: result.id, created: true, url: wikiBrowserUrl(result.path) }));
         }
       }
 
       // ── edit ────────────────────────────────────────────────────
       // Hashlines come from `read` (which now formats content as
-      // `lineNum:hash|content`). The server applies the ops via the same
+      // `LINE+ID|content`). The server applies the ops via the same
       // hashline algorithm — no client-side re-hashing, no algorithm drift.
+      case 'write_excalidraw': {
+        const { path, excalidraw_data, mermaid, width, height, color } = args;
+        if (!path) throw new Error('path required for action=write_excalidraw');
+        if (excalidraw_data != null && mermaid) throw new Error('Provide only one of excalidraw_data or mermaid');
+        const skillErr = await checkProjectSkills(getState().projectId);
+        if (skillErr) return err(new Error(skillErr));
+        const anchorErr = await checkAnchors(parseLayer(path));
+        if (anchorErr) return err(new Error(anchorErr));
+        const parts = path.replace(/^\/+/, '').split('/');
+        if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}');
+        const filename = parts[2].toLowerCase().endsWith('.excalidraw') ? parts[2] : parts[2] + '.excalidraw';
+        const scene = mermaid ? await excalidrawSceneFromMermaid(mermaid) : (excalidraw_data ?? emptyExcalidrawScene());
+        const body = { content: stringifyExcalidrawScene(scene) };
+        if (width) body.width = width;
+        if (height) body.height = height;
+        if (color) body.color = color;
+        const result = await api('PUT', `/api/fs/${parts[0]}/${parts[1]}/${filename}`, body);
+        return ok(withProject(withFrameBreadcrumb(result, { hint: true })), {
+          structuredContent: frameStructuredContent(result, projectCtx),
+          _meta: { frameHtml: body.content },
+        });
+      }
       case 'edit': {
         const { path: editPath, operations: editOps } = args;
         if (!editPath) throw new Error('path required for action=edit');
@@ -2178,7 +2605,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         const normalized = normalizeWikiPath(editPath);
         const page = await api('GET', `/api/wiki/page?path=${encodeURIComponent(normalized)}`);
         const result = await api('POST', `/api/wiki/pages/${page.id}/edit`, { operations: editOps });
-        return ok(withOrg({ path: result.path, id: result.id, updated: true, applied: result.applied }));
+        return ok(withOrg({ path: result.path, id: result.id, updated: true, applied: result.applied, url: wikiBrowserUrl(result.path) }));
       }
 
       // ── mv ──────────────────────────────────────────────────────
@@ -2199,7 +2626,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
 
         // Server-side cascade: /move rewrites referrers in one transaction
         const moved = await api('PATCH', `/api/wiki/pages/${page.id}/move`, { path: toPath });
-        return ok(withOrg({ path: moved.path, title: moved.title, id: moved.id, referrersUpdated: moved.referrersUpdated ?? 0 }));
+        return ok(withOrg({ path: moved.path, title: moved.title, id: moved.id, referrersUpdated: moved.referrersUpdated ?? 0, url: wikiBrowserUrl(moved.path) }));
       }
 
       // ── rm ──────────────────────────────────────────────────────
@@ -2251,8 +2678,8 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         return ok(withOrg({
           created: result.created?.length ?? 0,
           updated: result.updated?.length ?? 0,
-          createdPaths: (result.created ?? []).map((r) => r.path),
-          updatedPaths: (result.updated ?? []).map((r) => r.path),
+          createdPages: (result.created ?? []).map((r) => ({ path: r.path, url: wikiBrowserUrl(r.path) })),
+          updatedPages: (result.updated ?? []).map((r) => ({ path: r.path, url: wikiBrowserUrl(r.path) })),
           errors: result.errors ?? [],
         }));
       }