Understand load order on macOS/zsh: .zshenv (all shells) → .zprofile (login shells) → .zshrc (interactive shells); place environment variables like PATH and EDITOR in .zshenv or .zprofile, not .zshrc.
Export PATH additions in ~/.zprofile: export PATH="/usr/local/bin:$PATH" so they are inherited by GUI apps and non-interactive login shells.
Place aliases, functions, prompt configuration, and completion setup in ~/.zshrc — these only apply to interactive sessions.
Use .zshenv for variables that must reach non-interactive scripts (e.g., cron or launchd jobs): export LANG=en_US.UTF-8
Reload the current shell's rc without logging out: source ~/.zshrc (reloads aliases/functions but does not re-run .zprofile).
Known gotchas
On macOS, /etc/zprofile runs path_helper to set PATH before ~/.zprofile; prepend entries rather than overwriting PATH entirely to avoid losing system paths.
.zshenv is sourced for every shell invocation including scripts called by launchd or cron; keep it minimal and avoid interactive commands or slow initialisation in it.
Changes to .zprofile take effect only in new login shells; open a new Terminal window or run exec -l zsh to apply them without logging out.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp