# CLAUDE.md

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

## Overview

This is an Ansible-based machine provisioning system for Arch Linux systems. It automates the setup of a new machine including hostname, networking (WiFi/Ethernet), user accounts, SSH configuration, and package installation from multiple sources (pacman, AUR, Flatpak, AppImage).

## Architecture

The repository follows Ansible's role-based structure with two primary roles:

### Common Role (`roles/common/`)
Handles system-level configuration:
- Hostname configuration
- Network configuration using NetworkManager (nmcli)
- User account management with password-hashed credentials
- SSH daemon configuration with handlers for service restart

**Key Implementation Details:**
- Network connections use `creates:` parameter to avoid recreating existing NetworkManager connection files
- User passwords should be hashed (SHA-512) or managed via Ansible Vault
- SSH configuration changes trigger the `Restart sshd` handler (defined in `roles/common/handlers/main.yml`)

### Packages Role (`roles/packages/`)
Manages software installation from multiple sources:
- Ensures `yay` AUR helper is installed (clones from AUR, builds with makepkg)
- Installs pacman packages from `roles/packages/files/pkglist.txt`
- Installs AUR packages from `roles/packages/files/aur_pkglist.txt` using yay
- Installs Flatpak packages from `roles/packages/files/flatpak_pkglist.txt`
- Downloads AppImages from URLs in `roles/packages/files/appimage_pkglist.txt` to `~/Applications`

**Key Implementation Details:**
- Yay installation uses a block with conditional execution (checks if yay exists first)
- Package lists are read line-by-line using `with_lines` module
- AppImages are set to executable mode (0755) upon download

## Common Commands

### Running the Full Playbook
```bash
# Full run with privilege escalation prompt
ansible-playbook -i inventory playbook.yml --ask-become-pass

# Dry-run to preview changes
ansible-playbook -i inventory playbook.yml --check

# With encrypted vault variables
ansible-playbook -i inventory playbook.yml --ask-vault-pass --ask-become-pass
```

### Running Specific Tasks with Tags
```bash
# Network configuration only (WiFi + Ethernet)
ansible-playbook -i inventory playbook.yml --tags "network" --ask-become-pass

# WiFi configuration only
ansible-playbook -i inventory playbook.yml --tags "wifi" --ask-become-pass

# Ethernet configuration only
ansible-playbook -i inventory playbook.yml --tags "ethernet" --ask-become-pass

# User management only
ansible-playbook -i inventory playbook.yml --tags "users" --ask-become-pass

# SSH daemon configuration only
ansible-playbook -i inventory playbook.yml --tags "sshd" --ask-become-pass

# Install pacman packages only
ansible-playbook -i inventory playbook.yml --tags "pacman" --ask-become-pass

# Install AUR packages only
ansible-playbook -i inventory playbook.yml --tags "aur" --ask-become-pass

# Install Flatpak packages only
ansible-playbook -i inventory playbook.yml --tags "flatpak" --ask-become-pass

# Download AppImages only
ansible-playbook -i inventory playbook.yml --tags "appimage" --ask-become-pass
```

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

# Lint all playbooks and roles
ansible-lint playbook.yml
```

## Configuration Files

- **`ansible.cfg`**: Sets default inventory location
- **`inventory`**: Defines target hosts (currently configured for `[new_machine]` group)
- **`playbook.yml`**: Main orchestration playbook applying both roles
- **`roles/common/defaults/main.yml`**: Default variables for hostname, network, users, SSH (contains sensitive data)
- **`roles/packages/defaults/main.yml`**: File paths for package lists

## Security Considerations

**This repository contains sensitive information in plaintext** (`roles/common/defaults/main.yml`):
- WiFi passwords
- User password hashes
- Static IP configurations

When modifying sensitive variables:
```bash
# Encrypt sensitive files
ansible-vault encrypt roles/common/defaults/main.yml

# Edit encrypted files
ansible-vault edit roles/common/defaults/main.yml

# View encrypted files
ansible-vault view roles/common/defaults/main.yml
```

## Target System Requirements

- **OS**: Arch Linux (uses pacman, AUR, systemd)
- **Network**: NetworkManager for network configuration
- **Python**: Python 3 interpreter at `/usr/bin/python3`
- **SSH**: SSH access with sudo privileges