docs: document card avatars and the business-senders list

1 files changed, 24 insertions, 0 deletions

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.