From b5ce26f244666b4becb68412bb8dab152d996d00 Mon Sep 17 00:00:00 2001
From: Alex Blank <alexblank@fastmail.com>
Date: Mon, 27 Jul 2026 15:24:01 +0200
Subject: [PATCH] docs: refresh README

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..19d268c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# Dotfiles
+
+Personal, Arch-oriented user dotfiles and support scripts for shells, window management, applications, and package lists. This repository is a collection of machine-specific configuration, not a general-purpose installer.
+
+## Status and scope
+
+There is no authoritative root installation, linking, backup, overwrite, or rollback script. Do not infer one: review and apply only the individual files appropriate to a machine. Some filenames use `##class.arch_*` suffixes to distinguish machine classes. The repository also includes a nested README for the custom/vendored `st` terminal under `.config/st/`; it documents that component, not installation of this repository.
+
+Several scripts assume paths below `~/.setup`, Arch tooling, and root access. Some repository scripts contain machine-specific connection details; do not publish, copy, or document such values. Use local, private configuration for hosts, addresses, accounts, and credentials.
+
+## Prerequisites
+
+- An Arch-based system for the supplied `pacman`/`yay` package workflows.
+- The package manager or helper required by the script being considered (`pacman` and/or `yay`).
+- Desktop/session tools matching the chosen configuration (for example X11/XMonad-related files where applicable).
+- Root access only for the system-changing scripts described below.
+
+Package lists in `.setup/packages/` are inputs for a user-managed installation; no repository command defines how to install an entire list. Inspect package names and select lists for the intended machine before installing anything.
+
+## Safe review and user-level configuration
+
+Start by reviewing the intended files and any machine-class variants. Typical areas are:
+
+- `.zshrc`, `.bashrc`, `.terminal_aliases`, `.tmux.conf`, and `.p10k.zsh` — shell and terminal setup.
+- `.xmonad/`, `.Xresources##class.*`, `.xprofile##class.*`, and `.config/` — desktop/window-manager and application configuration.
+- `.scripts/` — optional shell, network, virtual-environment, and update helpers.
+- `.setup/packages/` — package lists grouped by purpose.
+
+Back up existing configuration before manually placing or linking a file. No test suite is provided; validate a change in the relevant shell/session or application and keep a rollback copy of the previous configuration.
+
+## Package updates
+
+`.scripts/updating.sh` defines, but does not invoke, two functions. It expects `~/.setup/packages/exclude_from_updating.list`:
+
+```sh
+source .scripts/updating.sh
+update_system
+# or
+update_pacman_packages
+```
+
+> **Warning: system-wide, potentially disruptive operation.** `update_system` runs `yay -Syu` and `update_pacman_packages` runs `sudo pacman -Syu`, both non-interactively and with the exclusion list. Review the exclusion list and pending package changes first. These functions update the running system; they are not tests.
+
+## System-changing scripts
+
+The following scripts mutate files outside this repository and must be inspected before use:
+
+- `.setup/config/setup_touchpad.sh` copies an X11 configuration into `/etc/X11/xorg.conf.d/` when absent.
+- `.setup/config/exclude_from_update.sh` edits `/etc/pacman.conf` with `sudo` based on `~/.setup/packages/exclude_from_updating.list`.
+- `.setup/config/dinit_add_logs_to_all_services.sh` edits files in `/etc/dinit.d` and writes log specifications under `/var/log/dinit`; its `-o` option removes existing logfile lines before adding them.
+
+> **Warning: destructive/system-wide operations.** These scripts can alter system package policy, service definitions, or input configuration. They have no repository-provided dry run or rollback. Run only on a machine you control after backups and after checking paths, permissions, and the script contents.
+
+`.setup/config/set_default_programs.sh` sets the default HTTP/HTTPS handler through `xdg-mime`; review the desktop entry before using it.
+
+## Custom `st` terminal
+
+The nested `.config/st/README.md` documents its own `make` and `sudo make install` workflow. Those commands build/install only that terminal component, may modify the system, and are not a bootstrap procedure for all dotfiles.