fix(help): add missing examples and normalize option ordering

Add examples to undo (was the only command without any). Fix missing
descriptions on example lines in branch rename, rename, repo clone, and
list. Fix misleading bare `arb branch rename` example (needs --continue).

Normalize option registration order across push, pull, delete, detach,
rename, and branch rename to match the canonical pattern established by
rebase/merge/retarget: domain-specific flags, fetch pair, --yes,
--dry-run, --verbose, scope expansion, --where, --continue/--abort.

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

Author: henrikje

src/commands/branch-rename.ts

@@ -541,16 +541,16 @@ export function registerBranchRenameSubcommand(parent: Command): void {
     .option("-r, --delete-remote", "Delete old branch on remote after rename")
     .option("--fetch", "Fetch from all remotes before rename (default)")
     .option("-N, --no-fetch", "Skip fetching before rename")
-    .option("--dry-run", "Show what would happen without executing")
     .option("-y, --yes", "Skip confirmation prompt")
+    .option("--dry-run", "Show what would happen without executing")
     .option("--include-in-progress", "Rename repos even if they have an in-progress git operation")
     .addOption(new Option("--continue", "Resume a partial branch rename").conflicts("abort"))
     .addOption(
       new Option("--abort", "Cancel the in-progress branch rename and restore pre-rename state").conflicts("continue"),
     )
     .summary("Rename the workspace branch across all repos")
     .description(
-      "Examples:\n\n  arb branch rename feat/PROJ-209          Rename across all repos\n  arb branch rename feat/PROJ-209 --delete-remote\n  arb branch rename                        Resume after partial failure\n\nRenames the workspace branch locally across all repos and updates .arbws/config.json. The workspace directory is not renamed — use 'arb rename' to rename both the workspace and branch together.\n\nFetches before assessing to get fresh remote state (use -N/--no-fetch to skip). Shows a plan and asks for confirmation before proceeding. Repos with an in-progress git operation (rebase, merge, cherry-pick) are skipped by default — use --include-in-progress to override.\n\nBranch rename is tracked as an operation in .arbws/operation.json. If it fails partway, use 'arb branch rename --continue' to retry remaining repos, or 'arb branch rename --abort' to roll back. After rename, tracking is cleared so 'arb push' treats the branch as new and pushes under the new name. Use --delete-remote to also delete the old remote branch during rename.",
+      "Examples:\n\n  arb branch rename feat/PROJ-209          Rename across all repos\n  arb branch rename feat/PROJ-209 -r       Also delete old remote branch\n  arb branch rename --continue             Resume after partial failure\n\nRenames the workspace branch locally across all repos and updates .arbws/config.json. The workspace directory is not renamed — use 'arb rename' to rename both the workspace and branch together.\n\nFetches before assessing to get fresh remote state (use -N/--no-fetch to skip). Shows a plan and asks for confirmation before proceeding. Repos with an in-progress git operation (rebase, merge, cherry-pick) are skipped by default — use --include-in-progress to override.\n\nBranch rename is tracked as an operation in .arbws/operation.json. If it fails partway, use 'arb branch rename --continue' to retry remaining repos, or 'arb branch rename --abort' to roll back. After rename, tracking is cleared so 'arb push' treats the branch as new and pushes under the new name. Use --delete-remote to also delete the old remote branch during rename.",
     )
     .action(
       arbAction(async (ctx, newNameArg: string | undefined, options: RenameOptions) => {

src/commands/delete.ts

@@ -465,22 +465,22 @@ function buildConfirmMessage(count: number, deleteRemote: boolean): string {
 export function registerDeleteCommand(program: Command): void {
   program
     .command("delete [names...]")
-    .option("-y, --yes", "Skip confirmation prompt")
     .option("-f, --force", "Force deletion of at-risk workspaces")
     .option("-r, --delete-remote", "Delete remote branches")
     .option(
       "-a, --all-safe",
       "Delete all safe workspaces (no uncommitted changes, unpushed commits, or branch drift; behind base is fine)",
     )
-    .option("-w, --where <filter>", "Filter workspaces by repo status flags (comma = OR, + = AND, ^ = negate)")
     .option(
       "--older-than <duration>",
       "Only delete workspaces not touched in the given duration (e.g. 30d, 2w, 3m, 1y)",
     )
     .option("--newer-than <duration>", "Only delete workspaces touched within the given duration (e.g. 7d, 2w)")
-    .option("--dry-run", "Show what would happen without executing")
     .option("--fetch", "Fetch before assessing workspace status (default)")
     .option("-N, --no-fetch", "Skip fetching")
+    .option("-y, --yes", "Skip confirmation prompt")
+    .option("--dry-run", "Show what would happen without executing")
+    .option("-w, --where <filter>", "Filter workspaces by repo status flags (comma = OR, + = AND, ^ = negate)")
     .summary("Delete one or more workspaces")
     .description(
       "Examples:\n\n  arb delete PROJ-208                      Delete a workspace\n  arb delete --all-safe                    Delete all safe workspaces\n  arb delete --where gone --yes            Delete all merged workspaces\n\nDelete one or more workspaces and their repos. Fetches workspace repos before assessing for fresh remote state (skip with -N/--no-fetch). Shows the status of each repo (uncommitted changes, unpushed commits) and any modified template files before proceeding. Prompts with a workspace picker when run without arguments.\n\nUse --all-safe to batch-delete all workspaces with safe status (no uncommitted changes, unpushed commits, or branch drift). Use --where <filter> to filter by status flags. Use --older-than/--newer-than to filter by workspace activity age. When used without workspace names, these filters select from all matching workspaces (e.g. arb delete --where gone deletes all gone workspaces). In a TTY, --where, --older-than/--newer-than, and --all-safe show an interactive picker with all matches pre-selected, letting you deselect workspaces to keep. When combined with names, filters narrow the selection further (AND logic). Combine with --all-safe to narrow further (e.g. --all-safe --where gone for merged-and-safe workspaces). See 'arb help filtering' for filter syntax.\n\nUse --yes to skip confirmation (and interactive selection), --force to override at-risk safety checks, --delete-remote to also delete the remote branches.\n\nSee 'arb help stacked' for stacked workspace deletion.",

src/commands/detach.ts

@@ -77,10 +77,10 @@ export function registerDetachCommand(program: Command): void {
     .option("-f, --force", "Force detach even with at-risk repos (uncommitted changes, unpushed commits, etc.)")
     .option("-a, --all-repos", "Detach all repos from the workspace")
     .option("--delete-branch", "Delete the local branch from the canonical repo")
-    .option("-y, --yes", "Skip confirmation prompt")
-    .option("--dry-run", "Show what would happen without executing")
     .option("--fetch", "Fetch before detaching (default)")
     .option("-N, --no-fetch", "Skip pre-fetch")
+    .option("-y, --yes", "Skip confirmation prompt")
+    .option("--dry-run", "Show what would happen without executing")
     .summary("Detach repos from the workspace")
     .description(
       "Examples:\n\n  arb detach api                           Detach a single repo\n  arb detach api web --delete-branch       Detach and delete local branch\n  arb detach --all-repos --force           Detach all, skip safety checks\n\nDetach one or more repos from the current workspace without deleting the workspace itself. Shows a plan and asks for confirmation before proceeding. Regenerates templates that reference the repo list (those using {% for repo in workspace.repos %}) to reflect the updated repo list. Skips repos with at-risk state (uncommitted changes, unpushed commits, operation in progress, detached HEAD, wrong branch) unless --force is used. Use --all-repos to detach all repos. Use --delete-branch to also delete the local branch from the canonical repo. Fetches the selected repos before detaching for fresh state (skip with -N/--no-fetch). Use --yes to skip the confirmation prompt. Use --dry-run to see what would happen without executing.",

src/commands/list.ts

@@ -60,7 +60,7 @@ export function registerListCommand(program: Command): void {
     .command("list")
     .summary("List workspaces with status overview")
     .description(
-      "Examples:\n\n  arb list                                 List all workspaces\n  arb list --where dirty                   Only dirty workspaces\n  arb list -q | xargs -I{} arb status -C {}\n\nList all workspaces in the project with aggregate status. Shows branch, base, repo count, last commit date, and status for each workspace. The last commit date is the most recent author date across all repos, shown as relative time (e.g. '3 days ago'). The active workspace (the one you're currently inside) is marked with *.\n\nUse --dirty / -d to show only workspaces with dirty repos, or --where <filter> to filter by status flags (any workspace with at least one matching repo is shown). See 'arb help filtering' for filter syntax. Use --no-status to skip per-repo status gathering for faster output.\n\nFetches workspace repos by default for fresh remote data (skip with -N/--no-fetch). Press Ctrl+C during the fetch to cancel and use stale data. Quiet mode (-q) skips fetching by default for scripting speed.\n\nUse --json for machine-readable output. See 'arb help scripting' for output modes and piping.",
+      "Examples:\n\n  arb list                                 List all workspaces\n  arb list --where dirty                   Only dirty workspaces\n  arb list -q | xargs -I{} arb status -C {}   Run status on each workspace\n\nList all workspaces in the project with aggregate status. Shows branch, base, repo count, last commit date, and status for each workspace. The last commit date is the most recent author date across all repos, shown as relative time (e.g. '3 days ago'). The active workspace (the one you're currently inside) is marked with *.\n\nUse --dirty / -d to show only workspaces with dirty repos, or --where <filter> to filter by status flags (any workspace with at least one matching repo is shown). See 'arb help filtering' for filter syntax. Use --no-status to skip per-repo status gathering for faster output.\n\nFetches workspace repos by default for fresh remote data (skip with -N/--no-fetch). Press Ctrl+C during the fetch to cancel and use stale data. Quiet mode (-q) skips fetching by default for scripting speed.\n\nUse --json for machine-readable output. See 'arb help scripting' for output modes and piping.",
     )
     .option("--fetch", "Fetch workspace repos before listing (default)")
     .option("-N, --no-fetch", "Skip fetching")

src/commands/pull.ts

@@ -55,13 +55,13 @@ export function registerPullCommand(program: Command): void {
   program
     .command("pull [repos...]")
     .option("--reset", "Reset to remote tip instead of pulling (overrides rebased-locally skip)")
-    .option("-y, --yes", "Skip confirmation prompt")
-    .option("--dry-run", "Show what would happen without executing")
     .addOption(new Option("--rebase", "Pull with rebase").conflicts("merge"))
     .addOption(new Option("--merge", "Pull with merge").conflicts("rebase"))
+    .option("-y, --yes", "Skip confirmation prompt")
+    .option("--dry-run", "Show what would happen without executing")
+    .option("-v, --verbose", "Show incoming commits in the plan")
     .option("--autostash", "Stash uncommitted changes before pull, re-apply after")
     .option("--include-wrong-branch", "Include repos on a different branch than the workspace")
-    .option("-v, --verbose", "Show incoming commits in the plan")
     .option("-w, --where <filter>", "Only pull repos matching status filter (comma = OR, + = AND, ^ = negate)")
     .addOption(new Option("--continue", "Resume after resolving conflicts").conflicts("abort"))
     .addOption(new Option("--abort", "Cancel the in-progress pull and restore pre-pull state").conflicts("continue"))

src/commands/push.ts

@@ -33,12 +33,12 @@ export function registerPushCommand(program: Command): void {
     .command("push [repos...]")
     .option("-f, --force", "Force push with lease")
     .option("--include-merged", "Include branches already merged into base")
-    .option("--include-wrong-branch", "Include repos on a different branch than the workspace")
     .option("--fetch", "Fetch from all remotes before push (default)")
     .option("-N, --no-fetch", "Skip fetching before push")
     .option("-y, --yes", "Skip confirmation prompt")
     .option("--dry-run", "Show what would happen without executing")
     .option("-v, --verbose", "Show outgoing commits in the plan")
+    .option("--include-wrong-branch", "Include repos on a different branch than the workspace")
     .option("-w, --where <filter>", "Only push repos matching status filter (comma = OR, + = AND, ^ = negate)")
     .summary("Push feature branches to the remote")
     .description(

src/commands/rename.ts

@@ -398,16 +398,16 @@ export function registerRenameCommand(program: Command): void {
     .option("-r, --delete-remote", "Delete old branch on remote after rename")
     .option("--fetch", "Fetch from all remotes before rename (default)")
     .option("-N, --no-fetch", "Skip fetching before rename")
+    .option("-y, --yes", "Skip confirmation prompt")
+    .option("--dry-run", "Show what would happen without executing")
+    .option("--include-in-progress", "Rename repos even if they have an in-progress git operation")
     .addOption(new Option("--continue", "Resume a partial workspace rename").conflicts("abort"))
     .addOption(
       new Option("--abort", "Cancel the in-progress rename and restore pre-rename state").conflicts("continue"),
     )
-    .option("--dry-run", "Show what would happen without executing")
-    .option("-y, --yes", "Skip confirmation prompt")
-    .option("--include-in-progress", "Rename repos even if they have an in-progress git operation")
     .summary("Rename the workspace (directory + branch)")
     .description(
-      "Examples:\n\n  arb rename PROJ-209                      Rename workspace and branch\n  arb rename PROJ-209 --branch feat/PROJ-209\n  arb rename --branch feat/PROJ-209        Derive workspace name from branch\n\nRenames the workspace directory and branch across all repos. Completes the create/delete/rename lifecycle triad.\n\nThe positional <new-name> sets the workspace directory name and, by default, the branch name. Use --branch to set the branch name independently (e.g. 'arb rename PROJ-208 --branch feat/PROJ-208'). If only --branch is provided, the workspace name is derived from the last path segment.\n\nUse --base to change the base branch as part of the rename, completing the 'repurpose workspace' workflow.\n\nFetches before assessing to get fresh remote state (use -N/--no-fetch to skip). Shows a plan and asks for confirmation before proceeding. Repos with an in-progress git operation (rebase, merge, cherry-pick) are skipped.\n\nRename is tracked as an operation in .arbws/operation.json. If it fails partway, use 'arb rename --continue' to retry, or 'arb rename --abort' to roll back.",
+      "Examples:\n\n  arb rename PROJ-209                      Rename workspace and branch\n  arb rename PROJ-209 --branch feat/PROJ-209   Set branch independently\n  arb rename --branch feat/PROJ-209        Derive workspace name from branch\n\nRenames the workspace directory and branch across all repos. Completes the create/delete/rename lifecycle triad.\n\nThe positional <new-name> sets the workspace directory name and, by default, the branch name. Use --branch to set the branch name independently (e.g. 'arb rename PROJ-208 --branch feat/PROJ-208'). If only --branch is provided, the workspace name is derived from the last path segment.\n\nUse --base to change the base branch as part of the rename, completing the 'repurpose workspace' workflow.\n\nFetches before assessing to get fresh remote state (use -N/--no-fetch to skip). Shows a plan and asks for confirmation before proceeding. Repos with an in-progress git operation (rebase, merge, cherry-pick) are skipped.\n\nRename is tracked as an operation in .arbws/operation.json. If it fails partway, use 'arb rename --continue' to retry, or 'arb rename --abort' to roll back.",
     )
     .action(
       arbAction(async (ctx, newNameArg: string | undefined, options: RenameCommandOptions) => {

src/commands/repo.ts

@@ -88,7 +88,7 @@ export function registerRepoCommand(program: Command): void {
     .option("--upstream <url>", "Add an upstream remote (for fork workflows)")
     .summary("Clone a repo into .arb/repos/")
     .description(
-      "Examples:\n\n  arb repo clone git@github.com:org/api\n  arb repo clone git@github.com:org/api backend\n  arb repo clone git@github.com:me/api --upstream git@github.com:org/api\n\nClone a git repository into .arb/repos/<name> as a canonical copy. These permanent clones are never worked in directly — instead, arb creates worktrees that point back to them. The repo name is derived from the URL if not specified.\n\nFor fork workflows, use --upstream to add the canonical repo as an upstream remote. This sets remote.pushDefault so arb knows to push to origin (your fork) and rebase onto upstream.",
+      "Examples:\n\n  arb repo clone git@github.com:org/api                                   Clone a repo\n  arb repo clone git@github.com:org/api backend                           Clone with custom name\n  arb repo clone git@github.com:me/api --upstream git@github.com:org/api  Clone fork with upstream\n\nClone a git repository into .arb/repos/<name> as a canonical copy. These permanent clones are never worked in directly — instead, arb creates worktrees that point back to them. The repo name is derived from the URL if not specified.\n\nFor fork workflows, use --upstream to add the canonical repo as an upstream remote. This sets remote.pushDefault so arb knows to push to origin (your fork) and rebase onto upstream.",
     )
     .action(
       arbAction(async (ctx, url: string, nameArg: string | undefined, options) => {