@attentionform/astra-mcp-server 0.5.0 → 0.5.1

package/dist/index.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",
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -15535,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);
@@ -15934,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 = [];
@@ -15954,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();
@@ -16536,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];
@@ -16803,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'.`
@@ -16812,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();
@@ -17121,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;
@@ -17172,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);
@@ -18355,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;
@@ -19585,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) {
@@ -19828,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;
@@ -20337,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) };
   });
 }
@@ -21614,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(),
@@ -21626,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(),
@@ -21648,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({
@@ -21685,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(),
@@ -21772,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(),
@@ -21853,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(),
@@ -21986,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());
@@ -22112,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(),
@@ -22122,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
@@ -22462,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 = [];
@@ -22469,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;
@@ -22514,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(" ");
   }
@@ -23342,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) {
@@ -23867,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);
@@ -26868,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);
@@ -31616,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"
@@ -31734,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) {
@@ -32257,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 {
@@ -33056,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.`;
     }
@@ -34679,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.`
     );
   }
 }
@@ -35196,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();
@@ -35313,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) {
@@ -35353,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,
@@ -35412,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 {
@@ -35443,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 = [];
@@ -35579,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";
@@ -35627,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;
   }
@@ -38202,9 +38437,9 @@ function escapeHtml(str) {
 
 // ../engine/src/export/pdf.ts
 var import_child_process = require("child_process");
-var fs9 = __toESM(require("fs"));
+var fs10 = __toESM(require("fs"));
 var fsp4 = __toESM(require("fs/promises"));
-var path8 = __toESM(require("path"));
+var path9 = __toESM(require("path"));
 var import_url = require("url");
 
 // ../engine/src/export/preflight.ts
@@ -38545,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";
@@ -38590,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) {
@@ -38613,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);
@@ -38675,7 +39037,7 @@ async function removeStagedDir(dir) {
 }
 async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, binary, stagedForensics) {
   const tmpDir = secureMkdtemp("astra-pdf-");
-  const tmpDocxPath = path8.join(tmpDir, `doc_${Date.now()}.docx`);
+  const tmpDocxPath = path9.join(tmpDir, `doc_${Date.now()}.docx`);
   let succeeded = false;
   try {
     await fsp4.writeFile(tmpDocxPath, docxBuffer);
@@ -38687,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)(path8.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 = "";
@@ -38723,19 +39085,19 @@ async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, bi
     if (!converted && lastError) {
       throw lastError;
     }
-    const expectedPdfName = path8.basename(tmpDocxPath).replace(/\.docx$/i, ".pdf");
-    const generatedPdfPath = path8.join(tmpDir, expectedPdfName);
-    if (!fs9.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 = path8.dirname(path8.resolve(outPdfPath));
-    assertWriteTargetNoSymlink(path8.resolve(outPdfPath));
+    const targetDir = path9.dirname(path9.resolve(outPdfPath));
+    assertWriteTargetNoSymlink(path9.resolve(outPdfPath));
     await fsp4.mkdir(targetDir, { recursive: true });
-    assertWriteTargetNoSymlink(path8.resolve(outPdfPath));
-    await writeFileNoFollow(path8.resolve(outPdfPath), await fsp4.readFile(generatedPdfPath));
-    fs9.chmodSync(path8.resolve(outPdfPath), 420);
+    assertWriteTargetNoSymlink(path9.resolve(outPdfPath));
+    await writeFileNoFollow(path9.resolve(outPdfPath), await fsp4.readFile(generatedPdfPath));
+    fs10.chmodSync(path9.resolve(outPdfPath), 420);
     succeeded = true;
-    return path8.resolve(outPdfPath);
+    return path9.resolve(outPdfPath);
   } finally {
     if (succeeded) {
       try {
@@ -38751,82 +39113,8 @@ async function convertWithFilter(docxBuffer, outPdfPath, filterSpec, options, bi
   }
 }
 
-// ../engine/src/visual/backend.ts
-var fs10 = __toESM(require("fs"));
-var path9 = __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 = path9.resolve(trimmed);
-        fs10.accessSync(abs, fs10.constants.X_OK);
-        const stat3 = fs10.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(path9.delimiter).filter((d) => d.length > 0);
-    for (const dir of dirs) {
-      try {
-        const candidate = path9.join(dir, trimmed);
-        fs10.accessSync(candidate, fs10.constants.X_OK);
-        const stat3 = fs10.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 fs11 = __toESM(require("fs"));
@@ -39216,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
@@ -40810,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.`
     );
   }
 }
@@ -43103,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.'
@@ -43144,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). `
@@ -43182,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 +
@@ -43429,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) {
@@ -43528,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,
@@ -43541,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}.'
@@ -43554,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) {
@@ -43620,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,
@@ -43629,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.`;
       }
@@ -43693,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 = {};
@@ -45666,7 +46007,7 @@ async function handleExportDocument(store, rawArgs) {
   }
   let validatedPdfPath;
   if (format === "pdf") {
-    if (!hasPdfBackend()) {
+    if (!hasPdfBackend2()) {
       return {
         ok: false,
         code: "E_DEPENDENCY",
@@ -46392,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) {
@@ -46714,7 +47056,7 @@ var import_zod9 = require("zod");
 var package_default = {
   name: "@attentionform/astra-mcp-server",
   mcpName: "com.attentionform/astra-mcp-server",
-  version: "0.5.0",
+  version: "0.5.1",
   description: "Official Model Context Protocol (MCP) server for ASTra document IDE",
   main: "dist/index.js",
   types: "dist/index.d.ts",
@@ -46755,8 +47097,8 @@ var package_default = {
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   dependencies: {
-    "@attentionform/astra-engine": "^0.5.0",
-    "@attentionform/ooxml-validator": "^0.5.0",
+    "@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",