diff --git a/README.md b/README.md
index c4154e6..b984b00 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ dot_config/
   paru/                         (arch-only) paru config
 
 run_once_00-install-bootstrap-tools.sh.tmpl
+run_once_05-install-hosts.sh.tmpl             merge LAN host entries into /etc/hosts
 run_once_10-add-chaotic-aur.sh.tmpl            (arch-only)
 run_once_20-install-user-packages.sh.tmpl
 run_onchange_30-ensure-cargo.sh.tmpl
@@ -32,43 +33,53 @@ run_onchange_30-ensure-cargo.sh.tmpl
 
 ## Onboarding a new box
 
-On a fresh debian-stable or arch-base install:
+**One command.** Copy/paste this on a fresh debian-stable or arch-base install:
 
 ```bash
-# 1. Install chezmoi binary itself (one-time, before this repo's run_once runs)
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/...")" -- -b "$HOME/.local/bin" \
+  && export PATH="$HOME/.local/bin:$PATH" \
+  && chezmoi init --apply https://git.melonbread.xyz/rain/gnu-plus-dotfiles.git
+```
+
+Or as a heredoc that installs chezmoi then runs the bootstrap (more verbose, easier to read):
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
 sh -c "$(curl -fsSL get.chezmoi.io)" -- -b "$HOME/.local/bin"
-
-# 2. Initialize from your repo (HTTPS — works without SSH keys on a fresh box)
 chezmoi init --apply https://git.melonbread.xyz/rain/gnu-plus-dotfiles.git
+```
 
-# 3. The bootstrap scripts run automatically. They will:
-#    - install age, git, curl (run_once_00)
-#    - on arch: add Chaotic-AUR + install paru (run_once_10)
-#    - install zsh, tmux, neovim, oh-my-zsh, all CLI tools, Maple Mono NF font (run_once_20)
-#    - install rustup if cargo missing (run_onchange_30)
+The bootstrap scripts run automatically as part of `chezmoi init --apply`. They will:
 
-# 4. Reboot or `exec zsh` to start using the new shell
+1. **run_once_00**: install `age`, `git`, `curl`, `ca-certificates` via the OS package manager
+2. **run_once_05**: merge LAN host entries (`miche.local`, `kaiser.local`, etc.) into `/etc/hosts` so omp/curl can resolve them
+3. **run_once_10** (arch only): add Chaotic-AUR repo + signing key, install `paru`
+4. **run_once_20**: install zsh, tmux, neovim (binary tarball, arch-aware URL), oh-my-zsh + plugins (autosuggestions, syntax-highlighting, history-substring-search, fzf-tab), tpm, all modern CLI tools (`bat` via cargo or PM, `btop`, `eza`, `fzf`, `fd`, `ripgrep`, `zoxide`, `starship`, `lazygit`, `yt-dlp`, `jq`, etc.), set zsh as login shell (via `sudo chsh`), install Maple Mono NF font (GitHub release zip)
+5. **run_onchange_30**: ensure rustup/cargo; install topgrade (`pacman` on arch via chaotic-aur, `cargo` on debian) and cargo-update
+
+After bootstrap completes (~5-10 min on x86_64, longer on aarch64 with `cargo install bat`):
+
+```bash
 exec zsh
 ```
 
-The first run will take a few minutes (downloading packages, cloning oh-my-zsh plugins, tpm, LazyVim plugins via nvim).
+fastfetch will run on shell start, starship prompt active, all tools on PATH.
 
-## Adding age encryption (when you have secrets)
+### Per-machine age key (required to decrypt secrets)
+
+The repo contains encrypted secrets (`~/.omp/agent/zai.key`, `~/.omp/agent/.env`) that only your per-machine age key can decrypt. After bootstrap, generate the key on this box:
 
 ```bash
-# On your main workstation:
-mkdir -p ~/.config/chezmoi/keys
-age-keygen -o ~/.config/chezmoi/keys/recovery.key
-# Save the printed secret key in your password manager.
-
-# On each machine, generate a per-machine identity:
 age-keygen -o ~/.config/chezmoi/key.txt
-# Paste the public key back to your main workstation.
-
-# In .chezmoi.yaml.tmpl, uncomment and fill the recipients block, then:
-chezmoi age rekey
+# Paste the printed public key into ~/.local/share/chezmoi/.chezmoi.yaml.tmpl
+# under the recipients list, then:
+cd ~/.local/share/chezmoi
+git pull
+# (You'll be prompted to add --force if you have local changes)
+chezmoi apply
 ```
 
+If you skip this step, the omp config files will still land (they're not encrypted), but `zai.key` and `.env` will be missing and omp won't be able to authenticate against providers.
 ## Editing dotfiles
 
 ```bash
diff --git a/run_once_05-install-hosts.sh.tmpl b/run_once_05-install-hosts.sh.tmpl
new file mode 100644
index 0000000..7462ec0
--- /dev/null
+++ b/run_once_05-install-hosts.sh.tmpl
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# =============================================================================
+#  run_once_05-install-hosts.sh.tmpl
+#  Merge LAN host entries into /etc/hosts so omp / config / curl can
+#  resolve miche.local, kaiser.local, etc. by name.
+#
+#  Idempotent: re-running this script is safe; it just rewrites the same
+#  block of LAN entries. Won't touch non-LAN entries.
+#
+#  Skipped on boxes where /etc/hosts is cloud-init managed (e.g. cloud
+#  VMs) — they need a different strategy (cloud-init module).
+# =============================================================================
+set -euo pipefail
+
+log() { printf '\033[1;34m[hosts]\033[0m %s\n' "$*"; }
+
+HOSTS_FILE="/etc/hosts"
+LAN_BLOCK_BEGIN="# >>> lan-hosts-managed-by-chezmoi >>>"
+LAN_BLOCK_END="# <<< lan-hosts-managed-by-chezmoi <<<"
+
+# Skip on cloud-init managed hosts
+if [[ -f /etc/cloud/cloud.cfg ]] && grep -q "manage_etc_hosts" /etc/cloud/cloud.cfg; then
+    log "WARNING: /etc/hosts is cloud-init managed on this box"
+    log "         add LAN host entries to your cloud-init config instead"
+    exit 0
+fi
+
+# LAN host entries to merge. Keep in sync with /etc/hosts on existing
+# boxes (miche, kaiser, byte) so all boxes agree.
+LAN_ENTRIES=$(cat <<'LAN_HOSTS'
+192.168.1.208	tadbit.local
+192.168.1.91	byte.local
+192.168.1.194	bit.local
+192.168.1.103	dayold.local
+192.168.1.212	rorclar.local
+192.168.1.153	ggbuttz.local
+192.168.1.219	bazzite.local
+192.168.1.107	crouton.local
+192.168.1.215	rye.local
+192.168.1.172	miche.local
+192.168.1.65	kaiser.local
+192.168.1.118	riska.local
+LAN_HOSTS
+)
+
+# Build the new block
+NEW_BLOCK="$LAN_BLOCK_BEGIN
+$LAN_ENTRIES
+$LAN_BLOCK_END"
+
+# Read current hosts file
+if [[ ! -f "$HOSTS_FILE" ]]; then
+    log "ERROR: $HOSTS_FILE missing — cannot merge LAN entries"
+    exit 1
+fi
+
+# If our block already exists, remove it first (so re-runs don't duplicate)
+if grep -q "$LAN_BLOCK_BEGIN" "$HOSTS_FILE"; then
+    log "removing old LAN block"
+    sudo cp "$HOSTS_FILE" "${HOSTS_FILE}.bak.$(date +%s)"
+    sudo sed -i "/$LAN_BLOCK_BEGIN/,/$LAN_BLOCK_END/d" "$HOSTS_FILE"
+fi
+
+# Append the new block
+log "appending LAN block to $HOSTS_FILE"
+echo "" | sudo tee -a "$HOSTS_FILE" >/dev/null
+echo "$NEW_BLOCK" | sudo tee -a "$HOSTS_FILE" >/dev/null
+echo "" | sudo tee -a "$HOSTS_FILE" >/dev/null
+
+# Verify by checking one of the entries
+if grep -q "miche.local" "$HOSTS_FILE"; then
+    log "verified miche.local is now resolvable"
+else
+    log "WARNING: miche.local not in $HOSTS_FILE after merge"
+fi
\ No newline at end of file