diff --git a/README.md b/README.md
index 6e68425..a8f6dd4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,44 @@
-# dotfiles
+# Gentoo Hyprland dotfiles
 
-Desktop configuration files for my Gentoo setup.
\ No newline at end of file
+My desktop setup lives here: a mostly keyboard-driven Hyprland session, a narrow Quickshell bar down the left edge, and a restrained charcoal palette with steel-blue accents. The configs are tuned to my machine, so expect to adjust paths and hardware-specific bits before using them elsewhere.
+
+![Desktop with the Quickshell side bar and media notification](screenshots/desktop.png)
+
+## What’s in the repo
+
+| Path | What it configures |
+| --- | --- |
+| `.config/hypr/` | Hyprland layout, animations, key bindings, monitor defaults, and startup commands |
+| `.config/quickshell/` | The bar, app launcher, wallpaper picker, system tray, quick settings, and power menu |
+| `.config/foot/` | Foot terminal font, spacing, scrollback, key bindings, and matching colors |
+| `.config/fish/` | Interactive shell defaults, including a quiet greeting and `vim` alias |
+| `.config/fastfetch/` | System summary shown in the terminal |
+
+## The desktop
+
+Hyprland uses a compact dwindle layout, small gaps, subtle borders, and short window animations. `SUPER+E` opens Foot, `SUPER+D` opens the Quickshell launcher, and `SUPER+P` opens the wallpaper picker. The config also binds workspace navigation, media keys, volume, brightness, screenshots, and power actions.
+
+Quickshell handles the things I want at a glance or one click away: workspace and status indicators, audio and media controls, Wi-Fi and Bluetooth, battery and brightness, night light, calendar, tray menus, and power controls. Its panels share Foot’s dark colors, with blue for focus and olive green for battery status.
+
+![Battery and brightness panel](screenshots/battery-panel.png)
+
+![Audio devices and volume controls](screenshots/audio-panel.png)
+
+Foot uses Maple Mono at 9 pt, 14 px padding, and a 10,000-line scrollback. The palette carries through to Quickshell; Fish keeps startup quiet, while Fastfetch prints the system summary when I need it.
+
+![Volume on-screen display](screenshots/volume-osd.png)
+
+## Software
+
+- **Session and shell:** Gentoo Linux, Hyprland, Quickshell, Fish
+- **Terminal and system display:** Foot, Fastfetch
+- **Desktop services:** Hyprpaper, PipeWire, NetworkManager, BlueZ
+- **Controls and utilities:** `pactl`, `wpctl`, `playerctl`, `brightnessctl`, `hyprsunset`, `nmcli`, `bluetoothctl`, `grim`, `slurp`, and `wl-clip-persist`
+
+The config expects Maple Mono, the Bibata Modern Classic cursor, and a GTK theme named `KVJ`. It also calls `~/.local/bin/wallpaper-set` and looks for wallpapers in `~/Pictures/Wallpapers`; those aren’t included here. Some actions use `doas`, so review those commands and your `doas` rules before enabling them.
+
+## Using these files
+
+Clone the repo and copy the `.config` directories you want into your home directory. There’s no install script; check the paths and commands in `hyprland.lua` and `shell.qml` first, since several are specific to my setup.
+
+Keep API keys, passwords, private keys, and machine-specific secrets out of the repo. Store those in a local, untracked file or a password manager.
diff --git a/screenshots/audio-panel.png b/screenshots/audio-panel.png
new file mode 100644
index 0000000..c239793
Binary files /dev/null and b/screenshots/audio-panel.png differ
diff --git a/screenshots/battery-panel.png b/screenshots/battery-panel.png
new file mode 100644
index 0000000..dc4f4cd
Binary files /dev/null and b/screenshots/battery-panel.png differ
diff --git a/screenshots/desktop.png b/screenshots/desktop.png
new file mode 100644
index 0000000..f4fe304
Binary files /dev/null and b/screenshots/desktop.png differ
diff --git a/screenshots/volume-osd.png b/screenshots/volume-osd.png
new file mode 100644
index 0000000..6828a2d
Binary files /dev/null and b/screenshots/volume-osd.png differ