docs: update notes

docs/00 INBOX/ai/hyprland-lua-migration-plan.md

@@ -0,0 +1,102 @@
+# Hyprland Lua Migration Plan
+
+## Problem Statement
+
+The Hyprland compositor config uses Home Manager's hyprlang output.
+Hyprland deprecates hyprlang for the main compositor config.
+The repository needs to generate a Lua config without changing desktop behavior.
+
+## Solution
+
+Keep the config owned by Nix and Home Manager.
+Switch the Hyprland Home Manager config output to Lua.
+Convert only the settings whose shape changes under Lua.
+
+This is not a desktop redesign.
+The change preserves the current monitors, binds, window rules, environment variables, and UWSM startup.
+
+## User Stories
+
+1. As the operator, I want Hyprland to load `hyprland.lua`, so that startup no longer warns about hyprlang deprecation.
+
+2. As the operator, I want existing keyboard binds to keep working, so that the desktop behavior stays unchanged.
+
+3. As the operator, I want host monitor layout to stay unchanged, so that the physical display setup does not move.
+
+4. As the operator, I want session environment variables to stay in the compositor config, so that Wayland and cursor behavior stays unchanged.
+
+5. As the operator, I want auxiliary module binds to keep working, so that launcher, lock, screenshot, clipboard, notifications, and recording flows stay usable.
+
+## Implementation Decisions
+
+1. Use Home Manager's Lua config generator.
+   Set the Hyprland config type to Lua and keep package ownership unchanged.
+
+2. Keep ordinary compositor options declarative in Nix.
+   Move input, general, decoration, xwayland, animation, and layout settings into the Lua config structure.
+
+3. Remove hyprlang-only variables from generated config.
+   Keep modifier and terminal values as Nix locals or helper inputs.
+
+4. Add minimal local helpers for Lua calls.
+   Use helpers only for repeated bind, dispatcher, command, environment, and rule shapes.
+
+5. Convert all bind strings to Lua bind call data.
+   Preserve key combinations, dispatchers, commands, repeat behavior, and locked-session behavior.
+
+6. Convert contributed binds in their owning modules.
+   Keep each bind near the module that owns the tool it launches.
+
+7. Convert monitor strings to Lua monitor records.
+   Preserve output names, modes, positions, scale values, and rotation.
+
+8. Convert the screenshot window rule to the Lua rule shape.
+   Preserve the Satty class matcher and floating behavior.
+
+9. Convert environment strings to Lua environment calls.
+   Preserve the Wayland flag and cursor variables.
+
+10. Delete or update comments that describe hyprlang syntax.
+    Keep comments that explain behavior or non-obvious invariants.
+
+## Testing Decisions
+
+1. Run the repository Nix formatting and style checks for modified Nix files.
+
+2. Evaluate or build the affected host configuration.
+   This proves Home Manager accepts the Lua settings structure.
+
+3. Confirm the generated config file uses Lua.
+   The expected output is `hyprland.lua`, not `hyprland.conf`.
+
+4. Verify Hyprland accepts the generated Lua config.
+   Use Hyprland config verification when the installed build supports it.
+   Otherwise reload the compositor and inspect errors.
+
+5. Smoke test the changed desktop surface.
+   Test one bind from each source area after reload.
+
+6. Check the explicit monitor layout on the host that declares it.
+   Confirm resolution, position, scale, and rotation stayed unchanged.
+
+## Out of Scope
+
+- Do not split the config into Lua modules.
+- Do not hand-write a full Lua config.
+- Do not add new Hyprland behavior.
+- Do not change UWSM startup.
+- Do not redesign binds, monitor layout, or visual settings.
+- Do not change hyprlock, hypridle, waybar, mako, or rofi settings beyond their Hyprland binds.
+
+## Further Notes
+
+Home Manager documents `configType = "lua"` for Hyprland.
+It maps settings to `hl.*` calls.
+It supports `_args` for multi-argument calls.
+It supports raw Lua expressions with `lib.generators.mkLuaInline`.
+
+The riskiest parts are binds, monitor declarations, and window rules.
+Those parts changed shape more than scalar config sections.
+
+Assumption: the pinned Home Manager input contains the documented Lua Hyprland generator.
+Validate this during the configuration build.