opentakeoff-mcp 0.9.38 → 0.9.40

package/README.md

@@ -101,13 +101,35 @@ Each tool call writes one JSON line to stderr with the tool name, duration,
 sheet, result size, and error flag. The trace never writes to stdout and never
 includes document text, shape vertices, or result payload content.
 
+### Staged tool exposure (opt-in)
+
+By default every client gets all 40 tool schemas on `tools/list` — the flat
+contract every published client already expects. Forty descriptions is real
+token weight for an agent session that may never touch half of them, so the
+server can instead stage the surface along the workflow it already teaches:
+
+```bash
+OPENTAKEOFF_MCP_STAGED_TOOLS=1 npx -y opentakeoff-mcp
+```
+
+Staged, only the **setup** stage (load, scale, read the set — 10 tools) starts
+enabled, plus one opener: `open_tool_stage`. Calling it with `"measure"`,
+`"revise"`, or `"handoff"` enables that stage's tools and fires
+`tools/list_changed`, so any client that supports dynamic tool lists (Claude
+Code, Claude Desktop, anything built against the current spec) sees the group
+appear the moment the agent asks for it. Opening is idempotent and never
+closes anything — the surface only grows. The initialize instructions state
+the scheme, so an agent knows to open a stage before it needs one. Requires a
+client that honors `tools/list_changed`; leave the flag unset for one that
+reads the tool list once. ([#230](https://github.com/Kentucky-ai/opentakeoff/issues/230))
+
 ## Tools
 
 | Tool | What it does |
 |---|---|
 | `load_plan` | Open a plan PDF from disk. Default replaces the whole session; **`merge: true` ADDS the document to the working set** (#152) — plans + schedule + addenda as one takeoff, sheet graph spanning the whole set, marked set covering every worked sheet. Returns per-sheet dims, title-block `sheet_number`, and the detected drawn scale where present. |
 | `sheet_info` | One sheet's dims, vector segment count, scale status, detected suggestion, committed shape count. |
-| `set_scale` | Set a sheet's scale — exactly one of `label`, `upp`, `calibrate {p1, p2, feet}`, `use_detected`. |
+| `set_scale` | Set a sheet's scale — exactly one of `label`, `upp`, `calibrate {p1, p2, feet}`, `use_detected`. **Lands unconfirmed** (`confirmed: false`) until a human confirms in the canvas — see Scale rules. |
 | `one_click` | One-Click Area at (x, y): the sealed flood engine bounded by the plan linework, traced, vertices snapped — the SAME feet-true arguments the canvas passes at a click (gap sealing up to a door width, door-swing wedge inclusion, the half-foot minimum-passage rule), so an MCP trace and a canvas click at one seed measure the same square footage (pinned against the bench corpus goldens in `test/parity.test.ts`). Every trace carries the engine's account of itself: `confidence` 0–1 with `confidence_factors` naming each deduction (`gap_sealed_px`, `door_wedges`, `min_pass_delta`, …) — a review prioritizer, never a verification; a low score is a `view_sheet {overlay: true}` audit prompt, not a fact. On a SCANNED sheet (no usable linework) the flood falls back automatically to the rendered pixels — same engine as the canvas — with `raster_traced` disclosed on the reply and on the shape's origin (#154). Pass `condition` to commit (the full account stamps `origin` centrally at the commit); `role: "deduct"` subtracts. |
 | `detect_rooms` | Batch One-Click: reads every room-number label off the sheet's text layer and floods each — one call instead of `read_sheet_text` + reasoning + N `one_click` calls, through the SAME sealed engine per room (confidence + the engine account ride each room and its committed origin). Only cleanly-traced rooms come back; everything skipped is counted and reasoned in `withheld` (degenerate / duplicate / implausible / unresolved), never dropped silently. To commit: `assign_from_schedule: true` routes each room through its OWN room-finish schedule row and commits under the FLOOR finish that row states (rooms the schedule can't answer for return in `unresolved[]` with reasons and re-seedable coordinates); or pass `condition` to commit every room under one stated tag. |
 | `measure_polygon` | Area + perimeter of a polygon you supply (min 3 verts). Requires scale. |
@@ -216,6 +238,14 @@ space, which makes them usable directly as click targets.
 
 - A detected scale is a **suggestion** — it is never applied automatically.
   Adopting it is always an explicit `set_scale { use_detected: true }`.
+- **Agent proposes, human confirms.** `set_scale` is the agent surface, so a
+  scale set here lands **unconfirmed** (`confirmed: false` in the reply).
+  Quantities still flow — the gate is a flag, never a refusal — but
+  `takeoff_summary` names the affected sheets in
+  `scale_unconfirmed`, and the export/report carry `scale_confirmed` so the
+  canvas can ask the estimator to confirm (its scale menu grows a
+  **Confirm agent-set scale** row on import). Only a human act in the canvas
+  clears the flag.
 - `measure_polygon` and `measure_line` refuse without a scale:
   `Set the scale for <sheet> first — use set_scale (detected: <label>).`
 - `one_click` without a scale returns a **px-only preview**

package/dist/server-core.js

@@ -1005,12 +1005,12 @@ function circleFitOk(segs, chain, c0, c1) {
   my /= m;
   let sxx = 0, sxy = 0, syy = 0, sxz = 0, syz = 0;
   for (let i = 0; i < m; i++) {
-    const x = xs[i] - mx, y = ys[i] - my, z3 = x * x + y * y;
+    const x = xs[i] - mx, y = ys[i] - my, z4 = x * x + y * y;
     sxx += x * x;
     sxy += x * y;
     syy += y * y;
-    sxz += x * z3;
-    syz += y * z3;
+    sxz += x * z4;
+    syz += y * z4;
   }
   const det = sxx * syy - sxy * sxy;
   if (Math.abs(det) < 1e-9) return null;
@@ -1993,12 +1993,12 @@ function arcClusterFit(cl, mw, mask) {
   my /= m;
   let sxx = 0, sxy = 0, syy = 0, sxz = 0, syz = 0;
   for (const i of cl) {
-    const x = X(i) - mx, y = Y(i) - my, z3 = x * x + y * y;
+    const x = X(i) - mx, y = Y(i) - my, z4 = x * x + y * y;
     sxx += x * x;
     sxy += x * y;
     syy += y * y;
-    sxz += x * z3;
-    syz += y * z3;
+    sxz += x * z4;
+    syz += y * z4;
   }
   const tr = sxx + syy, dsc = Math.sqrt(Math.max(0, ((sxx - syy) / 2) ** 2 + sxy * sxy));
   const l1 = tr / 2 + dsc;
@@ -4199,7 +4199,11 @@ function reportJson({ projectName = "", rows = [], bySheet = [], scaleInfo = [],
     schema: "opentakeoff.report.v1",
     project_name: projectName || null,
     generated_with: "OpenTakeoff",
-    sheets: scaleInfo.map((si) => ({ sheet_id: si.sheet_id, sheet: label(si.sheet_id), scale_source: si.scale_source ?? si.source ?? "unknown" })),
+    // scale_confirmed (scale gate): false = an agent set this sheet's scale and
+    // no human confirmed it — the report's consumer should treat those sheets'
+    // quantities as standing on an unverified number. Absent input = true
+    // (human-era payloads predate the flag).
+    sheets: scaleInfo.map((si) => ({ sheet_id: si.sheet_id, sheet: label(si.sheet_id), scale_source: si.scale_source ?? si.source ?? "unknown", scale_confirmed: si.scale_confirmed !== false })),
     // custom-column values APPEND after materials (row key order otherwise
     // untouched). Iterating the DEFINED columns — never raw attrs — naturally
     // drops orphaned colIds; attrValue (the shared assigned-value rule) keeps
@@ -4856,7 +4860,7 @@ function drawShapes(ctx, toCanvas, shapes, sheetW, sheetH, longEdge) {
 var SNAP_CELL = 24;
 var SNAP_TOL = 7;
 var PALETTE = ["#c96442", "#2f7d54", "#2563eb", "#9333ea", "#b8860b", "#0d9488", "#be185d", "#1f2937", "#dc2626", "#0891b2"];
-var HATCH_IDS = ["solid", "diag", "diag2", "cross", "diagdense", "horiz", "vert", "grid", "brick", "plank", "herring", "basket", "checker", "wave", "dots", "speckle", "iso", "honeycomb", "scan", "plus", "circuit", "topo"];
+var HATCH_IDS = ["solid", "diag", "diag2", "cross", "diagdense", "horiz", "vert", "grid", "brick", "plank", "herring", "basket", "checker", "wave", "dots", "speckle", "iso", "honeycomb", "scan", "plus", "circuit", "topo", "woodgrain", "chevron", "pinwheel", "harlequin", "hexagon", "penny", "octagondot", "fleur", "concrete"];
 var mintUuid2 = () => globalThis.crypto && typeof globalThis.crypto.randomUUID === "function" ? globalThis.crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 var uid = (p) => `${p}-${mintUuid2()}`;
 var nowIso2 = () => (/* @__PURE__ */ new Date()).toISOString();
@@ -5399,11 +5403,13 @@ var Session = class _Session {
     }
     s.upp = upp;
     s.scaleSource = source === "label" ? "standard" : source === "calibrate" ? "calibrated" : source;
+    s.scaleConfirmed = false;
     return {
       sheet: s.key,
       upp,
       ...label ? { label } : {},
       source,
+      confirmed: false,
       // #153 — several DISTINCT scale notes on one sheet means enlarged plans
       // or details are likely; region measurements will warn when a
       // disagreeing note sits inside them, but say it up front too
@@ -6679,7 +6685,8 @@ var Session = class _Session {
   summary() {
     const rows = conditionTotals(this.conditions, this.shapes, this.seamCtx());
     const lean = rows.map(({ color, fill, hatch, materials, ...rest }) => rest);
-    return { conditions: lean, totals: grandTotals(rows) };
+    const unconfirmed = [...this.sheets.values()].filter((s) => s.upp != null && s.scaleConfirmed === false).map((s) => s.key);
+    return { conditions: lean, totals: grandTotals(rows), ...unconfirmed.length ? { scale_unconfirmed: unconfirmed } : {} };
   }
   deleteShape(id) {
     const i = this.shapes.findIndex((x) => x.id === id);
@@ -7458,7 +7465,15 @@ var Session = class _Session {
       schema: ANN_SCHEMA,
       project_name: "",
       units: "imperial",
-      sheets: [...this.sheets.values()].filter((s) => s.upp != null).map((s) => ({ sheet_id: s.key, units_per_px: s.upp })),
+      sheets: [...this.sheets.values()].filter((s) => s.upp != null).map((s) => ({
+        sheet_id: s.key,
+        units_per_px: s.upp,
+        // provenance rides the payload (it used to be dropped here): the canvas
+        // hydrates scale_source for its report and scale_confirmed for the
+        // scale gate's confirm affordance — absent = confirmed (pre-flag docs)
+        ...s.scaleSource ? { scale_source: s.scaleSource } : {},
+        ...s.scaleConfirmed === false ? { scale_confirmed: false } : {}
+      })),
       conditions: this.conditions,
       shapes: this.shapes,
       markups: this.markups,
@@ -7488,7 +7503,7 @@ var Session = class _Session {
       projectName,
       rows,
       bySheet: sheetTotals(this.conditions, this.shapes),
-      scaleInfo: [...this.sheets.values()].filter((s) => s.upp != null).map((s) => ({ sheet_id: s.key, scale_source: s.scaleSource ?? "unknown" })),
+      scaleInfo: [...this.sheets.values()].filter((s) => s.upp != null).map((s) => ({ sheet_id: s.key, scale_source: s.scaleSource ?? "unknown", scale_confirmed: s.scaleConfirmed !== false })),
       markups: this.markups,
       rfis: [],
       rollGoods: rollReportRows(byCond, rows)
@@ -7722,6 +7737,7 @@ var setScaleOutput = {
   upp: z.number().describe("Real feet per image px at render scale 2.0"),
   label: z.string().optional().describe("The standard scale label, when set by label or detected note"),
   source: z.enum(["label", "upp", "calibrate", "detected"]),
+  confirmed: z.boolean().describe("Always false here: set_scale is the agent surface, and an agent-set scale stays UNCONFIRMED until a human confirms it in the canvas \u2014 quantities still flow, wearing the caveat"),
   warning: z.string().optional().describe("Present when the sheet carries MULTIPLE distinct scale notes (#153) \u2014 enlarged plans/details likely; region measurements under a disagreeing note will warn")
 };
 var oneClickOutput = {
@@ -7888,7 +7904,8 @@ var takeoffSummaryOutput = {
     lf_net: z.number(),
     ea: z.number(),
     sy_net: z.number()
-  }).passthrough()
+  }).passthrough(),
+  scale_unconfirmed: z.array(z.string()).optional().describe("Sheets whose scale is agent-set and no human has confirmed \u2014 these totals stand on an unverified scale; verify against a stated dimension or confirm in the canvas")
 };
 var exportTakeoffOutput = {
   schema: z.string(),
@@ -8790,6 +8807,80 @@ function rfiStatus(id) {
   return STATUS_BY_ID[id] || RFI_STATUSES[0];
 }
 
+// ../web/src/lib/stitches.ts
+function stitchExtent(members, dims) {
+  let w = 0, h = 0;
+  for (const m of members) {
+    const d = dims[m.key];
+    if (!d?.w) continue;
+    w = Math.max(w, m.dx + d.w);
+    h = Math.max(h, m.dy + d.h);
+  }
+  return { w: Math.ceil(w), h: Math.ceil(h) };
+}
+function memberBoxes(members, dims) {
+  return members.map((m) => {
+    const d = dims[m.key] || { w: 0, h: 0 };
+    return { x0: m.dx, y0: m.dy, x1: m.dx + d.w, y1: m.dy + d.h };
+  });
+}
+function seamClips(members, dims) {
+  const boxes = memberBoxes(members, dims);
+  const clips = boxes.map((b) => ({ ...b }));
+  if (boxes.length < 2) return clips;
+  const cxs = boxes.map((b) => (b.x0 + b.x1) / 2), cys = boxes.map((b) => (b.y0 + b.y1) / 2);
+  const spread = (a) => Math.max(...a) - Math.min(...a);
+  const horizontal = spread(cxs) >= spread(cys);
+  const order = boxes.map((_, i) => i).sort((a, b) => horizontal ? boxes[a].x0 - boxes[b].x0 : boxes[a].y0 - boxes[b].y0);
+  for (let k = 0; k + 1 < order.length; k++) {
+    const i = order[k], j = order[k + 1];
+    if (horizontal && boxes[j].x0 < boxes[i].x1) {
+      const seam = (boxes[j].x0 + boxes[i].x1) / 2;
+      clips[i].x1 = Math.min(clips[i].x1, seam);
+      clips[j].x0 = Math.max(clips[j].x0, seam);
+    } else if (!horizontal && boxes[j].y0 < boxes[i].y1) {
+      const seam = (boxes[j].y0 + boxes[i].y1) / 2;
+      clips[i].y1 = Math.min(clips[i].y1, seam);
+      clips[j].y0 = Math.max(clips[j].y0, seam);
+    }
+  }
+  return clips;
+}
+function stitchPagePlan(members, dims) {
+  const clips = seamClips(members, dims);
+  return {
+    extent: stitchExtent(members, dims),
+    members: members.map((m, i) => ({ key: m.key, dx: m.dx, dy: m.dy, clip: clips[i] }))
+  };
+}
+function memberEmbed(vpTransform, member, pageH, renderScale) {
+  const [a, b, c, d, e, f] = Array.from(vpTransform);
+  const det = a * d - b * c;
+  const inv = (x, y) => [(d * (x - e) - c * (y - f)) / det, (-b * (x - e) + a * (y - f)) / det];
+  const { clip, dx, dy } = member;
+  const corners = [
+    inv(clip.x0 - dx, clip.y0 - dy),
+    inv(clip.x1 - dx, clip.y0 - dy),
+    inv(clip.x0 - dx, clip.y1 - dy),
+    inv(clip.x1 - dx, clip.y1 - dy)
+  ];
+  const xs = corners.map((p) => p[0]), ys = corners.map((p) => p[1]);
+  const z4 = (n) => n + 0 || 0;
+  return {
+    bbox: { left: z4(Math.min(...xs)), bottom: z4(Math.min(...ys)), right: z4(Math.max(...xs)), top: z4(Math.max(...ys)) },
+    // user → visual px (vpTransform), + stitch offset, ÷ renderScale into
+    // points, y flipped into PDF's y-up — composed into one affine
+    matrix: [
+      a / renderScale,
+      -b / renderScale,
+      c / renderScale,
+      -d / renderScale,
+      (e + dx) / renderScale,
+      pageH - (f + dy) / renderScale
+    ]
+  };
+}
+
 // ../web/src/lib/lineStyles.js
 var LINE_STYLES = {
   solid: { label: "Solid", dash: null },
@@ -9165,7 +9256,8 @@ async function buildMarkedSetPdf({ projectName, dark, sheets, shapes, markups, a
     for (const sh of marked) {
       if (y < 90) break;
       const items = shapesBy.get(sh.key) || [];
-      draw(`${sh.label} \xB7 page ${sh.page} \xB7 ${items.length + (marksBy.get(sh.key) || []).length + (apBy.get(sh.key) || []).length} item(s)`, { x: 52, y, size: 9.5, font: bold, color: ink });
+      const where = sh.stitch ? `stitched \xB7 ${sh.stitch.members.length} sheets` : `page ${sh.page}`;
+      draw(`${sh.label} \xB7 ${where} \xB7 ${items.length + (marksBy.get(sh.key) || []).length + (apBy.get(sh.key) || []).length} item(s)`, { x: 52, y, size: 9.5, font: bold, color: ink });
       y -= 13;
       for (const r of bySheetId.get(sh.key)?.rows || []) {
         if (y < 92) break;
@@ -9244,37 +9336,100 @@ async function buildMarkedSetPdf({ projectName, dark, sheets, shapes, markups, a
     }
   }
   const srcDocs = /* @__PURE__ */ new Map();
+  const srcDocFor = async (file) => {
+    let src = srcDocs.get(file);
+    if (!src) {
+      src = await PDFDocument.load(await loadPdfData(file), { ignoreEncryption: true });
+      srcDocs.set(file, src);
+    }
+    return src;
+  };
   for (const sh of marked) {
-    const page = await getPage(sh.file, sh.page);
-    const vpR = page.getViewport({ scale: RENDER_SCALE });
-    const W = vpR.width, H = vpR.height;
-    let pg, toPage, chipRot = degrees(0);
-    if (dark) {
-      const vp1 = page.getViewport({ scale: 1 });
-      const s = Math.min(RASTER_MAX / Math.max(vp1.width, vp1.height), 4);
-      const vp = page.getViewport({ scale: s });
-      const cv = document.createElement("canvas");
-      cv.width = Math.ceil(vp.width);
-      cv.height = Math.ceil(vp.height);
-      await page.render({ canvasContext: cv.getContext("2d"), viewport: vp }).promise;
-      invertPixels(cv);
-      const png = await doc.embedPng(cv.toDataURL("image/png"));
-      pg = doc.addPage([vp1.width, vp1.height]);
-      pg.drawImage(png, { x: 0, y: 0, width: vp1.width, height: vp1.height });
-      const k = vp1.width / W;
-      toPage = (x, y) => [x * k, vp1.height - y * k];
+    let pg, toPage, chipRot = degrees(0), W, H;
+    if (sh.stitch) {
+      const members = sh.stitch.members;
+      const pages = [];
+      const dims = {};
+      for (const m of members) {
+        const page = await getPage(m.file, m.page);
+        const vpR = page.getViewport({ scale: RENDER_SCALE });
+        dims[m.key] = { w: vpR.width, h: vpR.height };
+        pages.push({ m, page, vpR });
+      }
+      const plan = stitchPagePlan(members, dims);
+      W = plan.extent.w;
+      H = plan.extent.h;
+      const pageW = W / RENDER_SCALE, pageH = H / RENDER_SCALE;
+      if (dark) {
+        const s = Math.min(RASTER_MAX / Math.max(pageW, pageH), 4);
+        const cv = document.createElement("canvas");
+        cv.width = Math.ceil(pageW * s);
+        cv.height = Math.ceil(pageH * s);
+        const ctx = cv.getContext("2d");
+        ctx.fillStyle = "#fff";
+        ctx.fillRect(0, 0, cv.width, cv.height);
+        const k = s / RENDER_SCALE;
+        for (let i = 0; i < pages.length; i++) {
+          const { page } = pages[i], pm = plan.members[i];
+          const vp = page.getViewport({ scale: s });
+          const mc = document.createElement("canvas");
+          mc.width = Math.ceil(vp.width);
+          mc.height = Math.ceil(vp.height);
+          await page.render({ canvasContext: mc.getContext("2d"), viewport: vp }).promise;
+          ctx.save();
+          ctx.beginPath();
+          ctx.rect(pm.clip.x0 * k, pm.clip.y0 * k, (pm.clip.x1 - pm.clip.x0) * k, (pm.clip.y1 - pm.clip.y0) * k);
+          ctx.clip();
+          ctx.drawImage(mc, pm.dx * k, pm.dy * k);
+          ctx.restore();
+        }
+        invertPixels(cv);
+        const png = await doc.embedPng(cv.toDataURL("image/png"));
+        pg = doc.addPage([pageW, pageH]);
+        pg.drawImage(png, { x: 0, y: 0, width: pageW, height: pageH });
+      } else {
+        pg = doc.addPage([pageW, pageH]);
+        for (let i = 0; i < pages.length; i++) {
+          const { m, vpR } = pages[i], pm = plan.members[i];
+          const src = await srcDocFor(m.file);
+          const { bbox, matrix } = memberEmbed(vpR.transform, pm, pageH, RENDER_SCALE);
+          const emb = await doc.embedPage(src.getPage(m.page - 1), bbox, matrix);
+          pg.drawPage(emb, { x: 0, y: 0 });
+        }
+      }
+      toPage = (x, y) => [x / RENDER_SCALE, pageH - y / RENDER_SCALE];
     } else {
-      let src = srcDocs.get(sh.file);
-      if (!src) {
-        src = await PDFDocument.load(await loadPdfData(sh.file), { ignoreEncryption: true });
-        srcDocs.set(sh.file, src);
-      }
-      const [copied] = await doc.copyPages(src, [sh.page - 1]);
-      pg = doc.addPage(copied);
-      const [a, b, c, d, e, f] = vpR.transform;
-      const det = a * d - b * c;
-      toPage = (x, y) => [(d * (x - e) - c * (y - f)) / det, (-b * (x - e) + a * (y - f)) / det];
-      chipRot = degrees(page.rotate || 0);
+      const page = await getPage(sh.file, sh.page);
+      const vpR = page.getViewport({ scale: RENDER_SCALE });
+      W = vpR.width;
+      H = vpR.height;
+      if (dark) {
+        const vp1 = page.getViewport({ scale: 1 });
+        const s = Math.min(RASTER_MAX / Math.max(vp1.width, vp1.height), 4);
+        const vp = page.getViewport({ scale: s });
+        const cv = document.createElement("canvas");
+        cv.width = Math.ceil(vp.width);
+        cv.height = Math.ceil(vp.height);
+        await page.render({ canvasContext: cv.getContext("2d"), viewport: vp }).promise;
+        invertPixels(cv);
+        const png = await doc.embedPng(cv.toDataURL("image/png"));
+        pg = doc.addPage([vp1.width, vp1.height]);
+        pg.drawImage(png, { x: 0, y: 0, width: vp1.width, height: vp1.height });
+        const k = vp1.width / W;
+        toPage = (x, y) => [x * k, vp1.height - y * k];
+      } else {
+        let src = srcDocs.get(sh.file);
+        if (!src) {
+          src = await PDFDocument.load(await loadPdfData(sh.file), { ignoreEncryption: true });
+          srcDocs.set(sh.file, src);
+        }
+        const [copied] = await doc.copyPages(src, [sh.page - 1]);
+        pg = doc.addPage(copied);
+        const [a, b, c, d, e, f] = vpR.transform;
+        const det = a * d - b * c;
+        toPage = (x, y) => [(d * (x - e) - c * (y - f)) / det, (-b * (x - e) + a * (y - f)) / det];
+        chipRot = degrees(page.rotate || 0);
+      }
     }
     const ptScale = Math.hypot(...(() => {
       const p0 = toPage(0, 0), p1 = toPage(1, 0);
@@ -9478,7 +9633,8 @@ async function buildMarkedSetPdf({ projectName, dark, sheets, shapes, markups, a
       const tw = bold.widthOfTextAtSize(label, size);
       pg.drawText(label, { x: pcx - tw / 2, y: pcy - size / 2.7, size, font: bold, color: acol, rotate: chipRot });
     }
-    text(`${sh.label} \xB7 marked set`, 14, 20, 8, muted);
+    const stamp = sh.stitch ? `${sh.label} \xB7 stitched composite (${sh.stitch.members.map((m) => m.label || m.key).join(" + ")}) \xB7 marked set` : `${sh.label} \xB7 marked set`;
+    text(stamp, 14, 20, 8, muted);
   }
   const allPages = doc.getPages();
   const lastPg = allPages[allPages.length - 1];
@@ -9792,6 +9948,7 @@ async function importTakeoff(session, filePath) {
     if (s && s.upp == null && row.units_per_px > 0) {
       s.upp = row.units_per_px;
       s.scaleSource = row.scale_source ?? "upp";
+      if (row.scale_confirmed === false) s.scaleConfirmed = false;
     }
   }
   const tagKey2 = (t) => String(t || "").trim().toUpperCase();
@@ -9838,7 +9995,16 @@ var run = (tool, fn) => async (args) => {
   traceToolCall(tool, args, startedAt, reply);
   return reply;
 };
-function registerTools(server, session) {
+function registerTools(realServer, session) {
+  const registered = /* @__PURE__ */ new Map();
+  const server = {
+    registerTool(name, meta, handler) {
+      const tool = realServer.registerTool(name, meta, handler);
+      registered.set(name, tool);
+      return tool;
+    },
+    sendResourceListChanged: () => realServer.sendResourceListChanged()
+  };
   server.registerTool("load_plan", {
     description: `Open a plan PDF from disk. Default: replace the whole session (previous documents, scales, conditions, and shapes are cleared). merge: true ADDS the document to the working set instead (#152) \u2014 a bid set is plans + schedule + addenda, not one PDF \u2014 keeping every scale, condition, and shape; sheet keys carry file names so documents never collide, the sheet graph spans the whole set (resolve_tag can chain a plan tag on one file to a schedule row in another), and the marked set covers every worked sheet. Re-loading an already-merged file is refused \u2014 reload = replace, deliberately. Returns file, files, page_count, and one entry per sheet. The loaded sheets also become browsable resources (takeoff://sheets). ${COORDS}`,
     inputSchema: {
@@ -10294,6 +10460,7 @@ No review gate: the pencil-not-ink rule exists to stop an agent inventing geomet
     },
     outputSchema: deleteVerdictOutput
   }, run("delete_verdict", ({ verdict_id }) => session.deleteVerdict(verdict_id)));
+  return registered;
 }
 
 // src/resources.ts
@@ -10372,10 +10539,107 @@ function registerResources(server, session) {
   );
 }
 
+// src/staging.ts
+import { z as z3 } from "zod";
+var TOOL_STAGES = {
+  // Always enabled: an agent needs these to orient before anything else is useful.
+  setup: [
+    "load_plan",
+    "sheet_info",
+    "set_scale",
+    "sheet_graph",
+    "resolve_tag",
+    "find_schedule",
+    "read_sheet_text",
+    "find_text",
+    "sheet_context",
+    "view_sheet"
+  ],
+  measure: [
+    "one_click",
+    "detect_rooms",
+    "measure_polygon",
+    "cut_out",
+    "measure_line",
+    "measure_surface",
+    "place_count",
+    "symbol_sweep",
+    "sweep_schedule_row",
+    "derive_base",
+    "derive_transitions"
+  ],
+  revise: [
+    "list_shapes",
+    "delete_shape",
+    "edit_shape",
+    "edit_materials",
+    "edit_condition",
+    "duplicate_condition",
+    "split_condition",
+    "undo_last",
+    "annotate",
+    "list_annotations",
+    "link_annotation",
+    "mark_verdict",
+    "delete_verdict"
+  ],
+  handoff: [
+    "takeoff_summary",
+    "export_takeoff",
+    "export_report",
+    "import_takeoff",
+    "apply_rules",
+    "export_marked_pdf"
+  ]
+};
+var OPENABLE = ["measure", "revise", "handoff"];
+var openToolStageOutput = {
+  stage: z3.string().describe("The stage that was opened"),
+  enabled: z3.array(z3.string()).describe("Tool names enabled by this call (empty if the stage was already open)"),
+  open_stages: z3.array(z3.string()).describe("Every stage currently enabled, setup included"),
+  closed_stages: z3.array(z3.string()).describe("Stages still closed \u2014 open them here when the work reaches them")
+};
+var STAGED_INSTRUCTIONS = 'TOOL EXPOSURE IS STAGED: only the setup tools are enabled at start. Before measuring, call open_tool_stage {stage:"measure"}; likewise "revise" for edit/annotate/verdict tools and "handoff" for summaries and exports. Opening a stage is instant, idempotent, and never closes anything.';
+function applyStagedTools(server, registered) {
+  const openStages = /* @__PURE__ */ new Set(["setup"]);
+  for (const stage of OPENABLE) {
+    for (const name of TOOL_STAGES[stage]) registered.get(name)?.disable();
+  }
+  server.registerTool("open_tool_stage", {
+    description: `Enable a stage of this server's tools. Tool exposure is staged to match the takeoff workflow: "setup" (orient: load, scale, read the set) is always enabled; "measure" (commit shapes: one_click, detect_rooms, measure_*, sweeps and derives), "revise" (edit, annotate, verdict-mark, undo), and "handoff" (summaries, exports, the marked set) start closed and open here on demand. Opening a stage is idempotent and never closes another \u2014 the surface only grows. Call it the moment the work reaches a closed stage; the reply lists exactly which tools just became available.`,
+    inputSchema: {
+      stage: z3.enum(OPENABLE).describe('Which stage to enable: "measure", "revise", or "handoff"')
+    },
+    outputSchema: openToolStageOutput
+  }, async ({ stage }) => {
+    try {
+      const names = TOOL_STAGES[stage];
+      const enabled = [];
+      for (const name of names) {
+        const tool = registered.get(name);
+        if (!tool) throw new UserError(`Stage table names an unregistered tool: ${name}`);
+        if (!tool.enabled) {
+          tool.enable();
+          enabled.push(name);
+        }
+      }
+      openStages.add(stage);
+      return ok({
+        stage,
+        enabled,
+        open_stages: Object.keys(TOOL_STAGES).filter((s) => openStages.has(s)),
+        closed_stages: Object.keys(TOOL_STAGES).filter((s) => !openStages.has(s))
+      });
+    } catch (e) {
+      return fail(e);
+    }
+  });
+}
+
 // package.json
 var package_default = {
   name: "opentakeoff-mcp",
-  version: "0.9.38",
+  version: "0.9.40",
   mcpName: "io.github.Kentucky-ai/opentakeoff",
   type: "module",
   description: "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
@@ -10391,7 +10655,7 @@ var package_default = {
     mcpb: "npm run build && node scripts/build-mcpb.mjs",
     prepublishOnly: "npm run typecheck && npm test && npm run build",
     typecheck: "tsc --noEmit",
-    test: "node --import tsx --test test/conformance.test.ts test/context.test.ts test/e2e.test.ts test/labels.test.ts test/parity.test.ts test/raster.test.ts test/resources.test.ts test/safewrite.test.ts test/scalewarn.test.ts test/session.test.ts test/tools.test.ts test/transitions.test.ts test/twins.test.ts test/view.test.ts"
+    test: "node --import tsx --test test/conformance.test.ts test/context.test.ts test/e2e.test.ts test/labels.test.ts test/parity.test.ts test/raster.test.ts test/resources.test.ts test/safewrite.test.ts test/scalewarn.test.ts test/session.test.ts test/staging.test.ts test/tools.test.ts test/transitions.test.ts test/twins.test.ts test/view.test.ts"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.12.0",
@@ -10448,7 +10712,8 @@ var package_default = {
 };
 
 // server.ts
-function buildServer(session = new Session()) {
+function buildServer(session = new Session(), opts = {}) {
+  const staged = opts.stagedTools ?? process.env.OPENTAKEOFF_MCP_STAGED_TOOLS === "1";
   const server = new McpServer2({ name: "opentakeoff", version: package_default.version }, {
     // Served to every client at initialize — the discipline that makes agent
     // takeoffs land as reviewable work instead of a bare numbers report.
@@ -10460,11 +10725,13 @@ function buildServer(session = new Session()) {
       "3. DERIVE what follows from the rooms instead of re-measuring it: derive_base for base LF (perimeter \u2212 the door openings YOU state), derive_transitions for the line where two finishes meet. Both read committed floor shapes, so they come after step 2 and their output is audited in step 4 like anything else.",
       "4. LOOK at what landed with view_sheet overlay:true and fix misses with edit_shape before trusting totals \u2014 crop the work region tight (full-sheet renders downsample too far to audit a ring).",
       "5. Finish by writing the marked-up planset with export_marked_pdf and give the user its file path, alongside export_report for the numbers. Never end a takeoff with numbers alone.",
-      "WITHHELD IS NOT A FAILURE \u2014 IT IS THE ANSWER. detect_rooms, symbol_sweep, sweep_schedule_row and derive_transitions all measure things they then decline to commit, and say why: a near-match in the score band, a room the schedule cannot answer for, adjacency across a WALL rather than a butt joint. Read those arrays, view_sheet the coordinates they hand you, and resolve them or report them. A withheld item you ignore is a hole in the bid; one you never mention is worse."
+      "WITHHELD IS NOT A FAILURE \u2014 IT IS THE ANSWER. detect_rooms, symbol_sweep, sweep_schedule_row and derive_transitions all measure things they then decline to commit, and say why: a near-match in the score band, a room the schedule cannot answer for, adjacency across a WALL rather than a butt joint. Read those arrays, view_sheet the coordinates they hand you, and resolve them or report them. A withheld item you ignore is a hole in the bid; one you never mention is worse.",
+      ...staged ? [STAGED_INSTRUCTIONS] : []
     ].join("\n")
   });
-  registerTools(server, session);
+  const registered = registerTools(server, session);
   registerResources(server, session);
+  if (staged) applyStagedTools(server, registered);
   return server;
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentakeoff-mcp",
-  "version": "0.9.38",
+  "version": "0.9.40",
   "mcpName": "io.github.Kentucky-ai/opentakeoff",
   "type": "module",
   "description": "OpenTakeoff MCP server — drive the takeoff engine from your MCP client over stdio.",
@@ -16,7 +16,7 @@
     "mcpb": "npm run build && node scripts/build-mcpb.mjs",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test test/conformance.test.ts test/context.test.ts test/e2e.test.ts test/labels.test.ts test/parity.test.ts test/raster.test.ts test/resources.test.ts test/safewrite.test.ts test/scalewarn.test.ts test/session.test.ts test/tools.test.ts test/transitions.test.ts test/twins.test.ts test/view.test.ts"
+    "test": "node --import tsx --test test/conformance.test.ts test/context.test.ts test/e2e.test.ts test/labels.test.ts test/parity.test.ts test/raster.test.ts test/resources.test.ts test/safewrite.test.ts test/scalewarn.test.ts test/session.test.ts test/staging.test.ts test/tools.test.ts test/transitions.test.ts test/twins.test.ts test/view.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",