@rubytech/create-maxy-code 0.1.265 → 0.1.267

package/payload/server/server.js

@@ -9,6 +9,7 @@ import {
   COMMERCIAL_MODE,
   GREETING_DIRECTIVE,
   Hono,
+  HtmlEscapedCallbackPhase,
   INSTALL_OWNER_FILE,
   LOG_DIR,
   MAXY_DIR,
@@ -71,6 +72,7 @@ import {
   requirePortEnv,
   resolveAccount,
   resolveAgentConfig,
+  resolveCallback,
   resolveClientIp,
   resolveDefaultAgentSlug,
   resolveUserAccounts,
@@ -93,7 +95,7 @@ import {
   vncLog,
   walkPremiumBundles,
   writeAdminUserAndPerson
-} from "./chunk-SOLVVUST.js";
+} from "./chunk-W4EM7RK4.js";
 import {
   __commonJS,
   __toESM
@@ -1105,24 +1107,24 @@ var pr54206Applied = () => {
   return major >= 23 || major === 22 && minor >= 7 || major === 20 && minor >= 18;
 };
 var useReadableToWeb = pr54206Applied();
-var createStreamBody = (stream) => {
+var createStreamBody = (stream2) => {
   if (useReadableToWeb) {
-    return Readable.toWeb(stream);
+    return Readable.toWeb(stream2);
   }
   const body = new ReadableStream({
     start(controller) {
-      stream.on("data", (chunk) => {
+      stream2.on("data", (chunk) => {
         controller.enqueue(chunk);
       });
-      stream.on("error", (err) => {
+      stream2.on("error", (err) => {
         controller.error(err);
       });
-      stream.on("end", () => {
+      stream2.on("end", () => {
         controller.close();
       });
     },
     cancel() {
-      stream.destroy();
+      stream2.destroy();
     }
   });
   return body;
@@ -1227,10 +1229,10 @@ var serveStatic = (options = { root: "" }) => {
         end = size - 1;
       }
       const chunksize = end - start + 1;
-      const stream = createReadStream(path2, { start, end });
+      const stream2 = createReadStream(path2, { start, end });
       c.header("Content-Length", chunksize.toString());
       c.header("Content-Range", `bytes ${start}-${end}/${stats.size}`);
-      result = c.body(createStreamBody(stream), 206);
+      result = c.body(createStreamBody(stream2), 206);
     }
     await options.onFound?.(path2, c);
     return result;
@@ -2892,9 +2894,9 @@ function getDownloadableContent(message) {
   if (msg.stickerMessage) return { downloadable: msg.stickerMessage, mediaType: "sticker" };
   return void 0;
 }
-async function streamToBuffer(stream) {
+async function streamToBuffer(stream2) {
   const chunks = [];
-  for await (const chunk of stream) {
+  for await (const chunk of stream2) {
     chunks.push(Buffer.from(chunk));
   }
   return Buffer.concat(chunks);
@@ -2925,8 +2927,8 @@ async function downloadInboundMedia(msg, sock, opts) {
       const downloadable = getDownloadableContent(content);
       if (downloadable) {
         try {
-          const stream = await downloadContentFromMessage(downloadable.downloadable, downloadable.mediaType);
-          buffer = await streamToBuffer(stream);
+          const stream2 = await downloadContentFromMessage(downloadable.downloadable, downloadable.mediaType);
+          buffer = await streamToBuffer(stream2);
         } catch (fallbackErr) {
           console.error(`${TAG8} direct download fallback failed: ${String(fallbackErr)}`);
         }
@@ -4671,7 +4673,8 @@ async function managerRcSpawn(opts) {
       initialMessage: opts.initialMessage,
       closeAfterTurn: opts.closeAfterTurn,
       sliceToken: opts.sliceToken,
-      personId: opts.personId
+      personId: opts.personId,
+      waChannel: opts.waChannel
     })
   }).catch((err) => ({ __throw: err instanceof Error ? err.message : String(err) }));
   if ("__throw" in res) {
@@ -15567,6 +15570,300 @@ function startReaper2() {
   startReaper();
 }
 
+// app/lib/whatsapp/gateway/inbound-hub.ts
+var InboundHub = class {
+  senders = /* @__PURE__ */ new Map();
+  state(senderId) {
+    let s = this.senders.get(senderId);
+    if (!s) {
+      s = { subscriber: null, queue: [] };
+      this.senders.set(senderId, s);
+    }
+    return s;
+  }
+  /** Route an inbound message to its sender. Delivers immediately if that
+   *  sender's channel server is attached; otherwise queues it (cold start). */
+  deliver(payload) {
+    const s = this.state(payload.senderId);
+    if (s.subscriber) {
+      s.subscriber(payload);
+    } else {
+      s.queue.push(payload);
+    }
+  }
+  /** A sender's channel server connected. Drain any queued messages to it in
+   *  arrival order, then route live. Replaces any prior subscriber. */
+  attach(senderId, subscriber) {
+    const s = this.state(senderId);
+    s.subscriber = subscriber;
+    if (s.queue.length > 0) {
+      const pending = s.queue;
+      s.queue = [];
+      for (const payload of pending) subscriber(payload);
+    }
+  }
+  /** A sender's channel server disconnected (session ended/restarting).
+   *  Subsequent messages queue again until re-attach, so nothing is lost
+   *  across a restart. */
+  detach(senderId) {
+    const s = this.senders.get(senderId);
+    if (s) s.subscriber = null;
+  }
+  /** Whether a sender currently has a live channel server. The gateway uses
+   *  this to decide whether an inbound needs a cold-start spawn/resume. */
+  hasSubscriber(senderId) {
+    return this.senders.get(senderId)?.subscriber != null;
+  }
+};
+
+// node_modules/hono/dist/utils/stream.js
+var StreamingApi = class {
+  writer;
+  encoder;
+  writable;
+  abortSubscribers = [];
+  responseReadable;
+  /**
+   * Whether the stream has been aborted.
+   */
+  aborted = false;
+  /**
+   * Whether the stream has been closed normally.
+   */
+  closed = false;
+  constructor(writable, _readable) {
+    this.writable = writable;
+    this.writer = writable.getWriter();
+    this.encoder = new TextEncoder();
+    const reader = _readable.getReader();
+    this.abortSubscribers.push(async () => {
+      await reader.cancel();
+    });
+    this.responseReadable = new ReadableStream({
+      async pull(controller) {
+        const { done, value } = await reader.read();
+        done ? controller.close() : controller.enqueue(value);
+      },
+      cancel: () => {
+        this.abort();
+      }
+    });
+  }
+  async write(input) {
+    try {
+      if (typeof input === "string") {
+        input = this.encoder.encode(input);
+      }
+      await this.writer.write(input);
+    } catch {
+    }
+    return this;
+  }
+  async writeln(input) {
+    await this.write(input + "\n");
+    return this;
+  }
+  sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+  }
+  async close() {
+    try {
+      await this.writer.close();
+    } catch {
+    }
+    this.closed = true;
+  }
+  async pipe(body) {
+    this.writer.releaseLock();
+    await body.pipeTo(this.writable, { preventClose: true });
+    this.writer = this.writable.getWriter();
+  }
+  onAbort(listener) {
+    this.abortSubscribers.push(listener);
+  }
+  /**
+   * Abort the stream.
+   * You can call this method when stream is aborted by external event.
+   */
+  abort() {
+    if (!this.aborted) {
+      this.aborted = true;
+      this.abortSubscribers.forEach((subscriber) => subscriber());
+    }
+  }
+};
+
+// node_modules/hono/dist/helper/streaming/utils.js
+var isOldBunVersion = () => {
+  const version = typeof Bun !== "undefined" ? Bun.version : void 0;
+  if (version === void 0) {
+    return false;
+  }
+  const result = version.startsWith("1.1") || version.startsWith("1.0") || version.startsWith("0.");
+  isOldBunVersion = () => result;
+  return result;
+};
+
+// node_modules/hono/dist/helper/streaming/sse.js
+var SSEStreamingApi = class extends StreamingApi {
+  constructor(writable, readable) {
+    super(writable, readable);
+  }
+  async writeSSE(message) {
+    const data = await resolveCallback(message.data, HtmlEscapedCallbackPhase.Stringify, false, {});
+    const dataLines = data.split(/\r\n|\r|\n/).map((line) => {
+      return `data: ${line}`;
+    }).join("\n");
+    for (const key of ["event", "id", "retry"]) {
+      if (message[key] && /[\r\n]/.test(message[key])) {
+        throw new Error(`${key} must not contain "\\r" or "\\n"`);
+      }
+    }
+    const sseData = [
+      message.event && `event: ${message.event}`,
+      dataLines,
+      message.id && `id: ${message.id}`,
+      message.retry && `retry: ${message.retry}`
+    ].filter(Boolean).join("\n") + "\n\n";
+    await this.write(sseData);
+  }
+};
+var run = async (stream2, cb, onError) => {
+  try {
+    await cb(stream2);
+  } catch (e) {
+    if (e instanceof Error && onError) {
+      await onError(e, stream2);
+      await stream2.writeSSE({
+        event: "error",
+        data: e.message
+      });
+    } else {
+      console.error(e);
+    }
+  } finally {
+    stream2.close();
+  }
+};
+var contextStash = /* @__PURE__ */ new WeakMap();
+var streamSSE = (c, cb, onError) => {
+  const { readable, writable } = new TransformStream();
+  const stream2 = new SSEStreamingApi(writable, readable);
+  if (isOldBunVersion()) {
+    c.req.raw.signal.addEventListener("abort", () => {
+      if (!stream2.closed) {
+        stream2.abort();
+      }
+    });
+  }
+  contextStash.set(stream2.responseReadable, c);
+  c.header("Transfer-Encoding", "chunked");
+  c.header("Content-Type", "text/event-stream");
+  c.header("Cache-Control", "no-cache");
+  c.header("Connection", "keep-alive");
+  run(stream2, cb, onError);
+  return c.newResponse(stream2.responseReadable);
+};
+
+// app/lib/whatsapp/gateway/routes.ts
+function createWaChannelRoutes(deps) {
+  const app45 = new Hono();
+  app45.get("/wa-channel/inbound", (c) => {
+    const senderId = c.req.query("senderId");
+    if (!senderId) return c.json({ error: "senderId required" }, 400);
+    return streamSSE(c, async (stream2) => {
+      deps.hub.attach(senderId, (payload) => {
+        void stream2.writeSSE({ data: JSON.stringify(payload) });
+      });
+      console.error(`[whatsapp-native] op=channel-attached senderId=${senderId}`);
+      stream2.onAbort(() => {
+        deps.hub.detach(senderId);
+        console.error(`[whatsapp-native] op=channel-detached senderId=${senderId}`);
+      });
+      while (!stream2.aborted) {
+        await stream2.sleep(15e3);
+        await stream2.writeSSE({ data: "", event: "ping" });
+      }
+    });
+  });
+  app45.post("/wa-channel/reply", async (c) => {
+    const body = await c.req.json().catch(() => null);
+    const senderId = body?.senderId;
+    const text = body?.text;
+    if (typeof senderId !== "string" || typeof text !== "string") {
+      return c.json({ error: "senderId and text required" }, 400);
+    }
+    const bytes = Buffer.byteLength(text, "utf8");
+    try {
+      await deps.sendOutbound(senderId, text);
+    } catch (err) {
+      console.error(
+        `[whatsapp-native] op=reply-failed senderId=${senderId} bytes=${bytes} error=${err instanceof Error ? err.message : String(err)}`
+      );
+      return c.json({ error: "send-failed" }, 500);
+    }
+    console.error(`[whatsapp-native] op=reply-dispatch senderId=${senderId} bytes=${bytes}`);
+    return c.json({ ok: true });
+  });
+  app45.post("/wa-channel/ready", async (c) => {
+    const body = await c.req.json().catch(() => null);
+    const senderId = body?.senderId;
+    if (typeof senderId !== "string") {
+      return c.json({ error: "senderId required" }, 400);
+    }
+    deps.onReady?.(senderId);
+    return c.json({ ok: true });
+  });
+  return app45;
+}
+
+// app/lib/whatsapp/gateway/wa-gateway.ts
+var WaGateway = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  hub = new InboundHub();
+  replies = /* @__PURE__ */ new Map();
+  spawning = /* @__PURE__ */ new Set();
+  seq = 0;
+  /** Hono sub-app exposing the loopback channel routes; mount on the UI app. */
+  routes() {
+    return createWaChannelRoutes({
+      hub: this.hub,
+      sendOutbound: (senderId, text) => this.sendOutbound(senderId, text)
+    });
+  }
+  /** Handle one inbound admin WhatsApp message. */
+  async handleInbound(input) {
+    const bytes = Buffer.byteLength(input.text, "utf8");
+    const hadSubscriber = this.hub.hasSubscriber(input.senderId);
+    this.replies.set(input.senderId, input.reply);
+    this.hub.deliver({ senderId: input.senderId, text: input.text, waMessageId: `wa-${++this.seq}` });
+    console.error(
+      `[whatsapp-native] op=inbound senderId=${input.senderId} accountId=${input.accountId} bytes=${bytes} delivery=${hadSubscriber ? "immediate" : "queued"}`
+    );
+    if (!hadSubscriber && !this.spawning.has(input.senderId)) {
+      this.spawning.add(input.senderId);
+      console.error(`[whatsapp-native] op=spawn-trigger senderId=${input.senderId}`);
+      try {
+        await this.deps.ensureChannelSession({
+          accountId: input.accountId,
+          senderId: input.senderId,
+          gatewayUrl: this.deps.gatewayUrl,
+          serverPath: this.deps.serverPath
+        });
+      } finally {
+        this.spawning.delete(input.senderId);
+      }
+    }
+  }
+  async sendOutbound(senderId, text) {
+    const reply = this.replies.get(senderId);
+    if (!reply) throw new Error(`wa-gateway: no reply route for sender ${senderId}`);
+    await reply(text);
+  }
+};
+
 // app/lib/admin-sse-registry.ts
 var activeAdminSSEControllers = /* @__PURE__ */ new Set();
 function broadcastAdminShutdown(reason) {
@@ -16524,6 +16821,23 @@ app44.all("*", (c) => {
 });
 var port = requirePortEnv("MAXY_UI_INTERNAL_PORT", { tag: "ui-server" });
 var hostname = process.env.HOSTNAME ?? "127.0.0.1";
+var waNativeGatewayUrl = `http://127.0.0.1:${port}`;
+var waChannelServerPath = process.env.MAXY_WA_CHANNEL_SERVER_PATH ?? resolve26(process.env.MAXY_PLATFORM_ROOT ?? join18(__dirname, ".."), "services/whatsapp-channel/dist/server.js");
+var waGateway = new WaGateway({
+  gatewayUrl: waNativeGatewayUrl,
+  serverPath: waChannelServerPath,
+  ensureChannelSession: async ({ accountId, senderId, gatewayUrl, serverPath }) => {
+    const result = await managerRcSpawn({
+      sessionId: adminSessionIdFor(accountId, senderId),
+      waChannel: { senderId, gatewayUrl, serverPath },
+      logContext: `channel=whatsapp-native senderId=${senderId}`
+    });
+    if ("error" in result) {
+      console.error(`[whatsapp-native] spawn-failed senderId=${senderId} error=${result.error} status=${result.status}`);
+    }
+  }
+});
+app44.route("/", waGateway.routes());
 var httpServer = serve({ fetch: app44.fetch, port, hostname });
 console.log(`${BRAND.productName} listening on http://${hostname}:${port}`);
 startAuthHealthHeartbeat();
@@ -16702,6 +17016,23 @@ init({
   platformRoot: resolve26(process.env.MAXY_PLATFORM_ROOT ?? join18(__dirname, "..")),
   accountConfig: bootAccountConfig,
   onMessage: async (msg) => {
+    if (process.env.MAXY_WA_NATIVE_CHANNEL === "1" && msg.agentType === "admin" && !msg.isOwnerMirror && msg.text) {
+      try {
+        void msg.composing().catch(() => {
+        });
+        await waGateway.handleInbound({
+          accountId: msg.accountId,
+          senderId: msg.senderPhone,
+          text: msg.text,
+          reply: msg.reply
+        });
+      } catch (err) {
+        console.error(
+          `[whatsapp-native] reject senderId=${msg.senderPhone} message=${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      return;
+    }
     if ((msg.text || msg.mediaPath) && !msg.isOwnerMirror) {
       try {
         void msg.composing().catch(() => {

package/payload/platform/plugins/business-assistant/references/quote-engine.md

@@ -1,122 +0,0 @@
-# Priced-quote compute engine
-
-This reference is the **compute core** for a structured, priced quote: it turns a job (the items the
-owner selected, with their measurements or counts) into priced figures — line prices, group
-subtotals, and a final total — computed by **this owner's own pricing method**.
-
-It carries no items, no units, no rates, no margins, no overheads, no taxes, and no roll-up sequence.
-Every such value and rule is the owner's, captured as data. A trade pricing by the square metre, a
-caterer pricing by the head, and a printer pricing by per-unit break are all priced by the same
-approach — only their captured method differs.
-
-The compute engine itself is **not shipped**. You generate a small bespoke engine for this owner the
-first time they need a priced quote, and regenerate it whenever their business changes. The captured
-method is data the engine reads. Both persist in the owner's workspace and are re-run on demand.
-
-## When this path applies
-
-Use this for a **priced quote computed from the owner's method** — measured or counted work that has
-to be priced the way this owner prices it, then totalled. This is distinct from the simple
-photo-to-quote / chat-to-quote flow in `references/quoting.md`, which formats a quote the owner has
-already priced. If the owner has already worked out the numbers, stay in `quoting.md`. Come here when
-the numbers have to be **computed**.
-
-**Precondition:** a captured method for this owner must exist. Its *content* (the owner's items,
-rules, dials, roll-up, and past-job fixtures) is produced and maintained by the method-capture flow —
-Task 659 — which populates the method/job shape **this reference defines** below. If no captured method
-exists, capture it first; do not invent rates or rules here.
-
-## Where the engine and method live
-
-The agent runs in the owner's workspace (the spawn cwd, `$ACCOUNT_DIR`). Keep the engine and the
-captured method together under a `quoting/` subdirectory there, addressed by relative path:
-
-- the **method** — the owner's items, dials, and roll-up, as data;
-- the **engine** — the bespoke script that reads a method and a job and prices it;
-- the owner's **past jobs**, each with the figures they actually issued, used to verify the engine.
-
-These persist across sessions, are edited when the business changes, and are the engine's only inputs.
-Nothing about the owner's business lives in this reference or in the plugin.
-
-## The method shape (owner data)
-
-This section is the authoritative definition of the method/job shape; the method-capture flow (Task
-659) fills it with one owner's content. The method describes how this owner prices. For each
-**priceable item** it records:
-
-- what the item is (an identifier, a human label, a unit);
-- **how a quantity arises** — the item's own rule for turning a measurement into a quantity (for
-  example, an area from supplied dimensions, a length, a volume), or that the item carries **no
-  measurement rule** because it is counted or taken as a single unit. This is the item's *default*
-  quantity rule; a quantity entered on the job line always overrides it (see the job shape);
-- **how a line price is computed** — the owner's own rule for that item, in whatever form their
-  history shows it takes;
-- which **group** the line rolls into (the owner's own section headings);
-- whether the item is **standing-rule priced** (a rule fixes its price) or **judgement priced** (the
-  owner sets the price per job) — so the quote flow knows when it must ask the owner for a figure
-  rather than computing one.
-
-Alongside the items the method holds:
-
-- named **dials** — the owner's own scalars that their rules reference (a labour day-rate, a margin
-  multiplier, a percentage — whatever their method uses, named by them);
-- the **roll-up** — an ordered list of steps applied above the line items to reach the final total.
-  Each step names its rule, the prior figures it reads, and the label of the figure it produces. This
-  is whatever sequence the owner actually applies. It is **not** a fixed margin-then-overhead-then-tax
-  chain: an owner may apply an overhead, a contingency, a discount, a tax, or nothing, in their own
-  order. The engine implements exactly the step kinds this owner's roll-up uses, and no others.
-
-## The job shape (per quote)
-
-A job is the work selected for one quote: a list of lines, each naming an item and supplying **either**
-measurements **or** a directly-entered quantity, plus — for a judgement-priced item — the price the
-owner set for this line. The quantity source is decided per line by precedence: a quantity entered on
-the line is used as-is; otherwise the engine derives the quantity from the line's measurements via the
-item's measurement rule. An item with no measurement rule therefore requires an entered quantity (or
-its single-unit default). The job also carries the header the issued quote needs (who it is for, the
-address, the reference).
-
-## What the generated engine must do
-
-The engine reads one method and one job and produces the priced result. It must:
-
-1. **Resolve each line's quantity** — an entered quantity takes precedence; otherwise derive it from
-   the line's measurements via the item's measurement rule — and record which source was used.
-2. **Resolve each line's price** — by the item's own rule, or by the per-line figure the owner gave for
-   a judgement item — and record which was used.
-3. **Group** the priced lines under the owner's own headings.
-4. **Run the roll-up** steps in their defined order to reach the final total.
-5. **Emit observability** so a wrong figure is diagnosable from the log, not just the document: per
-   line, the resolved quantity and its source (measurement-derived vs entered) and the price rule
-   applied and its source (item rule vs per-line override); and each roll-up step with its result.
-6. **Reconcile** the sum of the group subtotals against the running line-item total and report it as an
-   explicit pass/fail — not a silent assumption.
-7. **Verify** on demand: given one of the owner's own past jobs, compare every computed figure
-   (line, group, final) against the figures the owner actually issued and report each as a match or
-   a mismatch.
-
-## Expressiveness — bounded by the owner's history
-
-Build the engine to support **exactly** the quantity, pricing, and roll-up forms the owner's own
-history exercises — discovered when their method was captured. Do not add quantity bases, price-rule
-forms, or roll-up step kinds the owner does not use. Unused generality is a liability: it is untested
-against their figures and invites a wrong quote later. If a new job needs a form the method has never
-expressed, that is a change to the captured method (and a re-verification), not a guess made here.
-
-## Acceptance — reproduction of the owner's own figures
-
-The engine is correct only when it **reproduces the owner's own past jobs** — line prices, group
-subtotals, and final totals — to the owner's own precision. The fixtures are that owner's
-history, supplied with their method; there are no built-in figures to test against. Reproducing their
-history, not parsing cleanly, is the signal that the engine prices the way they do. Verify on every
-generate and every method change; a reproduction failure blocks issuing a computed quote.
-
-## Boundaries
-
-- **Capturing and maintaining** the content of the method (items, rules, dials, roll-up, past-job
-  fixtures) is the method-capture flow — Task 659; it populates the shape this reference defines. This
-  reference consumes that method; it does not build it.
-- **Rendering** the priced result into the documents the owner issues (internal view, client
-  breakdown, branded quote) is Task 658. Those documents are printed to PDF through the existing
-  `browser-pdf-save` path (see `references/invoicing.md`); this compute reference produces only the
-  figures, not the documents.

package/payload/platform/plugins/business-assistant/references/quote-generation.md

@@ -1,94 +0,0 @@
-# Quote generation — output contract
-
-This is the **output half** of the engine-driven quote path. The engine (the operator's captured
-pricing method applied to a job) produces the figures; this contract turns those figures into the
-documents the operator issues, each rendered to PDF.
-
-It holds **no** business content. There are no fixed section names, no fixed wording, no fixed brand,
-and no fixed page layout here. What each document contains and how it looks is the operator's, held
-as their own data (their headings, their narrative, their charts, their logo, colours, contact and
-terms, their page size). The same contract serves any trade or service business by reading that
-operator's own document definitions.
-
-This is distinct from the lightweight WhatsApp quote in `references/quoting.md`. Use that one for a
-quick text quote. Use this one when the operator prices a job from a captured method and issues a set
-of reconciling documents.
-
-## What the engine hands you
-
-You render from the engine result. Read it as:
-
-- an ordered set of priced **groups** (the operator's own stages or categories);
-- each group an ordered set of **lines**; each line carries its quantity and the quantity's source
-  (measurement-derived or entered), its unit, its rate, its cost, and its sell;
-- each group's **subtotal**;
-- the operator's named **roll-up** steps — whatever sequence of adjustments and taxes they apply
-  above the line items, in order;
-- the **totals**: the client-visible subtotal and the final total.
-
-The engine guarantees the reconciliation invariant: the group subtotals carried through the roll-up
-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 three documents
-
-The operator defines the content and styling of each; the **roles** are fixed, the **contents** are
-not. A document is **engine-driven**: a section or line appears **only where the job priced it**.
-
-| Role | Shows | Withholds | Filing scope |
-|---|---|---|---|
-| **Internal margin-bearing view** | every line's quantity and its source, unit, rate, cost and sell; each group subtotal; the full roll-up; the totals | nothing — this is the operator's own check on profitability before issuing | **admin-only** |
-| **Client breakdown** | how the price is composed, at the granularity the operator chooses: the client-facing amount per group or line, the roll-up steps the client sees, and the headline figure | any cost, margin, or internal rate figure (the operator's own unit rate, not a client-facing per-unit price) | client-facing (shared) |
-| **Client quote document** | the issued document in the operator's brand: their cover, their narrative or schedule, the client breakdown, the headline price, the acceptance block, and their standing terms | any cost, margin, or internal rate figure (the operator's own unit rate, not a client-facing per-unit price) | client-facing (shared) |
-
-The internal view exists so the operator can confirm the job is profitable before it goes out; it may
-expose cost and margin freely. The two client documents **never** surface a cost, margin, or
-internal-rate figure. A column or line that shows the price to the client is fine; a figure that
-reveals what the work cost the operator, or the markup applied, is a leak.
-
-### The margin boundary is the filing scope
-
-The leak boundary is structural, not a matter of remembering to omit a column. File each document by
-its scope, exactly as `references/document-management.md` defines:
-
-- the **internal margin-bearing view** goes to the **admin-only** customer folder
-  (`memory/admin/customers/{phone}/`), which the customer never receives;
-- the **client breakdown** and the **client quote** go to the customer-facing documents folder
-  (`memory/users/{phone}/documents/`).
-
-A document that carries cost or margin must never be written to the shared scope.
-
-## Print fidelity
-
-Each document becomes a PDF through the device's Chromium print pipeline, so the HTML must survive
-that pipeline. Start from the A4 print conventions already in `references/invoicing.md` and
-`references/document-management.md` — an `@page` size directive, `@media print` styles, and
-`page-break-inside: avoid` on blocks that must not split — and keep the operator's own page size on
-`@page` (their stationery may not be A4).
-
-A multi-page issued quote needs two things beyond what those siblings show; state them explicitly in
-the document:
-
-- page-level chrome — a running header or footer and page numbers — via `@page` margin boxes, never
-  absolutely-positioned elements that drift across pages;
-- `print-color-adjust: exact` on coloured fills, so the operator's brand fills survive print. The
-  renderer prints backgrounds, but make the intent explicit rather than relying on the default.
-
-## 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:
-
-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
-   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.