@go-labs-sg/bb 2.33.1 → 2.34.0

package/README.md

@@ -12,6 +12,16 @@ For AI agents using this CLI: do not execute mutations until the user explicitly
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
+## Company discovery and reuse
+
+`bb company search --query "a star" [--page 2]` searches stored BB companies and QuickBooks company customers, including inactive records. Results identify `bb`, `qbo`, or `both`; punctuation/spacing normalization is for suggestions only. Search does not write to either system.
+
+After reviewing a result, `bb company use --companyId <bbId>` reuses BB and resolves its QBO customer. `bb company use --quickbooksId <qboId>` imports the existing QBO name/website when BB is missing. Supply both IDs to explicitly connect two unlinked records whose names differ; existing company details are preserved. If QBO has no website, add `--website <url>` for the BB import only.
+
+The shared API rechecks existing records at submission. Canonical matches reuse records; fuzzy matches require an explicit choice or `--confirmDistinct true` to confirm a separate legal entity. Inactive companies and conflicting links require review, never implicit reactivation. QBO project/sub-customers are not company-import candidates. Provider failures are not treated as missing records.
+
+`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.
+
 ## 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.
@@ -286,6 +296,48 @@ Bill creation determines its required permissions from the parsed input, for bot
 
 **Contact-person estimate email:** `bb budget estimate send --payload '<json>'` calls the same `email.sendEstimateToContactPerson` procedure as the web composer. The payload requires `budgetId`, `estimateId`, optional `estimateDocNumber`, `to`, `cc`, `replyTo`, `subject`, HTML `content`, and HTML `signature`. It durably queues worker delivery of the QuickBooks PDF, standard terms, and Budget Builder budget attachments, and returns the outbound-email and operation IDs immediately. Worker retries reuse one provider idempotency key; the budget becomes `ESTIMATE_SENT` only after Resend accepts the email. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first.
 
+### Quotation amounts and line allocations
+
+Quotation create and update payloads use `amountWithoutGst` for the supplier subtotal and `gstAmount` for GST. Keep GST separate; do not add it to `amountWithoutGst`. When a quotation covers more than one budget item, `lineAmounts` is required and must contain each selected item exactly once. The line amounts must sum to `amountWithoutGst`.
+
+Use the actual `budgetItemIds` returned by `bb budget get <budget-id>` or the relevant budget-item read. Do not invent IDs, use item names, or reuse IDs from another project or budget. `quotationAllocations` belongs to bill creation/update as the bill's source-quotation allocation; it is not a quotation create/update field.
+
+Upload exactly one quotation document first. Pass the single attachment object returned by `bb quotation attachment upload <project-id> <file-path>` in the quotation payload's one-element `attachments` array. The server accepts one original quotation file and normalizes it to PDF when needed.
+
+Replace the example attachment size `12345` with the actual byte count from the upload response.
+
+For a quotation split across two real budget lines at S$750 and S$450, with no GST, the complete CLI payload shape is:
+
+```bash
+bb quotation attachment upload "<project-id>" "<quotation-file.pdf>"
+
+# Replace every <...> placeholder with the matching value from the reads and
+# the upload response. The attachment array must contain that one upload object.
+bb quotation create --payload '{
+  "projectId": "<project-id>",
+  "budgetId": "<budget-id>",
+  "supplierId": "<supplier-id>",
+  "budgetItemIds": ["<budget-item-id-for-750>", "<budget-item-id-for-450>"],
+  "lineAmounts": [
+    {"budgetItemId": "<budget-item-id-for-750>", "amount": 750},
+    {"budgetItemId": "<budget-item-id-for-450>", "amount": 450}
+  ],
+  "amountWithoutGst": 1200,
+  "gstAmount": 0,
+  "attachments": [
+    {
+      "id": "<attachment-id-from-upload>",
+      "name": "<attachment-name-from-upload>",
+      "key": "<attachment-key-from-upload>",
+      "size": 12345
+    }
+  ]
+}'
+```
+
+Use the same fields for `bb quotation update --payload`, adding the existing quotation `"id": "<quotation-id>"`. Read the quotation and its budget before updating so the IDs and current status are confirmed. The example's subtotal is S$1,200, GST is S$0, and total is S$1,200; those values are illustrative only and contain no live resource IDs.
+
+
 ### Link an existing QuickBooks invoice
 
 **Release status:** these CLI commands are pending release. The repository package version remains `2.31.0`; that version number alone does not establish that a published CLI contains them. Check `bb help` for `customer-invoice preview-qbo` and `customer-invoice import-qbo` after the normal CLI release. This code delivery does not publish the CLI, deploy the API, or perform a production import. The backend must expose `customerInvoice.previewExistingInvoice` and `customerInvoice.linkExistingInvoice` (implemented in PR #1067).
@@ -358,7 +410,7 @@ Bill, claim, and quotation mutations accept only suppliers whose approval status
 | --- | --- |
 | **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`; cloned unavailable lines require `unavailableItemReviewAcknowledged: true`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `create-estimate`, `send-estimate-to-contact-person` (same contact-person email workflow as web), `add-budget-items`, `update-budget-item`, `replace-budget-item`, `approve-unavailable-item-exception` (Lead/Admin), `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `mark-budget-items-not-utilized`, `restore-budget-item`, `create-placeholder-bill` (admin recovery), `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `delete-budget-commission`, `update-budget-discount`, `delete-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
 | **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `validate-bill-selection` (`--payload`, plus `--quotationIds q1,q2` or legacy `--quotationId q1`; validates the approved supplier and quotation coverage), `link-bill-quotations` (`<billId> --quotationIds q1,q2`; Admin source-link repair for eligible supplier bills), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON; ownership and one-hour expiry are enforced by a server-side staged-upload record rather than encoded in the object key), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill and provide approved `quotationIds`, or use `--quotation-exempt` for an eligible server-validated exemption; set `isClaimable=true` for a claim without quotations; supplier bills require positive **before-GST** `extractedAmount` (full invoice subtotal) and `amount` (portion billed), with `amount <= extractedAmount`; line and quotation allocation amounts also exclude GST; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`; admin creation automatically queues QBO finalization while other roles remain pending approval), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (`PAID` requires `--paymentReference`; pass `--paymentProof <receipt.pdf>` to stage and submit a PDF up to 20MB atomically, or omit it only when BB already has payment proof; moving to `PAID` runs the server's paid-bill notification workflow), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
-| **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` 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`) |
+| **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst`, `gstAmount`, and `lineAmounts` entries `{ budgetItemId, amount }` for multiple selected items), `update-quotation` (`--payload`; updates a `DRAFT` or `REJECTED` quotation), `delete-quotation`, `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
 | **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `list-customer-invoices` (global/project/budget filters plus summary metrics; `--sortBy totalInvoiceAmount` sorts provider-confirmed totals including GST, with unknown amounts last), `get-customer-invoice`, `get-customer-invoice-email-context`, `preview-qbo-customer-invoice`, `import-qbo-customer-invoice` (BB-only link with reviewed token), `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
 | **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`) |

package/command-manifest.json

@@ -3107,7 +3107,7 @@
 	{
 		"path": ["quotation", "create"],
 		"legacyAliases": ["create-quotation", "create_quotation"],
-		"summary": "Create a quotation with an approved supplier.",
+		"summary": "Create a quotation with an approved supplier using --payload JSON. Include projectId, budgetId, supplierId, budgetItemIds, amountWithoutGst, gstAmount, and one uploaded attachment in attachments. Multiple budget items require lineAmounts: [{\"budgetItemId\":\"<first-id>\",\"amount\":750},{\"budgetItemId\":\"<second-id>\",\"amount\":450}], covering every selected budget-item ID exactly once and summing to amountWithoutGst. Amounts exclude GST; use gstAmount: 0 for no GST. Example: amountWithoutGst: 1200 with line amounts 750 and 450.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3148,6 +3148,11 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--payload",
+				"description": "Quotation JSON including lineAmounts for multiple selected budget items; see the payload format above.",
+				"required": true
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -3157,7 +3162,7 @@
 	{
 		"path": ["quotation", "update"],
 		"legacyAliases": ["update-quotation", "update_quotation"],
-		"summary": "Update a quotation with an approved supplier.",
+		"summary": "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.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -3198,6 +3203,11 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--payload",
+				"description": "Complete quotation JSON plus id, including lineAmounts for multiple selected budget items.",
+				"required": true
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -4780,10 +4790,134 @@
 		"effects": [],
 		"legacyTarget": "get-company"
 	},
+	{
+		"path": ["company", "search"],
+		"legacyAliases": ["search-existing-companies", "search_existing_companies"],
+		"summary": "Search BB and QuickBooks companies without writes. --query <name> [--page <number>].",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--query",
+				"description": "Company name to search in BB and QuickBooks."
+			},
+			{
+				"name": "--page",
+				"description": "Results page (eight companies per page)."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "search-existing-companies"
+	},
+	{
+		"path": ["company", "use"],
+		"legacyAliases": ["use-existing-company", "use_existing_company"],
+		"summary": "Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--companyId",
+				"description": "Existing BB company ID; combine with quickbooksId to explicitly connect both records."
+			},
+			{
+				"name": "--quickbooksId",
+				"description": "Existing QBO customer ID; alone imports or reuses its BB company."
+			},
+			{
+				"name": "--website",
+				"description": "Website only when missing from a QBO-only import."
+			},
+			{
+				"name": "--confirmDistinct",
+				"description": "Set true only when similar records do not represent this legal entity."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "external-write"],
+		"legacyTarget": "use-existing-company"
+	},
 	{
 		"path": ["company", "create"],
 		"legacyAliases": ["create-company", "create_company"],
-		"summary": "Create Company.",
+		"summary": "Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -4824,6 +4958,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--confirmDistinct",
+				"description": "Set true to confirm a separate legal entity despite similar names."
 			}
 		],
 		"argumentMode": "legacy-passthrough",

package/command-reference.md

@@ -507,7 +507,7 @@ Effects: state-change, delete.
 
 ## `bb quotation create`
 
-Create a quotation with an approved supplier.
+Create a quotation with an approved supplier using --payload JSON. Include projectId, budgetId, supplierId, budgetItemIds, amountWithoutGst, gstAmount, and one uploaded attachment in attachments. Multiple budget items require lineAmounts: [{"budgetItemId":"<first-id>","amount":750},{"budgetItemId":"<second-id>","amount":450}], covering every selected budget-item ID exactly once and summing to amountWithoutGst. Amounts exclude GST; use gstAmount: 0 for no GST. Example: amountWithoutGst: 1200 with line amounts 750 and 450.
 
 Legacy aliases: `create-quotation`, `create_quotation`.
 
@@ -515,7 +515,7 @@ Effects: state-change.
 
 ## `bb quotation update`
 
-Update a quotation with an approved supplier.
+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.
 
 Legacy aliases: `update-quotation`, `update_quotation`.
 
@@ -769,9 +769,25 @@ Legacy aliases: `get-company`, `get_company`.
 
 Effects: none.
 
+## `bb company search`
+
+Search BB and QuickBooks companies without writes. --query <name> [--page <number>].
+
+Legacy aliases: `search-existing-companies`, `search_existing_companies`.
+
+Effects: none.
+
+## `bb company use`
+
+Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.
+
+Legacy aliases: `use-existing-company`, `use_existing_company`.
+
+Effects: state-change, external-write.
+
 ## `bb company create`
 
-Create Company.
+Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.
 
 Legacy aliases: `create-company`, `create_company`.
 

package/dist/index.js

@@ -19478,14 +19478,6 @@ var logoutCliSession = async ({
 // src/cli.ts
 import { readFileSync } from "fs";
 
-// src/api-client.ts
-import {
-  createTRPCProxyClient,
-  httpBatchLink,
-  loggerLink
-} from "@trpc/client";
-import SuperJSON from "superjson";
-
 // src/cli-trace.ts
 var cliQuietSession = false;
 var setCliQuiet = (quiet) => {
@@ -19570,6 +19562,12 @@ var normalizeApiBaseUrl = (value) => {
 };
 
 // src/api-client.ts
+import {
+  createTRPCProxyClient,
+  httpBatchLink,
+  loggerLink
+} from "@trpc/client";
+import SuperJSON from "superjson";
 var BUDGET_BUILDER_API_BASE_URL = DEFAULT_BUDGET_BUILDER_API_BASE_URL;
 var interactiveAccessToken;
 function getAuthHeader() {
@@ -20130,6 +20128,138 @@ var normalizePlainTextRichTextField = ({
   };
 };
 
+// src/runtime/error.ts
+var invocationErrorCodes = new Set([
+  "USAGE",
+  "VALIDATION",
+  "CONFIRMATION_REQUIRED"
+]);
+var trpcCodeMap = {
+  BAD_REQUEST: "VALIDATION",
+  CONFLICT: "CONFLICT",
+  FORBIDDEN: "AUTHORIZATION",
+  INTERNAL_SERVER_ERROR: "API",
+  METHOD_NOT_SUPPORTED: "API",
+  NOT_FOUND: "NOT_FOUND",
+  PARSE_ERROR: "VALIDATION",
+  PAYLOAD_TOO_LARGE: "VALIDATION",
+  PRECONDITION_FAILED: "CONFLICT",
+  TIMEOUT: "NETWORK",
+  TOO_MANY_REQUESTS: "API",
+  UNAUTHORIZED: "AUTHENTICATION",
+  UNPROCESSABLE_CONTENT: "VALIDATION"
+};
+var cliErrorCodes = new Set([
+  "USAGE",
+  "VALIDATION",
+  "CONFIRMATION_REQUIRED",
+  "AUTHENTICATION",
+  "AUTHORIZATION",
+  "NOT_FOUND",
+  "CONFLICT",
+  "API",
+  "NETWORK",
+  "ABORTED",
+  "INTERRUPTED",
+  "INTERNAL"
+]);
+
+class CliRuntimeError extends Error {
+  code;
+  details;
+  requestId;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "CliRuntimeError";
+    this.code = code;
+    this.details = options.details;
+    this.requestId = options.requestId;
+  }
+}
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var asNonEmptyString = (value) => typeof value === "string" && value.trim() !== "" ? value : undefined;
+var asDetails = (value) => {
+  if (!isRecord(value))
+    return;
+  const details = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    if (isJsonValue(nestedValue))
+      details[key] = nestedValue;
+  }
+  return Object.keys(details).length > 0 ? details : undefined;
+};
+var isJsonValue = (value) => {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") {
+    return true;
+  }
+  if (Array.isArray(value))
+    return value.every(isJsonValue);
+  return isRecord(value) && Object.values(value).every(isJsonValue);
+};
+var mapErrorCode = (value) => {
+  if (typeof value !== "string")
+    return;
+  if (cliErrorCodes.has(value))
+    return value;
+  if (value in trpcCodeMap)
+    return trpcCodeMap[value];
+  return;
+};
+var networkMessagePattern = /\b(fetch failed|network error|unable to connect|econnrefused|econnreset|enotfound|etimedout|socket hang up)\b/i;
+var isNetworkError = (error61, depth = 0) => {
+  if (depth > 3 || !isRecord(error61))
+    return false;
+  const message = asNonEmptyString(error61.message);
+  if (message !== undefined && networkMessagePattern.test(message))
+    return true;
+  const code = asNonEmptyString(error61.code);
+  if (code !== undefined && networkMessagePattern.test(code))
+    return true;
+  return isNetworkError(error61.cause, depth + 1);
+};
+var normalizeCliError = (error61) => {
+  if (error61 instanceof CliRuntimeError) {
+    return {
+      code: error61.code,
+      message: error61.message,
+      ...error61.details === undefined ? {} : { details: error61.details },
+      ...error61.requestId === undefined ? {} : { requestId: error61.requestId }
+    };
+  }
+  if (isNetworkError(error61)) {
+    return {
+      code: "NETWORK",
+      message: error61 instanceof Error ? error61.message : "The Budget Builder API could not be reached."
+    };
+  }
+  if (isRecord(error61)) {
+    const data = isRecord(error61.data) ? error61.data : undefined;
+    const transportCode = mapErrorCode(data?.code ?? error61.code);
+    if (error61 instanceof Error && data === undefined && transportCode === undefined) {
+      return { code: "INTERNAL", message: error61.message };
+    }
+    const code = transportCode ?? "API";
+    const message = asNonEmptyString(error61.message) ?? "The Budget Builder API request failed.";
+    const requestId = asNonEmptyString(data?.requestId) ?? asNonEmptyString(data?.requestID) ?? asNonEmptyString(error61.requestId);
+    const details = asDetails(data?.details ?? error61.details);
+    return {
+      code,
+      message,
+      ...details === undefined ? {} : { details },
+      ...requestId === undefined ? {} : { requestId }
+    };
+  }
+  if (error61 instanceof Error) {
+    return { code: "INTERNAL", message: error61.message };
+  }
+  return { code: "INTERNAL", message: "An unexpected CLI error occurred." };
+};
+var exitCodeForCliError = (error61) => {
+  if (error61.code === "INTERRUPTED")
+    return 130;
+  return invocationErrorCodes.has(error61.code) ? 2 : 1;
+};
+
 // src/parse-mutation-payload.ts
 function requireObject(raw, label) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
@@ -20547,12 +20677,42 @@ function parseUpdateBillPaymentEvidencePayload(raw) {
   requireObject(raw, "update-bill-payment-evidence payload");
   return raw;
 }
+var validateQuotationAllocations = (raw, command) => {
+  const input2 = requireObject(raw, `${command} payload`);
+  const ids = input2.budgetItemIds;
+  if (!Array.isArray(ids) || ids.length === 0 || ids.some((id) => typeof id !== "string" || id.length === 0) || new Set(ids).size !== ids.length) {
+    throw new CliRuntimeError("VALIDATION", `${command} payload.budgetItemIds must contain each selected budget-item ID exactly once.`);
+  }
+  const isCurrency = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 99999999.99 && Math.abs(value * 100 - Math.round(value * 100)) < 0.00000001;
+  if (!isCurrency(input2.amountWithoutGst) || input2.amountWithoutGst === 0 || !isCurrency(input2.gstAmount)) {
+    throw new CliRuntimeError("VALIDATION", `${command} requires a positive payload.amountWithoutGst and a non-negative payload.gstAmount, in currency units with at most two decimal places. Use gstAmount: 0 for no GST.`);
+  }
+  const guidance = `${command} requires payload.lineAmounts as [{"budgetItemId":"<first-id>","amount":750},{"budgetItemId":"<second-id>","amount":450}] for multiple budget items. Include each payload.budgetItemIds entry exactly once, with non-negative amounts before GST summing to payload.amountWithoutGst. For a 1200 quotation with no GST, use line amounts 750 and 450, amountWithoutGst: 1200, gstAmount: 0.`;
+  if (input2.lineAmounts === undefined && ids.length === 1)
+    return;
+  if (!Array.isArray(input2.lineAmounts) || input2.lineAmounts.length !== ids.length) {
+    throw new CliRuntimeError("VALIDATION", guidance);
+  }
+  const seen = new Set;
+  let totalCents = 0;
+  for (const rawLine of input2.lineAmounts) {
+    const line = requireObject(rawLine, `${command} payload.lineAmounts entry`);
+    if (typeof line.budgetItemId !== "string" || !ids.includes(line.budgetItemId) || seen.has(line.budgetItemId) || !isCurrency(line.amount)) {
+      throw new CliRuntimeError("VALIDATION", guidance);
+    }
+    seen.add(line.budgetItemId);
+    totalCents += Math.round(line.amount * 100);
+  }
+  if (totalCents !== Math.round(input2.amountWithoutGst * 100)) {
+    throw new CliRuntimeError("VALIDATION", guidance);
+  }
+};
 function parseCreateQuotationPayload(raw) {
-  requireObject(raw, "create-quotation payload");
+  validateQuotationAllocations(raw, "create-quotation");
   return raw;
 }
 function parseUpdateQuotationPayload(raw) {
-  requireObject(raw, "update-quotation payload");
+  validateQuotationAllocations(raw, "update-quotation");
   return raw;
 }
 function parseCreateCustomerInvoicePayload(raw) {
@@ -20663,138 +20823,6 @@ function parseCompanyUpdatePayload(raw) {
   return raw;
 }
 
-// src/runtime/error.ts
-var invocationErrorCodes = new Set([
-  "USAGE",
-  "VALIDATION",
-  "CONFIRMATION_REQUIRED"
-]);
-var trpcCodeMap = {
-  BAD_REQUEST: "VALIDATION",
-  CONFLICT: "CONFLICT",
-  FORBIDDEN: "AUTHORIZATION",
-  INTERNAL_SERVER_ERROR: "API",
-  METHOD_NOT_SUPPORTED: "API",
-  NOT_FOUND: "NOT_FOUND",
-  PARSE_ERROR: "VALIDATION",
-  PAYLOAD_TOO_LARGE: "VALIDATION",
-  PRECONDITION_FAILED: "CONFLICT",
-  TIMEOUT: "NETWORK",
-  TOO_MANY_REQUESTS: "API",
-  UNAUTHORIZED: "AUTHENTICATION",
-  UNPROCESSABLE_CONTENT: "VALIDATION"
-};
-var cliErrorCodes = new Set([
-  "USAGE",
-  "VALIDATION",
-  "CONFIRMATION_REQUIRED",
-  "AUTHENTICATION",
-  "AUTHORIZATION",
-  "NOT_FOUND",
-  "CONFLICT",
-  "API",
-  "NETWORK",
-  "ABORTED",
-  "INTERRUPTED",
-  "INTERNAL"
-]);
-
-class CliRuntimeError extends Error {
-  code;
-  details;
-  requestId;
-  constructor(code, message, options = {}) {
-    super(message);
-    this.name = "CliRuntimeError";
-    this.code = code;
-    this.details = options.details;
-    this.requestId = options.requestId;
-  }
-}
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var asNonEmptyString = (value) => typeof value === "string" && value.trim() !== "" ? value : undefined;
-var asDetails = (value) => {
-  if (!isRecord(value))
-    return;
-  const details = {};
-  for (const [key, nestedValue] of Object.entries(value)) {
-    if (isJsonValue(nestedValue))
-      details[key] = nestedValue;
-  }
-  return Object.keys(details).length > 0 ? details : undefined;
-};
-var isJsonValue = (value) => {
-  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") {
-    return true;
-  }
-  if (Array.isArray(value))
-    return value.every(isJsonValue);
-  return isRecord(value) && Object.values(value).every(isJsonValue);
-};
-var mapErrorCode = (value) => {
-  if (typeof value !== "string")
-    return;
-  if (cliErrorCodes.has(value))
-    return value;
-  if (value in trpcCodeMap)
-    return trpcCodeMap[value];
-  return;
-};
-var networkMessagePattern = /\b(fetch failed|network error|unable to connect|econnrefused|econnreset|enotfound|etimedout|socket hang up)\b/i;
-var isNetworkError = (error61, depth = 0) => {
-  if (depth > 3 || !isRecord(error61))
-    return false;
-  const message = asNonEmptyString(error61.message);
-  if (message !== undefined && networkMessagePattern.test(message))
-    return true;
-  const code = asNonEmptyString(error61.code);
-  if (code !== undefined && networkMessagePattern.test(code))
-    return true;
-  return isNetworkError(error61.cause, depth + 1);
-};
-var normalizeCliError = (error61) => {
-  if (error61 instanceof CliRuntimeError) {
-    return {
-      code: error61.code,
-      message: error61.message,
-      ...error61.details === undefined ? {} : { details: error61.details },
-      ...error61.requestId === undefined ? {} : { requestId: error61.requestId }
-    };
-  }
-  if (isNetworkError(error61)) {
-    return {
-      code: "NETWORK",
-      message: error61 instanceof Error ? error61.message : "The Budget Builder API could not be reached."
-    };
-  }
-  if (isRecord(error61)) {
-    const data = isRecord(error61.data) ? error61.data : undefined;
-    const transportCode = mapErrorCode(data?.code ?? error61.code);
-    if (error61 instanceof Error && data === undefined && transportCode === undefined) {
-      return { code: "INTERNAL", message: error61.message };
-    }
-    const code = transportCode ?? "API";
-    const message = asNonEmptyString(error61.message) ?? "The Budget Builder API request failed.";
-    const requestId = asNonEmptyString(data?.requestId) ?? asNonEmptyString(data?.requestID) ?? asNonEmptyString(error61.requestId);
-    const details = asDetails(data?.details ?? error61.details);
-    return {
-      code,
-      message,
-      ...details === undefined ? {} : { details },
-      ...requestId === undefined ? {} : { requestId }
-    };
-  }
-  if (error61 instanceof Error) {
-    return { code: "INTERNAL", message: error61.message };
-  }
-  return { code: "INTERNAL", message: "An unexpected CLI error occurred." };
-};
-var exitCodeForCliError = (error61) => {
-  if (error61.code === "INTERRUPTED")
-    return 130;
-  return invocationErrorCodes.has(error61.code) ? 2 : 1;
-};
-
 // src/runtime/confirmation.ts
 var effectLabels = {
   "state-change": "changes Budget Builder state",
@@ -22790,6 +22818,12 @@ async function createCompany(opts) {
   const result = await api2.company.createCompany.mutate(opts);
   out(result);
 }
+var searchExistingCompanies = async (query, page = 1) => {
+  out(await api2.company.searchExistingCompanies.query({ query, page }));
+};
+var reuseExistingCompany = async (input2) => {
+  out(await api2.company.useExistingCompany.mutate(input2));
+};
 async function listProjects(opts) {
   const result = await api2.project.getAllProjects.query({
     companyId: opts.companyId,
@@ -23308,6 +23342,7 @@ var mutationPrefixes = [
   "submit-",
   "sync-",
   "update-",
+  "use-existing-",
   "upload-",
   "void-"
 ];
@@ -23338,6 +23373,7 @@ var externalWriteTargets = new Set([
   "complete-project",
   "create-bill",
   "create-company",
+  "use-existing-company",
   "create-estimate",
   "create-placeholder-bill",
   "create-customer-invoice",
@@ -23435,6 +23471,12 @@ var effectsFor = (legacyTarget) => {
 };
 var titleCase = (value) => value.split("-").map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(" ");
 var summaryFor = (legacyTarget) => {
+  if (legacyTarget === "search-existing-companies")
+    return "Search BB and QuickBooks companies without writes. --query <name> [--page <number>].";
+  if (legacyTarget === "use-existing-company")
+    return "Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.";
+  if (legacyTarget === "create-company")
+    return "Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.";
   if (legacyTarget === "preview-qbo-customer-invoice") {
     return "Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.";
   }
@@ -23453,10 +23495,10 @@ var summaryFor = (legacyTarget) => {
     return "Validate the approved supplier and selected bill line items.";
   }
   if (legacyTarget === "create-quotation") {
-    return "Create a quotation with an approved supplier.";
+    return 'Create a quotation with an approved supplier using --payload JSON. Include projectId, budgetId, supplierId, budgetItemIds, amountWithoutGst, gstAmount, and one uploaded attachment in attachments. Multiple budget items require lineAmounts: [{"budgetItemId":"<first-id>","amount":750},{"budgetItemId":"<second-id>","amount":450}], covering every selected budget-item ID exactly once and summing to amountWithoutGst. Amounts exclude GST; use gstAmount: 0 for no GST. Example: amountWithoutGst: 1200 with line amounts 750 and 450.';
   }
   if (legacyTarget === "update-quotation") {
-    return "Update a quotation with an approved supplier.";
+    return '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.';
   }
   if (legacyTarget === "download-customer-invoice-pdf") {
     return "Download a customer invoice PDF when permitted.";
@@ -23628,8 +23670,20 @@ var registry2 = [
     "staged",
     "cleanup"
   ]),
-  legacyCommand("create-quotation", ["quotation", "create"]),
-  legacyCommand("update-quotation", ["quotation", "update"]),
+  legacyCommand("create-quotation", ["quotation", "create"], [], [
+    {
+      name: "--payload",
+      description: "Quotation JSON including lineAmounts for multiple selected budget items; see the payload format above.",
+      required: true
+    }
+  ]),
+  legacyCommand("update-quotation", ["quotation", "update"], [], [
+    {
+      name: "--payload",
+      description: "Complete quotation JSON plus id, including lineAmounts for multiple selected budget items.",
+      required: true
+    }
+  ]),
   legacyCommand("delete-quotation", ["quotation", "delete"]),
   legacyCommand("submit-quotation", ["quotation", "submit"]),
   legacyCommand("approve-quotation", ["quotation", "approve"]),
@@ -23686,7 +23740,40 @@ var registry2 = [
   legacyCommand("get-supplier-details", ["supplier", "detail", "get"]),
   legacyCommand("list-companies", ["company", "list"]),
   legacyCommand("get-company", ["company", "get"]),
-  legacyCommand("create-company", ["company", "create"]),
+  legacyCommand("search-existing-companies", ["company", "search"], [], [
+    {
+      name: "--query",
+      description: "Company name to search in BB and QuickBooks."
+    },
+    {
+      name: "--page",
+      description: "Results page (eight companies per page)."
+    }
+  ]),
+  legacyCommand("use-existing-company", ["company", "use"], [], [
+    {
+      name: "--companyId",
+      description: "Existing BB company ID; combine with quickbooksId to explicitly connect both records."
+    },
+    {
+      name: "--quickbooksId",
+      description: "Existing QBO customer ID; alone imports or reuses its BB company."
+    },
+    {
+      name: "--website",
+      description: "Website only when missing from a QBO-only import."
+    },
+    {
+      name: "--confirmDistinct",
+      description: "Set true only when similar records do not represent this legal entity."
+    }
+  ]),
+  legacyCommand("create-company", ["company", "create"], [], [
+    {
+      name: "--confirmDistinct",
+      description: "Set true to confirm a separate legal entity despite similar names."
+    }
+  ]),
   legacyCommand("update-company", ["company", "update"]),
   legacyCommand("delete-company", ["company", "delete"]),
   legacyCommand("list-projects", ["project", "list"]),
@@ -23877,12 +23964,28 @@ var resolveCommand = (argv) => {
     isLegacyAlias: true
   };
 };
-var createHumanHelp = () => {
-  const lines = commandRegistry.map((command) => {
-    const canonical = `bb ${command.path.join(" ")}`;
-    const aliases = command.legacyAliases.filter((alias) => alias.includes("-")).map((alias) => `bb ${alias}`).join(", ");
+var createHumanHelp = (command) => {
+  if (command) {
+    return [
+      `Usage: bb ${command.path.join(" ")} [options] [args]`,
+      "",
+      command.summary,
+      "",
+      `Legacy aliases: ${command.legacyAliases.join(", ")}`,
+      "",
+      "Options",
+      ...command.options.map((option) => `  ${option.name}
+    ${option.description}`),
+      "",
+      "Use `bb help --legacy` for additional command arguments."
+    ].join(`
+`);
+  }
+  const lines = commandRegistry.map((command2) => {
+    const canonical = `bb ${command2.path.join(" ")}`;
+    const aliases = command2.legacyAliases.filter((alias) => alias.includes("-")).map((alias) => `bb ${alias}`).join(", ");
     return `  ${canonical}
-    ${command.summary}${aliases ? ` Legacy: ${aliases}.` : ""}`;
+    ${command2.summary}${aliases ? ` Legacy: ${aliases}.` : ""}`;
   });
   return [
     "bb \u2014 Budget Builder CLI",
@@ -24167,8 +24270,8 @@ Quotations
   get-quotation <quotationId>
   upload-quotation-attachment <projectId> <filePath>   Upload one PDF, JPEG, or PNG up to 20MB; returns attachment JSON for a quotation payload.
   cleanup-staged-quotation-attachments <projectId> --keys <csv>   Delete unattached staged quotation uploads.
-  create-quotation           --payload '<json>'  (quotation.createDraft; requires amountWithoutGst and gstAmount)
-  update-quotation           --payload '<json>'  Update a DRAFT or REJECTED quotation; same payload plus id.
+  create-quotation           --payload '<json>'  (quotation.createDraft; requires amountWithoutGst, gstAmount, and lineAmounts [{budgetItemId, amount}] for multiple budgetItemIds; amounts before GST must sum to amountWithoutGst)
+  update-quotation           --payload '<json>'  Update a DRAFT or REJECTED quotation; same allocation payload plus id; use lineAmounts [{budgetItemId, amount}] for every selected item.
   delete-quotation <quotationId>
   submit-quotation <quotationId> [--overBudgetOverrideReason <text>]
   approve-quotation <quotationId> [--overBudgetOverrideReason <text>]
@@ -24207,7 +24310,12 @@ Companies & projects
   list-companies             [--name] [--createdBy] [--active true|false] [--page] [--perPage]
     Omit --active to include both active and inactive companies.
   get-company <id>
-  create-company             --name --website <url>
+  search-existing-companies  --query <name> [--page] (BB + QuickBooks, read-only)
+  use-existing-company      --companyId <bbId> and/or --quickbooksId <qboId> [--website <url>] [--confirmDistinct true]
+    Supply both IDs to explicitly connect existing records with different names.
+    Reuses both records, creating only the missing counterpart. Website is needed only for a QBO import without one.
+  create-company             --name --website <url> [--confirmDistinct true]
+    Exact existing companies are reused. Similar names require explicit separate-entity confirmation.
   update-company             --payload '<json>'  (company.updateCompany; must include id, name, website)
   delete-company <id>
   list-projects              [--companyId] [--name] [--status] [--active true|false] [--page] [--perPage]
@@ -24443,7 +24551,9 @@ async function runCli(argv = process.argv, runtime2 = createProcessRuntime(), cr
     if (commandArgv.includes("--legacy")) {
       printLegacyHelp(runtime2);
     } else {
-      runtime2.stdout.write(`${createHumanHelp()}
+      const helpArgv = commandArgv.filter((argument, index) => argument !== "-h" && argument !== "--help" && !argument.startsWith("--help=") && !(commandArgv[index - 1] === "--help" && booleanFlagValues.has(argument)));
+      const helpCommand = resolveCommand(helpArgv[0] === "help" ? helpArgv.slice(1) : helpArgv)?.command;
+      runtime2.stdout.write(`${createHumanHelp(helpCommand)}
 `);
     }
     return 0;
@@ -25593,7 +25703,39 @@ Waiting for approval\u2026
         if (!name || !website) {
           throw new Error("create-company requires --name and --website <url>");
         }
-        await createCompany({ name, website });
+        await createCompany({
+          name,
+          website,
+          confirmDistinct: parseOptionalBoolFlag(flags, "confirmDistinct")
+        });
+        break;
+      }
+      case "search-existing-companies": {
+        const query = getFlag(flags, "query");
+        if (!query)
+          throw new Error("search-existing-companies requires --query <name>");
+        await searchExistingCompanies(query, parsePositiveIntFlag(getFlag(flags, "page"), "--page"));
+        break;
+      }
+      case "use-existing-company": {
+        const companyId = getFlag(flags, "companyId");
+        const quickbooksId = getFlag(flags, "quickbooksId");
+        if (!companyId && !quickbooksId)
+          throw new Error("Supply --companyId and/or --quickbooksId");
+        if (companyId)
+          await reuseExistingCompany({
+            source: "bb",
+            companyId,
+            quickbooksId,
+            confirmDistinct: parseOptionalBoolFlag(flags, "confirmDistinct")
+          });
+        else if (quickbooksId)
+          await reuseExistingCompany({
+            source: "qbo",
+            quickbooksId,
+            website: getFlag(flags, "website"),
+            confirmDistinct: parseOptionalBoolFlag(flags, "confirmDistinct")
+          });
         break;
       }
       case "update-company": {

package/package.json

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

@@ -134,6 +134,46 @@ The following distinctions are especially important:
 - Ordinary unpaid creation does not require `--allow-email`, but remains role-dependent: Accounting auto-checks and Admin auto-approves. It still requires `--allow-external-write`, including for possible placeholder adjustments. Already-paid creation retains the email gate.
 - Staged attachments belong to the user in the database. Do not reuse, share, or manually construct staged keys.
 
+## Creating and updating quotations
+
+Quotation payloads keep the supplier subtotal and GST in separate fields: `amountWithoutGst` is the subtotal and `gstAmount` is GST. For a multi-line quotation, `lineAmounts` is required and must list every selected budget item exactly once; its amounts must add up to `amountWithoutGst`. Read the budget first and copy the actual `budgetItemIds` returned by Budget Builder. Never substitute item names, invented IDs, or IDs from another budget or project.
+
+`quotationAllocations` is a bill-side source allocation. Use it when creating or updating a supplier bill to record which approved quotations fund bill lines. Do not put `quotationAllocations` in a quotation create/update payload.
+
+Upload one quotation file with `bb quotation attachment upload <project-id> <file-path>`, then pass the one returned attachment object in the quotation payload's one-element `attachments` array. The create and update procedures require that single original quotation attachment.
+
+Replace the example attachment size `12345` with the actual byte count from the upload response.
+
+Use this complete placeholder shape for a quotation with S$750 on one real budget line and S$450 on another (S$1,200 subtotal, S$0 GST):
+
+```bash
+bb quotation attachment upload "<project-id>" "<quotation-file.pdf>"
+
+# Replace every <...> placeholder with values from the budget read or upload response.
+bb quotation create --payload '{
+  "projectId": "<project-id>",
+  "budgetId": "<budget-id>",
+  "supplierId": "<supplier-id>",
+  "budgetItemIds": ["<budget-item-id-for-750>", "<budget-item-id-for-450>"],
+  "lineAmounts": [
+    {"budgetItemId": "<budget-item-id-for-750>", "amount": 750},
+    {"budgetItemId": "<budget-item-id-for-450>", "amount": 450}
+  ],
+  "amountWithoutGst": 1200,
+  "gstAmount": 0,
+  "attachments": [
+    {
+      "id": "<attachment-id-from-upload>",
+      "name": "<attachment-name-from-upload>",
+      "key": "<attachment-key-from-upload>",
+      "size": 12345
+    }
+  ]
+}'
+```
+
+For an update, use the same shape with `"id": "<quotation-id>"` and the existing quotation's editable status. The numeric example is documentation-only; it contains no live resource IDs. Report the quotation subtotal, GST, and total separately after reading the result.
+
 ## Bill amounts: always identify the subtotal before writing
 
 For bill creation (including `--draft-only`) and updates, `amount`, `extractedAmount`, `lineAmounts[].amount`, and `quotationAllocations[].amount` all **exclude GST**. The CLI does not strip GST from a supplied total. BB calculates applicable GST separately from the supplier and line settings.