@rubytech/create-sitedesk-code 0.1.429 → 0.1.431

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/src/lib/geometry.ts

@@ -0,0 +1,93 @@
+// Deterministic takeoff geometry. Pure arithmetic over agent-supplied measured
+// inputs — scale to a real dimension, a scaled area from two sides, and a count
+// roll-up — plus a cross-check of a scaled quantity against a printed figure.
+// Reading the drawing and eliciting the inputs is the takeoff skill's job, not
+// this module's. No business content: it multiplies numbers, it prices nothing.
+
+export type Basis = "printed" | "scaled" | "count" | "operator";
+
+/** A drawing scale: a stated ratio (1:R → R), or a known-dimension calibration
+ *  where `actual/measuredRef` is the factor. */
+export type Scale = { ratio: number } | { measuredRef: number; actual: number };
+
+export interface InLine {
+  element: string;
+  basis: Basis;
+  value?: number; // printed | operator
+  unit?: string;
+  measured?: number; // scaled
+  measuredB?: number; // scaled area — second side
+  kind?: "length" | "area"; // scaled
+  count?: number | number[]; // count
+  crossCheck?: { value: number; unit?: string; tolerance?: number };
+}
+
+export interface OutLine {
+  element: string;
+  quantity: number;
+  unit?: string;
+  basis: Basis;
+  crossCheck?: { printed: number; delta: number; disagree: boolean };
+}
+
+export interface TakeoffResult {
+  lines: OutLine[];
+  counts: { exact: number; scaled: number };
+}
+
+function scaleFactor(scale: Scale | undefined, element: string): number {
+  if (!scale) throw new Error(`takeoff: line "${element}" is scale-derived but no scale was supplied`);
+  const factor = "ratio" in scale ? scale.ratio : scale.actual / scale.measuredRef;
+  if (!Number.isFinite(factor)) {
+    throw new Error(`takeoff: line "${element}" has a degenerate scale (factor=${factor})`);
+  }
+  return factor;
+}
+
+function quantityFor(line: InLine, scale: Scale | undefined): number {
+  switch (line.basis) {
+    case "printed":
+    case "operator": {
+      if (typeof line.value !== "number") {
+        throw new Error(`takeoff: line "${line.element}" (${line.basis}) is missing its value`);
+      }
+      return line.value;
+    }
+    case "count": {
+      if (line.count === undefined) {
+        throw new Error(`takeoff: line "${line.element}" (count) is missing its count`);
+      }
+      return Array.isArray(line.count) ? line.count.reduce((a, b) => a + b, 0) : line.count;
+    }
+    case "scaled": {
+      if (typeof line.measured !== "number") {
+        throw new Error(`takeoff: line "${line.element}" (scaled) is missing its measured length`);
+      }
+      const factor = scaleFactor(scale, line.element);
+      if (line.kind === "area") {
+        if (typeof line.measuredB !== "number") {
+          throw new Error(`takeoff: line "${line.element}" (scaled area) is missing its second side`);
+        }
+        return line.measured * line.measuredB * factor * factor;
+      }
+      return line.measured * factor;
+    }
+  }
+}
+
+export function computeTakeoff(input: { scale?: Scale; lines: InLine[] }): TakeoffResult {
+  const lines: OutLine[] = input.lines.map((line) => {
+    const quantity = quantityFor(line, input.scale);
+    const out: OutLine = { element: line.element, quantity, unit: line.unit, basis: line.basis };
+    if (line.basis === "scaled" && line.crossCheck) {
+      const printed = line.crossCheck.value;
+      const delta = quantity - printed;
+      const tolerance = line.crossCheck.tolerance ?? 0;
+      out.crossCheck = { printed, delta, disagree: Math.abs(delta) > tolerance };
+    }
+    return out;
+  });
+
+  const scaled = lines.filter((l) => l.basis === "scaled").length;
+  return { lines, counts: { exact: lines.length - scaled, scaled } };
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/src/lib/log.ts

@@ -0,0 +1,8 @@
+/**
+ * Emit one structured observability line to stderr. Every tool invocation logs
+ * one line here, correlated by `jobId`; journald captures stderr, so the
+ * diagnostic path is `journalctl --user | grep -E '\\[quote-engine\\]|...'`.
+ */
+export function logLine(s: string): void {
+  process.stderr.write(s + "\n");
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/src/lib/render-run.ts

@@ -0,0 +1,125 @@
+// Execute the operator's persisted render script (quoting/render.mjs) to turn
+// figures into the three reconciling HTML documents, then enforce the three
+// deterministic gates and file each doc by its scope. The render script owns
+// brand/layout as its own data; this module templates nothing. HTML only — the
+// PDF is produced downstream by the browser plugin's browser-pdf-save.
+//
+// Fail-closed and atomic: if any gate fails, no document is filed and a
+// cause-naming fault is returned. "Fail loudly and stop", never a partial issue.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { gateReconcile, gateMarginLeak, gateSignLink, type SignLinkVerdict } from "./gates.js";
+
+export type RenderFault = "render-absent" | "render-error" | "reconcile-fail" | "margin-leak" | "sign-link";
+
+export interface RunRenderArgs {
+  accountDir: string;
+  renderScriptPath: string; // absolute
+  figures: Record<string, unknown>;
+  signUrl?: string;
+  jobId: string;
+}
+
+export type RenderResult =
+  | {
+      ok: true;
+      docs: { internal: string; breakdown: string; quote: string };
+      reconcile: { internal: boolean; breakdown: boolean; quote: boolean };
+      signLink: SignLinkVerdict;
+    }
+  | { ok: false; reason: RenderFault; detail: string };
+
+interface DocHtml { internal: string; breakdown: string; quote: string }
+
+export async function runRender(a: RunRenderArgs): Promise<RenderResult> {
+  if (!existsSync(a.renderScriptPath)) {
+    return { ok: false, reason: "render-absent", detail: `no render script at ${a.renderScriptPath}` };
+  }
+
+  const payload = JSON.stringify({ figures: a.figures, signUrl: a.signUrl ?? null });
+  const { code, stdout, stderr } = await new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve) => {
+    const child = spawn("node", [a.renderScriptPath], { cwd: a.accountDir });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", (e) => resolve({ code: -1, stdout: out, stderr: String(e) }));
+    child.on("close", (c) => resolve({ code: c, stdout: out, stderr: err }));
+    // A script that exits before draining stdin closes the read end mid-write,
+    // raising EPIPE. Swallow it: the exit code from `close` carries the fault, so
+    // an early exit surfaces as render-error rather than crashing the server.
+    child.stdin.on("error", () => {});
+    child.stdin.write(payload);
+    child.stdin.end();
+  });
+
+  if (code !== 0) {
+    return { ok: false, reason: "render-error", detail: `render script exited ${code}: ${stderr.trim().slice(0, 400)}` };
+  }
+
+  let html: DocHtml;
+  try {
+    const parsed = JSON.parse(stdout) as Partial<DocHtml>;
+    if (typeof parsed.internal !== "string" || typeof parsed.breakdown !== "string" || typeof parsed.quote !== "string") {
+      return { ok: false, reason: "render-error", detail: "render output must be { internal, breakdown, quote } HTML strings" };
+    }
+    html = parsed as DocHtml;
+  } catch {
+    return { ok: false, reason: "render-error", detail: `render stdout was not JSON: ${stdout.trim().slice(0, 200)}` };
+  }
+
+  const engineTotal = Number(a.figures.total);
+  const phone = (a.figures.header as { phone?: string } | undefined)?.phone;
+  if (!phone) {
+    return { ok: false, reason: "render-error", detail: "figures.header.phone is required to file the documents by scope" };
+  }
+  // The phone is a filing-path segment; reject a separator or traversal so a
+  // crafted header cannot escape the customer scope, the same guard account.ts
+  // applies to ACCOUNT_ID.
+  if (phone.includes("/") || phone.includes("..")) {
+    return { ok: false, reason: "render-error", detail: `figures.header.phone contains a path separator or traversal: ${phone}` };
+  }
+
+  // Gate every document before filing any, so the log reports each doc's verdict
+  // and nothing is written when one fails.
+  const recInternal = gateReconcile(html.internal, engineTotal);
+  const recBreakdown = gateReconcile(html.breakdown, engineTotal);
+  const recQuote = gateReconcile(html.quote, engineTotal);
+  const leakBreakdown = gateMarginLeak(html.breakdown);
+  const leakQuote = gateMarginLeak(html.quote);
+  const signLink = gateSignLink(html.quote);
+
+  const internalOk = recInternal.pass;
+  const breakdownOk = recBreakdown.pass && leakBreakdown.pass;
+  const quoteOk = recQuote.pass && leakQuote.pass && signLink.pass;
+
+  if (!internalOk || !breakdownOk || !quoteOk) {
+    // Reason names the first failing gate, in document then gate order.
+    let reason: RenderFault;
+    let detail: string;
+    if (!recInternal.pass) { reason = "reconcile-fail"; detail = `internal total ${recInternal.shown} != engine ${engineTotal}`; }
+    else if (!recBreakdown.pass) { reason = "reconcile-fail"; detail = `breakdown total ${recBreakdown.shown} != engine ${engineTotal}`; }
+    else if (!leakBreakdown.pass) { reason = "margin-leak"; detail = "breakdown carries data-internal-only"; }
+    else if (!recQuote.pass) { reason = "reconcile-fail"; detail = `quote total ${recQuote.shown} != engine ${engineTotal}`; }
+    else if (!leakQuote.pass) { reason = "margin-leak"; detail = "quote carries data-internal-only"; }
+    else { reason = "sign-link"; detail = `quote Sign-Online link ${signLink.reason} (href=${signLink.href ?? ""})`; }
+    return { ok: false, reason, detail };
+  }
+
+  const internalPath = join(a.accountDir, "memory/admin/customers", phone, `quote-${a.jobId}-internal.html`);
+  const breakdownPath = join(a.accountDir, "memory/users", phone, "documents", `quote-${a.jobId}-breakdown.html`);
+  const quotePath = join(a.accountDir, "memory/users", phone, "documents", `quote-${a.jobId}.html`);
+  for (const [p, body] of [[internalPath, html.internal], [breakdownPath, html.breakdown], [quotePath, html.quote]] as const) {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, body);
+  }
+
+  return {
+    ok: true,
+    docs: { internal: internalPath, breakdown: breakdownPath, quote: quotePath },
+    reconcile: { internal: internalOk, breakdown: breakdownOk, quote: quoteOk },
+    signLink,
+  };
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/src/tools/quote-engine-run.ts

@@ -0,0 +1,66 @@
+// quote-engine-run — execute the operator's persisted pricing engine against a
+// job and return structured figures. Runs the already-persisted engine; never
+// regenerates it, never embeds a rate/catalogue/roll-up. A fault returns a
+// cause-naming error and zero figures — never a partial or guessed total.
+
+import { z } from "zod";
+import { join } from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { lifelineTool } from "../../../../../../../platform/lib/mcp-lifeline/dist/index.js";
+import { resolveAccountDir } from "../lib/account.js";
+import { runEngine, writeFigures } from "../lib/engine-run.js";
+import { logLine } from "../lib/log.js";
+
+export function registerQuoteEngineRun(server: McpServer): void {
+  lifelineTool(
+    server,
+    "quote-engine-run",
+    "Execute the operator's already-persisted pricing engine (quoting/engine.mjs) against a job's quantities and return line prices, group subtotals and total. mode=verify runs the engine against a past job and returns the per-level reproduction delta. Runs the operator's own script; it is not a pricing model and embeds no rate, catalogue or roll-up. Faults (engine-absent, method-absent, script-error) return zero figures.",
+    {
+      jobId: z.string().describe("Correlation id; figures persist under quoting/jobs/<jobId>/."),
+      job: z.record(z.any()).describe("The job: header + lines. Passed to the engine verbatim; not interpreted here."),
+      mode: z.enum(["quote", "verify"]).default("quote").describe("quote = price the job; verify = reproduce a past job and return the delta."),
+      enginePath: z.string().default("quoting/engine.mjs").describe("Engine path relative to the account workspace."),
+      methodPath: z.string().default("quoting/method.json").describe("Method path relative to the account workspace."),
+    },
+    async (params: Record<string, unknown>) => {
+      const { jobId, job, mode, enginePath, methodPath } = params as {
+        jobId: string;
+        job: unknown;
+        mode: "quote" | "verify";
+        enginePath: string;
+        methodPath: string;
+      };
+      const accountId = process.env.ACCOUNT_ID ?? "local";
+      const accountDir = resolveAccountDir();
+      if (!accountDir) {
+        const detail = "ACCOUNT_DIR unset and PLATFORM_ROOT+ACCOUNT_ID unavailable";
+        logLine(`[quote-engine] op=fault jobId=${jobId} reason=no-account-context detail=${detail}`);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, reason: "no-account-context", detail }) }], isError: true };
+      }
+
+      const absEngine = join(accountDir, enginePath);
+      const absMethod = join(accountDir, methodPath);
+      const r = await runEngine({ accountDir, enginePath: absEngine, methodPath: absMethod, job, mode });
+
+      if (!r.ok) {
+        logLine(`[quote-engine] op=fault jobId=${jobId} reason=${r.reason} detail=${r.detail}`);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, reason: r.reason, detail: r.detail }, null, 2) }], isError: true };
+      }
+
+      if (mode === "verify") {
+        const deltas = (r.figures.deltas as unknown[]) ?? [];
+        const worst = (r.figures.worst as number) ?? 0;
+        logLine(`[quote-engine] op=verify jobId=${jobId} accountId=${accountId} worst=${worst} levels=${deltas.length}`);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ jobId, deltas, worst }, null, 2) }] };
+      }
+
+      const total = r.figures.total as number;
+      const lineCount = Array.isArray(r.figures.lines) ? r.figures.lines.length : 0;
+      const reconcile = r.figures.reconcile;
+      const figuresPath = writeFigures(accountDir, jobId, r.figures);
+      logLine(`[quote-engine] op=run jobId=${jobId} accountId=${accountId} enginePath=${enginePath} methodPath=${methodPath} lines=${lineCount} total=${total}`);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ jobId, total, lineCount, reconcile, figuresPath }, null, 2) }] };
+    },
+  );
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/src/tools/quote-render.ts

@@ -0,0 +1,66 @@
+// quote-render — turn engine figures into the three reconciling HTML documents
+// via the operator's persisted render script, enforcing the reconcile,
+// margin-leak and link-liveness gates, and filing each doc by its scope. HTML
+// only: the PDF is produced downstream by the browser plugin's browser-pdf-save.
+// A gate failure is fail-closed — no document is filed.
+
+import { z } from "zod";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { lifelineTool } from "../../../../../../../platform/lib/mcp-lifeline/dist/index.js";
+import { resolveAccountDir } from "../lib/account.js";
+import { runRender } from "../lib/render-run.js";
+import { logLine } from "../lib/log.js";
+
+export function registerQuoteRender(server: McpServer): void {
+  lifelineTool(
+    server,
+    "quote-render",
+    "Turn engine figures into the three reconciling HTML documents (internal margin view, client breakdown, client quote) via the operator's persisted quoting/render.mjs, enforcing three gates — reconcile (displayed total == engine total), margin-leak (no cost/margin in client docs), link-liveness (the client quote's Sign-Online href is absolute https). Files each doc by scope and returns the HTML paths. HTML only; print the PDFs with the browser plugin's browser-pdf-save. A gate failure files nothing.",
+    {
+      jobId: z.string().describe("Correlation id; figures load from quoting/jobs/<jobId>/figures.json unless figures is supplied inline."),
+      figures: z.record(z.any()).optional().describe("Inline figures (overrides the persisted figures.json) — for fixed-figure render parity."),
+      signUrl: z.string().optional().describe("The deployed e-sign signing URL injected into the client quote's acceptance anchor. Absent or non-https fails the link-liveness gate."),
+      renderScriptPath: z.string().default("quoting/render.mjs").describe("Render script path relative to the account workspace."),
+    },
+    async (params: Record<string, unknown>) => {
+      const { jobId, figures: inlineFigures, signUrl, renderScriptPath } = params as {
+        jobId: string;
+        figures?: Record<string, unknown>;
+        signUrl?: string;
+        renderScriptPath: string;
+      };
+      const accountDir = resolveAccountDir();
+      if (!accountDir) {
+        const detail = "ACCOUNT_DIR unset and PLATFORM_ROOT+ACCOUNT_ID unavailable";
+        logLine(`[quote-render] op=fault jobId=${jobId} reason=no-account-context detail=${detail}`);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, reason: "no-account-context", detail }) }], isError: true };
+      }
+
+      let figures: Record<string, unknown>;
+      if (inlineFigures) {
+        figures = inlineFigures;
+      } else {
+        const figuresPath = join(accountDir, "quoting", "jobs", jobId, "figures.json");
+        if (!existsSync(figuresPath)) {
+          const detail = `no figures at ${figuresPath} — run quote-engine-run first`;
+          logLine(`[quote-render] op=fault jobId=${jobId} reason=figures-absent detail=${detail}`);
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, reason: "figures-absent", detail }) }], isError: true };
+        }
+        figures = JSON.parse(readFileSync(figuresPath, "utf8"));
+      }
+
+      const absRender = join(accountDir, renderScriptPath);
+      const r = await runRender({ accountDir, renderScriptPath: absRender, figures, signUrl, jobId });
+
+      if (!r.ok) {
+        logLine(`[quote-render] op=fault jobId=${jobId} reason=${r.reason} detail=${r.detail}`);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, reason: r.reason, detail: r.detail }, null, 2) }], isError: true };
+      }
+
+      logLine(`[quote-render] op=render jobId=${jobId} docs=3 internal=${r.reconcile.internal} breakdown=${r.reconcile.breakdown} quote=${r.reconcile.quote}`);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ jobId, docs: r.docs, reconcile: r.reconcile, signLink: r.signLink }, null, 2) }] };
+    },
+  );
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/src/tools/takeoff-compute.ts

@@ -0,0 +1,51 @@
+// takeoff-compute — deterministic takeoff geometry over agent-supplied measured
+// inputs. Reading the drawing and eliciting inputs stay in the takeoff skill;
+// this tool only does the arithmetic. Carries no business content.
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { lifelineTool } from "../../../../../../../platform/lib/mcp-lifeline/dist/index.js";
+import { computeTakeoff, type InLine, type Scale } from "../lib/geometry.js";
+import { logLine } from "../lib/log.js";
+
+export function registerTakeoffCompute(server: McpServer): void {
+  lifelineTool(
+    server,
+    "takeoff-compute",
+    "Deterministic takeoff geometry: turn agent-supplied measured inputs into a tagged quantity list — scale a measured length to its real dimension, a scaled area from two sides, roll up counts, and cross-check a scaled quantity against a printed figure. Reading the drawing and eliciting the inputs is the takeoff skill; this tool does only the arithmetic and carries no business content.",
+    {
+      jobId: z.string().describe("Correlation id for this quote/takeoff."),
+      scale: z
+        .union([z.object({ ratio: z.number() }), z.object({ measuredRef: z.number(), actual: z.number() })])
+        .optional()
+        .describe("Drawing scale: {ratio} for 1:R, or {measuredRef, actual} calibration. Required only when a line is scale-derived."),
+      lines: z
+        .array(
+          z.object({
+            element: z.string(),
+            basis: z.enum(["printed", "scaled", "count", "operator"]),
+            value: z.number().optional(),
+            unit: z.string().optional(),
+            measured: z.number().optional(),
+            measuredB: z.number().optional(),
+            kind: z.enum(["length", "area"]).optional(),
+            count: z.union([z.number(), z.array(z.number())]).optional(),
+            crossCheck: z.object({ value: z.number(), unit: z.string().optional(), tolerance: z.number().optional() }).optional(),
+          }),
+        )
+        .describe("The measured lines to compute."),
+    },
+    async (params: Record<string, unknown>) => {
+      const { jobId, scale, lines } = params as { jobId: string; scale?: Scale; lines: InLine[] };
+      try {
+        const r = computeTakeoff({ scale, lines });
+        logLine(`[takeoff-compute] op=compute jobId=${jobId} lines=${r.lines.length} exact=${r.counts.exact} scaled=${r.counts.scaled}`);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ jobId, ...r }, null, 2) }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logLine(`[takeoff-compute] op=fault jobId=${jobId} detail=${msg}`);
+        return { content: [{ type: "text" as const, text: `Error: ${msg}` }], isError: true };
+      }
+    },
+  );
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/mcp/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/__tests__/**", "src/**/*.test.ts"]
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/quotation/references/quote-engine.md

@@ -95,6 +95,30 @@ The engine reads one method and one job and produces the priced result. It must:
    (line, group, final) against the figures the owner actually issued and report each as a match or
    a mismatch.
 
+## The apply-path tool runs the engine
+
+The deterministic apply step is the `sitedesk-job:quote-engine-run` MCP tool, not an inline Bash run
+of the script. The tool executes the **already-persisted** engine and never regenerates it. Generate
+the engine to the canonical layout and I/O boundary the tool invokes:
+
+- the engine at `quoting/engine.mjs` and the method at `quoting/method.json`, both under the account
+  workspace (`$ACCOUNT_DIR`);
+- the engine reads `{ methodPath, job, mode }` as one JSON object on **stdin**, loads its method from
+  `methodPath`, and writes its result as one JSON object on **stdout**;
+- in `mode: "quote"` the result is the figures the seven duties above produce: `{ lines, groups,
+  rollup, total, reconcile }`;
+- in `mode: "verify"` the result is the per-level delta `{ deltas, worst }` that feeds the
+  reproduction report in `references/verification.md`;
+- a non-zero exit, non-JSON stdout, or a missing `total`/`reconcile` (quote) or `deltas` (verify) is
+  the fault the tool surfaces as `script-error`; a missing engine or method is `engine-absent` or
+  `method-absent`. Every fault returns zero figures, never a partial total.
+
+`quote-engine-run` persists the quote-mode figures to `quoting/jobs/<jobId>/figures.json` and returns
+`{ jobId, total, lineCount, reconcile }`. The render step (`quote-render`, in
+`references/quote-generation.md`) reads those figures by `jobId`, so a Workflow chains
+`quote-engine-run` then `quote-render` by passing `jobId` alone. Building and maintaining the engine's
+content stays as this reference and the method-capture flow define; only the run seam is now the tool.
+
 ## Expressiveness — bounded by the owner's history
 
 Build the engine to support **exactly** the quantity, pricing, and roll-up forms the owner's own

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/quotation/references/quote-generation.md

@@ -32,6 +32,38 @@ equal the final total. You never recompute these figures — you display them.
 The engine itself, and how a line's quantity, rate, cost and sell are derived, are out of scope here
 (that is the compute core). This contract only reads the result.
 
+## The apply-path tool renders the documents
+
+Rendering is the `sitedesk-job:quote-render` MCP tool, not hand-authored HTML each run. The tool runs
+the operator's **persisted render script** at `quoting/render.mjs` (the render analog of the pricing
+engine): it reads `{ figures, signUrl }` on stdin and writes the three documents as one JSON object of
+HTML strings on stdout, `{ internal, breakdown, quote }`. The script holds the operator's brand,
+layout, headings, narrative, charts, page size, contact and terms as their own data. The tool
+templates nothing and carries no brand. Generating and maintaining that render script is the build
+half of this skill, exactly as generating the pricing engine is the build half of the compute core.
+
+The render script marks three stable attributes so the tool gates the output deterministically,
+whatever the operator's brand or language:
+
+- **`data-quote-total`** on each document's displayed grand total, carrying the numeric total, so the
+  tool reconciles it against the engine total;
+- **`data-internal-only`** on every cost, margin, or internal-rate figure in the internal view, so the
+  tool asserts the two client documents carry none;
+- **`data-esign-accept`** on the client quote's Sign-Online anchor (one line, double-quoted `href`), so
+  the tool asserts the acceptance link is live.
+
+`quote-render` enforces three fail-closed gates before it files anything: **reconcile** (each
+document's `data-quote-total` equals the engine total), **margin-leak** (no `data-internal-only` in the
+client breakdown or client quote), and **link-liveness** (the client quote's `data-esign-accept` href
+is an absolute `https://` URL). If any gate fails the tool files nothing and returns a cause-naming
+fault (`reconcile-fail`, `margin-leak`, `sign-link`, `render-absent`, `render-error`). On success it
+files each document to its scope (below) and returns the three HTML paths plus the gate verdicts.
+
+The tool produces **HTML, not PDF**. Print each returned path to PDF with the `browser` plugin as the
+final step: `browser-navigate` to its `file://` URL, then `browser-pdf-save` to a `.pdf` alongside it,
+confirming a non-zero byte count. A Workflow chains `quote-engine-run`, then `quote-render`, then one
+`browser` `browser-pdf-save` step per document.
+
 ## The three documents
 
 The operator defines the content and styling of each; the **roles** are fixed, the **contents** are
@@ -64,17 +96,19 @@ rendered until the deploy has run**. The order is fixed and load-bearing:
 
 1. run **e-sign § 5** to deploy the signing page and take its returned absolute `https://` URL (e-sign
    § 5 names it as an explicit hand-back);
-2. inject that URL as the `href` of the acceptance block's Sign-Online anchor;
-3. render the client quote to PDF (`Producing the PDF`, below), through the link-liveness gate;
+2. pass that URL to `quote-render` as `signUrl`; the render script injects it as the `href` of the
+   acceptance block's `data-esign-accept` anchor, and the tool's link-liveness gate holds it to an
+   absolute `https://` target or files nothing;
+3. print the returned client-quote HTML to PDF (`Producing the PDF`, below);
 4. send.
 
-Mark that one anchor with a stable attribute — `data-esign-accept` — so the pre-export gate (`Before
-you hand anything to the PDF tool`, below) finds it deterministically, whatever the operator's brand,
-wording, or language. The gate reads the anchor's opening tag line by line, so emit that opening tag
-on a **single line** with a **double-quoted `href`** (the default for these self-contained documents);
-a split tag or single-quoted `href` reads as no anchor and fails the gate closed. The anchor's `href`
-is **never** a placeholder, a bare `#`, or a `file://`/relative path: it is the deployed signing URL
-or the quote does not ship.
+The render script marks that one anchor with the stable attribute `data-esign-accept` so
+`quote-render`'s link-liveness gate finds it deterministically, whatever the operator's brand,
+wording, or language. The gate matches the anchor's opening tag, so the render script emits that
+opening tag on a **single line** with a **double-quoted `href`** (the default for these self-contained
+documents); a split tag or single-quoted `href` reads as no anchor and fails the gate closed. The
+anchor's `href` is **never** a placeholder, a bare `#`, or a `file://`/relative path: it is the
+deployed signing URL or the quote does not ship.
 
 When the quote is **confidential to a named client**, the acceptance is gated per e-sign § 1a. That
 section's **same-origin invariant** is load-bearing: the `/api/accept` and `/api/status` capture
@@ -113,51 +147,33 @@ the document:
 
 ## Producing the PDF
 
-Render the document as self-contained HTML (styles inline, images by absolute local path), then use
-the same path as every other business-assistant document:
+`quote-render` renders each document as self-contained HTML (the render script inlines styles and
+references images by absolute local path) and files it to its filing-scope path, returning the paths.
+For each returned path, print it the same way as every other business-assistant document:
 
-1. write the HTML to the document's filing-scope path;
-2. `browser-navigate` to it via a `file://` absolute URL;
-3. `browser-pdf-save` to an absolute `.pdf` path alongside the HTML;
-4. confirm a non-zero byte count from the `Saved PDF to <path> (<bytes>)` line before treating the PDF
+1. `browser-navigate` to it via a `file://` absolute URL;
+2. `browser-pdf-save` to an absolute `.pdf` path alongside the HTML;
+3. confirm a non-zero byte count from the `Saved PDF to <path> (<bytes>)` line before treating the PDF
    as done.
 
-## Before you hand anything to the PDF tool
-
-Log, for the run: which document roles were produced, each one's page count, and the reconciliation —
-each document's displayed total against the engine total. If a document's total does not reconcile to
-the engine total, fail loudly and stop. Never ship a document whose figures disagree with the engine.
-
-**Link-liveness gate — the client quote's Sign-Online anchor must resolve to the live signing page.**
-The reconciliation above guards the *figures*; it says nothing about whether the acceptance block's
-Sign-Online link is live. A client quote whose acceptance link is empty, a bare fragment (`#…`),
-relative, `file://`, `about:`, or any non-`https://` target must **fail loudly and stop** — no PDF
-written, nothing sent — exactly as a reconciliation mismatch does. Run this deterministic,
-exit-code-gated assertion over the **rendered client-quote HTML**, after it is written (`Producing the
-PDF` step 1) and **before `browser-pdf-save`** (step 3). It is authored as an assertion, not prose,
-because a dead link emits no other signal:
-
-```bash
-# Link-liveness gate. QUOTE_HTML = the client quote's written HTML (its filing-scope path);
-# DOC_REF = the e-sign document reference for this quote (for the log line).
-tag=$(grep -oiE '<a[^>]*\bdata-esign-accept\b[^>]*>' "$QUOTE_HTML" | head -1)
-href=$(printf '%s' "$tag" | grep -oiE 'href="[^"]*"' | head -1 | sed -E 's/^href="(.*)"$/\1/')
-verdict() { echo "op=sign-link doc_ref=${DOC_REF} href=${href} live=$1"; }
-if [ -z "$tag" ]; then verdict "fail reason=no-anchor"; exit 1; fi
-case "$href" in
-  https://*)  verdict ok ;;
-  "")         verdict "fail reason=empty";     exit 1 ;;
-  '#'*)       verdict "fail reason=fragment";  exit 1 ;;
-  *://*|*:*)  verdict "fail reason=non-https"; exit 1 ;;   # http://, file://, about:, mailto:
-  *)          verdict "fail reason=relative";  exit 1 ;;   # /path, path, ./x, ../x
-esac
-```
-
-A client quote PDF exists **only** when this line read `live=ok`. The per-run log for a client quote
-therefore carries one `op=sign-link doc_ref=<ref> href=<value> live=ok` line — naming the absolute
-`https://` href — alongside the roles / page-count / reconciliation lines above. A `Saved PDF to
-<path>` line for a client quote with no preceding `live=ok` for the same `doc_ref` is itself a
-regression signature: the gate was bypassed.
+## The tool enforces the reconciliation and link-liveness gates
+
+`quote-render` runs three fail-closed gates over the rendered HTML before it files any document, so
+these checks are enforced deterministically at render time, not as a separate hand-run step:
+
+- **reconciliation.** Each document's `data-quote-total` must equal the engine total. A mismatch files
+  nothing and returns `reconcile-fail`. Never ship a document whose figures disagree with the engine.
+- **margin-leak.** The client breakdown and client quote must carry no `data-internal-only` marker. A
+  leak files nothing and returns `margin-leak`. The margin boundary is structural, not a matter of
+  remembering to omit a column.
+- **link-liveness.** The client quote's `data-esign-accept` href must be an absolute `https://` URL,
+  not empty, a bare fragment (`#…`), relative, `file://`, `about:`, or any non-https target. A dead
+  link files nothing and returns `sign-link`, because a dead link emits no other signal.
+
+The tool emits one `[quote-render] op=render jobId=… docs=3 internal=… breakdown=… quote=…` line on
+success and `[quote-render] op=fault jobId=… reason=… detail=…` on any gate failure. A `Saved PDF to
+<path>` line for a client quote with no preceding successful `op=render` for the same job is itself a
+regression signature: the render gate was bypassed.
 
 **No-event standing check — filed quotes against live signing pages.** The gate fires only while a
 quote is being produced; it cannot catch a quote that shipped a bad link before the gate existed.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/takeoff/SKILL.md

@@ -55,6 +55,18 @@ Every line names how its quantity was measured. There are four bases and no othe
 
 `references/measuring.md` carries how to establish the reference and work each basis.
 
+## Computing the quantities
+
+Reading the drawing and eliciting the missing figures is this skill's work. Turning the readings into
+quantities is the `sitedesk-job:takeoff-compute` tool. Pass it the measured lines, each tagged with its
+basis, and (when any line is scale-derived) the scale as a ratio or a known-dimension calibration. The
+tool applies the deterministic arithmetic (a scaled length from the scale, a scaled area from two
+measured sides, a count roll-up by summation, and printed and operator-supplied figures passed through
+exactly) and returns the tagged quantity list with a count of how many lines are exact versus
+scale-approximated. Where a line carries a printed figure to check a scaled reading against, the tool
+records the delta and whether it disagrees beyond the tolerance you give. The tool measures nothing off
+the drawing itself and asks the operator nothing; those stay this skill's job.
+
 ## Cross-check
 
 Where a quantity is scale-derived and the drawing also prints a dimension for the same element, record