Add user preferences and persistence for overlays.

PR Details:
- Enables saving and restoring overlay configuration
- Supports personalization across sessions

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,9 +2,9 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement adaptive UI behavior for overlays:
-- Add rule system for adaptive UI (visibility, size, emphasis)
-- React to gameplay + overlay context + telemetry
-- Respect layout constraints and safe zones
-- Do not modify existing rendering pipeline unnecessarily
+Implement overlay user preferences and persistence:
+- Store preferences (visibility, layout, keybind profile)
+- Restore preferences on runtime load
+- Ensure compatibility with adaptive UI and contextual input
+- Use lightweight storage (local or existing state system)
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,5 @@
-Add adaptive UI behavior to overlay system.
+Add user preferences and persistence for overlays.
 
 PR Details:
-- Introduces runtime adaptive UI rules
-- Enhances responsiveness of overlays
+- Enables saving and restoring overlay configuration
+- Supports personalization across sessions

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,5 @@
-[ ] UI adapts to gameplay state
-[ ] No layout conflicts
-[ ] Stable rendering
+[ ] Preferences save correctly
+[ ] Preferences restore correctly
+[ ] No regression in behavior
+[ ] Compatible with adaptive UI
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -638,6 +638,7 @@
 - [x] Level 22 gesture abstraction added for overlays (tap/hold/swipe mapped to runtime actions with explicit gameplay-safe gating)
 - [x] Level 22 contextual input mapping added (active overlay/layer stack-aware resolution across keybind and gesture actions)
 - [x] Level 22 adaptive overlay UI rules added (visibility/size/emphasis responsive to gameplay state, overlay context, and telemetry)
+- [x] Level 22 overlay preferences persistence added (visibility, layout overrides, and keybind profile restored on runtime load)
 
 ### Sample Phase Tracks
 - [x] 3D phase normalized

docs/pr/BUILD_PR.md

@@ -1,21 +1,21 @@
-# BUILD_PR_LEVEL_22_4_OVERLAY_ADAPTIVE_UI_BEHAVIOR
+# BUILD_PR_LEVEL_22_5_OVERLAY_USER_PREFERENCES_AND_PERSISTENCE
 
 ## Purpose
-Enable overlays to adapt their UI behavior dynamically based on runtime conditions.
+Persist user preferences for overlay behavior and customization.
 
 ## Roadmap Improvement
-Extends Level 22 into adaptive UI systems layered on contextual input.
+Completes Level 22 by adding persistence and personalization.
 
 ## Scope
-- Define adaptive UI rules (visibility, size, emphasis)
-- React to gameplay state, overlay stack, and telemetry
-- Avoid conflicts with layout constraints and safe zones
+- Store user preferences (visibility, layout, keybind profile)
+- Restore preferences on load
+- Ensure compatibility with adaptive UI and contextual input systems
 
 ## Test Steps
-1. Trigger different gameplay states
-2. Verify UI adapts (size/visibility/emphasis)
-3. Confirm no layout violations
+1. Modify overlay preferences
+2. Reload runtime
+3. Verify preferences persist
 
 ## Expected
-- UI responds dynamically to context
-- No overlap or instability
+- Preferences saved and restored
+- No regression in overlay behavior