fix: log environment API user only once per session

- Store user in static variable for reuse - Only debugPrint on first successful load 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
fix: sun position arc overflow and revert user display
2026-01-07 15:40:06 +01:00 · 2026-01-07 15:26:51 +01:00 · 2026-01-07 14:05:16 +01:00 · 2026-01-07 13:29:56 +01:00 · 2026-01-07 12:06:17 +01:00 · 2026-01-07 11:21:48 +01:00
128 changed files with 15733 additions and 633 deletions
@@ -1,15 +1,27 @@
 name: Build and Push

 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - 'v*'

 jobs:
-  build:
+  release:
    runs-on: ubuntu-latest
    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Create Gitea Release
+        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
@@ -13,11 +13,12 @@ pubspec.lock
 *.gr.dart
 *.mocks.dart

-# Keep version.g.dart - it's generated but should be committed
-# so CI/CD builds have version info without running the generator
-# Other *.g.dart files (from json_serializable, etc.) are ignored
+# All generated *.g.dart files (from json_serializable, riverpod, version_builder)
+# These are regenerated by build_runner during CI/CD builds
 lib/**/*.g.dart
-!lib/version.g.dart
+
+# Generated health.json (regenerated by tool/generate_health_json.dart during build)
+web/health.json

 # IDE
 .idea/
@@ -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**:
-  * LAN: `http://192.168.86.149:8000`
-  * External: `tatlock.schweitz.net` (behind Authentik SSO)
-  * Redis DBs: 1 (memory), 6 (benchmarks)
-* **Health check**: `curl http://192.168.86.149:8000/health`
+* **Health checks**:
+  * Core API: `curl http://192.168.86.149:8083/health`
+  * Tatlock API: `curl http://192.168.86.149:8000/health`

 ### 🛡️ Git Discipline
 * **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
@@ -53,10 +59,8 @@ This project uses version-tag-based CI/CD. Releases trigger automated Docker bui
 3. Commit changes: `git commit -m "chore: release vX.X.X"`
 4. Create git tag: `git tag vX.X.X`
 5. Push with tags: `git push origin master --tags`
-6. Create release in Gitea UI (git.schweitz.net → Releases → New Release)
-   * Select the tag
-   * Add release notes (can copy from CHANGELOG)
-   * **Publish** the release (this triggers CI/CD)
+
+CI/CD auto-triggers when a tag starting with `v` is pushed.

 **What happens on release:**

@@ -7,6 +7,435 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [1.5.6] - 2026-01-07
+
+### Changed
+
+- **Environment user logging** - Now logs API user only once per session instead of on every refresh
+
+## [1.5.5] - 2026-01-07
+
+### Fixed
+
+- **Sun position arc overflow** - Arc now constrained to fit within card boundaries
+  - Prevents arc and sun/moon from overflowing on wider displays
+  - Scales radius down when arc height exceeds available space
+
+### Added
+
+- **Debug logging for environment user** - Logs authenticated user on environment data load
+
+## [1.5.4] - 2026-01-07
+
+### Added
+
+- User display in environment section header (reverted in 1.5.5)
+
+## [1.5.3] - 2026-01-07
+
+### Changed
+
+- **Sun position arc redesign** - Arc now touches horizon at sunrise/sunset points
+  - Arc geometry uses chord-radius calculation for proper horizon intersection
+  - Sunrise/sunset icons integrated at horizon endpoints (no duplicate labels)
+  - Daylight duration centered below arc
+  - Increased card height 20% for better arc visibility (140px → 170px)
+- **Visual balance improvements** - Sunrise/sunset labels raised 10px, daylight label at bottom
+
+## [1.5.2] - 2026-01-07
+
+### Changed
+
+- **Proportional sun/moon arc visualization** - Arc angle now proportional to day/night duration
+  - Day arc: spans (daylight hours / 24) × 360° above horizon
+  - Night arc: spans (night hours / 24) × 360° with moon traversal
+  - Horizon points represent sunrise/sunset times
+  - Gradient colors: yellow/orange for day, blue/indigo for night
+- **Sun position widget now updates every 10 minutes** - Position aligned to clock intervals (0/10/20/30/40/50)
+  - Converted to StatefulWidget with timer-based updates
+  - Shows default 7am/5pm sunrise/sunset when API data unavailable (asymmetric for visual effect)
+  - Always displays times and daylight duration (no more "--:--")
+- **Environment widgets consistent height** - All cards maintain same height in "no data" state
+
+## [1.5.1] - 2026-01-07
+
+### Changed
+
+- **Environment widgets layout redesign** - All 4 widgets always visible with responsive layout
+  - Desktop (>900px): 4-in-a-row with 30/20/20/30 width distribution (Sun | Weather | Air Quality | Forecast)
+  - Tablet (600-900px): 2x2 grid layout
+  - Mobile (<600px): Stacked vertically
+  - Widgets now show "No data available" state instead of being hidden or using mock data
+- Sun position widget now calculates position from system clock
+  - Defaults to 6am/6pm (12-hour day/night cycles) when API sun times unavailable
+- Environment data refresh interval changed from 5 minutes to 1 hour
+
+## [1.5.0] - 2026-01-06
+
+### Added
+
+- **Dynamic Environment Widgets** - Live weather, sun position, and forecast data from Qdrant
+  - `SunPositionWidget` - Animated semicircle arc showing sun/moon position based on current time
+    - Gradient colors: yellow for daytime, orange for sunrise/sunset, blue for night
+    - Displays sunrise, sunset times and daylight duration
+  - `WeatherWidget` - Current temperature, conditions, humidity from API
+  - `ForecastWidget` - Multi-day weather forecast with conditions icons
+  - `AirQualityWidget` - AQI display (only shown when data available)
+- Environment data provider with auto-refresh every 5 minutes
+- Environment datasource calling `GET /tools/environment`
+- Freezed models for environment data (weather, forecast, sun times, air quality)
+- Comprehensive widget tests for environment section
+
+### Changed
+
+- Dashboard layout now displays dynamic environment data instead of static widgets
+- Weather and air quality widgets accept optional API data parameters
+
+## [1.4.0] - 2026-01-05
+
+### Added
+- **Decentralized Room Registry** - Each room registers itself with central registry
+  - `RoomDefinition` class with id, label, icons, routes, and permissions
+  - `RoomRegistry` singleton for managing all rooms
+  - Dynamic navigation tabs built from registry
+  - Settings dropdown builds from available rooms
+  - Permission-based room filtering support
+- **Media Room** - New placeholder room for future media management features
+- **Parlor** - Now a proper feature folder with router registration
+
+### Changed
+- Room navigation is now fully dynamic via registry
+  - `top_header_bar.dart` uses `roomRegistry.all` instead of hardcoded list
+  - `app_scaffold.dart` uses registry for route matching and navigation
+  - Settings page dropdown populated from `roomRegistry.all`
+- Routers moved to per-room pattern:
+  - `lib/features/front_hall/router.dart` (new)
+  - `lib/features/parlor/router.dart` (new)
+  - `lib/features/media_room/router.dart` (new)
+  - Existing `control_room/router.dart` and `security/router.dart` now register with registry
+- Documentation updated in ARCHITECTURE.md with Room Registry Pattern section
+
+### Removed
+- Hardcoded room lists in `top_header_bar.dart` and `app_scaffold.dart`
+- `_PlaceholderPage` widget in `app_router.dart` (each room has its own page)
+
+## [1.3.1] - 2026-01-05
+
+### Fixed
+- Default room preference now applies on app load
+  - Root `/` redirects to user's preferred default room
+  - Front Hall moved to `/front-hall` route (was `/`)
+
+## [1.3.0] - 2026-01-05
+
+### Added
+- **URL deep-linking for DataGrids** - State is now reflected in URL query parameters
+  - `?search=` - DataGrid search query
+  - `?sort=` - Column ID for sorting
+  - `?order=desc` - Sort direction
+  - `?id=` - Opened document ID (proxy hosts page)
+- `PageUrlState` utility class (`lib/routing/url_state.dart`) for URL ↔ state serialization
+- Browser URL updates via `replaceState` without triggering GoRouter rebuilds
+- `id` field added to `DataGridColumn` for unique column identification in URLs
+- `FilterPanelSemantics` class for filter panel semantic IDs
+- TESTING.md documentation for semantic widgets and automation testing
+
+### Changed
+- `idSelector` in DataGridController now returns `String` (was `Object`) for URL compatibility
+- All DataGrid pages now support URL deep-linking:
+  - Containers list (`/control-room/containers`)
+  - Proxy hosts (`/control-room/proxy-hosts`)
+  - Users (`/security/users`)
+  - Groups (`/security/groups`)
+- Router passes `GoRouterState` to pages for query parameter access
+
+## [1.2.0] - 2026-01-05
+
+### Added
+- **Semantic labels for UI automation** (`lib/core/semantics/`)
+  - `semantic_ids.dart` - Centralized semantic identifier constants
+  - `semantic_widget.dart` - Helper widget and extension for adding semantics
+  - Enables browser automation tools (Puppeteer, WebDriver) via accessibility tree
+- Semantic IDs added to:
+  - Profile dropdown button and menu items (theme options, settings, logout)
+  - Room navigation tabs (Front Hall, Control Room, Security, Parlor)
+  - NavPanel items (sidebar navigation)
+- `SemanticsBinding.instance.ensureSemantics()` enabled on web builds
+
+## [1.1.16] - 2026-01-05
+
+### Fixed
+- Theme toggle causing logout due to AuthInterceptor auto-signout on 401
+  - Removed aggressive `signOut()` call in `AuthInterceptor.onError`
+  - 401 errors now propagate to calling code for graceful handling
+  - Preferences API 401 no longer triggers full logout redirect
+
+## [1.1.15] - 2026-01-05
+
+### Fixed
+- Theme toggle causing auth issues due to AuthNotifier auto-dispose
+  - Applied `@persistentRiverpod` annotation to AuthNotifier
+  - AuthProvider now persists for app lifetime, preventing rebuild on theme change
+
+## [1.1.14] - 2026-01-04
+
+### Fixed
+- Theme toggle causing auth issues due to ThemeProvider auto-dispose
+  - Added `@persistentRiverpod` annotation for providers that need keepAlive
+  - ThemeProvider now persists for app lifetime
+
+### Added
+- `@persistentRiverpod` annotation in `core/providers/annotations.dart`
+  - Reusable annotation for providers that should not auto-dispose
+  - Documented in ARCHITECTURE.md
+
+## [1.1.13] - 2026-01-04
+
+### Added
+- Settings page with Appearance, Navigation, and Account sections
+- Theme toggle in user profile dropdown (System/Light/Dark)
+- Theme syncs with API preferences on login
+- Default room preference syncs with backend
+
+### Changed
+- Theme changes now persist to both local storage and API
+
+## [1.1.12] - 2026-01-04
+
+### Changed
+- Control Room navigation reorganized:
+  - New "Stack" section with Containers and Proxy Hosts
+  - New "Data Management" section with PostgreSQL, Redis, Qdrant, Neo4j placeholders
+  - Removed: Networks, Volumes, Images (Portainer) and Redirections, Streams, Certificates (NPM)
+
+## [1.1.11] - 2026-01-04
+
+### Fixed
+- API client providers now use `keepAlive: true` to prevent Ref invalidation
+  - Fixes "DioException [unknown]: null" error on /security/users and other API pages
+  - AuthInterceptor's stored Ref was becoming invalid when provider auto-disposed
+
+## [1.1.10] - 2026-01-04
+
+### Changed
+- Removed page swipe transitions - all navigation is now instant (NoTransitionPage)
+
+## [1.1.9] - 2026-01-04
+
+### Changed
+- Moved health check to `/health` directory - URL is now `/health` instead of `/health.html`
+  - Enables NPM forward auth path exclusion for health endpoint
+
+## [1.1.8] - 2026-01-04
+
+### Changed
+- Dark background (`#1a1a2e`) on web/index.html to prevent white flash during auth redirects
+
+## [1.1.7] - 2026-01-04
+
+### Removed
+- Removed `/callback` route from Flutter router - AuthController handles callback in main() before app starts
+- Removed `_OidcCallbackPage` widget - no visible auth UI needed
+
+## [1.1.6] - 2026-01-04
+
+### Changed
+- **Auth moved to standalone controller** - Handles OIDC completely outside Riverpod
+  - New `AuthController` runs in `main()` before `runApp()` - avoids provider lifecycle issues
+  - Handles callback, token exchange, and /auth/sync before app starts
+  - If auth not ready (redirecting), app doesn't start at all
+  - `AuthProvider` now just loads stored tokens (no async OIDC logic)
+  - Fixes "Cannot use Ref after disposed" errors from autoDispose providers
+
+## [1.1.5] - 2026-01-04
+
+### Fixed
+- Race condition in OIDC callback: AuthProvider.build() was initiating silent OIDC while the callback page was processing, causing PKCE state to be cleared. Now skips silent OIDC when on `/callback` route.
+
+## [1.1.4] - 2026-01-04
+
+### Fixed
+- Silent OIDC fallback: when `prompt=none` fails with `login_required` (no Authentik session), automatically fall back to regular OIDC flow to show login UI
+
+## [1.1.3] - 2026-01-04
+
+### Changed
+- **Web auth uses silent OIDC with JWT Bearer tokens**
+  - Uses `prompt=none` to silently obtain JWT when Authentik session exists (via NPM forward auth)
+  - Flutter sends Bearer token to core-api instead of relying on forward auth cookies
+  - Fixes cross-subdomain cookie issues between home.schweitz.net and api.schweitz.net
+  - Callback now syncs with `/auth/sync` to get user profile and roles from core-api
+  - API interceptor now adds Bearer token on web (previously skipped)
+
+## [1.1.2] - 2026-01-04
+
+### Changed
+- **Web auth simplified**: Skip Flutter OIDC on web - NPM forward auth handles it
+  - NPM authenticates at proxy level before app loads
+  - No more redundant OIDC redirect after NPM auth completes
+  - Fixes "Cannot use Ref after disposed" error from conflicting auth flows
+  - Mobile still uses Flutter OIDC flow
+
+### Added
+- Logout now redirects to Authentik to end SSO session
+  - Clears local tokens AND invalidates Authentik session
+  - Uses OIDC end_session_endpoint from discovery document
+  - Redirects back to app after Authentik logout completes
+
+## [1.1.0] - 2026-01-04
+
+### Changed
+- **Dockerfile rebuild fix**: Added `flutter clean` before build to prevent stale cached artifacts
+  - VERSION build arg added for explicit cache busting
+  - Reordered build steps: clean → pub get → build_runner → health.json → flutter build
+  - Ensures deployed app always matches the version in health.json
+
+### Fixed
+- Replaced deprecated `dart:html` with `package:web` in iframe_view_web.dart
+  - Uses `web.HTMLIFrameElement` instead of `html.IFrameElement`
+  - Fixes deprecation warnings for Flutter 3.x web builds
+
+## [1.0.12] - 2026-01-04
+
+### Changed
+- Removed login page - auth now auto-initiates from AppScaffold
+  - No more redirect to /login, just auto-start OIDC if not authenticated
+  - Shows loading screen during auth, error screen on failure with retry
+  - Seamless experience when Authentik session exists
+
+### Removed
+- Removed /login route and _LoginPage widget
+
+## [1.0.11] - 2026-01-04
+
+### Changed
+- Web auth now extracts user info directly from JWT instead of syncing with core-api
+  - Eliminates CORS preflight issues with /auth/sync endpoint
+  - Decodes JWT claims (name, email, groups) client-side
+  - Bearer token will be used for API authentication
+
+## [1.0.10] - 2026-01-04
+
+### Fixed
+- Fixed OIDC callback route being redirected to login before processing
+  - Moved callback route exception check BEFORE the auth redirect check in router
+  - This was preventing token exchange from ever happening
+- Added favicon.ico to web root for proper browser tab icon display
+
+## [1.0.9] - 2026-01-04
+
+### Fixed
+- Fixed OIDC callback Riverpod state modification error
+  - Deferred callback processing to `addPostFrameCallback` to avoid modifying state during widget build
+
+## [1.0.8] - 2026-01-04
+
+### Changed
+- Switched from hash-based URLs (`/#/login`) to path-based URLs (`/login`)
+  - Required for OIDC callback to work correctly
+  - Uses conditional import to avoid breaking mobile/desktop builds
+
+## [1.0.7] - 2026-01-04
+
+### Fixed
+- Fixed OIDC PKCE state loss across browser redirect
+  - Code verifier and state now persist in sessionStorage instead of memory
+  - Prevents "No code verifier" error after Authentik redirect
+
+## [1.0.6] - 2026-01-04
+
+### Fixed
+- Fixed version generation in CI/CD builds
+- Removed generated files (version.g.dart, health.json) from git tracking
+- These files are now regenerated from pubspec.yaml during Docker build
+
+## [1.0.5] - 2026-01-04
+
+### Changed
+- **Web authentication now uses OIDC** instead of NPM forward auth
+  - Added `OidcServiceWeb` for browser redirect-based Authorization Code flow with PKCE
+  - Added `/callback` route to handle Authentik redirect after login
+  - Login page now shows "Sign in with Authentik" button for both web and mobile
+  - Tokens stored in SharedPreferences and synced with core-api via `/auth/sync`
+- Added web utility functions (`web_utils.dart`) with conditional imports for non-web platforms
+- Added `crypto` and `web` packages for PKCE SHA-256 and browser API access
+
+### Fixed
+- Removed cross-origin cookie dependency that caused authentication failures on web
+
+## [1.0.4] - 2026-01-03
+
+### Added
+- `health.json` generated at build time with app version info
+- `health.html` now displays version, title, and status from health.json
+
+## [1.0.3] - 2026-01-03
+
+### Fixed
+- Fixed auth endpoint path: `/auth/me` → `/auth/users/me`
+
+## [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
+- Health check endpoint (`/health.html`) for Portainer container monitoring
+- Local search filtering in DataGrid (filters cached data client-side)
+- Container status badges now reflect health status (green=healthy, orange=unhealthy)
+- `ContainerHealth` enum for parsing Docker health status from status string
+
+### Changed
+- Standardized header bar heights to 56px across all panels
+- Container grid now correctly parses Docker API JSON format (capitalized keys)
+- Status column displays clean uptime (stripped health indicators)
+- Status badges have consistent minimum width (90px)
+- Search bar styling improved (36px height, visible border, proper background)
+- Quick links now properly persist link type (iframe vs new tab)
+- Iframe switching now closes existing content before loading new link
+
+### Fixed
+- Quick links form properly saves changes and refreshes panel
+- `ContainerState` type conflict resolved (removed duplicate enum)
+- Container data parsing handles null values safely
+
+### Branding
+- Updated favicon and icons with Tatlock bucket logo
+- Updated manifest.json with Tatlock branding
+
+## [0.3.2] - 2025-01-02
+
 ### Changed
 - API defaults now use LAN IPs for local development (no auth required)
 - Auth interceptor skips authentication when using LAN endpoints
@@ -3,20 +3,34 @@ FROM ghcr.io/cirruslabs/flutter:stable AS builder

 WORKDIR /app

-# Copy dependency files first for better caching
-COPY pubspec.yaml ./
+# VERSION arg busts cache when version changes in pubspec.yaml
+# Extract version: docker build --build-arg VERSION=$(grep '^version:' pubspec.yaml | cut -d' ' -f2) .
+ARG VERSION=0.0.0
+RUN echo "Building version: $VERSION"

-# Get dependencies (generates pubspec.lock)
+# Copy dependency files first for better caching
+COPY pubspec.yaml pubspec.lock* ./
+
+# Get dependencies
 RUN flutter pub get

 # Copy the rest of the application
 COPY . .

-# Generate code with build_runner
+# Clean any cached build artifacts to ensure fresh build
+RUN flutter clean && flutter pub get
+
+# Generate code with build_runner (after clean for fresh generation)
 RUN dart run build_runner build --delete-conflicting-outputs

-# Build for web release
-RUN flutter build web --release
+# Generate health.json with version info
+RUN dart run tool/generate_health_json.dart
+
+# Build for web release with production configuration
+# 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
@@ -0,0 +1,86 @@
+# Auth Flow Refactor: Invisible Token Exchange
+
+> Research note for future implementation
+
+## Problem
+
+The `/callback?code=...` URL is visible in the browser during token refresh. This happens every time tokens need refreshing, not just on initial login. The current implementation appears to re-run the full OIDC redirect flow (`prompt=none`) instead of using the refresh_token.
+
+## Current Behavior
+
+```
+Token expires → Redirect to Authentik (prompt=none) →
+Redirect to /callback?code=xxx → Exchange code → Continue
+```
+
+User sees URL flicker to `/callback` repeatedly.
+
+## Desired Behavior
+
+```
+Token expires → Show overlay (lock/lightning icon) →
+XHR refresh request → Hide overlay → Continue
+```
+
+No URL changes. No redirects. Just a brief visual indicator.
+
+## Key Insight
+
+**Only the initial authorization MUST redirect** (user needs to see Authentik login UI).
+
+Everything else can be XHR:
+
+| Operation | Current | Should Be |
+|-----------|---------|-----------|
+| Initial login | Redirect | Redirect (unavoidable) |
+| Token exchange (code → tokens) | Redirect to /callback | XHR POST |
+| Token refresh | Full OIDC with prompt=none | XHR POST with refresh_token |
+| Session expired | Redirect | Redirect (unavoidable) |
+
+## Token Refresh via XHR
+
+```dart
+final response = await dio.post(
+  'https://authentik.schweitz.net/application/o/token/',
+  data: {
+    'grant_type': 'refresh_token',
+    'refresh_token': storedRefreshToken,
+    'client_id': clientId,
+  },
+  options: Options(
+    contentType: Headers.formUrlEncodedContentType,
+  ),
+);
+// Returns new access_token, refresh_token, expires_in
+```
+
+## Potential Blocker: CORS
+
+Authentik's token endpoint may block browser XHR. Solutions:
+
+1. **Configure Authentik CORS** - Allow `home.schweitz.net` origin
+2. **Proxy through core-api** (recommended)
+   - Flutter → `POST /auth/refresh` → core-api → Authentik
+   - Keeps client_secret server-side
+   - No CORS issues
+
+## Implementation Steps
+
+1. [ ] Verify Authentik is issuing refresh_tokens (check token response)
+2. [ ] Check if refresh_token is being stored (SharedPreferences)
+3. [ ] Test XHR to token endpoint (check CORS)
+4. [ ] If CORS blocked, add `/auth/refresh` endpoint to core-api
+5. [ ] Refactor `AuthProvider` to use XHR refresh instead of full OIDC flow
+6. [ ] Add refresh overlay UI (lock icon + brief animation)
+7. [ ] Remove `prompt=none` redirect logic for refresh cases
+
+## Files to Investigate
+
+- `lib/core/auth/auth_provider.dart` - Main auth state management
+- `lib/core/auth/oidc_service_web.dart` - OIDC implementation
+- `lib/core/api/api_interceptors.dart` - Token refresh trigger point
+
+## References
+
+- CHANGELOG entries v1.1.3-v1.1.6 document the current auth architecture
+- AuthController runs in `main()` before `runApp()` (v1.1.6 pattern)
@@ -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 {
@@ -20,6 +20,7 @@ lib/
 │   ├── auth/                     # Authentik OIDC integration
 │   ├── config/                   # Environment configuration
 │   ├── error/                    # Error types and handling
+│   ├── semantics/                # Semantic IDs for automation
 │   └── theme/                    # Material 3 theming
 ├── routing/                      # go_router configuration
 ├── shared/                       # Reusable components
@@ -27,14 +28,20 @@ lib/
 │   └── layouts/                  # App scaffold, navigation
 ├── features/                     # Feature modules (rooms)
 │   ├── front_hall/               # Dashboard - estate overview
+│   │   └── router.dart           # Room registration
 │   ├── control_room/             # Infrastructure
+│   │   ├── router.dart           # Room registration
 │   │   ├── containers/           # Container management
-│   │   ├── stacks/               # Stack management
-│   │   ├── networks/             # Network management
-│   │   └── volumes/              # Volume management
-│   ├── parlor/                   # Housekeeping - home automation
-│   ├── library/                  # Knowledge management (future)
-│   └── study/                    # Secretarial tasks (future)
+│   │   └── npm/                  # Proxy hosts management
+│   ├── security/                 # User & access management
+│   │   ├── router.dart           # Room registration
+│   │   ├── users/                # User management
+│   │   └── groups/               # Group management
+│   ├── parlor/                   # AI chat & automation hub
+│   │   └── router.dart           # Room registration
+│   ├── media_room/               # Media management (future)
+│   │   └── router.dart           # Room registration
+│   └── settings/                 # User preferences
 └── chat/                         # Tatlock chat - omnipresent, NOT a room
 ```

@@ -44,13 +51,16 @@ lib/
 |---------|-----------|---------|
 | Front Hall | `features/front_hall/` | Dashboard, overview, quick access |
 | Control Room | `features/control_room/` | Infrastructure management |
-| Parlor | `features/parlor/` | Home automation |
-| Library | `features/library/` | Knowledge, docs, bookmarks |
-| Study | `features/study/` | Email, calendar (hidden for now) |
+| Security | `features/security/` | User & access management |
+| Parlor | `features/parlor/` | AI chat & automation hub |
+| Media Room | `features/media_room/` | Media management (future) |
+| *(non-room)* | `features/settings/` | User preferences |
 | *(omnipresent)* | `chat/` | Tatlock assistant dock |

 Note: `chat/` lives at the top level of `lib/` (not under `features/`) because it's not a navigable room - it's an omnipresent dock injected at the layout level.

+Each room has a `router.dart` file that registers the room with the central registry. See [Room Registry Pattern](#room-registry-pattern) for details.
+
 ## Feature Structure

 Each feature follows a three-layer architecture:
@@ -142,7 +152,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,
@@ -197,6 +207,139 @@ class ContainerRepositoryImpl implements ContainerRepository {
 }
 ```

+## Data Model Patterns
+
+Models handle conversion between API JSON and domain entities. The pattern depends on whether the feature is **read-only** or **CRUD**.
+
+### Read-Only Models
+
+For data fetched from external systems (Docker, NPM, Portainer) where Flutter doesn't create/update records:
+
+```dart
+@freezed
+sealed class ContainerModel with _$ContainerModel {
+  const factory ContainerModel({
+    required String id,
+    required String name,
+    required String status,
+  }) = _ContainerModel;
+
+  const ContainerModel._();
+
+  factory ContainerModel.fromJson(Map<String, dynamic> json) =>
+      _$ContainerModelFromJson(json);
+
+  /// Converts API response to domain entity.
+  Container toEntity() => Container(
+    id: id,
+    name: name,
+    status: ContainerStatus.values.byName(status),
+  );
+}
+```
+
+**Only `toEntity()` is needed** - no `fromEntity()` or `toJson()` required.
+
+### CRUD Models (Bidirectional)
+
+For data that Flutter creates, updates, and deletes:
+
+```dart
+@freezed
+sealed class QuickLinkModel with _$QuickLinkModel {
+  const factory QuickLinkModel({
+    @Default(0) int id,
+    required String title,
+    required String url,
+    String? icon,
+    String? category,
+    @Default(0) int position,
+    @JsonKey(name: 'is_visible') @Default(true) bool isVisible,
+  }) = _QuickLinkModel;
+
+  const QuickLinkModel._();
+
+  factory QuickLinkModel.fromJson(Map<String, dynamic> json) =>
+      _$QuickLinkModelFromJson(json);
+
+  /// Converts API response to domain entity.
+  QuickLink toEntity() => QuickLink(
+    id: id.toString(),
+    name: title,
+    url: url,
+    iconName: icon ?? 'link',
+    category: category,
+    sortOrder: position,
+    isActive: isVisible,
+  );
+
+  /// Creates model from domain entity for API requests.
+  factory QuickLinkModel.fromEntity(QuickLink entity) => QuickLinkModel(
+    id: int.tryParse(entity.id) ?? 0,
+    title: entity.name,
+    url: entity.url,
+    icon: entity.iconName,
+    category: entity.category,
+    position: entity.sortOrder,
+    isVisible: entity.isActive,
+  );
+}
+```
+
+**Critical rules for CRUD models:**
+
+1. **Always use generated `toJson()`** - Never write custom JSON methods that selectively include fields. The generated `toJson()` from freezed/json_serializable always includes ALL fields, which is the correct behavior.
+
+2. **Never create custom `toCreateJson()` or similar** - This leads to bugs where fields are silently dropped.
+
+3. **Use `fromEntity()` factory** - Maps domain entity fields to API field names.
+
+### Form Update Pattern
+
+When updating existing entities in forms, **always use `copyWith()`** to preserve existing data:
+
+```dart
+// ✅ Correct - preserves all existing fields
+final updatedLink = existingLink.copyWith(
+  name: _nameController.text.trim(),
+  url: _urlController.text.trim(),
+  category: category.isEmpty ? null : category,
+);
+await actions.update(updatedLink);
+
+// ❌ Wrong - loses existing data not in form
+final newLink = QuickLink(
+  id: existingLink.id,
+  name: _nameController.text.trim(),
+  url: _urlController.text.trim(),
+  // Missing: sortOrder, other fields...
+);
+```
+
+### Datasource Usage
+
+```dart
+// Create - convert entity to model, use toJson()
+Future<QuickLink> createQuickLink(QuickLink link) async {
+  final model = QuickLinkModel.fromEntity(link);
+  final response = await _dio.post<Map<String, dynamic>>(
+    _basePath,
+    data: model.toJson(), // Always use generated toJson()
+  );
+  return QuickLinkModel.fromJson(response.data!).toEntity();
+}
+
+// Update - same pattern
+Future<QuickLink> updateQuickLink(QuickLink link) async {
+  final model = QuickLinkModel.fromEntity(link);
+  final response = await _dio.put<Map<String, dynamic>>(
+    '$_basePath/${link.id}',
+    data: model.toJson(), // Always use generated toJson()
+  );
+  return QuickLinkModel.fromJson(response.data!).toEntity();
+}
+```
+
 ### Presentation Layer (Flutter + Riverpod)

 The presentation layer contains UI code and state management.
@@ -287,6 +430,41 @@ ContainerRepository containerRepository(Ref ref) {
 }
 ```

+### Persistent Providers
+
+By default, `@riverpod` generates providers with `isAutoDispose: true`, meaning they dispose when no longer watched. This causes issues for:
+
+- **API clients** with interceptors that store a `Ref`
+- **App-level state** like theme, auth, config
+- **Providers with listeners** to other providers
+
+Use `@persistentRiverpod` from `core/providers/annotations.dart` for these cases:
+
+```dart
+import 'package:tatlock_ui/core/providers/annotations.dart';
+
+// ✅ Correct - persists for app lifetime
+@persistentRiverpod
+Dio coreApiClient(Ref ref) { ... }
+
+@persistentRiverpod
+class ThemeNotifier extends _$ThemeNotifier { ... }
+
+// ❌ Wrong - auto-dispose can invalidate stored Ref
+@riverpod
+Dio coreApiClient(Ref ref) { ... }
+```
+
+**When to use `@persistentRiverpod`:**
+
+| Use Case | Annotation | Example |
+|----------|------------|---------|
+| API clients with interceptors | `@persistentRiverpod` | `coreApiClient`, `tatlockApiClient` |
+| Auth state provider | `@persistentRiverpod` | `AuthNotifier` |
+| Theme/config providers | `@persistentRiverpod` | `ThemeNotifier` |
+| Feature data providers | `@riverpod` (default) | `ContainersNotifier` |
+| UI state providers | `@riverpod` (default) | `SearchFilterNotifier` |
+
 ## File Naming Conventions

 | Type | Convention | Example |
@@ -331,6 +509,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/`
@@ -348,3 +554,172 @@ import 'package:tatlock_ui/features/containers/domain/entities/container.dart';
 // Bad - importing model in presentation
 import '../data/models/container_model.dart'; // Don't do this
 ```
+
+## Semantic Identifiers for Automation
+
+All interactive widgets should have semantic identifiers for UI automation. This enables reliable testing with Puppeteer, Appium, and other automation tools.
+
+### Quick Reference
+
+```dart
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+
+// Wrap interactive widgets with Semantics
+Semantics(
+  identifier: DataGridSemantics.row(item.id),
+  label: 'Select ${item.name}',
+  child: MyRowWidget(item: item),
+)
+```
+
+### Key Points
+
+1. **Central ID Registry** - All IDs defined in `lib/core/semantics/semantic_ids.dart`
+2. **Naming Convention** - `{area}_{component}_{identifier}` (e.g., `dataGrid_row_abc123`)
+3. **Web Enabled** - Semantics tree exposed via `SemanticsBinding.instance.ensureSemantics()` in `main.dart`
+
+For complete documentation on semantic patterns, automation queries, and best practices, see **[TESTING.md](./TESTING.md)**.
+
+## Room Registry Pattern
+
+The application uses a **decentralized room registry** pattern for navigation. Each feature/room registers itself with the central registry, providing:
+
+- **Decoupled navigation** - Rooms define their own routes, icons, and metadata
+- **Permission-based filtering** - Rooms can specify required permissions
+- **Dynamic UI** - Settings dropdowns and tab bars build from registry
+- **Single source of truth** - All room metadata in one place per room
+
+### Architecture
+
+```
+lib/routing/room_registry.dart          # Central registry class
+lib/features/{room}/router.dart         # Per-room registration
+```
+
+### Room Definition
+
+Each room's `router.dart` exports a `RoomDefinition` and register function:
+
+```dart
+// lib/features/control_room/router.dart
+import 'package:tatlock_ui/routing/room_registry.dart';
+
+/// Room definition with all metadata.
+final controlRoomRoom = RoomDefinition(
+  id: 'control-room',              // Preference value, URL segment
+  label: 'Control Room',           // Display name
+  icon: Icons.dns_outlined,        // Unselected icon
+  selectedIcon: Icons.dns,         // Selected icon
+  defaultRoute: '/control-room/containers',  // Landing route
+  routes: controlRoomRoutes,       // Function returning List<RouteBase>
+  requiredPermissions: [],         // Empty = accessible to all
+);
+
+/// Register with the central registry.
+void registerControlRoom() {
+  roomRegistry.register(controlRoomRoom);
+}
+
+/// Routes for go_router.
+List<RouteBase> controlRoomRoutes() {
+  return [
+    GoRoute(path: '/control-room', ...),
+    // Sub-routes...
+  ];
+}
+```
+
+### Registration Order
+
+Rooms are registered in `app_router.dart` in display order:
+
+```dart
+void _initializeRoomRegistry() {
+  if (roomRegistry.all.isNotEmpty) return; // Skip if initialized
+
+  // Registration order = tab order
+  registerFrontHall();
+  registerControlRoom();
+  registerSecurity();
+  registerParlor();
+  registerMediaRoom();
+}
+```
+
+### Using the Registry
+
+**Navigation tabs** (`top_header_bar.dart`):
+```dart
+List<RoomDefinition> get _rooms => roomRegistry.all;
+
+// Build tab for each room
+for (final room in _rooms) {
+  IconButton(
+    icon: Icon(isSelected ? room.selectedIcon : room.icon),
+    onPressed: () => onRoomSelected(index),
+  );
+}
+```
+
+**Settings dropdown**:
+```dart
+DropdownButton<String>(
+  items: roomRegistry.all
+      .map((room) => DropdownMenuItem(
+            value: room.id,
+            child: Text(room.label),
+          ))
+      .toList(),
+);
+```
+
+**Router** - All routes from registry:
+```dart
+ShellRoute(
+  routes: [
+    ...roomRegistry.allRoutes(),
+    // Plus non-room routes like /settings
+  ],
+);
+```
+
+**Route matching**:
+```dart
+int _selectedIndex(BuildContext context) {
+  final location = GoRouterState.of(context).matchedLocation;
+  return roomRegistry.indexOfRoute(location);
+}
+```
+
+### Permission Filtering
+
+Rooms can specify required permissions:
+
+```dart
+final adminRoom = RoomDefinition(
+  id: 'admin',
+  requiredPermissions: ['admin:access'],
+  // ...
+);
+
+// Filter by user permissions
+final accessibleRooms = roomRegistry.accessibleTo(userPermissions);
+```
+
+### Adding a New Room
+
+1. Create feature folder: `lib/features/{room_name}/`
+2. Create `router.dart` with `RoomDefinition` and register function
+3. Create placeholder page in `presentation/pages/{room_name}_page.dart`
+4. Add `register{RoomName}()` call to `_initializeRoomRegistry()` in `app_router.dart`
+5. Import the router in `app_router.dart`
+
+### Current Rooms
+
+| Room | ID | Default Route |
+|------|-----|---------------|
+| Front Hall | `front-hall` | `/front-hall` |
+| Control Room | `control-room` | `/control-room/containers` |
+| Security | `security` | `/security/users` |
+| Parlor | `parlor` | `/parlor` |
+| Media Room | `media-room` | `/media-room` |
@@ -0,0 +1,368 @@
+# Testing & Automation Guide
+
+This document covers automated testing patterns for Tatlock UI, focusing on semantic identifiers that enable reliable UI automation.
+
+## Overview
+
+Tatlock UI uses Flutter's **Semantics tree** to expose stable identifiers for automated testing. These identifiers are accessible to:
+
+- **Puppeteer** (via Chrome DevTools accessibility API)
+- **Appium** (via accessibility labels)
+- **WebDriver** (via ARIA attributes)
+- **Flutter integration tests**
+
+The semantics system is enabled on web in `main.dart`:
+
+```dart
+if (kIsWeb) {
+  SemanticsBinding.instance.ensureSemantics();
+}
+```
+
+## Semantic Identifiers
+
+All semantic IDs are centralized in `lib/core/semantics/semantic_ids.dart`. This provides:
+
+1. **Stable selectors** - IDs don't change with UI refactoring
+2. **Type safety** - Compile-time verification of ID usage
+3. **Discoverability** - Single source of truth for automation targets
+
+### Available ID Classes
+
+| Class | Purpose | Example IDs |
+|-------|---------|-------------|
+| `ProfileSemantics` | User profile dropdown | `profile_button`, `profile_menu_settings` |
+| `RoomTabSemantics` | Main navigation tabs | `roomTab_frontHall`, `roomTab_controlRoom` |
+| `NavSemantics` | Side navigation panel | `nav_panel`, `nav_item_{id}` |
+| `DataGridSemantics` | Data tables | `dataGrid_row_{id}`, `dataGrid_search` |
+| `DialogSemantics` | Modal dialogs | `dialog_confirm`, `dialog_cancel` |
+| `SettingsSemantics` | Settings page | `settings_theme`, `settings_defaultRoom` |
+| `StateSemantics` | Loading/error states | `state_auth_loading`, `snackbar_{type}` |
+
+### ID Naming Convention
+
+```
+{area}_{component}_{identifier}
+```
+
+- **area**: Feature or section (e.g., `profile`, `nav`, `dataGrid`)
+- **component**: Widget type (e.g., `menu`, `button`, `row`)
+- **identifier**: Specific item (e.g., `light`, `settings`, `selectAll`)
+
+Examples:
+- `profile_menu_theme_dark` - Dark theme option in profile menu
+- `dataGrid_row_abc123` - Row with ID "abc123" in data grid
+- `nav_item_containers` - Containers nav item
+
+## Adding Semantics to Widgets
+
+### Method 1: Direct Semantics Widget
+
+Use Flutter's `Semantics` widget with the `identifier` property:
+
+```dart
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+
+Semantics(
+  identifier: ProfileSemantics.button,
+  label: 'Open profile menu',
+  button: true,
+  child: IconButton(
+    icon: Icon(Icons.person),
+    onPressed: () => ...,
+  ),
+)
+```
+
+### Method 2: SemanticWidget Wrapper
+
+Use the convenience wrapper from `lib/core/semantics/semantic_widget.dart`:
+
+```dart
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+import 'package:tatlock_ui/core/semantics/semantic_widget.dart';
+
+SemanticWidget(
+  id: DataGridSemantics.search,
+  label: 'Search data grid',
+  textField: true,
+  child: TextField(
+    decoration: InputDecoration(hintText: 'Search...'),
+  ),
+)
+```
+
+### Method 3: Extension Method
+
+Use the `withSemantics` extension for inline wrapping:
+
+```dart
+TextField(
+  decoration: InputDecoration(hintText: 'Search...'),
+).withSemantics(
+  id: DataGridSemantics.search,
+  label: 'Search data grid',
+)
+```
+
+### Dynamic IDs
+
+For lists and grids, use the generator methods:
+
+```dart
+// Row in a data grid
+Semantics(
+  identifier: DataGridSemantics.row(item.id),  // "dataGrid_row_abc123"
+  child: DataGridRow(item: item),
+)
+
+// Navigation item
+Semantics(
+  identifier: NavSemantics.item(route.id),  // "nav_item_containers"
+  child: NavItem(route: route),
+)
+
+// Bulk action button
+Semantics(
+  identifier: DataGridSemantics.bulkAction('delete'),  // "dataGrid_bulk_delete"
+  child: IconButton(icon: Icon(Icons.delete), ...),
+)
+```
+
+## Querying from Puppeteer
+
+Puppeteer can query semantic identifiers via Chrome's accessibility tree:
+
+```javascript
+// Connect to Chrome with DevTools protocol
+const browser = await puppeteer.connect({
+  browserURL: 'http://localhost:9222'
+});
+const page = await browser.newPage();
+
+// Get accessibility snapshot
+const snapshot = await page.accessibility.snapshot({ interestingOnly: false });
+
+// Find element by semantic identifier
+function findBySemanticId(node, id) {
+  if (node.name === id || node.description === id) {
+    return node;
+  }
+  for (const child of node.children || []) {
+    const found = findBySemanticId(child, id);
+    if (found) return found;
+  }
+  return null;
+}
+
+// Example: Find profile button
+const profileButton = findBySemanticId(snapshot, 'profile_button');
+
+// Example: Find a specific data grid row
+const row = findBySemanticId(snapshot, 'dataGrid_row_abc123');
+```
+
+### Using Chrome DevTools MCP
+
+With the Chrome DevTools MCP server, you can query semantics directly:
+
+```javascript
+// Take a snapshot (returns accessibility tree)
+const snapshot = await mcp__chrome_devtools__take_snapshot();
+
+// Click by semantic ID (uid in snapshot)
+await mcp__chrome_devtools__click({ uid: 'profile_button' });
+
+// Fill input by semantic ID
+await mcp__chrome_devtools__fill({
+  uid: 'dataGrid_search',
+  value: 'my search query'
+});
+```
+
+## Best Practices
+
+### 1. Add Semantics to Interactive Elements
+
+Every clickable, tappable, or input element should have a semantic identifier:
+
+```dart
+// Buttons
+Semantics(
+  identifier: 'myFeature_submit',
+  button: true,
+  label: 'Submit form',
+  child: ElevatedButton(...),
+)
+
+// Text fields
+Semantics(
+  identifier: 'myFeature_email',
+  textField: true,
+  label: 'Email address',
+  child: TextField(...),
+)
+
+// Checkboxes
+Semantics(
+  identifier: 'myFeature_rememberMe',
+  checked: isChecked,
+  label: 'Remember me',
+  child: Checkbox(...),
+)
+```
+
+### 2. Use Meaningful Labels
+
+Labels help both accessibility tools and test debugging:
+
+```dart
+// Good - descriptive label
+Semantics(
+  identifier: DataGridSemantics.rowAction(item.id, 'delete'),
+  label: 'Delete ${item.name}',
+  button: true,
+  child: ...,
+)
+
+// Bad - no context
+Semantics(
+  identifier: 'btn1',
+  child: ...,
+)
+```
+
+### 3. Register New IDs Centrally
+
+Always add new semantic IDs to `semantic_ids.dart`:
+
+```dart
+/// My new feature IDs.
+abstract class MyFeatureSemantics {
+  static const submitButton = 'myFeature_submit';
+  static const cancelButton = 'myFeature_cancel';
+  static const nameField = 'myFeature_name';
+
+  /// Generate ID for a list item.
+  static String item(String id) => 'myFeature_item_$id';
+}
+```
+
+### 4. Test ID Stability
+
+Semantic IDs should remain stable across releases. When refactoring:
+
+- Keep existing IDs unchanged
+- Add deprecation comments if IDs must change
+- Update automation tests when IDs change
+
+### 5. Exclude Decorative Elements
+
+Don't add semantic IDs to purely decorative elements:
+
+```dart
+// Decorative icon - no semantics needed
+Icon(Icons.star, color: Colors.yellow)
+
+// Interactive icon - needs semantics
+Semantics(
+  identifier: 'rating_star_3',
+  button: true,
+  label: 'Rate 3 stars',
+  child: IconButton(
+    icon: Icon(Icons.star),
+    onPressed: () => rate(3),
+  ),
+)
+```
+
+## DataGrid Semantic Patterns
+
+The DataGrid component has comprehensive semantic coverage:
+
+```
+dataGrid                     - The grid container
+dataGrid_search              - Search input field
+dataGrid_search_clear        - Clear search button
+dataGrid_selectAll           - Select all checkbox
+dataGrid_header_{columnId}   - Column header (sortable)
+dataGrid_row_{itemId}        - Row container
+dataGrid_row_{itemId}_checkbox    - Row selection checkbox
+dataGrid_row_{itemId}_actions     - Row actions menu trigger
+dataGrid_row_{itemId}_action_{actionId}  - Specific row action
+dataGrid_bulk_{actionId}     - Bulk action button
+dataGrid_bulk_clear          - Clear selection button
+dataGrid_loading             - Loading indicator
+dataGrid_empty               - Empty state message
+dataGrid_error               - Error state message
+dataGrid_refresh             - Refresh button
+```
+
+### Example: Automating DataGrid Selection
+
+```javascript
+// Select all rows
+await click('dataGrid_selectAll');
+
+// Select specific row
+await click('dataGrid_row_abc123_checkbox');
+
+// Perform bulk delete
+await click('dataGrid_bulk_delete');
+
+// Confirm in dialog
+await click('dialog_confirm');
+```
+
+## Debugging Semantics
+
+### Flutter DevTools
+
+1. Open Flutter DevTools
+2. Go to "Inspector" tab
+3. Enable "Semantics" overlay
+4. Click widgets to see their semantic properties
+
+### Chrome DevTools
+
+1. Open DevTools (F12)
+2. Go to "Accessibility" tab
+3. Inspect the accessibility tree
+4. Search for semantic identifiers
+
+### Programmatic Inspection
+
+```dart
+// In a test, dump the semantics tree
+debugDumpSemanticsTree();
+
+// Check if semantics are enabled
+print('Semantics enabled: ${SemanticsBinding.instance.semanticsEnabled}');
+```
+
+## Integration with URL Routing
+
+For deep-linkable test scenarios, semantic IDs work with URL query parameters:
+
+```
+/control-room/containers?selected=abc123
+```
+
+Automation can:
+1. Navigate to URL with query params
+2. Verify selection state via `dataGrid_row_abc123_checkbox` (checked: true)
+3. Interact with selected rows via semantic IDs
+
+See [URL Routing](#url-routing) section for query parameter patterns.
+
+## Checklist for New Features
+
+When adding a new feature, ensure semantic coverage:
+
+- [ ] Add semantic ID class to `semantic_ids.dart`
+- [ ] Wrap all buttons with `Semantics` + `identifier`
+- [ ] Wrap all inputs with `Semantics` + `identifier`
+- [ ] Wrap list/grid items with dynamic IDs
+- [ ] Add labels for accessibility
+- [ ] Test that IDs appear in accessibility snapshot
+- [ ] Document IDs in this file if they establish new patterns
@@ -191,13 +191,81 @@ The NavPanel widget receives items and auto-generates section headers based on u
 ## Panel Configurations by Room

 ### Front Hall
+
+Front Hall uses a **three-mode content system** with a persistent QuickLinks panel:
+
+| Mode | QuickLinks Panel | Content Area |
+|------|------------------|--------------|
+| **Dashboard** | Normal navigation | Dashboard widgets (stats, weather) |
+| **Iframe** | Normal navigation | Embedded iframe content |
+| **Settings** | Edit mode (back button, add new, overflow menus) | QuickLinkPage (EntityPageScaffold) |
+
+#### Dashboard Mode (default)
 ```
-┌────────────────────────────────────────────────────────────────┬────────────┐
-│  PRIMARY CONTENT (no nav panel)                                │ CHAT DOCK  │
-│  Dashboard cards, activity feed                                │ (expanded) │
-└────────────────────────────────────────────────────────────────┴────────────┘
+┌──────────────┬─────────────────────────────────────────────────┬────────────┐
+│ QUICK LINKS  │  PRIMARY CONTENT                                │ CHAT DOCK  │
+│              │                                                 │ (expanded) │
+│ ▌HOME        │  SYSTEM STATS                                   │            │
+│   Jellyfin   │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐           │            │
+│   WebUI      │  │ CPU  │ │ MEM  │ │ DISK │ │ NET  │           │            │
+│              │  └──────┘ └──────┘ └──────┘ └──────┘           │            │
+│ ▌AMP         │                                                 │            │
+│   AMP Home   │  WEATHER              AIR QUALITY               │            │
+│              │  ┌────────────────┐   ┌────────────────┐        │            │
+│ ▌INFRA       │  │ 72°F Sunny     │   │ AQI: 42 Good   │        │            │
+│   Netdata    │  └────────────────┘   └────────────────┘        │            │
+│              │                                                 │            │
+│ [⚙ Settings] │                                                 │            │
+└──────────────┴─────────────────────────────────────────────────┴────────────┘
 ```

+#### Iframe Mode
+```
+┌──────────────┬─────────────────────────────────────────────────┬────────────┐
+│ QUICK LINKS  │ ┌─────────────────────────────────────────────┐ │ CHAT DOCK  │
+│              │ │ Jellyfin          [↗] [⟳] [✕]              │ │ (collapsed)│
+│ ▌HOME        │ ├─────────────────────────────────────────────┤ │            │
+│  ▸Jellyfin   │ │                                             │ │            │
+│   WebUI      │ │        <iframe src="jellyfin.url">          │ │            │
+│              │ │                                             │ │            │
+│ ▌AMP         │ │                                             │ │            │
+│   AMP Home   │ │                                             │ │            │
+│              │ │                                             │ │            │
+│ ▌INFRA       │ │                                             │ │            │
+│   Netdata    │ │                                             │ │            │
+│              │ └─────────────────────────────────────────────┘ │            │
+│ [⚙ Settings] │                                                 │            │
+└──────────────┴─────────────────────────────────────────────────┴────────────┘
+```
+
+#### Settings Mode
+```
+┌──────────────┬─────────────────────────────────────────────────┬────────────┐
+│ [←] Links    │ ┌─────────────────────────────────────────────┐ │ CHAT DOCK  │
+│              │ │ ← Back    Edit Quick Link         [Save]    │ │ (collapsed)│
+│ [+ Add New]  │ ├─────────────────────────────────────────────┤ │            │
+├──────────────┤ │                                             │ │            │
+│ ▌HOME        │ │  Name:     [Jellyfin_________________]      │ │            │
+│  ▸Jellyfin ⋮ │ │                                             │ │            │
+│   WebUI    ⋮ │ │  URL:      [https://jellyfin.schweitz...]   │ │            │
+│              │ │                                             │ │            │
+│ ▌AMP         │ │  Category: [Home ▼]                         │ │            │
+│   AMP Home ⋮ │ │                                             │ │            │
+│              │ │  Type:     ◉ Iframe  ○ New Tab              │ │            │
+│ ▌INFRA       │ │                                             │ │            │
+│   Netdata  ⋮ │ │  Icon:     [🎬 Pick...]                     │ │            │
+│   Portainer⋮ │ │                                             │ │            │
+│              │ │  Active:   [✓]                              │ │            │
+└──────────────┴─────────────────────────────────────────────────┴────────────┘
+```
+
+**Settings mode panel behavior:**
+- Back button in header (exits settings mode → dashboard)
+- "+ Add New Link" button at top
+- Each item has overflow menu (Edit, Delete, Move Up/Down)
+- Clicking item selects it for editing in content area
+- Uses EntityPageScaffold pattern (no modals)
+
 ### Control Room
 ```
 ┌───────────┬──────────────────────────────────────────────────────┬──────────┐
@@ -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>
@@ -2,24 +2,28 @@ 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;

 part 'api_client.g.dart';

 /// Provides the Dio instance for Core API.
-@riverpod
+@persistentRiverpod
 Dio coreApiClient(Ref ref) {
-  final dio = Dio(
-    BaseOptions(
-      baseUrl: AppConfig.coreApiUrl,
-      connectTimeout: const Duration(seconds: 10),
-      receiveTimeout: const Duration(seconds: 30),
-      headers: {
-        'Content-Type': 'application/json',
-        'Accept': 'application/json',
-      },
-    ),
+  final options = BaseOptions(
+    baseUrl: AppConfig.coreApiUrl,
+    connectTimeout: const Duration(seconds: 10),
+    receiveTimeout: const Duration(seconds: 30),
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+    },
  );

+  final dio = platform.createDio(options);
+
  dio.interceptors.addAll([
    AuthInterceptor(ref),
    LoggingInterceptor(),
@@ -30,20 +34,20 @@ Dio coreApiClient(Ref ref) {
 }

 /// Provides the Dio instance for Tatlock API.
-@riverpod
+@persistentRiverpod
 Dio tatlockApiClient(Ref ref) {
-  final dio = Dio(
-    BaseOptions(
-      baseUrl: AppConfig.tatlockApiUrl,
-      connectTimeout: const Duration(seconds: 10),
-      receiveTimeout: const Duration(minutes: 5), // Longer for LLM responses
-      headers: {
-        'Content-Type': 'application/json',
-        'Accept': 'application/json',
-      },
-    ),
+  final options = BaseOptions(
+    baseUrl: AppConfig.tatlockApiUrl,
+    connectTimeout: const Duration(seconds: 10),
+    receiveTimeout: const Duration(minutes: 5), // Longer for LLM responses
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+    },
  );

+  final dio = platform.createDio(options);
+
  dio.interceptors.addAll([
    AuthInterceptor(ref),
    LoggingInterceptor(),
@@ -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);
+}
@@ -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;
+}
@@ -1,6 +1,7 @@
 import 'dart:developer' as developer;

 import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:tatlock_ui/core/auth/auth_provider.dart';
 import 'package:tatlock_ui/core/config/app_config.dart';
@@ -8,7 +9,8 @@ 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 + Mobile**: Adds Bearer token from OIDC authentication
 class AuthInterceptor extends Interceptor {
  AuthInterceptor(this._ref);

@@ -22,6 +24,7 @@ class AuthInterceptor extends Interceptor {
      return;
    }

+    // Add Bearer token for all platforms (web + mobile)
    final authState = _ref.read(authProvider);

    authState.whenData((auth) {
@@ -35,47 +38,66 @@ class AuthInterceptor extends Interceptor {

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
-    // Skip auth error handling for LAN development
-    if (!AppConfig.requiresAuth) {
-      handler.next(err);
-      return;
-    }
-
-    if (err.response?.statusCode == 401) {
-      // Token expired - trigger re-authentication
-      _ref.read(authProvider.notifier).signOut();
-    }
+    // Don't auto-signout on 401 - let calling code handle auth errors gracefully.
+    // Auto-signout was causing issues (e.g., theme toggle triggering logout when
+    // preferences API returned 401).
    handler.next(err);
  }
 }

-/// Logs requests and responses in debug mode.
+/// Logs API requests and responses to the console.
+///
+/// All requests are logged with method, URL, query params, and body.
+/// Responses include status code. Errors include full details.
 class LoggingInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
-    developer.log(
-      '→ ${options.method} ${options.uri}',
-      name: 'api',
-    );
+    final buffer = StringBuffer()
+      ..writeln('┌── API Request ──────────────────────────────────────')
+      ..writeln('│ ${options.method} ${options.path}');
+
+    if (options.queryParameters.isNotEmpty) {
+      buffer.writeln('│ Query: ${options.queryParameters}');
+    }
+
+    if (options.data != null) {
+      buffer.writeln('│ Body: ${options.data}');
+    }
+
+    buffer.writeln('└─────────────────────────────────────────────────────');
+
+    final message = buffer.toString();
+    developer.log(message, name: 'API');
+    debugPrint(message);
    handler.next(options);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
-    developer.log(
-      '← ${response.statusCode} ${response.requestOptions.uri}',
-      name: 'api',
-    );
+    final message =
+        '✓ ${response.statusCode} ${response.requestOptions.method} ${response.requestOptions.path}';
+    developer.log(message, name: 'API');
+    debugPrint(message);
    handler.next(response);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
-    developer.log(
-      '✗ ${err.response?.statusCode ?? 'NETWORK'} ${err.requestOptions.uri}: ${err.message}',
-      name: 'api',
-      error: err,
-    );
+    final buffer = StringBuffer()
+      ..writeln('┌── API Error ────────────────────────────────────────')
+      ..writeln('│ ${err.requestOptions.method} ${err.requestOptions.path}')
+      ..writeln('│ Status: ${err.response?.statusCode ?? 'NETWORK ERROR'}')
+      ..writeln('│ Message: ${err.message}');
+
+    if (err.response?.data != null) {
+      buffer.writeln('│ Response: ${err.response?.data}');
+    }
+
+    buffer.writeln('└─────────────────────────────────────────────────────');
+
+    final message = buffer.toString();
+    developer.log(message, name: 'API', error: err);
+    debugPrint(message);
    handler.next(err);
  }
 }
@@ -0,0 +1,288 @@
+import 'dart:convert' show jsonDecode, jsonEncode;
+import 'dart:developer' as developer;
+
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart' show kIsWeb;
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../config/app_config.dart';
+import 'auth_datasource.dart';
+import 'auth_state.dart';
+import 'oidc_service_web.dart';
+import 'permissions.dart';
+import 'user_preferences.dart';
+import 'web_utils.dart' as web_utils;
+
+/// Standalone auth controller that handles OIDC flow before app starts.
+///
+/// This runs outside of Riverpod to avoid lifecycle issues. Call [initialize]
+/// in main() before runApp(). The controller will:
+/// 1. Handle callback if on /callback route (exchange code, sync, store tokens)
+/// 2. Check for valid stored tokens
+/// 3. Redirect to silent OIDC if no tokens (app won't continue)
+///
+/// Once auth is complete, [AuthProvider] can simply read the stored tokens.
+class AuthController {
+  // Storage keys (same as AuthProvider)
+  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';
+
+  /// Initialize auth before app starts.
+  ///
+  /// Returns true if auth is ready (tokens available).
+  /// Returns false if redirecting (app should not continue).
+  /// Throws on error.
+  static Future<bool> initialize() async {
+    // Skip auth entirely for LAN mode
+    if (!AppConfig.requiresAuth) {
+      developer.log('Auth not required (LAN mode)', name: 'auth_controller');
+      return true;
+    }
+
+    // Only handle web auth here - mobile uses different flow
+    if (!kIsWeb) {
+      developer.log('Non-web platform, skipping controller init', name: 'auth_controller');
+      return true;
+    }
+
+    final currentUrl = web_utils.getCurrentUrl();
+    developer.log('Auth controller init, URL: $currentUrl', name: 'auth_controller');
+
+    // Check if we're on the callback route
+    if (currentUrl.contains('/callback')) {
+      return _handleCallback(currentUrl);
+    }
+
+    // Check for valid stored tokens
+    final prefs = await SharedPreferences.getInstance();
+    final accessToken = prefs.getString(_accessTokenKey);
+    if (accessToken != null) {
+      final expiresAtMs = prefs.getInt(_expiresAtKey);
+      final expiresAt = expiresAtMs != null
+          ? DateTime.fromMillisecondsSinceEpoch(expiresAtMs)
+          : null;
+
+      if (expiresAt == null || expiresAt.isAfter(DateTime.now())) {
+        developer.log('Valid tokens found', name: 'auth_controller');
+        return true; // Auth ready
+      }
+      developer.log('Tokens expired', name: 'auth_controller');
+    }
+
+    // No valid tokens - initiate silent OIDC
+    developer.log('No valid tokens, starting silent OIDC', name: 'auth_controller');
+    await _initiateSilentOidc();
+    return false; // Redirecting, app should not continue
+  }
+
+  /// Handle the OIDC callback.
+  static Future<bool> _handleCallback(String url) async {
+    final uri = Uri.parse(url);
+    final code = uri.queryParameters['code'];
+    final state = uri.queryParameters['state'];
+    final error = uri.queryParameters['error'];
+
+    developer.log('Handling callback: code=${code != null}, error=$error', name: 'auth_controller');
+
+    // Handle errors
+    if (error != null) {
+      if (error == 'login_required') {
+        // Silent auth failed - no session, start regular OIDC
+        developer.log('Silent auth failed (login_required), starting regular OIDC', name: 'auth_controller');
+        await _initiateRegularOidc();
+        return false;
+      }
+      throw Exception('Auth error: $error - ${uri.queryParameters['error_description']}');
+    }
+
+    if (code == null || state == null) {
+      throw Exception('Invalid callback - missing code or state');
+    }
+
+    // Exchange code for tokens
+    developer.log('Exchanging code for tokens', name: 'auth_controller');
+    final oidcService = OidcServiceWeb();
+    final tokens = await oidcService.exchangeCode(code, state);
+
+    // Sync with core-api
+    developer.log('Syncing with core-api', name: 'auth_controller');
+    final dio = Dio(BaseOptions(
+      baseUrl: AppConfig.coreApiUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    ));
+    final authDatasource = AuthDatasource(dio);
+    final syncResponse = await authDatasource.syncUser(tokens.accessToken);
+
+    developer.log('Synced user: ${syncResponse.name}', name: 'auth_controller');
+
+    // Store credentials
+    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,
+    );
+
+    // Redirect to home (removes callback params from URL)
+    developer.log('Auth complete, redirecting to home', name: 'auth_controller');
+    web_utils.redirectTo('/');
+    return false; // Redirecting
+  }
+
+  /// Initiate silent OIDC (prompt=none).
+  static Future<void> _initiateSilentOidc() async {
+    final oidcService = OidcServiceWeb();
+    final authUrl = await oidcService.getAuthorizationUrl(silent: true);
+    developer.log('Redirecting to silent OIDC', name: 'auth_controller');
+    web_utils.redirectTo(authUrl);
+  }
+
+  /// Initiate regular OIDC (shows login UI).
+  static Future<void> _initiateRegularOidc() async {
+    final oidcService = OidcServiceWeb();
+    final authUrl = await oidcService.getAuthorizationUrl(silent: false);
+    developer.log('Redirecting to regular OIDC', name: 'auth_controller');
+    web_utils.redirectTo(authUrl);
+  }
+
+  /// Store auth data.
+  static 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();
+
+    await prefs.setString(_accessTokenKey, accessToken);
+    if (refreshToken != null) {
+      await prefs.setString(_refreshTokenKey, refreshToken);
+    }
+    if (expiresAt != null) {
+      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);
+
+    if (roles != null) {
+      final rolesJson = jsonEncode(roles.map((r) => {
+        'id': r.id,
+        'name': r.name,
+        'domain': r.domain.value,
+        'category': r.category,
+        'action': r.action.name,
+      }).toList());
+      await prefs.setString(_rolesKey, rolesJson);
+    }
+
+    if (preferences != null) {
+      await prefs.setString(_preferencesKey, jsonEncode(preferences.toJson()));
+    }
+  }
+
+  /// Load stored auth state (for AuthProvider to use).
+  static Future<AuthState> loadStoredAuth() async {
+    try {
+      final prefs = await SharedPreferences.getInstance();
+
+      final accessToken = prefs.getString(_accessTokenKey);
+      if (accessToken == null) {
+        return const AuthState();
+      }
+
+      final expiresAtMs = prefs.getInt(_expiresAtKey);
+      final expiresAt = expiresAtMs != null
+          ? DateTime.fromMillisecondsSinceEpoch(expiresAtMs)
+          : null;
+
+      final rolesJson = prefs.getString(_rolesKey);
+      final roles = rolesJson != null ? _parseRoles(rolesJson) : <Role>[];
+
+      final prefsJson = prefs.getString(_preferencesKey);
+      final preferences = prefsJson != null
+          ? UserPreferences.fromJson(jsonDecode(prefsJson) as Map<String, dynamic>)
+          : null;
+
+      return 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,
+      );
+    } catch (e) {
+      developer.log('Failed to load stored auth: $e', name: 'auth_controller');
+      return const AuthState();
+    }
+  }
+
+  static 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) {
+      return [];
+    }
+  }
+
+  /// Clear stored auth (for logout).
+  static Future<void> clearAuth() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_accessTokenKey);
+    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);
+  }
+}
@@ -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/users/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));
+}
@@ -1,28 +1,49 @@
+import 'dart:convert' show jsonDecode, jsonEncode;
 import 'dart:developer' as developer;

+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 '../providers/annotations.dart';
+import 'auth_datasource.dart';
 import 'auth_state.dart';
+import 'oidc_service.dart';
+import 'oidc_service_web.dart';
+import 'permissions.dart';
+import 'user_preferences.dart';
+import 'web_utils.dart' as web_utils;

 part 'auth_provider.g.dart';

 /// Provides authentication state and operations.
 ///
-/// Note: Full OIDC implementation with flutter_appauth requires
-/// native platform configuration. For now, this provides the
-/// state management infrastructure.
-@riverpod
+/// Supports OIDC Authorization Code flow with PKCE on all platforms:
+/// - **Web**: Browser redirect to Authentik, callback via /callback route
+/// - **Mobile**: flutter_appauth with custom URL scheme
+///
+/// After OIDC authentication, syncs with core-api via POST /auth/sync
+/// to get user profile, roles, and preferences.
+@persistentRiverpod
 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 {
+    // AuthController.initialize() in main() handles OIDC flow before app starts.
+    // By the time we get here, tokens are already stored (or we're in LAN mode).
+    // Just load the stored auth state.
    return _loadStoredAuth();
  }

@@ -40,17 +61,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,29 +105,285 @@ 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**: Redirects to Authentik for OIDC authentication
+  /// - **Mobile**: Opens Authentik login via OIDC, then syncs with core-api
  Future<void> signIn() async {
-    // TODO: Implement OIDC flow with flutter_appauth
-    // For now, this is a placeholder that will be implemented
-    // when native platform configuration is complete.
-    developer.log('Sign in requested - OIDC not yet configured', name: 'auth');
+    if (!AppConfig.requiresAuth) {
+      developer.log('Auth not required in LAN mode', name: 'auth');
+      // In LAN mode, set a minimal authenticated state
+      state = const AsyncData(AuthState(isAuthenticated: true));
+      return;
+    }
+
+    // Web: Use OIDC flow with browser redirect
+    if (kIsWeb) {
+      developer.log('Web sign-in: starting OIDC flow', name: 'auth');
+      state = const AsyncLoading();
+
+      try {
+        final oidcService = OidcServiceWeb();
+        final authUrl = await oidcService.getAuthorizationUrl();
+        developer.log('Redirecting to: $authUrl', name: 'auth');
+        web_utils.redirectTo(authUrl);
+        // Browser will redirect, so we don't update state here
+      } catch (e, stack) {
+        developer.log('Failed to start OIDC flow: $e', name: 'auth');
+        state = AsyncError(e, stack);
+      }
+      return;
+    }
+
+    // Mobile: Use OIDC flow with flutter_appauth
+    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);
+    }
+  }
+
+  /// Handle OIDC callback after Authentik redirects back (web only).
+  ///
+  /// [code] is the authorization code from the callback URL.
+  /// [state] is the state parameter for CSRF verification.
+  Future<void> handleOidcCallback(String code, String callbackState) async {
+    if (!kIsWeb) {
+      developer.log('handleOidcCallback called on non-web platform', name: 'auth');
+      return;
+    }
+
+    developer.log('Handling OIDC callback', name: 'auth');
+    state = const AsyncLoading();
+
+    try {
+      // Step 1: Exchange code for tokens
+      final oidcService = OidcServiceWeb();
+      final tokens = await oidcService.exchangeCode(code, callbackState);
+
+      // 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);
+
+      developer.log(
+        'Synced user: ${syncResponse.name} with ${syncResponse.roles.length} roles',
+        name: 'auth',
+      );
+
+      // Step 3: Store credentials and user data from sync response
+      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}', name: 'auth');
+
+      // Clean up the URL by removing the query parameters
+      web_utils.replaceUrl('/');
+    } on OidcException catch (e) {
+      developer.log('OIDC callback failed: $e', name: 'auth');
+      state = AsyncError(e, StackTrace.current);
+    } catch (e, stack) {
+      developer.log('Callback handling failed: $e', name: 'auth');
+      state = AsyncError(e, stack);
+    }
  }

  /// Sign out and clear stored credentials.
+  ///
+  /// On web, also redirects to Authentik's logout endpoint to end the SSO session.
  Future<void> signOut() async {
+    // Clear local storage first
    await _clearStoredAuth();
    state = const AsyncData(AuthState());
-    developer.log('Signed out', name: 'auth');
+    developer.log('Signed out locally', name: 'auth');
+
+    // On web, redirect to Authentik logout to end SSO session
+    if (kIsWeb && AppConfig.requiresAuth) {
+      try {
+        final oidcService = OidcServiceWeb();
+        final logoutUrl = await oidcService.getLogoutUrl();
+        developer.log('Redirecting to Authentik logout', name: 'auth');
+        web_utils.redirectTo(logoutUrl);
+      } catch (e) {
+        developer.log('Failed to get logout URL: $e', name: 'auth');
+        // Local logout already done, just reload to trigger re-auth
+        web_utils.redirectTo('/');
+      }
+    }
  }

-  /// Update auth state (called after successful OIDC flow).
-  Future<void> setAuthenticated({
+  /// Update user preferences.
+  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 +395,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(
-      isAuthenticated: true,
-      accessToken: accessToken,
-      refreshToken: refreshToken,
-      expiresAt: expiresAt,
-      userId: userId,
-      userName: userName,
-      userEmail: userEmail,
-    ));
+    // Store roles as JSON
+    if (roles != null) {
+      final rolesJson = jsonEncode(roles.map((r) => {
+        'id': r.id,
+        'name': r.name,
+        'domain': r.domain.value,
+        'category': r.category,
+        '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 +424,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);
  }
 }
@@ -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;
 }
@@ -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();
+}
@@ -0,0 +1,245 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:developer' as developer;
+import 'dart:math';
+
+import 'package:crypto/crypto.dart';
+import 'package:dio/dio.dart';
+
+import '../config/app_config.dart';
+import 'oidc_service.dart';
+import 'web_utils.dart' as web_utils;
+
+/// Web implementation of OIDC service using browser redirect flow.
+///
+/// Uses Authorization Code flow with PKCE for secure authentication.
+/// On web, we can't use flutter_appauth, so we implement the flow manually
+/// using browser redirects and URL parsing.
+class OidcServiceWeb implements OidcService {
+  OidcServiceWeb({Dio? dio}) : _dio = dio ?? Dio();
+
+  final Dio _dio;
+
+  /// OIDC scopes to request.
+  static const _scopes = ['openid', 'profile', 'email', 'offline_access'];
+
+  /// Redirect URI for web.
+  static String get _redirectUri => '${AppConfig.webBaseUrl}/callback';
+
+  // SessionStorage keys for PKCE state (persists across redirect)
+  static const _codeVerifierKey = 'oidc_code_verifier';
+  static const _stateKey = 'oidc_state';
+
+  /// Get the authorization URL to redirect the browser to.
+  ///
+  /// Returns a URL that the browser should navigate to for authentication.
+  /// The [codeVerifier] and [state] are stored for later verification.
+  ///
+  /// If [silent] is true, adds `prompt=none` to skip login UI.
+  /// This is used when the user already has an Authentik session (via NPM).
+  /// Authentik will instantly redirect back with a code, or return an error
+  /// if there's no valid session.
+  Future<String> getAuthorizationUrl({bool silent = false}) async {
+    // Fetch OIDC discovery document
+    final discovery = await _fetchDiscovery();
+    final authEndpoint = discovery['authorization_endpoint'] as String;
+
+    // Generate PKCE code verifier and challenge
+    final codeVerifier = _generateCodeVerifier();
+    final codeChallenge = _generateCodeChallenge(codeVerifier);
+
+    // Generate state for CSRF protection
+    final state = _generateRandomString(32);
+
+    // Store PKCE state in sessionStorage (persists across redirect)
+    web_utils.setSessionStorage(_codeVerifierKey, codeVerifier);
+    web_utils.setSessionStorage(_stateKey, state);
+
+    // Build authorization URL
+    final params = {
+      'client_id': AppConfig.authClientId,
+      'redirect_uri': _redirectUri,
+      'response_type': 'code',
+      'scope': _scopes.join(' '),
+      'code_challenge': codeChallenge,
+      'code_challenge_method': 'S256',
+      'state': state,
+      if (silent) 'prompt': 'none', // Silent auth - no UI, instant redirect
+    };
+
+    final uri = Uri.parse(authEndpoint).replace(queryParameters: params);
+    developer.log('Authorization URL (silent=$silent): $uri', name: 'oidc_web');
+    return uri.toString();
+  }
+
+  /// Exchange authorization code for tokens.
+  ///
+  /// Call this after the browser redirects back with the authorization code.
+  /// [code] is the authorization code from the callback URL.
+  /// [state] is the state parameter from the callback URL (verified for CSRF).
+  Future<OidcTokens> exchangeCode(String code, String state) async {
+    // Retrieve PKCE state from sessionStorage
+    final storedState = web_utils.getSessionStorage(_stateKey);
+    final codeVerifier = web_utils.getSessionStorage(_codeVerifierKey);
+
+    developer.log('Stored state: $storedState, received state: $state', name: 'oidc_web');
+    developer.log('Code verifier present: ${codeVerifier != null}', name: 'oidc_web');
+
+    // Verify state matches
+    if (storedState == null || state != storedState) {
+      _clearPkceState();
+      throw OidcException('State mismatch - possible CSRF attack');
+    }
+
+    if (codeVerifier == null) {
+      _clearPkceState();
+      throw OidcException('No code verifier - flow not started properly');
+    }
+
+    try {
+      // Fetch token endpoint from discovery
+      final discovery = await _fetchDiscovery();
+      final tokenEndpoint = discovery['token_endpoint'] as String;
+
+      developer.log('Exchanging code at: $tokenEndpoint', name: 'oidc_web');
+
+      // Exchange code for tokens
+      final response = await _dio.post<Map<String, dynamic>>(
+        tokenEndpoint,
+        data: {
+          'grant_type': 'authorization_code',
+          'client_id': AppConfig.authClientId,
+          'redirect_uri': _redirectUri,
+          'code': code,
+          'code_verifier': codeVerifier,
+        },
+        options: Options(
+          contentType: Headers.formUrlEncodedContentType,
+        ),
+      );
+
+      final data = response.data!;
+      developer.log('Token exchange successful', name: 'oidc_web');
+
+      // Clear stored PKCE state
+      _clearPkceState();
+
+      return OidcTokens(
+        accessToken: data['access_token'] as String,
+        refreshToken: data['refresh_token'] as String?,
+        expiresAt: DateTime.now().add(
+          Duration(seconds: data['expires_in'] as int? ?? 3600),
+        ),
+        idToken: data['id_token'] as String?,
+      );
+    } on DioException catch (e) {
+      developer.log('Token exchange failed: $e', name: 'oidc_web');
+      _clearPkceState();
+      throw OidcException('Token exchange failed: ${e.message}');
+    }
+  }
+
+  /// Clear PKCE state from sessionStorage.
+  void _clearPkceState() {
+    web_utils.removeSessionStorage(_codeVerifierKey);
+    web_utils.removeSessionStorage(_stateKey);
+  }
+
+  /// Not used on web - use [getAuthorizationUrl] and [exchangeCode] instead.
+  @override
+  Future<OidcTokens> signIn() async {
+    throw OidcException(
+      'signIn() not supported on web. Use getAuthorizationUrl() and exchangeCode() instead.',
+    );
+  }
+
+  /// Refresh the access token using a refresh token.
+  @override
+  Future<OidcTokens> refreshToken(String refreshToken) async {
+    try {
+      final discovery = await _fetchDiscovery();
+      final tokenEndpoint = discovery['token_endpoint'] as String;
+
+      final response = await _dio.post<Map<String, dynamic>>(
+        tokenEndpoint,
+        data: {
+          'grant_type': 'refresh_token',
+          'client_id': AppConfig.authClientId,
+          'refresh_token': refreshToken,
+        },
+        options: Options(
+          contentType: Headers.formUrlEncodedContentType,
+        ),
+      );
+
+      final data = response.data!;
+
+      return OidcTokens(
+        accessToken: data['access_token'] as String,
+        refreshToken: data['refresh_token'] as String? ?? refreshToken,
+        expiresAt: DateTime.now().add(
+          Duration(seconds: data['expires_in'] as int? ?? 3600),
+        ),
+        idToken: data['id_token'] as String?,
+      );
+    } on DioException catch (e) {
+      throw OidcException('Token refresh failed: ${e.message}');
+    }
+  }
+
+  /// Fetch OIDC discovery document.
+  Future<Map<String, dynamic>> _fetchDiscovery() async {
+    final response = await _dio.get<Map<String, dynamic>>(
+      AppConfig.authDiscoveryUrl,
+    );
+    return response.data!;
+  }
+
+  /// Generate a random code verifier for PKCE.
+  String _generateCodeVerifier() {
+    return _generateRandomString(64);
+  }
+
+  /// Generate code challenge from verifier using S256.
+  String _generateCodeChallenge(String verifier) {
+    final bytes = utf8.encode(verifier);
+    final digest = sha256.convert(bytes);
+    return base64Url.encode(digest.bytes).replaceAll('=', '');
+  }
+
+  /// Generate a random string of given length.
+  String _generateRandomString(int length) {
+    const chars =
+        'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+    final random = Random.secure();
+    return List.generate(length, (_) => chars[random.nextInt(chars.length)])
+        .join();
+  }
+
+  /// Get the logout URL to redirect the browser to for SSO logout.
+  ///
+  /// [idToken] is optional but recommended for logout verification.
+  /// After logout, Authentik redirects back to [postLogoutRedirectUri].
+  Future<String> getLogoutUrl({String? idToken}) async {
+    final discovery = await _fetchDiscovery();
+    final endSessionEndpoint = discovery['end_session_endpoint'] as String?;
+
+    if (endSessionEndpoint == null) {
+      // Fallback: just redirect to home, local state already cleared
+      developer.log('No end_session_endpoint in discovery', name: 'oidc_web');
+      return AppConfig.webBaseUrl;
+    }
+
+    final params = <String, String>{
+      'post_logout_redirect_uri': AppConfig.webBaseUrl,
+    };
+
+    if (idToken != null) {
+      params['id_token_hint'] = idToken;
+    }
+
+    final uri = Uri.parse(endSessionEndpoint).replace(queryParameters: params);
+    developer.log('Logout URL: $uri', name: 'oidc_web');
+    return uri.toString();
+  }
+}
@@ -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,
+    );
+  }
+}
@@ -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);
+}
@@ -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);
+}
@@ -0,0 +1,7 @@
+/// Web utilities with conditional imports.
+///
+/// Uses stub implementation on non-web platforms.
+library;
+
+export 'web_utils_stub.dart'
+    if (dart.library.js_interop) 'web_utils_web.dart';
@@ -0,0 +1,32 @@
+/// Stub for non-web platforms.
+library;
+
+/// Redirect to a URL (no-op on non-web).
+void redirectTo(String url) {
+  throw UnsupportedError('redirectTo is only supported on web');
+}
+
+/// Get current URL (no-op on non-web).
+String getCurrentUrl() {
+  throw UnsupportedError('getCurrentUrl is only supported on web');
+}
+
+/// Replace current URL without navigation (no-op on non-web).
+void replaceUrl(String url) {
+  throw UnsupportedError('replaceUrl is only supported on web');
+}
+
+/// Store a value in sessionStorage (no-op on non-web).
+void setSessionStorage(String key, String value) {
+  throw UnsupportedError('setSessionStorage is only supported on web');
+}
+
+/// Get a value from sessionStorage (no-op on non-web).
+String? getSessionStorage(String key) {
+  throw UnsupportedError('getSessionStorage is only supported on web');
+}
+
+/// Remove a value from sessionStorage (no-op on non-web).
+void removeSessionStorage(String key) {
+  throw UnsupportedError('removeSessionStorage is only supported on web');
+}
@@ -0,0 +1,34 @@
+/// Web-specific utilities for browser operations.
+library;
+
+import 'package:web/web.dart' as web;
+
+/// Redirect the browser to a URL.
+void redirectTo(String url) {
+  web.window.location.href = url;
+}
+
+/// Get the current browser URL.
+String getCurrentUrl() {
+  return web.window.location.href;
+}
+
+/// Replace the current URL in history without navigation.
+void replaceUrl(String url) {
+  web.window.history.replaceState(null, '', url);
+}
+
+/// Store a value in sessionStorage.
+void setSessionStorage(String key, String value) {
+  web.window.sessionStorage.setItem(key, value);
+}
+
+/// Get a value from sessionStorage.
+String? getSessionStorage(String key) {
+  return web.window.sessionStorage.getItem(key);
+}
+
+/// Remove a value from sessionStorage.
+void removeSessionStorage(String key) {
+  web.window.sessionStorage.removeItem(key);
+}
@@ -45,12 +45,18 @@ class AppConfig {
    defaultValue: 'tatlock-ui',
  );

-  /// Authentik redirect URI scheme
+  /// Authentik redirect URI scheme (for mobile/native)
  static const authRedirectScheme = String.fromEnvironment(
    'AUTH_REDIRECT_SCHEME',
    defaultValue: 'net.schweitz.tatlock',
  );

+  /// Web app base URL (for OIDC redirect URI on web)
+  static const webBaseUrl = String.fromEnvironment(
+    'WEB_BASE_URL',
+    defaultValue: 'https://home.schweitz.net',
+  );
+
  /// Whether running in debug mode
  static const isDebug = bool.fromEnvironment('DEBUG', defaultValue: false);

@@ -0,0 +1,5 @@
+/// URL strategy with conditional imports for web/non-web platforms.
+library;
+
+export 'url_strategy_stub.dart'
+    if (dart.library.js_interop) 'url_strategy_web.dart';
@@ -0,0 +1,4 @@
+/// Stub for non-web platforms - does nothing.
+void configureUrlStrategy() {
+  // No-op on mobile/desktop
+}
@@ -0,0 +1,10 @@
+/// Web-specific URL strategy configuration.
+library;
+
+import 'package:flutter_web_plugins/url_strategy.dart';
+
+void configureUrlStrategy() {
+  // Use path-based URLs instead of hash-based (e.g., /login instead of /#/login)
+  // Required for OIDC callback to work properly
+  usePathUrlStrategy();
+}
@@ -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);
@@ -0,0 +1,125 @@
+/// Semantic identifiers for UI automation and accessibility.
+///
+/// These IDs are exposed via Flutter's Semantics tree, making widgets
+/// discoverable by automation tools (Appium, WebDriver, Puppeteer with
+/// accessibility enabled).
+///
+/// Naming convention: `{area}_{component}_{identifier}`
+/// - area: room or feature area (e.g., profile, nav, dataGrid)
+/// - component: widget type (e.g., menu, button, row)
+/// - identifier: specific item (e.g., light, containers, selectAll)
+library;
+
+/// Profile dropdown menu IDs.
+abstract class ProfileSemantics {
+  static const button = 'profile_button';
+  static const menu = 'profile_menu';
+  static const settings = 'profile_menu_settings';
+  static const themeSystem = 'profile_menu_theme_system';
+  static const themeLight = 'profile_menu_theme_light';
+  static const themeDark = 'profile_menu_theme_dark';
+  static const logout = 'profile_menu_logout';
+}
+
+/// Room tab navigation IDs.
+abstract class RoomTabSemantics {
+  static const frontHall = 'roomTab_frontHall';
+  static const controlRoom = 'roomTab_controlRoom';
+  static const security = 'roomTab_security';
+  static const parlor = 'roomTab_parlor';
+
+  /// Get semantic ID for room index.
+  static String forIndex(int index) => switch (index) {
+        0 => frontHall,
+        1 => controlRoom,
+        2 => security,
+        3 => parlor,
+        _ => 'roomTab_$index',
+      };
+}
+
+/// Navigation panel IDs.
+abstract class NavSemantics {
+  static const panel = 'nav_panel';
+  static const refresh = 'nav_refresh';
+
+  /// Generate ID for a nav item.
+  static String item(String id) => 'nav_item_$id';
+
+  /// Generate ID for a nav section.
+  static String section(String id) => 'nav_section_$id';
+}
+
+/// DataGrid component IDs.
+abstract class DataGridSemantics {
+  static const grid = 'dataGrid';
+  static const search = 'dataGrid_search';
+  static const searchClear = 'dataGrid_search_clear';
+  static const selectAll = 'dataGrid_selectAll';
+  static const loading = 'dataGrid_loading';
+  static const empty = 'dataGrid_empty';
+  static const error = 'dataGrid_error';
+  static const refresh = 'dataGrid_refresh';
+
+  /// Generate ID for a column header.
+  static String header(String columnId) => 'dataGrid_header_$columnId';
+
+  /// Generate ID for a row.
+  static String row(String itemId) => 'dataGrid_row_$itemId';
+
+  /// Generate ID for a row checkbox.
+  static String rowCheckbox(String itemId) => 'dataGrid_row_${itemId}_checkbox';
+
+  /// Generate ID for a row actions menu.
+  static String rowActions(String itemId) => 'dataGrid_row_${itemId}_actions';
+
+  /// Generate ID for a row action.
+  static String rowAction(String itemId, String actionId) =>
+      'dataGrid_row_${itemId}_action_$actionId';
+
+  /// Generate ID for a bulk action button.
+  static String bulkAction(String actionId) => 'dataGrid_bulk_$actionId';
+
+  static const bulkClear = 'dataGrid_bulk_clear';
+}
+
+/// Dialog/modal IDs.
+abstract class DialogSemantics {
+  static const confirm = 'dialog_confirm';
+  static const cancel = 'dialog_cancel';
+  static const close = 'dialog_close';
+
+  /// Generate ID for a named dialog.
+  static String named(String name) => 'dialog_$name';
+
+  /// Generate ID for a dialog action button.
+  static String action(String dialogName, String actionId) =>
+      'dialog_${dialogName}_$actionId';
+}
+
+/// Settings page IDs.
+abstract class SettingsSemantics {
+  static const themeDropdown = 'settings_theme';
+  static const defaultRoomDropdown = 'settings_defaultRoom';
+}
+
+/// Filter panel IDs.
+abstract class FilterPanelSemantics {
+  static const panel = 'filterPanel';
+  static const search = 'filterPanel_search';
+  static const searchClear = 'filterPanel_search_clear';
+  static const refresh = 'filterPanel_refresh';
+
+  /// Generate ID for a filter item.
+  static String item(String id) => 'filterPanel_item_$id';
+}
+
+/// Loading/state indicator IDs.
+abstract class StateSemantics {
+  static const authLoading = 'state_auth_loading';
+  static const authError = 'state_auth_error';
+  static const pageLoading = 'state_page_loading';
+
+  /// Generate ID for a snackbar.
+  static String snackbar(String type) => 'snackbar_$type';
+}
@@ -0,0 +1,118 @@
+import 'package:flutter/material.dart';
+
+/// Wraps a widget with semantic information for accessibility and automation.
+///
+/// Usage:
+/// ```dart
+/// SemanticWidget(
+///   id: ProfileSemantics.button,
+///   label: 'Open profile menu',
+///   child: IconButton(...),
+/// )
+/// ```
+///
+/// For buttons, use `button: true`. For other interactive elements,
+/// set the appropriate semantic properties.
+class SemanticWidget extends StatelessWidget {
+  const SemanticWidget({
+    super.key,
+    required this.id,
+    required this.child,
+    this.label,
+    this.hint,
+    this.button = false,
+    this.link = false,
+    this.header = false,
+    this.textField = false,
+    this.enabled = true,
+    this.selected,
+    this.checked,
+    this.value,
+    this.excludeSemantics = false,
+  });
+
+  /// Unique identifier for this widget, exposed via [SemanticsProperties.identifier].
+  final String id;
+
+  /// The widget to wrap.
+  final Widget child;
+
+  /// Accessibility label describing the widget.
+  final String? label;
+
+  /// Hint text for screen readers.
+  final String? hint;
+
+  /// Whether this widget represents a button.
+  final bool button;
+
+  /// Whether this widget represents a link.
+  final bool link;
+
+  /// Whether this widget represents a header.
+  final bool header;
+
+  /// Whether this widget represents a text field.
+  final bool textField;
+
+  /// Whether the widget is enabled.
+  final bool enabled;
+
+  /// Whether the widget is selected (for toggle buttons, tabs).
+  final bool? selected;
+
+  /// Whether the widget is checked (for checkboxes).
+  final bool? checked;
+
+  /// Current value (for sliders, progress indicators).
+  final String? value;
+
+  /// Whether to exclude child semantics.
+  final bool excludeSemantics;
+
+  @override
+  Widget build(BuildContext context) {
+    return Semantics(
+      identifier: id,
+      label: label,
+      hint: hint,
+      button: button,
+      link: link,
+      header: header,
+      textField: textField,
+      enabled: enabled,
+      selected: selected,
+      checked: checked,
+      value: value,
+      excludeSemantics: excludeSemantics,
+      child: child,
+    );
+  }
+}
+
+/// Extension to easily wrap any widget with semantic info.
+extension SemanticExtension on Widget {
+  /// Wraps this widget with a semantic identifier.
+  Widget withSemantics({
+    required String id,
+    String? label,
+    String? hint,
+    bool button = false,
+    bool link = false,
+    bool enabled = true,
+    bool? selected,
+    bool? checked,
+  }) {
+    return SemanticWidget(
+      id: id,
+      label: label,
+      hint: hint,
+      button: button,
+      link: link,
+      enabled: enabled,
+      selected: selected,
+      checked: checked,
+      child: this,
+    );
+  }
+}
@@ -1,6 +1,10 @@
+import 'dart:developer' as developer;
+
 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';

@@ -17,13 +21,21 @@ enum ThemeSetting {
 }

 /// Provider for theme setting state.
-@riverpod
+///
+/// Syncs with API preferences when user is authenticated. On login, the theme
+/// from API preferences takes precedence over local storage.
+@persistentRiverpod
 class ThemeNotifier extends _$ThemeNotifier {
  static const _prefsKey = 'theme_setting';

  @override
  ThemeSetting build() {
+    // Load local setting first for immediate UI
    _loadSavedSetting();
+
+    // Listen for auth state changes to sync from API preferences
+    _syncFromAuthPreferences();
+
    return ThemeSetting.system;
  }

@@ -39,6 +51,36 @@ class ThemeNotifier extends _$ThemeNotifier {
    }
  }

+  /// Listen to auth state and sync theme from API preferences.
+  void _syncFromAuthPreferences() {
+    ref.listen(authProvider, (_, next) {
+      next.whenData((auth) {
+        final apiTheme = auth.preferences?.theme;
+        if (apiTheme != null && apiTheme.isNotEmpty) {
+          try {
+            final themeSetting = ThemeSetting.values.byName(apiTheme);
+            if (themeSetting != state) {
+              developer.log(
+                'Syncing theme from API: $apiTheme',
+                name: 'theme',
+              );
+              state = themeSetting;
+              // Also persist to local storage for offline use
+              _saveToLocalStorage(themeSetting);
+            }
+          } catch (_) {
+            // Invalid theme value from API, keep current
+          }
+        }
+      });
+    });
+  }
+
+  Future<void> _saveToLocalStorage(ThemeSetting setting) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_prefsKey, setting.name);
+  }
+
  /// Update theme setting and persist to storage.
  Future<void> setSetting(ThemeSetting setting) async {
    state = setting;
@@ -1,12 +1,19 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart' hide Container;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/providers/containers_provider.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/widgets/container_logs_viewer.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/widgets/container_status_badge.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';

+/// Health status of a container.
+enum ContainerHealth { healthy, unhealthy, starting, none }
+
 /// Container data class for DataGrid display.
 class ContainerData {
  ContainerData({
@@ -17,25 +24,45 @@ class ContainerData {
    required this.state,
    required this.status,
    required this.ports,
+    required this.health,
  });

  factory ContainerData.fromJson(Map<String, dynamic> json) {
-    final ports = (json['ports'] as List<dynamic>?)
+    // Docker API uses capitalized keys
+    final ports = (json['Ports'] as List<dynamic>?)
            ?.map((p) => ContainerPort.fromJson(p as Map<String, dynamic>))
            .toList() ??
        [];

+    final fullId = json['Id'] as String? ?? '';
+    final names = json['Names'] as List<dynamic>? ?? [];
+    final name = names.isNotEmpty
+        ? (names.first as String).replaceFirst('/', '')
+        : 'Unknown';
+
+    final status = json['Status'] as String? ?? 'Unknown';
+
    return ContainerData(
-      id: json['id'] as String,
-      fullId: json['full_id'] as String? ?? json['id'] as String,
-      name: json['name'] as String,
-      image: json['image'] as String,
-      state: json['state'] as String,
-      status: json['status'] as String,
+      id: fullId.length > 12 ? fullId.substring(0, 12) : fullId,
+      fullId: fullId,
+      name: name,
+      image: json['Image'] as String? ?? 'Unknown',
+      state: json['State'] as String? ?? 'unknown',
+      status: status,
      ports: ports,
+      health: _parseHealth(status),
    );
  }

+  /// Parse health status from Docker status string (e.g., "Up 2 hours (healthy)")
+  static ContainerHealth _parseHealth(String status) {
+    final lower = status.toLowerCase();
+    if (lower.contains('(healthy)')) return ContainerHealth.healthy;
+    if (lower.contains('(unhealthy)')) return ContainerHealth.unhealthy;
+    if (lower.contains('(health: starting)')) return ContainerHealth.starting;
+    return ContainerHealth.none;
+  }
+
  final String id;
  final String fullId;
  final String name;
@@ -43,6 +70,16 @@ class ContainerData {
  final String state;
  final String status;
  final List<ContainerPort> ports;
+  final ContainerHealth health;
+
+  /// Status string with health info stripped (just shows uptime).
+  String get displayStatus {
+    return status
+        .replaceAll(RegExp(r'\s*\(healthy\)', caseSensitive: false), '')
+        .replaceAll(RegExp(r'\s*\(unhealthy\)', caseSensitive: false), '')
+        .replaceAll(RegExp(r'\s*\(health: starting\)', caseSensitive: false), '')
+        .trim();
+  }

  bool get canStart => state == 'exited' || state == 'created';
  bool get canStop => state == 'running';
@@ -53,9 +90,10 @@ class ContainerPort {
  ContainerPort({required this.privatePort, this.publicPort, this.type = 'tcp'});

  factory ContainerPort.fromJson(Map<String, dynamic> json) => ContainerPort(
-        privatePort: json['private_port'] as int? ?? json['PrivatePort'] as int? ?? 0,
-        publicPort: json['public_port'] as int? ?? json['PublicPort'] as int?,
-        type: json['type'] as String? ?? json['Type'] as String? ?? 'tcp',
+        // Docker API uses PrivatePort/PublicPort
+        privatePort: json['PrivatePort'] as int? ?? 0,
+        publicPort: json['PublicPort'] as int?,
+        type: json['Type'] as String? ?? 'tcp',
      );

  final int privatePort;
@@ -67,7 +105,10 @@ class ContainerPort {

 /// Page displaying the list of containers using DataGrid.
 class ContainersListPage extends ConsumerStatefulWidget {
-  const ContainersListPage({super.key});
+  const ContainersListPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;

  @override
  ConsumerState<ContainersListPage> createState() => _ContainersListPageState();
@@ -76,10 +117,18 @@ class ContainersListPage extends ConsumerStatefulWidget {
 class _ContainersListPageState extends ConsumerState<ContainersListPage> {
  late final StateNotifierProvider<DataGridController<ContainerData>,
      DataGridState<ContainerData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;

  @override
  void initState() {
    super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
    final dio = ref.read(coreApiClientProvider);
    final source = CoreApiDataSource<ContainerData>(
      dio: dio,
@@ -87,34 +136,87 @@ class _ContainersListPageState extends ConsumerState<ContainersListPage> {
      fromJson: ContainerData.fromJson,
    );

+    // Initialize grid with URL state
    _gridProvider = dataGridProvider<ContainerData>(
      source: source,
      config: _buildConfig(),
      idSelector: (c) => c.id,
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
    );
  }

+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+
+    final params = PageUrlState(
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
+  }
+
  DataGridConfig<ContainerData> _buildConfig() {
    return DataGridConfig<ContainerData>(
      columns: [
        DataGridColumn<ContainerData>(
+          id: 'container',
          header: 'Container',
-          valueBuilder: (c) => c.name,
+          valueBuilder: (c) => '${c.name} ${c.image}',
          sortable: true,
          searchable: true,
          width: const DataGridColumnWidth.flex(2),
          cellBuilder: (context, c) => _ContainerCell(container: c),
        ),
        DataGridColumn<ContainerData>(
+          id: 'ports',
          header: 'Ports',
          valueBuilder: (c) => c.ports.map((p) => p.formatted).join(', '),
          width: const DataGridColumnWidth.flex(1),
          cellBuilder: (context, c) => _PortsCell(ports: c.ports),
        ),
        DataGridColumn<ContainerData>(
+          id: 'status',
          header: 'Status',
-          valueBuilder: (c) => c.status,
-          width: const DataGridColumnWidth.fixed(140),
+          valueBuilder: (c) => c.displayStatus,
+          width: const DataGridColumnWidth.fixed(160),
          alignment: DataGridColumnAlignment.end,
        ),
      ],
@@ -177,6 +279,15 @@ class _ContainersListPageState extends ConsumerState<ContainersListPage> {
  Widget build(BuildContext context) {
    final colorScheme = Theme.of(context).colorScheme;

+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
    // Listen for container action results to show snackbars
    ref.listen<AsyncValue<void>>(containerActionsProvider, (previous, next) {
      if (previous?.isLoading == true && !next.isLoading) {
@@ -242,7 +353,7 @@ class _ContainerCell extends StatelessWidget {

    return Row(
      children: [
-        ContainerStatusBadge.fromString(container.state),
+        ContainerStatusBadge.fromString(container.state, health: container.health),
        const SizedBox(width: 8),
        Expanded(
          child: Column(
@@ -1,48 +1,67 @@
 import 'package:flutter/material.dart' hide Container;
+import 'package:tatlock_ui/features/control_room/containers/domain/entities/container.dart';
+import 'package:tatlock_ui/features/control_room/containers/presentation/pages/containers_list_page.dart';

-/// Container state enum for status display.
-enum ContainerState {
-  created,
-  running,
-  paused,
-  restarting,
-  removing,
-  exited,
-  dead;
+/// Status badge for container state with optional health indication.
+class ContainerStatusBadge extends StatelessWidget {
+  const ContainerStatusBadge({
+    super.key,
+    required this.state,
+    this.health,
+    this.showLabel = true,
+  });

-  /// Parse a string to ContainerState.
-  static ContainerState fromString(String value) {
+  /// Create badge from a string state value.
+  factory ContainerStatusBadge.fromString(
+    String state, {
+    ContainerHealth? health,
+    bool showLabel = true,
+  }) {
+    return ContainerStatusBadge(
+      state: _parseState(state),
+      health: health,
+      showLabel: showLabel,
+    );
+  }
+
+  /// Create badge from state enum and status string (parses health from status).
+  factory ContainerStatusBadge.withStatus({
+    required ContainerState state,
+    required String status,
+    bool showLabel = true,
+  }) {
+    return ContainerStatusBadge(
+      state: state,
+      health: _parseHealthFromStatus(status),
+      showLabel: showLabel,
+    );
+  }
+
+  /// Parse health status from Docker status string.
+  static ContainerHealth _parseHealthFromStatus(String status) {
+    final lower = status.toLowerCase();
+    if (lower.contains('(healthy)')) return ContainerHealth.healthy;
+    if (lower.contains('(unhealthy)')) return ContainerHealth.unhealthy;
+    if (lower.contains('(health: starting)')) return ContainerHealth.starting;
+    return ContainerHealth.none;
+  }
+
+  final ContainerState state;
+  final ContainerHealth? health;
+  final bool showLabel;
+
+  static ContainerState _parseState(String value) {
    return ContainerState.values.firstWhere(
      (s) => s.name == value.toLowerCase(),
      orElse: () => ContainerState.exited,
    );
  }
-}
-
-/// Status badge for container state.
-class ContainerStatusBadge extends StatelessWidget {
-  const ContainerStatusBadge({
-    super.key,
-    required this.state,
-    this.showLabel = true,
-  });
-
-  /// Create badge from a string state value.
-  factory ContainerStatusBadge.fromString(String state, {bool showLabel = true}) {
-    return ContainerStatusBadge(
-      state: ContainerState.fromString(state),
-      showLabel: showLabel,
-    );
-  }
-
-  final ContainerState state;
-  final bool showLabel;

  @override
  Widget build(BuildContext context) {
    final (color, icon, label) = _getStateStyle(context);

-    return DecoratedBox(
+    Widget badge = DecoratedBox(
      decoration: BoxDecoration(
        color: color.withValues(alpha: 0.15),
        borderRadius: BorderRadius.circular(4),
@@ -69,17 +88,22 @@ class ContainerStatusBadge extends StatelessWidget {
        ),
      ),
    );
+
+    if (showLabel) {
+      badge = ConstrainedBox(
+        constraints: const BoxConstraints(minWidth: 90),
+        child: badge,
+      );
+    }
+
+    return badge;
  }

  (Color, IconData, String) _getStateStyle(BuildContext context) {
    final colorScheme = Theme.of(context).colorScheme;

    return switch (state) {
-      ContainerState.running => (
-          Colors.green,
-          Icons.play_circle,
-          'Running',
-        ),
+      ContainerState.running => _getRunningStyle(colorScheme),
      ContainerState.paused => (
          Colors.orange,
          Icons.pause_circle,
@@ -112,4 +136,30 @@ class ContainerStatusBadge extends StatelessWidget {
        ),
    };
  }
+
+  /// Get style for running state, factoring in health status.
+  (Color, IconData, String) _getRunningStyle(ColorScheme colorScheme) {
+    return switch (health) {
+      ContainerHealth.healthy => (
+          Colors.green,
+          Icons.play_circle,
+          'Running',
+        ),
+      ContainerHealth.unhealthy => (
+          Colors.orange,
+          Icons.warning_amber_rounded,
+          'Unhealthy',
+        ),
+      ContainerHealth.starting => (
+          Colors.blue,
+          Icons.hourglass_top,
+          'Starting',
+        ),
+      ContainerHealth.none || null => (
+          Colors.green,
+          Icons.play_circle,
+          'Running',
+        ),
+    };
+  }
 }
@@ -1,8 +1,12 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
 import 'package:tatlock_ui/features/control_room/npm/presentation/pages/proxy_host_page.dart';
 import 'package:tatlock_ui/features/control_room/npm/presentation/providers/proxy_hosts_provider.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';

@@ -33,7 +37,10 @@ class DomainData {

 /// Page displaying the list of proxy hosts (domains) from NPM.
 class ProxyHostsPage extends ConsumerStatefulWidget {
-  const ProxyHostsPage({super.key});
+  const ProxyHostsPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;

  @override
  ConsumerState<ProxyHostsPage> createState() => _ProxyHostsPageState();
@@ -42,10 +49,18 @@ class ProxyHostsPage extends ConsumerStatefulWidget {
 class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
  late final StateNotifierProvider<DataGridController<DomainData>,
      DataGridState<DomainData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;

  @override
  void initState() {
    super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
    final dio = ref.read(coreApiClientProvider);
    final source = CoreApiDataSource<DomainData>(
      dio: dio,
@@ -53,17 +68,80 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
      fromJson: DomainData.fromJson,
    );

+    // Initialize grid with URL state
    _gridProvider = dataGridProvider<DomainData>(
      source: source,
      config: _buildConfig(),
      idSelector: (d) => d.proxyHostId.toString(),
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
    );
+
+    // Open document from URL if id present
+    if (_urlState.id != null) {
+      final id = int.tryParse(_urlState.id!);
+      if (id != null) {
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          ref.read(selectedProxyHostProvider.notifier).select(id);
+        });
+      }
+    }
+  }
+
+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+    final selectedId = ref.read(selectedProxyHostProvider);
+
+    final params = PageUrlState(
+      id: selectedId?.toString(),
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
  }

  DataGridConfig<DomainData> _buildConfig() {
    return DataGridConfig<DomainData>(
      columns: [
        DataGridColumn<DomainData>(
+          id: 'domain',
          header: 'Domain',
          valueBuilder: (d) => d.domain,
          sortable: true,
@@ -72,12 +150,14 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
          cellBuilder: (context, d) => _DomainCell(domain: d),
        ),
        DataGridColumn<DomainData>(
+          id: 'service',
          header: 'Service',
          valueBuilder: (d) => d.service,
          width: const DataGridColumnWidth.flex(1),
          cellBuilder: (context, d) => _ServiceCell(service: d.service),
        ),
        DataGridColumn<DomainData>(
+          id: 'ssl',
          header: 'SSL',
          valueBuilder: (d) => d.sslEnabled ? 'Enabled' : 'Disabled',
          width: const DataGridColumnWidth.fixed(100),
@@ -101,6 +181,8 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {

  void _viewDomain(DomainData domain) {
    ref.read(selectedProxyHostProvider.notifier).select(domain.proxyHostId);
+    // Navigate with id to enable back button
+    context.go('/control-room/proxy-hosts?id=${domain.proxyHostId}');
  }

  void _createNew() {
@@ -112,6 +194,15 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
    final selectedId = ref.watch(selectedProxyHostProvider);
    final isCreating = ref.watch(creatingProxyHostProvider);

+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
    // Show create page if creating new
    if (isCreating) {
      return ProxyHostPage.create(
@@ -128,6 +219,8 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
        proxyHostId: selectedId,
        onClose: () {
          ref.read(selectedProxyHostProvider.notifier).clear();
+          // Clear id from URL
+          context.go('/control-room/proxy-hosts');
          ref.read(_gridProvider.notifier).refresh();
        },
      );
@@ -17,11 +17,15 @@ class ControlRoomPage extends ConsumerWidget {
  const ControlRoomPage({
    super.key,
    this.nav = ControlRoomNav.containers,
+    this.routerState,
  });

  /// The current nav item to display.
  final ControlRoomNav nav;

+  /// Router state for URL deep-linking (query params).
+  final GoRouterState? routerState;
+
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final colorScheme = Theme.of(context).colorScheme;
@@ -53,7 +57,7 @@ class ControlRoomPage extends ConsumerWidget {
          ),
          // Section content
          Expanded(
-            child: _SectionContent(nav: nav),
+            child: _SectionContent(nav: nav, routerState: routerState),
          ),
        ],
      ),
@@ -63,50 +67,18 @@ class ControlRoomPage extends ConsumerWidget {

 /// Renders content for the selected nav item.
 class _SectionContent extends ConsumerWidget {
-  const _SectionContent({required this.nav});
+  const _SectionContent({required this.nav, this.routerState});

  final ControlRoomNav nav;
+  final GoRouterState? routerState;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
-    switch (nav) {
-      case ControlRoomNav.containers:
-        return const _ContainersSection();
-      case ControlRoomNav.proxyHosts:
-        return const ProxyHostsPage();
-      default:
-        return _PlaceholderSection(nav: nav);
-    }
-  }
-}
-
-/// Containers section with optional stack filter.
-class _ContainersSection extends ConsumerWidget {
-  const _ContainersSection();
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final selectedStack = ref.watch(selectedStackProvider);
-    final colorScheme = Theme.of(context).colorScheme;
-
-    return Row(
-      children: [
-        // Stacks filter panel
-        const _StacksFilterPanel(),
-        // Divider
-        VerticalDivider(
-          width: 1,
-          thickness: 1,
-          color: colorScheme.outlineVariant,
-        ),
-        // Main content - containers list or stack detail
-        Expanded(
-          child: selectedStack == null
-              ? const ContainersListPage()
-              : StackDetailPage(stackId: selectedStack),
-        ),
-      ],
-    );
+    return switch (nav) {
+      ControlRoomNav.containers => _ContainersSection(routerState: routerState),
+      ControlRoomNav.proxyHosts => ProxyHostsPage(routerState: routerState),
+      _ => _PlaceholderSection(nav: nav),
+    };
  }
 }

@@ -150,9 +122,43 @@ class _PlaceholderSection extends StatelessWidget {
  }
 }

+/// Containers section with optional stack filter.
+class _ContainersSection extends ConsumerWidget {
+  const _ContainersSection({this.routerState});
+
+  final GoRouterState? routerState;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final selectedStack = ref.watch(selectedStackProvider);
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Row(
+      children: [
+        // Stacks filter panel
+        _StacksFilterPanel(routerState: routerState),
+        // Divider
+        VerticalDivider(
+          width: 1,
+          thickness: 1,
+          color: colorScheme.outlineVariant,
+        ),
+        // Main content - containers list or stack detail
+        Expanded(
+          child: selectedStack == null
+              ? ContainersListPage(routerState: routerState)
+              : StackDetailPage(stackId: selectedStack),
+        ),
+      ],
+    );
+  }
+}
+
 /// Stacks filter panel for Containers section (includes "All Containers" option).
 class _StacksFilterPanel extends ConsumerWidget {
-  const _StacksFilterPanel();
+  const _StacksFilterPanel({this.routerState});
+
+  final GoRouterState? routerState;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
@@ -210,6 +216,7 @@ class _StacksFilterPanel extends ConsumerWidget {
              data: (stacks) => _StacksList(
                stacks: stacks,
                selectedStackId: selectedStack,
+                routerState: routerState,
                onStackSelected: (id) =>
                    ref.read(selectedStackProvider.notifier).select(id),
                onStackAction: (id, action) =>
@@ -284,12 +291,14 @@ class _StacksList extends StatefulWidget {
    required this.selectedStackId,
    required this.onStackSelected,
    required this.onStackAction,
+    this.routerState,
  });

  final List<Stack> stacks;
  final String? selectedStackId;
  final void Function(String) onStackSelected;
  final void Function(String, String) onStackAction;
+  final GoRouterState? routerState;

  @override
  State<_StacksList> createState() => _StacksListState();
@@ -1,35 +1,33 @@
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/features/control_room/presentation/pages/control_room_page.dart';
+import 'package:tatlock_ui/routing/app_router.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
 import 'package:tatlock_ui/shared/layouts/widgets/nav_panel.dart';

 /// Route paths for Control Room.
 abstract class ControlRoomRoutes {
  static const base = '/control-room';
-  // Portainer
+  // Stack
  static const containers = '/control-room/containers';
-  static const networks = '/control-room/networks';
-  static const volumes = '/control-room/volumes';
-  static const images = '/control-room/images';
-  // NPM
  static const proxyHosts = '/control-room/proxy-hosts';
-  static const redirections = '/control-room/redirections';
-  static const streams = '/control-room/streams';
-  static const certificates = '/control-room/certificates';
+  // Data Management
+  static const postgres = '/control-room/postgres';
+  static const redis = '/control-room/redis';
+  static const qdrant = '/control-room/qdrant';
+  static const neo4j = '/control-room/neo4j';
 }

 /// Control Room navigation items with section grouping.
 enum ControlRoomNav {
-  // Portainer section
-  containers('containers', 'Containers', Icons.dns, 'Portainer'),
-  networks('networks', 'Networks', Icons.hub, 'Portainer'),
-  volumes('volumes', 'Volumes', Icons.storage, 'Portainer'),
-  images('images', 'Images', Icons.photo_library, 'Portainer'),
-  // NPM section
-  proxyHosts('proxy-hosts', 'Proxy Hosts', Icons.public, 'NPM'),
-  redirections('redirections', 'Redirections', Icons.alt_route, 'NPM'),
-  streams('streams', 'Streams', Icons.stream, 'NPM'),
-  certificates('certificates', 'SSL Certificates', Icons.verified_user, 'NPM');
+  // Stack Management section - Docker containers and reverse proxy
+  containers('containers', 'Containers', Icons.dns, 'Stack Management'),
+  proxyHosts('proxy-hosts', 'Proxy Hosts', Icons.public, 'Stack Management'),
+  // Data Management section - Database browsers
+  postgres('postgres', 'PostgreSQL', Icons.table_chart, 'Data Management'),
+  redis('redis', 'Redis', Icons.memory, 'Data Management'),
+  qdrant('qdrant', 'Qdrant', Icons.scatter_plot, 'Data Management'),
+  neo4j('neo4j', 'Neo4j', Icons.hub, 'Data Management');

  const ControlRoomNav(this.id, this.label, this.icon, this.section);

@@ -52,6 +50,22 @@ enum ControlRoomNav {
 /// Get route path for a nav item.
 String pathForNav(ControlRoomNav nav) => nav.path;

+/// Control Room room definition.
+final controlRoomRoom = RoomDefinition(
+  id: 'control-room',
+  label: 'Control Room',
+  icon: Icons.dns_outlined,
+  selectedIcon: Icons.dns,
+  defaultRoute: ControlRoomRoutes.containers,
+  routes: controlRoomRoutes,
+  // No permissions required - accessible to all authenticated users
+);
+
+/// Register Control Room with the room registry.
+void registerControlRoom() {
+  roomRegistry.register(controlRoomRoom);
+}
+
 /// Control Room routes for go_router.
 List<RouteBase> controlRoomRoutes() {
  return [
@@ -66,7 +80,11 @@ List<RouteBase> controlRoomRoutes() {
      GoRoute(
        path: nav.path,
        name: 'controlRoom${_capitalize(nav.id.replaceAll('-', '_'))}',
-        builder: (context, state) => ControlRoomPage(nav: nav),
+        pageBuilder: (context, state) => noTransitionPage(
+          context,
+          state,
+          ControlRoomPage(nav: nav, routerState: state),
+        ),
      ),
  ];
 }
@@ -1,5 +1,7 @@
 import 'package:flutter/material.dart' hide Stack;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/features/control_room/containers/domain/entities/container.dart'
+    as container_entity;
 import 'package:tatlock_ui/features/control_room/containers/presentation/providers/containers_provider.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/widgets/container_logs_viewer.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/widgets/container_status_badge.dart';
@@ -133,7 +135,9 @@ class _StackEditor extends ConsumerWidget {
      children: [
        // Header with stack info and actions
        Container(
-          padding: const EdgeInsets.all(16),
+          height: 56,
+          padding: const EdgeInsets.only(left: 16, right: 16, bottom: 8),
+          alignment: Alignment.bottomCenter,
          decoration: BoxDecoration(
            color: colorScheme.surfaceContainerHighest,
            border: Border(
@@ -141,11 +145,13 @@ class _StackEditor extends ConsumerWidget {
            ),
          ),
          child: Row(
+            crossAxisAlignment: CrossAxisAlignment.end,
            children: [
              Icon(Icons.layers, color: colorScheme.primary),
              const SizedBox(width: 12),
              Expanded(
                child: Column(
+                  mainAxisSize: MainAxisSize.min,
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text(
@@ -211,7 +217,7 @@ class _CompactContainerList extends ConsumerWidget {
    required this.stackId,
  });

-  final List<dynamic> containers;
+  final List<container_entity.Container> containers;
  final String stackId;

  @override
@@ -269,7 +275,10 @@ class _CompactContainerList extends ConsumerWidget {
                      ),
                      child: ListTile(
                        dense: true,
-                        leading: ContainerStatusBadge(state: container.state),
+                        leading: ContainerStatusBadge.withStatus(
+                          state: container.state,
+                          status: container.status,
+                        ),
                        title: Text(
                          container.name,
                          style: const TextStyle(fontSize: 13),
@@ -0,0 +1,38 @@
+import 'package:dio/dio.dart';
+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/environment_model.dart';
+
+part 'environment_datasource.g.dart';
+
+/// Data source for environment data operations.
+///
+/// Fetches weather, forecast, sun times, and air quality from Core API.
+class EnvironmentDatasource {
+  EnvironmentDatasource(this._dio);
+
+  final Dio _dio;
+
+  static const _basePath = '/tools/environment';
+
+  /// Gets current environment data.
+  ///
+  /// Returns weather, forecast, sun times, and optionally air quality.
+  Future<EnvironmentData> getEnvironment() async {
+    final response = await _dio.get<Map<String, dynamic>>(_basePath);
+    final data = response.data;
+
+    if (data == null) {
+      throw Exception('Failed to fetch environment data');
+    }
+
+    return EnvironmentData.fromJson(data);
+  }
+}
+
+/// Provides the environment datasource.
+@riverpod
+EnvironmentDatasource environmentDatasource(Ref ref) {
+  final dio = ref.watch(coreApiClientProvider);
+  return EnvironmentDatasource(dio);
+}
@@ -0,0 +1,104 @@
+import 'package:dio/dio.dart';
+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/quick_link_model.dart';
+import 'package:tatlock_ui/features/front_hall/domain/entities/quick_link.dart';
+
+part 'quick_links_datasource.g.dart';
+
+/// Data source for quick link operations.
+///
+/// Provides CRUD operations for Front Hall quick links via Core API
+/// dashboard/quick-links endpoint.
+class QuickLinksDatasource {
+  QuickLinksDatasource(this._dio);
+
+  final Dio _dio;
+
+  static const _basePath = '/dashboard/quick-links';
+
+  /// Gets all quick links.
+  ///
+  /// API returns: {"links": [...], "total": N}
+  Future<List<QuickLink>> getQuickLinks() async {
+    final response = await _dio.get<Map<String, dynamic>>(_basePath);
+    final data = response.data;
+
+    if (data == null) {
+      return [];
+    }
+
+    final links = data['links'] as List<dynamic>? ?? [];
+    return links
+        .map((json) => QuickLinkModel.fromJson(json as Map<String, dynamic>))
+        .map((model) => model.toEntity())
+        .toList();
+  }
+
+  /// Gets a single quick link by ID.
+  Future<QuickLink> getQuickLink(int id) async {
+    final response = await _dio.get<Map<String, dynamic>>('$_basePath/$id');
+    final data = response.data;
+
+    if (data == null) {
+      throw Exception('Quick link not found: $id');
+    }
+
+    return QuickLinkModel.fromJson(data).toEntity();
+  }
+
+  /// Creates a new quick link.
+  Future<QuickLink> createQuickLink(QuickLink link) async {
+    final model = QuickLinkModel.fromEntity(link);
+    final response = await _dio.post<Map<String, dynamic>>(
+      _basePath,
+      data: model.toJson(),
+    );
+    final data = response.data;
+
+    if (data == null) {
+      throw Exception('Failed to create quick link');
+    }
+
+    return QuickLinkModel.fromJson(data).toEntity();
+  }
+
+  /// Updates an existing quick link.
+  Future<QuickLink> updateQuickLink(QuickLink link) async {
+    final model = QuickLinkModel.fromEntity(link);
+    final id = int.tryParse(link.id) ?? 0;
+    final response = await _dio.put<Map<String, dynamic>>(
+      '$_basePath/$id',
+      data: model.toJson(),
+    );
+    final data = response.data;
+
+    if (data == null) {
+      throw Exception('Failed to update quick link');
+    }
+
+    return QuickLinkModel.fromJson(data).toEntity();
+  }
+
+  /// Deletes a quick link.
+  Future<void> deleteQuickLink(int id) async {
+    await _dio.delete<void>('$_basePath/$id');
+  }
+
+  /// Reorders quick links by updating positions.
+  ///
+  /// API expects: {"link_ids": [1, 2, 3]}
+  Future<void> reorderQuickLinks(List<int> orderedIds) async {
+    await _dio.post<void>(
+      '$_basePath/reorder',
+      data: {'link_ids': orderedIds},
+    );
+  }
+}
+
+/// Provides the quick links datasource.
+@riverpod
+QuickLinksDatasource quickLinksDatasource(Ref ref) {
+  final dio = ref.watch(coreApiClientProvider);
+  return QuickLinksDatasource(dio);
+}
@@ -0,0 +1,91 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'environment_model.freezed.dart';
+part 'environment_model.g.dart';
+
+/// Environment data response from Core API.
+/// Contains weather, forecast, sun times, and optionally air quality.
+@freezed
+sealed class EnvironmentData with _$EnvironmentData {
+  const factory EnvironmentData({
+    WeatherData? weather,
+    List<ForecastDay>? forecast,
+    @JsonKey(name: 'sun_times') SunTimesData? sunTimes,
+    @JsonKey(name: 'air_quality') AirQualityData? airQuality,
+    @JsonKey(name: 'updated_at') required DateTime updatedAt,
+    String? user,
+  }) = _EnvironmentData;
+
+  factory EnvironmentData.fromJson(Map<String, dynamic> json) =>
+      _$EnvironmentDataFromJson(json);
+}
+
+/// Current weather conditions.
+@freezed
+sealed class WeatherData with _$WeatherData {
+  const factory WeatherData({
+    double? temperature,
+    @JsonKey(name: 'feels_like') double? feelsLike,
+    String? conditions,
+    int? humidity,
+    @JsonKey(name: 'wind_speed') double? windSpeed,
+    @JsonKey(name: 'wind_direction') String? windDirection,
+    double? pressure,
+    double? visibility,
+    @JsonKey(name: 'uv_index') double? uvIndex,
+    String? location,
+    String? icon,
+  }) = _WeatherData;
+
+  factory WeatherData.fromJson(Map<String, dynamic> json) =>
+      _$WeatherDataFromJson(json);
+}
+
+/// Single day forecast data.
+@freezed
+sealed class ForecastDay with _$ForecastDay {
+  const factory ForecastDay({
+    required String date,
+    double? high,
+    double? low,
+    String? conditions,
+    @JsonKey(name: 'precipitation_chance') int? precipitationChance,
+    String? icon,
+  }) = _ForecastDay;
+
+  factory ForecastDay.fromJson(Map<String, dynamic> json) =>
+      _$ForecastDayFromJson(json);
+}
+
+/// Sunrise and sunset times.
+@freezed
+sealed class SunTimesData with _$SunTimesData {
+  const factory SunTimesData({
+    DateTime? sunrise,
+    DateTime? sunset,
+    @JsonKey(name: 'daylight_minutes') int? daylightMinutes,
+    @JsonKey(name: 'solar_noon') DateTime? solarNoon,
+    DateTime? dawn,
+    DateTime? dusk,
+  }) = _SunTimesData;
+
+  factory SunTimesData.fromJson(Map<String, dynamic> json) =>
+      _$SunTimesDataFromJson(json);
+}
+
+/// Air quality information.
+@freezed
+sealed class AirQualityData with _$AirQualityData {
+  const factory AirQualityData({
+    int? aqi,
+    String? quality,
+    double? pm25,
+    double? pm10,
+    double? o3,
+    double? no2,
+    String? location,
+  }) = _AirQualityData;
+
+  factory AirQualityData.fromJson(Map<String, dynamic> json) =>
+      _$AirQualityDataFromJson(json);
+}
@@ -0,0 +1,79 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+import 'package:tatlock_ui/features/front_hall/domain/entities/quick_link.dart';
+
+part 'quick_link_model.freezed.dart';
+part 'quick_link_model.g.dart';
+
+/// Quick link data model matching Core API dashboard/quick-links endpoint.
+///
+/// Field mapping:
+/// - title (API) ↔ name (Flutter entity)
+/// - icon (API) ↔ iconName (Flutter entity)
+/// - position (API) ↔ sortOrder (Flutter entity)
+/// - is_visible (API) ↔ isActive (Flutter entity)
+/// - link_type (API) ↔ type (Flutter entity)
+@freezed
+sealed class QuickLinkModel with _$QuickLinkModel {
+  const factory QuickLinkModel({
+    @Default(0) int id,
+    required String title,
+    required String url,
+    String? icon,
+    String? description,
+    String? category,
+    @Default(0) int position,
+    @JsonKey(name: 'is_visible') @Default(true) bool isVisible,
+    @JsonKey(name: 'link_type') @Default('iframe') String linkType,
+    String? color,
+    @JsonKey(name: 'background_color') String? backgroundColor,
+  }) = _QuickLinkModel;
+
+  const QuickLinkModel._();
+
+  factory QuickLinkModel.fromJson(Map<String, dynamic> json) =>
+      _$QuickLinkModelFromJson(json);
+
+  /// Converts to domain entity.
+  QuickLink toEntity() {
+    return QuickLink(
+      id: id.toString(),
+      name: title,
+      url: url,
+      iconName: icon ?? 'link',
+      category: category,
+      type: _parseQuickLinkType(linkType),
+      sortOrder: position,
+      isActive: isVisible,
+    );
+  }
+
+  /// Creates model from domain entity.
+  factory QuickLinkModel.fromEntity(QuickLink entity) {
+    return QuickLinkModel(
+      id: int.tryParse(entity.id) ?? 0,
+      title: entity.name,
+      url: entity.url,
+      icon: entity.iconName,
+      category: entity.category,
+      position: entity.sortOrder,
+      isVisible: entity.isActive,
+      linkType: _formatQuickLinkType(entity.type),
+    );
+  }
+}
+
+/// Parses API link_type string to QuickLinkType enum.
+QuickLinkType _parseQuickLinkType(String linkType) {
+  return switch (linkType) {
+    'new_tab' => QuickLinkType.newTab,
+    _ => QuickLinkType.iframe,
+  };
+}
+
+/// Formats QuickLinkType enum to API link_type string.
+String _formatQuickLinkType(QuickLinkType type) {
+  return switch (type) {
+    QuickLinkType.newTab => 'new_tab',
+    QuickLinkType.iframe => 'iframe',
+  };
+}
@@ -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);
+}
@@ -0,0 +1,53 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'quick_link.freezed.dart';
+
+/// Quick link type for navigation behavior.
+enum QuickLinkType {
+  /// Opens in embedded iframe within the app.
+  iframe,
+
+  /// Opens in a new browser tab.
+  newTab,
+}
+
+/// Quick link entity for Front Hall navigation.
+///
+/// Represents a shortcut link that can either open embedded content
+/// in an iframe or navigate to an external URL in a new tab.
+@freezed
+sealed class QuickLink with _$QuickLink {
+  const factory QuickLink({
+    /// Unique identifier.
+    required String id,
+
+    /// Display name.
+    required String name,
+
+    /// Target URL.
+    required String url,
+
+    /// Material icon name (e.g., 'home', 'settings', 'movie').
+    required String iconName,
+
+    /// Category for grouping (e.g., 'Home', 'AMP', 'Coding', 'Infrastructure').
+    String? category,
+
+    /// Navigation behavior type.
+    @Default(QuickLinkType.iframe) QuickLinkType type,
+
+    /// Sort order within category.
+    @Default(0) int sortOrder,
+
+    /// Whether the link is active/visible.
+    @Default(true) bool isActive,
+  }) = _QuickLink;
+
+  const QuickLink._();
+
+  /// Whether this link opens in an iframe.
+  bool get isIframe => type == QuickLinkType.iframe;
+
+  /// Whether this link opens in a new tab.
+  bool get isNewTab => type == QuickLinkType.newTab;
+}
@@ -1,142 +1,65 @@
 import 'package:flutter/material.dart';
-import 'package:tatlock_ui/version.g.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/front_hall_state_provider.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/widgets/dashboard_content.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/widgets/iframe_view.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/widgets/quick_link_settings_content.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/widgets/quick_links_panel.dart';

 /// Front Hall - estate overview and quick access.
-class FrontHallPage extends StatelessWidget {
+///
+/// Three-mode content area:
+/// - Dashboard: Stats, weather, welcome message
+/// - Iframe: Embedded external content (web only)
+/// - Settings: Quick link management
+class FrontHallPage extends ConsumerWidget {
  const FrontHallPage({super.key});

  @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
    final colorScheme = Theme.of(context).colorScheme;
+    final frontHallState = ref.watch(frontHallStateProvider);

-    // No Scaffold/AppBar needed - header is provided by AppScaffold
-    return ListView(
-        padding: const EdgeInsets.all(16),
-        children: [
-          // Welcome card
-          Card(
-            child: Padding(
-              padding: const EdgeInsets.all(24),
-              child: Column(
-                crossAxisAlignment: CrossAxisAlignment.start,
-                children: [
-                  Row(
-                    children: [
-                      Icon(
-                        Icons.waving_hand,
-                        size: 32,
-                        color: colorScheme.primary,
-                      ),
-                      const SizedBox(width: 12),
-                      Flexible(
-                        child: Text(
-                          'Welcome to Tatlock',
-                          style: Theme.of(context).textTheme.headlineSmall,
-                        ),
-                      ),
-                    ],
-                  ),
-                  const SizedBox(height: 12),
-                  Text(
-                    'Your homelab dashboard is ready. More features coming soon.',
-                    style: Theme.of(context).textTheme.bodyLarge?.copyWith(
-                          color: colorScheme.onSurfaceVariant,
-                        ),
-                  ),
-                ],
-              ),
-            ),
-          ),
-          const SizedBox(height: 16),
+    return Row(
+      children: [
+        // Left panel - Quick Links
+        const QuickLinksPanel(),

-          // Quick stats placeholder
-          Wrap(
-            spacing: 12,
-            runSpacing: 12,
-            children: [
-              SizedBox(
-                width: 160,
-                child: _StatCard(
-                  icon: Icons.memory,
-                  label: 'CPU',
-                  value: '--',
-                  color: colorScheme.primary,
-                ),
-              ),
-              SizedBox(
-                width: 160,
-                child: _StatCard(
-                  icon: Icons.storage,
-                  label: 'Memory',
-                  value: '--',
-                  color: colorScheme.secondary,
-                ),
-              ),
-              SizedBox(
-                width: 160,
-                child: _StatCard(
-                  icon: Icons.dns,
-                  label: 'Containers',
-                  value: '--',
-                  color: colorScheme.tertiary,
-                ),
-              ),
-            ],
-          ),
-          const SizedBox(height: 24),
-
-          // Version info
-          Center(
-            child: Text(
-              '${AppVersion.name} v${AppVersion.fullVersion}',
-              style: Theme.of(context).textTheme.bodySmall?.copyWith(
-                    color: colorScheme.outline,
-                  ),
-            ),
-          ),
-        ],
-      );
-  }
-}
-
-class _StatCard extends StatelessWidget {
-  const _StatCard({
-    required this.icon,
-    required this.label,
-    required this.value,
-    required this.color,
-  });
-
-  final IconData icon;
-  final String label;
-  final String value;
-  final Color color;
-
-  @override
-  Widget build(BuildContext context) {
-    return Card(
-      child: Padding(
-        padding: const EdgeInsets.all(16),
-        child: Column(
-          children: [
-            Icon(icon, size: 32, color: color),
-            const SizedBox(height: 8),
-            Text(
-              value,
-              style: Theme.of(context).textTheme.headlineMedium?.copyWith(
-                    fontWeight: FontWeight.bold,
-                  ),
-            ),
-            const SizedBox(height: 4),
-            Text(
-              label,
-              style: Theme.of(context).textTheme.bodySmall?.copyWith(
-                    color: Theme.of(context).colorScheme.outline,
-                  ),
-            ),
-          ],
+        // Vertical divider
+        VerticalDivider(
+          width: 1,
+          thickness: 1,
+          color: colorScheme.outlineVariant,
        ),
-      ),
+
+        // Main content area - switches based on mode
+        Expanded(
+          child: _buildContent(context, ref, frontHallState),
+        ),
+      ],
    );
  }
+
+  Widget _buildContent(
+    BuildContext context,
+    WidgetRef ref,
+    FrontHallState state,
+  ) {
+    switch (state.mode) {
+      case FrontHallMode.dashboard:
+        return const DashboardContent();
+
+      case FrontHallMode.iframe:
+        return IframeView(
+          key: ValueKey(state.activeIframeUrl),
+          url: state.activeIframeUrl!,
+          title: state.activeIframeTitle ?? 'External Content',
+          onClose: () =>
+              ref.read(frontHallStateProvider.notifier).showDashboard(),
+        );
+
+      case FrontHallMode.settings:
+        return const QuickLinkSettingsContent();
+    }
+  }
 }
@@ -0,0 +1,27 @@
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import 'package:tatlock_ui/features/front_hall/data/datasources/environment_datasource.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/environment_model.dart';
+
+part 'environment_provider.g.dart';
+
+/// Fetches environment data (weather, forecast, sun times) from Core API.
+///
+/// Auto-invalidates every 5 minutes to keep data fresh.
+/// Weather data in Qdrant has 1-hour TTL, so 5-minute refresh is reasonable.
+@riverpod
+Future<EnvironmentData> environment(Ref ref) async {
+  final datasource = ref.watch(environmentDatasourceProvider);
+  return datasource.getEnvironment();
+}
+
+/// Provides whether air quality data is available.
+///
+/// Used for conditional rendering of AirQualityWidget.
+@riverpod
+bool hasAirQuality(Ref ref) {
+  final asyncValue = ref.watch(environmentProvider);
+  return asyncValue.maybeWhen(
+    data: (data) => data.airQuality != null,
+    orElse: () => false,
+  );
+}
@@ -0,0 +1,82 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'front_hall_state_provider.freezed.dart';
+part 'front_hall_state_provider.g.dart';
+
+/// Front Hall content display mode.
+enum FrontHallMode {
+  /// Shows dashboard widgets (stats, weather, etc.).
+  dashboard,
+
+  /// Shows embedded iframe content.
+  iframe,
+
+  /// Shows link management/settings UI.
+  settings,
+}
+
+/// State for Front Hall content area.
+@freezed
+sealed class FrontHallState with _$FrontHallState {
+  const factory FrontHallState({
+    /// Current display mode.
+    @Default(FrontHallMode.dashboard) FrontHallMode mode,
+
+    /// Active iframe URL (when mode is iframe).
+    String? activeIframeUrl,
+
+    /// Active iframe title (when mode is iframe).
+    String? activeIframeTitle,
+
+    /// Selected link ID for editing (when mode is settings).
+    /// Null means creating a new link.
+    String? selectedLinkId,
+  }) = _FrontHallState;
+
+  const FrontHallState._();
+}
+
+/// Controller for Front Hall state.
+@riverpod
+class FrontHallStateNotifier extends _$FrontHallStateNotifier {
+  @override
+  FrontHallState build() => const FrontHallState();
+
+  /// Shows the dashboard (default mode).
+  void showDashboard() {
+    state = const FrontHallState();
+  }
+
+  /// Shows an iframe with the given URL and title.
+  void showIframe(String url, String title) {
+    state = FrontHallState(
+      mode: FrontHallMode.iframe,
+      activeIframeUrl: url,
+      activeIframeTitle: title,
+    );
+  }
+
+  /// Enters settings mode, optionally selecting a link for editing.
+  void enterSettings({String? linkId}) {
+    state = FrontHallState(
+      mode: FrontHallMode.settings,
+      selectedLinkId: linkId,
+    );
+  }
+
+  /// Selects a link for editing (while in settings mode).
+  void selectLink(String linkId) {
+    state = state.copyWith(selectedLinkId: linkId);
+  }
+
+  /// Clears the selected link (for creating new).
+  void clearSelectedLink() {
+    state = state.copyWith(selectedLinkId: null);
+  }
+
+  /// Exits settings mode and returns to dashboard.
+  void exitSettings() {
+    state = const FrontHallState();
+  }
+}
@@ -0,0 +1,229 @@
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import 'package:tatlock_ui/features/front_hall/data/datasources/quick_links_datasource.dart';
+import 'package:tatlock_ui/features/front_hall/domain/entities/quick_link.dart';
+
+part 'quick_links_provider.g.dart';
+
+/// Provides the list of all quick links.
+/// Falls back to default links if API is unavailable.
+@riverpod
+Future<List<QuickLink>> quickLinks(Ref ref) async {
+  try {
+    final datasource = ref.watch(quickLinksDatasourceProvider);
+    final links = await datasource.getQuickLinks();
+    // Return defaults if API returns empty list
+    return links.isEmpty ? getDefaultQuickLinks() : links;
+  } catch (_) {
+    // Return default links if API fails (e.g., backend not running)
+    return getDefaultQuickLinks();
+  }
+}
+
+/// Provides a single quick link by ID.
+/// Falls back to default links if API is unavailable.
+@riverpod
+Future<QuickLink> quickLink(Ref ref, String id) async {
+  // First try to find in defaults (works offline)
+  final defaults = getDefaultQuickLinks();
+  final defaultLink = defaults.where((link) => link.id == id).firstOrNull;
+  if (defaultLink != null) {
+    return defaultLink;
+  }
+
+  // If not in defaults, try API
+  try {
+    final datasource = ref.watch(quickLinksDatasourceProvider);
+    final intId = int.tryParse(id);
+    if (intId == null) {
+      throw Exception('Invalid link ID: $id');
+    }
+    return await datasource.getQuickLink(intId);
+  } catch (_) {
+    throw Exception('Link not found: $id');
+  }
+}
+
+/// Controller for quick link CRUD operations.
+@riverpod
+class QuickLinkActions extends _$QuickLinkActions {
+  @override
+  AsyncValue<void> build() => const AsyncValue.data(null);
+
+  /// Safely sets state, ignoring disposal errors.
+  void _safeSetState(AsyncValue<void> newState) {
+    try {
+      state = newState;
+    } catch (_) {
+      // Provider was disposed - ignore
+    }
+  }
+
+  /// Safely invalidates providers after async operations.
+  void _safeInvalidate(List<ProviderOrFamily> providers) {
+    try {
+      for (final provider in providers) {
+        ref.invalidate(provider);
+      }
+    } catch (_) {
+      // Provider was disposed - ignore
+    }
+  }
+
+  /// Creates a new quick link.
+  Future<QuickLink?> create(QuickLink link) async {
+    QuickLink? result;
+    try {
+      _safeSetState(const AsyncValue.loading());
+      final datasource = ref.read(quickLinksDatasourceProvider);
+      result = await datasource.createQuickLink(link);
+      _safeInvalidate([quickLinksProvider]);
+      _safeSetState(const AsyncValue.data(null));
+    } catch (e, st) {
+      _safeSetState(AsyncValue.error(e, st));
+    }
+    return result;
+  }
+
+  /// Updates an existing quick link.
+  Future<QuickLink?> update(QuickLink link) async {
+    QuickLink? result;
+    try {
+      _safeSetState(const AsyncValue.loading());
+      final datasource = ref.read(quickLinksDatasourceProvider);
+      result = await datasource.updateQuickLink(link);
+      _safeInvalidate([quickLinksProvider, quickLinkProvider(link.id)]);
+      _safeSetState(const AsyncValue.data(null));
+    } catch (e, st) {
+      _safeSetState(AsyncValue.error(e, st));
+    }
+    return result;
+  }
+
+  /// Deletes a quick link.
+  Future<void> delete(String id) async {
+    try {
+      _safeSetState(const AsyncValue.loading());
+      final datasource = ref.read(quickLinksDatasourceProvider);
+      final intId = int.tryParse(id) ?? 0;
+      await datasource.deleteQuickLink(intId);
+      _safeInvalidate([quickLinksProvider]);
+      _safeSetState(const AsyncValue.data(null));
+    } catch (e, st) {
+      _safeSetState(AsyncValue.error(e, st));
+    }
+  }
+
+  /// Reorders quick links.
+  Future<void> reorder(List<String> orderedIds) async {
+    try {
+      _safeSetState(const AsyncValue.loading());
+      final datasource = ref.read(quickLinksDatasourceProvider);
+      final intIds = orderedIds.map((id) => int.tryParse(id) ?? 0).toList();
+      await datasource.reorderQuickLinks(intIds);
+      _safeInvalidate([quickLinksProvider]);
+      _safeSetState(const AsyncValue.data(null));
+    } catch (e, st) {
+      _safeSetState(AsyncValue.error(e, st));
+    }
+  }
+}
+
+/// Default seed data for quick links (used when API returns empty).
+List<QuickLink> getDefaultQuickLinks() {
+  return [
+    // Home category
+    const QuickLink(
+      id: 'jellyfin',
+      name: 'Jellyfin',
+      url: 'https://jellyfin.schweitz.net',
+      iconName: 'movie',
+      category: 'Home',
+      type: QuickLinkType.iframe,
+      sortOrder: 0,
+    ),
+    const QuickLink(
+      id: 'webui',
+      name: 'Open WebUI',
+      url: 'https://webui.schweitz.net',
+      iconName: 'chat',
+      category: 'Home',
+      type: QuickLinkType.iframe,
+      sortOrder: 1,
+    ),
+    const QuickLink(
+      id: 'searxng',
+      name: 'SearXNG',
+      url: 'https://search.schweitz.net',
+      iconName: 'search',
+      category: 'Home',
+      type: QuickLinkType.newTab,
+      sortOrder: 2,
+    ),
+    // AMP category
+    const QuickLink(
+      id: 'amp',
+      name: 'AMP Home',
+      url: 'https://amp.schweitz.net',
+      iconName: 'videogame_asset',
+      category: 'AMP',
+      type: QuickLinkType.newTab,
+      sortOrder: 0,
+    ),
+    // Coding category
+    const QuickLink(
+      id: 'gitea',
+      name: 'Gitea',
+      url: 'https://git.schweitz.net',
+      iconName: 'code',
+      category: 'Coding',
+      type: QuickLinkType.iframe,
+      sortOrder: 0,
+    ),
+    const QuickLink(
+      id: 'cloud-ide',
+      name: 'Cloud IDE',
+      url: 'https://code.schweitz.net',
+      iconName: 'terminal',
+      category: 'Coding',
+      type: QuickLinkType.newTab,
+      sortOrder: 1,
+    ),
+    // Infrastructure category
+    const QuickLink(
+      id: 'netdata',
+      name: 'Netdata',
+      url: 'https://netdata.schweitz.net',
+      iconName: 'monitoring',
+      category: 'Infrastructure',
+      type: QuickLinkType.iframe,
+      sortOrder: 0,
+    ),
+    const QuickLink(
+      id: 'portainer',
+      name: 'Portainer',
+      url: 'https://portainer.schweitz.net',
+      iconName: 'dns',
+      category: 'Infrastructure',
+      type: QuickLinkType.iframe,
+      sortOrder: 1,
+    ),
+    const QuickLink(
+      id: 'npm',
+      name: 'Proxy Manager',
+      url: 'https://npm.schweitz.net',
+      iconName: 'public',
+      category: 'Infrastructure',
+      type: QuickLinkType.iframe,
+      sortOrder: 2,
+    ),
+    const QuickLink(
+      id: 'core-api',
+      name: 'Core API',
+      url: 'https://api.schweitz.net/docs',
+      iconName: 'api',
+      category: 'Infrastructure',
+      type: QuickLinkType.iframe,
+      sortOrder: 3,
+    ),
+  ];
+}
@@ -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>);
+}
@@ -0,0 +1,386 @@
+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/environment_provider.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/forecast_widget.dart';
+import 'package:tatlock_ui/shared/widgets/sun_position_widget.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.
+/// 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? _systemStatsTimer;
+  Timer? _environmentTimer;
+
+  /// Tracks if we've logged the environment API user (log once per session)
+  static bool _hasLoggedEnvUser = false;
+  static String? _envApiUser;
+
+  /// Get the environment API user (available after first load)
+  static String? get envApiUser => _envApiUser;
+
+  @override
+  void initState() {
+    super.initState();
+    // Refresh system stats every 30 seconds
+    _systemStatsTimer = Timer.periodic(
+      const Duration(seconds: 30),
+      (_) => ref.invalidate(systemStatsProvider),
+    );
+    // Refresh environment data every hour
+    _environmentTimer = Timer.periodic(
+      const Duration(hours: 1),
+      (_) => ref.invalidate(environmentProvider),
+    );
+  }
+
+  @override
+  void dispose() {
+    _systemStatsTimer?.cancel();
+    _environmentTimer?.cancel();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final systemStatsAsync = ref.watch(systemStatsProvider);
+    final environmentAsync = ref.watch(environmentProvider);
+
+    return ListView(
+      padding: const EdgeInsets.all(16),
+      children: [
+        // Welcome card
+        Card(
+          child: Padding(
+            padding: const EdgeInsets.all(24),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Row(
+                  children: [
+                    Icon(
+                      Icons.waving_hand,
+                      size: 32,
+                      color: colorScheme.primary,
+                    ),
+                    const SizedBox(width: 12),
+                    Flexible(
+                      child: Text(
+                        'Welcome to Tatlock',
+                        style: Theme.of(context).textTheme.headlineSmall,
+                      ),
+                    ),
+                  ],
+                ),
+                const SizedBox(height: 12),
+                Text(
+                  'Your homelab dashboard is ready.',
+                  style: Theme.of(context).textTheme.bodyLarge?.copyWith(
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+                ),
+              ],
+            ),
+          ),
+        ),
+        const SizedBox(height: 16),
+
+        // System Stats - Gauges
+        _SectionHeader(title: 'System Stats', icon: Icons.monitor_heart),
+        const SizedBox(height: 8),
+        systemStatsAsync.when(
+          data: (stats) => _SystemStatsCard(stats: stats),
+          loading: () => const Card(
+            child: Padding(
+              padding: EdgeInsets.all(32),
+              child: Center(child: CircularProgressIndicator()),
+            ),
+          ),
+          error: (error, _) => Card(
+            child: Padding(
+              padding: const EdgeInsets.all(16),
+              child: Row(
+                children: [
+                  Icon(Icons.error_outline, color: colorScheme.error),
+                  const SizedBox(width: 12),
+                  Expanded(
+                    child: Text(
+                      'Failed to load system stats',
+                      style: TextStyle(color: colorScheme.error),
+                    ),
+                  ),
+                  IconButton(
+                    icon: const Icon(Icons.refresh),
+                    onPressed: () => ref.invalidate(systemStatsProvider),
+                  ),
+                ],
+              ),
+            ),
+          ),
+        ),
+        const SizedBox(height: 24),
+
+        // Environment - Sun, Weather, Forecast, Air Quality
+        const _SectionHeader(title: 'Environment', icon: Icons.eco),
+        const SizedBox(height: 8),
+        environmentAsync.when(
+          data: (envData) {
+            // Store and log user once per session
+            if (!_hasLoggedEnvUser && envData.user != null) {
+              _envApiUser = envData.user;
+              _hasLoggedEnvUser = true;
+              debugPrint('Environment API user: ${envData.user}');
+            }
+            return _EnvironmentSection(
+              envData: envData,
+              onRefresh: () => ref.invalidate(environmentProvider),
+            );
+          },
+          loading: () => const Card(
+            child: Padding(
+              padding: EdgeInsets.all(32),
+              child: Center(child: CircularProgressIndicator()),
+            ),
+          ),
+          error: (error, _) => Card(
+            child: Padding(
+              padding: const EdgeInsets.all(16),
+              child: Row(
+                children: [
+                  Icon(Icons.error_outline, color: colorScheme.error),
+                  const SizedBox(width: 12),
+                  Expanded(
+                    child: Text(
+                      'Failed to load environment data',
+                      style: TextStyle(color: colorScheme.error),
+                    ),
+                  ),
+                  IconButton(
+                    icon: const Icon(Icons.refresh),
+                    onPressed: () => ref.invalidate(environmentProvider),
+                  ),
+                ],
+              ),
+            ),
+          ),
+        ),
+        const SizedBox(height: 24),
+
+        // Version info
+        Center(
+          child: Text(
+            '${AppVersion.name} v${AppVersion.fullVersion}',
+            style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                  color: colorScheme.outline,
+                ),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Section header with icon and title.
+class _SectionHeader extends StatelessWidget {
+  const _SectionHeader({
+    required this.title,
+    required this.icon,
+  });
+
+  final String title;
+  final IconData icon;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Row(
+      children: [
+        Icon(
+          icon,
+          size: 18,
+          color: colorScheme.onSurfaceVariant,
+        ),
+        const SizedBox(width: 8),
+        Text(
+          title,
+          style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                color: colorScheme.onSurfaceVariant,
+                fontWeight: FontWeight.w500,
+              ),
+        ),
+      ],
+    );
+  }
+}
+
+/// 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;
+  }
+}
+
+/// Environment section displaying sun position, weather, air quality, and forecast.
+///
+/// Layout:
+/// - Desktop (>900px): 4 widgets in a row - Sun(30%) | Weather(20%) | AirQuality(20%) | Forecast(30%)
+/// - Tablet (600-900px): 2x2 grid
+/// - Mobile (<600px): Stacked vertically
+class _EnvironmentSection extends StatelessWidget {
+  const _EnvironmentSection({
+    required this.envData,
+    required this.onRefresh,
+  });
+
+  final dynamic envData;
+  final VoidCallback onRefresh;
+
+  @override
+  Widget build(BuildContext context) {
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        if (constraints.maxWidth > 900) {
+          // Desktop: 4 in a row (30/20/20/30) - wider widgets on outsides
+          return Row(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Expanded(
+                flex: 30,
+                child: SunPositionWidget(sunTimes: envData.sunTimes),
+              ),
+              const SizedBox(width: 12),
+              Expanded(
+                flex: 20,
+                child: WeatherWidget(apiData: envData.weather),
+              ),
+              const SizedBox(width: 12),
+              Expanded(
+                flex: 20,
+                child: AirQualityWidget(apiData: envData.airQuality),
+              ),
+              const SizedBox(width: 12),
+              Expanded(
+                flex: 30,
+                child: ForecastWidget(forecast: envData.forecast),
+              ),
+            ],
+          );
+        } else if (constraints.maxWidth > 600) {
+          // Tablet: 2x2 grid
+          return Column(
+            children: [
+              Row(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Expanded(
+                    child: SunPositionWidget(sunTimes: envData.sunTimes),
+                  ),
+                  const SizedBox(width: 12),
+                  Expanded(child: WeatherWidget(apiData: envData.weather)),
+                ],
+              ),
+              const SizedBox(height: 12),
+              Row(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Expanded(
+                    child: AirQualityWidget(apiData: envData.airQuality),
+                  ),
+                  const SizedBox(width: 12),
+                  Expanded(child: ForecastWidget(forecast: envData.forecast)),
+                ],
+              ),
+            ],
+          );
+        } else {
+          // Mobile: stacked vertically
+          return Column(
+            children: [
+              SunPositionWidget(sunTimes: envData.sunTimes),
+              const SizedBox(height: 12),
+              WeatherWidget(apiData: envData.weather),
+              const SizedBox(height: 12),
+              AirQualityWidget(apiData: envData.airQuality),
+              const SizedBox(height: 12),
+              ForecastWidget(forecast: envData.forecast),
+            ],
+          );
+        }
+      },
+    );
+  }
+}
@@ -0,0 +1,4 @@
+// Conditional export for platform-specific iframe implementation.
+// Web uses actual iframe embedding, other platforms open in browser.
+export 'iframe_view_stub.dart'
+    if (dart.library.html) 'iframe_view_web.dart';
@@ -0,0 +1,83 @@
+import 'package:flutter/material.dart';
+import 'package:url_launcher/url_launcher.dart';
+
+/// Stub implementation for non-web platforms.
+///
+/// Since iframes are web-only, this shows a message and offers
+/// to open the link in an external browser.
+class IframeView extends StatelessWidget {
+  const IframeView({
+    super.key,
+    required this.url,
+    required this.title,
+    required this.onClose,
+  });
+
+  final String url;
+  final String title;
+  final VoidCallback onClose;
+
+  Future<void> _openInBrowser() async {
+    final uri = Uri.tryParse(url);
+    if (uri != null && await canLaunchUrl(uri)) {
+      await launchUrl(uri, mode: LaunchMode.externalApplication);
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    // Auto-open in browser and show message
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      _openInBrowser();
+    });
+
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(32),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(
+              Icons.open_in_browser,
+              size: 64,
+              color: colorScheme.primary,
+            ),
+            const SizedBox(height: 16),
+            Text(
+              'Opening in Browser',
+              style: textTheme.titleLarge,
+            ),
+            const SizedBox(height: 8),
+            Text(
+              'Embedded views are not supported on this platform.\n"$title" is opening in your browser.',
+              textAlign: TextAlign.center,
+              style: textTheme.bodyMedium?.copyWith(
+                color: colorScheme.onSurfaceVariant,
+              ),
+            ),
+            const SizedBox(height: 24),
+            Row(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                OutlinedButton.icon(
+                  onPressed: _openInBrowser,
+                  icon: const Icon(Icons.open_in_new),
+                  label: const Text('Open Again'),
+                ),
+                const SizedBox(width: 12),
+                FilledButton.icon(
+                  onPressed: onClose,
+                  icon: const Icon(Icons.arrow_back),
+                  label: const Text('Back to Dashboard'),
+                ),
+              ],
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
@@ -0,0 +1,145 @@
+import 'dart:ui_web' as ui_web;
+
+import 'package:flutter/material.dart';
+import 'package:url_launcher/url_launcher.dart';
+import 'package:web/web.dart' as web;
+
+/// Embedded iframe view for displaying external content (web only).
+///
+/// Uses HtmlElementView for Flutter web to embed an iframe.
+/// Includes a header bar with title, refresh, open in new tab, and close actions.
+class IframeView extends StatefulWidget {
+  const IframeView({
+    super.key,
+    required this.url,
+    required this.title,
+    required this.onClose,
+  });
+
+  /// URL to display in the iframe.
+  final String url;
+
+  /// Title displayed in the header bar.
+  final String title;
+
+  /// Callback when the close button is pressed.
+  final VoidCallback onClose;
+
+  @override
+  State<IframeView> createState() => _IframeViewState();
+}
+
+class _IframeViewState extends State<IframeView> {
+  late final String _viewType;
+  late web.HTMLIFrameElement _iframe;
+  bool _isLoading = true;
+
+  @override
+  void initState() {
+    super.initState();
+    _viewType = 'iframe-${widget.url.hashCode}-${DateTime.now().millisecondsSinceEpoch}';
+    _createIframe();
+  }
+
+  void _createIframe() {
+    _iframe = web.document.createElement('iframe') as web.HTMLIFrameElement
+      ..src = widget.url
+      ..style.border = 'none'
+      ..style.width = '100%'
+      ..style.height = '100%'
+      ..allow = 'fullscreen';
+
+    _iframe.onLoad.listen((_) {
+      if (mounted) {
+        setState(() => _isLoading = false);
+      }
+    });
+
+    // Register the view factory
+    ui_web.platformViewRegistry.registerViewFactory(
+      _viewType,
+      (int viewId) => _iframe,
+    );
+  }
+
+  void _refresh() {
+    setState(() => _isLoading = true);
+    // Reload the iframe by setting src again
+    _iframe.src = widget.url;
+  }
+
+  Future<void> _openInNewTab() async {
+    final uri = Uri.tryParse(widget.url);
+    if (uri != null && await canLaunchUrl(uri)) {
+      await launchUrl(uri, mode: LaunchMode.externalApplication);
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Column(
+      children: [
+        // Header bar
+        Container(
+          height: 56,
+          padding: const EdgeInsets.symmetric(horizontal: 16),
+          decoration: BoxDecoration(
+            color: colorScheme.surfaceContainerHighest,
+            border: Border(
+              bottom: BorderSide(color: colorScheme.outlineVariant),
+            ),
+          ),
+          child: Row(
+            children: [
+              // Title
+              Expanded(
+                child: Text(
+                  widget.title,
+                  style: textTheme.titleSmall?.copyWith(
+                    fontWeight: FontWeight.w600,
+                  ),
+                  overflow: TextOverflow.ellipsis,
+                ),
+              ),
+              // Actions
+              IconButton(
+                icon: const Icon(Icons.open_in_new, size: 20),
+                tooltip: 'Open in new tab',
+                onPressed: _openInNewTab,
+              ),
+              IconButton(
+                icon: const Icon(Icons.refresh, size: 20),
+                tooltip: 'Refresh',
+                onPressed: _refresh,
+              ),
+              IconButton(
+                icon: const Icon(Icons.close, size: 20),
+                tooltip: 'Close',
+                onPressed: widget.onClose,
+              ),
+            ],
+          ),
+        ),
+        // Iframe content
+        Expanded(
+          child: Stack(
+            children: [
+              HtmlElementView(viewType: _viewType),
+              // Loading overlay
+              if (_isLoading)
+                Container(
+                  color: colorScheme.surface,
+                  child: const Center(
+                    child: CircularProgressIndicator(),
+                  ),
+                ),
+            ],
+          ),
+        ),
+      ],
+    );
+  }
+}
@@ -0,0 +1,343 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/features/front_hall/domain/entities/quick_link.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/quick_links_provider.dart';
+import 'package:tatlock_ui/shared/widgets/entity_page.dart';
+import 'package:tatlock_ui/shared/widgets/icon_picker.dart';
+
+/// Form for creating and editing Quick Links.
+///
+/// Handles validation, submission, and state management for link data.
+class QuickLinkForm extends ConsumerStatefulWidget {
+  const QuickLinkForm({
+    super.key,
+    required this.mode,
+    this.quickLink,
+    required this.onCancel,
+    required this.onSaved,
+  });
+
+  final EntityPageMode mode;
+  final QuickLink? quickLink;
+  final VoidCallback onCancel;
+  final VoidCallback onSaved;
+
+  @override
+  ConsumerState<QuickLinkForm> createState() => _QuickLinkFormState();
+}
+
+class _QuickLinkFormState extends ConsumerState<QuickLinkForm> {
+  final _formKey = GlobalKey<FormState>();
+
+  late final TextEditingController _nameController;
+  late final TextEditingController _urlController;
+  late final TextEditingController _categoryController;
+  late String _iconName;
+  late QuickLinkType _type;
+  late bool _isActive;
+
+  bool _isSubmitting = false;
+
+  @override
+  void initState() {
+    super.initState();
+    final link = widget.quickLink;
+    _nameController = TextEditingController(text: link?.name ?? '');
+    _urlController = TextEditingController(text: link?.url ?? '');
+    _categoryController = TextEditingController(text: link?.category ?? '');
+    _iconName = link?.iconName ?? 'link';
+    _type = link?.type ?? QuickLinkType.iframe;
+    _isActive = link?.isActive ?? true;
+  }
+
+  @override
+  void dispose() {
+    _nameController.dispose();
+    _urlController.dispose();
+    _categoryController.dispose();
+    super.dispose();
+  }
+
+  bool get isCreate => widget.mode == EntityPageMode.create;
+
+  Future<void> _handleSubmit() async {
+    if (!_formKey.currentState!.validate()) return;
+
+    setState(() => _isSubmitting = true);
+
+    try {
+      final actions = ref.read(quickLinkActionsProvider.notifier);
+      final category = _categoryController.text.trim();
+
+      final QuickLink link;
+      if (isCreate) {
+        // Create new entity
+        link = QuickLink(
+          id: _nameController.text.toLowerCase().replaceAll(RegExp(r'\s+'), '-'),
+          name: _nameController.text.trim(),
+          url: _urlController.text.trim(),
+          iconName: _iconName,
+          category: category.isEmpty ? null : category,
+          type: _type,
+          isActive: _isActive,
+          sortOrder: 0,
+        );
+        await actions.create(link);
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(
+              content: Text('Link created successfully'),
+              behavior: SnackBarBehavior.floating,
+            ),
+          );
+        }
+      } else {
+        // Update: use copyWith to preserve all existing data
+        link = widget.quickLink!.copyWith(
+          name: _nameController.text.trim(),
+          url: _urlController.text.trim(),
+          iconName: _iconName,
+          category: category.isEmpty ? null : category,
+          type: _type,
+          isActive: _isActive,
+        );
+        await actions.update(link);
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(
+              content: Text('Link updated successfully'),
+              behavior: SnackBarBehavior.floating,
+            ),
+          );
+        }
+      }
+
+      // Refresh the list before exiting
+      ref.invalidate(quickLinksProvider);
+
+      widget.onSaved();
+    } catch (e) {
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(
+            content: Text('Error: $e'),
+            behavior: SnackBarBehavior.floating,
+            backgroundColor: Theme.of(context).colorScheme.error,
+          ),
+        );
+      }
+    } finally {
+      if (mounted) {
+        setState(() => _isSubmitting = false);
+      }
+    }
+  }
+
+  Future<void> _handleDelete() async {
+    if (widget.quickLink == null) return;
+
+    final confirm = await showDialog<bool>(
+      context: context,
+      builder: (context) => AlertDialog(
+        title: const Text('Delete Link'),
+        content: Text('Are you sure you want to delete "${widget.quickLink!.name}"?'),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.of(context).pop(false),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.of(context).pop(true),
+            style: FilledButton.styleFrom(
+              backgroundColor: Theme.of(context).colorScheme.error,
+            ),
+            child: const Text('Delete'),
+          ),
+        ],
+      ),
+    );
+
+    if (confirm == true) {
+      setState(() => _isSubmitting = true);
+      try {
+        await ref.read(quickLinkActionsProvider.notifier).delete(widget.quickLink!.id);
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(
+              content: Text('Link deleted'),
+              behavior: SnackBarBehavior.floating,
+            ),
+          );
+          widget.onSaved();
+        }
+      } catch (e) {
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(
+              content: Text('Error deleting: $e'),
+              behavior: SnackBarBehavior.floating,
+              backgroundColor: Theme.of(context).colorScheme.error,
+            ),
+          );
+        }
+      } finally {
+        if (mounted) {
+          setState(() => _isSubmitting = false);
+        }
+      }
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Form(
+      key: _formKey,
+      child: ListView(
+        padding: const EdgeInsets.all(24),
+        children: [
+          // Name field
+          TextFormField(
+            controller: _nameController,
+            decoration: const InputDecoration(
+              labelText: 'Name',
+              hintText: 'Enter link name',
+              border: OutlineInputBorder(),
+            ),
+            validator: (value) {
+              if (value == null || value.trim().isEmpty) {
+                return 'Name is required';
+              }
+              return null;
+            },
+            textInputAction: TextInputAction.next,
+          ),
+          const SizedBox(height: 16),
+
+          // URL field
+          TextFormField(
+            controller: _urlController,
+            decoration: const InputDecoration(
+              labelText: 'URL',
+              hintText: 'https://example.com',
+              border: OutlineInputBorder(),
+            ),
+            validator: (value) {
+              if (value == null || value.trim().isEmpty) {
+                return 'URL is required';
+              }
+              final uri = Uri.tryParse(value);
+              if (uri == null || !uri.hasScheme) {
+                return 'Enter a valid URL with scheme (http/https)';
+              }
+              return null;
+            },
+            keyboardType: TextInputType.url,
+            textInputAction: TextInputAction.next,
+          ),
+          const SizedBox(height: 16),
+
+          // Category field
+          TextFormField(
+            controller: _categoryController,
+            decoration: const InputDecoration(
+              labelText: 'Category',
+              hintText: 'e.g., Home, Infrastructure, Coding',
+              border: OutlineInputBorder(),
+            ),
+            textInputAction: TextInputAction.done,
+          ),
+          const SizedBox(height: 24),
+
+          // Icon picker
+          IconPicker(
+            selectedIcon: _iconName,
+            onChanged: (icon) => setState(() => _iconName = icon),
+          ),
+          const SizedBox(height: 24),
+
+          // Link type
+          Text(
+            'Link Type',
+            style: Theme.of(context).textTheme.labelMedium?.copyWith(
+                  color: colorScheme.onSurfaceVariant,
+                ),
+          ),
+          const SizedBox(height: 8),
+          SegmentedButton<QuickLinkType>(
+            segments: const [
+              ButtonSegment(
+                value: QuickLinkType.iframe,
+                icon: Icon(Icons.web),
+                label: Text('Iframe'),
+              ),
+              ButtonSegment(
+                value: QuickLinkType.newTab,
+                icon: Icon(Icons.open_in_new),
+                label: Text('New Tab'),
+              ),
+            ],
+            selected: {_type},
+            onSelectionChanged: (selected) {
+              setState(() => _type = selected.first);
+            },
+          ),
+          const SizedBox(height: 8),
+          Text(
+            _type == QuickLinkType.iframe
+                ? 'Opens embedded in the dashboard'
+                : 'Opens in a new browser tab',
+            style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                  color: colorScheme.outline,
+                ),
+          ),
+          const SizedBox(height: 24),
+
+          // Active toggle
+          SwitchListTile(
+            title: const Text('Active'),
+            subtitle: const Text('Show this link in the panel'),
+            value: _isActive,
+            onChanged: (value) => setState(() => _isActive = value),
+            contentPadding: EdgeInsets.zero,
+          ),
+          const SizedBox(height: 32),
+
+          // Action buttons
+          Row(
+            children: [
+              if (!isCreate) ...[
+                OutlinedButton.icon(
+                  onPressed: _isSubmitting ? null : _handleDelete,
+                  style: OutlinedButton.styleFrom(
+                    foregroundColor: colorScheme.error,
+                  ),
+                  icon: const Icon(Icons.delete),
+                  label: const Text('Delete'),
+                ),
+                const Spacer(),
+              ] else
+                const Spacer(),
+              TextButton(
+                onPressed: _isSubmitting ? null : widget.onCancel,
+                child: const Text('Cancel'),
+              ),
+              const SizedBox(width: 8),
+              FilledButton(
+                onPressed: _isSubmitting ? null : _handleSubmit,
+                child: _isSubmitting
+                    ? const SizedBox(
+                        width: 20,
+                        height: 20,
+                        child: CircularProgressIndicator(strokeWidth: 2),
+                      )
+                    : Text(isCreate ? 'Create' : 'Save'),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  }
+}
@@ -0,0 +1,147 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/front_hall_state_provider.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/quick_links_provider.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/widgets/quick_link_form.dart';
+import 'package:tatlock_ui/shared/widgets/entity_page.dart';
+
+/// Settings content for Quick Link management.
+///
+/// Shows either:
+/// - Create form (when isCreating state is set)
+/// - Edit form (when a link is selected)
+/// - Empty state with "Add New Link" prompt (when no link selected)
+class QuickLinkSettingsContent extends ConsumerStatefulWidget {
+  const QuickLinkSettingsContent({super.key});
+
+  @override
+  ConsumerState<QuickLinkSettingsContent> createState() =>
+      _QuickLinkSettingsContentState();
+}
+
+class _QuickLinkSettingsContentState
+    extends ConsumerState<QuickLinkSettingsContent> {
+  bool _isCreating = false;
+
+  void _startCreating() {
+    setState(() => _isCreating = true);
+    // Clear any selected link when creating new
+    ref.read(frontHallStateProvider.notifier).clearSelectedLink();
+  }
+
+  void _stopCreating() {
+    setState(() => _isCreating = false);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final frontHallState = ref.watch(frontHallStateProvider);
+    final selectedLinkId = frontHallState.selectedLinkId;
+
+    // Create mode - show create form
+    if (_isCreating) {
+      return Scaffold(
+        appBar: AppBar(
+          leading: IconButton(
+            icon: const Icon(Icons.arrow_back),
+            onPressed: _stopCreating,
+          ),
+          title: const Text('Create New Link'),
+        ),
+        body: QuickLinkForm(
+          mode: EntityPageMode.create,
+          onCancel: _stopCreating,
+          onSaved: () =>
+              ref.read(frontHallStateProvider.notifier).exitSettings(),
+        ),
+      );
+    }
+
+    // No link selected - show empty state
+    if (selectedLinkId == null) {
+      return Center(
+        child: Padding(
+          padding: const EdgeInsets.all(32),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Icon(
+                Icons.add_link,
+                size: 64,
+                color: colorScheme.outline,
+              ),
+              const SizedBox(height: 16),
+              Text(
+                'No link selected',
+                style: textTheme.titleLarge?.copyWith(
+                  color: colorScheme.onSurfaceVariant,
+                ),
+              ),
+              const SizedBox(height: 8),
+              Text(
+                'Select a link from the panel to edit, or create a new one.',
+                textAlign: TextAlign.center,
+                style: textTheme.bodyMedium?.copyWith(
+                  color: colorScheme.outline,
+                ),
+              ),
+              const SizedBox(height: 24),
+              FilledButton.icon(
+                onPressed: _startCreating,
+                icon: const Icon(Icons.add),
+                label: const Text('Create New Link'),
+              ),
+            ],
+          ),
+        ),
+      );
+    }
+
+    // Link selected - show edit form
+    final linkAsync = ref.watch(quickLinkProvider(selectedLinkId));
+
+    return linkAsync.when(
+      loading: () => const Center(child: CircularProgressIndicator()),
+      error: (error, _) => Center(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(Icons.error_outline, size: 48, color: colorScheme.error),
+            const SizedBox(height: 16),
+            Text('Error loading link: $error'),
+            const SizedBox(height: 16),
+            TextButton.icon(
+              onPressed: () =>
+                  ref.invalidate(quickLinkProvider(selectedLinkId)),
+              icon: const Icon(Icons.refresh),
+              label: const Text('Retry'),
+            ),
+          ],
+        ),
+      ),
+      data: (link) => Scaffold(
+        appBar: AppBar(
+          leading: IconButton(
+            icon: const Icon(Icons.arrow_back),
+            onPressed: () => ref
+                .read(frontHallStateProvider.notifier)
+                .clearSelectedLink(),
+          ),
+          title: Text('Edit: ${link.name}'),
+        ),
+        body: QuickLinkForm(
+          key: ValueKey(link.id), // Force recreation when link changes
+          mode: EntityPageMode.edit,
+          quickLink: link,
+          onCancel: () => ref
+              .read(frontHallStateProvider.notifier)
+              .clearSelectedLink(),
+          onSaved: () =>
+              ref.read(frontHallStateProvider.notifier).exitSettings(),
+        ),
+      ),
+    );
+  }
+}
@@ -0,0 +1,683 @@
+import 'dart:ui' show lerpDouble;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/features/front_hall/domain/entities/quick_link.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/front_hall_state_provider.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/providers/quick_links_provider.dart';
+import 'package:tatlock_ui/shared/layouts/widgets/panel_header.dart';
+import 'package:tatlock_ui/shared/widgets/icon_picker.dart';
+import 'package:url_launcher/url_launcher.dart';
+
+/// Left-side panel for quick link navigation in Front Hall.
+///
+/// Shows categorized links that can open in iframe or new tab.
+/// Adapts behavior based on current mode (normal vs settings).
+class QuickLinksPanel extends ConsumerWidget {
+  const QuickLinksPanel({
+    super.key,
+    this.width = 280,
+  });
+
+  final double width;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final frontHallState = ref.watch(frontHallStateProvider);
+    final quickLinksAsync = ref.watch(quickLinksProvider);
+    final isSettingsMode = frontHallState.mode == FrontHallMode.settings;
+
+    return SizedBox(
+      width: width,
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        children: [
+          // Header changes based on mode
+          if (isSettingsMode)
+            _SettingsModeHeader(
+              onBack: () =>
+                  ref.read(frontHallStateProvider.notifier).exitSettings(),
+            )
+          else
+            PanelHeader(
+              title: 'Quick Links',
+              icon: Icons.link,
+              dockToBottom: true,
+              actions: [
+                IconButton(
+                  icon: const Icon(Icons.refresh, size: 20),
+                  tooltip: 'Refresh',
+                  onPressed: () => ref.invalidate(quickLinksProvider),
+                  padding: EdgeInsets.zero,
+                  constraints: const BoxConstraints(),
+                ),
+              ],
+            ),
+
+          // Add new link button (settings mode only)
+          if (isSettingsMode) ...[
+            Padding(
+              padding: const EdgeInsets.all(8),
+              child: FilledButton.icon(
+                onPressed: () => ref
+                    .read(frontHallStateProvider.notifier)
+                    .clearSelectedLink(),
+                icon: const Icon(Icons.add, size: 18),
+                label: const Text('Add New Link'),
+              ),
+            ),
+            Divider(height: 1, color: colorScheme.outlineVariant),
+          ],
+
+          // Links list
+          Expanded(
+            child: quickLinksAsync.when(
+              loading: () => const Center(child: CircularProgressIndicator()),
+              error: (error, _) => _ErrorState(
+                error: error,
+                onRetry: () => ref.invalidate(quickLinksProvider),
+              ),
+              data: (links) {
+                // Use default links if empty
+                final displayLinks =
+                    links.isEmpty ? getDefaultQuickLinks() : links;
+                return _QuickLinksList(
+                  links: displayLinks,
+                  selectedLinkId: frontHallState.selectedLinkId,
+                  isSettingsMode: isSettingsMode,
+                );
+              },
+            ),
+          ),
+
+          // Settings button (normal mode only)
+          if (!isSettingsMode) ...[
+            Divider(height: 1, color: colorScheme.outlineVariant),
+            Padding(
+              padding: const EdgeInsets.all(8),
+              child: TextButton.icon(
+                onPressed: () => ref
+                    .read(frontHallStateProvider.notifier)
+                    .enterSettings(),
+                icon: const Icon(Icons.settings, size: 18),
+                label: const Text('Settings'),
+              ),
+            ),
+          ],
+        ],
+      ),
+    );
+  }
+}
+
+/// Header for settings mode with back button.
+class _SettingsModeHeader extends StatelessWidget {
+  const _SettingsModeHeader({required this.onBack});
+
+  final VoidCallback onBack;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Container(
+      height: 56,
+      padding: const EdgeInsets.symmetric(horizontal: 8),
+      decoration: BoxDecoration(
+        color: colorScheme.surfaceContainerHighest,
+        border: Border(
+          bottom: BorderSide(color: colorScheme.outlineVariant),
+        ),
+      ),
+      child: Row(
+        children: [
+          IconButton(
+            icon: const Icon(Icons.arrow_back),
+            tooltip: 'Back to Dashboard',
+            onPressed: onBack,
+          ),
+          const SizedBox(width: 4),
+          Icon(Icons.link, size: 20, color: colorScheme.primary),
+          const SizedBox(width: 8),
+          Text(
+            'Quick Links',
+            style: textTheme.titleSmall?.copyWith(
+              fontWeight: FontWeight.w600,
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+/// List of quick links grouped by category.
+///
+/// In settings mode, shows a flat reorderable list.
+/// In normal mode, shows grouped list with category headers.
+class _QuickLinksList extends ConsumerWidget {
+  const _QuickLinksList({
+    required this.links,
+    required this.selectedLinkId,
+    required this.isSettingsMode,
+  });
+
+  final List<QuickLink> links;
+  final String? selectedLinkId;
+  final bool isSettingsMode;
+
+  /// Groups links by category, preserving order.
+  List<(String?, List<QuickLink>)> get _groupedLinks {
+    final groups = <String?, List<QuickLink>>{};
+    final order = <String?>[];
+
+    for (final link in links) {
+      if (!groups.containsKey(link.category)) {
+        groups[link.category] = [];
+        order.add(link.category);
+      }
+      groups[link.category]!.add(link);
+    }
+
+    return order.map((category) => (category, groups[category]!)).toList();
+  }
+
+  bool get _showCategoryHeaders {
+    final categories =
+        links.map((l) => l.category).where((c) => c != null).toSet();
+    return categories.length > 1;
+  }
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    // In settings mode, show reorderable list
+    if (isSettingsMode) {
+      return _buildReorderableList(context, ref);
+    }
+
+    // In normal mode, show grouped list
+    return ListView(
+      padding: const EdgeInsets.symmetric(vertical: 8),
+      children: _buildLinkList(context, ref),
+    );
+  }
+
+  Widget _buildReorderableList(BuildContext context, WidgetRef ref) {
+    return ReorderableListView.builder(
+      padding: const EdgeInsets.symmetric(vertical: 8),
+      itemCount: links.length,
+      onReorder: (oldIndex, newIndex) => _handleReorder(ref, oldIndex, newIndex),
+      proxyDecorator: (child, index, animation) {
+        return AnimatedBuilder(
+          animation: animation,
+          builder: (context, child) {
+            final elevation = lerpDouble(0, 8, animation.value) ?? 0;
+            return Material(
+              elevation: elevation,
+              borderRadius: BorderRadius.circular(8),
+              child: child,
+            );
+          },
+          child: child,
+        );
+      },
+      itemBuilder: (context, index) {
+        final link = links[index];
+        return _ReorderableLinkTile(
+          key: ValueKey(link.id),
+          link: link,
+          index: index,
+          isSelected: link.id == selectedLinkId,
+          onTap: () => _handleLinkTap(ref, link),
+          onEdit: () => ref
+              .read(frontHallStateProvider.notifier)
+              .selectLink(link.id),
+          onDelete: () => _handleDelete(context, ref, link),
+        );
+      },
+    );
+  }
+
+  void _handleReorder(WidgetRef ref, int oldIndex, int newIndex) {
+    // Adjust for the removal
+    if (newIndex > oldIndex) {
+      newIndex -= 1;
+    }
+
+    // Create new ordered list
+    final reorderedLinks = List<QuickLink>.from(links);
+    final item = reorderedLinks.removeAt(oldIndex);
+    reorderedLinks.insert(newIndex, item);
+
+    // Extract IDs in new order
+    final orderedIds = reorderedLinks.map((l) => l.id).toList();
+
+    // Call reorder API
+    ref.read(quickLinkActionsProvider.notifier).reorder(orderedIds);
+  }
+
+  List<Widget> _buildLinkList(BuildContext context, WidgetRef ref) {
+    final widgets = <Widget>[];
+    final showHeaders = _showCategoryHeaders;
+
+    for (final (category, categoryLinks) in _groupedLinks) {
+      // Add category header if multiple categories exist
+      if (showHeaders && category != null) {
+        widgets.add(_CategoryHeader(title: category));
+      }
+
+      // Add links
+      for (final link in categoryLinks) {
+        widgets.add(
+          _QuickLinkTile(
+            link: link,
+            isSelected: link.id == selectedLinkId,
+            isSettingsMode: isSettingsMode,
+            onTap: () => _handleLinkTap(ref, link),
+            onEdit: isSettingsMode
+                ? () => ref
+                    .read(frontHallStateProvider.notifier)
+                    .selectLink(link.id)
+                : null,
+            onDelete: isSettingsMode
+                ? () => _handleDelete(context, ref, link)
+                : null,
+          ),
+        );
+      }
+    }
+
+    return widgets;
+  }
+
+  void _handleLinkTap(WidgetRef ref, QuickLink link) {
+    if (isSettingsMode) {
+      // In settings mode, select link for editing
+      ref.read(frontHallStateProvider.notifier).selectLink(link.id);
+    } else {
+      // Close any open content first to ensure clean state
+      ref.read(frontHallStateProvider.notifier).showDashboard();
+
+      // Then open the new link
+      if (link.isIframe) {
+        ref
+            .read(frontHallStateProvider.notifier)
+            .showIframe(link.url, link.name);
+      } else {
+        // Open in new tab
+        _openInNewTab(link.url);
+      }
+    }
+  }
+
+  Future<void> _openInNewTab(String url) async {
+    final uri = Uri.tryParse(url);
+    if (uri != null && await canLaunchUrl(uri)) {
+      await launchUrl(uri, mode: LaunchMode.externalApplication);
+    }
+  }
+
+  Future<void> _handleDelete(
+    BuildContext context,
+    WidgetRef ref,
+    QuickLink link,
+  ) async {
+    final confirmed = await showDialog<bool>(
+      context: context,
+      builder: (context) => AlertDialog(
+        title: const Text('Delete Link'),
+        content: Text('Delete "${link.name}"?'),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(context, false),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.pop(context, true),
+            child: const Text('Delete'),
+          ),
+        ],
+      ),
+    );
+
+    if (confirmed == true) {
+      await ref.read(quickLinkActionsProvider.notifier).delete(link.id);
+    }
+  }
+}
+
+/// Reorderable link tile with drag handle for settings mode.
+class _ReorderableLinkTile extends StatelessWidget {
+  const _ReorderableLinkTile({
+    super.key,
+    required this.link,
+    required this.index,
+    required this.isSelected,
+    required this.onTap,
+    required this.onEdit,
+    required this.onDelete,
+  });
+
+  final QuickLink link;
+  final int index;
+  final bool isSelected;
+  final VoidCallback onTap;
+  final VoidCallback onEdit;
+  final VoidCallback onDelete;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Padding(
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+      child: Material(
+        color: isSelected
+            ? colorScheme.primaryContainer.withValues(alpha: 0.4)
+            : Colors.transparent,
+        borderRadius: BorderRadius.circular(8),
+        child: InkWell(
+          onTap: onTap,
+          borderRadius: BorderRadius.circular(8),
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 10),
+            child: Row(
+              children: [
+                // Drag handle
+                ReorderableDragStartListener(
+                  index: index,
+                  child: MouseRegion(
+                    cursor: SystemMouseCursors.grab,
+                    child: Icon(
+                      Icons.drag_indicator,
+                      size: 20,
+                      color: colorScheme.outline,
+                    ),
+                  ),
+                ),
+                const SizedBox(width: 8),
+                // Icon
+                Icon(
+                  getIconData(link.iconName),
+                  size: 20,
+                  color: isSelected
+                      ? colorScheme.primary
+                      : colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 12),
+                // Name and subtitle
+                Expanded(
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      Text(
+                        link.name,
+                        style: textTheme.bodyMedium?.copyWith(
+                          color: isSelected
+                              ? colorScheme.primary
+                              : colorScheme.onSurface,
+                          fontWeight: isSelected ? FontWeight.w600 : null,
+                        ),
+                      ),
+                      Text(
+                        link.category ?? 'No category',
+                        style: textTheme.bodySmall?.copyWith(
+                          color: colorScheme.outline,
+                          fontSize: 11,
+                        ),
+                      ),
+                    ],
+                  ),
+                ),
+                // Overflow menu
+                PopupMenuButton<String>(
+                  icon: Icon(
+                    Icons.more_vert,
+                    size: 18,
+                    color: colorScheme.onSurfaceVariant,
+                  ),
+                  padding: EdgeInsets.zero,
+                  itemBuilder: (context) => [
+                    const PopupMenuItem(
+                      value: 'edit',
+                      child: Row(
+                        children: [
+                          Icon(Icons.edit, size: 18),
+                          SizedBox(width: 8),
+                          Text('Edit'),
+                        ],
+                      ),
+                    ),
+                    const PopupMenuItem(
+                      value: 'delete',
+                      child: Row(
+                        children: [
+                          Icon(Icons.delete, size: 18),
+                          SizedBox(width: 8),
+                          Text('Delete'),
+                        ],
+                      ),
+                    ),
+                  ],
+                  onSelected: (value) {
+                    switch (value) {
+                      case 'edit':
+                        onEdit();
+                      case 'delete':
+                        onDelete();
+                    }
+                  },
+                ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+/// Category header with left accent bar.
+class _CategoryHeader extends StatelessWidget {
+  const _CategoryHeader({required this.title});
+
+  final String title;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Container(
+      margin: const EdgeInsets.only(top: 8, bottom: 4),
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 6),
+      decoration: BoxDecoration(
+        color: colorScheme.surfaceContainerHigh,
+        border: Border(
+          left: BorderSide(
+            color: colorScheme.primary,
+            width: 2,
+          ),
+        ),
+      ),
+      child: Text(
+        title.toUpperCase(),
+        style: textTheme.labelSmall?.copyWith(
+          color: colorScheme.onSurfaceVariant,
+          letterSpacing: 0.5,
+          fontWeight: FontWeight.w600,
+        ),
+      ),
+    );
+  }
+}
+
+/// Individual quick link tile.
+class _QuickLinkTile extends StatelessWidget {
+  const _QuickLinkTile({
+    required this.link,
+    required this.isSelected,
+    required this.isSettingsMode,
+    required this.onTap,
+    this.onEdit,
+    this.onDelete,
+  });
+
+  final QuickLink link;
+  final bool isSelected;
+  final bool isSettingsMode;
+  final VoidCallback onTap;
+  final VoidCallback? onEdit;
+  final VoidCallback? onDelete;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Padding(
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+      child: Material(
+        color: isSelected
+            ? colorScheme.primaryContainer.withValues(alpha: 0.4)
+            : Colors.transparent,
+        borderRadius: BorderRadius.circular(8),
+        child: InkWell(
+          onTap: onTap,
+          borderRadius: BorderRadius.circular(8),
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
+            child: Row(
+              children: [
+                Icon(
+                  getIconData(link.iconName),
+                  size: 20,
+                  color: isSelected
+                      ? colorScheme.primary
+                      : colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 12),
+                Expanded(
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      Text(
+                        link.name,
+                        style: textTheme.bodyMedium?.copyWith(
+                          color:
+                              isSelected ? colorScheme.primary : colorScheme.onSurface,
+                          fontWeight: isSelected ? FontWeight.w600 : null,
+                        ),
+                      ),
+                      if (isSettingsMode)
+                        Text(
+                          link.isNewTab ? 'Opens in new tab' : 'Opens in iframe',
+                          style: textTheme.bodySmall?.copyWith(
+                            color: colorScheme.outline,
+                            fontSize: 11,
+                          ),
+                        ),
+                    ],
+                  ),
+                ),
+                // New tab indicator (normal mode)
+                if (!isSettingsMode && link.isNewTab)
+                  Icon(
+                    Icons.open_in_new,
+                    size: 14,
+                    color: colorScheme.outline,
+                  ),
+                // Overflow menu (settings mode)
+                if (isSettingsMode)
+                  PopupMenuButton<String>(
+                    icon: Icon(
+                      Icons.more_vert,
+                      size: 18,
+                      color: colorScheme.onSurfaceVariant,
+                    ),
+                    padding: EdgeInsets.zero,
+                    itemBuilder: (context) => [
+                      const PopupMenuItem(
+                        value: 'edit',
+                        child: Row(
+                          children: [
+                            Icon(Icons.edit, size: 18),
+                            SizedBox(width: 8),
+                            Text('Edit'),
+                          ],
+                        ),
+                      ),
+                      const PopupMenuItem(
+                        value: 'delete',
+                        child: Row(
+                          children: [
+                            Icon(Icons.delete, size: 18),
+                            SizedBox(width: 8),
+                            Text('Delete'),
+                          ],
+                        ),
+                      ),
+                    ],
+                    onSelected: (value) {
+                      switch (value) {
+                        case 'edit':
+                          onEdit?.call();
+                        case 'delete':
+                          onDelete?.call();
+                      }
+                    },
+                  ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+/// Error state widget.
+class _ErrorState extends StatelessWidget {
+  const _ErrorState({
+    required this.error,
+    required this.onRetry,
+  });
+
+  final Object error;
+  final VoidCallback onRetry;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(
+              Icons.error_outline,
+              color: colorScheme.error,
+              size: 32,
+            ),
+            const SizedBox(height: 8),
+            Text(
+              'Failed to load links',
+              style: TextStyle(color: colorScheme.error),
+            ),
+            const SizedBox(height: 8),
+            TextButton.icon(
+              onPressed: onRetry,
+              icon: const Icon(Icons.refresh, size: 16),
+              label: const Text('Retry'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
@@ -0,0 +1,38 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+import 'package:tatlock_ui/features/front_hall/presentation/pages/front_hall_page.dart';
+import 'package:tatlock_ui/routing/app_router.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
+
+/// Route paths for Front Hall.
+abstract class FrontHallRoutes {
+  static const base = '/front-hall';
+}
+
+/// Front Hall room definition.
+final frontHallRoom = RoomDefinition(
+  id: 'front-hall',
+  label: 'Front Hall',
+  icon: Icons.door_front_door_outlined,
+  selectedIcon: Icons.door_front_door,
+  defaultRoute: FrontHallRoutes.base,
+  routes: frontHallRoutes,
+  // No permissions required - accessible to all authenticated users
+);
+
+/// Register Front Hall with the room registry.
+void registerFrontHall() {
+  roomRegistry.register(frontHallRoom);
+}
+
+/// Front Hall routes for go_router.
+List<RouteBase> frontHallRoutes() {
+  return [
+    GoRoute(
+      path: FrontHallRoutes.base,
+      name: 'frontHall',
+      pageBuilder: (context, state) =>
+          noTransitionPage(context, state, const FrontHallPage()),
+    ),
+  ];
+}
@@ -0,0 +1,36 @@
+import 'package:flutter/material.dart';
+
+/// Media Room - media management and playback.
+///
+/// Placeholder page for future implementation.
+class MediaRoomPage extends StatelessWidget {
+  const MediaRoomPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Center(
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
+        children: [
+          Icon(
+            Icons.movie,
+            size: 64,
+            color: Theme.of(context).colorScheme.outline,
+          ),
+          const SizedBox(height: 16),
+          Text(
+            'Media Room',
+            style: Theme.of(context).textTheme.headlineMedium,
+          ),
+          const SizedBox(height: 8),
+          Text(
+            'Media management and playback - coming soon',
+            style: Theme.of(context).textTheme.bodyLarge?.copyWith(
+                  color: Theme.of(context).colorScheme.outline,
+                ),
+          ),
+        ],
+      ),
+    );
+  }
+}
@@ -0,0 +1,38 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+import 'package:tatlock_ui/features/media_room/presentation/pages/media_room_page.dart';
+import 'package:tatlock_ui/routing/app_router.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
+
+/// Route paths for Media Room.
+abstract class MediaRoomRoutes {
+  static const base = '/media-room';
+}
+
+/// Media Room room definition.
+final mediaRoomRoom = RoomDefinition(
+  id: 'media-room',
+  label: 'Media Room',
+  icon: Icons.movie_outlined,
+  selectedIcon: Icons.movie,
+  defaultRoute: MediaRoomRoutes.base,
+  routes: mediaRoomRoutes,
+  // No permissions required - accessible to all authenticated users
+);
+
+/// Register Media Room with the room registry.
+void registerMediaRoom() {
+  roomRegistry.register(mediaRoomRoom);
+}
+
+/// Media Room routes for go_router.
+List<RouteBase> mediaRoomRoutes() {
+  return [
+    GoRoute(
+      path: MediaRoomRoutes.base,
+      name: 'mediaRoom',
+      pageBuilder: (context, state) =>
+          noTransitionPage(context, state, const MediaRoomPage()),
+    ),
+  ];
+}
@@ -0,0 +1,36 @@
+import 'package:flutter/material.dart';
+
+/// Parlor - AI chat and automation hub.
+///
+/// Placeholder page for future implementation.
+class ParlorPage extends StatelessWidget {
+  const ParlorPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Center(
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
+        children: [
+          Icon(
+            Icons.lightbulb,
+            size: 64,
+            color: Theme.of(context).colorScheme.outline,
+          ),
+          const SizedBox(height: 16),
+          Text(
+            'Parlor',
+            style: Theme.of(context).textTheme.headlineMedium,
+          ),
+          const SizedBox(height: 8),
+          Text(
+            'AI chat and automation hub - coming soon',
+            style: Theme.of(context).textTheme.bodyLarge?.copyWith(
+                  color: Theme.of(context).colorScheme.outline,
+                ),
+          ),
+        ],
+      ),
+    );
+  }
+}
@@ -0,0 +1,38 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+import 'package:tatlock_ui/features/parlor/presentation/pages/parlor_page.dart';
+import 'package:tatlock_ui/routing/app_router.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
+
+/// Route paths for Parlor.
+abstract class ParlorRoutes {
+  static const base = '/parlor';
+}
+
+/// Parlor room definition.
+final parlorRoom = RoomDefinition(
+  id: 'parlor',
+  label: 'Parlor',
+  icon: Icons.lightbulb_outline,
+  selectedIcon: Icons.lightbulb,
+  defaultRoute: ParlorRoutes.base,
+  routes: parlorRoutes,
+  // No permissions required - accessible to all authenticated users
+);
+
+/// Register Parlor with the room registry.
+void registerParlor() {
+  roomRegistry.register(parlorRoom);
+}
+
+/// Parlor routes for go_router.
+List<RouteBase> parlorRoutes() {
+  return [
+    GoRoute(
+      path: ParlorRoutes.base,
+      name: 'parlor',
+      pageBuilder: (context, state) =>
+          noTransitionPage(context, state, const ParlorPage()),
+    ),
+  ];
+}
@@ -1,6 +1,10 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';

@@ -31,7 +35,10 @@ class GroupData {

 /// Groups list page using the shared DataGrid component.
 class GroupsListPage extends ConsumerStatefulWidget {
-  const GroupsListPage({super.key});
+  const GroupsListPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;

  @override
  ConsumerState<GroupsListPage> createState() => _GroupsListPageState();
@@ -40,11 +47,19 @@ class GroupsListPage extends ConsumerStatefulWidget {
 class _GroupsListPageState extends ConsumerState<GroupsListPage> {
  late final StateNotifierProvider<DataGridController<GroupData>,
      DataGridState<GroupData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;
  bool _isSyncing = false;

  @override
  void initState() {
    super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
    // Create provider in initState to ensure stable reference
    final dio = ref.read(coreApiClientProvider);
    final source = CoreApiDataSource<GroupData>(
@@ -53,13 +68,63 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
      fromJson: GroupData.fromJson,
    );

+    // Initialize grid with URL state
    _gridProvider = dataGridProvider<GroupData>(
      source: source,
      config: _buildConfig(),
      idSelector: (g) => g.id,
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
    );
  }

+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+
+    final params = PageUrlState(
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
+  }
+
  Future<void> _syncFromAuthentik() async {
    if (_isSyncing) return;
    setState(() => _isSyncing = true);
@@ -96,6 +161,7 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
    return DataGridConfig<GroupData>(
      columns: [
        DataGridColumn<GroupData>(
+          id: 'name',
          header: 'Name',
          valueBuilder: (g) => g.name,
          sortable: true,
@@ -103,18 +169,21 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
          width: const DataGridColumnWidth.flex(2),
        ),
        DataGridColumn<GroupData>(
+          id: 'members',
          header: 'Members',
          valueBuilder: (g) => g.memberCount.toString(),
          width: const DataGridColumnWidth.fixed(100),
          alignment: DataGridColumnAlignment.end,
        ),
        DataGridColumn<GroupData>(
+          id: 'type',
          header: 'Type',
          valueBuilder: (g) => g.isSuperuser ? 'Superuser' : 'Standard',
          cellBuilder: (context, g) => _GroupTypeBadge(isSuperuser: g.isSuperuser),
          width: const DataGridColumnWidth.fixed(120),
        ),
        DataGridColumn<GroupData>(
+          id: 'parent',
          header: 'Parent',
          valueBuilder: (g) => g.parentName ?? '-',
          width: const DataGridColumnWidth.flex(1),
@@ -129,6 +198,15 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {

  @override
  Widget build(BuildContext context) {
+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
    return DataGrid<GroupData>(
      provider: _gridProvider,
      config: _buildConfig(),
@@ -11,11 +11,15 @@ class SecurityPage extends ConsumerWidget {
  const SecurityPage({
    super.key,
    this.nav = SecurityNav.users,
+    this.routerState,
  });

  /// The current nav item to display.
  final SecurityNav nav;

+  /// Router state for URL deep-linking (query params).
+  final GoRouterState? routerState;
+
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final colorScheme = Theme.of(context).colorScheme;
@@ -45,7 +49,7 @@ class SecurityPage extends ConsumerWidget {
          ),
          // Section content
          Expanded(
-            child: _SectionContent(nav: nav),
+            child: _SectionContent(nav: nav, routerState: routerState),
          ),
        ],
      ),
@@ -55,17 +59,18 @@ class SecurityPage extends ConsumerWidget {

 /// Renders content for the selected nav item.
 class _SectionContent extends StatelessWidget {
-  const _SectionContent({required this.nav});
+  const _SectionContent({required this.nav, this.routerState});

  final SecurityNav nav;
+  final GoRouterState? routerState;

  @override
  Widget build(BuildContext context) {
    switch (nav) {
      case SecurityNav.users:
-        return const UsersListPage();
+        return UsersListPage(routerState: routerState);
      case SecurityNav.groups:
-        return const GroupsListPage();
+        return GroupsListPage(routerState: routerState);
      default:
        return _PlaceholderSection(nav: nav);
    }
@@ -1,6 +1,8 @@
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/features/security/presentation/pages/security_page.dart';
+import 'package:tatlock_ui/routing/app_router.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
 import 'package:tatlock_ui/shared/layouts/widgets/nav_panel.dart';

 /// Route paths for Security room.
@@ -46,6 +48,22 @@ enum SecurityNav {
 /// Get route path for a nav item.
 String pathForSecurityNav(SecurityNav nav) => nav.path;

+/// Security room definition.
+final securityRoom = RoomDefinition(
+  id: 'security',
+  label: 'Security',
+  icon: Icons.security_outlined,
+  selectedIcon: Icons.security,
+  defaultRoute: SecurityRoutes.users,
+  routes: securityRoutes,
+  // No permissions required - accessible to all authenticated users
+);
+
+/// Register Security room with the room registry.
+void registerSecurity() {
+  roomRegistry.register(securityRoom);
+}
+
 /// Security room routes for go_router.
 List<RouteBase> securityRoutes() {
  return [
@@ -60,7 +78,11 @@ List<RouteBase> securityRoutes() {
      GoRoute(
        path: nav.path,
        name: 'security${_capitalize(nav.id.replaceAll('-', '_'))}',
-        builder: (context, state) => SecurityPage(nav: nav),
+        pageBuilder: (context, state) => noTransitionPage(
+          context,
+          state,
+          SecurityPage(nav: nav, routerState: state),
+        ),
      ),
  ];
 }
@@ -1,6 +1,10 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';

@@ -61,7 +65,10 @@ class UserData {

 /// Users list page using the shared DataGrid component.
 class UsersListPage extends ConsumerStatefulWidget {
-  const UsersListPage({super.key});
+  const UsersListPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;

  @override
  ConsumerState<UsersListPage> createState() => _UsersListPageState();
@@ -70,11 +77,19 @@ class UsersListPage extends ConsumerStatefulWidget {
 class _UsersListPageState extends ConsumerState<UsersListPage> {
  late final StateNotifierProvider<DataGridController<UserData>,
      DataGridState<UserData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;
  bool _isSyncing = false;

  @override
  void initState() {
    super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
    final dio = ref.read(coreApiClientProvider);
    final source = CoreApiDataSource<UserData>(
      dio: dio,
@@ -82,13 +97,63 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
      fromJson: UserData.fromJson,
    );

+    // Initialize grid with URL state
    _gridProvider = dataGridProvider<UserData>(
      source: source,
      config: _buildConfig(),
      idSelector: (u) => u.id,
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
    );
  }

+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+
+    final params = PageUrlState(
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
+  }
+
  Future<void> _syncFromAuthentik() async {
    if (_isSyncing) return;
    setState(() => _isSyncing = true);
@@ -125,6 +190,7 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
    return DataGridConfig<UserData>(
      columns: [
        DataGridColumn<UserData>(
+          id: 'user',
          header: 'User',
          valueBuilder: (u) => u.name,
          sortable: true,
@@ -133,12 +199,14 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
          cellBuilder: (context, u) => _UserCell(user: u),
        ),
        DataGridColumn<UserData>(
+          id: 'roles',
          header: 'Roles',
          valueBuilder: (u) => u.roles.join(', '),
          width: const DataGridColumnWidth.flex(1),
          cellBuilder: (context, u) => _RolesCell(roles: u.roles),
        ),
        DataGridColumn<UserData>(
+          id: 'lastLogin',
          header: 'Last Login',
          valueBuilder: (u) => u.lastLoginFormatted,
          width: const DataGridColumnWidth.fixed(120),
@@ -154,6 +222,15 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {

  @override
  Widget build(BuildContext context) {
+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
    return DataGrid<UserData>(
      provider: _gridProvider,
      config: _buildConfig(),
@@ -0,0 +1,301 @@
+import 'dart:developer' as developer;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:tatlock_ui/core/auth/auth_provider.dart';
+import 'package:tatlock_ui/core/theme/theme_provider.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
+
+/// Settings page with user preferences.
+class SettingsPage extends ConsumerWidget {
+  const SettingsPage({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final authState = ref.watch(authProvider);
+    final currentTheme = ref.watch(themeProvider);
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Scaffold(
+      body: authState.when(
+        data: (auth) => SingleChildScrollView(
+          padding: const EdgeInsets.all(24),
+          child: Center(
+            child: ConstrainedBox(
+              constraints: const BoxConstraints(maxWidth: 600),
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  // Page header
+                  Text(
+                    'Settings',
+                    style: textTheme.headlineMedium,
+                  ),
+                  const SizedBox(height: 32),
+
+                  // Appearance section
+                  _SectionHeader(title: 'Appearance'),
+                  const SizedBox(height: 8),
+                  Card(
+                    child: Padding(
+                      padding: const EdgeInsets.all(16),
+                      child: Row(
+                        children: [
+                          Icon(
+                            _themeIcon(currentTheme),
+                            color: colorScheme.onSurfaceVariant,
+                          ),
+                          const SizedBox(width: 16),
+                          Expanded(
+                            child: Column(
+                              crossAxisAlignment: CrossAxisAlignment.start,
+                              children: [
+                                Text('Theme', style: textTheme.titleMedium),
+                                Text(
+                                  'Choose your preferred color scheme',
+                                  style: textTheme.bodySmall?.copyWith(
+                                    color: colorScheme.onSurfaceVariant,
+                                  ),
+                                ),
+                              ],
+                            ),
+                          ),
+                          DropdownButton<ThemeSetting>(
+                            value: currentTheme,
+                            underline: const SizedBox(),
+                            onChanged: (value) {
+                              if (value != null) {
+                                _updateTheme(ref, value);
+                              }
+                            },
+                            items: const [
+                              DropdownMenuItem(
+                                value: ThemeSetting.system,
+                                child: Text('System'),
+                              ),
+                              DropdownMenuItem(
+                                value: ThemeSetting.light,
+                                child: Text('Light'),
+                              ),
+                              DropdownMenuItem(
+                                value: ThemeSetting.dark,
+                                child: Text('Dark'),
+                              ),
+                            ],
+                          ),
+                        ],
+                      ),
+                    ),
+                  ),
+
+                  const SizedBox(height: 24),
+
+                  // Navigation section
+                  _SectionHeader(title: 'Navigation'),
+                  const SizedBox(height: 8),
+                  Card(
+                    child: Padding(
+                      padding: const EdgeInsets.all(16),
+                      child: Row(
+                        children: [
+                          Icon(
+                            Icons.home_outlined,
+                            color: colorScheme.onSurfaceVariant,
+                          ),
+                          const SizedBox(width: 16),
+                          Expanded(
+                            child: Column(
+                              crossAxisAlignment: CrossAxisAlignment.start,
+                              children: [
+                                Text(
+                                  'Default Room',
+                                  style: textTheme.titleMedium,
+                                ),
+                                Text(
+                                  'Room to show when app opens',
+                                  style: textTheme.bodySmall?.copyWith(
+                                    color: colorScheme.onSurfaceVariant,
+                                  ),
+                                ),
+                              ],
+                            ),
+                          ),
+                          DropdownButton<String>(
+                            value:
+                                auth.preferences?.defaultRoom ?? 'front-hall',
+                            underline: const SizedBox(),
+                            onChanged: (value) {
+                              if (value != null) {
+                                _updateDefaultRoom(ref, value);
+                              }
+                            },
+                            items: roomRegistry.all
+                                .map(
+                                  (room) => DropdownMenuItem(
+                                    value: room.id,
+                                    child: Text(room.label),
+                                  ),
+                                )
+                                .toList(),
+                          ),
+                        ],
+                      ),
+                    ),
+                  ),
+
+                  const SizedBox(height: 24),
+
+                  // Account section
+                  _SectionHeader(title: 'Account'),
+                  const SizedBox(height: 8),
+                  Card(
+                    child: Column(
+                      children: [
+                        _AccountInfoTile(
+                          icon: Icons.person_outline,
+                          label: 'Name',
+                          value: auth.userName ?? 'Not available',
+                        ),
+                        const Divider(height: 1),
+                        _AccountInfoTile(
+                          icon: Icons.email_outlined,
+                          label: 'Email',
+                          value: auth.userEmail ?? 'Not available',
+                        ),
+                        if (auth.roles.isNotEmpty) ...[
+                          const Divider(height: 1),
+                          _AccountInfoTile(
+                            icon: Icons.shield_outlined,
+                            label: 'Roles',
+                            value: auth.roles.map((r) => r.name).join(', '),
+                          ),
+                        ],
+                      ],
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ),
+        ),
+        loading: () => const Center(child: CircularProgressIndicator()),
+        error: (error, _) => Center(
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Icon(Icons.error_outline, size: 48, color: colorScheme.error),
+              const SizedBox(height: 16),
+              Text(
+                'Failed to load settings',
+                style: textTheme.titleMedium,
+              ),
+              const SizedBox(height: 8),
+              Text(
+                error.toString(),
+                style: textTheme.bodySmall?.copyWith(
+                  color: colorScheme.onSurfaceVariant,
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+
+  IconData _themeIcon(ThemeSetting theme) {
+    return switch (theme) {
+      ThemeSetting.system => Icons.brightness_auto,
+      ThemeSetting.light => Icons.light_mode,
+      ThemeSetting.dark => Icons.dark_mode,
+    };
+  }
+
+  Future<void> _updateTheme(WidgetRef ref, ThemeSetting setting) async {
+    // Update local theme immediately for instant UI response
+    await ref.read(themeProvider.notifier).setSetting(setting);
+
+    // Sync to backend
+    try {
+      await ref.read(authProvider.notifier).updatePreferences(
+            theme: setting.name,
+          );
+    } catch (e) {
+      developer.log('Failed to sync theme preference: $e', name: 'settings');
+    }
+  }
+
+  Future<void> _updateDefaultRoom(WidgetRef ref, String room) async {
+    try {
+      await ref.read(authProvider.notifier).updatePreferences(
+            defaultRoom: room,
+          );
+    } catch (e) {
+      developer.log('Failed to sync default room: $e', name: 'settings');
+    }
+  }
+}
+
+/// Section header widget.
+class _SectionHeader extends StatelessWidget {
+  const _SectionHeader({required this.title});
+
+  final String title;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Text(
+      title.toUpperCase(),
+      style: textTheme.labelMedium?.copyWith(
+        color: colorScheme.primary,
+        letterSpacing: 1.0,
+        fontWeight: FontWeight.w600,
+      ),
+    );
+  }
+}
+
+/// Account info tile widget.
+class _AccountInfoTile extends StatelessWidget {
+  const _AccountInfoTile({
+    required this.icon,
+    required this.label,
+    required this.value,
+  });
+
+  final IconData icon;
+  final String label;
+  final String value;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Padding(
+      padding: const EdgeInsets.all(16),
+      child: Row(
+        children: [
+          Icon(icon, color: colorScheme.onSurfaceVariant),
+          const SizedBox(width: 16),
+          Expanded(
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text(label, style: textTheme.bodySmall?.copyWith(
+                  color: colorScheme.onSurfaceVariant,
+                )),
+                const SizedBox(height: 2),
+                Text(value, style: textTheme.titleMedium),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
@@ -1,22 +1,37 @@
 import 'dart:developer' as developer;

+import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';

 import 'app.dart';
+import 'core/auth/auth_controller.dart';
+import 'core/config/url_strategy.dart';
 import 'version.g.dart';

-void main() {
+void main() async {
  WidgetsFlutterBinding.ensureInitialized();

-  developer.log(
-    '${AppVersion.name} v${AppVersion.fullVersion}',
-    name: 'tatlock_ui',
-  );
+  // Enable semantics tree on web for accessibility and automation tools.
+  // This exposes widget identifiers to browser automation (Puppeteer, etc.)
+  if (kIsWeb) {
+    SemanticsBinding.instance.ensureSemantics();
+  }

-  runApp(
-    const ProviderScope(
-      child: TatlockApp(),
-    ),
-  );
+  // Use path-based URLs on web (no-op on mobile/desktop)
+  configureUrlStrategy();
+
+  debugPrint('🪣 ${AppVersion.name} v${AppVersion.fullVersion}');
+
+  // Initialize auth before starting the app.
+  // This handles OIDC callback and silent auth on web.
+  // If it returns false, we're redirecting and shouldn't continue.
+  final authReady = await AuthController.initialize();
+  if (!authReady) {
+    developer.log('Auth redirecting, not starting app', name: 'tatlock_ui');
+    return; // Don't run the app - browser is redirecting
+  }
+
+  runApp(const ProviderScope(child: TatlockApp()));
 }
@@ -1,48 +1,98 @@
 import 'package:flutter/material.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/features/control_room/router.dart';
-import 'package:tatlock_ui/features/front_hall/presentation/pages/front_hall_page.dart';
+import 'package:tatlock_ui/features/front_hall/router.dart';
+import 'package:tatlock_ui/features/media_room/router.dart';
+import 'package:tatlock_ui/features/parlor/router.dart';
 import 'package:tatlock_ui/features/security/router.dart';
+import 'package:tatlock_ui/features/settings/presentation/pages/settings_page.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
 import 'package:tatlock_ui/shared/layouts/app_scaffold.dart';

 part 'app_router.g.dart';

+/// Initialize room registry with all rooms.
+///
+/// Called once before creating the router.
+/// Order of registration determines tab order in UI.
+void _initializeRoomRegistry() {
+  // Skip if already initialized
+  if (roomRegistry.all.isNotEmpty) return;
+
+  // Register rooms in display order
+  registerFrontHall();
+  registerControlRoom();
+  registerSecurity();
+  registerParlor();
+  registerMediaRoom();
+}
+
+/// No-animation page builder for instant transitions
+Page<void> noTransitionPage(BuildContext context, GoRouterState state, Widget child) {
+  return NoTransitionPage<void>(
+    key: state.pageKey,
+    child: child,
+  );
+}
+
 /// Route paths as constants.
 abstract class AppRoutes {
-  static const frontHall = '/';
-  static const parlor = '/parlor';
+  static const root = '/';
  static const settings = '/settings';
 }

+/// Maps defaultRoom preference value to route path.
+String _routeForDefaultRoom(String? defaultRoom) {
+  // Look up room in registry, fall back to first room's default route
+  final room = roomRegistry.byId(defaultRoom ?? '');
+  if (room != null) {
+    return room.defaultRoute;
+  }
+  // Default to first registered room (Front Hall)
+  return roomRegistry.all.isNotEmpty
+      ? roomRegistry.all.first.defaultRoute
+      : FrontHallRoutes.base;
+}
+
 /// Provides the GoRouter instance.
@riverpod
 GoRouter appRouter(Ref ref) {
+  // Initialize room registry on first access
+  _initializeRoomRegistry();
+
+  final authState = ref.watch(authProvider);
+
  return GoRouter(
-    initialLocation: AppRoutes.frontHall,
+    initialLocation: AppRoutes.root,
    debugLogDiagnostics: true,
+    redirect: (context, state) {
+      // Redirect from root to user's default room preference
+      if (state.matchedLocation == AppRoutes.root) {
+        final defaultRoom = authState.value?.preferences?.defaultRoom;
+        return _routeForDefaultRoom(defaultRoom);
+      }
+      return null;
+    },
    routes: [
+      // Root redirects to default room (handled by redirect callback above)
+      GoRoute(
+        path: AppRoutes.root,
+        redirect: (context, state) => _routeForDefaultRoom(null),
+      ),
+      // Main app routes (inside shell with app scaffold)
      ShellRoute(
        builder: (context, state, child) => AppScaffold(child: child),
        routes: [
-          GoRoute(
-            path: AppRoutes.frontHall,
-            name: 'frontHall',
-            builder: (context, state) => const FrontHallPage(),
-          ),
-          ...controlRoomRoutes(),
-          ...securityRoutes(),
-          GoRoute(
-            path: AppRoutes.parlor,
-            name: 'parlor',
-            builder: (context, state) =>
-                const _PlaceholderPage(title: 'Parlor'),
-          ),
+          // All room routes from registry
+          ...roomRegistry.allRoutes(),
+          // Settings page (not a room, just a page)
          GoRoute(
            path: AppRoutes.settings,
            name: 'settings',
-            builder: (context, state) =>
-                const _PlaceholderPage(title: 'Settings'),
+            pageBuilder: (context, state) =>
+                noTransitionPage(context, state, const SettingsPage()),
          ),
        ],
      ),
@@ -50,37 +100,4 @@ GoRouter appRouter(Ref ref) {
  );
 }

-/// Placeholder page for routes not yet implemented.
-class _PlaceholderPage extends StatelessWidget {
-  const _PlaceholderPage({required this.title});

-  final String title;
-
-  @override
-  Widget build(BuildContext context) {
-    return Center(
-      child: Column(
-        mainAxisAlignment: MainAxisAlignment.center,
-        children: [
-          Icon(
-            Icons.construction,
-            size: 64,
-            color: Theme.of(context).colorScheme.outline,
-          ),
-          const SizedBox(height: 16),
-          Text(
-            title,
-            style: Theme.of(context).textTheme.headlineMedium,
-          ),
-          const SizedBox(height: 8),
-          Text(
-            'Coming soon',
-            style: Theme.of(context).textTheme.bodyLarge?.copyWith(
-                  color: Theme.of(context).colorScheme.outline,
-                ),
-          ),
-        ],
-      ),
-    );
-  }
-}
@@ -0,0 +1,113 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+/// Defines a room in the application.
+///
+/// Each feature/room registers itself with metadata for navigation,
+/// routing, and permission-based access control.
+class RoomDefinition {
+  const RoomDefinition({
+    required this.id,
+    required this.label,
+    required this.icon,
+    required this.selectedIcon,
+    required this.defaultRoute,
+    required this.routes,
+    this.requiredPermissions = const [],
+  });
+
+  /// Unique identifier used in preferences (e.g., 'front-hall', 'control-room').
+  final String id;
+
+  /// Display label for UI.
+  final String label;
+
+  /// Icon when not selected.
+  final IconData icon;
+
+  /// Icon when selected.
+  final IconData selectedIcon;
+
+  /// Default route path when room is selected.
+  final String defaultRoute;
+
+  /// All routes this room provides to go_router.
+  final List<RouteBase> Function() routes;
+
+  /// Permissions required to access this room (empty = accessible to all).
+  /// User must have ALL listed permissions.
+  final List<String> requiredPermissions;
+}
+
+/// Central registry of all rooms in the application.
+///
+/// Each room's router.dart file registers itself here.
+/// UI components query this registry to build navigation.
+class RoomRegistry {
+  RoomRegistry._();
+
+  static final RoomRegistry instance = RoomRegistry._();
+
+  final List<RoomDefinition> _rooms = [];
+
+  /// Register a room. Called by each room's router.dart.
+  void register(RoomDefinition room) {
+    // Avoid duplicate registration
+    if (!_rooms.any((r) => r.id == room.id)) {
+      _rooms.add(room);
+    }
+  }
+
+  /// Get all registered rooms.
+  List<RoomDefinition> get all => List.unmodifiable(_rooms);
+
+  /// Get rooms filtered by user permissions.
+  ///
+  /// [userPermissions] is the set of permissions the user has.
+  /// Returns rooms where the user has ALL required permissions.
+  List<RoomDefinition> accessibleTo(Set<String> userPermissions) {
+    return _rooms.where((room) {
+      if (room.requiredPermissions.isEmpty) return true;
+      return room.requiredPermissions.every(userPermissions.contains);
+    }).toList();
+  }
+
+  /// Get a room by its ID.
+  RoomDefinition? byId(String id) {
+    try {
+      return _rooms.firstWhere((r) => r.id == id);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /// Get the index of a room by its ID.
+  int indexOfId(String id) {
+    return _rooms.indexWhere((r) => r.id == id);
+  }
+
+  /// Get the index of a room by route path.
+  int indexOfRoute(String path) {
+    // Find room whose defaultRoute matches or whose routes start with path
+    for (var i = 0; i < _rooms.length; i++) {
+      final room = _rooms[i];
+      if (path == room.defaultRoute || path.startsWith('/${room.id}')) {
+        return i;
+      }
+    }
+    return 0; // Default to first room
+  }
+
+  /// Get all routes from all registered rooms.
+  List<RouteBase> allRoutes() {
+    return _rooms.expand((room) => room.routes()).toList();
+  }
+
+  /// Clear registry (useful for testing).
+  void clear() {
+    _rooms.clear();
+  }
+}
+
+/// Global registry instance.
+final roomRegistry = RoomRegistry.instance;
@@ -0,0 +1,98 @@
+import 'package:flutter/foundation.dart' show kIsWeb;
+
+// Conditional import for web-only functionality
+import 'url_state_stub.dart' if (dart.library.js_interop) 'url_state_web.dart'
+    as platform;
+
+/// Parses and builds URL query parameters for page state.
+///
+/// Used to enable deep-linking for DataGrid and filter panel state.
+/// Query params are read once on page load and updated via browser
+/// replaceState to avoid GoRouter rebuild loops.
+class PageUrlState {
+  const PageUrlState({
+    this.id,
+    this.filter,
+    this.search,
+    this.sortColumn,
+    this.sortDescending = false,
+  });
+
+  /// Opened document ID (view/edit mode).
+  final String? id;
+
+  /// Filter panel search value.
+  final String? filter;
+
+  /// DataGrid search value.
+  final String? search;
+
+  /// Column ID for sorting.
+  final String? sortColumn;
+
+  /// Sort direction (true = descending).
+  final bool sortDescending;
+
+  /// Parse from query parameters map.
+  factory PageUrlState.fromQueryParams(Map<String, String> params) {
+    return PageUrlState(
+      id: params['id'],
+      filter: params['filter'],
+      search: params['search'],
+      sortColumn: params['sort'],
+      sortDescending: params['order'] == 'desc',
+    );
+  }
+
+  /// Convert to query parameter map (omits empty/default values).
+  Map<String, String> toQueryParams() {
+    return {
+      if (id != null && id!.isNotEmpty) 'id': id!,
+      if (filter != null && filter!.isNotEmpty) 'filter': filter!,
+      if (search != null && search!.isNotEmpty) 'search': search!,
+      if (sortColumn != null && sortColumn!.isNotEmpty) 'sort': sortColumn!,
+      if (sortDescending) 'order': 'desc',
+    };
+  }
+
+  /// Create a copy with modified values.
+  PageUrlState copyWith({
+    String? id,
+    String? filter,
+    String? search,
+    String? sortColumn,
+    bool? sortDescending,
+    bool clearId = false,
+  }) {
+    return PageUrlState(
+      id: clearId ? null : (id ?? this.id),
+      filter: filter ?? this.filter,
+      search: search ?? this.search,
+      sortColumn: sortColumn ?? this.sortColumn,
+      sortDescending: sortDescending ?? this.sortDescending,
+    );
+  }
+
+  /// Whether any state is present.
+  bool get isEmpty =>
+      id == null &&
+      (filter == null || filter!.isEmpty) &&
+      (search == null || search!.isEmpty) &&
+      sortColumn == null;
+
+  @override
+  String toString() =>
+      'PageUrlState(id: $id, filter: $filter, search: $search, '
+      'sort: $sortColumn, desc: $sortDescending)';
+}
+
+/// Updates browser URL with query parameters without triggering navigation.
+///
+/// Uses browser's replaceState API on web, no-op on other platforms.
+/// This allows the URL to stay in sync for bookmarking/sharing without
+/// causing Flutter to rebuild.
+void updateBrowserUrlParams(Map<String, String> params) {
+  if (kIsWeb) {
+    platform.updateBrowserUrlParams(params);
+  }
+}
@@ -0,0 +1,4 @@
+/// Stub implementation for non-web platforms.
+void updateBrowserUrlParams(Map<String, String> params) {
+  // No-op on non-web platforms
+}
@@ -0,0 +1,13 @@
+import 'package:web/web.dart' as web;
+
+/// Updates browser URL with query parameters without triggering navigation.
+///
+/// Uses browser's replaceState API to update the URL bar for bookmarking
+/// without causing Flutter/GoRouter to rebuild the page.
+void updateBrowserUrlParams(Map<String, String> params) {
+  final currentUri = Uri.parse(web.window.location.href);
+  final newUri = currentUri.replace(
+    queryParameters: params.isEmpty ? null : params,
+  );
+  web.window.history.replaceState(null, '', newUri.toString());
+}
@@ -103,9 +103,19 @@ class DataGrid<T> extends ConsumerWidget {
    DataGridState<T> state,
    DataGridController<T> controller,
  ) {
-    return Padding(
-      padding: const EdgeInsets.all(16),
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Container(
+      height: 56,
+      padding: const EdgeInsets.symmetric(horizontal: 16),
+      decoration: BoxDecoration(
+        color: colorScheme.surfaceContainerHighest,
+        border: Border(
+          bottom: BorderSide(color: colorScheme.outlineVariant),
+        ),
+      ),
      child: Row(
+        crossAxisAlignment: CrossAxisAlignment.center,
        children: [
          if (config.enableSearch)
            DataGridSearchBar(
@@ -45,6 +45,7 @@ enum DataGridColumnAlignment {
 /// Column definition for DataGrid.
 class DataGridColumn<T> {
  const DataGridColumn({
+    required this.id,
    required this.header,
    required this.valueBuilder,
    this.cellBuilder,
@@ -58,6 +59,9 @@ class DataGridColumn<T> {
    this.tooltip,
  });

+  /// Unique identifier for this column (used in URL deep-linking).
+  final String id;
+
  /// Column header text.
  final String header;

@@ -15,9 +15,15 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
    required this.source,
    required this.config,
    required this.idSelector,
+    String? initialSearch,
+    int? initialSortColumnIndex,
+    bool? initialSortDescending,
  }) : super(DataGridState<T>(
-          sortColumnIndex: config.defaultSortColumn,
-          sortDescending: config.defaultSortDescending,
+          searchQuery: initialSearch ?? '',
+          sortColumnIndex:
+              initialSortColumnIndex ?? config.defaultSortColumn,
+          sortDescending:
+              initialSortDescending ?? config.defaultSortDescending,
        )) {
    // Initial load
    _load();
@@ -29,12 +35,20 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
  /// Grid configuration.
  final DataGridConfig<T> config;

-  /// Function to extract unique ID from an item.
-  final Object Function(T item) idSelector;
+  /// Function to extract unique ID from an item (used for selection and URL deep-linking).
+  ///
+  /// Returns a unique string identifier for each row. Can be:
+  /// - A simple ID field: `(item) => item.id.toString()`
+  /// - A combination of fields: `(item) => '${item.name}_${item.type}'`
+  /// - Any unique identifier suitable for URLs
+  final String Function(T item) idSelector;

  /// Debounce timer for search.
  Timer? _searchDebounce;

+  /// All items before local filtering (for local search).
+  List<T> _allItems = [];
+
  @override
  void dispose() {
    _searchDebounce?.cancel();
@@ -57,16 +71,21 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
      final (offset, limit) = _getPaginationParams();

      final result = await source.fetch(
-        searchQuery: state.searchQuery.isEmpty ? null : state.searchQuery,
        sortField: sortField,
        sortDescending: state.sortDescending,
        offset: offset,
        limit: limit,
      );

+      // Store all items for local filtering
+      _allItems = result.items;
+
+      // Apply local filter if search query exists
+      final filteredItems = _applyLocalFilter(_allItems);
+
      state = state.copyWith(
-        items: result.items,
-        totalCount: result.totalCount,
+        items: filteredItems,
+        totalCount: filteredItems.length,
        hasMore: result.hasMore,
        isLoading: false,
        isInitialLoad: false,
@@ -82,6 +101,26 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
    }
  }

+  /// Applies local filtering based on search query.
+  List<T> _applyLocalFilter(List<T> items) {
+    if (state.searchQuery.isEmpty) return items;
+
+    final query = state.searchQuery.toLowerCase();
+
+    return items.where((item) {
+      // Check all searchable columns
+      for (final column in config.columns) {
+        if (column.searchable) {
+          final value = column.valueBuilder(item);
+          if (value.toLowerCase().contains(query)) {
+            return true;
+          }
+        }
+      }
+      return false;
+    }).toList();
+  }
+
  /// Gets pagination parameters based on data mode.
  (int?, int?) _getPaginationParams() {
    return switch (config.dataMode) {
@@ -97,13 +136,13 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
  /// Refreshes the grid data.
  Future<void> refresh() => _load(refresh: true);

-  /// Sets the search query with debouncing.
+  /// Sets the search query with debouncing (filters locally).
  void search(String query) {
    _searchDebounce?.cancel();
-    _searchDebounce = Timer(const Duration(milliseconds: 300), () {
+    _searchDebounce = Timer(const Duration(milliseconds: 150), () {
      if (state.searchQuery != query) {
        state = state.copyWith(searchQuery: query, currentPage: 0);
-        _load(refresh: true);
+        _applyFilterAndUpdateState();
      }
    });
  }
@@ -113,10 +152,19 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
    _searchDebounce?.cancel();
    if (state.searchQuery.isNotEmpty) {
      state = state.copyWith(searchQuery: '', currentPage: 0);
-      _load(refresh: true);
+      _applyFilterAndUpdateState();
    }
  }

+  /// Applies local filter and updates state with filtered items.
+  void _applyFilterAndUpdateState() {
+    final filteredItems = _applyLocalFilter(_allItems);
+    state = state.copyWith(
+      items: filteredItems,
+      totalCount: filteredItems.length,
+    );
+  }
+
  /// Sorts by the given column index.
  void sortBy(int columnIndex) {
    final column = config.columns[columnIndex];
@@ -148,7 +196,7 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
    if (!config.rowsSelectable) return;

    final id = idSelector(item);
-    final newSelection = Set<Object>.from(state.selectedIds);
+    final newSelection = Set<String>.from(state.selectedIds);

    if (newSelection.contains(id)) {
      newSelection.remove(id);
@@ -250,17 +298,35 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
 ///   idSelector: (c) => c.id,
 /// );
 /// ```
+///
+/// For URL deep-linking, pass initial state from URL params:
+/// ```dart
+/// final gridProvider = dataGridProvider<Container>(
+///   source: source,
+///   config: config,
+///   idSelector: (c) => c.id,
+///   initialSearch: urlState.search,
+///   initialSortColumnIndex: _columnIndexForId(urlState.sortColumn),
+///   initialSortDescending: urlState.sortDescending,
+/// );
+/// ```
 StateNotifierProvider<DataGridController<T>, DataGridState<T>>
    dataGridProvider<T>({
  required DataGridSource<T> source,
  required DataGridConfig<T> config,
-  required Object Function(T) idSelector,
+  required String Function(T) idSelector,
+  String? initialSearch,
+  int? initialSortColumnIndex,
+  bool? initialSortDescending,
 }) {
  return StateNotifierProvider<DataGridController<T>, DataGridState<T>>(
    (ref) => DataGridController<T>(
      source: source,
      config: config,
      idSelector: idSelector,
+      initialSearch: initialSearch,
+      initialSortColumnIndex: initialSortColumnIndex,
+      initialSortDescending: initialSortDescending,
    ),
  );
 }
@@ -31,7 +31,7 @@ sealed class DataGridState<T> with _$DataGridState<T> {
    @Default(false) bool sortDescending,

    /// Currently selected item IDs (if selectable).
-    @Default({}) Set<Object> selectedIds,
+    @Default({}) Set<String> selectedIds,

    /// Current page (for paginated mode).
    @Default(0) int currentPage,
@@ -40,14 +40,16 @@ class _DataGridSearchBarState extends State<DataGridSearchBar> {

    return SizedBox(
      width: 300,
+      height: 36,
      child: TextField(
        controller: _controller,
+        style: const TextStyle(fontSize: 14),
        decoration: InputDecoration(
          hintText: widget.hintText,
-          prefixIcon: const Icon(Icons.search),
+          prefixIcon: const Icon(Icons.search, size: 20),
          suffixIcon: _controller.text.isNotEmpty
              ? IconButton(
-                  icon: const Icon(Icons.clear),
+                  icon: const Icon(Icons.clear, size: 18),
                  onPressed: () {
                    _controller.clear();
                    widget.onClear();
@@ -56,14 +58,22 @@ class _DataGridSearchBarState extends State<DataGridSearchBar> {
              : null,
          isDense: true,
          filled: true,
-          fillColor: colorScheme.surfaceContainerHighest,
+          fillColor: colorScheme.surface,
          border: OutlineInputBorder(
            borderRadius: BorderRadius.circular(8),
-            borderSide: BorderSide.none,
+            borderSide: BorderSide(color: colorScheme.outlineVariant),
+          ),
+          enabledBorder: OutlineInputBorder(
+            borderRadius: BorderRadius.circular(8),
+            borderSide: BorderSide(color: colorScheme.outlineVariant),
+          ),
+          focusedBorder: OutlineInputBorder(
+            borderRadius: BorderRadius.circular(8),
+            borderSide: BorderSide(color: colorScheme.primary),
          ),
          contentPadding: const EdgeInsets.symmetric(
-            horizontal: 16,
-            vertical: 12,
+            horizontal: 12,
+            vertical: 8,
          ),
        ),
        onChanged: (value) {
@@ -1,12 +1,19 @@
+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:tatlock_ui/features/control_room/router.dart';
-import 'package:tatlock_ui/features/security/router.dart';
-import 'package:tatlock_ui/routing/app_router.dart';
+import 'package:tatlock_ui/core/auth/auth_provider.dart';
+import 'package:tatlock_ui/core/config/app_config.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';
 import 'package:tatlock_ui/shared/layouts/widgets/top_header_bar.dart';

 /// Main application scaffold with top header navigation.
 ///
+/// Handles authentication automatically:
+/// - If not authenticated, auto-initiates OIDC flow
+/// - Shows loading state during authentication
+/// - Shows error state if auth fails (with retry)
+///
 /// Layout structure per UI_LAYOUT.md:
 /// ```
 /// ┌─────────────────────────────────────────────────────────────────┐
@@ -15,16 +22,62 @@ import 'package:tatlock_ui/shared/layouts/widgets/top_header_bar.dart';
 /// │  BODY: Room page content (may include room-specific sidebar)    │
 /// └─────────────────────────────────────────────────────────────────┘
 /// ```
-class AppScaffold extends StatelessWidget {
+class AppScaffold extends ConsumerStatefulWidget {
  const AppScaffold({super.key, required this.child});

  final Widget child;

+  @override
+  ConsumerState<AppScaffold> createState() => _AppScaffoldState();
+}
+
+class _AppScaffoldState extends ConsumerState<AppScaffold> {
  // Header height must match TopHeaderBar._headerHeight
  static const double _headerHeight = 56.0;

+  bool _authInitiated = false;
+
  @override
  Widget build(BuildContext context) {
+    // No auth required in LAN mode - show content directly
+    if (!AppConfig.requiresAuth) {
+      return _buildScaffold(context);
+    }
+
+    // Watch auth state (works for both web and mobile)
+    final authAsync = ref.watch(authProvider);
+
+    return authAsync.when(
+      data: (authState) {
+        if (authState.isAuthenticated) {
+          // Authenticated - show the app
+          _authInitiated = false; // Reset for next time
+          return _buildScaffold(context);
+        }
+
+        // On web, NPM handles auth - if we're here without auth, something is wrong
+        // (NPM should have redirected to Authentik before we loaded)
+        if (kIsWeb) {
+          return _buildAuthErrorScreen(context, 'Authentication required');
+        }
+
+        // Mobile: Not authenticated - auto-initiate OIDC
+        if (!_authInitiated) {
+          _authInitiated = true;
+          WidgetsBinding.instance.addPostFrameCallback((_) {
+            ref.read(authProvider.notifier).signIn();
+          });
+        }
+
+        // Show loading while redirecting to Authentik
+        return _buildAuthLoadingScreen(context, 'Redirecting to sign in...');
+      },
+      loading: () => _buildAuthLoadingScreen(context, 'Loading user info...'),
+      error: (error, _) => _buildAuthErrorScreen(context, error),
+    );
+  }
+
+  Widget _buildScaffold(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
@@ -32,7 +85,7 @@ class AppScaffold extends StatelessWidget {
          Positioned.fill(
            child: Padding(
              padding: const EdgeInsets.only(top: _headerHeight),
-              child: child,
+              child: widget.child,
            ),
          ),

@@ -51,24 +104,124 @@ class AppScaffold extends StatelessWidget {
    );
  }

+  Widget _buildAuthLoadingScreen(BuildContext context, String message) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Scaffold(
+      body: Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          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: 32),
+            const SizedBox(
+              width: 24,
+              height: 24,
+              child: CircularProgressIndicator(strokeWidth: 2),
+            ),
+            const SizedBox(height: 16),
+            Text(
+              message,
+              style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                    color: colorScheme.onSurfaceVariant,
+                  ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildAuthErrorScreen(BuildContext context, Object error) {
+    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.error_outline,
+                    size: 64,
+                    color: colorScheme.error,
+                  ),
+                  const SizedBox(height: 24),
+                  Text(
+                    'Authentication Failed',
+                    style: Theme.of(context).textTheme.headlineMedium?.copyWith(
+                          fontWeight: FontWeight.w600,
+                        ),
+                  ),
+                  const SizedBox(height: 16),
+                  Container(
+                    padding: const EdgeInsets.all(12),
+                    decoration: BoxDecoration(
+                      color: colorScheme.errorContainer,
+                      borderRadius: BorderRadius.circular(8),
+                    ),
+                    child: Text(
+                      _formatError(error),
+                      style: TextStyle(color: colorScheme.onErrorContainer),
+                      textAlign: TextAlign.center,
+                    ),
+                  ),
+                  const SizedBox(height: 24),
+                  FilledButton.icon(
+                    onPressed: () {
+                      _authInitiated = false;
+                      ref.read(authProvider.notifier).signIn();
+                    },
+                    icon: const Icon(Icons.refresh),
+                    label: const Text('Try again'),
+                    style: FilledButton.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.';
+    }
+    return 'Authentication failed. Please try again.';
+  }
+
  int _selectedIndex(BuildContext context) {
    final location = GoRouterState.of(context).matchedLocation;
-
-    if (location.startsWith(ControlRoomRoutes.base)) return 1;
-    if (location.startsWith(SecurityRoutes.base)) return 2;
-    if (location.startsWith(AppRoutes.parlor)) return 3;
-    // Settings is no longer in main nav (accessed via Profile dropdown)
-    return 0; // Front Hall
+    return roomRegistry.indexOfRoute(location);
  }

  void _onNavSelected(BuildContext context, int index) {
-    final route = switch (index) {
-      0 => AppRoutes.frontHall,
-      1 => ControlRoomRoutes.containers,
-      2 => SecurityRoutes.users,
-      3 => AppRoutes.parlor,
-      _ => AppRoutes.frontHall,
-    };
-    context.go(route);
+    final rooms = roomRegistry.all;
+    if (index >= 0 && index < rooms.length) {
+      context.go(rooms[index].defaultRoute);
+    }
  }
 }
@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';

 import 'panel_header.dart';

@@ -199,17 +200,22 @@ class _NavTile extends StatelessWidget {
    final colorScheme = Theme.of(context).colorScheme;
    final textTheme = Theme.of(context).textTheme;

-    return Padding(
-      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
-      child: Material(
-        color: isSelected
-            ? colorScheme.primaryContainer.withValues(alpha: 0.4)
-            : Colors.transparent,
-        borderRadius: BorderRadius.circular(8),
-        child: InkWell(
-          onTap: onTap,
+    return Semantics(
+      identifier: NavSemantics.item(item.id),
+      label: item.label,
+      button: true,
+      selected: isSelected,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+        child: Material(
+          color: isSelected
+              ? colorScheme.primaryContainer.withValues(alpha: 0.4)
+              : Colors.transparent,
          borderRadius: BorderRadius.circular(8),
-          child: Padding(
+          child: InkWell(
+            onTap: onTap,
+            borderRadius: BorderRadius.circular(8),
+            child: Padding(
            padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
            child: Row(
              children: [
@@ -258,6 +264,7 @@ class _NavTile extends StatelessWidget {
          ),
        ),
      ),
+      ),
    );
  }
 }
@@ -1,7 +1,11 @@
+import 'dart:developer' as developer;
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/auth/auth_provider.dart';
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+import 'package:tatlock_ui/core/theme/theme_provider.dart';
 import 'package:tatlock_ui/routing/app_router.dart';

 /// Profile dropdown menu in the header.
@@ -13,90 +17,213 @@ class ProfileDropdown extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final authState = ref.watch(authProvider);
+    final currentTheme = ref.watch(themeProvider);
    final colorScheme = Theme.of(context).colorScheme;

    return authState.when(
-      data: (auth) => PopupMenuButton<String>(
-        offset: const Offset(0, 48),
-        shape: RoundedRectangleBorder(
-          borderRadius: BorderRadius.circular(8),
-        ),
-        child: Tooltip(
-          message: auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
-          child: CircleAvatar(
-            radius: 18,
-            backgroundColor: colorScheme.primaryContainer,
-            child: auth.isAuthenticated
-                ? Text(
-                    _getInitials(auth.userName),
-                    style: TextStyle(
+      data: (auth) => Semantics(
+        identifier: ProfileSemantics.button,
+        label: 'Profile menu',
+        button: true,
+        child: PopupMenuButton<String>(
+          offset: const Offset(0, 48),
+          shape: RoundedRectangleBorder(
+            borderRadius: BorderRadius.circular(8),
+          ),
+          child: Tooltip(
+            message: auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
+            child: CircleAvatar(
+              radius: 18,
+              backgroundColor: colorScheme.primaryContainer,
+              child: auth.isAuthenticated
+                  ? Text(
+                      _getInitials(auth.userName),
+                      style: TextStyle(
+                        color: colorScheme.onPrimaryContainer,
+                        fontWeight: FontWeight.w500,
+                      ),
+                    )
+                  : Icon(
+                      Icons.person_outline,
+                      size: 20,
                      color: colorScheme.onPrimaryContainer,
-                      fontWeight: FontWeight.w500,
                    ),
-                  )
-                : Icon(
-                    Icons.person_outline,
-                    size: 20,
-                    color: colorScheme.onPrimaryContainer,
-                  ),
-          ),
-        ),
-        itemBuilder: (context) => [
-          // User info header (non-selectable)
-          PopupMenuItem<String>(
-            enabled: false,
-            child: Column(
-              crossAxisAlignment: CrossAxisAlignment.start,
-              children: [
-                Text(
-                  auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
-                  style: Theme.of(context).textTheme.titleSmall,
-                ),
-                if (auth.userEmail != null)
-                  Text(
-                    auth.userEmail!,
-                    style: Theme.of(context).textTheme.bodySmall?.copyWith(
-                          color: colorScheme.onSurfaceVariant,
-                        ),
-                  ),
-              ],
            ),
          ),
-          const PopupMenuDivider(),
-
-          // Settings
-          const PopupMenuItem<String>(
-            value: 'settings',
-            child: Row(
-              children: [
-                Icon(Icons.settings_outlined, size: 20),
-                SizedBox(width: 12),
-                Text('Settings'),
-              ],
-            ),
-          ),
-
-          // Logout (only if authenticated)
-          if (auth.isAuthenticated)
-            const PopupMenuItem<String>(
-              value: 'logout',
-              child: Row(
+          itemBuilder: (context) => [
+            // User info header (non-selectable)
+            PopupMenuItem<String>(
+              enabled: false,
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
-                  Icon(Icons.logout, size: 20),
-                  SizedBox(width: 12),
-                  Text('Logout'),
+                  Text(
+                    auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
+                    style: Theme.of(context).textTheme.titleSmall,
+                  ),
+                  if (auth.userEmail != null)
+                    Text(
+                      auth.userEmail!,
+                      style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                            color: colorScheme.onSurfaceVariant,
+                          ),
+                    ),
                ],
              ),
            ),
-        ],
-        onSelected: (value) {
-          switch (value) {
-            case 'settings':
-              context.go(AppRoutes.settings);
-            case 'logout':
-              ref.read(authProvider.notifier).signOut();
-          }
-        },
+            const PopupMenuDivider(),
+
+            // Settings
+            PopupMenuItem<String>(
+              value: 'settings',
+              child: Semantics(
+                identifier: ProfileSemantics.settings,
+                child: const Row(
+                  children: [
+                    Icon(Icons.settings_outlined, size: 20),
+                    SizedBox(width: 12),
+                    Text('Settings'),
+                  ],
+                ),
+              ),
+            ),
+
+            // Theme submenu header
+            PopupMenuItem<String>(
+              enabled: false,
+              height: 32,
+              child: Text(
+                'THEME',
+                style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                      color: colorScheme.onSurfaceVariant,
+                      letterSpacing: 0.5,
+                    ),
+              ),
+            ),
+
+            // Theme: System
+            PopupMenuItem<String>(
+              value: 'theme_system',
+              height: 40,
+              child: Semantics(
+                identifier: ProfileSemantics.themeSystem,
+                child: Row(
+                  children: [
+                    Icon(
+                      Icons.brightness_auto,
+                      size: 18,
+                      color: currentTheme == ThemeSetting.system
+                          ? colorScheme.primary
+                          : null,
+                    ),
+                    const SizedBox(width: 12),
+                    Text(
+                      'System',
+                      style: currentTheme == ThemeSetting.system
+                          ? TextStyle(color: colorScheme.primary)
+                          : null,
+                    ),
+                    const Spacer(),
+                    if (currentTheme == ThemeSetting.system)
+                      Icon(Icons.check, size: 16, color: colorScheme.primary),
+                  ],
+                ),
+              ),
+            ),
+
+            // Theme: Light
+            PopupMenuItem<String>(
+              value: 'theme_light',
+              height: 40,
+              child: Semantics(
+                identifier: ProfileSemantics.themeLight,
+                child: Row(
+                  children: [
+                    Icon(
+                      Icons.light_mode,
+                      size: 18,
+                      color: currentTheme == ThemeSetting.light
+                          ? colorScheme.primary
+                          : null,
+                    ),
+                    const SizedBox(width: 12),
+                    Text(
+                      'Light',
+                      style: currentTheme == ThemeSetting.light
+                          ? TextStyle(color: colorScheme.primary)
+                          : null,
+                    ),
+                    const Spacer(),
+                    if (currentTheme == ThemeSetting.light)
+                      Icon(Icons.check, size: 16, color: colorScheme.primary),
+                  ],
+                ),
+              ),
+            ),
+
+            // Theme: Dark
+            PopupMenuItem<String>(
+              value: 'theme_dark',
+              height: 40,
+              child: Semantics(
+                identifier: ProfileSemantics.themeDark,
+                child: Row(
+                  children: [
+                    Icon(
+                      Icons.dark_mode,
+                      size: 18,
+                      color: currentTheme == ThemeSetting.dark
+                          ? colorScheme.primary
+                          : null,
+                    ),
+                    const SizedBox(width: 12),
+                    Text(
+                      'Dark',
+                      style: currentTheme == ThemeSetting.dark
+                          ? TextStyle(color: colorScheme.primary)
+                          : null,
+                    ),
+                    const Spacer(),
+                    if (currentTheme == ThemeSetting.dark)
+                      Icon(Icons.check, size: 16, color: colorScheme.primary),
+                  ],
+                ),
+              ),
+            ),
+
+            const PopupMenuDivider(),
+
+            // Logout (only if authenticated)
+            if (auth.isAuthenticated)
+              PopupMenuItem<String>(
+                value: 'logout',
+                child: Semantics(
+                  identifier: ProfileSemantics.logout,
+                  child: const Row(
+                    children: [
+                      Icon(Icons.logout, size: 20),
+                      SizedBox(width: 12),
+                      Text('Logout'),
+                    ],
+                  ),
+                ),
+              ),
+          ],
+          onSelected: (value) {
+            switch (value) {
+              case 'settings':
+                context.go(AppRoutes.settings);
+              case 'theme_system':
+                _updateTheme(ref, ThemeSetting.system);
+              case 'theme_light':
+                _updateTheme(ref, ThemeSetting.light);
+              case 'theme_dark':
+                _updateTheme(ref, ThemeSetting.dark);
+              case 'logout':
+                ref.read(authProvider.notifier).signOut();
+            }
+          },
+        ),
      ),
      loading: () => const CircleAvatar(
        radius: 18,
@@ -126,4 +253,20 @@ class ProfileDropdown extends ConsumerWidget {
    }
    return name[0].toUpperCase();
  }
+
+  /// Update theme locally and sync to API.
+  Future<void> _updateTheme(WidgetRef ref, ThemeSetting setting) async {
+    // Update local theme immediately for instant UI response
+    await ref.read(themeProvider.notifier).setSetting(setting);
+
+    // Sync to backend (fire-and-forget, errors logged not shown)
+    try {
+      await ref.read(authProvider.notifier).updatePreferences(
+            theme: setting.name,
+          );
+    } catch (e) {
+      // Theme still works locally even if API sync fails
+      developer.log('Failed to sync theme preference: $e', name: 'profile');
+    }
+  }
 }
@@ -1,6 +1,8 @@
 import 'dart:math';

 import 'package:flutter/material.dart';
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+import 'package:tatlock_ui/routing/room_registry.dart';

 import 'profile_dropdown.dart';

@@ -23,28 +25,8 @@ class TopHeaderBar extends StatelessWidget {
  static const double _logoCircleRadius = (_logoSize + _logoMargin * 2) / 2; // 64px
  static const double _bulgeFraction = 0.20; // 20% of circle below header line

-  static const _rooms = [
-    _RoomDestination(
-      icon: Icons.door_front_door_outlined,
-      selectedIcon: Icons.door_front_door,
-      label: 'Front Hall',
-    ),
-    _RoomDestination(
-      icon: Icons.dns_outlined,
-      selectedIcon: Icons.dns,
-      label: 'Control Room',
-    ),
-    _RoomDestination(
-      icon: Icons.security_outlined,
-      selectedIcon: Icons.security,
-      label: 'Security',
-    ),
-    _RoomDestination(
-      icon: Icons.lightbulb_outline,
-      selectedIcon: Icons.lightbulb,
-      label: 'Parlor',
-    ),
-  ];
+  /// Get rooms from the registry.
+  List<RoomDefinition> get _rooms => roomRegistry.all;

  @override
  Widget build(BuildContext context) {
@@ -120,24 +102,31 @@ class TopHeaderBar extends StatelessWidget {

  List<Widget> _buildRoomTabs(BuildContext context) {
    final colorScheme = Theme.of(context).colorScheme;
+    final rooms = _rooms;

-    return List.generate(_rooms.length, (index) {
-      final room = _rooms[index];
+    return List.generate(rooms.length, (index) {
+      final room = rooms[index];
      final isSelected = index == selectedIndex;

      return Padding(
        padding: const EdgeInsets.symmetric(horizontal: 4),
-        child: Tooltip(
-          message: room.label,
-          child: IconButton(
-            icon: Icon(
-              isSelected ? room.selectedIcon : room.icon,
-              color: isSelected ? colorScheme.primary : colorScheme.onSurface,
-            ),
-            onPressed: () => onRoomSelected(index),
-            style: IconButton.styleFrom(
-              backgroundColor:
-                  isSelected ? colorScheme.primaryContainer : null,
+        child: Semantics(
+          identifier: RoomTabSemantics.forIndex(index),
+          label: room.label,
+          button: true,
+          selected: isSelected,
+          child: Tooltip(
+            message: room.label,
+            child: IconButton(
+              icon: Icon(
+                isSelected ? room.selectedIcon : room.icon,
+                color: isSelected ? colorScheme.primary : colorScheme.onSurface,
+              ),
+              onPressed: () => onRoomSelected(index),
+              style: IconButton.styleFrom(
+                backgroundColor:
+                    isSelected ? colorScheme.primaryContainer : null,
+              ),
            ),
          ),
        ),
@@ -250,14 +239,3 @@ class _HeaderPainter extends CustomPainter {
  }
 }

-class _RoomDestination {
-  const _RoomDestination({
-    required this.icon,
-    required this.selectedIcon,
-    required this.label,
-  });
-
-  final IconData icon;
-  final IconData selectedIcon;
-  final String label;
-}
@@ -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);
+}
@@ -0,0 +1,450 @@
+import 'package:flutter/material.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/environment_model.dart'
+    as api;
+import 'package:tatlock_ui/shared/theme/stoplight_colors.dart';
+
+/// Air Quality Index widget displaying current AQI.
+///
+/// Displays air quality data from the Core API environment endpoint.
+/// Only render this widget when air quality data is available.
+class AirQualityWidget extends StatelessWidget {
+  const AirQualityWidget({
+    super.key,
+    this.apiData,
+    this.data,
+    this.compact = false,
+  });
+
+  /// Air quality data from API. Takes priority over legacy data.
+  final api.AirQualityData? apiData;
+
+  /// Legacy air quality data to display. Uses mock data if null.
+  final AirQualityData? data;
+
+  /// Whether to use compact layout.
+  final bool compact;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    // Show "no data" state when no API data and no legacy data
+    if (apiData == null && data == null) {
+      if (compact) {
+        return _buildCompactNoData(context, colorScheme);
+      }
+      return _buildNoData(context, colorScheme);
+    }
+
+    // Convert API data to local model, or use legacy data
+    final aqi = apiData != null ? _fromApiData(apiData!) : data!;
+
+    if (compact) {
+      return _buildCompact(context, colorScheme, aqi);
+    }
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Header
+            Row(
+              children: [
+                Icon(
+                  Icons.air,
+                  size: 20,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 8),
+                Text(
+                  'Air Quality',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 16),
+
+            // AQI Display
+            Row(
+              children: [
+                // AQI number with colored background
+                Container(
+                  width: 64,
+                  height: 64,
+                  decoration: BoxDecoration(
+                    color: aqi.level.color.withValues(alpha: 0.15),
+                    borderRadius: BorderRadius.circular(12),
+                    border: Border.all(
+                      color: aqi.level.color.withValues(alpha: 0.3),
+                      width: 2,
+                    ),
+                  ),
+                  child: Center(
+                    child: Text(
+                      '${aqi.index}',
+                      style:
+                          Theme.of(context).textTheme.headlineMedium?.copyWith(
+                                fontWeight: FontWeight.bold,
+                                color: aqi.level.color,
+                              ),
+                    ),
+                  ),
+                ),
+                const SizedBox(width: 16),
+
+                // Level info
+                Expanded(
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      Text(
+                        aqi.level.label,
+                        style:
+                            Theme.of(context).textTheme.titleMedium?.copyWith(
+                                  fontWeight: FontWeight.w600,
+                                  color: aqi.level.color,
+                                ),
+                      ),
+                      const SizedBox(height: 4),
+                      Text(
+                        aqi.level.description,
+                        style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                              color: colorScheme.onSurfaceVariant,
+                            ),
+                        maxLines: 2,
+                        overflow: TextOverflow.ellipsis,
+                      ),
+                    ],
+                  ),
+                ),
+              ],
+            ),
+
+            // Pollutants
+            if (aqi.pollutants.isNotEmpty) ...[
+              const SizedBox(height: 16),
+              const Divider(height: 1),
+              const SizedBox(height: 12),
+              Wrap(
+                spacing: 16,
+                runSpacing: 8,
+                children: aqi.pollutants
+                    .map((p) => _PollutantChip(pollutant: p))
+                    .toList(),
+              ),
+            ],
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildCompact(
+    BuildContext context,
+    ColorScheme colorScheme,
+    AirQualityData aqi,
+  ) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Container(
+              width: 32,
+              height: 32,
+              decoration: BoxDecoration(
+                color: aqi.level.color.withValues(alpha: 0.15),
+                borderRadius: BorderRadius.circular(6),
+              ),
+              child: Center(
+                child: Text(
+                  '${aqi.index}',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        fontWeight: FontWeight.bold,
+                        color: aqi.level.color,
+                      ),
+                ),
+              ),
+            ),
+            const SizedBox(width: 8),
+            Text(
+              'AQI',
+              style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                    color: colorScheme.onSurfaceVariant,
+                  ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildNoData(BuildContext context, ColorScheme colorScheme) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Header
+            Row(
+              children: [
+                Icon(
+                  Icons.air,
+                  size: 20,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 8),
+                Text(
+                  'Air Quality',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 8),
+            // Match sun position card height (170px content area)
+            SizedBox(
+              height: 170,
+              child: Center(
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    Icon(
+                      Icons.air_outlined,
+                      size: 32,
+                      color: colorScheme.outline,
+                    ),
+                    const SizedBox(height: 8),
+                    Text(
+                      'No data available',
+                      style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                            color: colorScheme.outline,
+                          ),
+                    ),
+                  ],
+                ),
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildCompactNoData(BuildContext context, ColorScheme colorScheme) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Container(
+              width: 32,
+              height: 32,
+              decoration: BoxDecoration(
+                color: colorScheme.outline.withValues(alpha: 0.15),
+                borderRadius: BorderRadius.circular(6),
+              ),
+              child: Center(
+                child: Text(
+                  '--',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        color: colorScheme.outline,
+                      ),
+                ),
+              ),
+            ),
+            const SizedBox(width: 8),
+            Text(
+              'AQI',
+              style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                    color: colorScheme.outline,
+                  ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _PollutantChip extends StatelessWidget {
+  const _PollutantChip({required this.pollutant});
+
+  final Pollutant pollutant;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Row(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Text(
+          pollutant.name,
+          style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                color: colorScheme.outline,
+              ),
+        ),
+        const SizedBox(width: 4),
+        Text(
+          '${pollutant.value.round()} ${pollutant.unit}',
+          style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                fontWeight: FontWeight.w500,
+              ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Converts API air quality data to local AirQualityData model.
+AirQualityData _fromApiData(api.AirQualityData data) {
+  final index = data.aqi ?? 0;
+  final pollutants = <Pollutant>[];
+
+  if (data.pm25 != null) {
+    pollutants.add(Pollutant(name: 'PM2.5', value: data.pm25!, unit: 'µg/m³'));
+  }
+  if (data.pm10 != null) {
+    pollutants.add(Pollutant(name: 'PM10', value: data.pm10!, unit: 'µg/m³'));
+  }
+  if (data.o3 != null) {
+    pollutants.add(Pollutant(name: 'O₃', value: data.o3!, unit: 'ppb'));
+  }
+  if (data.no2 != null) {
+    pollutants.add(Pollutant(name: 'NO₂', value: data.no2!, unit: 'ppb'));
+  }
+
+  return AirQualityData(
+    index: index,
+    level: AqiLevel.fromIndex(index),
+    pollutants: pollutants,
+  );
+}
+
+/// Air Quality Index levels based on US EPA standard.
+enum AqiLevel {
+  good(
+    label: 'Good',
+    description: 'Air quality is satisfactory',
+    color: StoplightColors.green,
+    minIndex: 0,
+    maxIndex: 50,
+  ),
+  moderate(
+    label: 'Moderate',
+    description: 'Acceptable for most people',
+    color: StoplightColors.orange,
+    minIndex: 51,
+    maxIndex: 100,
+  ),
+  unhealthySensitive(
+    label: 'Unhealthy for Sensitive',
+    description: 'May affect sensitive groups',
+    color: StoplightColors.orange,
+    minIndex: 101,
+    maxIndex: 150,
+  ),
+  unhealthy(
+    label: 'Unhealthy',
+    description: 'Health effects for everyone',
+    color: StoplightColors.red,
+    minIndex: 151,
+    maxIndex: 200,
+  ),
+  veryUnhealthy(
+    label: 'Very Unhealthy',
+    description: 'Serious health effects',
+    color: Color(0xFF8B008B),
+    minIndex: 201,
+    maxIndex: 300,
+  ),
+  hazardous(
+    label: 'Hazardous',
+    description: 'Health emergency conditions',
+    color: Color(0xFF800000),
+    minIndex: 301,
+    maxIndex: 500,
+  );
+
+  const AqiLevel({
+    required this.label,
+    required this.description,
+    required this.color,
+    required this.minIndex,
+    required this.maxIndex,
+  });
+
+  final String label;
+  final String description;
+  final Color color;
+  final int minIndex;
+  final int maxIndex;
+
+  static AqiLevel fromIndex(int index) {
+    for (final level in AqiLevel.values) {
+      if (index >= level.minIndex && index <= level.maxIndex) {
+        return level;
+      }
+    }
+    return AqiLevel.hazardous;
+  }
+}
+
+/// Pollutant data.
+class Pollutant {
+  const Pollutant({
+    required this.name,
+    required this.value,
+    required this.unit,
+  });
+
+  final String name;
+  final double value;
+  final String unit;
+}
+
+/// Air quality data model.
+class AirQualityData {
+  const AirQualityData({
+    required this.index,
+    required this.level,
+    this.pollutants = const [],
+  });
+
+  final int index;
+  final AqiLevel level;
+  final List<Pollutant> pollutants;
+
+  /// Create from index value.
+  factory AirQualityData.fromIndex(int index, {List<Pollutant>? pollutants}) {
+    return AirQualityData(
+      index: index,
+      level: AqiLevel.fromIndex(index),
+      pollutants: pollutants ?? const [],
+    );
+  }
+
+  /// Mock air quality data for development.
+  factory AirQualityData.mock() {
+    return const AirQualityData(
+      index: 42,
+      level: AqiLevel.good,
+      pollutants: [
+        Pollutant(name: 'PM2.5', value: 8.5, unit: 'µg/m³'),
+        Pollutant(name: 'PM10', value: 15, unit: 'µg/m³'),
+        Pollutant(name: 'O₃', value: 32, unit: 'ppb'),
+      ],
+    );
+  }
+}
@@ -0,0 +1,344 @@
+import 'package:flutter/material.dart';
+import 'package:intl/intl.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/environment_model.dart';
+
+/// Forecast widget displaying multi-day weather outlook.
+///
+/// Shows a horizontal scrollable list of forecast days with
+/// high/low temperatures and weather icons.
+class ForecastWidget extends StatelessWidget {
+  const ForecastWidget({
+    super.key,
+    this.forecast,
+    this.compact = false,
+  });
+
+  /// Forecast data to display.
+  final List<ForecastDay>? forecast;
+
+  /// Whether to use compact layout.
+  final bool compact;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    if (forecast == null || forecast!.isEmpty) {
+      return Card(
+        child: Padding(
+          padding: const EdgeInsets.all(16),
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              // Header
+              Row(
+                children: [
+                  Icon(
+                    Icons.calendar_today,
+                    size: 20,
+                    color: colorScheme.onSurfaceVariant,
+                  ),
+                  const SizedBox(width: 8),
+                  Text(
+                    'Forecast',
+                    style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                  ),
+                ],
+              ),
+              const SizedBox(height: 8),
+              // Match sun position card height (170px content area)
+              SizedBox(
+                height: 170,
+                child: Center(
+                  child: Column(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Icon(
+                        Icons.event_busy_outlined,
+                        size: 32,
+                        color: colorScheme.outline,
+                      ),
+                      const SizedBox(height: 8),
+                      Text(
+                        'No data available',
+                        style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                              color: colorScheme.outline,
+                            ),
+                      ),
+                    ],
+                  ),
+                ),
+              ),
+            ],
+          ),
+        ),
+      );
+    }
+
+    if (compact) {
+      return _buildCompact(context, colorScheme);
+    }
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Header
+            Row(
+              children: [
+                Icon(
+                  Icons.calendar_today,
+                  size: 20,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 8),
+                Text(
+                  'Forecast',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 16),
+
+            // Forecast days - horizontal scroll
+            SizedBox(
+              height: 100,
+              child: ListView.separated(
+                scrollDirection: Axis.horizontal,
+                itemCount: forecast!.length,
+                separatorBuilder: (_, i) => const SizedBox(width: 12),
+                itemBuilder: (context, index) {
+                  return _ForecastDayCard(day: forecast![index]);
+                },
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildCompact(BuildContext context, ColorScheme colorScheme) {
+    // Show just first 3 days in compact mode
+    final days = forecast!.take(3).toList();
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(
+              Icons.calendar_today,
+              size: 20,
+              color: colorScheme.onSurfaceVariant,
+            ),
+            const SizedBox(width: 8),
+            ...days.map((day) => Padding(
+                  padding: const EdgeInsets.symmetric(horizontal: 4),
+                  child: Column(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Text(
+                        _getDayName(day.date),
+                        style: Theme.of(context).textTheme.labelSmall,
+                      ),
+                      Icon(
+                        _getWeatherIcon(day.conditions),
+                        size: 16,
+                        color: _getWeatherColor(day.conditions),
+                      ),
+                      Text(
+                        '${day.high?.round() ?? '--'}°',
+                        style: Theme.of(context).textTheme.labelSmall,
+                      ),
+                    ],
+                  ),
+                )),
+          ],
+        ),
+      ),
+    );
+  }
+
+  String _getDayName(String dateStr) {
+    try {
+      final date = DateTime.parse(dateStr);
+      final now = DateTime.now();
+      if (date.day == now.day &&
+          date.month == now.month &&
+          date.year == now.year) {
+        return 'Today';
+      }
+      final tomorrow = now.add(const Duration(days: 1));
+      if (date.day == tomorrow.day &&
+          date.month == tomorrow.month &&
+          date.year == tomorrow.year) {
+        return 'Tmrw';
+      }
+      return DateFormat('E').format(date);
+    } catch (_) {
+      return dateStr.length > 3 ? dateStr.substring(0, 3) : dateStr;
+    }
+  }
+
+  IconData _getWeatherIcon(String? conditions) {
+    final condition = conditions?.toLowerCase() ?? '';
+
+    if (condition.contains('clear') || condition.contains('sunny')) {
+      return Icons.wb_sunny;
+    } else if (condition.contains('cloud') || condition.contains('overcast')) {
+      return Icons.cloud;
+    } else if (condition.contains('rain') || condition.contains('drizzle')) {
+      return Icons.grain;
+    } else if (condition.contains('storm') || condition.contains('thunder')) {
+      return Icons.thunderstorm;
+    } else if (condition.contains('snow') || condition.contains('sleet')) {
+      return Icons.ac_unit;
+    } else if (condition.contains('fog') || condition.contains('mist')) {
+      return Icons.blur_on;
+    }
+    return Icons.cloud;
+  }
+
+  Color? _getWeatherColor(String? conditions) {
+    final condition = conditions?.toLowerCase() ?? '';
+
+    if (condition.contains('clear') || condition.contains('sunny')) {
+      return Colors.amber;
+    } else if (condition.contains('cloud')) {
+      return Colors.blueGrey;
+    } else if (condition.contains('rain')) {
+      return Colors.blue;
+    } else if (condition.contains('storm')) {
+      return Colors.deepPurple;
+    } else if (condition.contains('snow')) {
+      return Colors.lightBlue;
+    }
+    return null;
+  }
+}
+
+class _ForecastDayCard extends StatelessWidget {
+  const _ForecastDayCard({required this.day});
+
+  final ForecastDay day;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final icon = _getWeatherIcon(day.conditions);
+    final color = _getWeatherColor(day.conditions) ?? colorScheme.primary;
+
+    return Container(
+      width: 72,
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 12),
+      decoration: BoxDecoration(
+        color: colorScheme.surfaceContainerHighest,
+        borderRadius: BorderRadius.circular(12),
+      ),
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.spaceBetween,
+        children: [
+          // Day name
+          Text(
+            _getDayName(day.date),
+            style: Theme.of(context).textTheme.labelMedium?.copyWith(
+                  fontWeight: FontWeight.w600,
+                ),
+          ),
+
+          // Weather icon
+          Icon(
+            icon,
+            size: 24,
+            color: color,
+          ),
+
+          // High/Low temps
+          Column(
+            children: [
+              Text(
+                '${day.high?.round() ?? '--'}°',
+                style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                      fontWeight: FontWeight.bold,
+                    ),
+              ),
+              Text(
+                '${day.low?.round() ?? '--'}°',
+                style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                      color: colorScheme.onSurfaceVariant,
+                    ),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  }
+
+  String _getDayName(String dateStr) {
+    try {
+      final date = DateTime.parse(dateStr);
+      final now = DateTime.now();
+      if (date.day == now.day &&
+          date.month == now.month &&
+          date.year == now.year) {
+        return 'Today';
+      }
+      final tomorrow = now.add(const Duration(days: 1));
+      if (date.day == tomorrow.day &&
+          date.month == tomorrow.month &&
+          date.year == tomorrow.year) {
+        return 'Tmrw';
+      }
+      return DateFormat('EEE').format(date);
+    } catch (_) {
+      return dateStr.length > 3 ? dateStr.substring(0, 3) : dateStr;
+    }
+  }
+
+  IconData _getWeatherIcon(String? conditions) {
+    final condition = conditions?.toLowerCase() ?? '';
+
+    if (condition.contains('clear') || condition.contains('sunny')) {
+      return Icons.wb_sunny;
+    } else if (condition.contains('cloud') || condition.contains('overcast')) {
+      return Icons.cloud;
+    } else if (condition.contains('rain') || condition.contains('drizzle')) {
+      return Icons.grain;
+    } else if (condition.contains('storm') || condition.contains('thunder')) {
+      return Icons.thunderstorm;
+    } else if (condition.contains('snow') || condition.contains('sleet')) {
+      return Icons.ac_unit;
+    } else if (condition.contains('fog') || condition.contains('mist')) {
+      return Icons.blur_on;
+    }
+    return Icons.cloud;
+  }
+
+  Color? _getWeatherColor(String? conditions) {
+    final condition = conditions?.toLowerCase() ?? '';
+
+    if (condition.contains('clear') || condition.contains('sunny')) {
+      return Colors.amber;
+    } else if (condition.contains('cloud')) {
+      return Colors.blueGrey;
+    } else if (condition.contains('rain')) {
+      return Colors.blue;
+    } else if (condition.contains('storm')) {
+      return Colors.deepPurple;
+    } else if (condition.contains('snow')) {
+      return Colors.lightBlue;
+    }
+    return null;
+  }
+}
@@ -0,0 +1,224 @@
+import 'dart:math' as math;
+
+import 'package:flutter/material.dart';
+
+/// A speedometer-style gauge widget for displaying percentage values.
+///
+/// Commonly used for system stats like CPU, Memory, Disk usage.
+class GaugeWidget extends StatelessWidget {
+  const GaugeWidget({
+    super.key,
+    required this.value,
+    required this.label,
+    this.size = 120,
+    this.strokeWidth = 10,
+    this.color,
+    this.backgroundColor,
+    this.showPercentage = true,
+    this.icon,
+  });
+
+  /// The value to display (0.0 - 1.0).
+  final double value;
+
+  /// Label displayed below the gauge.
+  final String label;
+
+  /// Size of the gauge widget.
+  final double size;
+
+  /// Width of the gauge arc stroke.
+  final double strokeWidth;
+
+  /// Color of the filled arc. Uses primary color if not specified.
+  final Color? color;
+
+  /// Color of the background arc. Uses surfaceVariant if not specified.
+  final Color? backgroundColor;
+
+  /// Whether to show the percentage text in the center.
+  final bool showPercentage;
+
+  /// Optional icon to show above the percentage.
+  final IconData? icon;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final effectiveColor = color ?? colorScheme.primary;
+    final effectiveBackgroundColor =
+        backgroundColor ?? colorScheme.surfaceContainerHighest;
+
+    // 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: gaugeHeight + 32 + iconSpace, // Space for label + icon
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          SizedBox(
+            width: size,
+            height: gaugeHeight,
+            child: CustomPaint(
+              painter: _GaugePainter(
+                value: clampedValue,
+                color: effectiveColor,
+                backgroundColor: effectiveBackgroundColor,
+                strokeWidth: strokeWidth,
+              ),
+              child: Align(
+                alignment: const Alignment(0, 0.6),
+                child: showPercentage
+                    ? Text(
+                        '${(clampedValue * 100).round()}%',
+                        style: Theme.of(context).textTheme.titleLarge?.copyWith(
+                              fontWeight: FontWeight.bold,
+                              fontSize: size * 0.2,
+                            ),
+                      )
+                    : const SizedBox.shrink(),
+              ),
+            ),
+          ),
+          const SizedBox(height: 4),
+          Text(
+            label,
+            style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                  color: colorScheme.onSurfaceVariant,
+                ),
+            textAlign: TextAlign.center,
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+          ),
+          if (icon != null) ...[
+            const SizedBox(height: 8),
+            Icon(
+              icon,
+              size: size * 0.28,
+              color: effectiveColor,
+            ),
+          ],
+        ],
+      ),
+    );
+  }
+}
+
+class _GaugePainter extends CustomPainter {
+  _GaugePainter({
+    required this.value,
+    required this.color,
+    required this.backgroundColor,
+    required this.strokeWidth,
+  });
+
+  final double value;
+  final Color color;
+  final Color backgroundColor;
+  final double strokeWidth;
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    // Center at bottom of widget for speedometer style
+    final center = Offset(size.width / 2, size.height);
+    final radius = (size.width - strokeWidth) / 2;
+
+    // Speedometer arc: starts from left (180°) and sweeps 180° to right
+    const startAngle = math.pi; // 180 degrees (left side)
+    const sweepAngle = math.pi; // 180 degrees sweep (semicircle)
+
+    // Background arc
+    final backgroundPaint = Paint()
+      ..color = backgroundColor
+      ..style = PaintingStyle.stroke
+      ..strokeWidth = strokeWidth
+      ..strokeCap = StrokeCap.round;
+
+    canvas.drawArc(
+      Rect.fromCircle(center: center, radius: radius),
+      startAngle,
+      sweepAngle,
+      false,
+      backgroundPaint,
+    );
+
+    // Value arc
+    if (value > 0) {
+      final valuePaint = Paint()
+        ..color = color
+        ..style = PaintingStyle.stroke
+        ..strokeWidth = strokeWidth
+        ..strokeCap = StrokeCap.round;
+
+      canvas.drawArc(
+        Rect.fromCircle(center: center, radius: radius),
+        startAngle,
+        sweepAngle * value,
+        false,
+        valuePaint,
+      );
+    }
+  }
+
+  @override
+  bool shouldRepaint(_GaugePainter oldDelegate) {
+    return oldDelegate.value != value ||
+        oldDelegate.color != color ||
+        oldDelegate.backgroundColor != backgroundColor ||
+        oldDelegate.strokeWidth != strokeWidth;
+  }
+}
+
+/// A row of gauge widgets with consistent sizing.
+class GaugeRow extends StatelessWidget {
+  const GaugeRow({
+    super.key,
+    required this.gauges,
+    this.gaugeSize = 100,
+  });
+
+  final List<GaugeData> gauges;
+  final double gaugeSize;
+
+  @override
+  Widget build(BuildContext context) {
+    return Wrap(
+      spacing: 24,
+      runSpacing: 16,
+      alignment: WrapAlignment.center,
+      children: gauges
+          .map(
+            (data) => GaugeWidget(
+              value: data.value,
+              label: data.label,
+              size: gaugeSize,
+              strokeWidth: gaugeSize * 0.1,
+              color: data.color,
+              icon: data.icon,
+            ),
+          )
+          .toList(),
+    );
+  }
+}
+
+/// Data class for gauge configuration.
+class GaugeData {
+  const GaugeData({
+    required this.value,
+    required this.label,
+    this.color,
+    this.icon,
+  });
+
+  final double value;
+  final String label;
+  final Color? color;
+  final IconData? icon;
+}
@@ -0,0 +1,465 @@
+import 'package:flutter/material.dart';
+
+/// A widget that displays a grid of Material icons for selection.
+///
+/// Shows a button that opens a dialog with available icons.
+class IconPicker extends StatelessWidget {
+  const IconPicker({
+    super.key,
+    required this.selectedIcon,
+    required this.onChanged,
+    this.label = 'Icon',
+  });
+
+  /// Currently selected icon name.
+  final String selectedIcon;
+
+  /// Callback when an icon is selected.
+  final ValueChanged<String> onChanged;
+
+  /// Label for the field.
+  final String label;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        Text(
+          label,
+          style: textTheme.labelMedium?.copyWith(
+            color: colorScheme.onSurfaceVariant,
+          ),
+        ),
+        const SizedBox(height: 8),
+        InkWell(
+          onTap: () => _showIconPicker(context),
+          borderRadius: BorderRadius.circular(8),
+          child: Container(
+            padding: const EdgeInsets.all(12),
+            decoration: BoxDecoration(
+              border: Border.all(color: colorScheme.outline),
+              borderRadius: BorderRadius.circular(8),
+            ),
+            child: Row(
+              children: [
+                Container(
+                  width: 40,
+                  height: 40,
+                  decoration: BoxDecoration(
+                    color: colorScheme.primaryContainer,
+                    borderRadius: BorderRadius.circular(8),
+                  ),
+                  child: Icon(
+                    getIconData(selectedIcon),
+                    color: colorScheme.onPrimaryContainer,
+                  ),
+                ),
+                const SizedBox(width: 12),
+                Expanded(
+                  child: Text(
+                    selectedIcon,
+                    style: textTheme.bodyLarge,
+                  ),
+                ),
+                Icon(
+                  Icons.arrow_drop_down,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+              ],
+            ),
+          ),
+        ),
+      ],
+    );
+  }
+
+  Future<void> _showIconPicker(BuildContext context) async {
+    final result = await showDialog<String>(
+      context: context,
+      builder: (context) => IconPickerDialog(
+        selectedIcon: selectedIcon,
+        onSelected: (icon) => Navigator.of(context).pop(icon),
+      ),
+    );
+
+    if (result != null) {
+      onChanged(result);
+    }
+  }
+}
+
+/// Dialog that displays a grid of icons.
+class IconPickerDialog extends StatefulWidget {
+  const IconPickerDialog({
+    super.key,
+    required this.selectedIcon,
+    required this.onSelected,
+  });
+
+  final String selectedIcon;
+  final ValueChanged<String> onSelected;
+
+  @override
+  State<IconPickerDialog> createState() => _IconPickerDialogState();
+}
+
+class _IconPickerDialogState extends State<IconPickerDialog> {
+  String _searchQuery = '';
+
+  List<String> get _filteredIcons {
+    if (_searchQuery.isEmpty) {
+      return availableIcons;
+    }
+    return availableIcons
+        .where((icon) => icon.toLowerCase().contains(_searchQuery.toLowerCase()))
+        .toList();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Dialog(
+      child: Container(
+        width: 400,
+        height: 500,
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text(
+              'Select Icon',
+              style: Theme.of(context).textTheme.titleLarge,
+            ),
+            const SizedBox(height: 16),
+            TextField(
+              decoration: const InputDecoration(
+                hintText: 'Search icons...',
+                prefixIcon: Icon(Icons.search),
+                border: OutlineInputBorder(),
+                isDense: true,
+              ),
+              onChanged: (value) => setState(() => _searchQuery = value),
+            ),
+            const SizedBox(height: 16),
+            Expanded(
+              child: GridView.builder(
+                gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
+                  crossAxisCount: 5,
+                  mainAxisSpacing: 8,
+                  crossAxisSpacing: 8,
+                ),
+                itemCount: _filteredIcons.length,
+                itemBuilder: (context, index) {
+                  final iconName = _filteredIcons[index];
+                  final isSelected = iconName == widget.selectedIcon;
+
+                  return InkWell(
+                    onTap: () => widget.onSelected(iconName),
+                    borderRadius: BorderRadius.circular(8),
+                    child: Container(
+                      decoration: BoxDecoration(
+                        color: isSelected
+                            ? colorScheme.primaryContainer
+                            : colorScheme.surfaceContainerHighest,
+                        borderRadius: BorderRadius.circular(8),
+                        border: isSelected
+                            ? Border.all(color: colorScheme.primary, width: 2)
+                            : null,
+                      ),
+                      child: Tooltip(
+                        message: iconName,
+                        child: Icon(
+                          getIconData(iconName),
+                          color: isSelected
+                              ? colorScheme.onPrimaryContainer
+                              : colorScheme.onSurface,
+                        ),
+                      ),
+                    ),
+                  );
+                },
+              ),
+            ),
+            const SizedBox(height: 16),
+            Row(
+              mainAxisAlignment: MainAxisAlignment.end,
+              children: [
+                TextButton(
+                  onPressed: () => Navigator.of(context).pop(),
+                  child: const Text('Cancel'),
+                ),
+              ],
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+/// Common icons available for selection.
+const List<String> availableIcons = [
+  'home',
+  'settings',
+  'search',
+  'menu',
+  'add',
+  'remove',
+  'close',
+  'check',
+  'edit',
+  'delete',
+  'favorite',
+  'star',
+  'movie',
+  'music_note',
+  'photo',
+  'videocam',
+  'camera',
+  'mic',
+  'volume_up',
+  'play_arrow',
+  'pause',
+  'stop',
+  'skip_next',
+  'skip_previous',
+  'folder',
+  'file_copy',
+  'cloud',
+  'cloud_download',
+  'cloud_upload',
+  'download',
+  'upload',
+  'share',
+  'link',
+  'public',
+  'language',
+  'dns',
+  'storage',
+  'memory',
+  'code',
+  'terminal',
+  'bug_report',
+  'api',
+  'http',
+  'vpn_key',
+  'lock',
+  'lock_open',
+  'security',
+  'verified_user',
+  'admin_panel_settings',
+  'monitor',
+  'monitoring',
+  'analytics',
+  'dashboard',
+  'speed',
+  'timer',
+  'schedule',
+  'calendar_today',
+  'event',
+  'notifications',
+  'email',
+  'message',
+  'chat',
+  'forum',
+  'person',
+  'people',
+  'group',
+  'account_circle',
+  'shopping_cart',
+  'credit_card',
+  'attach_money',
+  'trending_up',
+  'trending_down',
+  'wifi',
+  'bluetooth',
+  'router',
+  'devices',
+  'computer',
+  'laptop',
+  'phone_android',
+  'tablet',
+  'watch',
+  'tv',
+  'games',
+  'videogame_asset',
+  'sports_esports',
+  'local_cafe',
+  'local_dining',
+  'restaurant',
+  'directions_car',
+  'flight',
+  'hotel',
+  'map',
+  'place',
+  'explore',
+  'navigation',
+  'book',
+  'school',
+  'science',
+  'psychology',
+  'work',
+  'business',
+  'apartment',
+  'location_city',
+  'eco',
+  'water_drop',
+  'air',
+  'thermostat',
+  'bolt',
+  'light_mode',
+  'dark_mode',
+  'brightness_4',
+  'palette',
+  'brush',
+  'format_paint',
+  'extension',
+  'widgets',
+  'view_module',
+  'grid_view',
+  'list',
+  'table_chart',
+  'pie_chart',
+  'bar_chart',
+  'show_chart',
+  'donut_large',
+  'disc_full',
+];
+
+/// Convert icon name string to IconData.
+IconData getIconData(String iconName) {
+  const iconMap = <String, IconData>{
+    'home': Icons.home,
+    'settings': Icons.settings,
+    'search': Icons.search,
+    'menu': Icons.menu,
+    'add': Icons.add,
+    'remove': Icons.remove,
+    'close': Icons.close,
+    'check': Icons.check,
+    'edit': Icons.edit,
+    'delete': Icons.delete,
+    'favorite': Icons.favorite,
+    'star': Icons.star,
+    'movie': Icons.movie,
+    'music_note': Icons.music_note,
+    'photo': Icons.photo,
+    'videocam': Icons.videocam,
+    'camera': Icons.camera,
+    'mic': Icons.mic,
+    'volume_up': Icons.volume_up,
+    'play_arrow': Icons.play_arrow,
+    'pause': Icons.pause,
+    'stop': Icons.stop,
+    'skip_next': Icons.skip_next,
+    'skip_previous': Icons.skip_previous,
+    'folder': Icons.folder,
+    'file_copy': Icons.file_copy,
+    'cloud': Icons.cloud,
+    'cloud_download': Icons.cloud_download,
+    'cloud_upload': Icons.cloud_upload,
+    'download': Icons.download,
+    'upload': Icons.upload,
+    'share': Icons.share,
+    'link': Icons.link,
+    'public': Icons.public,
+    'language': Icons.language,
+    'dns': Icons.dns,
+    'storage': Icons.storage,
+    'memory': Icons.memory,
+    'code': Icons.code,
+    'terminal': Icons.terminal,
+    'bug_report': Icons.bug_report,
+    'api': Icons.api,
+    'http': Icons.http,
+    'vpn_key': Icons.vpn_key,
+    'lock': Icons.lock,
+    'lock_open': Icons.lock_open,
+    'security': Icons.security,
+    'verified_user': Icons.verified_user,
+    'admin_panel_settings': Icons.admin_panel_settings,
+    'monitor': Icons.monitor,
+    'monitoring': Icons.monitor_heart,
+    'analytics': Icons.analytics,
+    'dashboard': Icons.dashboard,
+    'speed': Icons.speed,
+    'timer': Icons.timer,
+    'schedule': Icons.schedule,
+    'calendar_today': Icons.calendar_today,
+    'event': Icons.event,
+    'notifications': Icons.notifications,
+    'email': Icons.email,
+    'message': Icons.message,
+    'chat': Icons.chat,
+    'forum': Icons.forum,
+    'person': Icons.person,
+    'people': Icons.people,
+    'group': Icons.group,
+    'account_circle': Icons.account_circle,
+    'shopping_cart': Icons.shopping_cart,
+    'credit_card': Icons.credit_card,
+    'attach_money': Icons.attach_money,
+    'trending_up': Icons.trending_up,
+    'trending_down': Icons.trending_down,
+    'wifi': Icons.wifi,
+    'bluetooth': Icons.bluetooth,
+    'router': Icons.router,
+    'devices': Icons.devices,
+    'computer': Icons.computer,
+    'laptop': Icons.laptop,
+    'phone_android': Icons.phone_android,
+    'tablet': Icons.tablet,
+    'watch': Icons.watch,
+    'tv': Icons.tv,
+    'games': Icons.games,
+    'videogame_asset': Icons.videogame_asset,
+    'sports_esports': Icons.sports_esports,
+    'local_cafe': Icons.local_cafe,
+    'local_dining': Icons.local_dining,
+    'restaurant': Icons.restaurant,
+    'directions_car': Icons.directions_car,
+    'flight': Icons.flight,
+    'hotel': Icons.hotel,
+    'map': Icons.map,
+    'place': Icons.place,
+    'explore': Icons.explore,
+    'navigation': Icons.navigation,
+    'book': Icons.book,
+    'school': Icons.school,
+    'science': Icons.science,
+    'psychology': Icons.psychology,
+    'work': Icons.work,
+    'business': Icons.business,
+    'apartment': Icons.apartment,
+    'location_city': Icons.location_city,
+    'eco': Icons.eco,
+    'water_drop': Icons.water_drop,
+    'air': Icons.air,
+    'thermostat': Icons.thermostat,
+    'bolt': Icons.bolt,
+    'light_mode': Icons.light_mode,
+    'dark_mode': Icons.dark_mode,
+    'brightness_4': Icons.brightness_4,
+    'palette': Icons.palette,
+    'brush': Icons.brush,
+    'format_paint': Icons.format_paint,
+    'extension': Icons.extension,
+    'widgets': Icons.widgets,
+    'view_module': Icons.view_module,
+    'grid_view': Icons.grid_view,
+    'list': Icons.list,
+    'table_chart': Icons.table_chart,
+    'pie_chart': Icons.pie_chart,
+    'bar_chart': Icons.bar_chart,
+    'show_chart': Icons.show_chart,
+    'donut_large': Icons.donut_large,
+    'disc_full': Icons.disc_full,
+  };
+
+  return iconMap[iconName] ?? Icons.help_outline;
+}
@@ -0,0 +1,600 @@
+import 'dart:async';
+import 'dart:math' as math;
+import 'package:flutter/material.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/environment_model.dart';
+
+/// Sun position widget displaying sunrise/sunset with animated arc.
+///
+/// Shows a semicircle arc representing the day, with sun/moon icon
+/// moving along based on current time. Uses color gradients:
+/// - Blue tones for night
+/// - Orange tones for sunrise/sunset
+/// - Yellow tones for daytime
+///
+/// Position updates every 10 minutes based on system clock.
+/// When sun times are unavailable, assumes 12-hour day/night cycles
+/// (6am sunrise, 6pm sunset).
+class SunPositionWidget extends StatefulWidget {
+  const SunPositionWidget({
+    super.key,
+    this.sunTimes,
+    this.compact = false,
+  });
+
+  /// Sun times data to display.
+  final SunTimesData? sunTimes;
+
+  /// Whether to use compact layout.
+  final bool compact;
+
+  @override
+  State<SunPositionWidget> createState() => _SunPositionWidgetState();
+}
+
+class _SunPositionWidgetState extends State<SunPositionWidget> {
+  Timer? _positionTimer;
+
+  @override
+  void initState() {
+    super.initState();
+    _scheduleNextUpdate();
+  }
+
+  /// Schedule update at next 10-minute wall clock mark (0/10/20/30/40/50)
+  void _scheduleNextUpdate() {
+    final now = DateTime.now();
+    final currentMinute = now.minute;
+    // Calculate minutes until next 10-minute mark
+    final minutesUntilNext = 10 - (currentMinute % 10);
+    final secondsUntilNext = (minutesUntilNext * 60) - now.second;
+
+    _positionTimer = Timer(
+      Duration(seconds: secondsUntilNext),
+      () {
+        if (mounted) {
+          setState(() {});
+          _scheduleNextUpdate();
+        }
+      },
+    );
+  }
+
+  @override
+  void dispose() {
+    _positionTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Get sunrise time, defaulting to 7am if not available (asymmetric for visual effect)
+  DateTime get _sunrise {
+    final now = DateTime.now();
+    return widget.sunTimes?.sunrise ?? DateTime(now.year, now.month, now.day, 7, 0);
+  }
+
+  /// Get sunset time, defaulting to 5pm if not available (asymmetric for visual effect)
+  DateTime get _sunset {
+    final now = DateTime.now();
+    return widget.sunTimes?.sunset ?? DateTime(now.year, now.month, now.day, 17, 0);
+  }
+
+  /// Calculate daylight minutes from sunrise/sunset
+  int get _daylightMinutes {
+    return _sunset.difference(_sunrise).inMinutes;
+  }
+
+  bool get _isDaytime {
+    final now = DateTime.now();
+    return now.isAfter(_sunrise) && now.isBefore(_sunset);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    if (widget.compact) {
+      return _buildCompact(context, colorScheme);
+    }
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Header
+            Row(
+              children: [
+                Icon(
+                  _isDaytime ? Icons.wb_sunny : Icons.nightlight_round,
+                  size: 20,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 8),
+                Text(
+                  'Sun Position',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 8),
+
+            // Arc with integrated horizon labels
+            SizedBox(
+              height: 170,
+              child: LayoutBuilder(
+                builder: (context, constraints) {
+                  return Stack(
+                    clipBehavior: Clip.none,
+                    children: [
+                      // Arc painter
+                      Positioned.fill(
+                        child: CustomPaint(
+                          painter: _SunArcPainter(
+                            sunTimes: widget.sunTimes,
+                            isDark: colorScheme.brightness == Brightness.dark,
+                          ),
+                        ),
+                      ),
+                      // Sunrise widget at left horizon (10px up for balance)
+                      Positioned(
+                        left: 0,
+                        bottom: 10,
+                        child: _HorizonTimeDisplay(
+                          icon: Icons.wb_twilight,
+                          label: 'Sunrise',
+                          time: _sunrise,
+                          iconColor: Colors.orange,
+                          alignment: CrossAxisAlignment.start,
+                        ),
+                      ),
+                      // Daylight display centered (at bottom for balance)
+                      Positioned(
+                        left: 0,
+                        right: 0,
+                        bottom: 0,
+                        child: Center(
+                          child: _DaylightDisplay(minutes: _daylightMinutes),
+                        ),
+                      ),
+                      // Sunset widget at right horizon (10px up for balance)
+                      Positioned(
+                        right: 0,
+                        bottom: 10,
+                        child: _HorizonTimeDisplay(
+                          icon: Icons.nights_stay,
+                          label: 'Sunset',
+                          time: _sunset,
+                          iconColor: Colors.deepOrange,
+                          alignment: CrossAxisAlignment.end,
+                        ),
+                      ),
+                    ],
+                  );
+                },
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildCompact(BuildContext context, ColorScheme colorScheme) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(
+              _isDaytime ? Icons.wb_sunny : Icons.nightlight_round,
+              size: 24,
+              color: _isDaytime ? Colors.amber : Colors.indigo,
+            ),
+            const SizedBox(width: 8),
+            Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                Text(
+                  _formatTime(_sunrise),
+                  style: Theme.of(context).textTheme.labelSmall,
+                ),
+                Text(
+                  _formatTime(_sunset),
+                  style: Theme.of(context).textTheme.labelSmall,
+                ),
+              ],
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  String _formatTime(DateTime time) {
+    return '${time.hour.toString().padLeft(2, '0')}:${time.minute.toString().padLeft(2, '0')}';
+  }
+}
+
+/// Horizon-aligned time display with icon above time and label.
+class _HorizonTimeDisplay extends StatelessWidget {
+  const _HorizonTimeDisplay({
+    required this.icon,
+    required this.label,
+    required this.time,
+    this.iconColor,
+    this.alignment = CrossAxisAlignment.center,
+  });
+
+  final IconData icon;
+  final String label;
+  final DateTime time;
+  final Color? iconColor;
+  final CrossAxisAlignment alignment;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: alignment,
+      children: [
+        Icon(
+          icon,
+          size: 18,
+          color: iconColor ?? colorScheme.primary,
+        ),
+        const SizedBox(height: 2),
+        Text(
+          '${time.hour.toString().padLeft(2, '0')}:${time.minute.toString().padLeft(2, '0')}',
+          style: Theme.of(context).textTheme.labelMedium?.copyWith(
+                fontWeight: FontWeight.w600,
+              ),
+        ),
+        Text(
+          label,
+          style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                color: colorScheme.onSurfaceVariant,
+                fontSize: 10,
+              ),
+        ),
+      ],
+    );
+  }
+}
+
+class _DaylightDisplay extends StatelessWidget {
+  const _DaylightDisplay({required this.minutes});
+
+  final int minutes;
+
+  @override
+  Widget build(BuildContext context) {
+    final hours = minutes ~/ 60;
+    final mins = minutes % 60;
+
+    return Column(
+      children: [
+        Icon(
+          Icons.access_time,
+          size: 16,
+          color: Theme.of(context).colorScheme.outline,
+        ),
+        const SizedBox(height: 4),
+        Text(
+          '${hours}h ${mins}m',
+          style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                fontWeight: FontWeight.w500,
+              ),
+        ),
+        Text(
+          'Daylight',
+          style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                color: Theme.of(context).colorScheme.onSurfaceVariant,
+              ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Custom painter for the sun arc visualization.
+///
+/// The arc is proportional to the day/night duration:
+/// - During day: shows a day arc spanning (daylight hours / 24) × 360°
+/// - During night: shows a night arc spanning (night hours / 24) × 360°
+/// - Arc endpoints touch the horizon line at sunrise/sunset positions
+class _SunArcPainter extends CustomPainter {
+  _SunArcPainter({
+    this.sunTimes,
+    this.isDark = false,
+  });
+
+  final SunTimesData? sunTimes;
+  final bool isDark;
+
+  // Color palette
+  static const _nightBlue = Color(0xFF1a237e);
+  static const _dawnOrange = Color(0xFFff6f00);
+  static const _sunriseOrange = Color(0xFFffa000);
+  static const _dayYellow = Color(0xFFffc107);
+  static const _dayGold = Color(0xFFffb300);
+  static const _duskOrange = Color(0xFFef6c00);
+  static const _nightIndigo = Color(0xFF283593);
+  static const _moonSilver = Color(0xFFB0BEC5);
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final now = DateTime.now();
+
+    // Get sunrise/sunset times (default to 7am/5pm for asymmetric visual)
+    final sunrise = sunTimes?.sunrise ?? DateTime(now.year, now.month, now.day, 7, 0);
+    final sunset = sunTimes?.sunset ?? DateTime(now.year, now.month, now.day, 17, 0);
+
+    // Calculate durations
+    final daylightMinutes = sunset.difference(sunrise).inMinutes;
+    final nightMinutes = 1440 - daylightMinutes; // 24 hours = 1440 minutes
+
+    // Determine if currently day or night
+    final isDaytime = now.isAfter(sunrise) && now.isBefore(sunset);
+
+    // Calculate arc angles (proportional to duration)
+    final dayArcAngle = (daylightMinutes / 1440) * 2 * math.pi;
+    final nightArcAngle = (nightMinutes / 1440) * 2 * math.pi;
+
+    // Layout constants - horizon is 50px from bottom to leave room for labels
+    const horizonY = 50.0;
+    const horizontalPadding = 40.0;
+    final horizonWidth = size.width - (horizontalPadding * 2);
+    final centerX = size.width / 2;
+
+    // Draw horizon line
+    final horizonPaint = Paint()
+      ..color = isDark ? Colors.white24 : Colors.black12
+      ..strokeWidth = 1;
+    canvas.drawLine(
+      Offset(horizontalPadding - 5, size.height - horizonY),
+      Offset(size.width - horizontalPadding + 5, size.height - horizonY),
+      horizonPaint,
+    );
+
+    if (isDaytime) {
+      _drawDayArc(canvas, size, centerX, horizonWidth, horizonY, dayArcAngle, now, sunrise, sunset);
+    } else {
+      _drawNightArc(canvas, size, centerX, horizonWidth, horizonY, nightArcAngle, now, sunrise, sunset);
+    }
+  }
+
+  void _drawDayArc(
+    Canvas canvas,
+    Size size,
+    double centerX,
+    double horizonWidth,
+    double horizonY,
+    double arcAngle,
+    DateTime now,
+    DateTime sunrise,
+    DateTime sunset,
+  ) {
+    // Clamp arc angle between 30° and 180° for visual sanity
+    final clampedAngle = arcAngle.clamp(math.pi / 6, math.pi);
+
+    // Calculate radius so arc endpoints touch horizon
+    // For a chord of width W and arc angle θ: R = W / (2 * sin(θ/2))
+    var radius = horizonWidth / (2 * math.sin(clampedAngle / 2));
+
+    // Constrain arc height to fit within available space (leave 25px margin for sun)
+    final maxArcHeight = size.height - horizonY - 25;
+    final arcHeight = radius * (1 - math.cos(clampedAngle / 2));
+    if (arcHeight > maxArcHeight) {
+      // Scale radius down to fit
+      radius = maxArcHeight / (1 - math.cos(clampedAngle / 2));
+    }
+
+    // Arc center is below the horizon for an upward-bulging arc
+    // Distance from chord to center = R * cos(θ/2)
+    final horizonYPos = size.height - horizonY;
+    final centerY = horizonYPos + radius * math.cos(clampedAngle / 2);
+    final center = Offset(centerX, centerY);
+
+    // The arc starts at the LEFT horizon point
+    // In canvas coords (Y down), angle to left point = 3π/2 - θ/2
+    // The arc sweeps clockwise (positive) through angle θ to reach right point
+    final startAngle = (3 * math.pi / 2) - (clampedAngle / 2);
+
+    final arcRect = Rect.fromCenter(
+      center: center,
+      width: radius * 2,
+      height: radius * 2,
+    );
+
+    // Draw arc background with day gradient
+    final arcPaint = Paint()
+      ..style = PaintingStyle.stroke
+      ..strokeWidth = 6
+      ..strokeCap = StrokeCap.round
+      ..shader = SweepGradient(
+        center: Alignment.center,
+        startAngle: 0,
+        endAngle: 2 * math.pi,
+        colors: [
+          _dawnOrange.withValues(alpha: 0.6),
+          _sunriseOrange.withValues(alpha: 0.7),
+          _dayYellow.withValues(alpha: 0.8),
+          _dayGold.withValues(alpha: 0.8),
+          _dayYellow.withValues(alpha: 0.7),
+          _duskOrange.withValues(alpha: 0.6),
+        ],
+        stops: const [0.0, 0.15, 0.4, 0.6, 0.85, 1.0],
+        transform: GradientRotation(startAngle),
+      ).createShader(arcRect);
+
+    // Draw the arc (positive sweep = clockwise in canvas coords = visually upward arc)
+    canvas.drawArc(arcRect, startAngle, clampedAngle, false, arcPaint);
+
+    // Calculate sun position along the arc
+    final totalDaylight = sunset.difference(sunrise).inMinutes;
+    final minutesSinceSunrise = now.difference(sunrise).inMinutes;
+    final progress = (minutesSinceSunrise / totalDaylight).clamp(0.0, 1.0);
+
+    // Map progress to angle along the arc (0 = sunrise/left, 1 = sunset/right)
+    final sunAngle = startAngle + (progress * clampedAngle);
+    final sunX = center.dx + radius * math.cos(sunAngle);
+    final sunY = center.dy + radius * math.sin(sunAngle);
+
+    // Determine sun color based on position (orange near horizon, yellow at peak)
+    final isNearHorizon = progress < 0.15 || progress > 0.85;
+    final sunColor = isNearHorizon ? _sunriseOrange : _dayYellow;
+    final glowColor = isNearHorizon ? _dawnOrange : _dayYellow;
+
+    // Draw sun glow
+    final glowPaint = Paint()
+      ..shader = RadialGradient(
+        colors: [
+          glowColor.withValues(alpha: 0.6),
+          glowColor.withValues(alpha: 0.0),
+        ],
+      ).createShader(Rect.fromCircle(center: Offset(sunX, sunY), radius: 20));
+    canvas.drawCircle(Offset(sunX, sunY), 20, glowPaint);
+
+    // Draw sun
+    final sunPaint = Paint()
+      ..style = PaintingStyle.fill
+      ..color = sunColor;
+    canvas.drawCircle(Offset(sunX, sunY), 10, sunPaint);
+
+    // Draw sun rays
+    final rayPaint = Paint()
+      ..style = PaintingStyle.stroke
+      ..strokeWidth = 2
+      ..color = (isNearHorizon ? _dawnOrange : _dayGold).withValues(alpha: 0.8);
+
+    for (var i = 0; i < 8; i++) {
+      final rayAngle = (i * math.pi / 4);
+      canvas.drawLine(
+        Offset(sunX + 12 * math.cos(rayAngle), sunY + 12 * math.sin(rayAngle)),
+        Offset(sunX + 16 * math.cos(rayAngle), sunY + 16 * math.sin(rayAngle)),
+        rayPaint,
+      );
+    }
+  }
+
+  void _drawNightArc(
+    Canvas canvas,
+    Size size,
+    double centerX,
+    double horizonWidth,
+    double horizonY,
+    double arcAngle,
+    DateTime now,
+    DateTime sunrise,
+    DateTime sunset,
+  ) {
+    // Clamp arc angle between 30° and 180° for visual sanity
+    final clampedAngle = arcAngle.clamp(math.pi / 6, math.pi);
+
+    // Calculate radius so arc endpoints touch horizon
+    var radius = horizonWidth / (2 * math.sin(clampedAngle / 2));
+
+    // Constrain arc height to fit within available space (leave 20px margin for moon)
+    final maxArcHeight = size.height - horizonY - 20;
+    final arcHeight = radius * (1 - math.cos(clampedAngle / 2));
+    if (arcHeight > maxArcHeight) {
+      // Scale radius down to fit
+      radius = maxArcHeight / (1 - math.cos(clampedAngle / 2));
+    }
+
+    // Arc center is below the horizon for an upward-bulging arc
+    final horizonYPos = size.height - horizonY;
+    final centerY = horizonYPos + radius * math.cos(clampedAngle / 2);
+    final center = Offset(centerX, centerY);
+
+    // The arc starts at the LEFT horizon point
+    // In canvas coords (Y down), angle to left point = 3π/2 - θ/2
+    final startAngle = (3 * math.pi / 2) - (clampedAngle / 2);
+
+    final arcRect = Rect.fromCenter(
+      center: center,
+      width: radius * 2,
+      height: radius * 2,
+    );
+
+    // Draw arc background with night gradient
+    final arcPaint = Paint()
+      ..style = PaintingStyle.stroke
+      ..strokeWidth = 6
+      ..strokeCap = StrokeCap.round
+      ..shader = SweepGradient(
+        center: Alignment.center,
+        startAngle: 0,
+        endAngle: 2 * math.pi,
+        colors: [
+          _duskOrange.withValues(alpha: 0.4),
+          _nightIndigo.withValues(alpha: 0.5),
+          _nightBlue.withValues(alpha: 0.6),
+          _nightBlue.withValues(alpha: 0.6),
+          _nightIndigo.withValues(alpha: 0.5),
+          _dawnOrange.withValues(alpha: 0.4),
+        ],
+        stops: const [0.0, 0.15, 0.4, 0.6, 0.85, 1.0],
+        transform: GradientRotation(startAngle),
+      ).createShader(arcRect);
+
+    // Draw the arc (positive sweep = clockwise in canvas coords)
+    canvas.drawArc(arcRect, startAngle, clampedAngle, false, arcPaint);
+
+    // Calculate moon position
+    // Night spans from sunset to next sunrise
+    final double progress;
+    if (now.isAfter(sunset)) {
+      // After sunset: progress from sunset toward midnight and beyond
+      final nextSunrise = DateTime(now.year, now.month, now.day + 1, sunrise.hour, sunrise.minute);
+      final nightDuration = nextSunrise.difference(sunset).inMinutes;
+      final minutesSinceSunset = now.difference(sunset).inMinutes;
+      progress = (minutesSinceSunset / nightDuration).clamp(0.0, 1.0);
+    } else {
+      // Before sunrise: progress toward sunrise
+      final prevSunset = DateTime(now.year, now.month, now.day - 1, sunset.hour, sunset.minute);
+      final nightDuration = sunrise.difference(prevSunset).inMinutes;
+      final minutesSincePrevSunset = now.difference(prevSunset).inMinutes;
+      progress = (minutesSincePrevSunset / nightDuration).clamp(0.0, 1.0);
+    }
+
+    // Map progress to angle along the arc (0 = sunset/left, 1 = sunrise/right)
+    final moonAngle = startAngle + (progress * clampedAngle);
+    final moonX = center.dx + radius * math.cos(moonAngle);
+    final moonY = center.dy + radius * math.sin(moonAngle);
+
+    // Draw moon glow
+    final glowPaint = Paint()
+      ..shader = RadialGradient(
+        colors: [
+          _moonSilver.withValues(alpha: 0.3),
+          _moonSilver.withValues(alpha: 0.0),
+        ],
+      ).createShader(Rect.fromCircle(center: Offset(moonX, moonY), radius: 16));
+    canvas.drawCircle(Offset(moonX, moonY), 16, glowPaint);
+
+    // Draw moon
+    final moonPaint = Paint()
+      ..style = PaintingStyle.fill
+      ..color = _moonSilver;
+    canvas.drawCircle(Offset(moonX, moonY), 8, moonPaint);
+
+    // Draw crescent shadow for moon effect
+    final shadowPaint = Paint()
+      ..style = PaintingStyle.fill
+      ..color = _nightBlue.withValues(alpha: 0.7);
+    canvas.drawCircle(Offset(moonX + 3, moonY - 1), 6, shadowPaint);
+  }
+
+  @override
+  bool shouldRepaint(covariant _SunArcPainter oldDelegate) {
+    return oldDelegate.sunTimes != sunTimes || oldDelegate.isDark != isDark;
+  }
+}
@@ -0,0 +1,407 @@
+import 'package:flutter/material.dart';
+import 'package:tatlock_ui/features/front_hall/data/models/environment_model.dart'
+    as api;
+
+/// Weather widget displaying current conditions.
+///
+/// Displays weather data from the Core API environment endpoint.
+class WeatherWidget extends StatelessWidget {
+  const WeatherWidget({
+    super.key,
+    this.apiData,
+    this.data,
+    this.compact = false,
+  });
+
+  /// Weather data from API. Takes priority over legacy data.
+  final api.WeatherData? apiData;
+
+  /// Legacy weather data to display. Uses mock data if null.
+  final WeatherData? data;
+
+  /// Whether to use compact layout.
+  final bool compact;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    // Show "no data" state when no API data and no legacy data
+    if (apiData == null && data == null) {
+      if (compact) {
+        return _buildCompactNoData(context, colorScheme);
+      }
+      return _buildNoData(context, colorScheme);
+    }
+
+    // Convert API data to local model, or use legacy data
+    final weather = apiData != null ? _fromApiData(apiData!) : data!;
+
+    if (compact) {
+      return _buildCompact(context, colorScheme, weather);
+    }
+
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Header
+            Row(
+              children: [
+                Icon(
+                  Icons.wb_sunny_outlined,
+                  size: 20,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 8),
+                Expanded(
+                  child: Text(
+                    weather.location,
+                    style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 16),
+
+            // Main weather display (matching AQI layout)
+            Row(
+              children: [
+                // Weather icon in box (like AQI number box)
+                Container(
+                  width: 64,
+                  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: 16),
+
+                // Temperature and condition
+                Expanded(
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      Text(
+                        '${weather.temperature.round()}°${weather.unit.symbol}',
+                        style:
+                            Theme.of(context).textTheme.titleMedium?.copyWith(
+                                  fontWeight: FontWeight.w600,
+                                ),
+                      ),
+                      const SizedBox(height: 4),
+                      Text(
+                        weather.condition,
+                        style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                              color: colorScheme.onSurfaceVariant,
+                            ),
+                        maxLines: 2,
+                        overflow: TextOverflow.ellipsis,
+                      ),
+                    ],
+                  ),
+                ),
+              ],
+            ),
+
+            // Details
+            if (weather.humidity != null || weather.windSpeed != null) ...[
+              const SizedBox(height: 16),
+              const Divider(height: 1),
+              const SizedBox(height: 12),
+              Wrap(
+                spacing: 16,
+                runSpacing: 8,
+                children: [
+                  if (weather.humidity != null)
+                    _DetailChip(
+                      label: 'Humidity',
+                      value: '${weather.humidity}%',
+                    ),
+                  if (weather.windSpeed != null)
+                    _DetailChip(
+                      label: 'Wind',
+                      value: '${weather.windSpeed!.round()} ${weather.windUnit}',
+                    ),
+                  if (weather.feelsLike != null)
+                    _DetailChip(
+                      label: 'Feels',
+                      value: '${weather.feelsLike!.round()}°${weather.unit.symbol}',
+                    ),
+                ],
+              ),
+            ],
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildCompact(
+    BuildContext context,
+    ColorScheme colorScheme,
+    WeatherData weather,
+  ) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(
+              weather.icon,
+              size: 24,
+              color: weather.iconColor ?? colorScheme.primary,
+            ),
+            const SizedBox(width: 8),
+            Text(
+              '${weather.temperature.round()}°${weather.unit.symbol}',
+              style: Theme.of(context).textTheme.titleMedium?.copyWith(
+                    fontWeight: FontWeight.bold,
+                  ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildNoData(BuildContext context, ColorScheme colorScheme) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Header
+            Row(
+              children: [
+                Icon(
+                  Icons.wb_sunny_outlined,
+                  size: 20,
+                  color: colorScheme.onSurfaceVariant,
+                ),
+                const SizedBox(width: 8),
+                Text(
+                  'Weather',
+                  style: Theme.of(context).textTheme.titleSmall?.copyWith(
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+                ),
+              ],
+            ),
+            const SizedBox(height: 8),
+            // Match sun position card height (170px content area)
+            SizedBox(
+              height: 170,
+              child: Center(
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    Icon(
+                      Icons.cloud_off_outlined,
+                      size: 32,
+                      color: colorScheme.outline,
+                    ),
+                    const SizedBox(height: 8),
+                    Text(
+                      'No data available',
+                      style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                            color: colorScheme.outline,
+                          ),
+                    ),
+                  ],
+                ),
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildCompactNoData(BuildContext context, ColorScheme colorScheme) {
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+        child: Row(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Icon(
+              Icons.cloud_off_outlined,
+              size: 24,
+              color: colorScheme.outline,
+            ),
+            const SizedBox(width: 8),
+            Text(
+              '--',
+              style: Theme.of(context).textTheme.titleMedium?.copyWith(
+                    color: colorScheme.outline,
+                  ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _DetailChip extends StatelessWidget {
+  const _DetailChip({
+    required this.label,
+    required this.value,
+  });
+
+  final String label;
+  final String value;
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Row(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Text(
+          label,
+          style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                color: colorScheme.outline,
+              ),
+        ),
+        const SizedBox(width: 4),
+        Text(
+          value,
+          style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                fontWeight: FontWeight.w500,
+              ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Converts API weather data to local WeatherData model.
+WeatherData _fromApiData(api.WeatherData data) {
+  return WeatherData(
+    location: data.location ?? 'Unknown',
+    temperature: data.temperature ?? 0,
+    condition: data.conditions ?? 'Unknown',
+    icon: _getWeatherIcon(data.conditions, data.icon),
+    humidity: data.humidity,
+    windSpeed: data.windSpeed,
+    feelsLike: data.feelsLike,
+    iconColor: _getWeatherColor(data.conditions),
+  );
+}
+
+/// Maps weather condition to icon.
+IconData _getWeatherIcon(String? conditions, String? iconCode) {
+  final condition = conditions?.toLowerCase() ?? '';
+
+  if (condition.contains('clear') || condition.contains('sunny')) {
+    return Icons.wb_sunny;
+  } else if (condition.contains('cloud') || condition.contains('overcast')) {
+    return Icons.cloud;
+  } else if (condition.contains('rain') || condition.contains('drizzle')) {
+    return Icons.grain;
+  } else if (condition.contains('storm') || condition.contains('thunder')) {
+    return Icons.thunderstorm;
+  } else if (condition.contains('snow') || condition.contains('sleet')) {
+    return Icons.ac_unit;
+  } else if (condition.contains('fog') || condition.contains('mist')) {
+    return Icons.blur_on;
+  } else if (condition.contains('wind')) {
+    return Icons.air;
+  }
+  return Icons.cloud;
+}
+
+/// Maps weather condition to color.
+Color? _getWeatherColor(String? conditions) {
+  final condition = conditions?.toLowerCase() ?? '';
+
+  if (condition.contains('clear') || condition.contains('sunny')) {
+    return Colors.amber;
+  } else if (condition.contains('cloud')) {
+    return Colors.blueGrey;
+  } else if (condition.contains('rain')) {
+    return Colors.blue;
+  } else if (condition.contains('storm')) {
+    return Colors.deepPurple;
+  } else if (condition.contains('snow')) {
+    return Colors.lightBlue;
+  }
+  return null;
+}
+
+/// Temperature unit for weather display.
+enum TemperatureUnit {
+  celsius('C'),
+  fahrenheit('F');
+
+  const TemperatureUnit(this.symbol);
+  final String symbol;
+}
+
+/// Weather data model.
+class WeatherData {
+  const WeatherData({
+    required this.location,
+    required this.temperature,
+    required this.condition,
+    required this.icon,
+    this.unit = TemperatureUnit.celsius,
+    this.humidity,
+    this.windSpeed,
+    this.windUnit = 'km/h',
+    this.feelsLike,
+    this.iconColor,
+  });
+
+  final String location;
+  final double temperature;
+  final String condition;
+  final IconData icon;
+  final TemperatureUnit unit;
+  final int? humidity;
+  final double? windSpeed;
+  final String windUnit;
+  final double? feelsLike;
+  final Color? iconColor;
+
+  /// Mock weather data for development.
+  factory WeatherData.mock() {
+    return const WeatherData(
+      location: 'Rotterdam, NL',
+      temperature: 8,
+      condition: 'Partly Cloudy',
+      icon: Icons.cloud,
+      humidity: 72,
+      windSpeed: 18,
+      feelsLike: 5,
+      iconColor: Colors.blueGrey,
+    );
+  }
+}
@@ -0,0 +1,7 @@
+/// Shared widgets for Tatlock UI.
+library;
+
+export 'air_quality_widget.dart';
+export 'gauge_widget.dart';
+export 'icon_picker.dart';
+export 'weather_widget.dart';
@@ -1,13 +0,0 @@
-// GENERATED FILE - DO NOT EDIT
-// Generated by build_runner from pubspec.yaml
-
-/// Application version information from pubspec.yaml
-class AppVersion {
-  AppVersion._();
-
-  static const String name = 'tatlock_ui';
-  static const String description = 'Tatlock - a Home Lab AI';
-  static const String version = '0.3.0';
-  static const int buildNumber = 1;
-  static const String fullVersion = '0.3.0+1';
-}
@@ -0,0 +1,53 @@
+# Increase buffer size for large headers from Authentik
+proxy_buffers 8 16k;
+proxy_buffer_size 32k;
+
+# Exclude static assets from forward auth
+# These paths bypass auth_request but still proxy to upstream
+location ~ ^/(manifest\.json|favicon\.(ico|png)|health|icons|assets) {
+    auth_request off;
+    proxy_pass $forward_scheme://$server:$port;
+}
+
+# Forward authentication via standalone outpost
+auth_request /outpost.goauthentik.io/auth/nginx;
+error_page 401 = @goauthentik_proxy_signin;
+
+# Capture auth response headers
+auth_request_set $auth_cookie $upstream_http_set_cookie;
+auth_request_set $authentik_username $upstream_http_x_authentik_username;
+auth_request_set $authentik_groups $upstream_http_x_authentik_groups;
+auth_request_set $authentik_email $upstream_http_x_authentik_email;
+auth_request_set $authentik_name $upstream_http_x_authentik_name;
+auth_request_set $authentik_uid $upstream_http_x_authentik_uid;
+
+# Forward auth headers to application
+add_header Set-Cookie $auth_cookie;
+proxy_set_header X-authentik-username $authentik_username;
+proxy_set_header X-authentik-groups $authentik_groups;
+proxy_set_header X-authentik-email $authentik_email;
+proxy_set_header X-authentik-name $authentik_name;
+proxy_set_header X-authentik-uid $authentik_uid;
+
+# Outpost proxy location
+location /outpost.goauthentik.io {
+    proxy_pass https://localhost:9444/outpost.goauthentik.io;
+    proxy_set_header Host $host;
+    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $http_host;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+
+    # WebSocket support
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+}
+
+# Signin redirect handler
+location @goauthentik_proxy_signin {
+    internal;
+    return 302 /outpost.goauthentik.io/start?rd=$request_uri;
+}
@@ -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.2+1
+version: 1.5.6+1

 environment:
  sdk: ^3.10.4
@@ -30,6 +30,8 @@ environment:
 dependencies:
  flutter:
    sdk: flutter
+  flutter_web_plugins:
+    sdk: flutter

  # State Management
  flutter_riverpod: ^3.0.0
@@ -50,6 +52,14 @@ dependencies:
  # Storage
  shared_preferences: ^2.3.3

+  # Authentication (OIDC/OAuth2)
+  flutter_appauth: ^8.0.0
+  crypto: ^3.0.3
+  web: ^1.1.0
+
+  # Internationalization
+  intl: ^0.19.0
+
  # UI
  flex_color_scheme: ^8.1.0
  flutter_adaptive_scaffold: ^0.3.1
@@ -64,6 +74,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:
@@ -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)));
+      });
+    });
+  });
+}
@@ -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);
+    });
+  });
+}
@@ -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);
+      });
+    });
+  });
+}
--- a/Show More
+++ b/Show More