fix(cli): centralize command help metadata

packages/coding-agent/src/cli-commands.ts

@@ -9,6 +9,7 @@
  * regression that motivated the split.
  */
 import type { CommandEntry } from "@oh-my-pi/pi-utils/cli";
+import * as commandHelp from "./cli/command-help";
 import { flagConsumesValue } from "./cli/flag-tables";
 import { launchHelp } from "./commands/launch-help";
 
@@ -17,162 +18,164 @@ export const commands: CommandEntry[] = [
 	{
 		name: "acp",
 		load: () => import("./commands/acp").then(m => m.default),
-		help: { description: "Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio" },
+		help: commandHelp.acpHelp,
 	},
 	{
 		name: "auth-broker",
 		load: () => import("./commands/auth-broker").then(m => m.default),
-		help: { description: "Manage the omp auth-broker (credential vault)" },
+		help: commandHelp.authBrokerHelp,
 	},
 	{
 		name: "auth-gateway",
 		load: () => import("./commands/auth-gateway").then(m => m.default),
-		help: { description: "Run an auth-gateway forward proxy backed by the configured broker" },
+		help: commandHelp.authGatewayHelp,
 	},
 	{
 		name: "agents",
 		load: () => import("./commands/agents").then(m => m.default),
-		help: { description: "Manage bundled task agents" },
+		help: commandHelp.agentsHelp,
 	},
 	{
 		name: "bench",
 		load: () => import("./commands/bench").then(m => m.default),
-		help: {
-			description: "Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)",
-		},
+		help: commandHelp.benchHelp,
 	},
 	{
 		name: "cleanse",
 		load: () => import("./commands/cleanse").then(m => m.default),
-		help: { description: "Detect and fix project diagnostics with weighted parallel subagents" },
+		help: commandHelp.cleanseHelp,
 	},
 	{
 		name: "commit",
 		load: () => import("./commands/commit").then(m => m.default),
-		help: { description: "Generate a commit message and update changelogs" },
+		help: commandHelp.commitHelp,
 	},
 	{
 		name: "completions",
 		load: () => import("./commands/completions").then(m => m.default),
-		help: { description: "Print a shell completion script (bash, zsh, or fish)" },
+		help: commandHelp.completionsHelp,
+	},
+	{
+		name: "__complete",
+		load: () => import("./commands/complete").then(m => m.default),
+		help: commandHelp.completeHelp,
 	},
-	{ name: "__complete", load: () => import("./commands/complete").then(m => m.default), help: { hidden: true } },
 	{
 		name: "config",
 		load: () => import("./commands/config").then(m => m.default),
-		help: { description: "Manage configuration settings" },
+		help: commandHelp.configHelp,
 	},
 	{
 		name: "dry-balance",
 		load: () => import("./commands/dry-balance").then(m => m.default),
-		help: { description: "Dry-run OAuth account balancing across random session ids" },
+		help: commandHelp.dryBalanceHelp,
 	},
 	{
 		name: "gc",
 		load: () => import("./commands/gc").then(m => m.default),
-		help: { description: "Run storage garbage collection" },
+		help: commandHelp.gcHelp,
 	},
 	{
 		name: "grep",
 		load: () => import("./commands/grep").then(m => m.default),
-		help: { description: "Test grep tool" },
+		help: commandHelp.grepHelp,
 	},
 	{
 		name: "gallery",
 		load: () => import("./commands/gallery").then(m => m.default),
-		help: { description: "Preview tool renderers across streaming, in-progress, success, and failure states" },
+		help: commandHelp.galleryHelp,
 	},
 	{
 		name: "grievances",
 		load: () => import("./commands/grievances").then(m => m.default),
-		help: { description: "View, clean, or push reported tool issues (auto-QA grievances)" },
+		help: commandHelp.grievancesHelp,
 	},
 	{
 		name: "install",
 		load: () => import("./commands/install").then(m => m.default),
-		help: { description: "Install or link an extension package (alias of `plugin install`/`plugin link`)" },
+		help: commandHelp.installHelp,
 	},
 	{
 		name: "join",
 		load: () => import("./commands/join").then(m => m.default),
-		help: { description: "Join a shared collab session (same as /join)" },
+		help: commandHelp.joinHelp,
 	},
 	{
 		name: "models",
 		load: () => import("./commands/models").then(m => m.default),
-		help: { description: "List, search, and refresh available models" },
+		help: commandHelp.modelsHelp,
 	},
 	{
 		name: "plugin",
 		load: () => import("./commands/plugin").then(m => m.default),
-		help: { description: "Manage plugins (install, uninstall, list, etc.)" },
+		help: commandHelp.pluginHelp,
 	},
 	{
 		name: "say",
 		load: () => import("./commands/say").then(m => m.default),
-		help: { description: "Synthesize text with the local TTS engine and play it through the speakers" },
+		help: commandHelp.sayHelp,
 	},
 	{
 		name: "setup",
 		load: () => import("./commands/setup").then(m => m.default),
-		help: { description: "Run onboarding setup or install dependencies for optional features" },
+		help: commandHelp.setupHelp,
 	},
 	{
 		name: "shell",
 		load: () => import("./commands/shell").then(m => m.default),
-		help: { description: "Interactive shell console" },
+		help: commandHelp.shellHelp,
 	},
 	{
 		name: "read",
 		load: () => import("./commands/read").then(m => m.default),
-		help: { description: "Show what the read tool will return for a path, URL, or internal URI" },
+		help: commandHelp.readHelp,
 	},
 	{
 		name: "ssh",
 		load: () => import("./commands/ssh").then(m => m.default),
-		help: { description: "Manage SSH host configurations" },
+		help: commandHelp.sshHelp,
 	},
 	{
 		name: "stats",
 		load: () => import("./commands/stats").then(m => m.default),
-		help: { description: "View usage statistics" },
+		help: commandHelp.statsHelp,
 	},
 	{
 		name: "update",
 		load: () => import("./commands/update").then(m => m.default),
-		help: { description: "Check for and install updates" },
+		help: commandHelp.updateHelp,
 	},
 	{
 		name: "usage",
 		load: () => import("./commands/usage").then(m => m.default),
-		help: { description: "Show provider usage limits for every authenticated account" },
+		help: commandHelp.usageHelp,
 	},
 	{
 		name: "tiny-models",
 		load: () => import("./commands/tiny-models").then(m => m.default),
-		help: { description: "Download tiny local models (session titles + memory)" },
+		help: commandHelp.tinyModelsHelp,
 	},
 	{
 		name: "token",
 		load: () => import("./commands/token").then(m => m.default),
-		help: { description: "Get the API key or OAuth token for a provider" },
+		help: commandHelp.tokenHelp,
 	},
 	{
 		name: "ttsr",
 		load: () => import("./commands/ttsr").then(m => m.default),
-		help: { description: "Inspect and test Time-Traveling Stream Rules (TTSR)" },
+		help: commandHelp.ttsrHelp,
 	},
 	{
 		name: "worktree",
 		load: () => import("./commands/worktree").then(m => m.default),
 		aliases: ["wt"],
-		help: { description: "List or clear agent-managed git worktrees (~/.omp/wt)" },
+		help: commandHelp.worktreeHelp,
 	},
 	{
 		name: "search",
 		load: () => import("./commands/web-search").then(m => m.default),
 		aliases: ["q"],
-		help: { description: "Test web search providers" },
+		help: commandHelp.searchHelp,
 	},
 ];
 

packages/coding-agent/src/cli/command-help.ts

@@ -0,0 +1,99 @@
+import type { CommandMetadata } from "@oh-my-pi/pi-utils/cli";
+
+export const acpHelp = {
+	description: "Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio",
+} satisfies CommandMetadata;
+
+export const agentsHelp = { description: "Manage bundled task agents" } satisfies CommandMetadata;
+
+export const authBrokerHelp = {
+	description: "Manage the omp auth-broker (credential vault)",
+} satisfies CommandMetadata;
+
+export const authGatewayHelp = {
+	description: "Run an auth-gateway forward proxy backed by the configured broker",
+} satisfies CommandMetadata;
+
+export const benchHelp = {
+	description: "Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)",
+} satisfies CommandMetadata;
+
+export const cleanseHelp = {
+	description: "Detect and fix project diagnostics with weighted parallel subagents",
+} satisfies CommandMetadata;
+
+export const commitHelp = { description: "Generate a commit message and update changelogs" } satisfies CommandMetadata;
+
+export const completionsHelp = {
+	description: "Print a shell completion script (bash, zsh, or fish)",
+} satisfies CommandMetadata;
+
+export const completeHelp = { hidden: true } satisfies CommandMetadata;
+
+export const configHelp = { description: "Manage configuration settings" } satisfies CommandMetadata;
+
+export const dryBalanceHelp = {
+	description: "Dry-run OAuth account balancing across random session ids",
+} satisfies CommandMetadata;
+
+export const galleryHelp = {
+	description: "Preview tool renderers across streaming, in-progress, success, and failure states",
+} satisfies CommandMetadata;
+
+export const gcHelp = { description: "Run storage garbage collection" } satisfies CommandMetadata;
+
+export const grepHelp = { description: "Test grep tool" } satisfies CommandMetadata;
+
+export const grievancesHelp = {
+	description: "View, clean, or push reported tool issues (auto-QA grievances)",
+} satisfies CommandMetadata;
+
+export const installHelp = {
+	description: "Install or link an extension package (alias of `plugin install`/`plugin link`)",
+} satisfies CommandMetadata;
+
+export const joinHelp = { description: "Join a shared collab session (same as /join)" } satisfies CommandMetadata;
+
+export const modelsHelp = { description: "List, search, and refresh available models" } satisfies CommandMetadata;
+
+export const pluginHelp = { description: "Manage plugins (install, uninstall, list, etc.)" } satisfies CommandMetadata;
+
+export const readHelp = {
+	description: "Show what the read tool will return for a path, URL, or internal URI",
+} satisfies CommandMetadata;
+
+export const sayHelp = {
+	description: "Synthesize text with the local TTS engine and play it through the speakers",
+} satisfies CommandMetadata;
+
+export const searchHelp = { description: "Test web search providers" } satisfies CommandMetadata;
+
+export const setupHelp = {
+	description: "Run onboarding setup or install dependencies for optional features",
+} satisfies CommandMetadata;
+
+export const shellHelp = { description: "Interactive shell console" } satisfies CommandMetadata;
+
+export const sshHelp = { description: "Manage SSH host configurations" } satisfies CommandMetadata;
+
+export const statsHelp = { description: "View usage statistics" } satisfies CommandMetadata;
+
+export const tinyModelsHelp = {
+	description: "Download tiny local models (session titles + memory)",
+} satisfies CommandMetadata;
+
+export const tokenHelp = { description: "Get the API key or OAuth token for a provider" } satisfies CommandMetadata;
+
+export const ttsrHelp = {
+	description: "Inspect and test Time-Traveling Stream Rules (TTSR)",
+} satisfies CommandMetadata;
+
+export const updateHelp = { description: "Check for and install updates" } satisfies CommandMetadata;
+
+export const usageHelp = {
+	description: "Show provider usage limits for every authenticated account",
+} satisfies CommandMetadata;
+
+export const worktreeHelp = {
+	description: "List or clear agent-managed git worktrees (~/.omp/wt)",
+} satisfies CommandMetadata;

packages/coding-agent/src/commands/acp.ts

@@ -4,13 +4,15 @@
  * Thin wrapper around the launch flow that forces `mode: "acp"` unless the
  * ACP terminal-auth flag asks the same command to open the interactive TUI.
  */
+
 import { Command } from "@oh-my-pi/pi-utils/cli";
 import { type Args as ParsedArgs, parseArgs, reportCliUsageError } from "../cli/args";
+import { acpHelp as commandHelp } from "../cli/command-help";
 import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
 
 export default class Acp extends Command {
-	static description = "Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio";
+	static description = commandHelp.description;
 	static strict = false;
 
 	async run(): Promise<void> {

packages/coding-agent/src/commands/agents.ts

@@ -1,15 +1,16 @@
 /**
  * Manage bundled task agents.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import { type AgentsAction, type AgentsCommandArgs, runAgentsCommand } from "../cli/agents-cli";
+import { agentsHelp as commandHelp } from "../cli/command-help";
 import { initTheme } from "../modes/theme/theme";
 
 const ACTIONS: AgentsAction[] = ["unpack"];
 
 export default class Agents extends Command {
-	static description = "Manage bundled task agents";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Agents action",

packages/coding-agent/src/commands/auth-broker.ts

@@ -1,6 +1,7 @@
 /**
  * `omp auth-broker` — manage the omp credential vault.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import {
 	AUTH_BROKER_ACTIONS,
@@ -8,11 +9,11 @@ import {
 	type AuthBrokerCommandArgs,
 	runAuthBrokerCommand,
 } from "../cli/auth-broker-cli";
+import { authBrokerHelp as commandHelp } from "../cli/command-help";
 import { initTheme } from "../modes/theme/theme";
 
 export default class AuthBroker extends Command {
-	static description = "Manage the omp auth-broker (credential vault)";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Sub-command",

packages/coding-agent/src/commands/auth-gateway.ts

@@ -1,6 +1,7 @@
 /**
  * `omp auth-gateway` — run a forward proxy that injects auth from the broker.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import {
 	AUTH_GATEWAY_ACTIONS,
@@ -8,11 +9,11 @@ import {
 	type AuthGatewayCommandArgs,
 	runAuthGatewayCommand,
 } from "../cli/auth-gateway-cli";
+import { authGatewayHelp as commandHelp } from "../cli/command-help";
 import { initTheme } from "../modes/theme/theme";
 
 export default class AuthGateway extends Command {
-	static description = "Run an auth-gateway forward proxy backed by the configured broker";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Sub-command",

packages/coding-agent/src/commands/bench.ts

@@ -1,11 +1,10 @@
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { runBenchCommand } from "../cli/bench-cli";
+import { benchHelp as commandHelp } from "../cli/command-help";
 import { SERVICE_TIER_OPENAI_VALUES } from "../config/service-tier";
 
 export default class Bench extends Command {
-	static description =
-		"Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)";
-
+	static description = commandHelp.description;
 	static args = {
 		models: Args.string({
 			description: "Model selectors (provider/model or fuzzy id, e.g. opus)",

packages/coding-agent/src/commands/cleanse.ts

@@ -1,11 +1,11 @@
 import { postmortem } from "@oh-my-pi/pi-utils";
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { runCleanseCommand } from "../cleanse";
+import { cleanseHelp as commandHelp } from "../cli/command-help";
 import { CliUsageError } from "../cli/usage-error";
 
 export default class Cleanse extends Command {
-	static description = "Detect and fix project diagnostics with weighted parallel subagents";
-
+	static description = commandHelp.description;
 	static flags = {
 		agents: Flags.integer({
 			char: "n",

packages/coding-agent/src/commands/commit.ts

@@ -1,15 +1,16 @@
 /**
  * Generate and optionally push a commit with changelog updates.
  */
+
 import { postmortem } from "@oh-my-pi/pi-utils";
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { commitHelp as commandHelp } from "../cli/command-help";
 import { runCommitCommand } from "../commit";
 import type { CommitCommandArgs } from "../commit/types";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Commit extends Command {
-	static description = "Generate a commit message and update changelogs";
-
+	static description = commandHelp.description;
 	static flags = {
 		push: Flags.boolean({ description: "Push after committing" }),
 		"dry-run": Flags.boolean({ description: "Preview without committing" }),

packages/coding-agent/src/commands/complete.ts

@@ -10,10 +10,11 @@
  */
 import { type GeneratedProvider, getBundledModels, getBundledProviders } from "@oh-my-pi/pi-catalog/models";
 import { Command } from "@oh-my-pi/pi-utils/cli";
+import { completeHelp as commandHelp } from "../cli/command-help";
 import { SessionManager } from "../session/session-manager";
 
 export default class Complete extends Command {
-	static hidden = true;
+	static hidden = commandHelp.hidden;
 	static strict = false;
 
 	async run(): Promise<void> {

packages/coding-agent/src/commands/completions.ts

@@ -4,8 +4,10 @@
  * The script is derived entirely from the declarative command/flag metadata
  * (see `cli/completion-gen.ts`), so it never drifts from the actual CLI surface.
  */
+
 import { APP_NAME, VERSION } from "@oh-my-pi/pi-utils";
 import { Args, type CliConfig, Command, type CommandCtor } from "@oh-my-pi/pi-utils/cli";
+import { completionsHelp as commandHelp } from "../cli/command-help";
 import { buildSpec, generateCompletion, type Shell } from "../cli/completion-gen";
 import { commands } from "../cli-commands";
 
@@ -14,8 +16,7 @@ const ROOT_COMMAND = "launch";
 const SHELLS = ["bash", "zsh", "fish"] as const;
 
 export default class Completions extends Command {
-	static description = "Print a shell completion script (bash, zsh, or fish)";
-
+	static description = commandHelp.description;
 	static args = {
 		shell: Args.string({
 			description: "Target shell",

packages/coding-agent/src/commands/config.ts

@@ -1,15 +1,16 @@
 /**
  * Manage configuration settings.
  */
+
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { configHelp as commandHelp } from "../cli/command-help";
 import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
 import { initTheme } from "../modes/theme/theme";
 
 const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
 
 export default class Config extends Command {
-	static description = "Manage configuration settings";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Config action",

packages/coding-agent/src/commands/dry-balance.ts

@@ -1,9 +1,9 @@
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { dryBalanceHelp as commandHelp } from "../cli/command-help";
 import { runDryBalanceCommand } from "../cli/dry-balance-cli";
 
 export default class DryBalance extends Command {
-	static description = "Dry-run OAuth account balancing across random session ids";
-
+	static description = commandHelp.description;
 	static args = {
 		model: Args.string({
 			description: "Model selector (provider/model or fuzzy id). Defaults to the configured default model.",

packages/coding-agent/src/commands/gallery.ts

@@ -1,12 +1,13 @@
 /**
  * Render every built-in tool's renderer across its lifecycle states.
  */
+
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { galleryHelp as commandHelp } from "../cli/command-help";
 import { GALLERY_STATE_TOKENS, type GalleryState, parseGalleryStates, runGalleryCommand } from "../cli/gallery-cli";
 
 export default class Gallery extends Command {
-	static description = "Preview tool renderers across streaming, in-progress, success, and failure states";
-
+	static description = commandHelp.description;
 	static flags = {
 		tool: Flags.string({ char: "t", description: "Render a single tool by name" }),
 		state: Flags.string({

packages/coding-agent/src/commands/gc.ts

@@ -1,12 +1,13 @@
 /**
  * Run on-disk storage maintenance.
  */
+
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { gcHelp as commandHelp } from "../cli/command-help";
 import { collectGcErrors, type GcCommandArgs, runGcCommand } from "../cli/gc-cli";
 
 export default class Gc extends Command {
-	static description = "Run storage garbage collection";
-
+	static description = commandHelp.description;
 	static flags = {
 		apply: Flags.boolean({ description: "Apply changes (default is dry-run)" }),
 		json: Flags.boolean({ description: "Output JSON" }),

packages/coding-agent/src/commands/grep.ts

@@ -1,14 +1,15 @@
 /**
  * Test grep tool.
  */
+
 import { GrepOutputMode } from "@oh-my-pi/pi-natives";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { grepHelp as commandHelp } from "../cli/command-help";
 import { type GrepCommandArgs, runGrepCommand } from "../cli/grep-cli";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Grep extends Command {
-	static description = "Test grep tool";
-
+	static description = commandHelp.description;
 	static args = {
 		pattern: Args.string({ description: "Regex pattern to search for", required: false }),
 		path: Args.string({ description: "Directory or file to search", required: false }),

packages/coding-agent/src/commands/grievances.ts

@@ -1,12 +1,13 @@
 /**
  * View, clean, and push reported tool issues from automated QA.
  */
+
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { grievancesHelp as commandHelp } from "../cli/command-help";
 import { cleanGrievances, listGrievances, pushGrievances } from "../cli/grievances-cli";
 
 export default class Grievances extends Command {
-	static description = "View, clean, or push reported tool issues (auto-QA grievances)";
-
+	static description = commandHelp.description;
 	static args = {
 		// Positional action: "list" (default), "clean", or "push". A positional
 		// arg keeps the historical `omp grievances` invocation working unchanged

packages/coding-agent/src/commands/install.ts

@@ -21,6 +21,7 @@
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { installHelp as commandHelp } from "../cli/command-help";
 import { type PluginAction, type PluginCommandArgs, runPluginCommand } from "../cli/plugin-cli";
 import { initTheme } from "../modes/theme/theme";
 
@@ -41,8 +42,7 @@ export function looksLikeLocalPath(target: string, cwd?: string): boolean {
 }
 
 export default class Install extends Command {
-	static description = "Install or link an extension package (alias of `plugin install`/`plugin link`)";
-
+	static description = commandHelp.description;
 	static args = {
 		targets: Args.string({
 			description: "Local path, npm spec, or marketplace ref (e.g. ./my-ext, my-pkg@1.2.3, name@marketplace)",

packages/coding-agent/src/commands/join.ts

@@ -2,14 +2,15 @@
  * Join a shared collab session from the CLI: launches the interactive TUI and
  * immediately runs `/join <link>`.
  */
+
 import { APP_NAME } from "@oh-my-pi/pi-utils";
 import { Args, Command } from "@oh-my-pi/pi-utils/cli";
 import { parseArgs } from "../cli/args";
+import { joinHelp as commandHelp } from "../cli/command-help";
 import { runRootCommand } from "../main";
 
 export default class Join extends Command {
-	static description = "Join a shared collab session (same as /join)";
-
+	static description = commandHelp.description;
 	static args = {
 		link: Args.string({
 			description: "Collab link shared by the host (/collab)",

packages/coding-agent/src/commands/models.ts

@@ -1,13 +1,14 @@
 /**
  * List, search, and refresh available models.
  */
+
 import { APP_NAME } from "@oh-my-pi/pi-utils";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { modelsHelp as commandHelp } from "../cli/command-help";
 import { resolveModelsArgs, runModelsCommand } from "../cli/models-cli";
 
 export default class Models extends Command {
-	static description = "List, search, and refresh available models";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "ls (default) | find | refresh | <provider>",

packages/coding-agent/src/commands/plugin.ts

@@ -1,7 +1,9 @@
 /**
  * Manage plugins (install, uninstall, list, etc.).
  */
+
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { pluginHelp as commandHelp } from "../cli/command-help";
 import { type PluginAction, type PluginCommandArgs, runPluginCommand } from "../cli/plugin-cli";
 import { initTheme } from "../modes/theme/theme";
 
@@ -21,8 +23,7 @@ const ACTIONS: PluginAction[] = [
 ];
 
 export default class Plugin extends Command {
-	static description = "Manage plugins (install, uninstall, list, etc.)";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Plugin action",

packages/coding-agent/src/commands/read.ts

@@ -1,13 +1,14 @@
 /**
  * Show what the read tool will return for a path, URL, or internal URI.
  */
+
 import { Args, Command } from "@oh-my-pi/pi-utils/cli";
+import { readHelp as commandHelp } from "../cli/command-help";
 import { type ReadCommandArgs, runReadCommand } from "../cli/read-cli";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Read extends Command {
-	static description = "Show what the read tool will return for a path, URL, or internal URI";
-
+	static description = commandHelp.description;
 	static args = {
 		path: Args.string({
 			description:

packages/coding-agent/src/commands/say.ts

@@ -8,9 +8,11 @@
  * streamed segments into one WAV. The first run downloads the configured local
  * model into the worker's cache.
  */
+
 import { getProjectDir } from "@oh-my-pi/pi-utils";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import chalk from "chalk";
+import { sayHelp as commandHelp } from "../cli/command-help";
 import { Settings, settings } from "../config/settings";
 import { TTS_LOCAL_VOICE_VALUES } from "../tts/models";
 import { SpeakableStream } from "../tts/speakable";
@@ -19,8 +21,7 @@ import { shutdownTtsClient, ttsClient } from "../tts/tts-client";
 import { encodeWav } from "../tts/wav";
 
 export default class Say extends Command {
-	static description = "Synthesize text with the local TTS engine and play it through the speakers";
-
+	static description = commandHelp.description;
 	static args = {
 		text: Args.string({ description: "Text to speak (or use --file)" }),
 	};

packages/coding-agent/src/commands/setup.ts

@@ -1,8 +1,10 @@
 /**
  * Run onboarding setup or install dependencies for optional features.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import { parseArgs } from "../cli/args";
+import { setupHelp as commandHelp } from "../cli/command-help";
 import { runSetupCommand, type SetupCommandArgs, type SetupComponent } from "../cli/setup-cli";
 import { runRootCommand } from "../main";
 import { initTheme } from "../modes/theme/theme";
@@ -29,8 +31,7 @@ export async function runOnboardingSetup(deps: OnboardingSetupDependencies = {})
 }
 
 export default class Setup extends Command {
-	static description = "Run onboarding setup or install dependencies for optional features";
-
+	static description = commandHelp.description;
 	static args = {
 		component: Args.string({
 			description: "Optional component to install",

packages/coding-agent/src/commands/shell.ts

@@ -1,13 +1,14 @@
 /**
  * Interactive shell console.
  */
+
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { shellHelp as commandHelp } from "../cli/command-help";
 import { runShellCommand, type ShellCommandArgs } from "../cli/shell-cli";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Shell extends Command {
-	static description = "Interactive shell console";
-
+	static description = commandHelp.description;
 	static flags = {
 		cwd: Flags.string({ char: "C", description: "Set working directory for commands" }),
 		timeout: Flags.integer({ char: "t", description: "Timeout per command in milliseconds" }),

packages/coding-agent/src/commands/ssh.ts

@@ -1,15 +1,16 @@
 /**
  * Manage SSH host configurations.
  */
+
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { sshHelp as commandHelp } from "../cli/command-help";
 import { runSSHCommand, type SSHAction, type SSHCommandArgs } from "../cli/ssh-cli";
 import { initTheme } from "../modes/theme/theme";
 
 const ACTIONS: SSHAction[] = ["add", "remove", "list"];
 
 export default class SSH extends Command {
-	static description = "Manage SSH host configurations";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "SSH action",

packages/coding-agent/src/commands/stats.ts

@@ -1,13 +1,14 @@
 /**
  * View usage statistics dashboard.
  */
+
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { statsHelp as commandHelp } from "../cli/command-help";
 import { runStatsCommand, type StatsCommandArgs } from "../cli/stats-cli";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Stats extends Command {
-	static description = "View usage statistics";
-
+	static description = commandHelp.description;
 	static flags = {
 		port: Flags.integer({ char: "p", description: "Port for the dashboard server", default: 3847 }),
 		json: Flags.boolean({ char: "j", description: "Output stats as JSON", default: false }),

packages/coding-agent/src/commands/tiny-models.ts

@@ -1,11 +1,11 @@
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { tinyModelsHelp as commandHelp } from "../cli/command-help";
 import { runTinyModelsCommand, type TinyModelsAction, type TinyModelsCommandArgs } from "../cli/tiny-models-cli";
 
 const ACTIONS: TinyModelsAction[] = ["download", "list"];
 
 export default class TinyModels extends Command {
-	static description = "Download tiny local models (session titles + memory)";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Action to perform",

packages/coding-agent/src/commands/token.ts

@@ -5,13 +5,13 @@
 import { PROVIDER_REGISTRY } from "@oh-my-pi/pi-ai";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import chalk from "chalk";
+import { tokenHelp as commandHelp } from "../cli/command-help";
 import { isAuthenticated, ModelRegistry } from "../config/model-registry";
 import { discoverAuthStorage } from "../sdk";
 import { getAvailableAuthMethods } from "../web/search/providers/perplexity-auth";
 
 export default class Token extends Command {
-	static description = "Get the API key or OAuth token for a provider";
-
+	static description = commandHelp.description;
 	static args = {
 		provider: Args.string({
 			description: "Provider ID (e.g. anthropic, openai)",

packages/coding-agent/src/commands/ttsr.ts

@@ -8,6 +8,7 @@ import * as path from "node:path";
  * shows every TTSR-registered rule the current project/user config would load.
  */
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { ttsrHelp as commandHelp } from "../cli/command-help";
 import {
 	runTtsrCommand,
 	TTSR_ACTIONS,
@@ -19,8 +20,7 @@ import {
 import type { TtsrMatchSource } from "../export/ttsr";
 
 export default class Ttsr extends Command {
-	static description = "Inspect and test Time-Traveling Stream Rules (TTSR)";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "TTSR action",

packages/coding-agent/src/commands/update.ts

@@ -1,14 +1,15 @@
 /**
  * Check for and install updates.
  */
+
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { updateHelp as commandHelp } from "../cli/command-help";
 import * as pluginCli from "../cli/plugin-cli";
 import * as updateCli from "../cli/update-cli";
 import { initTheme } from "../modes/theme/theme";
 
 export default class Update extends Command {
-	static description = "Check for and install updates";
-
+	static description = commandHelp.description;
 	static flags = {
 		force: Flags.boolean({ char: "f", description: "Force update", default: false }),
 		check: Flags.boolean({ char: "c", description: "Check for updates without installing", default: false }),

packages/coding-agent/src/commands/usage.ts

@@ -1,12 +1,13 @@
 /**
  * Show provider usage limits for every authenticated account.
  */
+
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { usageHelp as commandHelp } from "../cli/command-help";
 import { runUsageCommand } from "../cli/usage-cli";
 
 export default class Usage extends Command {
-	static description = "Show provider usage limits for every authenticated account";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Optional subcommand to execute",

packages/coding-agent/src/commands/web-search.ts

@@ -1,7 +1,9 @@
 /**
  * Test web search providers.
  */
+
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { searchHelp as commandHelp } from "../cli/command-help";
 import { runSearchCommand, type SearchCommandArgs } from "../cli/web-search-cli";
 import { SEARCH_PROVIDER_ORDER } from "../web/search/provider";
 
@@ -10,8 +12,7 @@ const PROVIDERS: Array<string> = ["auto", ...SEARCH_PROVIDER_ORDER];
 const RECENCY: NonNullable<SearchCommandArgs["recency"]>[] = ["day", "week", "month", "year"];
 
 export default class Search extends Command {
-	static description = "Test web search providers";
-
+	static description = commandHelp.description;
 	static aliases = ["q"];
 
 	static args = {

packages/coding-agent/src/commands/worktree.ts

@@ -1,14 +1,15 @@
 /**
  * List and clean up agent-managed git worktrees under `~/.omp/wt`.
  */
+
 import { getProjectDir } from "@oh-my-pi/pi-utils";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { worktreeHelp as commandHelp } from "../cli/command-help";
 import { clearWorktrees, listWorktrees } from "../cli/worktree-cli";
 import { Settings } from "../config/settings";
 
 export default class Worktree extends Command {
-	static description = "List or clear agent-managed git worktrees (~/.omp/wt)";
-
+	static description = commandHelp.description;
 	static aliases = ["wt"];
 
 	static args = {