diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bebad9b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,30 @@
+# NixOS Personal Configs
+
+This repository contains the NixOS and Home Manager configuration for my
+personal computer. It is tailored to my hardware and workflow, so treat it as a
+reference rather than a drop-in template.
+
+## Disclaimer
+
+Not for production use. Use at your own risk.
+
+## Structure
+
+- `hosts/Nixos/configuration.nix`: main system configuration
+- `hosts/Nixos/hardware-configuration.nix`: hardware config (generated by NixOS)
+- `home/ltadeu6.nix`: Home Manager configuration
+- `configs/`: app configs (Hyprland, Waybar, Doom Emacs, etc.)
+- `secrets/`: agenix rules and encrypted secrets (no plaintext secrets)
+- `openclaw/`: OpenClaw documents
+
+## Notes
+
+- Secrets are managed with agenix and are not stored in plaintext in this repo.
+- This setup is specific to my machine; use with care if you copy anything.
+
+## Apply changes
+
+- Rebuild system:
+  `sudo nixos-rebuild switch --flake .#Nixos`
+- Basic syntax check:
+  `nix-instantiate --parse hosts/Nixos/configuration.nix`