@go-labs-sg/bb 2.36.0 → 2.38.0

package/README.md

@@ -193,7 +193,7 @@ Run `bb version` before agent-driven work to record the installed package versio
 
 **Authoritative command list:** run `bb help` or inspect the generated `command-reference.md` / `command-manifest.json`. The catalog includes every canonical route, global option, and effect classification, but does not filter by the current `whoami` role. During the handler migration, command-specific arguments retain the compatibility dispatcher's validation and are explicitly marked `legacy-passthrough` in the manifest; use `bb help --legacy` for their detailed transition reference. Version 2 uses grouped, resource-first commands such as `bb budget list` and `bb bill attachment upload`. Flat commands such as `bb list-budgets` and their MCP-style `snake_case` aliases remain available during the v2 transition, with a deprecation notice and an equivalent grouped command in help. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI.
 
-**Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. The first accepted estimate also requires `--invoiceSettings '<json>'` while customer invoicing is enabled. Provide `depositPercentage`, `balancePercentage`, `deliveryMethod`, and the matching `billingEmail` or HTTPS `uploadUrl`; revenue at or below S$5,000 requires `100/0`. If the parent project is `PITCH` or `LOST`, the API marks it `WON` automatically and runs enabled Asana automation. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
+**Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. `--invoiceSettings '<json>'` remains available when the project needs saved delivery preferences, but invoice creation chooses its amount independently from those settings. If the parent project is `PITCH` or `LOST`, the API marks it `WON` automatically and runs enabled Asana automation. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
 ### Typeform inbound administration
 
@@ -306,51 +306,40 @@ 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.
 
-### Acceptance invoice splits and grouped sending
+### Invoice amount, due date, and approval
 
-After `bb budget won mark` (or an accepted status update), the JSON result includes an `invoiceSetup` prompt for QuickBooks-backed estimates. Choose the split amounts and each split's contractual due date; invoice creation does not wait for those due dates. There is no separate split-approval request.
+After accepting an estimate, choose any eligible budget with an uninvoiced balance. Create one invoice at a time for all or part of the remaining estimate percentage. Creation is immediate; the due date is the payment deadline.
 
-1. `bb customer-invoice splits <budgetId>` returns the current revision, row IDs, billing defaults, and invoice approval/delivery states.
-2. `bb customer-invoice preview-splits --payload '<json>'` previews amounts including GST and due-date changes, without writes.
-3. `bb customer-invoice save-splits --payload '<json>'` saves that setup only. It does not create QBO invoices or request invoice approval. Re-read `splits` for the new revision and instalment IDs.
-4. `bb customer-invoice create-splits --payload '{"budgetId":"budget_1","expectedRevision":2,"instalmentIds":["row_1","row_2"]}'` creates selected ready invoices in QBO. Non-admin creation automatically requests admin approval **after creation**; admin creation auto-approves. No customer email is sent.
-5. An admin uses the existing `bb customer-invoice approve <batchId>` action for each pending invoice batch. Approval does not send the invoice to the customer.
-6. The user re-reads `splits`, then runs `bb customer-invoice send-group --payload '{"budgetId":"budget_1","expectedRevision":2,"instalmentIds":["row_1","row_2"]}'` to send approved invoices together in one email. Select one row for individual sending. Alternatively, use `--all-approved --payload '{"budgetId":"budget_1","expectedRevision":2}'` to select all approved, unsent invoices in that budget. Do not combine `--all-approved` with `instalmentIds`.
+1. Run `bb customer-invoice eligible-budget list <projectId>` to review each estimate total, already invoiced percentage, remaining percentage, and available amount.
+2. Run `bb customer-invoice readiness check <budgetId>` for live QuickBooks validation and the full remaining-balance preview.
+3. For a partial invoice, run `bb customer-invoice amount preview <budgetId> <percentage-of-estimate>` to review the amount before GST, GST, and total. The percentage is based on the original estimate and cannot exceed the remaining percentage.
+4. Run `bb customer-invoice create --payload '<json>'` with a recommended UUID request ID, invoice date, billing address, customer memo, and exactly one split containing its estimate percentage and due date.
+5. Non-admin creation automatically requests admin approval after QBO creation. Admin creation is auto-approved. Pending approval never sends invoices.
+6. Use the normal invoice detail/email or portal-upload actions after approval. Creation and approval do not automatically email the customer.
 
-Preview/save use this shape, populated from the current `splits` result and the signed terms (IDs, addresses, and dates below are examples only):
+Example for a 50% invoice:
 
 ```json
 {
   "budgetId": "budget_1",
-  "expectedRevision": 1,
-  "scope": "BASE",
-  "changeReason": "Confirmed invoice split and due dates from signed estimate",
-  "definition": {
-    "rows": [
-      { "key": "deposit", "label": "Deposit", "amount": { "type": "PERCENTAGE", "value": 70 }, "due": { "type": "CONFIRMATION" }, "issue": { "type": "ACCEPTANCE" } },
-      { "key": "balance", "label": "Balance", "amount": { "type": "PERCENTAGE", "value": 30 }, "due": { "type": "FIXED_DATE", "date": "2026-12-01" }, "issue": { "type": "ACCEPTANCE" } }
-    ],
-    "reminderLeadDays": 7,
-    "billingRestriction": ""
+  "requestId": "6ec0d99f-24a4-4f3e-9a74-d3f4fd971a25",
+  "invoiceDate": "2026-11-21",
+  "details": {
+    "billingAddress": "Customer name\n1 Example Street\nSingapore 123456",
+    "customerMemo": "Thank you for your business."
   },
-  "billing": {
-    "legalEntityName": "Customer legal entity",
-    "purchaseOrder": "PO-reference",
-    "billingAddress": "Customer billing address",
-    "to": "billing@example.invalid",
-    "cc": [],
-    "replyTo": "owner@example.invalid",
-    "deliveryMethod": "EMAIL",
-    "uploadUrl": null
-  }
+  "isCustomPercentage": true,
+  "splits": [
+    { "label": "Partial invoice", "percentage": 50, "dueDate": "2026-12-01" }
+  ]
 }
 ```
 
-Use the exact current revision (or `null` only when no schedule exists). Fixed amounts use **pre-GST cents**; percentages use percentage points. Event-relative due rules are `EVENT_START` or `EVENT_END` with `offsetDays`. Preview and resolve missing dates, past-due review or unresolved amounts rather than inventing replacements.
+Use the exact percentage returned by the preview flow. Non-interactive creation requires `--allow-state-change --allow-financial-write --allow-external-write --allow-email` (internal approval notification, not customer delivery). Reuse the same `requestId` when retrying an uncertain request, and review the existing batch before retrying.
 
-Non-interactive save requires `--allow-state-change`; creation requires `--allow-state-change --allow-financial-write --allow-external-write --allow-email` (approval-request email, not customer invoice delivery); grouped sending requires `--allow-state-change --allow-email --allow-external-write`. These flags acknowledge effects, not role permissions or user authorisation. Both ordinary users and admins still need server-granted project access. Pending/rejected invoices cannot be sent; a mixed selection is rejected rather than silently dropping invoices. Sending uses each issued invoice's original billing revision, not later edits. Invoices with different original billing instructions must be sent in separate groups. Do not blindly retry uncertain QBO or email outcomes.
+To link an invoice that already exists in QuickBooks, first run `bb customer-invoice existing list <budgetId>`. Choose a returned `qboInvoiceId`, review it with `bb customer-invoice preview-qbo <budgetId> <qboInvoiceId>`, then use the preview token with `bb customer-invoice import-qbo <budgetId> <qboInvoiceId> --token <previewToken>`.
 
-These commands require the matching API deployment and a new CLI release; changing this repository does not publish the CLI or deploy production.
+The former `splits`, `preview-splits`, `save-splits`, `create-splits`, and `send-group` schedule commands are retired. Update the CLI alongside the API. Existing schedule data and invoices are retained, and previously queued emails retain their delivery/reconciliation support; no new schedules or reminders are created.
 
 ### Quotation amounts and line allocations
 
@@ -467,7 +456,7 @@ Bill, claim, and quotation mutations accept only suppliers whose approval status
 | **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`, 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 **before-GST** `extractedAmount` (full invoice subtotal) and `amount` (portion billed), with `amount <= extractedAmount`; line and quotation allocation amounts also exclude GST; 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`, `gstAmount`, and `lineAmounts` entries `{ budgetItemId, amount }` for multiple selected items), `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` |
+| **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `preview-customer-invoice-amount`, `list-available-qbo-customer-invoices`, `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`) |

package/command-manifest.json

@@ -3571,112 +3571,12 @@
 		"legacyTarget": "list-eligible-customer-invoice-budgets"
 	},
 	{
-		"path": ["customer-invoice", "list"],
-		"legacyAliases": ["list-customer-invoices", "list_customer_invoices"],
-		"summary": "List customer invoices.",
-		"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": "list-customer-invoices"
-	},
-	{
-		"path": ["customer-invoice", "get"],
-		"legacyAliases": ["get-customer-invoice", "get_customer_invoice"],
-		"summary": "Get customer invoice.",
-		"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": "get-customer-invoice"
-	},
-	{
-		"path": ["customer-invoice", "email-context", "get"],
+		"path": ["customer-invoice", "amount", "preview"],
 		"legacyAliases": [
-			"get-customer-invoice-email-context",
-			"get_customer_invoice_email_context"
+			"preview-customer-invoice-amount",
+			"preview_customer_invoice_amount"
 		],
-		"summary": "Get customer invoice email context.",
+		"summary": "Preview amount before GST, GST, and total for a percentage of an accepted estimate. Arguments: <budgetId> <percentage-of-estimate>.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3721,15 +3621,15 @@
 		],
 		"argumentMode": "legacy-passthrough",
 		"effects": [],
-		"legacyTarget": "get-customer-invoice-email-context"
+		"legacyTarget": "preview-customer-invoice-amount"
 	},
 	{
-		"path": ["customer-invoice", "preview-qbo"],
+		"path": ["customer-invoice", "existing", "list"],
 		"legacyAliases": [
-			"preview-qbo-customer-invoice",
-			"preview_qbo_customer_invoice"
+			"list-available-qbo-customer-invoices",
+			"list_available_qbo_customer_invoices"
 		],
-		"summary": "Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.",
+		"summary": "List unlinked QuickBooks invoices available for an accepted or closed estimate. Argument: <budgetId>.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3774,68 +3674,12 @@
 		],
 		"argumentMode": "legacy-passthrough",
 		"effects": [],
-		"legacyTarget": "preview-qbo-customer-invoice"
+		"legacyTarget": "list-available-qbo-customer-invoices"
 	},
 	{
-		"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", "splits"],
-		"legacyAliases": [
-			"get-customer-invoice-splits",
-			"get_customer_invoice_splits"
-		],
-		"summary": "Review acceptance invoice splits, due dates, approval states and saved billing details. Arguments: <budgetId>.",
+		"path": ["customer-invoice", "list"],
+		"legacyAliases": ["list-customer-invoices", "list_customer_invoices"],
+		"summary": "List customer invoices.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3880,15 +3724,12 @@
 		],
 		"argumentMode": "legacy-passthrough",
 		"effects": [],
-		"legacyTarget": "get-customer-invoice-splits"
+		"legacyTarget": "list-customer-invoices"
 	},
 	{
-		"path": ["customer-invoice", "preview-splits"],
-		"legacyAliases": [
-			"preview-customer-invoice-splits",
-			"preview_customer_invoice_splits"
-		],
-		"summary": "Preview splits, GST totals and due-date changes without writes. Requires --payload with the schedule save input.",
+		"path": ["customer-invoice", "get"],
+		"legacyAliases": ["get-customer-invoice", "get_customer_invoice"],
+		"summary": "Get customer invoice.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3933,15 +3774,15 @@
 		],
 		"argumentMode": "legacy-passthrough",
 		"effects": [],
-		"legacyTarget": "preview-customer-invoice-splits"
+		"legacyTarget": "get-customer-invoice"
 	},
 	{
-		"path": ["customer-invoice", "save-splits"],
+		"path": ["customer-invoice", "email-context", "get"],
 		"legacyAliases": [
-			"save-customer-invoice-splits",
-			"save_customer_invoice_splits"
+			"get-customer-invoice-email-context",
+			"get_customer_invoice_email_context"
 		],
-		"summary": "Save split amounts and separate due dates after estimate acceptance. Requires --payload; does not create invoices or request approval.",
+		"summary": "Get customer invoice email context.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3985,16 +3826,16 @@
 			}
 		],
 		"argumentMode": "legacy-passthrough",
-		"effects": ["state-change"],
-		"legacyTarget": "save-customer-invoice-splits"
+		"effects": [],
+		"legacyTarget": "get-customer-invoice-email-context"
 	},
 	{
-		"path": ["customer-invoice", "create-splits"],
+		"path": ["customer-invoice", "preview-qbo"],
 		"legacyAliases": [
-			"create-customer-invoice-splits",
-			"create_customer_invoice_splits"
+			"preview-qbo-customer-invoice",
+			"preview_qbo_customer_invoice"
 		],
-		"summary": "Create selected split invoices in QBO, then request admin approval for non-admin creators or auto-approve admin creators. Requires --payload with budgetId, expectedRevision, instalmentIds. Never sends customer invoices.",
+		"summary": "Preview an available QuickBooks invoice selected for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -4038,16 +3879,16 @@
 			}
 		],
 		"argumentMode": "legacy-passthrough",
-		"effects": ["state-change", "financial-write", "external-write", "email"],
-		"legacyTarget": "create-customer-invoice-splits"
+		"effects": [],
+		"legacyTarget": "preview-qbo-customer-invoice"
 	},
 	{
-		"path": ["customer-invoice", "send-group"],
+		"path": ["customer-invoice", "import-qbo"],
 		"legacyAliases": [
-			"send-customer-invoice-group",
-			"send_customer_invoice_group"
+			"import-qbo-customer-invoice",
+			"import_qbo_customer_invoice"
 		],
-		"summary": "Send selected approved invoices together in one email. Requires --payload with budgetId, expectedRevision, instalmentIds, or --all-approved without instalmentIds. Pass one instalment for individual sending.",
+		"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",
@@ -4088,20 +3929,16 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
-			},
-			{
-				"name": "--all-approved",
-				"description": "Select all approved unsent invoices; payload must contain only budgetId and expectedRevision."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
-		"effects": ["state-change", "email", "external-write"],
-		"legacyTarget": "send-customer-invoice-group"
+		"effects": ["state-change", "financial-write"],
+		"legacyTarget": "import-qbo-customer-invoice"
 	},
 	{
 		"path": ["customer-invoice", "create"],
 		"legacyAliases": ["create-customer-invoice", "create_customer_invoice"],
-		"summary": "Create Customer Invoice.",
+		"summary": "Create one invoice from an eligible budget using --payload JSON with invoice date, due date, billing address, customer memo, and a percentage of the original estimate that does not exceed its remaining coverage.",
 		"globalOptions": [
 			{
 				"name": "--help",

package/command-reference.md

@@ -577,6 +577,22 @@ Legacy aliases: `list-eligible-customer-invoice-budgets`, `list_eligible_custome
 
 Effects: none.
 
+## `bb customer-invoice amount preview`
+
+Preview amount before GST, GST, and total for a percentage of an accepted estimate. Arguments: <budgetId> <percentage-of-estimate>.
+
+Legacy aliases: `preview-customer-invoice-amount`, `preview_customer_invoice_amount`.
+
+Effects: none.
+
+## `bb customer-invoice existing list`
+
+List unlinked QuickBooks invoices available for an accepted or closed estimate. Argument: <budgetId>.
+
+Legacy aliases: `list-available-qbo-customer-invoices`, `list_available_qbo_customer_invoices`.
+
+Effects: none.
+
 ## `bb customer-invoice list`
 
 List customer invoices.
@@ -603,7 +619,7 @@ Effects: none.
 
 ## `bb customer-invoice preview-qbo`
 
-Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.
+Preview an available QuickBooks invoice selected for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.
 
 Legacy aliases: `preview-qbo-customer-invoice`, `preview_qbo_customer_invoice`.
 
@@ -617,49 +633,9 @@ Legacy aliases: `import-qbo-customer-invoice`, `import_qbo_customer_invoice`.
 
 Effects: state-change, financial-write.
 
-## `bb customer-invoice splits`
-
-Review acceptance invoice splits, due dates, approval states and saved billing details. Arguments: <budgetId>.
-
-Legacy aliases: `get-customer-invoice-splits`, `get_customer_invoice_splits`.
-
-Effects: none.
-
-## `bb customer-invoice preview-splits`
-
-Preview splits, GST totals and due-date changes without writes. Requires --payload with the schedule save input.
-
-Legacy aliases: `preview-customer-invoice-splits`, `preview_customer_invoice_splits`.
-
-Effects: none.
-
-## `bb customer-invoice save-splits`
-
-Save split amounts and separate due dates after estimate acceptance. Requires --payload; does not create invoices or request approval.
-
-Legacy aliases: `save-customer-invoice-splits`, `save_customer_invoice_splits`.
-
-Effects: state-change.
-
-## `bb customer-invoice create-splits`
-
-Create selected split invoices in QBO, then request admin approval for non-admin creators or auto-approve admin creators. Requires --payload with budgetId, expectedRevision, instalmentIds. Never sends customer invoices.
-
-Legacy aliases: `create-customer-invoice-splits`, `create_customer_invoice_splits`.
-
-Effects: state-change, financial-write, external-write, email.
-
-## `bb customer-invoice send-group`
-
-Send selected approved invoices together in one email. Requires --payload with budgetId, expectedRevision, instalmentIds, or --all-approved without instalmentIds. Pass one instalment for individual sending.
-
-Legacy aliases: `send-customer-invoice-group`, `send_customer_invoice_group`.
-
-Effects: state-change, email, external-write.
-
 ## `bb customer-invoice create`
 
-Create Customer Invoice.
+Create one invoice from an eligible budget using --payload JSON with invoice date, due date, billing address, customer memo, and a percentage of the original estimate that does not exceed its remaining coverage.
 
 Legacy aliases: `create-customer-invoice`, `create_customer_invoice`.