# CLAUDE.md - Operational Guidelines for Claude Code

This file contains guidelines and context for Claude Code when working on this
Gentoo ThinkPad project.

## Project Context

This is a **Gentoo Linux development workstation** setup project. The system
is a Lenovo ThinkPad configured for professional software development with a
focus on minimalism, performance, and Wayland-native tools.

For complete system details, see:
- **System-Overview.md** - Hardware specs, software stack, design philosophy
- **Feature-Status.md** - Current state, working features, session history
- **Troubleshooting.md** - Troubleshooting commands and procedures

## Technical Considerations

### System Architecture

- **Init System**: OpenRC (not systemd)
- **Session Manager**: elogind for session management and suspend/resume
- **Display Protocol**: Wayland (no X11)
- **Window Manager**: Hyprland (configured via `hyprctl`)
- **Single User System**: Optimized for user `alexander`

### Critical System Notes

#### Kernel Compilation

**⚠️ CRITICAL**: NEVER use genkernel for any kernel tasks.

- genkernel was found to be unreliable (uses separate config files in
`/etc/kernels/` that override `/usr/src/linux/.config`)
- All kernel builds MUST use the automated build script:
`scripts/build-kernel.sh`
- Manual compilation is documented in the script and in Feature-Status.md

#### DisplayLink Monitors

DisplayLink requires special Hyprland configuration:
- No VRR (Variable Refresh Rate)
- No blur effects
- No tearing optimization
- No direct scanout

These settings are already configured. See `Fix-DisplayLink-Artifacts.md` for
details.

#### AMD Platform Specifics

- **CPU**: AMD Ryzen AI 7 PRO 350
- **Power Management**: AMD P-State EPP driver (mode 3 - active)
- **GPIO/ACPI**: Requires `CONFIG_PINCTRL_AMD=y` in kernel for
touchpad/touchscreen

### Hardware-Specific Details

#### Wireless (MediaTek MT7925)

- **WiFi**: WiFi 7 (BE) - Interface: `wlp194s0`
- **Bluetooth**: Bluetooth 5.4 - Controller: `hci0`
- **Management**: Custom scripts at `/usr/local/bin/wifi-setup` and
`/usr/local/bin/bluetooth-setup`

#### Input Devices

- **Touchpad**: ELAN901C I2C HID (requires CONFIG_PINCTRL_AMD=y)
- **Touchscreen**: ELAN0678 I2C HID multitouch (requires CONFIG_PINCTRL_AMD=y)
- Both require `i2c-hid-acpi` module

#### Power Management

- Automatic AC/Battery profile switching via ACPI events
- Battery conservation mode (20-80% charge thresholds) for extended lifespan
- Scripts: `/usr/local/bin/power-profile-ac` and
`/usr/local/bin/power-profile-battery`
- Logs: `/var/log/power-profile.log`

## System Scripts and Tools

All management scripts are installed system-wide with ZSH completion:

### Core Management Scripts

- `/usr/local/bin/wifi-setup` - WiFi connection manager
- `/usr/local/bin/bluetooth-setup` - Bluetooth device manager
- `/usr/local/bin/audio-setup` - Audio input/output manager
- `/usr/local/bin/monitor-setup` - Interactive monitor configuration
- `/usr/local/bin/battery-setup` - Battery charge threshold manager
- `/usr/local/bin/backup-setup` - Interactive backup management

### Automation Scripts

- `/usr/local/bin/lid-handler.sh` - Lid event handler (suspend/monitor
switching)
- `/usr/local/bin/backup-trigger` - Network trigger daemon (monitors NAS)
- `/home/alexander/.config/hypr/scripts/monitor-setup.sh` - Automatic monitor
configuration

### Backup Workers

- `/usr/local/bin/backup-full` - Full system backup
- `/usr/local/bin/backup-home` - Home directory backup
- `/usr/local/bin/backup-incremental` - Incremental backup
- `/usr/local/bin/backup-configs` - Configuration files backup

### OpenRC Services

- `backup-monitor` - Network trigger for automatic backups
- `battery-thresholds` - Persistent battery charge thresholds
- `bluetooth` - Bluetooth daemon
- `nftables` - Firewall
- `acpid` - ACPI event handling

## Configuration Files and Locations

### System Configuration

- `/etc/nftables.conf` - Firewall configuration (default deny incoming)
- `/etc/backup.conf` - Backup configuration (NAS connection, exclusions)
- `/etc/acpi/default.sh` - ACPI event handler (power profile auto-switching)
- `/etc/acpi/lid.sh` - ACPI lid event entry point
- `/etc/conf.d/battery-thresholds` - Battery threshold configuration

### User Configuration

- `~/.config/hypr/` - Hyprland configuration (Catppuccin Mocha theme)
- `~/.config/waybar/` - Waybar configuration (Catppuccin Mocha theme, Nerd
Font icons)
- `~/.config/nvim/` - Neovim configuration (LSP with native API)
- `~/.config/ghostty/` - Ghostty terminal configuration
- `~/.config/chezmoi/` - Chezmoi dotfile manager configuration

### Dotfile Management

- **Tool**: chezmoi (cross-platform dotfile manager)
- **Source**: `~/.local/share/chezmoi` (git clone of dotfiles repo)
- **Repository**: `~/repository/git.hinrichs.dev/alexander/dotfiles`
- See `Dotfiles-Management.md` for complete guide

### Logs

- `/var/log/power-profile.log` - Power management log
- `~/.local/var/log/backup.log` - Backup operations log
- `~/.local/var/log/backup-monitor.log` - Monitor daemon log
- `/tmp/lid-handler.log` - Lid automation log

## UI/Theme Configuration

The system uses **Catppuccin Mocha** theme consistently across all
applications:

- **Hyprland**: Lavender→Mauve gradient on active windows, Surface0 on
inactive
- **Waybar**: Color-coded modules with Nerd Font icons (Hasklug Nerd Font)
- **Neovim**: Feline statusline with Mocha colors, LSP using native
`vim.lsp.config[]` API
- **Ghostty**: Pure Wayland terminal (no X11)

### Theme Colors (Catppuccin Mocha)

- Base: `#1e1e2e`
- Text: `#cdd6f4`
- Lavender: `#b4befe`
- Mauve: `#cba6f7`
- Surface0: `#313244`

See Feature-Status.md for complete theme documentation.

## Documentation Structure

### User Documentation

- **USER-GUIDE.md** - Quick reference for everyday tasks (package management,
services, network, audio, updates)
- **System-Overview.md** - Hardware specs, software stack, design philosophy,
system health
- **Feature-Status.md** - Current state, working features, session history,
success metrics
- **Troubleshooting.md** - Troubleshooting commands and procedures for all
components

### Complete Guides

- **Backup-Setup.md** - Complete backup guide (automated NAS backups, network
trigger, troubleshooting)
- **Security-Hardening.md** - Complete security guide (firewall, fail2ban, SSH
hardening, monitoring)
- **Power-Management-Setup.md** - Complete power management guide
- **Bluetooth-Setup.md** - Complete Bluetooth setup and troubleshooting
- **Dotfiles-Management.md** - Complete chezmoi guide (managing dotfiles,
adding new tools, editing configs)
- **Lid-Automation-Working-Solution.md** - Lid automation implementation
- **Fix-DisplayLink-Artifacts.md** - DisplayLink optimization guide

### Script Documentation

Each script directory under `scripts/` contains a `README.md`:
- `scripts/wifi-setup/README.md`
- `scripts/bluetooth-setup/README.md`
- `scripts/audio-setup/README.md`
- `scripts/monitor-setup/README.md`
- `scripts/battery-setup/README.md`
- `scripts/backup-setup/` - Backup system scripts and configurations
- `scripts/security-setup/` - Security hardening scripts and configurations

### Technical Specifications

- **Lid-Automation-Implementation.md** - Technical lid automation specs
- **kernel-6.12.41-gentoo-x86_64.config** - Complete kernel configuration
- **Touchpad-Touchscreen-Setup.md** - Touchpad and touchscreen setup details
- **POST-REBOOT-CHECKLIST.md** - Post-reboot verification checklist

## Operational Guidelines for Claude

### When Working with Commands

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

### Package Management

Use Gentoo's Portage system:
```bash
emerge --search <package>
emerge -av <package>  # Ask and verbose
emerge -avuDN @world  # Update world
```

### Service Management

Use OpenRC (not systemd):
```bash
rc-service <service> start|stop|restart|status
rc-update add|del <service> <runlevel>
rc-status -a  # List all services
```

### Kernel Work

- NEVER suggest using genkernel
- Always use `scripts/build-kernel.sh` or manual compilation
- Reference saved config: `kernel-6.12.41-gentoo-x86_64.config`

### File Editing

When editing system configuration files:
1. Always read the file first using the Read tool
2. Use the Edit tool for modifications
3. Preserve exact formatting and structure
4. Test changes before marking complete

### Documentation Updates

When updating documentation:
1. Maintain consistency across all related files
2. Update cross-references when moving content
3. Keep USER-GUIDE.md concise (quick reference only)
4. Put detailed information in dedicated guides
5. Ensure examples are correct and tested

### Troubleshooting Approach

When helping with issues:
1. Check Troubleshooting.md first for existing procedures
2. Check relevant guide (Backup-Setup.md, Security-Hardening.md, etc.)
3. Check script-specific README.md files
4. Verify system state before making changes
5. Document any new procedures discovered

### Testing Changes

Always verify changes work:
1. Test commands before marking tasks complete
2. Verify services restart successfully
3. Check logs for errors
4. Ensure no regressions in existing functionality

## Common Workflows

### Adding a New Feature

1. Implement the feature (scripts, configs, services)
2. Test thoroughly
3. Update Feature-Status.md (add to "Working" section)
4. Update USER-GUIDE.md (add quick reference)
5. Create or update detailed guide (if complex)
6. Update this CLAUDE.md (if it affects operational guidelines)

### Fixing a Bug

1. Diagnose using Troubleshooting.md procedures
2. Implement fix
3. Test fix thoroughly
4. Update documentation if procedure changed
5. Update Feature-Status.md (remove from "Known Issues" if listed)

### Updating Documentation

1. Identify which files need updates
2. Maintain consistency across related files
3. Update cross-references
4. Keep tone professional and technical
5. Use markdown formatting consistently

## Project Status

**Overall Status**: 🟢 Excellent - Production Ready

Core system setup is complete (~99%). Only development-specific tools remain
(Kotlin, Android, IoT tooling) which will be configured as needed by the user.

For detailed status, see:
- **Feature-Status.md** - Complete status, working features, session history
- **System-Overview.md** - System health and metrics

---

**Note**: This file should remain focused on operational guidelines for Claude
Code. Project-specific details belong in the appropriate documentation files
listed above.