diff --git a/.zshenv b/.zshenv
index 692bac4..a4df88a 100644
--- a/.zshenv
+++ b/.zshenv
@@ -1,5 +1,8 @@
+# Homebrew on macOS. .zshenv runs for every zsh (interactive, scripts, GUI-launched),
+# and brew shellenv needs a readable CWD: cd to a safe dir first so launching from a
+# TCC-protected directory (e.g. ~/Documents) does not break the eval or prompt for access.
 if [ -x /opt/homebrew/bin/brew ]; then
-    eval "$(/opt/homebrew/bin/brew shellenv)"
+    eval "$(cd /tmp && /opt/homebrew/bin/brew shellenv)"
 elif [ -x /usr/local/bin/brew ]; then
-    eval "$(/usr/local/bin/brew shellenv)"
+    eval "$(cd /tmp && /usr/local/bin/brew shellenv)"
 fi
diff --git a/.zshrc b/.zshrc
index a60630f..da29a5d 100644
--- a/.zshrc
+++ b/.zshrc
@@ -151,14 +151,9 @@ autoload -U compinit && compinit -C -d ~/.cache/zsh/.zcompdump        # zsh-comp
 SAVEHIST=50000      #save upto 50,000 lines in history. oh-my-zsh default is 10,000
 #setopt hist_ignore_all_dups     # dont record duplicated entries in history during a single session
 
-alias myip="wget -qO- https://wtfismyip.com/text"	# quickly show external ip address
-alias l="eza --hyperlink -lA --sort=modified --reverse --classify"    # show all except . .. , sort by recent, / at the end of folders, clickable
-alias e="exit"
-alias ip="ip --color=auto"
-## EZA - the better ls command
-alias a='eza -la --git --colour-scale all -g --smart-group --icons always --hyperlink'  # the new ls; add --hyperlink if you like
-alias aa='eza -la --git --colour-scale all -g --smart-group --icons always -s modified -r --hyperlink'  # sort by new
-
+# NOTE: personal aliases that must win over oh-my-zsh are defined AFTER
+# `source "$ZSH/oh-my-zsh.sh"` below, because oh-my-zsh's lib/directories.zsh
+# re-defines several of them (e.g. `l`) when it loads.
 
 # CUSTOM FUNCTIONS
 
@@ -217,6 +212,16 @@ source "$ZSH/oh-my-zsh.sh"
 
 # Configs that can only work after "source $ZSH/oh-my-zsh.sh", such as Aliases that depend oh-my-zsh plugins
 
+# Personal aliases. Defined after oh-my-zsh so they win over oh-my-zsh's own
+# aliases (lib/directories.zsh sets `l`, `ll`, etc. when it loads).
+alias myip="wget -qO- https://wtfismyip.com/text"	# quickly show external ip address
+alias l="eza --hyperlink -lA --sort=modified --reverse --classify"    # show all except . .. , sort by recent, / at the end of folders, clickable
+alias e="exit"
+alias ip="ip --color=auto"
+## EZA - the better ls command
+alias a='eza -la --git --colour-scale all -g --smart-group --icons always --hyperlink'  # the new ls; add --hyperlink if you like
+alias aa='eza -la --git --colour-scale all -g --smart-group --icons always -s modified -r --hyperlink'  # sort by new
+
 # ponytail: Trash aliases accept paths, not every rm flag; add a wrapper only if flag compatibility is required.
 if [[ "$OSTYPE" == darwin* && -x /usr/bin/trash ]]; then
     alias rm='/usr/bin/trash'
diff --git a/README.md b/README.md
index bbff3cf..e92f0c1 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,40 @@
-# Easy Zsh Setup
\ No newline at end of file
+# Easy Zsh Setup
+
+One-command zsh environment: oh-my-zsh, powerlevel10k, and a curated plugin set
+(autosuggestions, syntax-highlighting, completions, history-substring-search,
+fzf-tab, k), plus eza, zoxide, fzf, and Nerd Fonts.
+
+## Install
+
+```bash
+curl -fsSL https://git.miomio.moe/mio/easyzsh/raw/branch/master/install.sh | bash
+```
+
+Options: `--cp-hist` / `-c` imports bash history; `--non-interactive` / `-n`
+skips the default-shell change. The installer backs up an existing `~/.zshrc`
+and `~/.zshenv` before replacing them.
+
+## Personal configuration
+
+`~/.zshrc` is meant to stay close to this repo's canonical version. Put your own
+tweaks in `~/.config/zshrc/` instead of editing `~/.zshrc` directly: every
+`*.zsh` file there is sourced near the end of `~/.zshrc`, just before oh-my-zsh
+loads, so it can add plugins and override defaults.
+
+```bash
+# ~/.config/zshrc/my.zsh
+plugins+=(zsh-nvm)                 # add plugins
+plugins=(${plugins:#zsh-autosuggestions})   # or remove one
+alias gs='git status'
+```
+
+Ready-made configs from this repo's `zshrc/` directory (`fnm`, `nvm`, `pyenv`,
+`merlin_devbox`, `merlin_worker`, `personal`, `p10k`) can be pulled in by name:
+
+```bash
+curl -fsSL https://git.miomio.moe/mio/easyzsh/raw/branch/master/patch.sh | bash -s -- fnm pyenv
+```
+
+Because these files load before oh-my-zsh, plugin and theme changes take effect;
+aliases that must beat oh-my-zsh's own should be defined after oh-my-zsh loads
+(see the note in `~/.zshrc`).