@go-labs-sg/bb 2.41.0 → 2.43.0

package/dist/index.js

@@ -6789,6 +6789,186 @@ var ExtendedErrorStatus = {
   ...ErrorStatus
 };
 
+// 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 formatValidationMessage = (message, data) => {
+  const zodError = isRecord(data?.zodError) ? data.zodError : undefined;
+  const fieldErrors = isRecord(zodError?.fieldErrors) ? zodError.fieldErrors : undefined;
+  const fields = fieldErrors ? Object.entries(fieldErrors).flatMap(([field, errors]) => Array.isArray(errors) ? errors.filter((entry) => typeof entry === "string").map((entry) => `${field}: ${entry}`) : []) : [];
+  const formErrors = Array.isArray(zodError?.formErrors) ? zodError.formErrors.filter((entry) => typeof entry === "string") : [];
+  const validationIssues = [...fields, ...formErrors];
+  if (validationIssues.length > 0)
+    return validationIssues.join("; ");
+  let parsed = message;
+  for (let depth = 0;depth < 3 && typeof parsed === "string"; depth++) {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      return message;
+    }
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(isRecord))
+    return message;
+  const issues = parsed.map((issue) => {
+    if (!Array.isArray(issue.path) || typeof issue.message !== "string" || typeof issue.code !== "string")
+      return;
+    const path = issue.path.filter((part) => typeof part === "string" || typeof part === "number").join(".") || "payload";
+    if (issue.code === "invalid_type" && typeof issue.expected === "string" && issue.message.toLowerCase().includes("required")) {
+      return `${path} must be a ${issue.expected}${path === "cost" ? ', e.g. "19"' : ""}`;
+    }
+    if (issue.code === "invalid_format" && issue.format === "regex" && path === "name" && String(issue.pattern ?? issue.message).includes("A-Za-z0-9,.?@&!#'~* _;+-")) {
+      return `${path} contains characters that are not allowed. Allowed: letters, numbers, spaces and , . ? @ & ! # ' ~ * _ ; + -`;
+    }
+    return `${path}: ${issue.message}`;
+  });
+  return issues.every((issue) => issue !== undefined) ? issues.join("; ") : message;
+};
+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 = (error, depth = 0) => {
+  if (depth > 3 || !isRecord(error))
+    return false;
+  const message = asNonEmptyString(error.message);
+  if (message !== undefined && networkMessagePattern.test(message))
+    return true;
+  const code = asNonEmptyString(error.code);
+  if (code !== undefined && networkMessagePattern.test(code))
+    return true;
+  return isNetworkError(error.cause, depth + 1);
+};
+var normalizeCliError = (error) => {
+  if (error instanceof CliRuntimeError) {
+    return {
+      code: error.code,
+      message: error.message,
+      ...error.details === undefined ? {} : { details: error.details },
+      ...error.requestId === undefined ? {} : { requestId: error.requestId }
+    };
+  }
+  if (isNetworkError(error)) {
+    return {
+      code: "NETWORK",
+      message: error instanceof Error ? error.message : "The Budget Builder API could not be reached."
+    };
+  }
+  if (isRecord(error)) {
+    const data = isRecord(error.data) ? error.data : undefined;
+    const transportCode = mapErrorCode(data?.code ?? error.code);
+    if (error instanceof Error && data === undefined && transportCode === undefined) {
+      return { code: "INTERNAL", message: error.message };
+    }
+    const code = transportCode ?? "API";
+    const rawMessage = asNonEmptyString(error.message) ?? "The Budget Builder API request failed.";
+    const message = code === "VALIDATION" ? formatValidationMessage(rawMessage, data) : rawMessage;
+    const requestId = asNonEmptyString(data?.requestId) ?? asNonEmptyString(data?.requestID) ?? asNonEmptyString(error.requestId);
+    const details = asDetails(data?.details ?? error.details);
+    return {
+      code,
+      message,
+      ...details === undefined ? {} : { details },
+      ...requestId === undefined ? {} : { requestId }
+    };
+  }
+  if (error instanceof Error) {
+    return { code: "INTERNAL", message: error.message };
+  }
+  return { code: "INTERNAL", message: "An unexpected CLI error occurred." };
+};
+var exitCodeForCliError = (error) => {
+  if (error.code === "INTERRUPTED")
+    return 130;
+  return invocationErrorCodes.has(error.code) ? 2 : 1;
+};
+
+// src/budget-create-outcome.ts
+var isP2028Error = (value, depth = 0) => {
+  if (depth > 3 || typeof value !== "object" || value === null)
+    return false;
+  const error = value;
+  return error.code === "P2028" || typeof error.message === "string" && /\bP2028\b/.test(error.message) || isP2028Error(error.cause, depth + 1) || isP2028Error(error.data, depth + 1) || isP2028Error(error.error, depth + 1);
+};
+var budgetCreateUncertainError = (error, input) => {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = normalizeCliError(error);
+  if (!isP2028Error(error) && normalized.code !== "NETWORK")
+    return;
+  return new CliRuntimeError(normalized.code === "NETWORK" ? "NETWORK" : "API", `Budget creation outcome is uncertain (the write may have committed). Run list-budgets --projectId ${input.projectId} and check for ${JSON.stringify(input.name)} before retrying; matching names alone may be ambiguous. Original error: ${message}`);
+};
+
 // src/commands/invoice-splits.ts
 var invoiceSplitSetupNextAction = (budgetId) => ({
   prompt: "Review the uninvoiced balance, choose all or part of the remaining percentage, then supply invoice and due dates, billing address, and customer message. Non-admin creation requests admin approval; admin creation auto-approves. Sending remains separate.",
@@ -7135,142 +7315,11 @@ 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 = (error, depth = 0) => {
-  if (depth > 3 || !isRecord(error))
-    return false;
-  const message = asNonEmptyString(error.message);
-  if (message !== undefined && networkMessagePattern.test(message))
-    return true;
-  const code = asNonEmptyString(error.code);
-  if (code !== undefined && networkMessagePattern.test(code))
-    return true;
-  return isNetworkError(error.cause, depth + 1);
-};
-var normalizeCliError = (error) => {
-  if (error instanceof CliRuntimeError) {
-    return {
-      code: error.code,
-      message: error.message,
-      ...error.details === undefined ? {} : { details: error.details },
-      ...error.requestId === undefined ? {} : { requestId: error.requestId }
-    };
-  }
-  if (isNetworkError(error)) {
-    return {
-      code: "NETWORK",
-      message: error instanceof Error ? error.message : "The Budget Builder API could not be reached."
-    };
-  }
-  if (isRecord(error)) {
-    const data = isRecord(error.data) ? error.data : undefined;
-    const transportCode = mapErrorCode(data?.code ?? error.code);
-    if (error instanceof Error && data === undefined && transportCode === undefined) {
-      return { code: "INTERNAL", message: error.message };
-    }
-    const code = transportCode ?? "API";
-    const message = asNonEmptyString(error.message) ?? "The Budget Builder API request failed.";
-    const requestId = asNonEmptyString(data?.requestId) ?? asNonEmptyString(data?.requestID) ?? asNonEmptyString(error.requestId);
-    const details = asDetails(data?.details ?? error.details);
-    return {
-      code,
-      message,
-      ...details === undefined ? {} : { details },
-      ...requestId === undefined ? {} : { requestId }
-    };
-  }
-  if (error instanceof Error) {
-    return { code: "INTERNAL", message: error.message };
-  }
-  return { code: "INTERNAL", message: "An unexpected CLI error occurred." };
-};
-var exitCodeForCliError = (error) => {
-  if (error.code === "INTERRUPTED")
-    return 130;
-  return invocationErrorCodes.has(error.code) ? 2 : 1;
-};
-
 // src/parse-mutation-payload.ts
+var validationError = (message) => new CliRuntimeError("VALIDATION", message);
 function requireObject(raw, label) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error(`${label} must be a JSON object.`);
+    throw validationError(`${label} must be a JSON object.`);
   }
   return raw;
 }
@@ -7283,7 +7332,7 @@ function toDate(value, field) {
     if (!Number.isNaN(d.getTime()))
       return d;
   }
-  throw new Error(`${field} must be an ISO date/datetime string.`);
+  throw validationError(`${field} must be an ISO date/datetime string.`);
 }
 function optionalString(v) {
   if (v === undefined || v === null)
@@ -7297,14 +7346,14 @@ var parseQuotationReferences = (input, commandName) => {
   let quotationAllocations;
   if (rawAllocations !== undefined && rawAllocations !== null) {
     if (!Array.isArray(rawAllocations) || rawAllocations.length === 0) {
-      throw new Error(`${commandName} payload.quotationAllocations must be a non-empty array.`);
+      throw validationError(`${commandName} payload.quotationAllocations must be a non-empty array.`);
     }
     quotationAllocations = rawAllocations.map((raw, index) => {
       const label = `${commandName} payload.quotationAllocations[${index}]`;
       const allocation = requireObject(raw, label);
       const amount = Number(allocation.amount);
       if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
-        throw new Error(`${label}.amount must be a non-negative cent value.`);
+        throw validationError(`${label}.amount must be a non-negative cent value.`);
       }
       return {
         budgetItemId: requiredString(allocation.budgetItemId, `${label}.budgetItemId`),
@@ -7314,22 +7363,22 @@ var parseQuotationReferences = (input, commandName) => {
     });
     const keys = quotationAllocations.map((allocation) => `${allocation.budgetItemId}\x00${allocation.quotationId}`);
     if (new Set(keys).size !== keys.length) {
-      throw new Error(`${commandName} payload.quotationAllocations must not repeat a budget-item/quotation pair.`);
+      throw validationError(`${commandName} payload.quotationAllocations must not repeat a budget-item/quotation pair.`);
     }
   }
   const rawQuotationIds = input.quotationIds;
   let quotationIds;
   if (rawQuotationIds !== undefined && rawQuotationIds !== null) {
     if (!Array.isArray(rawQuotationIds)) {
-      throw new Error(`${commandName} payload.quotationIds must be a string array.`);
+      throw validationError(`${commandName} payload.quotationIds must be a string array.`);
     }
     quotationIds = rawQuotationIds.map((id, index) => requiredString(id, `${commandName} payload.quotationIds[${index}]`));
     if (new Set(quotationIds).size !== quotationIds.length) {
-      throw new Error(`${commandName} payload.quotationIds must not contain duplicates.`);
+      throw validationError(`${commandName} payload.quotationIds must not contain duplicates.`);
     }
   }
   if (quotationId && quotationIds && (quotationIds.length !== 1 || quotationIds[0] !== quotationId)) {
-    throw new Error(`${commandName} payload.quotationId conflicts with payload.quotationIds.`);
+    throw validationError(`${commandName} payload.quotationId conflicts with payload.quotationIds.`);
   }
   if (quotationAllocations && quotationIds) {
     const allocationIds = [
@@ -7337,7 +7386,7 @@ var parseQuotationReferences = (input, commandName) => {
     ].sort();
     const selectedIds = [...quotationIds].sort();
     if (allocationIds.join("\x00") !== selectedIds.join("\x00")) {
-      throw new Error(`${commandName} payload.quotationIds conflicts with payload.quotationAllocations.`);
+      throw validationError(`${commandName} payload.quotationIds conflicts with payload.quotationAllocations.`);
     }
   }
   return {
@@ -7350,14 +7399,14 @@ var parseBillLineAmounts = (input, commandName) => {
   if (input.lineAmounts === undefined || input.lineAmounts === null)
     return;
   if (!Array.isArray(input.lineAmounts) || input.lineAmounts.length === 0) {
-    throw new Error(`${commandName} payload.lineAmounts must be a non-empty array.`);
+    throw validationError(`${commandName} payload.lineAmounts must be a non-empty array.`);
   }
   const lineAmounts = input.lineAmounts.map((raw, index) => {
     const label = `${commandName} payload.lineAmounts[${index}]`;
     const line = requireObject(raw, label);
     const amount = Number(line.amount);
     if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
-      throw new Error(`${label}.amount must be a non-negative cent value.`);
+      throw validationError(`${label}.amount must be a non-negative cent value.`);
     }
     return {
       budgetItemId: requiredString(line.budgetItemId, `${label}.budgetItemId`),
@@ -7365,7 +7414,7 @@ var parseBillLineAmounts = (input, commandName) => {
     };
   });
   if (new Set(lineAmounts.map((line) => line.budgetItemId)).size !== lineAmounts.length) {
-    throw new Error(`${commandName} payload.lineAmounts must contain each budget item once.`);
+    throw validationError(`${commandName} payload.lineAmounts must contain each budget item once.`);
   }
   return lineAmounts;
 };
@@ -7380,14 +7429,14 @@ var validateExplicitBillAllocations = ({
   if (!lineAmounts && !quotationAllocations)
     return;
   if (!lineAmounts) {
-    throw new Error(`${commandName} payload.lineAmounts is required with quotationAllocations.`);
+    throw validationError(`${commandName} payload.lineAmounts is required with quotationAllocations.`);
   }
   const selected = new Set(budgetItemIds);
   if (lineAmounts.length !== selected.size || lineAmounts.some((line) => !selected.has(line.budgetItemId))) {
-    throw new Error(`${commandName} payload.lineAmounts must contain each selected budget item exactly once.`);
+    throw validationError(`${commandName} payload.lineAmounts must contain each selected budget item exactly once.`);
   }
   if (lineAmounts.reduce((sum, line) => sum + cents(line.amount), 0) !== cents(amount)) {
-    throw new Error(`${commandName} payload.lineAmounts must sum to payload.amount.`);
+    throw validationError(`${commandName} payload.lineAmounts must sum to payload.amount.`);
   }
   if (!quotationAllocations)
     return;
@@ -7395,27 +7444,27 @@ var validateExplicitBillAllocations = ({
   const allocatedById = new Map;
   for (const allocation of quotationAllocations) {
     if (!selected.has(allocation.budgetItemId)) {
-      throw new Error(`${commandName} payload.quotationAllocations references an unselected budget item.`);
+      throw validationError(`${commandName} payload.quotationAllocations references an unselected budget item.`);
     }
     allocatedById.set(allocation.budgetItemId, (allocatedById.get(allocation.budgetItemId) ?? 0) + cents(allocation.amount));
     if (cents(allocation.amount) === 0 && lineAmountById.get(allocation.budgetItemId) !== 0) {
-      throw new Error(`${commandName} zero quotation allocations are only valid for zero-value bill lines.`);
+      throw validationError(`${commandName} zero quotation allocations are only valid for zero-value bill lines.`);
     }
   }
   for (const [budgetItemId, allocated] of allocatedById) {
     if (allocated > (lineAmountById.get(budgetItemId) ?? 0)) {
-      throw new Error(`${commandName} quotation allocations exceed the line amount for ${budgetItemId}.`);
+      throw validationError(`${commandName} quotation allocations exceed the line amount for ${budgetItemId}.`);
     }
   }
 };
 function requiredString(value, fieldLabel) {
   if (value === undefined || value === null) {
-    throw new Error(`${fieldLabel} is required.`);
+    throw validationError(`${fieldLabel} is required.`);
   }
   const s = typeof value === "string" ? value : String(value);
   const t = s.trim();
   if (t === "") {
-    throw new Error(`${fieldLabel} is required.`);
+    throw validationError(`${fieldLabel} is required.`);
   }
   return t;
 }
@@ -7423,13 +7472,13 @@ var EMAIL_ADDRESS_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var requiredEmail = (value, fieldLabel) => {
   const email = requiredString(value, fieldLabel);
   if (!EMAIL_ADDRESS_PATTERN.test(email)) {
-    throw new Error(`${fieldLabel} must be a valid email address.`);
+    throw validationError(`${fieldLabel} must be a valid email address.`);
   }
   return email;
 };
 var parseContactPersonEmailPayload = (input, commandName) => {
   if (!Array.isArray(input.cc)) {
-    throw new Error(`${commandName} payload.cc must be an email array.`);
+    throw validationError(`${commandName} payload.cc must be an email array.`);
   }
   return {
     to: requiredEmail(input.to, `${commandName} payload.to`),
@@ -7459,7 +7508,7 @@ var parseSendCustomerInvoiceToContactPersonPayload = (raw) => {
 function parseCreateBudgetPayload(raw) {
   const o = requireObject(raw, "create-budget payload");
   if (o.unavailableItemReviewAcknowledged !== undefined && typeof o.unavailableItemReviewAcknowledged !== "boolean") {
-    throw new Error("create-budget payload.unavailableItemReviewAcknowledged must be a boolean when set.");
+    throw validationError("create-budget payload.unavailableItemReviewAcknowledged must be a boolean when set.");
   }
   return {
     name: requiredString(o.name, "create-budget payload.name"),
@@ -7493,7 +7542,7 @@ function parseBudgetDiscountPayload(raw) {
   const o = requireObject(raw, "update-budget-discount payload");
   const type = o.type;
   if (type !== "percentage" && type !== "amount") {
-    throw new Error('update-budget-discount payload.type must be "percentage" or "amount".');
+    throw validationError('update-budget-discount payload.type must be "percentage" or "amount".');
   }
   return {
     budgetId: requiredString(o.budgetId, "update-budget-discount payload.budgetId"),
@@ -7517,28 +7566,28 @@ function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, req
   const o = requireObject(raw, "create-bill payload");
   const isClaimable = o.isClaimable;
   if (typeof isClaimable !== "boolean") {
-    throw new Error("create-bill payload.isClaimable must be boolean.");
+    throw validationError("create-bill payload.isClaimable must be boolean.");
   }
   const budgetItemIds = o.budgetItemIds;
   if (!Array.isArray(budgetItemIds) || budgetItemIds.length === 0) {
-    throw new Error("create-bill payload.budgetItemIds must be a non-empty string array.");
+    throw validationError("create-bill payload.budgetItemIds must be a non-empty string array.");
   }
   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.");
+    throw validationError("create-bill payload.draftOnly must be boolean.");
   }
   if (draftOnlyFlag !== undefined && draftOnlyRaw !== undefined && draftOnlyFlag !== draftOnlyRaw) {
-    throw new Error("--draft-only conflicts with payload.draftOnly.");
+    throw validationError("--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.");
+    throw validationError("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.");
+    throw validationError("create-bill payload.alreadyPaid must be boolean.");
   }
   const paymentProofAttachmentsRaw = o.paymentProofAttachments;
   const paymentProofAttachments = Array.isArray(paymentProofAttachmentsRaw) ? paymentProofAttachmentsRaw.map((x, i) => billAttachment(x, i, "paymentProofAttachments")) : [];
@@ -7548,7 +7597,7 @@ function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, req
     const v = requireObject(vr, "verificationResults");
     const verificationResultStatus = v.status;
     if (verificationResultStatus !== BillVerificationStatus.PENDING && verificationResultStatus !== BillVerificationStatus.PASS && verificationResultStatus !== BillVerificationStatus.FAIL && verificationResultStatus !== BillVerificationStatus.MANUAL_REVIEW) {
-      throw new Error("create-bill payload.verificationResults.status must be PENDING | PASS | FAIL | MANUAL_REVIEW.");
+      throw validationError("create-bill payload.verificationResults.status must be PENDING | PASS | FAIL | MANUAL_REVIEW.");
     }
     verificationResults = {
       status: verificationResultStatus,
@@ -7563,11 +7612,11 @@ function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, req
   if (verificationStatus === BillVerificationStatus.PENDING || verificationStatus === BillVerificationStatus.PASS || verificationStatus === BillVerificationStatus.FAIL || verificationStatus === BillVerificationStatus.MANUAL_REVIEW) {
     vs = verificationStatus;
   } else if (verificationStatus !== undefined && verificationStatus !== null) {
-    throw new Error("create-bill payload.verificationStatus must be PENDING | PASS | FAIL | MANUAL_REVIEW.");
+    throw validationError("create-bill payload.verificationStatus must be PENDING | PASS | FAIL | MANUAL_REVIEW.");
   }
   const amount = Number(o.amount);
   if (!Number.isFinite(amount) || amount < 0) {
-    throw new Error("create-bill payload.amount must be a number >= 0.");
+    throw validationError("create-bill payload.amount must be a number >= 0.");
   }
   const quotationReferences = parseQuotationReferences(o, "create-bill");
   const parsedBudgetItemIds = budgetItemIds.map((id, i) => requiredString(id, `create-bill payload.budgetItemIds[${i}]`));
@@ -7580,16 +7629,16 @@ function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, req
     quotationAllocations: quotationReferences.quotationAllocations
   });
   if (quotationExempt && isClaimable) {
-    throw new Error("--quotation-exempt is only valid for supplier bills.");
+    throw validationError("--quotation-exempt is only valid for supplier bills.");
   }
   if (quotationExempt && (quotationReferences.quotationId || (quotationReferences.quotationIds?.length ?? 0) > 0 || (quotationReferences.quotationAllocations?.length ?? 0) > 0)) {
-    throw new Error("--quotation-exempt cannot be combined with payload quotation IDs.");
+    throw validationError("--quotation-exempt cannot be combined with payload quotation IDs.");
   }
   if (isClaimable && (quotationReferences.quotationId || (quotationReferences.quotationIds?.length ?? 0) > 0 || (quotationReferences.quotationAllocations?.length ?? 0) > 0)) {
-    throw new Error("Employee claims cannot include quotation source inputs.");
+    throw validationError("Employee claims cannot include quotation source inputs.");
   }
   if (requireSupplierQuotation && !quotationExempt && !isClaimable && !quotationReferences.quotationId && (quotationReferences.quotationIds?.length ?? 0) === 0 && (quotationReferences.quotationAllocations?.length ?? 0) === 0) {
-    throw new Error("create-bill supplier bills require payload.quotationAllocations, payload.quotationIds, or legacy payload.quotationId.");
+    throw validationError("create-bill supplier bills require payload.quotationAllocations, payload.quotationIds, or legacy payload.quotationId.");
   }
   return {
     budgetId: requiredString(o.budgetId, "create-bill payload.budgetId"),
@@ -7616,14 +7665,110 @@ function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, req
 }
 function parseUpdateBillPayload(raw) {
   const o = requireObject(raw, "update-bill payload");
-  const { draftOnly, ...input } = parseCreateBillPayload(raw, undefined, false, false);
-  if (draftOnly !== undefined) {
-    throw new Error("draftOnly is only supported when creating a bill.");
+  if (o.draftOnly !== undefined) {
+    throw validationError("draftOnly is only supported when creating a bill.");
   }
-  return {
-    ...input,
+  const input = {
     id: requiredString(o.id, "update-bill payload.id")
   };
+  const knownFields = new Set([
+    "id",
+    "budgetId",
+    "projectId",
+    "supplierId",
+    "quotationId",
+    "quotationIds",
+    "quotationAllocations",
+    "overBudgetOverrideReason",
+    "amount",
+    "budgetItemIds",
+    "lineAmounts",
+    "comment",
+    "isClaimable",
+    "attachments",
+    "alreadyPaid",
+    "paymentReference",
+    "paymentProofAttachments",
+    "extractedSupplierName",
+    "extractedAmount",
+    "invoiceNumber",
+    "invoiceDate",
+    "verificationStatus",
+    "verificationResults"
+  ]);
+  for (const key of Object.keys(o))
+    if (!knownFields.has(key))
+      throw validationError(`Unknown update-bill payload field: ${key}`);
+  for (const key of [
+    "budgetId",
+    "projectId",
+    "supplierId",
+    "comment",
+    "paymentReference",
+    "extractedSupplierName",
+    "invoiceNumber",
+    "overBudgetOverrideReason"
+  ]) {
+    if (o[key] === undefined)
+      continue;
+    if (typeof o[key] !== "string")
+      throw validationError(`update-bill payload.${key} must be a string.`);
+    input[key] = o[key];
+  }
+  for (const key of ["amount", "extractedAmount"]) {
+    if (o[key] === undefined)
+      continue;
+    const amount = Number(o[key]);
+    if (!Number.isFinite(amount) || amount < 0)
+      throw validationError(`update-bill payload.${key} must be a number >= 0.`);
+    input[key] = amount;
+  }
+  for (const key of ["isClaimable", "alreadyPaid"]) {
+    if (o[key] === undefined)
+      continue;
+    if (typeof o[key] !== "boolean")
+      throw validationError(`update-bill payload.${key} must be boolean.`);
+    input[key] = o[key];
+  }
+  for (const key of ["attachments", "paymentProofAttachments"]) {
+    const attachments = o[key];
+    if (attachments === undefined)
+      continue;
+    if (!Array.isArray(attachments))
+      throw validationError(`update-bill payload.${key} must be an array.`);
+    input[key] = attachments.map((value, index) => billAttachment(value, index, key));
+  }
+  if (o.budgetItemIds !== undefined) {
+    if (!Array.isArray(o.budgetItemIds) || !o.budgetItemIds.length)
+      throw validationError("update-bill payload.budgetItemIds must be a non-empty array.");
+    input.budgetItemIds = o.budgetItemIds.map((id, index) => requiredString(id, `update-bill payload.budgetItemIds[${index}]`));
+  }
+  Object.assign(input, parseQuotationReferences(o, "update-bill"));
+  if (o.lineAmounts !== undefined)
+    input.lineAmounts = parseBillLineAmounts(o, "update-bill");
+  if (o.invoiceDate !== undefined)
+    input.invoiceDate = toDate(o.invoiceDate, "invoiceDate");
+  if (o.verificationStatus !== undefined) {
+    if (!Object.values(BillVerificationStatus).includes(o.verificationStatus))
+      throw validationError("Invalid bill verification status.");
+    input.verificationStatus = o.verificationStatus;
+  }
+  if (o.verificationResults !== undefined) {
+    const value = requireObject(o.verificationResults, "verificationResults");
+    const status = value.status;
+    if (status !== BillVerificationStatus.PENDING && status !== BillVerificationStatus.PASS && status !== BillVerificationStatus.FAIL && status !== BillVerificationStatus.MANUAL_REVIEW)
+      throw validationError("Invalid verificationResults.status.");
+    input.verificationResults = {
+      status,
+      extractedAmount: value.extractedAmount == null ? null : Number(value.extractedAmount),
+      difference: value.difference == null ? null : Number(value.difference),
+      confidence: value.confidence == null ? null : Number(value.confidence),
+      failureReason: value.failureReason == null ? null : String(value.failureReason)
+    };
+  }
+  if (Object.keys(input).length === 1)
+    throw validationError("Supply at least one field to update.");
+  return input;
 }
 function parseValidateBillSelectionPayload(raw, quotationFlags = {}) {
   const input = requireObject(raw, "validate-bill-selection payload");
@@ -7632,21 +7777,21 @@ function parseValidateBillSelectionPayload(raw, quotationFlags = {}) {
   const payloadIds = payloadReferences.quotationIds ?? (payloadReferences.quotationId ? [payloadReferences.quotationId] : undefined);
   const flagIds = flagReferences.quotationIds ?? (flagReferences.quotationId ? [flagReferences.quotationId] : undefined);
   if (payloadIds && flagIds && payloadIds.join("\x00") !== flagIds.join("\x00")) {
-    throw new Error("validate-bill-selection quotation flags conflict with the payload quotation IDs.");
+    throw validationError("validate-bill-selection quotation flags conflict with the payload quotation IDs.");
   }
   const isClaimable = input.isClaimable;
   if (isClaimable !== undefined && typeof isClaimable !== "boolean") {
-    throw new Error("validate-bill-selection payload.isClaimable must be boolean.");
+    throw validationError("validate-bill-selection payload.isClaimable must be boolean.");
   }
   if (isClaimable === true && (payloadReferences.quotationId || (payloadReferences.quotationIds?.length ?? 0) > 0 || (payloadReferences.quotationAllocations?.length ?? 0) > 0 || !!flagReferences.quotationId || (flagReferences.quotationIds?.length ?? 0) > 0)) {
-    throw new Error("Employee claims cannot include quotation source inputs.");
+    throw validationError("Employee claims cannot include quotation source inputs.");
   }
   const lineAmounts = parseBillLineAmounts(input, "validate-bill-selection");
   const budgetItemIds = Array.isArray(input.budgetItemIds) ? input.budgetItemIds.map((id, index) => requiredString(id, `validate-bill-selection payload.budgetItemIds[${index}]`)) : [];
   const amount = input.amount === undefined || input.amount === null ? undefined : Number(input.amount);
   if (lineAmounts || payloadReferences.quotationAllocations) {
     if (amount === undefined || !Number.isFinite(amount) || budgetItemIds.length === 0) {
-      throw new Error("validate-bill-selection explicit allocations require payload.amount and payload.budgetItemIds.");
+      throw validationError("validate-bill-selection explicit allocations require payload.amount and payload.budgetItemIds.");
     }
     validateExplicitBillAllocations({
       amount,
@@ -7669,10 +7814,10 @@ function parseLinkBillQuotationsPayload(billId, raw) {
   const input = requireObject(raw, "link-bill-quotations payload");
   const references = parseQuotationReferences(input, "link-bill-quotations");
   if (references.quotationId) {
-    throw new Error("link-bill-quotations payload uses quotationIds or quotationAllocations; legacy quotationId is not supported.");
+    throw validationError("link-bill-quotations payload uses quotationIds or quotationAllocations; legacy quotationId is not supported.");
   }
   if ((references.quotationIds?.length ?? 0) === 0 && (references.quotationAllocations?.length ?? 0) === 0) {
-    throw new Error("link-bill-quotations payload requires quotationIds or quotationAllocations.");
+    throw validationError("link-bill-quotations payload requires quotationIds or quotationAllocations.");
   }
   return {
     billId: requiredString(billId, "billId"),
@@ -7725,14 +7870,14 @@ function parseUpdateQuotationPayload(raw) {
 var parseCreateCustomerInvoicePayload = (raw) => {
   const input = requireObject(raw, "create-customer-invoice payload");
   if (!Array.isArray(input.splits) || input.splits.length !== 1) {
-    throw new Error("create-customer-invoice payload.splits must contain exactly one invoice.");
+    throw validationError("create-customer-invoice payload.splits must contain exactly one invoice.");
   }
   if (input.isCustomPercentage !== undefined && typeof input.isCustomPercentage !== "boolean") {
-    throw new Error("create-customer-invoice payload.isCustomPercentage must be a boolean.");
+    throw validationError("create-customer-invoice payload.isCustomPercentage must be a boolean.");
   }
   const details = input.details === undefined ? undefined : requireObject(input.details, "invoice details");
   if (details && typeof details.billingAddress !== "string")
-    throw new Error("invoice details.billingAddress must be a string.");
+    throw validationError("invoice details.billingAddress must be a string.");
   return {
     ...input.requestId === undefined ? {} : { requestId: requiredString(input.requestId, "requestId") },
     ...input.invoiceDate === undefined ? {} : { invoiceDate: toDate(input.invoiceDate, "invoiceDate") },
@@ -7748,7 +7893,7 @@ var parseCreateCustomerInvoicePayload = (raw) => {
       const split = requireObject(rawSplit, `create-customer-invoice payload.splits[${index}]`);
       const percentage = Number(split.percentage);
       if (!Number.isFinite(percentage) || percentage <= 0 || percentage > 100 || Math.round(percentage * 100) !== percentage * 100) {
-        throw new Error(`create-customer-invoice payload.splits[${index}].percentage must be between 0.01 and 100 with at most two decimal places.`);
+        throw validationError(`create-customer-invoice payload.splits[${index}].percentage must be between 0.01 and 100 with at most two decimal places.`);
       }
       return {
         dueDate: toDate(split.dueDate, `create-customer-invoice payload.splits[${index}].dueDate`),
@@ -7762,7 +7907,7 @@ function parseUpdateProjectPayload(raw) {
   const o = requireObject(raw, "update-project payload");
   const dr = o.dateRange;
   if (dr === null || typeof dr !== "object" || Array.isArray(dr)) {
-    throw new Error("update-project payload.dateRange must be an object.");
+    throw validationError("update-project payload.dateRange must be an object.");
   }
   const range = dr;
   const notification = o.requestQboAccountantNotification;
@@ -7770,14 +7915,14 @@ function parseUpdateProjectPayload(raw) {
   if (typeof notification === "boolean") {
     requestQboAccountantNotification = notification;
   } else if (notification !== undefined && notification !== null) {
-    throw new Error("update-project payload.requestQboAccountantNotification must be a boolean when set.");
+    throw validationError("update-project payload.requestQboAccountantNotification must be a boolean when set.");
   }
   const estimateInvalidation = o.confirmEstimateInvalidation;
   let confirmEstimateInvalidation;
   if (typeof estimateInvalidation === "boolean") {
     confirmEstimateInvalidation = estimateInvalidation;
   } else if (estimateInvalidation !== undefined && estimateInvalidation !== null) {
-    throw new Error("update-project payload.confirmEstimateInvalidation must be a boolean when set.");
+    throw validationError("update-project payload.confirmEstimateInvalidation must be a boolean when set.");
   }
   const slackChannelId = optionalString(o.slackChannelId);
   const slackChannelUrl = optionalString(o.slackChannelUrl);
@@ -7820,21 +7965,30 @@ function parseSupplierUpdatePayload(raw) {
   requireObject(raw, "update-supplier payload");
   return raw;
 }
-function parseItemCreatePayload(raw) {
-  const input = requireObject(raw, "create-item payload");
+var normalizeItemPayload = (input, command) => {
+  if (typeof input.name === "string") {
+    const invalidCharacters = [
+      ...new Set([...input.name].filter((character) => !/^[A-Za-z0-9,.?@&!#'~* _;+-]$/.test(character)))
+    ];
+    if (invalidCharacters.length > 0) {
+      throw validationError(`${command} payload.name contains characters that are not allowed: ${invalidCharacters.join(" ")}. Allowed: letters, numbers, spaces and , . ? @ & ! # ' ~ * _ ; + -`);
+    }
+  }
+  const normalized = {
+    ...input,
+    ...typeof input.cost === "number" && Number.isFinite(input.cost) ? { cost: String(input.cost) } : {}
+  };
   return normalizePlainTextRichTextField({
-    input,
+    input: normalized,
     textField: "description",
     richTextField: "descriptionRichText"
   });
+};
+function parseItemCreatePayload(raw) {
+  return normalizeItemPayload(requireObject(raw, "create-item payload"), "create-item");
 }
 function parseItemUpdatePayload(raw) {
-  const input = requireObject(raw, "update-item payload");
-  return normalizePlainTextRichTextField({
-    input,
-    textField: "description",
-    richTextField: "descriptionRichText"
-  });
+  return normalizeItemPayload(requireObject(raw, "update-item payload"), "update-item");
 }
 function parseContactCreatePayload(raw) {
   requireObject(raw, "create-contact-person payload");
@@ -8211,10 +8365,10 @@ var formatAsanaCandidateMetadata = (candidate) => {
 };
 var promptForAsanaLeadCandidate = async (candidates) => {
   if (candidates.length === 0) {
-    throw new Error("No open Asana lead tasks were found in the Deals project. Pass --asanaTaskId explicitly or update the Deals project first.");
+    throw new Error("create-project requires an existing Asana deal task in the Deals project; none matched. For a new direct client, create the deal task using the website form first, then pass --asanaTaskId or --asanaSearch. The Slack channel comes from that task.");
   }
   if (!process.stdin.isTTY || !process.stderr.isTTY) {
-    throw new Error("create-project requires --asanaTaskId in non-interactive runs. Interactive runs can omit it to choose from the top Asana lead task matches.");
+    throw new Error("create-project requires an existing Asana deal task: pass --asanaTaskId in non-interactive runs. Create the deal task using the website form first for a new direct client. The Slack channel comes from that task; interactive runs can choose from matching tasks.");
   }
   console.error("Select the Asana lead task to link to this project:");
   candidates.forEach((candidate, index) => {
@@ -8778,6 +8932,42 @@ async function updateBillStatus(opts) {
     } : undefined);
   }
 }
+var listExternalBillPaymentAccounts = async () => {
+  out(await api2.bill.getExternalPaymentAccounts.query());
+};
+var recordExternalBillPayment = async (opts) => {
+  if (!opts.paymentReference.trim() || !opts.paymentAccount.trim() || !/^\d{4}-\d{2}-\d{2}$/.test(opts.paymentDate) || new Date(`${opts.paymentDate}T00:00:00Z`).toISOString().slice(0, 10) !== opts.paymentDate)
+    throw new Error("Supply --paymentReference, --paymentDate YYYY-MM-DD, and --paymentAccount <QBO account ID>.");
+  await assertSensitiveWorkflowConfirmed({
+    action: "Record external payment (no email)",
+    entity: `bill ${opts.id}`,
+    details: `already paid on ${opts.paymentDate}; reference ${opts.paymentReference}; QBO account ${opts.paymentAccount}. No money is transferred.`
+  });
+  const bill = await api2.bill.getById.query({ id: opts.id });
+  const proof = !bill.externalPayment && opts.paymentProofPath ? await stageBillPaymentProof(bill.projectId, opts.paymentProofPath) : undefined;
+  try {
+    out(await api2.bill.recordExternalPayment.mutate({
+      id: opts.id,
+      paymentReference: opts.paymentReference,
+      paymentDate: opts.paymentDate,
+      paymentAccount: opts.paymentAccount,
+      paymentProofAttachments: proof ? [proof] : undefined
+    }));
+  } catch (error) {
+    try {
+      const latest = await api2.bill.getById.query({ id: opts.id });
+      if (latest.externalPayment?.paymentAccount === opts.paymentAccount && latest.paymentReference === opts.paymentReference.trim() && latest.paymentDate?.toISOString().slice(0, 10) === opts.paymentDate) {
+        out({
+          ...latest,
+          supplierNotified: false,
+          quickbooksReconciliationPending: !latest.externalPayment.quickbooksBillPaymentIds.length
+        });
+        return;
+      }
+    } catch {}
+    throw new Error("External payment result could not be confirmed. Inspect the bill, then retry the same reference/date/account; do not pay again. Any uploaded proof is retained.", { cause: error });
+  }
+};
 async function patchBillPayment(opts) {
   const input = { id: opts.id };
   if (opts.paymentTrackingUrl !== undefined)
@@ -9141,7 +9331,15 @@ async function getBudgetDetails(budgetId) {
 }
 async function createBudgetFromPayload(raw) {
   const input = parseCreateBudgetPayload(raw);
-  const result = await api2.budget.createBudget.mutate(input);
+  let result;
+  try {
+    result = await api2.budget.createBudget.mutate(input);
+  } catch (error) {
+    const uncertain = budgetCreateUncertainError(error, input);
+    if (uncertain)
+      throw uncertain;
+    throw error;
+  }
   out(result);
 }
 async function updateBudgetFromPayload(raw) {
@@ -9543,31 +9741,44 @@ async function deleteBillById(id) {
 }
 async function createSupplierFromPayload(raw) {
   const input = parseSupplierCreatePayload(raw);
-  const created = await api2.supplier.createSupplier.mutate(input);
+  await assertSensitiveWorkflowConfirmed({
+    action: "Create supplier and request approval if required",
+    entity: `supplier ${input.name}`,
+    details: "creates the supplier first; pending-approval suppliers also request approval and send emails"
+  });
+  let created;
+  try {
+    created = await api2.supplier.createSupplier.mutate(input);
+  } catch (error) {
+    const normalized = normalizeCliError(error);
+    if (normalized.code !== "NETWORK" && normalized.code !== "API") {
+      throw error;
+    }
+    throw new CliRuntimeError(normalized.code, `Supplier creation outcome is uncertain for ${JSON.stringify(input.name)}. Run list-suppliers and inspect matching supplier details before retrying; names may not be unique, so do not retry create-supplier until you can verify that no supplier was created. Original error: ${normalized.message}`);
+  }
   const supplier = created.result;
   if (supplier.status !== ApprovalStatus.PENDING_APPROVAL) {
     out(created);
     return;
   }
-  await assertSensitiveWorkflowConfirmed({
-    action: "Create supplier approval request",
-    entity: `supplier ${supplier.id}`,
-    details: "and send approval request emails"
-  });
-  const approval = await api2.supplier.createSupplierApproval.mutate({
-    supplierId: supplier.id
-  });
+  let approval;
+  try {
+    approval = await api2.supplier.createSupplierApproval.mutate({
+      supplierId: supplier.id
+    });
+  } catch (error) {
+    throw new CliRuntimeError("API", `Supplier ${supplier.id} was created, but the approval request did not complete or its outcome is uncertain. Run get-supplier-details ${supplier.id} and inspect its approvals before retrying; do not run create-supplier again. Original error: ${normalizeCliError(error).message}`);
+  }
   let emailResult;
   const approvalIds = (approval.results ?? []).map((item) => ({ id: item.id }));
   if (approvalIds.length === 0) {
-    emailResult = createApprovalEmailDeliveryFailure("No approval ids returned");
-  } else {
-    try {
-      const delivery = approval.emailDelivery;
-      emailResult = createApprovalEmailDeliveryReport(delivery);
-    } catch (error) {
-      emailResult = createApprovalEmailDeliveryFailure(error instanceof Error ? error.message : String(error));
-    }
+    throw new CliRuntimeError("API", `Supplier ${supplier.id} was created, but the approval request returned no approval IDs. Run get-supplier-details ${supplier.id} and inspect its approvals before retrying the approval request; do not run create-supplier again.`);
+  }
+  try {
+    const delivery = approval.emailDelivery;
+    emailResult = createApprovalEmailDeliveryReport(delivery);
+  } catch (error) {
+    emailResult = createApprovalEmailDeliveryFailure(error instanceof Error ? error.message : String(error));
   }
   out({
     ...created,
@@ -10312,24 +10523,167 @@ function getFlag(flags, key, parse) {
 // src/parse-json-flag.ts
 function parseJsonFlag(raw, label) {
   if (raw === undefined || raw === "") {
-    throw new Error(`${label} is required (JSON string).`);
+    throw new CliRuntimeError("VALIDATION", `${label} is required (JSON string).`);
   }
   try {
     return JSON.parse(raw);
   } catch {
-    throw new Error(`${label} must be valid JSON.`);
+    throw new CliRuntimeError("VALIDATION", `${label} must be valid JSON.`);
   }
 }
+function parseJsonObjectFlag(raw, label) {
+  const value = parseJsonFlag(raw, label);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliRuntimeError("VALIDATION", `${label} must be a JSON object.`);
+  }
+  return value;
+}
 function parseOptionalNumber(raw, label) {
   if (raw === undefined || raw === "")
     return;
   const n = typeof raw === "number" ? raw : Number.parseFloat(String(raw).trim());
   if (!Number.isFinite(n)) {
-    throw new Error(`${label} must be a number.`);
+    throw new CliRuntimeError("VALIDATION", `${label} must be a number.`);
   }
   return n;
 }
 
+// src/registry/payload-help.ts
+var payloadHelp = {
+  "create-budget": {
+    required: "name: string; budget: decimal string; paymentTerm: string; categoryId: string; projectId: string",
+    optional: "sourceBudgetId: string; unavailableItemReviewAcknowledged: boolean (only after review); pipedriveDealId: string",
+    example: '{"name":"Event budget","budget":"1500","paymentTerm":"Net 30","categoryId":"<category-id>","projectId":"<project-id>"}'
+  },
+  "update-budget": {
+    required: "id: string; name: string; budget: decimal string; paymentTerm: string; categoryId: string; projectId: string",
+    optional: "sourceBudgetId: string; pipedriveDealId: string",
+    example: '{"id":"<budget-id>","name":"Event budget","budget":"1500","paymentTerm":"Net 30","categoryId":"<category-id>","projectId":"<project-id>"}'
+  },
+  "create-item": {
+    required: "name: string (QuickBooks-safe characters); categoryId: string; supplierId: string; cost: decimal string or number",
+    optional: "description: string; gstInclusive: boolean; gstOutOfScope: boolean; goLabsProduct: boolean; attachments: array",
+    example: '{"name":"Event Crew per hour","categoryId":"<category-id>","supplierId":"<supplier-id>","cost":19}'
+  },
+  "update-item": {
+    required: "id: string; name: string; categoryId: string; supplierId: string; cost: decimal string or number",
+    optional: "description: string; gstInclusive: boolean; gstOutOfScope: boolean; goLabsProduct: boolean; attachments: array",
+    example: '{"id":"<item-id>","name":"Event Crew per hour","categoryId":"<category-id>","supplierId":"<supplier-id>","cost":"19"}'
+  },
+  "create-contact-person": {
+    required: "companyId: string; title: MR|MRS|MS|DR; firstName: string; lastName: string|null; email: string; mobile: string",
+    optional: "address: {streetAddress1?, city?, state?, postalCode?, country?}",
+    example: '{"companyId":"<company-id>","title":"MS","firstName":"Jane","lastName":"Tan","email":"jane@example.com","mobile":"+65 9123 4567"}'
+  },
+  "update-contact-person": {
+    required: "id: string; companyId: string; title: MR|MRS|MS|DR; firstName: string; lastName: string|null; email: string; mobile: string",
+    optional: "address: object",
+    example: '{"id":"<contact-id>","companyId":"<company-id>","title":"MS","firstName":"Jane","lastName":"Tan","email":"jane@example.com","mobile":"+65 9123 4567"}'
+  },
+  "update-company": {
+    required: "id: string; name: string; website: URL string",
+    optional: "confirmDistinct: boolean",
+    example: '{"id":"<company-id>","name":"Example Co","website":"https://example.com"}'
+  },
+  "update-project": {
+    required: "id: string; name: string; companyId: string; contactPersonId: string; asanaTaskId: string; insideSalesId: string; businessDevelopmentId: string; venue: string; dateRange: {from: ISO date}",
+    optional: "dateRange.to: ISO date; projectManagerId: string; pax: string; description: string; slackChannelId/slackChannelUrl/slackChannelName: strings (supply all three); requestQboAccountantNotification: boolean; confirmEstimateInvalidation: boolean",
+    example: '{"id":"<project-id>","name":"Launch","companyId":"<company-id>","contactPersonId":"<contact-id>","asanaTaskId":"<asana-task-id>","insideSalesId":"<user-id>","businessDevelopmentId":"<user-id>","venue":"Hall","dateRange":{"from":"2026-10-01T09:00:00Z"}}'
+  },
+  "create-supplier": {
+    required: "name: string; primaryContactPerson: string; email: string; phone: string; paymentMethodId: string; paymentTerm: string; roleId: string",
+    optional: "gstRegistered: boolean; tags: string[]; website: URL string; address: object; attachments: array; bank and PayNow fields",
+    example: '{"name":"Example Supplier","primaryContactPerson":"Jane Tan","email":"jane@example.com","phone":"91234567","paymentMethodId":"<method-id>","paymentTerm":"Net 30","roleId":"<role-id>"}'
+  },
+  "update-supplier": {
+    required: "id: string; name: string; primaryContactPerson: string; email: string; phone: string; paymentMethodId: string; paymentTerm: string; roleId: string",
+    optional: "gstRegistered: boolean; tags: string[]; website: URL string; address: object; attachments: array; bank and PayNow fields",
+    example: '{"id":"<supplier-id>","name":"Example Supplier","primaryContactPerson":"Jane Tan","email":"jane@example.com","phone":"91234567","paymentMethodId":"<method-id>","paymentTerm":"Net 30","roleId":"<role-id>"}'
+  },
+  "update-budget-commission": {
+    required: "budgetId: string; name: string; percentage: decimal string; totalSellingAfterDiscount: number",
+    optional: "none",
+    example: '{"budgetId":"<budget-id>","name":"Sales commission","percentage":"10","totalSellingAfterDiscount":1500}'
+  },
+  "update-budget-discount": {
+    required: "budgetId: string; name: string; type: percentage|amount; value: decimal string; totalSellingBeforeDiscount: number",
+    optional: "none",
+    example: '{"budgetId":"<budget-id>","name":"Discount","type":"amount","value":"100","totalSellingBeforeDiscount":1500}'
+  },
+  "send-estimate-to-contact-person": {
+    required: "estimateId: string; budgetId: string; to: email; cc: email[]; replyTo: email; subject: string; content: HTML string; signature: HTML string",
+    optional: "estimateDocNumber: string",
+    example: '{"estimateId":"<estimate-id>","budgetId":"<budget-id>","to":"client@example.com","cc":[],"replyTo":"team@example.com","subject":"Estimate","content":"<p>Attached estimate</p>","signature":"<p>Team</p>"}'
+  },
+  "create-bill": {
+    required: "budgetId: string; projectId: string; supplierId: string; amount: number (ex-GST); budgetItemIds: string[]; isClaimable: boolean; supplier bills: quotationIds: string[] or quotationAllocations: {budgetItemId, quotationId, amount}[] (unless --quotation-exempt)",
+    optional: "lineAmounts: {budgetItemId, amount}[] (required with quotationAllocations); attachments: {id,name,key,size}[]; invoiceNumber: string; invoiceDate: ISO date; draftOnly: boolean; alreadyPaid: boolean; extractedAmount: number",
+    example: '{"budgetId":"<budget-id>","projectId":"<project-id>","supplierId":"<supplier-id>","amount":1800,"budgetItemIds":["<budget-item-id>"],"isClaimable":false,"quotationIds":["<quotation-id>"],"attachments":[]}'
+  },
+  "update-bill": {
+    required: "id: string; budgetId: string; projectId: string; supplierId: string; amount: number (ex-GST); budgetItemIds: string[]; isClaimable: boolean",
+    optional: "quotationIds: string[]; quotationAllocations: {budgetItemId, quotationId, amount}[]; lineAmounts: {budgetItemId, amount}[]; attachments: {id,name,key,size}[]; invoiceNumber: string; invoiceDate: ISO date",
+    example: '{"id":"<bill-id>","budgetId":"<budget-id>","projectId":"<project-id>","supplierId":"<supplier-id>","amount":1800,"budgetItemIds":["<budget-item-id>"],"isClaimable":false,"quotationIds":["<quotation-id>"],"attachments":[]}'
+  },
+  "validate-bill-selection": {
+    required: "projectId: string; supplierId: string; budgetItemIds: string[]",
+    optional: "quotationIds: string[] for supplier bills; isClaimable: boolean; amount: number; lineAmounts: {budgetItemId, amount}[]; quotationAllocations: {budgetItemId, quotationId, amount}[] (requires amount and lineAmounts)",
+    example: '{"projectId":"<project-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"quotationIds":["<quotation-id>"]}'
+  },
+  "link-bill-quotations": {
+    required: "positional <billId>; quotationIds: string[] or quotationAllocations: {budgetItemId, quotationId, amount}[]",
+    optional: "none (legacy quotationId is not supported)",
+    example: '{"quotationIds":["<quotation-id>"]}'
+  },
+  "update-bill-payment-evidence": {
+    required: "id: string; paymentReference: string; paymentProofAttachments: {id,name (PDF),key,size}[] (at least one)",
+    optional: "none",
+    example: '{"id":"<bill-id>","paymentReference":"TRANSFER-123","paymentProofAttachments":[{"id":"<attachment-id>","name":"receipt.pdf","key":"<staged-key>","size":1000}]}'
+  },
+  "create-quotation": {
+    required: "projectId: string; budgetId: string; supplierId: string; budgetItemIds: string[]; amountWithoutGst: number; gstAmount: number; attachments: array (uploaded attachment)",
+    optional: "lineAmounts: {budgetItemId, amount}[] (required for multiple budget items)",
+    example: '{"projectId":"<project-id>","budgetId":"<budget-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"amountWithoutGst":1200,"gstAmount":0,"attachments":[{"id":"<attachment-id>","name":"quote.pdf","key":"<staged-key>","size":1000}]}'
+  },
+  "update-quotation": {
+    required: "id: string; projectId: string; budgetId: string; supplierId: string; budgetItemIds: string[]; amountWithoutGst: number; gstAmount: number; attachments: array",
+    optional: "lineAmounts: {budgetItemId, amount}[] (required for multiple budget items)",
+    example: '{"id":"<quotation-id>","projectId":"<project-id>","budgetId":"<budget-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"amountWithoutGst":1200,"gstAmount":0,"attachments":[{"id":"<attachment-id>","name":"quote.pdf","key":"<staged-key>","size":1000}]}'
+  },
+  "create-customer-invoice": {
+    required: "budgetId: string; splits: [{label: string, percentage: number, dueDate: ISO date}] (exactly one)",
+    optional: "requestId: UUID string (recommended); invoiceDate: ISO date; details: {billingAddress: string, customerMemo: string}; isCustomPercentage: boolean",
+    example: '{"budgetId":"<budget-id>","splits":[{"label":"Deposit","percentage":50,"dueDate":"2026-10-15"}],"details":{"billingAddress":"1 Example St","customerMemo":"Thanks"}}'
+  },
+  "send-customer-invoice-to-contact-person": {
+    required: "invoiceId: string; to: email; cc: email[]; replyTo: email; subject: string; content: HTML string; signature: HTML string",
+    optional: "none",
+    example: '{"invoiceId":"<invoice-id>","to":"client@example.com","cc":[],"replyTo":"team@example.com","subject":"Invoice","content":"<p>Attached invoice</p>","signature":"<p>Team</p>"}'
+  },
+  "save-inbound-mapping": {
+    required: "positional <sourceId>; payload: [{canonicalField: enum, typeformFieldId: string, required?: boolean, typeformFieldRef?: string|null}] (1-50 entries)",
+    optional: "required defaults false; typeformFieldRef may be omitted",
+    example: '[{"canonicalField":"CONTACT_FIRST_NAME","typeformFieldId":"<typeform-field-id>"}]'
+  },
+  "save-inbound-automation-config": {
+    required: "positional <sourceId>; asanaCustomFields: object; asanaDefaultAssigneeId: string|null; asanaDefaultAssigneeName: string|null; asanaFollowerIds: string[]; asanaProjectId: string; asanaSectionId: string; asanaWonSectionId: string; asanaLostSectionId: string; googleCalendarId: string; googleCalendarTimeZone: string; goshBriefBaseUrl: URL; slackDefaultAssigneeId: string|null; slackInboundChannelId: string; slackInviteUserIds: string[]; slackPitchChannelPrefix: string",
+    optional: "asanaDiscussionSectionId, asanaFirstContactSectionId, asanaFirstProposalSentSectionId, asanaProposalWipSectionId: string|null; asanaCustomFields.*: mapped IDs",
+    example: '{"asanaCustomFields":{},"asanaDefaultAssigneeId":null,"asanaDefaultAssigneeName":null,"asanaFollowerIds":[],"asanaProjectId":"<asana-project-id>","asanaSectionId":"<asana-section-id>","asanaWonSectionId":"<asana-won-id>","asanaLostSectionId":"<asana-lost-id>","googleCalendarId":"team@example.com","googleCalendarTimeZone":"Asia/Singapore","goshBriefBaseUrl":"https://example.com/brief","slackDefaultAssigneeId":null,"slackInboundChannelId":"<slack-channel-id>","slackInviteUserIds":[],"slackPitchChannelPrefix":"pitch"}'
+  }
+};
+var formatPayloadHelp = (command) => {
+  const help = payloadHelp[command];
+  if (!help)
+    return [];
+  return [
+    "Payload fields (--payload JSON)",
+    `  Required: ${help.required}`,
+    `  Optional: ${help.optional}`,
+    `  Example: bb ${command}${command === "link-bill-quotations" ? " <billId>" : command.startsWith("save-inbound-") ? " <sourceId>" : ""} --payload '${help.example}'`,
+    ""
+  ];
+};
+
 // src/registry/index.ts
 var globalCommandOptions = [
   { name: "--help", description: "Show help for this command." },
@@ -10380,6 +10734,7 @@ var mutationPrefixes = [
   "patch-",
   "reactivate-",
   "reconcile-",
+  "record-",
   "reject-",
   "remove-",
   "replace-",
@@ -10420,6 +10775,7 @@ var emailTargets = new Set([
   "update-supplier"
 ]);
 var externalWriteTargets = new Set([
+  "record-external-bill-payment",
   "approve-bill",
   "approve-customer-invoice",
   "approve-supplier",
@@ -10465,6 +10821,7 @@ var externalWriteTargets = new Set([
   "void-customer-invoice"
 ]);
 var financialWriteTargets = new Set([
+  "record-external-bill-payment",
   "import-qbo-customer-invoice",
   "link-bill-quotations",
   "approve-bill",
@@ -10530,6 +10887,8 @@ var summaryFor = (legacyTarget) => {
     return "Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.";
   if (legacyTarget === "create-company")
     return "Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.";
+  if (legacyTarget === "create-project")
+    return "Create a project linked to an existing Asana Deals lead task. Supply --asanaTaskId in non-interactive use; interactive use searches for and selects a lead task (optionally --asanaSearch). The Slack channel is resolved from the selected Asana task unless all three Slack channel flags are supplied. For a new direct client, create the lead task using the website form first.";
   if (legacyTarget === "preview-qbo-customer-invoice") {
     return "Preview an available QuickBooks invoice selected for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.";
   }
@@ -10547,8 +10906,12 @@ var summaryFor = (legacyTarget) => {
   if (legacyTarget === "create-bill") {
     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 === "record-external-bill-payment")
+    return "Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.";
+  if (legacyTarget === "list-external-payment-accounts")
+    return "List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).";
   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.";
+    return "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.";
   }
   if (legacyTarget === "validate-bill-selection") {
     return "Validate the approved supplier and selected bill line items.";
@@ -10587,6 +10950,20 @@ var legacyCommand = (legacyTarget, path, aliases = [], commandOptions = []) => (
   effects: effectsFor(legacyTarget),
   legacyTarget
 });
+var budgetPreflightOptions = [
+  {
+    name: "--companyPayload <json>",
+    description: "Company update JSON object with id, name, and website fields."
+  },
+  {
+    name: "--contactPayload <json>",
+    description: "Contact update JSON object with companyId, title, firstName, lastName, email, and mobile fields."
+  },
+  {
+    name: "--eventPayload <json>",
+    description: "Event timing JSON object with date, startTime, and endTime fields."
+  }
+];
 var authCommand = (action, summary) => ({
   path: ["auth", action],
   legacyAliases: [],
@@ -10611,8 +10988,8 @@ var registry2 = [
   legacyCommand("rename-budget-version", ["budget", "version", "rename"]),
   legacyCommand("restore-budget-version", ["budget", "version", "restore"]),
   legacyCommand("update-budget-status", ["budget", "status", "update"]),
-  legacyCommand("create-budget-approval", ["budget", "approval", "create"]),
-  legacyCommand("create-estimate", ["budget", "estimate", "create"]),
+  legacyCommand("create-budget-approval", ["budget", "approval", "create"], [], budgetPreflightOptions),
+  legacyCommand("create-estimate", ["budget", "estimate", "create"], [], budgetPreflightOptions),
   legacyCommand("send-estimate-to-contact-person", ["budget", "estimate", "send"], ["send-estimate-email"]),
   legacyCommand("create-budget", ["budget", "create"]),
   legacyCommand("update-budget", ["budget", "update"]),
@@ -10694,6 +11071,16 @@ var registry2 = [
   ]),
   legacyCommand("delete-bill", ["bill", "delete"]),
   legacyCommand("update-bill-status", ["bill", "status", "update"]),
+  legacyCommand("record-external-bill-payment", [
+    "bill",
+    "payment",
+    "record-external"
+  ]),
+  legacyCommand("list-external-payment-accounts", [
+    "bill",
+    "payment",
+    "accounts"
+  ]),
   legacyCommand("patch-bill-payment", ["bill", "payment", "patch"]),
   legacyCommand("patch-bill-invoice-number", [
     "bill",
@@ -11046,6 +11433,7 @@ var createHumanHelp = (command) => {
       ...command.options.map((option) => `  ${option.name}
     ${option.description}`),
       "",
+      ...formatPayloadHelp(command.legacyTarget ?? ""),
       "Use `bb help --legacy` for additional command arguments."
     ].join(`
 `);
@@ -11932,9 +12320,9 @@ Waiting for approval\u2026
         const contactPayloadRaw = getFlag(flags, "contactPayload");
         const eventPayloadRaw = getFlag(flags, "eventPayload");
         await createBudgetApproval(id, {
-          company: companyPayloadRaw !== undefined ? parseJsonFlag(String(companyPayloadRaw), "--companyPayload") : undefined,
-          contactPerson: contactPayloadRaw !== undefined ? parseJsonFlag(String(contactPayloadRaw), "--contactPayload") : undefined,
-          eventDetails: eventPayloadRaw !== undefined ? parseJsonFlag(String(eventPayloadRaw), "--eventPayload") : undefined
+          company: companyPayloadRaw !== undefined ? parseJsonObjectFlag(String(companyPayloadRaw), "--companyPayload") : undefined,
+          contactPerson: contactPayloadRaw !== undefined ? parseJsonObjectFlag(String(contactPayloadRaw), "--contactPayload") : undefined,
+          eventDetails: eventPayloadRaw !== undefined ? parseJsonObjectFlag(String(eventPayloadRaw), "--eventPayload") : undefined
         });
         break;
       }
@@ -11946,9 +12334,9 @@ Waiting for approval\u2026
         const contactPayloadRaw = getFlag(flags, "contactPayload");
         const eventPayloadRaw = getFlag(flags, "eventPayload");
         await createEstimate(id, {
-          company: companyPayloadRaw !== undefined ? parseJsonFlag(String(companyPayloadRaw), "--companyPayload") : undefined,
-          contactPerson: contactPayloadRaw !== undefined ? parseJsonFlag(String(contactPayloadRaw), "--contactPayload") : undefined,
-          eventDetails: eventPayloadRaw !== undefined ? parseJsonFlag(String(eventPayloadRaw), "--eventPayload") : undefined
+          company: companyPayloadRaw !== undefined ? parseJsonObjectFlag(String(companyPayloadRaw), "--companyPayload") : undefined,
+          contactPerson: contactPayloadRaw !== undefined ? parseJsonObjectFlag(String(contactPayloadRaw), "--contactPayload") : undefined,
+          eventDetails: eventPayloadRaw !== undefined ? parseJsonObjectFlag(String(eventPayloadRaw), "--eventPayload") : undefined
         });
         break;
       }
@@ -12269,6 +12657,27 @@ Waiting for approval\u2026
         });
         break;
       }
+      case "list-external-payment-accounts": {
+        await listExternalBillPaymentAccounts();
+        break;
+      }
+      case "record-external-bill-payment": {
+        const id = positional[0];
+        const paymentReference = getFlag(flags, "paymentReference");
+        const paymentDate = getFlag(flags, "paymentDate");
+        const paymentAccount = getFlag(flags, "paymentAccount");
+        const paymentProofPath = getFlag(flags, "paymentProof");
+        if (!id || !paymentReference || !paymentDate || !paymentAccount)
+          throw new Error("record-external-bill-payment requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]");
+        await recordExternalBillPayment({
+          id,
+          paymentReference,
+          paymentDate,
+          paymentAccount,
+          paymentProofPath
+        });
+        break;
+      }
       case "patch-bill-payment": {
         const id = positional[0];
         if (!id)