From 40e1db0bf9b4817d33ca13a8b9b66defc04f1ea5 Mon Sep 17 00:00:00 2001
From: Jan Ehrhardt <jan.ehrhardt@cozybytes.tech>
Date: Wed, 3 Dec 2025 22:07:24 +0100
Subject: [PATCH] Update documentation

---
 README.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 163 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 3c7a369..1c8da6d 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,198 @@
 # dotfiles
 
-My dotfiles for CachyOS, managed by [chezmoi](https://www.chezmoi.io).
+My dotfiles for Arch Linux.
 
 ## Usage
 
 ### Prerequisits
 
-- [CachyOS Desktop Edition](https://cachyos.org/download/)
-- [LazyVim config](https://www.lazyvim.org/installation)
+I use CachyOS, which is an Arch Linux based distro with some nice benefits:
+
+- Kernel and packages compiled with Zen 4 (AMD) support
+- Desktop environment selection during installation
+- Good defaults ([Alacritty](https://alacritty.org), [fish](https://fishshell.com), [paru](https://github.com/Morganamilo/paru))
+- Many useful packages pre-installed (libfido2, fprintd, bat)
+
+First, install [CachyOS Desktop Edition](https://cachyos.org/download/) and select Limine as a bootloader and Hyprland as desktop environment.
 
 ### Setup
 
-#### Required packages
+After first boot login to Hyprland (uwsm) and open a terminal (defaults to kitty).
 
-Install required packages:
+#### Install required Hyprland packages
+
+My Hyprland setup depends on the following additional packages:
+
+```bash
+paru -S \
+  xdg-desktop-portal-gtk \
+  qt5-wayland \
+  qt6-wayland \
+  hypridle \
+  waybar \
+  swaybg \
+  swayosd \
+  wl-clip-persist \
+  zen-browser-bin \
+  yazi \
+  btop \
+  bluetui \
+  impala
+```
+
+I prefer [iwd as Wifi back-end of NetworkManager](https://wiki.archlinux.org/title/NetworkManager#Using_iwd_as_the_Wi-Fi_backend). Once configured, restart the service:
+
+```bash
+sudo systemctl restart NetworkManager.service
+```
+
+Wifi must be reconfigured now.
+
+#### Create SSH key
+
+Generate a new SSH key protected by Yubikey (default location, no passphrase):
+
+```bash
+ssh-keygen -t ed25519-sk -C jan.ehrhardt@cozybytes.tech
+```
+
+#### Setup fingerprint reader
+
+I prefer to use the fingerprint reader to unlock my laptop and authorize `sudo` commands in my terminal.
+
+#### Setup Neovim
+
+Install the required packages:
+
+```bash
+paru -S \
+  neovim \
+  tree-sitter-cli
+```
+
+I use LazyVim, which is a Neovim distro with good defaults for programming. Install it by [following the instructions](https://www.lazyvim.org/installation).
+
+#### Setup terminal
+
+Install additional packages for my terminal setup:
 
 ```bash
 paru -S \
-  chezmoi \
-  ttf-firacode-nerd \
-  libfido2 \
-  fprintd \
   starship \
   zellij \
   eza \
   zoxide \
   atuin \
-  mise \
-  yazy \
-  github-cli \
-  lazygit \
-  tree-sitter-cli \
-  neovim \
+  mise
+```
+
+Login to atuin and sync history:
+
+```bash
+atuin login
+atuin sync
+```
+
+#### Setup dotfiles
+
+I use [chezmoi](https://www.chezmoi.io) to manage my dotfiles. First, install it:
+
+```bash
+paru -S chezmoi
+```
+
+Then apply the dotfiles from my Git repo:
+
+```bash
+chezmoi init --ssh --apply git@tangled.org:jehrhardt.dev/dotfiles
+```
+
+This will automatically configure the system.
+
+#### Install development tools
+
+I use several tools for development that are not configured via my dotfiles, but need to be setup.
+
+##### OpenCode
+
+I use OpenCode as my preferred coding agent. Some of the reasons:
+
+- Nice TUI
+- Supports different models and providers
+- It works really well
+
+Install it:
+
+```bash
+paru -S opencode-bin
+```
+
+##### Docker and Supabase CLI
+
+Supabase CLI uses Docker to run locally. This is nice for development.
+
+Install required packages:
+
+```bash
+paru -S \
+  supabase-bin \
   lazydocker \
   docker \
   docker-buildx \
   docker-compose
 ```
 
-#### SSH key
+Enable Docker service:
+
+```bash
+sudo systemctl enable docker.service
+```
+
+Give yourself permission to access Docker daemon:
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+##### Rust
+
+I use [mise](https://mise.jdx.dev) to setup development environments including programming languages. Rust is the only exception as I prefer [rustup](https://rustup.rs).
 
-Generate a new SSH key protected by Yubikey (default location, no passphrase)
+It can be installed as a package:
 
 ```bash
-ssh-keygen -t ed25519-sk -C jan.ehrhardt@cozybytes.tech
+paru -S rustup
 ```
 
-#### Setup dotfiles
+I use stable toolchain:
+
+```bash
+rustup install stable
+```
 
-Init and apply chezmoi:
+##### Python via `uv`
+
+I vibe code Python for automation and experimentation and my preferred way to handle it is `uv`.
+
+Install it via mise:
+
+```bash
+mise use --global uv
+```
+
+Then install completions:
 
 ```bash
-chezmoi init --ssh --apply jehrhardt
+echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish
+echo 'uvx --generate-shell-completion fish | source' > ~/.config/fish/completions/uvx.fish
 ```
 
-This will automatically install and configure the system.
+##### Node.js
+
+Plenty of tools (e.g. language servers used by Neovim) require Node.js to present.
+
+Install LTS version via mise:
+
+```bash
+mise use --global node@lts
+```
-- 
2.51.2