lenovo-gentoo/CLAUDE.md

# Gentoo Development Workstation Setup

## Project Overview
Setting up a Lenovo ThinkPad as a rock-solid, minimal, high-performance development environment for professional software development.

## Hardware Specs
- **Model**: Lenovo ThinkPad (14")
- **CPU**: AMD Ryzen AI 7 PRO 350 (2.0-5.0 GHz)
- **RAM**: 96GB DDR5-5600MHz (2x 48GB)
- **Storage**: 512GB NVMe PCIe 4.0 TLC Opal SSD
- **Display**: 14" 2.8K OLED (2880x1800) @ 30-120Hz VRR, HDR 500
- **WiFi**: MediaTek Wi-Fi 7 MT7925 2x2 BE + Bluetooth 5.4
- **Dock**: USB-C dock with DisplayLink
- **External Monitors**: 2x Shenzhen KTC Q3212RUC (2560x1440 @ 59.95Hz)

## Software Stack
- **OS**: Gentoo Linux (OpenRC)
- **Kernel**: 6.12.41-gentoo-x86_64 (manual compilation - genkernel NOT used)
- **Display Server**: Wayland (no X11)
- **Window Manager**: Hyprland 0.49.0 (no XWayland)
- **Status Bar**: waybar (with Catppuccin Mocha theme)
- **Terminal**: Ghostty (pure Wayland, no X11)
- **Editor**: Neovim (with LSP support)
- **File Manager**: Midnight Commander (mc)
- **Init System**: OpenRC
- **Session Manager**: elogind
- **Network Manager**: NetworkManager
- **Bluetooth**: BlueZ
- **Theme**: Catppuccin Mocha (consistent across all applications)

## Development Focus
- **Backend**: Go services
- **Frontend**: Web applications
- **Mobile**: Kotlin-based applications
- **Systems**: C programming
- **IoT**: Embedded electronics, firmware flashing

## Design Philosophy
1. **Minimal footprint** - No bloated desktop environments (GNOME/KDE)
2. **Performance first** - Slim, fast, responsive
3. **Wayland native** - Modern display protocol
4. **Single-user system** - Optimized for alexander
5. **Rock solid** - Stability and reliability over bleeding edge
6. **Development focused** - All tools optimized for professional work

## Current State (as of 2025-11-05)

### Working ✅
- ✅ Base Gentoo installation
- ✅ Hyprland window manager running
- ✅ DisplayLink drivers installed and functional
- ✅ External monitors detected and working (DVI-I-1, DVI-I-2)
- ✅ **DisplayLink artifacts FIXED** - Zero visual glitches
- ✅ ACPI event handling (acpid service)
- ✅ **Lid automation FULLY WORKING** - Smart suspend/monitor switching
- ✅ **Suspend/resume WORKING** - elogind integration complete
- ✅ **Multi-monitor configuration** - 3-monitor mode when docked
- ✅ **Waybar enhanced** - Clear labels, tooltips, auto-adapts to monitors
- ✅ **Kernel optimized** - Rebuilt for MediaTek MT7925 WiFi 7 + Bluetooth support
- ✅ **WiFi Support** - MediaTek MT7925 driver working (interface: wlp194s0)
- ✅ **WiFi Management** - Custom wifi-setup script with ZSH autocompletion
- ✅ **Waybar WiFi Display** - Shows SSID and signal strength (network module enabled)
- ✅ **Power Management** - Automatic AC/Battery profiles with ~30-50% battery improvement
- ✅ **Timezone** - Europe/Berlin (CET/CEST with automatic DST)
- ✅ **USB4/Thunderbolt** - Enabled for better dock support
- ✅ Go toolchain
- ✅ GCC/G++ toolchain
- ✅ **Bluetooth Support** - MediaTek MT7925 Bluetooth 5.4 working (hci0)
- ✅ **Bluetooth Management** - Custom bluetooth-setup script with ZSH autocompletion
- ✅ **Waybar Bluetooth Display** - Shows connection status and device name
- ✅ **Docker** - Container runtime installed
- ✅ **Touchpad** - ELAN901C I2C HID working (manual kernel compilation with CONFIG_PINCTRL_AMD=y)
- ✅ **Touchscreen** - ELAN0678 I2C HID multitouch working (manual kernel compilation with CONFIG_PINCTRL_AMD=y)
- ✅ **Audio Management** - Custom audio-setup script with ZSH autocompletion
- ✅ **Webcam** - Luxvisions Integrated RGB Camera working (640x480@30fps, UVC driver)
- ✅ **Monitor Management** - Custom monitor-setup script with swap/reset functionality
- ✅ **Ghostty Terminal** - Pure Wayland terminal emulator (no X11), set as default
- ✅ **Battery Conservation** - Charge threshold management (20-80% mode for battery longevity)
- ✅ **Catppuccin Mocha Theme** - Beautiful, cohesive theme applied to Neovim, Hyprland, and Waybar
- ✅ **Neovim LSP** - Updated to Neovim 0.11+ native LSP API (vim.lsp.config)

### In Progress 🔧
- None currently

### Incomplete/Missing ⚠️
- ⚠️ Kotlin toolchain
- ⚠️ Android/mobile development environment
- ⚠️ IoT tooling (ESP32, Arduino, bare metal flashing tools)
- ⚠️ System hardening and optimization
- ⚠️ Backup strategy
- ⚠️ Development environment configuration (IDE setup, shell customization)

## Requirements - Lid and Monitor Behavior
1. **Lid closed + External monitors**: Disable laptop screen, continue on externals ✅
2. **Lid closed + No externals**: Enter suspend/sleep mode ✅
3. **Lid open + Docked**: Three-monitor mode (2 external + laptop) ✅
4. **Lid open + Wake from sleep**: Resume all active monitors ✅
5. **Dock disconnected**: Switch to mobile-only mode ✅
6. **Dock connected**: Auto-detect and enable external monitors ✅
7. **Dynamic profiles**: Support different monitor configs ✅
8. **Waybar auto-update**: Updates on monitor configuration changes ✅

## Technical Considerations
- ACPI events are available and triggered
- OpenRC service management (not systemd)
- elogind for session management and suspend/resume
- Hyprland monitor configuration via hyprctl
- DisplayLink requires special handling (no VRR, blur, tearing, direct scanout)
- Single user (alexander) - no multi-user complexity needed
- AMD P-State EPP driver for CPU frequency scaling

## WiFi Setup

WiFi is managed using NetworkManager with a custom `wifi-setup` script for easy connection management.

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

**Quick Start**:
```bash
# Install from the scripts folder
cd scripts/wifi-setup
sudo cp wifi-setup /usr/local/bin/wifi-setup
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _wifi-setup /usr/local/share/zsh/site-functions/_wifi-setup

# Connect to a network
wifi-setup connect "NetworkName"
```

**Waybar Integration**: The waybar network module automatically displays WiFi status including SSID and signal strength when connected.

## Bluetooth Setup

Bluetooth is managed using BlueZ with a custom `bluetooth-setup` script for easy device management.

**Full documentation**: See `Bluetooth-Setup.md` for complete setup instructions, troubleshooting, and technical details.

**Status**: ✅ **WORKING** - Bluetooth controller fully functional!

**Bluetooth Controller**:
- Device: hci0
- MAC Address: F4:4E:B4:8A:E3:AC
- Hardware: MediaTek MT7925 Bluetooth 5.4
- Firmware: `mediatek/mt7925/BT_RAM_CODE_MT7925_1_1_hdr.bin`

**Quick Start**:
```bash
# Scan for devices
bluetooth-setup scan

# Pair with a device
bluetooth-setup pair AA:BB:CC:DD:EE:FF

# Connect to device
bluetooth-setup connect AA:BB:CC:DD:EE:FF

# Check status
bluetooth-setup status
```

**Waybar Integration**: The waybar Bluetooth module displays connection status and device name when connected.

**Auto-Start Configuration**:
- Bluetooth service enabled at boot
- btmtk module auto-loads via `/etc/modules-load.d/bluetooth.conf`
- Will persist across reboots

## Audio Management Setup

Audio input/output management using PulseAudio with a custom `audio-setup` script for easy device switching.

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

**Status**: ✅ **WORKING** - Audio management fully functional!

**Audio Hardware**:
- Output: Family 17h/19h/1ah HD Audio Controller (Analog Stereo)
- Driver: PulseAudio with ALSA backend
- Multiple device support (speakers, headphones, HDMI, DisplayPort, etc.)

**Quick Start**:
```bash
# Show current audio status
audio-setup

# List available outputs
audio-setup list-outputs

# List available inputs
audio-setup list-inputs

# Switch output device
audio-setup output 2

# Switch input device
audio-setup input 2

# Set volume
audio-setup volume 75

# Mute/unmute
audio-setup mute
audio-setup unmute
```

**Features**:
- Easy switching between multiple audio outputs (speakers, headphones, HDMI, etc.)
- Easy switching between multiple audio inputs (microphones, line-in, etc.)
- Automatic stream moving (active audio moves to new device)
- Volume control (0-100%)
- Mute/unmute for outputs and inputs
- Color-coded terminal output
- ZSH autocompletion with device descriptions

**Script Location**: `/usr/local/bin/audio-setup`

## Webcam

**Status**: ✅ **WORKING** - Webcam fully functional!

**Hardware**:
- **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

**Verification**:
- Camera detected by kernel (dmesg shows UVC 1.50 device)
- Video device nodes created and accessible
- Successfully tested with ffmpeg capture
- User in video group for proper permissions

**Testing Camera**:
```bash
# Test with ffmpeg (capture 1 frame)
ffmpeg -f v4l2 -i /dev/video0 -frames:v 1 test.jpg

# List camera capabilities (requires v4l-utils)
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --list-formats-ext
```

**Common Applications**:
- Video conferencing: Zoom, Teams, Google Meet (via browser)
- Recording: ffmpeg, OBS Studio
- Testing: cheese, mpv, vlc

## Monitor Management Setup

Easy monitor configuration and management using Hyprland.

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

**Status**: ✅ **WORKING** - Monitor management fully functional!

**Quick Start**:
```bash
# Install from the scripts folder
cd scripts/monitor-setup
sudo cp monitor-setup /usr/local/bin/monitor-setup
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _monitor-setup /usr/local/share/zsh/site-functions/_monitor-setup

# Show current monitor layout
monitor-setup

# Swap left/right external monitors
monitor-setup swap

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

**Features**:
- Show current monitor layout with visual representation
- Swap left/right external monitor positions (fixes reversed monitors)
- List all detected monitors with detailed information
- Reset to automatic configuration
- Color-coded terminal output
- ZSH autocompletion

**Use Cases**:
- Fix monitor order after docking
- Quick monitor configuration adjustments
- Verify monitor setup
- Complement automatic monitor-setup.sh script

**Script Location**: `/usr/local/bin/monitor-setup`

## Ghostty Terminal Emulator

**Status**: ✅ **WORKING** - Ghostty installed and set as default terminal!

**Installation Details**:
- **Version**: 1.1.3
- **Build Mode**: Pure Wayland (no X11 dependencies)
- **USE Flags**: `-X adwaita` (X11 support disabled)
- **Zig Compilation**: Built with znver4 CPU target (znver5 not yet supported by Zig 0.13.0)

**Features**:
- Fast, GPU-accelerated rendering
- Native Wayland support
- GTK4 + libadwaita integration
- Modern, feature-rich terminal emulator
- Cross-platform (but we use Wayland-only build)

**Configuration**:
- Config file: `~/.config/ghostty/config`
- Set as default in Hyprland keybindings
- Launched with `Super+Return` (or your terminal keybinding)

**Package Configuration**:
```bash
# /etc/portage/package.use/ghostty
x11-terms/ghostty -X adwaita
gui-libs/libadwaita introspection
>=gui-libs/gtk-4.18.6-r1 introspection
>=x11-libs/pango-1.57.0 introspection
>=media-libs/graphene-1.10.8-r1 introspection
>=media-libs/harfbuzz-11.4.5 introspection

# /etc/portage/package.env/zig
dev-lang/zig zig-cpu.conf
x11-terms/ghostty-terminfo zig-cpu.conf
x11-terms/ghostty zig-cpu.conf

# /etc/portage/env/zig-cpu.conf
CPU_FLAGS_X86="znver4"
CFLAGS="${CFLAGS} -march=znver4"
CXXFLAGS="${CXXFLAGS} -march=znver4"
```

**Why Ghostty?**:
- More comfortable than foot for extended use
- Modern, actively developed
- Pure Wayland (no X11 baggage in our build)
- Fast and responsive

## Battery Conservation Setup

Manage battery charge thresholds for extended battery lifespan on ThinkPad.

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

**Status**: ✅ **WORKING** - Battery threshold management fully functional!

**Hardware Support**:
- ThinkPad battery threshold support via `thinkpad_acpi` module
- Battery: BAT0
- Thresholds: Fully supported and working

**Quick Start**:
```bash
# Install from the scripts folder
cd scripts/battery-setup
sudo cp battery-setup /usr/local/bin/battery-setup
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _battery-setup /usr/local/share/zsh/site-functions/_battery-setup

# Install OpenRC service for persistence
sudo cp battery-thresholds /etc/init.d/battery-thresholds
sudo chmod +x /etc/init.d/battery-thresholds
sudo cp battery-thresholds.conf /etc/conf.d/battery-thresholds
sudo rc-update add battery-thresholds boot

# Show current status
battery-setup

# Enable conservation mode (RECOMMENDED)
sudo battery-setup conservation

# For travel: enable full charge mode
sudo battery-setup full
```

**Features**:
- Conservation mode (20-80%) for battery longevity
- Full charge mode (0-100%) for maximum capacity
- Custom threshold ranges
- Battery health monitoring
- Charge cycle tracking
- Persistent settings across reboots (OpenRC service)
- Color-coded terminal output
- ZSH autocompletion

**Battery Science**:
- Keeping battery at 20-80% can **double battery lifespan**
- High voltage states (90-100%) accelerate degradation
- Ideal for docked/frequent AC usage
- Reduces stress on lithium-ion cells
- Heat + high charge = worst combination for battery

**Configuration**:
- Default: Conservation mode (20-80%)
- Start charging: When battery drops below 20%
- Stop charging: When battery reaches 80%
- Laptop runs on AC power while maintaining ~80%

**Script Location**: `/usr/local/bin/battery-setup`

## Touchpad and Touchscreen Setup

**Status**: ✅ **WORKING** - Both devices fully functional!

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

**Problem (Resolved)**: Both devices detected but not functional - missing CONFIG_PINCTRL_AMD kernel support

**Root Cause**: genkernel was silently ignoring config changes. After 4 rebuild attempts, discovered genkernel uses separate config in `/etc/kernels/` that overrides `/usr/src/linux/.config`.

**Solution (Implemented)**:
1. ✅ Switched to manual kernel compilation (no genkernel)
2. ✅ Enabled `CONFIG_I2C_HID_ACPI=m`
3. ✅ Enabled `CONFIG_PINCTRL_AMD=y` (critical for GPIO interrupts on AMD platforms)

**Kernel Configuration**:
- `CONFIG_I2C_HID=m` ✅ Enabled
- `CONFIG_I2C_HID_ACPI=m` ✅ Enabled
- `CONFIG_PINCTRL_AMD=y` ✅ Enabled (built-in)

**Functionality Verified**:
- ✅ Touchpad cursor movement and multi-finger gestures
- ✅ Touchscreen touch and multitouch input
- ✅ Modules load automatically (i2c-hid-acpi)

**Full Documentation**: See `Touchpad-Touchscreen-Setup.md` and `POST-REBOOT-CHECKLIST.md`

## Power Management

Dynamic power management with automatic profile switching based on AC adapter status.

**Full documentation**: See `Power-Management-Setup.md` for complete details and advanced configuration.

**Features**:
- ✅ Automatic AC/Battery profile switching via ACPI events
- ✅ CPU frequency scaling (performance/powersave governors)
- ✅ AMD P-State EPP tuning (power/performance preferences)
- ✅ GPU power management (DPM states)
- ✅ Laptop mode for disk power saving
- ✅ ~30-50% battery life improvement
- ✅ Detailed logging to `/var/log/power-profile.log`

**Status**: Fully installed and working.

**Quick Check**:
```bash
# Check current profile
cat /sys/class/power_supply/AC/online  # 1 = AC, 0 = battery
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# View power profile log
tail -f /var/log/power-profile.log

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

**Components**:
- `/usr/local/bin/power-profile-ac` - Performance profile
- `/usr/local/bin/power-profile-battery` - Power saving profile
- `/etc/acpi/default.sh` - ACPI event handler (auto-switching)

## Timezone Configuration

**Current Timezone**: Europe/Berlin (CET/CEST)
- System clock runs in UTC internally
- Display time shows CET (UTC+1) or CEST (UTC+2) with automatic DST transitions
- Configured via `/etc/localtime` → `/usr/share/zoneinfo/Europe/Berlin`

## Kernel Configuration

**Version**: 6.12.41-gentoo-x86_64

**Build Method**: **MANUAL COMPILATION ONLY** - genkernel is NOT used

**⚠️ CRITICAL NOTE**:
- **NEVER USE GENKERNEL FOR ANY FUTURE TASKS**
- genkernel was found to be unreliable - it uses separate config files in `/etc/kernels/` that override `/usr/src/linux/.config`, causing config changes to be silently ignored
- After 4 failed rebuild attempts, we switched to manual kernel compilation for full control
- All kernel builds MUST use the automated build script: `scripts/build-kernel.sh`

**Automated Kernel Build Script**: `scripts/build-kernel.sh`
```bash
# Run the automated build script (handles everything)
sudo ./scripts/build-kernel.sh
```

**What the script does**:
1. Backs up current `.config` to `.config.backup`
2. Runs `make mrproper` (clean build tree)
3. Restores `.config` from backup
4. Runs `make oldconfig` (update config)
5. Builds kernel with `make -j16`
6. Installs modules with `make modules_install`
7. Creates timestamped backups in `/boot`
8. Copies kernel to `/boot/vmlinuz-6.12.41-gentoo-x86_64`
9. Generates initramfs with dracut
10. Updates GRUB configuration
11. Logs everything to `logs/kernel-build-TIMESTAMP.log`

**Manual Build Process** (if script unavailable):
```bash
# Extract current running config
zcat /proc/config.gz > /usr/src/linux/.config

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

# Build kernel
sudo make -j16

# Install modules
sudo make modules_install

# Copy kernel to /boot
sudo cp arch/x86_64/boot/bzImage /boot/vmlinuz-6.12.41-gentoo-x86_64

# Generate initramfs
sudo dracut --force --kver 6.12.41-gentoo-x86_64 /boot/initramfs-6.12.41-gentoo-x86_64.img

# Update GRUB
sudo grub-mkconfig -o /boot/grub/grub.cfg
```

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

**Key Optimizations**:
- AMD Ryzen AI 7 PRO 350 specific optimizations
- MediaTek MT7925 WiFi 7 support (CONFIG_MT7925E=m)
- MediaTek MT7925 Bluetooth support (CONFIG_BT_HCIBTUSB_MTK=y)
- I2C HID ACPI support (CONFIG_I2C_HID_ACPI=m) - for touchpad and touchscreen ✅
- AMD Pinctrl support (CONFIG_PINCTRL_AMD=y) - REQUIRED for GPIO interrupts on touchpad/touchscreen ✅
- USB4/Thunderbolt support (CONFIG_USB4=m, CONFIG_THUNDERBOLT=m)
- AMD P-State EPP driver (CONFIG_X86_AMD_PSTATE=y, mode 3 - active)
- DisplayLink support
- Power management optimizations

**Latest Kernel Build**: November 5, 2025 - Successfully built with manual compilation (touchpad/touchscreen working)

## UI Theme Configuration - Catppuccin Mocha

**Status**: ✅ **COMPLETE** - Cohesive Catppuccin Mocha theme across all applications!

The system uses the beautiful Catppuccin Mocha color palette for a consistent, professional look and feel.

### Catppuccin Mocha Color Palette

**Core Colors**:
- Base (Background): `#1e1e2e`
- Text: `#cdd6f4`
- Lavender (Accent): `#b4befe`
- Mauve (Secondary): `#cba6f7`
- Surface0 (UI Elements): `#313244`

**Module-Specific Colors**:
- CPU: Blue `#89b4fa`
- Memory: Mauve `#cba6f7`
- Temperature: Green `#a6e3a1` (Red `#f38ba8` when critical)
- Battery: Green `#a6e3a1` (Teal `#94e2d5` when charging, Peach `#fab387` warning, Red critical)
- Network: Sapphire `#74c7ec`
- Volume: Pink `#f5c2e7`
- Bluetooth: Sky `#89dceb`
- Clock: Lavender `#b4befe` (bold)

### Neovim Configuration

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

**LSP Configuration** (`lua/alxndrhi/plugins/lsp.lua`):
- Updated to Neovim 0.11+ native API
- Uses `vim.lsp.config[]` instead of deprecated `require('lspconfig')`
- Integrated with blink.cmp for completions
- Configured LSP servers: html, cssls, gopls, clangd, jsonls, yamlls, bashls, dockerls, vimls, lua_ls, ruff, graphql, tailwindcss, vuels, cmake

**Feline Statusline** (`lua/alxndrhi/plugins/feline.lua`):
- Catppuccin Mocha color integration
- Uses `require("catppuccin.palettes").get_palette()` for color consistency
- Minimal, clean statusline with Mocha colors

**Catppuccin Theme** (`lua/alxndrhi/plugins/catppuccin.lua`):
- Flavor: Mocha (dark theme)
- Feline integration enabled
- Consistent with system-wide theme

### Hyprland Theme

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

**Color Configuration** (`hyprland.conf`):
- Active window border: Lavender → Mauve gradient (`$lavender $mauve 45deg`)
- Inactive window border: Surface0 (`$surface0`)
- Smooth transitions with beautiful purple gradient on focused windows

**Color Variables** (`mocha.conf`):
- Complete Catppuccin Mocha palette defined as Hyprland variables
- All colors available for use throughout configuration
- Consistent with Neovim and Waybar themes

### Waybar Theme

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

**Status**: ✅ Fully themed with Catppuccin Mocha colors and Nerd Font icons

**Theme Configuration** (`style.css`):
- Base background: `#1e1e2e`
- Active workspace: Lavender border with subtle glow
- Hover workspace: Mauve accent
- Color-coded modules for easy identification
- Rounded corners (`border-radius: 5px`)
- Consistent spacing and padding

**Font Configuration**:
- Primary font: Hasklug Nerd Font
- Fallback fonts: Roboto, Helvetica, Arial, sans-serif
- Font size: 13px
- Nerd Font icons throughout for visual clarity

**Modules with Icons** (`config`):
- **CPU**: 󰻠 (processor icon) - Blue
- **Memory**:  (RAM chip) - Mauve
- **Temperature**: No icon (self-explanatory) - Green/Red
- **Backlight**:  (adaptive brightness icons) - Yellow
- **Battery**: 󰁺-󰁹 (10-level battery indicators) - Green/Teal/Peach/Red
- **Network**: 󰖩 (WiFi), 󰈀 (Ethernet), 󰖪 (Disconnected) - Sapphire
- **Volume**: 󰕿 󰖀 󰕾 (speaker levels), 󰖁 (muted) - Pink
- **Bluetooth**: 󰂯 (connected), 󰂲 (off) - Sky
- **Clock**: Time display - Lavender (bold)

**Features**:
- Catppuccin Mocha color scheme throughout
- Nerd Font icons for all modules
- Detailed hover tooltips
- Auto-adapts to all connected monitors
- Automatically updates via Hyprland IPC (no restart needed)
- Clean, professional aesthetic

**Configuration Files**:
- `config` - Waybar module configuration with icon definitions
- `style.css` - Catppuccin Mocha theme with color-coded modules
- `mocha.css` - Catppuccin Mocha color palette definitions

### Theme Benefits

1. **Visual Consistency**: Same color palette across all applications
2. **Professional Look**: Catppuccin is designed for long-term use without eye strain
3. **Clear Information Hierarchy**: Color-coded modules make information scanning quick
4. **OLED Friendly**: Dark theme optimized for OLED display
5. **Icon Clarity**: Nerd Font icons provide visual cues without text clutter

## Waybar Configuration

**Status Bar Modules** (left to right):
- Workspaces
- Window title
- Clock (center)
- Audio (pulseaudio) - Pink 󰕿
- Bluetooth status - Sky 󰂯
- Network (WiFi/Ethernet) - Sapphire 󰖩
- CPU usage - Blue 󰻠
- RAM usage - Mauve
- Temperature - Green (no icon)
- Brightness - Yellow
- Battery - Green/Teal 󰁹

**Configuration**: `~/.config/waybar/config`

**Style**: `~/.config/waybar/style.css` (Catppuccin Mocha theme)

**Features**:
- Nerd Font icons with Catppuccin Mocha colors
- Detailed hover tooltips
- Auto-adapts to all connected monitors
- Automatically updates via Hyprland IPC (no restart needed)

## System Scripts

### Kernel Build
- `scripts/build-kernel.sh` - Automated kernel build script (NEVER use genkernel)
- `logs/` - Build logs directory (kernel-build-TIMESTAMP.log)

### Power Management
- `/usr/local/bin/power-profile-ac` - AC power profile (performance)
- `/usr/local/bin/power-profile-battery` - Battery profile (power saving)
- `/var/log/power-profile.log` - Power management log

### WiFi Management
- `/usr/local/bin/wifi-setup` - WiFi connection manager
- `/usr/local/share/zsh/site-functions/_wifi-setup` - ZSH completion

### Bluetooth Management
- `/usr/local/bin/bluetooth-setup` - Bluetooth device manager
- `/usr/local/share/zsh/site-functions/_bluetooth-setup` - ZSH completion

### Audio Management
- `/usr/local/bin/audio-setup` - Audio input/output manager
- `/usr/local/share/zsh/site-functions/_audio-setup` - ZSH completion

### Monitor Management
- `/usr/local/bin/monitor-setup` - Interactive monitor configuration tool
- `/usr/local/share/zsh/site-functions/_monitor-setup` - ZSH completion
- `/home/alexander/.config/hypr/scripts/monitor-setup.sh` - Automatic monitor configuration

### Battery Conservation
- `/usr/local/bin/battery-setup` - Battery charge threshold manager
- `/usr/local/share/zsh/site-functions/_battery-setup` - ZSH completion
- `/etc/init.d/battery-thresholds` - OpenRC service for persistent thresholds
- `/etc/conf.d/battery-thresholds` - Battery threshold configuration

### Monitor/Lid Automation
- `/usr/local/bin/lid-handler.sh` - Lid event handler (suspend/monitor switching)
- `/etc/acpi/lid.sh` - ACPI lid event entry point
- `/lib/elogind/system-sleep/hyprland-resume` - Resume hook

## Documentation

### User Guide
- `USER-GUIDE.md` - **Quick reference for everyday tasks** - Package management, services, network, audio, updates, and more

### Complete Guides
- `Claude.md` - **This file** - System overview and current state
- `Power-Management-Setup.md` - Complete power management guide
- `Bluetooth-Setup.md` - Complete Bluetooth setup and troubleshooting
- `Lid-Automation-Working-Solution.md` - Lid automation implementation
- `Fix-DisplayLink-Artifacts.md` - DisplayLink optimization guide
- `Session-Summary.md` - Previous session achievements

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

### Technical Specifications
- `Lid-Automation-Implementation.md` - Technical lid automation specs
- `kernel-6.12.41-gentoo-x86_64.config` - Complete kernel configuration

## Post-Reboot Checklist (Last Reboot - November 5, 2025)

All items verified and working! ✅

### Touchpad and Touchscreen (Latest Addition)
- [x] ✅ Touchpad working (ELAN901C I2C HID)
- [x] ✅ Touchscreen working (ELAN0678 multitouch)
- [x] ✅ i2c-hid-acpi module loads automatically
- [x] ✅ Multi-finger gestures working

### Bluetooth (Auto-Start Verified)
- [x] ✅ `bluetoothctl list` shows Bluetooth controller (hci0)
- [x] ✅ Bluetooth service starts automatically
- [x] ✅ btmtk module loads automatically
- [x] ✅ Waybar shows Bluetooth module

### Existing Features (Regression Testing)
- [x] ✅ WiFi connects and shows in waybar
- [x] ✅ Power management switches profiles when AC plugged/unplugged
- [x] ✅ Lid automation works (close lid → correct behavior)
- [x] ✅ Multi-monitor setup works when docked
- [x] ✅ Suspend/resume works
- [x] ✅ DisplayLink monitors work without artifacts

## Known Issues

### None Currently

All previously identified issues have been resolved:
- ✅ Bluetooth controller detection - Fixed (module conflict resolved)
- ✅ DisplayLink artifacts - Fixed (Hyprland configuration optimized)
- ✅ Lid automation - Fixed (custom ACPI scripts working)
- ✅ Power management - Fixed (AC/Battery profiles working)

## Success Metrics

- ✅ Zero DisplayLink artifacts
- ✅ 100% reliable lid automation
- ✅ Waybar survives all transitions
- ✅ Three-monitor mode working
- ✅ Suspend/resume working
- ✅ WiFi working with easy management (WiFi 7)
- ✅ Bluetooth working with easy management (BT 5.4)
- ✅ Audio management with easy device switching
- ✅ Webcam fully functional
- ✅ Touchpad fully functional (multi-finger gestures)
- ✅ Touchscreen fully functional (multitouch)
- ✅ Monitor management with swap/reset functionality
- ✅ Ghostty terminal emulator (pure Wayland, no X11)
- ✅ Battery conservation system (20-80% for extended lifespan)
- ✅ ~30-50% battery life improvement (power profiles)
- ✅ Potentially 2x battery lifespan (conservation mode)
- ✅ Kernel optimized for exact hardware
- ✅ System fully documented
- ✅ All critical hardware functional
- ✅ Complete suite of management scripts
- ✅ **Cohesive Catppuccin Mocha theme** across all applications
- ✅ **Neovim LSP** updated to native API (no deprecations)
- ✅ **Waybar with Nerd Font icons** and color-coded modules
- ✅ **Professional UI** optimized for OLED display

## Session Summary (November 5, 2025 - Late Evening)

**Achievements:**
1. ✅ **Catppuccin Mocha Theme** - Complete system-wide theming for beautiful, cohesive UI
2. ✅ **Neovim LSP Migration** - Updated to Neovim 0.11+ native API (vim.lsp.config)
3. ✅ **Feline Statusline** - Integrated Catppuccin Mocha colors
4. ✅ **Hyprland Theme** - Applied Catppuccin Mocha colors to window borders
5. ✅ **Waybar Redesign** - Complete Catppuccin Mocha theme with Nerd Font icons
6. ✅ **Documentation** - Comprehensive UI/Theme section added to Claude.md

**Technical Details:**
- Migrated Neovim LSP from deprecated `require('lspconfig')` to native `vim.lsp.config[]` API
- Fixed Feline integration with Catppuccin using palette API
- Applied Catppuccin Mocha color palette across Hyprland, Waybar, and Neovim
- Implemented Nerd Font icons in Waybar using exact UTF-8 glyphs from verified working config
- Color-coded all Waybar modules for easy visual identification
- Removed obsolete Hyprland shadow settings that caused errors

**UI/Theme Components:**
- Hyprland: Lavender→Mauve gradient on active windows, Surface0 on inactive
- Waybar: Full Catppuccin Mocha theme with color-coded modules and Nerd Font icons
- Neovim: Updated LSP config, Feline statusline with Mocha colors
- Font: Hasklug Nerd Font with proper fallbacks

**Previous Session (November 5, 2025 - Evening):**
1. ✅ Monitor Management Tool - Interactive monitor-setup script
2. ✅ Ghostty Terminal - Pure Wayland terminal (no X11)
3. ✅ Battery Conservation - 20-80% charge threshold system
4. ✅ Documentation - Comprehensive READMEs

## Next Tasks

Recommended priority order:

1. **Backup strategy** - System backup solution
2. **System hardening** - Security improvements, firewall

**Development tools** (User will configure):
- Kotlin toolchain
- Android/mobile development environment
- IoT tooling (ESP32, Arduino, bare metal flashing tools)
- IDE setup and shell customization

## Contact Points for Troubleshooting

### Bluetooth Issues
```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
```

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

# Check current state
cat /sys/class/power_supply/AC/online
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# Manual profile test
sudo /usr/local/bin/power-profile-ac
```

### WiFi Issues
```bash
# Check status
wifi-setup status

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

### Audio Issues
```bash
# Check status
audio-setup status

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

# Check PulseAudio
pactl info
```

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

# Check monitor configuration
monitor-setup status
hyprctl monitors
```

### Monitor Management Issues
```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
```

### Battery Conservation Issues
```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
```

### Ghostty Issues
```bash
# Test if Ghostty works
ghostty

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

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

### Neovim/LSP Issues
```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
```

### Theme/Waybar Issues
```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
```

## System Health

**Overall Status**: 🟢 Excellent

**Stability**: Rock solid
**Performance**: Optimized
**Battery Life**: 30-50% improvement (power profiles) + potentially 2x lifespan (conservation mode)
**Hardware Support**: Complete (all input/output devices working)
**Management Tools**: Complete suite of interactive scripts
**UI/Theme**: Professional Catppuccin Mocha theme with Nerd Font icons
**Completeness**: ~97% (all core hardware, features, management tools, and UI theme complete)

**Ready for production use!** 🚀

---

**Note for Claude**: When commands require sudo, provide the command for the user to copy-paste rather than attempting to run it directly.