docs: implementation plan for human CLI grammar redesign

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

USER-MANUAL.md

@@ -33,8 +33,9 @@ This manual is for **using and administering** `emcli`. It assumes you have the
 ## 1. Key concepts
 
 **Two kinds of commands.**
-- **Admin commands** (`init`, `account`, `whitelist`, `config`, `audit`) require `EMCLI_ADMIN_KEY`
-  and are for *you*, the human. They print human-readable text or open an interactive form.
+- **Admin commands** (`init`, `account add/edit/remove`, `whitelist`, `config`, `audit`) require
+  `EMCLI_ADMIN_KEY` and are for *you*, the human. They print human-readable text or open an
+  interactive form. (`account list` is the one exception — it is also an agent command; see below.)
 - **Agent commands** (`list`, `get`, `search`, `ack`, `send`, `doctor`) require `EMCLI_KEY` (or
   `EMCLI_ADMIN_KEY` as a superset) and are for the *agent*. They print one line of JSON and
   nothing else, so a program can consume them reliably. (`doctor` prints human-readable text but
@@ -124,8 +125,12 @@ DEK for an admin command, even if it somehow knows the agent key.
 
 | Command | Role required |
 |---|---|
-| `list`, `get`, `search`, `ack`, `send`, `doctor` | Agent (`EMCLI_KEY` or `EMCLI_ADMIN_KEY`) |
-| `account`, `whitelist`, `config`, `audit` | Admin (`EMCLI_ADMIN_KEY` required) |
+| `list`, `get`, `search`, `ack`, `send`, `doctor`, `account list` | Agent (`EMCLI_KEY` or `EMCLI_ADMIN_KEY`) |
+| `account add/edit/remove`, `whitelist`, `config`, `audit` | Admin (`EMCLI_ADMIN_KEY` required) |
+
+`account list` is dual-role: with the admin key it prints the full `NAME MODE IMAP USER` table;
+with only `EMCLI_KEY` (an agent) it prints a JSON envelope exposing just `name`, `from`, and
+`can_send` — no host or login username.
 | `init` | Both keys required (writes both wrap slots) |
 
 ### Agent launcher guidance
@@ -261,9 +266,15 @@ emcli account edit --name work --mode RW --smtp-host smtp.example.com --smtp-por
 emcli account edit --name gmail --password 'new-app-password'   # rotate the app password
 ```
 
-> Note: the flag form of `account edit` covers connection/auth fields and `--subject-regex`. To
-> toggle whitelists or `process-backlog`, use the interactive form (`emcli account edit --name X`
-> with no other flags), or the `whitelist` commands in section 6.
+```bash
+emcli account edit --name work --from 'Work Team <you@yourdomain.com>'   # set the send-as address
+emcli account edit --name work --from ''                                 # clear it (revert to username)
+```
+
+> Note: the flag form of `account edit` covers connection/auth fields, `--from`, and
+> `--subject-regex`. Passing `--from ''` clears the send-as address so mail falls back to the login
+> username. To toggle whitelists or `process-backlog`, use the interactive form (`emcli account edit
+> --name X` with no other flags), or the `whitelist` commands in section 6.
 
 **Remove an account** (requires `--yes`):
 
@@ -421,6 +432,11 @@ emcli send --account gmail --to a@x.com --subject "Re: Hi" --body "thanks" \
 client. The source is subject to the inbound whitelist — you can't reply to mail you aren't allowed
 to see.
 
+The message's `From:` is the account's send-as address (`--from`, set on `account add`/`edit`); if
+none is configured it falls back to the login username. A display-name address like
+`Steve Cliff <me@example.com>` shows the name in the recipient's client while the bare address is
+used for the SMTP envelope.
+
 ---
 
 ## 8. The JSON envelope
@@ -541,8 +557,8 @@ base64-encoded 32-byte key (section 2). Agent commands (`list`, `get`, `search`,
 `doctor`) need this key.
 
 **"this command requires EMCLI_ADMIN_KEY (admin privilege)".** Set `EMCLI_ADMIN_KEY` (section 2).
-Admin commands (`account`, `whitelist`, `config`, `audit`, `init`) need this key; `EMCLI_KEY`
-alone is not enough for them.
+Admin commands (`account add/edit/remove`, `whitelist`, `config`, `audit`, `init`) need this key;
+`EMCLI_KEY` alone is not enough for them. (`account list` is the exception — an agent can run it.)
 
 **A command fails to decrypt / wrong key.** The key doesn't match the one used when the database
 was initialised. Restore the original key, or re-run `emcli init` (idempotent — it won't regenerate
@@ -583,7 +599,7 @@ emcli <command> --help # usage and flags for one command
 # Admin (requires EMCLI_ADMIN_KEY)
 emcli init                                            # create DB + add first account (form)
 emcli account add [flags | none for form]            # add an account
-emcli account list                                    # list accounts (no secrets)
+emcli account list                                    # full table (admin) / name+from+can_send JSON (agent)
 emcli account edit --name N [flags | none for form]  # change an account
 emcli account remove --name N --yes                   # delete an account
 emcli whitelist in|out add|remove|list --account N [--address A]

docs/superpowers/plans/2026-06-23-agent-account-list.md

@@ -0,0 +1,497 @@
+# Agent-readable `account list` Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let an agent holding only `EMCLI_KEY` run `emcli account list` and get a reduced JSON view (name, from, can_send), while admin keeps the full text table and `account add/edit/remove` stay admin-only.
+
+**Architecture:** Make `commandRole` subcommand-aware so `account list` routes to the agent role; branch the `list` renderer on whether the admin key is present (admin → existing text table; agent → standard `Success` JSON envelope). No schema change; `ListAccounts` already avoids decrypting secrets.
+
+**Tech Stack:** Go, standard library (`flag`, `encoding/json`), existing `internal/cli` envelope helpers and `internal/crypto` key loaders.
+
+## Global Constraints
+
+- Agent output is the existing JSON envelope shape: `{"error":bool,"error_detail":{...},"data":{...}}` via `Success(...)` / `Failure(...)` in `internal/cli/envelope.go`.
+- Admin `account list` output stays byte-for-byte the current human-readable table (`NAME MODE IMAP USER`).
+- The agent (reduced) view exposes only `name`, `from`, `can_send` — never the IMAP host/port or login username.
+- `from = Account.SendFrom()` (explicit `FromAddress`, else `Username`). `can_send = (Mode == "RW")`.
+- `account add/edit/remove` remain admin-only (hard-require `EMCLI_ADMIN_KEY`, no fallback).
+- Privilege detection: a caller is "admin" iff `crypto.AdminKeyFromEnv()` returns no error.
+- Spec: `docs/superpowers/specs/2026-06-23-agent-account-list-design.md`.
+
+---
+
+### Task 1: Route `account list` to the agent role and render by privilege
+
+**Files:**
+- Modify: `internal/cli/run.go` (`commandRole`, its call site in `Run`)
+- Modify: `internal/cli/admin.go` (the `list` branch of `runAccount`; add `crypto` import)
+- Modify: `internal/cli/role_test.go` (`TestCommandRole`)
+- Modify: `internal/cli/security_invariant_test.go` (refused-commands set)
+- Create/Test: `internal/cli/account_list_test.go`
+
+**Interfaces:**
+- Consumes: `store.Account.SendFrom() string`, `store.Account.Mode string`, `store.Store.ListAccounts() ([]store.Account, error)`, `crypto.AdminKeyFromEnv() ([]byte, error)`, `Success(map[string]any) Envelope`, `Failure(code, msg string) Envelope`, `Envelope.Write(io.Writer) error`, test helpers `adminEnv(t)`, `run(t, args...)`.
+- Produces: `commandRole(args []string) store.Role` (signature changes from `commandRole(cmd string)`). Agent `account list` emits `{"data":{"accounts":[{"name":string,"from":string,"can_send":bool}]}}`.
+
+- [ ] **Step 1: Rewrite `TestCommandRole` for the new signature and subcommand routing**
+
+Replace the body of `TestCommandRole` in `internal/cli/role_test.go` with:
+
+```go
+func TestCommandRole(t *testing.T) {
+	adminCmds := [][]string{
+		{"whitelist"}, {"config"}, {"audit"},
+		{"account"}, {"account", "add"}, {"account", "edit"}, {"account", "remove"},
+	}
+	agentCmds := [][]string{
+		{"list"}, {"get"}, {"search"}, {"ack"}, {"send"}, {"doctor"},
+		{"account", "list"},
+	}
+	for _, c := range adminCmds {
+		if commandRole(c) != store.RoleAdmin {
+			t.Errorf("%v should be admin", c)
+		}
+	}
+	for _, c := range agentCmds {
+		if commandRole(c) != store.RoleAgent {
+			t.Errorf("%v should be agent", c)
+		}
+	}
+}
+```
+
+Note: `init` is intentionally absent from this table. `commandRole({"init"})` falls through to the agent arm, but `Run` dispatches `init` via its own bootstrap path (which requires both keys), so its `commandRole` result is never used — asserting a role for it here would be both wrong and meaningless.
+
+- [ ] **Step 2: Run the routing test to verify it fails to compile**
+
+Run: `go test ./internal/cli/ -run TestCommandRole`
+Expected: FAIL — compile error, `commandRole` takes `string`, called with `[]string`.
+
+- [ ] **Step 3: Make `commandRole` subcommand-aware, update its call site, and fix the security invariant**
+
+In `internal/cli/run.go`, replace:
+
+```go
+func commandRole(cmd string) store.Role {
+	switch cmd {
+	case "account", "whitelist", "config", "audit":
+		return store.RoleAdmin
+	default: // list, get, search, ack, send, doctor
+		return store.RoleAgent
+	}
+}
+```
+
+with:
+
+```go
+func commandRole(args []string) store.Role {
+	switch args[0] {
+	case "account":
+		// account list is a read-only discovery view available to agents;
+		// add/edit/remove mutate config and require admin.
+		if len(args) >= 2 && args[1] == "list" {
+			return store.RoleAgent
+		}
+		return store.RoleAdmin
+	case "whitelist", "config", "audit":
+		return store.RoleAdmin
+	default: // list, get, search, ack, send, doctor
+		return store.RoleAgent
+	}
+}
+```
+
+In `Run`, change the call site from `role := commandRole(cmd)` to `role := commandRole(args)`.
+
+In `internal/cli/security_invariant_test.go`, in `TestAgentKeyCannotRunAdminCommands`, replace the `adminAttempts` entry `{"account", "list"}` so the set covers a *mutating* account command instead (account list is now allowed for agents):
+
+```go
+	adminAttempts := [][]string{
+		{"account", "add", "--name", "x", "--imap-host", "h", "--username", "u@x.com"},
+		{"config", "set", "audit_retention_days", "30"},
+		{"audit"},
+	}
+```
+
+- [ ] **Step 4: Run the cli package tests to verify routing + invariant pass**
+
+Run: `go test ./internal/cli/ -run 'TestCommandRole|TestAgentKeyCannotRunAdminCommands'`
+Expected: PASS (both). The agent can no longer be proven to refuse `account list` — that is intended; the invariant now proves `account add` is refused and the DB is unchanged.
+
+- [ ] **Step 5: Add the rendering tests (agent JSON view + admin text view)**
+
+Create `internal/cli/account_list_test.go`:
+
+```go
+package cli
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// With only EMCLI_KEY set, `account list` emits the reduced JSON envelope:
+// name/from/can_send, and never the IMAP host or login username.
+func TestAccountListAgentJSONView(t *testing.T) {
+	adminEnv(t) // both keys + initialized temp DB
+	run(t, "account", "add", "--name", "work", "--mode", "RW",
+		"--imap-host", "imap.example.com", "--smtp-host", "smtp.example.com",
+		"--username", "login@example.com", "--from", "me@example.com")
+	run(t, "account", "add", "--name", "alerts", "--mode", "RO",
+		"--imap-host", "imap.example.com", "--username", "alerts@example.com")
+
+	// Drop the admin key → caller is an agent.
+	t.Setenv("EMCLI_ADMIN_KEY", "")
+	code, out, errOut := run(t, "account", "list")
+	if code != 0 {
+		t.Fatalf("agent account list should succeed: code=%d err=%q", code, errOut)
+	}
+
+	var env struct {
+		Error bool `json:"error"`
+		Data  struct {
+			Accounts []struct {
+				Name    string `json:"name"`
+				From    string `json:"from"`
+				CanSend bool   `json:"can_send"`
+			} `json:"accounts"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(out), &env); err != nil {
+		t.Fatalf("output is not the agent envelope: %v\n%s", err, out)
+	}
+	if env.Error || len(env.Data.Accounts) != 2 {
+		t.Fatalf("want 2 accounts and no error, got %+v", env)
+	}
+	// The reduced view must not leak the IMAP host or the login username.
+	if strings.Contains(out, "imap.example.com") || strings.Contains(out, "login@example.com") {
+		t.Fatalf("agent view leaked host/username:\n%s", out)
+	}
+
+	got := map[string]struct {
+		from    string
+		canSend bool
+	}{}
+	for _, a := range env.Data.Accounts {
+		got[a.Name] = struct {
+			from    string
+			canSend bool
+		}{a.From, a.CanSend}
+	}
+	if g := got["work"]; g.from != "me@example.com" || !g.canSend {
+		t.Errorf("work: want from=me@example.com can_send=true, got %+v", g)
+	}
+	// alerts has no --from → SendFrom() falls back to the username.
+	if g := got["alerts"]; g.from != "alerts@example.com" || g.canSend {
+		t.Errorf("alerts: want from=alerts@example.com can_send=false, got %+v", g)
+	}
+}
+
+// With the admin key present, `account list` stays the full human-readable table.
+func TestAccountListAdminTextView(t *testing.T) {
+	adminEnv(t)
+	run(t, "account", "add", "--name", "work", "--mode", "RW",
+		"--imap-host", "imap.example.com", "--smtp-host", "smtp.example.com",
+		"--username", "login@example.com", "--from", "me@example.com")
+
+	code, out, _ := run(t, "account", "list")
+	if code != 0 {
+		t.Fatalf("admin account list failed: code=%d", code)
+	}
+	for _, want := range []string{"NAME", "MODE", "IMAP", "USER", "imap.example.com:993", "login@example.com"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("admin view missing %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, `"accounts"`) {
+		t.Fatalf("admin view should be text, not JSON:\n%s", out)
+	}
+}
+```
+
+- [ ] **Step 6: Run the rendering tests to verify the agent view fails**
+
+Run: `go test ./internal/cli/ -run 'TestAccountListAgentJSONView|TestAccountListAdminTextView'`
+Expected: `TestAccountListAdminTextView` PASS (already text); `TestAccountListAgentJSONView` FAIL — output is still the text table, so `json.Unmarshal` errors.
+
+- [ ] **Step 7: Split the `list` branch by privilege in `runAccount`**
+
+In `internal/cli/admin.go`, add the crypto import. Change the import block:
+
+```go
+import (
+	"flag"
+	"fmt"
+	"io"
+	"strconv"
+
+	"git.dcglab.co.uk/steve/emcli/internal/crypto"
+	"git.dcglab.co.uk/steve/emcli/internal/store"
+	"git.dcglab.co.uk/steve/emcli/internal/tui"
+)
+```
+
+Replace the `case "list":` block (currently):
+
+```go
+	case "list":
+		accs, err := st.ListAccounts()
+		if err != nil {
+			fmt.Fprintf(errOut, "list: %v\n", err)
+			return 1
+		}
+		fmt.Fprintf(out, "%-16s %-4s %-28s %s\n", "NAME", "MODE", "IMAP", "USER")
+		for _, a := range accs {
+			fmt.Fprintf(out, "%-16s %-4s %-28s %s\n",
+				a.Name, a.Mode, fmt.Sprintf("%s:%d", a.IMAPHost, a.IMAPPort), a.Username)
+		}
+		return 0
+```
+
+with:
+
+```go
+	case "list":
+		// Holding the admin key means the caller is the human admin (full
+		// detail). An agent holds only EMCLI_KEY and gets a reduced JSON view.
+		_, adminErr := crypto.AdminKeyFromEnv()
+		isAdmin := adminErr == nil
+		accs, err := st.ListAccounts()
+		if err != nil {
+			if isAdmin {
+				fmt.Fprintf(errOut, "list: %v\n", err)
+			} else {
+				_ = Failure(CodeDB, err.Error()).Write(out)
+			}
+			return 1
+		}
+		if !isAdmin {
+			items := make([]map[string]any, 0, len(accs))
+			for _, a := range accs {
+				items = append(items, map[string]any{
+					"name":     a.Name,
+					"from":     a.SendFrom(),
+					"can_send": a.Mode == "RW",
+				})
+			}
+			_ = Success(map[string]any{"accounts": items}).Write(out)
+			return 0
+		}
+		fmt.Fprintf(out, "%-16s %-4s %-28s %s\n", "NAME", "MODE", "IMAP", "USER")
+		for _, a := range accs {
+			fmt.Fprintf(out, "%-16s %-4s %-28s %s\n",
+				a.Name, a.Mode, fmt.Sprintf("%s:%d", a.IMAPHost, a.IMAPPort), a.Username)
+		}
+		return 0
+```
+
+- [ ] **Step 8: Run the full cli package test suite**
+
+Run: `go test ./internal/cli/`
+Expected: PASS (all tests, including the two new rendering tests, the routing test, and the security invariant).
+
+- [ ] **Step 9: Run the whole module to confirm nothing else regressed**
+
+Run: `go build ./... && go test ./...`
+Expected: build clean; all packages PASS.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add internal/cli/run.go internal/cli/admin.go internal/cli/role_test.go \
+        internal/cli/security_invariant_test.go internal/cli/account_list_test.go
+git commit -m "feat(cli): agent-readable account list (reduced JSON view)
+
+account list now routes to the agent role; an agent (EMCLI_KEY only) gets a
+JSON envelope of name/from/can_send, while the admin keeps the full text
+table. account add/edit/remove stay admin-only.
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Update user and agent documentation
+
+**Files:**
+- Modify: `USER-MANUAL.md` (command-kinds note, role table, cheatsheet)
+- Modify: `skills/emcli/SKILL.md` (allowed-commands note, command table, do/don't)
+- Modify: `skills/emcli/AGENTIC-MANUAL.md` (§4 account discovery)
+
+**Interfaces:**
+- Consumes: behavior shipped in Task 1 (agent `account list` → `{"data":{"accounts":[{name,from,can_send}]}}`).
+- Produces: docs only; no code interface.
+
+- [ ] **Step 1: USER-MANUAL — note that `account list` is the one agent-readable admin view**
+
+In `USER-MANUAL.md`, in the "Two kinds of commands" block, change the Admin bullet (line ~36) from:
+
+```
+- **Admin commands** (`init`, `account`, `whitelist`, `config`, `audit`) require `EMCLI_ADMIN_KEY`
+  and are for *you*, the human. They print human-readable text or open an interactive form.
+```
+
+to:
+
+```
+- **Admin commands** (`init`, `account add/edit/remove`, `whitelist`, `config`, `audit`) require
+  `EMCLI_ADMIN_KEY` and are for *you*, the human. They print human-readable text or open an
+  interactive form. (`account list` is the one exception — it is also an agent command; see below.)
+```
+
+- [ ] **Step 2: USER-MANUAL — update the role table**
+
+Replace the role table rows (lines ~127-128):
+
+```
+| `list`, `get`, `search`, `ack`, `send`, `doctor` | Agent (`EMCLI_KEY` or `EMCLI_ADMIN_KEY`) |
+| `account`, `whitelist`, `config`, `audit` | Admin (`EMCLI_ADMIN_KEY` required) |
+```
+
+with:
+
+```
+| `list`, `get`, `search`, `ack`, `send`, `doctor`, `account list` | Agent (`EMCLI_KEY` or `EMCLI_ADMIN_KEY`) |
+| `account add/edit/remove`, `whitelist`, `config`, `audit` | Admin (`EMCLI_ADMIN_KEY` required) |
+
+`account list` is dual-role: with the admin key it prints the full `NAME MODE IMAP USER` table;
+with only `EMCLI_KEY` (an agent) it prints a JSON envelope exposing just `name`, `from`, and
+`can_send` — no host or login username.
+```
+
+- [ ] **Step 3: USER-MANUAL — annotate the cheatsheet**
+
+In the cheatsheet (line ~597), change:
+
+```
+emcli account list                                    # list accounts (no secrets)
+```
+
+to:
+
+```
+emcli account list                                    # full table (admin) / name+from+can_send JSON (agent)
+```
+
+- [ ] **Step 4: SKILL.md — carve `account list` out of the forbidden-commands rule**
+
+In `skills/emcli/SKILL.md`, change the first bullet (lines ~20-24):
+
+```
+- **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`, `doctor`. You are
+  provided only `EMCLI_KEY` (the agent key), which authorises these commands and nothing else.
+  Account setup, passwords, whitelists, and config are the **user's** job (admin commands that
+  require `EMCLI_ADMIN_KEY`) — do not run or suggest running `account`, `whitelist`, `config`,
+  `audit`, or `init`. You have only `EMCLI_KEY` (agent key); `emcli` will refuse admin commands
+  with a privilege error.
+```
+
+to:
+
+```
+- **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`, `doctor`, and
+  `account list` (to discover accounts). You are provided only `EMCLI_KEY` (the agent key), which
+  authorises these and nothing else. Account *setup* (`account add/edit/remove`), passwords,
+  whitelists, and config are the **user's** job (admin commands that require `EMCLI_ADMIN_KEY`) —
+  do not run or suggest running `account add/edit/remove`, `whitelist`, `config`, `audit`, or
+  `init`. `emcli` will refuse those with a privilege error.
+```
+
+- [ ] **Step 5: SKILL.md — add `account list` to the command table**
+
+In the command table (after the `send` row, line ~122), add:
+
+```
+| `emcli account list` | Discover accounts: JSON `name` / `from` / `can_send` per account |
+```
+
+- [ ] **Step 6: SKILL.md — fix the "don't" bullet**
+
+Change (lines ~147-148):
+
+```
+- ❌ Don't run admin commands (`account`/`whitelist`/`config`/`audit`/`init`) — you have only
+  `EMCLI_KEY` (agent key); `emcli` will refuse admin commands with a privilege error.
+```
+
+to:
+
+```
+- ❌ Don't run admin commands (`account add/edit/remove`, `whitelist`, `config`, `audit`, `init`) —
+  you have only `EMCLI_KEY` (agent key); `emcli` will refuse them with a privilege error.
+  (`account list` is allowed — use it to discover accounts.)
+```
+
+Also change the ✅ bullet (line ~145) from `Ask the user for the account name; keep bodies plain text.` to:
+
+```
+- ✅ Discover accounts with `emcli account list`, or ask the user; keep bodies plain text.
+```
+
+- [ ] **Step 7: AGENTIC-MANUAL — document discovery via `account list`**
+
+In `skills/emcli/AGENTIC-MANUAL.md`, replace the body of `## 4. Find the account(s)` (lines ~88-97):
+
+```
+You refer to an account by name (e.g. `gmail`, `work`). Ask the user which account to use.
+`emcli doctor` is an agent command (authorised by `EMCLI_KEY`), so you can run it to check that
+configured accounts connect and authenticate:
+
+```bash
+emcli doctor              # all accounts
+emcli doctor --account gmail
+```
+
+Just take the account name from the user and start with the workflow in `SKILL.md`.
+```
+
+with:
+
+```
+You refer to an account by name (e.g. `gmail`, `work`). Discover the configured accounts yourself
+with `emcli account list` (an agent command authorised by `EMCLI_KEY`); it prints a JSON envelope
+with one entry per account:
+
+```bash
+emcli account list
+# {"error":false,"error_detail":{},"data":{"accounts":[
+#   {"name":"gmail","from":"me@gmail.com","can_send":true},
+#   {"name":"alerts","from":"alerts@x.com","can_send":false}]}}
+```
+
+`name` is what you pass to `--account`; `from` is the send-as identity; `can_send` is false for
+read-only accounts (they reject `send`). If unsure which to use, ask the user. `emcli doctor`
+(also an agent command) checks that accounts connect and authenticate:
+
+```bash
+emcli doctor              # all accounts
+emcli doctor --account gmail
+```
+
+Then start with the workflow in `SKILL.md`.
+```
+
+- [ ] **Step 8: Sanity-check the docs render and reference reality**
+
+Run: `grep -n "account list" USER-MANUAL.md skills/emcli/SKILL.md skills/emcli/AGENTIC-MANUAL.md`
+Expected: each file shows the updated `account list` references; no remaining text claims the agent cannot run `account list`.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add USER-MANUAL.md skills/emcli/SKILL.md skills/emcli/AGENTIC-MANUAL.md
+git commit -m "docs: agent can discover accounts via account list
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Notes for the implementer
+
+- Run all Go commands from the repo root (`/home/steve/src/emcli`).
+- The two intentional red states are Step 2 (compile error) and Step 6 (agent JSON test) in Task 1. Every other test run must be green.
+- Do not change the admin text table or add columns to it — admin output must stay identical.
+- `adminEnv(t)` and `run(t, ...)` live in `internal/cli/admin_test.go`; `b64Key`/`b64AgentKey` in `internal/cli/run_test.go`. No new helpers are needed.

docs/superpowers/specs/2026-06-23-agent-account-list-design.md

@@ -0,0 +1,141 @@
+# Agent-readable `account list` — design
+
+**Date:** 2026-06-23
+**Status:** Approved (brainstorm), ready for implementation plan
+**Author:** Steve + Claude
+
+## Problem
+
+An agent process is launched with only `EMCLI_KEY` (the two-key model — see
+`2026-06-22-two-key-privilege-design.md`). Every agent command takes
+`--account NAME`, but the agent has no way to *discover* which accounts exist:
+`account list` is classified admin-only and is refused under the agent key. So
+account names must be supplied to the agent out of band, which is brittle and
+defeats the point of a self-directed agent.
+
+The two-key spec deliberately gated the whole `account` command to admin because
+`account add/edit/remove` mutate configuration. But `account list` is read-only
+and exposes no secrets — `store.ListAccounts` never decrypts the password
+(`enc_password` is scanned and discarded). Gating *discovery* behind admin is
+stricter than the threat model requires.
+
+## Goal
+
+Let an agent holding only `EMCLI_KEY` run `account list` to discover the
+accounts it may operate on, while:
+
+- keeping `account add/edit/remove` admin-only (mutation stays gated);
+- exposing to the agent only what it needs — **account name, the send-as From
+  address, and whether the account can send** — and *not* the IMAP host/port or
+  login username;
+- preserving the admin's existing full-detail view unchanged.
+
+## Constraints / decisions
+
+Settled during brainstorming:
+
+1. **Scope is exactly `account list`.** `whitelist list`, `config get`, and
+   `audit list` stay admin-only. `audit` in particular is oversight data and
+   must remain invisible to the agent.
+2. **Privilege-dependent rendering.** The admin keeps the current full table
+   (`NAME  MODE  IMAP  USER`, human-readable). The agent gets a *reduced* view
+   containing only name, From, and send-capability.
+3. **Agent output is JSON.** The agent is a machine consumer, so its
+   `account list` emits the standard agent envelope (like `list`/`get`/`search`),
+   not a text table. The admin path stays human-readable text.
+4. **No secret exposure, no schema change.** `ListAccounts` already avoids
+   decrypting passwords; nothing about the data model changes.
+
+## Approach
+
+Reclassify `account list` to the agent role, and branch rendering on the
+caller's actual privilege (presence of the admin key).
+
+### Routing (`internal/cli/run.go`)
+
+`commandRole` becomes subcommand-aware for `account`:
+
+- `account list` → `RoleAgent`
+- `account add | edit | remove` (and bare `account`) → `RoleAdmin`
+- all other commands unchanged.
+
+`commandRole` currently takes `cmd string`; it changes to take the full
+`args []string` so it can peek at the `account` subcommand. `Run` passes
+`args` through. This keeps `commandRole` the single source of truth for the
+classification table.
+
+Authorization mechanics are unchanged: `openStore(RoleAgent)` requires
+`EMCLI_KEY` (falling back to the admin key for a human who holds only that and
+runs `account list`). `account add/edit/remove` still hard-require
+`EMCLI_ADMIN_KEY` with no fallback.
+
+### Rendering (`internal/cli/admin.go`, the `list` branch)
+
+Determine privilege from the environment: `_, err := crypto.AdminKeyFromEnv()`;
+`isAdmin := err == nil`. (Holding the admin key *is* being the admin in this
+trust model. A human with only the admin key still gets the admin view; an agent
+with only `EMCLI_KEY` gets the reduced view.)
+
+- **Admin** → existing full table, unchanged:
+  ```
+  NAME             MODE IMAP                         USER
+  work             RW   imap.example.com:993         me@example.com
+  ```
+- **Agent** → JSON envelope to stdout:
+  ```json
+  {"error":false,"error_detail":{},"data":{"accounts":[
+    {"name":"work","from":"me@example.com","can_send":true},
+    {"name":"alerts","from":"alerts@example.com","can_send":false}
+  ]}}
+  ```
+  where `from = Account.SendFrom()` (the configured From address, falling back
+  to the username) and `can_send = (Mode == "RW")` (RW accounts have SMTP
+  configured; RO cannot send). The IMAP host/port and the raw login username are
+  **not** emitted (when From falls back to the username it may coincide with it,
+  which is acceptable — the user asked for From specifically).
+
+The reduced view reuses the existing `Success(...)` envelope and `Envelope.Write`
+helper; no new output machinery.
+
+## Error handling
+
+- Agent key on `account add/edit/remove` → unchanged:
+  `emcli: this command requires EMCLI_ADMIN_KEY (admin privilege)`, non-zero.
+- Agent `account list` with neither key set → the agent-command config error
+  (`EMCLI_KEY is not set`), surfaced the same way other agent commands surface a
+  missing key. Because the agent path now emits JSON, a missing-key failure on
+  `account list` is a JSON `Failure(CodeConfig, …)` envelope, consistent with the
+  other agent commands.
+- DB/list errors on the agent path → `Failure(CodeDB, …)` envelope; on the admin
+  path → existing `list: <err>` text to stderr.
+
+## Testing
+
+- **Routing:** extend the `commandRole` table test — `account list` → agent;
+  `account add` / `account edit` / `account remove` → admin.
+- **Agent view:** with only `EMCLI_KEY`, `account list` exits 0, emits a valid
+  envelope, and the `data.accounts` entries carry `name`/`from`/`can_send` — and
+  the output does **not** contain the IMAP host or the login username.
+- **Admin view:** with `EMCLI_ADMIN_KEY`, `account list` still prints the full
+  `NAME MODE IMAP USER` table (regression guard).
+- **`can_send`:** an RW account yields `can_send:true`, an RO account
+  `can_send:false`; `from` reflects `SendFrom()` (explicit From, else username).
+- **Security invariant (`security_invariant_test.go`):** remove
+  `{"account","list"}` from the refused-commands set (it is now allowed) and
+  replace it with a *mutating* `account add …` attempt, so the "forced agent
+  cannot run admin commands and the DB is byte-for-byte unchanged" invariant
+  still covers the `account` family.
+
+## Documentation updates
+
+- **USER-MANUAL:** role/command table — `account list` is agent-readable
+  (reduced JSON view); `account add/edit/remove` remain admin.
+- **`skills/emcli` (SKILL.md / AGENTIC-MANUAL.md):** document that the agent
+  discovers accounts via `account list`, including the JSON shape
+  (`name`, `from`, `can_send`).
+
+## Out of scope
+
+- Agent access to `whitelist list`, `config get`, or `audit list`.
+- Any change to the admin `account list` columns or to the data model.
+- JSON output for the admin `account list` path (stays human-readable text).

docs/superpowers/specs/2026-06-27-human-cli-grammar-redesign-design.md

@@ -0,0 +1,201 @@
+# emcli — Human-facing CLI grammar redesign
+
+Date: 2026-06-27
+Status: Approved (design)
+
+## Problem
+
+`emcli` was designed flag-first for AI agents — explicit, stable, machine-parseable. The
+human-facing **admin** commands inherited that flag-heavy grammar, and the result is inconsistent
+and error-prone for a person at a terminal. The "main noun" of each command is sometimes
+positional, sometimes a flag:
+
+| Command (today) | Names its target via |
+|---|---|
+| `config set audit_retention_days 90` | positional key + value |
+| `account remove --name bobby --yes` | flag |
+| `whitelist in add --account bobby --address x@y` | flags (×2) |
+| `audit list --account bobby` | flag |
+
+A human has no rule to remember. The concrete failure that triggered this work:
+
+```
+emcli whitelist in add --account bobby "Tk555@protonmail.com"
+```
+
+Go's `flag` parser read `--account bobby`, treated `"Tk555@protonmail.com"` as an ignored leftover
+positional, and `--address` defaulted to `""`. `AddWhitelist` then ran
+`INSERT OR IGNORE ... VALUES(id, "")` — silently inserting a blank whitelist row. No error, no
+validation.
+
+## Goals
+
+- One consistent, predictable grammar for all human-facing (admin) commands.
+- Eliminate the silently-ignored-input and empty-operand bug classes.
+- Improve discoverability (`config list`, `account show`) and onboarding (whitelists fully
+  decoupled from account creation).
+- Keep the agent JSON command surface (`list`/`get`/`search`/`ack`/`send`) **frozen**.
+
+## Non-goals
+
+- No change to agent JSON commands' flags, output, or behavior.
+- No change to the encryption/key model, store schema semantics, or policy engine logic.
+- No unrelated refactoring.
+
+## Unifying grammar
+
+> **`emcli <group> <verb> <operands…> [--flags]`**
+>
+> Primary targets — account name, address(es), config key/value — are **positional**.
+> Flags carry only options/modifiers (`--in`/`--out`, `--yes`, `--limit`, account field values
+> like `--imap-host`).
+
+Two cross-cutting safety rules enforced everywhere:
+
+1. **No silently-ignored input.** Any leftover positional argument beyond what a command expects
+   is an error (`unexpected argument "x"`). This alone prevents the triggering bug.
+2. **No empty primary operands.** Empty account / address / key is rejected with a clear message.
+
+### Verb aliases
+
+Applied at the verb position for every group (and the top-level command position, additively):
+
+- `remove` = `rm` = `del`
+- `list` = `ls`
+
+Implemented as a single `normalizeVerb(string) string` map applied before the verb `switch`.
+
+## Command surface (after)
+
+### account
+| Command | Notes |
+|---|---|
+| `account add [name] [--imap-host … --username … …]` | `name` positional. No flags → interactive TUI form (unchanged). **`--whitelist-in`/`--whitelist-out` removed** (see Whitelist decoupling). `--process-backlog` kept. |
+| `account edit <name> [--flags]` | `name` positional; only `name` → interactive form prefilled. **`--whitelist-in`/`--whitelist-out` removed.** |
+| `account remove <name> [--yes]` | `name` positional. On a TTY, prompt `Remove account "bobby"? [y/N]`; non-TTY (piped) requires `--yes`. Aliases: `rm`, `del`. |
+| `account show <name>` | **New.** Human-readable detail: mode (RO/RW), IMAP host/port/security, SMTP host/port/security, send-from address, subject regex, inbound/outbound whitelist enabled state. Never prints the password. |
+| `account list` | Unchanged table. Alias: `ls`. |
+
+### whitelist
+Direction is a **required** `--in` / `--out` flag (error if neither given — no wrong-list default).
+Whitelist management is fully self-contained in this group (enable/disable moved here from
+`account edit`).
+
+| Command | Notes |
+|---|---|
+| `whitelist add <account> <addr…> --in\|--out` | One or more addresses, each validated (see Address validation). Aliases for verb: n/a. |
+| `whitelist remove <account> <addr…> --in\|--out` | One or more addresses. Aliases: `rm`, `del`. |
+| `whitelist list <account> --in\|--out` | Header line shows `ENABLED`/`DISABLED`. Alias: `ls`. |
+| `whitelist enable <account> --in\|--out` | **New.** If the list is empty, print a warning: `warning: inbound whitelist for "bobby" is empty — this blocks ALL inbound mail until you add addresses`. Still enables (explicit user action). |
+| `whitelist disable <account> --in\|--out` | **New.** |
+
+### config
+A known-key **settings registry** backs validation and discovery. Each entry: `key`,
+`description`, and a `validate(value) error`.
+
+| Command | Notes |
+|---|---|
+| `config list` | **New.** Table: `KEY  VALUE  DESCRIPTION`. Lists every registered key, its current value (or `(unset)`), and description. Alias: `ls`. |
+| `config get <key>` | Rejects unknown key. |
+| `config set <key> <value>` | Rejects unknown key (`unknown setting "foo" (see: emcli config list)`); runs the key's validator. |
+
+Initial registry: `audit_retention_days` (description "Days to keep audit-log entries"; validator:
+integer ≥ 0 — same rule as today).
+
+### audit
+| Command | Notes |
+|---|---|
+| `audit list [account] [--limit N]` | `account` positional (optional; omitted = all accounts). `--limit` stays a flag (it's a modifier). Alias: `ls`. |
+
+### doctor (exception — dual-use)
+`doctor` is agent-runnable (`RoleAgent`) and the agentic manual documents `emcli doctor --account
+gmail`. To avoid breaking documented agent usage while still giving humans the positional form, it
+accepts **both**:
+
+| Command | Notes |
+|---|---|
+| `doctor [account]` | Positional account (human shorthand). |
+| `doctor --account <name>` | Retained for agent/script compatibility. If both a positional and `--account` are given and they differ, that's an error. |
+
+### Frozen (untouched)
+`list`, `get`, `search`, `ack`, `send` — `--account`/`--folder`/`--uid…` flags, JSON envelope
+output. **Intentional split**, documented in help: agent commands are flag-driven for parse
+stability; human admin commands are positional. `init`, `version`, `help` unchanged (except `init`
+no longer references whitelists).
+
+## Whitelist decoupling from onboarding
+
+Verified against the code: `WhitelistInEnabled`/`WhitelistOutEnabled` are stored per-account
+booleans, default `false`, read fresh on every command via `Deps.setup` (which rebuilds
+`policy.InboundRule` each call) and `SendCmd`. `policy.InboundRule.Allows` / `OutboundRule.Check`
+only consult them at evaluation time. Nothing in account creation, `init`, or the policy engine
+needs them set at creation time, and toggling them later takes effect on the next command.
+
+Therefore: remove `--whitelist-in` / `--whitelist-out` from `account add`, from `init`'s flow, and
+from the interactive TUI account form (the `Whitelist inbound`/`Whitelist outbound` toggles in
+`internal/tui/account.go`) entirely — leaving them in the form would contradict the decoupling and
+re-expose the empty-enabled-whitelist footgun. Accounts are created with whitelists off; the user
+sets them up afterward:
+
+```
+emcli whitelist add bobby alice@example.com bob@example.com --in
+emcli whitelist enable bobby --in
+```
+
+Default (whitelist off) is the existing permissive default; RO/RW mode and subject regex still
+apply regardless.
+
+## Address validation
+
+`whitelist add` / `whitelist remove` validate each address argument before touching the store.
+Accepted shapes:
+
+- A full address: `local@domain` (non-empty local part, a domain with at least one dot).
+- A domain wildcard: `@domain` (leading `@`, domain with at least one dot).
+
+Anything else (empty, no `@`, no domain) is rejected: `invalid address "x": expected
+local@domain or @domain`. Validation lives in a small reusable helper so `add` and `remove` share
+it. (Addresses are still lowercased on store as today.)
+
+## Error & output conventions (unchanged where already good)
+
+- Usage/errors → stderr; successful human output → stdout.
+- Exit codes: `0` success, `1` runtime error, `2` usage error (preserved).
+- Admin commands remain human-readable (never JSON). `account list` for an agent (agent key only)
+  still emits the reduced JSON view — unchanged.
+
+## Implementation surface
+
+- `internal/cli/admin.go` — rewrite arg parsing for `account`, `whitelist`, `config`, `audit` to
+  the positional grammar; add `account show`, `whitelist enable/disable`, `config list`; add the
+  leftover-positional and empty-operand guards; wire `normalizeVerb`.
+- `internal/cli/run.go` — `doctor` accepts positional + `--account`; routing unchanged otherwise.
+- `internal/cli/interactive.go` (`runInit`) — drop whitelist references.
+- `internal/tui/account.go` — remove the `WhitelistIn`/`WhitelistOut` form fields, their rows,
+  and their render/parse/`ToAccount`/`FieldsFromAccount` handling (new accounts are created with
+  whitelists off; managed via the `whitelist` group thereafter).
+- `internal/cli/help.go` — rewrite admin synopses to the new grammar; document the
+  agent-vs-human positional/flag split; list aliases.
+- New: settings registry (small map + validators) — location `internal/cli` (e.g.
+  `config_registry.go`) unless it needs store access, in which case `internal/store`.
+- New: address validator helper (e.g. `internal/cli` or `internal/policy`, near existing address
+  matching).
+- `internal/store` — add `SetWhitelistEnabled(account, dir, bool)` (or equivalent) if not already
+  expressible via existing account update; `account show` reads existing getters.
+- TTY detection helper for `account remove` confirmation (e.g. `term.IsTerminal` on stdin fd).
+- Docs: `USER-MANUAL.md`, `skills/emcli/AGENTIC-MANUAL.md` (the `doctor --account` example stays
+  valid; verify wording), `README.md` getting-started (no whitelist at init).
+- Tests: `admin_test.go`, `run_test.go`, plus new tests for aliases, leftover-arg rejection,
+  empty-operand rejection, address validation, `config list`/unknown-key, `whitelist
+  enable/disable` (incl. empty-list warning), `account show`, and `account remove` confirm path.
+
+## What breaks (accepted)
+
+Every current admin invocation using `--account` / `--name` / `--address` on `account`,
+`whitelist`, `config` (positional already), `audit`, plus `account edit --whitelist-in/out` and
+`account add --whitelist-in/out`. The agent path (skill + installer drive only the frozen JSON
+commands; `doctor --account` retained) is unaffected.
+
+## Open questions
+
+None outstanding — all design forks resolved with the user.

internal/cli/account_list_test.go

@@ -0,0 +1,85 @@
+package cli
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// With only EMCLI_KEY set, `account list` emits the reduced JSON envelope:
+// name/from/can_send, and never the IMAP host or login username.
+func TestAccountListAgentJSONView(t *testing.T) {
+	adminEnv(t) // both keys + initialized temp DB
+	run(t, "account", "add", "--name", "work", "--mode", "RW",
+		"--imap-host", "imap.example.com", "--smtp-host", "smtp.example.com",
+		"--username", "login@example.com", "--from", "me@example.com")
+	run(t, "account", "add", "--name", "alerts", "--mode", "RO",
+		"--imap-host", "imap.example.com", "--username", "alerts@example.com")
+
+	// Drop the admin key → caller is an agent.
+	t.Setenv("EMCLI_ADMIN_KEY", "")
+	code, out, errOut := run(t, "account", "list")
+	if code != 0 {
+		t.Fatalf("agent account list should succeed: code=%d err=%q", code, errOut)
+	}
+
+	var env struct {
+		Error bool `json:"error"`
+		Data  struct {
+			Accounts []struct {
+				Name    string `json:"name"`
+				From    string `json:"from"`
+				CanSend bool   `json:"can_send"`
+			} `json:"accounts"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(out), &env); err != nil {
+		t.Fatalf("output is not the agent envelope: %v\n%s", err, out)
+	}
+	if env.Error || len(env.Data.Accounts) != 2 {
+		t.Fatalf("want 2 accounts and no error, got %+v", env)
+	}
+	// The reduced view must not leak the IMAP host or the login username.
+	if strings.Contains(out, "imap.example.com") || strings.Contains(out, "login@example.com") {
+		t.Fatalf("agent view leaked host/username:\n%s", out)
+	}
+
+	got := map[string]struct {
+		from    string
+		canSend bool
+	}{}
+	for _, a := range env.Data.Accounts {
+		got[a.Name] = struct {
+			from    string
+			canSend bool
+		}{a.From, a.CanSend}
+	}
+	if g := got["work"]; g.from != "me@example.com" || !g.canSend {
+		t.Errorf("work: want from=me@example.com can_send=true, got %+v", g)
+	}
+	// alerts has no --from → SendFrom() falls back to the username.
+	if g := got["alerts"]; g.from != "alerts@example.com" || g.canSend {
+		t.Errorf("alerts: want from=alerts@example.com can_send=false, got %+v", g)
+	}
+}
+
+// With the admin key present, `account list` stays the full human-readable table.
+func TestAccountListAdminTextView(t *testing.T) {
+	adminEnv(t)
+	run(t, "account", "add", "--name", "work", "--mode", "RW",
+		"--imap-host", "imap.example.com", "--smtp-host", "smtp.example.com",
+		"--username", "login@example.com", "--from", "me@example.com")
+
+	code, out, _ := run(t, "account", "list")
+	if code != 0 {
+		t.Fatalf("admin account list failed: code=%d", code)
+	}
+	for _, want := range []string{"NAME", "MODE", "IMAP", "USER", "imap.example.com:993", "login@example.com"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("admin view missing %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, `"accounts"`) {
+		t.Fatalf("admin view should be text, not JSON:\n%s", out)
+	}
+}

internal/cli/admin.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"strconv"
 
+	"git.dcglab.co.uk/steve/emcli/internal/crypto"
 	"git.dcglab.co.uk/steve/emcli/internal/store"
 	"git.dcglab.co.uk/steve/emcli/internal/tui"
 )
@@ -23,7 +24,14 @@ func runAccount(args []string, role store.Role, out, errOut io.Writer) int {
 	sub, rest := args[0], args[1:]
 	st, err := openStore(role)
 	if err != nil {
+		// account list is an agent command (a JSON consumer), so its
+		// open/key failures are emitted as an envelope, like the other agent
+		// commands; the admin subcommands stay human-readable.
+		if sub == "list" {
+			_ = Failure(CodeConfig, err.Error()).Write(out)
+		} else {
 			fmt.Fprintf(errOut, "emcli: %v\n", err)
+		}
 		return 1
 	}
 	defer st.Close()
@@ -171,11 +179,31 @@ func runAccount(args []string, role store.Role, out, errOut io.Writer) int {
 		fmt.Fprintf(out, "account %q removed\n", *name)
 		return 0
 	case "list":
+		// Holding the admin key means the caller is the human admin (full
+		// detail). An agent holds only EMCLI_KEY and gets a reduced JSON view.
+		_, adminErr := crypto.AdminKeyFromEnv()
+		isAdmin := adminErr == nil
 		accs, err := st.ListAccounts()
 		if err != nil {
+			if isAdmin {
 				fmt.Fprintf(errOut, "list: %v\n", err)
+			} else {
+				_ = Failure(CodeDB, err.Error()).Write(out)
+			}
 			return 1
 		}
+		if !isAdmin {
+			items := make([]map[string]any, 0, len(accs))
+			for _, a := range accs {
+				items = append(items, map[string]any{
+					"name":     a.Name,
+					"from":     a.SendFrom(),
+					"can_send": a.Mode == "RW",
+				})
+			}
+			_ = Success(map[string]any{"accounts": items}).Write(out)
+			return 0
+		}
 		fmt.Fprintf(out, "%-16s %-4s %-28s %s\n", "NAME", "MODE", "IMAP", "USER")
 		for _, a := range accs {
 			fmt.Fprintf(out, "%-16s %-4s %-28s %s\n",
@@ -302,7 +330,19 @@ func runWhitelist(args []string, role store.Role, out, errOut io.Writer) int {
 		return 2
 	}
 	dir := store.Direction(args[0])
+	if dir != store.DirIn && dir != store.DirOut {
+		fmt.Fprintf(errOut, "whitelist direction must be \"in\" or \"out\", got %q\n", args[0])
+		fmt.Fprintln(errOut, "usage: emcli whitelist <in|out> <add|remove|list> [flags]")
+		return 2
+	}
 	sub, rest := args[1], args[2:]
+	switch sub {
+	case "add", "remove", "list": // valid
+	default:
+		fmt.Fprintf(errOut, "unknown whitelist subcommand %q (want add|remove|list)\n", sub)
+		fmt.Fprintln(errOut, "usage: emcli whitelist <in|out> <add|remove|list> [flags]")
+		return 2
+	}
 	fs := flag.NewFlagSet("whitelist", flag.ContinueOnError)
 	fs.SetOutput(errOut)
 	account := fs.String("account", "", "account name")
@@ -343,9 +383,6 @@ func runWhitelist(args []string, role store.Role, out, errOut io.Writer) int {
 		for _, a := range addrs {
 			fmt.Fprintln(out, a)
 		}
-	default:
-		fmt.Fprintf(errOut, "unknown whitelist subcommand %q\n", sub)
-		return 2
 	}
 	return 0
 }

internal/cli/admin_test.go

@@ -110,6 +110,51 @@ func TestAccountEditPartialPreservesOtherFields(t *testing.T) {
 	}
 }
 
+// A missing direction (e.g. `whitelist list`) must report the real problem —
+// the in|out direction — not the misleading "--account is required".
+func TestWhitelistMissingDirectionReported(t *testing.T) {
+	adminEnv(t)
+	code, _, errOut := run(t, "whitelist", "list", "--account", "bobby")
+	if code == 0 {
+		t.Fatal("missing direction must be a usage error")
+	}
+	if strings.Contains(errOut, "--account is required") {
+		t.Fatalf("misleading error; want a direction complaint, got: %q", errOut)
+	}
+	if !strings.Contains(errOut, "in") || !strings.Contains(errOut, "out") {
+		t.Fatalf("error should name the in|out direction, got: %q", errOut)
+	}
+}
+
+// A missing subcommand (e.g. `whitelist out --account x`) must report the real
+// problem — the add|remove|list subcommand — not "--account is required".
+func TestWhitelistMissingSubcommandReported(t *testing.T) {
+	adminEnv(t)
+	code, _, errOut := run(t, "whitelist", "out", "--account", "bobby")
+	if code == 0 {
+		t.Fatal("missing subcommand must be a usage error")
+	}
+	if strings.Contains(errOut, "--account is required") {
+		t.Fatalf("misleading error; want a subcommand complaint, got: %q", errOut)
+	}
+	if !strings.Contains(errOut, "add") || !strings.Contains(errOut, "list") {
+		t.Fatalf("error should name the add|remove|list subcommand, got: %q", errOut)
+	}
+}
+
+// The happy path still works after the direction/subcommand validation.
+func TestWhitelistListWorks(t *testing.T) {
+	adminEnv(t)
+	run(t, "account", "add", "--name", "bobby", "--imap-host", "h", "--username", "u@x.com")
+	if code, _, e := run(t, "whitelist", "out", "add", "--account", "bobby", "--address", "@x.com"); code != 0 {
+		t.Fatalf("add failed: %s", e)
+	}
+	code, out, _ := run(t, "whitelist", "out", "list", "--account", "bobby")
+	if code != 0 || !strings.Contains(out, "@x.com") {
+		t.Fatalf("list: code=%d out=%q", code, out)
+	}
+}
+
 func TestAuditListCoreRenders(t *testing.T) {
 	st, err := store.Open(filepath.Join(t.TempDir(), "e.db"))
 	if err != nil {

internal/cli/role_test.go

@@ -9,16 +9,22 @@ import (
 )
 
 func TestCommandRole(t *testing.T) {
-	admin := []string{"account", "whitelist", "config", "audit"}
-	agent := []string{"list", "get", "search", "ack", "send", "doctor"}
-	for _, c := range admin {
+	adminCmds := [][]string{
+		{"whitelist"}, {"config"}, {"audit"},
+		{"account"}, {"account", "add"}, {"account", "edit"}, {"account", "remove"},
+	}
+	agentCmds := [][]string{
+		{"list"}, {"get"}, {"search"}, {"ack"}, {"send"}, {"doctor"},
+		{"account", "list"},
+	}
+	for _, c := range adminCmds {
 		if commandRole(c) != store.RoleAdmin {
-			t.Errorf("%s should be admin", c)
+			t.Errorf("%v should be admin", c)
 		}
 	}
-	for _, c := range agent {
+	for _, c := range agentCmds {
 		if commandRole(c) != store.RoleAgent {
-			t.Errorf("%s should be agent", c)
+			t.Errorf("%v should be agent", c)
 		}
 	}
 }

internal/cli/run.go

@@ -27,9 +27,16 @@ func realMailer(acc store.Account) (Mailer, error) {
 
 // commandRole maps a command to the privilege it requires. Admin commands
 // mutate configuration or expose oversight data; everything else is agent.
-func commandRole(cmd string) store.Role {
-	switch cmd {
-	case "account", "whitelist", "config", "audit":
+func commandRole(args []string) store.Role {
+	switch args[0] {
+	case "account":
+		// account list is a read-only discovery view available to agents;
+		// add/edit/remove mutate config and require admin.
+		if len(args) >= 2 && args[1] == "list" {
+			return store.RoleAgent
+		}
+		return store.RoleAdmin
+	case "whitelist", "config", "audit":
 		return store.RoleAdmin
 	default: // list, get, search, ack, send, doctor
 		return store.RoleAgent
@@ -135,7 +142,7 @@ func Run(args []string, out, errOut io.Writer) int {
 		return 0
 	}
 	cmd, rest := args[0], args[1:]
-	role := commandRole(cmd)
+	role := commandRole(args)
 	switch cmd {
 	case "list", "get", "search", "ack":
 		return runAgent(cmd, rest, role, out, errOut)

internal/cli/run_test.go

@@ -18,9 +18,9 @@ func TestRunUnknownCommand(t *testing.T) {
 	}
 }
 
-func TestRunVersionIsJSONForAgentButTextHere(t *testing.T) {
-	// `account list` with no DB key should fail closed with a usage/config error,
-	// proving the key check happens before any DB work.
+func TestAccountListMissingKeyFailsClosedAsJSON(t *testing.T) {
+	// `account list` is an agent command: with no DB key it fails closed before
+	// any DB work, emitting a JSON config-error envelope that names EMCLI_KEY.
 	var out, errOut bytes.Buffer
 	t.Setenv("EMCLI_KEY", "")
 	t.Setenv("EMCLI_ADMIN_KEY", "")
@@ -28,8 +28,15 @@ func TestRunVersionIsJSONForAgentButTextHere(t *testing.T) {
 	if code == 0 {
 		t.Fatal("missing EMCLI_KEY must fail")
 	}
-	if !strings.Contains(out.String()+errOut.String(), "EMCLI_ADMIN_KEY") {
-		t.Fatalf("should mention EMCLI_ADMIN_KEY, got out=%q err=%q", out.String(), errOut.String())
+	var env map[string]any
+	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
+		t.Fatalf("agent account list error must be JSON, got out=%q err=%q", out.String(), errOut.String())
+	}
+	if env["error"] != true {
+		t.Fatalf("want error envelope: %v", env)
+	}
+	if !strings.Contains(out.String(), "EMCLI_KEY") {
+		t.Fatalf("should name the missing EMCLI_KEY, got %q", out.String())
 	}
 }
 

internal/cli/security_invariant_test.go

@@ -49,7 +49,7 @@ func TestAgentKeyCannotRunAdminCommands(t *testing.T) {
 
 	before := dbBytes(t, db)
 	adminAttempts := [][]string{
-		{"account", "list"},
+		{"account", "add", "--name", "x", "--imap-host", "h", "--username", "u@x.com"},
 		{"config", "set", "audit_retention_days", "30"},
 		{"audit"},
 	}

internal/store/store.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strconv"
+	"strings"
 
 	_ "modernc.org/sqlite"
 )
@@ -77,10 +78,24 @@ func (s *Store) migrate() error {
 
 func (s *Store) Close() error { return s.db.Close() }
 
+// expandUserHome replaces a leading "~" or "~/" in p with the user's home
+// directory. Only a leading tilde is expanded (the usual shell convention) —
+// "~user" and a tilde elsewhere in the path are left untouched. This guards
+// against an EMCLI_DB set to a literal "~/..." (no shell to expand it), which
+// would otherwise be opened relative to the cwd and create a stray "~" dir.
+func expandUserHome(p string) string {
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			return filepath.Join(home, strings.TrimPrefix(p[1:], "/"))
+		}
+	}
+	return p
+}
+
 // DefaultDBPath resolves EMCLI_DB or the per-OS default location.
 func DefaultDBPath() (string, error) {
 	if p := os.Getenv("EMCLI_DB"); p != "" {
-		return p, nil
+		return expandUserHome(p), nil
 	}
 	if runtime.GOOS == "windows" {
 		if dir := os.Getenv("AppData"); dir != "" {

internal/store/store_test.go

@@ -2,10 +2,53 @@ package store
 
 import (
 	"database/sql"
+	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
+// A leading "~" in EMCLI_DB must be expanded to the home dir, so a literal
+// tilde (no shell to expand it) can't be opened relative to the cwd and
+// silently create a stray "~" directory.
+func TestDefaultDBPathExpandsLeadingTilde(t *testing.T) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skipf("no home dir: %v", err)
+	}
+	cases := map[string]string{
+		"~/.config/emcli/emcli.db": filepath.Join(home, ".config", "emcli", "emcli.db"),
+		"~":                        home,
+	}
+	for in, want := range cases {
+		t.Setenv("EMCLI_DB", in)
+		got, err := DefaultDBPath()
+		if err != nil {
+			t.Fatalf("DefaultDBPath(%q): %v", in, err)
+		}
+		if got != want {
+			t.Fatalf("EMCLI_DB=%q -> %q, want %q", in, got, want)
+		}
+		if strings.Contains(got, "~") {
+			t.Fatalf("EMCLI_DB=%q left a literal tilde: %q", in, got)
+		}
+	}
+}
+
+// A non-leading tilde or "~user" is NOT a path we should rewrite — leave it be.
+func TestDefaultDBPathLeavesOtherPathsUntouched(t *testing.T) {
+	for _, p := range []string{"/var/lib/emcli.db", "./rel/emcli.db", "~user/db"} {
+		t.Setenv("EMCLI_DB", p)
+		got, err := DefaultDBPath()
+		if err != nil {
+			t.Fatalf("DefaultDBPath(%q): %v", p, err)
+		}
+		if got != p {
+			t.Fatalf("EMCLI_DB=%q was rewritten to %q", p, got)
+		}
+	}
+}
+
 // openTemp opens a fresh store in a temp dir and initialises keys so that
 // account tests (which do crypto) work without needing their own setup.
 func openTemp(t *testing.T) *Store {

skills/emcli/AGENTIC-MANUAL.md

@@ -54,7 +54,7 @@ checksum, makes it executable in `~/.local/bin` (ensure that's on your PATH), an
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `EMCLI_VERSION` | `v0.5.0` | Release tag to fetch |
+| `EMCLI_VERSION` | `v0.5.2` | Release tag to fetch |
 | `EMCLI_BASE_URL` | `https://gitea.dcglab.co.uk/steve/emcli` | Repo base URL |
 | `EMCLI_INSTALL_DIR` | `$HOME/.local/bin` | Install location |
 
@@ -85,16 +85,27 @@ with both keys exported. Account creation and other admin is the human's job —
 
 ## 4. Find the account(s)
 
-You refer to an account by name (e.g. `gmail`, `work`). Ask the user which account to use.
-`emcli doctor` is an agent command (authorised by `EMCLI_KEY`), so you can run it to check that
-configured accounts connect and authenticate:
+You refer to an account by name (e.g. `gmail`, `work`). Discover the configured accounts yourself
+with `emcli account list` (an agent command authorised by `EMCLI_KEY`); it prints a JSON envelope
+with one entry per account:
+
+```bash
+emcli account list
+# {"error":false,"error_detail":{},"data":{"accounts":[
+#   {"name":"gmail","from":"me@gmail.com","can_send":true},
+#   {"name":"alerts","from":"alerts@x.com","can_send":false}]}}
+```
+
+`name` is what you pass to `--account`; `from` is the send-as identity; `can_send` is false for
+read-only accounts (they reject `send`). If unsure which to use, ask the user. `emcli doctor`
+(also an agent command) checks that accounts connect and authenticate:
 
 ```bash
 emcli doctor              # all accounts
 emcli doctor --account gmail
 ```
 
-Just take the account name from the user and start with the workflow in `SKILL.md`.
+Then start with the workflow in `SKILL.md`.
 
 ## You're set up
 

skills/emcli/SKILL.md

@@ -17,12 +17,12 @@ sets its exit code to match.
 
 ## Security model — read this first
 
-- **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`, `doctor`. You are
-  provided only `EMCLI_KEY` (the agent key), which authorises these commands and nothing else.
-  Account setup, passwords, whitelists, and config are the **user's** job (admin commands that
-  require `EMCLI_ADMIN_KEY`) — do not run or suggest running `account`, `whitelist`, `config`,
-  `audit`, or `init`. You have only `EMCLI_KEY` (agent key); `emcli` will refuse admin commands
-  with a privilege error.
+- **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`, `doctor`, and
+  `account list` (to discover accounts). You are provided only `EMCLI_KEY` (the agent key), which
+  authorises these and nothing else. Account *setup* (`account add/edit/remove`), passwords,
+  whitelists, and config are the **user's** job (admin commands that require `EMCLI_ADMIN_KEY`) —
+  do not run or suggest running `account add/edit/remove`, `whitelist`, `config`, `audit`, or
+  `init`. `emcli` will refuse those with a privilege error.
 - **Never touch the secret key.** `EMCLI_KEY` is supplied in the environment by whoever launched
   you. Do not read it, print it, log it, pass it as an argument, or try to generate one. If it is
   missing, stop and tell the user (see "Files & first run").
@@ -120,6 +120,7 @@ read-only — tell the user; do not attempt another account without their say-so
 | `emcli search --account A [--folder F] [--from X] [--subject-contains X] [--text X] [--since-date D] [--before-date D]` | Server-side search |
 | `emcli ack --account A [--folder F] --uid-list U1,U2` | Mark message(s) processed |
 | `emcli send --account A --to X [--cc X] [--bcc X] --subject S --body B [--attach P]… [--reply-to U]` | Send / reply |
+| `emcli account list` | Discover accounts: JSON `name` / `from` / `can_send` per account |
 
 Defaults: `--folder INBOX`, `--limit 50` (max 500). Dates are RFC 3339 (e.g.
 `2026-06-01T00:00:00Z`). UIDs come from `list`/`search` output.
@@ -142,8 +143,9 @@ The user configures these; you cannot change them and shouldn't try.
 
 - ✅ Check `error` on every call; report `policy`/`not_found`/`auth` outcomes plainly to the user.
 - ✅ `get` to read, then `ack` only after you've truly processed a message.
-- ✅ Ask the user for the account name; keep bodies plain text.
+- ✅ Discover accounts with `emcli account list`, or ask the user; keep bodies plain text.
 - ❌ Don't read, print, or invent `EMCLI_KEY` or any password.
-- ❌ Don't run admin commands (`account`/`whitelist`/`config`/`audit`/`init`) — you have only
-  `EMCLI_KEY` (agent key); `emcli` will refuse admin commands with a privilege error.
+- ❌ Don't run admin commands (`account add/edit/remove`, `whitelist`, `config`, `audit`, `init`) —
+  you have only `EMCLI_KEY` (agent key); `emcli` will refuse them with a privilege error.
+  (`account list` is allowed — use it to discover accounts.)
 - ❌ Don't treat a blocked send or filtered message as a bug to route around — it's the user's policy.

skills/emcli/scripts/install.sh

@@ -7,17 +7,17 @@
 #   bash install.sh
 #
 # Environment overrides:
-#   EMCLI_VERSION      release tag to fetch          (default: v0.5.0)
+#   EMCLI_VERSION      release tag to fetch          (default: v0.5.2)
 #   EMCLI_BASE_URL     repo base URL                 (default: https://gitea.dcglab.co.uk/steve/emcli)
 #   EMCLI_INSTALL_DIR  where to put the binary        (default: $HOME/.local/bin)
 #
 # Release assets follow this naming scheme:
-#   emcli_<version>_<os>_<arch>[.exe]   e.g. emcli_0.5.0_linux_amd64
+#   emcli_<version>_<os>_<arch>[.exe]   e.g. emcli_0.5.2_linux_amd64
 #   checksums.txt                       (sha256, one "<sum>  <asset>" line per asset)
 
 set -euo pipefail
 
-VERSION="${EMCLI_VERSION:-v0.5.0}"
+VERSION="${EMCLI_VERSION:-v0.5.2}"
 BASE_URL="${EMCLI_BASE_URL:-https://gitea.dcglab.co.uk/steve/emcli}"
 INSTALL_DIR="${EMCLI_INSTALL_DIR:-$HOME/.local/bin}"