docs: add GPL-3.0 LICENSE and initial README

Initial README. Personal values (emails, URLs, repo names, the temporary root password) are placeholders for the eventual public release. LICENSE is the canonical GPL-3.0 license text.

1 files changed, 163 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4a25f89
--- /dev/null
+++ b/README.md
@@ -0,0 +1,163 @@
+# archsetup
+
+Automated Arch Linux installation, dotfile management, and machine maintenance for a personal workstation, driven by a single Bash script, GNU Stow, and a handful of helper utilities.
+
+[Overview](#overview) | [Features](#features) | [Requirements](#requirements) | [Installation](#installation) | [Configuration](#configuration) | [Dotfile Management](#dotfile-management) | [Desktop Environments](#desktop-environments) | [Testing](#testing) | [Contributing](#contributing) | [License](#license)
+
+> **Note:** This is one person's personal Arch setup. It works as-is on that machine; if you fork it, change the hardcoded repositories and account details first (see [Configuration](#configuration)).
+
+## Overview
+
+archsetup turns a freshly installed Arch Linux box into a working desktop. It does three things:
+
+1. **Provisions the system.** The `archsetup` script installs packages, creates the primary user, builds suckless tools and an Emacs config from source, enables systemd services, sets up an AUR helper, configures the firewall, and installs a desktop environment (DWM on Xorg, or Hyprland on Wayland).
+2. **Manages dotfiles.** Configuration lives under `dotfiles/`, symlinked into `$HOME` by GNU Stow. A `Makefile` wraps the common Stow operations and adds an `fzf`-driven importer for new app configs.
+3. **Provides maintenance scripts.** Small utilities under `scripts/` and `dotfiles/*/.local/bin/` for VPN setup, post-install repo cloning, disk wiping, ZFS replication, and similar chores.
+
+The provisioning step is resumable: it records progress as marker files, so an interrupted run picks up where it left off. `archsetup --status` shows what's done; `archsetup --fresh` starts over.
+
+## Features
+
+- One-script system provisioning with per-step state tracking and resume
+- Pre-flight checks (root, disk space, network) before anything is touched
+- Interactive or fully unattended install (via a config file)
+- Choice of desktop environment: `dwm` (Xorg + DWM), `hyprland` (Wayland + Hyprland), or `none` (headless/server)
+- GPU driver auto-detection (skippable)
+- Optional automatic console login for encrypted-root systems
+- Builds suckless tools (dwm, dmenu, st, slock) and an Emacs config from configurable Git repos, compiled on a tmpfs RAM disk
+- Stow-managed dotfiles split into `common/`, `dwm/`, and `hyprland/` trees
+- `Makefile` targets for stow / restow / reset / unstow / import
+- Two-theme system (`dupre`, `hudson`) switchable with the `set-theme` script
+- VM-based integration test harness (QEMU/KVM) that installs into a throwaway VM and validates the result
+- Logs everything to `/var/log/archsetup-*.log`
+
+## Requirements
+
+- A booted Arch Linux live ISO (for the initial OS install), or an already-installed Arch system (to run `archsetup`)
+- UEFI firmware (the test harness and typical installs assume UEFI)
+- A network connection
+- `git`, `make`, `stow`, and `fzf` for the dotfile workflow (`make deps` installs these)
+- For the test harness: `qemu-full`, `sshpass`, OVMF firmware, `socat`, and KVM support (`make deps` or `scripts/testing/setup-testing-env.sh`)
+
+## Installation
+
+### 1. Install Arch (live ISO bootstrap)
+
+Boot any Arch Linux ISO from a USB stick and run the bootstrap script:
+
+```sh
+curl -s https://<your-domain>/archsetup/init | sh
+```
+
+`init` installs `git` and `tmux`, sets a temporary `root` password, and starts `sshd` so you can finish the install remotely. Then it launches `archinstall` to partition the disk and install the base system. (You can also do the base install by hand; `init` is just a convenience.)
+
+### 2. Run archsetup on the installed system
+
+Boot into the new install, clone this repo, and run the provisioning script as root:
+
+```sh
+git clone https://github.com/yourusername/archsetup.git
+cd archsetup
+sudo ./archsetup
+```
+
+The script prompts for the username, password, locale, and (on encrypted systems) autologin, unless you supply them via a config file.
+
+#### `archsetup` options
+
+```
+Usage: ./archsetup [OPTIONS]
+
+  --config-file PATH    Use a config file for unattended installation
+  --fresh               Start fresh, ignore previous progress
+  --status              Show installation progress and exit
+  --no-gpu-drivers      Skip GPU driver detection/installation
+  --autologin           Enable automatic console login
+  --no-autologin        Disable automatic console login
+  --help, -h            Show this help message
+```
+
+### 3. Link the dotfiles
+
+```sh
+make stow dwm         # Xorg + DWM
+# or
+make stow hyprland    # Wayland + Hyprland
+```
+
+## Configuration
+
+For an unattended install, copy the template and edit it:
+
+```sh
+cp archsetup.conf.example archsetup.conf
+./archsetup --config-file archsetup.conf
+```
+
+Every field has a default. Set only what you want to change. The config covers:
+
+- `USERNAME` / `PASSWORD`: primary user account (prompted if unset)
+- `AUTOLOGIN`: `yes`/`no`, automatic console login (only relevant with encrypted root)
+- `NO_GPU_DRIVERS`: `yes` to skip GPU driver auto-detection
+- `LOCALE`: e.g. `en_US.UTF-8`
+- `DESKTOP_ENV`: `dwm`, `hyprland`, or `none`
+- `DWM_REPO`, `DMENU_REPO`, `ST_REPO`, `SLOCK_REPO`, `DOTEMACS_REPO`, `ARCHSETUP_REPO`: Git URLs for the suckless tools, the Emacs config, and this repo
+
+> **Forking note:** The upstream defaults point at the original author's personal Git server and assume a particular username. If you're adapting this for yourself, override the `*_REPO` variables in `archsetup.conf` to point at your own forks. Also review `scripts/post-install.sh` and `scripts/gitrepos.sh` — they clone personal repositories you won't want. The `archsetup` header, `init`'s temporary root password, and a handful of dotfiles (`.gitconfig`, `.ssh/config`, etc.) also carry author-specific values.
+
+## Dotfile Management
+
+Dotfiles live under `dotfiles/` and are stowed into `$HOME` with GNU Stow. The tree splits three ways:
+
+- `dotfiles/common/` — shared by every setup (shell config, `~/.local/bin` scripts, app configs that don't depend on the display server)
+- `dotfiles/dwm/` — Xorg/DWM-specific configs and scripts
+- `dotfiles/hyprland/` — Wayland/Hyprland-specific configs and scripts
+
+`make stow <de>` links `common` plus the chosen DE tree. The `Makefile` drives all of it:
+
+```
+make stow dwm          # Fresh install: link common + dwm
+make stow hyprland     # Fresh install: link common + hyprland
+make restow dwm        # Refresh links after a git pull (prompts on conflicts)
+make reset hyprland    # Resolve conflicts by keeping the repo version
+make unstow dwm        # Remove all symlinks
+make import common     # fzf-pick app configs and import them into dotfiles/common/
+make import dwm        # ...into dotfiles/dwm/
+make import hyprland   # ...into dotfiles/hyprland/
+make deps              # Install stow, fzf, and the VM-test toolchain
+make help              # Full target list
+```
+
+`make import` scans `~`, `~/.config`, and `~/.local` for config directories not yet in the repo, lets you multi-select with `fzf`, moves them into the chosen tree, and re-stows so the originals become symlinks. It reminds you to commit afterwards.
+
+### Theme system
+
+Two themes ship in the repo, `dupre` (default) and `hudson`. Switch with the `set-theme` script (installed via the `common` dotfiles). Theme files live under `dotfiles/hyprland/.config/themes/<theme>/` and cover foot, fuzzel, waybar, dunst, hyprlock, and Xresources.
+
+## Desktop Environments
+
+- **DWM (Xorg).** The `dwm` desktop env builds dwm, dmenu, st, and slock from the configured Git repos and links the `dwm` dotfile tree. DWM keybindings live in that fork's `config.def.h`.
+- **Hyprland (Wayland).** The `hyprland` desktop env installs Hyprland and links the `hyprland` dotfile tree, including a waybar/foot/fuzzel/dunst/hyprlock stack themed to match.
+
+Pick the desktop env at install time with `DESKTOP_ENV` in the config file (or accept the prompt/default), then link the matching dotfiles with `make stow dwm` or `make stow hyprland`.
+
+## Testing
+
+archsetup ships a VM-based integration test harness under `scripts/testing/`. It uses QEMU/KVM directly (no libvirt) to install Arch into a throwaway VM, run `archsetup` inside it, and validate the result: user creation, stowed dotfiles, AUR helper, desktop environment, services, firewall, and package set.
+
+```sh
+make deps              # Install qemu-full, sshpass, OVMF, socat (one-time)
+make test              # Create the base VM if needed, then run the full test
+make test-keep         # Same, but leave the VM running for manual inspection
+make test-vm-base      # (Re)create the base VM only
+```
+
+Results land in `test-results/<timestamp>/` (logs, a summary report, and package lists). See `scripts/testing/README.org` for the full workflow, the cleanup and debug helpers, and the validation checks.
+
+## Contributing
+
+This is a personal setup, but bug reports and pull requests are welcome, especially fixes that make it easier to fork. If you're sending a change, keep the `common` / `dwm` / `hyprland` dotfile split intact and run `make test` (or at least `bash -n archsetup`) before opening a PR.
+
+## License
+
+[GPL-3.0](LICENSE)