feat(users): quality pass + admin UX (sub-projects 1 & 2)

docs/framework-conventions.md

@@ -116,10 +116,10 @@ Module settings should:
 ```python
 class UsersModule(ModuleBase):
     def register_settings(self, app: FastAPI) -> None:
-        from users.services import UsersServices
         from users.settings import UsersSettings
+        from users.state import UsersState
 
-        app.state.users = UsersServices(settings=UsersSettings())
+        app.state.users = UsersState(settings=UsersSettings())
 ```
 
 ## Database
@@ -202,6 +202,8 @@ Service code should not call `session.commit()` directly. Flush for intermediate
 - `menus` — grouped by `MenuSection` (sidebar, adminSidebar, navbar, userDropdown), role-filtered.
 - `i18n` — active locale and translation bundle.
 
+The framework does not know the shape of `auth.user`. A module (typically `users`) registers a `principal_serializer: Callable[[user], dict]` on `app.state` during `register_settings(app)`; the middleware calls it with `request.state.user` to build the `auth.user` payload. Without a registered serializer, `auth.user` is `None` even when a user is authenticated.
+
 Use `InertiaDep` from `simple_module_hosting.inertia_deps` — it attaches the shared data automatically.
 
 ## Permissions