docs: document card avatars and the business-senders list

2 files changed, 31 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e069722..bc3308d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,6 +46,13 @@ point at which they are stable.
   to the message and nothing reaches your mail server. It is deliberately a
   different mark from `passed`, which is the Maildir `P` flag and means *you*
   forwarded something.
+- Cards carry the sender's avatar: a squircle with their initials, filled with
+  a pattern generated from their address so the same sender always looks the
+  same. Senders that present a display name get an identicon, bulk senders a
+  two-tone fill, and `~/.config/qtmaildir/business-senders` decides the
+  borderline cases. Nothing is fetched from the network.
+- The account's colour now fades across the left of a card instead of only
+  marking its edge, and a reply's fade starts at its own indent.
 
 ### Changed
 
diff --git a/README.md b/README.md
index bbb423e..91561f5 100644
--- a/README.md
+++ b/README.md
@@ -429,6 +429,30 @@ Sent mail is presented differently from the rest, because it reads differently:
 This applies only to the Sent button. The same query typed into the bar by hand
 behaves like any other query, threads and all.
 
+### `~/.config/qtmaildir/business-senders`
+
+Addresses that should read as businesses rather than people, one per line.
+A card's avatar takes its pattern from this: a listed address gets the
+two-tone fill, anything presenting a display name gets the identicon.
+
+    # a comment, and the form the application itself writes
+    # noreply@cofidis.it (47 messages)
+    billing@example.org
+    @newsletter.example.com
+
+An entry is either an exact address or a whole domain written `@example.com`.
+Comments and blank lines are ignored.
+
+After each sync the application appends addresses that look like bulk mail,
+**always commented out**, so nothing changes appearance until you uncomment
+it. Anything already in the file, commented or not, is never proposed again:
+commenting a line out is therefore the permanent way to reject it, while
+deleting it lets that sender be proposed again if they write to you.
+
+The first scan, when the file does not exist or holds no active entry, covers
+the whole database so the list is useful straight away. Afterwards it covers
+the last week's mail.
+
 ## The query bar
 
 The bar at the top takes a notmuch query and shows the matching threads.