@go-labs-sg/bb 3.0.0 → 3.1.0

package/README.md

@@ -45,6 +45,32 @@ Roll out the API and maintained CLI together: `suppliers`/`pageCount` and offset
 
 **Breaking API migration:** `bill.getList` is removed completely, with no alias or fallback. Direct scripts reading the former rich `bill.getAll` response must adopt summaries and fetch selected bill/claim details with `bb get-bill-details <billId>`. Do not fetch details for every list row unless the task actually needs them. No rich-list flag or automatic detail expansion is added.
 
+**Bill detail shape:** `bill.getById` / `bb get-bill-details` return only what the web bill pages read. Nested supplier, project, budget, people, attachments and approvals are narrowed to the displayed fields; supplier banking/provider data, contact people, catalogue descriptions and budget-item notes are not returned. Fetch line items, approvals, attachments or payment with `get-bill-line-items`, `get-bill-approvals`, `get-bill-attachments` or `get-bill-payment` only when a task needs them. Payment workflows (`update-bill-status --paymentProof`, `record-external-payment`) now read `bill.getPayment`.
+
+**Quotation detail shape:** `quotation.getById` / `bb get-quotation` return only what the web quotation pages read: status, amounts, dates, project/company/budget/supplier names, people, line totals with budget-item name/description/quantity/cost, file roles and approvals. Signature placement metadata, raw supplier records and attachment audit fields are not returned. Use `get-quotation-line-items <quotationId>` (newest-first cursor pages, `--limit 1-100`, `--cursor`) for line-item supplier/budget/unit-price detail.
+
+**Item detail shape:** `item.getItem` / `bb get-item` return the catalogue item's own fields (name, code, cost, rich-text description, GST flags, active/QuickBooks/availability state) with `supplier` narrowed to `{ id, name, gstRegistered, active, status }`, `itemCategory` to `{ id, name }` and attachments to `{ id, name, key, size }`. Full supplier and category records, plain-text `description`, `lowerCaseName` and the QuickBooks sync token are no longer included. `list-items` rows carry the list columns plus the same edit fields.
+
+**Supplier detail shape:** `supplier.getSupplierById` / `bb get-supplier-details` keep every supplier field the detail page and pending-update diff compare (contact, banking, PayNow, payment/role/certification ids, address, pending update), with `createdBy` narrowed to `{ id, name, email, image, role }`, attachments to `{ id, name, key, size }`, payment method/role/certification/tags to `{ id, name }` and each catalogue item to `{ id, catalogueCode, name, cost, descriptionRichText, itemCategory { id, name }, _count }`. Approvals carry their ids, status, timestamps and approver/responder users, not budget/bill/quotation links. `lowerCaseName`, the QuickBooks id and sync token, and `createdById` are no longer included.
+
+**Project detail shape:** `project.getProjectById` returns the project's own scheduling, ownership, Slack, Asana-task, QuickBooks and win fields plus the derived calendar, Asana and PM-membership fields, with `company { id, name }`, `asanaProject { gid, url }`, `insideSales`/`businessDevelopment`/`wonBy { id, name }`, `projectManager { id, name, email, bannedAt }` and `contactPerson { id, displayName, firstName, lastName }`. `project.getProjectDetailsById` / `bb get-project` returns the same project fields with only the derived Asana fields, `company { id, name }`, `asanaProject { gid, url }`, `wonBy { id, name }` and `contactPerson { id, displayName, firstName, lastName, email, mobile }`; it has no assignment relations, calendar or PM-membership fields. Both no longer include lost/override reasons, deal-automation and deal-lost bookkeeping columns, `winProofRequirement` or the payment-schedule lead days.
+
+**Dashboard read shapes:** `get-dashboard`, `get-monthly-metrics` and `get-financial-overview` (and the web user dashboard) now read only the budget, item, discount and commission fields their totals use, and `get-estimate-performance` reads only budget status; their outputs are unchanged. The web-only `dashboard.getSupplierById` supplier read selects just the analytics card fields; its output is unchanged.
+
+**Asana read shapes:** `asana.getAsanaTasks` returns the same sections and flattened task tree; its read now selects only the section and task fields it returns, not full task rows. The background Asana export reads only section and task titles and notes.
+
+**Error-log read shapes:** `bb error recent list` / `bb get-recent-errors` items now carry only the table columns: `id, severity, status, message, errorName, errorType, component, route, action, createdAt` and `user { id, name, email }`. Stack, cause, request details, metadata, tags, AI summary and resolution moved to the new `bb error get <errorId>` / `bb get-error <errorId>` (`errorLog.getErrorById`), which no longer returns alert-group bookkeeping or the raw `userId`/`resolvedById` columns (use `user`/`resolvedByUser`).
+
+**Company read shapes:** `company.getCompanyById` / `bb get-company` now return the company's own fields (`id, name, website, active, quickbooksId, createdById, createdAt, updatedAt`) without the embedded full `projects` array; use `bb list-projects --companyId <id>` for its projects. `bb list-companies` rows carry only `id, name, website, active, createdById, createdAt, updatedAt`, `createdBy { id, name, email, image }` and `_count`; use `bb get-company` for `quickbooksId`. Recent companies and the company QuickBooks sync status read only the fields they use; their outputs are unchanged.
+
+**Customer-invoice readiness and quotation list loading:** `customerInvoice.getInvoiceReadiness`, `getInvoiceAmountPreview`, `getEligibleBudgets` and `getProjectInvoiceReadiness` read the budget through one selected shape (only the budget, project, contact, invoice-settings, discount and item fields the readiness and amount helpers use) with Prisma's default join instead of forced per-relation queries. The quotation list page and metrics reads also use the default join. Their outputs are unchanged.
+
+**Bill item, quotation download and invoice-candidate reads:** `bill.getBudgetItemsForBill` / `getBudgetItemsForProject` rows now carry only the budget-item fields the bill, claim, quotation and line-item screens use: `item { id, catalogueCode }`, `supplier { id, name, gstRegistered, lowerCaseName }` (plus `address` on the project list for supplier verification), `itemCategory { id, name }`, and, on the project list only, `actualSpendings[] { id, amount, supplier }` (the bill list has no spendings). Neither is called by the CLI. `bb quotation pdf download` / `download-quotation-pdf` (`quotation.getSignedDownloadUrl`) returns `attachment { id, name, size, supplierQuotationFileRole }` with the signed `url`, without the internal storage key and row bookkeeping. `bb customer-invoice existing list` / `list-available-qbo-customer-invoices` (`customerInvoice.getExistingInvoiceCandidates`) reads only the budget state and project access fields; its output is unchanged.
+
+**Project and item-category list read shapes:** `bb project list` / `bb list-projects` (`project.getAllProjects`) items keep every column the project table, cards and edit dialog use. They drop the deal-automation, calendar, Slack-message, win-override and lost-reason bookkeeping columns. Their relations narrow to `contactPerson { id, displayName, email }`, `company { id, name }`, `createdBy { id, name, email, image }` and `wonBy { id, name }`; `asanaProjectGid`/`asanaProjectUrl` are unchanged. Use `bb get-project <id>` for project details. `bb list-item-categories` rows carry `createdBy { id, name, email, image }` instead of the full user row.
+
+**Customer invoice detail shape:** `customerInvoice.getInvoiceDetail` / `bb get-customer-invoice` return only what the web invoice page reads: batch status, totals, budget name, project permission ids, creator, approval approvers, operation/QuickBooks error state and per-invoice summaries (label, milestone, status, amounts, billing address, customer memo, email delivery). Invoice lines, history, QuickBooks ids/dates and full approval people are no longer included. Use `get-customer-invoice-invoices <batchId>`, `get-customer-invoice-lines <invoiceId>`, `get-customer-invoice-approvals <batchId>` and `get-customer-invoice-history <batchId>`; the last three are newest-first `{ items, pageInfo }` pages. `list-customer-invoices` rows likewise carry only the list columns (budget/project/company names, creator, invoice labels/doc numbers and amounts).
+
 Coordinate the matching API/web deployment and CLI release/installations. MCP is deprecated and is not a rollout or acceptance gate. Published CLI builds still calling `getList` receive `NOT_FOUND` after API rollout, so a mixed-revision deployment is not compatible. Update those installations to the matching CLI release. Budget-list options are unchanged. This source change does not publish the CLI or deploy the API.
 
 ## Inventory list reads
@@ -230,6 +256,8 @@ bb get-budget-details <budget-id> --includeInactive
 
 `get-budget` and `get-budget-items` return every line item of the budget (`{ items, truncated, totals }`), not a page. `truncated` is true only past the 1,000-line safety cap. `totals` (item count, cost, total cost, total price, actual spending, pending approval) comes from `budget.getBudgetItemTotals`.
 
+**Budget read shapes:** `get-budget` (`budget.getBudget`) now carries only the estimation grand total (`budgetEstimation.totals.grandTotal`); use `get-budget-details <budget-id>` (`budget.getBudgetDetail`) for the full estimation (plans, crew, validation, summary, assumptions, timeline, risks, recommendations). `get-budget-items` rows keep the editor fields (name, rich-text description/note, quantity, prices, flags, availability exception, bills, actual spending) with `supplier` narrowed to `{ id, name, gstRegistered, active, status }` and `itemCategory` to `{ id, name }`; plain-text `description`/`note`, timestamps and supplier contact/bank fields are no longer included.
+
 `--active false` lists inactive budgets only. `--active all` lists active and inactive budgets. `--includeInactive` allows the three budget/detail/item commands to read inactive history. If the authenticated identity is not an Admin, the API rejects the historical request before reading budget data. For `get-budget`, the CLI requests the budget and its line items concurrently; each API read independently enforces the same active-only default and Admin-only historical opt-in.
 
 ## Secure credential storage
@@ -627,7 +655,7 @@ For `QBO_IMPORT` invoices, this existing command reads QBO and updates BB balanc
 
 The Seatrium example must be previewed against live QBO again before an operator imports it. Previously observed invoice numbers and paid/open balances are not authorization or current-state evidence.
 
-**Customer-invoice workflow parity:** `bb customer-invoice list` uses the same global/project cursor-page procedure as the web pages, and `bb customer-invoice count` returns the same totals, facets and metrics; omit filters for the global list or use `--projectId` for project scope. `bb customer-invoice send --payload '<json>'` uses the same protected email workflow as the web composer, sends to the payload's `to` address, saves that address as the project's configured billing email after a successful send, and marks the invoice `SENT`. `bb customer-invoice approve` and `bb customer-invoice reject` are Admin-only batch operations: callers select a batch ID, and the API resolves its internal pending Admin approval record. `bb customer-invoice sync` follows QuickBooks' paid state and zero balance, restoring `SENT` or `APPROVED` if that payment is reversed. Invoice approval refuses voided invoices and closes the estimate only when approved invoice coverage totals 100%; deletion, voiding, rejection, expiry, and QBO synchronization use the same estimate-reopening and live-payment guards as the web app.
+**Customer-invoice workflow parity:** `bb customer-invoice list` uses the same global/project cursor-page procedure as the web pages, and `bb customer-invoice count` returns the same totals, facets and metrics; omit filters for the global list or use `--projectId` for project scope. `bb customer-invoice send --payload '<json>'` uses the same protected email workflow as the web composer, sends to the payload's `to` address, saves that address as the project's configured billing email after a successful send, and marks the invoice `SENT`. `bb customer-invoice approve` and `bb customer-invoice reject` are Admin-only batch operations: callers select a batch ID, and the API resolves its internal pending Admin approval record. `bb customer-invoice sync` follows QuickBooks' paid state and zero balance, restoring `SENT` or `APPROVED` if that payment is reversed. Invoice approval refuses voided invoices and closes the estimate only when approved invoice coverage totals 100%; deletion, voiding, rejection, expiry, and QBO synchronization use the same estimate-reopening and live-payment guards as the web app. `bb customer-invoice void`, `delete` and `reject` print `{ batchId, batch, operation }`, where `batch` is the same shape as `get-customer-invoice` (or `null` once a delete completes); use `get-customer-invoice-invoices`, `-lines`, `-approvals` and `-history` for invoice lines, history and approval requester/responder.
 
 For agent-driven invoice work, use this read-before-write sequence:
 
@@ -668,16 +696,16 @@ Admin/Lead users can run `bb supplier approve <supplierId>` to directly re-appro
 | 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` (forward cursor pages of active categories, name A–Z: `--q` / `--limit` / `--cursor`; returns `{ items, pageInfo }`), `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, adds 5 mandatory supplier subtasks ending in "Get bill and upload to Budget Builder", and sets no subtask due dates; `--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` (newest-first cursor pages: `--limit` 1–50, `--cursor`; returns `{ items, pageInfo }`), `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
-| **Quotations** | `list-quotations` (project, budget, supplier, status, requester and text-search filters; newest-first cursor pages via `--limit` / `--cursor` / `--direction` returning `{ items, pageInfo }`; `--page` / `--perPage` / `--pageSize` are rejected), `count-quotations` (`quotation.getCounts`: filters only, returns `totalCount`, status facets that ignore their own status filter, and `--includeMetrics true` amount metrics), `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`, `preview-customer-invoice-amount`, `list-available-qbo-customer-invoices`, `list-customer-invoices` (global/project/budget filters; cursor pages via `--limit` / `--cursor` / `--direction` returning `{ items, pageInfo }`, `--page` / `--perPage` rejected; `--sortBy totalInvoiceAmount` sorts provider-confirmed totals including GST, with unknown amounts last), `count-customer-invoices` (`customerInvoice.getCounts`: filters only; `totalCount`, lifecycle status facets that ignore their own status filter, and amount metrics), `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` |
+| **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` (newest-first cursor pages: `--limit` 1–50, `--cursor`; returns `{ items, pageInfo }`), `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` (the web bill summary: status, amounts, people, payment, line totals), `get-bill-line-items` / `get-bill-approvals` (newest-first cursor pages: `--limit`, `--cursor`; `{ items, pageInfo }`), `get-bill-payment` (payment status, reference, date, tracking URL, QuickBooks link, external payment) |
+| **Quotations** | `list-quotations` (project, budget, supplier, status, requester and text-search filters; newest-first cursor pages via `--limit` / `--cursor` / `--direction` returning `{ items, pageInfo }`; `--page` / `--perPage` / `--pageSize` are rejected), `count-quotations` (`quotation.getCounts`: filters only, returns `totalCount`, status facets that ignore their own status filter, and `--includeMetrics true` amount metrics), `get-quotation` (web quotation shape), `get-quotation-line-items` (`<quotationId>`; newest-first cursor pages, `--limit 1-100`, `--cursor`), `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`, `preview-customer-invoice-amount`, `list-available-qbo-customer-invoices`, `list-customer-invoices` (global/project/budget filters; cursor pages via `--limit` / `--cursor` / `--direction` returning `{ items, pageInfo }`, `--page` / `--perPage` rejected; `--sortBy totalInvoiceAmount` sorts provider-confirmed totals including GST, with unknown amounts last), `count-customer-invoices` (`customerInvoice.getCounts`: filters only; `totalCount`, lifecycle status facets that ignore their own status filter, and amount metrics), `get-customer-invoice` (web-shaped batch), `get-customer-invoice-invoices`, `get-customer-invoice-lines`, `get-customer-invoice-approvals`, `get-customer-invoice-history`, `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`) |
 | **Contacts** | `list-contacts`, `create-contact-person` (`--payload`), `update-contact-person` (`--payload`) |
 | **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics` (admin; cursor pages: `--limit` / `--cursor` / `--direction`, optional `--name`, `--status` CSV, `--gstRegistered true|false`, `--createdBy`, `--timeFrame` (with `--startDate`/`--endDate` for `CUSTOM` only), `--sortBy name|gstRegistered|status|phone|email|updatedAt|createdAt`, `--sortDir`; `--page` / `--perPage` rejected; invalid filters are rejected instead of silently widening results), `count-supplier-analytics` (admin; `{ totalCount }` for the same filters), `list-items` (`--includeQuickBooksDeactivationPending true` discovers interrupted QuickBooks deactivations for Admin retry), `create-item` (`--payload`), `update-item` (`--payload`), `archive-items` (`--ids` CSV, max 100; Budget Builder-only; open estimates retain unavailable snapshot lines for resolution), `delete-item` (admin; archives in Budget Builder and makes the item inactive in QuickBooks; blocked while an open estimate references it), `get-item`, `list-item-categories` (cursor pages of active categories: `--limit` / `--cursor` / `--direction`, optional `--name`, `--sortBy createdAt|name|itemCount|createdBy`, `--sortDir`; `--page` / `--perPage` rejected), `count-item-categories` (`{ totalCount }` for the same `--name`), `create-item-category` / `update-item-category` / `delete-item-categories` (admin; `--ids` CSV for delete) |
 | **Dashboard & users** | `whoami` (current authenticated identity and role), `list-users` (forward cursor pages, name A–Z: `--limit` / `--cursor`, optional `--q` matching name or email; `--page` / `--perPage` rejected), `count-users` (`{ totalCount }` for the same `--q`), `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (`--name`; defaults to the caller; admin-only `--userId` for another user; raw key shown once), `list-api-keys` (newest-first cursor pages: `--limit` 1–100, `--cursor`; returns `{ items, pageInfo }`; defaults to the caller; admin-only `--userId` for another user), `revoke-api-key` (key ID; admin-only `--userId` for another user), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` (performance/dashboard commands are admin-only) |
-| **Errors (admin)** | `get-recent-errors`, `get-error-metrics` |
-| **Automation (admin)** | `list-integration-operations` (cursor pages, newest first: `--limit` / `--cursor` / `--direction` with `--search`, `--destination`, `--status`; `--page` / `--perPage` rejected), `count-integration-operations` (`{ totalCount, filterOptions }` for the same filters), `get-integration-operation <operationId>` (who queued the job, what it is for, saved progress, Retry state), `reconcile-resource-operation <operationId>`, `retry-integration-operation` (QuickBooks jobs with a saved attempt check QuickBooks first and never resend an applied change; Resend resolution requires `--confirmExternalStateReconciled true` plus `--outboundEmailResolution ACCEPTED\|NOT_ACCEPTED_RETRY`; include `--providerMessageId` when accepted) |
+| **Errors (admin)** | `get-recent-errors`, `get-error`, `get-error-metrics` |
+| **Automation (admin)** | `list-integration-operations` (cursor pages, newest first: `--limit` / `--cursor` / `--direction` with `--search`, `--destination`, `--status`; `--page` / `--perPage` rejected), `count-integration-operations` (`{ filterOptions }` provider options only; no total, so the command does not scan the outbox; filter flags are accepted but ignored), `get-integration-operation <operationId>` (who queued the job, what it is for, saved progress, Retry state), `reconcile-resource-operation <operationId>`, `retry-integration-operation` (QuickBooks jobs with a saved attempt check QuickBooks first and never resend an applied change; Resend resolution requires `--confirmExternalStateReconciled true` plus `--outboundEmailResolution ACCEPTED\|NOT_ACCEPTED_RETRY`; include `--providerMessageId` when accepted) |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 
 The CLI intentionally wraps low-level upload-request/confirm procedures into file-based commands and omits browser-only helpers such as navigation counts, combobox/facet data, recent-page bookkeeping, and live UI subscriptions. Operational workflows for bills, claims, quotations, customer invoices, project reconciliation/completion, and integration recovery are available directly.