1 files changed, 46 insertions, 0 deletions

diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
index ba0ade5..f559bf1 100644
--- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
+++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
@@ -116,6 +116,7 @@ taking that too literally.
 | 56 | No action carries an icon, so the toolbar reserves space for nothing | presentation | S | **done** |
 | 57 | "Flag" would read better as "Important" or "Starred" | presentation | XS | **done** |
 | 58 | `message_zoom` documents a 0.5 to 3.0 range and enforces none of it | correctness | XS | open |
+| 59 | Archive and Mark all read shipped with the same icon | presentation | XS | **done** |
 
 Sizes are rough: XS under an hour, S a sitting, M a session.
 
@@ -3576,6 +3577,51 @@ numbers.
 `messageZoomDefaultsAndValidates` exists and passes today, so it is asserting
 only on the parse and not on the range.
 
+## 59. Archive and Mark all read shipped with the same icon
+
+**Observed (user, 2026-08-09), against 0.12.0:** "Archive" and "Mark all read"
+share the same icon, and in an icon-only setup they are not distinguishable.
+
+**Cause.** Introduced by item 56, in this session. The `themeIcons` table gave
+`archive` the name `mail-mark-read` (it predates item 56, from when only eight
+actions had icons and `mark_all_read` had none), and item 56 then assigned
+`mail-mark-read` to `mark_all_read` as well without checking the table for
+duplicates. Twenty-four entries were added or reviewed by hand and this one
+overlap was not noticed.
+
+It only became visible because of the other half of item 56. While the toolbar
+forced `TextBesideIcon` the label disambiguated the two buttons; once it follows
+a desktop set to icon-only, the icon **is** the whole control, and two buttons
+whose consequences differ (`archive` removes `inbox` from the selection,
+`mark_all_read` removes `unread` from the entire view) looked identical.
+
+**Fix.** `archive` now uses `mail-archive`, which is also the more accurate
+name: `mail-mark-read` describes read state, which is what `mark_all_read`
+does, not what archiving does.
+
+**The verification is the point of this entry.** A test for the reported pair
+would have been worthless, since the defect is the class and not the instance: a
+hand-written table of twenty-four names has more plausible duplicates in it.
+`noTwoActionsShareAnIcon` compares every action against every other and names
+any pair that matches. Two details matter:
+
+- It compares `QIcon::cacheKey()`, not the theme name, which the window does not
+  keep. Two *different* names that resolve to the same art on some theme are
+  equally ambiguous on screen, and that is what the user actually sees.
+- It carries a guard requiring every action to have an icon before comparing.
+  On a theme that resolves nothing, every icon is null, the loop body never
+  runs, and the assertion would pass having compared nothing.
+
+Mutation-checked by introducing a *different* collision (`zoom_out` pointed at
+`zoom-in`); the test named that pair rather than the one it was written for.
+
+**Also worth recording: the icon-name probe endorsed the wrong thing.** Item 56
+verified that every name resolves to non-null art, and that check passes
+happily for two names resolving to the *same* art. Resolving and being
+distinguishable are separate properties, and only the first was tested. The
+candidate replacement was therefore checked by rendering both icons at 24px and
+comparing the images, not by asking whether the name existed.
+
 ## Deferred, unsized, or split out
 
 Items noted while triaging but not part of the original list. Same numbering