paean 0.10.18 → 0.10.19

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.10.19] - /usage command (2026-04-15)
+
+### Features
+- Added `paean usage` CLI command and `/usage` TUI slash command: shows subscription tier, total credits, and 5h/7d rolling-window usage with color-coded progress bars.
+- Added `getUsageLimits()` wrapper for zero-api `GET /credits/usage-limits`.
+
 ## [0.8.12] - Deep UX & Stability Optimization (2026-02-11)
 
 ### 🛡️ Critical Fixes

package/dist/api/credits.d.ts

@@ -17,6 +17,21 @@ export declare function getCreditsStatus(): Promise<{
     success: boolean;
     data: CreditsStatus;
 }>;
+export interface UsageLimits {
+    usage5h: number;
+    usage7d: number;
+    limits: {
+        credits5h: number;
+        credits7d: number;
+    };
+    percentUsed5h: number;
+    percentUsed7d: number;
+    subscriptionTier: string;
+}
+export declare function getUsageLimits(): Promise<{
+    success: boolean;
+    data: UsageLimits;
+}>;
 export interface NetworkDepositInfo {
     name: string;
     depositAddress: string;

package/dist/api/credits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/api/credits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,CAI3F;AAID,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAI3D;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC,CAIxD;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC;IAAE,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAIhF;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAInF"}
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/api/credits.ts"],"names":[],"mappings":"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"}

package/dist/api/credits.js

@@ -8,6 +8,11 @@ export async function getCreditsStatus() {
     const { data } = await client.get('/credits/status');
     return data;
 }
+export async function getUsageLimits() {
+    const client = getApiClient();
+    const { data } = await client.get('/credits/usage-limits');
+    return data;
+}
 export async function getDepositInfo() {
     const client = getApiClient();
     const { data } = await client.get('/crypto-deposit/info');

package/dist/api/credits.js.map

@@ -1 +1 @@
-{"version":3,"file":"credits.js","sourceRoot":"","sources":["../../src/api/credits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAgB3C,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC;AAuBD,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAuBD,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAiBD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc;IACnD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,0BAA0B,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"credits.js","sourceRoot":"","sources":["../../src/api/credits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAgB3C,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAuBD,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAuBD,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAiBD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc;IACnD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,0BAA0B,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli.js

@@ -33454,10 +33454,23 @@ var contextEmitter, pendingCompactSummary, CONTEXT_TOOL_NAMES, init_context_tool
 });
 
 // src/api/credits.ts
+var credits_exports = {};
+__export(credits_exports, {
+  getCreditsStatus: () => getCreditsStatus,
+  getDepositHistory: () => getDepositHistory,
+  getDepositInfo: () => getDepositInfo,
+  getDepositStatus: () => getDepositStatus,
+  getUsageLimits: () => getUsageLimits,
+  pollDeposits: () => pollDeposits
+});
 async function getCreditsStatus() {
   let client = getApiClient(), { data } = await client.get("/credits/status");
   return data;
 }
+async function getUsageLimits() {
+  let client = getApiClient(), { data } = await client.get("/credits/usage-limits");
+  return data;
+}
 async function getDepositInfo() {
   let client = getApiClient(), { data } = await client.get("/crypto-deposit/info");
   return data;
@@ -33479,6 +33492,7 @@ var init_credits = __esm({
     "use strict";
     init_client();
     __name(getCreditsStatus, "getCreditsStatus");
+    __name(getUsageLimits, "getUsageLimits");
     __name(getDepositInfo, "getDepositInfo");
     __name(pollDeposits, "pollDeposits");
     __name(getDepositHistory, "getDepositHistory");
@@ -65873,7 +65887,8 @@ function useCommands(options = {}) {
     "/memory",
     "/shortcuts",
     "/tools",
-    "/loop"
+    "/loop",
+    "/usage"
   ], getHelp = (0, import_react30.useCallback)(() => `
   \u2500\u2500\u2500 Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 
@@ -65888,6 +65903,7 @@ function useCommands(options = {}) {
 
     /status      Show session status & config
     /stats       Show detailed session statistics
+    /usage       Show subscription, credits, and 5h/7d usage
     /mcp         Show MCP connection status
     /tools       List all available local tools
     /model       Show current model info
@@ -67991,6 +68007,34 @@ var init_components = __esm({
 });
 
 // src/ui/App.tsx
+function renderUsageBar(percent, width = 20) {
+  let p = Math.max(0, Math.min(100, percent)), filled = Math.round(p / 100 * width);
+  return "\u2588".repeat(filled) + "\u2591".repeat(width - filled);
+}
+function formatUsageOutput(status, limits) {
+  let bar5h = renderUsageBar(limits.percentUsed5h), bar7d = renderUsageBar(limits.percentUsed7d), out = `
+  \u2500\u2500\u2500 Usage \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+`;
+  if (out += `    Subscription:    ${status.subscriptionTier}
+`, out += `    Credits:         ${status.credits} / ${status.totalCredits}
+`, status.canRecover)
+    out += `    Recovery:        available now
+`;
+  else if (status.nextRecoveryAt) {
+    let d = new Date(status.nextRecoveryAt);
+    out += `    Next recovery:   ${d.toLocaleString()}
+`;
+  }
+  return out += `
+  \u2500\u2500\u2500 Rolling Windows \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+`, out += `    5h   ${bar5h}  ${limits.percentUsed5h}%  (${limits.usage5h} / ${limits.limits.credits5h})
+`, out += `    7d   ${bar7d}  ${limits.percentUsed7d}%  (${limits.usage7d} / ${limits.limits.credits7d})
+`, (limits.percentUsed5h >= 90 || limits.percentUsed7d >= 90) && (out += `
+  \u26A0  Approaching usage limits \u2014 requests may be throttled.
+`), out;
+}
 var import_react41, import_jsx_runtime8, DOUBLE_CTRL_C_WINDOW, App2, init_App2 = __esm({
   async "src/ui/App.tsx"() {
     "use strict";
@@ -67999,7 +68043,10 @@ var import_react41, import_jsx_runtime8, DOUBLE_CTRL_C_WINDOW, App2, init_App2 =
     await init_components();
     await init_hooks();
     init_ink_theme();
-    import_jsx_runtime8 = __toESM(require_jsx_runtime(), 1), DOUBLE_CTRL_C_WINDOW = 1500, App2 = /* @__PURE__ */ __name(({
+    import_jsx_runtime8 = __toESM(require_jsx_runtime(), 1), DOUBLE_CTRL_C_WINDOW = 1500;
+    __name(renderUsageBar, "renderUsageBar");
+    __name(formatUsageOutput, "formatUsageOutput");
+    App2 = /* @__PURE__ */ __name(({
       mcpState,
       onMcpToolCall,
       mcpClient: mcpClient2,
@@ -68149,6 +68196,22 @@ To resume this session: paean --resume=${conversationId}
         return completions.length === 1 ? (setCommandSuggestions([]), completions[0]) : null;
       }, [getCompletions]), handleSubmit = (0, import_react41.useCallback)((input) => {
         if (setCommandOutput(null), setCommandSuggestions([]), input.startsWith("/")) {
+          if (input.trim().toLowerCase() === "/usage") {
+            setCommandOutput("  Fetching usage\u2026"), (async () => {
+              try {
+                let { getCreditsStatus: getCreditsStatus2, getUsageLimits: getUsageLimits2 } = await Promise.resolve().then(() => (init_credits(), credits_exports)), [statusRes, limitsRes] = await Promise.all([
+                  getCreditsStatus2(),
+                  getUsageLimits2()
+                ]);
+                setCommandOutput(formatUsageOutput(statusRes.data, limitsRes.data));
+              } catch (err) {
+                setCommandOutput(`
+  Failed to fetch usage: ${err?.message || err}
+`);
+              }
+            })();
+            return;
+          }
           let result = handleCommand(input);
           if (result.handled) {
             if (result.action === "exit") {
@@ -134853,24 +134916,68 @@ function printDeposit(dep) {
 }
 __name(printDeposit, "printDeposit");
 
+// src/commands/usage.ts
+init_esm();
+init_config();
+init_credits();
+init_output();
+function requireAuth6() {
+  isAuthenticated() || (error2("Not logged in. Run `paean login` first."), process.exit(1));
+}
+__name(requireAuth6, "requireAuth");
+function renderBar(percent, width = 24) {
+  let p = Math.max(0, Math.min(100, percent)), filled = Math.round(p / 100 * width), empty = width - filled, bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+  return p >= 90 ? colors.error(bar) : p >= 70 ? colors.warning(bar) : colors.success(bar);
+}
+__name(renderBar, "renderBar");
+var usageCommand = new Command("usage").description("Show subscription tier, credits, and rolling-window usage (5h / 7d)").option("--json", "Output in JSON format").action(async (options) => {
+  requireAuth6();
+  let spin = spinner("Fetching usage\u2026").start();
+  try {
+    let [statusRes, limitsRes] = await Promise.all([
+      getCreditsStatus(),
+      getUsageLimits()
+    ]);
+    spin.stop();
+    let status = statusRes.data, limits = limitsRes.data;
+    if (options.json) {
+      json({ status, limits });
+      return;
+    }
+    header("Usage"), tableRow("Subscription", colors.bold(status.subscriptionTier)), tableRow("Credits", `${status.credits} / ${status.totalCredits}`), status.canRecover ? tableRow("Recovery", colors.success("available now")) : status.nextRecoveryAt && tableRow("Next recovery", formatDate(status.nextRecoveryAt)), newline(), header("Rolling Window Usage");
+    let bar5h = renderBar(limits.percentUsed5h), bar7d = renderBar(limits.percentUsed7d);
+    tableRow(
+      "5h",
+      `${bar5h} ${limits.percentUsed5h}%  (${limits.usage5h} / ${limits.limits.credits5h})`
+    ), tableRow(
+      "7d",
+      `${bar7d} ${limits.percentUsed7d}%  (${limits.usage7d} / ${limits.limits.credits7d})`
+    ), newline(), limits.percentUsed5h >= 90 || limits.percentUsed7d >= 90 ? warning2("Approaching usage limits \u2014 requests may be throttled.") : status.credits < 20 && warning2(
+      `Credits are low (${status.credits}). Use \`paean credits deposit-info\` to top up.`
+    );
+  } catch (err) {
+    spin.stop(), errorWithHint(err.message || "Failed to fetch usage");
+  }
+});
+
 // src/commands/sparklet.ts
 init_esm();
 init_open();
 init_client();
 init_config();
 init_output();
-function requireAuth6() {
+function requireAuth7() {
   isAuthenticated() || (error2("Not logged in. Run `paean login` first."), process.exit(1));
 }
-__name(requireAuth6, "requireAuth");
+__name(requireAuth7, "requireAuth");
 var sparkletCommand = new Command("sparklet").description("View and manage sparklets (AI-generated micro-apps)").action(async () => {
-  requireAuth6(), await listSparklets();
+  requireAuth7(), await listSparklets();
 });
 sparkletCommand.command("list").description("List your sparklets").option("--json", "Output as JSON").action(async (options) => {
-  requireAuth6(), await listSparklets(options.json);
+  requireAuth7(), await listSparklets(options.json);
 });
 sparkletCommand.command("show <id>").description("Show sparklet details").option("--json", "Output as JSON").action(async (id, options) => {
-  requireAuth6();
+  requireAuth7();
   try {
     let response = await getApiClient().get(`/sparklet/${id}`), sparklet = response.data.data || response.data;
     if (options.json) {
@@ -134887,7 +134994,7 @@ sparkletCommand.command("show <id>").description("Show sparklet details").option
   }
 });
 sparkletCommand.command("open <id>").description("Open sparklet in browser").action(async (id) => {
-  requireAuth6();
+  requireAuth7();
   let url3 = `${getWebUrl()}/sparklet/${id}`;
   dim2(`Opening ${url3}...`);
   try {
@@ -134897,7 +135004,7 @@ sparkletCommand.command("open <id>").description("Open sparklet in browser").act
   }
 });
 sparkletCommand.command("delete <id>").description("Delete a sparklet").action(async (id) => {
-  requireAuth6();
+  requireAuth7();
   try {
     await getApiClient().delete(`/sparklet/${id}`), success2("Sparklet deleted.");
   } catch (error4) {
@@ -134906,7 +135013,7 @@ sparkletCommand.command("delete <id>").description("Delete a sparklet").action(a
   }
 });
 sparkletCommand.command("publish <id>").description("Publish or unpublish a sparklet").option("--unpublish", "Unpublish instead of publish").action(async (id, options) => {
-  requireAuth6();
+  requireAuth7();
   try {
     await getApiClient().put(`/sparklet/${id}/publish`, {
       isPublished: !options.unpublish
@@ -135596,10 +135703,10 @@ __name(getUserProfile, "getUserProfile");
 // src/commands/workers.ts
 init_config();
 init_output();
-function requireAuth7() {
+function requireAuth8() {
   isAuthenticated() || (error2("Not logged in. Run `paean login` first."), process.exit(1));
 }
-__name(requireAuth7, "requireAuth");
+__name(requireAuth8, "requireAuth");
 var DEFAULT_IGNORE_PATTERNS = [
   "node_modules",
   ".git",
@@ -135690,10 +135797,10 @@ function saveManifest(dir, manifest) {
 }
 __name(saveManifest, "saveManifest");
 var workersCommand = new Command("workers").description("Publish and manage Worker packages on 0.works marketplace").action(async () => {
-  requireAuth7(), await listMy();
+  requireAuth8(), await listMy();
 });
 workersCommand.command("whoami").description("Show current authenticated user").option("--json", "Output as JSON").action(async (options) => {
-  requireAuth7();
+  requireAuth8();
   try {
     let u3 = (await getUserProfile()).user;
     if (options.json) {
@@ -135753,7 +135860,7 @@ workersCommand.command("pack").description("Create a .zip package from the curre
   success2(`Package created: ${outputPath}`), dim2(`Size: ${formatSize(stat4.size)}`), stat4.size > MAX_PACKAGE_SIZE && warning2(`Package exceeds ${formatSize(MAX_PACKAGE_SIZE)} limit`);
 });
 workersCommand.command("publish").description("Package and publish the current directory to 0.works marketplace").option("--draft", "Upload as draft without publishing").option("--zip <path>", "Upload an existing zip file instead of packing").option("--changelog <text>", "Changelog / release notes for this version").action(async (options) => {
-  requireAuth7();
+  requireAuth8();
   let dir = process.cwd(), manifest = loadManifest(dir);
   manifest || (error2(`No ${MANIFEST_FILE} found. Run: paean workers init`), process.exit(1)), manifest.name || (error2("name is required in workers.json"), process.exit(1));
   let zipPath = options.zip, tempZip = !1;
@@ -135800,7 +135907,7 @@ View: https://0.works/workers/${worker.slug}`), newline();
   }
 });
 workersCommand.command("publish-id <id>").description("Publish a previously uploaded draft worker by ID").action(async (id) => {
-  requireAuth7();
+  requireAuth8();
   try {
     let result = await publishWorkerPackage(id);
     success2(`Published: ${result.worker.displayName}`), dim2("Status: published (pending review)");
@@ -135810,7 +135917,7 @@ workersCommand.command("publish-id <id>").description("Publish a previously uplo
   }
 });
 workersCommand.command("update [bump]").description("Bump version and publish in one step (default: patch)").option("--changelog <text>", "Changelog / release notes").option("--draft", "Upload as draft without publishing").action(async (bump, options) => {
-  requireAuth7();
+  requireAuth8();
   let dir = process.cwd(), manifest = loadManifest(dir);
   manifest || (error2(`No ${MANIFEST_FILE} found. Run: paean workers init`), process.exit(1));
   let bumpType = bump || "patch", parts = (manifest.version || "1.0.0").split(".").map(Number);
@@ -135888,7 +135995,7 @@ workersCommand.command("inspect [dir]").description("Inspect directory contents
   tableRow("Hash", `${hash2.substring(0, 16)}...`), totalSize > MAX_PACKAGE_SIZE && issues.push(`Package too large: ${formatSize(totalSize)} > ${formatSize(MAX_PACKAGE_SIZE)}`), files.some((f) => f.toLowerCase().startsWith("readme")) || warnings.push("Consider adding a README.md"), issues.length > 0 && (newline(), error2("Errors:"), issues.forEach((i) => listItem(colors.error(i), 1))), warnings.length > 0 && (newline(), warning2("Warnings:"), warnings.forEach((w2) => listItem(colors.warning(w2), 1))), issues.length === 0 && warnings.length === 0 && (newline(), success2("No issues found.")), newline();
 });
 workersCommand.command("list").alias("ls").description("List my published workers").option("--json", "Output as JSON").action(async (options) => {
-  requireAuth7(), await listMy(options.json);
+  requireAuth8(), await listMy(options.json);
 });
 workersCommand.command("search [query]").description("Search the workers marketplace").option("--agent <agent>", "Filter by compatible agent").option("--category <cat>", "Filter by category").option("--json", "Output as JSON").action(async (query, options) => {
   try {
@@ -135924,7 +136031,7 @@ https://0.works/workers/${w2.slug}`), newline();
   }
 });
 workersCommand.command("install <slug>").alias("add").description("Download and install a worker package from the marketplace").option("-v, --version <version>", "Install a specific version").option("-o, --output <dir>", "Output directory (default: .workers/<slug>)").option("--json", "Output download info as JSON").action(async (slug, options) => {
-  requireAuth7();
+  requireAuth8();
   let spin = spinner(`Fetching ${slug}...`).start();
   try {
     let w2 = (await getWorkerBySlug(slug)).worker, dlResult = await downloadWorker(slug, options.version);
@@ -135962,7 +136069,7 @@ workersCommand.command("install <slug>").alias("add").description("Download and
   }
 });
 workersCommand.command("purchase <slug>").alias("buy").description("Purchase a paid worker from the marketplace").option("--json", "Output as JSON").action(async (slug, options) => {
-  requireAuth7();
+  requireAuth8();
   try {
     let w2 = (await getWorkerBySlug(slug)).worker;
     if (w2.priceType === "free") {
@@ -135983,10 +136090,10 @@ workersCommand.command("purchase <slug>").alias("buy").description("Purchase a p
 });
 var myCommand = workersCommand.command("my").description("Manage your workers (published and purchased)");
 myCommand.command("published").alias("pub").description("List my published workers").option("--json", "Output as JSON").action(async (options) => {
-  requireAuth7(), await listMy(options.json);
+  requireAuth8(), await listMy(options.json);
 });
 myCommand.command("purchased").alias("bought").description("List my purchased workers").option("--json", "Output as JSON").action(async (options) => {
-  requireAuth7();
+  requireAuth8();
   try {
     let result = await listMyPurchasedWorkers();
     if (options.json) {
@@ -136009,10 +136116,10 @@ myCommand.command("purchased").alias("bought").description("List my purchased wo
   }
 });
 myCommand.action(async () => {
-  requireAuth7(), await listMy();
+  requireAuth8(), await listMy();
 });
 workersCommand.command("unpublish <id>").description("Remove a published worker (soft delete)").action(async (id) => {
-  requireAuth7();
+  requireAuth8();
   try {
     let result = await deleteWorkerPackage(id);
     success2(`Removed: ${result.worker.displayName}`);
@@ -136127,6 +136234,7 @@ program2.addCommand(devicesCommand);
 program2.addCommand(configCommand);
 program2.addCommand(mcpCommand);
 program2.addCommand(creditsCommand);
+program2.addCommand(usageCommand);
 program2.addCommand(sparkletCommand);
 program2.addCommand(completionCommand);
 program2.addCommand(wechatCommand);