feat(mail): add batch subcommand, docs, and CHANGELOG (0.2.6)

[bscott]

Supersedes #13, carrying forward only its unique portion.

#13 bundled three features. Two of them — the PM_CLI_BRIDGE_PASSWORD env var (#8) and the mail list server-side filtering / envelope fields / field selection (#9) — landed independently via #14 and #16, which conflicted with #13 across five files. Rather than resolve duplicate implementations of shipped features, this PR keeps only the batch command, which nothing else covers.

mail batch (closes #10)

Runs multiple label/unlabel/archive/move/flag/delete operations over a single IMAP session, avoiding a connect + auth round-trip per operation. Reads a JSON array from stdin or --file.

Validation happens up front, before any connection is opened — malformed input can't leave a mailbox half-mutated. Verified end-to-end:

$ echo '[{"op":"bogus","uids":["uid:1"]}]' | pm-cli mail batch --json
{"error": "operation 0: unknown op \"bogus\" (valid: label, unlabel, archive, move, flag, delete)", "success": false}

$ echo '[{"op":"label","uids":["uid:1"],"label":"Work\r\nX"}]' | pm-cli mail batch --json
{"error": "operation 0 (label): invalid mailbox/label name ...: contains IMAP special characters", "success": false}

CRLF/wildcard injection into mailbox and label names is rejected, input is capped at 10MB, and errors pass through safetext.SanitizeForTerminal.

Two defects fixed from #13

1. --help-json escaping. The batch examples used \" inside backtick raw string literals, so literal backslashes leaked into the agent-facing schema. Now emits valid JSON.
2. docs/commands.md field name. Listed seq as a --fields value; the implementation that actually shipped in feat(mail list): server-side unread/flagged filtering, envelope fields, and field selection #16 uses seq_num.

Also included

• docs/batch-format.md (operation schema) and docs/commands.md updates — the latter also documents the env var and new list flags from feat(config): read Bridge password from PM_CLI_BRIDGE_PASSWORD env var #14/feat(mail list): server-side unread/flagged filtering, envelope fields, and field selection #16, which weren't otherwise covered there.
• CHANGELOG.md for the full 0.2.6 set, crediting @Juan-de-Costa-Rica for reporting feat: read bridge password from environment variable #8–bug: silent success when STORE/COPY targets UIDs not present in selected mailbox #11 and @kochj23 for feat(config): read Bridge password from PM_CLI_BRIDGE_PASSWORD env var #14/fix(imap): error instead of silent success when STORE/COPY/MOVE target UIDs aren't present #15/feat(mail list): server-side unread/flagged filtering, envelope fields, and field selection #16.
• Version bump 0.2.5 → 0.2.6.

Verification

gofmt -l, go vet ./..., go test ./... clean. --help-json smoke-tested for correct rendering and version.

🤖 Generated with Claude Code