@go-labs-sg/bb 2.33.0 → 2.33.2

package/README.md

@@ -232,6 +232,36 @@ Every canonical command is classified by effect: `state-change`, `email`, `exter
 
 **Draft-only bills:** Use `bb bill create --draft-only --payload '<bill-json>' --allow-state-change --allow-financial-write` when the user authorizes a draft only. The equivalent payload field is `draftOnly: true`. This creates `DRAFT` for every role, without auto-checking, auto-approval, approval requests, emails, or QuickBooks writes. It cannot be combined with `alreadyPaid: true`; conflicting flag and payload values are rejected. Draft-only creation uses the dedicated `bill.createDraft` API route and fails on older servers without falling back to ordinary creation. Deploy backend support before releasing the updated CLI. Reconciled projects must be moved to Won separately before draft-only creation, because reopening a project can trigger external integrations. Completed projects retain their existing creation restriction.
 
+### Bill amounts and GST (create and update)
+
+**All bill amount fields below exclude GST.** This applies to ordinary creation, draft-only creation, and updates. The CLI does not convert a GST-inclusive invoice total into a subtotal. BB calculates applicable GST separately using the supplier's GST registration and each line's out-of-scope setting.
+
+| Payload field | Meaning |
+| --- | --- |
+| `amount` | Amount being billed now, **before GST**. For a deposit or partial bill, use only the portion being billed. |
+| `extractedAmount` | Full supplier invoice amount **before GST**, as shown on the attachment. For a partial bill, this can exceed `amount`. |
+| `lineAmounts[].amount` | This bill's allocation to each selected budget item, **before GST**. The entries must sum to `amount`. |
+| `quotationAllocations[].amount` | Quotation coverage for each bill line, **before GST**. Use the same tax basis as `lineAmounts`. |
+
+For an invoice showing **S$1,800 subtotal + S$162 GST = S$1,962 total**, a full bill uses the following amount fields (fragment only; include the other required bill fields):
+
+```json
+{
+  "amount": 1800,
+  "extractedAmount": 1800,
+  "lineAmounts": [{ "budgetItemId": "item-a", "amount": 1800 }],
+  "quotationAllocations": [
+    { "budgetItemId": "item-a", "quotationId": "quote-a", "amount": 1800 }
+  ]
+}
+```
+
+Do **not** put `1962` in either `amount` or `extractedAmount` for this full bill: BB would treat it as a before-GST value. A 50% partial bill against the same invoice uses `amount: 900`, `extractedAmount: 1800`, and line/quotation allocations totaling `900`; with 9% GST applicable to that line, its total is S$981.
+
+Use the invoice's actual subtotal and tax breakdown. Do not blindly divide every invoice total by 1.09: non-GST-registered suppliers, out-of-scope lines, and mixed-tax invoices need their actual breakdown. If the attachment does not establish the before-GST amount, clarify it before creating or updating the bill.
+
+After a mutation, re-read the bill and verify `amount`, `extractedAmount`, line amounts, and quotation allocations against the attachment. Report the subtotal, GST, and total separately; do not describe the stored `amount` as the GST-inclusive total. When correcting a gross/net input mistake, also check `extractedAmount` so the full invoice is not accidentally represented as a partial bill.
+
 **Quotation-first supplier bills:** Use `quotationIds` when approved quotations cover disjoint bill lines. When two quotations fund the same bill line, pass `quotationAllocations` entries with `{ budgetItemId, quotationId, amount }` and an exact `lineAmounts` entry for every selected budget item; `lineAmounts` must sum to the bill amount. Canonical allocation rows are the stored source of every bill-line quotation relationship. A required zero-value bill line needs one or more allocations with `amount: 0`, which record its approved source(s) without consuming quotation capacity. Every quotation must belong to the bill supplier and project and cover the allocated budget item. Legacy `quotationId` remains valid as single-quotation input and maps to the current selection. Supplier bills that qualify for an existing exemption must state that intent with `--quotation-exempt`. Claims share budget allowance but never consume or link quotations, so quotation source fields are rejected for claims.
 
 Every selected bill or claim line must belong to an active budget in `ESTIMATE_ACCEPTED` or `ESTIMATE_CLOSED`, including lines drawn from additional budgets in the project. The server checks this during selection, creation, editing, and approval. An unaccepted budget never qualifies a line for a quotation exemption. Existing pending bills expose budget and source-link blockers in `commitmentReview.blockers`.
@@ -256,6 +286,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).
@@ -327,8 +399,8 @@ Bill, claim, and quotation mutations accept only suppliers whose approval status
 | Area | Legacy handler labels (reference only; non-exhaustive) |
 | --- | --- |
 | **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`; 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 `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), `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`) |
+| **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `validate-bill-selection` (`--payload`, plus `--quotationIds q1,q2` or legacy `--quotationId q1`; validates the approved supplier and quotation coverage), `link-bill-quotations` (`<billId> --quotationIds q1,q2`; Admin source-link repair for eligible supplier bills), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON; ownership and one-hour expiry are enforced by a server-side staged-upload record rather than encoded in the object key), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill and provide approved `quotationIds`, or use `--quotation-exempt` for an eligible server-validated exemption; set `isClaimable=true` for a claim without quotations; supplier bills require positive **before-GST** `extractedAmount` (full invoice subtotal) and `amount` (portion billed), with `amount <= extractedAmount`; line and quotation allocation amounts also exclude GST; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`; admin creation automatically queues QBO finalization while other roles remain pending approval), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (`PAID` requires `--paymentReference`; pass `--paymentProof <receipt.pdf>` to stage and submit a PDF up to 20MB atomically, or omit it only when BB already has payment proof; moving to `PAID` runs the server's paid-bill notification workflow), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
+| **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst`, `gstAmount`, and `lineAmounts` entries `{ budgetItemId, amount }` for multiple selected items), `update-quotation` (`--payload`; updates a `DRAFT` or `REJECTED` quotation), `delete-quotation`, `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
 | **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `list-customer-invoices` (global/project/budget filters plus summary metrics; `--sortBy totalInvoiceAmount` sorts provider-confirmed totals including GST, with unknown amounts last), `get-customer-invoice`, `get-customer-invoice-email-context`, `preview-qbo-customer-invoice`, `import-qbo-customer-invoice` (BB-only link with reviewed token), `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
 | **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

@@ -2063,7 +2063,7 @@
 	{
 		"path": ["bill", "create"],
 		"legacyAliases": ["create-bill", "create_bill"],
-		"summary": "Create a bill or claim with an approved supplier. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.",
+		"summary": "Create a bill or claim with an approved supplier. 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. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2237,7 +2237,7 @@
 	{
 		"path": ["bill", "update"],
 		"legacyAliases": ["update-bill", "update_bill"],
-		"summary": "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.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -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",

package/command-reference.md

@@ -347,7 +347,7 @@ Effects: state-change, email.
 
 ## `bb bill create`
 
-Create a bill or claim with an approved supplier. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.
+Create a bill or claim with an approved supplier. 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. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.
 
 Legacy aliases: `create-bill`, `create_bill`.
 
@@ -371,7 +371,7 @@ Effects: state-change, financial-write.
 
 ## `bb bill update`
 
-Update Bill.
+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.
 
 Legacy aliases: `update-bill`, `update_bill`.
 
@@ -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`.
 

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",
@@ -23444,16 +23472,19 @@ var summaryFor = (legacyTarget) => {
   if (legacyTarget === "whoami")
     return "Show the active API-key identity.";
   if (legacyTarget === "create-bill") {
-    return "Create a bill or claim with an approved supplier. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
+    return "Create a bill or claim with an approved supplier. 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. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
+  }
+  if (legacyTarget === "update-bill") {
+    return "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.";
   }
   if (legacyTarget === "validate-bill-selection") {
     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.";
@@ -23625,8 +23656,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"]),
@@ -23874,12 +23917,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",
@@ -24134,6 +24193,8 @@ Bills
   list-claims                same flags as list-bills; only reimbursable claims (ignores --isClaimable)
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
   Create supplier bills from approved quotations from the same supplier and project. Use quotationAllocations plus lineAmounts when quotations split one bill line. Eligible exemptions require explicit --quotation-exempt intent; claims do not consume or link quotations.
+  Amounts for create/update (including drafts) exclude GST: amount = portion billed; extractedAmount = full invoice subtotal; lineAmounts[].amount and quotationAllocations[].amount also exclude GST. The CLI does not strip GST from input.
+  Example: invoice subtotal 1800 + GST 162 = total 1962 -> amount: 1800, extractedAmount: 1800, allocations totaling 1800. BB calculates applicable GST separately. Re-read and verify both amount fields after writing.
   create-bill-approval <billId>       (also queues approval request emails)
   create-bill                --payload '<json>' [--draft-only] [--quotation-exempt]  (bill.create; supplier bills use payload.quotationAllocations for split sources or quotationIds for disjoint coverage; explicit allocations require lineAmounts; claims reject quotation sources)
   validate-bill-selection    --payload '<json>' [--quotationIds <csv> | --quotationId <id>]  Validate an approved supplier and approved quotation coverage for each supplier-bill line. --quotationId is legacy single-quotation syntax.
@@ -24162,8 +24223,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>]
@@ -24438,7 +24499,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.33.0",
+  "version": "2.33.2",
   "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,58 @@ 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.
+
+- `amount` is the portion being billed now; `extractedAmount` is the full invoice subtotal before GST. They are equal for a full bill and may differ for a deposit or partial bill.
+- Example: an invoice for **S$1,800 + S$162 GST = S$1,962** requires `amount: 1800` and `extractedAmount: 1800` for a full bill, with line/quotation allocations totaling `1800`. Entering `1962` as the bill amount charges GST again.
+- Read the attachment's actual subtotal and tax breakdown. Do not assume every invoice includes 9% GST or blindly divide all totals by 1.09. Clarify missing or ambiguous tax information before writing.
+- After creation or correction, re-read the bill and verify both amount fields and the line/quotation allocations. Correcting only `amount` can leave an incorrect `extractedAmount` suggesting a partial bill.
+- Report **subtotal, GST, and total separately**. Keep the original invoice attachment as evidence; recording GST only in a comment does not correct the structured amount fields.
+
+See [Bill amounts and GST](README.md#bill-amounts-and-gst-create-and-update) for payload and partial-bill examples.
+
 ## Handling authorization failures
 
 On `FORBIDDEN`: