docs: notification dots — AOSP semantics detail, K-9 badge behavior, validation trick

CLAUDE.md

@@ -87,13 +87,38 @@ Prefs live in `/data/data/app.easy.launcher/shared_prefs/`. To change them:
   Users must grant notification access; the "Notification Dots" settings toggle
   opens `ACTION_NOTIFICATION_LISTENER_SETTINGS` when missing.
 - Badge semantics: per package the service sums `Notification.number` (or 1
-  when unset) over COUNTED notifications — same as AOSP Launcher3. Only
-  swipe-away, non-ongoing notifications are counted (music/FGS excluded).
+  when unset) over COUNTED notifications — same as AOSP Launcher3. Counted
+  = clearable (swipe-away), NON-ongoing, NON group-summary, userId >= 0.
+  Group summaries and USER_ALL (-1) records are excluded (verified with
+  `cmd notification post`, see the log tag `BadgeService` — `publish counts=`
+  lines). Re-posts overwrite the stored entry (in-place `Notification.number`
+  updates, e.g. K-9 unread count), and a notification that becomes
+  non-counted is dropped.
+- The dot is a plain red circle (NO white outline), drawn tangent to the
+  icon's top-right corner so it is never clipped (`NotificationDotHelper`).
+- NOTE: the dot follows ACTIVE notifications (AOSP/Pixel behavior). Apps that
+  cancel their notification when opened — K-9 Mail does this on every open —
+  make the dot disappear even when unread mail remains. There is NO Android
+  API to read an app's unread count (K-9 v22 exposes no provider and no
+  AccountManager accounts; counts live in its private Room DBs). This is
+  standard Android behavior, not a bug in this launcher.
+- Pref writes: `SHOW_NOTIFICATION_DOTS` must NOT be re-pushed from
+  `observeUserInterfaceSettings` — the other `setShowX` calls do write prefs,
+  and adding this one silently clobbered an on-disk `true` back to `false`
+  at startup (in-memory cache won). HomeFragment only observes
+  `showNotificationDotsLiveData` to rebind visible rows on toggle.
 - Grant from adb:
   `cmd notification allow_listener app.easy.launcher/com.github.droidworksstudio.launcher.service.NotificationBadgeService`
-- Test notification: `cmd notification post -t 'Title' tag 'body'` — posts as
-  `com.android.shell`, which has no launcher icon, so no dot is visible; verify
-  visually with a real app notification instead.
+- End-to-end validation trick (the shell can't spoof other packages): run
+  Termux's termux-notification as the user that owns com.termux.api (has a
+  launcher icon + posts a clearable notification):
+  ```
+  adb shell "su -c 'su 10261 -c \"PATH=/data/data/com.termux/files/usr/bin:\$PATH \
+    termux-notification --id reddot-test --title RedDotTest --content Clearable\"'"
+  ```
+  Expect a `BadgeService: publish counts={... 0/com.termux.api=1}` log and a
+  red dot on the Termux:API icon in the drawer. Verify pixels with
+  `python3`/PIL (dot = pure red, top-right of the icon box).
 - Counts live in `NotificationBadgeService.notificationCounts`
   (StateFlow, key `"userId/packageName"`); fragments rebind visible rows.