fix(cli): improve --help documentation and add --yes/--check to upgrade

- upgrade: add --yes and --check flags to skip interactive prompt
- benchmark: clarify description — preset fps/quality/worker configs
- browser: describe each subcommand (ensure/path/clear) in help
- docs: list available topics inline in --help output

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vanceingalls

packages/cli/src/commands/benchmark.ts

@@ -38,7 +38,7 @@ const DEFAULT_CONFIGS: BenchmarkConfig[] = [
 export default defineCommand({
   meta: {
     name: "benchmark",
-    description: "Run multiple render configurations and compare results",
+    description: "Render with preset fps/quality/worker configs and compare speed and file size",
   },
   args: {
     dir: { type: "positional", description: "Project directory", required: false },

packages/cli/src/commands/browser.ts

@@ -90,7 +90,8 @@ export default defineCommand({
   args: {
     subcommand: {
       type: "positional",
-      description: "Subcommand: ensure, path, clear",
+      description:
+        "ensure = find or download Chrome, path = print executable path, clear = remove cached download",
       required: false,
     },
   },

packages/cli/src/commands/docs.ts

@@ -84,10 +84,16 @@ function renderMarkdown(content: string): void {
   }
 }
 
+const TOPIC_NAMES = Object.keys(TOPICS).join(", ");
+
 export default defineCommand({
   meta: { name: "docs", description: "View inline documentation in the terminal" },
   args: {
-    topic: { type: "positional", description: "Topic to view", required: false },
+    topic: {
+      type: "positional",
+      description: `Topic: ${TOPIC_NAMES}. Omit to list all.`,
+      required: false,
+    },
   },
   async run({ args }) {
     const topic = args.topic;

packages/cli/src/commands/upgrade.ts

@@ -5,8 +5,13 @@ import { VERSION } from "../version.js";
 
 export default defineCommand({
   meta: { name: "upgrade", description: "Check for updates and show upgrade instructions" },
-  args: {},
-  async run() {
+  args: {
+    yes: { type: "boolean", alias: "y", description: "Show upgrade commands without prompting" },
+    check: { type: "boolean", description: "Check for updates and exit (no prompt)" },
+  },
+  async run({ args }) {
+    const autoYes = args.yes === true;
+    const checkOnly = args.check === true;
     clack.intro(c.bold("hyperframes upgrade"));
 
     const s = clack.spinner();
@@ -41,15 +46,22 @@ export default defineCommand({
     console.log(`   ${c.dim("Latest:")}   ${c.bold(c.accent("v" + latest))}`);
     console.log();
 
-    const shouldUpgrade = await clack.confirm({
-      message: "Upgrade now?",
-    });
-
-    if (clack.isCancel(shouldUpgrade) || !shouldUpgrade) {
-      clack.outro(c.dim("Skipped."));
+    if (checkOnly) {
+      clack.outro(c.accent("Update available: v" + latest));
       return;
     }
 
+    if (!autoYes) {
+      const shouldUpgrade = await clack.confirm({
+        message: "Upgrade now?",
+      });
+
+      if (clack.isCancel(shouldUpgrade) || !shouldUpgrade) {
+        clack.outro(c.dim("Skipped."));
+        return;
+      }
+    }
+
     console.log();
     console.log(`   ${c.accent("npm install -g hyperframes@" + latest)}`);
     console.log(`   ${c.dim("or")}`);