@indigoai-us/hq-cli 5.345.142 → 5.345.144

package/dist/command-catalog.generated.js

@@ -2902,6 +2902,16 @@ export const COMMAND_CATALOG = [
                         "flags": "--expires <ISO8601>",
                         "description": "Optional ISO-8601 expiry timestamp",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--preset <name>",
+                        "description": "Grant a fixed capability bundle: library-agent (library-agent = search:query, files:read)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--allow-upload",
+                        "description": "With --preset library-agent, also grant files:write (hq library add)",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -7811,7 +7821,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--size <size>",
-                        "description": "Agent box size: basic | power | dev (omitted keeps the current default)",
+                        "description": "Agent box size: small | medium | large | xlarge, or basic | power | dev (on usage pricing these map to small | medium | large); omitted keeps the current default",
                         "hidden": false
                     },
                     {
@@ -9008,7 +9018,7 @@ export const COMMAND_CATALOG = [
                             },
                             {
                                 "flags": "--cron <expr>",
-                                "description": "Recurring schedule, such as rate(1 day) or a cron expression",
+                                "description": "Recurring schedule: rate(N minutes|hours|days), a five-field cron with * for day of month and month (such as \"*/15 * * * *\"; translated to the AWS form), or cron(MIN HOUR ? * DOW *)",
                                 "hidden": false
                             },
                             {
@@ -9265,6 +9275,11 @@ export const COMMAND_CATALOG = [
                         "description": "Outpost id (defaults to your primary box)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Request a new sign-in link for the company's Outpost (owner or admin)",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "Emit raw JSON",
@@ -9296,6 +9311,11 @@ export const COMMAND_CATALOG = [
                         "description": "Outpost id (defaults to your primary box)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Sign in the company's Outpost (owner or admin)",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "Emit raw JSON",
@@ -9403,7 +9423,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "upgrade",
-                "description": "Open Stripe Checkout to upgrade this company to HQ Workforce ($500/mo)",
+                "description": "Open Stripe Checkout to upgrade a company on an earlier plan (usage-pricing companies have no plan to upgrade)",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -9432,7 +9452,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "sponsor",
-                "description": "Ask a company to cover your $50 plan, or answer a request",
+                "description": "Ask a company to cover your personal HQ plan, or answer a request",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -9444,7 +9464,7 @@ export const COMMAND_CATALOG = [
                 "subcommands": [
                     {
                         "name": "request",
-                        "description": "Ask a company to cover your $50 HQ plan",
+                        "description": "Ask a company to cover your personal HQ plan",
                         "aliases": [],
                         "hidden": false,
                         "helpOption": true,
@@ -9494,7 +9514,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "name": "approve",
-                        "description": "Say yes — put someone's $50 plan on the company bill",
+                        "description": "Say yes — put someone's personal plan on the company bill",
                         "aliases": [],
                         "hidden": false,
                         "helpOption": true,
@@ -9597,6 +9617,50 @@ export const COMMAND_CATALOG = [
                         "subcommands": []
                     }
                 ]
+            },
+            {
+                "name": "usage",
+                "description": "Show this month's usage, projected bill, included usage left and what drives it (read-only)",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "One of your companies (default: your only company)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--personal",
+                        "description": "Your personal HQ instead of a company",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--no-storage-scan",
+                        "description": "Skip listing cloud file versions (faster; no old-versions split)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--fresh",
+                        "description": "List cloud file versions live instead of using figures from the last 15 minutes",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--card",
+                        "description": "Print the usage price card (meters, included usage, trial, boxes, domains) and exit",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
             }
         ]
     },
@@ -12013,6 +12077,277 @@ export const COMMAND_CATALOG = [
             }
         ]
     },
+    {
+        "name": "library",
+        "description": "Company media library (.hqcloud asset placeholders)",
+        "aliases": [],
+        "hidden": false,
+        "helpOption": true,
+        "helpCommand": true,
+        "usage": "[options] [command]",
+        "helpText": [],
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "search",
+                "description": "Search library assets in the cloud, falling back to the local index when offline",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] [query...]",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "query",
+                        "required": false,
+                        "variadic": true,
+                        "description": "Query terms (joined with spaces)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--tag <tag>",
+                        "description": "Require a tag (repeatable or comma-separated)",
+                        "hidden": false,
+                        "defaultValue": []
+                    },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Restrict to one company",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "-n, --count <count>",
+                        "description": "Maximum result count",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "add",
+                "description": "Upload files or URLs to the company vault and add .hqcloud placeholders to the library",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <sources...>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "sources",
+                        "required": true,
+                        "variadic": true,
+                        "description": "Local files or http(s) URLs"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--to <dir>",
+                        "description": "Library folder inside companies/<co>/ (default companies/<co>/library)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--tags <tags>",
+                        "description": "Tags (comma-separated, repeatable)",
+                        "hidden": false,
+                        "defaultValue": []
+                    },
+                    {
+                        "flags": "--title <title>",
+                        "description": "Asset title (default: the file name)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--note <text>",
+                        "description": "Asset description",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company whose vault receives the files",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--no-caption",
+                        "description": "Skip the AI description and suggested tags for images and videos",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "tag",
+                "description": "Add or remove tags on a library placeholder",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <placeholder>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "placeholder",
+                        "required": true,
+                        "variadic": false,
+                        "description": "A .hqcloud placeholder (or the original path)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--add <tags>",
+                        "description": "Tags to add (comma-separated, repeatable)",
+                        "hidden": false,
+                        "defaultValue": []
+                    },
+                    {
+                        "flags": "--remove <tags>",
+                        "description": "Tags to remove (comma-separated, repeatable)",
+                        "hidden": false,
+                        "defaultValue": []
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "ls",
+                "description": "List library placeholders in a folder (default: companies/)",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] [dir]",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "dir",
+                        "required": false,
+                        "variadic": false,
+                        "description": "Folder to list, relative to HQ"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--tag <tag>",
+                        "description": "Require a tag (repeatable or comma-separated)",
+                        "hidden": false,
+                        "defaultValue": []
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "describe",
+                "description": "Re-run the AI description and suggested tags for a library image or video",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <placeholder>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "placeholder",
+                        "required": true,
+                        "variadic": false,
+                        "description": "A .hqcloud placeholder (or the original path)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "fetch",
+                "description": "Download a library asset next to its placeholder (wraps hq storage fetch)",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <placeholder>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "placeholder",
+                        "required": true,
+                        "variadic": false,
+                        "description": "A .hqcloud placeholder (or the original path)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "link",
+                "description": "Mint a short-lived download URL for a library asset (needs files:read)",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <target>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "target",
+                        "required": true,
+                        "variadic": false,
+                        "description": "A .hqcloud placeholder, its original path, or a vault key (.hq-offload/…)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--company <company>",
+                        "description": "Company uid (cmp_…), or a slug on a session; default: the placeholder's company or the key's",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--expires <minutes>",
+                        "description": "Link lifetime in minutes, 1-60 (default 15)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            }
+        ]
+    },
     {
         "name": "index",
         "description": "Manage the local HQ search index",

package/dist/command-registration-plan.d.ts

@@ -448,6 +448,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/search.js";
     readonly exportName: "registerSearchCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "library";
+    readonly parent: "program";
+    readonly module: "./commands/library.js";
+    readonly exportName: "registerLibraryCommand";
 }, {
     readonly type: "registrar";
     readonly root: "index";

package/dist/command-registration-plan.js

@@ -77,6 +77,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "vault", parent: "program", module: "./commands/vault-retention.js", exportName: "registerVaultRetentionCommand" },
     { type: "registrar", root: "core", parent: "program", module: "./commands/core.js", exportName: "registerCoreCommands" },
     { type: "registrar", root: "search", parent: "program", module: "./commands/search.js", exportName: "registerSearchCommand" },
+    { type: "registrar", root: "library", parent: "program", module: "./commands/library.js", exportName: "registerLibraryCommand" },
     { type: "registrar", root: "index", parent: "program", module: "./commands/index-cmd.js", exportName: "registerIndexCommand" },
     { type: "registrar", root: "capacity", parent: "program", module: "./commands/capacity.js", exportName: "registerCapacityCommand" },
     { type: "registrar", root: "doctor", parent: "program", module: "./commands/doctor.js", exportName: "registerDoctorCommand" },

package/dist/commands/agent-enroll.d.ts

@@ -59,6 +59,7 @@ export declare function mapEnrollFailure(status: number, body: {
     message?: unknown;
     attemptsRemaining?: unknown;
     upgradeUrl?: unknown;
+    pricingPlan?: unknown;
 }, headers?: {
     retryAfter?: string | null;
 }): EnrollError;

package/dist/commands/agent-enroll.js

@@ -20,6 +20,7 @@ import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL, personTokenCacheFile, } from "../utils/cognito-session.js";
 import { HQ_CLIENT_NAME } from "../utils/vault-api.js";
+import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, } from "../lib/billing/usage-only.js";
 import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
@@ -135,6 +136,12 @@ export function mapEnrollFailure(status, body, headers) {
         return new EnrollError(`This agent was revoked; its enrollment code no longer works. An admin must ` +
             `create a new external agent or rotate this one.${suffix}`, status, code);
     }
+    if ((status === 402 || code === "billing_required") &&
+        isUsageOnly(pricingPlanFromBody(body))) {
+        // Usage pricing (US-012): no paid plan to upgrade to. A company admin adds
+        // a card; the agent then bills per use.
+        return new EnrollError(usageOnlyCardRequiredLines("An external agent").join(" ") + suffix, status, code);
+    }
     if (status === 402 || code === "billing_required") {
         return new EnrollError(`External agents are available on paid HQ plans only. A company admin must ` +
             `upgrade the plan (\`hq billing\` or the console billing page) before enrolling.${suffix}`, status, code, typeof body.upgradeUrl === "string" ? body.upgradeUrl : undefined);

package/dist/commands/agents.d.ts

@@ -31,6 +31,8 @@ import { Command } from "commander";
 import { type ResidentCommandLeaseOptions } from "../utils/resident-package-preload.js";
 import { type TerminalSessionPayload } from "@indigoai-us/hq-cloud/outposts/node";
 import { type AgentModelProvider, type AgentModelCatalog } from "../lib/agents/model-catalog.js";
+import { type PricingPlan } from "../lib/billing/usage-only.js";
+import { type UsageCard } from "../lib/billing/usage-card.js";
 import { type BillingErrorPayload } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export declare const VALID_EFFORTS: Set<string>;
@@ -40,7 +42,14 @@ export declare const VALID_TIERS: Set<string>;
 export declare const VALID_PROVIDERS: Set<string>;
 /** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
 export declare const VALID_AUTH_MODES: Set<string>;
-/** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
+/**
+ * Customer-facing agent size keys served by hq-pro's authoritative catalog.
+ * basic / power / dev are the legacy ladder; small / medium / large / xlarge
+ * are the usage-pricing ladder (US-012). hq-pro returns the ladder that
+ * applies to the company, and a key it does not quote is refused with
+ * "did not return a quote".
+ */
+export type AgentSizeKey = "basic" | "power" | "dev" | "small" | "medium" | "large" | "xlarge";
 export declare const VALID_AGENT_SIZE_KEYS: Set<string>;
 /**
  * `hq agents create` exits with this distinct status when payment is required.
@@ -64,6 +73,8 @@ export declare function agentCreatePlanLimitFromPayload(status: number, body: un
 export declare function surfaceAgentCreatePlanLimit(planLimit: AgentCreatePlanLimit, opts?: {
     json?: boolean;
     companyUid?: string;
+    pricingPlan?: PricingPlan | null;
+    usageCard?: UsageCard;
 }): Promise<void>;
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
@@ -223,7 +234,7 @@ export declare function resolveProvisionSlackTokens(options: ProvisionSlackToken
 export declare const CLI_AGENT_CREATE_SURFACE: "cli_agents_create";
 export type AgentCreateSurface = typeof CLI_AGENT_CREATE_SURFACE;
 export interface AgentCreateSizeOption {
-    key: "basic" | "power" | "dev";
+    key: AgentSizeKey;
     productName: string;
     instanceType: string;
     listCents: number;
@@ -247,8 +258,19 @@ export type QuotedAgentCreateSizeOption = AgentCreateSizeOption & {
 };
 /** Read hq-pro's company-specific creation prices and capacities. */
 export declare function getAgentCreateOptions(token: string, companyUid: string, idempotencyKey?: string): Promise<AgentCreateOptionsView>;
+/**
+ * Legacy size names on the usage-pricing (v2) box ladder, owner decision
+ * 2026-10-16: basic -> small, power -> medium, dev -> large.
+ */
+export declare const LEGACY_TO_V2_AGENT_SIZE: Readonly<Record<string, AgentSizeKey>>;
+/**
+ * The size key to look up in the server's options. A key the server offers is
+ * used as is. A legacy key (basic, power, dev) against a v2 catalog maps to its
+ * v2 size. Anything else is returned unchanged and refused by the caller.
+ */
+export declare function resolveAgentSizeKey(view: AgentCreateOptionsView, sizeKey: string): string;
 /** Resolve a requested size from the server response, never from local prices. */
-export declare function requireQuotedCreateSize(view: AgentCreateOptionsView, sizeKey: string): QuotedAgentCreateSizeOption;
+export declare function requireQuotedCreateSize(view: AgentCreateOptionsView, requestedKey: string): QuotedAgentCreateSizeOption;
 /** Resolve hq-pro's default quote while leaving the POST default implicit. */
 export declare function requireDefaultAgentCreateSize(view: AgentCreateOptionsView): QuotedAgentCreateSizeOption;
 /** Human-facing quote summary sourced entirely from hq-pro. */

package/dist/commands/agents.js

@@ -44,6 +44,8 @@ import { peekIdToken } from "../utils/id-token.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, } from "../utils/plan-gate-error.js";
 import { AGENT_UID_PATTERN, isAgentUid } from "../lib/notify-recipient.js";
 import { AGENT_MODEL_PROVIDERS, modelSelectionErrorMessage, readAgentModelCatalog, validateAgentModelSelection, } from "../lib/agents/model-catalog.js";
+import { fetchCompanyPricingPlan, isUsageOnly, usageOnlyBoxSentence, usageOnlyCardRequiredLines, } from "../lib/billing/usage-only.js";
+import { BUNDLED_USAGE_CARD, fetchUsageCard, } from "../lib/billing/usage-card.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
@@ -59,8 +61,15 @@ export const VALID_TIERS = new Set(["default", "priority"]);
 export const VALID_PROVIDERS = new Set(["codex", "grok", "claude", "agents-v2"]);
 /** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
 export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
-/** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
-export const VALID_AGENT_SIZE_KEYS = new Set(["basic", "power", "dev"]);
+export const VALID_AGENT_SIZE_KEYS = new Set([
+    "basic",
+    "power",
+    "dev",
+    "small",
+    "medium",
+    "large",
+    "xlarge",
+]);
 // Keep cloud agent create slugs aligned with hq-pro-agents POST /v1/agents.
 const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const CLAUDE_PROVISION_COMMAND = "hq agents provision <name> --provider agents-v2 --model <model-id>";
@@ -146,6 +155,17 @@ async function offerAgentCheckout(url) {
 }
 /** Print a server-priced plan block without minting or rewriting its URL. */
 export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
+    if (isUsageOnly(opts.pricingPlan)) {
+        // Usage pricing (US-012): no Workforce plan to buy. The company adds a
+        // card and each agent box bills by size from the usage card.
+        const card = opts.usageCard ?? BUNDLED_USAGE_CARD;
+        for (const line of usageOnlyCardRequiredLines("An agent box", card)) {
+            console.error(line);
+        }
+        console.error(usageOnlyBoxSentence(card));
+        queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
+        return;
+    }
     const price = `${formatServerPrice(planLimit.amountMinor, planLimit.currency)}/month`;
     const reason = `HQ Workforce plan required to create an agent (${price}).`;
     const argv = opts.json ? [...process.argv, "--json"] : process.argv;
@@ -351,8 +371,31 @@ export async function getAgentCreateOptions(token, companyUid, idempotencyKey) {
     }
     return view;
 }
+/**
+ * Legacy size names on the usage-pricing (v2) box ladder, owner decision
+ * 2026-10-16: basic -> small, power -> medium, dev -> large.
+ */
+export const LEGACY_TO_V2_AGENT_SIZE = {
+    basic: "small",
+    power: "medium",
+    dev: "large",
+};
+/**
+ * The size key to look up in the server's options. A key the server offers is
+ * used as is. A legacy key (basic, power, dev) against a v2 catalog maps to its
+ * v2 size. Anything else is returned unchanged and refused by the caller.
+ */
+export function resolveAgentSizeKey(view, sizeKey) {
+    if (view.options.some((candidate) => candidate.key === sizeKey))
+        return sizeKey;
+    const v2 = LEGACY_TO_V2_AGENT_SIZE[sizeKey];
+    if (v2 && view.options.some((candidate) => candidate.key === v2))
+        return v2;
+    return sizeKey;
+}
 /** Resolve a requested size from the server response, never from local prices. */
-export function requireQuotedCreateSize(view, sizeKey) {
+export function requireQuotedCreateSize(view, requestedKey) {
+    const sizeKey = resolveAgentSizeKey(view, requestedKey);
     const option = view.options.find((candidate) => candidate.key === sizeKey);
     if (!option) {
         throw new Error(`HQ Pro did not return a quote for agent size ${sizeKey}.`);
@@ -1460,7 +1503,7 @@ export function registerAgentsCommand(program) {
         .option("--slack-tokens-stdin", "Read the bot token and optional app token from one or two stdin lines")
         .option("--title <title>", "Org-chart job title")
         .option("--description <text>", "Short description / bio")
-        .option("--size <size>", "Agent box size: basic | power | dev (omitted keeps the current default)")
+        .option("--size <size>", "Agent box size: small | medium | large | xlarge, or basic | power | dev (on usage pricing these map to small | medium | large); omitted keeps the current default")
         .option("--yes", "Confirm the quoted monthly cost and provision the agent")
         .option("--json", "Emit machine-readable output and never open a browser")
         .addHelpText("after", `\n${claudeProvisionGuidance()}\n`)
@@ -1626,9 +1669,19 @@ export function registerAgentsCommand(program) {
                     if (!err.agentCreatePlanLimit) {
                         throw new Error("HQ Pro returned an unrecognized agent payment-required response.");
                     }
+                    // Bounded: an unreachable API leaves the plan unknown (legacy copy)
+                    // within 3 s instead of holding the refusal.
+                    const pricingPlan = await fetchCompanyPricingPlan(token, companyUid, {
+                        timeoutMs: 2000,
+                        deadlineMs: 3000,
+                    }).catch(() => null);
                     await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, {
                         ...opts,
                         companyUid,
+                        pricingPlan,
+                        ...(isUsageOnly(pricingPlan)
+                            ? { usageCard: (await fetchUsageCard()).card }
+                            : {}),
                     });
                     // Keep the payment-required status through normal CLI teardown.
                     // Unlike process.exit(), this is testable and cannot be caught by