lenovo-gentoo/CLAUDE.md

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:

emerge --search <package>
emerge -av <package>  # Ask and verbose
emerge -avuDN @world  # Update world

Service Management

Use OpenRC (not systemd):

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.