@go-labs-sg/bb 2.41.0 → 2.43.0

package/README.md

@@ -22,6 +22,39 @@ The shared API rechecks existing records at submission. Canonical matches reuse
 
 `bb company use` and `bb company create` are state-changing, potentially external-writing commands. In non-interactive mode their existing permission gates require `--allow-state-change --allow-external-write`. Deploy the backend before publishing this CLI change. See [company discovery details](../api/docs/company-discovery.md) for limits and retry behaviour.
 
+## Record a payment made outside Budget Builder
+
+Admins can record an already-made payment on an APPROVED bill or claim without transferring money or emailing the supplier/claimant:
+
+```bash
+bb bill payment accounts
+bb bill payment record-external <billId> \
+  --paymentReference 2343190532 \
+  --paymentDate 2026-09-01 \
+  --paymentAccount <quickbooks-account-id> \
+  --paymentProof receipt.pdf
+```
+
+Choose the bank or card account actually used (including `Events Requisitions`); no account or date is defaulted. Omit `--paymentProof` if a payment-proof PDF is already attached. In non-interactive use, add `--allow-state-change --allow-external-write --allow-financial-write`; no `--allow-email` is needed. The UI offers the same **Record external payment** action next to ordinary **Mark paid**.
+
+BB marks the bill PAID immediately and queues durable QuickBooks reconciliation. A settled zero-balance QBO bill reuses its existing BillPayment IDs. Otherwise reconciliation creates a payment with the specified date/account and a stable provider request ID. Partially settled or inconsistent QBO bills require manual reconciliation; BB never guesses. Inspect failed/pending work in Integration Queue and **do not pay the bill again**. Exact retries with the same reference/date/account return the recorded settlement; changed details conflict. Ordinary Mark paid keeps its existing payment-advice workflow.
+
+`bb update-bill --payload '{"id":"<billId>","comment":"Already paid; do not pay again"}'` now accepts a partial payload. Omitted fields are preserved; comment-only updates do not change financial data or sync QBO, and are allowed on approved/paid bills for the creator or an admin. Financial edits retain their draft/rejected restrictions.
+
+Deployment prerequisite: apply the Budget Builder Prisma schema additions (`Bill.externalPayment` JSON and `EXTERNAL_PAYMENT` operation enum) before deploying the API/web/workers; deploy the backend before publishing the CLI. This feature does not modify existing paid bills or repair historical QBO entries automatically.
+
+## Payload help and uncertain writes
+
+Run `bb <command> --help` (for example, `bb create-item --help`) to see required and optional `--payload` fields and an example JSON object. Item creation and updates accept a finite numeric `cost` and convert it to the API's decimal-string input. Validation errors identify the affected field; unsupported QuickBooks name characters are listed explicitly.
+
+If `create-budget` reports an uncertain outcome (including Prisma P2028 or a network interruption), **do not retry immediately**. Run `bb list-budgets --projectId <project-id>` and check for the budget name first; the write may have committed even though the CLI did not receive a successful response. This check is not an idempotency guarantee when another budget has the same name.
+
+A failed `create-supplier` request may likewise have committed. Inspect `bb list-suppliers --name <name>` and matching supplier details before retrying; names alone do not identify one attempt. If supplier creation succeeded but its separate approval request failed or returned no approval IDs, inspect that supplier's approvals by ID and retry only the approval step if needed. Do not create the supplier again. The CLI confirms the combined supplier-and-approval workflow before the first write.
+
+`create-budget-approval` and `create-estimate` accept `--companyPayload`, `--contactPayload`, and `--eventPayload` as JSON objects. The CLI rejects non-object JSON; the API validates required fields.
+
+`create-project` requires an existing Asana Deals lead task. In non-interactive runs pass `--asanaTaskId`; interactive runs can select a match with `--asanaSearch`. The Slack channel is resolved from the task unless all Slack channel flags are provided. For a new direct client, create the lead task in the website form first.
+
 ## Shared catalogue editing
 
 All active authenticated users can edit suppliers, inventory items and item categories. Normal-user supplier updates submit a revision for approval in the shared API; item/category edits apply immediately. Lead/Admin supplier edits bypass human review. `bb supplier update` returns the server-owned approval/synchronization result without issuing another approval request. New supplier usage stays on hold during review and linked QuickBooks synchronization; existing usage continues with the last approved details until the edit is approved. Creator identity and delete/archive permissions are unchanged.

package/command-manifest.json

@@ -790,6 +790,18 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--companyPayload <json>",
+				"description": "Company update JSON object with id, name, and website fields."
+			},
+			{
+				"name": "--contactPayload <json>",
+				"description": "Contact update JSON object with companyId, title, firstName, lastName, email, and mobile fields."
+			},
+			{
+				"name": "--eventPayload <json>",
+				"description": "Event timing JSON object with date, startTime, and endTime fields."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -840,6 +852,18 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--companyPayload <json>",
+				"description": "Company update JSON object with id, name, and website fields."
+			},
+			{
+				"name": "--contactPayload <json>",
+				"description": "Contact update JSON object with companyId, title, firstName, lastName, email, and mobile fields."
+			},
+			{
+				"name": "--eventPayload <json>",
+				"description": "Event timing JSON object with date, startTime, and endTime fields."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -2237,7 +2261,7 @@
 	{
 		"path": ["bill", "update"],
 		"legacyAliases": ["update-bill", "update_bill"],
-		"summary": "Update a bill or claim; payload must include id. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.",
+		"summary": "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2437,6 +2461,112 @@
 		"effects": ["state-change", "email", "financial-write"],
 		"legacyTarget": "update-bill-status"
 	},
+	{
+		"path": ["bill", "payment", "record-external"],
+		"legacyAliases": [
+			"record-external-bill-payment",
+			"record_external_bill_payment"
+		],
+		"summary": "Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "external-write", "financial-write"],
+		"legacyTarget": "record-external-bill-payment"
+	},
+	{
+		"path": ["bill", "payment", "accounts"],
+		"legacyAliases": [
+			"list-external-payment-accounts",
+			"list_external_payment_accounts"
+		],
+		"summary": "List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "list-external-payment-accounts"
+	},
 	{
 		"path": ["bill", "payment", "patch"],
 		"legacyAliases": ["patch-bill-payment", "patch_bill_payment"],
@@ -5504,7 +5634,7 @@
 	{
 		"path": ["project", "create"],
 		"legacyAliases": ["create-project", "create_project"],
-		"summary": "Create Project.",
+		"summary": "Create a project linked to an existing Asana Deals lead task. Supply --asanaTaskId in non-interactive use; interactive use searches for and selects a lead task (optionally --asanaSearch). The Slack channel is resolved from the selected Asana task unless all three Slack channel flags are supplied. For a new direct client, create the lead task using the website form first.",
 		"globalOptions": [
 			{
 				"name": "--help",

package/command-reference.md

@@ -161,6 +161,11 @@ Legacy aliases: `send-estimate-to-contact-person`, `send_estimate_to_contact_per
 
 Effects: state-change, email.
 
+Payload fields (--payload JSON)
+  Required: estimateId: string; budgetId: string; to: email; cc: email[]; replyTo: email; subject: string; content: HTML string; signature: HTML string
+  Optional: estimateDocNumber: string
+  Example: bb send-estimate-to-contact-person --payload '{"estimateId":"<estimate-id>","budgetId":"<budget-id>","to":"client@example.com","cc":[],"replyTo":"team@example.com","subject":"Estimate","content":"<p>Attached estimate</p>","signature":"<p>Team</p>"}'
+
 ## `bb budget create`
 
 Create Budget.
@@ -169,6 +174,11 @@ Legacy aliases: `create-budget`, `create_budget`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: name: string; budget: decimal string; paymentTerm: string; categoryId: string; projectId: string
+  Optional: sourceBudgetId: string; unavailableItemReviewAcknowledged: boolean (only after review); pipedriveDealId: string
+  Example: bb create-budget --payload '{"name":"Event budget","budget":"1500","paymentTerm":"Net 30","categoryId":"<category-id>","projectId":"<project-id>"}'
+
 ## `bb budget update`
 
 Update Budget.
@@ -177,6 +187,11 @@ Legacy aliases: `update-budget`, `update_budget`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; budget: decimal string; paymentTerm: string; categoryId: string; projectId: string
+  Optional: sourceBudgetId: string; pipedriveDealId: string
+  Example: bb update-budget --payload '{"id":"<budget-id>","name":"Event budget","budget":"1500","paymentTerm":"Net 30","categoryId":"<category-id>","projectId":"<project-id>"}'
+
 ## `bb budget delete`
 
 Delete Budget.
@@ -273,6 +288,11 @@ Legacy aliases: `update-budget-commission`, `update_budget_commission`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; name: string; percentage: decimal string; totalSellingAfterDiscount: number
+  Optional: none
+  Example: bb update-budget-commission --payload '{"budgetId":"<budget-id>","name":"Sales commission","percentage":"10","totalSellingAfterDiscount":1500}'
+
 ## `bb budget discount update`
 
 Update Budget Discount.
@@ -281,6 +301,11 @@ Legacy aliases: `update-budget-discount`, `update_budget_discount`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; name: string; type: percentage|amount; value: decimal string; totalSellingBeforeDiscount: number
+  Optional: none
+  Example: bb update-budget-discount --payload '{"budgetId":"<budget-id>","name":"Discount","type":"amount","value":"100","totalSellingBeforeDiscount":1500}'
+
 ## `bb budget commission delete`
 
 Delete Budget Commission.
@@ -353,6 +378,11 @@ Legacy aliases: `create-bill`, `create_bill`.
 
 Effects: state-change, email, external-write, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; projectId: string; supplierId: string; amount: number (ex-GST); budgetItemIds: string[]; isClaimable: boolean; supplier bills: quotationIds: string[] or quotationAllocations: {budgetItemId, quotationId, amount}[] (unless --quotation-exempt)
+  Optional: lineAmounts: {budgetItemId, amount}[] (required with quotationAllocations); attachments: {id,name,key,size}[]; invoiceNumber: string; invoiceDate: ISO date; draftOnly: boolean; alreadyPaid: boolean; extractedAmount: number
+  Example: bb create-bill --payload '{"budgetId":"<budget-id>","projectId":"<project-id>","supplierId":"<supplier-id>","amount":1800,"budgetItemIds":["<budget-item-id>"],"isClaimable":false,"quotationIds":["<quotation-id>"],"attachments":[]}'
+
 ## `bb bill selection validate`
 
 Validate the approved supplier and selected bill line items.
@@ -361,6 +391,11 @@ Legacy aliases: `validate-bill-selection`, `validate_bill_selection`.
 
 Effects: none.
 
+Payload fields (--payload JSON)
+  Required: projectId: string; supplierId: string; budgetItemIds: string[]
+  Optional: quotationIds: string[] for supplier bills; isClaimable: boolean; amount: number; lineAmounts: {budgetItemId, amount}[]; quotationAllocations: {budgetItemId, quotationId, amount}[] (requires amount and lineAmounts)
+  Example: bb validate-bill-selection --payload '{"projectId":"<project-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"quotationIds":["<quotation-id>"]}'
+
 ## `bb bill quotation link`
 
 Link Bill Quotations.
@@ -369,14 +404,24 @@ Legacy aliases: `link-bill-quotations`, `link_bill_quotations`, `billId`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: positional <billId>; quotationIds: string[] or quotationAllocations: {budgetItemId, quotationId, amount}[]
+  Optional: none (legacy quotationId is not supported)
+  Example: bb link-bill-quotations <billId> --payload '{"quotationIds":["<quotation-id>"]}'
+
 ## `bb bill update`
 
-Update a bill or claim; payload must include id. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.
+Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.
 
 Legacy aliases: `update-bill`, `update_bill`.
 
 Effects: state-change, external-write, financial-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; budgetId: string; projectId: string; supplierId: string; amount: number (ex-GST); budgetItemIds: string[]; isClaimable: boolean
+  Optional: quotationIds: string[]; quotationAllocations: {budgetItemId, quotationId, amount}[]; lineAmounts: {budgetItemId, amount}[]; attachments: {id,name,key,size}[]; invoiceNumber: string; invoiceDate: ISO date
+  Example: bb update-bill --payload '{"id":"<bill-id>","budgetId":"<budget-id>","projectId":"<project-id>","supplierId":"<supplier-id>","amount":1800,"budgetItemIds":["<budget-item-id>"],"isClaimable":false,"quotationIds":["<quotation-id>"],"attachments":[]}'
+
 ## `bb bill payment-evidence update`
 
 Update Bill Payment Evidence.
@@ -385,6 +430,11 @@ Legacy aliases: `update-bill-payment-evidence`, `update_bill_payment_evidence`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; paymentReference: string; paymentProofAttachments: {id,name (PDF),key,size}[] (at least one)
+  Optional: none
+  Example: bb update-bill-payment-evidence --payload '{"id":"<bill-id>","paymentReference":"TRANSFER-123","paymentProofAttachments":[{"id":"<attachment-id>","name":"receipt.pdf","key":"<staged-key>","size":1000}]}'
+
 ## `bb bill delete`
 
 Delete Bill.
@@ -401,6 +451,22 @@ Legacy aliases: `update-bill-status`, `update_bill_status`.
 
 Effects: state-change, email, financial-write.
 
+## `bb bill payment record-external`
+
+Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.
+
+Legacy aliases: `record-external-bill-payment`, `record_external_bill_payment`.
+
+Effects: state-change, external-write, financial-write.
+
+## `bb bill payment accounts`
+
+List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).
+
+Legacy aliases: `list-external-payment-accounts`, `list_external_payment_accounts`.
+
+Effects: none.
+
 ## `bb bill payment patch`
 
 Patch Bill Payment.
@@ -513,6 +579,11 @@ Legacy aliases: `create-quotation`, `create_quotation`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: projectId: string; budgetId: string; supplierId: string; budgetItemIds: string[]; amountWithoutGst: number; gstAmount: number; attachments: array (uploaded attachment)
+  Optional: lineAmounts: {budgetItemId, amount}[] (required for multiple budget items)
+  Example: bb create-quotation --payload '{"projectId":"<project-id>","budgetId":"<budget-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"amountWithoutGst":1200,"gstAmount":0,"attachments":[{"id":"<attachment-id>","name":"quote.pdf","key":"<staged-key>","size":1000}]}'
+
 ## `bb quotation update`
 
 Update a DRAFT or REJECTED quotation using --payload JSON with id and the complete creation payload. Multiple budget items require lineAmounts: [{"budgetItemId":"<first-id>","amount":750},{"budgetItemId":"<second-id>","amount":450}], covering every budgetItemIds entry exactly once and summing to amountWithoutGst. Amounts exclude GST; use gstAmount: 0 for no GST.
@@ -521,6 +592,11 @@ Legacy aliases: `update-quotation`, `update_quotation`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: id: string; projectId: string; budgetId: string; supplierId: string; budgetItemIds: string[]; amountWithoutGst: number; gstAmount: number; attachments: array
+  Optional: lineAmounts: {budgetItemId, amount}[] (required for multiple budget items)
+  Example: bb update-quotation --payload '{"id":"<quotation-id>","projectId":"<project-id>","budgetId":"<budget-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"amountWithoutGst":1200,"gstAmount":0,"attachments":[{"id":"<attachment-id>","name":"quote.pdf","key":"<staged-key>","size":1000}]}'
+
 ## `bb quotation delete`
 
 Delete Quotation.
@@ -641,6 +717,11 @@ Legacy aliases: `create-customer-invoice`, `create_customer_invoice`.
 
 Effects: state-change, email, external-write, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; splits: [{label: string, percentage: number, dueDate: ISO date}] (exactly one)
+  Optional: requestId: UUID string (recommended); invoiceDate: ISO date; details: {billingAddress: string, customerMemo: string}; isCustomPercentage: boolean
+  Example: bb create-customer-invoice --payload '{"budgetId":"<budget-id>","splits":[{"label":"Deposit","percentage":50,"dueDate":"2026-10-15"}],"details":{"billingAddress":"1 Example St","customerMemo":"Thanks"}}'
+
 ## `bb customer-invoice discard`
 
 Discard Customer Invoice.
@@ -689,6 +770,11 @@ Legacy aliases: `send-customer-invoice-to-contact-person`, `send_customer_invoic
 
 Effects: state-change, email.
 
+Payload fields (--payload JSON)
+  Required: invoiceId: string; to: email; cc: email[]; replyTo: email; subject: string; content: HTML string; signature: HTML string
+  Optional: none
+  Example: bb send-customer-invoice-to-contact-person --payload '{"invoiceId":"<invoice-id>","to":"client@example.com","cc":[],"replyTo":"team@example.com","subject":"Invoice","content":"<p>Attached invoice</p>","signature":"<p>Team</p>"}'
+
 ## `bb customer-invoice pdf download`
 
 Download a customer invoice PDF when permitted.
@@ -817,6 +903,11 @@ Legacy aliases: `update-company`, `update_company`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; website: URL string
+  Optional: confirmDistinct: boolean
+  Example: bb update-company --payload '{"id":"<company-id>","name":"Example Co","website":"https://example.com"}'
+
 ## `bb company delete`
 
 Delete Company.
@@ -875,7 +966,7 @@ Effects: state-change, external-write.
 
 ## `bb project create`
 
-Create Project.
+Create a project linked to an existing Asana Deals lead task. Supply --asanaTaskId in non-interactive use; interactive use searches for and selects a lead task (optionally --asanaSearch). The Slack channel is resolved from the selected Asana task unless all three Slack channel flags are supplied. For a new direct client, create the lead task using the website form first.
 
 Legacy aliases: `create-project`, `create_project`.
 
@@ -889,6 +980,11 @@ Legacy aliases: `update-project`, `update_project`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; companyId: string; contactPersonId: string; asanaTaskId: string; insideSalesId: string; businessDevelopmentId: string; venue: string; dateRange: {from: ISO date}
+  Optional: dateRange.to: ISO date; projectManagerId: string; pax: string; description: string; slackChannelId/slackChannelUrl/slackChannelName: strings (supply all three); requestQboAccountantNotification: boolean; confirmEstimateInvalidation: boolean
+  Example: bb update-project --payload '{"id":"<project-id>","name":"Launch","companyId":"<company-id>","contactPersonId":"<contact-id>","asanaTaskId":"<asana-task-id>","insideSalesId":"<user-id>","businessDevelopmentId":"<user-id>","venue":"Hall","dateRange":{"from":"2026-10-01T09:00:00Z"}}'
+
 ## `bb project delete`
 
 Delete Project.
@@ -953,6 +1049,11 @@ Legacy aliases: `create-contact-person`, `create_contact_person`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: companyId: string; title: MR|MRS|MS|DR; firstName: string; lastName: string|null; email: string; mobile: string
+  Optional: address: {streetAddress1?, city?, state?, postalCode?, country?}
+  Example: bb create-contact-person --payload '{"companyId":"<company-id>","title":"MS","firstName":"Jane","lastName":"Tan","email":"jane@example.com","mobile":"+65 9123 4567"}'
+
 ## `bb contact update`
 
 Update Contact Person.
@@ -961,6 +1062,11 @@ Legacy aliases: `update-contact-person`, `update_contact_person`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: id: string; companyId: string; title: MR|MRS|MS|DR; firstName: string; lastName: string|null; email: string; mobile: string
+  Optional: address: object
+  Example: bb update-contact-person --payload '{"id":"<contact-id>","companyId":"<company-id>","title":"MS","firstName":"Jane","lastName":"Tan","email":"jane@example.com","mobile":"+65 9123 4567"}'
+
 ## `bb supplier list`
 
 List suppliers.
@@ -977,6 +1083,11 @@ Legacy aliases: `create-supplier`, `create_supplier`.
 
 Effects: state-change, email, external-write.
 
+Payload fields (--payload JSON)
+  Required: name: string; primaryContactPerson: string; email: string; phone: string; paymentMethodId: string; paymentTerm: string; roleId: string
+  Optional: gstRegistered: boolean; tags: string[]; website: URL string; address: object; attachments: array; bank and PayNow fields
+  Example: bb create-supplier --payload '{"name":"Example Supplier","primaryContactPerson":"Jane Tan","email":"jane@example.com","phone":"91234567","paymentMethodId":"<method-id>","paymentTerm":"Net 30","roleId":"<role-id>"}'
+
 ## `bb supplier update`
 
 Update Supplier.
@@ -985,6 +1096,11 @@ Legacy aliases: `update-supplier`, `update_supplier`.
 
 Effects: state-change, email, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; primaryContactPerson: string; email: string; phone: string; paymentMethodId: string; paymentTerm: string; roleId: string
+  Optional: gstRegistered: boolean; tags: string[]; website: URL string; address: object; attachments: array; bank and PayNow fields
+  Example: bb update-supplier --payload '{"id":"<supplier-id>","name":"Example Supplier","primaryContactPerson":"Jane Tan","email":"jane@example.com","phone":"91234567","paymentMethodId":"<method-id>","paymentTerm":"Net 30","roleId":"<role-id>"}'
+
 ## `bb supplier delete`
 
 Delete Suppliers.
@@ -1065,6 +1181,11 @@ Legacy aliases: `create-item`, `create_item`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: name: string (QuickBooks-safe characters); categoryId: string; supplierId: string; cost: decimal string or number
+  Optional: description: string; gstInclusive: boolean; gstOutOfScope: boolean; goLabsProduct: boolean; attachments: array
+  Example: bb create-item --payload '{"name":"Event Crew per hour","categoryId":"<category-id>","supplierId":"<supplier-id>","cost":19}'
+
 ## `bb item update`
 
 Update Item.
@@ -1073,6 +1194,11 @@ Legacy aliases: `update-item`, `update_item`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; categoryId: string; supplierId: string; cost: decimal string or number
+  Optional: description: string; gstInclusive: boolean; gstOutOfScope: boolean; goLabsProduct: boolean; attachments: array
+  Example: bb update-item --payload '{"id":"<item-id>","name":"Event Crew per hour","categoryId":"<category-id>","supplierId":"<supplier-id>","cost":"19"}'
+
 ## `bb item archive`
 
 Archive Items.
@@ -1297,6 +1423,11 @@ Legacy aliases: `save-inbound-mapping`, `save_inbound_mapping`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: positional <sourceId>; payload: [{canonicalField: enum, typeformFieldId: string, required?: boolean, typeformFieldRef?: string|null}] (1-50 entries)
+  Optional: required defaults false; typeformFieldRef may be omitted
+  Example: bb save-inbound-mapping <sourceId> --payload '[{"canonicalField":"CONTACT_FIRST_NAME","typeformFieldId":"<typeform-field-id>"}]'
+
 ## `bb inbound automation save`
 
 Save Inbound Automation Config.
@@ -1305,6 +1436,11 @@ Legacy aliases: `save-inbound-automation-config`, `save_inbound_automation_confi
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: positional <sourceId>; asanaCustomFields: object; asanaDefaultAssigneeId: string|null; asanaDefaultAssigneeName: string|null; asanaFollowerIds: string[]; asanaProjectId: string; asanaSectionId: string; asanaWonSectionId: string; asanaLostSectionId: string; googleCalendarId: string; googleCalendarTimeZone: string; goshBriefBaseUrl: URL; slackDefaultAssigneeId: string|null; slackInboundChannelId: string; slackInviteUserIds: string[]; slackPitchChannelPrefix: string
+  Optional: asanaDiscussionSectionId, asanaFirstContactSectionId, asanaFirstProposalSentSectionId, asanaProposalWipSectionId: string|null; asanaCustomFields.*: mapped IDs
+  Example: bb save-inbound-automation-config <sourceId> --payload '{"asanaCustomFields":{},"asanaDefaultAssigneeId":null,"asanaDefaultAssigneeName":null,"asanaFollowerIds":[],"asanaProjectId":"<asana-project-id>","asanaSectionId":"<asana-section-id>","asanaWonSectionId":"<asana-won-id>","asanaLostSectionId":"<asana-lost-id>","googleCalendarId":"team@example.com","googleCalendarTimeZone":"Asia/Singapore","goshBriefBaseUrl":"https://example.com/brief","slackDefaultAssigneeId":null,"slackInboundChannelId":"<slack-channel-id>","slackInviteUserIds":[],"slackPitchChannelPrefix":"pitch"}'
+
 ## `bb inbound processing update`
 
 Update Inbound Processing.