zsh: add zsh dotfiles

zsh/README.md

@@ -0,0 +1,47 @@
+# zsh
+
+GNU Stow package for my zsh setup. Stowed from the repo root with the
+`.stowrc` defaults (`--dotfiles --target=$HOME`), i.e.:
+
+```sh
+stow zsh        # stow (idempotent, safe to re-run)
+stow -R zsh     # re-stow after adding/removing files in this package
+stow -D zsh     # unstow
+```
+
+## Layout
+
+| In this repo            | Becomes (symlink)     |
+|-------------------------|-----------------------|
+| `dot-zshrc`             | `~/.zshrc`            |
+| `.zsh/alias.zsh`        | `~/.zsh/alias.zsh`    |
+
+Other dirs under `~/.zsh/` (e.g. `local/`, `completions/`) are **not**
+managed by stow — they are plain host-side directories and never touch
+this repo.
+
+## Host-local config: `~/.zsh/local`
+
+`~/.zshrc` sources every `*.zsh` file in `~/.zsh/local/` at the **end**
+of the file, in alphabetical order — so anything there can override
+aliases, PATH, env vars, etc. set earlier.
+
+This is the place for **host-specific, non-shared** config: business/work
+inits, private env vars, machine-specific paths, per-host aliases and
+functions.
+
+The directory is **not** in the repo — it exists only on each host, so
+after cloning + stowing on a new machine, create it once:
+
+```sh
+mkdir -p ~/.zsh/local
+```
+
+(The sourcing loop in `.zshrc` tolerates the directory being missing.)
+
+## Notes
+
+- Editing existing files (`.zshrc`, `alias.zsh`) needs no restow — they're
+  symlinks. Only new/deleted files in this package require `stow -R zsh`.
+- zinit, Powerlevel10k and the plugins auto-clone on first shell start;
+  first launch may take a minute.