slima-mcp 0.1.15 → 0.3.0

package/dist/index.js

@@ -3,6 +3,46 @@
 // src/cli/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/core/schema-compat.ts
+var STRIPPED_SCHEMA_KEYS = ["$schema", "additionalProperties"];
+var STRIPPED = new Set(STRIPPED_SCHEMA_KEYS);
+function stripIncompatibleSchemaKeys(node) {
+  if (Array.isArray(node)) {
+    return node.map((item) => stripIncompatibleSchemaKeys(item));
+  }
+  if (node !== null && typeof node === "object") {
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (STRIPPED.has(key)) continue;
+      out[key] = stripIncompatibleSchemaKeys(value);
+    }
+    return out;
+  }
+  return node;
+}
+function sanitizeOutgoingMessage(message) {
+  const result = message.result;
+  if (!result || !Array.isArray(result.tools)) return message;
+  return {
+    ...message,
+    result: {
+      ...result,
+      tools: result.tools.map((tool) => {
+        const sanitized = { ...tool };
+        for (const field of ["inputSchema", "outputSchema"]) {
+          if (sanitized[field]) sanitized[field] = stripIncompatibleSchemaKeys(sanitized[field]);
+        }
+        return sanitized;
+      })
+    }
+  };
+}
+function withGeminiSchemaCompat(transport) {
+  const send = transport.send.bind(transport);
+  transport.send = (message, options) => send(sanitizeOutgoingMessage(message), options);
+  return transport;
+}
+
 // src/cli/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -33,7 +73,28 @@ var InsufficientCreditsError = class extends SlimaApiError {
     this.name = "InsufficientCreditsError";
   }
 };
+var RateLimitedError = class extends SlimaApiError {
+  constructor(retryAfterSeconds, message) {
+    super(429, "RATE_LIMITED", message || "Rate limited");
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "RateLimitedError";
+  }
+};
+var RequestTimeoutError = class extends SlimaApiError {
+  constructor(timeoutMs) {
+    super(408, "REQUEST_TIMEOUT", `Request timed out after ${Math.round(timeoutMs / 1e3)}s`);
+    this.timeoutMs = timeoutMs;
+    this.name = "RequestTimeoutError";
+  }
+};
 function formatErrorForMcp(error) {
+  if (error instanceof RateLimitedError) {
+    const wait = error.retryAfterSeconds;
+    return wait ? `Rate limited. Wait ${wait} second${wait === 1 ? "" : "s"} and try the same call again \u2014 this is a temporary throttle, not a rejected request.` : "Rate limited. Wait a few seconds and try the same call again \u2014 this is a temporary throttle, not a rejected request.";
+  }
+  if (error instanceof RequestTimeoutError) {
+    return `${error.message}. The server may still be processing it, so re-running a write could duplicate work \u2014 prefer re-reading the current state first.`;
+  }
   if (error instanceof SlimaApiError) {
     switch (error.code) {
       case "UNAUTHORIZED":
@@ -55,6 +116,16 @@ function formatErrorForMcp(error) {
 }
 
 // src/core/api/client.ts
+var REQUEST_TIMEOUT_MS = 6e4;
+function parseRetryAfter(response) {
+  const header = response.headers?.get?.("retry-after");
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds);
+  const when = Date.parse(header);
+  if (Number.isNaN(when)) return void 0;
+  return Math.max(0, Math.ceil((when - Date.now()) / 1e3));
+}
 var defaultLogger = {
   debug: () => {
   },
@@ -86,24 +157,69 @@ var SlimaApiClient = class {
   /**
    * Send API request
    */
-  async request(method, path, body) {
+  async request(method, path, body, options = {}) {
     const url = `${this.baseUrl}${path}`;
     const token = await this.getToken();
     this.logger.debug(`${method} ${path}`);
-    const response = await fetch(url, {
-      method,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-        "User-Agent": "slima-mcp-server/0.1.0"
-      },
-      body: body ? JSON.stringify(body) : void 0
-    });
+    const controller = new AbortController();
+    const deadline = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          "User-Agent": `slima-mcp-server/${"0.3.0"}`
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+        throw new RequestTimeoutError(REQUEST_TIMEOUT_MS);
+      }
+      throw error;
+    } finally {
+      clearTimeout(deadline);
+    }
+    this.handleUpgradeHint(response);
     if (!response.ok) {
       await this.handleErrorResponse(response);
     }
-    const json = await response.json();
-    return json.data;
+    const json3 = await response.json();
+    return options.envelope ? json3 : json3.data;
+  }
+  /**
+   * Like #request but keeps the whole envelope. Paginated endpoints carry the
+   * real total in `meta`, and dropping it is how `list_books` came to report a
+   * capped page as if it were the whole library.
+   *
+   * Delegates to #request rather than re-implementing fetch/auth/error handling:
+   * the first version copied those ~20 lines and had already lost request()'s
+   * debug log, so list_books was the one call invisible at debug level.
+   */
+  async requestWithMeta(method, path) {
+    return this.request(method, path, void 0, {
+      envelope: true
+    });
+  }
+  /**
+   * Surface the X-Slima-MCP-Upgrade-Hint header (if present) as a warn log.
+   * Deduped per (hint, baseUrl) to keep stderr quiet during long sessions.
+   * Defensive: mocked Response objects in tests may not carry a full Headers
+   * interface, so guard the access rather than hard-crashing the request.
+   */
+  loggedUpgradeHints = /* @__PURE__ */ new Set();
+  handleUpgradeHint(response) {
+    const hint = response?.headers?.get?.("X-Slima-MCP-Upgrade-Hint");
+    if (!hint) return;
+    const key = `${hint}::${this.baseUrl}`;
+    if (this.loggedUpgradeHints.has(key)) return;
+    this.loggedUpgradeHints.add(key);
+    this.logger.warn(
+      `[slima-mcp] ${hint} \u2014 upgrade options: npm install -g slima-mcp@latest, or change your Claude Desktop config to "npx -y slima-mcp@0".`
+    );
   }
   /**
    * Handle error response
@@ -123,20 +239,87 @@ var SlimaApiClient = class {
         throw new NotFoundError(message);
       case 402:
         throw new InsufficientCreditsError();
+      case 429:
+        throw new RateLimitedError(parseRetryAfter(response), message);
       default:
         throw new SlimaApiError(response.status, code, message);
     }
   }
   // === Book Operations ===
   /**
-   * List all books
+   * List books (one page). `meta` carries the true total — callers must report
+   * it rather than presenting a page as the whole library.
    */
-  async listBooks() {
-    return this.request("GET", "/api/v1/books?status=active");
+  async listBooks(options = {}) {
+    const page = options.page && options.page > 1 ? `&page=${options.page}` : "";
+    const response = await this.requestWithMeta(
+      "GET",
+      `/api/v1/books?status=active${page}`
+    );
+    return { books: response.data ?? [], meta: response.meta ?? {} };
   }
   /**
    * Get book details
    */
+  // === Teaching surface =====================================================
+  //
+  // These are why the client stays thin. Everything they return is authored and
+  // served by Rails, so the guidance an AI reads updates when the server
+  // deploys — including for the users who pinned an old version of this package,
+  // who are exactly the ones stale guidance would mislead.
+  async getCapabilities() {
+    return this.request("GET", "/api/v1/mcp/capabilities");
+  }
+  async listGuides() {
+    return this.request("GET", "/api/v1/mcp/guides");
+  }
+  async loadGuide(slug) {
+    return this.request("GET", `/api/v1/mcp/guides/${encodeURIComponent(slug)}`);
+  }
+  async listWritingSkills() {
+    return this.request("GET", "/api/v1/mcp/skills");
+  }
+  async loadWritingSkill(key) {
+    return this.request("GET", `/api/v1/mcp/skills/${encodeURIComponent(key)}`);
+  }
+  // === Teams ================================================================
+  async listTeams() {
+    return this.request("GET", "/api/v1/teams");
+  }
+  async getTeam(token) {
+    return this.request("GET", `/api/v1/teams/${token}`);
+  }
+  async listTeamSkills(token) {
+    return this.request("GET", `/api/v1/teams/${token}/skills`);
+  }
+  async listTeamMemories(token) {
+    return this.request("GET", `/api/v1/teams/${token}/memories`);
+  }
+  async listTeamRules(token) {
+    return this.request("GET", `/api/v1/teams/${token}/rules`);
+  }
+  async semanticSearch(bookToken, query, limit) {
+    return this.request("POST", `/api/v1/books/${bookToken}/semantic-search`, { query, limit });
+  }
+  // === Notes and comments ===================================================
+  async listNotes(bookToken) {
+    return this.request("GET", `/api/v1/books/${bookToken}/notes`);
+  }
+  async createNote(bookToken, note) {
+    return this.request("POST", `/api/v1/books/${bookToken}/notes`, { note });
+  }
+  async listComments(bookToken) {
+    return this.request("GET", `/api/v1/books/${bookToken}/comments`);
+  }
+  async createComment(bookToken, comment) {
+    return this.request("POST", `/api/v1/books/${bookToken}/comments`, { comment });
+  }
+  async resolveComment(bookToken, commentToken) {
+    return this.request("POST", `/api/v1/books/${bookToken}/comments/${commentToken}/resolve`);
+  }
+  async reopenComment(bookToken, commentToken) {
+    return this.request("POST", `/api/v1/books/${bookToken}/comments/${commentToken}/reopen`);
+  }
   async getBook(token) {
     return this.request("GET", `/api/v1/books/${token}`);
   }
@@ -263,7 +446,8 @@ var SlimaApiClient = class {
         path: params.path,
         content: params.content || "",
         parent_path: params.parentPath,
-        commit_message: params.commitMessage
+        commit_message: params.commitMessage,
+        content_type: params.contentType
       }
     );
   }
@@ -281,6 +465,42 @@ var SlimaApiClient = class {
       }
     );
   }
+  /**
+   * Field-level operations on a structured file — the ONLY write path for
+   * `.beats` / `.timeline` / `.script`.
+   *
+   * One endpoint takes every type; the type comes from the path's extension.
+   * The separate tool names on this side exist because a tool that writes must
+   * start with a verb, or the desktop agent will not know to ask the human.
+   */
+  async applyStructuredOps(bookToken, params) {
+    return this.request(
+      "POST",
+      `/api/v1/books/${bookToken}/mcp/files/structured`,
+      { path: params.path, intent: params.intent, operations: params.operations }
+    );
+  }
+  /**
+   * Search-and-replace inside a file, applied SERVER-side.
+   *
+   * The old client-side read-modify-write reported a replacement count this
+   * process computed and blind-wrote the whole file back, so concurrent edits
+   * silently clobbered each other while both callers saw a success
+   * (iss_gkqwnovhajzl7xvz). Rails re-reads inside its branch lock.
+   */
+  async editFile(bookToken, params) {
+    return this.request(
+      "POST",
+      `/api/v1/books/${bookToken}/mcp/files/edit`,
+      {
+        path: params.path,
+        old_string: params.oldString,
+        new_string: params.newString,
+        replace_all: params.replaceAll,
+        commit_message: params.commitMessage
+      }
+    );
+  }
   /**
    * Delete file
    */
@@ -290,7 +510,8 @@ var SlimaApiClient = class {
       `/api/v1/books/${bookToken}/mcp/files/delete`,
       {
         path: params.path,
-        commit_message: params.commitMessage
+        commit_message: params.commitMessage,
+        recursive: params.recursive
       }
     );
   }
@@ -308,6 +529,17 @@ var SlimaApiClient = class {
       }
     );
   }
+  /**
+   * Render a structured file (today: .map relationship graphs) as an image
+   * plus a text summary.
+   */
+  async visualizeFile(bookToken, path) {
+    return this.request(
+      "POST",
+      `/api/v1/books/${bookToken}/mcp/files/visualize`,
+      { path }
+    );
+  }
   /**
    * Search file content
    */
@@ -409,10 +641,32 @@ function formatFileTree(files, indent = 0) {
 }
 
 // src/core/tools/books.ts
+function studioLabel(book) {
+  if (book.bookType === "script") return "\u{1F4DD} Script Studio";
+  if (book.bookType === "knowledge") return "\u{1F4DA} Team Knowledge Base";
+  return "\u{1F4D6} Writing Studio";
+}
+function scriptStudioWriteRulesBlock(book) {
+  return `### \u{1F512} Write Restrictions (Script Studio)
+
+This book uses **structured schemas**. Via MCP you can:
+- \u2705 **Read** any file (series.json, *.character, *.scene, etc.)
+- \u2705 **Write / Edit / Delete** under \`.script_studio/planning/**/*\` only (free-form reference tree)
+- \u274C **Cannot modify** structured files (\`series.json\`, \`season.json\`, \`episode.json\`, \`*.character\`, \`*.location\`, \`*.scene\`, \`*.storyline\`, \`*.note\`)
+- \u274C **Cannot modify** \`.script_studio/planning/.initialized\` (frontend bootstrap sentinel)
+
+To add characters / scenes / storylines, use the Script Studio UI in the Slima app.
+
+For full per-book details, read the MCP resource: \`slima://books/${book.token}/schema\`.`;
+}
 function registerBookTools(server, client) {
   server.tool(
     "create_book",
-    "Create a new book in your Slima library",
+    `Create a new **Writing Studio** book in your Slima library.
+
+Only Writing Studio (free-form novels / long-form prose) books can be created via MCP.
+To create a **Script Studio** book (screenwriting with structured series/seasons/episodes/scenes),
+please use the Slima app UI \u2014 MCP does not yet support Script Studio scaffolding.`,
     {
       title: z.string().describe("Book title (required)"),
       author_name: z.string().optional().describe("Author name (optional)"),
@@ -450,12 +704,14 @@ You can now add files using create_file with book_token: ${book.token}`
   );
   server.tool(
     "list_books",
-    "List all books in your Slima library",
-    {},
+    "List the books in your Slima library. Results are paginated; if the response says more books exist, call again with the next `page` before concluding a book is not there.",
+    {
+      page: z.number().optional().describe("Page number (default 1). Only needed when the response says more books exist.")
+    },
     { readOnlyHint: true, openWorldHint: true },
-    async () => {
+    async ({ page }) => {
       try {
-        const books = await client.listBooks();
+        const { books, meta } = await client.listBooks({ page });
         if (books.length === 0) {
           return {
             content: [
@@ -468,16 +724,22 @@ You can now add files using create_file with book_token: ${book.token}`
         }
         const formatted = books.map((book) => {
           const words = book.totalWordCount?.toLocaleString() || "0";
-          return `- **${book.title}** (${book.token})
+          return `- **${book.title}** (${book.token}) \u2014 ${studioLabel(book)}
   Author: ${book.authorName || "N/A"} | Words: ${words}`;
         }).join("\n\n");
+        const currentPage = meta.page ?? 1;
+        const totalPages = meta.totalPages;
+        const hasMore = totalPages !== void 0 && currentPage < totalPages;
+        const header = hasMore ? `Showing ${books.length} of ${meta.total} book(s) \u2014 page ${currentPage} of ${totalPages}. Call list_books again with \`page: ${currentPage + 1}\` for the rest.` : meta.total !== void 0 && meta.total > books.length ? `Showing ${books.length} of ${meta.total} book(s) \u2014 page ${currentPage} of ${totalPages ?? "?"} (this is the last page).` : `Found ${books.length} book(s):`;
         return {
           content: [
             {
               type: "text",
-              text: `Found ${books.length} book(s):
+              text: `${header}
+
+${formatted}
 
-${formatted}`
+_\u{1F4DD} Script Studio books have write restrictions via MCP (see \`get_book\` or resource \`slima://books/{token}/schema\`). \u{1F4D6} Writing Studio books are fully writable._`
             }
           ]
         };
@@ -499,7 +761,7 @@ ${formatted}`
     async ({ book_token }) => {
       try {
         const book = await client.getBook(book_token);
-        const text = `# ${book.title}
+        const header = `# ${studioLabel(book)} \u2014 ${book.title}
 
 - **Token**: ${book.token}
 - **Author**: ${book.authorName || "N/A"}
@@ -510,8 +772,11 @@ ${formatted}`
 - **Reference Words**: ${book.referenceWordCount?.toLocaleString() || "0"}
 - **Created**: ${book.createdAt}
 - **Updated**: ${book.updatedAt}`;
+        const text2 = book.bookType === "script" ? `${header}
+
+${scriptStudioWriteRulesBlock(book)}` : header;
         return {
-          content: [{ type: "text", text }]
+          content: [{ type: "text", text: text2 }]
         };
       } catch (error) {
         return {
@@ -530,7 +795,10 @@ ${formatted}`
     { readOnlyHint: true, openWorldHint: true },
     async ({ book_token }) => {
       try {
-        const commits = await client.listCommits(book_token, 1);
+        const [book, commits] = await Promise.all([
+          client.getBook(book_token),
+          client.listCommits(book_token, 1)
+        ]);
         if (commits.length === 0) {
           return {
             content: [
@@ -544,13 +812,16 @@ ${formatted}`
         const flatSnapshot = commits[0].filesSnapshot;
         const nestedTree = buildFileTree(flatSnapshot);
         const tree = formatFileTree(nestedTree);
+        const footer = book.bookType === "script" ? `
+
+_\u{1F4DD} This is a Script Studio book. Via MCP, writes are restricted to \`.script_studio/planning/**/*\`. For the full write-restriction spec, read resource \`slima://books/${book.token}/schema\`._` : "";
         return {
           content: [
             {
               type: "text",
-              text: `File structure for book ${book_token}:
+              text: `File structure for ${studioLabel(book)} \u2014 ${book.title} (${book_token}):
 
-${tree}`
+${tree}${footer}`
             }
           ]
         };
@@ -564,35 +835,31 @@ ${tree}`
   );
   server.tool(
     "get_writing_stats",
-    "Get writing statistics for a book",
+    `Get word-count totals for a book.
+
+Reports the book's authoritative totals only. Do NOT compute "progress", "words
+written today", or a writing streak from commit history \u2014 Slima prunes intra-day
+commits after 30 days, so any delta derived from "the last N commits" silently
+changes span over time and will not match what the author sees in the app. Those
+figures are account-level and are not exposed here.`,
     {
       book_token: z.string().describe("Book token")
     },
     { readOnlyHint: true, openWorldHint: true },
     async ({ book_token }) => {
       try {
-        const [book, commits] = await Promise.all([
-          client.getBook(book_token),
-          client.listCommits(book_token, 10)
-        ]);
-        let wordChange = 0;
-        if (commits.length > 1) {
-          const latest = commits[0].totalWordCount || 0;
-          const oldest = commits[commits.length - 1].totalWordCount || 0;
-          wordChange = latest - oldest;
-        }
-        const sign = wordChange >= 0 ? "+" : "";
-        const progressText = commits.length > 1 ? `${sign}${wordChange.toLocaleString()} words (last ${commits.length} commits)` : "N/A (not enough history)";
-        const text = `# Writing Stats: ${book.title}
+        const book = await client.getBook(book_token);
+        const text2 = `# Writing Stats: ${book.title}
 
 - **Total Words**: ${book.totalWordCount?.toLocaleString() || "0"}
-- **Manuscript Words**: ${book.manuscriptWordCount?.toLocaleString() || "0"}
-- **Reference Words**: ${book.referenceWordCount?.toLocaleString() || "0"}
-- **Recent Progress**: ${progressText}
-- **Commits Analyzed**: ${commits.length}
-- **Language**: ${book.language || "N/A"}`;
+- **Manuscript Words**: ${book.manuscriptWordCount?.toLocaleString() || "0"} (the book itself \u2014 what counts toward the author's word count)
+- **Reference Words**: ${book.referenceWordCount?.toLocaleString() || "0"} (notes, worldbuilding \u2014 never counted)
+- **Language**: ${book.language || "N/A"}
+- **Last updated**: ${book.updatedAt}
+
+_Daily word count, writing streak and rest protection are account-level in Slima and are not available through this tool. Do not estimate them from commit history \u2014 the figure would not match the author's._`;
         return {
-          content: [{ type: "text", text }]
+          content: [{ type: "text", text: text2 }]
         };
       } catch (error) {
         return {
@@ -606,94 +873,99 @@ ${tree}`
 
 // src/core/tools/content.ts
 import { z as z2 } from "zod";
+
+// src/core/tools/file-read-rendering.ts
+function renderFileRead(result) {
+  if (result.contentWithheld) {
+    return [
+      `# ${result.file.name} \u{1F512}`,
+      "",
+      `**Path:** ${result.file.path}`,
+      `**Words:** ${result.file.wordCount}`,
+      "",
+      "---",
+      "",
+      `The content of this file is withheld from you (reason: ${result.withheldReason ?? "confidential"}).`,
+      "It is a confidential team skill: your team allows it to be USED but not READ,",
+      "so Slima applies it on the server without showing you the source.",
+      "",
+      "This is intentional, not an error and not an empty file. Do not try to rewrite,",
+      'restore or "fix" it \u2014 writes to this path are rejected. If you need its contents,',
+      "ask a team manager."
+    ].join("\n");
+  }
+  if (result.throttled) {
+    return [
+      `# ${result.file.name} \u23F3`,
+      "",
+      `**Path:** ${result.file.path}`,
+      `**Words:** ${result.file.wordCount}`,
+      "",
+      "---",
+      "",
+      `This team skill's read budget is exhausted for now (${result.throttledReason ?? "daily_read_limit"}).`,
+      "The file is not empty \u2014 try again later, or ask a team manager."
+    ].join("\n");
+  }
+  return [
+    `# ${result.file.name}`,
+    "",
+    `**Path:** ${result.file.path}`,
+    `**Words:** ${result.file.wordCount}`,
+    `**Type:** ${result.file.fileType || "unknown"}`,
+    "",
+    "---",
+    "",
+    result.content || "(empty file)"
+  ].join("\n");
+}
+
+// src/core/tools/content.ts
 function registerContentTools(server, client) {
   server.tool(
     "get_chapter",
-    "Read the content of a chapter or file from a book",
+    "Read a chapter or file from a book. Accepts a full path, or just a filename if you are not sure of the folder. If you already know the exact path, `read_file` is equivalent and more direct.",
     {
       book_token: z2.string().describe("Book token (e.g., bk_abc123)"),
-      file_path: z2.string().describe("File path (e.g., /chapters/01.md or chapter-01)")
+      file_path: z2.string().describe("File path (e.g., /chapters/01.md) or just a filename (e.g., 01.md)")
     },
     { readOnlyHint: true, openWorldHint: true },
     async ({ book_token, file_path }) => {
+      const normalized = file_path.replace(/^\//, "");
       try {
-        const commits = await client.listCommits(book_token, 1);
-        if (commits.length === 0) {
+        const result = await client.readFile(book_token, normalized);
+        return { content: [{ type: "text", text: renderFileRead(result) }] };
+      } catch (error) {
+        if (!(error instanceof NotFoundError)) {
           return {
-            content: [
-              {
-                type: "text",
-                text: "No commits found. The book may be empty."
-              }
-            ]
+            content: [{ type: "text", text: formatErrorForMcp(error) }],
+            isError: true
           };
         }
-        const file = findFileInSnapshot(commits[0].filesSnapshot, file_path);
-        if (!file) {
-          const availableFiles = listAllFiles(commits[0].filesSnapshot);
-          const fileList = availableFiles.slice(0, 10).join("\n- ");
-          const moreText = availableFiles.length > 10 ? `
-... and ${availableFiles.length - 10} more files` : "";
-          return {
-            content: [
-              {
-                type: "text",
-                text: `File not found: ${file_path}
+      }
+      try {
+        const { resolvedPath, availablePaths } = await resolveFromStructure(client, book_token, normalized);
+        if (!resolvedPath) {
+          const available = availablePaths;
+          const hint = available.length ? `
 
 Available files:
-- ${fileList}${moreText}
-
-Tip: Use get_book_structure to see the full file tree.`
-              }
-            ],
-            isError: true
-          };
-        }
-        if (file.kind === "folder") {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `"${file_path}" is a folder, not a file. Please specify a file path.`
-              }
-            ],
-            isError: true
-          };
-        }
-        if (!file.blobHash) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `File "${file_path}" has no content (empty file).`
-              }
-            ]
-          };
-        }
-        const blobs = await client.downloadBlobs(book_token, [file.blobHash]);
-        if (blobs.length === 0) {
+- ${available.slice(0, 10).join("\n- ")}${available.length > 10 ? `
+... and ${available.length - 10} more` : ""}` : "";
           return {
             content: [
               {
                 type: "text",
-                text: "Could not retrieve file content. The blob may be missing."
+                text: `File not found: ${file_path}${hint}
+
+Tip: use get_book_structure to see the full file tree.`
               }
             ],
             isError: true
           };
         }
-        const content = blobs[0].content;
-        const wordInfo = file.wordCount ? ` (${file.wordCount} words)` : "";
-        return {
-          content: [
-            {
-              type: "text",
-              text: `# ${file.name}${wordInfo}
-
-${content}`
-            }
-          ]
-        };
+        const result = await client.readFile(book_token, resolvedPath);
+        return { content: [{ type: "text", text: renderFileRead(result) }] };
       } catch (error) {
         return {
           content: [{ type: "text", text: formatErrorForMcp(error) }],
@@ -703,61 +975,36 @@ ${content}`
     }
   );
 }
-function findFileInSnapshot(files, path) {
-  const normalizedPath = path.replace(/^\//, "").toLowerCase();
-  const pathParts = normalizedPath.split("/");
-  function search(items, remainingParts) {
-    for (const item of items) {
-      const itemNameLower = item.name.toLowerCase();
-      const itemTokenLower = item.token.toLowerCase();
-      if (remainingParts.length === 1) {
-        const target = remainingParts[0];
-        if (itemNameLower === target || itemTokenLower === target || itemNameLower.replace(/\.[^.]+$/, "") === target.replace(/\.[^.]+$/, "")) {
-          return item;
-        }
-      }
-      if (item.kind === "folder" && item.children) {
-        if (itemNameLower === remainingParts[0] || itemTokenLower === remainingParts[0]) {
-          const result3 = search(item.children, remainingParts.slice(1));
-          if (result3) return result3;
-        }
-        const result2 = search(item.children, remainingParts);
-        if (result2) return result2;
-      }
-    }
-    return null;
-  }
-  let result = search(files, pathParts);
-  if (result) return result;
-  result = searchByName(files, pathParts[pathParts.length - 1]);
-  return result;
+function fullPathOf(entry, byToken) {
+  const parts = [entry.name];
+  let current = entry;
+  let depth = 0;
+  while (current) {
+    const parentToken = current.parentToken;
+    if (!parentToken) break;
+    const parent = byToken.get(parentToken);
+    if (!parent || depth++ > byToken.size) break;
+    parts.unshift(parent.name);
+    current = parent;
+  }
+  return parts.join("/");
 }
-function searchByName(files, name) {
-  const nameLower = name.toLowerCase();
-  for (const item of files) {
-    const itemNameLower = item.name.toLowerCase();
-    const itemTokenLower = item.token.toLowerCase();
-    if (itemNameLower === nameLower || itemTokenLower === nameLower || itemNameLower.replace(/\.[^.]+$/, "") === nameLower.replace(/\.[^.]+$/, "")) {
-      return item;
-    }
-    if (item.kind === "folder" && item.children) {
-      const result = searchByName(item.children, name);
-      if (result) return result;
-    }
-  }
-  return null;
+function flatten(files) {
+  return files.flatMap((f) => [f, ...f.children ? flatten(f.children) : []]);
 }
-function listAllFiles(files, prefix = "") {
-  const result = [];
-  for (const item of files) {
-    const path = prefix ? `${prefix}/${item.name}` : item.name;
-    if (item.kind === "file") {
-      result.push(path);
-    } else if (item.children) {
-      result.push(...listAllFiles(item.children, path));
-    }
-  }
-  return result;
+async function resolveFromStructure(client, bookToken, needle) {
+  const commits = await client.listCommits(bookToken, 1);
+  if (commits.length === 0) return { resolvedPath: null, availablePaths: [] };
+  const entries = flatten(commits[0].filesSnapshot ?? []);
+  const byToken = new Map(entries.map((e) => [e.token, e]));
+  const wanted = needle.toLowerCase();
+  const stripExt = (value) => value.replace(/\.[^./]+$/, "");
+  const candidates = entries.filter((e) => e.kind !== "folder");
+  const match = candidates.find((e) => fullPathOf(e, byToken).toLowerCase() === wanted) ?? candidates.find((e) => e.name.toLowerCase() === wanted) ?? candidates.find((e) => e.token.toLowerCase() === wanted) ?? candidates.find((e) => fullPathOf(e, byToken).toLowerCase().endsWith(`/${wanted}`)) ?? candidates.find((e) => stripExt(e.name.toLowerCase()) === stripExt(wanted));
+  return {
+    resolvedPath: match ? fullPathOf(match, byToken) : null,
+    availablePaths: candidates.map((e) => fullPathOf(e, byToken))
+  };
 }
 
 // src/core/tools/beta-reader.ts
@@ -826,15 +1073,31 @@ ${formatted}
   );
   server.tool(
     "analyze_chapter",
-    "Get AI Beta Reader feedback on a chapter from a specific reader persona. This may take a moment to complete.",
+    `Get AI Beta Reader feedback on a chapter from a specific reader persona. This may take a moment to complete.
+
+**Not supported for Script Studio books** (\`book_type: "script"\`) \u2014 AI Beta Reader is a Writing Studio feature and does not yet parse \`.scene\` or \`series.json\` structures. Use the Script Studio UI's built-in analysis for screenplays.`,
     {
-      book_token: z3.string().describe("Book token (e.g., bk_abc123)"),
+      book_token: z3.string().describe('Book token (e.g., bk_abc123) \u2014 must be a Writing Studio book (book_type: "book").'),
       file_path: z3.string().describe("Chapter file path (e.g., /chapters/01.md)"),
       persona_token: z3.string().describe("Persona token (e.g., psn_xxx). Use list_personas to find available personas.")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     async ({ book_token, file_path, persona_token }) => {
       try {
+        const book = await client.getBook(book_token);
+        if (book.bookType === "script") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u274C analyze_chapter is not available for Script Studio books.
+
+Book "${book.title}" (${book.token}) is a Script Studio book. Please use the Script Studio UI's built-in analysis features (structural notes, character consistency, scene-level feedback) \u2014 AI Beta Reader is a Writing Studio feature.`
+              }
+            ],
+            isError: true
+          };
+        }
         const commits = await client.listCommits(book_token, 1);
         if (commits.length === 0) {
           return {
@@ -847,7 +1110,7 @@ ${formatted}
             isError: true
           };
         }
-        const file = findFileInSnapshot2(commits[0].filesSnapshot, file_path);
+        const file = findFileInSnapshot(commits[0].filesSnapshot, file_path);
         if (!file) {
           return {
             content: [
@@ -912,9 +1175,14 @@ ${formatted}
             content: [
               {
                 type: "text",
-                text: `Analysis is still in progress. You can check the status later.
+                text: `The report is still being written (${result.progress ?? 0}% complete). It is running on the server and has already been paid for.
+
+Call \`get_reader_test\` with this token in a little while to collect it:
 
-Test ID: ${test.token}`
+  book_token: ${book_token}
+  test_token: ${test.token}
+
+Do NOT call analyze_chapter again for this chapter \u2014 that starts a separate report and charges for it a second time.`
               }
             ]
           };
@@ -932,40 +1200,94 @@ Test ID: ${test.token}`
       }
     }
   );
-}
-async function pollForCompletion(checkFn, timeoutMs, logger2) {
-  const startTime = Date.now();
-  const pollInterval = 3e3;
-  while (Date.now() - startTime < timeoutMs) {
-    const result = await checkFn();
-    logger2.debug(`Poll status: ${result.status}, progress: ${result.progress || "N/A"}`);
-    if (result.status === "completed" || result.status === "failed") {
-      return result;
-    }
-    await sleep(pollInterval);
-  }
-  return { status: "timeout" };
-}
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function formatBetaReaderFeedback(test, fileName) {
-  const feedbacks = test.individualFeedbacks || [];
-  const metrics = test.aggregatedMetrics;
-  if (feedbacks.length === 0 && !metrics) {
-    return "No feedback available.";
-  }
-  let output = `# Beta Reader Feedback: ${fileName}
-
-`;
-  if (metrics) {
-    output += formatAggregatedMetrics(metrics);
-  }
-  if (feedbacks.length > 0) {
-    output += `
----
+  server.tool(
+    "get_reader_test",
+    `Collect an AI Beta Reader report by its test token \u2014 for a report that analyze_chapter started but did not finish inside its wait window.
 
-## Individual Reader Feedback
+Use this rather than calling analyze_chapter again: the report is already running server-side and has already been charged. Re-running starts a second report and charges again.`,
+    {
+      book_token: z3.string().describe("Book token (e.g., bk_abc123)"),
+      test_token: z3.string().describe("Reader test token, as handed back by analyze_chapter when it timed out")
+    },
+    { readOnlyHint: true, openWorldHint: true },
+    async ({ book_token, test_token }) => {
+      try {
+        const progress = await client.getReaderTestProgress(book_token, test_token);
+        if (progress.status === "failed") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "That report failed while running. Start a new one with analyze_chapter."
+              }
+            ],
+            isError: true
+          };
+        }
+        if (progress.status !== "completed") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Still being written (${progress.progress ?? 0}% complete). Call get_reader_test again with the same token shortly \u2014 do not start a new analysis, this one is still running and already paid for.`
+              }
+            ]
+          };
+        }
+        const fullResult = await client.getReaderTest(book_token, test_token);
+        return {
+          content: [
+            { type: "text", text: formatBetaReaderFeedback(fullResult, describeScope(fullResult)) }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatErrorForMcp(error) }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function describeScope(test) {
+  const scopePath = test.scopeConfig?.filePath;
+  return typeof scopePath === "string" && scopePath.length > 0 ? scopePath : `${test.reportType} report`;
+}
+async function pollForCompletion(checkFn, timeoutMs, logger2) {
+  const startTime = Date.now();
+  const pollInterval = 3e3;
+  let lastProgress;
+  while (Date.now() - startTime < timeoutMs) {
+    const result = await checkFn();
+    lastProgress = result.progress;
+    logger2.debug(`Poll status: ${result.status}, progress: ${result.progress || "N/A"}`);
+    if (result.status === "completed" || result.status === "failed") {
+      return result;
+    }
+    await sleep(pollInterval);
+  }
+  return { status: "timeout", progress: lastProgress };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatBetaReaderFeedback(test, fileName) {
+  const feedbacks = test.individualFeedbacks || [];
+  const metrics = test.aggregatedMetrics;
+  if (feedbacks.length === 0 && !metrics) {
+    return "No feedback available.";
+  }
+  let output = `# Beta Reader Feedback: ${fileName}
+
+`;
+  if (metrics) {
+    output += formatAggregatedMetrics(metrics);
+  }
+  if (feedbacks.length > 0) {
+    output += `
+---
+
+## Individual Reader Feedback
 
 `;
     output += feedbacks.map(formatIndividualFeedback).join("\n---\n\n");
@@ -1132,7 +1454,7 @@ ${d.finalThoughts}
   }
   return output;
 }
-function findFileInSnapshot2(files, path) {
+function findFileInSnapshot(files, path) {
   const normalizedPath = path.replace(/^\//, "").toLowerCase();
   const pathParts = normalizedPath.split("/");
   function search(items, remainingParts) {
@@ -1158,10 +1480,10 @@ function findFileInSnapshot2(files, path) {
   }
   let result = search(files, pathParts);
   if (result) return result;
-  result = searchByName2(files, pathParts[pathParts.length - 1]);
+  result = searchByName(files, pathParts[pathParts.length - 1]);
   return result;
 }
-function searchByName2(files, name) {
+function searchByName(files, name) {
   const nameLower = name.toLowerCase();
   for (const item of files) {
     const itemNameLower = item.name.toLowerCase();
@@ -1170,7 +1492,7 @@ function searchByName2(files, name) {
       return item;
     }
     if (item.kind === "folder" && item.children) {
-      const result = searchByName2(item.children, name);
+      const result = searchByName(item.children, name);
       if (result) return result;
     }
   }
@@ -1179,10 +1501,54 @@ function searchByName2(files, name) {
 
 // src/core/tools/files.ts
 import { z as z4 } from "zod";
+
+// src/core/ai-file-policy.ts
+var AI_WRITABLE_EXTENSIONS = [".md", ".markdown", ".txt"];
+var AI_STRUCTURED_TOOLS = {
+  ".beats": "update_beat_board",
+  ".timeline": "update_timeline",
+  ".script": "update_script",
+  ".map": "update_relationship_map",
+  ".geomap": "update_world_map"
+};
+var AI_READONLY_EXTENSIONS = [
+  ".character",
+  ".location",
+  ".json",
+  ".yaml",
+  ".yml"
+];
+var AI_STRUCTURED_VIEWERS = {
+  ".map": "view_relationship_map \u2014 renders the graph as an image plus a cast/relationship summary"
+};
+var AI_WRITE_POLICY_NOTE = `
+**Not every file type takes a generic write.**
+- Field-level tools only: ${Object.entries(AI_STRUCTURED_TOOLS).map(([ext, tool]) => `\`${ext}\` \u2192 \`${tool}\``).join(", ")}
+- Not writable at all: ${AI_READONLY_EXTENSIONS.map((e) => `\`${e}\``).join(", ")}
+
+A refusal names the file type and what to do instead \u2014 it is information, not
+an obstacle to route around. Call \`get_capabilities\` for the authoritative
+table; this list ships with the client and can lag a deploy.`;
+
+// src/core/tools/files.ts
+var SCRIPT_STUDIO_WRITE_WARNING = `
+**IMPORTANT \u2014 Script Studio books (\`book_type: "script"\`):**
+Writes are restricted to \`.script_studio/planning/**/*\` only.
+Structured files (\`series.json\`, \`*.character\`, \`*.scene\`, \`*.storyline\`, \`*.note\`, \`*.location\`, \`season.json\`, \`episode.json\`) are READ-ONLY via MCP \u2014 structural edits must go through the Script Studio UI.
+The sentinel file \`.script_studio/planning/.initialized\` is also read-only (frontend bootstrap marker).
+Attempting to write outside \`planning/\` returns HTTP 400 with code \`INVALID_PATH\`.
+For per-book details, read resource \`slima://books/{book_token}/schema\`.
+
+For Writing Studio books (\`book_type: "book"\`), all paths remain writable.
+Always check \`book_type\` via \`list_books\` or \`get_book\` before writing to an unfamiliar book.`;
+var AI_READONLY_WARNING = AI_WRITE_POLICY_NOTE;
+var CONTENT_TYPE_HINT = `How Slima classifies this file. "manuscript" = the book itself (prose/chapters) \u2014 this is what counts toward the author's word count, daily goal and writing streak. "reference" = notes, worldbuilding, research (never counted). "character" / "location" / "storyline" = planner cards, which are reference plus a label. Omit to inherit the containing folder (root-level files default to "reference"). If you were asked to WRITE a chapter, pass "manuscript" \u2014 otherwise those words will not appear in the author's word count.`;
+var PATH_PARAM_HINT = 'File path relative to book root. For Script Studio books: MUST be under ".script_studio/planning/" (e.g., ".script_studio/planning/references/outline.md"). For Writing Studio books: any path (e.g., "characters/protagonist.md").';
+var SCRIPT_STRUCTURED_EXTENSIONS = ["character", "scene", "storyline", "note", "location"];
 function registerFileTools(server, client) {
   server.tool(
     "read_file",
-    "Read the content of any file in a book by its path",
+    "Read the content of any file in a book by its path. For `.map` relationship graphs, prefer `view_relationship_map` \u2014 this tool returns their raw JSON (node ids and pixel coordinates), which is hard to reason about.",
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
       path: z4.string().describe('File path (e.g., "characters/protagonist.md" or "chapter-01.md")')
@@ -1191,19 +1557,8 @@ function registerFileTools(server, client) {
     async ({ book_token, path }) => {
       try {
         const result = await client.readFile(book_token, path);
-        const fileInfo = [
-          `# ${result.file.name}`,
-          "",
-          `**Path:** ${result.file.path}`,
-          `**Words:** ${result.file.wordCount}`,
-          `**Type:** ${result.file.fileType || "unknown"}`,
-          "",
-          "---",
-          "",
-          result.content || "(empty file)"
-        ].join("\n");
         return {
-          content: [{ type: "text", text: fileInfo }]
+          content: [{ type: "text", text: renderFileRead(result) }]
         };
       } catch (error) {
         return {
@@ -1215,10 +1570,12 @@ function registerFileTools(server, client) {
   );
   server.tool(
     "write_file",
-    "Replace the entire content of an existing file (creates a new commit)",
+    `Replace the entire content of an existing file (creates a new commit).
+${SCRIPT_STUDIO_WRITE_WARNING}
+${AI_READONLY_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path (e.g., "characters/protagonist.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       content: z4.string().describe("New content to write"),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
@@ -1251,66 +1608,36 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "edit_file",
-    "Edit a file by replacing a specific text segment (search and replace). Use this for precise edits instead of rewriting the entire file.",
+    `Replace a specific text segment in a file (search and replace). Use this for precise edits instead of rewriting the whole file.
+
+The replacement is performed by the server inside a lock, so the reported count is what was actually written \u2014 not a local guess. If the text is missing or ambiguous the call fails with a message telling you what to do next; act on it rather than retrying the same arguments.
+${SCRIPT_STUDIO_WRITE_WARNING}
+${AI_READONLY_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path (e.g., "characters/protagonist.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       old_string: z4.string().describe("The exact text to find and replace (must match exactly, including whitespace)"),
-      new_string: z4.string().describe("The new text to replace it with"),
-      replace_all: z4.boolean().optional().describe("Replace all occurrences (default: false, replaces only first match)"),
+      new_string: z4.string().describe("The new text to replace it with (pass an empty string to delete)"),
+      replace_all: z4.boolean().optional().describe("Replace all occurrences (default: false, replaces only the first match)"),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
     async ({ book_token, path, old_string, new_string, replace_all, commit_message }) => {
       try {
-        const fileData = await client.readFile(book_token, path);
-        const currentContent = fileData.content || "";
-        if (!currentContent.includes(old_string)) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Edit failed: Could not find the specified text in the file.
-
-**Looking for:**
-\`\`\`
-${old_string.slice(0, 200)}${old_string.length > 200 ? "..." : ""}
-\`\`\`
-
-**Tip:** Make sure the text matches exactly, including whitespace and line breaks.`
-              }
-            ],
-            isError: true
-          };
-        }
-        if (!replace_all) {
-          const occurrences = currentContent.split(old_string).length - 1;
-          if (occurrences > 1) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `\u274C Edit failed: Found ${occurrences} occurrences of the text. Please provide a more specific/longer text segment to ensure a unique match, or set replace_all: true to replace all occurrences.`
-                }
-              ],
-              isError: true
-            };
-          }
-        }
-        const newContent = replace_all ? currentContent.split(old_string).join(new_string) : currentContent.replace(old_string, new_string);
-        const result = await client.updateFile(book_token, {
+        const result = await client.editFile(book_token, {
           path,
-          content: newContent,
-          commitMessage: commit_message || `Edit ${path}`
+          oldString: old_string,
+          newString: new_string,
+          replaceAll: replace_all,
+          commitMessage: commit_message
         });
-        const replacementCount = replace_all ? currentContent.split(old_string).length - 1 : 1;
         return {
           content: [
             {
               type: "text",
-              text: `\u2705 File edited successfully.
+              text: `\u2705 File edited.
 
-**Replacements:** ${replacementCount}
+**Replacements applied by the server:** ${result.replacements}
 **Commit:** ${result.commit.token}
 **Message:** ${result.commit.name || result.commit.message}`
             }
@@ -1326,21 +1653,35 @@ ${old_string.slice(0, 200)}${old_string.length > 200 ? "..." : ""}
   );
   server.tool(
     "create_file",
-    "Create a new file in a book (creates a new commit)",
+    `Create a new file in a book (creates a new commit).
+
+**Writing a chapter? Pass \`content_type: "manuscript"\`.** Files default to
+"reference" (not counted in the author's word count, streak, or manuscript export)
+unless they inherit a manuscript folder or you say otherwise.
+${SCRIPT_STUDIO_WRITE_WARNING}
+${AI_READONLY_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path including parent folders (e.g., "characters/new-character.md")'),
+      path: z4.string().describe(
+        `${PATH_PARAM_HINT} Parent folders are auto-created (mkdir -p behavior).`
+      ),
       content: z4.string().optional().describe("Initial content (optional, defaults to empty)"),
+      content_type: z4.enum(["manuscript", "reference", "character", "location", "storyline"]).optional().describe(CONTENT_TYPE_HINT),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    async ({ book_token, path, content, commit_message }) => {
+    async ({ book_token, path, content, content_type, commit_message }) => {
       try {
         const result = await client.createFile(book_token, {
           path,
           content: content || "",
+          contentType: content_type,
           commitMessage: commit_message
         });
+        const classification = content_type ? `Classified as: ${content_type}${content_type === "manuscript" ? " (counts toward the word count)" : " (not counted in the word count)"}` : "Classified by inheriting the parent folder (root-level defaults to reference, which is NOT counted in the word count).";
+        const notes = (result.notes ?? []).map((n) => `
+
+\u26A0\uFE0F ${n}`).join("");
         return {
           content: [
             {
@@ -1349,7 +1690,8 @@ ${old_string.slice(0, 200)}${old_string.length > 200 ? "..." : ""}
 
 File Token: ${result.fileToken}
 Commit: ${result.commit.token}
-Message: ${result.commit.name || result.commit.message}`
+Message: ${result.commit.name || result.commit.message}
+${classification}${notes}`
             }
           ]
         };
@@ -1363,27 +1705,42 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "delete_file",
-    "Delete a file from a book (creates a new commit)",
+    `Delete a file or an empty folder from a book (creates a new commit).
+
+A folder that still has anything inside it is refused unless you pass
+\`recursive: true\`. That is not bureaucracy: deleting only the folder would
+leave its contents with no parent, and the app then shows the whole subtree at
+the book's top level \u2014 the author sees their files scattered, with no error.
+Say the word and everything inside goes, and you are told how many.
+${SCRIPT_STUDIO_WRITE_WARNING}
+${AI_READONLY_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path to delete (e.g., "old-notes.md")'),
-      commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
+      path: z4.string().describe(PATH_PARAM_HINT),
+      commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)"),
+      recursive: z4.boolean().optional().describe("Required to delete a folder that is not empty \u2014 everything inside goes with it")
     },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
-    async ({ book_token, path, commit_message }) => {
+    async ({ book_token, path, commit_message, recursive }) => {
       try {
         const result = await client.deleteFile(book_token, {
           path,
-          commitMessage: commit_message
+          commitMessage: commit_message,
+          recursive
         });
         return {
           content: [
             {
               type: "text",
-              text: `File deleted successfully.
-
-Commit: ${result.commit.token}
-Message: ${result.commit.name || result.commit.message}`
+              text: [
+                "File deleted successfully.",
+                // The model asked to delete one path; several may have gone. It has to
+                // be able to tell the author that.
+                result.deletedDescendants ? `${result.deletedDescendants} item(s) inside it were deleted too \u2014 tell the author.` : null,
+                "",
+                `Commit: ${result.commit.token}`,
+                `Message: ${result.commit.name || result.commit.message}`
+              ].filter((line) => line !== null).join("\n")
             }
           ]
         };
@@ -1397,10 +1754,12 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "append_to_file",
-    "Append content to the end of an existing file (creates a new commit)",
+    `Append content to the end of an existing file (creates a new commit).
+${SCRIPT_STUDIO_WRITE_WARNING}
+${AI_READONLY_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path (e.g., "notes.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       content: z4.string().describe("Content to append"),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
@@ -1431,29 +1790,102 @@ Message: ${result.commit.name || result.commit.message}`
       }
     }
   );
+  server.tool(
+    "view_relationship_map",
+    `See a \`.map\` character-relationship graph as a picture plus a readable summary.
+
+Use this instead of \`read_file\` for \`.map\` files: their raw JSON is node ids and pixel coordinates.
+The summary lists every character, every relationship ("A \u2014childhood friends\u2192 B") and any faction groups,
+so it is useful even in clients that do not display images.
+
+\`.map\` files are read-only to AI \u2014 describe changes you recommend in words; the author edits them in the map editor.`,
+    {
+      book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
+      path: z4.string().describe('Path to a .map file (e.g., "world/relations.map")')
+    },
+    { readOnlyHint: true, openWorldHint: true },
+    async ({ book_token, path }) => {
+      try {
+        const result = await client.visualizeFile(book_token, path);
+        if (result.contentWithheld) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u{1F512} "${path}" is a confidential team skill. Its contents are withheld from you by your team's settings (reason: ${result.withheldReason ?? "confidential"}). This is intentional, not an error \u2014 do not try to rewrite it.`
+              }
+            ]
+          };
+        }
+        if (result.throttled) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u23F3 Read budget for this team skill is exhausted for today (${result.throttledReason ?? "daily_read_limit"}). Try again later; the file is not empty.`
+              }
+            ]
+          };
+        }
+        const content = [{ type: "text", text: result.summary ?? "(no summary available)" }];
+        if (result.format === "png" && result.image) {
+          content.push({ type: "image", data: result.image, mimeType: "image/png" });
+        } else if (result.imageUnavailable) {
+          content.push({
+            type: "text",
+            text: `_(The image could not be rendered on the server, so only the summary above is available.)_`
+          });
+        }
+        return { content };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatErrorForMcp(error) }],
+          isError: true
+        };
+      }
+    }
+  );
   server.tool(
     "search_content",
-    "Search for content across all files in a book",
+    `Search for content across all files in a book.
+
+**Script Studio behavior:** By default, structured files (\`*.character\`, \`*.scene\`, \`*.storyline\`, \`*.note\`, \`*.location\`, and \`*.json\` under \`.script_studio/\`) are **excluded** from search results \u2014 their raw JSON is noisy and not useful for full-text search.
+Pass \`include_structured: true\` to search those files too.
+Writing Studio books are unaffected by this filter.`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
       query: z4.string().describe('Search query (e.g., "blue eyes" or "protagonist name")'),
-      file_types: z4.array(z4.string()).optional().describe('Filter by file types (e.g., ["markdown", "txt"])'),
-      limit: z4.number().optional().describe("Maximum number of matches to return (default: 20)")
+      file_types: z4.array(z4.string()).optional().describe('Filter by file extension, with or without the dot: ["md", ".txt", "beats"]'),
+      limit: z4.number().optional().describe("Maximum number of matches to return (default: 20)"),
+      include_structured: z4.boolean().optional().describe(
+        "Script Studio only: set to true to include structured files (*.character / *.scene / etc.) in search results. Default: false (excluded)."
+      )
     },
     { readOnlyHint: true, openWorldHint: true },
-    async ({ book_token, query, file_types, limit }) => {
+    async ({ book_token, query, file_types, limit, include_structured }) => {
       try {
+        let bookType;
+        if (!include_structured) {
+          try {
+            const book = await client.getBook(book_token);
+            bookType = book.bookType;
+          } catch {
+          }
+        }
         const result = await client.searchFiles(book_token, {
           query,
           fileTypes: file_types,
           limit
         });
-        if (result.matches.length === 0) {
+        const shouldFilter = !include_structured && bookType === "script";
+        const filteredMatches = shouldFilter ? result.matches.filter((m) => !isStructuredScriptFile(m.file.path)) : result.matches;
+        if (filteredMatches.length === 0) {
+          const suffix = shouldFilter && result.matches.length > 0 ? ` (${result.matches.length} match(es) in structured files were excluded \u2014 pass include_structured: true to see them)` : "";
           return {
             content: [
               {
                 type: "text",
-                text: `No matches found for "${query}".`
+                text: `No matches found for "${query}"${suffix}.`
               }
             ]
           };
@@ -1461,10 +1893,17 @@ Message: ${result.commit.name || result.commit.message}`
         const output = [
           `# Search Results for "${query}"`,
           "",
-          `Found ${result.matches.length} file(s) with matches:`,
+          `Found ${filteredMatches.length} file(s) with matches:`,
           ""
         ];
-        for (const match of result.matches) {
+        if (shouldFilter && filteredMatches.length < result.matches.length) {
+          const excluded = result.matches.length - filteredMatches.length;
+          output.push(
+            `_Note: excluded ${excluded} Script Studio structured file(s). Pass include_structured: true to include them._`
+          );
+          output.push("");
+        }
+        for (const match of filteredMatches) {
           output.push(`## ${match.file.path}`);
           output.push(`Words: ${match.file.wordCount} | Matches: ${match.matchCount}`);
           output.push("");
@@ -1485,6 +1924,611 @@ Message: ${result.commit.name || result.commit.message}`
     }
   );
 }
+function isStructuredScriptFile(path) {
+  if (!path) return false;
+  const lower = path.toLowerCase();
+  if (lower.startsWith(".script_studio/") && lower.endsWith(".json")) return true;
+  const ext = lower.split(".").pop();
+  if (!ext) return false;
+  return SCRIPT_STRUCTURED_EXTENSIONS.includes(ext);
+}
+
+// src/core/tools/structured.ts
+import { z as z5 } from "zod";
+var TYPES = [
+  {
+    tool: "update_beat_board",
+    extension: ".beats",
+    noun: "beat board",
+    ops: "add_act, update_act, remove_act, add_beat, update_beat, remove_beat, move_beat",
+    example: '{"op": "add_act", "name": "Act Two", "op_ref": "A2"}, {"op": "add_beat", "title": "The turn", "act_id": "@A2"}'
+  },
+  {
+    tool: "update_timeline",
+    extension: ".timeline",
+    noun: "timeline",
+    ops: "add_entry, update_entry, remove_entry, set_config",
+    example: '{"op": "add_entry", "title": "The siege begins", "time_mode": "label", "time_label": "Winter"}'
+  },
+  {
+    tool: "update_script",
+    extension: ".script",
+    noun: "screenplay",
+    ops: "add_scene, update_scene_heading, remove_scene, add_element, update_element, remove_element",
+    example: '{"op": "add_scene", "interior": true, "location": "HARBOUR", "op_ref": "S1"}, {"op": "add_element", "scene_id": "@S1", "type": "action", "text": "The fog lifts."}'
+  },
+  {
+    tool: "update_relationship_map",
+    extension: ".map",
+    noun: "relationship map",
+    ops: "add_node, update_node, move_node, remove_node, add_edge, update_edge, remove_edge, add_group, update_group, remove_group, set_meta",
+    example: '{"op": "add_node", "label": "Lin Shuang", "op_ref": "N1", "position": {"near_id": "<id of Shen Yan>", "direction": "right"}}, {"op": "add_edge", "source_id": "<id of Shen Yan>", "target_id": "@N1", "label": "mentor"}',
+    extra: '**Position is content here, not layout.** `update_node` will not move anything \u2014 that is\n`move_node`, so that "I moved her next to him" is its own reviewable change. Prefer\n`{near_id, direction}` over computing numbers. Existing nodes never move; the final\ncoordinates come back in the notes. Group boxes are computed from `member_ids` \u2014 never\nsend x/y/width/height. Removing a node removes its edges, and you are told so.'
+  },
+  {
+    tool: "update_world_map",
+    extension: ".geomap",
+    noun: "world map",
+    ops: "add_place, update_place, add_label, update_label, remove_element, add_river, add_border, paint_region, set_meta",
+    example: '{"op": "add_place", "x": 210, "y": 96, "name": "Starhaven", "tier": "port"}, {"op": "add_label", "x": 240, "y": 60, "text": "The Cold Sea", "size": "large"}',
+    extra: "**Coordinates are grid cells, not pixels**: x 0-519, y 0-363. `read_file` gives you the\nmap with its three terrain grids replaced by a note \u2014 they are machine-encoded and you\ndo not need them; `paint_region` works in cells. `remove_element` takes any element id\n(`pl_` place, `lb_` label, `rv_` river, `bd_` border). Terrain has no undo: paint over it\ninstead. Move a place with `update_place`, never by removing and re-adding it. An unknown\nplace `tier` is refused with the full list of real ones \u2014 read the error, do not guess."
+  }
+];
+var SHARED_RULES = `
+**Read the file first.** Every id you send must come from that read \u2014 never
+invent one, never retype one from memory. An unknown id is refused with the
+list of real ones, so a mistake costs a round trip, not the author's data.
+
+**One operation per change.** Each operation takes only its own arguments; a
+field belonging to a different operation is refused rather than ignored.
+
+**\`op_ref\` chains within one batch.** Label what an operation creates with
+\`op_ref: "A2"\`, then a LATER operation can point at it as \`"@A2"\`. Backward
+references only, and only inside this one batch \u2014 a later call must use the
+real id, which comes back in \`applied\`.
+
+**The batch is all-or-nothing.** If one operation fails nothing is written, so
+you never have to work out how far it got.
+
+**Unlike the in-app assistant, there is no review panel here.** What you send
+lands in the author's version history immediately. Say what you changed, not
+"please confirm it".`;
+function describe(type) {
+  return `Change a Slima ${type.noun} (\`${type.extension}\`) one field at a time.
+
+This is the ONLY way to write this file type \u2014 \`write_file\` and \`edit_file\`
+are refused for it, because a whole-file write would drop the parts of the
+document you were never shown.
+
+Operations: ${type.ops}
+Example \`operations\`: [${type.example}]
+${SHARED_RULES}${type.extra ? `
+
+${type.extra}` : ""}`;
+}
+function render(type, result) {
+  const lines = [`Applied ${result.applied.length} change(s) to the ${type.noun}.`, ""];
+  const created = result.applied.filter((a) => a.id);
+  if (created.length > 0) {
+    lines.push("**New ids** (use these in later calls \u2014 do not re-read just for them):");
+    for (const a of created) lines.push(`- \`${a.op}\` \u2192 ${a.id}${a.op_ref ? ` (was @${a.op_ref})` : ""}`);
+    lines.push("");
+  }
+  if (result.notes.length > 0) {
+    lines.push("**Also happened, tell the author:**");
+    for (const note of result.notes) lines.push(`- ${note}`);
+    lines.push("");
+  }
+  lines.push(`**Commit:** ${result.commit.token}`);
+  return lines.join("\n");
+}
+function registerStructuredTools(server, client) {
+  for (const type of TYPES) {
+    server.tool(
+      type.tool,
+      describe(type),
+      {
+        book_token: z5.string().describe("Book token (e.g., bk_abc123)"),
+        path: z5.string().describe(`Path to the ${type.extension} file (e.g., "plan/board${type.extension}")`),
+        intent: z5.string().describe(
+          `One line in the author's own language saying what this batch does \u2014 it becomes the commit message they read later. Not "batch update".`
+        ),
+        operations: z5.array(z5.record(z5.unknown())).describe(
+          "The changes, in order. Each is a flat object: `op` names the operation and the other keys are that operation's arguments. There is no nested `args`."
+        )
+      },
+      { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      async ({ book_token, path, intent, operations }) => {
+        try {
+          const result = await client.applyStructuredOps(book_token, {
+            path,
+            intent,
+            operations
+          });
+          return { content: [{ type: "text", text: render(type, result) }] };
+        } catch (error) {
+          return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+        }
+      }
+    );
+  }
+}
+
+// src/core/tools/teaching.ts
+import { z as z6 } from "zod";
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+function text(body) {
+  return { content: [{ type: "text", text: body }] };
+}
+function failure(error) {
+  return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+}
+function registerTeachingTools(server, client) {
+  server.tool(
+    "get_capabilities",
+    `What this Slima server supports: which file extensions an AI may write, the content types, the available tools, and the guide index.
+
+Call this once at the start of a Slima session, before writing anything. Every field is derived from the contract the server actually enforces, so it cannot drift from real behaviour the way a written description can.`,
+    {},
+    READ_ONLY,
+    async () => {
+      try {
+        return text(JSON.stringify(await client.getCapabilities(), null, 2));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  server.tool(
+    "list_guides",
+    `List the available Slima guides: titles and one-line summaries of when to load each.
+
+Guides teach how to operate Slima \u2014 file structure, version control, team knowledge bases, the relationship-map format. Load one with \`load_guide\` when you are about to do the thing it covers.`,
+    {},
+    READ_ONLY,
+    async () => {
+      try {
+        const result = await client.listGuides();
+        const rows = result.guides.map((g) => `- **${g.slug}** \u2014 ${g.title}
+  ${g.summary}`);
+        return text(`## Slima guides
+
+${rows.join("\n")}`);
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  server.tool(
+    "load_guide",
+    `Load one Slima guide in full.
+
+Read \`book-structure\` before creating files, \`version-control-basics\` before a large rewrite, \`team-knowledge-base\` when working in a publisher's team, \`beta-reader\` before spending the author's credits on a report. \`list_guides\` has the current set.`,
+    {
+      slug: z6.string().describe('Guide slug, e.g. "book-structure" (from list_guides)')
+    },
+    READ_ONLY,
+    async ({ slug }) => {
+      try {
+        const guide = await client.loadGuide(slug);
+        return text(`# ${guide.title}
+
+${guide.body}`);
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  server.tool(
+    "list_writing_skills",
+    `List Slima's writing skills \u2014 the craft procedures the in-app coach follows for tasks like developing a character, revising a scene, or diagnosing pacing.
+
+Use these when the task is about the WRITING. Use \`list_guides\` when the task is about operating Slima.`,
+    {},
+    READ_ONLY,
+    async () => {
+      try {
+        const result = await client.listWritingSkills();
+        const rows = result.skills.map((s) => `- **${s.key}** \u2014 ${s.name}: ${s.description}`);
+        return text(`## Writing skills
+
+${rows.join("\n")}`);
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  server.tool(
+    "load_writing_skill",
+    `Load one writing skill in full \u2014 a step-by-step procedure plus the questions a coach would ask.
+
+Follow it rather than summarising it at the author.`,
+    {
+      key: z6.string().describe('Skill key, e.g. "character_develop" (from list_writing_skills)')
+    },
+    READ_ONLY,
+    async ({ key }) => {
+      try {
+        const skill = await client.loadWritingSkill(key);
+        return text(`# ${skill.name}
+
+${skill.body}`);
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+}
+
+// src/core/tools/teams.ts
+import { z as z7 } from "zod";
+var READ_ONLY2 = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+function json(body) {
+  return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+function failure2(error) {
+  return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+}
+var TEAM_TOKEN = z7.string().describe("Team token (from list_teams)");
+function registerTeamTools(server, client) {
+  server.tool(
+    "list_teams",
+    `List the teams this account belongs to \u2014 publishers, studios, writing groups.
+
+A team book carries house rules and shared knowledge that change how you should write for it. If a book belongs to a team, read \`list_team_rules\` before writing.`,
+    {},
+    READ_ONLY2,
+    async () => {
+      try {
+        return json(await client.listTeams());
+      } catch (error) {
+        return failure2(error);
+      }
+    }
+  );
+  server.tool(
+    "get_team",
+    "Get one team: its members and their roles.",
+    { team_token: TEAM_TOKEN },
+    READ_ONLY2,
+    async ({ team_token }) => {
+      try {
+        return json(await client.getTeam(team_token));
+      } catch (error) {
+        return failure2(error);
+      }
+    }
+  );
+  server.tool(
+    "list_team_rules",
+    `The team's coaching rules \u2014 its house style \u2014 each marked mandatory or advisory.
+
+Read these BEFORE writing for a team book, not after a draft is rejected. Mandatory rules are not suggestions: prose that ignores one gets re-edited by a person, which is worse than not writing it.`,
+    { team_token: TEAM_TOKEN },
+    READ_ONLY2,
+    async ({ team_token }) => {
+      try {
+        return json(await client.listTeamRules(team_token));
+      } catch (error) {
+        return failure2(error);
+      }
+    }
+  );
+  server.tool(
+    "list_team_memories",
+    `What the team has established over time: recurring characters, naming conventions, continuity spanning books, decisions already argued through.
+
+Treat these as settled. If one contradicts a book's text, say so rather than picking a side.`,
+    { team_token: TEAM_TOKEN },
+    READ_ONLY2,
+    async ({ team_token }) => {
+      try {
+        return json(await client.listTeamMemories(team_token));
+      } catch (error) {
+        return failure2(error);
+      }
+    }
+  );
+  server.tool(
+    "list_team_skills",
+    `The team's own writing procedures.
+
+Some are marked \`confidential: true\` and come back WITHOUT a source path; their file contents are withheld from this connection. That is deliberate, and it does not stop the skill working \u2014 the server applies it on the team's behalf. Do not try to reconstruct one, reproduce it verbatim, or reach its contents by another route: those routes are closed and audited. Read the \`team-knowledge-base\` guide before working in a team knowledge base.`,
+    { team_token: TEAM_TOKEN },
+    READ_ONLY2,
+    async ({ team_token }) => {
+      try {
+        return json(await client.listTeamSkills(team_token));
+      } catch (error) {
+        return failure2(error);
+      }
+    }
+  );
+}
+
+// src/core/tools/workspace.ts
+import { z as z8 } from "zod";
+var READ_ONLY3 = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var WRITES = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var BOOK_TOKEN = z8.string().describe("Book token (bk_...)");
+function json2(body) {
+  return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+function failure3(error) {
+  return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+}
+function registerWorkspaceTools(server, client) {
+  server.tool(
+    "list_notes",
+    "The author's margin notes on this book \u2014 book-level and chapter-level, including foreshadowing pairs.",
+    { book_token: BOOK_TOKEN },
+    READ_ONLY3,
+    async ({ book_token }) => {
+      try {
+        return json2(await client.listNotes(book_token));
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+  server.tool(
+    "create_note",
+    `Leave a note beside the manuscript. Notes do not touch the prose or the word count.
+
+Use \`note_type: "chapter"\` with the file's token in \`file_id\` to anchor it to one chapter; \`"book"\` for the work as a whole. Do not use notes as your own scratchpad \u2014 they appear in the author's interface as their own thinking. See the \`notes-and-foreshadowing\` guide.`,
+    {
+      book_token: BOOK_TOKEN,
+      title: z8.string().describe("Short title (required)"),
+      content: z8.string().optional().describe("Body, up to 50,000 characters"),
+      note_type: z8.enum(["book", "chapter"]).optional().describe('Defaults to "book"'),
+      file_id: z8.string().optional().describe('File token \u2014 required when note_type is "chapter"'),
+      color: z8.enum(["gray", "red", "blue", "green", "yellow", "purple"]).optional()
+    },
+    WRITES,
+    async ({ book_token, title, content, note_type, file_id, color }) => {
+      try {
+        return json2(
+          await client.createNote(book_token, {
+            title,
+            content,
+            note_type: note_type ?? "book",
+            file_id,
+            color
+          })
+        );
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+  server.tool(
+    "semantic_search",
+    `Find passages by MEANING rather than by the words used.
+
+\`search_content\` finds the word an author typed; this finds the passage they meant \u2014 "where does the mother's resentment surface?" returns the scene even when neither word appears in it. On a team knowledge base it is the difference between browsing and asking.
+
+Costs a small embedding charge, unlike literal search. Returns \xA7N paragraph anchors so you can quote them back precisely.`,
+    {
+      book_token: BOOK_TOKEN,
+      query: z8.string().describe("What you are looking for, in natural language"),
+      limit: z8.number().optional().describe("Max results (default 10, cap 50)")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    async ({ book_token, query, limit }) => {
+      try {
+        return json2(await client.semanticSearch(book_token, query, limit));
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+  server.tool(
+    "list_comments",
+    `Editorial comment threads on this book, open and resolved.
+
+Read these before starting work on a book you have been handed \u2014 they are where an editor has already said what is wrong, and producing an independent list without reading them usually contradicts a decision someone already made.`,
+    { book_token: BOOK_TOKEN },
+    READ_ONLY3,
+    async ({ book_token }) => {
+      try {
+        return json2(await client.listComments(book_token));
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+  server.tool(
+    "create_comment",
+    `Leave an editorial comment.
+
+Comment when the change is a judgement call \u2014 pacing, whether a motivation lands, whether a scene earns its length. Edit the file instead when the author asked for the change. When unsure, comment: a comment costs ten seconds to dismiss, an unwanted rewrite costs the author a diff of their own prose.`,
+    {
+      book_token: BOOK_TOKEN,
+      content: z8.string().describe("The comment"),
+      file_token: z8.string().optional().describe("File this comment is about, if any")
+    },
+    WRITES,
+    async ({ book_token, content, file_token }) => {
+      try {
+        return json2(await client.createComment(book_token, { content, file_token }));
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+  server.tool(
+    "resolve_comment",
+    `Mark a comment thread addressed.
+
+Say what you did when you resolve one. A silent resolve tells the editor nothing about whether you understood the note.`,
+    {
+      book_token: BOOK_TOKEN,
+      comment_token: z8.string().describe("Comment token (from list_comments)")
+    },
+    WRITES,
+    async ({ book_token, comment_token }) => {
+      try {
+        return json2(await client.resolveComment(book_token, comment_token));
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+  server.tool(
+    "reopen_comment",
+    "Reopen a comment thread that was resolved but should not have been.",
+    {
+      book_token: BOOK_TOKEN,
+      comment_token: z8.string().describe("Comment token (from list_comments)")
+    },
+    WRITES,
+    async ({ book_token, comment_token }) => {
+      try {
+        return json2(await client.reopenComment(book_token, comment_token));
+      } catch (error) {
+        return failure3(error);
+      }
+    }
+  );
+}
+
+// src/core/resources/book_schema.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+var BOOK_SCHEMA_URI_TEMPLATE = "slima://books/{book_token}/schema";
+function registerBookSchemaResource(server, client) {
+  server.resource(
+    "slima-book-schema",
+    new ResourceTemplate(BOOK_SCHEMA_URI_TEMPLATE, {
+      // Intentionally no `list` callback — books may number in the hundreds, so
+      // we expose only the URI template via `resources/templates/list` and let
+      // clients call `resources/read` with a concrete token.
+      list: void 0
+    }),
+    {
+      description: "Per-book MCP operation schema: which paths are readable/writable, which are structured (read-only), and the structured file catalog. Read this before planning writes on an unfamiliar book.",
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      const rawToken = variables["book_token"];
+      const bookToken = Array.isArray(rawToken) ? rawToken[0] : rawToken;
+      if (!bookToken) {
+        throw new Error(
+          `Invalid Slima book schema URI: missing book_token in ${uri.toString()}`
+        );
+      }
+      const book = await client.getBook(bookToken);
+      const schema = buildBookSchema(book);
+      return {
+        contents: [
+          {
+            uri: uri.toString(),
+            mimeType: "application/json",
+            text: JSON.stringify(schema, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+function buildBookSchema(book) {
+  const isScript = book.bookType === "script";
+  const isKnowledge = book.bookType === "knowledge";
+  return {
+    book_token: book.token,
+    book_title: book.title,
+    book_type: book.bookType ?? "book",
+    studio_label: isScript ? "Script Studio" : isKnowledge ? "Team Knowledge Base" : "Writing Studio",
+    mcp_capabilities: {
+      // Note: actual reads still go through validate_safe_path!
+      // (blocks absolute paths, traversal, control chars) even though it's
+      // not reflected in this allowlist.
+      readable_paths: "Any path within the book tree (path-traversal and absolute paths still rejected).",
+      writable_paths: isScript ? [".script_studio/planning/**/*"] : ["**/*"],
+      writable_exceptions: isScript ? [".script_studio/planning/.initialized"] : [],
+      readonly_paths: isScript ? [
+        ".script_studio/series.json",
+        ".script_studio/seasons/**/season.json",
+        ".script_studio/seasons/**/episodes/**/episode.json",
+        ".script_studio/seasons/**/scenes/*.scene",
+        ".script_studio/characters/**/*.character",
+        ".script_studio/locations/**/*.location",
+        ".script_studio/storylines/**/*.storyline",
+        ".script_studio/notes/**/*.note",
+        ".script_studio/planning/.initialized"
+      ] : [],
+      reserved_sentinels: isScript ? [".script_studio/planning/.initialized"] : [],
+      // Path allowlists are not the whole story on a team book: the server also
+      // checks the caller's ROLE. An editor gets 403 on every write no matter
+      // which path, so "writable_paths" above is an upper bound, not a promise.
+      write_access_note: isKnowledge ? "Team knowledge base: owner / admin / seated writer may write; an editor is read-only (every write returns 403). Files under .slima/skills/ may be enabled as team skills by a manager." : "Personal books: the owner and writer collaborators may write; editor collaborators are read-only."
+    },
+    // AI file-type policy — mirrors slima_vue `fileTypeRegistry.ts` (`aiPolicy`).
+    // Applies to BOTH studio types; the Script Studio path allowlist above is a
+    // separate, additional restriction.
+    ai_file_policy: {
+      writable: [...AI_WRITABLE_EXTENSIONS],
+      // Structured types are not one bucket. Collapsing them into `readonly`
+      // is what made this resource tell the model `.map` could not be written
+      // for weeks after it could, and never mention `.beats` at all.
+      field_level_tools: AI_STRUCTURED_TOOLS,
+      readonly: [...AI_READONLY_EXTENSIONS],
+      readonly_note: "Read-only means the AI must not write these via write_file / edit_file / create_file / append_to_file / delete_file. Slima owns their structure; overwriting one corrupts it for the author. Recommend changes in words and point the author at that file type's editor.",
+      field_level_note: "These take one change at a time through the tool named above. Every generic write is refused (write_file / edit_file / append_to_file), because a whole-document write drops the parts of the file you were never shown \u2014 a beat board loses its chapter cards, a relationship map loses a character, and nothing reports it. create_file works: it writes an empty document of the right shape and ignores the content you send, so you then fill it in with the tool.",
+      // ⚠️ This block ships with the client and can lag a Rails deploy.
+      // `get_capabilities` is derived from the contract Rails enforces; when the
+      // two disagree, that one is right.
+      authority: "get_capabilities",
+      viewers: AI_STRUCTURED_VIEWERS
+    },
+    structured_file_types: isScript ? {
+      "series.json": "Series metadata (title, genre, logline, theme, synopsis, acts)",
+      "season.json": "Season metadata",
+      "episode.json": "Episode metadata",
+      "*.scene": "Scene content with scene-specific format",
+      "*.character": "Character definition with scope (series / season / episode)",
+      "*.location": "Location definition with scope",
+      "*.storyline": "Storyline with tier and ID linkage",
+      "*.note": "Note with scope"
+    } : {},
+    notes: isScript ? "Structured files require schema-aware edits \u2014 use the Script Studio UI. MCP write access is restricted to planning/ (free-form reference tree) to prevent schema corruption." : isKnowledge ? "Team knowledge base. Free-form paths, but two team rules apply: writes follow team role (see write_access_note), and a file marked confidential is returned WITHOUT its content \u2014 read_file reports it as withheld rather than empty. That is intentional: the AI may use such a skill without reading it. Never try to rewrite a withheld file." : "Writing Studio books are free-form. No schema restrictions; any path is writable.",
+    policy_source: "Rails: Mcp::FileOperationService#validate_studio_write_path!"
+  };
+}
+
+// src/core/server-instructions.ts
+var SERVER_INSTRUCTIONS = `Slima is an AI writing IDE for long-form fiction. You are connected to an author's account.
+
+**Start by calling \`get_capabilities\`.** It returns what this server supports \u2014 which file types you may write, how content types work, the tools available, and the guide index \u2014 derived from the contract the server enforces, so it is never out of date.
+
+Then \`load_guide\` what the task needs: \`getting-started\` for the shape of a book, \`book-structure\` before creating files, \`version-control-basics\` before a large rewrite, \`team-knowledge-base\` inside a publisher's team, \`beta-reader\` before spending the author's credits.
+
+Three things worth knowing before your first call:
+
+- **Every write is a commit.** There is no save step, and the author sees your commits beside their own. Write real commit messages.
+- **The author may be editing the same file.** Prefer \`edit_file\` over \`update_file\`: an edit that cannot find its anchor fails loudly, where a whole-file write silently replaces whatever they just typed.
+- **Not every file type is yours to write.** A refusal naming the file type is information, not an obstacle to route around.
+
+Slima's AI is a writing coach by default. When a request is vague or the author is thinking out loud, ask the question that unblocks them. When they ask plainly \u2014 "write this scene", "rewrite this paragraph" \u2014 do it, without lecturing.`;
 
 // src/core/utils/logger.ts
 var isDebug = process.env.DEBUG === "true" || process.env.DEBUG === "1";
@@ -1521,14 +2565,24 @@ function createSlimaServer(config) {
     getToken: async () => config.apiToken,
     logger
   });
-  const server = new McpServer({
-    name: "slima",
-    version: "0.1.15"
-  });
+  const server = new McpServer(
+    {
+      name: "slima",
+      version: "0.3.0"
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS
+    }
+  );
+  registerTeachingTools(server, client);
   registerBookTools(server, client);
+  registerTeamTools(server, client);
+  registerWorkspaceTools(server, client);
   registerContentTools(server, client);
   registerBetaReaderTools(server, client, logger);
   registerFileTools(server, client);
+  registerStructuredTools(server, client);
+  registerBookSchemaResource(server, client);
   logger.info("Slima MCP Server initialized");
   logger.info(`API endpoint: ${config.baseUrl || "https://api.slima.ai"}`);
   return server;
@@ -1740,7 +2794,7 @@ function getSuccessHtml() {
 </body>
 </html>`;
 }
-function escapeHtml(text) {
+function escapeHtml(text2) {
   const map = {
     "&": "&amp;",
     "<": "&lt;",
@@ -1748,7 +2802,7 @@ function escapeHtml(text) {
     '"': "&quot;",
     "'": "&#039;"
   };
-  return text.replace(/[&<>"']/g, (char) => map[char]);
+  return text2.replace(/[&<>"']/g, (char) => map[char]);
 }
 function getErrorHtml(message) {
   const safeMessage = escapeHtml(message);
@@ -1975,7 +3029,7 @@ async function runStatus() {
 }
 
 // src/cli/index.ts
-var VERSION = "0.1.15";
+var VERSION = "0.3.0";
 function showHelp() {
   console.log(`
 Slima MCP v${VERSION}
@@ -2052,7 +3106,7 @@ async function startServer() {
       baseUrl
     });
     const transport = new StdioServerTransport();
-    await server.connect(transport);
+    await server.connect(withGeminiSchemaCompat(transport));
     logger.info("Slima MCP Server running on stdio");
     process.on("SIGINT", async () => {
       logger.info("Shutting down...");