lenovo-gentoo/scripts/monitor-setup/README.md

# Monitor Setup Tool

Easy monitor management for Gentoo + Hyprland using `hyprctl`.

## Features

- 📺 Show current monitor layout and configuration
- 🔄 Swap left/right external monitor positions
- 📋 List all detected monitors with details
- 🔁 Reset to automatic configuration
- ✨ Color-coded output with visual layout representation
- ⚡ ZSH autocompletion support

## Installation

```bash
# From the scripts folder
cd scripts/monitor-setup

# Install the main script
sudo cp monitor-setup /usr/local/bin/monitor-setup
sudo chmod +x /usr/local/bin/monitor-setup

# Install ZSH autocompletion
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _monitor-setup /usr/local/share/zsh/site-functions/_monitor-setup

# Reload ZSH completions (or restart your shell)
autoload -U compinit && compinit
```

## Requirements

- `hyprctl` (comes with Hyprland)
- `jq` for JSON parsing
- Hyprland window manager running

```bash
# Install jq if not already installed
sudo emerge -av app-misc/jq
```

## Usage

### Show current monitor status
```bash
monitor-setup
# or
monitor-setup status
```

This displays:
- All active monitors
- Resolution, refresh rate, and position for each
- Visual ASCII layout representation

### List all monitors
```bash
monitor-setup list
```

Shows detailed information about each detected monitor including:
- Monitor ID and name
- Description and model
- Resolution and refresh rate
- Position and scale
- Active workspace

### Swap external monitors (Fix left/right order)
```bash
monitor-setup swap
```

Swaps the position of two external monitors. This is useful when:
- Physical monitor arrangement doesn't match logical arrangement
- After docking/undocking your laptop
- After system updates that reset monitor positions

**Requirements:** Exactly 2 external monitors must be connected

### Reset to automatic configuration
```bash
monitor-setup reset
```

Resets monitor configuration to automatic detection. This will:
- Run the automatic monitor-setup script if available (`~/.config/hypr/scripts/monitor-setup.sh`)
- Otherwise, reset all monitors to auto-detection mode

Useful after:
- Reconnecting a dock
- Monitor connection issues
- Display glitches

### Get help
```bash
monitor-setup help
```

## Common Use Cases

### Fix reversed external monitors
```bash
# Check current layout
monitor-setup

# If left/right are reversed, swap them
monitor-setup swap

# Verify the change
monitor-setup status
```

### After docking laptop
```bash
# Reset to automatic detection
monitor-setup reset

# Check the layout
monitor-setup status

# If monitors are in wrong order
monitor-setup swap
```

### Check monitor details before configuration
```bash
# List all monitors with full details
monitor-setup list
```

## ZSH Autocompletion

Once installed, ZSH will provide intelligent completions:

- Command completion: `monitor-setup <TAB>`
- Shows available commands with descriptions

## Integration with Hyprland

This tool is designed to work alongside the automatic monitor setup script at `~/.config/hypr/scripts/monitor-setup.sh`.

**Differences:**
- **Automatic script**: Runs on dock/undock events, handles lid state
- **This tool**: Manual interactive management for quick adjustments

## Troubleshooting

### "Hyprland is not running"
Make sure Hyprland is your active window manager:
```bash
pgrep -x Hyprland
```

### "hyprctl command not found"
Ensure hyprctl is in your PATH. It should be installed with Hyprland.

### "jq command not found"
Install jq for JSON parsing:
```bash
sudo emerge -av app-misc/jq
```

### Swap command says "requires exactly 2 external monitors"
The swap command only works when you have exactly 2 external monitors connected. Check with:
```bash
monitor-setup list
```

### Changes don't persist after reboot
This tool makes runtime changes to Hyprland. To make permanent changes, update your Hyprland configuration file (`~/.config/hypr/hyprland.conf`) or use the automatic setup script.

## Examples

### Quick monitor check
```bash
# Show current configuration
monitor-setup

# Output will show:
# - Number of active monitors
# - Each monitor's resolution, position, scale
# - Visual layout representation
```

### Fix monitor order issue
```bash
# Problem: Left monitor appears on right, right monitor on left
monitor-setup swap

# Monitors are now in correct order
```

### After dock reconnection
```bash
# Monitors not detected properly
monitor-setup reset

# If order is wrong after reset
monitor-setup swap
```

## Visual Layout

The tool shows a visual representation of your monitor layout:

```
Monitor Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Active Monitors: 2

  DVI-I-1:
    Resolution: 2560x1440@60Hz
    Position: 0x0
    Scale: 1.00
    Type: External Display

  DVI-I-2:
    Resolution: 2560x1440@60Hz
    Position: 2560x0
    Scale: 1.00
    Type: External Display

Layout:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ┌────────────┐  ┌────────────┐
  │ DVI-I-1    │  │ DVI-I-2    │
  └────────────┘  └────────────┘
```

## Related

- Audio Setup: See `scripts/audio-setup/` for audio device management
- WiFi Setup: See `scripts/wifi-setup/` for WiFi management
- Bluetooth Setup: See `scripts/bluetooth-setup/` for Bluetooth management

## Future Enhancements

Planned features for future versions (contributions welcome!):
- Save/load monitor layout presets
- Support for monitor rotation
- Per-monitor refresh rate adjustment
- Workspace-to-monitor assignments
- Integration with waybar for quick access