@attentionform/astra-mcp-server 0.4.2 → 0.5.1

package/dist/index.js

@@ -45,7 +45,7 @@ __export(index_exports, {
   takeDirFlag: () => takeDirFlag
 });
 module.exports = __toCommonJS(index_exports);
-var path21 = __toESM(require("path"));
+var path24 = __toESM(require("path"));
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_types2 = require("@modelcontextprotocol/sdk/types.js");
@@ -212,6 +212,44 @@ async function refreshAstInPlace(target, parser2, options = {}) {
   return notes;
 }
 
+// ../engine/src/heading-style.ts
+function headingLevelOfStyle(lowerStyleId) {
+  const id = lowerStyleId.replace(/\s+/g, "");
+  const numbered = /^heading([1-9])$/.exec(id);
+  if (numbered) return Number(numbered[1]);
+  if (id === "subtitle") return 2;
+  return 1;
+}
+function headingLevelOfStyleId(styleId) {
+  if (!styleId) return null;
+  const lower = styleId.toLowerCase();
+  if (!(lower.includes("heading") || lower.includes("title") || lower.includes("subtitle"))) return null;
+  return headingLevelOfStyle(lower);
+}
+function ownParagraphStyleId(paragraph) {
+  if (paragraph.tagName !== "w:p") return void 0;
+  for (let i = 0; i < paragraph.childNodes.length; i++) {
+    const pPr = paragraph.childNodes[i];
+    if (pPr.nodeType !== 1 || pPr.tagName !== "w:pPr") continue;
+    for (let k = 0; k < pPr.childNodes.length; k++) {
+      const el = pPr.childNodes[k];
+      if (el.nodeType === 1 && el.tagName === "w:pStyle") return el.getAttribute("w:val") || void 0;
+    }
+    return void 0;
+  }
+  return void 0;
+}
+function headingOfNode(node) {
+  const style = ownParagraphStyleId(node.xml);
+  const level = headingLevelOfStyleId(style);
+  return style !== void 0 && level !== null ? { style, level } : null;
+}
+function countHeadings(ast) {
+  let n = 0;
+  for (const sec of ast.sections) for (const node of sec.nodes) if (headingOfNode(node)) n += 1;
+  return n;
+}
+
 // ../engine/src/ooxml/revision-ids.ts
 var REVISION_TAGS = [
   "ins",
@@ -2003,8 +2041,8 @@ function sortChildrenBySchema(element, order) {
 }
 function generateValidParaId(seed, counter = 0) {
   if (seed !== void 0 && seed !== null && seed !== "") {
-    const hash = import_crypto2.default.createHash("sha256").update(`${seed}:${counter}`).digest();
-    const raw = hash.readUInt32BE(0) & 2147483647;
+    const hash2 = import_crypto2.default.createHash("sha256").update(`${seed}:${counter}`).digest();
+    const raw = hash2.readUInt32BE(0) & 2147483647;
     const val2 = raw === 0 ? 1 : raw;
     return val2.toString(16).toUpperCase().padStart(8, "0");
   }
@@ -2905,8 +2943,8 @@ function parserRandomUnit() {
   if (injectedParserRandom) return injectedParserRandom();
   if (resolveReproducibleMode(void 0)) {
     parserDeterministicSeq += 1;
-    const hash = (parserDeterministicSeq * 2654435761 >>> 0) / 4294967296;
-    return hash === 0 ? 0.5 : hash;
+    const hash2 = (parserDeterministicSeq * 2654435761 >>> 0) / 4294967296;
+    return hash2 === 0 ? 0.5 : hash2;
   }
   return Math.random();
 }
@@ -3033,11 +3071,12 @@ function sortContainerChildren(container, order) {
   const after = next.filter((node) => node.nodeType === 1).map((node) => node.tagName);
   return { reordered: true, before, after };
 }
-function passSorts(doc, entries) {
+function passSorts(doc, entries, reorderedContainers) {
   for (const { tag, order } of SORT_CONTAINERS) {
     for (const container of snapshotElements(doc, tag)) {
       const { reordered, before, after } = sortContainerChildren(container, order);
       if (reordered) {
+        reorderedContainers?.push(elementXPath(container));
         entries.push(`Reordered ${tag} into schema order${locationSuffix(container)}: [${before.join(",")}] \u2192 [${after.join(",")}]`);
       }
     }
@@ -3100,6 +3139,9 @@ function normalizePartXml(partName, xml) {
   if (entries.length === 0) return { xml, normalized: [] };
   return { xml: partSerializer.serializeToString(doc), normalized: entries };
 }
+var ORDERED_CONTAINERS = new Map(
+  SORT_CONTAINERS.map((c) => [c.tag.slice(c.tag.indexOf(":") + 1), new Set(c.order)])
+);
 
 // ../engine/src/ooxml/omml.ts
 var OMML_MAX_DEPTH = 6;
@@ -4530,9 +4572,9 @@ function ommlToMathmlDisplay(xml) {
 // ../engine/src/ooxml/validator-backend.ts
 var nativeBackend = {
   name: "native",
-  async validateFile(path22, opts) {
+  async validateFile(path25, opts) {
     const native = await import("@attentionform/ooxml-validator");
-    return native.validateFile(path22, opts ? { officeVersion: opts.officeVersion } : void 0);
+    return native.validateFile(path25, opts ? { officeVersion: opts.officeVersion } : void 0);
   },
   async validateBuffer(buf, opts) {
     const native = await import("@attentionform/ooxml-validator");
@@ -4562,14 +4604,16 @@ var OoxmlValidationError = class extends Error {
   errors;
   firstError;
   code = "E_VALIDATION";
-  remedy = "re-export the file from Word (or pick a valid .docx) and retry";
+  remedy;
   retryable = false;
-  constructor(errors, context = "Document") {
+  /** `remedy` replaces the default text for callers that know a better next step (PDF export does). */
+  constructor(errors, context = "Document", remedy) {
     const first = errors[0] || {};
     const xp = typeof first.xPath === "string" && first.xPath || typeof first.path === "string" && first.path || "unknown";
     const hint = tableIndexHintForXPath(first.xPath ?? first.path);
     const detail = `${first.description || "Schema error"} @ ${xp}${hint ? ` (${hint})` : ""}`;
     super(`[OOXML Schema Violation] ${context} has ${errors.length} validation error(s): ${detail}`);
+    this.remedy = remedy ?? "re-export the file from Word (or pick a valid .docx) and retry";
     this.name = "OoxmlValidationError";
     this.errors = errors;
     this.firstError = first;
@@ -5494,10 +5538,10 @@ function mergeCorePropertiesXml(existingXml, patch, fallback) {
   return { xml: serializer2.serializeToString(doc), touched };
 }
 function ensureContentTypeOverride(adapter) {
-  const path22 = "[Content_Types].xml";
+  const path25 = "[Content_Types].xml";
   let raw = null;
   try {
-    raw = adapter.readTextOrNull(path22);
+    raw = adapter.readTextOrNull(path25);
   } catch {
     return;
   }
@@ -5514,13 +5558,13 @@ function ensureContentTypeOverride(adapter) {
   created.setAttribute("PartName", "/docProps/core.xml");
   created.setAttribute("ContentType", CORE_PROPERTIES_CONTENT_TYPE);
   root.appendChild(created);
-  adapter.writeText(path22, new import_xmldom7.XMLSerializer().serializeToString(doc));
+  adapter.writeText(path25, new import_xmldom7.XMLSerializer().serializeToString(doc));
 }
 function ensurePackageRel(adapter) {
-  const path22 = "_rels/.rels";
+  const path25 = "_rels/.rels";
   let raw = null;
   try {
-    raw = adapter.readTextOrNull(path22);
+    raw = adapter.readTextOrNull(path25);
   } catch {
     return;
   }
@@ -5553,7 +5597,7 @@ function ensurePackageRel(adapter) {
   created.setAttribute("Type", CORE_PROPERTIES_REL_TYPE);
   created.setAttribute("Target", CORE_PROPERTIES_PART);
   root.appendChild(created);
-  adapter.writeText(path22, new import_xmldom7.XMLSerializer().serializeToString(doc));
+  adapter.writeText(path25, new import_xmldom7.XMLSerializer().serializeToString(doc));
 }
 function writeCorePropertiesPart(adapter, xml) {
   adapter.writeText(CORE_PROPERTIES_PART, xml);
@@ -7416,20 +7460,20 @@ function sanitizeEmbeddedWorkbookBytes(buf, outerName) {
 }
 var XML_PART_RE = /^(word\/document\.xml|word\/styles\.xml|word\/stylesWithEffects\.xml|word\/numbering\.xml|word\/comments\.xml|word\/commentsExtended\.xml|word\/footnotes\.xml|word\/endnotes\.xml|word\/settings\.xml|word\/header.*\.xml|word\/footer.*\.xml|word\/people\.xml|word\/customXml\/.*\.xml|word\/charts\/.*\.xml|word\/embeddings\/.*\.xml)$/i;
 function bufferZipAdapter(files, touched) {
-  const write = (path22, content) => {
-    files.set(path22, content);
-    touched?.add(path22);
+  const write = (path25, content) => {
+    files.set(path25, content);
+    touched?.add(path25);
   };
   return {
-    hasFile: (path22) => files.has(path22),
-    readText: (path22) => {
-      const data = files.get(path22);
-      if (!data) throw new Error(`E_VALIDATION: Part ${path22} was not found.`);
+    hasFile: (path25) => files.has(path25),
+    readText: (path25) => {
+      const data = files.get(path25);
+      if (!data) throw new Error(`E_VALIDATION: Part ${path25} was not found.`);
       return data.toString("utf8");
     },
-    readTextOrNull: (path22) => files.get(path22)?.toString("utf8") ?? null,
-    writeText: (path22, content) => write(path22, Buffer.from(content, "utf8")),
-    writeBuffer: (path22, content) => write(path22, Buffer.from(content))
+    readTextOrNull: (path25) => files.get(path25)?.toString("utf8") ?? null,
+    writeText: (path25, content) => write(path25, Buffer.from(content, "utf8")),
+    writeBuffer: (path25, content) => write(path25, Buffer.from(content))
   };
 }
 function deleteRemovedComments(files, ids, touched) {
@@ -10414,7 +10458,7 @@ var DocxParser = class _DocxParser {
    * Captures a full package snapshot: a clone of every zip entry buffer.
    * Used by OperationEngine for transactional rollback of failed batches.
    */
-  capturePackageSnapshot() {
+  capturePackageSnapshot(options) {
     this.purgeRogueZipEntries();
     const snapshot3 = /* @__PURE__ */ new Map();
     for (const entry of this.zip.getEntries()) {
@@ -10425,7 +10469,7 @@ var DocxParser = class _DocxParser {
       snapshot3.set(entry.entryName, Buffer.from(entry.getData()));
     }
     try {
-      snapshot3.set("word/document.xml", Buffer.from(this.readDocumentXml(), "utf8"));
+      snapshot3.set("word/document.xml", Buffer.from(options?.documentXml ?? this.readDocumentXml(), "utf8"));
     } catch {
     }
     return snapshot3;
@@ -10912,22 +10956,10 @@ var DocxParser = class _DocxParser {
       }
       let isHeading = false;
       let headingLevel = void 0;
-      const pStyle = node.getElementsByTagName("w:pStyle")[0];
-      if (pStyle) {
-        const val = pStyle.getAttribute("w:val") || "";
-        const lowerVal = val.toLowerCase();
-        if (lowerVal.includes("heading") || lowerVal.includes("title") || lowerVal.includes("subtitle")) {
-          isHeading = true;
-          if (lowerVal.includes("heading 1") || lowerVal === "heading1" || lowerVal === "h1" || lowerVal.includes("title")) {
-            headingLevel = 1;
-          } else if (lowerVal.includes("heading 2") || lowerVal === "heading2" || lowerVal === "h2" || lowerVal.includes("subtitle")) {
-            headingLevel = 2;
-          } else if (lowerVal.includes("heading 3") || lowerVal === "heading3" || lowerVal === "h3") {
-            headingLevel = 3;
-          } else {
-            headingLevel = 1;
-          }
-        }
+      const ownLevel = headingLevelOfStyleId(ownParagraphStyleId(node));
+      if (ownLevel !== null) {
+        isHeading = true;
+        headingLevel = ownLevel;
       }
       const hasTrackedChanges = nodeHasTrackedChanges(node);
       if (hasTrackedChanges) summary.hasTrackedChanges = true;
@@ -11068,20 +11100,20 @@ var DocxParser = class _DocxParser {
   }
   getZipAdapter() {
     return {
-      hasFile: (path22) => !!this.zip.getEntry(this.sanitizePath(path22)),
-      readText: (path22) => {
-        const cleanPath = this.sanitizePath(path22);
+      hasFile: (path25) => !!this.zip.getEntry(this.sanitizePath(path25)),
+      readText: (path25) => {
+        const cleanPath = this.sanitizePath(path25);
         const entry = this.zip.getEntry(cleanPath);
         if (!entry) throw new Error(`File not found: ${cleanPath}`);
         return entry.getData().toString("utf8");
       },
-      readTextOrNull: (path22) => {
-        const cleanPath = this.sanitizePath(path22);
+      readTextOrNull: (path25) => {
+        const cleanPath = this.sanitizePath(path25);
         const entry = this.zip.getEntry(cleanPath);
         return entry ? entry.getData().toString("utf8") : null;
       },
-      writeText: (path22, content) => {
-        const cleanPath = this.sanitizePath(path22);
+      writeText: (path25, content) => {
+        const cleanPath = this.sanitizePath(path25);
         assertNoXxe(content, cleanPath);
         assertNoXxeAdjacent(content, cleanPath);
         if (this.zip.getEntry(cleanPath)) {
@@ -11090,8 +11122,8 @@ var DocxParser = class _DocxParser {
           this.zip.addFile(cleanPath, Buffer.from(content, "utf8"));
         }
       },
-      writeBuffer: (path22, content) => {
-        const cleanPath = this.sanitizePath(path22);
+      writeBuffer: (path25, content) => {
+        const cleanPath = this.sanitizePath(path25);
         assertNoXxe(content.toString("utf8"), cleanPath);
         assertNoXxeAdjacent(content.toString("utf8"), cleanPath);
         if (this.zip.getEntry(cleanPath)) {
@@ -11223,8 +11255,7 @@ var DocxParser = class _DocxParser {
           }
         }
       }
-      const pStyleEl = element.getElementsByTagName("w:pStyle")[0];
-      const namedStyle = pStyleEl ? pStyleEl.getAttribute("w:val") || void 0 : void 0;
+      const namedStyle = ownParagraphStyleId(element);
       let nodeType = element.tagName === "w:p" ? "paragraph" : "table";
       let chartData = void 0;
       let detectedChart = void 0;
@@ -12915,12 +12946,12 @@ ${validation.errors.join("\n")}`, "repair the part XML or re-save the document i
     if (!comments || /<w:comment[\s>]/.test(comments.getData().toString("utf8"))) return;
     const parts = ["comments", "commentsExtended", "commentsIds", "commentsExtensible"].map((n) => `${n}.xml`);
     for (const part of parts) if (this.zip.getEntry(`word/${part}`)) this.zip.deleteFile(`word/${part}`);
-    const edit = (path22, tag, attr, drop) => {
-      const entry = this.zip.getEntry(path22);
+    const edit = (path25, tag, attr, drop) => {
+      const entry = this.zip.getEntry(path25);
       if (!entry) return;
       const dom = this.parser.parseFromString(entry.getData().toString("utf8"), "text/xml");
       for (const el of Array.from(dom.getElementsByTagName(tag))) if (drop(el.getAttribute(attr) ?? "")) el.parentNode?.removeChild(el);
-      this.zip.updateFile(path22, Buffer.from(this.serializer.serializeToString(dom), "utf8"));
+      this.zip.updateFile(path25, Buffer.from(this.serializer.serializeToString(dom), "utf8"));
     };
     edit("word/_rels/document.xml.rels", "Relationship", "Target", (value) => parts.includes(value.replace(/^\/?(word\/)?/, "")));
     edit("[Content_Types].xml", "Override", "PartName", (value) => parts.map((p) => `/word/${p}`).includes(value));
@@ -13658,12 +13689,11 @@ ${validation.errors.join("\n")}`, "repair the part XML or re-save the document i
   }
 };
 
-// ../engine/src/git.ts
-var import_fs4 = __toESM(require("fs"));
-var import_promises2 = __toESM(require("fs/promises"));
-var import_path3 = __toESM(require("path"));
-var import_crypto4 = __toESM(require("crypto"));
-var import_isomorphic_git = __toESM(require("isomorphic-git"));
+// ../engine/src/original.ts
+var import_node_fs = __toESM(require("node:fs"));
+var import_promises2 = __toESM(require("node:fs/promises"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_crypto = require("node:crypto");
 
 // ../engine/src/sandbox/paths.ts
 var import_fs3 = __toESM(require("fs"));
@@ -13805,7 +13835,408 @@ function writeFileNoFollowSync(target, data, encoding = "utf8") {
   assertWriteTargetNoSymlink(import_path2.default.resolve(target));
 }
 
+// ../engine/src/original.ts
+var SNAPSHOT_NAME = "original.snapshot";
+var SNAPSHOT_MAGIC = Buffer.from("ASTRA-ORIGINAL\n");
+var MAX_SNAPSHOT_HEADER = 4096;
+function originalSha256(bytes) {
+  return (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
+}
+function coded(message, code = "E_IO") {
+  return Object.assign(new Error(message), { code });
+}
+function errno(e) {
+  return typeof e === "object" && e !== null && "code" in e ? String(e.code) : "";
+}
+function originalDir(docPath) {
+  return import_node_path.default.join(getRepoDir(docPath), ".git", "astra-original");
+}
+async function readSafe(file, maxBytes = resolveHistoryMaxSidecarBytes()) {
+  assertWriteTargetNoSymlink(file);
+  const h = await import_promises2.default.open(file, import_node_fs.default.constants.O_RDONLY | import_node_fs.default.constants.O_NOFOLLOW);
+  try {
+    const stat3 = await h.stat();
+    if (!stat3.isFile() || stat3.size > maxBytes) throw coded("Original recovery refused: expected a regular file within the size limit.");
+    return await h.readFile();
+  } finally {
+    await h.close();
+  }
+}
+async function exists(file) {
+  try {
+    await import_promises2.default.lstat(file);
+    return true;
+  } catch (e) {
+    if (errno(e) === "ENOENT") return false;
+    throw e;
+  }
+}
+async function syncDirectory(dir) {
+  if (process.platform === "win32") return false;
+  let h;
+  let synced = false;
+  try {
+    h = await import_promises2.default.open(dir, import_node_fs.default.constants.O_RDONLY);
+    await h.sync();
+    synced = true;
+  } catch {
+  }
+  try {
+    await h?.close();
+  } catch {
+    synced = false;
+  }
+  return synced;
+}
+async function cleanupTemp(file) {
+  try {
+    await import_promises2.default.unlink(file);
+  } catch (e) {
+    if (errno(e) !== "ENOENT") throw Object.assign(coded(`Temporary file cleanup failed: ${file}. ${e instanceof Error ? e.message : String(e)}`), { tempPath: file });
+  }
+}
+async function preparedTempParts(target, parts, mode = 384) {
+  assertWriteTargetNoSymlink(target);
+  const dir = import_node_path.default.dirname(target);
+  await import_promises2.default.mkdir(dir, { recursive: true, mode: 448 });
+  assertWriteTargetNoSymlink(target);
+  const tmp = import_node_path.default.join(dir, `.${import_node_path.default.basename(target).slice(0, 60)}.astra-tmp-${(0, import_node_crypto.randomUUID)()}`);
+  const h = await import_promises2.default.open(tmp, import_node_fs.default.constants.O_WRONLY | import_node_fs.default.constants.O_CREAT | import_node_fs.default.constants.O_EXCL | import_node_fs.default.constants.O_NOFOLLOW, mode);
+  let writeError;
+  try {
+    for (const part of parts) {
+      let offset = 0;
+      while (offset < part.length) {
+        const { bytesWritten } = await h.write(part, offset, part.length - offset, null);
+        if (bytesWritten === 0) throw coded("Original recovery refused: temporary file write made no progress.");
+        offset += bytesWritten;
+      }
+    }
+    await h.sync();
+  } catch (error) {
+    writeError = error;
+  }
+  let closeError;
+  try {
+    await h.close();
+  } catch (error) {
+    closeError = error;
+  }
+  if (writeError || closeError) {
+    const primary = writeError ?? closeError;
+    let message = primary instanceof Error ? primary.message : String(primary);
+    if (writeError && closeError) message += `; temporary file close also failed: ${closeError instanceof Error ? closeError.message : String(closeError)}`;
+    let cleanupFailed = false;
+    try {
+      await cleanupTemp(tmp);
+    } catch (cleanup) {
+      cleanupFailed = true;
+      message += `; ${cleanup instanceof Error ? cleanup.message : String(cleanup)}`;
+    }
+    throw Object.assign(coded(message, errno(primary) || "E_IO"), { ...cleanupFailed ? { tempPath: tmp } : {}, cause: primary });
+  }
+  try {
+    const expectedBytes = parts.reduce((total, part) => total + part.length, 0);
+    const expectedHash = (0, import_node_crypto.createHash)("sha256");
+    for (const part of parts) expectedHash.update(part);
+    const check = await import_promises2.default.open(tmp, import_node_fs.default.constants.O_RDONLY | import_node_fs.default.constants.O_NOFOLLOW);
+    try {
+      const stat3 = await check.stat();
+      if (!stat3.isFile() || stat3.size !== expectedBytes) throw coded("Original recovery refused: temporary file integrity check failed.");
+      const actualHash = (0, import_node_crypto.createHash)("sha256");
+      const chunk = Buffer.allocUnsafe(64 * 1024);
+      let position2 = 0;
+      while (position2 < expectedBytes) {
+        const { bytesRead } = await check.read(chunk, 0, Math.min(chunk.length, expectedBytes - position2), position2);
+        if (bytesRead === 0) throw coded("Original recovery refused: temporary file integrity check failed.");
+        actualHash.update(chunk.subarray(0, bytesRead));
+        position2 += bytesRead;
+      }
+      if (actualHash.digest("hex") !== expectedHash.digest("hex")) throw coded("Original recovery refused: temporary file integrity check failed.");
+    } finally {
+      await check.close();
+    }
+  } catch (e) {
+    try {
+      await cleanupTemp(tmp);
+    } catch (cleanup) {
+      throw coded(`${e instanceof Error ? e.message : String(e)}; ${cleanup instanceof Error ? cleanup.message : String(cleanup)}`);
+    }
+    throw e;
+  }
+  return tmp;
+}
+async function preparedTemp(target, data, mode = 384) {
+  return preparedTempParts(target, [data], mode);
+}
+async function writePartsExclusive(target, parts, mode = 384) {
+  const tmp = await preparedTempParts(target, parts, mode);
+  let failure;
+  try {
+    assertWriteTargetNoSymlink(target);
+    try {
+      await import_promises2.default.link(tmp, target);
+    } catch (e) {
+      if (errno(e) === "EEXIST") throw coded(`Destination exists: ${target}`, "E_CONFLICT");
+      if (["ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV", "ENOSYS"].includes(errno(e))) {
+        throw coded("This location does not support safe exclusive publication; export to another directory.");
+      }
+      throw e;
+    }
+    await syncDirectory(import_node_path.default.dirname(target));
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    await cleanupTemp(tmp);
+  } catch (cleanup) {
+    const detail = cleanup instanceof Error ? cleanup.message : String(cleanup);
+    if (failure) {
+      throw Object.assign(coded(`${failure instanceof Error ? failure.message : String(failure)}; ${detail}`, errno(failure) || "E_IO"), { tempPath: tmp });
+    }
+    throw Object.assign(coded(`Destination was published at ${target}, but ${detail}`), { tempPath: tmp, published: true });
+  }
+  if (failure) throw failure;
+}
+async function writeFileExclusive(target, data, mode = 384) {
+  return writePartsExclusive(target, [data], mode);
+}
+async function createVerifiedBackup(target, bytes) {
+  let ownsTarget = false;
+  try {
+    await writeFileExclusive(target, bytes);
+    ownsTarget = true;
+    assertWriteTargetNoSymlink(target);
+    const written = await import_promises2.default.readFile(target);
+    if (written.length !== bytes.length || originalSha256(written) !== originalSha256(bytes)) {
+      throw coded(`Restore backup verification failed: ${target}`, "E_IO");
+    }
+  } catch (error) {
+    if (error?.published === true) ownsTarget = true;
+    if (ownsTarget) {
+      try {
+        await import_promises2.default.unlink(target);
+      } catch (cleanupError) {
+        if (errno(cleanupError) !== "ENOENT") {
+          throw Object.assign(coded(`${error instanceof Error ? error.message : String(error)}; invalid backup could not be removed: ${target} (${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)})`, "E_IO"), { backupPath: target });
+        }
+      }
+    }
+    throw error;
+  }
+}
+function newRestoreBackupPath(target) {
+  return import_node_path.default.join(import_node_path.default.dirname(target), `.astra-restore-backup-${(0, import_node_crypto.randomUUID)()}`);
+}
+async function replaceFileAtomic(target, data, newFileMode = 384) {
+  let tmp;
+  let replaced = false;
+  let renameStarted = false;
+  try {
+    assertWriteTargetNoSymlink(target);
+    let mode = newFileMode;
+    try {
+      const st = await import_promises2.default.lstat(target);
+      if (!st.isFile()) throw coded("Atomic replace requires a regular target file.");
+      mode = st.mode & 511;
+      if ((mode & 146) === 0) throw coded("Atomic replace refused: target is read-only.");
+      await import_promises2.default.access(target, import_node_fs.default.constants.W_OK);
+    } catch (e) {
+      if (errno(e) !== "ENOENT") throw e;
+    }
+    tmp = await preparedTemp(target, data, mode);
+    assertWriteTargetNoSymlink(target);
+    renameStarted = true;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await import_promises2.default.rename(tmp, target);
+        replaced = true;
+        break;
+      } catch (e) {
+        if (process.platform !== "win32" || !["EBUSY", "EPERM", "EACCES"].includes(errno(e)) || attempt >= 3) throw e;
+        await new Promise((resolve10) => setTimeout(resolve10, 25 * (attempt + 1)));
+      }
+    }
+    const durable = await syncDirectory(import_node_path.default.dirname(target));
+    await cleanupTemp(tmp);
+    tmp = void 0;
+    return { outcome: "replaced", ...!durable ? { durabilityUnconfirmed: true } : {} };
+  } catch (e) {
+    let message = e instanceof Error ? e.message : String(e);
+    let outcome = replaced ? "replaced" : renameStarted ? "uncertain" : "not-replaced";
+    if (!replaced && renameStarted && tmp) {
+      try {
+        const tempStat = await import_promises2.default.lstat(tmp);
+        if (tempStat.isFile() && !tempStat.isSymbolicLink()) outcome = "not-replaced";
+      } catch (tempError) {
+        if (errno(tempError) === "ENOENT") {
+          try {
+            assertWriteTargetNoSymlink(target);
+            const targetStat = await import_promises2.default.lstat(target);
+            if (targetStat.isFile() && targetStat.size === data.length && (await import_promises2.default.readFile(target)).equals(data)) {
+              replaced = true;
+              outcome = "replaced";
+            }
+          } catch {
+          }
+        }
+      }
+    }
+    if (tmp) {
+      try {
+        await cleanupTemp(tmp);
+      } catch (cleanup) {
+        message += `; ${cleanup instanceof Error ? cleanup.message : String(cleanup)}`;
+      }
+    }
+    throw Object.assign(coded(message, errno(e) || "E_IO"), {
+      outcome
+    });
+  }
+}
+function encodeSnapshot(bytes, sourceName) {
+  const meta = { magic: "ASTRA-ORIGINAL", version: 1, sha256: originalSha256(bytes), bytes: bytes.length, capturedAt: (/* @__PURE__ */ new Date()).toISOString(), sourceName };
+  const json = Buffer.from(JSON.stringify(meta));
+  if (json.length > MAX_SNAPSHOT_HEADER) throw coded("Original snapshot metadata exceeds its format limit.", "E_LIMIT");
+  const prefix = Buffer.alloc(SNAPSHOT_MAGIC.length + 4);
+  SNAPSHOT_MAGIC.copy(prefix);
+  prefix.writeUInt32BE(json.length, SNAPSHOT_MAGIC.length);
+  return [prefix, json, bytes];
+}
+function decodeSnapshot(all) {
+  const offset = SNAPSHOT_MAGIC.length;
+  if (all.length < offset + 4 || !all.subarray(0, offset).equals(SNAPSHOT_MAGIC)) throw coded("Original snapshot has an invalid format header.", "E_VALIDATION");
+  const headerBytes = all.readUInt32BE(offset);
+  if (headerBytes < 2 || headerBytes > MAX_SNAPSHOT_HEADER || all.length < offset + 4 + headerBytes) throw coded("Original snapshot has an invalid metadata length.", "E_VALIDATION");
+  let meta;
+  try {
+    meta = JSON.parse(all.subarray(offset + 4, offset + 4 + headerBytes).toString("utf8"));
+  } catch {
+    throw coded("Original snapshot metadata is not valid JSON.", "E_VALIDATION");
+  }
+  const bytes = all.subarray(offset + 4 + headerBytes);
+  if (meta.magic !== "ASTRA-ORIGINAL" || meta.version !== 1 || !/^[a-f0-9]{64}$/.test(meta.sha256) || !Number.isSafeInteger(meta.bytes) || meta.bytes < 1 || meta.bytes !== bytes.length || typeof meta.capturedAt !== "string" || typeof meta.sourceName !== "string") {
+    throw coded("Original snapshot metadata is invalid.", "E_VALIDATION");
+  }
+  if (originalSha256(bytes) !== meta.sha256) throw coded("Original snapshot integrity verification failed.", "E_VALIDATION");
+  return { meta, bytes };
+}
+async function verifiedSnapshot(docPath) {
+  const file = import_node_path.default.join(originalDir(docPath), SNAPSHOT_NAME);
+  const raw = await readSafe(file);
+  return decodeSnapshot(raw);
+}
+async function getOriginalInfo(docPath) {
+  if (!import_node_path.default.isAbsolute(docPath)) return { available: false, reason: "not-applicable" };
+  const dir = originalDir(docPath);
+  try {
+    if (!await exists(dir)) return { available: false, reason: "predates-feature" };
+    const snapshot3 = import_node_path.default.join(dir, SNAPSHOT_NAME);
+    assertWriteTargetNoSymlink(snapshot3);
+    if (await exists(snapshot3)) {
+      const { meta } = await verifiedSnapshot(docPath);
+      return { available: true, sha256: meta.sha256, bytes: meta.bytes, capturedAt: meta.capturedAt };
+    }
+    try {
+      const status = JSON.parse((await readSafe(import_node_path.default.join(dir, "status.json"), 16 * 1024)).toString("utf8"));
+      if (["capture-failed", "too-large", "not-applicable"].includes(status.reason)) return { available: false, reason: status.reason, ...typeof status.detail === "string" ? { detail: status.detail.slice(0, 1024) } : {} };
+    } catch {
+    }
+    return { available: false, reason: "incomplete" };
+  } catch (e) {
+    return { available: false, reason: "corrupt", detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+async function captureOriginal(docPath, bytes) {
+  const dir = originalDir(docPath);
+  let result;
+  try {
+    assertWriteTargetNoSymlink(import_node_path.default.join(dir, SNAPSHOT_NAME));
+    await import_promises2.default.mkdir(dir, { recursive: true, mode: 448 });
+    assertWriteTargetNoSymlink(import_node_path.default.join(dir, SNAPSHOT_NAME));
+    if (await exists(import_node_path.default.join(dir, SNAPSHOT_NAME))) {
+      const info = await getOriginalInfo(docPath);
+      if (info.available && bytes && originalSha256(bytes) !== info.sha256) return { available: false, reason: "capture-failed", detail: "An original is already recorded for this history." };
+      return info;
+    }
+    if (!bytes) result = { available: false, reason: "not-applicable" };
+    else if (!Buffer.isBuffer(bytes) || bytes.length === 0) result = { available: false, reason: "capture-failed", detail: "Original input is empty." };
+    else if (await getSidecarBytes(getRepoDir(docPath)) + bytes.length + 4096 + SNAPSHOT_MAGIC.length > resolveHistoryMaxSidecarBytes()) result = { available: false, reason: "too-large" };
+    else {
+      const digest = originalSha256(bytes);
+      const snapshot3 = import_node_path.default.join(dir, SNAPSHOT_NAME);
+      try {
+        await writePartsExclusive(snapshot3, encodeSnapshot(bytes, import_node_path.default.basename(docPath)));
+      } catch (e) {
+        if (e?.published === true) {
+          const published = await getOriginalInfo(docPath);
+          if (published.available && published.sha256 === digest) return published;
+          throw e;
+        }
+        if (errno(e) !== "E_CONFLICT") throw e;
+        const winner = await verifiedSnapshot(docPath);
+        if (!winner.bytes.equals(bytes)) return { available: false, reason: "capture-failed", detail: "An original is already recorded for this history." };
+      }
+      const info = await getOriginalInfo(docPath);
+      if (info.available && info.sha256 !== digest) return { available: false, reason: "capture-failed", detail: "An original is already recorded for this history." };
+      return info;
+    }
+  } catch (e) {
+    result = { available: false, reason: "capture-failed", detail: e instanceof Error ? e.message : String(e) };
+  }
+  try {
+    await writeFileExclusive(import_node_path.default.join(dir, "status.json"), Buffer.from(JSON.stringify(result)));
+  } catch {
+  }
+  return result;
+}
+async function readOriginal(docPath) {
+  const info = await getOriginalInfo(docPath);
+  if (!info.available) {
+    throw Object.assign(coded(`Original unavailable: ${info.reason}${info.detail ? ` (${info.detail})` : ""}`, "E_STATE"), {
+      remedy: "The retained original cannot be trusted, so no substitute is returned. Keep the working file and any separate backup, and check the history status for the reason."
+    });
+  }
+  return (await verifiedSnapshot(docPath)).bytes;
+}
+async function exportOriginal(docPath, outPath, opts) {
+  const bytes = await readOriginal(docPath);
+  const source = await import_promises2.default.realpath(docPath).catch((e) => {
+    if (errno(e) === "ENOENT") return import_node_path.default.resolve(docPath);
+    throw e;
+  });
+  const parent = import_node_path.default.dirname(import_node_path.default.resolve(outPath));
+  const destination = import_node_path.default.join(await import_promises2.default.realpath(parent).catch((e) => {
+    if (errno(e) === "ENOENT") return parent;
+    throw e;
+  }), import_node_path.default.basename(outPath));
+  const samePath = (a, b) => process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  let sameFile = samePath(source, destination);
+  try {
+    const [a, b] = await Promise.all([import_promises2.default.stat(source), import_promises2.default.stat(destination)]);
+    sameFile ||= a.ino !== 0 && b.ino !== 0 && a.dev === b.dev && a.ino === b.ino;
+  } catch (e) {
+    if (errno(e) !== "ENOENT") throw e;
+  }
+  if (sameFile) throw coded("Use restore_original_document to replace the working file.", "E_CONFLICT");
+  const repo = await import_promises2.default.realpath(getRepoDir(docPath));
+  const normalizedDest = process.platform === "win32" ? destination.toLowerCase() : destination;
+  const normalizedRepo = process.platform === "win32" ? repo.toLowerCase() : repo;
+  if (normalizedDest === normalizedRepo || normalizedDest.startsWith(`${normalizedRepo}${import_node_path.default.sep}`)) {
+    throw coded("Original export cannot write inside the document history store.", "E_CONFLICT");
+  }
+  if (opts?.overwrite) await replaceFileAtomic(outPath, bytes, 438);
+  else await writeFileExclusive(outPath, bytes, 438);
+  return getOriginalInfo(docPath);
+}
+
 // ../engine/src/git.ts
+var import_fs4 = __toESM(require("fs"));
+var import_os = __toESM(require("os"));
+var import_promises3 = __toESM(require("fs/promises"));
+var import_path3 = __toESM(require("path"));
+var import_crypto4 = __toESM(require("crypto"));
+var import_isomorphic_git = __toESM(require("isomorphic-git"));
 var HISTORY_DIR_ENV = "ASTRA_HISTORY_DIR";
 function historyRoot() {
   const raw = process.env[HISTORY_DIR_ENV];
@@ -13916,7 +14347,7 @@ async function writeAndAdd(repoDir, relPath, content) {
   const fullPath = import_path3.default.join(repoDir, safeRel);
   const dirName = import_path3.default.dirname(fullPath);
   assertWriteTargetNoSymlink(fullPath);
-  await import_promises2.default.mkdir(dirName, { recursive: true, mode: 448 });
+  await import_promises3.default.mkdir(dirName, { recursive: true, mode: 448 });
   await secureDirChain0700(repoDir, dirName);
   assertWriteTargetNoSymlink(fullPath);
   await writeFileNoFollow(fullPath, content);
@@ -13945,6 +14376,40 @@ async function indexedPartPaths(repoDir) {
   const tracked = await import_isomorphic_git.default.listFiles({ fs: import_fs4.default, dir: repoDir });
   return new Set(tracked.map((t) => toRepoRelative(t)).filter(isRepoPartPath));
 }
+async function clearUncommittedPackageParts(repoDir) {
+  const repoRoot = import_path3.default.resolve(repoDir);
+  for (const rel of await indexedPartPaths(repoDir)) {
+    if (isTraversalName(rel)) {
+      throw Object.assign(new Error(`History repair refused an unsafe indexed path: ${rel}`), { code: "E_SANDBOX" });
+    }
+    const fullPath = import_path3.default.resolve(repoRoot, rel);
+    const relative3 = import_path3.default.relative(repoRoot, fullPath);
+    if (relative3 === "" || relative3 === ".." || relative3.startsWith(`..${import_path3.default.sep}`) || import_path3.default.isAbsolute(relative3)) {
+      throw Object.assign(new Error(`History repair refused an indexed path outside its repository: ${rel}`), { code: "E_SANDBOX" });
+    }
+    assertWriteTargetNoSymlink(fullPath);
+    try {
+      await import_promises3.default.unlink(fullPath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    await import_isomorphic_git.default.remove({ fs: import_fs4.default, dir: repoDir, filepath: rel });
+  }
+}
+async function isUnbornHistory(repoDir) {
+  let head;
+  try {
+    head = await import_promises3.default.readFile(import_path3.default.join(repoDir, ".git", "HEAD"), "utf8");
+  } catch {
+    return false;
+  }
+  if (!/^ref:\s*refs\/heads\/[^\s]+\s*$/.test(head)) return false;
+  const [branches, tags] = await Promise.all([
+    import_isomorphic_git.default.listBranches({ fs: import_fs4.default, dir: repoDir }),
+    import_isomorphic_git.default.listTags({ fs: import_fs4.default, dir: repoDir })
+  ]);
+  return branches.length === 0 && tags.length === 0;
+}
 async function snapshotIsProvenComplete(repoDir, extraFiles, written) {
   if (!extraFiles) return false;
   try {
@@ -13963,7 +14428,7 @@ async function applySnapshotMarker(repoDir, complete) {
     return;
   }
   try {
-    await import_promises2.default.unlink(import_path3.default.join(repoDir, SNAPSHOT_FORMAT_MARKER));
+    await import_promises3.default.unlink(import_path3.default.join(repoDir, SNAPSHOT_FORMAT_MARKER));
   } catch {
   }
   try {
@@ -13978,7 +14443,7 @@ async function applySnapshotMarker(repoDir, complete) {
 async function chmod0700BestEffort(dir) {
   if (process.platform === "win32") return;
   try {
-    await import_promises2.default.chmod(dir, 448);
+    await import_promises3.default.chmod(dir, 448);
   } catch {
   }
 }
@@ -14011,7 +14476,7 @@ async function migrateExistingTree0700(repoDir) {
       await chmod0700BestEffort(dir);
       let entries = [];
       try {
-        entries = await import_promises2.default.readdir(dir, { withFileTypes: true });
+        entries = await import_promises3.default.readdir(dir, { withFileTypes: true });
       } catch {
         continue;
       }
@@ -14061,7 +14526,7 @@ async function getSidecarBytes(repoDir) {
     const dir = stack.pop();
     let entries = [];
     try {
-      entries = await import_promises2.default.readdir(dir, { withFileTypes: true });
+      entries = await import_promises3.default.readdir(dir, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -14074,7 +14539,7 @@ async function getSidecarBytes(repoDir) {
           continue;
         }
         if (typeof entry?.isFile === "function" && !entry.isFile()) continue;
-        const st = await import_promises2.default.stat(full);
+        const st = await import_promises3.default.stat(full);
         if (st.isDirectory()) stack.push(full);
         else if (st.isFile()) total += st.size;
       } catch {
@@ -14092,6 +14557,116 @@ async function getHistoryCommitCount(repoDir) {
     return 0;
   }
 }
+var GIT_INITIALIZATION_LOCK = ".astra-init.lock";
+function gitInitializationLockPath(repoDir) {
+  return import_path3.default.join(repoDir, GIT_INITIALIZATION_LOCK);
+}
+function gitInitializationIncompleteError(repoDir) {
+  return Object.assign(new Error(`History initialization is incomplete at ${repoDir}.`), {
+    code: "E_STATE",
+    remedy: "Stop other ASTra processes using this document, inspect the history directory, then run `astra history <file> --init` to record a baseline."
+  });
+}
+async function gitInitializationLockExists(repoDir) {
+  const file = gitInitializationLockPath(repoDir);
+  try {
+    const st = await import_promises3.default.lstat(file);
+    if (!st.isFile() || st.isSymbolicLink()) throw Object.assign(new Error(`Unsafe history initialization lock: ${file}`), { code: "E_SANDBOX" });
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+async function describeInitializationLock(file) {
+  let record = {};
+  try {
+    const st = await import_promises3.default.lstat(file);
+    if (st.isFile() && !st.isSymbolicLink() && st.size <= 4096) record = JSON.parse(await import_promises3.default.readFile(file, "utf8"));
+  } catch {
+  }
+  const pid = typeof record.pid === "number" && Number.isInteger(record.pid) && record.pid > 0 ? record.pid : void 0;
+  const hostname = typeof record.hostname === "string" ? record.hostname.slice(0, 255) : void 0;
+  const started = typeof record.startedAt === "string" ? ` since ${record.startedAt.slice(0, 40)}` : "";
+  if (pid === void 0) return `the lock does not record its owner${started}; cannot tell whether an initializer is still running`;
+  if (hostname === void 0) return `owner pid ${pid}, host not recorded${started}; cannot tell whether it is still running`;
+  if (hostname !== import_os.default.hostname()) return `owner pid ${pid} on host ${hostname}${started}; this host is ${import_os.default.hostname()}, cannot tell whether it is still running`;
+  try {
+    process.kill(pid, 0);
+    return `owner pid ${pid} on this host${started}; that process is running`;
+  } catch (error) {
+    if (error?.code === "EPERM") return `owner pid ${pid} on this host${started}; that process is running`;
+    if (error?.code === "ESRCH") return `owner pid ${pid} on this host${started}; that process was not found (this alone does not prove the lock is stale)`;
+    return `owner pid ${pid} on this host${started}; cannot tell whether it is still running`;
+  }
+}
+async function gitInitializationConflictError(file) {
+  return Object.assign(new Error(`Another or interrupted ASTra history initialization is marked at ${file} (${await describeInitializationLock(file)}).`), {
+    code: "E_CONFLICT",
+    remedy: `Do not delete the lock while any ASTra process (an agent, a pipeline or a CLI run) may be using this document. Once you have made sure none is, delete ${file}; if the history then has no commits, run \`astra history <file> --init\`. ASTra never removes the lock itself.`
+  });
+}
+async function countCommitsStrict(repoDir) {
+  await assertUsableSidecarGit(repoDir);
+  try {
+    return (await import_isomorphic_git.default.log({ fs: import_fs4.default, dir: repoDir })).length;
+  } catch (error) {
+    if (await isUnbornHistory(repoDir)) return 0;
+    throw error;
+  }
+}
+async function assertGitHistoryReady(repoDir) {
+  await assertNoGitInitializationInProgress(repoDir);
+  if (await countCommitsStrict(repoDir) === 0) throw gitInitializationIncompleteError(repoDir);
+}
+async function assertNoGitInitializationInProgress(repoDir) {
+  if (await gitInitializationLockExists(repoDir)) throw await gitInitializationConflictError(gitInitializationLockPath(repoDir));
+}
+async function assertHistoryReadyForWrite(docPath) {
+  const repoDir = getRepoDir(docPath);
+  await assertNoGitInitializationInProgress(repoDir);
+  if (import_fs4.default.existsSync(import_path3.default.join(repoDir, ".git"))) await assertGitHistoryReady(repoDir);
+}
+async function withGitInitializationLock(repoDir, run) {
+  const file = gitInitializationLockPath(repoDir);
+  assertWriteTargetNoSymlink(file);
+  const token = import_crypto4.default.randomUUID();
+  let handle;
+  try {
+    handle = await import_promises3.default.open(file, import_fs4.default.constants.O_WRONLY | import_fs4.default.constants.O_CREAT | import_fs4.default.constants.O_EXCL | import_fs4.default.constants.O_NOFOLLOW, 384);
+  } catch (error) {
+    if (error?.code === "EEXIST") throw await gitInitializationConflictError(file);
+    throw error;
+  }
+  let primaryError;
+  let result;
+  try {
+    await handle.writeFile(JSON.stringify({ version: 2, pid: process.pid, hostname: import_os.default.hostname(), token, startedAt: (/* @__PURE__ */ new Date()).toISOString() }));
+    await handle.sync();
+    result = await run();
+  } catch (error) {
+    primaryError = error;
+  }
+  await handle.close().catch(() => void 0);
+  let cleanupError;
+  try {
+    const current = JSON.parse(await import_promises3.default.readFile(file, "utf8"));
+    if (current.token !== token) throw Object.assign(new Error(`History initialization lock ownership changed; left in place: ${file}`), { code: "E_CONFLICT" });
+    await import_promises3.default.unlink(file);
+  } catch (error) {
+    cleanupError = error;
+  }
+  if (cleanupError && cleanupError?.code !== "ENOENT") {
+    if (primaryError) {
+      const cause = primaryError instanceof Error ? primaryError.message : String(primaryError);
+      throw Object.assign(new Error(`${cause}; initialization lock cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`), { code: "E_IO", lockPath: file });
+    }
+    throw Object.assign(new Error(`History initialization lock cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`), { code: "E_IO", lockPath: file });
+  }
+  if (cleanupError && !primaryError) throw Object.assign(new Error(`History initialization finished, but its lock file disappeared while it ran: ${file}. Another process or a cleaner may have removed it, so exclusivity is not guaranteed for this run. Inspect the history with \`astra history <file>\` before relying on it.`), { code: "E_CONFLICT" });
+  if (primaryError) throw primaryError;
+  return result;
+}
 var SIDECAR_TOMBSTONE_FILENAME = ".astra-tombstones.json";
 var sidecarRegenWarnings = /* @__PURE__ */ new Map();
 function resolveDocIdentity(target) {
@@ -14211,7 +14786,7 @@ async function checkSidecarTombstone(target, repoDir) {
   const key = import_path3.default.resolve(repoDir);
   let hasGit = false;
   try {
-    hasGit = (await import_promises2.default.stat(import_path3.default.join(repoDir, ".git"))).isDirectory();
+    hasGit = (await import_promises3.default.stat(import_path3.default.join(repoDir, ".git"))).isDirectory();
   } catch {
     hasGit = false;
   }
@@ -14305,14 +14880,14 @@ async function assertUsableSidecarGit(repoDir) {
   const gitPath = import_path3.default.join(repoDir, ".git");
   let entry;
   try {
-    entry = await import_promises2.default.lstat(gitPath);
+    entry = await import_promises3.default.lstat(gitPath);
   } catch {
     return;
   }
   let usable = false;
   if (entry.isSymbolicLink()) {
     try {
-      usable = (await import_promises2.default.stat(gitPath)).isDirectory();
+      usable = (await import_promises3.default.stat(gitPath)).isDirectory();
     } catch {
       usable = false;
     }
@@ -14330,7 +14905,7 @@ async function assertUsableSidecarGit(repoDir) {
 async function ensureAstraGitRepo(target) {
   const repoDir = isRepoDirTarget(target) ? target : getRepoDir(target);
   await assertUsableSidecarGit(repoDir);
-  await import_promises2.default.mkdir(repoDir, { recursive: true, mode: 448 });
+  await import_promises3.default.mkdir(repoDir, { recursive: true, mode: 448 });
   if (process.platform !== "win32") {
     await chmod0700BestEffort(repoDir);
     const parent = import_path3.default.dirname(repoDir);
@@ -14346,17 +14921,44 @@ async function ensureAstraGitRepo(target) {
   }
   return repoDir;
 }
-async function initAstraRepo(docPath, initialXml, extraFiles) {
+async function initAstraRepo(docPath, initialXml, extraFiles, originalBytes) {
   const repoDir = await ensureAstraGitRepo(docPath);
-  await import_isomorphic_git.default.init({ fs: import_fs4.default, dir: repoDir });
-  await writeAndAdd(repoDir, "document.xml", initialXml);
-  const writtenParts = await writeSnapshotParts(repoDir, extraFiles);
-  await applySnapshotMarker(repoDir, await snapshotIsProvenComplete(repoDir, extraFiles, writtenParts));
-  await import_isomorphic_git.default.commit({
-    fs: import_fs4.default,
-    dir: repoDir,
-    author: { name: "ASTra", email: "astra@attentionform.com" },
-    message: "Initial state"
+  await withGitInitializationLock(repoDir, async () => {
+    await import_isomorphic_git.default.init({ fs: import_fs4.default, dir: repoDir });
+    let commits;
+    try {
+      commits = await import_isomorphic_git.default.log({ fs: import_fs4.default, dir: repoDir });
+    } catch (error) {
+      if (!await isUnbornHistory(repoDir)) throw error;
+      commits = [];
+    }
+    if (commits.length > 0) {
+      throw Object.assign(new Error(`History is already initialized at ${repoDir}.`), { code: "E_CONFLICT" });
+    }
+    await clearUncommittedPackageParts(repoDir);
+    if (originalBytes) {
+      const existing = await getOriginalInfo(import_path3.default.resolve(docPath));
+      if (existing.available && existing.sha256 !== originalSha256(originalBytes)) {
+        const snapshotPath = import_path3.default.join(repoDir, ".git", "astra-original", "original.snapshot");
+        throw Object.assign(new Error(
+          `History initialization refused: an interrupted earlier initialization left a retained original (sha256 ${existing.sha256}) that differs from this file (sha256 ${originalSha256(originalBytes)}), and no history was recorded.`
+        ), {
+          code: "E_CONFLICT",
+          reason: "original-mismatch",
+          remedy: `Nothing was changed. The retained original may be the only copy of the earlier document: keep ${snapshotPath} (copy or rename it, do not delete it; \`astra history <file> --export-original <out>\` can still write its bytes to a new file), then run \`astra history <file> --init\` again once it is out of the way.`
+        });
+      }
+    }
+    await captureOriginal(import_path3.default.resolve(docPath), originalBytes);
+    await writeAndAdd(repoDir, "document.xml", initialXml);
+    const writtenParts = await writeSnapshotParts(repoDir, extraFiles);
+    await applySnapshotMarker(repoDir, await snapshotIsProvenComplete(repoDir, extraFiles, writtenParts));
+    await import_isomorphic_git.default.commit({
+      fs: import_fs4.default,
+      dir: repoDir,
+      author: { name: "ASTra", email: "astra@attentionform.com" },
+      message: "Initial state"
+    });
   });
   try {
     await checkSidecarTombstone(docPath, repoDir);
@@ -14368,6 +14970,7 @@ async function commitChange(docPath, xmlContent, message, extraFiles, deletedFil
   const maxCommits = resolveHistoryMaxCommits(limits?.maxCommits);
   const maxSidecarBytes = resolveHistoryMaxSidecarBytes(limits?.maxSidecarBytes);
   const repoDir = await ensureAstraGitRepo(docPath);
+  await assertGitHistoryReady(repoDir);
   const existingCommits = await getHistoryCommitCount(repoDir);
   if (existingCommits + 1 > maxCommits) {
     throw Object.assign(
@@ -14446,7 +15049,7 @@ async function commitChange(docPath, xmlContent, message, extraFiles, deletedFil
       if (isTraversalName(rel)) continue;
       const fullPath = import_path3.default.join(repoDir, rel);
       try {
-        await import_promises2.default.unlink(fullPath);
+        await import_promises3.default.unlink(fullPath);
       } catch {
       }
       try {
@@ -14469,8 +15072,27 @@ async function commitChange(docPath, xmlContent, message, extraFiles, deletedFil
   }
   return sha;
 }
+async function getHistoryInitializationState(docPath) {
+  const repoDir = getRepoDir(docPath);
+  try {
+    if (await gitInitializationLockExists(repoDir)) {
+      return { state: "in-progress", detail: "Another ASTra process holds the history initialization lock (or it was interrupted)." };
+    }
+    if (!import_fs4.default.existsSync(import_path3.default.join(repoDir, ".git"))) return { state: "absent" };
+    await assertUsableSidecarGit(repoDir);
+    const commits = await import_isomorphic_git.default.log({ fs: import_fs4.default, dir: repoDir });
+    if (commits.length === 0) return { state: "incomplete", detail: "History initialization is incomplete: no commit was recorded." };
+    const root = commits[commits.length - 1];
+    const initial = await checkoutCommit(docPath, root.oid);
+    if (!initial.complete) return { state: "incomplete", detail: "The first history commit is not a complete package snapshot." };
+    return { state: "complete" };
+  } catch (error) {
+    return { state: "incomplete", detail: error instanceof Error ? error.message : String(error) };
+  }
+}
 async function getHistory(docPath) {
   const repoDir = getRepoDir(docPath);
+  await assertNoGitInitializationInProgress(repoDir);
   await assertUsableSidecarGit(repoDir);
   let commits;
   try {
@@ -14513,7 +15135,7 @@ async function listRepoPaths(repoDir) {
   async function walk(dir, relBase) {
     let entries = [];
     try {
-      entries = await import_promises2.default.readdir(dir, { withFileTypes: true });
+      entries = await import_promises3.default.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -14944,6 +15566,89 @@ function assertNoCellAddress(action, fields, ast) {
 // ../engine/src/operations/table.ts
 var import_xmldom12 = require("@xmldom/xmldom");
 var crypto3 = __toESM(require("crypto"));
+
+// ../engine/src/operations/colour.ts
+var COLOUR_NAMES = {
+  red: "FF0000",
+  green: "008000",
+  blue: "0000FF",
+  black: "000000",
+  white: "FFFFFF",
+  yellow: "FFFF00",
+  orange: "FFA500",
+  gray: "808080",
+  grey: "808080",
+  purple: "800080"
+};
+var HEX = /^#?([0-9A-Fa-f]{6})$/;
+function normalizeColour(input, options = {}) {
+  if (typeof input !== "string") return void 0;
+  const text2 = input.trim();
+  const hex = HEX.exec(text2);
+  if (hex) return hex[1];
+  const lower = text2.toLowerCase();
+  if (options.allowAuto && lower === "auto") return "auto";
+  return Object.prototype.hasOwnProperty.call(COLOUR_NAMES, lower) ? COLOUR_NAMES[lower] : void 0;
+}
+function resolveColourInput(input, options = {}) {
+  const value = normalizeColour(input, options);
+  return value === void 0 ? input : value;
+}
+function colourForms(options = {}) {
+  const names = Object.keys(COLOUR_NAMES).join(", ");
+  return `6 hex digits such as FF0000 (optionally with #), ${options.allowAuto ? '"auto", ' : ""}or one of: ${names}`;
+}
+function colourError(field, value, options = {}) {
+  return new Error(
+    `E_VALIDATION: ${field} must be ${colourForms(options)}. Got ${JSON.stringify(value)}. Remedy: pass ${field} as hex, for example "FF0000", or a colour name such as "red".`
+  );
+}
+function requireColour(field, input, options = {}) {
+  const value = normalizeColour(input, options);
+  if (value === void 0) throw colourError(field, input, options);
+  return value;
+}
+var BORDER_WIDTH_MIN = 1;
+var BORDER_WIDTH_MAX = 96;
+function requireBorderSize(field, input, fallback) {
+  if (input === void 0) return fallback;
+  const n = typeof input === "number" ? input : typeof input === "string" && input.trim() !== "" ? Number(input) : Number.NaN;
+  if (!Number.isInteger(n) || n < BORDER_WIDTH_MIN || n > BORDER_WIDTH_MAX) {
+    throw new Error(
+      `E_VALIDATION: ${field}: border width must be a whole number of eighths of a point from ${BORDER_WIDTH_MIN} to ${BORDER_WIDTH_MAX} (got ${JSON.stringify(input)}). Remedy: pass sz:4 for a 0.5 pt line, sz:8 for 1 pt, sz:96 for 12 pt (the widest).`
+    );
+  }
+  return n;
+}
+function colourPattern(options = {}) {
+  const ci = (word) => [...word].map((c) => `[${c.toLowerCase()}${c.toUpperCase()}]`).join("");
+  const words = [...Object.keys(COLOUR_NAMES), ...options.allowAuto ? ["auto"] : []].map(ci);
+  return `^\\s*(#?[0-9A-Fa-f]{6}|${words.join("|")})\\s*$`;
+}
+function colourDescription(options = {}) {
+  return `A colour: ${colourForms(options)}.`;
+}
+var HIGHLIGHT_COLOURS = [
+  "yellow",
+  "green",
+  "cyan",
+  "magenta",
+  "blue",
+  "red",
+  "darkBlue",
+  "darkCyan",
+  "darkGreen",
+  "darkMagenta",
+  "darkRed",
+  "darkYellow",
+  "darkGray",
+  "lightGray",
+  "black",
+  "white",
+  "none"
+];
+
+// ../engine/src/operations/table.ts
 function isTableReproducible() {
   try {
     return resolveReproducibleMode(void 0);
@@ -15343,13 +16048,13 @@ async function executeTable(opIn, ast, guide) {
     afterIndex: Number(pick("afterIndex", op.afterIndex) ?? rows.length - 1),
     cells: cellsArray,
     index: Number(pick("index", op.index) ?? 0),
-    fill: String(pick("fill", op.fill) ?? "F7F9FC").replace(/^#/, ""),
-    headerFill: pick("headerFill", op.headerFill)?.replace(/^#/, ""),
+    fill: String(resolveColourInput(pick("fill", op.fill) ?? "F7F9FC")).replace(/^#/, ""),
+    headerFill: resolveColourInput(pick("headerFill", op.headerFill))?.replace(/^#/, ""),
     zebra: pick("zebra", op.zebra),
     // Explicit header/single-cell text color for setShading/setCellShading
     // (flat or nested in params; wins over the guide per the precedence
     // invariant). Validated below before any mutation.
-    textColor: pick("textColor", op.textColor)
+    textColor: resolveColourInput(pick("textColor", op.textColor))
   };
   const warnings = [];
   const revisionIds = [];
@@ -15363,7 +16068,7 @@ async function executeTable(opIn, ast, guide) {
     const normText = String(P.textColor).replace(/^#/, "");
     if (!/^[0-9A-Fa-f]{6}$/.test(normText)) {
       throw new Error(
-        `E_VALIDATION: ${resolvedOp} requires textColor as a 6-digit hex color with optional leading '#' (got textColor='${String(P.textColor)}'). Remedy: pass textColor as 6 hex digits, e.g. textColor:'FFFFFF'.`
+        `E_VALIDATION: ${resolvedOp} requires textColor as ${colourForms()} (got textColor='${String(P.textColor)}'). Remedy: pass textColor as 6 hex digits, e.g. textColor:'FFFFFF', or a colour name such as 'white'.`
       );
     }
     explicitTextColor = normText.toUpperCase();
@@ -15945,16 +16650,8 @@ async function executeTable(opIn, ast, guide) {
     }
     case "setBorder": {
       const borderType = String(pick("border", void 0) || "all");
-      const color = String(pick("color", void 0) || "D1D5DB").replace(/^#/, "");
-      const rawSz = pick("sz", void 0) || raw.size || 4;
-      const szNum = Number(rawSz);
-      if (!Number.isInteger(szNum) || szNum < 1) {
-        throw toError(
-          "E_VALIDATION",
-          `setBorder sz must be a whole number of eighths of a point (got ${String(rawSz)}).`,
-          "Pass sz:4 for a 0.5 pt line or sz:8 for 1 pt."
-        );
-      }
+      const color = requireColour("color", pick("color", void 0) || "D1D5DB", { allowAuto: true });
+      const szNum = requireBorderSize("setBorder sz", pick("sz", void 0) ?? raw.size, 4);
       const sz = String(szNum);
       const val = String(raw.val || "single");
       let tblPr = directChildren5(tblEl, "w:tblPr")[0];
@@ -16212,7 +16909,7 @@ async function executeTable(opIn, ast, guide) {
         );
       }
       const tc = resolveTableCell(tr, colIndex, "setCellShading");
-      const fillInput = raw.fill ?? op.fill;
+      const fillInput = resolveColourInput(raw.fill ?? op.fill);
       if (fillInput === void 0) {
         throw new Error(
           `E_VALIDATION: setCellShading requires fill (got no fill). Remedy: pass fill as 6 hex digits without '#', e.g. fill:'FF0000'.`
@@ -16221,7 +16918,7 @@ async function executeTable(opIn, ast, guide) {
       const fill = String(fillInput).replace(/^#/, "");
       if (!/^[0-9A-Fa-f]{6}$/.test(fill)) {
         throw new Error(
-          `E_VALIDATION: setCellShading requires a 6-digit hex fill with optional leading '#' (got fill='${String(fillInput)}'). Remedy: pass fill as 6 hex digits, e.g. fill:'FF0000' or fill:'#FF0000'.`
+          `E_VALIDATION: setCellShading requires a fill that is ${colourForms()} (got fill='${String(fillInput)}'). Remedy: pass fill as 6 hex digits, e.g. fill:'FF0000' or fill:'#FF0000', or a colour name such as 'red'.`
         );
       }
       const normFill = fill.toUpperCase();
@@ -16530,19 +17227,20 @@ async function executeTable(opIn, ast, guide) {
       break;
     }
     case "setCellTextColor": {
-      const colorInput = raw.color ?? op.color ?? raw.textColor ?? op.textColor;
+      const colorInput = resolveColourInput(raw.color ?? op.color ?? raw.textColor ?? op.textColor, { allowAuto: true });
       if (colorInput === void 0 || colorInput === null || String(colorInput).trim() === "") {
         throw new Error(
           `E_VALIDATION: setCellTextColor requires color (got no color). Remedy: pass color as 6 hex digits without '#', e.g. color:'FFFFFF' for white header text.`
         );
       }
       const color = String(colorInput).replace(/^#/, "");
-      if (!/^[0-9A-Fa-f]{6}$/.test(color)) {
+      const autoColor = color === "auto";
+      if (!autoColor && !/^[0-9A-Fa-f]{6}$/.test(color)) {
         throw new Error(
-          `E_VALIDATION: setCellTextColor requires a 6-digit hex color with optional leading '#' (got color='${String(colorInput)}'). Remedy: pass color as 6 hex digits, e.g. color:'FFFFFF' or color:'#FFFFFF'.`
+          `E_VALIDATION: setCellTextColor requires ${colourForms({ allowAuto: true })} (got color='${String(colorInput)}'). Remedy: pass color as 6 hex digits, e.g. color:'FFFFFF' or color:'#FFFFFF', or a colour name such as 'white'.`
         );
       }
-      const normColor = color.toUpperCase();
+      const normColor = autoColor ? "auto" : color.toUpperCase();
       const cellFillOf2 = (tc) => {
         const tcPr = directChildren5(tc, "w:tcPr")[0];
         const shd = tcPr ? directChildren5(tcPr, "w:shd")[0] : void 0;
@@ -16581,7 +17279,7 @@ async function executeTable(opIn, ast, guide) {
             }
           }
         }
-        warnIfLowContrast(warnings, warnedContrastPairs, cellFillOf2(tc), normColor, `cell (${rIdx + 1},${cIdx + 1}) of table '${tableNode.id}'`);
+        if (!autoColor) warnIfLowContrast(warnings, warnedContrastPairs, cellFillOf2(tc), normColor, `cell (${rIdx + 1},${cIdx + 1}) of table '${tableNode.id}'`);
       };
       const tRowSrc = rowIndexAlias(raw, op);
       const tColSrc = colIndexAlias(raw, op);
@@ -17764,6 +18462,8 @@ function generateEmbeddedWorkbook(seriesList, categories, scatterSeriesXValues)
 var DEFAULT_SERIES_PALETTE = ["0066CC", "10B981", "F59E0B", "EF4444", "8B5CF6", "06B6D4", "EC4899", "84CC16"];
 function defaultSeriesColor(color, seriesIdx) {
   if (color) {
+    const named = normalizeColour(color);
+    if (named !== void 0) return named;
     const raw = color.replace(/^#/, "");
     if (isShorthandHex(raw)) return expandShorthandHex(raw);
     return raw;
@@ -18994,7 +19694,7 @@ function sameStrings(a, b) {
 }
 function normalizeHex(value) {
   if (typeof value !== "string") return void 0;
-  const raw = value.replace(/^#/, "").trim();
+  const raw = (normalizeColour(value) ?? value.replace(/^#/, "")).trim();
   return raw.length > 0 ? raw.toUpperCase() : void 0;
 }
 function isNumericText(value) {
@@ -19237,7 +19937,7 @@ function patchSeriesList(xml, req, patches, scope) {
     const haveColor = normalizeHex(existing?.color);
     if (wantColor !== void 0 && wantColor !== haveColor) {
       const lineSeries = combo ? (patch.chartType ?? existing?.chartType) === "line" : baseLineSeries;
-      serXml = patchSeriesColor(serXml, patch.color.replace(/^#/, ""), lineSeries, scope);
+      serXml = patchSeriesColor(serXml, normalizeColour(patch.color) ?? patch.color.replace(/^#/, ""), lineSeries, scope);
     }
     pieces.push(serXml);
     cursor = spans[i].end;
@@ -19746,7 +20446,7 @@ function withGuideSeriesColors(series, palette) {
   return series.map((s, i) => {
     const raw = typeof s?.color === "string" ? s.color.replace(/^#/, "") : "";
     const existing = isShorthandHex(raw) ? expandShorthandHex(raw) : raw;
-    if (/^[0-9A-Fa-f]{6}$/.test(existing)) return s;
+    if (/^[0-9A-Fa-f]{6}$/.test(existing) || typeof s?.color === "string" && normalizeColour(s.color) !== void 0) return s;
     return { ...s, color: guidePaletteColor(palette, i, taken) };
   });
 }
@@ -21023,10 +21723,15 @@ var twipsOrPoints = import_zod2.z.union([
   import_zod2.z.number().finite(),
   import_zod2.z.string().regex(FONT_SIZE_PT_REGEX, 'must be a number of twips (20 per point) or a string such as "12pt"')
 ]).describe('Twips (20 per point, so 240 is 12 pt), or a string in points such as "12pt".');
+var MAX_FONT_HALF_POINTS = 3276;
 var fontSizeOrSzSchema = import_zod2.z.union([
-  import_zod2.z.number().finite().nonnegative(),
-  import_zod2.z.string().regex(FONT_SIZE_PT_REGEX, 'Font size string must match format like "12pt" or "10.5pt"')
-]);
+  import_zod2.z.number().finite().nonnegative().max(MAX_FONT_HALF_POINTS, "font size must be at most 1638 pt (3276 half-points)"),
+  import_zod2.z.string().regex(FONT_SIZE_PT_REGEX, 'Font size string must match format like "12pt" or "10.5pt"').refine((v) => (parseFontSize(v) ?? 0) <= MAX_FONT_HALF_POINTS, "font size must be at most 1638 pt (3276 half-points)")
+]).describe('Font size: a number of half-points (24 is 12 pt) or a string in points such as "12pt"; at most 1638 pt.');
+var borderSizeSchema = import_zod2.z.number("border width is a whole number of eighths of a point, e.g. 8 for 1 pt").int("border width is a whole number of eighths of a point, e.g. 8 for 1 pt").min(BORDER_WIDTH_MIN, "border width must be at least 1 (an eighth of a point)").max(BORDER_WIDTH_MAX, "border width must be at most 96 (12 pt)").describe("Border width in eighths of a point (8 is 1 pt), a whole number from 1 to 96.");
+function colourField(options = {}, max = 32) {
+  return import_zod2.z.string().max(max).regex(new RegExp(colourPattern(options)), `color must be ${colourForms(options)}`).describe(colourDescription(options));
+}
 var styleProperties = import_zod2.z.object({
   bold: import_zod2.z.boolean().optional(),
   italic: import_zod2.z.boolean().optional(),
@@ -21035,11 +21740,11 @@ var styleProperties = import_zod2.z.object({
   doubleStrikethrough: import_zod2.z.boolean().optional(),
   vertAlign: import_zod2.z.enum(["superscript", "subscript", "baseline"]).optional(),
   alignment: import_zod2.z.enum(["left", "center", "right", "both", "justify"]).optional(),
-  color: import_zod2.z.string().max(32).optional(),
+  color: colourField({ allowAuto: true }).optional(),
   fontSize: fontSizeOrSzSchema.optional(),
   sz: fontSizeOrSzSchema.optional(),
   fontFamily: import_zod2.z.string().max(128).optional(),
-  highlight: import_zod2.z.string().max(32).optional(),
+  highlight: import_zod2.z.enum(HIGHLIGHT_COLOURS).optional(),
   lineSpacing: import_zod2.z.number().optional(),
   spacingBefore: twipsOrPoints.optional(),
   spacingAfter: twipsOrPoints.optional(),
@@ -21057,7 +21762,7 @@ var styleProperties = import_zod2.z.object({
 var insertChartSeries = import_zod2.z.object({
   name: import_zod2.z.string().max(500),
   values: import_zod2.z.array(import_zod2.z.number()).max(1e3),
-  color: import_zod2.z.string().max(16).optional()
+  color: import_zod2.z.string().max(16).describe("Series colour: 6 hex digits, optionally with #, or one of: red, green, blue, black, white, yellow, orange, gray, grey, purple. Any other value is replaced by the style guide palette colour when there is one.").optional()
 }).catchall(import_zod2.z.unknown());
 var insertWrapMode = import_zod2.z.enum(["inline", "square", "tight", "through", "topAndBottom", "behindText", "inFrontOfText"]);
 var tableCellPadding = import_zod2.z.object({
@@ -21094,7 +21799,7 @@ var insertOp = import_zod2.z.object({
   headers: import_zod2.z.array(import_zod2.z.string().max(1e4)).max(100).optional(),
   rows: import_zod2.z.array(import_zod2.z.array(import_zod2.z.string().max(1e4)).max(100)).max(1e3).optional(),
   cellPadding: import_zod2.z.union([import_zod2.z.number().int().nonnegative(), tableCellPadding]).optional(),
-  color: import_zod2.z.string().max(16).optional(),
+  color: colourField({ allowAuto: true }).optional(),
   thickness: import_zod2.z.number().optional(),
   lineStyle: import_zod2.z.string().max(32).optional(),
   spacingBefore: twipsOrPoints.optional(),
@@ -21181,11 +21886,11 @@ var styleOp = import_zod2.z.object({
   doubleStrikethrough: import_zod2.z.boolean().optional(),
   vertAlign: import_zod2.z.enum(["superscript", "subscript", "baseline"]).optional(),
   alignment: import_zod2.z.enum(["left", "center", "right", "both", "justify"]).optional(),
-  color: import_zod2.z.string().max(32).optional(),
+  color: colourField({ allowAuto: true }).optional(),
   fontSize: fontSizeOrSzSchema.optional(),
   sz: fontSizeOrSzSchema.optional(),
   fontFamily: import_zod2.z.string().max(128).optional(),
-  highlight: import_zod2.z.string().max(32).optional(),
+  highlight: import_zod2.z.enum(HIGHLIGHT_COLOURS).optional(),
   lineSpacing: import_zod2.z.number().optional(),
   spacingBefore: twipsOrPoints.optional(),
   spacingAfter: twipsOrPoints.optional(),
@@ -21262,20 +21967,20 @@ var tableOp = import_zod2.z.object({
   cells: import_zod2.z.array(import_zod2.z.string().max(1e5)).max(100).describe("addRow: the text of the new cells, one entry per column from the first (also accepted inside params).").optional(),
   afterIndex: import_zod2.z.number().int().describe("addRow: insert after this row number; addColumn: after this column number (counting from 1; default the last).").optional(),
   index: import_zod2.z.number().int().describe("deleteRow/deleteColumn: the row or column number to remove (counting from 1).").optional(),
-  fill: import_zod2.z.string().max(16).optional(),
-  headerFill: import_zod2.z.string().max(16).optional(),
+  fill: colourField({}, 32).optional(),
+  headerFill: colourField({}, 32).optional(),
   zebra: import_zod2.z.boolean().optional(),
   // Explicit header/single-cell text color for setShading/setCellShading
   // (flat or params-nested; wins over the guide per the precedence invariant).
-  textColor: import_zod2.z.string().max(16).optional(),
+  textColor: colourField({}, 32).optional(),
   widths: import_zod2.z.array(import_zod2.z.number()).max(100).optional(),
   columnWidths: import_zod2.z.array(import_zod2.z.number()).max(100).optional(),
   width: import_zod2.z.number().int().positive().optional(),
   height: import_zod2.z.number().int().positive().optional(),
   rule: import_zod2.z.enum(["atLeast", "exact", "auto"]).optional(),
   border: import_zod2.z.string().max(32).optional(),
-  color: import_zod2.z.string().max(16).optional(),
-  sz: fontSizeOrSzSchema.optional(),
+  color: colourField({ allowAuto: true }).optional(),
+  sz: borderSizeSchema.optional(),
   vAlign: import_zod2.z.string().max(16).optional(),
   align: tableAlignmentSchema.optional(),
   alignment: tableAlignmentSchema.optional(),
@@ -21395,7 +22100,7 @@ function chartHoleSizeSchemaRemedy(detail) {
 var chartSeries = import_zod2.z.object({
   name: import_zod2.z.string().max(500),
   values: import_zod2.z.array(import_zod2.z.number()).max(1e3),
-  color: import_zod2.z.string().max(16).optional(),
+  color: import_zod2.z.string().max(16).describe("Series colour: 6 hex digits, optionally with #, or one of: red, green, blue, black, white, yellow, orange, gray, grey, purple. Any other value is replaced by the style guide palette colour when there is one.").optional(),
   chartType: import_zod2.z.enum(["column", "line"]).optional(),
   axis: import_zod2.z.enum(["primary", "secondary"]).optional()
 }).catchall(import_zod2.z.unknown());
@@ -21521,7 +22226,7 @@ var watermarkSizeSchema = import_zod2.z.union([import_zod2.z.number().finite().n
 var watermarkOp = import_zod2.z.object({
   action: import_zod2.z.literal("watermark"),
   text: import_zod2.z.string().max(500).optional(),
-  color: import_zod2.z.string().max(16).optional(),
+  color: import_zod2.z.string().max(16).describe("Watermark colour: 6 hex digits, optionally with #, or one of: red, green, blue, black, white, yellow, orange, gray, grey, purple. Any other value falls back to D1D5DB.").optional(),
   fontSize: watermarkSizeSchema.optional(),
   sz: watermarkSizeSchema.optional(),
   opacity: import_zod2.z.number().min(0).max(1).optional(),
@@ -21531,9 +22236,9 @@ var watermarkOp = import_zod2.z.object({
 var pageBorderOp = import_zod2.z.object({
   action: import_zod2.z.literal("pageBorder"),
   style: import_zod2.z.string().max(32).optional(),
-  sz: fontSizeOrSzSchema.optional(),
+  sz: borderSizeSchema.optional(),
   fontSize: fontSizeOrSzSchema.optional(),
-  color: import_zod2.z.string().max(16).optional(),
+  color: colourField({ allowAuto: true }).optional(),
   marginOffset: import_zod2.z.enum(["page", "text"]).optional(),
   sectionIndex: sectionNumber.optional(),
   expectedVersion
@@ -21871,6 +22576,32 @@ var KEY_WORDS = {
 };
 var MAX_KEYS_LISTED = 60;
 var cachedShapes;
+function subOperationValues(shape) {
+  for (const key of ["operation", "op"]) {
+    let field = shape[key];
+    for (let depth = 0; depth < 4 && field?.def; depth++) {
+      const values = field.def.entries;
+      if (values && typeof values === "object") return Object.keys(values);
+      field = field.def["innerType"] ?? field.def["in"] ?? field.def["out"];
+    }
+  }
+  return [];
+}
+var ACTION_VERBS = ["set", "add", "insert", "update", "edit", "create", "apply", "remove", "delete", "change", "make"];
+function verbPrefixCandidates(given, actions) {
+  const key = squash(given);
+  for (const verb of ACTION_VERBS) {
+    if (!key.startsWith(verb) || key.length - verb.length < 3) continue;
+    const rest = key.slice(verb.length);
+    const target = actions.find((a) => squash(a) === rest);
+    if (!target) continue;
+    const out = [target];
+    const verbAction = actions.find((a) => squash(a) === verb) ?? ACTION_WORDS[verb];
+    if (verbAction && actions.includes(verbAction) && verbAction !== target) out.push(verbAction);
+    return out;
+  }
+  return [];
+}
 function actionShapes() {
   if (cachedShapes) return cachedShapes;
   const shapes = [];
@@ -21878,7 +22609,10 @@ function actionShapes() {
   for (const option of options) {
     const literal = option.shape["action"]?.def?.values?.[0];
     if (typeof literal !== "string") continue;
-    shapes.push({ action: literal, keys: Object.keys(option.shape).filter((k) => k !== "action") });
+    const shape = { action: literal, keys: Object.keys(option.shape).filter((k) => k !== "action") };
+    const sub = subOperationValues(option.shape);
+    if (sub.length > 0) shape.subOperations = sub;
+    shapes.push(shape);
   }
   cachedShapes = shapes;
   return shapes;
@@ -21923,9 +22657,17 @@ function hintFor(operations, issue) {
     const given = op["action"];
     if (typeof given !== "string") return void 0;
     const actions = shapes.map((s) => s.action);
-    const near = closestNames(given, actions, ACTION_WORDS);
+    let near = closestNames(given, actions, ACTION_WORDS);
+    if (near.length === 0) near = verbPrefixCandidates(given, actions);
     const parts = [`${label}: "${given}" is not an action.`];
-    if (near.length > 0) parts.push(`Did you mean ${quoted(near)}?`);
+    if (near.length > 0) {
+      parts.push(`Did you mean ${near.map((n) => `"${n}"`).join(" or ")}?`);
+      const candidate = shapes.find((s) => s.action === near[0]);
+      if (candidate) {
+        parts.push(`Keys of "${candidate.action}": ${candidate.keys.slice(0, MAX_KEYS_LISTED).join(", ")}${candidate.keys.length > MAX_KEYS_LISTED ? ", ..." : ""}.`);
+        if (candidate.subOperations) parts.push(`Operations of "${candidate.action}": ${candidate.subOperations.join(", ")}.`);
+      }
+    }
     parts.push(`Actions: ${actions.join(", ")}.`);
     return parts.join(" ");
   }
@@ -22751,16 +23493,14 @@ function applyRunProps(doc, run, props) {
       vaEl.setAttribute("w:val", props.vertAlign);
     }
   }
-  if (props.color !== void 0 && props.color !== null) {
+  if (props.color !== void 0 && props.color !== null && String(props.color).trim() !== "") {
+    const hex = requireColour("color", props.color, { allowAuto: true });
     let colorEl = rPr.getElementsByTagName("w:color")[0];
     if (!colorEl) {
       colorEl = createWordElement(doc, "w:color");
       rPr.appendChild(colorEl);
     }
-    const hex = String(props.color).replace(/^#/, "").trim();
-    if (hex) {
-      colorEl.setAttribute("w:val", hex);
-    }
+    colorEl.setAttribute("w:val", hex);
   }
   const rawSz = props.sz !== void 0 ? props.sz : props.fontSize;
   if (rawSz !== void 0 && rawSz !== null) {
@@ -23276,9 +24016,9 @@ function executeStyle(op, ast) {
             pBdr.appendChild(el);
           }
           el.setAttribute("w:val", config.style || "single");
-          el.setAttribute("w:sz", String(config.sz ?? 12));
+          el.setAttribute("w:sz", String(requireBorderSize(`${side} border sz`, config.sz, 12)));
           el.setAttribute("w:space", "1");
-          el.setAttribute("w:color", (config.color || "CBD5E1").replace(/^#/, ""));
+          el.setAttribute("w:color", config.color ? requireColour("color", config.color, { allowAuto: true }) : "CBD5E1");
         };
         if (props.borderBox) {
           applyBdr("top", props.borderBox);
@@ -26277,7 +27017,7 @@ async function executeInsert(op, ast, parser2, guide, paraIdCache) {
     const pBdr = createWordElement(doc, "w:pBdr");
     const bottom = createWordElement(doc, "w:bottom");
     const lineStyle = op.lineStyle || "single";
-    const color = (op.color || "CBD5E1").replace(/^#/, "");
+    const color = op.color ? requireColour("color", op.color, { allowAuto: true }) : "CBD5E1";
     const thickness = op.thickness !== void 0 ? String(op.thickness) : "12";
     bottom.setAttribute("w:val", lineStyle);
     bottom.setAttribute("w:sz", thickness);
@@ -31025,7 +31765,7 @@ function executeEndnote(op, ast, parser2) {
 function executeWatermark(op, ast, parser2) {
   const rawText = (op.text || "CONFIDENTIAL").trim();
   const text2 = rawText.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
-  const color = /^[0-9A-Fa-f]{6}$/.test((op.color || "").replace(/^#/, "")) ? op.color.replace(/^#/, "") : "D1D5DB";
+  const color = normalizeColour(op.color) ?? "D1D5DB";
   const fontSize = op.fontSize || 60;
   const rotation = op.rotation !== void 0 ? op.rotation : 315;
   const watermarkXml = `<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
@@ -31143,8 +31883,8 @@ function executePageBorder(op, ast, parser2) {
       const pgBorders = upsertSectPrChild(sectPr, "w:pgBorders");
       pgBorders.setAttribute("w:offsetFrom", op.marginOffset || "page");
       const style = op.style || "single";
-      const sz = String(op.sz || 12);
-      const color = (op.color || "CBD5E1").replace(/^#/, "");
+      const sz = String(requireBorderSize("pageBorder sz", op.sz, 12));
+      const color = op.color ? requireColour("color", op.color, { allowAuto: true }) : "CBD5E1";
       ["top", "left", "bottom", "right"].forEach((side) => {
         let sideEl = pgBorders.getElementsByTagName(`w:${side}`)[0];
         if (!sideEl) {
@@ -31666,6 +32406,7 @@ async function executeMetadata(op, ast, parser2) {
 }
 
 // ../engine/src/operation-engine.ts
+var COMPOSE_ID_IN_MESSAGE = /\b(md\d*_\d{4,})\b/;
 var ENGINE_MAX_OPS = 500;
 var ENGINE_MAX_BYTES = 200 * 1024 * 1024;
 var EngineQuotaError = class extends Error {
@@ -32465,6 +33206,10 @@ var OperationEngine = class _OperationEngine {
     }
   }
   generateHint(op, errorMessage) {
+    const missing = errorMessage.includes("not found") && !errorMessage.includes("not found in node") ? COMPOSE_ID_IN_MESSAGE.exec(errorMessage) : null;
+    if (missing) {
+      return `"${missing[1]}" looks like an id from compose_document. It may be an id of a session that was closed and reopened, a mistyped id, or a node that was deleted. If the document was reopened, use the paragraph id from persistentIds in the compose response, find the text with search_content, or re-read ids with inspect_document. Table ids are renumbered by position (t_001...) after reopen.`;
+    }
     if (errorMessage.includes("not found") && !errorMessage.includes("not found in node")) {
       return `Check if the target node ID is correct. Node ids are session-scoped and go stale after reopen/edit; re-read ids via inspect_document; locate current text with search_content, or append without an id via anchor:end.`;
     }
@@ -34088,12 +34833,12 @@ $$` : `[Equation]
 // ../engine/src/toon.ts
 var TOON_DEFAULT_FIDELITY = "standard";
 function isToonFidelity(value) {
-  return value === "compact" || value === "standard" || value === "full";
+  return value === "outline" || value === "compact" || value === "standard" || value === "full";
 }
 function assertToonFidelity(value) {
   if (!isToonFidelity(value)) {
     throw new Error(
-      `Unknown TOON fidelity '${String(value)}'. Supported: compact|standard|full. Remedy: call toon({ fidelity: 'standard' }) for the default enriched outline, 'compact' for the minimal outline, or 'full' with a sectionId for rPr/pPr detail.`
+      `Unknown TOON fidelity '${String(value)}'. Supported: outline|compact|standard|full. Remedy: call toon({ fidelity: 'standard' }) for the default enriched outline, 'compact' for the minimal table, 'outline' for headings only, or 'full' with a sectionId for rPr/pPr detail.`
     );
   }
 }
@@ -34605,6 +35350,15 @@ function resolveSectionScope(sections, sectionId) {
   if (sectionId.length >= MIN_NODE_ID_PREFIX_LENGTH) return pick((id) => id.startsWith(sectionId));
   return [];
 }
+var OUTLINE_HEADERS = ["ID", "L", "Style", "Text", "Section"];
+var OUTLINE_DEFAULT_TEXT_LENGTH = 80;
+function escapeOutlineCell(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+}
+function escapeOutlinePathPart(value) {
+  return escapeOutlineCell(value).replace(/>/g, "\\>");
+}
+var OUTLINE_PATH_PART_LENGTH = 60;
 var ToonGenerator = class _ToonGenerator {
   cache = /* @__PURE__ */ new Map();
   checksumCache = /* @__PURE__ */ new Map();
@@ -34722,7 +35476,10 @@ var ToonGenerator = class _ToonGenerator {
     }
     const sectionPaths = this.buildSectionPaths(ast.sections);
     const maxLen = options?.maxTextLength;
-    for (const section of sectionsToProcess) {
+    if (fidelity === "outline") {
+      rows.push(...this.buildOutlineRows(ast, sectionsToProcess, maxLen ?? OUTLINE_DEFAULT_TEXT_LENGTH));
+    }
+    for (const section of fidelity === "outline" ? [] : sectionsToProcess) {
       const sectionPath = sectionPaths.get(section.id) || "Root";
       const sectionHeader = section.heading?.text || "";
       for (const node of section.nodes) {
@@ -34762,7 +35519,7 @@ var ToonGenerator = class _ToonGenerator {
         rows.push(row);
       }
     }
-    const headers = fidelity === "full" ? ["ID", "V", "Path", "Header", "Style", "Text", "Flags", "Detail"] : ["ID", "V", "Path", "Header", "Style", "Text", "Flags"];
+    const headers = fidelity === "outline" ? [...OUTLINE_HEADERS] : fidelity === "full" ? ["ID", "V", "Path", "Header", "Style", "Text", "Flags", "Detail"] : ["ID", "V", "Path", "Header", "Style", "Text", "Flags"];
     const table = {
       headers,
       rows,
@@ -34821,6 +35578,20 @@ var ToonGenerator = class _ToonGenerator {
         if (fidelity !== "compact") {
           combined += `${fingerprintFmt(n)};`;
         }
+        if (fidelity === "outline") {
+          combined += `os${n.type === "paragraph" ? ownParagraphStyleId(n.xml) ?? "-" : "-"};`;
+        }
+      }
+    }
+    if (fidelity === "outline") {
+      combined += "oh:";
+      for (const sec of ast.sections) {
+        for (const n of sec.nodes) {
+          const h = headingOfNode(n);
+          if (!h) continue;
+          const t = (n.metadata.text ?? "").trim();
+          combined += `${n.id}:${h.level}:${h.style}:${t.length}:${t.slice(0, OUTLINE_PATH_PART_LENGTH + 4)};`;
+        }
       }
     }
     try {
@@ -34852,6 +35623,42 @@ var ToonGenerator = class _ToonGenerator {
     }
     return combined;
   }
+  /**
+   * The `outline` tier: one row per heading, in document order. A heading is a top-level body paragraph whose own
+   * `w:pStyle` is a heading style (`headingLevelOfStyleId`), the rule the structural summary uses. Section is the
+   * chain of headings above it, nested by level, and is built over the whole document so a `sectionId` scope still
+   * shows the real parents. `scope` limits which headings are listed.
+   */
+  buildOutlineRows(ast, scope, maxLen) {
+    const inScope = /* @__PURE__ */ new Set();
+    for (const sec of scope) for (const n of sec.nodes) inScope.add(n.id);
+    const cut = (text2, max) => max > 0 && text2.length > max ? `${text2.substring(0, max)}...` : text2;
+    const stack = [];
+    const rows = [];
+    for (const sec of ast.sections) {
+      for (const node of sec.nodes) {
+        const heading = headingOfNode(node);
+        if (!heading) continue;
+        const { style, level } = heading;
+        while (stack.length > 0 && stack[stack.length - 1].level >= level) stack.pop();
+        const text2 = node.metadata.text.trim() || this.generatePlaceholderText(node);
+        if (inScope.has(node.id)) {
+          rows.push({
+            id: node.id,
+            version: node.version,
+            path: stack.map((h) => escapeOutlinePathPart(cut(h.text, OUTLINE_PATH_PART_LENGTH))).join(" > "),
+            header: "",
+            style,
+            text: cut(text2, maxLen),
+            flags: "",
+            level
+          });
+        }
+        stack.push({ level, text: text2 });
+      }
+    }
+    return rows;
+  }
   buildSectionPaths(sections) {
     const paths = /* @__PURE__ */ new Map();
     const hierarchy = [];
@@ -34988,7 +35795,58 @@ var ToonGenerator = class _ToonGenerator {
     if (node.metadata.listLevel !== void 0) flags.push(`[L${node.metadata.listLevel + 1}]`);
     return flags.join(" ");
   }
+  /**
+   * One rendered row, wrapped to `rawWidth` when it is a usable width. Text is the cell at `textPos`; only it may
+   * wrap: the prefix (all columns before Text, trailing separator included) and the suffix (the columns after it,
+   * leading separator included) stay whole. The suffix rides on the LAST line so folding continuations back recovers
+   * the default line byte-identically; a row that fits emits exactly the default line.
+   */
+  renderRowLine(rowParts, textPos, sep5, textVal, rawWidth) {
+    const width = typeof rawWidth === "number" && Number.isFinite(rawWidth) && rawWidth >= 1 ? Math.floor(rawWidth) : void 0;
+    if (width === void 0) return `${rowParts.join(sep5)}
+`;
+    const prefix = `${rowParts.slice(0, textPos).join(sep5)}${sep5}`;
+    const tail = rowParts.slice(textPos + 1);
+    const suffix = tail.length > 0 ? `${sep5}${tail.join(sep5)}` : "";
+    const prefixLen = displayLen(prefix);
+    const budget = width - prefixLen - displayLen(suffix);
+    if (budget <= 0) return `${rowParts.join(sep5)}
+`;
+    const segments = wrapTextCell(textVal, budget);
+    if (segments.length <= 1) return `${rowParts.join(sep5)}
+`;
+    const indent = " ".repeat(prefixLen);
+    let out = `${prefix}${segments[0]}
+`;
+    for (let k = 1; k < segments.length - 1; k++) out += `${indent}${segments[k]}
+`;
+    out += `${indent}${segments[segments.length - 1]}${suffix}
+`;
+    return out;
+  }
+  renderOutlineText(table, options) {
+    const compact = options?.compact ?? false;
+    const sep5 = compact ? "|" : " | ";
+    let output = `> fidelity: ${table.fidelity || "lossy"} tier: outline
+`;
+    if (options?.includeHeaderRow !== false) {
+      output += `${OUTLINE_HEADERS.join(sep5)}
+`;
+      if (!compact) output += `${OUTLINE_HEADERS.map(() => "---").join(" | ")}
+`;
+    }
+    for (const row of table.rows) {
+      let text2 = row.text;
+      if (options?.maxTextLength && options.maxTextLength > 0 && text2.length > options.maxTextLength) {
+        text2 = `${text2.substring(0, options.maxTextLength)}...`;
+      }
+      const cells = [row.id, String(row.level ?? ""), escapeOutlineCell(row.style), escapeOutlineCell(text2), row.path];
+      output += this.renderRowLine(cells, 3, sep5, cells[3], options?.width);
+    }
+    return output;
+  }
   renderToonText(table, options) {
+    if (table.tier === "outline") return this.renderOutlineText(table, options);
     const omits = new Set(options?.omitColumns ?? []);
     const compact = options?.compact ?? false;
     const tier = table.tier ?? "compact";
@@ -35036,40 +35894,8 @@ var ToonGenerator = class _ToonGenerator {
           rowParts.push(row.detail ?? "");
         }
       }
-      const sep5 = compact ? "|" : " | ";
-      const rawWidth = options?.width;
-      const width = typeof rawWidth === "number" && Number.isFinite(rawWidth) && rawWidth >= 1 ? Math.floor(rawWidth) : void 0;
-      if (width === void 0) {
-        output += `${rowParts.join(sep5)}
-`;
-        continue;
-      }
       const textPos = 2 + (omits.has("path") ? 0 : 1) + (omits.has("header") ? 0 : 1) + (omits.has("style") ? 0 : 1);
-      const prefix = `${rowParts.slice(0, textPos).join(sep5)}${sep5}`;
-      const tail = rowParts.slice(textPos + 1);
-      const suffix = tail.length > 0 ? `${sep5}${tail.join(sep5)}` : "";
-      const prefixLen = displayLen(prefix);
-      const budget = width - prefixLen - displayLen(suffix);
-      if (budget <= 0) {
-        output += `${rowParts.join(sep5)}
-`;
-        continue;
-      }
-      const segments = wrapTextCell(textVal, budget);
-      if (segments.length <= 1) {
-        output += `${rowParts.join(sep5)}
-`;
-        continue;
-      }
-      const indent = " ".repeat(prefixLen);
-      output += `${prefix}${segments[0]}
-`;
-      for (let k = 1; k < segments.length - 1; k++) {
-        output += `${indent}${segments[k]}
-`;
-      }
-      output += `${indent}${segments[segments.length - 1]}${suffix}
-`;
+      output += this.renderRowLine(rowParts, textPos, compact ? "|" : " | ", textVal, options?.width);
     }
     return output;
   }
@@ -35195,7 +36021,7 @@ var ToonGenerator = class _ToonGenerator {
 // ../engine/src/tmp.ts
 var import_crypto5 = __toESM(require("crypto"));
 var import_fs7 = __toESM(require("fs"));
-var import_os = __toESM(require("os"));
+var import_os2 = __toESM(require("os"));
 var import_path6 = __toESM(require("path"));
 var ASTRA_TMPDIR_ENV = "ASTRA_TMPDIR";
 var TMP_SYMLINK_REMEDY = "Point $ASTRA_TMPDIR at a real directory (not a symlink), or unset it and retry.";
@@ -35251,7 +36077,7 @@ function resolveAstraTmpBase() {
     try {
       import_fs7.default.mkdirSync(dir, { recursive: true });
     } catch {
-      return import_os.default.tmpdir();
+      return import_os2.default.tmpdir();
     }
     refuseSymlinkBase(dir);
     refuseForeignOwner(dir);
@@ -35261,7 +36087,7 @@ function resolveAstraTmpBase() {
     }
     return dir;
   }
-  const fallback = import_os.default.tmpdir();
+  const fallback = import_os2.default.tmpdir();
   const injected = [process.env.TMPDIR, process.env.TEMP, process.env.TMP].filter((v) => typeof v === "string" && v.trim() !== "").map((v) => import_path6.default.resolve(v.trim()));
   if (injected.includes(import_path6.default.resolve(fallback))) {
     const dir = import_path6.default.resolve(fallback);
@@ -35301,12 +36127,12 @@ function logForensics(p, reason) {
   try {
     const rawName = import_path6.default.basename(p);
     const name2 = rawName !== "" ? rawName : "artifact";
-    let hash = "unknown";
+    let hash2 = "unknown";
     try {
-      hash = import_crypto5.default.createHash("sha256").update(p).digest("hex").slice(0, 16);
+      hash2 = import_crypto5.default.createHash("sha256").update(p).digest("hex").slice(0, 16);
     } catch {
     }
-    process.stderr.write(`[ASTra] tmp artifact kept for forensics: name="${name2}" sha256="${hash}" (${reason}). Base honors $ASTRA_TMPDIR; remove manually after inspection.
+    process.stderr.write(`[ASTra] tmp artifact kept for forensics: name="${name2}" sha256="${hash2}" (${reason}). Base honors $ASTRA_TMPDIR; remove manually after inspection.
 `);
   } catch {
   }
@@ -35370,12 +36196,12 @@ function logForensicPrune(target, reason) {
   try {
     const rawName = import_path6.default.basename(target);
     const name2 = rawName !== "" ? rawName : "artifact";
-    let hash = "unknown";
+    let hash2 = "unknown";
     try {
-      hash = import_crypto5.default.createHash("sha256").update(target).digest("hex").slice(0, 16);
+      hash2 = import_crypto5.default.createHash("sha256").update(target).digest("hex").slice(0, 16);
     } catch {
     }
-    process.stderr.write(`[ASTra] tmp forensics prune: name="${name2}" sha256="${hash}" (${reason}).
+    process.stderr.write(`[ASTra] tmp forensics prune: name="${name2}" sha256="${hash2}" (${reason}).
 `);
   } catch {
   }
@@ -37611,9 +38437,9 @@ function escapeHtml(str) {
 
 // ../engine/src/export/pdf.ts
 var import_child_process = require("child_process");
-var fs8 = __toESM(require("fs"));
-var fsp3 = __toESM(require("fs/promises"));
-var path7 = __toESM(require("path"));
+var fs10 = __toESM(require("fs"));
+var fsp4 = __toESM(require("fs/promises"));
+var path9 = __toESM(require("path"));
 var import_url = require("url");
 
 // ../engine/src/export/preflight.ts
@@ -37954,6 +38780,136 @@ function runPreflightChecks(docx) {
   return { blockers, warnings };
 }
 
+// ../engine/src/visual/backend.ts
+var fs9 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
+var VISUAL_DEPENDENCY_REMEDY = "PDF render backend missing. Install LibreOffice and poppler-utils (pdftoppm): Linux: sudo apt install libreoffice poppler-utils; macOS: brew install --cask libreoffice && brew install poppler; Windows: winget install TheDocumentFoundation.LibreOffice, then install Poppler for Windows (for example scoop install poppler, or choco install poppler) and make sure pdftoppm.exe is on PATH. Alternatively inspect the XML/DOM without images (telemetry-only mode).";
+function createDependencyError(missing) {
+  const which = missing.length > 0 ? missing.join(", ") : "soffice, pdftoppm";
+  return Object.assign(new Error(`E_DEPENDENCY: headless visual backend unavailable (missing: ${which})`), {
+    code: "E_DEPENDENCY",
+    remedy: VISUAL_DEPENDENCY_REMEDY
+  });
+}
+function windowsExtensions(pathExt) {
+  const requested = (pathExt ?? ".EXE;.COM").split(";").map((e) => e.trim().toLowerCase()).filter((e) => e === ".exe" || e === ".com");
+  const ordered = [".exe", ".com"].filter((e) => requested.includes(e));
+  return ordered.length > 0 ? ordered : [".exe", ".com"];
+}
+function isExecutableFile(candidate) {
+  try {
+    fs9.accessSync(candidate, fs9.constants.X_OK);
+    return fs9.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+function candidateNames(name2, platform, pathExt) {
+  if (platform !== "win32") return [name2];
+  const lower = name2.toLowerCase();
+  if (lower.endsWith(".exe") || lower.endsWith(".com")) return [name2];
+  return windowsExtensions(pathExt).map((ext) => name2 + ext);
+}
+function installFolders(name2, platform = process.platform, env = process.env) {
+  const bare = name2.toLowerCase().replace(/\.(exe|com)$/, "");
+  const isOffice = bare === "soffice" || bare === "libreoffice";
+  const isPoppler = bare === "pdftoppm";
+  const dirs = [];
+  if (platform === "win32") {
+    const programFiles = env.ProgramFiles ?? "C:\\Program Files";
+    const programFilesX86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    const localAppData = env.LOCALAPPDATA;
+    const userProfile = env.USERPROFILE;
+    if (isOffice) {
+      dirs.push(path8.join(programFiles, "LibreOffice", "program"));
+      dirs.push(path8.join(programFilesX86, "LibreOffice", "program"));
+      if (localAppData) dirs.push(path8.join(localAppData, "Programs", "LibreOffice", "program"));
+    }
+    if (isPoppler) {
+      if (userProfile) dirs.push(path8.join(userProfile, "scoop", "shims"));
+      dirs.push(path8.join(env.ProgramData ?? "C:\\ProgramData", "chocolatey", "bin"));
+      if (localAppData) dirs.push(path8.join(localAppData, "Microsoft", "WinGet", "Links"));
+    }
+  } else if (platform === "darwin") {
+    const home = env.HOME;
+    if (isOffice) {
+      dirs.push("/Applications/LibreOffice.app/Contents/MacOS");
+      if (home) dirs.push(path8.join(home, "Applications", "LibreOffice.app", "Contents", "MacOS"));
+    }
+    dirs.push("/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin");
+  }
+  return dirs;
+}
+function findOnPath(name2, pathEnv, options = {}) {
+  try {
+    if (!name2 || name2.trim() === "") return null;
+    const trimmed = name2.trim();
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const pathExt = options.pathExt ?? (platform === "win32" ? env.PATHEXT : void 0);
+    const names = candidateNames(trimmed, platform, pathExt);
+    if (trimmed.includes("/") || trimmed.includes("\\")) {
+      for (const n of names) {
+        const abs = path8.resolve(n);
+        if (isExecutableFile(abs)) return abs;
+      }
+      return null;
+    }
+    const pathValue = pathEnv !== void 0 ? pathEnv : env.PATH ?? env.Path ?? "";
+    const dirs = pathValue.split(path8.delimiter).map((d) => d.trim().replace(/^"(.*)"$/, "$1")).filter((d) => d.length > 0);
+    for (const dir of dirs) {
+      for (const n of names) {
+        const candidate = path8.resolve(dir, n);
+        if (isExecutableFile(candidate)) return candidate;
+      }
+    }
+    const useFallback = options.fallbackDirs ?? (pathEnv === void 0 && env.ASTRA_VISUAL_NO_FALLBACK_DIRS !== "1");
+    if (useFallback) {
+      for (const dir of options.installDirs ?? installFolders(trimmed, platform, env)) {
+        for (const n of names) {
+          const candidate = path8.resolve(dir, n);
+          if (isExecutableFile(candidate)) return candidate;
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function resolveSoffice(override, pathEnv) {
+  if (override && override.trim()) {
+    const direct = findOnPath(override.trim(), pathEnv);
+    if (direct) return direct;
+    return null;
+  }
+  return findOnPath("soffice", pathEnv) ?? findOnPath("libreoffice", pathEnv);
+}
+function hasPdfBackend(override) {
+  const pathEnv = override?.pathEnv;
+  const sofficePath = resolveSoffice(override?.sofficeBin, pathEnv);
+  let pdftoppmPath = null;
+  if (override?.pdftoppmBin && override.pdftoppmBin.trim()) {
+    pdftoppmPath = findOnPath(override.pdftoppmBin.trim(), pathEnv);
+  } else {
+    pdftoppmPath = findOnPath("pdftoppm", pathEnv);
+  }
+  const missing = [];
+  if (!sofficePath) missing.push("soffice");
+  if (!pdftoppmPath) missing.push("pdftoppm");
+  if (missing.length === 0) {
+    return { available: true, backend: "libreoffice", sofficePath, pdftoppmPath, missing: [] };
+  }
+  return { available: false, backend: "none", missing };
+}
+function assertPdfBackend(override) {
+  const status = hasPdfBackend(override);
+  if (!status.available) {
+    throw createDependencyError(status.missing);
+  }
+  return { sofficePath: status.sofficePath, pdftoppmPath: status.pdftoppmPath };
+}
+
 // ../engine/src/export/pdf.ts
 var DependencyError = class extends Error {
   code = "E_DEPENDENCY";
@@ -37999,19 +38955,15 @@ function getPdfBackendBinary() {
   if (cachedBackendBinary !== void 0) {
     return cachedBackendBinary;
   }
-  const candidates = ["libreoffice", "soffice"];
-  for (const bin of candidates) {
-    try {
-      (0, import_child_process.execSync)(`which ${bin}`, { stdio: "ignore" });
-      cachedBackendBinary = bin;
-      return bin;
-    } catch {
-    }
+  const found = findOnPath("soffice") ?? findOnPath("libreoffice");
+  if (found) {
+    cachedBackendBinary = found;
+    return found;
   }
   cachedBackendBinary = null;
   return null;
 }
-function hasPdfBackend() {
+function hasPdfBackend2() {
   return getPdfBackendBinary() !== null;
 }
 async function convertDocxToPdf(docxBuffer, outPdfPath, options) {
@@ -38022,7 +38974,8 @@ async function convertDocxToPdf(docxBuffer, outPdfPath, options) {
   Debian/Ubuntu: sudo apt install libreoffice
   Fedora/RHEL:   sudo dnf install libreoffice
   macOS:         brew install --cask libreoffice
-  Windows:       winget install TheDocumentFoundation.LibreOffice`
+  Windows:       winget install TheDocumentFoundation.LibreOffice
+ASTra also looks in the standard install folders (for example C:\\Program Files\\LibreOffice\\program and /Applications/LibreOffice.app/Contents/MacOS).`
     );
   }
   const preflight = runPreflightChecks(docxBuffer);
@@ -38072,7 +39025,7 @@ var MAX_CONVERT_ATTEMPTS = 3;
 async function removeStagedDir(dir) {
   for (let attempt = 1; attempt <= 2; attempt++) {
     try {
-      await fsp3.rm(dir, { recursive: true, force: true });
+      await fsp4.rm(dir, { recursive: true, force: true });
       return;
     } catch {
       if (attempt < 2) {
@@ -38084,10 +39037,10 @@ async function removeStagedDir(dir) {
 }
 async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, binary, stagedForensics) {
   const tmpDir = secureMkdtemp("astra-pdf-");
-  const tmpDocxPath = path7.join(tmpDir, `doc_${Date.now()}.docx`);
+  const tmpDocxPath = path9.join(tmpDir, `doc_${Date.now()}.docx`);
   let succeeded = false;
   try {
-    await fsp3.writeFile(tmpDocxPath, docxBuffer);
+    await fsp4.writeFile(tmpDocxPath, docxBuffer);
     secureFile(tmpDocxPath);
     let converted = false;
     let lastError = null;
@@ -38096,7 +39049,7 @@ async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, bi
         await new Promise((resolve10, reject) => {
           const child = (0, import_child_process.spawn)(
             binary,
-            [`-env:UserInstallation=${(0, import_url.pathToFileURL)(path7.join(tmpDir, "lo_profile")).href}`, "--headless", "--convert-to", filterSpec, tmpDocxPath, "--outdir", tmpDir],
+            [`-env:UserInstallation=${(0, import_url.pathToFileURL)(path9.join(tmpDir, "lo_profile")).href}`, "--headless", "--convert-to", filterSpec, tmpDocxPath, "--outdir", tmpDir],
             { stdio: ["ignore", "pipe", "pipe"] }
           );
           let stderr = "";
@@ -38132,23 +39085,23 @@ async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, bi
     if (!converted && lastError) {
       throw lastError;
     }
-    const expectedPdfName = path7.basename(tmpDocxPath).replace(/\.docx$/i, ".pdf");
-    const generatedPdfPath = path7.join(tmpDir, expectedPdfName);
-    if (!fs8.existsSync(generatedPdfPath)) {
+    const expectedPdfName = path9.basename(tmpDocxPath).replace(/\.docx$/i, ".pdf");
+    const generatedPdfPath = path9.join(tmpDir, expectedPdfName);
+    if (!fs10.existsSync(generatedPdfPath)) {
       throw new Error(`PDF conversion failed: output file ${generatedPdfPath} was not created`);
     }
-    const targetDir = path7.dirname(path7.resolve(outPdfPath));
-    assertWriteTargetNoSymlink(path7.resolve(outPdfPath));
-    await fsp3.mkdir(targetDir, { recursive: true });
-    assertWriteTargetNoSymlink(path7.resolve(outPdfPath));
-    await writeFileNoFollow(path7.resolve(outPdfPath), await fsp3.readFile(generatedPdfPath));
-    fs8.chmodSync(path7.resolve(outPdfPath), 420);
+    const targetDir = path9.dirname(path9.resolve(outPdfPath));
+    assertWriteTargetNoSymlink(path9.resolve(outPdfPath));
+    await fsp4.mkdir(targetDir, { recursive: true });
+    assertWriteTargetNoSymlink(path9.resolve(outPdfPath));
+    await writeFileNoFollow(path9.resolve(outPdfPath), await fsp4.readFile(generatedPdfPath));
+    fs10.chmodSync(path9.resolve(outPdfPath), 420);
     succeeded = true;
-    return path7.resolve(outPdfPath);
+    return path9.resolve(outPdfPath);
   } finally {
     if (succeeded) {
       try {
-        await fsp3.rm(tmpDir, { recursive: true, force: true });
+        await fsp4.rm(tmpDir, { recursive: true, force: true });
       } catch {
         keepForForensics(tmpDir, "could not remove tmp dir after success");
       }
@@ -38160,86 +39113,12 @@ async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, bi
   }
 }
 
-// ../engine/src/visual/backend.ts
-var fs9 = __toESM(require("fs"));
-var path8 = __toESM(require("path"));
-var VISUAL_DEPENDENCY_REMEDY = "PDF render backend missing. Install LibreOffice and poppler-utils (pdftoppm): sudo apt install libreoffice poppler-utils, or brew install libreoffice poppler. Alternatively inspect the XML/DOM without images (telemetry-only mode).";
-function createDependencyError(missing) {
-  const which = missing.length > 0 ? missing.join(", ") : "soffice, pdftoppm";
-  return Object.assign(new Error(`E_DEPENDENCY: headless visual backend unavailable (missing: ${which})`), {
-    code: "E_DEPENDENCY",
-    remedy: VISUAL_DEPENDENCY_REMEDY
-  });
-}
-function findOnPath(name2, pathEnv) {
-  try {
-    if (!name2 || name2.trim() === "") return null;
-    const trimmed = name2.trim();
-    if (trimmed.includes("/") || trimmed.includes("\\")) {
-      try {
-        const abs = path8.resolve(trimmed);
-        fs9.accessSync(abs, fs9.constants.X_OK);
-        const stat3 = fs9.statSync(abs);
-        if (stat3.isFile()) return abs;
-        return null;
-      } catch {
-        return null;
-      }
-    }
-    const pathValue = pathEnv !== void 0 ? pathEnv : process.env.PATH ?? "";
-    if (!pathValue) return null;
-    const dirs = pathValue.split(path8.delimiter).filter((d) => d.length > 0);
-    for (const dir of dirs) {
-      try {
-        const candidate = path8.join(dir, trimmed);
-        fs9.accessSync(candidate, fs9.constants.X_OK);
-        const stat3 = fs9.statSync(candidate);
-        if (stat3.isFile()) return candidate;
-      } catch {
-        continue;
-      }
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-function resolveSoffice(override, pathEnv) {
-  if (override && override.trim()) {
-    const direct = findOnPath(override.trim(), pathEnv);
-    if (direct) return direct;
-    return null;
-  }
-  return findOnPath("soffice", pathEnv) ?? findOnPath("libreoffice", pathEnv);
-}
-function hasPdfBackend2(override) {
-  const pathEnv = override?.pathEnv;
-  const sofficePath = resolveSoffice(override?.sofficeBin, pathEnv);
-  let pdftoppmPath = null;
-  if (override?.pdftoppmBin && override.pdftoppmBin.trim()) {
-    pdftoppmPath = findOnPath(override.pdftoppmBin.trim(), pathEnv);
-  } else {
-    pdftoppmPath = findOnPath("pdftoppm", pathEnv);
-  }
-  const missing = [];
-  if (!sofficePath) missing.push("soffice");
-  if (!pdftoppmPath) missing.push("pdftoppm");
-  if (missing.length === 0) {
-    return { available: true, backend: "libreoffice", sofficePath, pdftoppmPath, missing: [] };
-  }
-  return { available: false, backend: "none", missing };
-}
-function assertPdfBackend(override) {
-  const status = hasPdfBackend2(override);
-  if (!status.available) {
-    throw createDependencyError(status.missing);
-  }
-  return { sofficePath: status.sofficePath, pdftoppmPath: status.pdftoppmPath };
-}
+// ../engine/src/export/pdf-source.ts
+var STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
 
 // ../engine/src/visual/renderer.ts
-var fs10 = __toESM(require("fs"));
-var path9 = __toESM(require("path"));
+var fs11 = __toESM(require("fs"));
+var path10 = __toESM(require("path"));
 var import_url2 = require("url");
 var import_child_process2 = require("child_process");
 var import_util = require("util");
@@ -38250,13 +39129,13 @@ var VISUAL_DEFAULT_MAX_PAGES = 4;
 var VISUAL_MIN_DPI = 72;
 var VISUAL_MAX_DPI = 300;
 function getVisualArtifactsBaseDir() {
-  const dir = path9.join(resolveAstraTmpBase(), "ASTra", "visual");
+  const dir = path10.join(resolveAstraTmpBase(), "ASTra", "visual");
   try {
-    fs10.mkdirSync(dir, { recursive: true, mode: 448 });
+    fs11.mkdirSync(dir, { recursive: true, mode: 448 });
   } catch {
   }
   try {
-    secureDir(path9.join(resolveAstraTmpBase(), "ASTra"));
+    secureDir(path10.join(resolveAstraTmpBase(), "ASTra"));
   } catch {
   }
   secureDir(dir);
@@ -38266,9 +39145,9 @@ function getVisualArtifactsDir(subDir) {
   const base = getVisualArtifactsBaseDir();
   if (!subDir || subDir.trim() === "") return base;
   const safe = subDir.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 64) || "run";
-  const dir = path9.join(base, safe);
+  const dir = path10.join(base, safe);
   try {
-    fs10.mkdirSync(dir, { recursive: true, mode: 448 });
+    fs11.mkdirSync(dir, { recursive: true, mode: 448 });
   } catch {
   }
   secureDir(dir);
@@ -38302,7 +39181,7 @@ function parsePageNumber(fileName) {
 function listRenderedPages(workDir, prefixBase) {
   let entries = [];
   try {
-    entries = fs10.readdirSync(workDir);
+    entries = fs11.readdirSync(workDir);
   } catch {
     return [];
   }
@@ -38311,7 +39190,7 @@ function listRenderedPages(workDir, prefixBase) {
     if (!name2.startsWith(prefixBase)) continue;
     const page = parsePageNumber(name2);
     if (page === null) continue;
-    out.push({ page, file: path9.join(workDir, name2) });
+    out.push({ page, file: path10.join(workDir, name2) });
   }
   out.sort((a, b) => a.page - b.page);
   return out;
@@ -38325,7 +39204,7 @@ function sandboxError(message, remedy) {
 function canonicalVisualBaseDir() {
   const base = getVisualArtifactsBaseDir();
   try {
-    return fs10.realpathSync(base);
+    return fs11.realpathSync(base);
   } catch {
     return base;
   }
@@ -38349,7 +39228,7 @@ function resolveJailedVisualOutDir(rawOutDir) {
   if (trimmed.includes("\n") || trimmed.includes("\r")) {
     throw sandboxError("E_SANDBOX: visual outDir contains a forbidden line break.", "Remove line breaks from the path and retry.");
   }
-  const resolved = path9.resolve(trimmed);
+  const resolved = path10.resolve(trimmed);
   const canonical = canonicalizeForAsset(resolved);
   const canonicalBase = canonicalVisualBaseDir();
   assertVisualInsideBase(canonical, trimmed, canonicalBase);
@@ -38381,7 +39260,7 @@ async function renderDocxToImages(docxBuffer, opts = {}) {
     outDir = getVisualArtifactsDir(runId);
   }
   try {
-    fs10.mkdirSync(outDir, { recursive: true });
+    fs11.mkdirSync(outDir, { recursive: true });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw validationError(`E_VALIDATION: cannot create artifacts dir "${outDir}": ${msg}`, "Pass a writable outDir and retry.");
@@ -38392,16 +39271,16 @@ async function renderDocxToImages(docxBuffer, opts = {}) {
     outDir = live;
   }
   const workDir = secureMkdtemp("astra-visual-");
-  const inputDocx = path9.join(workDir, "input.docx");
+  const inputDocx = path10.join(workDir, "input.docx");
   let succeeded = false;
   try {
-    fs10.writeFileSync(inputDocx, docxBuffer);
+    fs11.writeFileSync(inputDocx, docxBuffer);
     secureFile(inputDocx);
     let lastErr;
     let converted = false;
     for (let attempt = 1; attempt <= 3; attempt++) {
       try {
-        await execFileAsync(sofficePath, [`-env:UserInstallation=${(0, import_url2.pathToFileURL)(path9.join(workDir, "lo_profile")).href}`, "--headless", "--convert-to", "pdf", "--outdir", workDir, inputDocx], {
+        await execFileAsync(sofficePath, [`-env:UserInstallation=${(0, import_url2.pathToFileURL)(path10.join(workDir, "lo_profile")).href}`, "--headless", "--convert-to", "pdf", "--outdir", workDir, inputDocx], {
           timeout: timeoutMs
         });
         converted = true;
@@ -38419,17 +39298,17 @@ async function renderDocxToImages(docxBuffer, opts = {}) {
     }
     let pdfPath = null;
     try {
-      const names = fs10.readdirSync(workDir).filter((n) => n.toLowerCase().endsWith(".pdf"));
+      const names = fs11.readdirSync(workDir).filter((n) => n.toLowerCase().endsWith(".pdf"));
       names.sort((a, b) => a === "input.pdf" ? -1 : b === "input.pdf" ? 1 : a.localeCompare(b));
-      if (names.length > 0) pdfPath = path9.join(workDir, names[0]);
+      if (names.length > 0) pdfPath = path10.join(workDir, names[0]);
     } catch {
       pdfPath = null;
     }
-    if (!pdfPath || !fs10.existsSync(pdfPath)) {
+    if (!pdfPath || !fs11.existsSync(pdfPath)) {
       throw validationError("E_VALIDATION: libreoffice produced no PDF output.", "Verify the .docx opens in Word/LibreOffice and retry.");
     }
     const prefixBase = "page";
-    const prefix = path9.join(workDir, prefixBase);
+    const prefix = path10.join(workDir, prefixBase);
     const ppmArgs = format === "png" ? ["-png", "-r", String(dpi), pdfPath, prefix] : ["-jpeg", "-jpegopt", `quality=${jpegQuality}`, "-r", String(dpi), pdfPath, prefix];
     try {
       await execFileAsync(pdftoppmPath, ppmArgs, { timeout: Math.min(timeoutMs, 6e4) });
@@ -38448,15 +39327,15 @@ async function renderDocxToImages(docxBuffer, opts = {}) {
     const ext = format === "png" ? "png" : "jpg";
     for (const entry of selected) {
       const destName = `page-${entry.page}.${ext}`;
-      const dest = path9.join(outDir, destName);
-      if (!isPathInsideDir(path9.resolve(dest), path9.resolve(outDir))) {
+      const dest = path10.join(outDir, destName);
+      if (!isPathInsideDir(path10.resolve(dest), path10.resolve(outDir))) {
         throw sandboxError(
           `E_SANDBOX: visual artifact destination escapes outDir: "${dest}".`,
           "Pass an outDir inside the visual artifacts dir (use getVisualArtifactsDir(subDir) for a run-scoped dir) and retry."
         );
       }
       try {
-        fs10.copyFileSync(entry.file, dest);
+        fs11.copyFileSync(entry.file, dest);
         secureFile(dest);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -38465,7 +39344,7 @@ async function renderDocxToImages(docxBuffer, opts = {}) {
       const canonicalDest = canonicalizeForAsset(dest);
       if (!isPathInsideDir(canonicalDest, canonicalizeForAsset(outDir))) {
         try {
-          fs10.unlinkSync(dest);
+          fs11.unlinkSync(dest);
         } catch {
         }
         throw sandboxError(
@@ -38475,7 +39354,7 @@ async function renderDocxToImages(docxBuffer, opts = {}) {
       }
       let bytes = 0;
       try {
-        bytes = fs10.statSync(dest).size;
+        bytes = fs11.statSync(dest).size;
       } catch {
         bytes = 0;
       }
@@ -38625,8 +39504,18 @@ function computeDocStats(ast) {
       if (hits) words += hits.length;
     }
   }
-  const pageBudget = words / 450 + (tables + callouts) * 0.45 + images * 0.5 + pageBreaks;
-  return { words, paragraphs, pages: Math.max(1, Math.ceil(pageBudget)), tables, callouts, images };
+  const pageTerms = {
+    words: words / 450,
+    tables: (tables + callouts) * 0.45,
+    images: images * 0.5,
+    pageBreaks
+  };
+  const pageBudget = pageTerms.words + pageTerms.tables + pageTerms.images + pageTerms.pageBreaks;
+  return { words, paragraphs, pages: Math.max(1, Math.ceil(pageBudget)), pageTerms, tables, callouts, images };
+}
+function roundedPageTerms(terms) {
+  const r = (n) => Math.round(n * 100) / 100;
+  return { words: r(terms.words), tables: r(terms.tables), images: r(terms.images), pageBreaks: r(terms.pageBreaks) };
 }
 
 // ../engine/src/visual/telemetry.ts
@@ -40219,7 +41108,7 @@ function assertTemplateSeed(parser2, template) {
   }
   if (!matched) {
     throw new Error(
-      `E_VALIDATION: line 1: open document does not hold the ${template} seed ("${marker}"). Remedy: open a fresh ${template} document first, then compose into it.`
+      `E_VALIDATION: line 1: open document does not hold the ${template} seed ("${marker}"). Remedy: to add to this document, call compose_document again without template; to start from the ${template} template, call new_document with template "${template}" first and compose into that.`
     );
   }
 }
@@ -40791,9 +41680,39 @@ function summarizeStyleGuide(guide) {
   return out;
 }
 
+// ../engine/src/restore-original.ts
+var import_node_fs2 = __toESM(require("node:fs"));
+var import_promises4 = __toESM(require("node:fs/promises"));
+var import_node_path2 = __toESM(require("node:path"));
+var import_isomorphic_git2 = __toESM(require("isomorphic-git"));
+async function captureHistoryState(docPath) {
+  const target = import_node_path2.default.resolve(docPath);
+  const [head, index] = await Promise.all([
+    getHistory(target).then((entries) => entries[0]?.oid, () => void 0),
+    import_isomorphic_git2.default.statusMatrix({ fs: import_node_fs2.default, dir: getRepoDir(target) }).then((matrix) => JSON.stringify(matrix), () => void 0)
+  ]);
+  return { head, index };
+}
+async function historyChangedSince(docPath, before) {
+  const after = await captureHistoryState(docPath);
+  if (before.head === void 0 || after.head === void 0 || before.index === void 0 || after.index === void 0) return true;
+  return after.head !== before.head || after.index !== before.index;
+}
+async function rollbackReplacedFile(docPath, previous, failure) {
+  const outcome = failure.error?.outcome;
+  if (!failure.replaced && outcome !== "replaced" && outcome !== "uncertain") return { recovered: true };
+  try {
+    await replaceFileAtomic(docPath, previous);
+    if (originalSha256(await import_promises4.default.readFile(docPath)) === originalSha256(previous)) return { recovered: true };
+    return { recovered: false, failure: "the file does not match the previous bytes after rollback" };
+  } catch (error) {
+    return { recovered: false, failure: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 // src/lib/mcp/baseline-gate.ts
 var crypto13 = __toESM(require("crypto"));
-var fsp4 = __toESM(require("fs/promises"));
+var fsp6 = __toESM(require("fs/promises"));
 
 // src/lib/mcp/errors.ts
 function mcpError(code, message, remedy) {
@@ -40873,8 +41792,8 @@ function invalidInput(message) {
 }
 
 // src/lib/mcp/diff.ts
-var fs12 = __toESM(require("fs"));
-var path11 = __toESM(require("path"));
+var fs14 = __toESM(require("fs"));
+var path13 = __toESM(require("path"));
 var DISCARDED_NODE_IDS_MAX = 20;
 var AUDIT_NODE_IDS_MAX = 100;
 var AUDIT_FILES_MAX = 100;
@@ -41241,7 +42160,7 @@ function pathDirname(p) {
 }
 function sidecarRepoExists(docPath) {
   try {
-    return fs12.existsSync(path11.join(getRepoDir(docPath), ".git"));
+    return fs14.existsSync(path13.join(getRepoDir(docPath), ".git"));
   } catch {
     return false;
   }
@@ -41280,7 +42199,7 @@ async function resolveBaseline(handle) {
   if (handle.validationBaseline !== void 0) return handle.validationBaseline;
   if (!handle.openSha256) return null;
   try {
-    const bytes = await fsp4.readFile(handle.filePath);
+    const bytes = await fsp6.readFile(handle.filePath);
     if (sha256Hex(bytes) !== handle.openSha256) return null;
     const baseline = buildBaseline(await validateForBaseline(bytes));
     handle.validationBaseline = baseline;
@@ -41364,7 +42283,7 @@ function withToleratedNote(message, preExisting) {
 async function validateAtOpen(handle, timeoutMs) {
   let bytes;
   try {
-    bytes = await fsp4.readFile(handle.filePath);
+    bytes = await fsp6.readFile(handle.filePath);
   } catch (err) {
     return { status: "skipped", note: `the file could not be read for validation: ${err instanceof Error ? err.message : String(err)}` };
   }
@@ -41408,10 +42327,10 @@ async function validateAtOpen(handle, timeoutMs) {
 }
 
 // src/lib/session-store.ts
-var fs13 = __toESM(require("fs"));
-var fsp5 = __toESM(require("fs/promises"));
-var os2 = __toESM(require("os"));
-var path12 = __toESM(require("path"));
+var fs15 = __toESM(require("fs"));
+var fsp7 = __toESM(require("fs/promises"));
+var os3 = __toESM(require("os"));
+var path14 = __toESM(require("path"));
 var import_crypto6 = require("crypto");
 var MCP_SESSION_MAX_DOCS = 10;
 var MCP_SESSION_MAX_BYTES = 200 * 1024 * 1024;
@@ -41609,19 +42528,19 @@ function getMcpAllowedRoots() {
   if (named.length > 0) return [...new Set(named)];
   const roots = [];
   try {
-    roots.push(path12.resolve(process.cwd(), "documents"));
+    roots.push(path14.resolve(process.cwd(), "documents"));
   } catch {
   }
   try {
-    roots.push(path12.resolve(os2.tmpdir()));
+    roots.push(path14.resolve(os3.tmpdir()));
   } catch {
   }
   try {
-    roots.push(path12.resolve(process.cwd(), "documents", "Drafts"));
+    roots.push(path14.resolve(process.cwd(), "documents", "Drafts"));
   } catch {
   }
   try {
-    roots.push(path12.resolve(os2.tmpdir(), "ASTra"));
+    roots.push(path14.resolve(os3.tmpdir(), "ASTra"));
   } catch {
   }
   return [...new Set(roots)];
@@ -41638,12 +42557,12 @@ function getExistingExtraRoots() {
   const raw = (process.env.ASTRA_EXTRA_DOC_ROOTS || "").trim();
   if (!raw) return [];
   const out = [];
-  for (const part of raw.split(path12.delimiter)) {
+  for (const part of raw.split(path14.delimiter)) {
     const p = part.trim();
     if (!p) continue;
     try {
-      const resolved = path12.resolve(p);
-      const stat3 = fs13.statSync(resolved);
+      const resolved = path14.resolve(p);
+      const stat3 = fs15.statSync(resolved);
       if (!stat3.isDirectory()) continue;
       out.push(resolved);
     } catch {
@@ -41655,7 +42574,7 @@ function findMcpContainingRoot(canonical) {
   for (const root of getMcpAllowedRoots()) {
     let canonicalRoot = root;
     try {
-      canonicalRoot = fs13.realpathSync(root);
+      canonicalRoot = fs15.realpathSync(root);
     } catch {
     }
     if (isPathInsideDir(canonical, canonicalRoot) || isPathInsideDir(canonical, root)) {
@@ -41665,8 +42584,8 @@ function findMcpContainingRoot(canonical) {
   return void 0;
 }
 function assertNoDotSegments(canonical, root) {
-  const rel = path12.relative(root, canonical);
-  const segs = rel.split(path12.sep).filter((s) => s && s !== "." && s !== "..");
+  const rel = path14.relative(root, canonical);
+  const segs = rel.split(path14.sep).filter((s) => s && s !== "." && s !== "..");
   for (const seg of segs) {
     if (seg.startsWith(".")) {
       throw Object.assign(new Error(`Document path traverses a hidden directory "${seg}"`), {
@@ -41675,7 +42594,7 @@ function assertNoDotSegments(canonical, root) {
       });
     }
   }
-  const base = path12.basename(canonical);
+  const base = path14.basename(canonical);
   if (base.startsWith(".")) {
     throw Object.assign(new Error("Document path must not use a hidden (dot-prefixed) file name"), {
       code: "E_SANDBOX",
@@ -41716,8 +42635,8 @@ function validateDocPath(rawPath) {
       remedy: `Use a path ${describeAllowedFolders()}.`
     });
   }
-  const resolved = path12.resolve(trimmed);
-  const resolvedSegments = resolved.split(path12.sep);
+  const resolved = path14.resolve(trimmed);
+  const resolvedSegments = resolved.split(path14.sep);
   if (resolvedSegments.includes("..")) {
     throw Object.assign(new Error("Document path resolves outside its directory"), {
       code: "E_SANDBOX",
@@ -41736,7 +42655,7 @@ function validateDocPath(rawPath) {
     );
   }
   assertNoDotSegments(canonical, containingRoot);
-  const ext = path12.extname(trimmed).toLowerCase();
+  const ext = path14.extname(trimmed).toLowerCase();
   if (ext !== ".docx") {
     throw Object.assign(new Error(`Document path must use a .docx extension (got "${ext || "(none)"}")`), {
       code: "E_VALIDATION",
@@ -41758,9 +42677,9 @@ function validateOpenBufferLabel(rawLabel) {
       remedy: "Pass a plain memory label such as memory.docx."
     });
   }
-  if (path12.isAbsolute(trimmed)) return validateDocPath(trimmed);
+  if (path14.isAbsolute(trimmed)) return validateDocPath(trimmed);
   if (trimmed.includes("\n") || trimmed.includes("\r")) return fallback;
-  const base = path12.basename(trimmed.replace(/\\/g, "/"));
+  const base = path14.basename(trimmed.replace(/\\/g, "/"));
   if (!base || base === "." || base === "..") return fallback;
   const clean = base.slice(0, 128);
   return clean.toLowerCase().endsWith(".docx") ? clean : fallback;
@@ -41774,29 +42693,141 @@ function collectTrackedExtrasForGit(parser2) {
     }
     return extras;
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`[collectTrackedExtrasForGit] snapshot failed: ${msg}`);
-    return {};
+    throw snapshotCollectionError(err);
   }
 }
-async function ensureGitRepo(docPath, xml, extras) {
+function snapshotCollectionError(cause) {
+  const detail = cause instanceof Error ? cause.message : String(cause);
+  return Object.assign(new Error(`The document's package parts could not be collected for history (${detail}). Nothing was recorded.`), {
+    code: "E_STATE",
+    remedy: "Nothing was recorded in history. Retry; if it keeps failing, the document package may be damaged."
+  });
+}
+async function ensureGitRepo(docPath, xml, extras, originalBytes) {
+  return (await ensureGitRepoWith(docPath, () => ({ xml, extras }), originalBytes)).existed;
+}
+async function ensureGitRepoWith(docPath, baseline, originalBytes, options) {
   const repoDir = getRepoDir(docPath);
   let hasGit = false;
   try {
-    hasGit = fs13.existsSync(path12.join(repoDir, ".git"));
+    hasGit = fs15.existsSync(path14.join(repoDir, ".git"));
   } catch {
     hasGit = false;
   }
-  if (hasGit) return true;
-  await initAstraRepo(docPath, xml, extras);
-  return false;
+  if (hasGit) {
+    if (!options?.alreadyReady) await assertGitHistoryReady(repoDir);
+    return { existed: true };
+  }
+  try {
+    const initial = baseline();
+    await initAstraRepo(docPath, initial.xml, initial.extras, originalBytes);
+    return { existed: false, baseline: initial };
+  } catch (error) {
+    if (fs15.existsSync(path14.join(repoDir, ".git"))) {
+      await assertGitHistoryReady(repoDir);
+      return { existed: true };
+    }
+    throw error;
+  }
 }
-async function initGitForHandleBestEffort(handle) {
+function collectBaselineForGit(parser2) {
+  const xml = parser2.readDocumentXml();
   try {
-    if (!path12.isAbsolute(handle.filePath)) return;
-    const xml = handle.parser.readDocumentXml();
-    await ensureGitRepo(handle.filePath, xml, collectTrackedExtrasForGit(handle.parser));
-  } catch {
+    const snapshot3 = parser2.capturePackageSnapshot({ documentXml: xml });
+    const extras = {};
+    for (const [name2, buf] of snapshot3) if (isTrackedPackageFile(name2)) extras[name2] = buf;
+    return { xml, extras };
+  } catch (err) {
+    throw snapshotCollectionError(err);
+  }
+}
+var sha256Of = (bytes) => (0, import_crypto6.createHash)("sha256").update(bytes).digest("hex");
+async function resolveSessionOriginal(handle) {
+  const fallback = handle.originalInfo ?? { available: false, reason: "not-applicable" };
+  const pin = handle.originalPin;
+  if (!pin || !path14.isAbsolute(handle.filePath)) return fallback;
+  const current = await getOriginalInfo(handle.filePath);
+  if (pin.kind === "retained") {
+    if (!current.available) return current;
+    if (current.sha256 !== pin.sha256) {
+      return { available: false, reason: "capture-failed", detail: "The retained original no longer matches the one this session opened." };
+    }
+    return current;
+  }
+  if (current.available && current.sha256 !== pin.sha256) {
+    return { available: false, reason: "capture-failed", detail: "Another opener recorded a different original for this history." };
+  }
+  const initialization = await getHistoryInitializationState(handle.filePath);
+  if (initialization.state !== "complete") {
+    return { available: false, reason: "initializing", detail: initialization.detail ?? "History initialization has not completed. Check get_document_history again later." };
+  }
+  if (!current.available) return current;
+  handle.originalInfo = current;
+  handle.originalPin = { kind: "retained", sha256: current.sha256 };
+  handle.originalWarning = void 0;
+  return current;
+}
+var INITIALIZING_WARNING = "History initialization was not complete when this document opened (another ASTra process may be creating it). Editing is available. Exact-original recovery becomes available if that initialization finishes for this same file; check get_document_history.";
+async function initGitForHandleBestEffort(handle, originalBytes) {
+  try {
+    if (!path14.isAbsolute(handle.filePath)) return;
+    const repoDir = getRepoDir(handle.filePath);
+    let completeBeforeRead = false;
+    if (fs15.existsSync(path14.join(repoDir, ".git"))) {
+      try {
+        await assertGitHistoryReady(repoDir);
+        completeBeforeRead = true;
+      } catch {
+      }
+    }
+    const availabilityAtOpen = await getOriginalInfo(handle.filePath);
+    const ensured = await ensureGitRepoWith(handle.filePath, () => collectBaselineForGit(handle.parser), originalBytes, { alreadyReady: completeBeforeRead });
+    if (ensured.existed) {
+      const preExisting = completeBeforeRead && availabilityAtOpen.available;
+      const now = preExisting ? availabilityAtOpen : await getOriginalInfo(handle.filePath);
+      handle.originalInfo = now;
+      if (now.available) {
+        if (preExisting || originalBytes && sha256Of(originalBytes) === now.sha256) {
+          handle.originalPin = { kind: "retained", sha256: now.sha256 };
+        } else {
+          handle.originalInfo = { available: false, reason: "capture-failed", detail: "Another opener recorded a different original for this history." };
+        }
+      } else if (originalBytes && now.reason === "incomplete") {
+        handle.originalInfo = { available: false, reason: "initializing", detail: "The history was still being initialized when this session opened." };
+        handle.originalPin = { kind: "input", sha256: sha256Of(originalBytes) };
+        handle.originalWarning = INITIALIZING_WARNING;
+      }
+    } else {
+      handle.originalInfo = await getOriginalInfo(handle.filePath);
+      const recorded = ensured.baseline;
+      const history = await getHistory(handle.filePath);
+      const head = history[0] ? await checkoutCommit(handle.filePath, history[0].oid) : void 0;
+      const names = Object.keys(recorded.extras).sort();
+      const headNames = head ? [...head.extra.keys()].sort() : [];
+      const initialStateMatches = !!head?.complete && recorded.xml === head.xml && JSON.stringify(names) === JSON.stringify(headNames) && names.every((name2) => recorded.extras[name2].equals(head.extra.get(name2)));
+      if (!initialStateMatches && handle.originalInfo.available) {
+        handle.originalInfo = { available: false, reason: "capture-failed", detail: "Concurrent history initialization produced a different initial document state. Close and reopen after inspecting history." };
+      }
+      if (originalBytes && handle.originalInfo.available && handle.originalInfo.sha256 !== sha256Of(originalBytes)) {
+        handle.originalInfo = { available: false, reason: "capture-failed", detail: "Another opener recorded a different original for this history." };
+      }
+      if (handle.originalInfo.available) handle.originalPin = { kind: "retained", sha256: handle.originalInfo.sha256 };
+    }
+    if (!handle.originalInfo.available && !["predates-feature", "not-applicable"].includes(handle.originalInfo.reason)) {
+      handle.originalWarning = handle.originalInfo.reason === "initializing" ? INITIALIZING_WARNING : `Exact-original recovery is unavailable: ${handle.originalInfo.reason}. Keep a separate copy of the input file.`;
+    }
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const mismatch = error?.reason === "original-mismatch";
+    const initialization = originalBytes && !mismatch && path14.isAbsolute(handle.filePath) ? await getHistoryInitializationState(handle.filePath) : void 0;
+    if (initialization && originalBytes && initialization.state !== "absent") {
+      handle.originalInfo = { available: false, reason: "initializing", detail: initialization.detail ?? detail };
+      handle.originalPin = { kind: "input", sha256: sha256Of(originalBytes) };
+      handle.originalWarning = INITIALIZING_WARNING;
+    } else {
+      handle.originalInfo = mismatch ? { available: false, reason: "capture-failed", detail } : { available: false, reason: "incomplete", detail };
+      handle.originalWarning = `History initialization or original-file capture did not complete. Editing is available, but exact-original recovery is not. ${detail} Keep a separate copy of the input file.`;
+    }
   }
 }
 var McpSessionStore = class {
@@ -42046,12 +43077,12 @@ var McpSessionStore = class {
    * Macro/active content refuses by default (E_VALIDATION naming the parts);
    * pass {allowMacros:true} to preserve or {stripMacros:true} to strip.
    */
-  async openDocument(filePath, sessionId, macroOpts) {
+  async openDocument(filePath, sessionId, macroOpts, captureInput = true) {
     const cleanPath = validateDocPath(filePath);
     const expiredEvicted = this.evictExpired();
     let buf;
     try {
-      buf = await fsp5.readFile(cleanPath);
+      buf = await fsp7.readFile(cleanPath);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       throw Object.assign(new Error(`open_document: cannot read "${cleanPath}": ${msg}`), {
@@ -42086,10 +43117,12 @@ var McpSessionStore = class {
       lastAccess: Date.now(),
       mutex: new SessionMutex(),
       redoStack: this.createRedoStack(),
-      pendingAudit: { ops: 0, nodeIds: [] }
+      pendingAudit: { ops: 0, nodeIds: [] },
+      lastWrittenSha256: (0, import_crypto6.createHash)("sha256").update(buf).digest("hex"),
+      macroPolicy: macroOpts
     };
     this.sessions.set(id, handle);
-    await initGitForHandleBestEffort(handle);
+    await initGitForHandleBestEffort(handle, captureInput ? buf : void 0);
     this.lastOpenEvicted = [...expiredEvicted, ...this.evictToFit(id)];
     const live = this.sessions.get(id);
     if (!live) {
@@ -42156,10 +43189,13 @@ var McpSessionStore = class {
       lastAccess: Date.now(),
       mutex: new SessionMutex(),
       redoStack: this.createRedoStack(),
-      pendingAudit: { ops: 0, nodeIds: [] }
+      pendingAudit: { ops: 0, nodeIds: [] },
+      lastWrittenSha256: (0, import_crypto6.createHash)("sha256").update(buf).digest("hex"),
+      macroPolicy: macroOpts
     };
     this.sessions.set(id, handle);
-    await initGitForHandleBestEffort(handle);
+    await initGitForHandleBestEffort(handle, buf);
+    if (!path14.isAbsolute(handle.filePath)) handle.originalInfo = { available: false, reason: "not-applicable" };
     this.lastOpenEvicted = [...expiredEvicted, ...this.evictToFit(id)];
     const live = this.sessions.get(id);
     if (!live) {
@@ -42334,6 +43370,8 @@ var LEAN6_TOOL_NAMES = [
 ];
 var GIT_HISTORY_TOOL_NAMES = [
   "get_document_history",
+  "export_original_document",
+  "restore_original_document",
   "preview_revert",
   "revert_document",
   "redo_document"
@@ -42363,7 +43401,7 @@ var LEAN6_DESCRIPTIONS = {
     { workflow: true }
   ),
   inspect_document: withSharedDocs(
-    'Inspect a session: standard TOON outline (fidelity compact|standard|full, default standard) plus style palette passthrough {availableStyles,brandColors,primaryFont} parsed from word/styles.xml, plus document core properties `metadata` {title,creator,subject,description,keywords,category,lastModifiedBy,revision,created,modified} read from docProps/core.xml (absent when the docx has no core part). Use include:["comments","revisions"] for review records paged by reviewOffset/reviewLimit (max 50; offset/limit page nodes only); commentId or revisionId reads full detail and needs its include. Renders the in-memory session state (includes unsaved execute_batch edits); `dirty:true` means the session differs from the last saved file, `revision` is the in-memory revision. Node ids are verbatim: paragraphs carry 8-hex w14:paraId (e.g. 3F2A9C1B), tables t_001.., sections sec_root, sec_2, sec_3.. by position; use them as-is for targets/anchors. A repeat paragraph sharing one native paraId reports a `<paraId>_dup` session id instead (e.g. 3F2A9C1B_dup): saving refuses until the repeat is deleted and its text reinserted for a fresh id. Tables render one row per table with grid cells as rNcM coordinates (r1c1 value | r1c2 value, rows joined by ;); merged spans are marked (spanN); merge covers are tagged hidden-cover (not directly editable, address the restart cell). Cell edits: the replace, style, namedStyle, clearFormat, hyperlink, bookmark and comment actions accept target "<tableId>:r<row>c<col>" (1-based, as the grid prints it; add ":p<n>" to pick one paragraph of a multi-paragraph cell). Other actions, including table, take the table id. Every row and column number counts from 1 (cell addresses, rowIndex, colIndex, columnIndex, row, col, index, afterIndex, fromRow/toRow/fromCol/toCol), so r3c2 and {rowIndex:3,colIndex:2} are the same cell. Chart nodes render style chart|chart3d with title + categories + series in the text ([Chart column] Title | cats: Q1,Q2 | ARR: 10,25), read from the chart part. Flag legend: [TBL] table [IMG] image/drawing [EQ] equation [CITE] citation [CMT] comment [TRK] tracked [LNK] link [BKMK] bookmark [L#] list level (1 is the top level; list ops count the same way) [+ADDED]/[~MODIFIED] diff; standard tier adds [B] bold [I] italic [C:hex] color [SZ:half-points] size [RS:name] run style [J:just] [N:num] numbering [HDR]/[ZEBRA] table look [CH:type]/[RID:id] chart. Palette lists every style id verbatim with no trim (large templates return the full list). 3-tier workflow for large docs: (1) macro-overview inspect (compact, first window) -> (2) search_content to find a target node id -> (3) local zoom via {aroundNode:"<id>",window:5} or page with {offset,limit}. Windowing opts: offset (min 0, default 0), limit (1-200, default 50), aroundNode + window (1-20, default 5) returning [node-w,node+w], maxTokens (200-8000, cuts on a clean row boundary, always reported via truncated/hasMore). aroundNode and offset/limit are mutually exclusive (use one or the other). Windowed renders preserve the requested tier; the TOON fidelity marker stays lossy by design (TOON is a lossy projection). Docs under ~2000 tokens return the full TOON (unchanged); larger docs default to the first ~50-node window {totalNodes,returnedNodes,offset,limit,hasMore,nextOffset,toonText} with a navigation remedy. Full fidelity requires sectionId; sectionId is a section id or a node id (a node id prefix needs 4 characters or more), and an id that matches nothing is an error that names the available section ids. Example {"sessionId":"sess_abc","fidelity":"standard"} -> TOON text + palette. Use the palette style names verbatim (e.g. Corporate Callout); never invent styles. When the session carries a style guide, the envelope also includes its compact styleGuide summary {name,headerFill,headerText,chartPalette,calloutTheme}. IDs are session-scoped: valid only in the issuing session, must not be stored across sessions, and duplicate client-supplied ids are rejected.'
+    'Inspect a session: standard TOON outline (fidelity outline|compact|standard|full, default standard) plus style palette passthrough fidelity outline lists headings only (ID, level L, Style, Text, Section = the headings above); there rowCount/totalNodes count heading rows, `outline` {headings,nodes,tables,images,words} counts the whole document, and aroundNode on a body node shows the heading above it (`aroundResolvedTo`). {availableStyles,brandColors,primaryFont} parsed from word/styles.xml, plus document core properties `metadata` {title,creator,subject,description,keywords,category,lastModifiedBy,revision,created,modified} read from docProps/core.xml (absent when the docx has no core part). Use include:["comments","revisions"] for review records paged by reviewOffset/reviewLimit (max 50; offset/limit page nodes only); commentId or revisionId reads full detail and needs its include. Renders the in-memory session state (includes unsaved execute_batch edits); `dirty:true` means the session differs from the last saved file, `revision` is the in-memory revision. Node ids are verbatim: paragraphs carry 8-hex w14:paraId (e.g. 3F2A9C1B), tables t_001.., sections sec_root, sec_2, sec_3.. by position; use them as-is for targets/anchors. A repeat paragraph sharing one native paraId reports a `<paraId>_dup` session id instead (e.g. 3F2A9C1B_dup): saving refuses until the repeat is deleted and its text reinserted for a fresh id. Tables render one row per table with grid cells as rNcM coordinates (r1c1 value | r1c2 value, rows joined by ;); merged spans are marked (spanN); merge covers are tagged hidden-cover (not directly editable, address the restart cell). Cell edits: the replace, style, namedStyle, clearFormat, hyperlink, bookmark and comment actions accept target "<tableId>:r<row>c<col>" (1-based, as the grid prints it; add ":p<n>" to pick one paragraph of a multi-paragraph cell). Other actions, including table, take the table id. Every row and column number counts from 1 (cell addresses, rowIndex, colIndex, columnIndex, row, col, index, afterIndex, fromRow/toRow/fromCol/toCol), so r3c2 and {rowIndex:3,colIndex:2} are the same cell. Chart nodes render style chart|chart3d with title + categories + series in the text ([Chart column] Title | cats: Q1,Q2 | ARR: 10,25), read from the chart part. Flag legend: [TBL] table [IMG] image/drawing [EQ] equation [CITE] citation [CMT] comment [TRK] tracked [LNK] link [BKMK] bookmark [L#] list level (1 is the top level; list ops count the same way) [+ADDED]/[~MODIFIED] diff; standard tier adds [B] bold [I] italic [C:hex] color [SZ:half-points] size [RS:name] run style [J:just] [N:num] numbering [HDR]/[ZEBRA] table look [CH:type]/[RID:id] chart. Palette lists every style id verbatim with no trim (large templates return the full list). 3-tier workflow for large docs: (1) macro-overview inspect (compact, first window) -> (2) search_content to find a target node id -> (3) local zoom via {aroundNode:"<id>",window:5} or page with {offset,limit}. Windowing opts: offset (min 0, default 0), limit (1-200, default 50), aroundNode + window (1-20, default 5) returning [node-w,node+w], maxTokens (200-8000, cuts on a clean row boundary, always reported via truncated/hasMore). aroundNode and offset/limit are mutually exclusive (use one or the other). Windowed renders preserve the requested tier; the TOON fidelity marker stays lossy by design (TOON is a lossy projection). Docs under ~2000 tokens return the full TOON (unchanged); larger docs default to the first ~50-node window {totalNodes,returnedNodes,offset,limit,hasMore,nextOffset,toonText} with a navigation remedy. Full fidelity requires sectionId; sectionId is a section id or a node id (a node id prefix needs 4 characters or more), and an id that matches nothing is an error that names the available section ids. Example {"sessionId":"sess_abc","fidelity":"standard"} -> TOON text + palette. Use the palette style names verbatim (e.g. Corporate Callout); never invent styles. When the session carries a style guide, the envelope also includes its compact styleGuide summary {name,headerFill,headerText,chartPalette,calloutTheme}. IDs are session-scoped: valid only in the issuing session, must not be stored across sessions, and duplicate client-supplied ids are rejected.'
   ),
   search_content: withSharedDocs(
     'Search live paragraph/table w:t text; returns [{id,preview}] node hits for anchors/targets. Use scope:"comments" or scope:"all" to search comment text; the default scope is body. At most 50 matches come back; truncated:true says more exist. A table hit also lists `cells` (up to 5 addresses such as t_001:r3c1) for the cells that hold the match; pass one as the target of replace/style/namedStyle/clearFormat/hyperlink/bookmark/comment. Chart titles/series are NOT matched by search (they live in the chart part, not w:t); discover them in inspect TOON chart rows, then anchor by the chart node id. Image alt text and footnote/endnote bodies are NOT matched either (search covers body w:t text only); find images via inspect [IMG] rows and footnotes via their anchor ids. Search extension to those parts is a later-program candidate, not this surface. Default is an exact literal substring (case-insensitive); pass {"regex":true} to interpret the query as a regular expression (bounded: pattern <=200 chars, ~500ms evaluation budget, case-insensitive). Caps: first 50 hits, 120-char previews. Literal queries containing regex metacharacters return literal results plus a hint that regex:true exists. Example {"sessionId":"sess_abc","query":"Executive Summary"} -> {"ok":true,"matches":[{"id":"3F2A9C1B","preview":"Executive ..."}]}. Search before editing when the anchor id is unknown.'
@@ -42381,8 +43419,10 @@ var LEAN6_DESCRIPTIONS = {
   )
 };
 var GIT_HISTORY_DESCRIPTIONS = {
+  export_original_document: "Export the exact original DOCX captured when this history was created. Requires sessionId and outPath; overwrite defaults to false. Verifies the retained SHA-256 and never serializes the original. Does not change the live session. Refuses overwriting the active document: use restore_original_document instead. Old histories and memory-only sessions may have no original. The original can contain content removed by later sanitization; history retains it until the history store is deleted.",
+  restore_original_document: "Replace the working file with the exact captured original, verified by SHA-256, and record a new history commit. Requires sessionId. Unsaved edits refuse unless discard:true explicitly discards them. Refuses an externally changed file or history that does not match the saved state. Close other programs editing this file before restoring; an external write racing the final replacement cannot be excluded. Reloads the session under its opening policy. Normal revert/redo restore document state, not necessarily the original ZIP bytes. The next normal save may normalize the file again. Use export_original_document for recovery to a different path.",
   get_document_history: withSharedDocs(
-    'List the saved git history for a session (newest first, read-only: never mutates, never flips dirty). Paginate with limit (1-100, default 20) and offset (default 0). Returns {ok:true,sessionId,documentPath,currentCommit,totalCommits,history:[{oid,message,author,timestamp,timestampMs,opCount,affectedNodeIds,resultingHeadOid}]} (timestampMs = ms-precision epoch millis; commit-time clock for tracked commits, git seconds for older ones; opCount is always present (0 for pre-tracking commits and heals-only saves: it folds operations, not normalizer rewrites); affectedNodeIds is always present ([] when untracked); resultingHeadOid always equals oid (append-only; refs never move). Example {"sessionId":"sess_abc","limit":10} -> history slice. Use the oids with revert_document (or preview_revert first) to restore an earlier saved state. '
+    'List the saved git history and original-file availability for a session (newest first, read-only: never mutates, never flips dirty). Paginate with limit (1-100, default 20) and offset (default 0). Returns {ok:true,sessionId,documentPath,currentCommit,totalCommits,history:[{oid,message,author,timestamp,timestampMs,opCount,affectedNodeIds,resultingHeadOid}]} (timestampMs = ms-precision epoch millis; commit-time clock for tracked commits, git seconds for older ones; opCount is always present (0 for pre-tracking commits and heals-only saves: it folds operations, not normalizer rewrites); affectedNodeIds is always present ([] when untracked); resultingHeadOid always equals oid (append-only; refs never move). Example {"sessionId":"sess_abc","limit":10} -> history slice. Use the oids with revert_document (or preview_revert first) to restore an earlier saved state. '
   ),
   preview_revert: withSharedDocs(
     `Read-only WOULD-restore preview for revert_document (never mutates: no revision bump, no disk write, no redo-stack change). Target one commit: {steps:N} walks back N saved commits from the head (1 = the previous saved commit, must be < totalCommits) OR {commitOid:"<40-hex>"} jumps to that commit (mutually exclusive). Returns {ok:true,sessionId,targetOid,targetMessage,targetAuthor,stepsBack,affectedFiles,changedValues,changedValuesTruncated,changedValuesPositional,dirty,dirtyHandling,currentHeadOid,totalCommits} where affectedFiles lists package paths that differ from the target (word/document.xml plus tracked extras). The preview also carries advisory changedValues [{nodeId,before,after}] (live current text -> target restore text, bounded: at most ${CHANGED_VALUES_MAX} entries, each side at most ${CHANGED_VALUE_TEXT_MAX} chars, truncated flag honest; changedValuesPositional:true means either side held orphan ids (no shared id across the boundary, common under duplicate native ids) so before/after pairing is positional, not identity; empty + changedValuesReason when the target range is not computable). Example {"sessionId":"sess_abc","steps":1} -> preview summary. Preview first when a revert would discard unsaved edits.`
@@ -42402,7 +43442,7 @@ var PARITY_DESCRIPTIONS = {
     'Preflight read-only OOXML audit for a session: runs the same validator gate save_document enforces, before anything is written. Detects schema violations while they are still cheap to fix. Strictly read-only: zero session mutation (revision and dirty flag untouched), zero disk writes, zero history commits. Returns {ok:true,sessionId,revision,dirty,validation:{valid,errorCount,errors}} where errors carry description + xPath (first 10, same shape as the save-blocked envelope). The verdict is on the document as a save would write it (children put in schema order first); when that save would repair something the result also carries pendingNormalizations (a list of repairs, absent when none), so a valid verdict is not mistaken for "valid exactly as it stands". Use before save_document when the package may be non-conforming; save_document re-gates before writing. Example {"sessionId":"sess_abc"} -> {"ok":true,"validation":{"valid":true,"errorCount":0,"errors":[]}}. '
   ),
   get_stats: withSharedDocs(
-    'Token-cheap document census for a session: words, paragraphs, tables, callouts, images, and an estimated editorial page budget (layout-weighted by words, tables, images, and explicit page breaks) in a single small envelope. Counters are the exact engine counters behind CLI stats, so both surfaces always agree. Physical pagination is finalized when exporting to PDF via LibreOffice. Read-only: never mutates, never bumps the revision. Returns {ok:true,sessionId,revision,dirty,words,paragraphs,tables,callouts,images,pages}. A callout (a "> [!NOTE]" alert or a callout op: a one-cell table with a fill) is counted in callouts and not in tables. Use instead of inspect_document when only counts are needed (a full TOON dump costs thousands of tokens for the same question). Example {"sessionId":"sess_abc"} -> {"ok":true,"words":42,"paragraphs":5}. '
+    'Token-cheap document census for a session: words, paragraphs, tables, callouts, images, and an estimated editorial page budget (layout-weighted by words, tables, images, and explicit page breaks) in a single small envelope. Counters are the exact engine counters behind CLI stats, so both surfaces always agree. Physical pagination is finalized when exporting to PDF via LibreOffice. Read-only: never mutates, never bumps the revision. Returns {ok:true,sessionId,revision,dirty,words,paragraphs,tables,callouts,images,pages,pageTerms}. pages is a rough estimate, max(1, ceil(words/450 + 0.45 per table or callout + 0.5 per image + 1 per page break)); pageTerms gives those four terms in pages, so a caller can see how much of it is counted from tables, callouts, images and page breaks (`pageTerms.tables` covers tables and callouts), which the estimate cannot size. Use visual_inspect for the renderer\'s page count. A callout (a "> [!NOTE]" alert or a callout op: a one-cell table with a fill) is counted in callouts and not in tables. Use instead of inspect_document when only counts are needed (a full TOON dump costs thousands of tokens for the same question). Example {"sessionId":"sess_abc"} -> {"ok":true,"words":42,"paragraphs":5}. '
   ),
   sanitize_document: withSharedDocs(
     `Scrub an open session document. By default it removes revision ids, authorship, embedded EXIF and hidden text PII. Tracked changes and comments are kept, with the text of every tracked deletion, unless you ask: acceptAllRevisions:true accepts all tracked changes (deleted text is removed) and stripComments:true removes comments. The CLI presets (bare sanitize, --client-safe, --metadata-only, --redact-pii) turn both on; this tool does not. Macro/active parts are removed on request. It uses the same engine scrub path as CLI sanitize. Body text is kept. Options mirror the engine scrub keys 1:1 (zeroRetention, purgeRSIDs, purgeAuthors, purgeExif, purgePII, acceptAllRevisions, stripComments, replacementAuthor, allowMacros, stripMacros); omitted options take engine defaults. With acceptAllRevisions it returns E_VALIDATION and no file when revision markup remains that cannot be resolved. allowMacros and stripMacros together fail with E_VALIDATION. ${piiCoverageSentence()} Returns {ok:true,sessionId,revision,dirty,removedRSIDs,purgedAuthors,strippedExifBytes,purgedPII,bodyPII,piiCoverage,acceptedRevisions,strippedComments,strippedMacros,macroParts,filesTouched,droppedRogue,...} plus the standard redoCleared signal when a redo chain is dropped. Example {"sessionId":"sess_abc","stripMacros":true} -> scrubbed session at a new revision (save after). `
@@ -42440,7 +43480,7 @@ var OpenDocumentSchema = import_zod4.z.object({
 }).strict();
 var InspectDocumentSchema = import_zod4.z.object({
   sessionId: import_zod4.z.string().min(1).max(128),
-  fidelity: import_zod4.z.enum(["compact", "standard", "full"]).optional(),
+  fidelity: import_zod4.z.enum(["outline", "compact", "standard", "full"]).optional(),
   sectionId: import_zod4.z.string().min(1).max(256).optional(),
   maxTextLength: import_zod4.z.number().int().min(1).max(1e4).optional(),
   // Phase C-2 smart windowing: offset/limit page the node rows; aroundNode +
@@ -42571,6 +43611,15 @@ var ImportDocumentSchema = import_zod4.z.object({
   // Read $...$ as inline math (off by default: prices and shell text can look like math).
   dollarMath: import_zod4.z.boolean().optional()
 }).strict();
+var ExportOriginalDocumentSchema = import_zod4.z.object({
+  sessionId: import_zod4.z.string().min(1).max(128),
+  outPath: import_zod4.z.string().min(1).max(1024),
+  overwrite: import_zod4.z.boolean().optional()
+}).strict();
+var RestoreOriginalDocumentSchema = import_zod4.z.object({
+  sessionId: import_zod4.z.string().min(1).max(128),
+  discard: import_zod4.z.boolean().optional()
+}).strict();
 
 // src/lib/mcp/handlers/open-inspect.ts
 function extractStylePalette2(parser2) {
@@ -42664,7 +43713,7 @@ async function handleOpenDocument(store, input) {
     const evicted = store.drainLastOpenEvicted();
     const pendingNormalizations = readPendingNormalizations(handle);
     const validation = await validateAtOpen(handle, parsed.data.validationTimeoutMs ?? openValidationTimeoutMs());
-    return { ok: true, sessionId: handle.sessionId, revision: handle.revision, summary, evicted, pendingNormalizations, validation };
+    return { ok: true, sessionId: handle.sessionId, revision: handle.revision, summary, evicted, pendingNormalizations, validation, original: handle.originalInfo, ...handle.originalWarning ? { originalWarning: handle.originalWarning } : {} };
   } catch (err) {
     return mcpErrorFrom(err, "E_IO", "Check the .docx path is readable and retry open_document.");
   }
@@ -42678,6 +43727,12 @@ function readPendingNormalizations(handle) {
     return [];
   }
 }
+function outlineCountsOf(ast) {
+  const stats = computeDocStats(ast);
+  let nodes = 0;
+  for (const sec of ast.sections) nodes += sec.nodes.length;
+  return { headings: countHeadings(ast), nodes, tables: stats.tables + stats.callouts, images: stats.images, words: stats.words };
+}
 async function handleInspectDocument(store, input) {
   const parsed = InspectDocumentSchema.safeParse(input);
   if (!parsed.success) {
@@ -42777,6 +43832,7 @@ async function handleInspectDocument(store, input) {
           pendingNormalizations: readPendingNormalizations(handle),
           ...handle.styleGuide !== void 0 ? { styleGuide: summarizeStyleGuide(handle.styleGuide) } : {},
           toonText: fullText,
+          ...fidelity === "outline" ? { outline: outlineCountsOf(handle.ast) } : {},
           rowCount: totalNodes,
           totalNodes,
           returnedNodes: totalNodes,
@@ -42790,11 +43846,40 @@ async function handleInspectDocument(store, input) {
       let start;
       let end;
       let effectiveLimit = limit;
+      let aroundResolvedTo;
+      let note;
       if (aroundNode !== void 0) {
-        const idx = table.rows.findIndex((r) => r.id === aroundNode);
+        let idx = table.rows.findIndex((r) => r.id === aroundNode);
+        if (idx < 0 && fidelity === "outline") {
+          const scoped = sectionId ? resolveSectionScope(handle.ast.sections, sectionId) : handle.ast.sections;
+          const order = scoped.flatMap((sec) => sec.nodes.map((n) => n.id));
+          const at = order.indexOf(aroundNode);
+          if (at < 0) {
+            const anywhere = handle.ast.sections.some((sec) => sec.nodes.some((n) => n.id === aroundNode));
+            if (anywhere) {
+              throw Object.assign(
+                new Error(`inspect_document: aroundNode "${aroundNode}" is not in section "${sectionId}".`),
+                { code: "E_VALIDATION", remedy: "Drop sectionId, or pass a node id that belongs to that section." }
+              );
+            }
+          } else {
+            const headingIds = new Set(table.rows.map((r) => r.id));
+            let above = -1;
+            for (let k = at; k >= 0 && above < 0; k--) if (headingIds.has(order[k])) above = k;
+            if (above >= 0) {
+              idx = table.rows.findIndex((r) => r.id === order[above]);
+              aroundResolvedTo = order[above];
+              note = `Node ${aroundNode} is not a heading; showing the heading above it (${order[above]}).`;
+            } else {
+              aroundResolvedTo = null;
+              note = totalNodes === 0 ? `No headings${sectionId ? " in this scope" : " in the document"}; the outline is empty.` : `Node ${aroundNode} has no heading above it${sectionId ? " in this scope" : ""}; showing the first headings.`;
+              idx = 0;
+            }
+          }
+        }
         if (idx < 0) {
           throw Object.assign(
-            new Error(`inspect_document: aroundNode "${aroundNode}" not found (${totalNodes} nodes in scope).`),
+            new Error(`inspect_document: aroundNode "${aroundNode}" not found (${totalNodes} ${fidelity === "outline" ? "headings" : "nodes"} in scope).`),
             {
               code: "E_VALIDATION",
               remedy: 'Call search_content to find a valid target node id, then retry inspect_document with {aroundNode:"<id>", window:5}.'
@@ -42803,6 +43888,10 @@ async function handleInspectDocument(store, input) {
         }
         start = Math.max(0, idx - window);
         end = Math.min(totalNodes, idx + window + 1);
+        if (aroundResolvedTo === null) {
+          start = 0;
+          end = Math.min(totalNodes, window * 2 + 1);
+        }
         effectiveLimit = end - start;
       } else {
         if (offset >= totalNodes && totalNodes > 0) {
@@ -42869,6 +43958,7 @@ async function handleInspectDocument(store, input) {
         pendingNormalizations: readPendingNormalizations(handle),
         ...handle.styleGuide !== void 0 ? { styleGuide: summarizeStyleGuide(handle.styleGuide) } : {},
         toonText,
+        ...fidelity === "outline" ? { outline: outlineCountsOf(handle.ast) } : {},
         rowCount: returnedNodes,
         totalNodes,
         returnedNodes,
@@ -42878,6 +43968,8 @@ async function handleInspectDocument(store, input) {
         nextOffset: hasMore ? start + returnedNodes : null,
         truncated
       };
+      if (aroundResolvedTo !== void 0) out.aroundResolvedTo = aroundResolvedTo;
+      if (note !== void 0) out.note = note;
       if (hasMore || truncated) {
         out.remedy = `Large document: showing ${returnedNodes}/${totalNodes} TOON nodes${truncated ? ` (cut to fit maxTokens ${maxTokens})` : ""}. Navigate: 1) search_content to find a target node id, 2) inspect_document {aroundNode:"<id>", window:5} to zoom, 3) page with {offset:${hasMore ? start + returnedNodes : start}, limit:${effectiveLimit}} to continue.`;
       }
@@ -42889,11 +43981,11 @@ async function handleInspectDocument(store, input) {
 }
 
 // src/lib/mcp/handlers/search-batch.ts
-var path14 = __toESM(require("path"));
+var path16 = __toESM(require("path"));
 
 // src/tools/compose-document.ts
-var fs14 = __toESM(require("fs"));
-var path13 = __toESM(require("path"));
+var fs16 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
 var import_zod5 = require("zod");
 var COMPOSE_MARKDOWN_MAX = 5e5;
 var COMPOSE_VALIDATION_ERRORS_MAX = 3;
@@ -42908,8 +44000,8 @@ function resolveMcpStyleGuide(ref, jail) {
   let anchor;
   if (jail?.allowedDir !== void 0) {
     anchor = jail.allowedDir;
-  } else if (jail?.sessionFilePath !== void 0 && path13.isAbsolute(jail.sessionFilePath)) {
-    anchor = canonicalizeForAsset(path13.resolve(path13.dirname(jail.sessionFilePath)));
+  } else if (jail?.sessionFilePath !== void 0 && path15.isAbsolute(jail.sessionFilePath)) {
+    anchor = canonicalizeForAsset(path15.resolve(path15.dirname(jail.sessionFilePath)));
   }
   if (anchor === void 0 && !hasGuideScheme(trimmed) && isFileGuideRef(trimmed)) {
     throw guideSandboxError(
@@ -42942,7 +44034,7 @@ var ComposeDocumentSchema = import_zod5.z.object({
   // Side of anchor the first block goes on (default after). Needs anchor.
   position: import_zod5.z.enum(["before", "after"]).optional()
 }).strict();
-var COMPOSE_DOCUMENT_DESCRIPTION = 'Compose a Markdown string into the open session document (appends after existing content, or at anchor with position before|after; an unchanged built-in template created in this session has its sample content replaced). A document can be built in several compose calls: the first call of a session mints ids md_0001..., later calls mint md2_0001..., md3_0001..., so ids never collide; pass anchor (a node id, start or end) and position to add a section in the middle without another tool. Runs the engine compose path, then applies the resulting operations through the same execute_batch path (strict schema gate, per-chunk quotas, structural checks, per-chunk atomic rollback, then inline-span run splitting), so every gate a batch meets applies here unchanged. Supported input: #/##/### headings (real Heading1..3 styles), blank-line paragraphs (single newlines join with a space), flat bullet (-, *, +) and ordered (1., 1)) lists with real numbering, GitHub-style tables with a header separator row (header row shaded and repeated), --- dividers, fenced or indented code blocks (monospace, line breaks kept), [^label] footnotes with definitions, inline spans (**bold**, *italic*, `code`, [text](url)) applied as runs with real hyperlink targets, plain `> quote` blocks (written in the Quote paragraph style: blank > lines start a new paragraph, > > nests up to 3 levels, flat lists and fenced code are kept inside, a table, heading or image inside a quote fails), and standalone block images/charts (![alt](path)) resolved from allowedDir. Out-of-scope input fails closed with E_VALIDATION plus a 1-based line number and writes nothing: raw HTML (except [!NOTE]-style alert callouts, which compile to callout containers and keep bold, italic, code and links), custom styles, deeper headings, nested lists or tables, task items. Block image/chart refs need allowedDir pointing at the folder holding the files (refs stay jailed inside it; without allowedDir they fail closed); remote URL refs fail closed; inline data-URL block images bypass allowedDir by design (bytes decode in memory through the same image gates). Sources compiling past 500 operations apply as sequential 500-operation chunks; the compose is atomic as a whole: when any chunk fails, every chunk before it is rewound and the document stays as it was. Citation numbers and the References list restart in each compose call. Optional template (report|memo|blank) is accepted on the first compose only and requires the open document to still hold that template seed, otherwise composition fails before any write (for a fresh templated document call new_document first, then compose_document with template), and placement is append after existing content except for an unchanged built-in template created in this session. Reopened documents and external templates keep existing content. Returns {ok:true,opCount,appliedCount,revision,createdNodeIds,results,validation:{valid,errorCount,errors}} where createdNodeIds lists new node ids in document order (use them as anchors without re-inspecting) and validation proves the post-compose package state via a read-only OOXML check (save_document re-gates before writing). A compose that drops a non-empty redo stack signals it (redoCleared:true + redoClearedWarning naming the depth): a fresh edit invalidates redo. Optional styleGuide (bundled guide name or guide .md path, jailed like image refs: explicit allowedDir else the session anchor; remote URLs fail closed) replaces the session guide (not a one-batch override: later batches inherit it until another compose replaces it) and skins this compose (table/header-fill, chart-palette, callout, and code defaults apply where ops omit params; explicit params still win). Guides cannot be detached: open a new session to work without a guide. With no guide, compose uses the built-in Default Corporate look (navy table header, bold white header text, striped rows). styleGuide "legacy" gives the older grey header for this call only and is not stored on the session. An italic-only line directly under the opening # title becomes the Subtitle; a [!NOTE]-style line outside a blockquote stays plain text and comes back in warnings. Later batches inherit it, inspect_document shows its compact summary, save_document reports advisory styleWarnings. Unknown names fail with E_VALIDATION naming the available set. Math: $$ ... $$ or \\[ ... \\] blocks become display equations and \\(...\\) becomes inline math (one line, up to 500 characters; refused inside links and table cells). Display blocks are top level only (inside a list item or alert body they fail closed). Optional dollarMath (default false) treats $...$ as inline math; off by default because prices and shell text can look like math. Workflow: open_document -> compose_document -> save_document. Example {"sessionId":"sess_abc","markdown":"# Plan\\n\\n- a\\n- b\\n"} (add "allowedDir":"<dir>" for image/chart refs, "template":"report|memo|blank" to verify the seed). IDs are session-scoped: valid only in the issuing session, must not be stored across sessions. When dc:title is still a template placeholder it is set from the first Title or Heading 1 (titleSetFrom says so); a title already set is kept. persistentIds maps each created paragraph id (md_0003) to the paragraph id the saved file carries, so a reopened session can be addressed with it (tables are renumbered t_001.. by position on reopen).';
+var COMPOSE_DOCUMENT_DESCRIPTION = 'Compose a Markdown string into the open session document (appends after existing content, or at anchor with position before|after; an unchanged built-in template created in this session has its sample content replaced). A document can be built in several compose calls: the first call of a session mints ids md_0001..., later calls mint md2_0001..., md3_0001..., so ids never collide; pass anchor (a node id, start or end) and position to add a section in the middle without another tool. Runs the engine compose path, then applies the resulting operations through the same execute_batch path (strict schema gate, per-chunk quotas, structural checks, per-chunk atomic rollback, then inline-span run splitting), so every gate a batch meets applies here unchanged. Supported input: #/##/### headings (real Heading1..3 styles), blank-line paragraphs (single newlines join with a space), flat bullet (-, *, +) and ordered (1., 1)) lists with real numbering, GitHub-style tables with a header separator row (header row shaded and repeated), --- dividers, fenced or indented code blocks (monospace, line breaks kept), [^label] footnotes with definitions, inline spans (**bold**, *italic*, `code`, [text](url)) applied as runs with real hyperlink targets, plain `> quote` blocks (written in the Quote paragraph style: blank > lines start a new paragraph, > > nests up to 3 levels, flat lists and fenced code are kept inside, a table, heading or image inside a quote fails), and standalone block images/charts (![alt](path)) resolved from allowedDir. Out-of-scope input fails closed with E_VALIDATION plus a 1-based line number and writes nothing: raw HTML (except [!NOTE]-style alert callouts, which compile to callout containers and keep bold, italic, code and links), custom styles, deeper headings, nested lists or tables, task items. Block image/chart refs need allowedDir pointing at the folder holding the files (refs stay jailed inside it; without allowedDir they fail closed); remote URL refs fail closed; inline data-URL block images bypass allowedDir by design (bytes decode in memory through the same image gates). Sources compiling past 500 operations apply as sequential 500-operation chunks; the compose is atomic as a whole: when any chunk fails, every chunk before it is rewound and the document stays as it was. Citation numbers and the References list restart in each compose call. Optional template (report|memo|blank) is accepted on the first compose only and requires the open document to still hold that template seed, otherwise composition fails before any write (to append to an existing document omit template; for a fresh templated document call new_document first, then compose_document with template), and placement is append after existing content except for an unchanged built-in template created in this session. Reopened documents and external templates keep existing content. Returns {ok:true,opCount,appliedCount,revision,createdNodeIds,results,validation:{valid,errorCount,errors}} where createdNodeIds lists new node ids in document order (use them as anchors without re-inspecting) and validation proves the post-compose package state via a read-only OOXML check (save_document re-gates before writing). A compose that drops a non-empty redo stack signals it (redoCleared:true + redoClearedWarning naming the depth): a fresh edit invalidates redo. Optional styleGuide (bundled guide name or guide .md path, jailed like image refs: explicit allowedDir else the session anchor; remote URLs fail closed) replaces the session guide (not a one-batch override: later batches inherit it until another compose replaces it) and skins this compose (table/header-fill, chart-palette, callout, and code defaults apply where ops omit params; explicit params still win). Guides cannot be detached: open a new session to work without a guide. With no guide, compose uses the built-in Default Corporate look (navy table header, bold white header text, striped rows). styleGuide "legacy" gives the older grey header for this call only and is not stored on the session. An italic-only line directly under the opening # title becomes the Subtitle; a [!NOTE]-style line outside a blockquote stays plain text and comes back in warnings. Later batches inherit it, inspect_document shows its compact summary, save_document reports advisory styleWarnings. Unknown names fail with E_VALIDATION naming the available set. Math: $$ ... $$ or \\[ ... \\] blocks become display equations and \\(...\\) becomes inline math (one line, up to 500 characters; refused inside links and table cells). Display blocks are top level only (inside a list item or alert body they fail closed). Optional dollarMath (default false) treats $...$ as inline math; off by default because prices and shell text can look like math. Workflow: open_document -> compose_document -> save_document. Example {"sessionId":"sess_abc","markdown":"# Plan\\n\\n- a\\n- b\\n"} (add "allowedDir":"<dir>" for image/chart refs, "template":"report|memo|blank" to verify the seed). IDs are session-scoped: valid only in the issuing session, must not be stored across sessions. When dc:title is still a template placeholder it is set from the first Title or Heading 1 (titleSetFrom says so); a title already set is kept. persistentIds maps each created paragraph id (md_0003) to the paragraph id the saved file carries, so a reopened session can be addressed with it (tables are renumbered t_001.. by position on reopen).';
 function persistentParagraphIds(ast, createdIds) {
   const wanted = new Set(createdIds);
   const out = {};
@@ -43008,22 +44100,22 @@ function assertPathAllowed(allowedDir, roots) {
       remedy: `Use a folder ${describeAllowedFolders()}.`
     });
   }
-  const resolved = path13.resolve(trimmed);
+  const resolved = path15.resolve(trimmed);
   const canonical = canonicalizeForAsset(resolved);
   const inside = roots.some((root) => {
     let canonicalRoot = root;
     try {
-      canonicalRoot = fs14.realpathSync(root);
+      canonicalRoot = fs16.realpathSync(root);
     } catch {
     }
-    const normC = path13.normalize(canonical);
-    const normR = path13.normalize(canonicalRoot);
+    const normC = path15.normalize(canonical);
+    const normR = path15.normalize(canonicalRoot);
     if (process.platform === "win32") {
       const lc = normC.toLowerCase();
       const lr = normR.toLowerCase();
-      return lc === lr || lc.startsWith(lr + path13.sep.toLowerCase());
+      return lc === lr || lc.startsWith(lr + path15.sep.toLowerCase());
     }
-    return normC === normR || normC.startsWith(normR + path13.sep);
+    return normC === normR || normC.startsWith(normR + path15.sep);
   });
   if (!inside) {
     throw Object.assign(
@@ -43401,8 +44493,8 @@ async function handleExecuteBatch(store, input) {
         const explicit = parsed.data.allowedDir;
         if (explicit !== void 0) {
           batchAllowedDir = assertPathAllowed(explicit, getMcpAllowedRoots());
-        } else if (path14.isAbsolute(handle.filePath)) {
-          batchAllowedDir = canonicalizeForAsset(path14.resolve(path14.dirname(handle.filePath)));
+        } else if (path16.isAbsolute(handle.filePath)) {
+          batchAllowedDir = canonicalizeForAsset(path16.resolve(path16.dirname(handle.filePath)));
         } else {
           throw Object.assign(
             new Error(
@@ -43551,8 +44643,9 @@ async function handleExecuteBatch(store, input) {
 }
 
 // src/lib/mcp/handlers/save-close.ts
-var fsp6 = __toESM(require("fs/promises"));
-var path15 = __toESM(require("path"));
+var import_crypto7 = require("crypto");
+var fsp8 = __toESM(require("fs/promises"));
+var path17 = __toESM(require("path"));
 async function executeSaveDocument(store, input) {
   const parsed = SaveDocumentSchema.safeParse(input);
   if (!parsed.success) {
@@ -43598,18 +44691,18 @@ async function executeSaveDocument(store, input) {
         ),
         {
           code: "E_VALIDATION",
-          remedy: `name the output "${path15.basename(target)}" with a .docm extension, or add stripMacros: true to remove the macro parts`
+          remedy: `name the output "${path17.basename(target)}" with a .docm extension, or add stripMacros: true to remove the macro parts`
         }
       );
     }
     if (isStripped && macroParts.length === 0 && /\.(docm|dotm)$/i.test(target)) {
       throw Object.assign(
         new Error(
-          `E_VALIDATION: save_document: stripMacros removes the macro parts, so the result is a plain document and cannot be written to "${path15.basename(target)}", a macro-enabled name`
+          `E_VALIDATION: save_document: stripMacros removes the macro parts, so the result is a plain document and cannot be written to "${path17.basename(target)}", a macro-enabled name`
         ),
         {
           code: "E_VALIDATION",
-          remedy: `write the result to a .docx with outPath: "${path15.basename(target).replace(/\.docm$/i, ".docx")}", or use allowMacros: true to keep the macro parts in the .docm`
+          remedy: `write the result to a .docx with outPath: "${path17.basename(target).replace(/\.docm$/i, ".docx")}", or use allowMacros: true to keep the macro parts in the .docm`
         }
       );
     }
@@ -43650,19 +44743,22 @@ async function executeSaveDocument(store, input) {
     const saveGateNormalized = readParserNormalizations(handle.parser);
     const buf = handle.parser.rezip();
     const saveNormalized = mergeNormalized(saveGateNormalized, readParserNormalizations(handle.parser));
+    const savedXml = handle.parser.readDocumentXml();
+    const extras = collectTrackedExtrasForGit(handle.parser);
     const prevRevision = handle.revision;
     const prevSavedRevision = handle.savedRevision;
     const prevByteSize = handle.byteSize;
     const prevFilePath = handle.filePath;
     let prevBytes = null;
     try {
-      prevBytes = await fsp6.readFile(target);
+      prevBytes = await fsp8.readFile(target);
     } catch {
       prevBytes = null;
     }
+    await assertHistoryReadyForWrite(target);
     try {
       assertWriteTargetNoSymlink(target);
-      await fsp6.mkdir(pathDirname(target), { recursive: true });
+      await fsp8.mkdir(pathDirname(target), { recursive: true });
       assertWriteTargetNoSymlink(target);
       await writeFileNoFollow(target, buf);
     } catch (err) {
@@ -43673,7 +44769,7 @@ async function executeSaveDocument(store, input) {
         if (prevBytes !== null) {
           await writeFileNoFollow(target, prevBytes);
         } else {
-          await fsp6.unlink(target);
+          await fsp8.unlink(target);
         }
       } catch (restoreErr) {
         diskOk = false;
@@ -43685,8 +44781,6 @@ async function executeSaveDocument(store, input) {
         remedy
       });
     }
-    const savedXml = handle.parser.readDocumentXml();
-    const extras = collectTrackedExtrasForGit(handle.parser);
     const opsSinceSave = handle.revision - handle.savedRevision;
     const fallbackMessage = opsSinceSave <= 0 ? `save_document: rev ${handle.revision} (initial baseline)` : `save_document: rev ${handle.revision} (${opsSinceSave} ops since last save)`;
     const baseMessage = sanitizeCommitMessage(parsed.data.message, fallbackMessage);
@@ -43694,7 +44788,7 @@ async function executeSaveDocument(store, input) {
     const authorName = sanitizeCommitAuthor(parsed.data.author);
     let commitOid;
     try {
-      await ensureGitRepo(target, savedXml, extras);
+      await ensureGitRepo(target, savedXml, extras, prevBytes ?? void 0);
       commitOid = await commitChange(target, savedXml, commitMessage, extras, void 0, authorName);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -43703,7 +44797,7 @@ async function executeSaveDocument(store, input) {
         if (prevBytes !== null) {
           await writeFileNoFollow(target, prevBytes);
         } else {
-          await fsp6.unlink(target);
+          await fsp8.unlink(target);
         }
       } catch (restoreErr) {
         diskOk = false;
@@ -43724,6 +44818,15 @@ async function executeSaveDocument(store, input) {
     }
     try {
       handle.filePath = target;
+      if (prevFilePath !== target || !handle.originalInfo) {
+        handle.originalInfo = await getOriginalInfo(target);
+        handle.originalPin = handle.originalInfo.available ? { kind: "retained", sha256: handle.originalInfo.sha256 } : void 0;
+      }
+      if (prevFilePath !== target) handle.originalWarning = void 0;
+      if (!handle.originalInfo.available && !["predates-feature", "not-applicable"].includes(handle.originalInfo.reason)) {
+        handle.originalWarning = `Exact-original recovery is unavailable: ${handle.originalInfo.reason}. Keep a separate copy of the input file.`;
+      }
+      handle.lastWrittenSha256 = (0, import_crypto7.createHash)("sha256").update(buf).digest("hex");
       handle.byteSize = buf.length;
       const auditNodeIds = [...handle.pendingAudit.nodeIds];
       const auditOps = handle.pendingAudit.ops;
@@ -43761,6 +44864,7 @@ async function executeSaveDocument(store, input) {
       ok: true,
       sessionId: handle.sessionId,
       path: target,
+      ...handle.originalWarning ? { originalWarning: handle.originalWarning } : {},
       revision: handle.revision,
       commitOid,
       commitMessage,
@@ -43830,8 +44934,151 @@ async function handleCloseDocument(store, input) {
   }
 }
 
+// src/lib/mcp/handlers/original.ts
+var fsp9 = __toESM(require("fs/promises"));
+var path18 = __toESM(require("path"));
+var import_crypto8 = require("crypto");
+var hash = (buf) => (0, import_crypto8.createHash)("sha256").update(buf).digest("hex");
+function refuse2(code, message, remedy = "Inspect the file and its history before retrying. Export the original to a new path for recovery without changing this document.") {
+  throw Object.assign(new Error(message), { code, remedy });
+}
+async function requireAvailableOriginal(handle) {
+  const info = await resolveSessionOriginal(handle);
+  if (info.available) return;
+  const detail = info.detail ?? "Close and reopen after checking history.";
+  const remedy = info.reason === "initializing" ? "History initialization for this document has not finished. Call get_document_history again later; the original becomes available once it completes for this same file." : "The retained original cannot be trusted, so no substitute is returned. Keep the working file and any separate backup, and call get_document_history to see the reason.";
+  refuse2("E_CONFLICT", `Exact-original recovery is unavailable to this session (${info.reason}). ${detail}`, remedy);
+}
+async function handleExportOriginalDocument(store, input) {
+  const parsed = ExportOriginalDocumentSchema.safeParse(input);
+  if (!parsed.success) return invalidInput(`export_original_document: ${parsed.error.message}`);
+  try {
+    return await store.withSession(parsed.data.sessionId, async (handle) => {
+      if (!path18.isAbsolute(handle.filePath)) refuse2("E_VALIDATION", "This memory session has no retained original.");
+      await requireAvailableOriginal(handle);
+      const outPath = validateSaveTarget(parsed.data.outPath);
+      if (outPath === handle.filePath) refuse2("E_CONFLICT", "Use restore_original_document to replace the active document.");
+      const original = await exportOriginal(handle.filePath, outPath, { overwrite: parsed.data.overwrite === true });
+      return { ok: true, sessionId: handle.sessionId, path: outPath, original };
+    });
+  } catch (err) {
+    return mcpErrorFrom(err, "E_IO", "Choose a writable output path inside the allowed directory.");
+  }
+}
+async function confirmHistoryCurrent(handle, bytes) {
+  const history = await getHistory(handle.filePath);
+  if (!history[0]) refuse2("E_CONFLICT", "Cannot confirm history is current: there is no recorded head.");
+  const head = await checkoutCommit(handle.filePath, history[0].oid);
+  if (!head.complete) refuse2("E_CONFLICT", "Cannot confirm history is current: the head is not a complete package snapshot. Save the document first.");
+  const parser2 = new DocxParser(bytes, handle.macroPolicy);
+  await parser2.getAST();
+  const snapshot3 = parser2.capturePackageSnapshot();
+  if (parser2.readDocumentXml() !== head.xml) refuse2("E_CONFLICT", "History differs from the current file. Save or revert before restoring the original.");
+  const names = [...snapshot3.keys()].filter(isTrackedPackageFile).sort();
+  const recorded = [...head.extra.keys()].sort();
+  if (JSON.stringify(names) !== JSON.stringify(recorded) || names.some((name2) => !snapshot3.get(name2).equals(head.extra.get(name2)))) {
+    refuse2("E_CONFLICT", "History is behind the file or the file was modified outside ASTra. Save or revert before restoring the original.");
+  }
+  return { oid: history[0].oid, parser: parser2 };
+}
+async function handleRestoreOriginalDocument(store, input) {
+  const parsed = RestoreOriginalDocumentSchema.safeParse(input);
+  if (!parsed.success) return invalidInput(`restore_original_document: ${parsed.error.message}`);
+  try {
+    return await store.withSession(parsed.data.sessionId, async (handle) => {
+      if (!path18.isAbsolute(handle.filePath)) refuse2("E_VALIDATION", "This memory session has no retained original.");
+      await requireAvailableOriginal(handle);
+      if (handle.revision !== handle.savedRevision && !parsed.data.discard) refuse2("E_CONFLICT", "The session has unsaved edits. Save first, or explicitly pass discard:true.");
+      const source = validateSaveTarget(handle.filePath);
+      await assertHistoryReadyForWrite(source);
+      const original = await getOriginalInfo(source);
+      if (!original.available) refuse2("E_NOT_FOUND", `The original is unavailable: ${original.reason}.`);
+      const bytes = await readOriginal(source);
+      const previous = await fsp9.readFile(source);
+      if (!handle.lastWrittenSha256 || hash(previous) !== handle.lastWrittenSha256) refuse2("E_CONFLICT", "The file changed outside ASTra. Reopen it before restoring.");
+      const checked = await confirmHistoryCurrent(handle, previous);
+      const parser2 = new DocxParser(bytes, handle.macroPolicy);
+      const ast = await parser2.getAST();
+      const engine = new OperationEngine(ast, parser2);
+      if (handle.styleGuide) engine.setStyleGuide(handle.styleGuide);
+      const validation = await validateForBaseline(bytes);
+      const backup = newRestoreBackupPath(source);
+      await createVerifiedBackup(backup, previous);
+      const historyBefore = await captureHistoryState(source);
+      const oldRedo = Array.from(handle.redoStack);
+      const previousSession = {
+        parser: handle.parser,
+        ast: handle.ast,
+        engine: handle.engine,
+        toon: handle.toon,
+        revision: handle.revision,
+        savedRevision: handle.savedRevision,
+        byteSize: handle.byteSize,
+        lastWrittenSha256: handle.lastWrittenSha256,
+        validationBaseline: handle.validationBaseline,
+        pendingAudit: { ops: handle.pendingAudit.ops, nodeIds: [...handle.pendingAudit.nodeIds] }
+      };
+      let replaced = false;
+      let commitAttempted = false;
+      let commitOid;
+      let durabilityUnconfirmed = false;
+      try {
+        handle.redoStack.length = 0;
+        try {
+          handle.redoStack.push((parsed.data.discard ? checked.parser : handle.parser).capturePackageSnapshot());
+        } catch (quota) {
+          if (quota?.code !== "E_QUOTA") throw quota;
+        }
+        if (hash(await fsp9.readFile(source)) !== hash(previous)) refuse2("E_CONFLICT", "The file changed while restore was being prepared.");
+        const write = await replaceFileAtomic(source, bytes);
+        replaced = true;
+        durabilityUnconfirmed = write.durabilityUnconfirmed === true;
+        commitAttempted = true;
+        commitOid = await commitChange(source, parser2.readDocumentXml(), `Restore original file (sha256 ${hash(bytes)})`, collectTrackedExtrasForGit(parser2));
+        handle.parser = parser2;
+        handle.ast = ast;
+        handle.engine = engine;
+        handle.toon = new ToonGenerator();
+        handle.byteSize = bytes.length;
+        store.bumpRevision(handle);
+        store.markSaved(handle);
+        handle.lastWrittenSha256 = hash(bytes);
+        adoptBaseline(handle, validation);
+      } catch (err) {
+        Object.assign(handle, previousSession);
+        handle.redoStack.length = 0;
+        Array.prototype.push.apply(handle.redoStack, oldRedo);
+        const { recovered: diskRecovered, failure: rollbackFailure } = await rollbackReplacedFile(source, previous, { replaced, error: err });
+        const rollbackError = rollbackFailure ?? "";
+        const historyChanged = commitAttempted && await historyChangedSince(source, historyBefore);
+        if (diskRecovered) await fsp9.unlink(backup).catch(() => void 0);
+        const detail = `${String(err instanceof Error ? err.message : err)}${historyChanged ? " History may have changed despite the failed commit; inspect history before continuing." : ""}${diskRecovered ? "" : ` Rollback failed (${rollbackError}); recovery bytes are retained at ${backup}.`}`;
+        throw Object.assign(new Error(detail), {
+          code: err?.code ?? "E_IO",
+          remedy: diskRecovered ? "Inspect the file and history before retrying." : `Recover from ${backup} before editing further.`
+        });
+      }
+      const cleanupFailed = await fsp9.unlink(backup).then(() => false, () => true);
+      return {
+        ok: true,
+        sessionId: handle.sessionId,
+        path: source,
+        revision: handle.revision,
+        dirty: false,
+        commitOid,
+        original,
+        ...durabilityUnconfirmed ? { durabilityUnconfirmed: true } : {},
+        ...cleanupFailed ? { warning: `Restore succeeded but the temporary recovery backup could not be removed: ${backup}` } : {}
+      };
+    });
+  } catch (err) {
+    return mcpErrorFrom(err, "E_IO", "Inspect the document and history; export the original to a new path if in-place restore is unavailable.");
+  }
+}
+
 // src/lib/mcp/handlers/history.ts
-var fsp7 = __toESM(require("fs/promises"));
+var import_crypto9 = require("crypto");
+var fsp10 = __toESM(require("fs/promises"));
 async function handleGetDocumentHistory(store, input) {
   const parsed = GetDocumentHistorySchema.safeParse(input);
   if (!parsed.success) {
@@ -43858,7 +45105,21 @@ async function handleGetDocumentHistory(store, input) {
           currentCommit: null,
           totalCommits: 0,
           history: [],
-          warning: emptyWarning
+          warning: emptyWarning,
+          original: await resolveSessionOriginal(handle)
+        };
+      }
+      const original = await resolveSessionOriginal(handle);
+      if (!original.available && original.reason === "initializing") {
+        return {
+          ok: true,
+          sessionId,
+          documentPath: filePath,
+          currentCommit: null,
+          totalCommits: 0,
+          history: [],
+          warning: original.detail ?? "History initialization has not completed.",
+          original
         };
       }
       const full = await getHistory(filePath);
@@ -43892,7 +45153,10 @@ async function handleGetDocumentHistory(store, input) {
         currentCommit: full.length > 0 ? full[0].oid : null,
         totalCommits: full.length,
         history: slice,
-        warning
+        warning,
+        // Recovery status was re-verified above against what this session pinned at open, so a corrupted or
+        // replaced original is not reported as available and another history's original is never adopted.
+        original
       };
     });
   } catch (err) {
@@ -43994,7 +45258,7 @@ async function handleRevertDocument(store, input) {
       const prevByteSize = handle.byteSize;
       let prevFileBytes = null;
       try {
-        prevFileBytes = await fsp7.readFile(handle.filePath);
+        prevFileBytes = await fsp10.readFile(handle.filePath);
       } catch {
         prevFileBytes = null;
       }
@@ -44017,6 +45281,7 @@ async function handleRevertDocument(store, input) {
           truncated: false
         };
       }
+      await assertHistoryReadyForWrite(handle.filePath);
       let target;
       try {
         target = await checkoutCommit(handle.filePath, targetOid);
@@ -44046,7 +45311,7 @@ async function handleRevertDocument(store, input) {
         }
         assertWriteTargetNoSymlink(handle.filePath);
         writeAttempted = true;
-        await fsp7.mkdir(pathDirname(handle.filePath), { recursive: true });
+        await fsp10.mkdir(pathDirname(handle.filePath), { recursive: true });
         assertWriteTargetNoSymlink(handle.filePath);
         await writeFileNoFollow(handle.filePath, buf);
         handle.byteSize = buf.length;
@@ -44075,6 +45340,7 @@ async function handleRevertDocument(store, input) {
           affectedNodeIds: diffIdTexts(liveBefore.texts, liveAfter.order, liveAfter.texts)
         });
         store.markSaved(handle);
+        handle.lastWrittenSha256 = (0, import_crypto9.createHash)("sha256").update(buf).digest("hex");
         adoptBaseline(handle, candidate);
         return {
           ok: true,
@@ -44110,7 +45376,7 @@ async function handleRevertDocument(store, input) {
             if (prevFileBytes !== null) {
               await writeFileNoFollow(handle.filePath, prevFileBytes);
             } else {
-              await fsp7.unlink(handle.filePath);
+              await fsp10.unlink(handle.filePath);
             }
           } catch (restoreErr) {
             diskOk = false;
@@ -44167,6 +45433,7 @@ async function handleRedoDocument(store, input) {
       const redoReasonProvided = "reason" in rawRedo && parsed.data.reason !== void 0;
       const redoReasonText = redoReasonProvided ? sanitizeCommitMessage(parsed.data.reason, "") : "";
       const authorName = sanitizeCommitAuthor(parsed.data.author);
+      await assertHistoryReadyForWrite(handle.filePath);
       const redoBefore = collectAstIdTexts(handle.ast);
       const prevRevision = handle.revision;
       const prevSavedRevision = handle.savedRevision;
@@ -44174,7 +45441,7 @@ async function handleRedoDocument(store, input) {
       const preRedoSnap = handle.parser.capturePackageSnapshot();
       let prevFileBytes = null;
       try {
-        prevFileBytes = await fsp7.readFile(handle.filePath);
+        prevFileBytes = await fsp10.readFile(handle.filePath);
       } catch {
         prevFileBytes = null;
       }
@@ -44194,7 +45461,7 @@ async function handleRedoDocument(store, input) {
         didPop = true;
         assertWriteTargetNoSymlink(handle.filePath);
         writeAttempted = true;
-        await fsp7.mkdir(pathDirname(handle.filePath), { recursive: true });
+        await fsp10.mkdir(pathDirname(handle.filePath), { recursive: true });
         assertWriteTargetNoSymlink(handle.filePath);
         await writeFileNoFollow(handle.filePath, buf);
         handle.byteSize = buf.length;
@@ -44227,6 +45494,7 @@ async function handleRedoDocument(store, input) {
           affectedNodeIds: diffIdTexts(redoBefore.texts, redoAfter.order, redoAfter.texts)
         });
         store.markSaved(handle);
+        handle.lastWrittenSha256 = (0, import_crypto9.createHash)("sha256").update(buf).digest("hex");
         adoptBaseline(handle, candidate);
         return {
           ok: true,
@@ -44261,7 +45529,7 @@ async function handleRedoDocument(store, input) {
             if (prevFileBytes !== null) {
               await writeFileNoFollow(handle.filePath, prevFileBytes);
             } else {
-              await fsp7.unlink(handle.filePath);
+              await fsp10.unlink(handle.filePath);
             }
           } catch (restoreErr) {
             diskOk = false;
@@ -44455,6 +45723,8 @@ async function handlePreviewRevert(store, input) {
   }
 }
 var GIT_HISTORY_HANDLERS = {
+  export_original_document: handleExportOriginalDocument,
+  restore_original_document: handleRestoreOriginalDocument,
   get_document_history: handleGetDocumentHistory,
   preview_revert: handlePreviewRevert,
   revert_document: handleRevertDocument,
@@ -44502,9 +45772,9 @@ function adoptForkNumbering(fork, ast) {
 }
 
 // src/tools/export.ts
-var fs15 = __toESM(require("fs"));
-var fsp8 = __toESM(require("fs/promises"));
-var path16 = __toESM(require("path"));
+var fs17 = __toESM(require("fs"));
+var fsp11 = __toESM(require("fs/promises"));
+var path19 = __toESM(require("path"));
 var ExportDocumentSchema = import_zod6.z.object({
   sessionId: import_zod6.z.string().describe("Active document session ID returned by open_document"),
   format: import_zod6.z.enum(["html", "markdown", "md", "pdf"]).describe('Target export format: "html", "markdown", "md", or "pdf"'),
@@ -44560,18 +45830,18 @@ function validateExportTarget(rawPath, expectedFormat) {
       remedy: "Use a path inside the workspace documents directory."
     });
   }
-  const resolved = path16.resolve(trimmed);
+  const resolved = path19.resolve(trimmed);
   const canonical = canonicalizeForAsset(resolved);
   const allowedRoots = getMcpAllowedRoots();
   const isInside2 = allowedRoots.some((root) => {
     let canonicalRoot = root;
     try {
-      canonicalRoot = fs15.realpathSync(root);
+      canonicalRoot = fs17.realpathSync(root);
     } catch {
     }
-    const normC = path16.normalize(canonical);
-    const normR = path16.normalize(canonicalRoot);
-    return normC === normR || normC.startsWith(normR + path16.sep);
+    const normC = path19.normalize(canonical);
+    const normR = path19.normalize(canonicalRoot);
+    return normC === normR || normC.startsWith(normR + path19.sep);
   });
   if (!isInside2) {
     throw Object.assign(
@@ -44582,7 +45852,7 @@ function validateExportTarget(rawPath, expectedFormat) {
       }
     );
   }
-  const ext = path16.extname(trimmed).toLowerCase();
+  const ext = path19.extname(trimmed).toLowerCase();
   const validExts = {
     html: [".html", ".htm"],
     markdown: [".md", ".markdown"],
@@ -44626,18 +45896,18 @@ function validateAssetTarget(rawPath) {
       remedy: "Use a path inside the workspace documents directory."
     });
   }
-  const resolved = path16.resolve(trimmed);
+  const resolved = path19.resolve(trimmed);
   const canonical = canonicalizeForAsset(resolved);
   const allowedRoots = getMcpAllowedRoots();
   const isInside2 = allowedRoots.some((root) => {
     let canonicalRoot = root;
     try {
-      canonicalRoot = fs15.realpathSync(root);
+      canonicalRoot = fs17.realpathSync(root);
     } catch {
     }
-    const normC = path16.normalize(canonical);
-    const normR = path16.normalize(canonicalRoot);
-    return normC === normR || normC.startsWith(normR + path16.sep);
+    const normC = path19.normalize(canonical);
+    const normR = path19.normalize(canonicalRoot);
+    return normC === normR || normC.startsWith(normR + path19.sep);
   });
   if (!isInside2) {
     throw Object.assign(
@@ -44737,7 +46007,7 @@ async function handleExportDocument(store, rawArgs) {
   }
   let validatedPdfPath;
   if (format === "pdf") {
-    if (!hasPdfBackend()) {
+    if (!hasPdfBackend2()) {
       return {
         ok: false,
         code: "E_DEPENDENCY",
@@ -44745,7 +46015,7 @@ async function handleExportDocument(store, rawArgs) {
         remedy: "Install LibreOffice on the host system: sudo apt install libreoffice (Linux) or brew install --cask libreoffice (macOS)."
       };
     }
-    const defaultPdf = targetPath || path16.join(path16.dirname(session.filePath), `${path16.basename(session.filePath, path16.extname(session.filePath))}.pdf`);
+    const defaultPdf = targetPath || path19.join(path19.dirname(session.filePath), `${path19.basename(session.filePath, path19.extname(session.filePath))}.pdf`);
     try {
       validatedPdfPath = validateExportTarget(defaultPdf, "pdf");
     } catch (err) {
@@ -44784,7 +46054,7 @@ async function handleExportDocument(store, rawArgs) {
         }
         throw original;
       }
-      const stat3 = await fsp8.stat(validatedPdfPath);
+      const stat3 = await fsp11.stat(validatedPdfPath);
       return {
         ok: true,
         format: "pdf",
@@ -44798,22 +46068,22 @@ async function handleExportDocument(store, rawArgs) {
     }
     const ast = session.ast;
     if (format === "html") {
-      const title = htmlDocumentTitle(ast, path16.basename(session.filePath, path16.extname(session.filePath)));
+      const title = htmlDocumentTitle(ast, path19.basename(session.filePath, path19.extname(session.filePath)));
       const html = convertAstToHtml(ast, title, void 0, session.parser);
       if (targetPath) {
         assertWriteTargetNoSymlink(targetPath);
-        await fsp8.mkdir(path16.dirname(targetPath), { recursive: true });
+        await fsp11.mkdir(path19.dirname(targetPath), { recursive: true });
         assertWriteTargetNoSymlink(targetPath);
         await writeFileNoFollow(targetPath, html, "utf-8");
-        const stat3 = await fsp8.stat(targetPath);
+        const stat3 = await fsp11.stat(targetPath);
         return { ok: true, format: "html", path: targetPath, bytes: stat3.size, dirty, revision };
       }
       return { ok: true, format: "html", content: html, bytes: Buffer.byteLength(html, "utf-8"), dirty, revision };
     } else {
       const effectiveImageMode = parsed.data.imageMode ?? (targetPath ? "file" : "embed");
-      const docBase = path16.basename(
+      const docBase = path19.basename(
         targetPath || session.filePath || "document.docx",
-        path16.extname(targetPath || session.filePath || "document.docx")
+        path19.extname(targetPath || session.filePath || "document.docx")
       ) || "document";
       const safeDocBase = docBase.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^\.+/, "").slice(0, 120) || "document";
       const defaultAssetPrefix = `${safeDocBase}_assets`;
@@ -44821,39 +46091,39 @@ async function handleExportDocument(store, rawArgs) {
       if (effectiveImageMode === "file") {
         const initialAssets = collectMarkdownImageAssets(ast, effectiveAssetPrefix);
         if (!targetPath) throw new Error("Markdown file image mode requires an output path.");
-        const destDir = path16.dirname(targetPath);
+        const destDir = path19.dirname(targetPath);
         let generation;
         let staging;
         let published = false;
         try {
           assertWriteTargetNoSymlink(targetPath);
-          await fsp8.mkdir(destDir, { recursive: true });
+          await fsp11.mkdir(destDir, { recursive: true });
           assertWriteTargetNoSymlink(targetPath);
           let outputPrefix = effectiveAssetPrefix;
           if (initialAssets.length > 0) {
-            const prefixDir = validateAssetTarget(path16.resolve(destDir, effectiveAssetPrefix));
+            const prefixDir = validateAssetTarget(path19.resolve(destDir, effectiveAssetPrefix));
             assertWriteTargetNoSymlink(prefixDir);
-            await fsp8.mkdir(prefixDir, { recursive: true });
+            await fsp11.mkdir(prefixDir, { recursive: true });
             assertWriteTargetNoSymlink(prefixDir);
-            generation = await fsp8.mkdtemp(path16.join(prefixDir, "export-"));
+            generation = await fsp11.mkdtemp(path19.join(prefixDir, "export-"));
             assertWriteTargetNoSymlink(generation);
-            outputPrefix = path16.relative(destDir, generation).split(path16.sep).join("/");
+            outputPrefix = path19.relative(destDir, generation).split(path19.sep).join("/");
           }
           const md = convertAstToMarkdown(ast, session.parser, { imageMode: "file", assetPrefix: outputPrefix });
           const imageAssets = collectMarkdownImageAssets(ast, outputPrefix);
           const writtenAssets = [];
           for (const asset of imageAssets) {
-            const assetPath = validateAssetTarget(path16.resolve(destDir, asset.name));
+            const assetPath = validateAssetTarget(path19.resolve(destDir, asset.name));
             assertWriteTargetNoSymlink(assetPath);
             await writeFileNoFollow(assetPath, asset.data);
             writtenAssets.push(assetPath);
           }
-          staging = await fsp8.mkdtemp(path16.join(destDir, ".astra-export-"));
-          const stagedFile = path16.join(staging, "document.md");
+          staging = await fsp11.mkdtemp(path19.join(destDir, ".astra-export-"));
+          const stagedFile = path19.join(staging, "document.md");
           assertWriteTargetNoSymlink(stagedFile);
           await writeFileNoFollow(stagedFile, md, "utf-8");
           assertWriteTargetNoSymlink(targetPath);
-          await fsp8.rename(stagedFile, targetPath);
+          await fsp11.rename(stagedFile, targetPath);
           published = true;
           return {
             ok: true,
@@ -44868,17 +46138,17 @@ async function handleExportDocument(store, rawArgs) {
             assetCount: writtenAssets.length
           };
         } finally {
-          if (staging) await fsp8.rm(staging, { recursive: true, force: true }).catch(() => void 0);
-          if (!published && generation) await fsp8.rm(generation, { recursive: true, force: true }).catch(() => void 0);
+          if (staging) await fsp11.rm(staging, { recursive: true, force: true }).catch(() => void 0);
+          if (!published && generation) await fsp11.rm(generation, { recursive: true, force: true }).catch(() => void 0);
         }
       } else {
         const md = convertAstToMarkdown(ast, session.parser, { imageMode: "embed" });
         if (targetPath) {
           assertWriteTargetNoSymlink(targetPath);
-          await fsp8.mkdir(path16.dirname(targetPath), { recursive: true });
+          await fsp11.mkdir(path19.dirname(targetPath), { recursive: true });
           assertWriteTargetNoSymlink(targetPath);
           await writeFileNoFollow(targetPath, md, "utf-8");
-          const stat3 = await fsp8.stat(targetPath);
+          const stat3 = await fsp11.stat(targetPath);
           return {
             ok: true,
             format: "markdown",
@@ -44916,8 +46186,8 @@ async function handleExportDocument(store, rawArgs) {
 }
 
 // src/tools/visual.ts
-var fs16 = __toESM(require("fs"));
-var path17 = __toESM(require("path"));
+var fs18 = __toESM(require("fs"));
+var path20 = __toESM(require("path"));
 var import_zod7 = require("zod");
 function visualError(code, message, remedy) {
   return { ok: false, code, message, remedy };
@@ -45065,14 +46335,14 @@ function serializeSessionCopy2(parser2, ast) {
   return fork.rezip();
 }
 function placeImages(images, dir, docPath) {
-  fs16.mkdirSync(dir, { recursive: true });
-  const base = path17.basename(docPath || "document", path17.extname(docPath || "")).replace(/[^a-zA-Z0-9._-]+/g, "-") || "document";
+  fs18.mkdirSync(dir, { recursive: true });
+  const base = path20.basename(docPath || "document", path20.extname(docPath || "")).replace(/[^a-zA-Z0-9._-]+/g, "-") || "document";
   return images.map((img) => {
-    const ext = path17.extname(img.path) || (img.format === "jpeg" ? ".jpg" : ".png");
-    const dest = path17.join(dir, `${base}-page-${img.page}${ext}`);
-    writeFileNoFollowSync(dest, fs16.readFileSync(img.path));
+    const ext = path20.extname(img.path) || (img.format === "jpeg" ? ".jpg" : ".png");
+    const dest = path20.join(dir, `${base}-page-${img.page}${ext}`);
+    writeFileNoFollowSync(dest, fs18.readFileSync(img.path));
     try {
-      fs16.rmSync(img.path, { force: true });
+      fs18.rmSync(img.path, { force: true });
     } catch {
     }
     return { ...img, path: dest };
@@ -45199,8 +46469,8 @@ async function handleVisualInspect(store, input) {
 
 // src/tools/new-document.ts
 var import_zod8 = require("zod");
-var fsp9 = __toESM(require("fs/promises"));
-var path18 = __toESM(require("path"));
+var fsp12 = __toESM(require("fs/promises"));
+var path21 = __toESM(require("path"));
 var NEW_DOCUMENT_TEMPLATES = ["report", "memo", "blank"];
 var NewDocumentSchema = import_zod8.z.object({
   outPath: import_zod8.z.string().min(1).max(1024),
@@ -45276,10 +46546,10 @@ async function handleNewDocument(store, rawArgs) {
   }
   if (!force) {
     try {
-      await fsp9.access(target);
+      await fsp12.access(target);
       return newDocError(
         "E_CONFLICT",
-        `new_document: destination "${path18.basename(target)}" already exists (refusing to overwrite without force)`,
+        `new_document: destination "${path21.basename(target)}" already exists (refusing to overwrite without force)`,
         'Retry with {"force":true} to overwrite, or choose a different outPath.'
       );
     } catch {
@@ -45330,7 +46600,7 @@ async function handleNewDocument(store, rawArgs) {
   }
   try {
     assertWriteTargetNoSymlink(target);
-    await fsp9.mkdir(path18.dirname(target), { recursive: true });
+    await fsp12.mkdir(path21.dirname(target), { recursive: true });
     assertWriteTargetNoSymlink(target);
     await writeFileNoFollow(target, buf);
   } catch (err) {
@@ -45342,12 +46612,12 @@ async function handleNewDocument(store, rawArgs) {
     );
   }
   try {
-    const handle = await store.openDocument(target, parsed.data.sessionId);
+    const handle = await store.openDocument(target, parsed.data.sessionId, void 0, false);
     handle.parser.adoptBuiltinSeedFrom(parser2);
     if (parsed.data.author !== void 0) handle.ast.settings.defaultAuthor = parsed.data.author;
     let bytes = buf.length;
     try {
-      bytes = (await fsp9.stat(target)).size;
+      bytes = (await fsp12.stat(target)).size;
     } catch {
     }
     if (guideRef !== void 0 && resolvedGuide !== void 0) {
@@ -45377,8 +46647,8 @@ async function handleNewDocument(store, rawArgs) {
 }
 
 // src/lib/mcp/handlers/parity.ts
-var fs17 = __toESM(require("fs"));
-var path19 = __toESM(require("path"));
+var fs19 = __toESM(require("fs"));
+var path22 = __toESM(require("path"));
 var IMPORT_FILE_MAX_BYTES = COMPOSE_MARKDOWN_MAX;
 async function refreshSessionAst(handle) {
   await refreshAstInPlace(handle.ast, handle.parser);
@@ -45463,7 +46733,8 @@ async function handleGetStats(store, input) {
         tables: stats.tables,
         callouts: stats.callouts,
         images: stats.images,
-        pages: stats.pages
+        pages: stats.pages,
+        pageTerms: roundedPageTerms(stats.pageTerms)
       };
     });
   } catch (err) {
@@ -45633,17 +46904,17 @@ function readImportMarkdownFile(rawPath, roots = getMcpAllowedRoots()) {
   if (segments.includes("..")) {
     throw toError("E_SANDBOX", 'import path contains forbidden ".." traversal', "Use a path inside the workspace documents directory.");
   }
-  const resolved = path19.resolve(trimmed);
+  const resolved = path22.resolve(trimmed);
   const canonical = canonicalizeForAsset(resolved);
   const inside = roots.some((root) => {
     let canonicalRoot = root;
     try {
-      canonicalRoot = fs17.realpathSync(root);
+      canonicalRoot = fs19.realpathSync(root);
     } catch {
     }
-    const normC = path19.normalize(canonical);
-    const normR = path19.normalize(canonicalRoot);
-    return normC === normR || normC.startsWith(normR + path19.sep);
+    const normC = path22.normalize(canonical);
+    const normR = path22.normalize(canonicalRoot);
+    return normC === normR || normC.startsWith(normR + path22.sep);
   });
   if (!inside) {
     throw toError(
@@ -45652,12 +46923,12 @@ function readImportMarkdownFile(rawPath, roots = getMcpAllowedRoots()) {
       "Place the Markdown file inside one of the allowed directories, or name its folder with --allowed-dir or ASTRA_EXTRA_DOC_ROOTS."
     );
   }
-  const base = path19.basename(canonical);
-  const nofollow = fs17.constants.O_NOFOLLOW;
-  const flags = typeof nofollow === "number" && nofollow !== 0 ? fs17.constants.O_RDONLY | nofollow : "r";
+  const base = path22.basename(canonical);
+  const nofollow = fs19.constants.O_NOFOLLOW;
+  const flags = typeof nofollow === "number" && nofollow !== 0 ? fs19.constants.O_RDONLY | nofollow : "r";
   let fd;
   try {
-    fd = fs17.openSync(canonical, flags);
+    fd = fs19.openSync(canonical, flags);
   } catch (err) {
     const code = err?.code;
     if (code === "ENOENT") {
@@ -45669,7 +46940,7 @@ function readImportMarkdownFile(rawPath, roots = getMcpAllowedRoots()) {
     throw toError("E_IO", `import file cannot be read (${base})`, "Check the file exists and is readable, then retry.");
   }
   try {
-    const st = fs17.fstatSync(fd);
+    const st = fs19.fstatSync(fd);
     if (!st.isFile()) {
       throw toError("E_IO", `import reference is not a file (${base})`, "Point the import at a regular Markdown file.");
     }
@@ -45683,7 +46954,7 @@ function readImportMarkdownFile(rawPath, roots = getMcpAllowedRoots()) {
         "Split the Markdown source into smaller files and import each in its own call."
       );
     }
-    const buf = fs17.readFileSync(fd);
+    const buf = fs19.readFileSync(fd);
     if (buf.length > IMPORT_FILE_MAX_BYTES) {
       throw toError(
         "E_LIMIT",
@@ -45693,18 +46964,18 @@ function readImportMarkdownFile(rawPath, roots = getMcpAllowedRoots()) {
     }
     let post = canonical;
     try {
-      post = fs17.realpathSync(canonical);
+      post = fs19.realpathSync(canonical);
     } catch {
     }
     const stillInside = roots.some((root) => {
       let canonicalRoot = root;
       try {
-        canonicalRoot = fs17.realpathSync(root);
+        canonicalRoot = fs19.realpathSync(root);
       } catch {
       }
-      const normC = path19.normalize(post);
-      const normR = path19.normalize(canonicalRoot);
-      return normC === normR || normC.startsWith(normR + path19.sep);
+      const normC = path22.normalize(post);
+      const normR = path22.normalize(canonicalRoot);
+      return normC === normR || normC.startsWith(normR + path22.sep);
     });
     if (!stillInside) {
       throw toError("E_SANDBOX", "import path points outside the allowed directory", `Keep Markdown files ${describeAllowedFolders()}.`);
@@ -45712,7 +46983,7 @@ function readImportMarkdownFile(rawPath, roots = getMcpAllowedRoots()) {
     return buf.toString("utf8");
   } finally {
     try {
-      if (fd !== void 0) fs17.closeSync(fd);
+      if (fd !== void 0) fs19.closeSync(fd);
     } catch {
     }
   }
@@ -45728,12 +46999,12 @@ async function handleImportDocument(store, input) {
       remedy: 'Retry with {"sessionId":"<id from open_document>","path":"<allowed-dir>/file.md"} (optional allowedDir for image refs, optional template report|memo|blank, optional styleGuide).'
     };
   }
-  const srcExt = path19.extname(parsed.data.path).toLowerCase();
+  const srcExt = path22.extname(parsed.data.path).toLowerCase();
   if (srcExt === ".html" || srcExt === ".htm") {
     return {
       ok: false,
       code: "E_VALIDATION",
-      message: `HTML import is not supported directly ("${path19.basename(parsed.data.path)}")`,
+      message: `HTML import is not supported directly ("${path22.basename(parsed.data.path)}")`,
       remedy: "ASTra imports Markdown (.md). Convert the HTML file to Markdown or supply a .md document"
     };
   }
@@ -45741,7 +47012,7 @@ async function handleImportDocument(store, input) {
     return {
       ok: false,
       code: "E_VALIDATION",
-      message: `import_document cannot ingest .docx files ("${path19.basename(parsed.data.path)}"): open .docx files directly with open_document instead`,
+      message: `import_document cannot ingest .docx files ("${path22.basename(parsed.data.path)}"): open .docx files directly with open_document instead`,
       remedy: "Call open_document with the .docx path to work with it, or convert it to Markdown first and import the .md file."
     };
   }
@@ -45777,15 +47048,15 @@ async function handleImportDocument(store, input) {
 }
 
 // src/lib/mcp/schema-dump.ts
-var fs18 = __toESM(require("fs"));
-var path20 = __toESM(require("path"));
+var fs20 = __toESM(require("fs"));
+var path23 = __toESM(require("path"));
 var import_zod9 = require("zod");
 
 // package.json
 var package_default = {
   name: "@attentionform/astra-mcp-server",
   mcpName: "com.attentionform/astra-mcp-server",
-  version: "0.4.2",
+  version: "0.5.1",
   description: "Official Model Context Protocol (MCP) server for ASTra document IDE",
   main: "dist/index.js",
   types: "dist/index.d.ts",
@@ -45826,8 +47097,8 @@ var package_default = {
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   dependencies: {
-    "@attentionform/astra-engine": "^0.4.2",
-    "@attentionform/ooxml-validator": "^0.4.2",
+    "@attentionform/astra-engine": "^0.5.1",
+    "@attentionform/ooxml-validator": "^0.5.1",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",
@@ -45872,6 +47143,8 @@ function getToolDefinitions() {
     { name: "compose_document", description: COMPOSE_DOCUMENT_DESCRIPTION, schema: ComposeDocumentSchema },
     { name: "export_document", description: EXPORT_DOCUMENT_DESCRIPTION, schema: ExportDocumentSchema },
     { name: "visual_inspect", description: VISUAL_INSPECT_DESCRIPTION, schema: VisualInspectSchema },
+    { name: "export_original_document", description: GIT_HISTORY_DESCRIPTIONS.export_original_document, schema: ExportOriginalDocumentSchema },
+    { name: "restore_original_document", description: GIT_HISTORY_DESCRIPTIONS.restore_original_document, schema: RestoreOriginalDocumentSchema },
     { name: "get_document_history", description: GIT_HISTORY_DESCRIPTIONS.get_document_history, schema: GetDocumentHistorySchema },
     { name: "preview_revert", description: GIT_HISTORY_DESCRIPTIONS.preview_revert, schema: PreviewRevertSchema },
     { name: "revert_document", description: GIT_HISTORY_DESCRIPTIONS.revert_document, schema: RevertDocumentSchema },
@@ -45892,8 +47165,8 @@ function compactToolSchema(schema) {
   return raw;
 }
 function generateSchemasToDir(targetDir, version = getServerVersion()) {
-  if (!fs18.existsSync(targetDir)) {
-    fs18.mkdirSync(targetDir, { recursive: true });
+  if (!fs20.existsSync(targetDir)) {
+    fs20.mkdirSync(targetDir, { recursive: true });
   }
   const stamp2 = buildStamp(version);
   const written = [];
@@ -45905,8 +47178,8 @@ function generateSchemasToDir(targetDir, version = getServerVersion()) {
       parameters: raw,
       [SCHEMA_STAMP_KEY]: stamp2
     };
-    const filePath = path20.join(targetDir, `${tool.name}.json`);
-    fs18.writeFileSync(filePath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+    const filePath = path23.join(targetDir, `${tool.name}.json`);
+    fs20.writeFileSync(filePath, JSON.stringify(payload, null, 2) + "\n", "utf8");
     written.push(filePath);
   }
   return { written, count: written.length };
@@ -45916,11 +47189,11 @@ function checkSchemasInDir(dir, expectedVersion2 = getServerVersion()) {
   const mismatches = [];
   let checked = 0;
   for (const tool of getToolDefinitions()) {
-    const file = path20.join(dir, `${tool.name}.json`);
+    const file = path23.join(dir, `${tool.name}.json`);
     checked += 1;
     let stamped = "<missing>";
     try {
-      const raw = JSON.parse(fs18.readFileSync(file, "utf8"));
+      const raw = JSON.parse(fs20.readFileSync(file, "utf8"));
       const value = raw[SCHEMA_STAMP_KEY];
       stamped = typeof value === "string" ? value : "<unstamped>";
     } catch {
@@ -45933,7 +47206,7 @@ function checkSchemasInDir(dir, expectedVersion2 = getServerVersion()) {
   return { ok: mismatches.length === 0, mismatches, checked };
 }
 function formatMismatchWarning(mismatches) {
-  const lines = mismatches.map((m) => `  ${path20.basename(m.file)}: stamped ${m.stamped}, installed ${m.expected}`);
+  const lines = mismatches.map((m) => `  ${path23.basename(m.file)}: stamped ${m.stamped}, installed ${m.expected}`);
   return "Schema cache is stale: regenerated wire schemas differ from the installed server. Refresh file-based client copies with `astra-mcp-server --dump-schemas <dir>` and restart memory-cached clients.\n" + lines.join("\n");
 }
 
@@ -46000,20 +47273,20 @@ function buildUsageText() {
 var CLI_USAGE_ERROR = 2;
 function initAllowedDirs(argv = process.argv) {
   const currentRoots = new Set(
-    (process.env.ASTRA_EXTRA_DOC_ROOTS || "").split(path21.delimiter).map((p) => p.trim()).filter(Boolean)
+    (process.env.ASTRA_EXTRA_DOC_ROOTS || "").split(path24.delimiter).map((p) => p.trim()).filter(Boolean)
   );
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--") break;
     if (argv[i] === "--allowed-dir" && argv[i + 1] && !argv[i + 1].startsWith("-")) {
-      currentRoots.add(path21.resolve(argv[i + 1]));
+      currentRoots.add(path24.resolve(argv[i + 1]));
       i++;
     } else if (argv[i].startsWith("--allowed-dir=")) {
       const value = argv[i].slice("--allowed-dir=".length).trim();
-      if (value && !value.startsWith("-")) currentRoots.add(path21.resolve(value));
+      if (value && !value.startsWith("-")) currentRoots.add(path24.resolve(value));
     }
   }
   if (currentRoots.size > 0) {
-    process.env.ASTRA_EXTRA_DOC_ROOTS = Array.from(currentRoots).join(path21.delimiter);
+    process.env.ASTRA_EXTRA_DOC_ROOTS = Array.from(currentRoots).join(path24.delimiter);
   }
 }
 function takeDirFlag(argv, flag) {
@@ -46079,6 +47352,16 @@ function createAstraMcpServer(store = createMcpSessionStore()) {
     },
     async (args) => toTextResult(await handleVisualInspect(store, args))
   );
+  server.registerTool(
+    "export_original_document",
+    { description: GIT_HISTORY_DESCRIPTIONS.export_original_document, inputSchema: ExportOriginalDocumentSchema },
+    async (args) => toTextResult(await GIT_HISTORY_HANDLERS.export_original_document(store, args))
+  );
+  server.registerTool(
+    "restore_original_document",
+    { description: GIT_HISTORY_DESCRIPTIONS.restore_original_document, inputSchema: RestoreOriginalDocumentSchema },
+    async (args) => toTextResult(await GIT_HISTORY_HANDLERS.restore_original_document(store, args))
+  );
   server.registerTool(
     "get_document_history",
     { description: GIT_HISTORY_DESCRIPTIONS.get_document_history, inputSchema: GetDocumentHistorySchema },
@@ -46206,7 +47489,7 @@ async function main(argv = process.argv) {
   if (openTimeout !== void 0) setOpenValidationTimeoutMs(Number(openTimeout));
   const dumpDir = takeDirFlag(argv, "--dump-schemas");
   if (dumpDir !== void 0) {
-    const resolved = path21.resolve(dumpDir);
+    const resolved = path24.resolve(dumpDir);
     const result = generateSchemasToDir(resolved, SERVER_VERSION);
     process.stdout.write(`[${SERVER_NAME} v${SERVER_VERSION}] wrote ${result.count} schemas to ${resolved}
 `);
@@ -46214,7 +47497,7 @@ async function main(argv = process.argv) {
   }
   const checkDir = takeDirFlag(argv, "--check-schemas");
   if (checkDir !== void 0) {
-    const resolved = path21.resolve(checkDir);
+    const resolved = path24.resolve(checkDir);
     const verdict = checkSchemasInDir(resolved, SERVER_VERSION);
     if (verdict.ok) {
       process.stdout.write(`[${SERVER_NAME} v${SERVER_VERSION}] schemas fresh (${verdict.checked} tools)