From 0e5c66b98fb6e618265755c13dcabcc1fd1bfca4 Mon Sep 17 00:00:00 2001
From: cottongin <cottongin@users.noreply.github.com>
Date: Mon, 23 Mar 2026 03:25:15 -0400
Subject: [PATCH] Address spec review feedback for named admins design

Clarify WS auth rejection for stale tokens, enumerate all
migrated localStorage keys, and add theme exception note to overview.

Made-with: Cursor
---
 .../specs/2026-03-23-named-admins-design.md         | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/superpowers/specs/2026-03-23-named-admins-design.md b/docs/superpowers/specs/2026-03-23-named-admins-design.md
index 83d1f60..cd8f9ee 100644
--- a/docs/superpowers/specs/2026-03-23-named-admins-design.md
+++ b/docs/superpowers/specs/2026-03-23-named-admins-design.md
@@ -5,7 +5,7 @@
 
 ## Overview
 
-Replace the single shared `ADMIN_KEY` with named admin accounts, each with their own key. Per-admin preferences are stored in namespaced `localStorage`. A real-time "who is watching" presence bar shows which admins are on the same page.
+Replace the single shared `ADMIN_KEY` with named admin accounts, each with their own key. Per-admin preferences are stored in namespaced `localStorage` (except theme, which stays shared — see Edge Cases). A real-time "who is watching" presence bar shows which admins are on the same page.
 
 ## Requirements
 
@@ -84,7 +84,7 @@ A utility function (e.g. in `frontend/src/utils/adminPrefs.js`):
 
 ### One-time migration
 
-On login, if old un-namespaced keys exist (e.g. `history-filter`), copy them to the namespaced version (`alice:history-filter`) and delete the originals. This preserves existing preferences for the first admin who logs in after the upgrade.
+On login, if old un-namespaced keys exist (`history-filter`, `history-show-limit`), copy them to the namespaced versions (`alice:history-filter`, `alice:history-show-limit`) and delete the originals. This preserves existing preferences for the first admin who logs in after the upgrade.
 
 ---
 
@@ -115,7 +115,7 @@ On login, if old un-namespaced keys exist (e.g. `history-filter`), copy them to
 ### Frontend component — `PresenceBar`
 
 - Renders below the `<nav>`, above page content (in `App.jsx` route layout area).
-- Only renders when the current admin is authenticated and there are viewers.
+- Only renders when the current admin is authenticated **and at least one other admin is on the same page**. A solo admin sees no presence bar — "me" alone is not useful information.
 - Small card with caption "who is watching" and a row of name badges (rounded pills).
 - Styling: subtle, fits the existing indigo/gray theme.
 - Non-admin visitors see nothing.
@@ -148,9 +148,14 @@ Example when Alice is on `/history` with Bob:
 | `docker-compose.yml` | Add `ADMIN_CONFIG_PATH` env var (optional) |
 | `tests/jest.setup.js` | Update test admin config |
 
+## Edge Cases
+
+- **Existing JWTs after deploy:** Tokens issued before this change lack `name`. The `verify` endpoint and `AuthContext` should treat a missing `name` as stale and force re-login (call `logout()`). WebSocket auth should also reject tokens missing `name` (send `auth_error`). Since tokens expire in 24h, this is a brief transition.
+- **Theme preference:** `ThemeContext` uses the global `theme` localStorage key. Theme stays **shared** (not namespaced per admin) — it's a browser-level display preference, not an admin workflow preference.
+
 ## Out of Scope
 
 - UI-based key management (keys are managed server-side only)
-- Audit logging / login history (clean upgrade path via Approach 3 if desired later)
+- Audit logging / login history (could be added later with a lightweight SQLite table if desired)
 - Server-side preference storage (per-browser localStorage is sufficient and desirable)
 - Admin key hashing (keys are compared with strict equality, same as current `ADMIN_KEY`)