# AGENTS.md

Arch Linux ISO profile (archiso). Builds a live ISO with Hyprland desktop, end-4 dots-hyprland, and curated packages. Hosted on Gitea.

## Build & Test Commands

```bash
# Build the ISO (repo root IS the profile directory)
sudo mkarchiso -v -w work -o out/ .

# Build AUR deps for end-4 (run locally before ISO build if localrepo/ is stale)
./localrepo/build-end4-deps.sh          # build all
./localrepo/build-end4-deps.sh --quick  # skip large AUR pkgs

# Refresh localrepo DB after adding/moving .pkg.tar.zst files
./localrepo/update.sh                    # re-indexes existing packages
./localrepo/update.sh pkg1.pkg.tar.zst   # add files, then re-index
```

## CI Checks (must pass before merge)

- **ShellCheck**: all `.sh` files checked with `shellcheck -x -s bash`
- **yamllint**: all `.yml`/`.yaml` files (relaxed config)
- **packages.x86_64 syntax**: one package per line, no trailing whitespace, `[a-zA-Z0-9._@+\-]+` only
- **Package repo check**: every package in `packages.x86_64` must be resolvable via `pacman -Si` in allowed repos (`cachyos`, `extra`, `multilib`, `chaotic-aur`), OR have a pre-built `.pkg.tar.zst` in `localrepo/`, OR appear in `localrepo/build-end4-deps.sh`

## Package Management

**Three sources** contribute packages to the ISO:

1. **`packages.x86_64`** — main list, installed by mkarchiso. Must be in an allowed repo.
2. **`localrepo/*.pkg.tar.zst`** — pre-built AUR packages. The `local-aur` repo is configured in `pacman.conf` and picked up by mkarchiso automatically.
3. **`build-end4-deps.sh`** — builds end-4 AUR deps at build time.

**Important**: `localrepo/update.sh` auto-appends new package names to `packages.x86_64`. If you remove a package from `packages.x86_64` that exists in `localrepo/`, it will be re-added on the next `update.sh` run.

## Key Files

| File | Purpose |
|------|---------|
| `packages.x86_64` | Live ISO package list (~402 packages) |
| `profiledef.sh` | ISO metadata, compression, boot modes |
| `pacman.conf` | Repos: cachyos → core → extra → multilib → chaotic-aur → local-aur |
| `bootstrap_packages` | Minimal build-time packages (`base`, `arch-install-scripts`) |
| `airootfs/root/customize_airootfs.sh` | Runs inside chroot during build: keyrings, oh-my-zsh, lazy.nvim, plugins |
| `localrepo/build-end4-deps.sh` | Non-interactive AUR builds for end-4 dependencies |
| `localrepo/update.sh` | Regenerates localrepo DB + syncs names to packages.x86_64 |

## Gotchas

- The profile root is the **repo root** (not a `releng/` subdirectory). The CI build-iso workflow uses `mkarchiso -v -w work -o out/ releng` but this is a naming convention — the actual profile files live at the repo root.
- `customize_airootfs.sh` clones git repos (oh-my-zsh, lazy.nvim, plugins) into `/etc/skel` during the ISO build. These require network access at build time but make the live ISO work offline.
- The `[local-aur]` repo path in `pacman.conf` (`file:///home/alvin/alvinarch/localrepo`) is for local builds only. The CI does not use this path.
- End-4 metapackages are built from `localrepo/end4-pkgbuilds/` (quickshell-git, bibata-modern-classic-bin, microtex-git).
- `packages.x86_64` is sorted alphabetically. Keep it sorted when adding/removing entries.