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