@thallylabs/mcp 0.10.21 → 0.10.23

package/dist/tools.js

@@ -324,24 +324,106 @@ async function handleUpdatePage(input) {
   ].join("\n");
 }
 
-// src/tools/migrate-docs.ts
+// src/tools/replace-page-text.ts
+import { createHash } from "crypto";
+import {
+  existsSync as existsSync3,
+  lstatSync,
+  readFileSync as readFileSync3,
+  realpathSync,
+  writeFileSync as writeFileSync4
+} from "fs";
+import { isAbsolute, join as join4, relative, sep } from "path";
 import { z as z6 } from "zod";
+var MAX_REPLACEMENT_BYTES = 64 * 1024;
+var replacePageTextSchema = z6.object({
+  projectDir: z6.string().describe("Path to the Thally project root"),
+  pageId: z6.string().describe(
+    'Page identifier (for example "guides/auth"). No .mdx extension.'
+  ),
+  oldText: z6.string().min(1).max(MAX_REPLACEMENT_BYTES).describe("Exact existing text to replace; it must occur exactly once"),
+  newText: z6.string().min(1).max(MAX_REPLACEMENT_BYTES).describe(
+    "Complete replacement prose for oldText; never include a Track evidence marker"
+  ),
+  evidenceReferenceId: z6.string().min(1).max(128).optional().describe(
+    "Exact evidence reference ID supplied by Track. When present, the tool appends its deterministic citation marker."
+  )
+});
+function isInside(root, candidate) {
+  const fromRoot = relative(root, candidate);
+  return Boolean(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+}
+function pageFile(projectDir, pageId) {
+  if (!/^[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*$/u.test(pageId) || pageId.split("/").some((part) => part.toLowerCase() === ".git")) {
+    throw new Error("Invalid pageId.");
+  }
+  const contentRoot = realpathSync(join4(projectDir, "src", "content"));
+  const candidates = [
+    join4(projectDir, "src", "content", `${pageId}.mdx`),
+    join4(projectDir, "src", "content", pageId, "index.mdx")
+  ];
+  const existing = candidates.filter((candidate2) => existsSync3(candidate2));
+  if (existing.length !== 1) throw new Error("Page not found or ambiguous.");
+  const candidate = existing[0];
+  const metadata = lstatSync(candidate);
+  if (!metadata.isFile() || metadata.isSymbolicLink() || !isInside(contentRoot, realpathSync(candidate))) {
+    throw new Error("Page must be a regular file inside src/content.");
+  }
+  return candidate;
+}
+function consumedTrailingLineSeparator(value) {
+  return value.match(/(\r?\n)[^\S\r\n]*$/u)?.[1] ?? "";
+}
+async function handleReplacePageText(input) {
+  if (input.oldText.includes("\0") || input.newText.includes("\0") || input.oldText === input.newText || input.newText.trim().length === 0) {
+    throw new Error("Replacement text is invalid.");
+  }
+  const filePath = pageFile(input.projectDir, input.pageId);
+  const source = readFileSync3(filePath, "utf8");
+  const first = source.indexOf(input.oldText);
+  if (first < 0 || source.indexOf(input.oldText, first + input.oldText.length) >= 0) {
+    throw new Error("oldText must match exactly one span.");
+  }
+  const marker = input.evidenceReferenceId ? `<!-- thally-cite:v1:${createHash("sha256").update(`evidence\0${input.evidenceReferenceId}`, "utf8").digest("hex")} -->` : null;
+  if (marker && input.newText.includes(marker)) {
+    throw new Error("Replacement text must not include its citation marker.");
+  }
+  const suffixSeparator = marker ? consumedTrailingLineSeparator(input.oldText) : "";
+  const citedReplacement = marker ? `${input.newText.replace(/\s*$/u, "")}
+${marker}` : input.newText;
+  const replacement = `${citedReplacement}${suffixSeparator}`;
+  writeFileSync4(
+    filePath,
+    `${source.slice(0, first)}${replacement}${source.slice(first + input.oldText.length)}`,
+    "utf8"
+  );
+  const startLine = source.slice(0, first).split("\n").length;
+  const endLine = startLine + citedReplacement.split("\n").length - 1;
+  return [
+    `\u2705 Page text replaced: ${input.pageId}`,
+    `Final replacement lines: ${startLine}-${endLine}.`,
+    "Use this exact final line range for the corresponding factual claim."
+  ].join("\n");
+}
+
+// src/tools/migrate-docs.ts
+import { z as z7 } from "zod";
 import { migrateDocs } from "create-thally-docs/migrate";
 var migrationSourceShape = {
-  sourceUrl: z6.string().describe("GitHub repository URL or public documentation URL to migrate"),
-  branch: z6.string().optional().describe("Git branch (default: auto-detect)"),
-  docsDir: z6.string().optional().describe("Docs subdirectory in repo (default: auto-detect)"),
-  apiKey: z6.string().optional().describe("Anthropic API key for non-Markdown file conversion"),
-  maxPages: z6.number().int().min(1).max(1e3).optional().describe("Maximum public URL pages to import"),
-  platform: z6.enum(["mintlify", "docusaurus"]).optional().describe("Source platform (default: auto-detect)")
+  sourceUrl: z7.string().describe("GitHub repository URL or public documentation URL to migrate"),
+  branch: z7.string().optional().describe("Git branch (default: auto-detect)"),
+  docsDir: z7.string().optional().describe("Docs subdirectory in repo (default: auto-detect)"),
+  apiKey: z7.string().optional().describe("Anthropic API key for non-Markdown file conversion"),
+  maxPages: z7.number().int().min(1).max(1e3).optional().describe("Maximum public URL pages to import"),
+  platform: z7.enum(["mintlify", "docusaurus"]).optional().describe("Source platform (default: auto-detect)")
 };
-var migrateDocsSchema = z6.object({
+var migrateDocsSchema = z7.object({
   ...migrationSourceShape,
-  projectDir: z6.string().describe("Path for the new canonical Thally project; the directory must be absent or empty")
+  projectDir: z7.string().describe("Path for the new canonical Thally project; the directory must be absent or empty")
 });
-var importDocsSchema = z6.object({
+var importDocsSchema = z7.object({
   ...migrationSourceShape,
-  projectDir: z6.string().describe("Path to an existing Thally project whose runtime should be preserved")
+  projectDir: z7.string().describe("Path to an existing Thally project whose runtime should be preserved")
 });
 async function runMigration(input, isInPlaceImport) {
   const apiKey = input.apiKey ?? process.env.ANTHROPIC_API_KEY;
@@ -369,13 +451,13 @@ async function handleImportDocs(input) {
 }
 
 // src/tools/search-docs.ts
-import { z as z7 } from "zod";
-import { readdirSync, statSync, readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
-import { join as join4, relative, extname } from "path";
-var searchDocsSchema = z7.object({
-  projectDir: z7.string().describe("Path to the Thally project root"),
-  query: z7.string().describe("Search query"),
-  limit: z7.number().optional().default(5).describe("Max results to return (default 5)")
+import { z as z8 } from "zod";
+import { readdirSync, statSync, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { join as join5, relative as relative2, extname } from "path";
+var searchDocsSchema = z8.object({
+  projectDir: z8.string().describe("Path to the Thally project root"),
+  query: z8.string().describe("Search query"),
+  limit: z8.number().optional().default(5).describe("Max results to return (default 5)")
 });
 function scanMdxFiles(dir, results) {
   let entries;
@@ -385,7 +467,7 @@ function scanMdxFiles(dir, results) {
     return;
   }
   for (const entry of entries) {
-    const fullPath = join4(dir, entry);
+    const fullPath = join5(dir, entry);
     try {
       const stat = statSync(fullPath);
       if (stat.isDirectory()) {
@@ -403,7 +485,7 @@ function scoreFiles(files, contentDir, query) {
   for (const filePath of files) {
     let raw;
     try {
-      raw = readFileSync3(filePath, "utf8");
+      raw = readFileSync4(filePath, "utf8");
     } catch {
       continue;
     }
@@ -411,7 +493,7 @@ function scoreFiles(files, contentDir, query) {
     const title = data.title ?? "";
     const description = data.description ?? "";
     const keywords = data.keywords ?? [];
-    const pageId = relative(contentDir, filePath).replace(/\.mdx$/, "").replace(/\\/g, "/");
+    const pageId = relative2(contentDir, filePath).replace(/\.mdx$/, "").replace(/\\/g, "/");
     let score = 0;
     for (const term of terms) {
       if (title.toLowerCase().includes(term)) score += 3;
@@ -428,8 +510,8 @@ function scoreFiles(files, contentDir, query) {
 }
 async function handleSearchDocs(input) {
   const { projectDir, query, limit = 5 } = input;
-  const contentDir = join4(projectDir, "src", "content");
-  if (!existsSync3(contentDir)) {
+  const contentDir = join5(projectDir, "src", "content");
+  if (!existsSync4(contentDir)) {
     throw new Error(`Content directory not found: ${contentDir}`);
   }
   const files = [];
@@ -449,12 +531,12 @@ async function handleSearchDocs(input) {
 }
 
 // src/tools/semantic-search.ts
-import { z as z8 } from "zod";
-var semanticSearchSchema = z8.object({
-  siteUrl: z8.string().describe("Base URL of the deployed Thally site (e.g. https://docs.example.com)"),
-  query: z8.string().describe("Natural-language search query"),
-  limit: z8.number().optional().default(8).describe("Max results to return (default 8)"),
-  mode: z8.enum(["hybrid", "fulltext"]).optional().default("hybrid").describe("Search mode: hybrid (full-text + vector) or fulltext")
+import { z as z9 } from "zod";
+var semanticSearchSchema = z9.object({
+  siteUrl: z9.string().describe("Base URL of the deployed Thally site (e.g. https://docs.example.com)"),
+  query: z9.string().describe("Natural-language search query"),
+  limit: z9.number().optional().default(8).describe("Max results to return (default 8)"),
+  mode: z9.enum(["hybrid", "fulltext"]).optional().default("hybrid").describe("Search mode: hybrid (full-text + vector) or fulltext")
 });
 async function handleSemanticSearch(input) {
   const { siteUrl, query, limit = 8, mode = "hybrid" } = input;
@@ -485,10 +567,10 @@ async function handleSemanticSearch(input) {
 }
 
 // src/tools/agent-readiness.ts
-import { z as z9 } from "zod";
-var agentReadinessSchema = z9.object({
-  siteUrl: z9.string().describe("Base URL of the deployed Thally site (e.g. https://docs.example.com)"),
-  minScore: z9.number().optional().describe("Optional threshold (0-100). If set, the summary flags whether the site passes.")
+import { z as z10 } from "zod";
+var agentReadinessSchema = z10.object({
+  siteUrl: z10.string().describe("Base URL of the deployed Thally site (e.g. https://docs.example.com)"),
+  minScore: z10.number().optional().describe("Optional threshold (0-100). If set, the summary flags whether the site passes.")
 });
 async function handleAgentReadiness(input) {
   const { siteUrl, minScore } = input;
@@ -523,53 +605,211 @@ async function handleAgentReadiness(input) {
 }
 
 // src/tools/read-page.ts
-import { z as z10 } from "zod";
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
-import { join as join5 } from "path";
-var readPageSchema = z10.object({
-  projectDir: z10.string().describe("Path to the Thally project root"),
-  pageId: z10.string().describe('Page ID, e.g. "guides/authentication"')
+import { z as z11 } from "zod";
+import { existsSync as existsSync5, lstatSync as lstatSync2, realpathSync as realpathSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join6, relative as relative3, sep as sep2 } from "path";
+
+// src/lib/text-window.ts
+import { createHash as createHash2 } from "crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  openSync,
+  readFileSync as readFileSync5
+} from "fs";
+var MODEL_READ_WINDOW_DEFAULT_BYTES = 48 * 1024;
+var MODEL_READ_WINDOW_MAX_BYTES = 180 * 1024;
+var MODEL_READ_SOURCE_MAX_BYTES = 8 * 1024 * 1024;
+function readModelTextFile(path) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const metadata = fstatSync(descriptor);
+    if (!metadata.isFile() || metadata.size > MODEL_READ_SOURCE_MAX_BYTES) {
+      throw new Error("text_source_invalid");
+    }
+    const bytes = readFileSync5(descriptor);
+    if (bytes.byteLength !== metadata.size)
+      throw new Error("text_source_invalid");
+    return bytes;
+  } catch (error) {
+    if (error instanceof Error && error.message === "text_source_invalid")
+      throw error;
+    throw new Error("text_source_invalid");
+  } finally {
+    if (descriptor !== void 0) closeSync(descriptor);
+  }
+}
+function textWindowMetadata(window) {
+  const metadata = [
+    `content-sha256: ${window.sha256}`,
+    window.contentBytes === 0 ? `window-bytes: empty at ${window.startByte} of ${window.totalBytes}` : `window-bytes: ${window.startByte}-${window.startByte + window.contentBytes - 1} of ${window.totalBytes}`,
+    `window-lines: ${window.startLine}-${window.endLine} of ${window.totalLines}`,
+    `complete: ${window.isComplete}`
+  ];
+  if (!window.isComplete) {
+    metadata.push(
+      `next-start-byte: ${window.nextStartByte}`,
+      `next-start-line: ${window.nextStartLine}`
+    );
+  }
+  return metadata;
+}
+function countLinesBefore(bytes, end) {
+  let lines = 1;
+  for (let index = 0; index < end; index += 1) {
+    if (bytes[index] === 10) lines += 1;
+  }
+  return lines;
+}
+function byteOffsetForLine(bytes, requestedLine) {
+  if (requestedLine === 1) return 0;
+  let line = 1;
+  for (let index = 0; index < bytes.byteLength; index += 1) {
+    if (bytes[index] !== 10) continue;
+    line += 1;
+    if (line === requestedLine) return index + 1;
+  }
+  throw new Error("text_window_start_out_of_range");
+}
+function decodeUtf8(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error("text_window_invalid_utf8");
+  }
+}
+function isUtf8Boundary(bytes, offset) {
+  return offset === 0 || offset === bytes.byteLength || (bytes[offset] & 192) !== 128;
+}
+function createTextWindow(bytes, request = {}) {
+  decodeUtf8(bytes);
+  const maxBytes = request.maxBytes ?? MODEL_READ_WINDOW_DEFAULT_BYTES;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MODEL_READ_WINDOW_MAX_BYTES) {
+    throw new Error("text_window_size_invalid");
+  }
+  if (request.startByte !== void 0 && request.startLine !== void 0) {
+    throw new Error("text_window_start_ambiguous");
+  }
+  let startByte;
+  if (request.startLine !== void 0) {
+    if (!Number.isSafeInteger(request.startLine) || request.startLine < 1) {
+      throw new Error("text_window_start_invalid");
+    }
+    startByte = byteOffsetForLine(bytes, request.startLine);
+  } else {
+    startByte = request.startByte ?? 0;
+    if (!Number.isSafeInteger(startByte) || startByte < 0 || startByte > bytes.byteLength || !isUtf8Boundary(bytes, startByte)) {
+      throw new Error("text_window_start_invalid");
+    }
+  }
+  let endByte = Math.min(bytes.byteLength, startByte + maxBytes);
+  while (endByte > startByte && !isUtf8Boundary(bytes, endByte)) endByte -= 1;
+  if (endByte === startByte && startByte < bytes.byteLength) {
+    throw new Error("text_window_size_invalid");
+  }
+  const contentBytes = endByte - startByte;
+  const content = decodeUtf8(bytes.subarray(startByte, endByte));
+  const startLine = countLinesBefore(bytes, startByte);
+  const endLine = startLine + (content.match(/\n/g)?.length ?? 0);
+  const isComplete = endByte === bytes.byteLength;
+  const totalLines = countLinesBefore(bytes, bytes.byteLength);
+  return {
+    content,
+    contentBytes,
+    endLine,
+    isComplete,
+    ...isComplete ? {} : { nextStartByte: endByte, nextStartLine: endLine },
+    sha256: createHash2("sha256").update(bytes).digest("hex"),
+    startByte,
+    startLine,
+    totalBytes: bytes.byteLength,
+    totalLines
+  };
+}
+function renderTextWindow(window) {
+  return [...textWindowMetadata(window), "", window.content].join("\n");
+}
+
+// src/tools/read-page.ts
+var readPageSchema = z11.object({
+  projectDir: z11.string().describe("Path to the Thally project root"),
+  pageId: z11.string().describe('Page ID, e.g. "guides/authentication"'),
+  startByte: z11.number().int().min(0).optional().describe("UTF-8 byte continuation from a previous partial result"),
+  startLine: z11.number().int().min(1).optional().describe("1-based body line to start at; do not combine with startByte"),
+  maxBytes: z11.number().int().min(1).max(MODEL_READ_WINDOW_MAX_BYTES).optional().describe(
+    `Maximum body bytes to return (default 49152, maximum ${MODEL_READ_WINDOW_MAX_BYTES})`
+  )
 });
+function isInside2(root, candidate) {
+  const fromRoot = relative3(root, candidate);
+  return Boolean(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep2}`) && !isAbsolute2(fromRoot);
+}
 async function handleReadPage(input) {
   const { projectDir, pageId } = input;
-  const contentDir = join5(projectDir, "src", "content");
+  const contentDir = join6(projectDir, "src", "content");
+  if (!/^[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*$/u.test(pageId) || pageId.split("/").some((part) => part.toLowerCase() === ".git")) {
+    throw new Error("Page ID must be a safe content-relative identifier");
+  }
+  const contentRoot = realpathSync2(contentDir);
   const candidates = [
-    join5(contentDir, `${pageId}.mdx`),
-    join5(contentDir, `${pageId}/index.mdx`)
+    join6(contentDir, `${pageId}.mdx`),
+    join6(contentDir, `${pageId}/index.mdx`)
   ];
   let filePath = null;
   for (const c of candidates) {
-    if (existsSync4(c)) {
+    if (existsSync5(c)) {
+      const metadata = lstatSync2(c);
+      if (!metadata.isFile() || metadata.isSymbolicLink() || !isInside2(contentRoot, realpathSync2(c))) {
+        throw new Error("Page must be a regular file inside src/content");
+      }
       filePath = c;
       break;
     }
   }
   if (!filePath) {
-    throw new Error(`Page not found: "${pageId}". No file at src/content/${pageId}.mdx`);
+    throw new Error(
+      `Page not found: "${pageId}". No file at src/content/${pageId}.mdx`
+    );
+  }
+  const rawBytes = readModelTextFile(filePath);
+  let raw;
+  try {
+    raw = new TextDecoder("utf-8", { fatal: true }).decode(rawBytes);
+  } catch {
+    throw new Error("Page is not valid UTF-8");
   }
-  const raw = readFileSync4(filePath, "utf8");
   const { data, content } = parseFrontmatter(raw);
   const title = data.title ?? pageId;
   const description = data.description ?? "";
   const lines = [`id: ${pageId}`, `title: ${title}`];
   if (description) lines.push(`description: ${description}`);
-  lines.push("", readPageBodyDelimiter(), "", content.trim());
+  const window = createTextWindow(Buffer.from(content, "utf8"), input);
+  lines.push(
+    "",
+    ...textWindowMetadata(window),
+    "",
+    readPageBodyDelimiter(),
+    "",
+    window.content
+  );
   return lines.join("\n");
 }
 
 // src/tools/get-context.ts
-import { z as z11 } from "zod";
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { join as join6 } from "path";
-var getContextSchema = z11.object({
-  projectDir: z11.string().describe("Path to the Thally project root"),
-  topic: z11.string().describe("Topic or question to find relevant docs for"),
-  maxTokens: z11.number().optional().default(4e3).describe("Approximate token budget for returned context (default 4000)")
+import { z as z12 } from "zod";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { join as join7 } from "path";
+var getContextSchema = z12.object({
+  projectDir: z12.string().describe("Path to the Thally project root"),
+  topic: z12.string().describe("Topic or question to find relevant docs for"),
+  maxTokens: z12.number().optional().default(4e3).describe("Approximate token budget for returned context (default 4000)")
 });
 async function handleGetContext(input) {
   const { projectDir, topic, maxTokens = 4e3 } = input;
-  const contentDir = join6(projectDir, "src", "content");
-  if (!existsSync5(contentDir)) {
+  const contentDir = join7(projectDir, "src", "content");
+  if (!existsSync6(contentDir)) {
     throw new Error(`Content directory not found: ${contentDir}`);
   }
   const files = [];
@@ -583,13 +823,13 @@ async function handleGetContext(input) {
   const sections = [];
   for (const result of scored) {
     const candidates = [
-      join6(contentDir, `${result.pageId}.mdx`),
-      join6(contentDir, `${result.pageId}/index.mdx`)
+      join7(contentDir, `${result.pageId}.mdx`),
+      join7(contentDir, `${result.pageId}/index.mdx`)
     ];
     let content = "";
     for (const c of candidates) {
-      if (existsSync5(c)) {
-        const raw = readFileSync5(c, "utf8");
+      if (existsSync6(c)) {
+        const raw = readFileSync6(c, "utf8");
         const { content: body } = parseFrontmatter(raw);
         content = body.trim();
         break;
@@ -613,12 +853,12 @@ async function handleGetContext(input) {
 }
 
 // src/tools/lint-project.ts
-import { z as z12 } from "zod";
-import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
-import { join as join7 } from "path";
-var lintProjectSchema = z12.object({
-  projectDir: z12.string().describe("Path to the Thally project root"),
-  fix: z12.boolean().optional().default(false).describe("Auto-fix issues where possible (adds orphan pages to nav)")
+import { z as z13 } from "zod";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { join as join8 } from "path";
+var lintProjectSchema = z13.object({
+  projectDir: z13.string().describe("Path to the Thally project root"),
+  fix: z13.boolean().optional().default(false).describe("Auto-fix issues where possible (adds orphan pages to nav)")
 });
 function collectNavPageIds(groups, seen, duplicates) {
   for (const page of groups) {
@@ -646,9 +886,9 @@ function addOrphanToNav(projectDir, pageId) {
 }
 async function handleLintProject(input) {
   const { projectDir, fix = false } = input;
-  const contentDir = join7(projectDir, "src", "content");
+  const contentDir = join8(projectDir, "src", "content");
   const issues = [];
-  if (!existsSync6(join7(projectDir, "docs.json"))) {
+  if (!existsSync7(join8(projectDir, "docs.json"))) {
     throw new Error(`Not a Thally project: docs.json not found in ${projectDir}`);
   }
   const config = readDocsJson(projectDir);
@@ -667,10 +907,10 @@ async function handleLintProject(input) {
   }
   for (const pageId of navPageIds) {
     const candidates = [
-      join7(contentDir, `${pageId}.mdx`),
-      join7(contentDir, `${pageId}/index.mdx`)
+      join8(contentDir, `${pageId}.mdx`),
+      join8(contentDir, `${pageId}/index.mdx`)
     ];
-    if (!candidates.some((c) => existsSync6(c))) {
+    if (!candidates.some((c) => existsSync7(c))) {
       issues.push({
         severity: "error",
         message: `"${pageId}" is in docs.json but has no MDX file`,
@@ -679,7 +919,7 @@ async function handleLintProject(input) {
     }
   }
   const allFiles = [];
-  if (existsSync6(contentDir)) {
+  if (existsSync7(contentDir)) {
     scanMdxFiles(contentDir, allFiles);
   }
   const fixedOrphans = [];
@@ -697,7 +937,7 @@ async function handleLintProject(input) {
     let data = {};
     let content = "";
     try {
-      const raw = readFileSync6(filePath, "utf8");
+      const raw = readFileSync7(filePath, "utf8");
       const parsed = parseFrontmatter(raw);
       data = parsed.data;
       content = parsed.content;
@@ -753,22 +993,22 @@ async function handleLintProject(input) {
 }
 
 // src/tools/translate-docs.ts
-import { z as z13 } from "zod";
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync5, existsSync as existsSync7, mkdirSync as mkdirSync2 } from "fs";
-import { join as join8, dirname as dirname2 } from "path";
+import { z as z14 } from "zod";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync2 } from "fs";
+import { join as join9, dirname as dirname2 } from "path";
 import Anthropic from "@anthropic-ai/sdk";
 import pLimit from "p-limit";
-var translateDocsSchema = z13.object({
-  projectDir: z13.string().describe("Path to the Thally project directory"),
-  locale: z13.string().describe('Target locale code, e.g. "es", "fr"'),
-  pages: z13.array(z13.string()).optional().describe("Page IDs to translate (omit for all pages)"),
-  force: z13.boolean().optional().default(false).describe("Overwrite existing translation files"),
-  apiKey: z13.string().optional().describe("Anthropic API key (falls back to ANTHROPIC_API_KEY env var)"),
-  model: z13.string().optional().default("claude-sonnet-4-6").describe("Claude model to use for translation")
+var translateDocsSchema = z14.object({
+  projectDir: z14.string().describe("Path to the Thally project directory"),
+  locale: z14.string().describe('Target locale code, e.g. "es", "fr"'),
+  pages: z14.array(z14.string()).optional().describe("Page IDs to translate (omit for all pages)"),
+  force: z14.boolean().optional().default(false).describe("Overwrite existing translation files"),
+  apiKey: z14.string().optional().describe("Anthropic API key (falls back to ANTHROPIC_API_KEY env var)"),
+  model: z14.string().optional().default("claude-sonnet-4-6").describe("Claude model to use for translation")
 });
 function readDocsJson2(projectDir) {
-  const docsPath = join8(projectDir, "docs.json");
-  const raw = readFileSync7(docsPath, "utf8");
+  const docsPath = join9(projectDir, "docs.json");
+  const raw = readFileSync8(docsPath, "utf8");
   return JSON.parse(raw);
 }
 function collectPageIds(pages) {
@@ -810,12 +1050,12 @@ function getAllPageIds(config) {
   return { ids, hrefOnlyPages };
 }
 function findSourceFile(projectDir, pageId) {
-  const contentRoot = join8(projectDir, "src", "content");
+  const contentRoot = join9(projectDir, "src", "content");
   const candidates = [
-    join8(contentRoot, `${pageId}.mdx`),
-    join8(contentRoot, `${pageId}/index.mdx`)
+    join9(contentRoot, `${pageId}.mdx`),
+    join9(contentRoot, `${pageId}/index.mdx`)
   ];
-  return candidates.find((p) => existsSync7(p)) ?? null;
+  return candidates.find((p) => existsSync8(p)) ?? null;
 }
 var TRANSLATION_SYSTEM_PROMPT = `You are a professional documentation translator. You will receive an MDX documentation file and translate it into the target language.
 
@@ -867,7 +1107,7 @@ async function handleTranslateDocs(input) {
   }
   const { ids: allPageIds, hrefOnlyPages } = getAllPageIds(config);
   const targetPageIds = pages ?? allPageIds;
-  const contentRoot = join8(projectDir, "src", "content");
+  const contentRoot = join9(projectDir, "src", "content");
   const toTranslate = [];
   const skipped = [];
   for (const pageId of targetPageIds) {
@@ -877,8 +1117,8 @@ async function handleTranslateDocs(input) {
       continue;
     }
     const relativeFromContent = sourceFile.slice(contentRoot.length + 1);
-    const targetFile = join8(contentRoot, locale, relativeFromContent);
-    if (existsSync7(targetFile) && !force) {
+    const targetFile = join9(contentRoot, locale, relativeFromContent);
+    if (existsSync8(targetFile) && !force) {
       skipped.push(`${pageId} (already translated)`);
       continue;
     }
@@ -894,14 +1134,14 @@ async function handleTranslateDocs(input) {
     toTranslate.map(
       ({ pageId, sourceFile, targetFile }) => limit(async () => {
         try {
-          const sourceContent = readFileSync7(sourceFile, "utf8");
+          const sourceContent = readFileSync8(sourceFile, "utf8");
           const parsed = parseFrontmatter(sourceContent);
           if (!parsed.data.title) {
             console.warn(`[translate] ${pageId}: missing title in frontmatter`);
           }
           const translated = await translatePage(sourceContent, targetLocale.label, locale, model, client);
           mkdirSync2(dirname2(targetFile), { recursive: true });
-          writeFileSync5(targetFile, translated + "\n", "utf8");
+          writeFileSync6(targetFile, translated + "\n", "utf8");
           results.push({ pageId, success: true });
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -941,19 +1181,30 @@ async function handleTranslateDocs(input) {
 }
 
 // src/tools/sync-from-repo.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 
 // src/lib/track.ts
-import { createSign, createHash } from "crypto";
+import { createSign, createHash as createHash3 } from "crypto";
 function parseOwnerRepo(spec) {
   const trimmed = spec.trim();
   const url = trimmed.match(
     /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:\/pull\/(\d+))?(?:[/#?].*)?$/i
   );
-  if (url) return { owner: url[1], repo: url[2], ...url[3] ? { pr: Number(url[3]) } : {} };
-  const plain = trimmed.match(/^([A-Za-z0-9-_.]+)\/([A-Za-z0-9-_.]+?)(?:#(\d+))?$/);
+  if (url)
+    return {
+      owner: url[1],
+      repo: url[2],
+      ...url[3] ? { pr: Number(url[3]) } : {}
+    };
+  const plain = trimmed.match(
+    /^([A-Za-z0-9-_.]+)\/([A-Za-z0-9-_.]+?)(?:#(\d+))?$/
+  );
   if (!plain) return null;
-  return { owner: plain[1], repo: plain[2], ...plain[3] ? { pr: Number(plain[3]) } : {} };
+  return {
+    owner: plain[1],
+    repo: plain[2],
+    ...plain[3] ? { pr: Number(plain[3]) } : {}
+  };
 }
 function base64url(input) {
   return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -962,22 +1213,34 @@ var installationTokenCache = /* @__PURE__ */ new Map();
 function createAppJwt(appId, privateKey) {
   const now = Math.floor(Date.now() / 1e3);
   const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
-  const payload = base64url(JSON.stringify({ iat: now - 60, exp: now + 9 * 60, iss: String(appId) }));
-  const signature = base64url(createSign("RSA-SHA256").update(`${header}.${payload}`).sign(privateKey));
+  const payload = base64url(
+    JSON.stringify({ iat: now - 60, exp: now + 9 * 60, iss: String(appId) })
+  );
+  const signature = base64url(
+    createSign("RSA-SHA256").update(`${header}.${payload}`).sign(privateKey)
+  );
   return `${header}.${payload}.${signature}`;
 }
 async function mintInstallationToken(creds, fetchImpl = fetch) {
-  const keyFp = createHash("sha256").update(creds.privateKey).digest("hex").slice(0, 12);
+  const keyFp = createHash3("sha256").update(creds.privateKey).digest("hex").slice(0, 12);
   const cacheKey = `${creds.appId}:${creds.installationId}:${keyFp}`;
   const cached = installationTokenCache.get(cacheKey);
   if (cached && cached.expiresAtMs - 6e4 > Date.now()) return cached.token;
   const jwt = createAppJwt(creds.appId, creds.privateKey);
-  const res = await fetchImpl(`https://api.github.com/app/installations/${creds.installationId}/access_tokens`, {
-    method: "POST",
-    headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${jwt}` }
-  });
+  const res = await fetchImpl(
+    `https://api.github.com/app/installations/${creds.installationId}/access_tokens`,
+    {
+      method: "POST",
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${jwt}`
+      }
+    }
+  );
   if (!res.ok) {
-    throw new Error(`GitHub App token exchange failed (${res.status}) \u2014 check the app id, installation id, and private key.`);
+    throw new Error(
+      `GitHub App token exchange failed (${res.status}) \u2014 check the app id, installation id, and private key.`
+    );
   }
   const body = await res.json();
   const parsed = Date.parse(body.expires_at);
@@ -989,7 +1252,8 @@ function envAppCreds() {
   const appId = (process.env.THALLY_GITHUB_APP_ID ?? process.env.DOX_GITHUB_APP_ID)?.trim();
   const installationId = (process.env.THALLY_GITHUB_APP_INSTALLATION_ID ?? process.env.DOX_GITHUB_APP_INSTALLATION_ID)?.trim();
   const privateKey = process.env.THALLY_GITHUB_APP_PRIVATE_KEY ?? process.env.DOX_GITHUB_APP_PRIVATE_KEY;
-  if (appId && installationId && privateKey) return { appId, installationId, privateKey };
+  if (appId && installationId && privateKey)
+    return { appId, installationId, privateKey };
   return void 0;
 }
 async function resolveGithubToken(options) {
@@ -1000,7 +1264,9 @@ async function resolveGithubToken(options) {
     try {
       return await mintInstallationToken(appCreds, options?.fetchImpl ?? fetch);
     } catch (err) {
-      console.warn(`[thally-track] GitHub App token mint failed, falling back to PAT: ${err instanceof Error ? err.message : String(err)}`);
+      console.warn(
+        `[thally-track] GitHub App token mint failed, falling back to PAT: ${err instanceof Error ? err.message : String(err)}`
+      );
       return pat;
     }
   }
@@ -1009,9 +1275,13 @@ async function resolveGithubToken(options) {
 async function githubJson(path, options) {
   const fetchImpl = options?.fetchImpl ?? fetch;
   const token = await resolveGithubToken(options);
-  const headers = { Accept: "application/vnd.github+json" };
+  const headers = {
+    Accept: "application/vnd.github+json"
+  };
   if (token) headers.Authorization = `Bearer ${token}`;
-  const response = await fetchImpl(`https://api.github.com${path}`, { headers });
+  const response = await fetchImpl(`https://api.github.com${path}`, {
+    headers
+  });
   if (!response.ok) {
     const hint = response.status === 404 || response.status === 403 ? " (private repo or rate limit? set THALLY_GITHUB_TOKEN or connect a GitHub App)" : "";
     throw new Error(`GitHub API ${response.status} for ${path}${hint}`);
@@ -1030,7 +1300,10 @@ function toPullRequestInfo(raw) {
   };
 }
 async function fetchPullRequest(owner, repo, number, options) {
-  const raw = await githubJson(`/repos/${owner}/${repo}/pulls/${number}`, options);
+  const raw = await githubJson(
+    `/repos/${owner}/${repo}/pulls/${number}`,
+    options
+  );
   return toPullRequestInfo(raw);
 }
 async function fetchPullRequestFiles(owner, repo, number, options) {
@@ -1038,7 +1311,10 @@ async function fetchPullRequestFiles(owner, repo, number, options) {
   const maxPages = 30;
   const raw = [];
   for (let page = 1; page <= maxPages; page++) {
-    const chunk = await githubJson(`/repos/${owner}/${repo}/pulls/${number}/files?per_page=${perPage}&page=${page}`, options);
+    const chunk = await githubJson(
+      `/repos/${owner}/${repo}/pulls/${number}/files?per_page=${perPage}&page=${page}`,
+      options
+    );
     raw.push(...chunk);
     if (chunk.length < perPage) break;
   }
@@ -1055,7 +1331,9 @@ async function fetchLatestMergedPr(owner, repo, base, options) {
     `/repos/${owner}/${repo}/pulls?state=closed&base=${encodeURIComponent(base)}&sort=updated&direction=desc&per_page=30`,
     options
   );
-  const merged = raw.filter((pr) => Boolean(pr.merged_at)).sort((a, b) => Date.parse(b.merged_at ?? "") - Date.parse(a.merged_at ?? ""))[0];
+  const merged = raw.filter((pr) => Boolean(pr.merged_at)).sort(
+    (a, b) => Date.parse(b.merged_at ?? "") - Date.parse(a.merged_at ?? "")
+  )[0];
   return merged ? toPullRequestInfo(merged) : null;
 }
 function compileGlob(pattern) {
@@ -1128,16 +1406,19 @@ _(diff truncated \u2014 ${files.length} file(s) total)_
   return context.slice(0, TRACK_CONTEXT_CHAR_CAP);
 }
 function buildTrackTask(repo, pr, files) {
-  return { instruction: buildTrackInstruction(repo, pr), context: buildTrackContext(repo, pr, files) };
+  return {
+    instruction: buildTrackInstruction(repo, pr),
+    context: buildTrackContext(repo, pr, files)
+  };
 }
 
 // src/tools/sync-from-repo.ts
-var syncFromRepoSchema = z14.object({
-  projectDir: z14.string().describe("Path to the Thally project (reads the tracking config from docs.json)"),
-  repo: z14.string().optional().describe("Tracked repo to sync as owner/repo (defaults to the single tracked repo when only one is configured)"),
-  pr: z14.number().optional().describe("Pull request number to analyze (defaults to the latest PR merged into the tracked base branch)"),
-  dryRun: z14.boolean().optional().default(true).describe("When true (default), preview the distilled docs task without dispatching anything"),
-  docsRepo: z14.string().optional().describe("owner/repo of the docs repository to dispatch the task to (required when dryRun is false)")
+var syncFromRepoSchema = z15.object({
+  projectDir: z15.string().describe("Path to the Thally project (reads the tracking config from docs.json)"),
+  repo: z15.string().optional().describe("Tracked repo to sync as owner/repo (defaults to the single tracked repo when only one is configured)"),
+  pr: z15.number().optional().describe("Pull request number to analyze (defaults to the latest PR merged into the tracked base branch)"),
+  dryRun: z15.boolean().optional().default(true).describe("When true (default), preview the distilled docs task without dispatching anything"),
+  docsRepo: z15.string().optional().describe("owner/repo of the docs repository to dispatch the task to (required when dryRun is false)")
 });
 async function handleSyncFromRepo(input) {
   const config = readDocsJson(input.projectDir);
@@ -1209,12 +1490,11 @@ async function handleSyncFromRepo(input) {
 }
 
 // src/tools/read-api-spec.ts
-import { readFileSync as readFileSync8 } from "fs";
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // src/lib/api-spec.ts
-import { existsSync as existsSync8, lstatSync, realpathSync } from "fs";
-import { isAbsolute, join as join9, posix, relative as relative2, resolve, sep } from "path";
+import { existsSync as existsSync9, lstatSync as lstatSync3, realpathSync as realpathSync3 } from "fs";
+import { isAbsolute as isAbsolute3, join as join10, posix, relative as relative4, resolve, sep as sep3 } from "path";
 var CONVENTIONAL_API_SOURCES = ["openapi.yaml", "openapi.yml", "openapi.json"];
 function normalizeApiSource(source) {
   const normalized = posix.normalize(source.trim().replace(/^\/+/, ""));
@@ -1226,7 +1506,7 @@ function normalizeApiSource(source) {
 function configuredApiSources(projectDir) {
   const configured = readDocsJson(projectDir).tabs.map((tab) => tab.api?.source).filter((source) => typeof source === "string").map(normalizeApiSource).filter((source) => source !== null);
   const conventional = CONVENTIONAL_API_SOURCES.filter(
-    (source) => existsSync8(join9(projectDir, source))
+    (source) => existsSync9(join10(projectDir, source))
   );
   return [.../* @__PURE__ */ new Set([...configured, ...conventional])];
 }
@@ -1250,12 +1530,12 @@ function resolveApiSource(projectDir, requested) {
 }
 function resolveApiSourcePath(projectDir, requested) {
   const source = resolveApiSource(projectDir, requested);
-  const projectRoot = realpathSync(projectDir);
+  const projectRoot = realpathSync3(projectDir);
   const candidate = resolve(projectRoot, source);
   try {
-    const resolved = realpathSync(candidate);
-    const fromRoot = relative2(projectRoot, resolved);
-    if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot) || !lstatSync(candidate).isFile() || lstatSync(candidate).isSymbolicLink()) {
+    const resolved = realpathSync3(candidate);
+    const fromRoot = relative4(projectRoot, resolved);
+    if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep3}`) || isAbsolute3(fromRoot) || !lstatSync3(candidate).isFile() || lstatSync3(candidate).isSymbolicLink()) {
       throw new Error("unsafe");
     }
     return { source, path: resolved };
@@ -1265,24 +1545,33 @@ function resolveApiSourcePath(projectDir, requested) {
 }
 
 // src/tools/read-api-spec.ts
-var readApiSpecSchema = z15.object({
-  projectDir: z15.string().describe("Path to the Thally project root"),
-  source: z15.string().optional().describe("Configured OpenAPI source; omit when the project has one")
+var readApiSpecSchema = z16.object({
+  projectDir: z16.string().describe("Path to the Thally project root"),
+  source: z16.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
+  startByte: z16.number().int().min(0).optional().describe("UTF-8 byte continuation from a previous partial result"),
+  startLine: z16.number().int().min(1).optional().describe("1-based source line to start at; do not combine with startByte"),
+  maxBytes: z16.number().int().min(1).max(MODEL_READ_WINDOW_MAX_BYTES).optional().describe(
+    `Maximum source bytes to return (default 49152, maximum ${MODEL_READ_WINDOW_MAX_BYTES})`
+  )
 });
 async function handleReadApiSpec(input) {
   const source = resolveApiSourcePath(input.projectDir, input.source);
-  return [`API source: ${source.source}`, "", readFileSync8(source.path, "utf8")].join("\n");
+  const window = createTextWindow(readModelTextFile(source.path), input);
+  return [
+    `API source: ${source.source}`,
+    ...renderTextWindow(window).split("\n")
+  ].join("\n");
 }
 
 // src/tools/update-api-spec.ts
-import { writeFileSync as writeFileSync6 } from "fs";
+import { writeFileSync as writeFileSync7 } from "fs";
 import { extname as extname2 } from "path";
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 import { parse as parseYaml } from "yaml";
-var updateApiSpecSchema = z16.object({
-  projectDir: z16.string().describe("Path to the Thally project root"),
-  source: z16.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
-  content: z16.string().min(2).max(512e3).describe("Complete replacement OpenAPI JSON or YAML document")
+var updateApiSpecSchema = z17.object({
+  projectDir: z17.string().describe("Path to the Thally project root"),
+  source: z17.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
+  content: z17.string().min(2).max(512e3).describe("Complete replacement OpenAPI JSON or YAML document")
 });
 function parseDocument(source, content) {
   try {
@@ -1301,7 +1590,7 @@ async function handleUpdateApiSpec(input) {
   }
   const content = input.content.endsWith("\n") ? input.content : `${input.content}
 `;
-  writeFileSync6(source.path, content, "utf8");
+  writeFileSync7(source.path, content, "utf8");
   return `\u2705 API source updated: ${source.source}`;
 }
 
@@ -1345,9 +1634,16 @@ var tools = [
     schema: updatePageSchema,
     handler: handleUpdatePage
   }),
+  defineTool({
+    name: "replace_page_text",
+    description: "Replace one exact unique span in an existing MDX page; prefer this for small edits so the full page never travels through the model response",
+    scope: "project",
+    schema: replacePageTextSchema,
+    handler: handleReplacePageText
+  }),
   defineTool({
     name: "read_api_spec",
-    description: "Read an OpenAPI JSON or YAML source explicitly configured by this Thally project",
+    description: "Read a bounded UTF-8 window from an OpenAPI JSON or YAML source configured by this project; follow next-start-byte until complete",
     scope: "project",
     schema: readApiSpecSchema,
     handler: handleReadApiSpec
@@ -1396,7 +1692,7 @@ var tools = [
   }),
   defineTool({
     name: "read_page",
-    description: "Read the full content of a documentation page by its page ID",
+    description: "Read a bounded UTF-8 body window from a documentation page; follow next-start-byte until complete before replacing a page",
     scope: "project",
     schema: readPageSchema,
     handler: handleReadPage