323 lines
10 KiB
Markdown
323 lines
10 KiB
Markdown
# 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.
|