@go-labs-sg/bb 1.20.0 → 2.0.0

package/dist/runtime/confirmation.js

@@ -0,0 +1,76 @@
+import { CliRuntimeError } from "./error.js";
+const effectLabels = {
+    "state-change": "changes Budget Builder state",
+    email: "sends email",
+    "external-write": "writes to an external system",
+    delete: "deletes data",
+    "financial-write": "creates or changes financial records",
+};
+const isEffectAllowed = (effect, permissions) => {
+    switch (effect) {
+        case "state-change":
+            return permissions.allowStateChange === true;
+        case "email":
+            return permissions.allowEmail === true;
+        case "external-write":
+            return permissions.allowExternalWrite === true;
+        case "delete":
+            return permissions.allowDelete === true;
+        case "financial-write":
+            return permissions.allowFinancialWrite === true;
+    }
+};
+const uniqueEffects = (effects) => [...new Set(effects)];
+export const getRequiredEffectPermissions = (effects, permissions) => uniqueEffects(effects).filter((effect) => !isEffectAllowed(effect, permissions));
+export const formatConfirmationPreview = (request) => [
+    "Budget Builder workflow preview",
+    `Action: ${request.action}`,
+    `Target: ${request.target?.trim() || "not specified"}`,
+    `Effects: ${uniqueEffects(request.effects)
+        .map((effect) => effectLabels[effect])
+        .join("; ") || "none"}`,
+    ...(request.details === undefined ? [] : [`Details: ${request.details}`]),
+].join("\n");
+export const confirmSensitiveCommand = async (runtime, request) => {
+    const requiredPermissions = getRequiredEffectPermissions(request.effects, request.permissions);
+    if (request.effects.length === 0) {
+        return { confirmed: true, requiredPermissions };
+    }
+    const target = request.target?.trim();
+    if (!runtime.isTTY) {
+        if (target === undefined) {
+            throw new CliRuntimeError("CONFIRMATION_REQUIRED", "Non-interactive sensitive commands require an explicit target.", {
+                details: {
+                    action: request.action,
+                    effects: requiredPermissions,
+                    missingFlags: requiredPermissions.map((effect) => `--allow-${effect}`),
+                    target: "required",
+                },
+            });
+        }
+        if (requiredPermissions.length === 0) {
+            return { confirmed: true, requiredPermissions };
+        }
+        const missing = requiredPermissions.map((effect) => `--allow-${effect}`);
+        throw new CliRuntimeError("CONFIRMATION_REQUIRED", "Non-interactive sensitive commands require an explicit target and all applicable allow flags.", {
+            details: {
+                action: request.action,
+                effects: requiredPermissions,
+                missingFlags: missing,
+            },
+        });
+    }
+    if (requiredPermissions.length === 0) {
+        return { confirmed: true, requiredPermissions };
+    }
+    const preview = formatConfirmationPreview(request);
+    runtime.stderr.write(`${preview}\n`);
+    if (runtime.prompt === undefined) {
+        throw new CliRuntimeError("CONFIRMATION_REQUIRED", "This command needs an interactive confirmation prompt.");
+    }
+    const answer = await runtime.prompt("Type CONFIRM to continue: ");
+    if (answer !== "CONFIRM") {
+        throw new CliRuntimeError("ABORTED", "Command aborted by user.");
+    }
+    return { confirmed: true, preview, requiredPermissions };
+};

package/dist/runtime/error.js

@@ -0,0 +1,143 @@
+const invocationErrorCodes = new Set([
+    "USAGE",
+    "VALIDATION",
+    "CONFIRMATION_REQUIRED",
+]);
+const 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",
+};
+const cliErrorCodes = new Set([
+    "USAGE",
+    "VALIDATION",
+    "CONFIRMATION_REQUIRED",
+    "AUTHENTICATION",
+    "AUTHORIZATION",
+    "NOT_FOUND",
+    "CONFLICT",
+    "API",
+    "NETWORK",
+    "ABORTED",
+    "INTERRUPTED",
+    "INTERNAL",
+]);
+export 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;
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const asNonEmptyString = (value) => typeof value === "string" && value.trim() !== "" ? value : undefined;
+const asDetails = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const details = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+        if (isJsonValue(nestedValue))
+            details[key] = nestedValue;
+    }
+    return Object.keys(details).length > 0 ? details : undefined;
+};
+const 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);
+};
+const mapErrorCode = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    if (cliErrorCodes.has(value))
+        return value;
+    if (value in trpcCodeMap)
+        return trpcCodeMap[value];
+    return undefined;
+};
+const networkMessagePattern = /\b(fetch failed|network error|unable to connect|econnrefused|econnreset|enotfound|etimedout|socket hang up)\b/i;
+const 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);
+};
+/**
+ * Maps local errors and the common tRPC client error shape into the stable
+ * CLI contract without importing a transport-specific error class.
+ */
+export const 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." };
+};
+export const exitCodeForCliError = (error) => {
+    if (error.code === "INTERRUPTED")
+        return 130;
+    return invocationErrorCodes.has(error.code) ? 2 : 1;
+};

package/dist/runtime/index.js

@@ -0,0 +1,6 @@
+export { confirmSensitiveCommand, formatConfirmationPreview, getRequiredEffectPermissions, } from "./confirmation.js";
+export { CliRuntimeError, exitCodeForCliError, normalizeCliError, } from "./error.js";
+export { createSuccessEnvelope, emitCliDiagnostic, emitCliError, emitCliSuccess, } from "./output.js";
+export { createProcessRuntime } from "./process-runtime.js";
+export { sanitizeCliDiagnostic, sanitizeCliValue } from "./sanitize.js";
+export { clearActiveCliSession, confirmCurrentCommand, emitCommandError, emitCommandResult, getActiveCliSession, setActiveCliSession, } from "./session.js";

package/dist/runtime/output.js

@@ -0,0 +1,36 @@
+import { exitCodeForCliError, normalizeCliError } from "./error.js";
+import { sanitizeCliDiagnostic } from "./sanitize.js";
+const serialize = (value) => `${JSON.stringify(value, null, 2)}\n`;
+export const createSuccessEnvelope = (data, invocation) => ({
+    ok: true,
+    data,
+    meta: {
+        command: invocation.command,
+        cliVersion: invocation.cliVersion,
+        apiBaseUrl: invocation.apiBaseUrl,
+    },
+});
+export const emitCliSuccess = (runtime, invocation, data) => {
+    runtime.stdout.write(serialize(invocation.legacy ? data : createSuccessEnvelope(data, invocation)));
+    return 0;
+};
+export const emitCliError = (runtime, invocation, error) => {
+    const normalized = normalizeCliError(error);
+    if (invocation.legacy) {
+        runtime.stderr.write(serialize({ error: normalized.message }));
+    }
+    else {
+        const envelope = {
+            ok: false,
+            error: normalized,
+            meta: { command: invocation.command },
+        };
+        runtime.stderr.write(serialize(envelope));
+    }
+    return exitCodeForCliError(normalized);
+};
+export const emitCliDiagnostic = (runtime, invocation, diagnostic) => {
+    if (invocation.quiet || !invocation.debug)
+        return;
+    runtime.stderr.write(serialize(sanitizeCliDiagnostic(diagnostic)));
+};

package/dist/runtime/process-runtime.js

@@ -0,0 +1,28 @@
+import { createInterface } from "node:readline/promises";
+export const createProcessRuntime = () => ({
+    stdout: {
+        write: (value) => {
+            process.stdout.write(value);
+        },
+    },
+    stderr: {
+        write: (value) => {
+            process.stderr.write(value);
+        },
+    },
+    isTTY: Boolean(process.stdin.isTTY && process.stderr.isTTY),
+    env: process.env,
+    prompt: async (message) => {
+        const prompt = createInterface({
+            input: process.stdin,
+            output: process.stderr,
+        });
+        try {
+            return await prompt.question(message);
+        }
+        finally {
+            prompt.close();
+        }
+    },
+    now: () => new Date(),
+});

package/dist/runtime/sanitize.js

@@ -0,0 +1,50 @@
+const sensitiveKeys = new Set([
+    "apikey",
+    "authorization",
+    "bb_api_key",
+    "password",
+    "paymentproof",
+    "paymentproofattachments",
+    "paymentproofpath",
+    "paymentreference",
+    "payload",
+    "proof",
+    "receipt",
+    "secret",
+    "token",
+]);
+const isPresignedUrl = (value) => typeof value === "string" &&
+    (/[?&]X-Amz-(?:Algorithm|Credential|Signature)=/i.test(value) ||
+        /[?&]X-Goog-(?:Algorithm|Credential|Signature)=/i.test(value));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const sanitizeCliValue = (value, seen = new WeakSet()) => {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        typeof value === "number") {
+        return isPresignedUrl(value) ? "[redacted]" : value;
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value !== "object" || value === null)
+        return String(value);
+    if (seen.has(value))
+        return "[circular]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeCliValue(item, seen));
+    }
+    if (!isRecord(value))
+        return String(value);
+    return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        sensitiveKeys.has(key.toLowerCase()) ||
+            key.toLowerCase().includes("secret") ||
+            key.toLowerCase().includes("password")
+            ? "[redacted]"
+            : sanitizeCliValue(nestedValue, seen),
+    ]));
+};
+export const sanitizeCliDiagnostic = (diagnostic) => sanitizeCliValue(diagnostic);

package/dist/runtime/session.js

@@ -0,0 +1,50 @@
+import { confirmSensitiveCommand } from "./confirmation.js";
+import { emitCliError, emitCliSuccess } from "./output.js";
+let activeSession;
+export const setActiveCliSession = (session) => {
+    activeSession = {
+        ...session,
+        confirmedEffects: new Set(),
+    };
+};
+export const clearActiveCliSession = () => {
+    activeSession = undefined;
+};
+export const getActiveCliSession = () => activeSession;
+const requireSession = () => {
+    if (activeSession === undefined) {
+        throw new Error("Budget Builder CLI runtime session is not configured.");
+    }
+    return activeSession;
+};
+const toJsonValue = (value) => {
+    const serialized = JSON.stringify(value, (_key, nestedValue) => typeof nestedValue === "bigint" ? nestedValue.toString() : nestedValue);
+    if (serialized === undefined)
+        return null;
+    return JSON.parse(serialized);
+};
+export const emitCommandResult = (data) => {
+    const session = requireSession();
+    return emitCliSuccess(session.runtime, session.invocation, toJsonValue(data));
+};
+export const emitCommandError = (error) => {
+    const session = requireSession();
+    return emitCliError(session.runtime, session.invocation, error);
+};
+export const confirmCurrentCommand = async (input) => {
+    const session = requireSession();
+    const effects = input.effects ?? session.effects;
+    const unconfirmedEffects = effects.filter((effect) => !session.confirmedEffects.has(effect));
+    if (unconfirmedEffects.length === 0)
+        return;
+    await confirmSensitiveCommand(session.runtime, {
+        action: input.action,
+        target: input.target,
+        details: input.details,
+        effects: unconfirmedEffects,
+        permissions: session.permissions,
+    });
+    for (const effect of unconfirmedEffects) {
+        session.confirmedEffects.add(effect);
+    }
+};

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,44 +1,38 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "1.20.0",
-  "description": "Budget Builder CLI for AI agents — manage budgets, bills, and claims; bill records use isClaimable=false for bills and isClaimable=true for claims.",
+  "version": "2.0.0",
+  "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./command-manifest": "./command-manifest.json"
+  },
   "bin": {
     "bb": "./dist/index.js"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "role-aware-agent-guide.md",
+    "command-reference.md",
+    "command-manifest.json"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "check": "biome check .",
-    "check:write": "biome check --write .",
-    "run": "bun run src/index.ts",
-    "prepack": "node scripts/strip-workspace-deps.js && bun run build",
-    "postpack": "node scripts/restore-package-json.js"
-  },
   "dependencies": {
     "@trpc/client": "^11.18.0",
     "dotenv": "^17.4.2",
     "mime-types": "^3.0.2",
     "superjson": "^2.2.6"
   },
-  "devDependencies": {
-    "@types/mime-types": "^3.0.1",
-    "typescript": "^6.0.3"
-  },
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/go-labs-sg/budget-builder",
-    "directory": "packages/cli"
+    "url": "https://github.com/go-labs-sg/go-labs.git",
+    "directory": "packages/budget-builder/cli"
   }
 }

package/role-aware-agent-guide.md

@@ -0,0 +1,169 @@
+# Role-aware Budget Builder CLI guide for agents
+
+This guide explains how an AI agent should choose Budget Builder CLI commands for the identity behind `BB_API_KEY`. It complements [`bb help`](./README.md#command-overview), which lists commands and arguments but intentionally does not decide authorization on the client. Version 2 documents grouped resource commands (for example, `bb budget get <budget-id>`); flat and `snake_case` commands remain compatibility aliases during the v2 transition.
+
+## Mandatory preflight
+
+Run these commands at the beginning of every agent session and after replacing `BB_API_KEY`:
+
+```bash
+bb version
+bb auth whoami
+```
+
+Keep the returned `id`, `email`, and `role` in the working context. Before any mutation, state which identity will perform it. A safe agent summary is:
+
+> Authenticated as `<name> <email>` with role `<role>`. I will use only operations allowed for this identity and for resources it owns, is assigned to, or is recorded to approve.
+
+Never infer authority from a person's job title, email address, API-key label, or the fact that a command appears in `bb help`.
+
+## How authorization is decided
+
+The Budget Builder API, not the CLI, makes the final decision. A request may need all of the following:
+
+1. An active API key and user account.
+2. A sufficient current database role: `USER`, `INSIDE_SALES`, `LEAD`, `ACCOUNTING_TEAM`, or `ADMIN`. Pending approval assignment does not preserve decision authority after a role change.
+3. Access to the specific resource, commonly through creator ownership or project assignment as Business Development, Inside Sales, or Project Manager.
+4. A compatible resource state, such as a bill being `DRAFT` or `REJECTED` before editing.
+5. A pending approval record assigned to the current user for approval decisions.
+6. Required evidence and consistent related records, such as payment proof, approved quotation coverage, or matching project/budget IDs.
+
+Therefore, two users with the same role can receive different results for the same command and different resource IDs.
+
+## Role guide
+
+### `USER`
+
+Use base-user credentials for ordinary, attributable work. Typical operations include:
+
+- `bb auth whoami` and managing the current user's own API keys with `bb user api-key ...`.
+- Collaboration endpoints intentionally shared with every authenticated role, including company, contact, and project creation/update.
+- Creating claims and creating supplier bills when project access and validation permit it.
+- Creating and maintaining the user's own draft/rejected quotations and bills.
+- Working on budgets the user created or whose project assigns that user.
+- Requesting approval after inspecting the entity and obtaining user confirmation.
+
+Shared collaboration endpoints are explicit API exceptions, not a general grant over every resource. Do not attempt admin analytics, error logs, integration recovery, user provisioning, cross-user API-key management, final payment actions, or approval decisions.
+
+### `INSIDE_SALES`
+
+Apply the `USER` rules, plus the supplier access and assigned project/budget responsibilities granted to Inside Sales. This role can participate in supplier approval-request flows and has broader supplier access than a base user.
+
+Do not treat Inside Sales as Lead or Admin. Budget and supplier decisions still follow the recorded approval chain, and all project assignment and state checks remain active.
+
+### `LEAD`
+
+Apply the base resource rules, plus Lead-stage budget and supplier workflows. Lead-created suppliers are auto-approved, and Leads can handle budget/supplier approvals that the API assigns to them.
+
+Do not use Lead credentials for Admin-only dashboards, user/service-identity administration, errors, integration retries, final bill payment, or admin customer-invoice actions.
+
+### `ACCOUNTING_TEAM`
+
+Use this role for finance-stage bill work. Typical additional operations include:
+
+- Moving an eligible bill to `CHECKED`.
+- Acting on bill approval records assigned to this accounting user.
+- Correcting allowed paid-bill metadata with `bb bill payment patch`.
+- Correcting a bill invoice number with `bb bill invoice-number patch`.
+
+The role does not grant the direct Admin-only `APPROVED` or `PAID` status changes. It also does not grant user administration, system dashboards/errors/integration recovery, or Admin-only customer-invoice payment actions.
+
+### `ADMIN`
+
+Admin credentials may perform global and final-control operations, including:
+
+- `bb user create` for API-only service identities.
+- Cross-user `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` with `--userId`.
+- Global dashboard/performance, error-log, and integration-operation commands.
+- Admin-only supplier/category recovery and archive operations.
+- Final bill approval/payment and Admin customer-invoice decisions/payment.
+
+Admin is not a force flag. State transitions, evidence, consistency checks, external-operation locks, and interactive confirmation rules still apply.
+
+## Common command gates
+
+This table highlights the role-sensitive command groups an agent is most likely to confuse. It is not exhaustive, and the resource/state checks described above still apply.
+
+| Commands or action | Required identity condition |
+| --- | --- |
+| `bb auth whoami`; own `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` | Any active role; omit `--userId` to act as the current user. |
+| Cross-user API-key commands; `bb user create` | `ADMIN`. |
+| Budget/project mutations, estimates, and budget attachments | `ADMIN`, budget creator, or project assignment as Business Development, Inside Sales, or Project Manager, depending on the endpoint. |
+| Edit/delete a bill or quotation | Usually creator or `ADMIN`, with a supported status. |
+| `bb budget approve`, `bb budget reject`, `bb supplier approve`, and `bb supplier reject` | Current user must be the pending approver and currently have role `LEAD` or `ADMIN`. |
+| `bb bill approve` and `bb bill reject` | Current user must be the pending approver and currently have role `ACCOUNTING_TEAM` for the finance/check stage or `ADMIN` for the final approval stage. |
+| `bb quotation approve` and `bb quotation reject` | Current user must be the pending approver and currently have role `ADMIN`; a normal submitter cannot decide the quotation. |
+| `bb bill status update ... CHECKED` | `ACCOUNTING_TEAM` or `ADMIN`. |
+| `bb bill status update ... APPROVED` or `... PAID` | `ADMIN`; state, integration, payment-reference, and payment-proof requirements still apply. |
+| `bb bill payment patch`; `bb bill invoice-number patch` | `ACCOUNTING_TEAM` or `ADMIN`, with the procedure's bill-state constraints. |
+| `bb customer-invoice approve` and `bb customer-invoice reject` | `ADMIN` batch operations selected by batch ID; the API resolves the internal pending Admin approval record. |
+| `bb customer-invoice payment mark-paid` | `ADMIN`. |
+| Dashboard/performance, supplier analytics, errors, integration operations | `ADMIN`. |
+| `bb item category create`, `bb item category update`, `bb item category delete`, `bb supplier delete`, `bb supplier reactivate`, and `bb budget item placeholder-bill create` | `ADMIN`. |
+
+## Command-selection rules
+
+Use this sequence for every task:
+
+1. Run `bb auth whoami` and classify the identity using the role guide above.
+2. Start with a read command for the exact target, such as `bb budget get`, `bb bill get`, `bb quotation get`, or `bb customer-invoice get`.
+3. Confirm creator, project assignments, status, and pending approver information from the returned data when available.
+4. Compare the intended command with both the role and resource conditions.
+5. Before every mutation, explain the exact target and side effects and wait for explicit user confirmation.
+6. In an interactive terminal, review the CLI preview and type the exact `CONFIRM` only when it matches the user's approved action. In non-interactive use, supply every effect guard declared for the command: `--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and/or `--allow-financial-write`.
+7. Execute once, then verify the returned JSON or re-read the resource.
+
+The granular flags acknowledge specific runtime effects; they never grant role or resource authorization and never replace the user's explicit confirmation. If the CLI reports a missing effect flag, stop and reassess the preview instead of adding broad flags automatically.
+
+The following distinctions are especially important:
+
+- `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` default to the current user for every role; targeting someone else with `--userId` is Admin-only.
+- Budget, supplier, bill, and quotation decisions require both the matching live role and a pending approval assigned to the current identity. Customer-invoice approve/reject are Admin batch operations selected by batch ID; the API resolves their internal approval record.
+- Some company, contact, project, supplier, and catalog collaboration procedures intentionally allow every active authenticated role. Treat these endpoint-specific rules as exceptions rather than inferring access to adjacent mutations.
+- Budget and project commands often depend on creator/assignment access even when the role itself is valid.
+- Bill/claim status commands have separate role rules for `CHECKED`, `APPROVED`, and `PAID`.
+- `bb bill create --payload` uses `isClaimable=false`; `isClaimable=true` creates a claim. Claims intentionally permit some base-user flows that supplier bills do not.
+- Staged attachments belong to the user in the database. Do not reuse, share, or manually construct staged keys.
+
+## Handling authorization failures
+
+On `FORBIDDEN`:
+
+1. Stop the attempted workflow.
+2. Report the command and target resource.
+3. Include the `whoami` `id`, `email`, and `role` without exposing the API key.
+4. Explain the likely missing role, creator ownership, project assignment, or pending-approver record.
+5. Ask the user whether the resource assignment or operating identity should change.
+
+Do not retry with lower-level upload/request procedures, direct tRPC paths, a different API key, or repeated calls. A CLI denial is an API authorization result, not a client limitation to work around.
+
+On `BAD_REQUEST` or `CONFLICT`, re-read the resource before deciding whether to retry. These responses commonly indicate an invalid state transition, stale data, missing evidence, or an integration operation already in progress.
+
+## Safe examples
+
+Base user preparing a claim:
+
+```bash
+bb auth whoami
+bb project get <project-id>
+bb bill attachment stage <project-id> <receipt.pdf>
+bb bill create --payload '<claim-json-with-isClaimable-true>'
+```
+
+Accounting user processing a bill:
+
+```bash
+bb auth whoami
+bb bill get <bill-id>
+bb bill status update <bill-id> CHECKED
+```
+
+Admin inspecting a failed integration before a confirmed retry:
+
+```bash
+bb auth whoami
+bb integration operation list --status FAILED
+bb integration operation retry <operation-id>
+```
+
+The mutation and retry examples remain subject to explicit user approval and the effect-aware runtime rules above: exact `CONFIRM` interactively, or every applicable granular `--allow-*` flag in non-interactive use.