Zsh developer documentation (index)

Entry point for humans and AI agents — history layout, .zshrc changelog, Cursor shell notes

Zsh documentation (index)

Use this folder when onboarding or when an agent needs machine shell context (not in-repo package.json scripts).

Document	Purpose
`zshrc-latest-changes.md`	Changelog of important `~/.zshrc` decisions: lazy completions, history cleanup perf, `~/.zsh/history/` session files, `compinit` / `fpath` / `_brew` on Apple Silicon. Start here for “why is it like this?”
`zsh-history-directory-migration-spec.md`	Spec: move per-session `~/.zsh_history_` out of `$HOME` root into `~/.zsh/history/`*, env vars, migration, rollback
`enhanced-zsh-system.md`	Overview: tools (fzf, starship), aliases, key bindings, cleanup behavior, troubleshooting
`.cursor-shell-optimization.md`	Cursor IDE: fast shell init, minimal profile option, safe background tasks
`yarn-scripts-fzf.md`	Optional `yserve` / `yscripts`: fzf picker from `package.json` (no history/keybind changes)
`zshrc/ADD_TO_ZSHRC.txt`	Legacy Node/monorepo env snippet (paths may need updating per machine)

Path	Purpose
`tools/scripts/system/migrate-zsh-history-directory.sh`	One-time move of `~/.zsh_history_*` → `~/.zsh/history/`
`tools/scripts/system/zsh-history-path.snippet.zsh`	Copy-paste starter for `ZSH_HISTORY_DIR` / `SESSION_HISTFILE` (see comments for split vs single-`HISTFILE` model)
`tools/scripts/system/zsh-advanced-history.zsh`	Optional arrow-key history widget (sourced from `.zshrc` if used)
`tools/scripts/system/zsh-yarn-scripts-fzf.zsh`	`yserve` / `yscripts` — fzf yarn scripts from `package.json` (see `yarn-scripts-fzf.md`)

~/.zsh = directory for zsh state; ~/.zsh/history/ = per-session log files matching .zsh_history_*.
~/.zshrc = config file (not a directory). Do not confuse with ~/.zsh/.
Split history model (current maintainer setup): HISTFILE=$HOME/.zsh_history (zsh’s main persisted history) + SESSION_HISTFILE=$ZSH_HISTORY_DIR/.zsh_history_… (session-sidecar files for sas / logging). Both are valid; the spec describes the directory layout for the session blobs only.
~/.zsh_sessions = macOS Terminal session metadata — not the same as our SESSION_HISTFILE files.

Read zshrc-latest-changes.md before suggesting edits to a user’s ~/.zshrc.
Never recommend find "$HOME" for session history cleanup; use a glob on $ZSH_HISTORY_DIR only.
If the user reports compinit: ... _brew and /usr/local/share/zsh/site-functions, see Change 4 in zshrc-latest-changes.md (prune stale fpath before compinit on Apple Silicon).