drafted 1.1.2 → 1.1.4

package/mcp/server.mjs

@@ -9,15 +9,45 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { execFile } from 'child_process';
-import { readFileSync, existsSync } from 'fs';
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, realpathSync } from 'fs';
 import { join, dirname, basename, extname, resolve } from 'path';
 import { homedir } 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// ── Per-instance session ──────────────────────────────────────────
+// State is per-request via AsyncLocalStorage. Standalone modes (stdio, --http)
+// share a process-wide default frame so the existing single-tenant behaviour
+// is preserved. The mounted /mcp route in server/server.mjs wraps each
+// request in runWithRequestState({...}, handler) so concurrent OAuth users
+// never see each other's session or active project.
+
+const requestState = new AsyncLocalStorage();
+const standaloneState = { sessionId: null, projectId: null };
+
+function getState() {
+  return requestState.getStore() || standaloneState;
+}
+
+export function runWithRequestState(initial, fn) {
+  return requestState.run({ ...standaloneState, ...initial }, fn);
+}
+
+// ── MCP server factory ────────────────────────────────────────────
+// Streamable-HTTP requires a fresh McpServer per request — the SDK only
+// permits one transport connection per server instance, so a singleton
+// crashes on the second request. All tool + resource registrations live
+// inside the factory so each HTTP request gets its own isolated server.
+// Stdio mode uses the `mcpServer` singleton (built once at module load).
+
+export function createMcpServer() {
 const server = new McpServer({
   name: 'drafted',
   version: '2.4.0',
@@ -25,15 +55,151 @@ const server = new McpServer({
 
 An org contains projects. Each project has a zoomable canvas with frames (HTML files) organized as /{layer}/{lane}/{filename}. Layers are predefined categories (wireframes, designs, brand-assets, etc.), lanes are groups within a layer, and frames are the individual design files.
 
-WORKFLOW: list_projects → open_project → ls / → read/write/edit. Projects span all orgs -- open_project auto-switches org context. Every response includes a "project" field showing which project you're operating on -- always verify it matches your intent before writing.
+WORKFLOW: project(action="list") → project(action="open") → ls / → read/write/edit. Projects span all orgs -- opening a project auto-switches org context. Every response includes a "project" field showing which project you're operating on -- always verify it matches your intent before writing.
 
-SKILLS: Drafted has a skill library -- reusable agent instructions stored as SKILL.md files. When a user says "use the X skill", use search_skills to find it, then load_skill to get its instructions. Skills can cover anything: UX guidelines, copywriting rules, brand voice, coding standards, review checklists, etc.
+SKILLS: Drafted has a skill library -- reusable agent instructions stored as SKILL.md files. When a user says "use the X skill", call skill(action="search") to find it, then skill(action="load") to get its instructions. Skills can cover anything: UX guidelines, copywriting rules, brand voice, coding standards, review checklists, etc.
+
+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.
 
 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.`,
 });
 
 const layerKeys = Object.keys(LAYERS);
 
+// ── Tool annotations ──────────────────────────────────────────────
+// Required by Claude (readOnlyHint, destructiveHint) and ChatGPT Apps SDK
+// (openWorldHint). All tools are registered via tool() below — never call
+// server.tool / server.registerTool directly. New tools must be added here.
+//
+// Semantics (per MCP spec):
+//   readOnlyHint   = tool does not modify any state
+//   destructiveHint = tool may delete or overwrite (only meaningful when readOnly=false)
+//   openWorldHint  = tool affects state outside Drafted (browser, email, public web)
+
+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.' },
+
+  // 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: 'Get organization',    readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Get the current organization and membership info.' },
+
+  // Templates
+  template:            { title: 'Templates',            readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage project templates: list, create, update, delete, fork.' },
+
+  // Layers
+  layer:               { title: 'Layers',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage layers in a project: add, update, remove, reorder.' },
+
+  // 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.' },
+  rm:                  { title: 'Delete frame',        readOnlyHint: false, destructiveHint: true,  openWorldHint: false },
+  // batch:               { title: 'Batch operations',   readOnlyHint: false, destructiveHint: true,  openWorldHint: false },
+
+  // Canvas / view
+  focus:               { title: 'Focus on target',     readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Pan the canvas viewport for connected clients to a frame, lane, or layer.' },
+  screenshot:          { title: 'Screenshot',          readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Render a PNG via headless browser. `scope=frame` for a single frame, `scope=canvas` for a region of the project surface.' },
+
+  // Assets
+  asset:               { title: 'Assets',              readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Manage project assets (CSS/JS/images/fonts referenced by frames). `action=upload` or `action=list`.' },
+
+  // Shapes / connectors / groups / layout
+  shape:               { title: 'Add shape',           readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  group:               { title: 'Create group',        readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  connector:           { title: 'Connectors',          readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Connect or disconnect frames with arrows on the surface. `action=connect` or `action=disconnect`.' },
+  layout:              { title: 'Auto-layout',         readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+
+  // Skills
+  skill:               { title: 'Skills',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage the Drafted skill library: search, load, add, update, remove, attach/detach from projects, favorite, and edit skill files.' },
+};
+
+function tool(name, descOrSchema, schemaOrHandler, handler) {
+  const ann = TOOL_ANNOTATIONS[name];
+  if (!ann) throw new Error(`MCP tool "${name}" missing entry in TOOL_ANNOTATIONS`);
+  let description, inputSchema, cb;
+  if (typeof descOrSchema === 'string') {
+    description = descOrSchema;
+    inputSchema = schemaOrHandler;
+    cb = handler;
+  } else {
+    description = ann.description || '';
+    inputSchema = descOrSchema;
+    cb = schemaOrHandler;
+  }
+  const config = {
+    title: ann.title,
+    description,
+    inputSchema,
+    annotations: {
+      readOnlyHint: ann.readOnlyHint,
+      destructiveHint: ann.destructiveHint,
+      openWorldHint: ann.openWorldHint,
+    },
+  };
+  // ChatGPT Apps SDK: if this tool has a widget, wire its UI template URI
+  // so ChatGPT renders the widget instead of text-only tool results.
+  if (ann.widgetUri) {
+    config._meta = { 'ui': { resourceUri: ann.widgetUri } };
+  }
+  return server.registerTool(name, config, cb);
+}
+
+// ── ChatGPT Apps SDK widgets ──────────────────────────────────────
+// Register UI resource templates that tools link to via _meta.ui.resourceUri.
+// ChatGPT and Claude render these HTML files in a sandboxed iframe when the
+// linked tool is called. The `ui.domain` field is required and must match
+// Claude's format: `{sha256(mcp_url)[:32]}.claudemcpcontent.com`. ChatGPT
+// only requires uniqueness per app, so the sha256-derived subdomain satisfies
+// both clients.
+
+const MCP_URL = 'https://drafted.live/mcp';
+const WIDGET_DOMAIN =
+  createHash('sha256').update(MCP_URL).digest('hex').slice(0, 32) +
+  '.claudemcpcontent.com';
+
+function makeWidgetResource(uri, htmlPath) {
+  const html = readFileSync(join(__dirname, 'widgets', htmlPath), 'utf8');
+  return () => ({
+    contents: [
+      {
+        uri,
+        mimeType: RESOURCE_MIME_TYPE,
+        text: html,
+        _meta: {
+          ui: {
+            prefersBorder: true,
+            domain: WIDGET_DOMAIN,
+            csp: {
+              connectDomains: ['https://drafted.live'],
+              resourceDomains: [
+                'https://drafted.live',
+                'https://fonts.googleapis.com',
+                'https://fonts.gstatic.com',
+              ],
+            },
+          },
+        },
+      },
+    ],
+  });
+}
+
+registerAppResource(
+  server,
+  'drafted-frame-preview',
+  'ui://widget/drafted-frame-preview.html',
+  {},
+  makeWidgetResource('ui://widget/drafted-frame-preview.html', 'frame-preview.html')
+);
+
+registerAppResource(
+  server,
+  'drafted-canvas-overview',
+  'ui://widget/drafted-canvas-overview.html',
+  {},
+  makeWidgetResource('ui://widget/drafted-canvas-overview.html', 'canvas-overview.html')
+);
+
 // ── Config ────────────────────────────────────────────────────────
 
 const AUTH_FILE = process.env.DRAFTED_AUTH_FILE || join(homedir(), '.drafted', 'auth.json');
@@ -51,13 +217,6 @@ function getServerUrl() {
   return `http://localhost:${process.env.DRAFTED_PORT || 3477}`;
 }
 
-// ── Per-instance session ──────────────────────────────────────────
-// Each MCP instance clones its own session from the bootstrap session in auth.json.
-// This ensures multiple Claude Code instances don't share state.
-
-let instanceSessionId = null; // cloned session, in-memory only
-let agentActiveProjectId = null; // in-memory only, never persisted
-
 function getBootstrapSessionId() {
   try {
     if (existsSync(AUTH_FILE)) {
@@ -69,7 +228,7 @@ function getBootstrapSessionId() {
 }
 
 function getAuthHeaders() {
-  const sid = instanceSessionId || getBootstrapSessionId();
+  const sid = getState().sessionId || getBootstrapSessionId();
   if (sid) return { Cookie: `gc_session=${sid}` };
   return {};
 }
@@ -87,13 +246,13 @@ async function cloneSession() {
     if (!res.ok) return;
     const data = await res.json();
     if (data.sessionId) {
-      instanceSessionId = data.sessionId;
+      getState().sessionId = data.sessionId;
     }
   } catch { /* server may not be ready yet, will retry on first API call */ }
 }
 
 async function ensureSession() {
-  if (instanceSessionId) return;
+  if (getState().sessionId) return;
   await cloneSession();
 }
 
@@ -109,7 +268,7 @@ function mimeFromExt(ext) { return MIME_MAP[ext?.toLowerCase()] || 'application/
 
 async function api(method, path, body, _retried) {
   await ensureSession();
-  const pid = agentActiveProjectId;
+  const pid = getState().projectId;
   const sep = path.includes('?') ? '&' : '?';
   const scopedPath = pid ? `${path}${sep}projectId=${pid}` : path;
   const url = `${getServerUrl()}${scopedPath}`;
@@ -126,7 +285,7 @@ async function api(method, path, body, _retried) {
 
   // Session expired after server restart — re-clone and retry once
   if (res.status === 401 && !_retried) {
-    instanceSessionId = null;
+    getState().sessionId = null;
     await cloneSession();
     return api(method, path, body, true);
   }
@@ -143,18 +302,77 @@ async function api(method, path, body, _retried) {
   return data;
 }
 
-function ok(text) {
-  return { content: [{ type: 'text', text: typeof text === 'string' ? text : JSON.stringify(text, null, 2) }] };
+// MCP spec caps tool results at 25k tokens. Text averages ~4 chars/token,
+// so 90k chars ≈ 22.5k tokens — safe margin under the cap. Image content
+// (screenshot scope=frame/canvas) goes through a separate path and is
+// token-counted by Claude vision, not by char length, so no need to cap here.
+const MAX_TOOL_RESULT_CHARS = 90_000;
+
+function enforceTokenBudget(text, max = MAX_TOOL_RESULT_CHARS) {
+  if (text.length <= max) return text;
+  const head = text.slice(0, max - 240);
+  const tail = `\n\n[TRUNCATED: result was ${text.length} chars, capped at ${max} to stay under the MCP 25k-token tool-result limit. Use a more specific query, pagination params (limit/offset), or frame(action="read") with lines to fetch in chunks.]`;
+  return head + tail;
+}
+
+function ok(text, opts) {
+  const str = typeof text === 'string' ? text : JSON.stringify(text, null, 2);
+  const result = { content: [{ type: 'text', text: enforceTokenBudget(str) }] };
+  // ChatGPT Apps SDK: widgets read structuredContent (also visible to model —
+  // keep it tight) and _meta (widget-only, never reaches the model).
+  if (opts?.structuredContent) result.structuredContent = opts.structuredContent;
+  if (opts?._meta) result._meta = opts._meta;
+  return result;
+}
+
+// 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.
+function frameStructuredContent(result) {
+  return {
+    id: result.id,
+    path: result.path || (result.layer && result.lane && result.label
+      ? `/${result.layer}/${result.lane}/${result.label}`
+      : undefined),
+    frameId: result.id,
+    contentType: result.contentType,
+    layer: result.layer,
+    lane: result.lane,
+    width: result.width,
+    height: result.height,
+    frameUrl: result.id ? `${getServerUrl()}/f/${result.id}` : undefined,
+  };
+}
+
+// Attach a canonical breadcrumb token (+ optional hint) to a response that
+// references a frame or project by UUID. Agents should paste the token as a
+// comment in any codebase file that corresponds to the frame/project so
+// future agents grepping for "drafted:" discover the link.
+function withFrameBreadcrumb(result, { hint = false } = {}) {
+  if (!result || typeof result !== 'object' || !result.id) return result;
+  const out = { ...result, breadcrumb: `drafted:${result.id}` };
+  if (hint) {
+    out.breadcrumbHint = `If this frame maps to a file in the user's codebase, paste "drafted:${result.id}" as a comment in that file so future agents discover the link.`;
+  }
+  return out;
+}
+
+function withProjectBreadcrumb(result) {
+  if (!result || typeof result !== 'object' || !result.id) return result;
+  return {
+    ...result,
+    breadcrumb: `drafted-project:${result.id}`,
+    breadcrumbHint: `Consider pasting "drafted-project:${result.id}" in the project README or CLAUDE.md so future agents discover the linked Drafted project.`,
+  };
 }
 
 // ── Agent WebSocket presence ──────────────────────────────────────
-import WebSocket from 'ws';
 
 let agentWs = null;
 let agentWsReconnectTimer = null;
 
 function setMcpActiveProject(projectId) {
-  agentActiveProjectId = projectId;
+  getState().projectId = projectId;
 }
 
 async function connectAgentWs() {
@@ -169,8 +387,8 @@ async function connectAgentWs() {
 
   agentWs.on('open', () => {
     console.error('[MCP-WS] Connected');
-    if (agentActiveProjectId) {
-      agentWs.send(JSON.stringify({ type: 'join', projectId: agentActiveProjectId, agent: true }));
+    if (getState().projectId) {
+      agentWs.send(JSON.stringify({ type: 'join', projectId: getState().projectId, agent: true }));
     }
   });
 
@@ -178,7 +396,7 @@ async function connectAgentWs() {
     console.error('[MCP-WS] Disconnected, reconnecting in 5s...');
     agentWs = null;
     // Server may have restarted — invalidate session so ensureSession re-clones
-    instanceSessionId = null;
+    getState().sessionId = null;
     clearTimeout(agentWsReconnectTimer);
     agentWsReconnectTimer = setTimeout(() => {
       connectAgentWs().catch((e) => {
@@ -206,10 +424,15 @@ async function joinAgentWsRoom(projectId) {
   }
 }
 
-// Clone session and connect WebSocket on startup (delayed to let server be ready)
-setTimeout(() => {
-  cloneSession().then(() => connectAgentWs()).catch(() => {});
-}, 1000);
+// Clone session and connect WebSocket on startup (delayed to let server be ready).
+// Guarded because createMcpServer() runs per HTTP request — the bootstrap must
+// fire exactly once per process, not per request.
+if (!globalThis.__draftedAgentWsBootstrapped) {
+  globalThis.__draftedAgentWsBootstrapped = true;
+  setTimeout(() => {
+    cloneSession().then(() => connectAgentWs()).catch(() => {});
+  }, 1000);
+}
 
 function err(error) {
   return { content: [{ type: 'text', text: error.message || String(error) }], isError: true };
@@ -281,253 +504,271 @@ function runCLI(command, args = [], options = {}) {
 
 // ── Login tools ─────────────────────────────────────────────────────
 
-// Shared pending device code — get_login_link stores it, login reuses it
+// Shared pending device code — auth(action=get_link) stores it, auth(action=login) reuses it
 let pendingDeviceCode = null;
 
-server.tool('get_login_link', 'Get a sign-in URL without blocking. Use this before login when the browser may not open (SSH, headless, tmux). Returns the URL immediately for the user to open manually. Then call login to complete the flow.', {}, async () => {
+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.', {
+  action: z.enum(['get_link', 'login']).describe('Operation to perform.'),
+}, async ({ action }) => {
   try {
-    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;
-    return ok(data.verificationUrl);
-  } catch (error) { return err(error); }
-});
-
-server.tool('login', 'Authenticate with Drafted. Opens a browser for the user to sign in. Run this if other tools return auth errors or "fetch failed". If get_login_link was called first, polls for that approval instead of opening a new browser.', {}, async () => {
-  try {
-    // Check if already authenticated
-    const existing = getBootstrapSessionId();
-    if (existing) {
-      try {
-        const res = await fetch(`${getServerUrl()}/auth/me`, {
-          headers: { Cookie: `gc_session=${existing}` },
-        });
-        if (res.ok) {
-          const me = await res.json();
-          return ok({ status: 'already_authenticated', userId: me.userId, email: me.userEmail, org: me.currentOrg?.name });
-        }
-      } catch { /* session invalid, proceed with login */ }
-    }
-
-    let deviceCode, verificationUrl, expiresIn;
-    let reusingPending = false;
-
-    // Reuse pending device code from get_login_link if available
-    if (pendingDeviceCode) {
-      ({ deviceCode, verificationUrl, expiresIn } = pendingDeviceCode);
-      pendingDeviceCode = null;
-      reusingPending = true;
-    } else {
-      // Request a new device code
+    if (action === 'get_link') {
       const codeRes = await fetch(`${getServerUrl()}/auth/device/code`, { method: 'POST' });
       if (!codeRes.ok) throw new Error(`Failed to start device authorization (HTTP ${codeRes.status})`);
-      ({ deviceCode, verificationUrl, expiresIn } = await codeRes.json());
+      const data = await codeRes.json();
+      pendingDeviceCode = data;
+      return ok(data.verificationUrl);
     }
+    if (action === 'login') {
+      const existing = getBootstrapSessionId();
+      if (existing) {
+        try {
+          const res = await fetch(`${getServerUrl()}/auth/me`, {
+            headers: { Cookie: `gc_session=${existing}` },
+          });
+          if (res.ok) {
+            const me = await res.json();
+            return ok({ status: 'already_authenticated', userId: me.userId, email: me.userEmail, org: me.currentOrg?.name });
+          }
+        } catch { /* session invalid, proceed with login */ }
+      }
 
-    // Generate QR code for the verification URL
-    let qrText = '';
-    try {
-      const qrcode = await import('qrcode-terminal');
-      qrText = await new Promise((resolve) => {
-        qrcode.default.generate(verificationUrl, { small: true }, (code) => resolve(code));
-      });
-    } catch { /* QR generation failed, continue without it */ }
-
-    // Log the URL to stderr so it's visible even if MCP response is delayed
-    console.error(`\n[MCP] Sign in at: ${verificationUrl}\n${qrText ? qrText + '\n' : ''}[MCP] Waiting for approval...`);
-
-    // Open browser only if we're not reusing a pending code (user already has the URL)
-    if (!reusingPending) {
-      const { exec } = await import('child_process');
-      const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      exec(`${cmd} ${JSON.stringify(verificationUrl)}`);
-    }
+      let deviceCode, verificationUrl, expiresIn;
+      let reusingPending = false;
 
-    // Poll for approval
-    const deadline = Date.now() + (expiresIn * 1000);
-    while (Date.now() < deadline) {
-      await new Promise(r => setTimeout(r, 4000));
-      const res = await fetch(`${getServerUrl()}/auth/device/token`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ deviceCode }),
-      });
-      if (!res.ok) throw new Error(`Token poll failed (HTTP ${res.status})`);
-      const data = await res.json();
-
-      if (data.status === 'approved') {
-        // Write auth file
-        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));
-
-        // Re-clone session for this instance
-        instanceSessionId = null;
-        await cloneSession();
-        connectAgentWs();
-
-        return ok({ status: 'logged_in', sessionId: data.sessionId, userId: data.userId });
+      if (pendingDeviceCode) {
+        ({ deviceCode, verificationUrl, expiresIn } = pendingDeviceCode);
+        pendingDeviceCode = null;
+        reusingPending = true;
+      } else {
+        const codeRes = await fetch(`${getServerUrl()}/auth/device/code`, { method: 'POST' });
+        if (!codeRes.ok) throw new Error(`Failed to start device authorization (HTTP ${codeRes.status})`);
+        ({ deviceCode, verificationUrl, expiresIn } = await codeRes.json());
       }
 
-      if (data.status === 'expired') throw new Error('Device code expired. Try again.');
-    }
-
-    throw new Error(`Login timed out. If the browser didn't open, visit: ${verificationUrl}`);
-  } catch (error) { return err(error); }
-});
+      let qrText = '';
+      try {
+        const qrcode = await import('qrcode-terminal');
+        qrText = await new Promise((resolve) => {
+          qrcode.default.generate(verificationUrl, { small: true }, (code) => resolve(code));
+        });
+      } catch { /* QR generation failed, continue without it */ }
 
-// ── Project management tools (direct HTTP) ────────────────────────
+      console.error(`\n[MCP] Sign in at: ${verificationUrl}\n${qrText ? qrText + '\n' : ''}[MCP] Waiting for approval...`);
 
-server.tool('list_projects', 'START HERE. Lists all projects across all orgs. Use this first to find the project you need, then open_project to switch to it (org switches automatically).', {}, async () => {
-  try {
-    const data = await api('GET', '/api/projects');
-    data.agentProject = agentActiveProjectId || null;
-    // Inject favorited skills so the agent knows about them from the first call
-    try {
-      const favData = await api('GET', '/api/skills/favorites');
-      const favs = favData.skills || [];
-      if (favs.length > 0) {
-        data.favoritedSkills = favs.map(s => ({
-          id: s.id,
-          name: s.name,
-          slug: s.slug,
-          description: s.description,
-          tags: s.tags,
-        }));
+      if (!reusingPending) {
+        const { exec } = await import('child_process');
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${cmd} ${JSON.stringify(verificationUrl)}`);
       }
-    } catch { /* skills not available */ }
-    return ok(data);
-  } catch (error) { return err(error); }
-});
-
-server.tool('create_project', {
-  name: z.string().describe('Project name'),
-  description: z.string().optional().describe('Project description'),
-  templateSlug: z.string().optional().describe('Template slug (e.g. "web-design", "mobile-app", "landing-page")'),
-}, async ({ name, description, templateSlug }) => {
-  try {
-    const body = { name };
-    if (description) body.description = description;
-    if (templateSlug) body.templateSlug = templateSlug;
-    return ok(await api('POST', '/api/projects', body));
-  } catch (error) { return err(error); }
-});
 
-server.tool('list_templates', {}, async () => {
-  try { return ok(await api('GET', '/api/templates')); }
-  catch (error) { return err(error); }
-});
+      const deadline = Date.now() + (expiresIn * 1000);
+      while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, 4000));
+        const res = await fetch(`${getServerUrl()}/auth/device/token`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ deviceCode }),
+        });
+        if (!res.ok) throw new Error(`Token poll failed (HTTP ${res.status})`);
+        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));
+
+          getState().sessionId = null;
+          await cloneSession();
+          connectAgentWs();
+
+          return ok({ status: 'logged_in', sessionId: data.sessionId, userId: data.userId });
+        }
 
-server.tool('create_template', {
-  name: z.string().describe('Template name'),
-  description: z.string().describe('Template description'),
-  layers: z.array(z.object({}).passthrough()).describe('Array of layer definitions'),
-  visibility: z.string().optional().describe('Visibility: "org" or "public"'),
-}, async ({ name, description, layers, visibility }) => {
-  try {
-    const body = { name, description, layers };
-    if (visibility) body.visibility = visibility;
-    return ok(await api('POST', '/api/templates', body));
-  } catch (error) { return err(error); }
-});
+        if (data.status === 'expired') throw new Error('Device code expired. Try again.');
+      }
 
-server.tool('update_template', {
-  templateId: z.string().describe('Template ID to update'),
-  name: z.string().optional().describe('Template name'),
-  description: z.string().optional().describe('Template description'),
-  layers: z.array(z.object({}).passthrough()).optional().describe('Array of layer definitions'),
-  visibility: z.string().optional().describe('Visibility: "org" or "public"'),
-}, async ({ templateId, name, description, layers, visibility }) => {
-  try {
-    const body = {};
-    if (name) body.name = name;
-    if (description) body.description = description;
-    if (layers) body.layers = layers;
-    if (visibility) body.visibility = visibility;
-    return ok(await api('PUT', `/api/templates/${templateId}`, body));
+      throw new Error(`Login timed out. If the browser didn't open, visit: ${verificationUrl}`);
+    }
+    throw new Error(`Unknown auth action: ${action}`);
   } catch (error) { return err(error); }
 });
 
-server.tool('delete_template', {
-  templateId: z.string().describe('Template ID to delete'),
-}, async ({ templateId }) => {
-  try { return ok(await api('DELETE', `/api/templates/${templateId}`)); }
-  catch (error) { return err(error); }
-});
+// ── Project management tools (direct HTTP) ────────────────────────
 
-server.tool('fork_template', {
-  templateId: z.string().describe('Template ID to fork'),
-  name: z.string().optional().describe('Name for the forked copy'),
-}, async ({ templateId, name }) => {
+tool('project', 'START HERE for project management. Dispatch by `action`: list (lists all projects across all orgs — always call first), open (switch the active project; required before reading/writing frames), create (new project, optionally from a template), update (change name/folder/description/layers), move (transfer to another org). The org switches automatically when you open a project.', {
+  action: z.enum(['list', 'open', 'create', 'update', 'move']).describe('Operation to perform.'),
+  projectId: z.string().optional().describe('[open|update|move] project ID. Get IDs from action=list.'),
+  name: z.string().optional().describe('[create|update] project name'),
+  description: z.string().nullable().optional().describe('[create|update] project description'),
+  templateSlug: z.string().optional().describe('[create] template slug (e.g. "web-design", "mobile-app", "landing-page")'),
+  folder: z.string().nullable().optional().describe('[update] folder name (null to remove from folder)'),
+  layers: z.array(z.object({}).passthrough()).optional().describe('[update] full layers array replacement. Use ls / to read current layers first.'),
+  targetOrgId: z.string().optional().describe('[move] destination organization ID. Get org IDs from action=list (each project has an orgId field) or get_org. Both source and target org must include the current user.'),
+  skipBrowser: z.boolean().optional().describe('[open] skip opening/navigating a browser tab (use when the user already has the project open, e.g. from an invite snippet)'),
+}, async (args) => {
   try {
-    const body = {};
-    if (name) body.name = name;
-    return ok(await api('POST', `/api/templates/${templateId}/fork`, body));
+    const { action } = args;
+    switch (action) {
+      case 'list': {
+        const data = await api('GET', '/api/projects');
+        data.agentProject = getState().projectId || null;
+        try {
+          const favData = await api('GET', '/api/skills/favorites');
+          const favs = favData.skills || [];
+          if (favs.length > 0) {
+            data.favoritedSkills = favs.map(s => ({
+              id: s.id,
+              name: s.name,
+              slug: s.slug,
+              description: s.description,
+              tags: s.tags,
+            }));
+          }
+        } catch { /* skills not available */ }
+
+        const structuredContent = {
+          projects: (data.projects || []).map(p => ({
+            id: p.id,
+            name: p.name,
+            slug: p.slug,
+            description: p.description,
+            orgId: p.orgId,
+          })),
+          activeProject: data.agentProject,
+        };
+        return ok(data, { structuredContent });
+      }
+      case 'open': {
+        const { projectId, skipBrowser } = args;
+        if (!projectId) throw new Error('projectId required for action=open');
+        const result = await api('POST', '/api/project/switch', { projectId });
+        setMcpActiveProject(projectId);
+        joinAgentWsRoom(projectId);
+        const base = getServerUrl();
+        let projectSlug = projectId;
+        try {
+          const data = await api('GET', '/api/projects');
+          const proj = (data.projects || []).find(p => p.id === projectId);
+          if (proj?.slug) projectSlug = proj.slug;
+        } catch { /* fall back to projectId */ }
+        const url = `${base}/project/${projectSlug}`;
+        let navigated = 0;
+        if (!skipBrowser) {
+          try {
+            const nav = await api('POST', '/api/project/navigate', { projectId });
+            navigated = nav.navigated || 0;
+          } catch { /* server may not support navigate yet */ }
+          if (navigated === 0) {
+            const { exec } = await import('child_process');
+            const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+            exec(`${cmd} ${JSON.stringify(url)}`);
+          }
+        }
+        let projectSkillsList = [];
+        try {
+          const skillData = await api('GET', `/api/projects/${projectId}/skills`);
+          projectSkillsList = skillData.skills || [];
+        } catch { /* skills not available yet */ }
+
+        if (projectSkillsList.length > 0 && projectSkillsList.length <= 3) {
+          for (const s of projectSkillsList) {
+            try {
+              const full = await api('GET', `/api/skills/${s.id}`);
+              s.content = full.content;
+              s.files = full.files || [];
+            } catch { /* skip */ }
+          }
+        }
+
+        return ok({ ...result, url, opened: true, navigated, skills: projectSkillsList });
+      }
+      case 'create': {
+        const { name, description, templateSlug } = args;
+        if (!name) throw new Error('name required for action=create');
+        const body = { name };
+        if (description) body.description = description;
+        if (templateSlug) body.templateSlug = templateSlug;
+        return ok(withProjectBreadcrumb(await api('POST', '/api/projects', body)));
+      }
+      case 'update': {
+        const { projectId, name, folder, description, layers } = args;
+        if (!projectId) throw new Error('projectId required for action=update');
+        const body = {};
+        if (name !== undefined) body.name = name;
+        if (folder !== undefined) body.folder = folder;
+        if (description !== undefined) body.description = description;
+        if (layers) body.layers = layers;
+        if (Object.keys(body).length === 0) throw new Error('At least one field (name, folder, description, layers) is required for action=update');
+        return ok(await api('PATCH', `/api/project/${projectId}`, body));
+      }
+      case 'move': {
+        const { projectId, targetOrgId } = args;
+        if (!projectId || !targetOrgId) throw new Error('projectId and targetOrgId required for action=move');
+        return ok(await api('POST', `/api/project/${projectId}/move`, { targetOrgId }));
+      }
+      default:
+        throw new Error(`Unknown project action: ${action}`);
+    }
   } catch (error) { return err(error); }
 });
 
-server.tool('open_project', 'Switch active project. REQUIRED before reading or writing — all fs tools (ls, read, write, edit, rm, mv, batch) operate on the active project. Get project IDs from list_projects.', {
-  projectId: z.string().describe('Project ID to switch to and open in browser'),
-  skipBrowser: z.boolean().optional().describe('Skip opening/navigating a browser tab (use when the user already has the project open, e.g. from an invite snippet)'),
-}, async ({ projectId, skipBrowser }) => {
+tool('template', 'Manage project templates in the org. Dispatch by `action`: list/create/update/delete/fork. A template bundles layer definitions that new projects can be created from.', {
+  action: z.enum(['list', 'create', 'update', 'delete', 'fork']).describe('Operation to perform.'),
+  templateId: z.string().optional().describe('[update|delete|fork] template ID'),
+  name: z.string().optional().describe('[create|update|fork] template name (required for create; optional rename for fork)'),
+  description: z.string().optional().describe('[create|update] template description'),
+  layers: z.array(z.object({}).passthrough()).optional().describe('[create|update] array of layer definitions'),
+  visibility: z.string().optional().describe('[create|update] "org" or "public"'),
+}, async (args) => {
   try {
-    const result = await api('POST', '/api/project/switch', { projectId });
-    setMcpActiveProject(projectId);
-    joinAgentWsRoom(projectId);
-    const base = getServerUrl();
-    // Resolve project slug for URL
-    let projectSlug = projectId;
-    try {
-      const data = await api('GET', '/api/projects');
-      const proj = (data.projects || []).find(p => p.id === projectId);
-      if (proj?.slug) projectSlug = proj.slug;
-    } catch { /* fall back to projectId */ }
-    const url = `${base}/project/${projectSlug}`;
-    let navigated = 0;
-    if (!skipBrowser) {
-      // Navigate existing browser tabs instead of opening new ones
-      try {
-        const nav = await api('POST', '/api/project/navigate', { projectId });
-        navigated = nav.navigated || 0;
-      } catch { /* server may not support navigate yet */ }
-      // Only open a new tab if no browser tabs were reached
-      if (navigated === 0) {
-        const { exec } = await import('child_process');
-        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-        exec(`${cmd} ${JSON.stringify(url)}`);
+    const { action } = args;
+    switch (action) {
+      case 'list':
+        return ok(await api('GET', '/api/templates'));
+      case 'create': {
+        const { name, description, layers, visibility } = args;
+        if (!name || !description || !layers) throw new Error('name, description, layers required for action=create');
+        const body = { name, description, layers };
+        if (visibility) body.visibility = visibility;
+        return ok(await api('POST', '/api/templates', body));
       }
-    }
-    // Fetch attached skills (metadata only)
-    let projectSkillsList = [];
-    try {
-      const skillData = await api('GET', `/api/projects/${projectId}/skills`);
-      projectSkillsList = skillData.skills || [];
-    } catch { /* skills not available yet */ }
-
-    // Auto-load content for projects with <= 3 attached skills
-    if (projectSkillsList.length > 0 && projectSkillsList.length <= 3) {
-      for (const s of projectSkillsList) {
-        try {
-          const full = await api('GET', `/api/skills/${s.id}`);
-          s.content = full.content;
-          s.files = full.files || [];
-        } catch { /* skip */ }
+      case 'update': {
+        const { templateId, name, description, layers, visibility } = args;
+        if (!templateId) throw new Error('templateId required for action=update');
+        const body = {};
+        if (name) body.name = name;
+        if (description) body.description = description;
+        if (layers) body.layers = layers;
+        if (visibility) body.visibility = visibility;
+        if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
+        return ok(await api('PUT', `/api/templates/${templateId}`, body));
       }
+      case 'delete': {
+        const { templateId } = args;
+        if (!templateId) throw new Error('templateId required for action=delete');
+        return ok(await api('DELETE', `/api/templates/${templateId}`));
+      }
+      case 'fork': {
+        const { templateId, name } = args;
+        if (!templateId) throw new Error('templateId required for action=fork');
+        const body = {};
+        if (name) body.name = name;
+        return ok(await api('POST', `/api/templates/${templateId}/fork`, body));
+      }
+      default:
+        throw new Error(`Unknown template action: ${action}`);
     }
-
-    return ok({ ...result, url, opened: true, navigated, skills: projectSkillsList });
   } catch (error) { return err(error); }
 });
 
-server.tool('focus', {
+tool('focus', {
   target: z.string().describe('Frame URL (any URL containing /f/{uuid}), frame ID (UUID), or file path (/{layer}/{lane}/{filename}) to pan the canvas viewport to. When a user shares a Drafted frame link, pass it directly here.'),
 }, async ({ target }) => {
   try {
@@ -550,175 +791,159 @@ server.tool('focus', {
   } catch (error) { return err(error); }
 });
 
-server.tool('screenshot', {
-  target: z.string().describe('Frame URL (any URL containing /f/{uuid}), frame ID (UUID), or file path (/{layer}/{lane}/{filename}) to screenshot.'),
-  width: z.number().optional().default(1440).describe('Viewport width in pixels (default 1440)'),
-  height: z.number().optional().default(900).describe('Viewport height in pixels (default 900)'),
-  fullPage: z.boolean().optional().default(true).describe('Capture full page or just viewport (default true)'),
-}, async ({ target, width, height, fullPage }) => {
-  try {
-    // Resolve target to a frame ID
-    const frameUrlMatch = target.match(/\/f\/([a-f0-9-]{36})/);
-    const uuidMatch = target.match(/^[a-f0-9-]{36}$/);
-    let frameId = frameUrlMatch?.[1] || (uuidMatch ? target : null);
-
-    if (!frameId) {
-      const parts = target.replace(/^\/+/, '').split('/');
-      if (parts.length !== 3) throw new Error('Target must be a frame URL, frame ID, or path /{layer}/{lane}/{filename}');
-      const frame = await api('GET', `/api/fs/${parts[0]}/${parts[1]}/${parts[2]}`);
-      if (!frame.id) throw new Error('Frame not found');
-      frameId = frame.id;
-    }
-
-    const url = `${getServerUrl()}/api/screenshot/${frameId}?width=${width}&height=${height}&fullPage=${fullPage}`;
-    const res = await fetch(url, { headers: getAuthHeaders() });
-    if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
-
-    const buffer = await res.arrayBuffer();
-    const base64 = Buffer.from(buffer).toString('base64');
-
-    return {
-      content: [{
-        type: 'image',
-        data: base64,
-        mimeType: 'image/png',
-      }],
-    };
-  } catch (error) { return err(error); }
-});
-
-server.tool('update_project', {
-  projectId: z.string().describe('Project ID to update'),
-  name: z.string().optional().describe('New project name'),
-  folder: z.string().nullable().optional().describe('Folder name (null to remove from folder)'),
-  description: z.string().nullable().optional().describe('Project description'),
-  layers: z.array(z.object({}).passthrough()).optional().describe('Full layers array replacement. Use ls / to read current layers first.'),
-}, async ({ projectId, name, folder, description, layers }) => {
-  try {
-    const body = {};
-    if (name !== undefined) body.name = name;
-    if (folder !== undefined) body.folder = folder;
-    if (description !== undefined) body.description = description;
-    if (layers) body.layers = layers;
-    if (Object.keys(body).length === 0) throw new Error('At least one field (name, folder, description, layers) is required');
-    return ok(await api('PATCH', `/api/project/${projectId}`, body));
-  } catch (error) { return err(error); }
-});
-
-server.tool('add_layer', {
-  projectId: z.string().describe('Project ID to add the layer to'),
-  key: z.string().describe('Unique layer key (e.g. "research", "prototypes")'),
-  label: z.string().describe('Display label for the layer'),
-  type: z.string().describe('Layer type (e.g. "html", "image", "text")'),
-  width: z.number().describe('Default frame width in pixels'),
-  height: z.number().describe('Default frame height in pixels'),
-  description: z.string().optional().describe('Layer description'),
-  prompt: z.string().optional().describe('Prompt hint for AI agents working in this layer'),
-}, async ({ projectId, key, label, type, width, height, description, prompt }) => {
-  try {
-    const project = await api('GET', `/api/project/${projectId}`);
-    const layers = project.layers || [];
-    if (layers.some(l => l.key === key)) {
-      throw new Error(`Layer with key "${key}" already exists in this project`);
-    }
-    const newLayer = { key, label, type, width, height };
-    if (description !== undefined) newLayer.description = description;
-    if (prompt !== undefined) newLayer.prompt = prompt;
-    layers.push(newLayer);
-    return ok(await api('PATCH', `/api/project/${projectId}`, { layers }));
-  } catch (error) { return err(error); }
-});
-
-server.tool('remove_layer', {
-  projectId: z.string().describe('Project ID to remove the layer from'),
-  key: z.string().describe('Layer key to remove (e.g. "research", "prototypes")'),
-  force: z.boolean().optional().default(false).describe('Force removal even if the layer contains frames'),
-}, async ({ projectId, key, force }) => {
+tool('screenshot', 'Render a PNG via headless browser. `scope=frame` captures a single frame (default 1440×900, fullPage). `scope=canvas` captures a region of the project surface (default 1600×1200, typically the "plans" layer where shapes live).', {
+  scope: z.enum(['frame', 'canvas']).describe('What to capture.'),
+  target: z.string().optional().describe('[scope=frame] frame URL, UUID, or /{layer}/{lane}/{filename} path.'),
+  slug: z.string().optional().describe('[scope=canvas] project slug. Defaults to the currently active project.'),
+  layer: z.string().optional().describe('[scope=canvas] layer key to capture (default: plans).'),
+  width: z.number().optional().describe('Viewport width in pixels (frame default 1440, canvas default 1600).'),
+  height: z.number().optional().describe('Viewport height in pixels (frame default 900, canvas default 1200).'),
+  fullPage: z.boolean().optional().describe('[scope=frame] capture full page or just viewport (default true).'),
+}, async (args) => {
   try {
-    const project = await api('GET', `/api/project/${projectId}`);
-    const layers = project.layers || [];
-    if (!layers.some(l => l.key === key)) {
-      throw new Error(`Layer with key "${key}" does not exist in this project`);
+    const { scope } = args;
+    if (scope === 'frame') {
+      const { target, width = 1440, height = 900, fullPage = true } = args;
+      if (!target) throw new Error('target required for scope=frame');
+      const frameUrlMatch = target.match(/\/f\/([a-f0-9-]{36})/);
+      const uuidMatch = target.match(/^[a-f0-9-]{36}$/);
+      let frameId = frameUrlMatch?.[1] || (uuidMatch ? target : null);
+      if (!frameId) {
+        const parts = target.replace(/^\/+/, '').split('/');
+        if (parts.length !== 3) throw new Error('Target must be a frame URL, frame ID, or path /{layer}/{lane}/{filename}');
+        const frame = await api('GET', `/api/fs/${parts[0]}/${parts[1]}/${parts[2]}`);
+        if (!frame.id) throw new Error('Frame not found');
+        frameId = frame.id;
+      }
+      const url = `${getServerUrl()}/api/screenshot/${frameId}?width=${width}&height=${height}&fullPage=${fullPage}`;
+      const res = await fetch(url, { headers: getAuthHeaders() });
+      if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
+      const buffer = await res.arrayBuffer();
+      const base64 = Buffer.from(buffer).toString('base64');
+      return {
+        content: [{ type: 'image', data: base64, mimeType: 'image/png' }],
+      };
     }
-    // Check for existing frames in the layer
-    if (!force) {
-      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');
-      // Don't count the auto-generated context frame as real content
-      const realFrames = frames.filter(f => !f.path.endsWith('/_meta/_context.md') && !f.path.endsWith('/instructions/context.md'));
-      const frameCount = realFrames.length;
-      if (frameCount > 0) {
-        throw new Error(`Layer "${key}" contains ${frameCount} frame(s). Use force: true to confirm deletion.`);
+    if (scope === 'canvas') {
+      const { slug, layer = 'plans', width = 1600, height = 1200 } = args;
+      let targetSlug = slug;
+      if (!targetSlug) {
+        const list = await api('GET', '/api/projects');
+        const active = (list.projects || []).find(p => p.id === list.activeProject);
+        if (!active) throw new Error('No active project — pass slug explicitly.');
+        targetSlug = active.slug;
       }
+      const url = `${getServerUrl()}/api/canvas-screenshot/${encodeURIComponent(targetSlug)}?layer=${encodeURIComponent(layer)}&width=${width}&height=${height}`;
+      const res = await fetch(url, { headers: getAuthHeaders() });
+      if (!res.ok) throw new Error(`Canvas screenshot failed: ${res.status} ${await res.text()}`);
+      const buffer = await res.arrayBuffer();
+      const base64 = Buffer.from(buffer).toString('base64');
+      return {
+        content: [{ type: 'image', data: base64, mimeType: 'image/png' }],
+      };
     }
-    const filtered = layers.filter(l => l.key !== key);
-    return ok(await api('PATCH', `/api/project/${projectId}`, { layers: filtered }));
+    throw new Error(`Unknown screenshot scope: ${scope}`);
   } catch (error) { return err(error); }
 });
 
-server.tool('reorder_layers', {
-  projectId: z.string().describe('Project ID to reorder layers for'),
-  keys: z.array(z.string()).describe('Ordered array of ALL layer keys. Must contain exactly the same keys as current layers — no additions, removals, or duplicates.'),
-}, async ({ projectId, keys }) => {
+tool('layer', 'Manage layers in a project. Dispatch by `action`: add/update/remove/reorder. Layers are the horizontal bands of a Drafted canvas (e.g. wireframes, designs, brand-assets). All actions take projectId; add/update/remove also take the layer `key`.', {
+  action: z.enum(['add', 'update', 'remove', 'reorder']).describe('Operation to perform.'),
+  projectId: z.string().describe('Project ID (all actions require this)'),
+  key: z.string().optional().describe('[add|update|remove] unique layer key (e.g. "research", "prototypes")'),
+  label: z.string().optional().describe('[add|update] display label'),
+  type: z.string().optional().describe('[add|update] layer type (e.g. "html", "image", "text")'),
+  width: z.number().optional().describe('[add|update] default frame width in pixels'),
+  height: z.number().optional().describe('[add|update] default frame height in pixels'),
+  description: z.string().optional().describe('[add|update] layer description'),
+  prompt: z.string().optional().describe('[add|update] prompt hint for AI agents working in this layer'),
+  force: z.boolean().optional().describe('[remove] force removal even if the layer contains frames'),
+  keys: z.array(z.string()).optional().describe('[reorder] ordered array of ALL existing layer keys — no additions, removals, or duplicates'),
+}, async (args) => {
   try {
-    const project = await api('GET', `/api/project/${projectId}`);
-    const currentLayers = project.layers || [];
-    const currentKeys = currentLayers.map(l => l.key);
-
-    // Check for duplicates
-    const uniqueKeys = new Set(keys);
-    if (uniqueKeys.size !== keys.length) {
-      const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
-      throw new Error(`Duplicate keys: ${[...new Set(dupes)].join(', ')}`);
-    }
-
-    // Check for missing keys
-    const missing = currentKeys.filter(k => !uniqueKeys.has(k));
-    if (missing.length > 0) {
-      throw new Error(`Missing keys: ${missing.join(', ')}. You must include all existing layer keys.`);
-    }
-
-    // Check for extra keys
-    const currentSet = new Set(currentKeys);
-    const extra = keys.filter(k => !currentSet.has(k));
-    if (extra.length > 0) {
-      throw new Error(`Unknown keys: ${extra.join(', ')}. Only existing layer keys are allowed.`);
+    const { action, projectId } = args;
+    if (!projectId) throw new Error('projectId is required');
+    switch (action) {
+      case 'add': {
+        const { key, label, type, width, height, description, prompt } = args;
+        if (!key || !label || !type || width == null || height == null) {
+          throw new Error('key, label, type, width, height are required for action=add');
+        }
+        const project = await api('GET', `/api/project/${projectId}`);
+        const layers = project.layers || [];
+        if (layers.some(l => l.key === key)) {
+          throw new Error(`Layer with key "${key}" already exists in this project`);
+        }
+        const newLayer = { key, label, type, width, height };
+        if (description !== undefined) newLayer.description = description;
+        if (prompt !== undefined) newLayer.prompt = prompt;
+        layers.push(newLayer);
+        return ok(await api('PATCH', `/api/project/${projectId}`, { layers }));
+      }
+      case 'update': {
+        const { key, label, type, width, height, description, prompt } = args;
+        if (!key) throw new Error('key is required for action=update');
+        const project = await api('GET', `/api/project/${projectId}`);
+        const layers = project.layers || project.project?.layers;
+        if (!Array.isArray(layers)) throw new Error('Project has no layers array');
+        const idx = layers.findIndex(l => l.key === key);
+        if (idx === -1) throw new Error(`Layer with key "${key}" not found`);
+        const updates = { label, type, width, height, description, prompt };
+        const filtered = Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== undefined));
+        if (Object.keys(filtered).length === 0) throw new Error('At least one field (label, type, width, height, description, prompt) is required for action=update');
+        layers[idx] = { ...layers[idx], ...filtered };
+        return ok(await api('PATCH', `/api/project/${projectId}`, { layers }));
+      }
+      case 'remove': {
+        const { key, force = false } = args;
+        if (!key) throw new Error('key is required for action=remove');
+        const project = await api('GET', `/api/project/${projectId}`);
+        const layers = project.layers || [];
+        if (!layers.some(l => l.key === key)) {
+          throw new Error(`Layer with key "${key}" does not exist in this project`);
+        }
+        if (!force) {
+          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 frameCount = realFrames.length;
+          if (frameCount > 0) {
+            throw new Error(`Layer "${key}" contains ${frameCount} frame(s). Use force: true to confirm deletion.`);
+          }
+        }
+        const filtered = layers.filter(l => l.key !== key);
+        return ok(await api('PATCH', `/api/project/${projectId}`, { layers: filtered }));
+      }
+      case 'reorder': {
+        const { keys } = args;
+        if (!Array.isArray(keys)) throw new Error('keys (array) is required for action=reorder');
+        const project = await api('GET', `/api/project/${projectId}`);
+        const currentLayers = project.layers || [];
+        const currentKeys = currentLayers.map(l => l.key);
+        const uniqueKeys = new Set(keys);
+        if (uniqueKeys.size !== keys.length) {
+          const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
+          throw new Error(`Duplicate keys: ${[...new Set(dupes)].join(', ')}`);
+        }
+        const missing = currentKeys.filter(k => !uniqueKeys.has(k));
+        if (missing.length > 0) {
+          throw new Error(`Missing keys: ${missing.join(', ')}. You must include all existing layer keys.`);
+        }
+        const currentSet = new Set(currentKeys);
+        const extra = keys.filter(k => !currentSet.has(k));
+        if (extra.length > 0) {
+          throw new Error(`Unknown keys: ${extra.join(', ')}. Only existing layer keys are allowed.`);
+        }
+        const reorderedLayers = keys.map(k => currentLayers.find(l => l.key === k));
+        return ok(await api('PATCH', `/api/project/${projectId}`, { layers: reorderedLayers }));
+      }
+      default:
+        throw new Error(`Unknown layer action: ${action}`);
     }
-
-    const reorderedLayers = keys.map(k => currentLayers.find(l => l.key === k));
-    return ok(await api('PATCH', `/api/project/${projectId}`, { layers: reorderedLayers }));
   } catch (error) { return err(error); }
 });
 
-server.tool('update_layer', {
-  projectId: z.string().describe('Project ID containing the layer'),
-  key: z.string().describe('Layer key to update (e.g. "wireframes", "designs")'),
-  label: z.string().optional().describe('Display label'),
-  type: z.string().optional().describe('Layer type'),
-  width: z.number().optional().describe('Default frame width'),
-  height: z.number().optional().describe('Default frame height'),
-  description: z.string().optional().describe('Layer description'),
-  prompt: z.string().optional().describe('Layer prompt'),
-}, async ({ projectId, key, label, type, width, height, description, prompt }) => {
-  try {
-    const project = await api('GET', `/api/project/${projectId}`);
-    const layers = project.layers || project.project?.layers;
-    if (!Array.isArray(layers)) throw new Error('Project has no layers array');
-
-    const idx = layers.findIndex(l => l.key === key);
-    if (idx === -1) throw new Error(`Layer with key "${key}" not found`);
-
-    const updates = { label, type, width, height, description, prompt };
-    const filtered = Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== undefined));
-    if (Object.keys(filtered).length === 0) throw new Error('At least one field (label, type, width, height, description, prompt) is required');
-
-    layers[idx] = { ...layers[idx], ...filtered };
-    return ok(await api('PATCH', `/api/project/${projectId}`, { layers }));
-  } catch (error) { return err(error); }
-});
-
-server.tool('get_org', {}, async () => {
+tool('get_org', {}, async () => {
   try {
     const data = await api('GET', '/api/orgs');
     const orgs = data.orgs || data || [];
@@ -746,154 +971,207 @@ server.tool('get_org', {}, async () => {
   } catch (error) { return err(error); }
 });
 
-server.tool('search', {
-  query: z.string().describe('Search term to match against frame names'),
-  projectId: z.string().optional().describe('Limit search to a specific project (optional)'),
-}, async ({ query, projectId }) => {
-  try {
-    const params = new URLSearchParams({ q: query });
-    if (projectId) params.set('projectId', projectId);
-    await ensureSession();
-    const url = `${getServerUrl()}/api/search?${params.toString()}`;
-    const res = await fetch(url, { headers: getAuthHeaders() });
-    if (!res.ok) throw new Error(`Search failed: ${res.status}`);
-    const results = await res.json();
-    return ok(results.map(r => ({
-      id: r.id,
-      path: `/${r.layer}/${r.lane}/${r.label}`,
-      project: r.projectName,
-      projectId: r.projectId,
-      frameUrl: `${getServerUrl()}/f/${r.id}`,
-      contentType: r.contentType,
-      updatedAt: r.updatedAt,
-    })));
-  } catch (error) { return err(error); }
-});
-
 // ── Filesystem tools (direct HTTP to /api/fs) ─────────────────────
 
-server.tool('write', 'Write a frame to the ACTIVE PROJECT. Check the "project" field in the response to confirm it went to the right place. Use open_project first if needed.\n\n**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` — the file is uploaded to storage and displayed as an asset frame.\n\n**Dimensions:** By default, frames use the layer\'s default size (e.g., 1440×900 for designs, 1440×3000 for wireframes). This is often too large for small content like a brief or a single component. Use `autoSize: true` to automatically measure the HTML content and size the frame to fit. You can also pass explicit `width`/`height` for precise control. Choose dimensions that match your content — a short text document should be ~800×400, not 1440×3000.', {
-  path: z.string().describe('File path: /{layer}/{lane}/{filename} (e.g. /wireframes/analyse/variant-a.html, /images/tests/login.png). To write MULTIPLE files at once, use the batch tool instead. Returns frameUrl (canvas deep link to view the frame in the browser) and id (frame UUID).'),
-  content: z.string().optional().describe('File content (HTML, markdown, or text). Mutually exclusive with file_path — provide one or the other.'),
-  file_path: z.string().optional().describe('Absolute path to a local file to upload (e.g. /tmp/screenshot.png). The file is read from disk and uploaded to storage. Mutually exclusive with content.'),
-  autoSize: z.boolean().optional().describe('Automatically measure HTML content and size the frame to fit. Recommended for most content. Only applies to content, not file_path.'),
-  width: z.number().optional().describe('Explicit frame width in pixels. Overrides layer default. Ignored if autoSize is true.'),
-  height: z.number().optional().describe('Explicit frame height in pixels. Overrides layer default. Ignored if autoSize is true.'),
-  color: z.string().optional().describe('CSS color for frame border (e.g. #ff0000, red)'),
-}, async ({ path, content, file_path, autoSize, width, height, color }) => {
-  try {
-    // Validate: exactly one of content or file_path
-    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 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}');
-
-    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'];
-      if (TEXT_EXTS.includes(ext)) {
-        // Text file: read as content so it's stored inline (enables base tag injection for HTML)
-        body = { content: readFileSync(resolved, 'utf8') };
-        if (autoSize) body.autoSize = true;
-      } else {
-        // Binary upload: read file from disk, send as base64
-        const buffer = readFileSync(resolved);
-        const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.pdf': 'application/pdf' };
-        body = { base64: buffer.toString('base64'), contentType: MIME[ext] || 'application/octet-stream' };
-      }
-    } else {
-      body = { content };
-      if (autoSize) body.autoSize = true;
-    }
-    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]}/${parts[2]}`, body);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('read', 'Read a frame from the ACTIVE PROJECT. Response includes "project" field confirming which project was read.', {
-  path: z.string().describe('File path /{layer}/{lane}/{filename}, frame URL (any URL containing /f/{uuid}), or bare frame ID (UUID). When a user shares a Drafted frame link, pass it directly here. Use ls to discover paths.'),
-  lines: z.string().optional().describe('Line range (e.g. "1-50", "80-120"). Omit to read all.'),
-}, async ({ path, lines }) => {
-  try {
-    const query = lines ? `?lines=${encodeURIComponent(lines)}` : '';
-
-    // Detect frame URL (e.g. http://host/f/{uuid}) or bare UUID
-    const frameUrlMatch = path.match(/\/f\/([a-f0-9-]{36})/);
-    const uuidMatch = path.match(/^[a-f0-9-]{36}$/);
-    const frameId = frameUrlMatch?.[1] || (uuidMatch ? path : null);
-
-    let result;
-    if (frameId) {
-      result = await api('GET', `/api/fs/by-id/${frameId}${query}`);
-    } else {
-      const parts = path.replace(/^\/+/, '').split('/');
-      if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}, a frame URL, or a frame ID');
-      result = await api('GET', `/api/fs/${parts[0]}/${parts[1]}/${parts[2]}${query}`);
-    }
-
-    // Track full reads (no line range) for anchor enforcement
-    if (!lines && result.ok && result.id) {
-      readFrameIds.add(result.id);
-    }
-
-    return ok(result.content || result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('edit', 'Edit a frame in the ACTIVE PROJECT using hashline operations. Response includes "project" field. Use open_project first if needed.', {
-  path: z.string().describe('File path: /{layer}/{lane}/{filename}. To edit MULTIPLE files at once, use the batch tool instead — it sends one notification instead of many.'),
+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.'),
+  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.'),
+  file_path: z.string().optional().describe('[write] absolute path to a local file to upload. Mutually exclusive with content.'),
+  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 — even identical lines get different hashes.'),
+    lineHash: z.string().describe('4-char hash of the target line (from read output). Each line has a unique hash.'),
     newContent: z.string().optional().describe('New content (for replace, insertAfter, insertBefore)'),
-  })).describe('Hashline edit operations'),
-}, async ({ path, operations }) => {
+  })).optional().describe('[edit] hashline edit operations'),
+  from: z.string().optional().describe('[mv] source path /{layer}/{lane}/{filename}'),
+  to: z.string().optional().describe('[mv] destination path /{layer}/{lane}/{filename}'),
+  anchored: z.boolean().optional().describe('[anchor] true to anchor, false to unanchor. Anchored frames MUST be read before writing/editing in the same layer.'),
+  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)'),
+}, async (args) => {
   try {
-    const anchorErr = await checkAnchors(parseLayer(path));
-    if (anchorErr) return err(new Error(anchorErr));
-    const result = await api('POST', '/api/fs/edit', { path, operations });
-    return ok(result);
+    const { action } = args;
+    switch (action) {
+      case 'read': {
+        const { path, lines } = args;
+        if (!path) throw new Error('path required for action=read');
+        const query = lines ? `?lines=${encodeURIComponent(lines)}` : '';
+        const frameUrlMatch = path.match(/\/f\/([a-f0-9-]{36})/);
+        const uuidMatch = path.match(/^[a-f0-9-]{36}$/);
+        const frameId = frameUrlMatch?.[1] || (uuidMatch ? path : null);
+        let result;
+        if (frameId) {
+          result = await api('GET', `/api/fs/by-id/${frameId}${query}`);
+        } else {
+          const parts = path.replace(/^\/+/, '').split('/');
+          if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}, a frame URL, or a frame ID');
+          result = await api('GET', `/api/fs/${parts[0]}/${parts[1]}/${parts[2]}${query}`);
+        }
+        if (!lines && result.ok && result.id) {
+          readFrameIds.add(result.id);
+        }
+        return ok(result.content || result, {
+          structuredContent: frameStructuredContent(result),
+          _meta: { frameHtml: result.content },
+        });
+      }
+      case 'write': {
+        const { path, content, file_path, autoSize, width, height, color } = 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 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}');
+        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'];
+          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' };
+            body = { base64: buffer.toString('base64'), contentType: MIME[ext] || 'application/octet-stream' };
+          }
+        } else {
+          body = { content };
+          if (autoSize) body.autoSize = true;
+        }
+        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]}/${parts[2]}`, body);
+        return ok(withFrameBreadcrumb(result, { hint: true }), {
+          structuredContent: frameStructuredContent(result),
+          _meta: body.content ? { frameHtml: body.content } : undefined,
+        });
+      }
+      case 'edit': {
+        const { path, operations } = args;
+        if (!path) throw new Error('path required for action=edit');
+        if (!Array.isArray(operations) || operations.length === 0) throw new Error('operations (array) required for action=edit');
+        const anchorErr = await checkAnchors(parseLayer(path));
+        if (anchorErr) return err(new Error(anchorErr));
+        const result = await api('POST', '/api/fs/edit', { path, operations });
+        return ok(result, {
+          structuredContent: frameStructuredContent(result),
+          _meta: result.content ? { frameHtml: result.content } : undefined,
+        });
+      }
+      case 'mv': {
+        const { from, to } = args;
+        if (!from || !to) throw new Error('from and to required for action=mv');
+        const fromErr = await checkAnchors(parseLayer(from));
+        if (fromErr) return err(new Error(fromErr));
+        const toErr = await checkAnchors(parseLayer(to));
+        if (toErr) return err(new Error(toErr));
+        return ok(await api('POST', '/api/fs/mv', { from, to }));
+      }
+      case 'anchor': {
+        const { path, anchored } = args;
+        if (!path) throw new Error('path required for action=anchor');
+        if (typeof anchored !== 'boolean') throw new Error('anchored (boolean) required for action=anchor');
+        return ok(await api('POST', '/api/fs/anchor', { path, anchored }));
+      }
+      case 'search': {
+        const { query, projectId, limit = 50 } = args;
+        if (!query) throw new Error('query required for action=search');
+        const params = new URLSearchParams({ q: query });
+        if (projectId) params.set('projectId', projectId);
+        await ensureSession();
+        const url = `${getServerUrl()}/api/search?${params.toString()}`;
+        const res = await fetch(url, { headers: getAuthHeaders() });
+        if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+        const results = await res.json();
+        const cap = Math.min(Math.max(1, limit || 50), 200);
+        const slice = results.slice(0, cap);
+        return ok({
+          results: slice.map(r => ({
+            id: r.id,
+            path: `/${r.layer}/${r.lane}/${r.label}`,
+            project: r.projectName,
+            projectId: r.projectId,
+            frameUrl: `${getServerUrl()}/f/${r.id}`,
+            contentType: r.contentType,
+            updatedAt: r.updatedAt,
+          })),
+          totalAvailable: results.length,
+          truncated: results.length > cap,
+        });
+      }
+      default:
+        throw new Error(`Unknown frame action: ${action}`);
+    }
   } catch (error) { return err(error); }
 });
 
-server.tool('ls', 'List contents of the ACTIVE PROJECT. Use ls / after open_project to see layers, workflow, and confirm you\'re in the right project.', {
+tool('ls', 'List contents of the ACTIVE PROJECT. Use ls / after project(action="open") to see layers, workflow, and confirm you\'re in the right project.', {
   path: z.string().optional().default('/').describe('Directory path: / (layers), /{layer} (lanes), /{layer}/{lane} (frames). Frame entries include frameUrl (canvas deep link) and id (frame UUID).'),
-  recursive: z.boolean().optional().describe('List contents of subdirectories'),
+  recursive: z.boolean().optional().describe('List contents of subdirectories. When true, forces summary mode (metadata only, no full content) to keep results under the 25k token cap.'),
   summary: z.boolean().optional().describe('Include size, updatedAt, title for frames'),
   pattern: z.string().optional().describe('Glob pattern to filter filenames (e.g. "*.html")'),
-}, async ({ path, recursive, summary, pattern }) => {
+  limit: z.number().optional().default(500).describe('Max entries to return (default 500, max 2000). Use pattern or path to scope further.'),
+}, async ({ path, recursive, summary, pattern, limit }) => {
   try {
     const params = new URLSearchParams();
     params.set('path', path);
-    if (recursive) params.set('recursive', 'true');
-    if (summary) params.set('summary', 'true');
+    // Recursive walks can return huge content payloads — force summary mode
+    // so each entry stays small. Agents that need full content can read individual frames.
+    if (recursive) {
+      params.set('recursive', 'true');
+      params.set('summary', 'true');
+    } else if (summary) {
+      params.set('summary', 'true');
+    }
     if (pattern) params.set('pattern', pattern);
     const result = await api('GET', `/api/fs/?${params.toString()}`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
 
-server.tool('anchor', 'Mark a frame as a context anchor. Anchored frames MUST be read before writing or editing any frame in the same layer. Use this for briefs, style guides, or constraints that should inform all work in this layer.', {
-  path: z.string().describe('File path: /{layer}/{lane}/{filename}'),
-  anchored: z.boolean().describe('true to anchor, false to unanchor'),
-}, async ({ path, anchored }) => {
-  try {
-    const result = await api('POST', '/api/fs/anchor', { path, anchored });
-    return ok(result);
+    // Cap entries client-side as a safety net
+    const cap = Math.min(Math.max(1, limit || 500), 2000);
+    if (Array.isArray(result?.entries) && result.entries.length > cap) {
+      result.totalAvailable = result.entries.length;
+      result.truncated = true;
+      result.entries = result.entries.slice(0, cap);
+    }
+
+    // ChatGPT Apps SDK: canvas-overview widget renders byLayer.
+    const entries = Array.isArray(result?.entries) ? result.entries : [];
+    const byLayer = {};
+    for (const e of entries) {
+      const layer = e.layer || (e.type === 'directory' ? e.name : 'unsorted');
+      (byLayer[layer] ??= []).push({
+        label: e.label || e.name,
+        filename: e.filename || e.name,
+        layer: e.layer,
+        lane: e.lane,
+        frameUrl: e.id ? `${getServerUrl()}/f/${e.id}` : undefined,
+      });
+    }
+    const projectId = getState().projectId;
+    const structuredContent = {
+      project: result?.project || result?.projectName,
+      canvasUrl: result?.projectSlug ? `${getServerUrl()}/project/${result.projectSlug}` : undefined,
+      byLayer,
+      truncated: result?.truncated || false,
+      totalAvailable: result?.totalAvailable,
+    };
+    return ok(result, { structuredContent });
   } catch (error) { return err(error); }
 });
 
-server.tool('rm', 'Delete a frame or lane from the ACTIVE PROJECT. Response includes "project" field.', {
-  path: z.string().describe('Path to delete: /{layer}/{lane}/{filename} or /{layer}/{lane} (deletes entire lane). To delete MULTIPLE files, use the batch tool instead.'),
+tool('rm', 'Delete a frame or lane from the ACTIVE PROJECT. Response includes "project" field.', {
+  path: z.string().describe('Path to delete: /{layer}/{lane}/{filename} or /{layer}/{lane} (deletes entire lane).'),
 }, async ({ path }) => {
   try {
     const anchorErr = await checkAnchors(parseLayer(path));
@@ -904,21 +1182,9 @@ server.tool('rm', 'Delete a frame or lane from the ACTIVE PROJECT. Response incl
   } catch (error) { return err(error); }
 });
 
-server.tool('mv', 'Move/rename a frame within the ACTIVE PROJECT. Response includes "project" field.', {
-  from: z.string().describe('Source path: /{layer}/{lane}/{filename}'),
-  to: z.string().describe('Destination path: /{layer}/{lane}/{filename}'),
-}, async ({ from, to }) => {
-  try {
-    const fromErr = await checkAnchors(parseLayer(from));
-    if (fromErr) return err(new Error(fromErr));
-    const toErr = await checkAnchors(parseLayer(to));
-    if (toErr) return err(new Error(toErr));
-    const result = await api('POST', '/api/fs/mv', { from, to });
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('batch', 'Batch operations on the ACTIVE PROJECT. Response includes "project" field. Use open_project first if needed.', {
+// batch tool temporarily disabled — keep code intact for re-enablement later.
+/*
+tool('batch', 'Batch operations on the ACTIVE PROJECT. Response includes "project" field. Use project(action="open") first if needed.', {
   operations: z.array(z.object({
     tool: z.enum(['write', 'rm', 'mv', 'edit', 'upload_asset']).describe('Tool to execute'),
     path: z.string().optional().describe('Path (for write, rm, edit)'),
@@ -980,8 +1246,8 @@ server.tool('batch', 'Batch operations on the ACTIVE PROJECT. Response includes
         const body = { base64: b64, contentType: ct };
         if (op.frame_id) body.frameId = op.frame_id;
 
-        const projectId = agentActiveProjectId;
-        if (!projectId) throw new Error('No active project. Call open_project first.');
+        const projectId = getState().projectId;
+        if (!projectId) throw new Error('No active project. Call project(action="open") first.');
         const r = await api('PUT', `/api/projects/${projectId}/assets/${op.asset_path}`, body);
         results.push({ ok: true, tool: 'upload_asset', asset_path: op.asset_path, ...r });
       } catch (e) {
@@ -1009,285 +1275,289 @@ server.tool('batch', 'Batch operations on the ACTIVE PROJECT. Response includes
       });
 
       const batchResult = await api('POST', '/api/fs/batch', { operations: resolvedOps });
-      if (batchResult.results) results.push(...batchResult.results);
+      if (batchResult.results) {
+        for (const r of batchResult.results) {
+          results.push(withFrameBreadcrumb(r));
+        }
+      }
     }
 
     return ok({ ok: true, results });
   } catch (error) { return err(error); }
 });
+*/
 
 // ── Asset tools ──────────────────────────────────────────────────
 
-server.tool('upload_asset', 'Upload a supporting file (CSS, JS, image, font) to the ACTIVE PROJECT. Assets are referenced by frames via relative paths — e.g., if your HTML has <link href="css/styles.css">, upload the asset with asset_path="css/styles.css". Assets are NOT frames — they don\'t appear on the canvas. Use batch with upload_asset operations for bulk uploads.', {
-  asset_path: z.string().describe('Relative path for the asset (e.g., "css/styles.css", "js/app.js", "img/logo.png"). This must match the path used in HTML references.'),
-  file_path: z.string().optional().describe('Absolute path to a local file to upload. Mutually exclusive with content/base64.'),
-  content: z.string().optional().describe('Text content (for CSS/JS files). Mutually exclusive with file_path.'),
-  base64: z.string().optional().describe('Base64-encoded binary content. Mutually exclusive with file_path and content.'),
-  content_type: z.string().optional().describe('MIME type (auto-detected from extension if omitted)'),
-  frame_id: z.string().optional().describe('Frame ID to associate this asset with (for cleanup when the frame is deleted). Get this from the write tool response.'),
-}, async ({ asset_path, file_path, content, base64: rawBase64, content_type, frame_id }) => {
+tool('asset', 'Manage supporting files (CSS, JS, images, fonts) in the ACTIVE PROJECT. Assets are referenced by frames via relative paths — e.g., if your HTML has <link href="css/styles.css">, upload with asset_path="css/styles.css". Assets are NOT frames — they don\'t appear on the canvas. `action=upload` to add/replace, `action=list` to browse.', {
+  action: z.enum(['upload', 'list']).describe('Operation to perform.'),
+  asset_path: z.string().optional().describe('[upload] relative asset path (e.g. "css/styles.css"). Must match the path used in HTML references.'),
+  file_path: z.string().optional().describe('[upload] absolute path to a local file. Mutually exclusive with content/base64.'),
+  content: z.string().optional().describe('[upload] text content (for CSS/JS). Mutually exclusive with file_path/base64.'),
+  base64: z.string().optional().describe('[upload] base64-encoded binary content. Mutually exclusive with file_path/content.'),
+  content_type: z.string().optional().describe('[upload] MIME type (auto-detected from extension if omitted).'),
+  frame_id: z.string().optional().describe('[upload|list] associate with / filter by a specific frame. Get frame IDs from frame(action="write") or ls.'),
+}, async (args) => {
   try {
-    if (!asset_path) throw new Error('asset_path is required');
-    if (asset_path.includes('..')) throw new Error('asset_path must not contain ".."');
-
-    let b64, ct;
-    if (file_path) {
-      const resolved = resolve(file_path);
-      if (!existsSync(resolved)) throw new Error(`File not found: ${resolved}`);
-      const buffer = readFileSync(resolved);
-      b64 = buffer.toString('base64');
-      ct = content_type || mimeFromExt(extname(resolved));
-    } else if (content != null) {
-      b64 = Buffer.from(content).toString('base64');
-      ct = content_type || mimeFromExt(extname(asset_path));
-    } else if (rawBase64) {
-      b64 = rawBase64;
-      ct = content_type || mimeFromExt(extname(asset_path));
-    } else {
-      throw new Error('Provide file_path, content, or base64');
+    const { action } = args;
+    const projectId = getState().projectId;
+    if (!projectId) throw new Error('No active project. Call project(action="open") first.');
+    if (action === 'upload') {
+      const { asset_path, file_path, content, base64: rawBase64, content_type, frame_id } = args;
+      if (!asset_path) throw new Error('asset_path is required for action=upload');
+      if (asset_path.includes('..')) throw new Error('asset_path must not contain ".."');
+      let b64, ct;
+      if (file_path) {
+        const resolved = resolve(file_path);
+        if (!existsSync(resolved)) throw new Error(`File not found: ${resolved}`);
+        const buffer = readFileSync(resolved);
+        b64 = buffer.toString('base64');
+        ct = content_type || mimeFromExt(extname(resolved));
+      } else if (content != null) {
+        b64 = Buffer.from(content).toString('base64');
+        ct = content_type || mimeFromExt(extname(asset_path));
+      } else if (rawBase64) {
+        b64 = rawBase64;
+        ct = content_type || mimeFromExt(extname(asset_path));
+      } else {
+        throw new Error('Provide file_path, content, or base64');
+      }
+      const body = { base64: b64, contentType: ct };
+      if (frame_id) body.frameId = frame_id;
+      return ok(await api('PUT', `/api/projects/${projectId}/assets/${asset_path}`, body));
     }
-
-    const body = { base64: b64, contentType: ct };
-    if (frame_id) body.frameId = frame_id;
-
-    const projectId = agentActiveProjectId;
-    if (!projectId) throw new Error('No active project. Call open_project first.');
-
-    const result = await api('PUT', `/api/projects/${projectId}/assets/${asset_path}`, body);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('list_assets', 'List all assets in the ACTIVE PROJECT, optionally filtered by frame.', {
-  frame_id: z.string().optional().describe('Filter assets by frame ID'),
-}, async ({ frame_id }) => {
-  try {
-    const projectId = agentActiveProjectId;
-    if (!projectId) throw new Error('No active project. Call open_project first.');
-    const query = frame_id ? `?frameId=${frame_id}` : '';
-    const result = await api('GET', `/api/projects/${projectId}/assets${query}`);
-    return ok(result);
+    if (action === 'list') {
+      const { frame_id } = args;
+      const query = frame_id ? `?frameId=${frame_id}` : '';
+      return ok(await api('GET', `/api/projects/${projectId}/assets${query}`));
+    }
+    throw new Error(`Unknown asset action: ${action}`);
   } catch (error) { return err(error); }
 });
 
 // ── Shape tool ───────────────────────────────────────────────────────
 
-server.tool('shape', 'Create a flowchart shape on the surface. Shapes are lightweight text nodes — use them for flowcharts, process diagrams, and decision trees. Connect shapes with the connect tool, then call layout to auto-arrange.', {
-  text: z.string().describe('Text to display inside the shape'),
+tool('shape', 'Create a flowchart shape on the surface. Shapes are lightweight text nodes — use them for flowcharts, process diagrams, and decision trees. Connect shapes with connector(action="connect"), then call layout to auto-arrange.', {
+  text: z.string().describe('Text to display inside the shape. Supports multi-line with \\n.'),
   shape: z.enum(['rectangle', 'diamond', 'oval', 'pill']).optional().default('rectangle').describe('Shape type: rectangle (process/action), diamond (decision), oval (start/end), pill (rounded step)'),
   layer: z.string().optional().describe('Layer to place the shape in (default: plans)'),
   lane: z.string().optional().describe('Lane within the layer (default: default)'),
   color: z.string().optional().describe('Border color (CSS color string)'),
-}, async ({ text, shape, layer, lane, color }) => {
+  fill: z.string().optional().describe('Background fill color (CSS color string)'),
+  textColor: z.string().optional().describe('Text color (CSS color string)'),
+  group: z.string().optional().describe('Group ID to assign this shape to (for swim lane clustering). Use the ID returned by the group tool.'),
+  width: z.number().optional().describe('Explicit width in pixels (overrides auto-sizing from text)'),
+  height: z.number().optional().describe('Explicit height in pixels (overrides auto-sizing from text)'),
+  layoutIgnore: z.boolean().optional().describe('Exclude this shape from auto-layout. Use for annotations, labels, or manually positioned elements.'),
+}, async ({ text, shape, layer, lane, color, fill, textColor, group, width, height, layoutIgnore }) => {
   try {
     const body = { text, shape };
     if (layer) body.layer = layer;
     if (lane) body.lane = lane;
     if (color) body.color = color;
+    if (fill) body.fill = fill;
+    if (textColor) body.textColor = textColor;
+    if (group) body.group = group;
+    if (width) body.width = width;
+    if (height) body.height = height;
+    if (layoutIgnore) body.layoutIgnore = true;
     const result = await api('POST', '/api/fs/shape', body);
     return ok(result);
   } catch (error) { return err(error); }
 });
-// ── Connector tools ───────────────────────────────────────────────
 
-server.tool('connect', 'Create a connector (arrow) between two frames on the surface.', {
-  source: z.string().describe('Source frame path or ID'),
-  target: z.string().describe('Target frame path or ID'),
-  label: z.string().optional().describe('Connector label text'),
-  type: z.string().optional().default('arrow-forward').describe('Connector type (default: arrow-forward)'),
-  color: z.string().optional().describe('Connector color (CSS color string)'),
-}, async ({ source, target, label, type, color }) => {
+tool('group', 'Create a group (swim lane / region) on the surface. Groups are labeled, colored background areas that visually contain shapes. Assign shapes to a group using the group parameter on the shape tool. Use layout with groups=true to auto-cluster.', {
+  label: z.string().describe('Group label text (displayed in the header bar)'),
+  color: z.string().optional().describe('Header bar and border color (CSS color string)'),
+  fill: z.string().optional().describe('Background fill color (CSS color string). Defaults to a tinted version of color.'),
+  layer: z.string().optional().describe('Layer to place the group in (default: plans)'),
+  lane: z.string().optional().describe('Lane within the layer (default: default)'),
+  order: z.number().optional().describe('Sort order for group positioning (lower = first). Default: 0'),
+}, async ({ label, color, fill, layer, lane, order }) => {
   try {
-    const body = { source, target };
-    if (label) body.label = label;
-    if (type) body.type = type;
+    const body = { label };
     if (color) body.color = color;
-    const result = await api('POST', '/api/connectors', body);
+    if (fill) body.fill = fill;
+    if (layer) body.layer = layer;
+    if (lane) body.lane = lane;
+    if (order != null) body.order = order;
+    const result = await api('POST', '/api/fs/group', body);
     return ok(result);
   } catch (error) { return err(error); }
 });
+// ── Connector tools ───────────────────────────────────────────────
 
-server.tool('disconnect', 'Remove a connector between frames. Provide either connectorId directly, or source+target to find and remove it.', {
-  source: z.string().optional().describe('Source frame path or ID'),
-  target: z.string().optional().describe('Target frame path or ID'),
-  connectorId: z.string().optional().describe('Connector ID to delete directly'),
-}, async ({ source, target, connectorId }) => {
+tool('connector', 'Create or remove connectors (arrows) between frames on the surface. `action=connect` adds an arrow from source to target. `action=disconnect` removes one — pass either connectorId directly or source+target to find and delete.', {
+  action: z.enum(['connect', 'disconnect']).describe('Operation to perform.'),
+  source: z.string().optional().describe('[connect|disconnect] source frame path or ID'),
+  target: z.string().optional().describe('[connect|disconnect] target frame path or ID'),
+  label: z.string().optional().describe('[connect] connector label text'),
+  type: z.string().optional().describe('[connect] connector type (default: arrow-forward)'),
+  color: z.string().optional().describe('[connect] connector color (CSS color string)'),
+  connectorId: z.string().optional().describe('[disconnect] connector ID to delete directly'),
+}, async (args) => {
   try {
-    if (connectorId) {
-      const result = await api('DELETE', `/api/connectors/${connectorId}`);
-      return ok(result);
+    const { action } = args;
+    if (action === 'connect') {
+      const { source, target, label, type = 'arrow-forward', color } = args;
+      if (!source || !target) throw new Error('source and target required for action=connect');
+      const body = { source, target };
+      if (label) body.label = label;
+      if (type) body.type = type;
+      if (color) body.color = color;
+      return ok(await api('POST', '/api/connectors', body));
     }
-    if (source && target) {
-      // Resolve source/target paths to frame IDs
-      const sourceFrame = await api('GET', `/api/fs/${source.replace(/^\/+/, '')}`);
-      const targetFrame = await api('GET', `/api/fs/${target.replace(/^\/+/, '')}`);
-      const sourceId = sourceFrame.id;
-      const targetId = targetFrame.id;
-      if (!sourceId || !targetId) throw new Error('Could not resolve source or target frame');
-
-      const connectors = await api('GET', '/api/connectors');
-      const match = (connectors.connectors || connectors || []).find(
-        c => c.sourceDesignId === sourceId && c.targetDesignId === targetId
-      );
-      if (!match) throw new Error(`No connector found from ${source} to ${target}`);
-      const result = await api('DELETE', `/api/connectors/${match.id}`);
-      return ok(result);
+    if (action === 'disconnect') {
+      const { source, target, connectorId } = args;
+      if (connectorId) {
+        return ok(await api('DELETE', `/api/connectors/${connectorId}`));
+      }
+      if (source && target) {
+        const sourceFrame = await api('GET', `/api/fs/${source.replace(/^\/+/, '')}`);
+        const targetFrame = await api('GET', `/api/fs/${target.replace(/^\/+/, '')}`);
+        const sourceId = sourceFrame.id;
+        const targetId = targetFrame.id;
+        if (!sourceId || !targetId) throw new Error('Could not resolve source or target frame');
+        const connectors = await api('GET', '/api/connectors');
+        const match = (connectors.connectors || connectors || []).find(
+          c => c.sourceDesignId === sourceId && c.targetDesignId === targetId
+        );
+        if (!match) throw new Error(`No connector found from ${source} to ${target}`);
+        return ok(await api('DELETE', `/api/connectors/${match.id}`));
+      }
+      throw new Error('Provide either connectorId, or both source and target');
     }
-    throw new Error('Provide either connectorId, or both source and target');
+    throw new Error(`Unknown connector action: ${action}`);
   } catch (error) { return err(error); }
 });
 
 // ── Layout tools ──────────────────────────────────────────────────
 
-server.tool('layout', 'Auto-arrange frames using graph layout algorithm. Positions connected frames as a directed graph.', {
-  direction: z.enum(['TB', 'LR', 'BT', 'RL']).optional().default('TB').describe('Layout direction: TB (top-bottom), LR (left-right), BT (bottom-top), RL (right-left)')
-}, async ({ direction }) => {
+tool('layout', 'Auto-arrange frames using graph layout algorithm. Positions connected frames as a directed graph.', {
+  direction: z.enum(['TB', 'LR', 'BT', 'RL']).optional().default('TB').describe('Layout direction: TB (top-bottom), LR (left-right), BT (bottom-top), RL (right-left)'),
+  groups: z.boolean().optional().default(false).describe('Enable group clustering. When true, shapes assigned to a group (via the group param) are clustered together, and group frames are resized to enclose their members.'),
+}, async ({ direction, groups }) => {
   try {
-    const result = await api('POST', '/api/layout', { direction });
+    const body = { direction };
+    if (groups) body.groups = true;
+    const result = await api('POST', '/api/layout', body);
     return ok(result);
   } catch (error) { return err(error); }
 });
 
-// ── Skill library tools ──────────────────────────────────────────
-
-server.tool('search_skills', 'Search the Drafted skill library for reusable agent skills (e.g. "UX", "copywriting", "brand"). Skills are stored prompts, guidelines, and instructions that agents can load and follow. When a user says "use the X skill", search here first.', {
-  query: z.string().optional().describe('Search term (matches name, description, content)'),
-  tags: z.array(z.string()).optional().describe('Filter by tags'),
-  scope: z.enum(['all', 'org', 'global']).optional().default('all').describe('Scope: all (default), org, or global'),
-}, async ({ query, tags, scope }) => {
-  try {
-    const params = new URLSearchParams();
-    if (query) params.set('q', query);
-    if (tags?.length) params.set('tags', tags.join(','));
-    if (scope) params.set('scope', scope);
-    const qs = params.toString();
-    const endpoint = query ? '/api/skills/search' : '/api/skills';
-    const result = await api('GET', `${endpoint}${qs ? '?' + qs : ''}`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('load_skill', 'Load a skill to get its full instructions. Returns the SKILL.md content plus any supporting files. Use search_skills to find skills by keyword first.', {
-  skill: z.string().describe('Skill ID (UUID) or slug'),
-}, async ({ skill }) => {
-  try {
-    const isUuid = /^[a-f0-9-]{36}$/.test(skill);
-    const endpoint = isUuid ? `/api/skills/${skill}` : `/api/skills/slug/${skill}`;
-    const result = await api('GET', endpoint);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('read_skill_file', 'Read a supporting file from a skill directory (e.g. an example, template, or config). Use load_skill first to see available files.', {
-  skillId: z.string().describe('Skill ID'),
-  path: z.string().describe('Relative file path within the skill (e.g. "examples/react.md")'),
-}, async ({ skillId, path }) => {
-  try {
-    const result = await api('GET', `/api/skills/${skillId}/files/${path}`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('add_skill', 'Create a new skill in the org skill library. Creates a skill directory with a root SKILL.md. Use update_skill_file to add supporting files afterward.', {
-  name: z.string().describe('Skill name'),
-  description: z.string().describe('One-line description of what the skill does'),
-  content: z.string().describe('Root SKILL.md content (markdown with instructions/prompts)'),
-  tags: z.array(z.string()).optional().describe('Tags for discovery'),
-  triggerPatterns: z.array(z.string()).optional().describe('Patterns that suggest this skill (e.g. "designing a landing page", "writing tests")'),
-}, async ({ name, description, content, tags, triggerPatterns }) => {
-  try {
-    const body = { name, description, content };
-    if (tags) body.tags = tags;
-    if (triggerPatterns) body.triggerPatterns = triggerPatterns;
-    const result = await api('POST', '/api/skills', body);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('update_skill', 'Update an existing org skill. Can change name, description, content (SKILL.md), tags, or trigger patterns. Cannot edit global skills.', {
-  skillId: z.string().describe('Skill ID to update'),
-  name: z.string().optional().describe('New skill name'),
-  description: z.string().optional().describe('New description'),
-  content: z.string().optional().describe('New root SKILL.md content'),
-  tags: z.array(z.string()).optional().describe('Replace tags'),
-  triggerPatterns: z.array(z.string()).optional().describe('Replace trigger patterns'),
-}, async ({ skillId, name, description, content, tags, triggerPatterns }) => {
-  try {
-    const body = {};
-    if (name !== undefined) body.name = name;
-    if (description !== undefined) body.description = description;
-    if (content !== undefined) body.content = content;
-    if (tags !== undefined) body.tags = tags;
-    if (triggerPatterns !== undefined) body.triggerPatterns = triggerPatterns;
-    if (Object.keys(body).length === 0) throw new Error('At least one field is required');
-    const result = await api('PUT', `/api/skills/${skillId}`, body);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('update_skill_file', 'Add or update a supporting file in a skill directory. Use for examples, templates, configs -- anything beyond the root SKILL.md.', {
-  skillId: z.string().describe('Skill ID'),
-  path: z.string().describe('Relative file path (e.g. "examples/react.md", "templates/component.html")'),
-  content: z.string().describe('File content'),
-}, async ({ skillId, path, content }) => {
-  try {
-    const result = await api('PUT', `/api/skills/${skillId}/files/${path}`, { content });
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('remove_skill', 'Delete a skill from the org library. Also detaches it from all projects. Cannot delete global skills.', {
-  skillId: z.string().describe('Skill ID to delete'),
-}, async ({ skillId }) => {
-  try {
-    const result = await api('DELETE', `/api/skills/${skillId}`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('list_project_skills', 'List skills attached to the active project. These are the skills recommended for this project context.', {}, async () => {
-  try {
-    if (!agentActiveProjectId) throw new Error('No active project. Call open_project first.');
-    const result = await api('GET', `/api/projects/${agentActiveProjectId}/skills`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('attach_skill', 'Attach a skill to the active project. Attached skills are auto-loaded when agents open this project.', {
-  skillId: z.string().describe('Skill ID to attach'),
-}, async ({ skillId }) => {
+// ── Skill library tool ───────────────────────────────────────────
+
+tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. Dispatch by `action`: search/load/list for discovery; add/update/remove for org skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory.', {
+  action: z.enum([
+    'search', 'load', 'list',
+    'add', 'update', 'remove',
+    'attach', 'detach',
+    'favorite', 'unfavorite',
+    'read_file', 'update_file',
+  ]).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)'),
+  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'),
+  name: z.string().optional().describe('[add|update] skill name'),
+  description: z.string().optional().describe('[add|update] one-line description'),
+  content: z.string().optional().describe('[add|update] root SKILL.md content; [update_file] file content'),
+  triggerPatterns: z.array(z.string()).optional().describe('[add|update] patterns that suggest this skill'),
+  path: z.string().optional().describe('[read_file|update_file] relative path inside skill directory (e.g. "examples/react.md")'),
+}, async (args) => {
   try {
-    if (!agentActiveProjectId) throw new Error('No active project. Call open_project first.');
-    const result = await api('POST', `/api/projects/${agentActiveProjectId}/skills`, { skillId });
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('detach_skill', 'Remove a skill from the active project.', {
-  skillId: z.string().describe('Skill ID to detach'),
-}, async ({ skillId }) => {
-  try {
-    if (!agentActiveProjectId) throw new Error('No active project. Call open_project first.');
-    const result = await api('DELETE', `/api/projects/${agentActiveProjectId}/skills/${skillId}`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('favorite_skill', 'Add a skill to your favorites (max 12). Favorited skills appear in list_projects so agents always know about them.', {
-  skillId: z.string().describe('Skill ID to favorite'),
-}, async ({ skillId }) => {
-  try {
-    const result = await api('POST', `/api/skills/favorites/${skillId}`);
-    return ok(result);
-  } catch (error) { return err(error); }
-});
-
-server.tool('unfavorite_skill', 'Remove a skill from your favorites.', {
-  skillId: z.string().describe('Skill ID to unfavorite'),
-}, async ({ skillId }) => {
-  try {
-    const result = await api('DELETE', `/api/skills/favorites/${skillId}`);
-    return ok(result);
+    const { action } = args;
+    switch (action) {
+      case 'search': {
+        const { query, tags, scope = 'all', limit = 25 } = args;
+        const params = new URLSearchParams();
+        if (query) params.set('q', query);
+        if (tags?.length) params.set('tags', tags.join(','));
+        if (scope) params.set('scope', scope);
+        const qs = params.toString();
+        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);
+        }
+        return ok(result);
+      }
+      case 'load': {
+        const { skill } = args;
+        if (!skill) throw new Error('skill (ID or slug) is required for action=load');
+        const isUuid = /^[a-f0-9-]{36}$/.test(skill);
+        const endpoint = isUuid ? `/api/skills/${skill}` : `/api/skills/slug/${skill}`;
+        return ok(await api('GET', endpoint));
+      }
+      case 'list': {
+        if (!getState().projectId) throw new Error('No active project. Call project(action="open") first.');
+        return ok(await api('GET', `/api/projects/${getState().projectId}/skills`));
+      }
+      case 'add': {
+        const { name, description, content, tags, triggerPatterns } = args;
+        if (!name || !description || !content) throw new Error('name, description, content required for action=add');
+        const body = { name, description, content };
+        if (tags) body.tags = tags;
+        if (triggerPatterns) body.triggerPatterns = triggerPatterns;
+        return ok(await api('POST', '/api/skills', body));
+      }
+      case 'update': {
+        const { skillId, name, description, content, tags, triggerPatterns } = args;
+        if (!skillId) throw new Error('skillId required for action=update');
+        const body = {};
+        if (name !== undefined) body.name = name;
+        if (description !== undefined) body.description = description;
+        if (content !== undefined) body.content = content;
+        if (tags !== undefined) body.tags = tags;
+        if (triggerPatterns !== undefined) body.triggerPatterns = triggerPatterns;
+        if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
+        return ok(await api('PUT', `/api/skills/${skillId}`, body));
+      }
+      case 'remove': {
+        const { skillId } = args;
+        if (!skillId) throw new Error('skillId required for action=remove');
+        return ok(await api('DELETE', `/api/skills/${skillId}`));
+      }
+      case 'attach': {
+        const { skillId } = args;
+        if (!skillId) throw new Error('skillId required for action=attach');
+        if (!getState().projectId) throw new Error('No active project. Call project(action="open") first.');
+        return ok(await api('POST', `/api/projects/${getState().projectId}/skills`, { skillId }));
+      }
+      case 'detach': {
+        const { skillId } = args;
+        if (!skillId) throw new Error('skillId required for action=detach');
+        if (!getState().projectId) throw new Error('No active project. Call project(action="open") first.');
+        return ok(await api('DELETE', `/api/projects/${getState().projectId}/skills/${skillId}`));
+      }
+      case 'favorite': {
+        const { skillId } = args;
+        if (!skillId) throw new Error('skillId required for action=favorite');
+        return ok(await api('POST', `/api/skills/favorites/${skillId}`));
+      }
+      case 'unfavorite': {
+        const { skillId } = args;
+        if (!skillId) throw new Error('skillId required for action=unfavorite');
+        return ok(await api('DELETE', `/api/skills/favorites/${skillId}`));
+      }
+      case 'read_file': {
+        const { skillId, path } = args;
+        if (!skillId || !path) throw new Error('skillId and path required for action=read_file');
+        return ok(await api('GET', `/api/skills/${skillId}/files/${path}`));
+      }
+      case 'update_file': {
+        const { skillId, path, content } = args;
+        if (!skillId || !path || content == null) throw new Error('skillId, path, content required for action=update_file');
+        return ok(await api('PUT', `/api/skills/${skillId}/files/${path}`, { content }));
+      }
+      default:
+        throw new Error(`Unknown skill action: ${action}`);
+    }
   } catch (error) { return err(error); }
 });
 
@@ -1304,13 +1574,20 @@ server.resource('info', 'drafted://info', {
       text: JSON.stringify({
         layers: LAYERS,
         pathFormat: '/{layer}/{lane}/{filename}',
-        tools: ['write', 'read', 'edit', 'ls', 'rm', 'mv', 'batch'],
+        tools: ['write', 'read', 'edit', 'ls', 'rm', 'mv'],
       }, null, 2),
     }],
   };
 });
 
+  return server;
+}
+
 // ── Transport ─────────────────────────────────────────────────────
+// Default singleton for stdio mode. HTTP mode in server/server.mjs calls
+// createMcpServer() per request so each transport gets its own server.
+
+export const mcpServer = createMcpServer();
 
 const args = process.argv.slice(2);
 
@@ -1324,7 +1601,7 @@ async function main() {
       sessionIdGenerator: () => randomUUID(),
     });
 
-    await server.connect(transport);
+    await mcpServer.connect(transport);
 
     const httpServer = createServer((req, res) => {
       if (req.url === '/mcp') {
@@ -1341,16 +1618,31 @@ async function main() {
     });
   } else {
     const transport = new StdioServerTransport();
-    await server.connect(transport);
+    await mcpServer.connect(transport);
   }
 }
 
-// Prevent unhandled rejections from killing the stdio transport
-process.on('unhandledRejection', (err) => {
-  console.error('[MCP] Unhandled rejection:', err?.message || err);
-});
+// Only auto-start transports when invoked as a script (drafted-mcp / node mcp/server.mjs).
+// When imported by server/server.mjs for the mounted OAuth route, callers connect their
+// own transport. realpathSync handles the case where drafted-mcp is a symlink (the
+// global npm bin always is) — without it the equality check fails and stdio never starts.
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
 
-main().catch((err) => {
-  console.error('Fatal:', err.message);
-  process.exit(1);
-});
+if (isMain) {
+  // Prevent unhandled rejections from killing the stdio transport
+  process.on('unhandledRejection', (err) => {
+    console.error('[MCP] Unhandled rejection:', err?.message || err);
+  });
+
+  main().catch((err) => {
+    console.error('Fatal:', err.message);
+    process.exit(1);
+  });
+}