feat(cli): redesign help across command tree

cli/src/cli.ts

@@ -36,7 +36,7 @@ import {
   resolveSubCommandForUsage,
   showAltertableUsage,
   showCommandExamplesForArgs,
-} from "@/lib/citty-usage.ts";
+} from "@/lib/usage.ts";
 import { findFirstPositionalToken, valueFlagsFor } from "@/lib/command-delegation.ts";
 import { findEarlyBootstrapExit } from "@/lib/early-bootstrap.ts";
 import { terminalError, applyTerminalColorFromContext } from "@/ui/terminal/styles.ts";

cli/src/commands/api.ts

@@ -258,6 +258,7 @@ export const apiCommand = defineOperationCommand<ApiInvokeInput, ApiHttpResult |
   },
   meta: {
     name: "api",
+    commandGroup: "platform",
     description: "Management REST API — HTTP invoker and OpenAPI spec.",
     examples: [
       "altertable api /whoami",

cli/src/commands/catalogs.ts

@@ -97,6 +97,7 @@ const catalogsListCommand = defineOperationCommand({
 export const catalogsCommand = defineGroupCommand({
   meta: {
     name: "catalogs",
+    commandGroup: "platform",
     description: "Manage catalogs (databases and connections) in the current environment.",
     examples: [
       "altertable catalogs list",

cli/src/commands/completion.ts

@@ -465,6 +465,7 @@ export function createCompletionCommand(
     catalog: { effects: ["local", "output", "value"], mutates: true, output: "human" },
     meta: {
       name: "completion",
+      commandGroup: "platform",
       description: "Generate or install shell completion scripts.",
       examples: [
         "altertable completion install",

cli/src/commands/duckdb.ts

@@ -100,6 +100,7 @@ export const duckdbCommand = defineLocalCommand<DuckdbInput>({
   capabilities: ["management-http"],
   meta: {
     name: "duckdb",
+    commandGroup: "query",
     description: "Open a DuckDB shell attached to lakehouse catalogs (all of them by default).",
     examples: ["altertable duckdb", "altertable duckdb my_catalog"],
   },

cli/src/commands/lakehouse/append.ts

@@ -87,6 +87,7 @@ const appendStatusCommand = defineHttpCommand({
 export const appendCommand = defineGroupCommand({
   meta: {
     name: "append",
+    commandGroup: "ingest",
     description: "Append JSON rows to a table.",
     examples: [
       "altertable append --catalog db --schema public --table events --data '[{\"id\":1}]'",

cli/src/commands/lakehouse/query.ts

@@ -184,6 +184,7 @@ const QUERY_SUBCOMMAND_NAMES = new Set(Object.keys(querySubCommands));
 export const queryCommand = defineGroupCommand({
   meta: {
     name: "query",
+    commandGroup: "query",
     description: "Run SQL queries against the lakehouse.",
     examples: [
       'altertable query "SELECT * FROM users LIMIT 10"',

cli/src/commands/lakehouse/schema.ts

@@ -74,6 +74,7 @@ export const schemaCommand = defineOperationCommand<SchemaRunInput, LakehouseQue
   },
   meta: {
     name: "schema",
+    commandGroup: "query",
     description: "List schemas, tables, and columns for a catalog.",
     examples: ["altertable schema my-catalog", "altertable schema my-catalog --format json"],
   },

cli/src/commands/lakehouse/upload.ts

@@ -38,6 +38,7 @@ export const uploadCommand = defineOperationCommand({
   },
   meta: {
     name: "upload",
+    commandGroup: "ingest",
     description: "Upload a file to create, append to, or overwrite a table.",
     examples: [
       "altertable upload --catalog db --schema public --table users --mode overwrite --format csv --file users.csv",

cli/src/commands/lakehouse/upsert.ts

@@ -22,6 +22,7 @@ export const upsertCommand = defineOperationCommand({
   },
   meta: {
     name: "upsert",
+    commandGroup: "ingest",
     description: "Upload a file and match existing rows by primary key.",
     examples: [
       "altertable upsert --catalog db --schema public --table users --primary-key id --format csv --file users.csv",

cli/src/commands/login.ts

@@ -233,6 +233,7 @@ export const loginCommand = defineLocalCommand({
   output: "none",
   meta: {
     name: "login",
+    commandGroup: "platform",
     description: "Sign in with your browser (OAuth) and store the session.",
     examples: ["altertable login", "altertable login --replace-profile"],
   },
@@ -267,6 +268,7 @@ export const logoutCommand = defineLocalCommand({
   output: "none",
   meta: {
     name: "logout",
+    commandGroup: "platform",
     description: "Remove stored credentials and settings for all profiles.",
     examples: ["altertable logout"],
   },

cli/src/commands/profile.ts

@@ -421,6 +421,7 @@ export const profileCommand = defineLocalCommand<Record<string, unknown>, void>(
   output: "none",
   meta: {
     name: "profile",
+    commandGroup: "platform",
     description: "Manage named profiles and stored credentials.",
     examples: [
       "altertable profile show",

cli/src/commands/update.ts

@@ -137,6 +137,7 @@ async function runUpdateCommand(args: UpdateCommandArgs, sink: OutputSink): Prom
 export const updateCommand = defineAltertableCommand({
   meta: {
     name: "update",
+    commandGroup: "platform",
     description: "Check for a newer Altertable CLI release and optionally install it.",
     examples: [
       "altertable update",

cli/src/lib/command-context.ts

@@ -2,9 +2,12 @@ import type { ArgsDef, CommandContext, CommandDef, CommandMeta, Resolvable } fro
 import type { CliRuntime, OutputSink } from "@/lib/runtime.ts";
 import { getCliRuntime } from "@/lib/runtime.ts";
 
+export type AltertableCommandGroup = "platform" | "ingest" | "query";
+
 export type AltertableCommandMeta = CommandMeta & {
   examples?: readonly string[];
   hidden?: boolean;
+  commandGroup?: AltertableCommandGroup;
 };
 
 export type CommandRunContext<T extends ArgsDef = ArgsDef> = CommandContext<T> & {