diff --git a/chaotic-aur/README.md b/chaotic-aur/README.md
new file mode 100644
index 0000000..36de676
--- /dev/null
+++ b/chaotic-aur/README.md
@@ -0,0 +1,15 @@
+# Chaotic-AUR
+
+## Files
+
+### `chaotic.sh`
+Automated installer/enabler for the [Chaotic-AUR](https://chaotic.cx/) repository on Arch Linux. Idempotent — if Chaotic-AUR is already configured in `pacman.conf`, it skips setup and runs an update instead.
+
+**What it does:**
+1. Checks if Chaotic-AUR is already enabled; if so, updates `chaotic-keyring` and exits
+1. Downloads the mirrorlist to `/etc/pacman.d/chaotic-mirrorlist`
+1. Runs `pacman -Syu` to ensure the system is up to date
+1. Receives and signs the Chaotic-AUR GPG key
+1. Installs `chaotic-keyring` and `chaotic-mirrorlist` packages
+1. Appends the `[chaotic-aur]` section to `/etc/pacman.conf`
+1. Refreshes the pacman database
diff --git a/zsh/README.md b/zsh/README.md
new file mode 100644
index 0000000..bf5aa17
--- /dev/null
+++ b/zsh/README.md
@@ -0,0 +1,12 @@
+# Zsh Config
+
+## Files
+
+### `zshrc`
+Main Zsh configuration file. Sets up Oh My Zsh, plugins (git, sudo, eza, fzf, starship, etc.), history options, aliases, and auto-updates itself from a remote source. Also bootstraps tmux config and runs a fastfetch system info display on interactive shells.
+
+### `zshrc-bootstrap.zsh`
+One-shot setup script executed by `zshrc`. Installs missing dependencies (starship, lazydocker, fastfetch, eza, fzf, etc.) via the system package manager (brew, apt, dnf, pacman) or cargo, clones Oh My Zsh and custom plugins (zsh-autosuggestions, fast-syntax-highlighting, fzf-tab). Runs only when the bootstrap version changes.
+
+### `tmux.conf`
+Tmux configuration with GitHub Dark theming, Nerd Font auto-install, TPM plugin manager, pane/window keybindings (Vim-style navigation with `h/j/k/l`), status bar showing session info, battery, online status, and a built-in cheatsheet (bound to `prefix + ?`).