From 1a03ce1c69a2e435856d9431bd906559e4f7cfe5 Mon Sep 17 00:00:00 2001
From: Steve Cliff <steve@devcloud.guru>
Date: Sat, 27 Jun 2026 12:19:42 +0100
Subject: [PATCH] docs(cli): help reflects positional admin grammar + aliases

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 internal/cli/help.go      | 12 +++++++-----
 internal/cli/help_test.go | 15 +++++++++++++++
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/internal/cli/help.go b/internal/cli/help.go
index 36f32e7..6fd96e3 100644
--- a/internal/cli/help.go
+++ b/internal/cli/help.go
@@ -23,11 +23,11 @@ var agentCmds = []cmdHelp{
 
 var adminCmds = []cmdHelp{
 	{"init", "init", "Create the database and add the first account (interactive)."},
-	{"account", "account <add|edit|remove|list> [flags]", "Manage accounts (add/edit accept flags, or run with none for an interactive form)."},
-	{"whitelist", "whitelist <in|out> <add|remove|list> --account <name> [--address A]", "Manage inbound/outbound whitelists."},
-	{"config", "config <set|get> <key> [value]", "Get or set global settings (e.g. audit_retention_days)."},
-	{"audit", "audit list [--account <name>] [--limit N]", "Show recent audit-log entries."},
-	{"doctor", "doctor [--account <name>]", "Check each account's IMAP/SMTP connectivity and auth."},
+	{"account", "account <add|edit|remove|show|list> [name] [flags]", "Manage accounts. `add`/`edit` take a positional name + field flags, or run with none for an interactive form."},
+	{"whitelist", "whitelist <add|remove|list|enable|disable> <account> [address…] --in|--out", "Manage inbound/outbound whitelists. Direction (--in/--out) is required."},
+	{"config", "config <list|get|set> [key] [value]", "List, get, or set global settings (e.g. audit_retention_days)."},
+	{"audit", "audit list [account] [--limit N]", "Show recent audit-log entries."},
+	{"doctor", "doctor [account]", "Check each account's IMAP/SMTP connectivity and auth."},
 	{"version", "version", "Print the emcli version."},
 	{"help", "help [command]", "Show this help, or detailed usage for one command."},
 }
@@ -58,6 +58,8 @@ func printMainHelp(w io.Writer) {
 		fmt.Fprintf(w, "  %-10s %s\n", c.name, c.summary)
 	}
 	fmt.Fprint(w, "\nRun \"emcli <command> --help\" for a command's flags.\n")
+	fmt.Fprint(w, "\nAliases: rm/del = remove, ls = list. Admin commands take positional\n")
+	fmt.Fprint(w, "operands (account/address/key); agent commands use flags (--account …).\n")
 	fmt.Fprint(w, "\nEnvironment:\n")
 	fmt.Fprint(w, "  EMCLI_KEY   base64-encoded 32-byte AES key; required for any command that uses the database\n")
 	fmt.Fprint(w, "  EMCLI_DB    database path (default ~/.config/emcli/emcli.db; %AppData%\\emcli\\emcli.db on Windows)\n")
diff --git a/internal/cli/help_test.go b/internal/cli/help_test.go
index 7d2a964..740429a 100644
--- a/internal/cli/help_test.go
+++ b/internal/cli/help_test.go
@@ -71,3 +71,18 @@ func TestAdminCommandHelpExitsZero(t *testing.T) {
 		}
 	}
 }
+
+func TestHelpReflectsNewGrammar(t *testing.T) {
+	_, out, _ := run(t, "help", "whitelist")
+	if !strings.Contains(out, "<account>") || !strings.Contains(out, "--in") {
+		t.Fatalf("whitelist help should show positional account + --in/--out:\n%s", out)
+	}
+	_, out, _ = run(t, "help", "account")
+	if !strings.Contains(out, "show") {
+		t.Fatalf("account help should list the new show subcommand:\n%s", out)
+	}
+	_, mainOut, mainErr := run(t, "help")
+	if !strings.Contains(mainOut+mainErr, "rm") && !strings.Contains(mainOut+mainErr, "alias") {
+		t.Fatalf("main help should mention aliases:\n%s", mainOut+mainErr)
+	}
+}