# Developpers documentation

## Repository structure
 
```
dotfiles/
├── install.sh
├── scripts/
│   └── update.sh               ← dotfiles-update
├── packages/
│   ├── core.pkgs               ← always installed
│   ├── desktop.pkgs            ← always installed (automatic)
│   ├── aur.pkgs                ← AUR packages (paru)
│   ├── intel-cpu.pkgs          ← auto: Intel CPU
│   ├── amd-cpu.pkgs            ← auto: AMD CPU
│   ├── intel-gpu.pkgs          ← auto: Intel GPU
│   ├── amd-gpu.pkgs            ← auto: AMD GPU
│   ├── nvidia.pkgs             ← auto: NVIDIA GPU
│   ├── gaming.pkgs             ← optional
│   ├── development.pkgs        ← optional
│   ├── ...
│   ├── optional.groups         ← lists which groups are optional
│   └── <group>.desc            ← one-line description shown in installer
└── config/                     ← stow package; mirrors $HOME
    ├── .config/
    │   ├── hypr/
    │   ├── waybar/
    │   │   ├── vertical/
    │   │   └── horizontal/
    │   ├── rofi/
    │   └── ...
    └── .local/
        └── bin/
            └── atlas-update
```
 
### Package group conventions
 
| File | When installed |
|---|---|
| `core.pkgs` | Always |
| Any unlisted `*.pkgs` (e.g. `desktop.pkgs`) | Always (automatic) |
| `aur.pkgs` | Always, via paru |
| `intel-gpu.pkgs`, `amd-gpu.pkgs`, etc. | Auto-detected via `lspci` / `/proc/cpuinfo` |
| Groups listed in `optional.groups` | User-chosen during install, remembered on updates |
 
To add a new automatic group: create `packages/mygroup.pkgs` and commit.
To add a new optional group: also add its name to `packages/optional.groups` and optionally a `packages/mygroup.desc` one-liner.
 

## Package state tracking
 
After each install or update, a snapshot of every installed group is saved to `~/.dotfiles/.state/packages/<group>`. On the next run, each group is diffed:
 
- **New packages** in the `.pkgs` file → installed automatically
- **Removed packages** → you are asked before uninstalling
Delete `~/.dotfiles/.state/` to reset all state and force a full reinstall on the next update.