diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index d6e3a1c..fa54a16 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -70,7 +70,7 @@ jobs:
path: ${{ github.workspace }}/iso/
- name: Upload to Internet Archive
- if: github.ref == 'refs/heads/master'
+ if: false # temporarily disabled until ISO is stable
env:
IA_ACCESS_KEY: ${{ secrets.IA_ACCESS_KEY }}
IA_SECRET_KEY: ${{ secrets.IA_SECRET_KEY }}
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..228b0b0
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,55 @@
+name: Deploy docs to Pages
+
+on:
+ push:
+ branches: ["master"]
+ paths: ["docs/**"]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: "pages"
+ cancel-in-progress: true
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: docs
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+ - name: Setup Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: '3.3'
+ bundler-cache: true
+ cache-version: 0
+ working-directory: '${{ github.workspace }}/docs'
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v6
+ - name: Build with Jekyll
+ run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+ env:
+ JEKYLL_ENV: production
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v4
+ with:
+ path: docs/_site/
+
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v5
diff --git a/.gitignore b/.gitignore
index 5b16a54..6889476 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@ work/
iso/
out/
install.log
+docs/_site/
diff --git a/AGENTS.md b/AGENTS.md
index e7720ac..d7b60a4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,7 @@ git config user.email "ash8820@proton.me"
## The Crusade
- **Artix Linux** ISO (OpenRC init), forked from EndeavourOS-ISO, then migrated to artools after 15 days in a vent shaft
- **KDE Plasma** live environment with Calamares installer (offline + online modes)
-- **Build command**: `export WORKSPACE_DIR="$PWD" && sudo buildiso -p antergos`
+- **Build command**: `export WORKSPACE_DIR="$PWD" && sudo ./buildiso -p antergos` — **use `./buildiso`**, NOT `buildiso`; the system Artix `/usr/bin/buildiso` lacks `--overwrite='*'` and will fail with file conflicts
- ISO appears in `/var/lib/artools/buildiso/iso/antergos/` (assuming the build gods are pleased)
## Antergos NeXT Repos
diff --git a/README.md b/README.md
index a503d79..91273b5 100644
--- a/README.md
+++ b/README.md
@@ -50,9 +50,11 @@ mkdir -p ~/.config/artools/pacman.conf.d
cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/
# Build
-sudo buildiso -p antergos
+sudo ./buildiso -p antergos
```
+> **⚠️ VERY IMPORTANT**: Use `./buildiso`, not `buildiso`. The Artix system `buildiso` at `/usr/bin/buildiso` lacks the `--overwrite='*'` flag passed to `basestrap`, causing file conflicts (e.g. `calamares` vs `calamares-branding-antergos-next` both claiming `/usr/share/calamares/branding/default/`). Our repo's `./buildiso` has it.
+
The `.iso` appears in `/var/lib/artools/buildiso/iso/antergos/`.
First build pulls ~5 GB from the internet. Subsequent builds use pacman cache.
diff --git a/docs/Gemfile b/docs/Gemfile
new file mode 100644
index 0000000..78cd6f7
--- /dev/null
+++ b/docs/Gemfile
@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.4.1"
+gem "just-the-docs", "0.12.0"
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..83d071a
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1,28 @@
+title: Antergos NeXT
+description: >-
+ A community revival of Antergos — Artix Linux, OpenRC, KDE Plasma, Calamares
+theme: just-the-docs
+
+color_scheme: dark
+
+url: "https://antergos-next.github.io"
+baseurl: "/antergos-iso"
+
+aux_links:
+ "Antergos NeXT on GitHub":
+ - "https://github.com/Antergos-NeXT/antergos-iso"
+aux_links_new_tab: true
+
+heading_anchors: true
+search_enabled: true
+search:
+ heading_level: 3
+ previews: 3
+
+back_to_top: true
+back_to_top_text: "Back to top"
+
+footer_content: "Copyright © Antergos NeXT contributors. Distributed under the GPL-3.0 License."
+
+plugins:
+ - jekyll-seo-tag
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 0000000..f91eb94
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,60 @@
+---
+title: Building
+layout: default
+nav_order: 2
+---
+
+# Building the ISO
+
+Requires an **Artix-based** system with `artools` and `squashfs-tools`.
+
+## Prerequisites
+
+```bash
+pacman -S artools squashfs-tools
+modprobe loop
+```
+
+## Clone and configure
+
+```bash
+git clone https://github.com/Antergos-NeXT/antergos-iso.git
+cd antergos-iso
+
+export WORKSPACE_DIR="$PWD"
+
+# Override pacman config with our repo (antergos-pkgs)
+mkdir -p ~/.config/artools/pacman.conf.d
+cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/
+```
+
+## Build
+
+```bash
+sudo -E ./buildiso -p antergos
+```
+
+> **⚠️ Use `./buildiso`, not `buildiso`.** The Artix system `/usr/bin/buildiso` lacks the `--overwrite='*'` flag, causing file conflicts between `calamares` and `calamares-branding-antergos-next` (both claim `/usr/share/calamares/branding/default/`). Our repo's `./buildiso` has it.
+
+## Output
+
+The ISO appears in `/var/lib/artools/buildiso/iso/antergos/`.
+
+First build pulls ~5 GB from the internet. Subsequent builds use pacman cache. Go make a coffee. Or two. Maybe three.
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WORKSPACE_DIR` | Must point to repo root. `buildiso` looks for profiles under `$WORKSPACE_DIR/iso-profiles/` |
+| `COMPRESSION` | Squashfs compression type (e.g. `zstd`). If unset, `mksquashfs` fails silently with a zero-size image |
+
+## Custom packages repo
+
+The ISO pulls branding, Calamares config, and wallpapers from our custom repo. To use it on your system:
+
+```ini
+[antergos-pkgs]
+SigLevel = Optional TrustAll
+Server = https://antergos-next.github.io/antergos-packages
+```
diff --git a/docs/ci.md b/docs/ci.md
new file mode 100644
index 0000000..3d0e600
--- /dev/null
+++ b/docs/ci.md
@@ -0,0 +1,43 @@
+---
+title: CI/CD
+layout: default
+nav_order: 5
+---
+
+# CI/CD Pipeline
+
+Two GitHub Actions workflows:
+
+## Build ISO (`build.yml`)
+
+Triggers on push/PR to `master`. Runs in an `artixlinux/artixlinux:base` container.
+
+Steps:
+1. Install dependencies (artools, squashfs-tools, git, sudo, python)
+2. Set `WORKSPACE_DIR` to the checkout path
+3. Override pacman config with `[antergos-pkgs]` repo
+4. Mount a 12 GB tmpfs at `/var/lib/artools/buildiso`
+5. Run `./buildiso -p antergos`
+6. Upload the ISO directory as a build artifact
+
+### Internet Archive upload
+
+Currently **disabled** (`if: false`) until ISO is stable. When enabled, uploads the built ISO to the Internet Archive with metadata:
+
+- Collection: `open_source_software`
+- Access keys: `IA_ACCESS_KEY`, `IA_SECRET_KEY` (repo secrets)
+
+### Secrets
+
+| Secret | Purpose |
+|--------|---------|
+| `IA_ACCESS_KEY` | Internet Archive S3 access key |
+| `IA_SECRET_KEY` | Internet Archive S3 secret key |
+
+## Deploy docs (`pages.yml`)
+
+Triggers on push to `master` only when files under `docs/` change. Builds a Jekyll site from `docs/` using the Just the Docs theme and deploys to GitHub Pages.
+
+## antergos-packages CI
+
+Separate workflow in the [antergos-packages](https://github.com/Antergos-NeXT/antergos-packages) repo. Builds all packages listed in `packages.yaml` and publishes them to GitHub Pages as a pacman repo.
diff --git a/docs/desktop-environments.md b/docs/desktop-environments.md
new file mode 100644
index 0000000..8b4fa90
--- /dev/null
+++ b/docs/desktop-environments.md
@@ -0,0 +1,94 @@
+---
+title: Desktop Environments
+layout: default
+nav_order: 7
+---
+
+# Desktop Environments
+
+Available desktops in online mode, sourced from Artix repos.
+
+## Plasma (KDE)
+
+| | |
+|---|---|
+| **Repo** | world |
+| **Group** | `plasma` |
+| **Session** | `plasma.desktop` (Wayland) / `plasmax11.desktop` (X11) |
+| **Notes** | Default DE. Wayland is the default session. `plasma-wayland-session` is NOT a separate package on Artix — it's bundled in `plasma-workspace` |
+
+## Xfce
+
+| | |
+|---|---|
+| **Repo** | galaxy |
+| **Group** | `xfce4` |
+| **Session** | `xfce.desktop` |
+
+## Cinnamon
+
+| | |
+|---|---|
+| **Repo** | galaxy |
+| **Packages** | Individual (no meta-group) |
+| **Session** | `cinnamon.desktop` |
+
+## MATE
+
+| | |
+|---|---|
+| **Repo** | galaxy |
+| **Groups** | `mate` + `mate-extra` |
+| **Session** | `mate.desktop` |
+
+## LXQt
+
+| | |
+|---|---|
+| **Repo** | galaxy |
+| **Group** | `lxqt` |
+| **Session** | `lxqt.desktop` |
+
+## i3
+
+| | |
+|---|---|
+| **Repo** | world |
+| **Group** | `i3` |
+| **Session** | `i3.desktop` |
+
+## Sway
+
+| | |
+|---|---|
+| **Repo** | world |
+| **Packages** | `sway` + related |
+| **Session** | `sway.desktop` |
+
+## Hyprland
+
+| | |
+|---|---|
+| **Repo** | world |
+| **Packages** | `hyprland` |
+| **Session** | `hyprland.desktop` |
+
+## GNOME
+
+| | |
+|---|---|
+| **Repo** | imaginary |
+| **Group** | `gnome-systemd-hub` |
+| **Session** | `does-not-exist.desktop` |
+| **Status** | ❌ |
+
+> You really think you can get GNOME here? GNOME deleted all other init support. Take a walk.
+
+## Not available
+
+- **Budgie** — not in any Artix repo (system, world, galaxy, lib32). Slideshow entries removed.
+- **GNOME** — see above.
+
+## No Desktop
+
+Installs the base system only (TTY/login). Useful for servers or custom setups.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..034d917
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,86 @@
+---
+title: Development
+layout: default
+nav_order: 6
+---
+
+# Development
+
+## Critical gotchas
+
+### `./buildiso` vs `buildiso`
+
+Always use the repo's `./buildiso`, **not** the system Artix `/usr/bin/buildiso`. The system version lacks `--overwrite='*'` and will fail with file conflicts between `calamares` and `calamares-branding-antergos-next`.
+
+### `sudo -E` is required
+
+Without `-E`, `WORKSPACE_DIR` is stripped and `load_profile()` returns empty `HAS_LIVE`/`LIVEUSER`, causing build failures.
+
+### Pacman config must be user-overridden
+
+`buildiso` reads from `~/.config/artools/pacman.conf.d/iso-x86_64.conf`. If missing, it falls back to the Artix default at `/usr/share/artools/pacman.conf.d/iso-x86_64.conf` which lacks `[antergos-pkgs]`.
+
+```bash
+mkdir -p ~/.config/artools/pacman.conf.d
+cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/
+```
+
+### Squashfs compression
+
+If `$COMPRESSION` is unset in config, `mksquashfs` produces a sparse zero file instead of a valid squashfs. Always verify compression is set, or remove stale images before retry.
+
+### Calamares module precedence
+
+`/etc/calamares/modules/` overrides `/usr/share/calamares/modules/`. Live-overlay online/offline directories override both.
+
+### Live-overlay is not overlay-mounted
+
+Live-overlay files are copied via `cp -LR` in `make_livefs()`. Deleting a file from live-overlay exposes the package version, not hides it. Use `NoDisplay=true` in `.desktop` files instead.
+
+### `plasma-wayland-session` does not exist on Artix
+
+Artix bundles the Wayland session into `plasma-workspace` itself. Do not add it to package lists.
+
+### File conflicts
+
+`calamares` and `calamares-branding-antergos-next` both install to `/usr/share/calamares/branding/default/`. Handled by `--overwrite='*'`.
+
+### `calamares-next.sh SetConfig()`
+
+Must `rm -f` the symlink at `/etc/calamares/settings.conf` before `cp`, otherwise `cp` follows the symlink and overwrites the offline config file instead of replacing it.
+
+### Do not push commits while IA keys are set
+
+Test ISOs manually first. IA credentials are set as repo secrets and will trigger an upload on push to master.
+
+## Profile structure
+
+```
+iso-profiles/
+├── antergos/
+│ ├── profile.yaml # Packages, services (rootfs + livefs)
+│ ├── root-overlay/ # Merged into squashfs rootfs
+│ └── live-overlay/ # Merged into live environment
+└── common/
+ └── common.yaml # Shared base packages
+```
+
+## Building locally
+
+```bash
+export WORKSPACE_DIR="$PWD"
+sudo -E ./buildiso -p antergos
+```
+
+### A Note to the "Branding Police"
+
+If you came here to hate and you're about to type "why are you using Antergos's branding" — pack your bags and go to **Manjaro**. We have Dustin's blessing. We are respectful. We are not them. Move on.
+
+## Testing
+
+Boot the resulting ISO in a VM. Verify:
+- Wayland is the default display server (SDDM session is `plasma.desktop`)
+- No "Install Artix Linux" entry in the app menu
+- Wallpaper is set on first login
+- Online mode: init selector + DE selector both work
+- Slideshow renders correctly
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..0996622
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,36 @@
+---
+title: Home
+layout: home
+nav_order: 1
+---
+
+# Antergos NeXT
+
+> **Migration complete!** Antergos NeXT has migrated from systemd/Arch to OpenRC/Artix. Builds are stable, the installer works.
+
+A community revival of Antergos — built on **Artix Linux** with **OpenRC**, **KDE Plasma**, and the **Calamares** installer (offline + online modes).
+
+## Quick links
+
+- [Building the ISO](building) — set up and build locally
+- [Installer](installer) — Calamares modes, init & DE selectors
+- [Custom packages](packages) — PKGBUILDs, repo setup
+- [CI/CD](ci) — GitHub Actions pipeline
+- [Development](development) — contributing, gotchas, conventions
+
+## What changed
+
+| Area | Original Antergos | Antergos NeXT |
+|------|-------------------|---------------|
+| Base | Arch Linux (systemd) | Artix Linux (OpenRC) |
+| Desktop | GNOME | KDE Plasma |
+| Installer | Custom Cnchi | Calamares |
+| Build | archiso | artools (`buildiso`) |
+
+## Sources
+
+- [Artix Linux](https://artixlinux.org)
+- [artools](https://gitea.artixlinux.org/artix/artools)
+- [Calamares](https://codeberg.org/calamares/calamares)
+- [antergos-packages](https://github.com/Antergos-NeXT/antergos-packages)
+- [Original wallpapers](https://github.com/Antergos/wallpapers)
diff --git a/docs/installer.md b/docs/installer.md
new file mode 100644
index 0000000..cc32bbb
--- /dev/null
+++ b/docs/installer.md
@@ -0,0 +1,60 @@
+---
+title: Installer
+layout: default
+nav_order: 3
+---
+
+# Calamares Installer
+
+Uses [Calamares](https://codeberg.org/calamares/calamares) with two modes and custom branding.
+
+## Modes
+
+| Mode | Description |
+|------|-------------|
+| **Offline** | Unpacks a KDE Plasma squashfs — no internet needed |
+| **Online** | Netinstall with init system choice + desktop selection |
+
+The launcher (`calamares-next`) presents a mode picker before launching Calamares.
+
+## Key differences from upstream
+
+- `dracut`/`dracutlukscfg` replaced with `initcpiocfg`/`initcpio`/`luksopenswaphookcfg` (Artix uses mkinitcpio, not dracut)
+- `services-openrc` module instead of `services-systemd`
+- `removeuser` step removed, `postcfg` added
+- `packagechooser` module compiled in (upstream skips it)
+
+## Init system selector (online)
+
+Users choose from: **OpenRC**, **Runit**, **S6**, **Dinit**.
+
+Implemented as a `packagechooser` instance with `method: netinstall-add` — the selected init pulls its associated packages.
+
+## Desktop selector (online)
+
+Users choose from: **Plasma**, **Xfce**, **Cinnamon**, **MATE**, **LXQt**, **i3**, **Sway**, **Hyprland**, or **No Desktop**.
+
+Implemented as a separate `packagechooser` instance with `method: legacy`. "No Desktop" installs only the base system (TTY-only).
+
+## Available desktops
+
+| Desktop | Artix Repo | Group/Packages |
+|---------|------------|----------------|
+| Plasma | world | `plasma` group |
+| Xfce | galaxy | `xfce4` group |
+| Cinnamon | galaxy | Individual packages |
+| MATE | galaxy | `mate` + `mate-extra` groups |
+| LXQt | galaxy | `lxqt` group |
+| i3 | world | `i3` group |
+| Sway | world | `sway` + related packages |
+| Hyprland | world | `hyprland` |
+
+> **Note:** Budgie is not available in any Artix repo and has been removed from all configs and slideshows.
+
+## Offline mode
+
+No packagechooser. Uses `unpackfs` to deploy a pre-built KDE Plasma squashfs, then `initcpiocfg` + `initcpio` for mkinitcpio configuration.
+
+## Branding
+
+Custom branding lives in the `calamares-branding-antergos-next` package, installed to `/etc/calamares/branding/default/`. The `componentName` in `branding.desc` must match its directory name.
diff --git a/docs/launcher.md b/docs/launcher.md
new file mode 100644
index 0000000..e3fb3c6
--- /dev/null
+++ b/docs/launcher.md
@@ -0,0 +1,46 @@
+---
+title: Launcher
+layout: default
+nav_order: 9
+---
+
+# Calamares Launcher
+
+The `calamares-next` script (`calamares-next.sh`) handles the installer boot flow.
+
+## Flow
+
+1. **Mode picker** — Dialog asking Offline or Online install
+2. **Configuration** — Copies the appropriate `settings.conf` (offline or online) to `/etc/calamares/settings.conf`
+3. **Launch** — Runs `calamares` with the selected config
+
+## Launcher location
+
+Installed by `calamares-branding-antergos-next` to `/usr/bin/calamares-next`.
+
+## Desktop entry
+
+`/usr/share/applications/calamares.desktop` in the live-overlay launches with:
+
+```
+Exec=sudo -E calamares-next
+```
+
+Note: `sudo -E` preserves environment variables (required for `WAYLAND_DISPLAY`, `XDG_CURRENT_DESKTOP`, etc. when launched from the SDDM session).
+
+## Mode picker (dialog)
+
+A simple `kdialog` or `zenity` dialog:
+- **Offline** — No internet required, installs KDE Plasma from squashfs
+- **Online** — Init system selector + DE selector via packagechooser, downloads packages from the internet
+
+## Config switching
+
+`SetConfig()` in `calamares-next.sh`:
+1. Removes existing symlink at `/etc/calamares/settings.conf` (must `rm -f` first, not overwrite, or `cp` follows the symlink)
+2. Copies the selected settings file
+3. Calamares reads the config on launch
+
+## Hiding "Install Artix"
+
+The live-overlay includes `calamares-config-switcher.desktop` with `NoDisplay=true` — this hides the upstream Artix launcher while keeping the binary available.
diff --git a/docs/overlay-live.md b/docs/overlay-live.md
new file mode 100644
index 0000000..57f831c
--- /dev/null
+++ b/docs/overlay-live.md
@@ -0,0 +1,64 @@
+---
+title: Live Overlay
+layout: default
+parent: Overlays
+nav_order: 2
+---
+
+# Live Overlay
+
+Files in `iso-profiles/antergos/live-overlay/` exist only in the live environment — they are **not** present after installation.
+
+## Contents
+
+```
+live-overlay/
+├── etc/
+│ ├── calamares/
+│ │ ├── settings.conf # -> symlinks to online or offline
+│ ├── calamares-offline/
+│ │ ├── settings.conf # Offline install config (unpackfs)
+│ │ └── modules/
+│ │ └── ...
+│ ├── calamares-online/
+│ │ ├── settings.conf # Online install config (packagechooser)
+│ │ └── modules/
+│ │ ├── packagechooser_init.conf # Init system selector
+│ │ ├── packagechooser_desktop.conf # DE selector
+│ │ └── ...
+│ └── sddm.conf.d/
+│ └── kde_settings.conf # SDDM autologin + Wayland session
+└── usr/
+ └── share/
+ └── applications/
+ ├── calamares.desktop # Branded launcher
+ └── calamares-config-switcher.desktop # Hidden (NoDisplay=true)
+```
+
+## Key files
+
+### `etc/calamares/settings.conf`
+
+Symlink — points to either `../calamares-offline/settings.conf` or `../calamares-online/settings.conf`, set by `calamares-next.sh`.
+
+### `etc/calamares-online/settings.conf`
+
+Two `packagechooser` instances:
+- `packagechooser@init` — init system (OpenRC, Runit, S6, Dinit) via netinstall-add
+- `packagechooser@desktop` — DE selection via legacy method
+
+### `etc/calamares-online/modules/packagechooser_init.conf`
+
+Init selector config. Uses `method: netinstall-add` — the selected init pulls its associated packages.
+
+### `etc/calamares-online/modules/packagechooser_desktop.conf`
+
+DE selector config. Uses `method: legacy` — returns the selected DE as a global storage value.
+
+### `etc/calamares-offline/settings.conf`
+
+No packagechooser. Uses `unpackfs` to deploy a pre-built KDE Plasma squashfs.
+
+### `usr/share/applications/calamares-config-switcher.desktop`
+
+Has `NoDisplay=true` to hide it from the app menu. The upstream Artix "Install Artix Linux" entry is suppressed this way.
diff --git a/docs/overlay-root.md b/docs/overlay-root.md
new file mode 100644
index 0000000..b1696e1
--- /dev/null
+++ b/docs/overlay-root.md
@@ -0,0 +1,51 @@
+---
+title: Root Overlay
+layout: default
+parent: Overlays
+nav_order: 1
+---
+
+# Root Overlay
+
+Files in `iso-profiles/antergos/root-overlay/` are merged into the root squashfs and become part of the installed system.
+
+## Contents
+
+```
+root-overlay/
+├── etc/
+│ ├── os-release # Antergos NeXT branding
+│ ├── pacman.conf # Includes [antergos-pkgs] repo
+│ ├── sddm.conf.d/
+│ │ └── kde_settings.conf # SDDM theme + Wayland session
+│ └── skel/
+│ └── .config/
+│ └── autostart/
+│ └── antergos-wallpaper.desktop # One-shot wallpaper setter
+└── usr/
+ └── local/
+ └── bin/
+ └── set-antergos-wallpaper.sh # Wallpaper script
+```
+
+## Key files
+
+### `etc/os-release`
+
+Identifies the system as "Antergos NeXT" to tools, installers, and the login manager.
+
+### `etc/pacman.conf`
+
+Adds the `[antergos-pkgs]` custom repo so installed systems can receive updates.
+
+### `etc/sddm.conf.d/kde_settings.conf`
+
+Sets the SDDM session to `plasma.desktop` (Wayland) by default.
+
+### `etc/skel/.config/autostart/antergos-wallpaper.desktop`
+
+Runs the wallpaper setter on first login. Uses `X-KDE-autostart-phase=2` to run after Plasma has initialized.
+
+### `usr/local/bin/set-antergos-wallpaper.sh`
+
+Applies the wallpaper via `plasma-apply-wallpaperimage` and creates `~/.config/antergos-wallpaper-set` marker to prevent re-running.
diff --git a/docs/overlays.md b/docs/overlays.md
new file mode 100644
index 0000000..fd755bf
--- /dev/null
+++ b/docs/overlays.md
@@ -0,0 +1,28 @@
+---
+title: Overlays
+layout: default
+nav_order: 10
+has_children: true
+---
+
+# Overlays
+
+Two directories under `iso-profiles/antergos/` control what goes into the ISO.
+
+```
+iso-profiles/antergos/
+├── profile.yaml
+├── root-overlay/ # → rootfs (squashfs)
+└── live-overlay/ # → live environment (initramfs)
+```
+
+## How overlays work
+
+- `root-overlay/` files are merged into the root squashfs — they become part of the installed system
+- `live-overlay/` files are copied into the live environment only — they're not present after installation
+- Overlays are **self-contained** (no symlinks to external directories) so the repo builds standalone
+- Live-overlay files are **copied** via `cp -LR` in `make_livefs()`, not overlay-mounted. Deleting a file from live-overlay exposes the package version underneath
+
+> **Disclaimer:** No symlinks were harmed in the making of this ISO. Well, maybe a few. We killed some.
+
+> Also: this ISO is 100% systemd-free. Not even a trace. We checked. Twice.
diff --git a/docs/packages.md b/docs/packages.md
new file mode 100644
index 0000000..4e243d5
--- /dev/null
+++ b/docs/packages.md
@@ -0,0 +1,58 @@
+---
+title: Packages
+layout: default
+nav_order: 4
+---
+
+# Custom Packages
+
+Custom PKGBUILDs live in the [antergos-packages](https://github.com/Antergos-NeXT/antergos-packages) repo.
+
+## Package list
+
+| Package | Purpose |
+|---------|---------|
+| `calamares` | Built with `packagechooser` module enabled, `dracut`/`initramfs` modules skipped |
+| `calamares-branding-antergos-next` | Branding files: `branding.desc`, `show.qml`, `settings.conf`, `packagechooser.conf`, `initcpiocfg.conf`, `initcpio.conf`, `calamares-next.sh` |
+| `antergos-wallpapers` | Default wallpapers installed to `/usr/share/wallpapers/` (KDE) and `/usr/share/backgrounds/` (other DEs) |
+| `linux-next` | Custom kernel based on `linux-artix` |
+| `winver` | "About Antergos NeXT" dialog built with KF6 + Qt6 |
+
+## Repo setup
+
+```ini
+[antergos-pkgs]
+SigLevel = Optional TrustAll
+Server = https://antergos-next.github.io/antergos-packages
+```
+
+## Build system
+
+Packages are built and published via CI. The build order is defined in `packages.yaml`. AUR packages (`yay`, `downgrade`) are included with retry logic for transient clone failures.
+
+## Index
+
+The package index (`index.db`, `index.files`) is generated with timestamps in **Europe/Berlin** timezone. See `generate-index.py`.
+
+## PKGBUILD notes
+
+### calamares
+
+- `_skip_modules` includes `dracut`, `initramfs`, `initramfscfg` — these are Artix/systemd-holdovers not needed on OpenRC/mkinitcpio
+- `-DCMAKE_DISTRIBUTION_NAME` is a **no-op** — Calamares ignores it. The "for " text comes from `versionedName` in the active branding component at runtime
+
+### calamares-branding-antergos-next
+
+- `packagechooser.conf` provides a DE-only fallback for standalone use
+- `settings_offline.conf` / `settings_online.conf` override live-overlay settings at install time
+- `calamares-next.sh` `SetConfig()` must remove the symlink before copying config, or it follows the link and overwrites the wrong file
+
+### antergos-wallpapers
+
+- Installs to `/usr/share/wallpapers/antergos-wallpaper/` with `metadata.desktop` for KDE picker support
+- Also available at `/usr/share/backgrounds/antergos/` for other DEs
+- Current wallpaper: GNOME Adwaita Morning (`adwaita-morning.webp`, CC BY-SA 3.0 by Jakub Steiner)
+
+## File conflict notes
+
+`calamares` and `calamares-branding-antergos-next` both claim `/usr/share/calamares/branding/default/branding.desc` and `show.qml`. Resolved at ISO build time via `--overwrite='*'` in repo's `./buildiso`.
diff --git a/docs/wallpapers.md b/docs/wallpapers.md
new file mode 100644
index 0000000..c3b2d46
--- /dev/null
+++ b/docs/wallpapers.md
@@ -0,0 +1,46 @@
+---
+title: Wallpapers
+layout: default
+nav_order: 8
+---
+
+# Wallpapers
+
+The `antergos-wallpapers` package provides default wallpapers for the live session and installed system.
+
+## Current wallpaper
+
+GNOME **Adwaita Morning** (`adwaita-morning.webp`) — 7680×4320, CC BY-SA 3.0 by Jakub Steiner / GNOME Project.
+
+## Installation paths
+
+| Path | Purpose |
+|------|---------|
+| `/usr/share/wallpapers/antergos-wallpaper/` | KDE wallpaper picker (requires `metadata.desktop`) |
+| `/usr/share/backgrounds/antergos/` | Other DEs / fallback |
+
+## How it appears in KDE
+
+KDE's wallpaper picker scans `/usr/share/wallpapers/` for directories containing a `metadata.desktop` file. The `metadata.desktop` format:
+
+```ini
+[Wallpaper]
+name=Antergos NeXT
+filename=adwaita-morning.webp
+```
+
+## Set on first login
+
+Since Plasma overwrites `/etc/skel/.config/plasma-org.kde.plasma.desktop-appletsrc` on first login, the wallpaper is applied via a one-shot autostart script:
+
+1. `/usr/local/bin/set-antergos-wallpaper.sh` — runs `plasma-apply-wallpaperimage`, creates marker file `~/.config/antergos-wallpaper-set`
+2. `~/.config/autostart/antergos-wallpaper.desktop` — calls the script with `X-KDE-autostart-phase=2`
+
+The marker file prevents the script from running on subsequent logins.
+
+## Customizing
+
+To replace the wallpaper, update:
+- `packages/antergos-wallpapers/PKGBUILD` (source + checksum)
+- `packages/antergos-wallpapers/adwaita-morning.webp`
+- `packages/antergos-wallpapers/metadata.desktop` (if changing name)
diff --git a/iso-profiles/antergos/live-overlay/etc/calamares-online/modules/packagechooser_desktop.conf b/iso-profiles/antergos/live-overlay/etc/calamares-online/modules/packagechooser_desktop.conf
new file mode 100644
index 0000000..15ad7c2
--- /dev/null
+++ b/iso-profiles/antergos/live-overlay/etc/calamares-online/modules/packagechooser_desktop.conf
@@ -0,0 +1,55 @@
+---
+mode: required
+method: legacy
+labels:
+ step: "Desktop Environment"
+items:
+ - id: ""
+ name: "No Desktop"
+ description: "Install without a desktop environment — not recommended. You'll only get a TTY; screen recording won't work without a capture card."
+ - id: plasma
+ packages: [ plasma ]
+ name: "Plasma"
+ description: "KDE Plasma Desktop — modern, feature-rich, highly customizable"
+ - id: xfce
+ packages: [ xfce4, xfce4-goodies ]
+ name: "Xfce"
+ description: "Xfce — lightweight, classic desktop"
+ - id: cinnamon
+ packages:
+ - cinnamon
+ - cinnamon-control-center
+ - cinnamon-desktop
+ - cinnamon-menus
+ - cinnamon-screensaver
+ - cinnamon-session
+ - cinnamon-settings-daemon
+ - cinnamon-translations
+ name: "Cinnamon"
+ description: "Cinnamon — traditional desktop with modern conventions"
+ - id: mate
+ packages: [ mate, mate-extra ]
+ name: "MATE"
+ description: "MATE — continuation of GNOME 2"
+ - id: lxqt
+ packages: [ lxqt ]
+ name: "LXQt"
+ description: "LXQt — lightweight Qt desktop"
+ - id: i3
+ packages: [ i3 ]
+ name: "i3"
+ description: "i3 — tiling window manager"
+ - id: sway
+ packages:
+ - sway
+ - swaybg
+ - swayidle
+ - swaylock
+ name: "Sway"
+ description: "Sway — i3-compatible Wayland compositor"
+ - id: hyprland
+ packages:
+ - hyprland
+ - xdg-desktop-portal-hyprland
+ name: "Hyprland"
+ description: "Hyprland — dynamic tiling Wayland compositor"
diff --git a/iso-profiles/antergos/live-overlay/etc/calamares-online/modules/packagechooser_init.conf b/iso-profiles/antergos/live-overlay/etc/calamares-online/modules/packagechooser_init.conf
new file mode 100644
index 0000000..748302c
--- /dev/null
+++ b/iso-profiles/antergos/live-overlay/etc/calamares-online/modules/packagechooser_init.conf
@@ -0,0 +1,294 @@
+---
+mode: required
+
+method: netinstall-add
+
+labels:
+ step: "Init selection"
+ step[de]: "Initauswahl"
+
+default: OpenRC
+
+items:
+ - id: OpenRC
+ name: openrc
+ description: "OpenRC init system"
+ screenshot: ":/images/if.png"
+ netinstall:
+ name: "openrc"
+ description: "OpenRC init system"
+ selected: false
+ critical: true
+ immutable: false
+ expanded: true
+ hidden: false
+ subgroups:
+ - name: "Default"
+ description: "Default services"
+ selected: true
+ hidden: true
+ packages:
+ - audit-openrc
+ - cryptsetup-openrc
+ - dbus-openrc
+ - dhcpcd-openrc
+ - lvm2-openrc
+ - mdadm-openrc
+ - name: "Cron"
+ description: "Cron init"
+ selected: true
+ packages:
+ - cronie-openrc
+ - name: "Syslog"
+ description: "Syslog init"
+ packages:
+ - syslog-ng-openrc
+ - metalog-openrc
+ - name: "Internet"
+ description: "Network init"
+ packages:
+ - avahi-openrc
+ - bluez-openrc
+ - iptables-openrc
+ - krb5-openrc
+ - networkmanager-openrc
+ - nfs-utils-openrc
+ - ntp-openrc
+ - openldap-openrc
+ - openssh-openrc
+ - rpcbind-openrc
+ - xinetd-openrc
+ - wpa_supplicant-openrc
+ - name: "Office"
+ description: "Office init"
+ packages:
+ - cups-openrc
+ - sane-openrc
+ - name: "Services"
+ description: "Services init"
+ packages:
+ - acpid-openrc
+ - alsa-utils-openrc
+ - apparmor-openrc
+ - brltty-openrc
+ - fuse-openrc
+ - gpm-openrc
+ - hdparm-openrc
+ - haveged-openrc
+ - lm_sensors-openrc
+ - openrc-settingsd
+ - openvpn-openrc
+ - power-profiles-daemon-openrc
+ - rsync-openrc
+
+ - id: Dinit
+ name: dinit
+ description: "Dinit init system"
+ screenshot: ":/images/if.png"
+ netinstall:
+ name: "dinit"
+ description: "Dinit init system"
+ selected: false
+ critical: true
+ immutable: false
+ expanded: true
+ hidden: false
+ subgroups:
+ - name: "Default"
+ description: "Default services"
+ selected: true
+ hidden: true
+ packages:
+ - audit-dinit
+ - cryptsetup-dinit
+ - dbus-dinit
+ - dhcpcd-dinit
+ - lvm2-dinit
+ - mdadm-dinit
+ - name: "Cron"
+ description: "Cron init"
+ selected: true
+ packages:
+ - cronie-dinit
+ - name: "Syslog"
+ description: "Syslog init"
+ packages:
+ - syslog-ng-dinit
+ - metalog-dinit
+ - name: "Internet"
+ description: "Network init"
+ packages:
+ - avahi-dinit
+ - bluez-dinit
+ - iptables-dinit
+ - krb5-dinit
+ - networkmanager-dinit
+ - nfs-utils-dinit
+ - ntp-dinit
+ - openldap-dinit
+ - openssh-dinit
+ - rpcbind-dinit
+ - xinetd-dinit
+ - wpa_supplicant-dinit
+ - name: "Office"
+ description: "Office init"
+ packages:
+ - cups-dinit
+ - sane-dinit
+ - name: "Services"
+ description: "Services init"
+ packages:
+ - acpid-dinit
+ - alsa-utils-dinit
+ - apparmor-dinit
+ - brltty-dinit
+ - fuse-dinit
+ - gpm-dinit
+ - hdparm-dinit
+ - haveged-dinit
+ - lm_sensors-dinit
+ - openvpn-dinit
+ - power-profiles-daemon-dinit
+ - rsync-dinit
+
+ - id: S6
+ name: s6
+ description: "S6 init system"
+ screenshot: ":/images/if.png"
+ netinstall:
+ name: "s6"
+ description: "S6 init system"
+ selected: false
+ critical: true
+ immutable: false
+ expanded: true
+ hidden: false
+ subgroups:
+ - name: "Default"
+ description: "Default services"
+ selected: true
+ hidden: true
+ packages:
+ - audit-s6
+ - cryptsetup-s6
+ - dbus-s6
+ - dhcpcd-s6
+ - lvm2-s6
+ - mdadm-s6
+ - s6-contrib
+ - name: "Cron"
+ description: "Cron init"
+ selected: true
+ packages:
+ - cronie-s6
+ - name: "Syslog"
+ description: "Syslog init"
+ packages:
+ - syslog-ng-s6
+ - metalog-s6
+ - name: "Internet"
+ description: "Network init"
+ packages:
+ - avahi-s6
+ - bluez-s6
+ - iptables-s6
+ - krb5-s6
+ - networkmanager-s6
+ - nfs-utils-s6
+ - ntp-s6
+ - openldap-s6
+ - openssh-s6
+ - rpcbind-s6
+ - xinetd-s6
+ - wpa_supplicant-s6
+ - name: "Office"
+ description: "Office init"
+ packages:
+ - cups-s6
+ - sane-s6
+ - name: "Services"
+ description: "Services init"
+ packages:
+ - acpid-s6
+ - alsa-utils-s6
+ - apparmor-s6
+ - brltty-s6
+ - fuse-s6
+ - gpm-s6
+ - hdparm-s6
+ - haveged-s6
+ - lm_sensors-s6
+ - openvpn-s6
+ - power-profiles-daemon-s6
+ - rsync-s6
+
+ - id: Runit
+ name: runit
+ description: "Runit init system"
+ screenshot: ":/images/if.png"
+ netinstall:
+ name: "runit"
+ description: "Runit init system"
+ selected: false
+ critical: true
+ immutable: false
+ expanded: true
+ hidden: false
+ subgroups:
+ - name: "Default"
+ description: "Default services"
+ selected: true
+ hidden: true
+ packages:
+ - audit-runit
+ - cryptsetup-runit
+ - dbus-runit
+ - dhcpcd-runit
+ - lvm2-runit
+ - mdadm-runit
+ - rsm
+ - name: "Cron"
+ description: "Cron init"
+ selected: true
+ packages:
+ - cronie-runit
+ - name: "Syslog"
+ description: "Syslog init"
+ packages:
+ - syslog-ng-runit
+ - metalog-runit
+ - name: "Internet"
+ description: "Network init"
+ packages:
+ - avahi-runit
+ - bluez-runit
+ - iptables-runit
+ - krb5-runit
+ - networkmanager-runit
+ - nfs-utils-runit
+ - ntp-runit
+ - openldap-runit
+ - openssh-runit
+ - rpcbind-runit
+ - xinetd-runit
+ - wpa_supplicant-runit
+ - name: "Office"
+ description: "Office init"
+ packages:
+ - cups-runit
+ - sane-runit
+ - name: "Services"
+ description: "Services init"
+ packages:
+ - acpid-runit
+ - alsa-utils-runit
+ - apparmor-runit
+ - brltty-runit
+ - fuse-runit
+ - gpm-runit
+ - hdparm-runit
+ - haveged-runit
+ - lm_sensors-runit
+ - openvpn-runit
+ - power-profiles-daemon-runit
+ - rsync-runit
diff --git a/iso-profiles/antergos/live-overlay/etc/calamares-online/settings.conf b/iso-profiles/antergos/live-overlay/etc/calamares-online/settings.conf
index 89da7cf..01a3161 100644
--- a/iso-profiles/antergos/live-overlay/etc/calamares-online/settings.conf
+++ b/iso-profiles/antergos/live-overlay/etc/calamares-online/settings.conf
@@ -1,12 +1,21 @@
---
modules-search: [ local ]
+instances:
+ - id: init
+ module: packagechooser
+ config: packagechooser_init.conf
+ - id: desktop
+ module: packagechooser
+ config: packagechooser_desktop.conf
+
sequence:
- show:
- welcome
- locale
- keyboard
- - packagechooser
+ - packagechooser@init
+ - packagechooser@desktop
- netinstall
- partition
- users