# Troubleshooting Guide

This guide contains troubleshooting commands and procedures for common issues
on the Gentoo ThinkPad system.

## Bluetooth Issues

### Check Bluetooth Status

```bash
# Check controller
bluetoothctl list

# Check modules
lsmod | grep bt

# Check service
rc-service bluetooth status

# Check kernel messages
dmesg | grep -i bluetooth
```

### Full Troubleshooting Guide

See `Bluetooth-Setup.md` for complete Bluetooth setup, troubleshooting, and
technical details.

## Power Management Issues

### Check Power Profile Status

```bash
# Check logs
tail -50 /var/log/power-profile.log

# Check current state
cat /sys/class/power_supply/AC/online  # 1 = AC, 0 = battery
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# Manual profile test
sudo /usr/local/bin/power-profile-ac      # Performance mode
sudo /usr/local/bin/power-profile-battery # Power saving mode
```

### Full Troubleshooting Guide

See `Power-Management-Setup.md` for complete details and advanced
configuration.

## WiFi Issues

### Check WiFi Status

```bash
# Check status
wifi-setup status

# Check waybar integration
emerge -pv gui-apps/waybar | grep network

# Check network interface
ip link show wlp194s0

# Check NetworkManager
nmcli device status
```

### Full Troubleshooting Guide

See `scripts/wifi-setup/README.md` for complete setup instructions, usage
examples, and troubleshooting.

## Audio Issues

### Check Audio Status

```bash
# Check status
audio-setup status

# List devices
audio-setup list-outputs
audio-setup list-inputs

# Check PulseAudio
pactl info

# Check ALSA
aplay -l  # List playback devices
arecord -l  # List recording devices
```

### Full Troubleshooting Guide

See `scripts/audio-setup/README.md` for complete setup instructions, usage
examples, and troubleshooting.

## Monitor/Lid Issues

### Check Monitor Configuration

```bash
# Check logs
cat /tmp/lid-handler.log

# Check monitor configuration
monitor-setup status
hyprctl monitors

# Check ACPI events
acpi_listen  # Run this, then open/close lid to see events

# Check elogind
loginctl show-session $XDG_SESSION_ID

# Check Hyprland monitor script
/home/alexander/.config/hypr/scripts/monitor-setup.sh
```

### Full Troubleshooting Guides

- `Lid-Automation-Working-Solution.md` - Lid automation implementation
- `Fix-DisplayLink-Artifacts.md` - DisplayLink optimization guide

## Monitor Management Issues

### Interactive Monitor Commands

```bash
# Check current layout
monitor-setup status

# List all monitors
monitor-setup list

# Swap if order is wrong
sudo monitor-setup swap

# Reset to auto-detection
sudo monitor-setup reset
```

### Full Troubleshooting Guide

See `scripts/monitor-setup/README.md` for complete setup instructions, usage
examples, and troubleshooting.

## Battery Conservation Issues

### Check Battery Thresholds

```bash
# Check current thresholds
battery-setup status

# Check if thresholds are supported
ls /sys/class/power_supply/BAT*/charge_control_*_threshold

# Check OpenRC service
rc-service battery-thresholds status

# Manually set thresholds
sudo battery-setup conservation

# Check battery health
cat /sys/class/power_supply/BAT0/capacity
cat /sys/class/power_supply/BAT0/cycle_count
cat /sys/class/power_supply/BAT0/status

# Check ThinkPad ACPI module
lsmod | grep thinkpad_acpi
```

### Full Troubleshooting Guide

See `scripts/battery-setup/README.md` for complete setup instructions, battery
science, and troubleshooting.

## Backup Issues

### Check Backup Status

```bash
# Check backup status
backup-setup status

# Check if NAS is reachable
ping -c 3 192.168.2.171
ssh alexander@192.168.2.171 "echo test"

# Check network trigger logs
tail -20 ~/.local/var/log/backup-monitor.log

# Check backup logs
tail -50 ~/.local/var/log/backup.log

# Check for active backups
ls -la /tmp/backup-*.lock

# Remove stale lock files (if older than 6 hours)
rm /tmp/backup-*.lock

# Check backup service
sudo rc-service backup-monitor status
```

### Manual Backup Commands

```bash
# Run manual backup
backup-setup full     # Full system backup
backup-setup home     # Home directory only
backup-setup configs  # Configuration files only
backup-setup incremental  # Incremental backup

# Check last backup time
cat ~/.local/var/backup/last-backup
```

### Full Troubleshooting Guide

See `Backup-Setup.md` for complete backup guide - Automated NAS backups,
network trigger, troubleshooting.

## Firewall Issues

### Check Firewall Status

```bash
# Check firewall status
sudo rc-service nftables status

# View firewall rules
sudo nft list ruleset

# Test connectivity
ping -c 3 8.8.8.8  # Internet connectivity
ping -c 3 192.168.2.171  # NAS connectivity

# Check if port is blocked
sudo nft list ruleset | grep <port_number>

# Restart firewall
sudo rc-service nftables restart

# Test specific service
telnet <host> <port>
```

### Full Troubleshooting Guide

See `Security-Hardening.md` for complete security guide - Firewall, fail2ban,
SSH hardening, monitoring.

## Ghostty Terminal Issues

### Check Ghostty Status

```bash
# Test if Ghostty works
ghostty

# Check if it's pure Wayland (should show nothing)
ldd /usr/bin/ghostty | grep -i x11

# Check Hyprland keybinding
grep ghostty ~/.config/hypr/hyprland.conf

# Check Ghostty config
cat ~/.config/ghostty/config

# Run Ghostty with debug output
ghostty --verbose
```

### Ghostty Configuration

**Location**: `~/.config/ghostty/config`

**Package Configuration**: See `CLAUDE.md` section "Ghostty Terminal Emulator"
for complete USE flags and build configuration.

## Neovim/LSP Issues

### Check LSP Status

```bash
# Check LSP servers are working
nvim  # Open Neovim
:LspInfo  # Check LSP status

# Check for LSP errors
:messages

# Verify new API is being used (no deprecation warnings)
# Start nvim and check for warnings about lspconfig

# Test a file with LSP support
nvim test.go  # Should show LSP features

# Check Neovim version
nvim --version  # Should be 0.11+

# Check LSP config location
ls -la ~/.config/nvim/lua/alxndrhi/plugins/lsp.lua
```

### LSP Configuration

**Location**: `~/.config/nvim/lua/alxndrhi/plugins/lsp.lua`

**API**: Uses Neovim 0.11+ native `vim.lsp.config[]` API (not deprecated
`require('lspconfig')`)

**Configured Servers**: html, cssls, gopls, clangd, jsonls, yamlls, bashls,
dockerls, vimls, lua_ls, ruff, graphql, tailwindcss, vuels, cmake

## Theme/Waybar Issues

### Check Waybar Theme

```bash
# Check waybar is using correct CSS file
# Look for: "Using CSS file /home/alexander/.config/waybar/style.css"
killall waybar && waybar 2>&1 | head -20

# Verify Nerd Font is available
fc-list | grep -i hasklug

# Test icon display in terminal
echo "CPU: 󰻠  RAM:   WiFi: 󰖩  Volume: 󰕿"

# Check if Catppuccin colors are applied
cat ~/.config/waybar/style.css | grep "#1e1e2e"  # Should show base color

# Restart waybar to apply changes
killall waybar && waybar &

# Check Hyprland colors
hyprctl clients | grep -A 5 "Window"  # Should show borders

# View Hyprland color configuration
cat ~/.config/hypr/mocha.conf
```

### Waybar Configuration Files

- `~/.config/waybar/config` - Module configuration with icon definitions
- `~/.config/waybar/style.css` - Catppuccin Mocha theme with color-coded
modules
- `~/.config/waybar/mocha.css` - Catppuccin Mocha color palette definitions

### Hyprland Theme Files

- `~/.config/hypr/hyprland.conf` - Window border colors
- `~/.config/hypr/mocha.conf` - Catppuccin Mocha color variables

## Dotfile Management (chezmoi) Issues

### Common Chezmoi Problems

```bash
# Warning about config template changed
chezmoi init

# Diff shows nothing or just "pppp"
chezmoi diff --use-builtin-diff | less

# File conflicts
chezmoi merge ~/.zshrc
# Or force overwrite:
chezmoi apply --force

# Template errors
chezmoi cat ~/.zshrc  # See rendered output
chezmoi execute-template "{{ .chezmoi.os }}"  # Test expression

# Re-run installation scripts
chezmoi state reset --bucket=scriptState
chezmoi apply

# Check configuration
chezmoi data  # View all variables
cat ~/.config/chezmoi/chezmoi.yaml

# Remove file from management
chezmoi forget ~/.file

# Complete reset (DESTRUCTIVE - removes all managed files)
chezmoi purge
```

### Chezmoi Configuration

**Source Directory**: `~/.local/share/chezmoi` (git clone of dotfiles repo)

**Dotfiles Repository**: `~/repository/git.hinrichs.dev/alexander/dotfiles`

**Config File**: `~/.config/chezmoi/chezmoi.yaml` (generated from
`.chezmoi.yaml.tmpl`)

### Full Troubleshooting Guide

See `Dotfiles-Management.md` for complete chezmoi guide - Managing dotfiles,
adding new tools, editing configs.

## Kernel Issues

### Check Kernel Configuration

```bash
# Check current kernel version
uname -r

# Extract current running config
zcat /proc/config.gz > /tmp/current-config

# Check specific kernel option
zcat /proc/config.gz | grep CONFIG_PINCTRL_AMD

# Check loaded modules
lsmod

# Check kernel messages
dmesg | less

# Check for kernel errors
dmesg | grep -i error
dmesg | grep -i fail
```

### Kernel Build Issues

**⚠️ CRITICAL**: NEVER use genkernel. Always use manual kernel compilation or
the automated build script.

**Build Script**: `scripts/build-kernel.sh`

**Saved Config**: `kernel-6.12.41-gentoo-x86_64.config`

**Build Logs**: `logs/kernel-build-TIMESTAMP.log`

### Manual Kernel Build

```bash
# Extract current running config
zcat /proc/config.gz > /usr/src/linux/.config

# Edit config as needed
cd /usr/src/linux
sudo make menuconfig

# Or use automated script
sudo ./scripts/build-kernel.sh
```

See `CLAUDE.md` section "Kernel Configuration" for complete build process.

## Touchpad/Touchscreen Issues

### Check I2C HID Devices

```bash
# Check if devices are detected
dmesg | grep -i elan

# Check if modules are loaded
lsmod | grep i2c_hid

# Check device nodes
ls -la /dev/input/by-path/ | grep i2c

# Check Hyprland input devices
hyprctl devices

# Test touchpad events
libinput debug-events
```

### Hardware Details

- **Touchpad**: ELAN901C I2C HID device (ACPI: ELAN901C:00, PNP0C50)
- **Touchscreen**: ELAN0678 I2C HID multitouch display (ACPI: ELAN0678:00,
PNP0C50)

### Required Kernel Options

- `CONFIG_I2C_HID=m`
- `CONFIG_I2C_HID_ACPI=m`
- `CONFIG_PINCTRL_AMD=y` (CRITICAL for GPIO interrupts on AMD platforms)

### Full Documentation

See `Touchpad-Touchscreen-Setup.md` and `POST-REBOOT-CHECKLIST.md`

## Webcam Issues

### Check Webcam Status

```bash
# Check if webcam is detected
lsusb | grep -i camera

# Check kernel messages
dmesg | grep -i uvc

# List video devices
ls -la /dev/video*

# Check video device capabilities (requires v4l-utils)
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --list-formats-ext

# Test capture (requires ffmpeg)
ffmpeg -f v4l2 -i /dev/video0 -frames:v 1 test.jpg

# Check user permissions
groups | grep video
```

### Hardware Details

- **Model**: Luxvisions Innotech Limited Integrated RGB Camera
- **USB ID**: 30c9:00f4
- **Resolution**: 640x480 @ 30fps (default)
- **Driver**: uvcvideo (USB Video Class)
- **Device Nodes**: /dev/video0-3

## Docker Issues

### Check Docker Status

```bash
# Check Docker service
rc-service docker status

# Check Docker version
docker --version

# Test Docker
docker run hello-world

# Check Docker logs
docker logs <container_id>

# Check Docker network
docker network ls
```

### Docker Firewall Integration

If Docker containers cannot reach the internet, check firewall rules:

```bash
# Check if Docker chain exists in nftables
sudo nft list ruleset | grep docker

# Uncomment Docker forwarding rules in /etc/nftables.conf
# Then restart:
sudo rc-service nftables restart
```

See `Security-Hardening.md` for Docker firewall integration.

## General System Troubleshooting

### Service Management (OpenRC)

```bash
# List all services
rc-status -a

# Start/stop/restart service
sudo rc-service <service> start
sudo rc-service <service> stop
sudo rc-service <service> restart

# Enable/disable service at boot
sudo rc-update add <service> default
sudo rc-update del <service> default

# Check service logs
tail -f /var/log/<service>.log
```

### System Logs

```bash
# View system messages
dmesg | less

# View recent errors
dmesg | grep -i error | tail -20

# View kernel ring buffer
journalctl -k  # If using systemd-journald

# Check OpenRC logs
ls -la /var/log/rc.log
```

### Package Management (Gentoo)

```bash
# Search for package
emerge --search <package>

# Check package info
emerge --info <package>

# List installed packages
qlist -I

# Check for config file updates
dispatch-conf

# Rebuild @world
emerge -avuDN @world
```

### Performance Monitoring

```bash
# CPU usage
top
htop

# Memory usage
free -h

# Disk usage
df -h
du -sh /*

# I/O statistics
iostat -x 2

# Network statistics
iftop
nethogs
```

## Getting Help

### Documentation Files

- `USER-GUIDE.md` - Quick reference for everyday tasks
- `System-Overview.md` - Hardware specs and software stack
- `Feature-Status.md` - Current state and working features
- `Backup-Setup.md` - Complete backup guide
- `Security-Hardening.md` - Complete security guide
- `Power-Management-Setup.md` - Power management guide
- `Bluetooth-Setup.md` - Bluetooth setup and troubleshooting
- `Dotfiles-Management.md` - Complete chezmoi guide

### Script Documentation

- `scripts/wifi-setup/README.md` - WiFi setup tool
- `scripts/bluetooth-setup/README.md` - Bluetooth setup tool
- `scripts/audio-setup/README.md` - Audio setup tool
- `scripts/monitor-setup/README.md` - Monitor setup tool
- `scripts/battery-setup/README.md` - Battery conservation tool

### Emergency Recovery

If the system becomes unbootable:

1. Boot from Gentoo LiveCD/USB
2. Mount root filesystem: `mount /dev/sdXY /mnt/gentoo`
3. Chroot: `chroot /mnt/gentoo /bin/bash`
4. Source profile: `source /etc/profile`
5. Fix issue (kernel, config, etc.)
6. Exit chroot and reboot

### Backup Restoration

If you need to restore from backup:

```bash
# List available backups on NAS
ssh alexander@192.168.2.171 "ls -la /mnt/ssd-pool-a/backups/lenovo-gentoo/"

# Restore specific backup
rsync -avz --progress \
  alexander@192.168.2.171:/mnt/ssd-pool-a/backups/lenovo-gentoo/YYYY-MM-DD/ \
  /restore-location/
```

See `Backup-Setup.md` for complete restoration procedures.