@go-labs-sg/bb 2.10.3 → 2.11.0

package/README.md

@@ -193,15 +193,31 @@ Every canonical command is classified by effect: `state-change`, `email`, `exter
 
 **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.
 
-**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 payment mark-paid` requires an admin, a payment date, and a local PDF/GIF/JPEG/PNG proof up to 20MB; it uploads the proof, creates a QuickBooks Payment for the live outstanding balance when necessary, attempts to attach the proof in QuickBooks, records the result in Budget Builder, and sets the invoice status to `PAID`. `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` 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.
 
 For agent-driven invoice work, use this read-before-write sequence:
 
 1. Run `bb customer-invoice get <batchId>` and, when composing email, `bb customer-invoice email-context get <batchId>`.
 2. For creation, run `bb customer-invoice eligible-budget list <projectId>` or `bb customer-invoice readiness check <budgetId>` first.
-3. State the exact invoice or batch, current status, intended mutation, QuickBooks effect, email recipients, proof file, and estimate-closing/reopening effect to the user.
+3. State the exact invoice or batch, current status, intended mutation, QuickBooks effect, email recipients, and estimate-closing/reopening effect to the user.
 4. Wait for explicit confirmation, then run the sensitive command interactively and verify its JSON result. Do not treat the runtime `CONFIRM` prompt as user authorization.
 
+### Project Hub operations
+
+Project Hub setup and commercial-document reconciliation are durable, asynchronous Budget Builder operations. Read status before requesting either mutation:
+
+```bash
+bb project hub status <project-id>
+bb project hub setup <project-id>
+bb project hub sync <project-id>
+```
+
+`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.
+
+The fleet-wide legacy-layout migration is intentionally not exposed through the normal CLI. It remains a restricted deployment script that defaults to a read-only dry run.
+
 ### Command overview
 
 The table below is a behavior index keyed by the compatibility dispatcher's legacy handler labels. It is not invocation syntax. AI agents and new automation must resolve and use the grouped v2 route from `bb help`, [`command-reference.md`](./command-reference.md), or [`command-manifest.json`](./command-manifest.json); never copy a flat label from this table into a new command.
@@ -213,9 +229,9 @@ Project and budget query payloads keep the Asana identities explicit: `asanaTask
 | **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` |
 | **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`, `mark-customer-invoice-paid` (admin; high-level proof upload + QBO Payment workflow), `download-customer-invoice-payment-proof`, `download-customer-invoice-pdf`, `sync-customer-invoice` |
+| **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`, `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), `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`) |
+| **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) |
 | **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) |
@@ -241,7 +257,7 @@ From the monorepo root (after `bun install`):
 
 ```bash
 export BB_API_KEY=...
-bun run golabs -- bb budget list
+bun run packages/budget-builder/cli/src/index.ts budget list
 ```
 
 Or from `packages/budget-builder/cli`:

package/command-manifest.json

@@ -3446,104 +3446,6 @@
 		"effects": ["state-change", "email"],
 		"legacyTarget": "send-customer-invoice-to-contact-person"
 	},
-	{
-		"path": ["customer-invoice", "payment", "mark-paid"],
-		"legacyAliases": [
-			"mark-customer-invoice-paid",
-			"mark_customer_invoice_paid"
-		],
-		"summary": "Mark Customer Invoice Paid.",
-		"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", "external-write", "financial-write"],
-		"legacyTarget": "mark-customer-invoice-paid"
-	},
-	{
-		"path": ["customer-invoice", "payment-proof", "download"],
-		"legacyAliases": [
-			"download-customer-invoice-payment-proof",
-			"download_customer_invoice_payment_proof"
-		],
-		"summary": "Download Customer Invoice Payment Proof.",
-		"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": [],
-		"legacyTarget": "download-customer-invoice-payment-proof"
-	},
 	{
 		"path": ["customer-invoice", "pdf", "download"],
 		"legacyAliases": [
@@ -4334,6 +4236,147 @@
 		"effects": [],
 		"legacyTarget": "get-project"
 	},
+	{
+		"path": ["project", "hub", "status"],
+		"legacyAliases": ["get-project-hub-status", "get_project_hub_status"],
+		"summary": "Get project hub status.",
+		"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": [],
+		"legacyTarget": "get-project-hub-status"
+	},
+	{
+		"path": ["project", "hub", "setup"],
+		"legacyAliases": ["setup-project-hub", "setup_project_hub"],
+		"summary": "Setup Project Hub.",
+		"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", "external-write"],
+		"legacyTarget": "setup-project-hub"
+	},
+	{
+		"path": ["project", "hub", "sync"],
+		"legacyAliases": [
+			"sync-project-hub-commercial-documents",
+			"sync_project_hub_commercial_documents"
+		],
+		"summary": "Sync Project Hub Commercial Documents.",
+		"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", "external-write"],
+		"legacyTarget": "sync-project-hub-commercial-documents"
+	},
 	{
 		"path": ["project", "create"],
 		"legacyAliases": ["create-project", "create_project"],

package/command-reference.md

@@ -608,22 +608,6 @@ Legacy aliases: `send-customer-invoice-to-contact-person`, `send_customer_invoic
 
 Effects: state-change, email.
 
-## `bb customer-invoice payment mark-paid`
-
-Mark Customer Invoice Paid.
-
-Legacy aliases: `mark-customer-invoice-paid`, `mark_customer_invoice_paid`.
-
-Effects: state-change, external-write, financial-write.
-
-## `bb customer-invoice payment-proof download`
-
-Download Customer Invoice Payment Proof.
-
-Legacy aliases: `download-customer-invoice-payment-proof`, `download_customer_invoice_payment_proof`.
-
-Effects: none.
-
 ## `bb customer-invoice pdf download`
 
 Download Customer Invoice Pdf.
@@ -760,6 +744,30 @@ Legacy aliases: `get-project`, `get_project`.
 
 Effects: none.
 
+## `bb project hub status`
+
+Get project hub status.
+
+Legacy aliases: `get-project-hub-status`, `get_project_hub_status`.
+
+Effects: none.
+
+## `bb project hub setup`
+
+Setup Project Hub.
+
+Legacy aliases: `setup-project-hub`, `setup_project_hub`.
+
+Effects: state-change, external-write.
+
+## `bb project hub sync`
+
+Sync Project Hub Commercial Documents.
+
+Legacy aliases: `sync-project-hub-commercial-documents`, `sync_project_hub_commercial_documents`.
+
+Effects: state-change, external-write.
+
 ## `bb project create`
 
 Create Project.

package/dist/commands.js

@@ -264,18 +264,7 @@ const billAttachmentContentTypeForFileName = (fileName) => {
     return resolvedContentType;
 };
 const PAYMENT_PROOF_MAX_SIZE = 20 * 1024 * 1024;
-const CUSTOMER_INVOICE_PAYMENT_PROOF_MAX_SIZE = 20 * 1024 * 1024;
 const QUOTATION_ATTACHMENT_MAX_SIZE = 20 * 1024 * 1024;
-const customerInvoicePaymentProofContentTypeForFileName = (fileName) => {
-    const resolvedContentType = contentTypeHeaderForFileName(fileName);
-    if (resolvedContentType === "application/pdf" ||
-        resolvedContentType === "image/gif" ||
-        resolvedContentType === "image/jpeg" ||
-        resolvedContentType === "image/png") {
-        return resolvedContentType;
-    }
-    throw new Error(`Unsupported customer invoice payment-proof type: ${fileName}. Use PDF, GIF, JPEG, or PNG.`);
-};
 const quotationAttachmentContentTypeForFileName = (fileName) => {
     const resolvedContentType = contentTypeHeaderForFileName(fileName);
     if (resolvedContentType === "application/pdf" ||
@@ -1447,86 +1436,6 @@ export const sendCustomerInvoiceToContactPersonFromPayload = async (raw) => {
     const result = await api.customerInvoice.sendInvoiceToContactPerson.mutate(input);
     out(result);
 };
-export const describeCustomerInvoicePaymentConfirmation = ({ invoiceId, paymentDate, paymentReference, proofFileName, proofSize, }) => `for invoice ${invoiceId}, records payment date ${paymentDate}${paymentReference
-    ? " with a payment reference"
-    : " without a payment reference"}; uploads ${proofFileName} (${proofSize} bytes); creates a QuickBooks Payment for the live outstanding balance when non-zero, attaches the proof to QBO when possible, and records the payment in Budget Builder`;
-const assertPaymentDate = (paymentDate) => {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(paymentDate)) {
-        throw new Error("--paymentDate must use YYYY-MM-DD.");
-    }
-    const parsed = new Date(`${paymentDate}T00:00:00.000Z`);
-    if (Number.isNaN(parsed.getTime()) ||
-        parsed.toISOString().slice(0, 10) !== paymentDate) {
-        throw new Error("--paymentDate must be a valid calendar date.");
-    }
-    return paymentDate;
-};
-export const markCustomerInvoicePaidFromPath = async ({ invoiceId, paymentDate, paymentProofPath, paymentReference, }) => {
-    const normalizedPaymentDate = assertPaymentDate(paymentDate);
-    const proofContents = await readFile(paymentProofPath);
-    const proofFileName = basename(paymentProofPath);
-    if (proofContents.byteLength === 0) {
-        throw new Error("Customer invoice payment proof must not be empty.");
-    }
-    if (proofContents.byteLength > CUSTOMER_INVOICE_PAYMENT_PROOF_MAX_SIZE) {
-        throw new Error("Customer invoice payment proof must be 20MB or smaller.");
-    }
-    const proofContentType = customerInvoicePaymentProofContentTypeForFileName(proofFileName);
-    await assertSensitiveWorkflowConfirmed({
-        action: "Mark customer invoice paid",
-        entity: `invoice ${invoiceId}`,
-        details: describeCustomerInvoicePaymentConfirmation({
-            invoiceId,
-            paymentDate: normalizedPaymentDate,
-            paymentReference,
-            proofFileName,
-            proofSize: proofContents.byteLength,
-        }),
-    });
-    const proofUpload = await api.customerInvoice.requestPaymentProofUpload.mutate({
-        invoiceId,
-        fileName: proofFileName,
-        size: proofContents.byteLength,
-        contentType: proofContentType,
-    });
-    const uploadResponse = await fetch(proofUpload.uploadUrl, {
-        method: "PUT",
-        body: proofContents,
-        headers: { "Content-Type": proofUpload.contentType },
-    });
-    if (!uploadResponse.ok) {
-        throw new Error(`Payment-proof upload failed: HTTP ${uploadResponse.status} ${(await uploadResponse.text()).slice(0, 500)}`);
-    }
-    const result = await api.customerInvoice.markPaid.mutate({
-        invoiceId,
-        paymentDate: normalizedPaymentDate,
-        paymentReference,
-        proof: {
-            key: proofUpload.key,
-            name: proofUpload.name,
-            size: proofContents.byteLength,
-            contentType: proofUpload.contentType,
-        },
-    });
-    out(result);
-};
-export const downloadCustomerInvoicePaymentProof = async (invoiceId, outputPath) => {
-    const proof = await api.customerInvoice.getPaymentProofDownloadUrl.mutate({
-        invoiceId,
-    });
-    const response = await fetch(proof.url);
-    if (!response.ok) {
-        throw new Error(`Payment-proof download failed: HTTP ${response.status} ${(await response.text()).slice(0, 500)}`);
-    }
-    const contents = Buffer.from(await response.arrayBuffer());
-    const resolvedOutputPath = outputPath?.trim() || basename(proof.fileName);
-    await writeFile(resolvedOutputPath, contents);
-    out({
-        fileName: proof.fileName,
-        outputPath: resolvedOutputPath,
-        size: contents.byteLength,
-    });
-};
 export async function updateBillFromPayload(raw) {
     const input = parseUpdateBillPayload(raw);
     const result = await api.bill.update.mutate(input);
@@ -2006,6 +1915,30 @@ export async function getProject(id) {
     ]);
     out({ project, budgetsOverview, billsOverview });
 }
+export const getProjectHubStatus = async (projectId) => {
+    const result = await api.project.getProjectHubShareLink.query({ projectId });
+    out(result);
+};
+export const setupProjectHub = async (projectId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Set up Project Hub",
+        entity: `project ${projectId}`,
+        details: "queue Asana, Drive, and client Hub provisioning",
+    });
+    const result = await api.project.setupProjectHub.mutate({ projectId });
+    out(result);
+};
+export const syncProjectHubCommercialDocuments = async (projectId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Sync Project Hub commercial documents",
+        entity: `project ${projectId}`,
+        details: "queue a full Budget Builder to Google Drive and Asana reconciliation",
+    });
+    const result = await api.project.syncProjectHubCommercialDocuments.mutate({
+        projectId,
+    });
+    out(result);
+};
 export async function createProject(opts) {
     const links = await resolveCreateProjectLinks({
         name: opts.name,

package/dist/index.js

@@ -5,7 +5,7 @@ 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, downloadCustomerInvoicePaymentProof, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getInboundSource, getInboundSubmission, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, 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, markCustomerInvoicePaidFromPath, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, saveInboundAutomationConfig, saveInboundMappingVersion, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, 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, 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 { getFlag, parseArgs } from "./parse-args.js";
 import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
 import { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
@@ -261,9 +261,6 @@ Customer invoices
   approve-customer-invoice <batchId>           Admin approval; rejects voided invoices, notifies the creator, and closes the estimate at cumulative 100% coverage.
   reject-customer-invoice <batchId> --reason <text>   Admin rejection; voids QBO invoices and notifies the creator.
   send-customer-invoice-to-contact-person --payload '<json>'   Same composer workflow as web; requires invoiceId, to, cc, replyTo, subject, HTML content, and HTML signature.
-  mark-customer-invoice-paid <invoiceId> --paymentDate YYYY-MM-DD --paymentProof <path> [--paymentReference <text>]
-    Admin-only. Uploads proof, creates a QBO Payment for the live balance when needed, attaches proof in QBO when possible, and records payment history in BB.
-  download-customer-invoice-payment-proof <invoiceId> [--output <path>]
   download-customer-invoice-pdf <invoiceId> [--output <path>]
   sync-customer-invoice <invoiceId>             Refresh local status and balance from QuickBooks; paid invoices become PAID, reversals restore delivery/approval, and QBO voids can reopen an estimate.
 
@@ -1453,29 +1450,6 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 await sendCustomerInvoiceToContactPersonFromPayload(parseJsonFlag(String(payloadRaw), "--payload"));
                 break;
             }
-            case "mark-customer-invoice-paid": {
-                const invoiceId = positional[0];
-                const paymentDate = getFlag(flags, "paymentDate");
-                const paymentProofPath = getFlag(flags, "paymentProof");
-                if (!invoiceId || !paymentDate || !paymentProofPath) {
-                    throw new Error("mark-customer-invoice-paid requires <invoiceId> --paymentDate YYYY-MM-DD --paymentProof <path> [--paymentReference <text>]");
-                }
-                await markCustomerInvoicePaidFromPath({
-                    invoiceId,
-                    paymentDate,
-                    paymentProofPath,
-                    paymentReference: getFlag(flags, "paymentReference"),
-                });
-                break;
-            }
-            case "download-customer-invoice-payment-proof": {
-                const invoiceId = positional[0];
-                if (!invoiceId) {
-                    throw new Error("download-customer-invoice-payment-proof requires <invoiceId> [--output <path>]");
-                }
-                await downloadCustomerInvoicePaymentProof(invoiceId, getFlag(flags, "output"));
-                break;
-            }
             case "download-customer-invoice-pdf": {
                 const invoiceId = positional[0];
                 if (!invoiceId) {
@@ -1616,6 +1590,30 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 await getProject(id);
                 break;
             }
+            case "get-project-hub-status": {
+                const projectId = positional[0];
+                if (!projectId) {
+                    throw new Error("get-project-hub-status requires <projectId>");
+                }
+                await getProjectHubStatus(projectId);
+                break;
+            }
+            case "setup-project-hub": {
+                const projectId = positional[0];
+                if (!projectId) {
+                    throw new Error("setup-project-hub requires <projectId>");
+                }
+                await setupProjectHub(projectId);
+                break;
+            }
+            case "sync-project-hub-commercial-documents": {
+                const projectId = positional[0];
+                if (!projectId) {
+                    throw new Error("sync-project-hub-commercial-documents requires <projectId>");
+                }
+                await syncProjectHubCommercialDocuments(projectId);
+                break;
+            }
             case "create-project": {
                 const name = getFlag(flags, "name");
                 const companyId = getFlag(flags, "companyId");

package/dist/registry/index.js

@@ -59,6 +59,7 @@ const mutationPrefixes = [
     "save-",
     "send-",
     "stage-",
+    "setup-",
     "submit-",
     "sync-",
     "update-",
@@ -110,13 +111,14 @@ const externalWriteTargets = new Set([
     "import-qbo-project",
     "mark-budget-items-not-utilized",
     "mark-budget-won",
-    "mark-customer-invoice-paid",
     "reconcile-project",
     "reject-customer-invoice",
     "reactivate-suppliers",
     "restore-budget-item",
     "restore-budget-version",
     "retry-integration-operation",
+    "setup-project-hub",
+    "sync-project-hub-commercial-documents",
     "sync-customer-invoice",
     "update-bill",
     "update-budget-status",
@@ -143,7 +145,6 @@ const financialWriteTargets = new Set([
     "delete-customer-invoice",
     "mark-budget-items-not-utilized",
     "mark-budget-won",
-    "mark-customer-invoice-paid",
     "patch-bill-payment",
     "reject-customer-invoice",
     "restore-budget-item",
@@ -343,16 +344,6 @@ const registry = [
         "customer-invoice",
         "send",
     ]),
-    legacyCommand("mark-customer-invoice-paid", [
-        "customer-invoice",
-        "payment",
-        "mark-paid",
-    ]),
-    legacyCommand("download-customer-invoice-payment-proof", [
-        "customer-invoice",
-        "payment-proof",
-        "download",
-    ]),
     legacyCommand("download-customer-invoice-pdf", [
         "customer-invoice",
         "pdf",
@@ -374,6 +365,13 @@ const registry = [
     legacyCommand("delete-company", ["company", "delete"]),
     legacyCommand("list-projects", ["project", "list"]),
     legacyCommand("get-project", ["project", "get"]),
+    legacyCommand("get-project-hub-status", ["project", "hub", "status"]),
+    legacyCommand("setup-project-hub", ["project", "hub", "setup"]),
+    legacyCommand("sync-project-hub-commercial-documents", [
+        "project",
+        "hub",
+        "sync",
+    ]),
     legacyCommand("create-project", ["project", "create"]),
     legacyCommand("update-project", ["project", "update"]),
     legacyCommand("delete-project", ["project", "delete"]),

package/package.json

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

@@ -89,6 +89,7 @@ This table highlights the role-sensitive command groups an agent is most likely
 | `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 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`. |
 | `bb bill approve` and `bb bill reject` | Current user must be the pending approver and currently have role `ACCOUNTING_TEAM` for the finance/check stage or `ADMIN` for the final approval stage. |
@@ -97,7 +98,6 @@ This table highlights the role-sensitive command groups an agent is most likely
 | `bb bill status update ... APPROVED` or `... PAID` | `ADMIN`; state, integration, payment-reference, and payment-proof requirements still apply. |
 | `bb bill payment patch`; `bb bill invoice-number patch` | `ACCOUNTING_TEAM` or `ADMIN`, with the procedure's bill-state constraints. |
 | `bb customer-invoice approve` and `bb customer-invoice reject` | `ADMIN` batch operations selected by batch ID; the API resolves the internal pending Admin approval record. |
-| `bb customer-invoice payment mark-paid` | `ADMIN`. |
 | Dashboard/performance, supplier analytics, errors, integration operations | `ADMIN`. |
 | `bb item category create`, `bb item category update`, `bb item category delete`, `bb supplier delete`, `bb supplier reactivate`, and `bb budget item placeholder-bill create` | `ADMIN`. |
 
@@ -121,6 +121,7 @@ The following distinctions are especially important:
 - Budget, supplier, bill, and quotation decisions require both the matching live role and a pending approval assigned to the current identity. Customer-invoice approve/reject are Admin batch operations selected by batch ID; the API resolves their internal approval record.
 - Some company, contact, project, supplier, and catalog collaboration procedures intentionally allow every active authenticated role. Treat these endpoint-specific rules as exceptions rather than inferring access to adjacent mutations.
 - Budget and project commands often depend on creator/assignment access even when the role itself is valid.
+- Project Hub setup and sync are asynchronous external writes. Read `bb project hub status <project-id>` first, obtain explicit approval, and request the mutation once instead of repeatedly queueing it. Setup readiness remains visible through `status`; commercial sync returns an outbox operation ID for Admin diagnostics.
 - Bill/claim status commands have separate role rules for `CHECKED`, `APPROVED`, and `PAID`.
 - `bb bill create --payload` uses `isClaimable=false`; `isClaimable=true` creates a claim. Claims intentionally permit some base-user flows that supplier bills do not.
 - Staged attachments belong to the user in the database. Do not reuse, share, or manually construct staged keys.