diff --git a/internal/web/auth.go b/internal/web/auth.go
index 571be25..61a782b 100644
--- a/internal/web/auth.go
+++ b/internal/web/auth.go
@@ -1,6 +1,7 @@
-// Package web is the Stage-0 HTTP read/write surface (ADR-011, docs/ui-spec.md).
+// Package web is the multi-user HTTP read/write surface (ADR-012, docs/ui-spec.md).
 // It serves the summary reader over the existing store; the engine and ports are
-// untouched (ADR-003).
+// untouched (ADR-003). ADR-011 shipped this as a single-user Stage-0 reader; ADR-012
+// opened Stage 1 — multiple Dex-authenticated users with DB-enforced (RLS) isolation.
 //
 // This file defines the auth SEAM so the Dex session layer (internal/web/oidc)
 // and the page/handler layer can be built independently: handlers depend only on
@@ -10,9 +11,10 @@ package web
 
 import "net/http"
 
-// User is the authenticated principal. Subject is the Dex subject used for the
-// single-user allowlist (ADR-011); store operations key off the configured
-// tapir user_id (UUID), not this subject.
+// User is the authenticated principal. Subject is the Dex subject — the key for the
+// user_identities lookup (ADR-012) that resolves to a tapir user_id (UUID); store
+// operations scope every row by that id, not by this subject. A subject with no
+// users row is routed through the registration gate (see registration.go).
 type User struct {
 	Subject string
 	Email   string