fix: theme toggle causing auth issues due to auto-dispose

- Add @persistentRiverpod annotation for providers that need keepAlive
- ThemeProvider now persists for app lifetime
- Refactored API clients to use @persistentRiverpod
- Documented in ARCHITECTURE.md

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

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

lib/core/api/api_client.dart

@@ -2,6 +2,7 @@ import 'package:dio/dio.dart';
 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 'package:tatlock_ui/core/providers/annotations.dart';
 
 import 'api_client_native.dart' if (dart.library.html) 'api_client_web.dart'
     as platform;
@@ -9,10 +10,7 @@ import 'api_client_native.dart' if (dart.library.html) 'api_client_web.dart'
 part 'api_client.g.dart';
 
 /// Provides the Dio instance for Core API.
-///
-/// Uses keepAlive to prevent auto-dispose - the AuthInterceptor stores
-/// a Ref that must remain valid for the lifetime of API requests.
-@Riverpod(keepAlive: true)
+@persistentRiverpod
 Dio coreApiClient(Ref ref) {
   final options = BaseOptions(
     baseUrl: AppConfig.coreApiUrl,
@@ -36,10 +34,7 @@ Dio coreApiClient(Ref ref) {
 }
 
 /// Provides the Dio instance for Tatlock API.
-///
-/// Uses keepAlive to prevent auto-dispose - the AuthInterceptor stores
-/// a Ref that must remain valid for the lifetime of API requests.
-@Riverpod(keepAlive: true)
+@persistentRiverpod
 Dio tatlockApiClient(Ref ref) {
   final options = BaseOptions(
     baseUrl: AppConfig.tatlockApiUrl,

lib/core/providers/annotations.dart

@@ -0,0 +1,15 @@
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+/// Riverpod annotation for providers that should persist for the app lifetime.
+///
+/// Use this instead of `@riverpod` when:
+/// - The provider holds app-level state (theme, auth, config)
+/// - The provider stores a Ref that must remain valid (API clients with interceptors)
+/// - Disposing would cause flickering or re-initialization issues
+///
+/// Example:
+/// ```dart
+/// @persistentRiverpod
+/// class ThemeNotifier extends _$ThemeNotifier { ... }
+/// ```
+const persistentRiverpod = Riverpod(keepAlive: true);

lib/core/theme/theme_provider.dart

@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
 import 'package:riverpod_annotation/riverpod_annotation.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import 'package:tatlock_ui/core/auth/auth_provider.dart';
+import 'package:tatlock_ui/core/providers/annotations.dart';
 
 part 'theme_provider.g.dart';
 
@@ -23,7 +24,7 @@ enum ThemeSetting {
 ///
 /// Syncs with API preferences when user is authenticated. On login, the theme
 /// from API preferences takes precedence over local storage.
-@riverpod
+@persistentRiverpod
 class ThemeNotifier extends _$ThemeNotifier {
   static const _prefsKey = 'theme_setting';