nix-config/docs/uwsm-migration-summary.md

# UWSM Migration Complete ✅

## Summary

The Niri desktop environment has been **fully migrated** to UWSM (Universal Wayland Session Manager) for comprehensive systemd-based session management.

## What Changed

### 1. Session Launch (Host-Level)

**Before:**
- Manual desktop entry files in `/etc/wayland-sessions/`
- Manual UWSM package installation

**After:**
```nix
programs.uwsm = {
  enable = true;
  waylandCompositors.niri = {
    prettyName = "Niri";
    comment = "Niri scrollable-tiling Wayland compositor managed by UWSM";
    binPath = "/run/current-system/sw/bin/niri-session";
  };
};
```

### 2. Startup Applications (Home-Manager)

**Before:** Using `programs.niri.settings.spawn-at-startup`

**After:** Using `systemd.user.services` with proper targets

| Service | Type | Purpose |
|---------|------|---------|
| `nm-applet` | simple | Network manager tray icon |
| `zenbook-autostart` | oneshot | Initial display setup |
| `zenbook-delayed-setup` | oneshot | Secondary setup after delay |
| `zenbook-inotify-monitor` | simple | DRM status change monitor |
| `zenbook-udev-monitor` | simple | udev event monitor |

All services:
- `PartOf = ["graphical-session.target"]` - proper lifecycle
- `After = ["graphical-session.target"]` - correct ordering  
- `WantedBy = ["graphical-session.target"]` - auto-start
- `Restart` policies for resilience

### 3. Application Launches (Keybinds)

**Before:** Direct binary execution
```nix
programs.niri.settings.binds."Mod+Return".action.spawn = ["${pkgs.fuzzel}/bin/fuzzel"];
```

**After:** UWSM app wrapper
```nix
programs.niri.settings.binds."Mod+Return".action.spawn = ["uwsm" "app" "--" "${pkgs.fuzzel}/bin/fuzzel"];
```

All keybinds now use `uwsm app --`:
- `Mod+Return` → fuzzel launcher
- `Mod+L` → swaylock
- `Mod+Z` → zenbook-set-displays

### 4. Fuzzel Launcher Configuration

Fuzzel now has `launch-prefix` configured:
```nix
settings.main.launch-prefix = "uwsm app -- ";
```

This means apps launched from fuzzel are automatically placed in the correct systemd slice.

## Benefits Achieved

1. **✅ Environment Variable Inheritance**
   - Login shell → PAM → systemd → compositor → applications
   - All environment properly propagated

2. **✅ Systemd Integration**
   - All services bound to `graphical-session.target`
   - Proper dependency ordering and lifecycle management

3. **✅ Application Slicing**
   - Apps launched via `uwsm app --` go into `app-graphical.slice`
   - Better resource management and isolation

4. **✅ Clean Shutdown**
   - Proper cleanup when session ends
   - Services stopped in correct order

5. **✅ Resilience**
   - Services auto-restart on failure
   - Configurable restart policies

6. **✅ Standards Compliance**
   - Follows systemd graphical session standards
   - Compatible with XDG autostart (if needed)

## How to Use

### From Display Manager

Select **"Niri"** from your display manager (GDM, SDDM, etc.)

The session is now automatically launched via UWSM with full session management.

### From TTY

```bash
# Launch via UWSM
uwsm start niri
```

### Verify UWSM is Active

```bash
# Check UWSM status
uwsm status

# List UWSM-managed units
systemctl --user list-units 'wayland-*'

# Check graphical session services
systemctl --user list-units --type=service | grep graphical
```

## Monitoring

```bash
# Check specific service
systemctl --user status nm-applet

# View logs
journalctl --user -u zenbook-inotify-monitor -f

# List all services in graphical session
systemctl --user list-dependencies graphical-session.target
```

## Files Modified

| File | Changes |
|------|---------|
| `hosts/common/optional/niri.nix` | Added `programs.uwsm` module |
| `home/.../niri/waybar.nix` | nm-applet → systemd service |
| `home/.../niri/zenbook-screen.nix` | All tools → systemd services, keybind uses `uwsm app` |
| `home/.../niri/fuzzel.nix` | Keybind + launch-prefix use `uwsm app` |
| `home/.../niri/swaylock.nix` | Keybind uses `uwsm app` |
| `docs/uwsm-niri-integration.md` | Updated documentation |

## Testing

After rebuilding:

1. Log out and select "Niri" from display manager
2. Log in and verify all components work:
   - Waybar appears with tray icons
   - nm-applet icon visible in tray
   - `Mod+Return` opens fuzzel
   - `Mod+L` locks screen
   - Zenbook displays configured correctly

3. Check systemd services:
   ```bash
   systemctl --user status nm-applet waybar zenbook-autostart
   ```

4. Launch an app from fuzzel and verify it's in the right slice:
   ```bash
   systemctl --user list-units --type=service | grep app-
   ```

## Documentation

See `docs/uwsm-niri-integration.md` for:
- Detailed UWSM concepts
- Troubleshooting guide
- Advanced configuration options
- Environment variable management

## References

- [UWSM GitHub](https://github.com/vladimir-csp/uwsm)
- [NixOS UWSM Module](https://mynixos.com/nixpkgs/options/programs.uwsm)
- [UWSM Documentation](https://github.com/vladimir-csp/uwsm/blob/master/README.md)