fix(build): add production API URLs to Docker build

Dockerfile now passes --dart-define flags for CORE_API_URL and
TATLOCK_API_URL pointing to schweitz.net domains. This enables
requiresAuth=true, fixing auth being completely skipped in production.

Also added service port reference table to AGENTS.md.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitea/workflows/build.yml

@@ -1,15 +1,27 @@
 name: Build and Push
 
 on:
-  release:
+  push:
-    types: [published]
+    tags:
+      - 'v*'
 
 jobs:
-  build:
+  release:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - name: Create Gitea Release
-        uses: actions/checkout@v4
+        run: |
+          curl -sf -X POST \
+            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{"tag_name": "${{ github.ref_name }}", "name": "Release ${{ github.ref_name }}", "body": "Automated release for ${{ github.ref_name }}"}' \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
+
+  build:
+    runs-on: ubuntu-latest
+    needs: release
+    steps:
+      - uses: actions/checkout@v4
 
       - name: Login to Gitea Registry
         uses: docker/login-action@v3

AGENTS.md

@@ -22,14 +22,20 @@ This document contains instructions and documentation references for AI assistan
   * Related repos: , `core-api`, `tatlock`, `library-desk`, `scheduler`, `portainer-core`
 
 ### 🐳 Deployment & Infrastructure
+
+**⚠️ IMPORTANT: Service Port Reference**
+| Service | LAN Port | External URL | Notes |
+|---------|----------|--------------|-------|
+| **Core API** | 8083 | `api.schweitz.net` | FastAPI backend for this UI |
+| **Tatlock API** | 8000 | `tatlock.schweitz.net` | Legacy Python API (Ollama proxy) |
+| **Tatlock UI** | 9999 | `home.schweitz.net` | This Flutter app |
+
 * **Full stack documentation**: Available in the `portainer-core` repo
-  * Access: `curl http://localhost:3002/jpmschweitzer/portainer-core/raw/branch/main/CONTAINERS.md`
+  * Access: `curl http://192.168.86.149:3002/jpmschweitzer/portainer-core/raw/branch/main/CONTAINERS.md`
   * Contains: All service ports, URLs, Redis DB allocations, external domains
-* **Tatlock deployment**:
+* **Health checks**:
-  * LAN: `http://192.168.86.149:8000`
+  * Core API: `curl http://192.168.86.149:8083/health`
-  * External: `tatlock.schweitz.net` (behind Authentik SSO)
+  * Tatlock API: `curl http://192.168.86.149:8000/health`
-  * Redis DBs: 1 (memory), 6 (benchmarks)
-* **Health check**: `curl http://192.168.86.149:8000/health`
 
 ### 🛡️ Git Discipline
 * **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.

CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-01-03
+
+### Fixed
+- Production Docker build now uses correct API URLs
+  - Added `--dart-define` flags for `CORE_API_URL` and `TATLOCK_API_URL`
+  - This enables `requiresAuth=true` so authentication is actually triggered
+- Updated AGENTS.md with clear service port reference table
+
+## [1.0.1] - 2026-01-03
+
+### Fixed
+- Web authentication now works correctly with NPM forward auth
+  - Dio client sends cookies with requests via `withCredentials: true`
+  - Added platform-specific adapters (native vs web) for proper cookie handling
+
+## [1.0.0] - 2026-01-03
+
+### Added
+- **Authentication System** - Dual-flow auth supporting web (NPM forward auth) and mobile (OIDC)
+  - `AuthState` model with roles, permissions, and user preferences
+  - `AuthProvider` with automatic web session detection via `/auth/me`
+  - Permission system with Domain/Action enums and hierarchical access levels
+  - `PermissionGate` and `AdminGate` widgets for UI permission checks
+  - `Role` model with `{domain}.{category}:{action}` format parsing
+  - Route guards redirect unauthenticated users to login page
+- Login page with Authentik OAuth redirect
+- Mobile auth platform configuration (iOS URL schemes, Android AppAuth)
+- Comprehensive auth test suite (60 unit tests)
+
+### Changed
+- API interceptor skips Bearer tokens on web (uses cookies via NPM forward auth)
+- Router integrates auth state for protected route access
+- **First stable release** - Core functionality complete for home lab dashboard
+
 ## [0.3.3] - 2026-01-03
 
 ### Added

Dockerfile

@@ -15,8 +15,11 @@ COPY . .
 # Generate code with build_runner
 RUN dart run build_runner build --delete-conflicting-outputs
 
-# Build for web release
+# Build for web release with production configuration
-RUN flutter build web --release
+# These URLs enable authentication (requiresAuth = true when URL contains schweitz.net)
+RUN flutter build web --release \
+    --dart-define=CORE_API_URL=https://api.schweitz.net \
+    --dart-define=TATLOCK_API_URL=https://tatlock.schweitz.net
 
 # Stage 2: Serve with nginx
 FROM nginx:alpine

android/app/build.gradle.kts

@@ -24,10 +24,13 @@ android {
         applicationId = "net.schweitz.tatlock_ui"
         // You can update the following values to match your application needs.
         // For more information, see: https://flutter.dev/to/review-gradle-config.
-        minSdk = flutter.minSdkVersion
+        minSdk = 23  // Required for AppAuth
         targetSdk = flutter.targetSdkVersion
         versionCode = flutter.versionCode
         versionName = flutter.versionName
+
+        // flutter_appauth redirect scheme for OIDC callbacks
+        manifestPlaceholders["appAuthRedirectScheme"] = "net.schweitz.tatlock"
     }
 
     buildTypes {

docs/ARCHITECTURE.md

@@ -142,7 +142,7 @@ part 'container_model.freezed.dart';
 part 'container_model.g.dart';
 
 @freezed
-class ContainerModel with _$ContainerModel {
+sealed class ContainerModel with _$ContainerModel {
   const factory ContainerModel({
     required String id,
     required String name,
@@ -464,6 +464,34 @@ Generated files:
 - `*.freezed.dart` - Immutable classes
 - `*.g.dart` - JSON serialization, Riverpod providers
 
+### Freezed 3.x: Required `sealed class`
+
+**Freezed 3.x requires the `sealed` keyword** on all classes with generated mixins. Without it, the generated code will fail to compile with errors about missing concrete implementations.
+
+```dart
+// ✅ Correct - Freezed 3.x
+@freezed
+sealed class UserModel with _$UserModel {
+  const factory UserModel({
+    required String id,
+    required String name,
+  }) = _UserModel;
+
+  factory UserModel.fromJson(Map<String, dynamic> json) =>
+      _$UserModelFromJson(json);
+}
+
+// ❌ Wrong - will fail to compile
+@freezed
+class UserModel with _$UserModel {  // Missing `sealed`
+  const factory UserModel({...}) = _UserModel;
+}
+```
+
+The `sealed` keyword was introduced in Dart 3.0 and allows the generated mixin `_$UserModel` to have abstract members that are implemented by the private `_UserModel` class.
+
+**Always use `sealed class` with `@freezed`** - this applies to all models, entities, and state classes using Freezed.
+
 ## Import Rules
 
 1. Never import from `data/` in `domain/`

ios/Runner/Info.plist

@@ -45,5 +45,18 @@
 	<true/>
 	<key>UIApplicationSupportsIndirectInputEvents</key>
 	<true/>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleTypeRole</key>
+			<string>Editor</string>
+			<key>CFBundleURLName</key>
+			<string>net.schweitz.tatlock</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>net.schweitz.tatlock</string>
+			</array>
+		</dict>
+	</array>
 </dict>
 </plist>

lib/core/api/api_client.dart

@@ -3,23 +3,26 @@ import 'package:riverpod_annotation/riverpod_annotation.dart';
 import 'package:tatlock_ui/core/api/api_interceptors.dart';
 import 'package:tatlock_ui/core/config/app_config.dart';
 
+import 'api_client_native.dart' if (dart.library.html) 'api_client_web.dart'
+    as platform;
+
 part 'api_client.g.dart';
 
 /// Provides the Dio instance for Core API.
 @riverpod
 Dio coreApiClient(Ref ref) {
-  final dio = Dio(
+  final options = BaseOptions(
-    BaseOptions(
+    baseUrl: AppConfig.coreApiUrl,
-      baseUrl: AppConfig.coreApiUrl,
+    connectTimeout: const Duration(seconds: 10),
-      connectTimeout: const Duration(seconds: 10),
+    receiveTimeout: const Duration(seconds: 30),
-      receiveTimeout: const Duration(seconds: 30),
+    headers: {
-      headers: {
+      'Content-Type': 'application/json',
-        'Content-Type': 'application/json',
+      'Accept': 'application/json',
-        'Accept': 'application/json',
+    },
-      },
-    ),
   );
 
+  final dio = platform.createDio(options);
+
   dio.interceptors.addAll([
     AuthInterceptor(ref),
     LoggingInterceptor(),
@@ -32,18 +35,18 @@ Dio coreApiClient(Ref ref) {
 /// Provides the Dio instance for Tatlock API.
 @riverpod
 Dio tatlockApiClient(Ref ref) {
-  final dio = Dio(
+  final options = BaseOptions(
-    BaseOptions(
+    baseUrl: AppConfig.tatlockApiUrl,
-      baseUrl: AppConfig.tatlockApiUrl,
+    connectTimeout: const Duration(seconds: 10),
-      connectTimeout: const Duration(seconds: 10),
+    receiveTimeout: const Duration(minutes: 5), // Longer for LLM responses
-      receiveTimeout: const Duration(minutes: 5), // Longer for LLM responses
+    headers: {
-      headers: {
+      'Content-Type': 'application/json',
-        'Content-Type': 'application/json',
+      'Accept': 'application/json',
-        'Accept': 'application/json',
+    },
-      },
-    ),
   );
 
+  final dio = platform.createDio(options);
+
   dio.interceptors.addAll([
     AuthInterceptor(ref),
     LoggingInterceptor(),

lib/core/api/api_client_native.dart

@@ -0,0 +1,6 @@
+import 'package:dio/dio.dart';
+
+/// Create a Dio instance for native platforms (mobile, desktop).
+Dio createDio(BaseOptions options) {
+  return Dio(options);
+}

lib/core/api/api_client_web.dart

@@ -0,0 +1,12 @@
+import 'package:dio/dio.dart';
+import 'package:dio_web_adapter/dio_web_adapter.dart';
+
+/// Create a Dio instance for web platform with credentials support.
+///
+/// Enables `withCredentials` to send cookies with requests, which is
+/// required for NPM forward auth to work correctly.
+Dio createDio(BaseOptions options) {
+  final dio = Dio(options);
+  dio.httpClientAdapter = BrowserHttpClientAdapter(withCredentials: true);
+  return dio;
+}

lib/core/api/api_interceptors.dart

@@ -9,7 +9,9 @@ import 'package:tatlock_ui/core/error/app_exception.dart';
 
 /// Adds authentication token to requests.
 ///
-/// Skipped entirely when [AppConfig.requiresAuth] is false (LAN development).
+/// - **LAN mode**: Skipped entirely (no auth required)
+/// - **Web**: Skipped (cookies handle auth via NPM forward auth)
+/// - **Mobile**: Adds Bearer token from OIDC authentication
 class AuthInterceptor extends Interceptor {
   AuthInterceptor(this._ref);
 
@@ -23,10 +25,17 @@ class AuthInterceptor extends Interceptor {
       return;
     }
 
+    // Skip Bearer token on web - cookies handle auth via NPM forward auth
+    if (kIsWeb) {
+      handler.next(options);
+      return;
+    }
+
+    // Mobile: Add Bearer token from OIDC authentication
     final authState = _ref.read(authProvider);
 
     authState.whenData((auth) {
-      if (auth.isAuthenticated && auth.accessToken != null) {
+      if (auth.isAuthenticated && auth.accessToken != null && auth.accessToken != 'web-session') {
         options.headers['Authorization'] = 'Bearer ${auth.accessToken}';
       }
     });

lib/core/auth/auth_datasource.dart

@@ -0,0 +1,133 @@
+import 'package:dio/dio.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+import '../api/api_client.dart';
+import 'permissions.dart';
+import 'user_preferences.dart';
+
+part 'auth_datasource.g.dart';
+
+/// Response from POST /auth/sync endpoint.
+class AuthSyncResponse {
+  const AuthSyncResponse({
+    required this.userId,
+    required this.authentikId,
+    required this.email,
+    required this.name,
+    this.avatarUrl,
+    required this.roles,
+    required this.preferences,
+    required this.isNewUser,
+  });
+
+  final String userId;
+  final String authentikId;
+  final String email;
+  final String name;
+  final String? avatarUrl;
+  final List<Role> roles;
+  final UserPreferences preferences;
+  final bool isNewUser;
+
+  factory AuthSyncResponse.fromJson(Map<String, dynamic> json) {
+    final user = json['user'] as Map<String, dynamic>;
+    final rolesJson = json['roles'] as List<dynamic>;
+    final prefsJson = json['preferences'] as Map<String, dynamic>;
+
+    return AuthSyncResponse(
+      userId: user['id'] as String,
+      authentikId: user['authentik_id'] as String,
+      email: user['email'] as String,
+      name: user['name'] as String,
+      avatarUrl: user['avatar_url'] as String?,
+      roles: rolesJson.map((r) => _parseRole(r as Map<String, dynamic>)).toList(),
+      preferences: UserPreferences.fromJson(prefsJson),
+      isNewUser: json['is_new_user'] as bool,
+    );
+  }
+}
+
+/// Parse a role from API JSON.
+Role _parseRole(Map<String, dynamic> json) {
+  final name = json['name'] as String;
+  final domainStr = json['domain'] as String;
+  final category = json['category'] as String? ?? 'general';
+  final actionStr = json['action'] as String;
+
+  final domain = Domain.fromString(domainStr);
+  final action = Action.fromString(actionStr);
+
+  if (domain == null || action == null) {
+    // Return a placeholder role for unknown domains/actions
+    return Role(
+      id: json['id'] as String,
+      name: name,
+      domain: Domain.admin, // Fallback
+      category: category,
+      action: Action.viewer, // Fallback - least privilege
+    );
+  }
+
+  return Role(
+    id: json['id'] as String,
+    name: name,
+    domain: domain,
+    category: category,
+    action: action,
+  );
+}
+
+/// Datasource for auth API endpoints.
+class AuthDatasource {
+  AuthDatasource(this._dio);
+
+  final Dio _dio;
+
+  /// Sync user with core-api after OIDC authentication.
+  ///
+  /// Sends the OIDC access token to core-api, which validates it with Authentik
+  /// and returns the user profile, roles, and preferences.
+  Future<AuthSyncResponse> syncUser(String accessToken) async {
+    final response = await _dio.post<Map<String, dynamic>>(
+      '/auth/sync',
+      data: {'access_token': accessToken},
+    );
+
+    return AuthSyncResponse.fromJson(response.data!);
+  }
+
+  /// Get current user profile via NPM forward auth.
+  ///
+  /// This endpoint reads X-authentik-* headers set by NPM forward auth.
+  /// Returns user profile if authenticated via the proxy.
+  /// Throws 401 if not authenticated or accessing directly.
+  Future<AuthSyncResponse> getCurrentUser() async {
+    final response = await _dio.get<Map<String, dynamic>>('/auth/me');
+    return AuthSyncResponse.fromJson(response.data!);
+  }
+
+  /// Update user preferences.
+  Future<UserPreferences> updatePreferences({
+    String? theme,
+    String? defaultRoom,
+    Map<String, dynamic>? preferencesJson,
+  }) async {
+    final data = <String, dynamic>{};
+    if (theme != null) data['theme'] = theme;
+    if (defaultRoom != null) data['default_room'] = defaultRoom;
+    if (preferencesJson != null) data['preferences_json'] = preferencesJson;
+
+    final response = await _dio.patch<Map<String, dynamic>>(
+      '/auth/users/me/preferences',
+      data: data,
+    );
+
+    return UserPreferences.fromJson(response.data!);
+  }
+}
+
+/// Provider for the auth datasource.
+@riverpod
+AuthDatasource authDatasource(Ref ref) {
+  return AuthDatasource(ref.watch(coreApiClientProvider));
+}

lib/core/auth/auth_provider.dart

@@ -1,31 +1,109 @@
+import 'dart:convert';
 import 'dart:developer' as developer;
 
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:riverpod_annotation/riverpod_annotation.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
+import '../config/app_config.dart';
+import 'auth_datasource.dart';
 import 'auth_state.dart';
+import 'oidc_service.dart';
+import 'permissions.dart';
+import 'user_preferences.dart';
 
 part 'auth_provider.g.dart';
 
 /// Provides authentication state and operations.
 ///
-/// Note: Full OIDC implementation with flutter_appauth requires
+/// Supports two authentication flows:
-/// native platform configuration. For now, this provides the
+/// - **Web**: NPM forward auth with Authentik (cookies handled by proxy)
-/// state management infrastructure.
+/// - **Mobile**: OIDC Authorization Code flow with flutter_appauth
+///
+/// On web, the app calls GET /auth/me to check if user is authenticated
+/// via NPM forward auth headers. On mobile, uses OIDC flow then POST /auth/sync.
 @riverpod
 class AuthNotifier extends _$AuthNotifier {
+  // Storage keys
   static const _accessTokenKey = 'auth_access_token';
   static const _refreshTokenKey = 'auth_refresh_token';
   static const _expiresAtKey = 'auth_expires_at';
   static const _userIdKey = 'auth_user_id';
+  static const _authentikIdKey = 'auth_authentik_id';
   static const _userNameKey = 'auth_user_name';
   static const _userEmailKey = 'auth_user_email';
+  static const _avatarUrlKey = 'auth_avatar_url';
+  static const _rolesKey = 'auth_roles';
+  static const _preferencesKey = 'auth_preferences';
 
   @override
   Future<AuthState> build() async {
+    // On web with auth required, try to get user from NPM forward auth
+    if (kIsWeb && AppConfig.requiresAuth) {
+      final webAuth = await _tryWebAuth();
+      if (webAuth != null) {
+        return webAuth;
+      }
+      // If web auth failed, user needs to refresh to trigger NPM login
+      developer.log('Web auth not available - user may need to login via proxy', name: 'auth');
+      return const AuthState();
+    }
+
+    // On mobile or LAN, load from stored auth
     return _loadStoredAuth();
   }
 
+  /// Try to authenticate via NPM forward auth (web only).
+  ///
+  /// Returns AuthState if authenticated, null if not.
+  Future<AuthState?> _tryWebAuth() async {
+    try {
+      developer.log('Attempting web auth via /auth/me', name: 'auth');
+      final authDatasource = ref.read(authDatasourceProvider);
+      final syncResponse = await authDatasource.getCurrentUser();
+
+      developer.log(
+        'Web auth successful: ${syncResponse.name} with ${syncResponse.roles.length} roles',
+        name: 'auth',
+      );
+
+      // Store auth data for offline/cached access
+      await _storeAuth(
+        accessToken: 'web-session', // Placeholder - web uses cookies
+        userId: syncResponse.userId,
+        authentikId: syncResponse.authentikId,
+        userName: syncResponse.name,
+        userEmail: syncResponse.email,
+        avatarUrl: syncResponse.avatarUrl,
+        roles: syncResponse.roles,
+        preferences: syncResponse.preferences,
+      );
+
+      return AuthState(
+        isAuthenticated: true,
+        accessToken: 'web-session',
+        userId: syncResponse.userId,
+        authentikId: syncResponse.authentikId,
+        userName: syncResponse.name,
+        userEmail: syncResponse.email,
+        avatarUrl: syncResponse.avatarUrl,
+        roles: syncResponse.roles,
+        preferences: syncResponse.preferences,
+      );
+    } on DioException catch (e) {
+      if (e.response?.statusCode == 401) {
+        developer.log('Web auth: not authenticated via proxy', name: 'auth');
+        return null;
+      }
+      developer.log('Web auth error: $e', name: 'auth');
+      return null;
+    } catch (e) {
+      developer.log('Web auth unexpected error: $e', name: 'auth');
+      return null;
+    }
+  }
+
   Future<AuthState> _loadStoredAuth() async {
     try {
       final prefs = await SharedPreferences.getInstance();
@@ -40,17 +118,36 @@ class AuthNotifier extends _$AuthNotifier {
           ? DateTime.fromMillisecondsSinceEpoch(expiresAtMs)
           : null;
 
+      // Load roles from JSON
+      final rolesJson = prefs.getString(_rolesKey);
+      final roles = rolesJson != null ? _parseRoles(rolesJson) : <Role>[];
+
+      // Load preferences from JSON
+      final prefsJson = prefs.getString(_preferencesKey);
+      final preferences = prefsJson != null
+          ? UserPreferences.fromJson(jsonDecode(prefsJson) as Map<String, dynamic>)
+          : null;
+
       final authState = AuthState(
         isAuthenticated: true,
         accessToken: accessToken,
         refreshToken: prefs.getString(_refreshTokenKey),
         expiresAt: expiresAt,
         userId: prefs.getString(_userIdKey),
+        authentikId: prefs.getString(_authentikIdKey),
         userName: prefs.getString(_userNameKey),
         userEmail: prefs.getString(_userEmailKey),
+        avatarUrl: prefs.getString(_avatarUrlKey),
+        roles: roles,
+        preferences: preferences,
       );
 
-      // Check if token is expired
+      // Check if token is expired - try to refresh
+      if (authState.isTokenExpired && authState.refreshToken != null) {
+        developer.log('Token expired, attempting refresh', name: 'auth');
+        return _tryRefreshToken(authState);
+      }
+
       if (authState.isTokenExpired) {
         developer.log('Stored token expired, clearing auth', name: 'auth');
         await _clearStoredAuth();
@@ -65,12 +162,149 @@ class AuthNotifier extends _$AuthNotifier {
     }
   }
 
-  /// Sign in with OIDC (placeholder for flutter_appauth integration).
+  /// Parse roles from stored JSON.
+  List<Role> _parseRoles(String json) {
+    try {
+      final list = jsonDecode(json) as List<dynamic>;
+      return list.map((item) {
+        final map = item as Map<String, dynamic>;
+        final domain = Domain.fromString(map['domain'] as String);
+        final action = Action.fromString(map['action'] as String);
+
+        if (domain == null || action == null) {
+          return null;
+        }
+
+        return Role(
+          id: map['id'] as String,
+          name: map['name'] as String,
+          domain: domain,
+          category: map['category'] as String? ?? 'general',
+          action: action,
+        );
+      }).whereType<Role>().toList();
+    } catch (e) {
+      developer.log('Failed to parse roles: $e', name: 'auth');
+      return [];
+    }
+  }
+
+  /// Try to refresh the access token.
+  Future<AuthState> _tryRefreshToken(AuthState currentState) async {
+    if (currentState.refreshToken == null) {
+      await _clearStoredAuth();
+      return const AuthState();
+    }
+
+    try {
+      final oidcService = ref.read(oidcServiceProvider);
+      final tokens = await oidcService.refreshToken(currentState.refreshToken!);
+
+      // Update stored tokens
+      final prefs = await SharedPreferences.getInstance();
+      await prefs.setString(_accessTokenKey, tokens.accessToken);
+      if (tokens.refreshToken != null) {
+        await prefs.setString(_refreshTokenKey, tokens.refreshToken!);
+      }
+      await prefs.setInt(_expiresAtKey, tokens.expiresAt.millisecondsSinceEpoch);
+
+      developer.log('Token refreshed successfully', name: 'auth');
+
+      return currentState.copyWith(
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken ?? currentState.refreshToken,
+        expiresAt: tokens.expiresAt,
+      );
+    } catch (e) {
+      developer.log('Token refresh failed: $e', name: 'auth');
+      await _clearStoredAuth();
+      return const AuthState();
+    }
+  }
+
+  /// Sign in with the appropriate method for the platform.
+  ///
+  /// - **Web**: Triggers page reload to go through NPM forward auth
+  /// - **Mobile**: Opens Authentik login via OIDC, then syncs with core-api
   Future<void> signIn() async {
-    // TODO: Implement OIDC flow with flutter_appauth
+    if (!AppConfig.requiresAuth) {
-    // For now, this is a placeholder that will be implemented
+      developer.log('Auth not required in LAN mode', name: 'auth');
-    // when native platform configuration is complete.
+      // In LAN mode, set a minimal authenticated state
-    developer.log('Sign in requested - OIDC not yet configured', name: 'auth');
+      state = const AsyncData(AuthState(isAuthenticated: true));
+      return;
+    }
+
+    // On web, auth is handled by NPM forward auth
+    // User needs to access via the authenticated proxy URL
+    if (kIsWeb) {
+      developer.log('Web sign-in: user should access via authenticated proxy', name: 'auth');
+      // Try to refresh auth state from /auth/me
+      state = const AsyncLoading();
+      final webAuth = await _tryWebAuth();
+      if (webAuth != null) {
+        state = AsyncData(webAuth);
+      } else {
+        state = AsyncError(
+          Exception('Not authenticated - please access via the authenticated URL'),
+          StackTrace.current,
+        );
+      }
+      return;
+    }
+
+    // Mobile: Use OIDC flow
+    state = const AsyncLoading();
+
+    try {
+      // Step 1: OIDC authentication with Authentik
+      developer.log('Starting OIDC authentication', name: 'auth');
+      final oidcService = ref.read(oidcServiceProvider);
+      final tokens = await oidcService.signIn();
+
+      // Step 2: Sync with core-api to get user profile and roles
+      developer.log('Syncing with core-api', name: 'auth');
+      final authDatasource = ref.read(authDatasourceProvider);
+      final syncResponse = await authDatasource.syncUser(tokens.accessToken);
+
+      // Step 3: Store credentials and user data
+      await _storeAuth(
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        expiresAt: tokens.expiresAt,
+        userId: syncResponse.userId,
+        authentikId: syncResponse.authentikId,
+        userName: syncResponse.name,
+        userEmail: syncResponse.email,
+        avatarUrl: syncResponse.avatarUrl,
+        roles: syncResponse.roles,
+        preferences: syncResponse.preferences,
+      );
+
+      state = AsyncData(AuthState(
+        isAuthenticated: true,
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        expiresAt: tokens.expiresAt,
+        userId: syncResponse.userId,
+        authentikId: syncResponse.authentikId,
+        userName: syncResponse.name,
+        userEmail: syncResponse.email,
+        avatarUrl: syncResponse.avatarUrl,
+        roles: syncResponse.roles,
+        preferences: syncResponse.preferences,
+      ));
+
+      developer.log(
+        'Authenticated as ${syncResponse.name} with ${syncResponse.roles.length} roles',
+        name: 'auth',
+      );
+    } on OidcException catch (e) {
+      developer.log('OIDC authentication failed: $e', name: 'auth');
+      state = AsyncError(e, StackTrace.current);
+    } catch (e, stack) {
+      developer.log('Authentication failed: $e', name: 'auth');
+      state = AsyncError(e, stack);
+    }
   }
 
   /// Sign out and clear stored credentials.
@@ -80,14 +314,47 @@ class AuthNotifier extends _$AuthNotifier {
     developer.log('Signed out', name: 'auth');
   }
 
-  /// Update auth state (called after successful OIDC flow).
+  /// Update user preferences.
-  Future<void> setAuthenticated({
+  Future<void> updatePreferences({
+    String? theme,
+    String? defaultRoom,
+    Map<String, dynamic>? preferencesJson,
+  }) async {
+    final currentState = state.value;
+    if (currentState == null || !currentState.isAuthenticated) return;
+
+    try {
+      final authDatasource = ref.read(authDatasourceProvider);
+      final newPrefs = await authDatasource.updatePreferences(
+        theme: theme,
+        defaultRoom: defaultRoom,
+        preferencesJson: preferencesJson,
+      );
+
+      // Update stored preferences
+      final prefs = await SharedPreferences.getInstance();
+      await prefs.setString(_preferencesKey, jsonEncode(newPrefs.toJson()));
+
+      state = AsyncData(currentState.copyWith(preferences: newPrefs));
+      developer.log('Preferences updated', name: 'auth');
+    } catch (e) {
+      developer.log('Failed to update preferences: $e', name: 'auth');
+      rethrow;
+    }
+  }
+
+  /// Store authentication data to SharedPreferences.
+  Future<void> _storeAuth({
     required String accessToken,
     String? refreshToken,
     DateTime? expiresAt,
     String? userId,
+    String? authentikId,
     String? userName,
     String? userEmail,
+    String? avatarUrl,
+    List<Role>? roles,
+    UserPreferences? preferences,
   }) async {
     final prefs = await SharedPreferences.getInstance();
 
@@ -99,20 +366,27 @@ class AuthNotifier extends _$AuthNotifier {
       await prefs.setInt(_expiresAtKey, expiresAt.millisecondsSinceEpoch);
     }
     if (userId != null) await prefs.setString(_userIdKey, userId);
+    if (authentikId != null) await prefs.setString(_authentikIdKey, authentikId);
     if (userName != null) await prefs.setString(_userNameKey, userName);
     if (userEmail != null) await prefs.setString(_userEmailKey, userEmail);
+    if (avatarUrl != null) await prefs.setString(_avatarUrlKey, avatarUrl);
 
-    state = AsyncData(AuthState(
+    // Store roles as JSON
-      isAuthenticated: true,
+    if (roles != null) {
-      accessToken: accessToken,
+      final rolesJson = jsonEncode(roles.map((r) => {
-      refreshToken: refreshToken,
+        'id': r.id,
-      expiresAt: expiresAt,
+        'name': r.name,
-      userId: userId,
+        'domain': r.domain.value,
-      userName: userName,
+        'category': r.category,
-      userEmail: userEmail,
+        'action': r.action.name,
-    ));
+      }).toList());
+      await prefs.setString(_rolesKey, rolesJson);
+    }
 
-    developer.log('Authenticated as $userName', name: 'auth');
+    // Store preferences as JSON
+    if (preferences != null) {
+      await prefs.setString(_preferencesKey, jsonEncode(preferences.toJson()));
+    }
   }
 
   Future<void> _clearStoredAuth() async {
@@ -121,7 +395,11 @@ class AuthNotifier extends _$AuthNotifier {
     await prefs.remove(_refreshTokenKey);
     await prefs.remove(_expiresAtKey);
     await prefs.remove(_userIdKey);
+    await prefs.remove(_authentikIdKey);
     await prefs.remove(_userNameKey);
     await prefs.remove(_userEmailKey);
+    await prefs.remove(_avatarUrlKey);
+    await prefs.remove(_rolesKey);
+    await prefs.remove(_preferencesKey);
   }
 }

lib/core/auth/auth_state.dart

@@ -1,18 +1,46 @@
 import 'package:freezed_annotation/freezed_annotation.dart';
 
+import 'permissions.dart';
+import 'user_preferences.dart';
+
 part 'auth_state.freezed.dart';
 
-/// Authentication state.
+/// Authentication state including user profile, roles, and preferences.
 @freezed
 sealed class AuthState with _$AuthState {
   const factory AuthState({
+    /// Whether user is authenticated.
     @Default(false) bool isAuthenticated,
+
+    /// OIDC access token.
     String? accessToken,
+
+    /// OIDC refresh token.
     String? refreshToken,
+
+    /// Token expiration time.
     DateTime? expiresAt,
+
+    /// Internal user ID (from core-api).
     String? userId,
+
+    /// Authentik user ID.
+    String? authentikId,
+
+    /// User display name.
     String? userName,
+
+    /// User email address.
     String? userEmail,
+
+    /// User avatar URL.
+    String? avatarUrl,
+
+    /// User's permission roles.
+    @Default([]) List<Role> roles,
+
+    /// User preferences.
+    UserPreferences? preferences,
   }) = _AuthState;
 
   const AuthState._();
@@ -23,4 +51,12 @@ sealed class AuthState with _$AuthState {
     // Consider expired if less than 1 minute remaining
     return DateTime.now().isAfter(expiresAt!.subtract(const Duration(minutes: 1)));
   }
+
+  /// Check if user has the specified permission.
+  bool hasPermission(Domain domain, Action action, {String category = 'general'}) {
+    return roles.hasPermission(domain, action, category: category);
+  }
+
+  /// Check if user is a global admin.
+  bool get isGlobalAdmin => roles.isGlobalAdmin;
 }

lib/core/auth/oidc_service.dart

@@ -0,0 +1,115 @@
+import 'package:flutter_appauth/flutter_appauth.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+import '../config/app_config.dart';
+
+part 'oidc_service.g.dart';
+
+/// OIDC token response containing access and refresh tokens.
+class OidcTokens {
+  const OidcTokens({
+    required this.accessToken,
+    required this.refreshToken,
+    required this.expiresAt,
+    this.idToken,
+  });
+
+  final String accessToken;
+  final String? refreshToken;
+  final DateTime expiresAt;
+  final String? idToken;
+}
+
+/// Service for OIDC authentication using flutter_appauth.
+///
+/// Handles the Authorization Code flow with PKCE for secure authentication
+/// against Authentik.
+class OidcService {
+  OidcService({FlutterAppAuth? appAuth}) : _appAuth = appAuth ?? const FlutterAppAuth();
+
+  final FlutterAppAuth _appAuth;
+
+  /// OIDC scopes to request.
+  static const _scopes = ['openid', 'profile', 'email', 'offline_access'];
+
+  /// Redirect URI for the app.
+  static String get _redirectUri => '${AppConfig.authRedirectScheme}://callback';
+
+  /// Start the authorization code flow.
+  ///
+  /// Opens a browser/webview for user to authenticate with Authentik,
+  /// then exchanges the authorization code for tokens.
+  ///
+  /// Throws [OidcException] if authentication fails.
+  Future<OidcTokens> signIn() async {
+    try {
+      final result = await _appAuth.authorizeAndExchangeCode(
+        AuthorizationTokenRequest(
+          AppConfig.authClientId,
+          _redirectUri,
+          discoveryUrl: AppConfig.authDiscoveryUrl,
+          scopes: _scopes,
+        ),
+      );
+
+      if (result.accessToken == null) {
+        throw OidcException('Authorization failed: no access token');
+      }
+
+      return OidcTokens(
+        accessToken: result.accessToken!,
+        refreshToken: result.refreshToken,
+        expiresAt: result.accessTokenExpirationDateTime ?? DateTime.now().add(const Duration(hours: 1)),
+        idToken: result.idToken,
+      );
+    } on Exception catch (e) {
+      throw OidcException('Authorization failed: $e');
+    }
+  }
+
+  /// Refresh the access token using a refresh token.
+  ///
+  /// Throws [OidcException] if refresh fails.
+  Future<OidcTokens> refreshToken(String refreshToken) async {
+    try {
+      final result = await _appAuth.token(
+        TokenRequest(
+          AppConfig.authClientId,
+          _redirectUri,
+          discoveryUrl: AppConfig.authDiscoveryUrl,
+          refreshToken: refreshToken,
+          scopes: _scopes,
+        ),
+      );
+
+      if (result.accessToken == null) {
+        throw OidcException('Token refresh failed: no access token');
+      }
+
+      return OidcTokens(
+        accessToken: result.accessToken!,
+        refreshToken: result.refreshToken ?? refreshToken,
+        expiresAt: result.accessTokenExpirationDateTime ?? DateTime.now().add(const Duration(hours: 1)),
+        idToken: result.idToken,
+      );
+    } on Exception catch (e) {
+      throw OidcException('Token refresh failed: $e');
+    }
+  }
+}
+
+/// Exception thrown when OIDC operations fail.
+class OidcException implements Exception {
+  const OidcException(this.message);
+
+  final String message;
+
+  @override
+  String toString() => 'OidcException: $message';
+}
+
+/// Provider for the OIDC service.
+@riverpod
+OidcService oidcService(Ref ref) {
+  return OidcService();
+}

lib/core/auth/permission_gate.dart

@@ -0,0 +1,110 @@
+import 'package:flutter/widgets.dart' hide Action;
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'auth_provider.dart';
+import 'permissions.dart';
+
+/// A widget that conditionally renders its child based on user permissions.
+///
+/// Example:
+/// ```dart
+/// PermissionGate(
+///   domain: Domain.controlRoom,
+///   action: Action.admin,
+///   child: DeleteButton(),
+///   fallback: Text('No permission'),
+/// )
+/// ```
+class PermissionGate extends ConsumerWidget {
+  const PermissionGate({
+    super.key,
+    required this.domain,
+    required this.action,
+    this.category = 'general',
+    required this.child,
+    this.fallback,
+  });
+
+  /// The domain required for this permission.
+  final Domain domain;
+
+  /// The action level required (viewer, user, editor, admin).
+  final Action action;
+
+  /// Optional category within the domain (defaults to 'general').
+  final String category;
+
+  /// Widget to show when user has permission.
+  final Widget child;
+
+  /// Widget to show when user lacks permission (defaults to empty).
+  final Widget? fallback;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final authState = ref.watch(authProvider);
+
+    final hasPermission = authState.maybeWhen(
+      data: (state) => state.hasPermission(domain, action, category: category),
+      orElse: () => false,
+    );
+
+    if (hasPermission) {
+      return child;
+    }
+
+    return fallback ?? const SizedBox.shrink();
+  }
+}
+
+/// A widget that shows its child only if the user is a global admin.
+class AdminGate extends ConsumerWidget {
+  const AdminGate({
+    super.key,
+    required this.child,
+    this.fallback,
+  });
+
+  /// Widget to show when user is admin.
+  final Widget child;
+
+  /// Widget to show when user is not admin (defaults to empty).
+  final Widget? fallback;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final authState = ref.watch(authProvider);
+
+    final isAdmin = authState.maybeWhen(
+      data: (state) => state.isGlobalAdmin,
+      orElse: () => false,
+    );
+
+    if (isAdmin) {
+      return child;
+    }
+
+    return fallback ?? const SizedBox.shrink();
+  }
+}
+
+/// Extension for checking permissions in code.
+extension PermissionCheck on WidgetRef {
+  /// Check if the current user has a specific permission.
+  bool hasPermission(Domain domain, Action action, {String category = 'general'}) {
+    final authState = read(authProvider);
+    return authState.maybeWhen(
+      data: (state) => state.hasPermission(domain, action, category: category),
+      orElse: () => false,
+    );
+  }
+
+  /// Check if the current user is a global admin.
+  bool get isGlobalAdmin {
+    final authState = read(authProvider);
+    return authState.maybeWhen(
+      data: (state) => state.isGlobalAdmin,
+      orElse: () => false,
+    );
+  }
+}

lib/core/auth/permissions.dart

@@ -0,0 +1,137 @@
+// Permission system for role-based access control.
+//
+// Roles follow the format: `domain.category:action`
+// - Domain: Feature area (control-room, media, etc.)
+// - Category: Sub-area within domain (default: general)
+// - Action: Permission level (viewer < user < editor < admin)
+
+/// Permission domains matching feature areas.
+enum Domain {
+  controlRoom('control-room'),
+  library('library'),
+  media('media'),
+  ai('ai'),
+  housekeeper('housekeeper'),
+  developer('developer'),
+  documents('documents'),
+  gaming('gaming'),
+  admin('admin');
+
+  const Domain(this.value);
+
+  /// The API string value for this domain.
+  final String value;
+
+  /// Parse a domain string from API response.
+  static Domain? fromString(String value) {
+    for (final domain in Domain.values) {
+      if (domain.value == value) return domain;
+    }
+    return null;
+  }
+}
+
+/// Permission actions in hierarchical order.
+///
+/// Higher actions imply lower ones:
+/// - admin implies editor, user, viewer
+/// - editor implies user, viewer
+/// - user implies viewer
+enum Action {
+  viewer(1),
+  user(2),
+  editor(3),
+  admin(4);
+
+  const Action(this.level);
+
+  /// Numeric level for comparison (higher = more permissions).
+  final int level;
+
+  /// Check if this action grants at least the required action.
+  bool grants(Action required) => level >= required.level;
+
+  /// Parse an action string from API response.
+  static Action? fromString(String value) {
+    for (final action in Action.values) {
+      if (action.name == value) return action;
+    }
+    return null;
+  }
+}
+
+/// A permission role assigned to a user.
+///
+/// Roles are parsed from the API format: `domain.category:action`
+class Role {
+  const Role({
+    required this.id,
+    required this.name,
+    required this.domain,
+    required this.category,
+    required this.action,
+  });
+
+  /// Unique role ID.
+  final String id;
+
+  /// Full role name (e.g., "control-room.general:admin").
+  final String name;
+
+  /// Permission domain.
+  final Domain domain;
+
+  /// Permission category (usually "general").
+  final String category;
+
+  /// Permission action level.
+  final Action action;
+
+  /// Check if this role grants access for the given domain and action.
+  ///
+  /// Global admin (`admin.general:admin`) grants access to everything.
+  /// Otherwise, domain and category must match, and action level must be sufficient.
+  bool grants(Domain domain, Action action, {String category = 'general'}) {
+    // Global admin override
+    if (this.domain == Domain.admin &&
+        this.category == 'general' &&
+        this.action == Action.admin) {
+      return true;
+    }
+
+    // Check domain and category match
+    if (this.domain != domain || this.category != category) {
+      return false;
+    }
+
+    // Check action hierarchy
+    return this.action.grants(action);
+  }
+
+  @override
+  String toString() => 'Role($name)';
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is Role && runtimeType == other.runtimeType && id == other.id;
+
+  @override
+  int get hashCode => id.hashCode;
+}
+
+/// Extension for checking permissions on a list of roles.
+extension RoleListPermissions on List<Role> {
+  /// Check if any role grants the required permission.
+  bool hasPermission(Domain domain, Action action, {String category = 'general'}) {
+    return any((role) => role.grants(domain, action, category: category));
+  }
+
+  /// Check if any role grants any of the required permissions.
+  bool hasAnyPermission(List<(Domain, Action)> permissions) {
+    return permissions.any((p) => hasPermission(p.$1, p.$2));
+  }
+
+  /// Check if user is a global admin.
+  bool get isGlobalAdmin => hasPermission(Domain.admin, Action.admin);
+}

lib/core/auth/user_preferences.dart

@@ -0,0 +1,22 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'user_preferences.freezed.dart';
+part 'user_preferences.g.dart';
+
+/// User preferences synced from core-api.
+@freezed
+sealed class UserPreferences with _$UserPreferences {
+  const factory UserPreferences({
+    /// Theme preference: system, light, dark
+    @Default('system') String theme,
+
+    /// Default room for housekeeping
+    @Default('front-hall') String defaultRoom,
+
+    /// Extended preferences as JSON
+    @Default({}) Map<String, dynamic> preferencesJson,
+  }) = _UserPreferences;
+
+  factory UserPreferences.fromJson(Map<String, dynamic> json) =>
+      _$UserPreferencesFromJson(json);
+}

lib/features/front_hall/data/models/system_stats_model.dart

@@ -0,0 +1,91 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'system_stats_model.freezed.dart';
+part 'system_stats_model.g.dart';
+
+/// System statistics response from Core API.
+@freezed
+sealed class SystemStats with _$SystemStats {
+  const factory SystemStats({
+    required CpuStats cpu,
+    required MemoryStats memory,
+    required List<DiskStats> disks,
+    required NetworkStats network,
+    required GpuStats gpu,
+    required String hostname,
+    @JsonKey(name: 'queried_at') required DateTime queriedAt,
+  }) = _SystemStats;
+
+  factory SystemStats.fromJson(Map<String, dynamic> json) =>
+      _$SystemStatsFromJson(json);
+}
+
+@freezed
+sealed class CpuStats with _$CpuStats {
+  const factory CpuStats({
+    @JsonKey(name: 'usage_percent') required double usagePercent,
+    required int cores,
+    @JsonKey(name: 'load_1m') double? load1m,
+    @JsonKey(name: 'load_5m') double? load5m,
+    @JsonKey(name: 'load_15m') double? load15m,
+  }) = _CpuStats;
+
+  factory CpuStats.fromJson(Map<String, dynamic> json) =>
+      _$CpuStatsFromJson(json);
+}
+
+@freezed
+sealed class MemoryStats with _$MemoryStats {
+  const factory MemoryStats({
+    @JsonKey(name: 'usage_percent') required double usagePercent,
+    @JsonKey(name: 'total_bytes') required int totalBytes,
+    @JsonKey(name: 'used_bytes') required int usedBytes,
+    @JsonKey(name: 'available_bytes') required int availableBytes,
+  }) = _MemoryStats;
+
+  factory MemoryStats.fromJson(Map<String, dynamic> json) =>
+      _$MemoryStatsFromJson(json);
+}
+
+@freezed
+sealed class DiskStats with _$DiskStats {
+  const factory DiskStats({
+    @JsonKey(name: 'mount_point') required String mountPoint,
+    required String device,
+    required String fstype,
+    @JsonKey(name: 'usage_percent') required double usagePercent,
+    @JsonKey(name: 'total_bytes') required int totalBytes,
+    @JsonKey(name: 'used_bytes') required int usedBytes,
+    @JsonKey(name: 'free_bytes') required int freeBytes,
+  }) = _DiskStats;
+
+  factory DiskStats.fromJson(Map<String, dynamic> json) =>
+      _$DiskStatsFromJson(json);
+}
+
+@freezed
+sealed class NetworkStats with _$NetworkStats {
+  const factory NetworkStats({
+    @JsonKey(name: 'bytes_sent') required int bytesSent,
+    @JsonKey(name: 'bytes_recv') required int bytesRecv,
+    @JsonKey(name: 'bytes_total') required int bytesTotal,
+  }) = _NetworkStats;
+
+  factory NetworkStats.fromJson(Map<String, dynamic> json) =>
+      _$NetworkStatsFromJson(json);
+}
+
+@freezed
+sealed class GpuStats with _$GpuStats {
+  const factory GpuStats({
+    required bool available,
+    String? name,
+    @JsonKey(name: 'usage_percent') double? usagePercent,
+    @JsonKey(name: 'total_bytes') int? totalBytes,
+    @JsonKey(name: 'used_bytes') int? usedBytes,
+    @JsonKey(name: 'free_bytes') int? freeBytes,
+  }) = _GpuStats;
+
+  factory GpuStats.fromJson(Map<String, dynamic> json) =>
+      _$GpuStatsFromJson(json);
+}

lib/features/front_hall/presentation/providers/system_stats_provider.dart

@@ -0,0 +1,14 @@
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import 'package:tatlock_ui/core/api/api_client.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/system_stats_model.dart';
+
+part 'system_stats_provider.g.dart';
+
+/// Fetches system stats from Core API.
+@riverpod
+Future<SystemStats> systemStats(Ref ref) async {
+  final dio = ref.watch(coreApiClientProvider);
+
+  final response = await dio.get('/tools/system/stats');
+  return SystemStats.fromJson(response.data as Map<String, dynamic>);
+}

lib/features/front_hall/presentation/widgets/dashboard_content.dart

@@ -1,16 +1,46 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/system_stats_model.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/system_stats_provider.dart';
+import 'package:tatlock_ui/shared/theme/stoplight_colors.dart';
 import 'package:tatlock_ui/shared/widgets/widgets.dart';
 import 'package:tatlock_ui/version.g.dart';
 
 /// Dashboard content shown in Front Hall when mode is dashboard.
 ///
 /// Displays system stats with gauges, weather, air quality, and version info.
-class DashboardContent extends StatelessWidget {
+/// Auto-refreshes system stats every 30 seconds.
+class DashboardContent extends ConsumerStatefulWidget {
   const DashboardContent({super.key});
 
+  @override
+  ConsumerState<DashboardContent> createState() => _DashboardContentState();
+}
+
+class _DashboardContentState extends ConsumerState<DashboardContent> {
+  Timer? _refreshTimer;
+
+  @override
+  void initState() {
+    super.initState();
+    _refreshTimer = Timer.periodic(
+      const Duration(seconds: 30),
+      (_) => ref.invalidate(systemStatsProvider),
+    );
+  }
+
+  @override
+  void dispose() {
+    _refreshTimer?.cancel();
+    super.dispose();
+  }
+
   @override
   Widget build(BuildContext context) {
     final colorScheme = Theme.of(context).colorScheme;
+    final systemStatsAsync = ref.watch(systemStatsProvider);
 
     return ListView(
       padding: const EdgeInsets.all(16),
@@ -54,37 +84,33 @@ class DashboardContent extends StatelessWidget {
         // System Stats - Gauges
         _SectionHeader(title: 'System Stats', icon: Icons.monitor_heart),
         const SizedBox(height: 8),
-        Card(
+        systemStatsAsync.when(
-          child: Padding(
+          data: (stats) => _SystemStatsCard(stats: stats),
-            padding: const EdgeInsets.all(16),
+          loading: () => const Card(
-            child: GaugeRow(
+            child: Padding(
-              gaugeSize: 90,
+              padding: EdgeInsets.all(32),
-              gauges: [
+              child: Center(child: CircularProgressIndicator()),
-                GaugeData(
+            ),
-                  value: 0.35,
+          ),
-                  label: 'CPU',
+          error: (error, _) => Card(
-                  icon: Icons.memory,
+            child: Padding(
-                  color: colorScheme.primary,
+              padding: const EdgeInsets.all(16),
-                ),
+              child: Row(
-                GaugeData(
+                children: [
-                  value: 0.62,
+                  Icon(Icons.error_outline, color: colorScheme.error),
-                  label: 'Memory',
+                  const SizedBox(width: 12),
-                  icon: Icons.storage,
+                  Expanded(
-                  color: colorScheme.secondary,
+                    child: Text(
-                ),
+                      'Failed to load system stats',
-                GaugeData(
+                      style: TextStyle(color: colorScheme.error),
-                  value: 0.78,
+                    ),
-                  label: 'Disk',
+                  ),
-                  icon: Icons.disc_full,
+                  IconButton(
-                  color: colorScheme.tertiary,
+                    icon: const Icon(Icons.refresh),
-                ),
+                    onPressed: () => ref.invalidate(systemStatsProvider),
-                GaugeData(
+                  ),
-                  value: 0.12,
+                ],
-                  label: 'Network',
+              ),
-                  icon: Icons.wifi,
-                  color: Colors.teal,
-                ),
-              ],
             ),
           ),
         ),
@@ -165,3 +191,68 @@ class _SectionHeader extends StatelessWidget {
     );
   }
 }
+
+/// Card displaying system stats with gauges.
+class _SystemStatsCard extends StatelessWidget {
+  const _SystemStatsCard({required this.stats});
+
+  final SystemStats stats;
+
+  @override
+  Widget build(BuildContext context) {
+    // Build gauges list: CPU, Memory, GPU (if available), then all disks
+    final gauges = <GaugeData>[
+      GaugeData(
+        value: stats.cpu.usagePercent / 100,
+        label: 'CPU',
+        icon: Icons.memory,
+        color: StoplightColors.forPercent(stats.cpu.usagePercent),
+      ),
+      GaugeData(
+        value: stats.memory.usagePercent / 100,
+        label: 'RAM',
+        icon: Icons.storage,
+        color: StoplightColors.forPercent(stats.memory.usagePercent),
+      ),
+      if (stats.gpu.available && stats.gpu.usagePercent != null)
+        GaugeData(
+          value: stats.gpu.usagePercent! / 100,
+          label: 'VRAM',
+          icon: Icons.videocam,
+          color: StoplightColors.forPercent(stats.gpu.usagePercent!),
+        ),
+      // Add a gauge for each disk
+      ...stats.disks.map(
+        (disk) => GaugeData(
+          value: disk.usagePercent / 100,
+          label: _formatDiskLabel(disk),
+          icon: Icons.disc_full,
+          color: StoplightColors.forPercent(disk.usagePercent),
+        ),
+      ),
+    ];
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(24),
+        child: GaugeRow(
+          gaugeSize: 120,
+          gauges: gauges,
+        ),
+      ),
+    );
+  }
+
+  /// Formats disk label from mount point.
+  String _formatDiskLabel(DiskStats disk) {
+    final mount = disk.mountPoint;
+    if (mount == '/') return 'Root';
+    if (mount == '/hostfs') return 'Host';
+    if (mount.startsWith('/hostfs/')) return mount.substring(8);
+    if (mount.startsWith('/mnt/')) return mount.substring(5);
+    if (mount.startsWith('/media/')) return mount.substring(7);
+    // Return last path segment
+    final parts = mount.split('/');
+    return parts.isNotEmpty ? parts.last : mount;
+  }
+}

lib/routing/app_router.dart

@@ -1,6 +1,10 @@
+import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 import 'package:riverpod_annotation/riverpod_annotation.dart';
+import 'package:tatlock_ui/core/auth/auth_provider.dart';
+import 'package:tatlock_ui/core/config/app_config.dart';
 import 'package:tatlock_ui/features/control_room/router.dart';
 import 'package:tatlock_ui/features/front_hall/presentation/pages/front_hall_page.dart';
 import 'package:tatlock_ui/features/security/router.dart';
@@ -13,15 +17,46 @@ abstract class AppRoutes {
   static const frontHall = '/';
   static const parlor = '/parlor';
   static const settings = '/settings';
+  static const login = '/login';
 }
 
 /// Provides the GoRouter instance.
 @riverpod
 GoRouter appRouter(Ref ref) {
+  final authState = ref.watch(authProvider);
+
   return GoRouter(
     initialLocation: AppRoutes.frontHall,
     debugLogDiagnostics: true,
+    redirect: (context, state) {
+      // No auth required in LAN mode
+      if (!AppConfig.requiresAuth) {
+        return null;
+      }
+
+      final isAuthenticated = authState.value?.isAuthenticated ?? false;
+      final isLoginRoute = state.matchedLocation == AppRoutes.login;
+
+      // If not authenticated, redirect to login (except if already on login)
+      if (!isAuthenticated && !isLoginRoute) {
+        return AppRoutes.login;
+      }
+
+      // If authenticated and on login page, redirect to home
+      if (isAuthenticated && isLoginRoute) {
+        return AppRoutes.frontHall;
+      }
+
+      return null;
+    },
     routes: [
+      // Login route (outside shell - no app scaffold)
+      GoRoute(
+        path: AppRoutes.login,
+        name: 'login',
+        builder: (context, state) => const _LoginPage(),
+      ),
+      // Main app routes (inside shell with app scaffold)
       ShellRoute(
         builder: (context, state, child) => AppScaffold(child: child),
         routes: [
@@ -84,3 +119,156 @@ class _PlaceholderPage extends StatelessWidget {
     );
   }
 }
+
+/// Login page displayed when user is not authenticated.
+class _LoginPage extends ConsumerWidget {
+  const _LoginPage();
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final authAsync = ref.watch(authProvider);
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Scaffold(
+      body: Center(
+        child: ConstrainedBox(
+          constraints: const BoxConstraints(maxWidth: 400),
+          child: Card(
+            child: Padding(
+              padding: const EdgeInsets.all(32),
+              child: Column(
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  Icon(
+                    Icons.home_work_outlined,
+                    size: 64,
+                    color: colorScheme.primary,
+                  ),
+                  const SizedBox(height: 24),
+                  Text(
+                    'Tatlock Estate',
+                    style: Theme.of(context).textTheme.headlineMedium?.copyWith(
+                          fontWeight: FontWeight.w600,
+                        ),
+                  ),
+                  const SizedBox(height: 8),
+                  Text(
+                    'Sign in to access the estate management system',
+                    style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                    textAlign: TextAlign.center,
+                  ),
+                  const SizedBox(height: 32),
+                  authAsync.when(
+                    data: (_) => _buildSignInContent(context, ref),
+                    loading: () => const Column(
+                      children: [
+                        SizedBox(
+                          width: 24,
+                          height: 24,
+                          child: CircularProgressIndicator(strokeWidth: 2),
+                        ),
+                        SizedBox(height: 16),
+                        Text('Checking authentication...'),
+                      ],
+                    ),
+                    error: (error, _) => _buildErrorContent(context, ref, error),
+                  ),
+                ],
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+
+  Widget _buildSignInContent(BuildContext context, WidgetRef ref) {
+    if (kIsWeb) {
+      // Web: User needs to access via authenticated proxy
+      return Column(
+        children: [
+          Text(
+            'Please access Tatlock via the authenticated URL.\n'
+            'If you see this page, the proxy authentication may not be configured.',
+            style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                  color: Theme.of(context).colorScheme.onSurfaceVariant,
+                ),
+            textAlign: TextAlign.center,
+          ),
+          const SizedBox(height: 16),
+          OutlinedButton.icon(
+            onPressed: () => ref.read(authProvider.notifier).signIn(),
+            icon: const Icon(Icons.refresh),
+            label: const Text('Retry'),
+            style: OutlinedButton.styleFrom(
+              minimumSize: const Size(double.infinity, 48),
+            ),
+          ),
+        ],
+      );
+    }
+
+    // Mobile: Show sign in button
+    return FilledButton.icon(
+      onPressed: () => ref.read(authProvider.notifier).signIn(),
+      icon: const Icon(Icons.login),
+      label: const Text('Sign in with Authentik'),
+      style: FilledButton.styleFrom(
+        minimumSize: const Size(double.infinity, 48),
+      ),
+    );
+  }
+
+  Widget _buildErrorContent(BuildContext context, WidgetRef ref, Object error) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Column(
+      children: [
+        Container(
+          padding: const EdgeInsets.all(12),
+          decoration: BoxDecoration(
+            color: colorScheme.errorContainer,
+            borderRadius: BorderRadius.circular(8),
+          ),
+          child: Row(
+            children: [
+              Icon(Icons.error_outline, color: colorScheme.onErrorContainer),
+              const SizedBox(width: 12),
+              Expanded(
+                child: Text(
+                  _formatError(error),
+                  style: TextStyle(color: colorScheme.onErrorContainer),
+                ),
+              ),
+            ],
+          ),
+        ),
+        const SizedBox(height: 16),
+        OutlinedButton.icon(
+          onPressed: () => ref.read(authProvider.notifier).signIn(),
+          icon: const Icon(Icons.refresh),
+          label: const Text('Try again'),
+          style: OutlinedButton.styleFrom(
+            minimumSize: const Size(double.infinity, 48),
+          ),
+        ),
+      ],
+    );
+  }
+
+  String _formatError(Object error) {
+    final message = error.toString();
+    if (message.contains('user_cancelled')) {
+      return 'Sign in was cancelled';
+    }
+    if (message.contains('network')) {
+      return 'Network error. Please check your connection.';
+    }
+    if (message.contains('authenticated URL')) {
+      return 'Not authenticated - please access via the authenticated URL';
+    }
+    return 'Authentication failed. Please try again.';
+  }
+}

lib/shared/theme/stoplight_colors.dart

@@ -0,0 +1,37 @@
+import 'package:flutter/material.dart';
+
+/// Pastel stoplight colors for consistent status indication across the app.
+///
+/// Use these colors for any green/yellow/red status flows:
+/// - System stats (CPU, RAM, disk usage)
+/// - Air quality levels
+/// - Container health status
+/// - Any other threshold-based indicators
+abstract final class StoplightColors {
+  /// Good/healthy/low usage (0-50%)
+  static const green = Color(0xFF81C784);
+
+  /// Warning/moderate/medium usage (51-75%)
+  static const orange = Color(0xFFFFB74D);
+
+  /// Critical/unhealthy/high usage (76-100%)
+  static const red = Color(0xFFE57373);
+
+  /// Returns appropriate color based on percentage (0-100).
+  ///
+  /// - ≤50%: green
+  /// - 51-75%: orange
+  /// - >75%: red
+  static Color forPercent(double percent) {
+    if (percent <= 50) return green;
+    if (percent <= 75) return orange;
+    return red;
+  }
+
+  /// Returns appropriate color based on value (0.0-1.0).
+  ///
+  /// - ≤0.5: green
+  /// - 0.51-0.75: orange
+  /// - >0.75: red
+  static Color forValue(double value) => forPercent(value * 100);
+}

lib/shared/widgets/air_quality_widget.dart

@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:tatlock_ui/shared/theme/stoplight_colors.dart';
 
 /// Air Quality Index widget displaying current AQI.
 ///
@@ -203,28 +204,28 @@ enum AqiLevel {
   good(
     label: 'Good',
     description: 'Air quality is satisfactory',
-    color: Colors.green,
+    color: StoplightColors.green,
     minIndex: 0,
     maxIndex: 50,
   ),
   moderate(
     label: 'Moderate',
     description: 'Acceptable for most people',
-    color: Colors.amber,
+    color: StoplightColors.orange,
     minIndex: 51,
     maxIndex: 100,
   ),
   unhealthySensitive(
     label: 'Unhealthy for Sensitive',
     description: 'May affect sensitive groups',
-    color: Colors.orange,
+    color: StoplightColors.orange,
     minIndex: 101,
     maxIndex: 150,
   ),
   unhealthy(
     label: 'Unhealthy',
     description: 'Health effects for everyone',
-    color: Colors.red,
+    color: StoplightColors.red,
     minIndex: 151,
     maxIndex: 200,
   ),

lib/shared/widgets/gauge_widget.dart

@@ -2,7 +2,7 @@ import 'dart:math' as math;
 
 import 'package:flutter/material.dart';
 
-/// A circular gauge widget for displaying percentage values.
+/// A speedometer-style gauge widget for displaying percentage values.
 ///
 /// Commonly used for system stats like CPU, Memory, Disk usage.
 class GaugeWidget extends StatelessWidget {
@@ -52,15 +52,19 @@ class GaugeWidget extends StatelessWidget {
     // Clamp value between 0 and 1
     final clampedValue = value.clamp(0.0, 1.0);
 
+    // Height is smaller since we only draw half circle
+    final gaugeHeight = size * 0.6;
+    final iconSpace = icon != null ? size * 0.36 : 0.0;
+
     return SizedBox(
       width: size,
-      height: size + 24, // Extra space for label
+      height: gaugeHeight + 32 + iconSpace, // Space for label + icon
       child: Column(
         mainAxisSize: MainAxisSize.min,
         children: [
           SizedBox(
             width: size,
-            height: size,
+            height: gaugeHeight,
             child: CustomPaint(
               painter: _GaugePainter(
                 value: clampedValue,
@@ -68,32 +72,21 @@ class GaugeWidget extends StatelessWidget {
                 backgroundColor: effectiveBackgroundColor,
                 strokeWidth: strokeWidth,
               ),
-              child: Center(
+              child: Align(
-                child: Column(
+                alignment: const Alignment(0, 0.6),
-                  mainAxisSize: MainAxisSize.min,
+                child: showPercentage
-                  children: [
+                    ? Text(
-                    if (icon != null) ...[
-                      Icon(
-                        icon,
-                        size: size * 0.2,
-                        color: effectiveColor,
-                      ),
-                      SizedBox(height: size * 0.02),
-                    ],
-                    if (showPercentage)
-                      Text(
                         '${(clampedValue * 100).round()}%',
                         style: Theme.of(context).textTheme.titleLarge?.copyWith(
                               fontWeight: FontWeight.bold,
-                              fontSize: size * 0.18,
+                              fontSize: size * 0.2,
                             ),
-                      ),
+                      )
-                  ],
+                    : const SizedBox.shrink(),
-                ),
               ),
             ),
           ),
-          const SizedBox(height: 8),
+          const SizedBox(height: 4),
           Text(
             label,
             style: Theme.of(context).textTheme.bodySmall?.copyWith(
@@ -103,6 +96,14 @@ class GaugeWidget extends StatelessWidget {
             maxLines: 1,
             overflow: TextOverflow.ellipsis,
           ),
+          if (icon != null) ...[
+            const SizedBox(height: 8),
+            Icon(
+              icon,
+              size: size * 0.28,
+              color: effectiveColor,
+            ),
+          ],
         ],
       ),
     );
@@ -124,12 +125,13 @@ class _GaugePainter extends CustomPainter {
 
   @override
   void paint(Canvas canvas, Size size) {
-    final center = Offset(size.width / 2, size.height / 2);
+    // Center at bottom of widget for speedometer style
+    final center = Offset(size.width / 2, size.height);
     final radius = (size.width - strokeWidth) / 2;
 
-    // Start from top (-90 degrees) and sweep clockwise
+    // Speedometer arc: starts from left (180°) and sweeps 180° to right
-    const startAngle = -math.pi / 2;
+    const startAngle = math.pi; // 180 degrees (left side)
-    const sweepAngle = 2 * math.pi;
+    const sweepAngle = math.pi; // 180 degrees sweep (semicircle)
 
     // Background arc
     final backgroundPaint = Paint()
@@ -187,7 +189,7 @@ class GaugeRow extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return Wrap(
-      spacing: 16,
+      spacing: 24,
       runSpacing: 16,
       alignment: WrapAlignment.center,
       children: gauges
@@ -196,6 +198,7 @@ class GaugeRow extends StatelessWidget {
               value: data.value,
               label: data.label,
               size: gaugeSize,
+              strokeWidth: gaugeSize * 0.1,
               color: data.color,
               icon: data.icon,
             ),

lib/shared/widgets/weather_widget.dart

@@ -36,15 +36,15 @@ class WeatherWidget extends StatelessWidget {
             Row(
               children: [
                 Icon(
-                  Icons.location_on,
+                  Icons.wb_sunny_outlined,
-                  size: 16,
+                  size: 20,
                   color: colorScheme.onSurfaceVariant,
                 ),
-                const SizedBox(width: 4),
+                const SizedBox(width: 8),
                 Expanded(
                   child: Text(
                     weather.location,
-                    style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                    style: Theme.of(context).textTheme.titleSmall?.copyWith(
                           color: colorScheme.onSurfaceVariant,
                         ),
                     maxLines: 1,
@@ -53,18 +53,36 @@ class WeatherWidget extends StatelessWidget {
                 ),
               ],
             ),
-            const SizedBox(height: 12),
+            const SizedBox(height: 16),
 
-            // Main weather display
+            // Main weather display (matching AQI layout)
             Row(
-              crossAxisAlignment: CrossAxisAlignment.start,
               children: [
-                Icon(
+                // Weather icon in box (like AQI number box)
-                  weather.icon,
+                Container(
-                  size: 48,
+                  width: 64,
-                  color: weather.iconColor ?? colorScheme.primary,
+                  height: 64,
+                  decoration: BoxDecoration(
+                    color: (weather.iconColor ?? colorScheme.primary)
+                        .withValues(alpha: 0.15),
+                    borderRadius: BorderRadius.circular(12),
+                    border: Border.all(
+                      color: (weather.iconColor ?? colorScheme.primary)
+                          .withValues(alpha: 0.3),
+                      width: 2,
+                    ),
+                  ),
+                  child: Center(
+                    child: Icon(
+                      weather.icon,
+                      size: 32,
+                      color: weather.iconColor ?? colorScheme.primary,
+                    ),
+                  ),
                 ),
-                const SizedBox(width: 12),
+                const SizedBox(width: 16),
+
+                // Temperature and condition
                 Expanded(
                   child: Column(
                     crossAxisAlignment: CrossAxisAlignment.start,
@@ -72,15 +90,18 @@ class WeatherWidget extends StatelessWidget {
                       Text(
                         '${weather.temperature.round()}°${weather.unit.symbol}',
                         style:
-                            Theme.of(context).textTheme.headlineMedium?.copyWith(
+                            Theme.of(context).textTheme.titleMedium?.copyWith(
-                                  fontWeight: FontWeight.bold,
+                                  fontWeight: FontWeight.w600,
                                 ),
                       ),
+                      const SizedBox(height: 4),
                       Text(
                         weather.condition,
-                        style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                        style: Theme.of(context).textTheme.bodySmall?.copyWith(
                               color: colorScheme.onSurfaceVariant,
                             ),
+                        maxLines: 2,
+                        overflow: TextOverflow.ellipsis,
                       ),
                     ],
                   ),
@@ -90,36 +111,27 @@ class WeatherWidget extends StatelessWidget {
 
             // Details
             if (weather.humidity != null || weather.windSpeed != null) ...[
-              const SizedBox(height: 12),
+              const SizedBox(height: 16),
               const Divider(height: 1),
               const SizedBox(height: 12),
-              Row(
+              Wrap(
+                spacing: 16,
+                runSpacing: 8,
                 children: [
                   if (weather.humidity != null)
-                    Expanded(
+                    _DetailChip(
-                      child: _DetailItem(
+                      label: 'Humidity',
-                        icon: Icons.water_drop_outlined,
+                      value: '${weather.humidity}%',
-                        label: 'Humidity',
-                        value: '${weather.humidity}%',
-                      ),
                     ),
                   if (weather.windSpeed != null)
-                    Expanded(
+                    _DetailChip(
-                      child: _DetailItem(
+                      label: 'Wind',
-                        icon: Icons.air,
+                      value: '${weather.windSpeed!.round()} ${weather.windUnit}',
-                        label: 'Wind',
-                        value:
-                            '${weather.windSpeed!.round()} ${weather.windUnit}',
-                      ),
                     ),
                   if (weather.feelsLike != null)
-                    Expanded(
+                    _DetailChip(
-                      child: _DetailItem(
+                      label: 'Feels',
-                        icon: Icons.thermostat,
+                      value: '${weather.feelsLike!.round()}°${weather.unit.symbol}',
-                        label: 'Feels like',
-                        value:
-                            '${weather.feelsLike!.round()}°${weather.unit.symbol}',
-                      ),
                     ),
                 ],
               ),
@@ -160,14 +172,12 @@ class WeatherWidget extends StatelessWidget {
   }
 }
 
-class _DetailItem extends StatelessWidget {
+class _DetailChip extends StatelessWidget {
-  const _DetailItem({
+  const _DetailChip({
-    required this.icon,
     required this.label,
     required this.value,
   });
 
-  final IconData icon;
   final String label;
   final String value;
 
@@ -178,29 +188,18 @@ class _DetailItem extends StatelessWidget {
     return Row(
       mainAxisSize: MainAxisSize.min,
       children: [
-        Icon(
+        Text(
-          icon,
+          label,
-          size: 16,
+          style: Theme.of(context).textTheme.labelSmall?.copyWith(
-          color: colorScheme.onSurfaceVariant,
+                color: colorScheme.outline,
+              ),
         ),
         const SizedBox(width: 4),
-        Column(
+        Text(
-          crossAxisAlignment: CrossAxisAlignment.start,
+          value,
-          children: [
+          style: Theme.of(context).textTheme.bodySmall?.copyWith(
-            Text(
+                fontWeight: FontWeight.w500,
-              value,
+              ),
-              style: Theme.of(context).textTheme.bodySmall?.copyWith(
-                    fontWeight: FontWeight.w600,
-                  ),
-            ),
-            Text(
-              label,
-              style: Theme.of(context).textTheme.labelSmall?.copyWith(
-                    color: colorScheme.outline,
-                    fontSize: 10,
-                  ),
-            ),
-          ],
         ),
       ],
     );

pubspec.yaml

@@ -16,7 +16,7 @@ publish_to: 'none' # Remove this line if you wish to publish to pub.dev
 # https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 # In Windows, build-name is used as the major, minor, and patch parts
 # of the product and file versions while build-number is used as the build suffix.
-version: 0.3.3+1
+version: 1.0.2+1
 
 environment:
   sdk: ^3.10.4
@@ -50,6 +50,9 @@ dependencies:
   # Storage
   shared_preferences: ^2.3.3
 
+  # Authentication (OIDC/OAuth2)
+  flutter_appauth: ^8.0.0
+
   # UI
   flex_color_scheme: ^8.1.0
   flutter_adaptive_scaffold: ^0.3.1
@@ -64,6 +67,7 @@ dependencies:
   url_launcher: ^6.3.1
   flutter_code_editor: ^0.3.5
   highlight: ^0.7.0
+  dio_web_adapter: ^2.1.1
 
 dev_dependencies:
   flutter_test:

test/core/auth/auth_state_test.dart

@@ -0,0 +1,280 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tatlock_ui/core/auth/auth_state.dart';
+import 'package:tatlock_ui/core/auth/permissions.dart';
+import 'package:tatlock_ui/core/auth/user_preferences.dart';
+
+void main() {
+  group('AuthState', () {
+    group('default constructor', () {
+      test('creates unauthenticated state by default', () {
+        const state = AuthState();
+
+        expect(state.isAuthenticated, isFalse);
+        expect(state.accessToken, isNull);
+        expect(state.refreshToken, isNull);
+        expect(state.expiresAt, isNull);
+        expect(state.userId, isNull);
+        expect(state.userName, isNull);
+        expect(state.userEmail, isNull);
+        expect(state.roles, isEmpty);
+        expect(state.preferences, isNull);
+      });
+    });
+
+    group('authenticated state', () {
+      test('stores all user data', () {
+        final expiresAt = DateTime.now().add(const Duration(hours: 1));
+        const preferences = UserPreferences(
+          theme: 'dark',
+          defaultRoom: 'kitchen',
+        );
+
+        final state = AuthState(
+          isAuthenticated: true,
+          accessToken: 'access_token',
+          refreshToken: 'refresh_token',
+          expiresAt: expiresAt,
+          userId: 'user-123',
+          authentikId: 'authentik-456',
+          userName: 'Test User',
+          userEmail: 'test@example.com',
+          avatarUrl: 'https://example.com/avatar.jpg',
+          roles: const [
+            Role(
+              id: '1',
+              name: 'admin.general:admin',
+              domain: Domain.admin,
+              category: 'general',
+              action: Action.admin,
+            ),
+          ],
+          preferences: preferences,
+        );
+
+        expect(state.isAuthenticated, isTrue);
+        expect(state.accessToken, equals('access_token'));
+        expect(state.refreshToken, equals('refresh_token'));
+        expect(state.expiresAt, equals(expiresAt));
+        expect(state.userId, equals('user-123'));
+        expect(state.authentikId, equals('authentik-456'));
+        expect(state.userName, equals('Test User'));
+        expect(state.userEmail, equals('test@example.com'));
+        expect(state.avatarUrl, equals('https://example.com/avatar.jpg'));
+        expect(state.roles.length, equals(1));
+        expect(state.preferences?.theme, equals('dark'));
+      });
+    });
+
+    group('isTokenExpired', () {
+      test('returns true when expiresAt is null', () {
+        const state = AuthState(isAuthenticated: true);
+
+        expect(state.isTokenExpired, isTrue);
+      });
+
+      test('returns true when token is expired', () {
+        final expiredTime = DateTime.now().subtract(const Duration(hours: 1));
+        final state = AuthState(
+          isAuthenticated: true,
+          expiresAt: expiredTime,
+        );
+
+        expect(state.isTokenExpired, isTrue);
+      });
+
+      test('returns true when token expires within 1 minute', () {
+        final soonExpires = DateTime.now().add(const Duration(seconds: 30));
+        final state = AuthState(
+          isAuthenticated: true,
+          expiresAt: soonExpires,
+        );
+
+        expect(state.isTokenExpired, isTrue);
+      });
+
+      test('returns false when token is valid', () {
+        final futureExpires = DateTime.now().add(const Duration(hours: 1));
+        final state = AuthState(
+          isAuthenticated: true,
+          expiresAt: futureExpires,
+        );
+
+        expect(state.isTokenExpired, isFalse);
+      });
+    });
+
+    group('hasPermission', () {
+      test('returns true when role grants permission', () {
+        const state = AuthState(
+          isAuthenticated: true,
+          roles: [
+            Role(
+              id: '1',
+              name: 'control-room.general:admin',
+              domain: Domain.controlRoom,
+              category: 'general',
+              action: Action.admin,
+            ),
+          ],
+        );
+
+        expect(state.hasPermission(Domain.controlRoom, Action.admin), isTrue);
+        expect(state.hasPermission(Domain.controlRoom, Action.viewer), isTrue);
+      });
+
+      test('returns false when no role grants permission', () {
+        const state = AuthState(
+          isAuthenticated: true,
+          roles: [
+            Role(
+              id: '1',
+              name: 'media.general:viewer',
+              domain: Domain.media,
+              category: 'general',
+              action: Action.viewer,
+            ),
+          ],
+        );
+
+        expect(state.hasPermission(Domain.controlRoom, Action.viewer), isFalse);
+        expect(state.hasPermission(Domain.media, Action.admin), isFalse);
+      });
+
+      test('respects category parameter', () {
+        const state = AuthState(
+          isAuthenticated: true,
+          roles: [
+            Role(
+              id: '1',
+              name: 'control-room.servers:admin',
+              domain: Domain.controlRoom,
+              category: 'servers',
+              action: Action.admin,
+            ),
+          ],
+        );
+
+        expect(
+          state.hasPermission(
+            Domain.controlRoom,
+            Action.admin,
+            category: 'servers',
+          ),
+          isTrue,
+        );
+        expect(
+          state.hasPermission(
+            Domain.controlRoom,
+            Action.admin,
+            category: 'general',
+          ),
+          isFalse,
+        );
+      });
+
+      test('returns false for empty roles list', () {
+        const state = AuthState(isAuthenticated: true, roles: []);
+
+        expect(state.hasPermission(Domain.controlRoom, Action.viewer), isFalse);
+      });
+    });
+
+    group('isGlobalAdmin', () {
+      test('returns true when user has admin.general:admin role', () {
+        const state = AuthState(
+          isAuthenticated: true,
+          roles: [
+            Role(
+              id: '1',
+              name: 'admin.general:admin',
+              domain: Domain.admin,
+              category: 'general',
+              action: Action.admin,
+            ),
+          ],
+        );
+
+        expect(state.isGlobalAdmin, isTrue);
+      });
+
+      test('returns false when user lacks admin role', () {
+        const state = AuthState(
+          isAuthenticated: true,
+          roles: [
+            Role(
+              id: '1',
+              name: 'control-room.general:admin',
+              domain: Domain.controlRoom,
+              category: 'general',
+              action: Action.admin,
+            ),
+          ],
+        );
+
+        expect(state.isGlobalAdmin, isFalse);
+      });
+
+      test('returns false for empty roles list', () {
+        const state = AuthState(isAuthenticated: true, roles: []);
+
+        expect(state.isGlobalAdmin, isFalse);
+      });
+    });
+
+    group('copyWith', () {
+      test('creates a copy with modified values', () {
+        const original = AuthState(
+          isAuthenticated: true,
+          accessToken: 'old_token',
+          userName: 'Original User',
+        );
+
+        final updated = original.copyWith(
+          accessToken: 'new_token',
+          userName: 'Updated User',
+        );
+
+        // Original unchanged
+        expect(original.accessToken, equals('old_token'));
+        expect(original.userName, equals('Original User'));
+
+        // Updated has new values
+        expect(updated.accessToken, equals('new_token'));
+        expect(updated.userName, equals('Updated User'));
+
+        // Preserved unchanged values
+        expect(updated.isAuthenticated, equals(original.isAuthenticated));
+      });
+    });
+
+    group('equality', () {
+      test('two identical states are equal', () {
+        const state1 = AuthState(
+          isAuthenticated: true,
+          userId: 'user-123',
+          userName: 'Test User',
+        );
+        const state2 = AuthState(
+          isAuthenticated: true,
+          userId: 'user-123',
+          userName: 'Test User',
+        );
+
+        expect(state1, equals(state2));
+      });
+
+      test('different states are not equal', () {
+        const state1 = AuthState(
+          isAuthenticated: true,
+          userId: 'user-123',
+        );
+        const state2 = AuthState(
+          isAuthenticated: true,
+          userId: 'user-456',
+        );
+
+        expect(state1, isNot(equals(state2)));
+      });
+    });
+  });
+}

test/core/auth/permission_gate_test.dart

@@ -0,0 +1,172 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tatlock_ui/core/auth/auth_state.dart';
+import 'package:tatlock_ui/core/auth/permissions.dart';
+
+// Note: PermissionGate widget tests require complex provider mocking.
+// These unit tests verify the permission logic that PermissionGate relies on.
+// Widget integration tests should be done with a running app or container testing.
+
+void main() {
+  group('PermissionGate logic', () {
+    test('hasPermission returns true when role grants permission', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'control-room.general:admin',
+            domain: Domain.controlRoom,
+            category: 'general',
+            action: Action.admin,
+          ),
+        ],
+      );
+
+      expect(state.hasPermission(Domain.controlRoom, Action.admin), isTrue);
+      expect(state.hasPermission(Domain.controlRoom, Action.viewer), isTrue);
+    });
+
+    test('hasPermission returns false when role does not grant permission', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'media.general:viewer',
+            domain: Domain.media,
+            category: 'general',
+            action: Action.viewer,
+          ),
+        ],
+      );
+
+      expect(state.hasPermission(Domain.controlRoom, Action.admin), isFalse);
+      expect(state.hasPermission(Domain.media, Action.admin), isFalse);
+    });
+
+    test('hasPermission returns false when not authenticated', () {
+      const state = AuthState(isAuthenticated: false);
+
+      expect(state.hasPermission(Domain.controlRoom, Action.viewer), isFalse);
+    });
+
+    test('hasPermission respects category', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'control-room.servers:admin',
+            domain: Domain.controlRoom,
+            category: 'servers',
+            action: Action.admin,
+          ),
+        ],
+      );
+
+      expect(
+        state.hasPermission(Domain.controlRoom, Action.admin, category: 'servers'),
+        isTrue,
+      );
+      expect(
+        state.hasPermission(Domain.controlRoom, Action.admin, category: 'general'),
+        isFalse,
+      );
+    });
+
+    test('isGlobalAdmin returns true for admin.general:admin role', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'admin.general:admin',
+            domain: Domain.admin,
+            category: 'general',
+            action: Action.admin,
+          ),
+        ],
+      );
+
+      expect(state.isGlobalAdmin, isTrue);
+    });
+
+    test('isGlobalAdmin returns false for non-admin roles', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'control-room.general:admin',
+            domain: Domain.controlRoom,
+            category: 'general',
+            action: Action.admin,
+          ),
+        ],
+      );
+
+      expect(state.isGlobalAdmin, isFalse);
+    });
+
+    test('global admin has access to all domains', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'admin.general:admin',
+            domain: Domain.admin,
+            category: 'general',
+            action: Action.admin,
+          ),
+        ],
+      );
+
+      // Global admin should have access to everything
+      expect(state.hasPermission(Domain.controlRoom, Action.admin), isTrue);
+      expect(state.hasPermission(Domain.media, Action.editor), isTrue);
+      expect(state.hasPermission(Domain.library, Action.viewer), isTrue);
+      expect(
+        state.hasPermission(Domain.documents, Action.user, category: 'custom'),
+        isTrue,
+      );
+    });
+
+    test('empty roles list denies all permissions', () {
+      const state = AuthState(isAuthenticated: true, roles: []);
+
+      expect(state.hasPermission(Domain.controlRoom, Action.viewer), isFalse);
+      expect(state.isGlobalAdmin, isFalse);
+    });
+
+    test('multiple roles are evaluated correctly', () {
+      final state = AuthState(
+        isAuthenticated: true,
+        roles: const [
+          Role(
+            id: '1',
+            name: 'media.general:viewer',
+            domain: Domain.media,
+            category: 'general',
+            action: Action.viewer,
+          ),
+          Role(
+            id: '2',
+            name: 'control-room.general:admin',
+            domain: Domain.controlRoom,
+            category: 'general',
+            action: Action.admin,
+          ),
+        ],
+      );
+
+      // Should have permissions from both roles
+      expect(state.hasPermission(Domain.media, Action.viewer), isTrue);
+      expect(state.hasPermission(Domain.controlRoom, Action.admin), isTrue);
+
+      // But not permissions not granted by any role
+      expect(state.hasPermission(Domain.media, Action.admin), isFalse);
+      expect(state.hasPermission(Domain.library, Action.viewer), isFalse);
+    });
+  });
+}

test/core/auth/permissions_test.dart

@@ -0,0 +1,283 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tatlock_ui/core/auth/permissions.dart';
+
+void main() {
+  group('Domain', () {
+    group('fromString', () {
+      test('parses valid domain strings', () {
+        expect(Domain.fromString('control-room'), equals(Domain.controlRoom));
+        expect(Domain.fromString('library'), equals(Domain.library));
+        expect(Domain.fromString('media'), equals(Domain.media));
+        expect(Domain.fromString('ai'), equals(Domain.ai));
+        expect(Domain.fromString('housekeeper'), equals(Domain.housekeeper));
+        expect(Domain.fromString('developer'), equals(Domain.developer));
+        expect(Domain.fromString('documents'), equals(Domain.documents));
+        expect(Domain.fromString('gaming'), equals(Domain.gaming));
+        expect(Domain.fromString('admin'), equals(Domain.admin));
+      });
+
+      test('returns null for invalid domain', () {
+        expect(Domain.fromString('invalid'), isNull);
+        expect(Domain.fromString(''), isNull);
+        expect(Domain.fromString('CONTROL-ROOM'), isNull);
+      });
+    });
+
+    test('value returns correct string', () {
+      expect(Domain.controlRoom.value, equals('control-room'));
+      expect(Domain.library.value, equals('library'));
+      expect(Domain.admin.value, equals('admin'));
+    });
+  });
+
+  group('Action', () {
+    group('fromString', () {
+      test('parses valid action strings', () {
+        expect(Action.fromString('viewer'), equals(Action.viewer));
+        expect(Action.fromString('user'), equals(Action.user));
+        expect(Action.fromString('editor'), equals(Action.editor));
+        expect(Action.fromString('admin'), equals(Action.admin));
+      });
+
+      test('returns null for invalid action', () {
+        expect(Action.fromString('invalid'), isNull);
+        expect(Action.fromString(''), isNull);
+        expect(Action.fromString('ADMIN'), isNull);
+      });
+    });
+
+    group('level', () {
+      test('has correct hierarchy levels', () {
+        expect(Action.viewer.level, equals(1));
+        expect(Action.user.level, equals(2));
+        expect(Action.editor.level, equals(3));
+        expect(Action.admin.level, equals(4));
+      });
+
+      test('levels are ordered correctly', () {
+        expect(Action.viewer.level, lessThan(Action.user.level));
+        expect(Action.user.level, lessThan(Action.editor.level));
+        expect(Action.editor.level, lessThan(Action.admin.level));
+      });
+    });
+
+    group('grants', () {
+      test('admin grants all actions', () {
+        expect(Action.admin.grants(Action.admin), isTrue);
+        expect(Action.admin.grants(Action.editor), isTrue);
+        expect(Action.admin.grants(Action.user), isTrue);
+        expect(Action.admin.grants(Action.viewer), isTrue);
+      });
+
+      test('editor grants editor and below', () {
+        expect(Action.editor.grants(Action.admin), isFalse);
+        expect(Action.editor.grants(Action.editor), isTrue);
+        expect(Action.editor.grants(Action.user), isTrue);
+        expect(Action.editor.grants(Action.viewer), isTrue);
+      });
+
+      test('user grants user and below', () {
+        expect(Action.user.grants(Action.admin), isFalse);
+        expect(Action.user.grants(Action.editor), isFalse);
+        expect(Action.user.grants(Action.user), isTrue);
+        expect(Action.user.grants(Action.viewer), isTrue);
+      });
+
+      test('viewer only grants viewer', () {
+        expect(Action.viewer.grants(Action.admin), isFalse);
+        expect(Action.viewer.grants(Action.editor), isFalse);
+        expect(Action.viewer.grants(Action.user), isFalse);
+        expect(Action.viewer.grants(Action.viewer), isTrue);
+      });
+    });
+  });
+
+  group('Role', () {
+    group('grants', () {
+      test('grants permission for matching domain and category', () {
+        const role = Role(
+          id: '1',
+          name: 'control-room.general:admin',
+          domain: Domain.controlRoom,
+          category: 'general',
+          action: Action.admin,
+        );
+
+        expect(role.grants(Domain.controlRoom, Action.admin), isTrue);
+        expect(role.grants(Domain.controlRoom, Action.editor), isTrue);
+        expect(role.grants(Domain.controlRoom, Action.user), isTrue);
+        expect(role.grants(Domain.controlRoom, Action.viewer), isTrue);
+      });
+
+      test('denies permission for different domain', () {
+        const role = Role(
+          id: '1',
+          name: 'control-room.general:admin',
+          domain: Domain.controlRoom,
+          category: 'general',
+          action: Action.admin,
+        );
+
+        expect(role.grants(Domain.media, Action.viewer), isFalse);
+        expect(role.grants(Domain.library, Action.viewer), isFalse);
+      });
+
+      test('denies permission for different category', () {
+        const role = Role(
+          id: '1',
+          name: 'control-room.servers:admin',
+          domain: Domain.controlRoom,
+          category: 'servers',
+          action: Action.admin,
+        );
+
+        expect(
+          role.grants(Domain.controlRoom, Action.admin, category: 'general'),
+          isFalse,
+        );
+        expect(
+          role.grants(Domain.controlRoom, Action.admin, category: 'servers'),
+          isTrue,
+        );
+      });
+
+      test('global admin grants all permissions', () {
+        const globalAdmin = Role(
+          id: '1',
+          name: 'admin.general:admin',
+          domain: Domain.admin,
+          category: 'general',
+          action: Action.admin,
+        );
+
+        // Should grant any domain, category, action
+        expect(globalAdmin.grants(Domain.controlRoom, Action.admin), isTrue);
+        expect(globalAdmin.grants(Domain.media, Action.editor), isTrue);
+        expect(globalAdmin.grants(Domain.library, Action.viewer), isTrue);
+        expect(
+          globalAdmin.grants(Domain.documents, Action.user, category: 'specific'),
+          isTrue,
+        );
+      });
+
+      test('non-global admin role does not grant everything', () {
+        const domainAdmin = Role(
+          id: '1',
+          name: 'admin.specific:admin',
+          domain: Domain.admin,
+          category: 'specific', // Not 'general'
+          action: Action.admin,
+        );
+
+        // Should not grant arbitrary permissions
+        expect(domainAdmin.grants(Domain.controlRoom, Action.viewer), isFalse);
+      });
+    });
+  });
+
+  group('RoleListPermissions extension', () {
+    final roles = [
+      const Role(
+        id: '1',
+        name: 'control-room.general:admin',
+        domain: Domain.controlRoom,
+        category: 'general',
+        action: Action.admin,
+      ),
+      const Role(
+        id: '2',
+        name: 'media.general:viewer',
+        domain: Domain.media,
+        category: 'general',
+        action: Action.viewer,
+      ),
+    ];
+
+    group('hasPermission', () {
+      test('returns true when any role grants permission', () {
+        expect(
+          roles.hasPermission(Domain.controlRoom, Action.admin),
+          isTrue,
+        );
+        expect(
+          roles.hasPermission(Domain.controlRoom, Action.viewer),
+          isTrue,
+        );
+        expect(
+          roles.hasPermission(Domain.media, Action.viewer),
+          isTrue,
+        );
+      });
+
+      test('returns false when no role grants permission', () {
+        expect(
+          roles.hasPermission(Domain.media, Action.editor),
+          isFalse,
+        );
+        expect(
+          roles.hasPermission(Domain.library, Action.viewer),
+          isFalse,
+        );
+      });
+
+      test('returns false for empty role list', () {
+        expect(
+          <Role>[].hasPermission(Domain.controlRoom, Action.viewer),
+          isFalse,
+        );
+      });
+    });
+
+    group('isGlobalAdmin', () {
+      test('returns true when global admin role present', () {
+        final adminRoles = [
+          const Role(
+            id: '1',
+            name: 'admin.general:admin',
+            domain: Domain.admin,
+            category: 'general',
+            action: Action.admin,
+          ),
+        ];
+
+        expect(adminRoles.isGlobalAdmin, isTrue);
+      });
+
+      test('returns false when no global admin role', () {
+        expect(roles.isGlobalAdmin, isFalse);
+      });
+
+      test('returns false for empty role list', () {
+        expect(<Role>[].isGlobalAdmin, isFalse);
+      });
+
+      test('returns false for admin domain with non-general category', () {
+        final limitedAdmin = [
+          const Role(
+            id: '1',
+            name: 'admin.specific:admin',
+            domain: Domain.admin,
+            category: 'specific',
+            action: Action.admin,
+          ),
+        ];
+
+        expect(limitedAdmin.isGlobalAdmin, isFalse);
+      });
+
+      test('returns false for admin domain with non-admin action', () {
+        final viewerAdmin = [
+          const Role(
+            id: '1',
+            name: 'admin.general:viewer',
+            domain: Domain.admin,
+            category: 'general',
+            action: Action.viewer,
+          ),
+        ];
+
+        expect(viewerAdmin.isGlobalAdmin, isFalse);
+      });
+    });
+  });
+}

test/core/auth/user_preferences_test.dart

@@ -0,0 +1,147 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tatlock_ui/core/auth/user_preferences.dart';
+
+void main() {
+  group('UserPreferences', () {
+    group('default constructor', () {
+      test('creates with default values', () {
+        const prefs = UserPreferences();
+
+        expect(prefs.theme, equals('system'));
+        expect(prefs.defaultRoom, equals('front-hall'));
+        expect(prefs.preferencesJson, isEmpty);
+      });
+    });
+
+    group('custom constructor', () {
+      test('creates with custom values', () {
+        const prefs = UserPreferences(
+          theme: 'dark',
+          defaultRoom: 'kitchen',
+          preferencesJson: {'sidebar_collapsed': true, 'font_size': 14},
+        );
+
+        expect(prefs.theme, equals('dark'));
+        expect(prefs.defaultRoom, equals('kitchen'));
+        expect(prefs.preferencesJson['sidebar_collapsed'], isTrue);
+        expect(prefs.preferencesJson['font_size'], equals(14));
+      });
+    });
+
+    group('fromJson', () {
+      test('deserializes from JSON', () {
+        final json = {
+          'theme': 'light',
+          'defaultRoom': 'living-room',
+          'preferencesJson': {'key': 'value'},
+        };
+
+        final prefs = UserPreferences.fromJson(json);
+
+        expect(prefs.theme, equals('light'));
+        expect(prefs.defaultRoom, equals('living-room'));
+        expect(prefs.preferencesJson['key'], equals('value'));
+      });
+
+      test('uses defaults for missing fields', () {
+        final json = <String, dynamic>{};
+
+        final prefs = UserPreferences.fromJson(json);
+
+        expect(prefs.theme, equals('system'));
+        expect(prefs.defaultRoom, equals('front-hall'));
+        expect(prefs.preferencesJson, isEmpty);
+      });
+
+      test('handles partial JSON', () {
+        final json = {'theme': 'dark'};
+
+        final prefs = UserPreferences.fromJson(json);
+
+        expect(prefs.theme, equals('dark'));
+        expect(prefs.defaultRoom, equals('front-hall'));
+      });
+    });
+
+    group('toJson', () {
+      test('serializes to JSON', () {
+        const prefs = UserPreferences(
+          theme: 'dark',
+          defaultRoom: 'office',
+          preferencesJson: {'notifications': true},
+        );
+
+        final json = prefs.toJson();
+
+        expect(json['theme'], equals('dark'));
+        expect(json['defaultRoom'], equals('office'));
+        expect(json['preferencesJson']['notifications'], isTrue);
+      });
+
+      test('round-trip serialization preserves data', () {
+        const original = UserPreferences(
+          theme: 'light',
+          defaultRoom: 'bedroom',
+          preferencesJson: {'compact_mode': false},
+        );
+
+        final json = original.toJson();
+        final restored = UserPreferences.fromJson(json);
+
+        expect(restored.theme, equals(original.theme));
+        expect(restored.defaultRoom, equals(original.defaultRoom));
+        expect(
+          restored.preferencesJson['compact_mode'],
+          equals(original.preferencesJson['compact_mode']),
+        );
+      });
+    });
+
+    group('copyWith', () {
+      test('creates a copy with modified values', () {
+        const original = UserPreferences(
+          theme: 'system',
+          defaultRoom: 'front-hall',
+        );
+
+        final updated = original.copyWith(theme: 'dark');
+
+        // Original unchanged
+        expect(original.theme, equals('system'));
+
+        // Updated has new value
+        expect(updated.theme, equals('dark'));
+
+        // Preserved unchanged values
+        expect(updated.defaultRoom, equals(original.defaultRoom));
+      });
+    });
+
+    group('equality', () {
+      test('two identical preferences are equal', () {
+        const prefs1 = UserPreferences(theme: 'dark', defaultRoom: 'office');
+        const prefs2 = UserPreferences(theme: 'dark', defaultRoom: 'office');
+
+        expect(prefs1, equals(prefs2));
+      });
+
+      test('different preferences are not equal', () {
+        const prefs1 = UserPreferences(theme: 'dark');
+        const prefs2 = UserPreferences(theme: 'light');
+
+        expect(prefs1, isNot(equals(prefs2)));
+      });
+    });
+
+    group('theme validation', () {
+      test('accepts valid theme values', () {
+        const themes = ['system', 'light', 'dark'];
+
+        for (final theme in themes) {
+          final prefs = UserPreferences(theme: theme);
+          expect(prefs.theme, equals(theme));
+        }
+      });
+    });
+  });
+}