docs: record why mail-overview counts by tag, not path

qtmaildir scopes an account with a path glob, so the obvious move was to copy
that query. It is wrong for this panel. notmuch deduplicates by message id, so
a message that arrived at two configured addresses is one message with two
paths, and a path glob counts it under both accounts: the five accounts here
sum to 102 against a global total of 101.

The icon shows one global total and the panel header repeats it, so rows that
sum to a different number would look like a bug. Counting by the account tag,
which is a property of the message and therefore singular, makes the rows sum
to the header. The cost is that a cross posted message appears under only the
account the post-new hook attributed it to.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWL8JYHu7yhAdtx5pU9PMU

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-09-12-mail-overview-design.md b/docs/superpowers/specs/2026-09-12-mail-overview-design.md
index 571c26f..e5f2fa2 100644
--- a/docs/superpowers/specs/2026-09-12-mail-overview-design.md
+++ b/docs/superpowers/specs/2026-09-12-mail-overview-design.md
@@ -97,6 +97,29 @@ Plain `tag:unread` also counts archived but unread mail and mailing list
 traffic that was never in the inbox, which for one account is 41 against 32.
 The inbox scoped number is the one that means "new mail worth looking at".
 
+### Tags, not paths
+
+qtmaildir scopes a single account with a path glob,
+`path:"<maildir>/**" and tag:unread`. This design uses the `account-<key>` tag
+instead, and the difference is not cosmetic.
+
+notmuch deduplicates by message id, so one message that arrived at two of the
+configured addresses is a single message with two file paths. A path glob
+matches it under both accounts, so the per account counts sum to more than the
+total: measured here, five accounts summed to 102 against a global total of
+101. The `account-*` tag is a property of the message, so it is singular, and
+the per account counts always sum to the total.
+
+The waybar icon shows one global total and the panel header shows the same
+number, so rows that sum to something else would read as a bug. The cost is
+that a cross posted message appears under only one account, whichever the
+post-new hook attributed it to. That is the right trade for an overview whose
+headline figure is a single number.
+
+Note also that the qtmaildir query has no inbox term: the path glob restricts
+to the account but not to the inbox, so it includes archived unread mail unless
+qtmaildir adds its own scope. The queries here are always inbox scoped.
+
 ## The waybar module
 
 Continuous mode: the script does not exit, it prints one JSON line per