@go-labs-sg/bb 2.31.1 → 2.33.0

package/README.md

@@ -232,6 +232,18 @@ Every canonical command is classified by effect: `state-change`, `email`, `exter
 
 **Draft-only bills:** Use `bb bill create --draft-only --payload '<bill-json>' --allow-state-change --allow-financial-write` when the user authorizes a draft only. The equivalent payload field is `draftOnly: true`. This creates `DRAFT` for every role, without auto-checking, auto-approval, approval requests, emails, or QuickBooks writes. It cannot be combined with `alreadyPaid: true`; conflicting flag and payload values are rejected. Draft-only creation uses the dedicated `bill.createDraft` API route and fails on older servers without falling back to ordinary creation. Deploy backend support before releasing the updated CLI. Reconciled projects must be moved to Won separately before draft-only creation, because reopening a project can trigger external integrations. Completed projects retain their existing creation restriction.
 
+**Quotation-first supplier bills:** Use `quotationIds` when approved quotations cover disjoint bill lines. When two quotations fund the same bill line, pass `quotationAllocations` entries with `{ budgetItemId, quotationId, amount }` and an exact `lineAmounts` entry for every selected budget item; `lineAmounts` must sum to the bill amount. Canonical allocation rows are the stored source of every bill-line quotation relationship. A required zero-value bill line needs one or more allocations with `amount: 0`, which record its approved source(s) without consuming quotation capacity. Every quotation must belong to the bill supplier and project and cover the allocated budget item. Legacy `quotationId` remains valid as single-quotation input and maps to the current selection. Supplier bills that qualify for an existing exemption must state that intent with `--quotation-exempt`. Claims share budget allowance but never consume or link quotations, so quotation source fields are rejected for claims.
+
+Every selected bill or claim line must belong to an active budget in `ESTIMATE_ACCEPTED` or `ESTIMATE_CLOSED`, including lines drawn from additional budgets in the project. The server checks this during selection, creation, editing, and approval. An unaccepted budget never qualifies a line for a quotation exemption. Existing pending bills expose budget and source-link blockers in `commitmentReview.blockers`.
+
+Admins can repair missing source links on eligible draft, pending-approval, or rejected supplier bills with `bb bill quotation link <billId> --quotationIds q1,q2 --allow-state-change --allow-financial-write`. For same-line splits, use `--payload '{"quotationAllocations":[{"budgetItemId":"line_1","quotationId":"quote_1","amount":400},{"budgetItemId":"line_1","quotationId":"quote_2","amount":350}]}'`. The repair uses stored bill-line amounts and changes source linkage only.
+
+```sh
+bb bill create --payload '{"projectId":"project_1","budgetId":"budget_1","supplierId":"supplier_1","budgetItemIds":["line_1","line_2"],"quotationIds":["quote_1","quote_2"],"amount":1200,"isClaimable":false}'
+
+bb bill create --payload '{"projectId":"project_1","budgetId":"budget_1","supplierId":"supplier_1","budgetItemIds":["line_1"],"amount":750,"lineAmounts":[{"budgetItemId":"line_1","amount":750}],"quotationAllocations":[{"budgetItemId":"line_1","quotationId":"quote_1","amount":400},{"budgetItemId":"line_1","quotationId":"quote_2","amount":350}],"isClaimable":false}'
+```
+
 Bill creation determines its required permissions from the parsed input, for both canonical and legacy commands. Ordinary unpaid creation requires state-change, financial-write, and external-write permissions, but no email permission. Already-paid creation also requires email permission. Without draft-only mode, existing role behavior remains: ordinary users create drafts, Accounting creates checked bills, and Admin creates approved bills and writes to QuickBooks. Ordinary creation can also adjust existing QuickBooks placeholder bills. Explicit drafts defer those adjustments until the later approval/QuickBooks workflow. When later authorized to submit the draft, use `bb bill approval create <billId>` with its state-change and email permissions; Admin-created drafts also enter finance review through this command. The static command catalog lists the union of possible effects.
 
 **Approval email exclusions:** Approval requests create pending database records for every eligible approver, including configured non-recipient admin accounts. Automated approval-request emails skip those accounts.
@@ -315,7 +327,7 @@ Bill, claim, and quotation mutations accept only suppliers whose approval status
 | Area | Legacy handler labels (reference only; non-exhaustive) |
 | --- | --- |
 | **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`; cloned unavailable lines require `unavailableItemReviewAcknowledged: true`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `create-estimate`, `send-estimate-to-contact-person` (same contact-person email workflow as web), `add-budget-items`, `update-budget-item`, `replace-budget-item`, `approve-unavailable-item-exception` (Lead/Admin), `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `mark-budget-items-not-utilized`, `restore-budget-item`, `create-placeholder-bill` (admin recovery), `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `delete-budget-commission`, `update-budget-discount`, `delete-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
-| **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `validate-bill-selection` (`--payload`; validates the project and supplier separately, then checks approved quotation links for each selected budget line item independent of the bill supplier; `alreadyPaid` never bypasses the checks), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON; ownership and one-hour expiry are enforced by a server-side staged-upload record rather than encoded in the object key), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill, `isClaimable=true` for a claim; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`; admin creation automatically queues QBO finalization while other roles remain pending approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage linked to every selected line item, independent of the bill supplier, even when already paid), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (`PAID` requires `--paymentReference`; pass `--paymentProof <receipt.pdf>` to stage and submit a PDF up to 20MB atomically, or omit it only when BB already has payment proof; moving to `PAID` runs the server's paid-bill notification workflow), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
+| **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `validate-bill-selection` (`--payload`, plus `--quotationIds q1,q2` or legacy `--quotationId q1`; validates the approved supplier and quotation coverage), `link-bill-quotations` (`<billId> --quotationIds q1,q2`; Admin source-link repair for eligible supplier bills), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON; ownership and one-hour expiry are enforced by a server-side staged-upload record rather than encoded in the object key), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill and provide approved `quotationIds`, or use `--quotation-exempt` for an eligible server-validated exemption; set `isClaimable=true` for a claim without quotations; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`; admin creation automatically queues QBO finalization while other roles remain pending approval), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (`PAID` requires `--paymentReference`; pass `--paymentProof <receipt.pdf>` to stage and submit a PDF up to 20MB atomically, or omit it only when BB already has payment proof; moving to `PAID` runs the server's paid-bill notification workflow), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
 | **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` and `gstAmount`), `update-quotation` (`--payload`; updates a `DRAFT` or `REJECTED` quotation), `delete-quotation`, `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
 | **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `list-customer-invoices` (global/project/budget filters plus summary metrics; `--sortBy totalInvoiceAmount` sorts provider-confirmed totals including GST, with unknown amounts last), `get-customer-invoice`, `get-customer-invoice-email-context`, `preview-qbo-customer-invoice`, `import-qbo-customer-invoice` (BB-only link with reviewed token), `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
 | **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|customer_invoice\|all`), `approve-bill` / `reject-bill` (send reply email), `approve-budget` / `reject-budget` (send reply email), `approve-supplier` / `reject-supplier` (send reply email), `approve-quotation` / `reject-quotation`, `approve-customer-invoice` / `reject-customer-invoice` |
@@ -391,5 +403,6 @@ relationships or allocations block approval and require review. Multi-line quota
 create/update payloads must include `lineAmounts` with `{ budgetItemId, amount }`
 for every selected line, summing to `amountWithoutGst`. The server revalidates
 existing quotation links, reviewed usage, and per-line allowance inside the
-approval transaction. No new database fields or relationship declarations are
-required; unresolved historical overlaps continue to block approval.
+approval transaction. Multiple source quotations use canonical bill quotation
+allocation rows; apply the updated database schema and deploy the API before
+releasing the CLI. Unresolved historical overlaps continue to block approval.

package/command-manifest.json

@@ -2108,6 +2108,10 @@
 			{
 				"name": "--draft-only",
 				"description": "Create a draft for every role; no approval, email, or QuickBooks writes. Conflicts with alreadyPaid: true."
+			},
+			{
+				"name": "--quotation-exempt",
+				"description": "Explicitly request an eligible server-validated supplier-bill quotation exemption. Cannot be combined with quotation IDs."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -2158,12 +2162,78 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--quotationIds <csv>",
+				"description": "Approved quotation IDs for a supplier bill. Each selected budget item must be covered once."
+			},
+			{
+				"name": "--quotationId <id>",
+				"description": "Legacy syntax for selecting one approved quotation."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
 		"effects": [],
 		"legacyTarget": "validate-bill-selection"
 	},
+	{
+		"path": ["bill", "quotation", "link"],
+		"legacyAliases": ["link-bill-quotations", "link_bill_quotations", "billId"],
+		"summary": "Link Bill Quotations.",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--payload <json>",
+				"description": "Explicit quotationAllocations for split source coverage on the bill's stored line amounts."
+			},
+			{
+				"name": "--quotationIds <csv>",
+				"description": "Approved quotation IDs to link across the bill's disjoint line coverage."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "financial-write"],
+		"legacyTarget": "link-bill-quotations"
+	},
 	{
 		"path": ["bill", "update"],
 		"legacyAliases": ["update-bill", "update_bill"],

package/command-reference.md

@@ -361,6 +361,14 @@ Legacy aliases: `validate-bill-selection`, `validate_bill_selection`.
 
 Effects: none.
 
+## `bb bill quotation link`
+
+Link Bill Quotations.
+
+Legacy aliases: `link-bill-quotations`, `link_bill_quotations`, `billId`.
+
+Effects: state-change, financial-write.
+
 ## `bb bill update`
 
 Update Bill.

package/dist/index.js

@@ -20154,6 +20154,123 @@ function optionalString(v) {
   const s = String(v);
   return s === "" ? undefined : s;
 }
+var parseQuotationReferences = (input2, commandName) => {
+  const quotationId = optionalString(input2.quotationId)?.trim();
+  const rawAllocations = input2.quotationAllocations;
+  let quotationAllocations;
+  if (rawAllocations !== undefined && rawAllocations !== null) {
+    if (!Array.isArray(rawAllocations) || rawAllocations.length === 0) {
+      throw new Error(`${commandName} payload.quotationAllocations must be a non-empty array.`);
+    }
+    quotationAllocations = rawAllocations.map((raw, index) => {
+      const label = `${commandName} payload.quotationAllocations[${index}]`;
+      const allocation = requireObject(raw, label);
+      const amount = Number(allocation.amount);
+      if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
+        throw new Error(`${label}.amount must be a non-negative cent value.`);
+      }
+      return {
+        budgetItemId: requiredString(allocation.budgetItemId, `${label}.budgetItemId`),
+        quotationId: requiredString(allocation.quotationId, `${label}.quotationId`),
+        amount
+      };
+    });
+    const keys = quotationAllocations.map((allocation) => `${allocation.budgetItemId}\x00${allocation.quotationId}`);
+    if (new Set(keys).size !== keys.length) {
+      throw new Error(`${commandName} payload.quotationAllocations must not repeat a budget-item/quotation pair.`);
+    }
+  }
+  const rawQuotationIds = input2.quotationIds;
+  let quotationIds;
+  if (rawQuotationIds !== undefined && rawQuotationIds !== null) {
+    if (!Array.isArray(rawQuotationIds)) {
+      throw new Error(`${commandName} payload.quotationIds must be a string array.`);
+    }
+    quotationIds = rawQuotationIds.map((id, index) => requiredString(id, `${commandName} payload.quotationIds[${index}]`));
+    if (new Set(quotationIds).size !== quotationIds.length) {
+      throw new Error(`${commandName} payload.quotationIds must not contain duplicates.`);
+    }
+  }
+  if (quotationId && quotationIds && (quotationIds.length !== 1 || quotationIds[0] !== quotationId)) {
+    throw new Error(`${commandName} payload.quotationId conflicts with payload.quotationIds.`);
+  }
+  if (quotationAllocations && quotationIds) {
+    const allocationIds = [
+      ...new Set(quotationAllocations.map((allocation) => allocation.quotationId))
+    ].sort();
+    const selectedIds = [...quotationIds].sort();
+    if (allocationIds.join("\x00") !== selectedIds.join("\x00")) {
+      throw new Error(`${commandName} payload.quotationIds conflicts with payload.quotationAllocations.`);
+    }
+  }
+  return {
+    ...quotationId ? { quotationId } : {},
+    ...quotationIds ? { quotationIds } : {},
+    ...quotationAllocations ? { quotationAllocations } : {}
+  };
+};
+var parseBillLineAmounts = (input2, commandName) => {
+  if (input2.lineAmounts === undefined || input2.lineAmounts === null)
+    return;
+  if (!Array.isArray(input2.lineAmounts) || input2.lineAmounts.length === 0) {
+    throw new Error(`${commandName} payload.lineAmounts must be a non-empty array.`);
+  }
+  const lineAmounts = input2.lineAmounts.map((raw, index) => {
+    const label = `${commandName} payload.lineAmounts[${index}]`;
+    const line = requireObject(raw, label);
+    const amount = Number(line.amount);
+    if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
+      throw new Error(`${label}.amount must be a non-negative cent value.`);
+    }
+    return {
+      budgetItemId: requiredString(line.budgetItemId, `${label}.budgetItemId`),
+      amount
+    };
+  });
+  if (new Set(lineAmounts.map((line) => line.budgetItemId)).size !== lineAmounts.length) {
+    throw new Error(`${commandName} payload.lineAmounts must contain each budget item once.`);
+  }
+  return lineAmounts;
+};
+var cents = (amount) => Math.round(amount * 100);
+var validateExplicitBillAllocations = ({
+  amount,
+  budgetItemIds,
+  commandName,
+  lineAmounts,
+  quotationAllocations
+}) => {
+  if (!lineAmounts && !quotationAllocations)
+    return;
+  if (!lineAmounts) {
+    throw new Error(`${commandName} payload.lineAmounts is required with quotationAllocations.`);
+  }
+  const selected = new Set(budgetItemIds);
+  if (lineAmounts.length !== selected.size || lineAmounts.some((line) => !selected.has(line.budgetItemId))) {
+    throw new Error(`${commandName} payload.lineAmounts must contain each selected budget item exactly once.`);
+  }
+  if (lineAmounts.reduce((sum, line) => sum + cents(line.amount), 0) !== cents(amount)) {
+    throw new Error(`${commandName} payload.lineAmounts must sum to payload.amount.`);
+  }
+  if (!quotationAllocations)
+    return;
+  const lineAmountById = new Map(lineAmounts.map((line) => [line.budgetItemId, cents(line.amount)]));
+  const allocatedById = new Map;
+  for (const allocation of quotationAllocations) {
+    if (!selected.has(allocation.budgetItemId)) {
+      throw new Error(`${commandName} payload.quotationAllocations references an unselected budget item.`);
+    }
+    allocatedById.set(allocation.budgetItemId, (allocatedById.get(allocation.budgetItemId) ?? 0) + cents(allocation.amount));
+    if (cents(allocation.amount) === 0 && lineAmountById.get(allocation.budgetItemId) !== 0) {
+      throw new Error(`${commandName} zero quotation allocations are only valid for zero-value bill lines.`);
+    }
+  }
+  for (const [budgetItemId, allocated] of allocatedById) {
+    if (allocated > (lineAmountById.get(budgetItemId) ?? 0)) {
+      throw new Error(`${commandName} quotation allocations exceed the line amount for ${budgetItemId}.`);
+    }
+  }
+};
 function requiredString(value, fieldLabel) {
   if (value === undefined || value === null) {
     throw new Error(`${fieldLabel} is required.`);
@@ -20259,7 +20376,7 @@ var billAttachment = (x, i, field = "attachments") => {
     size: Number(a.size)
   };
 };
-function parseCreateBillPayload(raw, draftOnlyFlag) {
+function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, requireSupplierQuotation = true) {
   const o = requireObject(raw, "create-bill payload");
   const isClaimable = o.isClaimable;
   if (typeof isClaimable !== "boolean") {
@@ -20315,13 +20432,36 @@ function parseCreateBillPayload(raw, draftOnlyFlag) {
   if (!Number.isFinite(amount) || amount < 0) {
     throw new Error("create-bill payload.amount must be a number >= 0.");
   }
+  const quotationReferences = parseQuotationReferences(o, "create-bill");
+  const parsedBudgetItemIds = budgetItemIds.map((id, i) => requiredString(id, `create-bill payload.budgetItemIds[${i}]`));
+  const lineAmounts = parseBillLineAmounts(o, "create-bill");
+  validateExplicitBillAllocations({
+    amount,
+    budgetItemIds: parsedBudgetItemIds,
+    commandName: "create-bill",
+    lineAmounts,
+    quotationAllocations: quotationReferences.quotationAllocations
+  });
+  if (quotationExempt && isClaimable) {
+    throw new Error("--quotation-exempt is only valid for supplier bills.");
+  }
+  if (quotationExempt && (quotationReferences.quotationId || (quotationReferences.quotationIds?.length ?? 0) > 0 || (quotationReferences.quotationAllocations?.length ?? 0) > 0)) {
+    throw new Error("--quotation-exempt cannot be combined with payload quotation IDs.");
+  }
+  if (isClaimable && (quotationReferences.quotationId || (quotationReferences.quotationIds?.length ?? 0) > 0 || (quotationReferences.quotationAllocations?.length ?? 0) > 0)) {
+    throw new Error("Employee claims cannot include quotation source inputs.");
+  }
+  if (requireSupplierQuotation && !quotationExempt && !isClaimable && !quotationReferences.quotationId && (quotationReferences.quotationIds?.length ?? 0) === 0 && (quotationReferences.quotationAllocations?.length ?? 0) === 0) {
+    throw new Error("create-bill supplier bills require payload.quotationAllocations, payload.quotationIds, or legacy payload.quotationId.");
+  }
   return {
     budgetId: requiredString(o.budgetId, "create-bill payload.budgetId"),
     projectId: requiredString(o.projectId, "create-bill payload.projectId"),
     supplierId: requiredString(o.supplierId, "create-bill payload.supplierId"),
-    quotationId: optionalString(o.quotationId),
+    ...quotationReferences,
     amount,
-    budgetItemIds: budgetItemIds.map((id, i) => requiredString(id, `create-bill payload.budgetItemIds[${i}]`)),
+    budgetItemIds: parsedBudgetItemIds,
+    ...lineAmounts ? { lineAmounts } : {},
     comment: optionalString(o.comment),
     isClaimable,
     attachments,
@@ -20339,7 +20479,7 @@ function parseCreateBillPayload(raw, draftOnlyFlag) {
 }
 function parseUpdateBillPayload(raw) {
   const o = requireObject(raw, "update-bill payload");
-  const { draftOnly, ...input2 } = parseCreateBillPayload(raw);
+  const { draftOnly, ...input2 } = parseCreateBillPayload(raw, undefined, false, false);
   if (draftOnly !== undefined) {
     throw new Error("draftOnly is only supported when creating a bill.");
   }
@@ -20348,9 +20488,60 @@ function parseUpdateBillPayload(raw) {
     id: requiredString(o.id, "update-bill payload.id")
   };
 }
-function parseValidateBillSelectionPayload(raw) {
-  requireObject(raw, "validate-bill-selection payload");
-  return raw;
+function parseValidateBillSelectionPayload(raw, quotationFlags = {}) {
+  const input2 = requireObject(raw, "validate-bill-selection payload");
+  const payloadReferences = parseQuotationReferences(input2, "validate-bill-selection");
+  const flagReferences = parseQuotationReferences({ ...quotationFlags }, "validate-bill-selection flags");
+  const payloadIds = payloadReferences.quotationIds ?? (payloadReferences.quotationId ? [payloadReferences.quotationId] : undefined);
+  const flagIds = flagReferences.quotationIds ?? (flagReferences.quotationId ? [flagReferences.quotationId] : undefined);
+  if (payloadIds && flagIds && payloadIds.join("\x00") !== flagIds.join("\x00")) {
+    throw new Error("validate-bill-selection quotation flags conflict with the payload quotation IDs.");
+  }
+  const isClaimable = input2.isClaimable;
+  if (isClaimable !== undefined && typeof isClaimable !== "boolean") {
+    throw new Error("validate-bill-selection payload.isClaimable must be boolean.");
+  }
+  if (isClaimable === true && (payloadReferences.quotationId || (payloadReferences.quotationIds?.length ?? 0) > 0 || (payloadReferences.quotationAllocations?.length ?? 0) > 0 || !!flagReferences.quotationId || (flagReferences.quotationIds?.length ?? 0) > 0)) {
+    throw new Error("Employee claims cannot include quotation source inputs.");
+  }
+  const lineAmounts = parseBillLineAmounts(input2, "validate-bill-selection");
+  const budgetItemIds = Array.isArray(input2.budgetItemIds) ? input2.budgetItemIds.map((id, index) => requiredString(id, `validate-bill-selection payload.budgetItemIds[${index}]`)) : [];
+  const amount = input2.amount === undefined || input2.amount === null ? undefined : Number(input2.amount);
+  if (lineAmounts || payloadReferences.quotationAllocations) {
+    if (amount === undefined || !Number.isFinite(amount) || budgetItemIds.length === 0) {
+      throw new Error("validate-bill-selection explicit allocations require payload.amount and payload.budgetItemIds.");
+    }
+    validateExplicitBillAllocations({
+      amount,
+      budgetItemIds,
+      commandName: "validate-bill-selection",
+      lineAmounts,
+      quotationAllocations: payloadReferences.quotationAllocations
+    });
+  }
+  return {
+    ...input2,
+    ...amount !== undefined ? { amount } : {},
+    ...isClaimable !== undefined ? { isClaimable } : {},
+    ...lineAmounts ? { lineAmounts } : {},
+    ...payloadReferences,
+    ...flagReferences
+  };
+}
+function parseLinkBillQuotationsPayload(billId, raw) {
+  const input2 = requireObject(raw, "link-bill-quotations payload");
+  const references = parseQuotationReferences(input2, "link-bill-quotations");
+  if (references.quotationId) {
+    throw new Error("link-bill-quotations payload uses quotationIds or quotationAllocations; legacy quotationId is not supported.");
+  }
+  if ((references.quotationIds?.length ?? 0) === 0 && (references.quotationAllocations?.length ?? 0) === 0) {
+    throw new Error("link-bill-quotations payload requires quotationIds or quotationAllocations.");
+  }
+  return {
+    billId: requiredString(billId, "billId"),
+    ...references.quotationIds ? { quotationIds: references.quotationIds } : {},
+    ...references.quotationAllocations ? { quotationAllocations: references.quotationAllocations } : {}
+  };
 }
 function parseUpdateBillPaymentEvidencePayload(raw) {
   requireObject(raw, "update-bill-payment-evidence payload");
@@ -22048,8 +22239,8 @@ async function deleteItemCategoriesByIds(ids) {
   const result = await api2.itemCategory.deleteItemCategories.mutate({ ids });
   out(result);
 }
-async function createBillFromPayload(raw, draftOnlyFlag) {
-  const input2 = parseCreateBillPayload(raw, draftOnlyFlag);
+async function createBillFromPayload(raw, draftOnlyFlag, quotationExempt = false) {
+  const input2 = parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt);
   await confirmCurrentCommand({
     action: input2.draftOnly ? "bill create (draft only)" : "bill create",
     target: `project ${input2.projectId}, supplier ${input2.supplierId}`,
@@ -22250,11 +22441,16 @@ async function updateBillFromPayload(raw) {
   const result = await api2.bill.update.mutate(input2);
   out(result);
 }
-var validateBillSelectionFromPayload = async (raw) => {
-  const input2 = parseValidateBillSelectionPayload(raw);
+var validateBillSelectionFromPayload = async (raw, quotationFlags) => {
+  const input2 = parseValidateBillSelectionPayload(raw, quotationFlags);
   const result = await api2.bill.validateSelection.mutate(input2);
   out(result);
 };
+var linkBillQuotations = async (billId, raw) => {
+  const input2 = parseLinkBillQuotationsPayload(billId, raw);
+  const result = await api2.bill.linkQuotations.mutate(input2);
+  out(result);
+};
 var updateBillPaymentEvidenceFromPayload = async (raw) => {
   const input2 = parseUpdateBillPaymentEvidencePayload(raw);
   const result = await api2.bill.updatePaymentEvidence.mutate(input2);
@@ -23092,6 +23288,7 @@ var mutationPrefixes = [
   "delete-",
   "discard-",
   "import-",
+  "link-",
   "mark-",
   "patch-",
   "reactivate-",
@@ -23180,6 +23377,7 @@ var externalWriteTargets = new Set([
 ]);
 var financialWriteTargets = new Set([
   "import-qbo-customer-invoice",
+  "link-bill-quotations",
   "approve-bill",
   "approve-customer-invoice",
   "complete-project",
@@ -23358,9 +23556,32 @@ var registry2 = [
     {
       name: "--draft-only",
       description: "Create a draft for every role; no approval, email, or QuickBooks writes. Conflicts with alreadyPaid: true."
+    },
+    {
+      name: "--quotation-exempt",
+      description: "Explicitly request an eligible server-validated supplier-bill quotation exemption. Cannot be combined with quotation IDs."
+    }
+  ]),
+  legacyCommand("validate-bill-selection", ["bill", "selection", "validate"], [], [
+    {
+      name: "--quotationIds <csv>",
+      description: "Approved quotation IDs for a supplier bill. Each selected budget item must be covered once."
+    },
+    {
+      name: "--quotationId <id>",
+      description: "Legacy syntax for selecting one approved quotation."
+    }
+  ]),
+  legacyCommand("link-bill-quotations", ["bill", "quotation", "link"], ["billId"], [
+    {
+      name: "--payload <json>",
+      description: "Explicit quotationAllocations for split source coverage on the bill's stored line amounts."
+    },
+    {
+      name: "--quotationIds <csv>",
+      description: "Approved quotation IDs to link across the bill's disjoint line coverage."
     }
   ]),
-  legacyCommand("validate-bill-selection", ["bill", "selection", "validate"]),
   legacyCommand("update-bill", ["bill", "update"]),
   legacyCommand("update-bill-payment-evidence", [
     "bill",
@@ -23912,10 +24133,11 @@ Bills
   list-bills                 [--projectId] [--budgetId] [--status CSV] [--search <text>] [--isClaimable true|false] [--createdByIds <csv>] [--sortBy createdAt|amount|status] [--sortDir asc|desc] [--page] [--pageSize]
   list-claims                same flags as list-bills; only reimbursable claims (ignores --isClaimable)
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
-  Non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage linked to every selected line item, independent of the bill supplier, including already-paid bills.
+  Create supplier bills from approved quotations from the same supplier and project. Use quotationAllocations plus lineAmounts when quotations split one bill line. Eligible exemptions require explicit --quotation-exempt intent; claims do not consume or link quotations.
   create-bill-approval <billId>       (also queues approval request emails)
-  create-bill                --payload '<json>' [--draft-only]  (bill.create; payload.isClaimable false = bill, true = claim; supplier must be APPROVED)
-  validate-bill-selection    --payload '<json>'  Require an APPROVED supplier, then verify approved quotation links for each budgetItemId; alreadyPaid never bypasses quotation checks.
+  create-bill                --payload '<json>' [--draft-only] [--quotation-exempt]  (bill.create; supplier bills use payload.quotationAllocations for split sources or quotationIds for disjoint coverage; explicit allocations require lineAmounts; claims reject quotation sources)
+  validate-bill-selection    --payload '<json>' [--quotationIds <csv> | --quotationId <id>]  Validate an approved supplier and approved quotation coverage for each supplier-bill line. --quotationId is legacy single-quotation syntax.
+  link-bill-quotations       <billId> (--payload '<json>' | --quotationIds <csv>)  Admin-only source-link repair; payload.quotationAllocations supports same-line splits.
   stage-bill-attachment <projectId> <filePath...> [--file <path>] [--files <csv>]   Upload files before create-bill; returns attachment JSON for attachments/paymentProofAttachments
   cleanup-staged-bill-attachments <projectId> --keys <csv>   Delete unattached staged bill/claim uploads.
   update-bill                --payload '<json>'  (bill.update; must include id)
@@ -24769,7 +24991,11 @@ Waiting for approval\u2026
         }
         const raw = parseJsonFlag(String(payloadRaw), "--payload");
         const draftOnly = flags["draft-only"] === true ? true : parseOptionalBoolFlag(flags, "draft-only");
-        await createBillFromPayload(raw, draftOnly);
+        const quotationExempt = flags["quotation-exempt"] === true;
+        if (flags["quotation-exempt"] !== undefined && flags["quotation-exempt"] !== true) {
+          throw new Error("--quotation-exempt does not take a value.");
+        }
+        await createBillFromPayload(raw, draftOnly, quotationExempt);
         break;
       }
       case "validate-bill-selection": {
@@ -24778,7 +25004,37 @@ Waiting for approval\u2026
           throw new Error("validate-bill-selection requires --payload '<json>'");
         }
         const raw = parseJsonFlag(String(payloadRaw), "--payload");
-        await validateBillSelectionFromPayload(raw);
+        if (flags.quotationIds === true || flags.quotationId === true) {
+          throw new Error("--quotationIds requires a CSV value and --quotationId requires an ID value.");
+        }
+        const quotationIds = parseCommaSeparatedIds(getFlag(flags, "quotationIds"));
+        const quotationId = getFlag(flags, "quotationId")?.trim() || undefined;
+        if (quotationId && quotationIds && (quotationIds.length !== 1 || quotationIds[0] !== quotationId)) {
+          throw new Error("--quotationId conflicts with --quotationIds.");
+        }
+        if (quotationIds && new Set(quotationIds).size !== quotationIds.length) {
+          throw new Error("--quotationIds must not contain duplicates.");
+        }
+        await validateBillSelectionFromPayload(raw, {
+          ...quotationId ? { quotationId } : {},
+          ...quotationIds ? { quotationIds } : {}
+        });
+        break;
+      }
+      case "link-bill-quotations": {
+        const billId = positional[0];
+        const payloadRaw = getFlag(flags, "payload");
+        const quotationIds = parseCommaSeparatedIds(getFlag(flags, "quotationIds"));
+        if (!billId || !payloadRaw && (!quotationIds || quotationIds.length === 0)) {
+          throw new Error("link-bill-quotations requires <billId> and either --payload '<json>' or --quotationIds <csv>");
+        }
+        if (payloadRaw && quotationIds) {
+          throw new Error("--payload cannot be combined with --quotationIds.");
+        }
+        if (quotationIds && new Set(quotationIds).size !== quotationIds.length) {
+          throw new Error("--quotationIds must not contain duplicates.");
+        }
+        await linkBillQuotations(billId, payloadRaw ? parseJsonFlag(String(payloadRaw), "--payload") : { quotationIds });
         break;
       }
       case "update-bill": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.31.1",
+  "version": "2.33.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",

package/role-aware-agent-guide.md

@@ -129,6 +129,7 @@ The following distinctions are especially important:
 - Project Hub setup and sync are asynchronous external writes. Read `bb project hub status <project-id>` first, obtain explicit approval, and request the mutation once instead of repeatedly queueing it. Setup readiness remains visible through `status`; commercial sync returns an outbox operation ID for Admin diagnostics.
 - Bill/claim status commands have separate role rules for `CHECKED`, `APPROVED`, and `PAID`.
 - `bb bill create --payload` uses `isClaimable=false`; `isClaimable=true` creates a claim. Claims intentionally permit some base-user flows that supplier bills do not.
+- Create supplier bills from approved quotations by passing `quotationIds` for disjoint coverage, or `quotationAllocations` plus exact `lineAmounts` when quotations split a bill line. A required zero-value bill line needs one or more `quotationAllocations` entries with `amount: 0` so its approved source(s) are retained without consuming quotation capacity. Use `--quotation-exempt` only for an existing server-validated exemption. Claims share budget allowance but never consume or link quotations, and reject quotation source fields.
 - For a draft-only bill or claim, use `bb bill create --draft-only --payload` (or `draftOnly: true` in the payload). This forces `DRAFT` for every role and requires only `--allow-state-change --allow-financial-write`. It sends no approval/email and performs no QuickBooks writes. Do not combine it with `alreadyPaid: true`. An older API without `bill.createDraft` rejects the command; never retry with ordinary creation to bypass that error.
 - Ordinary unpaid creation does not require `--allow-email`, but remains role-dependent: Accounting auto-checks and Admin auto-approves. It still requires `--allow-external-write`, including for possible placeholder adjustments. Already-paid creation retains the email gate.
 - Staged attachments belong to the user in the database. Do not reuse, share, or manually construct staged keys.