@go-labs-sg/bb 2.16.0 → 2.18.0

package/README.md

@@ -183,17 +183,23 @@ external provider.
 
 ### Mutation safety
 
+While an estimate email is `QUEUED`, `PROCESSING`, or awaiting provider
+reconciliation, the API makes that Budget read-only. Budget-changing CLI
+commands return a conflict until delivery becomes `SENT` or `FAILED`.
+
 Every canonical command is classified by effect: `state-change`, `email`, `external-write`, `delete`, and/or `financial-write`. Interactive runs require one exact `CONFIRM`. Non-interactive runs require the corresponding flags (`--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and `--allow-financial-write`); commands with multiple effects require every matching flag. Agents must still get user confirmation in chat first—the runtime gate is not user authorization.
 
 **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.
 
 **Locked estimate budget changes:** Legacy flat commands retain their additional interactive `yes` prompt when the current budget is locked. Canonical v2 commands use the single effect-aware confirmation gate; non-interactive execution requires `--allow-state-change` plus any other effects declared for that command.
 
-**Mutations with `--payload`:** Commands such as `bb budget create`, `bb bill create`, and `bb supplier update` take a single JSON object (`--payload '<json>'`) matching the corresponding tRPC procedure input. Use ISO strings for date/datetime fields; the CLI coerces them where needed. The API still validates the full shape. Plain `description` fields for item create/update are converted to `descriptionRichText`; pass `descriptionRichText` directly when formatted Tiptap JSON is required. For **`bb project update`**, the project window is `dateRange.from` and `dateRange.to` (optional end); there are no separate event-date fields on the project payload. **`bb budget create` / `bb budget update`** do not accept `asanaTaskId`; configure the deal card on the project (`bb project update` / project settings).
+**Mutations with `--payload`:** Commands such as `bb budget create`, `bb bill create`, and `bb supplier update` take a single JSON object (`--payload '<json>'`) matching the corresponding tRPC procedure input. Use ISO strings for date/datetime fields; the CLI coerces them where needed. The API still validates the full shape. Plain `description` fields for item create/update are converted to `descriptionRichText`; pass `descriptionRichText` directly when formatted Tiptap JSON is required. For **`bb project update`**, the project window is `dateRange.from` and `dateRange.to` (optional end); there are no separate event-date fields on the project payload. **`bb budget create` / `bb budget update`** do not accept `asanaTaskId`; configure the deal card on the project (`bb project update` / project settings). When `bb budget create` clones a `sourceBudgetId` containing unavailable catalogue lines, the API preserves those snapshots for review and rejects the clone until the caller explicitly sets `unavailableItemReviewAcknowledged: true`.
+
+**Unavailable catalogue lines:** Budget Builder-only `bb item archive --ids <csv>` may retire catalogue items referenced by open estimates. The estimate snapshots remain intact, but sending or accepting is blocked until each unavailable line is resolved with `bb budget item replace --budgetItemId <id> --replacementItemId <active-item-id>`, `bb budget item remove <id>`, or the Lead/Admin-only `bb budget item exception approve --budgetItemId <id> --reason <text>`. The approved-exception reason is audited. `bb item delete <id>` also attempts QuickBooks deactivation and therefore remains blocked while an open estimate references the item.
 
-**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 sends the raw PDF returned by QuickBooks together with the standard terms and Budget Builder budget attachments, then marks the budget `ESTIMATE_SENT`. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first, and do not retry blindly after an ambiguous delivery failure.
+**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.
 
-**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` uses the same protected email workflow as the web composer and marks a successful 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.
+**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:
 
@@ -207,11 +213,14 @@ For agent-driven invoice work, use this read-before-write sequence:
 Project Hub setup and commercial-document reconciliation are durable, asynchronous Budget Builder operations. Read status before requesting either mutation:
 
 ```bash
+bb project hub list --q <project-or-company> --status WON,COMPLETED
 bb project hub status <project-id>
 bb project hub setup <project-id>
 bb project hub sync <project-id>
 ```
 
+`list` is read-only and returns active projects with a Project Hub integration, including setup state and the stored Hub URL when available. It supports project/company search, project-status filters, pagination, and sorting.
+
 `status` reports eligibility, whether setup can be requested, the current setup status, the latest setup error, and the client Hub URL. `setup` uses the same eligibility and accepted-estimate checks as the web button and may create the operational Asana project before provisioning Drive and Project Hub. `sync` requires an existing `READY` native-layout integration and queues a complete reconciliation of accepted estimates, commercial attachments, win proofs, and eligible customer invoices into Asana and Drive.
 
 Both mutation commands write external state asynchronously and therefore require `state-change` and `external-write` confirmation. In non-interactive use, pass both `--allow-state-change` and `--allow-external-write` only after obtaining explicit user approval. A successful `queued` response means the durable operation was accepted. `status` tracks setup readiness; the sync response returns its outbox operation ID, which an Admin can inspect with the integration-operation commands when completion or failure diagnostics are required.
@@ -226,17 +235,17 @@ Project and budget query payloads keep the Asana identities explicit: `asanaTask
 
 | 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`), `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`, `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`; runs the same supplier, line-item, and quotation-coverage checks as the web flow; `alreadyPaid` never bypasses them), `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 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` |
+| **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` |
 | **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), `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` |
 | **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`) |
-| **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics` (admin), `list-items`, `create-item` (`--payload`), `update-item` (`--payload`), `archive-items` (`--ids` CSV, max 100; Budget Builder only; users can archive their own items, leads/admins any item; blocked by Draft/Pending Approval/Approved budgets), `delete-item` (admin; archives in Budget Builder and makes the item inactive in QuickBooks), `get-item`, `list-item-categories`, `create-item-category` / `update-item-category` / `delete-item-categories` (admin; `--ids` CSV for delete) |
+| **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics` (admin), `list-items` (`--includeQuickBooksDeactivationPending true` discovers interrupted QuickBooks deactivations for Admin retry), `create-item` (`--payload`), `update-item` (`--payload`), `archive-items` (`--ids` CSV, max 100; Budget Builder-only; open estimates retain unavailable snapshot lines for resolution), `delete-item` (admin; archives in Budget Builder and makes the item inactive in QuickBooks; blocked while an open estimate references it), `get-item`, `list-item-categories`, `create-item-category` / `update-item-category` / `delete-item-categories` (admin; `--ids` CSV for delete) |
 | **Dashboard & users** | `whoami` (current API-key owner identity and role), `list-users`, `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (`--name`; defaults to the caller; admin-only `--userId` for another user; raw key shown once), `list-api-keys` (defaults to the caller; admin-only `--userId` for another user), `revoke-api-key` (key ID; admin-only `--userId` for another user), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` (performance/dashboard commands are admin-only) |
 | **Errors (admin)** | `get-recent-errors`, `get-error-metrics` |
-| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` |
+| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` (Resend resolution requires `--confirmExternalStateReconciled true` plus `--outboundEmailResolution ACCEPTED\|NOT_ACCEPTED_RETRY`; include `--providerMessageId` when accepted) |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 
 The CLI intentionally wraps low-level upload-request/confirm procedures into file-based commands and omits browser-only helpers such as navigation counts, combobox/facet data, recent-page bookkeeping, and live UI subscriptions. Operational workflows for bills, claims, quotations, customer invoices, project reconciliation/completion, and integration recovery are available directly.

package/command-manifest.json

@@ -970,6 +970,101 @@
 		"effects": ["state-change", "delete"],
 		"legacyTarget": "remove-budget-item"
 	},
+	{
+		"path": ["budget", "item", "replace"],
+		"legacyAliases": ["replace-budget-item", "replace_budget_item"],
+		"summary": "Replace Budget Item.",
+		"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": "--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": "replace-budget-item"
+	},
+	{
+		"path": ["budget", "item", "exception", "approve"],
+		"legacyAliases": [
+			"approve-unavailable-item-exception",
+			"approve_unavailable_item_exception"
+		],
+		"summary": "Approve Unavailable Item Exception.",
+		"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": "--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"],
+		"legacyTarget": "approve-unavailable-item-exception"
+	},
 	{
 		"path": ["budget", "item", "reorder"],
 		"legacyAliases": ["reorder-budget-items", "reorder_budget_items"],
@@ -3403,7 +3498,7 @@
 			"send-customer-invoice-to-contact-person",
 			"send_customer_invoice_to_contact_person"
 		],
-		"summary": "Send Customer Invoice To Contact Person.",
+		"summary": "Send a customer invoice and update the project billing email.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -4190,6 +4285,76 @@
 		"effects": [],
 		"legacyTarget": "list-projects"
 	},
+	{
+		"path": ["project", "hub", "list"],
+		"legacyAliases": ["list-project-hubs", "list_project_hubs"],
+		"summary": "List project hubs.",
+		"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": "--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": "--q",
+				"description": "Search project and company names."
+			},
+			{
+				"name": "--status",
+				"description": "Filter by comma-separated project statuses."
+			},
+			{
+				"name": "--page",
+				"description": "Select a results page."
+			},
+			{
+				"name": "--perPage",
+				"description": "Set the results page size."
+			},
+			{
+				"name": "--sortBy",
+				"description": "Sort by startDate, name, companyName, or status."
+			},
+			{
+				"name": "--sortDir",
+				"description": "Sort in asc or desc order."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "list-project-hubs"
+	},
 	{
 		"path": ["project", "get"],
 		"legacyAliases": ["get-project", "get_project"],

package/command-reference.md

@@ -184,6 +184,22 @@ Legacy aliases: `remove-budget-item`, `remove_budget_item`.
 
 Effects: state-change, delete.
 
+## `bb budget item replace`
+
+Replace Budget Item.
+
+Legacy aliases: `replace-budget-item`, `replace_budget_item`.
+
+Effects: state-change, financial-write.
+
+## `bb budget item exception approve`
+
+Approve Unavailable Item Exception.
+
+Legacy aliases: `approve-unavailable-item-exception`, `approve_unavailable_item_exception`.
+
+Effects: state-change.
+
 ## `bb budget item reorder`
 
 Reorder Budget Items.
@@ -602,7 +618,7 @@ Effects: state-change, email, external-write, financial-write.
 
 ## `bb customer-invoice send`
 
-Send Customer Invoice To Contact Person.
+Send a customer invoice and update the project billing email.
 
 Legacy aliases: `send-customer-invoice-to-contact-person`, `send_customer_invoice_to_contact_person`.
 
@@ -736,6 +752,14 @@ Legacy aliases: `list-projects`, `list_projects`.
 
 Effects: none.
 
+## `bb project hub list`
+
+List project hubs.
+
+Legacy aliases: `list-project-hubs`, `list_project_hubs`.
+
+Effects: none.
+
 ## `bb project get`
 
 Get project.

package/dist/commands.js

@@ -1037,6 +1037,16 @@ export async function removeBudgetItem(budgetItemId) {
     });
     out(result);
 }
+export const replaceBudgetItem = async (input) => {
+    await confirmLockedBudgetChangeByBudgetItemId(input.budgetItemId, "Replace unavailable budget item");
+    const result = await api.budgetItem.replaceBudgetItem.mutate(input);
+    out(result);
+};
+export const approveUnavailableItemException = async (input) => {
+    await confirmLockedBudgetChangeByBudgetItemId(input.budgetItemId, "Approve unavailable item exception");
+    const result = await api.budgetItem.approveUnavailableItemException.mutate(input);
+    out(result);
+};
 export async function getBudgetCategories() {
     const categories = await api.budget.getBudgetCategories.query();
     out(categories);
@@ -1091,7 +1101,7 @@ export async function createEstimate(budgetId, preflight) {
     const result = await api.quickbooks.createEstimate.mutate({ budgetId });
     out(result);
 }
-export const describeEstimateEmailConfirmation = (input) => `to ${input.to}; CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; attach the QBO estimate PDF, terms and conditions, and Budget Builder attachments, then mark the estimate sent`;
+export const describeEstimateEmailConfirmation = (input) => `to ${input.to}; CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; queue durable worker delivery with the QBO estimate PDF, terms and conditions, and Budget Builder attachments; mark the estimate sent after provider acceptance`;
 export const sendEstimateToContactPersonFromPayload = async (raw) => {
     const input = parseSendEstimateToContactPersonPayload(raw);
     await assertSensitiveWorkflowConfirmed({
@@ -1425,7 +1435,7 @@ export const syncCustomerInvoice = async (invoiceId) => {
     });
     out(result);
 };
-export const describeCustomerInvoiceEmailConfirmation = (input) => `emails the QBO invoice PDF to ${input.to}; requested CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; server-required admin, creator, business-development, and inside-sales CC recipients are added; success marks the invoice SENT; do not retry blindly after an ambiguous delivery failure`;
+export const describeCustomerInvoiceEmailConfirmation = (input) => `emails the QBO invoice PDF to ${input.to} and saves that address as the project's billing email; requested CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; server-required admin, creator, business-development, and inside-sales CC recipients are added; success marks the invoice SENT; do not retry blindly after an ambiguous delivery failure`;
 export const sendCustomerInvoiceToContactPersonFromPayload = async (raw) => {
     const input = parseSendCustomerInvoiceToContactPersonPayload(raw);
     await assertSensitiveWorkflowConfirmed({
@@ -1907,6 +1917,14 @@ export async function listProjects(opts) {
     });
     out(result);
 }
+export const listProjectHubs = async (opts) => {
+    const result = await api.project.getAllProjectHubs.query({
+        ...opts,
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+    });
+    out(result);
+};
 export async function getProject(id) {
     const [project, budgetsOverview, billsOverview] = await Promise.all([
         api.project.getProjectDetailsById.query({ id }),
@@ -2015,17 +2033,25 @@ export const listIntegrationOperations = async (input) => {
     const result = await api.integration.listOperations.query(input);
     out(result);
 };
-export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled) => {
+export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled, outboundEmailResolution, providerMessageId) => {
     await assertSensitiveWorkflowConfirmed({
-        action: "Retry integration operation",
+        action: outboundEmailResolution === "ACCEPTED"
+            ? "Reconcile integration operation as completed"
+            : "Retry integration operation",
         entity: `operation ${operationId}`,
-        details: confirmExternalStateReconciled
-            ? "after confirming the external state has been reconciled"
-            : undefined,
+        details: outboundEmailResolution === "ACCEPTED"
+            ? `mark provider-accepted email sent with message ID ${providerMessageId ?? "<missing>"}`
+            : outboundEmailResolution === "NOT_ACCEPTED_RETRY"
+                ? "rotate the Resend idempotency key and retry provider delivery"
+                : confirmExternalStateReconciled
+                    ? "after confirming the external state has been reconciled"
+                    : undefined,
     });
     const result = await api.integration.retryOperation.mutate({
         operationId,
         confirmExternalStateReconciled,
+        outboundEmailResolution,
+        providerMessageId,
     });
     out(result);
 };
@@ -2081,6 +2107,7 @@ export async function listContacts(companyId) {
 // --- Items ---
 export async function listItems(opts) {
     const result = await api.item.getItems.query({
+        includeQuickBooksDeactivationPending: opts.includeQuickBooksDeactivationPending,
         page: opts.page ?? 1,
         perPage: opts.perPage ?? 20,
         name: opts.name,

package/dist/index.js

@@ -5,9 +5,9 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BUDGET_BUILDER_API_BASE_URL, configureBudgetBuilderApiBaseUrl, DEFAULT_BUDGET_BUILDER_API_BASE_URL, requireApiKey, } from "./api-client.js";
 import { consumeCliQuietFlags, logCliAction, sanitizeFlagsForTrace, setCliQuiet, shouldLogCliActions, } from "./cli-trace.js";
-import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, archiveItemsByIds, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createInboundSource, createItemCategory, createItemFromPayload, createPlaceholderBillForBudgetItem, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteBudgetCommission, deleteBudgetDiscount, deleteCompanyById, deleteCustomerInvoice, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteQuotationById, deleteSuppliersByIds, discardCreatingCustomerInvoice, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getInboundSource, getInboundSubmission, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getProjectHubStatus, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listInboundSources, listInboundSubmissions, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, saveInboundAutomationConfig, saveInboundMappingVersion, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, setupProjectHub, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, syncProjectHubCommercialDocuments, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateInboundProcessing, updateInboundSource, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, whoAmI, } from "./commands.js";
+import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, approveUnavailableItemException, archiveItemsByIds, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createInboundSource, createItemCategory, createItemFromPayload, createPlaceholderBillForBudgetItem, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteBudgetCommission, deleteBudgetDiscount, deleteCompanyById, deleteCustomerInvoice, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteQuotationById, deleteSuppliersByIds, discardCreatingCustomerInvoice, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getInboundSource, getInboundSubmission, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getProjectHubStatus, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listInboundSources, listInboundSubmissions, listIntegrationOperations, listItemCategories, listItems, listProjectHubs, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, replaceBudgetItem, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, saveInboundAutomationConfig, saveInboundMappingVersion, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, setupProjectHub, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, syncProjectHubCommercialDocuments, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateInboundProcessing, updateInboundSource, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, whoAmI, } from "./commands.js";
 import { getFlag, parseArgs } from "./parse-args.js";
-import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedIntegrationOperationStatuses, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
+import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedIntegrationOperationStatuses, parseCommaSeparatedProjectStatuses, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalProjectHubSortBy, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
 import { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
 import { createCompletionScript, createHumanHelp, resolveCommand, } from "./registry/index.js";
 import { CliRuntimeError, clearActiveCliSession, confirmCurrentCommand, createProcessRuntime, emitCommandError, emitCommandResult, setActiveCliSession, } from "./runtime/index.js";
@@ -155,6 +155,9 @@ AI agents must inspect the entity first, summarize the exact entity, target
 state, and side effects, then wait for explicit user confirmation before running
 the sensitive command.
 
+Budget mutations return a conflict while an estimate email is queued,
+processing, or awaiting provider reconciliation.
+
 Budgets
   list-budgets              [--projectId] [--name] [--status CSV] [--createdBy] [--dateFrom] [--dateTo] [--sortBy] [--sortDir] [--page] [--perPage] [--summary]
   get-budget <id>            Budget + line items
@@ -170,7 +173,7 @@ Budgets
     ESTIMATE_REJECTED requires --projectStatusOnCommercialRejection when rejecting the only accepted/closed budget on a commercial project.
     status: ${budgetStatusesForHelp.join(", ")}
 	mark-budget-won <budgetId> <filePath> [--projectManagerId <id>] [--invoiceSettings <json>]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; first acceptance requires invoice settings when customer invoicing is enabled
-  create-budget              --payload '<json>'  (budget.createBudget; Asana deal card is on the project)
+  create-budget              --payload '<json>'  (budget.createBudget; when sourceBudgetId contains unavailable items, set unavailableItemReviewAcknowledged=true after explicit review)
   update-budget              --payload '<json>'  (budget.updateBudget; must include id)
   delete-budget <budgetId>
   create-budget-approval <budgetId>   (also sends approval request emails)
@@ -179,6 +182,8 @@ Budgets
   add-budget-items           --budgetId --items '[{"itemId":"…","quantity":1,"markup":30},…]'
   update-budget-item         --id <budgetItemId> [--description plain-text] [--note plain-text] [--quantity] [--markup] [--cost] [--unitPrice] [--isFreeOfCharge true|false] [--gstInclusive true|false] [--gstOutOfScope true|false]
   remove-budget-item <budgetItemId>
+  replace-budget-item        --budgetItemId <id> --replacementItemId <activeCatalogueItemId>
+  approve-unavailable-item-exception --budgetItemId <id> --reason <text>   Lead/Admin only; reason must be 5-1000 characters.
   reorder-budget-items       <budgetId> --itemIds <csv>
   update-budget-item-supplier --budgetItemId --supplierId
   create-budget-category     --name <text>
@@ -197,10 +202,10 @@ 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 for every selected line item, including already-paid bills.
+  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-bill-approval <billId>       (also sends approval request emails)
   create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim)
-  validate-bill-selection    --payload '<json>'  Check projectId, supplierId, and budgetItemIds before creation; alreadyPaid never bypasses quotation checks.
+  validate-bill-selection    --payload '<json>'  Check project and supplier validity separately, then verify approved quotation links for each budgetItemId; alreadyPaid never bypasses quotation checks.
   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)
@@ -268,6 +273,8 @@ Companies & projects
   delete-company <id>
   list-projects              [--companyId] [--name] [--status] [--active true|false] [--page] [--perPage]
     Omit --active to include both active and inactive projects.
+  list-project-hubs          [--q] [--status CSV] [--page] [--perPage] [--sortBy startDate|name|companyName|status] [--sortDir asc|desc]
+    List active projects that have a Project Hub integration.
   get-project <id>
     Budget overview totalRevenue includes Estimate Accepted and Estimate Closed budgets only.
   create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate <ISO> [--projectManagerId <userId>] [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
@@ -300,11 +307,11 @@ Suppliers & items
   create-supplier-tag        --name  (supplier.createSupplierTag)
   create-item                --payload '<json>'  (item.createItem)
   update-item                --payload '<json>'  (item.updateItem; must include id)
-  archive-items              --ids <csv>  (item.archiveItems; Budget Builder only; max 100; users can archive their own items, leads/admins any item; blocked by Draft/Pending Approval/Approved budgets)
-  delete-item <id>           (item.deleteItem; admin; archives in Budget Builder and makes the item inactive in QuickBooks)
+  archive-items              --ids <csv>  (item.archiveItems; Budget Builder only; max 100; users can archive their own items, leads/admins any item; open estimates retain snapshot lines and require resolution before send/acceptance)
+  delete-item <id>           (item.deleteItem; admin; archives in Budget Builder and makes the item inactive in QuickBooks; blocked while used by an open estimate)
   get-supplier-details <supplierId>
   get-supplier-analytics     [--name] [--page] [--perPage] [--timeFrame ALL|LAST_YEAR|…]  (admin)
-  list-items                 [--name] [--page] [--perPage]
+  list-items                 [--name] [--page] [--perPage] [--includeQuickBooksDeactivationPending true]
   get-item <id>
   list-item-categories       [--page] [--perPage]
   create-item-category       --name  (admin)
@@ -331,7 +338,7 @@ Errors
 
 Automation (admin)
   list-integration-operations [--search] [--destination <provider,...>] [--status <PENDING|PROCESSING|FAILED|COMPLETED,...>] [--page] [--perPage]
-  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false]
+  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false] [--outboundEmailResolution ACCEPTED|NOT_ACCEPTED_RETRY] [--providerMessageId <id>]
 
 Historical / benchmarks
   get-approved-budgets       [--projectId] [--limit] [--minRevenue] [--maxRevenue]
@@ -840,6 +847,30 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 await removeBudgetItem(id);
                 break;
             }
+            case "replace-budget-item": {
+                const budgetItemId = getFlag(flags, "budgetItemId");
+                const replacementItemId = getFlag(flags, "replacementItemId");
+                if (!budgetItemId || !replacementItemId) {
+                    throw new Error("replace-budget-item requires --budgetItemId and --replacementItemId");
+                }
+                await replaceBudgetItem({
+                    budgetItemId: String(budgetItemId),
+                    replacementItemId: String(replacementItemId),
+                });
+                break;
+            }
+            case "approve-unavailable-item-exception": {
+                const budgetItemId = getFlag(flags, "budgetItemId");
+                const reason = getFlag(flags, "reason");
+                if (!budgetItemId || !reason) {
+                    throw new Error("approve-unavailable-item-exception requires --budgetItemId and --reason");
+                }
+                await approveUnavailableItemException({
+                    budgetItemId: String(budgetItemId),
+                    reason: String(reason),
+                });
+                break;
+            }
             case "reorder-budget-items": {
                 const budgetId = positional[0];
                 const itemIdsRaw = getFlag(flags, "itemIds");
@@ -1569,6 +1600,17 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 });
                 break;
             }
+            case "list-project-hubs": {
+                await listProjectHubs({
+                    q: getFlag(flags, "q"),
+                    statuses: parseCommaSeparatedProjectStatuses(getFlag(flags, "status")),
+                    page: parsePositiveIntFlag(getFlag(flags, "page"), "--page"),
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage"),
+                    sortBy: parseOptionalProjectHubSortBy(getFlag(flags, "sortBy")),
+                    sortDir: parseOptionalBillListSortDir(getFlag(flags, "sortDir")),
+                });
+                break;
+            }
             case "get-project": {
                 const id = positional[0];
                 if (!id)
@@ -1824,6 +1866,9 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
             }
             case "list-items": {
                 await listItems({
+                    includeQuickBooksDeactivationPending: flags.includeQuickBooksDeactivationPending === true
+                        ? true
+                        : parseOptionalBoolFlag(flags, "includeQuickBooksDeactivationPending"),
                     name: getFlag(flags, "name"),
                     page: parsePositiveIntFlag(getFlag(flags, "page"), "--page"),
                     perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage"),
@@ -2008,8 +2053,14 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 if (!operationId) {
                     throw new Error("retry-integration-operation requires <operationId>");
                 }
+                const outboundEmailResolution = getFlag(flags, "outboundEmailResolution");
+                if (outboundEmailResolution &&
+                    outboundEmailResolution !== "ACCEPTED" &&
+                    outboundEmailResolution !== "NOT_ACCEPTED_RETRY") {
+                    throw new Error("--outboundEmailResolution must be ACCEPTED or NOT_ACCEPTED_RETRY");
+                }
                 await retryIntegrationOperation(operationId, parseOptionalBoolFlag(flags, "confirmExternalStateReconciled") ??
-                    false);
+                    false, outboundEmailResolution, getFlag(flags, "providerMessageId"));
                 break;
             }
             case "list-inbound-sources": {

package/dist/parse-cli-enums.js

@@ -78,6 +78,36 @@ export function parseOptionalExtendedProjectStatus(raw) {
     }
     return raw;
 }
+export function parseCommaSeparatedProjectStatuses(raw) {
+    if (raw === undefined)
+        return undefined;
+    const statuses = raw
+        .split(",")
+        .map((value) => value.trim().toUpperCase())
+        .filter(Boolean);
+    if (statuses.length === 0)
+        return undefined;
+    for (const status of statuses) {
+        if (!PROJECT_STATUS_VALUES.has(status)) {
+            throw new Error(`Invalid project status "${status}". Use one of: ${[...PROJECT_STATUS_VALUES].join(", ")}.`);
+        }
+    }
+    return statuses;
+}
+const PROJECT_HUB_SORT_FIELDS = new Set([
+    "startDate",
+    "name",
+    "companyName",
+    "status",
+]);
+export function parseOptionalProjectHubSortBy(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (!PROJECT_HUB_SORT_FIELDS.has(raw)) {
+        throw new Error(`Invalid --sortBy "${raw}". Use one of: ${[...PROJECT_HUB_SORT_FIELDS].join(", ")}.`);
+    }
+    return raw;
+}
 export function parseOptionalDashboardRole(raw) {
     if (raw === undefined || raw === "")
         return undefined;

package/dist/parse-mutation-payload.js

@@ -76,6 +76,10 @@ export const parseSendCustomerInvoiceToContactPersonPayload = (raw) => {
 /** Matches budget.createBudget — optional pipedriveDealId; Asana deal is project.asanaTaskId. */
 export function parseCreateBudgetPayload(raw) {
     const o = requireObject(raw, "create-budget payload");
+    if (o.unavailableItemReviewAcknowledged !== undefined &&
+        typeof o.unavailableItemReviewAcknowledged !== "boolean") {
+        throw new Error("create-budget payload.unavailableItemReviewAcknowledged must be a boolean when set.");
+    }
     return {
         name: requiredString(o.name, "create-budget payload.name"),
         budget: requiredString(o.budget, "create-budget payload.budget"),
@@ -83,6 +87,9 @@ export function parseCreateBudgetPayload(raw) {
         categoryId: requiredString(o.categoryId, "create-budget payload.categoryId"),
         projectId: requiredString(o.projectId, "create-budget payload.projectId"),
         sourceBudgetId: optionalString(o.sourceBudgetId),
+        ...(o.unavailableItemReviewAcknowledged !== undefined && {
+            unavailableItemReviewAcknowledged: o.unavailableItemReviewAcknowledged,
+        }),
         pipedriveDealId: optionalString(o.pipedriveDealId),
     };
 }

package/dist/registry/index.js

@@ -51,6 +51,7 @@ const mutationPrefixes = [
     "reconcile-",
     "reject-",
     "remove-",
+    "replace-",
     "rename-",
     "reorder-",
     "restore-",
@@ -149,6 +150,7 @@ const financialWriteTargets = new Set([
     "reject-customer-invoice",
     "restore-budget-item",
     "restore-budget-version",
+    "replace-budget-item",
     "sync-customer-invoice",
     "update-bill",
     "update-bill-payment-evidence",
@@ -195,6 +197,9 @@ const summaryFor = (legacyTarget) => {
     if (legacyTarget === "download-customer-invoice-pdf") {
         return "Download a customer invoice PDF when permitted.";
     }
+    if (legacyTarget === "send-customer-invoice-to-contact-person") {
+        return "Send a customer invoice and update the project billing email.";
+    }
     if (legacyTarget.startsWith("list-")) {
         return `List ${legacyTarget.slice("list-".length).replaceAll("-", " ")}.`;
     }
@@ -209,11 +214,11 @@ const aliasesFor = (legacyTarget, aliases) => [
         alias.replaceAll("-", "_"),
     ])),
 ];
-const legacyCommand = (legacyTarget, path, aliases = []) => ({
+const legacyCommand = (legacyTarget, path, aliases = [], commandOptions = []) => ({
     path,
     legacyAliases: aliasesFor(legacyTarget, aliases),
     summary: summaryFor(legacyTarget),
-    options: globalCommandOptions,
+    options: [...globalCommandOptions, ...commandOptions],
     effects: effectsFor(legacyTarget),
     legacyTarget,
 });
@@ -239,6 +244,13 @@ const registry = [
     legacyCommand("add-budget-items", ["budget", "item", "add"]),
     legacyCommand("update-budget-item", ["budget", "item", "update"]),
     legacyCommand("remove-budget-item", ["budget", "item", "remove"]),
+    legacyCommand("replace-budget-item", ["budget", "item", "replace"]),
+    legacyCommand("approve-unavailable-item-exception", [
+        "budget",
+        "item",
+        "exception",
+        "approve",
+    ]),
     legacyCommand("reorder-budget-items", ["budget", "item", "reorder"]),
     legacyCommand("update-budget-item-supplier", [
         "budget",
@@ -367,6 +379,23 @@ const registry = [
     legacyCommand("update-company", ["company", "update"]),
     legacyCommand("delete-company", ["company", "delete"]),
     legacyCommand("list-projects", ["project", "list"]),
+    legacyCommand("list-project-hubs", ["project", "hub", "list"], [], [
+        {
+            name: "--q",
+            description: "Search project and company names.",
+        },
+        {
+            name: "--status",
+            description: "Filter by comma-separated project statuses.",
+        },
+        { name: "--page", description: "Select a results page." },
+        { name: "--perPage", description: "Set the results page size." },
+        {
+            name: "--sortBy",
+            description: "Sort by startDate, name, companyName, or status.",
+        },
+        { name: "--sortDir", description: "Sort in asc or desc order." },
+    ]),
     legacyCommand("get-project", ["project", "get"]),
     legacyCommand("get-project-hub-status", ["project", "hub", "status"]),
     legacyCommand("setup-project-hub", ["project", "hub", "setup"]),

package/package.json

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

@@ -53,7 +53,7 @@ Do not treat Inside Sales as Lead or Admin. Budget and supplier decisions still
 
 ### `LEAD`
 
-Apply the base resource rules, plus Lead-stage budget and supplier workflows. Lead-created suppliers are auto-approved, and Leads can handle budget/supplier approvals that the API assigns to them.
+Apply the base resource rules, plus Lead-stage budget and supplier workflows. Lead-created suppliers are auto-approved, Leads can handle budget/supplier approvals that the API assigns to them, and Leads may approve an audited exception for an unavailable catalogue line after reviewing the exact estimate impact and reason.
 
 Do not use Lead credentials for Admin-only dashboards, user/service-identity administration, errors, integration retries, final bill payment, or admin customer-invoice actions.
 
@@ -76,6 +76,7 @@ Admin credentials may perform global and final-control operations, including:
 - Cross-user `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` with `--userId`.
 - Global dashboard/performance, error-log, and integration-operation commands.
 - Admin-only supplier/category recovery and archive operations.
+- Approving audited unavailable-item exceptions after confirming that replacement or removal is not appropriate.
 - Final bill approval/payment and Admin customer-invoice decisions/payment.
 
 Admin is not a force flag. State transitions, evidence, consistency checks, external-operation locks, and interactive confirmation rules still apply.
@@ -86,9 +87,11 @@ This table highlights the role-sensitive command groups an agent is most likely
 
 | Commands or action | Required identity condition |
 | --- | --- |
+| `bb project hub list` | Any active authenticated role; the command is read-only and returns only active projects with a Project Hub integration. |
 | `bb auth whoami`; own `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` | Any active role; omit `--userId` to act as the current user. |
 | Cross-user API-key commands; `bb user create` | `ADMIN`. |
 | Budget/project mutations, estimates, and budget attachments | `ADMIN`, budget creator, or project assignment as Business Development, Inside Sales, or Project Manager, depending on the endpoint. |
+| `bb budget item exception approve` | `LEAD` or `ADMIN`; requires an unavailable line and a specific audited reason. |
 | `bb project hub status`, `bb project hub setup`, and `bb project hub sync` | `ADMIN`, project creator, or project assignment as Business Development, Inside Sales, or Project Manager. Setup and sync also enforce Project Hub lifecycle/readiness checks. |
 | Edit/delete a bill or quotation | Usually creator or `ADMIN`, with a supported status. |
 | `bb budget approve`, `bb budget reject`, `bb supplier approve`, and `bb supplier reject` | Current user must be the pending approver and currently have role `LEAD` or `ADMIN`. |