# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Purpose

Comprehensive Ansible configuration for managing Fedora Workstation laptops. Provides automated configuration management for system setup, package management, security hardening, and laptop-specific optimizations.

## Common Commands

### Running Playbooks
```bash
# Run main playbook against localhost
ansible-playbook -i inventory/hosts playbook.yml --ask-become-pass

# Run specific tags
ansible-playbook -i inventory/hosts playbook.yml --tags "packages,security" --ask-become-pass

# Dry run (check mode)
ansible-playbook -i inventory/hosts playbook.yml --check --diff

# Run against specific host
ansible-playbook -i inventory/hosts playbook.yml --limit hostname

# Use vault-encrypted variables
ansible-playbook -i inventory/hosts playbook.yml --ask-vault-pass
```

### Testing and Validation
```bash
# Syntax check
ansible-playbook playbook.yml --syntax-check

# List all tasks that would be executed
ansible-playbook -i inventory/hosts playbook.yml --list-tasks

# List all hosts
ansible-playbook -i inventory/hosts playbook.yml --list-hosts

# Validate inventory
ansible-inventory -i inventory/hosts --list
```

### Vault Operations
```bash
# Create encrypted file
ansible-vault create group_vars/all/vault.yml

# Edit encrypted file
ansible-vault edit group_vars/all/vault.yml

# Encrypt existing file
ansible-vault encrypt secrets.yml

# Decrypt file (temporary)
ansible-vault view group_vars/all/vault.yml

# Rekey vault file
ansible-vault rekey group_vars/all/vault.yml
```

## Architecture

### Standard Ansible Directory Structure
This repository follows standard Ansible best practices for a workstation management setup:

- **inventory/** - Host definitions and group variables
- **roles/** - Reusable role modules (packages, security, dotfiles, etc.)
- **group_vars/** - Variables for host groups
- **host_vars/** - Variables for specific hosts
- **playbooks/** or root playbook.yml - Main orchestration
- **files/** - Static files to be copied to hosts
- **templates/** - Jinja2 templates for configuration files

### Typical Role Organization
Roles should follow the structure:
```
roles/role_name/
├── tasks/main.yml      # Main task list
├── handlers/main.yml   # Handlers for service restarts, etc.
├── templates/          # Jinja2 templates
├── files/              # Static files
├── vars/main.yml       # Role-specific variables
├── defaults/main.yml   # Default variables (lowest precedence)
└── meta/main.yml       # Role dependencies
```

### Workstation Management Patterns
For Fedora workstation management, typical role categories include:
- **Base system**: DNF configuration, repositories, system services
- **Packages**: Software installation and updates
- **Security**: Firewall, SELinux, user permissions
- **Laptop optimization**: Power management, suspend/hibernate, battery optimization
- **User configuration**: Dotfiles, shell setup, desktop environment
- **Development tools**: Programming languages, IDEs, containers

## Security Considerations

### Vault Usage
- All sensitive data (passwords, API keys, certificates) must be encrypted with ansible-vault
- Never commit unencrypted vault files (.gitignore already configured)
- Store vault password securely outside the repository

### Privilege Escalation
- Use `become: true` only when necessary
- Prefer targeted `become` on specific tasks rather than entire playbooks
- Always use `--ask-become-pass` when running locally for security

## Testing Approach

For workstation configurations:
1. Test in check mode first (`--check --diff`)
2. Use tags to test individual components
3. Validate on a test VM or secondary system before production workstation
4. Keep playbooks idempotent - safe to run multiple times