@go-labs-sg/bb 2.31.0 → 2.32.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. Every quotation must belong to the bill supplier and project and cover the allocated budget item. Legacy `quotationId` remains valid for one quotation. 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.
@@ -244,6 +256,38 @@ Bill creation determines its required permissions from the parsed input, for bot
 
 **Contact-person estimate email:** `bb budget estimate send --payload '<json>'` calls the same `email.sendEstimateToContactPerson` procedure as the web composer. The payload requires `budgetId`, `estimateId`, optional `estimateDocNumber`, `to`, `cc`, `replyTo`, `subject`, HTML `content`, and HTML `signature`. It durably queues worker delivery of the QuickBooks PDF, standard terms, and Budget Builder budget attachments, and returns the outbound-email and operation IDs immediately. Worker retries reuse one provider idempotency key; the budget becomes `ESTIMATE_SENT` only after Resend accepts the email. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first.
 
+### Link an existing QuickBooks invoice
+
+**Release status:** these CLI commands are pending release. The repository package version remains `2.31.0`; that version number alone does not establish that a published CLI contains them. Check `bb help` for `customer-invoice preview-qbo` and `customer-invoice import-qbo` after the normal CLI release. This code delivery does not publish the CLI, deploy the API, or perform a production import. The backend must expose `customerInvoice.previewExistingInvoice` and `customerInvoice.linkExistingInvoice` (implemented in PR #1067).
+
+Authenticate and run `bb auth whoami` first. Preview and import use the same project management permission as the web flow: with user access checks enabled, Admins or the project's creator, business-development owner, inside-sales owner, or project manager can act. A finance/Lead role alone does not grant access to an unrelated project. The server applies its current access-check configuration and rechecks permission during confirmation.
+
+Use the **BB budget ID** whose existing estimate should receive the invoice, and the numeric **QBO invoice transaction ID**, not the displayed invoice number or an estimate number. Accepted and closed estimates are supported; linking does not reopen them. Fully invoiced means all estimate coverage has been billed; it does not mean the invoices are fully paid.
+
+```bash
+bb customer-invoice preview-qbo <budgetId> <qboInvoiceId>
+bb customer-invoice import-qbo <budgetId> <qboInvoiceId> --token <previewToken>
+```
+
+Preview performs read-only QBO access and returns JSON under `data`, including `token`, project/estimate, invoice number/identity, currency, dates, total, outstanding `balance`, allocation `percentage`, lines, `alreadyLinked`, and other unlinked invoices. Review all of it before confirming. Import requires the exact `data.token` from that preview; it does not silently generate a fresh token. In an interactive terminal, confirm the named invoice and budget when prompted. For an explicitly authorized non-interactive import:
+
+```bash
+bb customer-invoice import-qbo <budgetId> <qboInvoiceId> \
+  --token <previewToken> --allow-state-change --allow-financial-write
+```
+
+Import writes BB financial records only and needs neither `--allow-external-write` nor `--allow-email`. It calls the same server validation as the UI: project/customer/currency/estimate/allocation checks, sibling invoice coverage, and financial drift checks. It preserves the original invoice evidence and does not create, update, void, delete, send, or match anything in QBO. A successful response returns `batchId`, `invoiceId` (the new BB invoice ID), and `alreadyLinked: false`. Repeating the same link returns the original IDs with `alreadyLinked: true`, provided upstream financial evidence still agrees. A conflicting budget, ambiguous allocation, or financial mismatch fails; a stale preview requires another reviewed preview. Do not retry a conflict with a different budget to bypass it.
+
+To refresh payments, use the returned **BB invoice ID**:
+
+```bash
+bb customer-invoice sync <invoiceId>
+```
+
+For `QBO_IMPORT` invoices, this existing command reads QBO and updates BB balance, payment status, and sync evidence only. Settlement becomes `PAID`; a reversal restores `APPROVED`; original invoice evidence is retained. Financial drift is reported separately as `qboFinancialDrift` and blocks further billing. The shared sync command also supports native invoices, so its generic automation permissions remain `--allow-state-change --allow-financial-write --allow-external-write`; imported records still take the server's BB-only path. Native creation continues to use `bb customer-invoice create --payload '<json>'` and needs no import token or fields.
+
+The Seatrium example must be previewed against live QBO again before an operator imports it. Previously observed invoice numbers and paid/open balances are not authorization or current-state evidence.
+
 **Customer-invoice workflow parity:** `bb customer-invoice list` uses the same global/project list procedure and metrics as the web pages; omit filters for the global list or use `--projectId` for project scope. `bb customer-invoice send --payload '<json>'` uses the same protected email workflow as the web composer, sends to the payload's `to` address, saves that address as the project's configured billing email after a successful send, and marks the invoice `SENT`. `bb customer-invoice approve` and `bb customer-invoice reject` are Admin-only batch operations: callers select a batch ID, and the API resolves its internal pending Admin approval record. `bb customer-invoice sync` follows QuickBooks' paid state and zero balance, restoring `SENT` or `APPROVED` if that payment is reversed. Invoice approval refuses voided invoices and closes the estimate only when approved invoice coverage totals 100%; deletion, voiding, rejection, expiry, and QBO synchronization use the same estimate-reopening and live-payment guards as the web app.
 
 For agent-driven invoice work, use this read-before-write sequence:
@@ -283,9 +327,9 @@ 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`, `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` |
+| **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` |
 | **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project` (its budget overview returns `totalRevenue`, calculated only from Estimate Accepted and Estimate Closed budgets), `get-project-hub-status`, `setup-project-hub`, `sync-project-hub-commercial-documents`, `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--startDate` as ISO datetime for project/window start; when `--asanaTaskId` is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional `--asanaSearch`, `--pax`, `--endDate`, `--description`, `--projectManagerId`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `projectManagerId` and `requestQboAccountantNotification` in JSON), `delete-project`, `check-project-reconciliation <id>` (runs the web app's live checks without changing status), `reconcile-project <id>` (reruns checks transactionally and marks an eligible project `RECONCILED`), `complete-project <id>` (reruns validation, marks a reconciled project `COMPLETED`, and queues QuickBooks placeholder cleanup), `import-qbo-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `RECONCILED` \| `LOST`; close-out follows `WON` → `RECONCILED` → `COMPLETED`, and reconciliation requires every accepted/closed budget line to have an Approved/Paid bill or claim or be explicitly Not Utilized; marking `COMPLETED` queues deletion of every remaining project placeholder bill from QuickBooks; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
 | **Contacts** | `list-contacts`, `create-contact-person` (`--payload`), `update-contact-person` (`--payload`) |
@@ -359,5 +403,7 @@ 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 `BillLineItem.quotationId`;
+apply the updated database schema and deploy the API before releasing the CLI.
+Legacy bill-wide links remain readable, and 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"],
@@ -3643,6 +3713,112 @@
 		"effects": [],
 		"legacyTarget": "get-customer-invoice-email-context"
 	},
+	{
+		"path": ["customer-invoice", "preview-qbo"],
+		"legacyAliases": [
+			"preview-qbo-customer-invoice",
+			"preview_qbo_customer_invoice"
+		],
+		"summary": "Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.",
+		"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."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "preview-qbo-customer-invoice"
+	},
+	{
+		"path": ["customer-invoice", "import-qbo"],
+		"legacyAliases": [
+			"import-qbo-customer-invoice",
+			"import_qbo_customer_invoice"
+		],
+		"summary": "Link an existing QuickBooks invoice in BB only after reviewing preview-qbo. Arguments: <budgetId> <qboInvoiceId> --token <previewToken>. Supports closed estimates; no QBO writes or emails.",
+		"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."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "financial-write"],
+		"legacyTarget": "import-qbo-customer-invoice"
+	},
 	{
 		"path": ["customer-invoice", "create"],
 		"legacyAliases": ["create-customer-invoice", "create_customer_invoice"],

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.
@@ -593,6 +601,22 @@ Legacy aliases: `get-customer-invoice-email-context`, `get_customer_invoice_emai
 
 Effects: none.
 
+## `bb customer-invoice preview-qbo`
+
+Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.
+
+Legacy aliases: `preview-qbo-customer-invoice`, `preview_qbo_customer_invoice`.
+
+Effects: none.
+
+## `bb customer-invoice import-qbo`
+
+Link an existing QuickBooks invoice in BB only after reviewing preview-qbo. Arguments: <budgetId> <qboInvoiceId> --token <previewToken>. Supports closed estimates; no QBO writes or emails.
+
+Legacy aliases: `import-qbo-customer-invoice`, `import_qbo_customer_invoice`.
+
+Effects: state-change, financial-write.
+
 ## `bb customer-invoice create`
 
 Create Customer Invoice.

package/dist/index.js

@@ -20154,6 +20154,120 @@ 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 positive 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));
+  }
+  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 +20373,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 +20429,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 +20476,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 +20485,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 +22236,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}`,
@@ -22134,6 +22322,19 @@ var getCustomerInvoiceEmailContext = async (batchId) => {
   });
   out(result);
 };
+var previewQboCustomerInvoice = async (input2) => {
+  const result = await api2.customerInvoice.previewExistingInvoice.mutate(input2);
+  out(result);
+};
+var importQboCustomerInvoice = async (input2) => {
+  await confirmCurrentCommand({
+    action: "Link existing QuickBooks invoice",
+    target: `QuickBooks invoice ${input2.qboInvoiceId} to budget ${input2.budgetId}`,
+    details: "records the reviewed invoice in Budget Builder only; QuickBooks access is read-only; preserves original evidence and revalidates the preview token"
+  });
+  const result = await api2.customerInvoice.linkExistingInvoice.mutate(input2);
+  out(result);
+};
 var createCustomerInvoice = async (raw) => {
   const input2 = parseCreateCustomerInvoicePayload(raw);
   await assertSensitiveWorkflowConfirmed({
@@ -22237,11 +22438,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);
@@ -23079,6 +23285,7 @@ var mutationPrefixes = [
   "delete-",
   "discard-",
   "import-",
+  "link-",
   "mark-",
   "patch-",
   "reactivate-",
@@ -23166,6 +23373,8 @@ var externalWriteTargets = new Set([
   "void-customer-invoice"
 ]);
 var financialWriteTargets = new Set([
+  "import-qbo-customer-invoice",
+  "link-bill-quotations",
   "approve-bill",
   "approve-customer-invoice",
   "complete-project",
@@ -23223,6 +23432,12 @@ var effectsFor = (legacyTarget) => {
 };
 var titleCase = (value) => value.split("-").map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(" ");
 var summaryFor = (legacyTarget) => {
+  if (legacyTarget === "preview-qbo-customer-invoice") {
+    return "Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.";
+  }
+  if (legacyTarget === "import-qbo-customer-invoice") {
+    return "Link an existing QuickBooks invoice in BB only after reviewing preview-qbo. Arguments: <budgetId> <qboInvoiceId> --token <previewToken>. Supports closed estimates; no QBO writes or emails.";
+  }
   if (legacyTarget === "whoami")
     return "Show the active API-key identity.";
   if (legacyTarget === "create-bill") {
@@ -23338,9 +23553,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",
@@ -23408,6 +23646,14 @@ var registry2 = [
     "email-context",
     "get"
   ]),
+  legacyCommand("preview-qbo-customer-invoice", [
+    "customer-invoice",
+    "preview-qbo"
+  ]),
+  legacyCommand("import-qbo-customer-invoice", [
+    "customer-invoice",
+    "import-qbo"
+  ]),
   legacyCommand("create-customer-invoice", ["customer-invoice", "create"]),
   legacyCommand("discard-customer-invoice", ["customer-invoice", "discard"]),
   legacyCommand("delete-customer-invoice", ["customer-invoice", "delete"]),
@@ -23884,10 +24130,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)
@@ -23927,6 +24174,8 @@ Customer invoices
     No scope flag lists invoices globally. --projectId uses the project scope. A positional budgetId is a backward-compatible shortcut for --budgetIds.
   get-customer-invoice <batchId>
   get-customer-invoice-email-context <batchId>        Contact, required CC, budget, and project context for composing an invoice email.
+  preview-qbo-customer-invoice <budgetId> <qboInvoiceId>   Preview linking an existing QBO transaction (numeric ID, not invoice number); works on accepted/closed estimates.
+  import-qbo-customer-invoice <budgetId> <qboInvoiceId> --token <previewToken>   Confirm the reviewed BB-only link; requires --allow-state-change --allow-financial-write in automation.
   create-customer-invoice --payload '<json>'   budgetId + one split with label, percentage, and dueDate.
   discard-customer-invoice <batchId>           Discard a reserved CREATING batch with no created QBO invoices.
   delete-customer-invoice <batchId>            Delete QBO invoices and the local batch.
@@ -24371,7 +24620,7 @@ Waiting for approval\u2026
       }
       configureAccessToken(accessToken);
     }
-    if (!resolvedCommand.isLegacyAlias && cmd !== "create-bill" && resolvedCommand.command.effects.length > 0) {
+    if (!resolvedCommand.isLegacyAlias && cmd !== "create-bill" && cmd !== "import-qbo-customer-invoice" && resolvedCommand.command.effects.length > 0) {
       await confirmCurrentCommand({
         action: resolvedCommand.command.path.join(" "),
         target: commandConfirmationTarget(resolvedCommand),
@@ -24739,7 +24988,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": {
@@ -24748,7 +25001,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": {
@@ -25123,6 +25406,26 @@ Waiting for approval\u2026
         await getCustomerInvoiceEmailContext(batchId);
         break;
       }
+      case "preview-qbo-customer-invoice":
+      case "import-qbo-customer-invoice": {
+        const [budgetId, qboInvoiceId] = positional;
+        if (!budgetId?.trim() || !qboInvoiceId || positional.length !== 2) {
+          throw new Error(`${cmd} requires <budgetId> <qboInvoiceId>`);
+        }
+        if (!/^\d+$/.test(qboInvoiceId)) {
+          throw new Error("qboInvoiceId must be the numeric QuickBooks transaction ID, not the invoice number");
+        }
+        if (cmd === "preview-qbo-customer-invoice") {
+          await previewQboCustomerInvoice({ budgetId, qboInvoiceId });
+        } else {
+          const token = getFlag(flags, "token");
+          if (!token || !/^[a-f0-9]{64}$/.test(token)) {
+            throw new Error("import-qbo-customer-invoice requires --token <64-character preview token> from a reviewed preview-qbo result");
+          }
+          await importQboCustomerInvoice({ budgetId, qboInvoiceId, token });
+        }
+        break;
+      }
       case "create-customer-invoice": {
         const payloadRaw = getFlag(flags, "payload");
         if (!payloadRaw) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.31.0",
+  "version": "2.32.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. 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.