@go-labs-sg/bb 2.29.0 → 2.31.0

package/README.md

@@ -230,6 +230,10 @@ commands return a conflict until delivery becomes `SENT` or `FAILED`.
 
 Every canonical command is classified by effect: `state-change`, `email`, `external-write`, `delete`, and/or `financial-write`. Interactive runs require one exact `CONFIRM`. Non-interactive runs require the corresponding flags (`--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and `--allow-financial-write`); commands with multiple effects require every matching flag. Agents must still get user confirmation in chat first—the runtime gate is not user authorization.
 
+**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 creation determines its required permissions from the parsed input, for both canonical and legacy commands. Ordinary unpaid creation requires state-change, financial-write, and external-write permissions, but no email permission. Already-paid creation also requires email permission. Without draft-only mode, existing role behavior remains: ordinary users create drafts, Accounting creates checked bills, and Admin creates approved bills and writes to QuickBooks. Ordinary creation can also adjust existing QuickBooks placeholder bills. Explicit drafts defer those adjustments until the later approval/QuickBooks workflow. When later authorized to submit the draft, use `bb bill approval create <billId>` with its state-change and email permissions; Admin-created drafts also enter finance review through this command. The static command catalog lists the union of possible effects.
+
 **Approval email exclusions:** Approval requests create pending database records for every eligible approver, including configured non-recipient admin accounts. Automated approval-request emails skip those accounts.
 
 **Locked estimate budget changes:** Legacy flat commands retain their additional interactive `yes` prompt when the current budget is locked. Canonical v2 commands use the single effect-aware confirmation gate; non-interactive execution requires `--allow-state-change` plus any other effects declared for that command.
@@ -281,7 +285,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`; validates the project and supplier separately, then checks approved quotation links for each selected budget line item independent of the bill supplier; `alreadyPaid` never bypasses the checks), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON; ownership and one-hour expiry are enforced by a server-side staged-upload record rather than encoded in the object key), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill, `isClaimable=true` for a claim; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`; admin creation automatically queues QBO finalization while other roles remain pending approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage linked to every selected line item, independent of the bill supplier, even when already paid), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (`PAID` requires `--paymentReference`; pass `--paymentProof <receipt.pdf>` to stage and submit a PDF up to 20MB atomically, or omit it only when BB already has payment proof; moving to `PAID` runs the server's paid-bill notification workflow), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
 | **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` and `gstAmount`), `update-quotation` (`--payload`; updates a `DRAFT` or `REJECTED` quotation), `delete-quotation`, `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
-| **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `list-customer-invoices` (global/project/budget filters plus summary metrics), `get-customer-invoice`, `get-customer-invoice-email-context`, `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
+| **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`, `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
 | **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|customer_invoice\|all`), `approve-bill` / `reject-bill` (send reply email), `approve-budget` / `reject-budget` (send reply email), `approve-supplier` / `reject-supplier` (send reply email), `approve-quotation` / `reject-quotation`, `approve-customer-invoice` / `reject-customer-invoice` |
 | **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project` (its budget overview returns `totalRevenue`, calculated only from Estimate Accepted and Estimate Closed budgets), `get-project-hub-status`, `setup-project-hub`, `sync-project-hub-commercial-documents`, `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--startDate` as ISO datetime for project/window start; when `--asanaTaskId` is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional `--asanaSearch`, `--pax`, `--endDate`, `--description`, `--projectManagerId`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `projectManagerId` and `requestQboAccountantNotification` in JSON), `delete-project`, `check-project-reconciliation <id>` (runs the web app's live checks without changing status), `reconcile-project <id>` (reruns checks transactionally and marks an eligible project `RECONCILED`), `complete-project <id>` (reruns validation, marks a reconciled project `COMPLETED`, and queues QuickBooks placeholder cleanup), `import-qbo-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `RECONCILED` \| `LOST`; close-out follows `WON` → `RECONCILED` → `COMPLETED`, and reconciliation requires every accepted/closed budget line to have an Approved/Paid bill or claim or be explicitly Not Utilized; marking `COMPLETED` queues deletion of every remaining project placeholder bill from QuickBooks; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
 | **Contacts** | `list-contacts`, `create-contact-person` (`--payload`), `update-contact-person` (`--payload`) |
@@ -345,3 +349,15 @@ The list also accepts `PARTIALLY_SENT`, `PARTIALLY_PAID`, `PAID`, and `VOIDED`,
 alongside existing approval states such as `APPROVED` and `PENDING_APPROVAL`.
 `--sortBy status` sorts by lifecycle; `lifecycleStatus` in list/detail output is
 separate from the stored approval/operational `status`.
+
+### Shared allowance decisions
+
+Quotation approval/submission and bill approval/status commands accept an optional
+`--overBudgetOverrideReason "<reason>"`. Bill create/update JSON payloads accept
+`overBudgetOverrideReason`. Only admins may override an assessed overrun; missing
+relationships or allocations block approval and require review. Multi-line quotation
+create/update payloads must include `lineAmounts` with `{ budgetItemId, amount }`
+for every selected line, summing to `amountWithoutGst`. The server revalidates
+existing quotation links, reviewed usage, and per-line allowance inside the
+approval transaction. No new database fields or relationship declarations are
+required; unresolved historical overlaps continue to block approval.

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.",
+		"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.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2104,6 +2104,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--draft-only",
+				"description": "Create a draft for every role; no approval, email, or QuickBooks writes. Conflicts with alreadyPaid: 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.
+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.
 
 Legacy aliases: `create-bill`, `create_bill`.
 

package/dist/index.js

@@ -20259,7 +20259,7 @@ var billAttachment = (x, i, field = "attachments") => {
     size: Number(a.size)
   };
 };
-function parseCreateBillPayload(raw) {
+function parseCreateBillPayload(raw, draftOnlyFlag) {
   const o = requireObject(raw, "create-bill payload");
   const isClaimable = o.isClaimable;
   if (typeof isClaimable !== "boolean") {
@@ -20271,7 +20271,18 @@ function parseCreateBillPayload(raw) {
   }
   const attachmentsRaw = o.attachments;
   const attachments = Array.isArray(attachmentsRaw) ? attachmentsRaw.map((x, i) => billAttachment(x, i)) : [];
+  const draftOnlyRaw = o.draftOnly;
+  if (draftOnlyRaw !== undefined && typeof draftOnlyRaw !== "boolean") {
+    throw new Error("create-bill payload.draftOnly must be boolean.");
+  }
+  if (draftOnlyFlag !== undefined && draftOnlyRaw !== undefined && draftOnlyFlag !== draftOnlyRaw) {
+    throw new Error("--draft-only conflicts with payload.draftOnly.");
+  }
+  const draftOnly = draftOnlyFlag ?? draftOnlyRaw;
   const alreadyPaidRaw = o.alreadyPaid;
+  if (draftOnly && alreadyPaidRaw === true) {
+    throw new Error("Draft-only creation cannot be combined with alreadyPaid: true.");
+  }
   if (alreadyPaidRaw !== undefined && alreadyPaidRaw !== null && typeof alreadyPaidRaw !== "boolean") {
     throw new Error("create-bill payload.alreadyPaid must be boolean.");
   }
@@ -20315,6 +20326,7 @@ function parseCreateBillPayload(raw) {
     isClaimable,
     attachments,
     alreadyPaid: alreadyPaidRaw ?? undefined,
+    draftOnly,
     paymentReference: optionalString(o.paymentReference),
     paymentProofAttachments,
     extractedSupplierName: optionalString(o.extractedSupplierName),
@@ -20327,8 +20339,12 @@ function parseCreateBillPayload(raw) {
 }
 function parseUpdateBillPayload(raw) {
   const o = requireObject(raw, "update-bill payload");
+  const { draftOnly, ...input2 } = parseCreateBillPayload(raw);
+  if (draftOnly !== undefined) {
+    throw new Error("draftOnly is only supported when creating a bill.");
+  }
   return {
-    ...parseCreateBillPayload(raw),
+    ...input2,
     id: requiredString(o.id, "update-bill payload.id")
   };
 }
@@ -21310,7 +21326,7 @@ async function listBills(opts) {
   const result = await api2.bill.getAll.query(input2);
   out(result);
 }
-async function approveBill(billId) {
+async function approveBill(billId, overBudgetOverrideReason) {
   await assertSensitiveWorkflowConfirmed({
     action: "Approve bill",
     entity: `bill ${billId}`,
@@ -21324,7 +21340,8 @@ async function approveBill(billId) {
   }
   const result = await api2.bill.updateApproval.mutate({
     billApprovalId: approval.id,
-    status: "APPROVED"
+    status: "APPROVED",
+    overBudgetOverrideReason
   });
   if (result.processing) {
     out(result);
@@ -21503,7 +21520,8 @@ async function updateBillStatus(opts) {
       rejectionReason: opts.rejectionReason,
       paymentTrackingUrl: opts.paymentTrackingUrl,
       paymentReference: opts.paymentReference,
-      paymentProofAttachments: paymentProof ? [paymentProof] : undefined
+      paymentProofAttachments: paymentProof ? [paymentProof] : undefined,
+      overBudgetOverrideReason: opts.overBudgetOverrideReason
     });
     out(result);
   } catch (error61) {
@@ -22030,9 +22048,24 @@ async function deleteItemCategoriesByIds(ids) {
   const result = await api2.itemCategory.deleteItemCategories.mutate({ ids });
   out(result);
 }
-async function createBillFromPayload(raw) {
-  const input2 = parseCreateBillPayload(raw);
-  const result = await api2.bill.create.mutate(input2);
+async function createBillFromPayload(raw, draftOnlyFlag) {
+  const input2 = parseCreateBillPayload(raw, draftOnlyFlag);
+  await confirmCurrentCommand({
+    action: input2.draftOnly ? "bill create (draft only)" : "bill create",
+    target: `project ${input2.projectId}, supplier ${input2.supplierId}`,
+    effects: [
+      "state-change",
+      "financial-write",
+      ...input2.draftOnly ? [] : ["external-write"],
+      ...input2.alreadyPaid ? ["email"] : []
+    ],
+    details: input2.draftOnly ? "Create a DRAFT bill without approval, email, or QuickBooks writes." : "Uses the caller's normal bill creation workflow; Accounting auto-checks and Admin auto-approves unpaid bills."
+  });
+  const result = input2.draftOnly ? await api2.bill.createDraft.mutate({
+    ...input2,
+    draftOnly: true,
+    alreadyPaid: false
+  }) : await api2.bill.create.mutate(input2);
   out(result);
 }
 async function listQuotations(opts) {
@@ -22057,12 +22090,15 @@ var deleteQuotationById = async (id) => {
   const result = await api2.quotation.delete.mutate({ id });
   out(result);
 };
-async function submitQuotation(id) {
+async function submitQuotation(id, overBudgetOverrideReason) {
   await assertSensitiveWorkflowConfirmed({
     action: "Submit quotation for approval",
     entity: `quotation ${id}`
   });
-  const result = await api2.quotation.submitForApproval.mutate({ id });
+  const result = await api2.quotation.submitForApproval.mutate({
+    id,
+    overBudgetOverrideReason
+  });
   out(result);
 }
 async function downloadQuotationPdf(id, fileRole) {
@@ -22492,7 +22528,7 @@ async function rejectBill(billId, reason) {
     email: email3
   });
 }
-async function approveQuotation(quotationId) {
+async function approveQuotation(quotationId, overBudgetOverrideReason) {
   await assertSensitiveWorkflowConfirmed({
     action: "Approve quotation",
     entity: `quotation ${quotationId}`
@@ -22504,7 +22540,8 @@ async function approveQuotation(quotationId) {
     throw new Error("No pending quotation approval found.");
   }
   const result = await api2.quotation.approve.mutate({
-    quotationApprovalId: approval.id
+    quotationApprovalId: approval.id,
+    overBudgetOverrideReason
   });
   out(result);
 }
@@ -23189,7 +23226,7 @@ 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.";
+    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.";
   }
   if (legacyTarget === "validate-bill-selection") {
     return "Validate the approved supplier and selected bill line items.";
@@ -23297,7 +23334,12 @@ var registry2 = [
   legacyCommand("list-bills", ["bill", "list"]),
   legacyCommand("list-claims", ["claim", "list"]),
   legacyCommand("create-bill-approval", ["bill", "approval", "create"]),
-  legacyCommand("create-bill", ["bill", "create"]),
+  legacyCommand("create-bill", ["bill", "create"], [], [
+    {
+      name: "--draft-only",
+      description: "Create a draft for every role; no approval, email, or QuickBooks writes. Conflicts with alreadyPaid: true."
+    }
+  ]),
   legacyCommand("validate-bill-selection", ["bill", "selection", "validate"]),
   legacyCommand("update-bill", ["bill", "update"]),
   legacyCommand("update-bill-payment-evidence", [
@@ -23675,6 +23717,7 @@ function parseOptionalBoolFlag(flags, key) {
 var CUSTOMER_INVOICE_SORT_FIELDS = [
   "createdAt",
   "status",
+  "totalInvoiceAmount",
   "totalNetAmount",
   "approvalExpiresAt"
 ];
@@ -23843,14 +23886,14 @@ Bills
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
   Non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage linked to every selected line item, independent of the bill supplier, including already-paid bills.
   create-bill-approval <billId>       (also queues approval request emails)
-  create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim; supplier must be APPROVED)
+  create-bill                --payload '<json>' [--draft-only]  (bill.create; payload.isClaimable false = bill, true = claim; supplier must be APPROVED)
   validate-bill-selection    --payload '<json>'  Require an APPROVED supplier, then verify approved quotation links for each budgetItemId; alreadyPaid never bypasses quotation checks.
   stage-bill-attachment <projectId> <filePath...> [--file <path>] [--files <csv>]   Upload files before create-bill; returns attachment JSON for attachments/paymentProofAttachments
   cleanup-staged-bill-attachments <projectId> --keys <csv>   Delete unattached staged bill/claim uploads.
   update-bill                --payload '<json>'  (bill.update; must include id)
   update-bill-payment-evidence --payload '<json>'  Replace paymentReference/paymentProofAttachments for an already-paid bill.
   delete-bill <billId>
-  update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference] [--paymentProof <receipt.pdf>]
+  update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference] [--paymentProof <receipt.pdf>] [--overBudgetOverrideReason <text>]
     status (${billStatusesForUpdateHelp.join(", ")}) \u2014 not PENDING_APPROVAL; use create-bill-approval
     PAID requires --paymentReference and a payment-proof PDF. Use --paymentProof to stage and submit the PDF atomically, or omit it only when BB already has a BILL_PAYMENT_PROOF attachment.
     Moving a bill or claim to PAID runs the server's paid-bill notification workflow.
@@ -23872,15 +23915,15 @@ Quotations
   create-quotation           --payload '<json>'  (quotation.createDraft; requires amountWithoutGst and gstAmount)
   update-quotation           --payload '<json>'  Update a DRAFT or REJECTED quotation; same payload plus id.
   delete-quotation <quotationId>
-  submit-quotation <quotationId>
-  approve-quotation <quotationId>
+  submit-quotation <quotationId> [--overBudgetOverrideReason <text>]
+  approve-quotation <quotationId> [--overBudgetOverrideReason <text>]
   reject-quotation <quotationId> --reason <text>
   download-quotation-pdf <quotationId> [original|staff|final]
 
 Customer invoices
   check-customer-invoice-readiness <budgetId>
   list-eligible-customer-invoice-budgets <projectId>   Accepted budgets that are ready and still have invoice coverage remaining.
-  list-customer-invoices [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+  list-customer-invoices [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalInvoiceAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
     No scope flag lists invoices globally. --projectId uses the project scope. A positional budgetId is a backward-compatible shortcut for --budgetIds.
   get-customer-invoice <batchId>
   get-customer-invoice-email-context <batchId>        Contact, required CC, budget, and project context for composing an invoice email.
@@ -23896,7 +23939,7 @@ Customer invoices
 
 Approvals
   list-approvals | get-pending-approvals   [--type budget|supplier|bill|quotation|customer_invoice|all]
-  approve-bill <billId>               (also sends requester reply email)
+  approve-bill <billId> [--overBudgetOverrideReason <text>]   (also sends requester reply email)
   reject-bill <billId> --reason <text> (also sends requester reply email)
   approve-budget <budgetId>           (also sends requester reply email)
   reject-budget <budgetId> --reason <text> (also sends requester reply email)
@@ -24328,7 +24371,7 @@ Waiting for approval\u2026
       }
       configureAccessToken(accessToken);
     }
-    if (!resolvedCommand.isLegacyAlias && resolvedCommand.command.effects.length > 0) {
+    if (!resolvedCommand.isLegacyAlias && cmd !== "create-bill" && resolvedCommand.command.effects.length > 0) {
       await confirmCurrentCommand({
         action: resolvedCommand.command.path.join(" "),
         target: commandConfirmationTarget(resolvedCommand),
@@ -24695,7 +24738,8 @@ Waiting for approval\u2026
           throw new Error("create-bill requires --payload '<json>'");
         }
         const raw = parseJsonFlag(String(payloadRaw), "--payload");
-        await createBillFromPayload(raw);
+        const draftOnly = flags["draft-only"] === true ? true : parseOptionalBoolFlag(flags, "draft-only");
+        await createBillFromPayload(raw, draftOnly);
         break;
       }
       case "validate-bill-selection": {
@@ -24748,7 +24792,8 @@ Waiting for approval\u2026
           rejectionReason: getFlag(flags, "rejectionReason"),
           paymentTrackingUrl: getFlag(flags, "paymentTrackingUrl"),
           paymentReference: getFlag(flags, "paymentReference"),
-          paymentProofPath: paymentProofFlag
+          paymentProofPath: paymentProofFlag,
+          overBudgetOverrideReason: getFlag(flags, "overBudgetOverrideReason")
         });
         break;
       }
@@ -24986,14 +25031,14 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("submit-quotation requires <quotationId>");
-        await submitQuotation(id);
+        await submitQuotation(id, getFlag(flags, "overBudgetOverrideReason"));
         break;
       }
       case "approve-quotation": {
         const id = positional[0];
         if (!id)
           throw new Error("approve-quotation requires <quotationId>");
-        await approveQuotation(id);
+        await approveQuotation(id, getFlag(flags, "overBudgetOverrideReason"));
         break;
       }
       case "reject-quotation": {
@@ -25163,7 +25208,7 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("approve-bill requires <billId>");
-        await approveBill(id);
+        await approveBill(id, getFlag(flags, "overBudgetOverrideReason"));
         break;
       }
       case "reject-bill": {

package/package.json

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

@@ -129,6 +129,8 @@ The following distinctions are especially important:
 - Project Hub setup and sync are asynchronous external writes. Read `bb project hub status <project-id>` first, obtain explicit approval, and request the mutation once instead of repeatedly queueing it. Setup readiness remains visible through `status`; commercial sync returns an outbox operation ID for Admin diagnostics.
 - Bill/claim status commands have separate role rules for `CHECKED`, `APPROVED`, and `PAID`.
 - `bb bill create --payload` uses `isClaimable=false`; `isClaimable=true` creates a claim. Claims intentionally permit some base-user flows that supplier bills do not.
+- For a draft-only bill or claim, use `bb bill create --draft-only --payload` (or `draftOnly: true` in the payload). This forces `DRAFT` for every role and requires only `--allow-state-change --allow-financial-write`. It sends no approval/email and performs no QuickBooks writes. Do not combine it with `alreadyPaid: true`. An older API without `bill.createDraft` rejects the command; never retry with ordinary creation to bypass that error.
+- 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.
 
 ## Handling authorization failures