diff --git a/README.md b/README.md
index b97e9ea..27c5b85 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,17 @@
 
 NixOS configuration for my Framework 12 laptop aka chi. Everything here is subject to change, and is for my own personal use.
 
-It's widely vibe coded togther, but seems to be stable. I'm not doing anything that difficult here, and goes to show that anyone can waste electricity. 
+It's widely vibe coded togther, but seems to be stable. I'm not doing anything that difficult here, and goes to show that anyone can waste electricity.
+
+## structure
+
+```
+hosts/chi/          — host-specific config (chi, a Framework 12 laptop)
+modules/common.nix  — shared settings (locale, firewall, fonts, nix settings)
+home/mollyw.nix     — Home Manager config (shell, editors, apps, dotfiles)
+secrets/            — agenix secrets scaffolding (empty, for future use)
+wallpapers/         — catppuccin-mocha gradient wallpaper
+```
 
 ## notes