Troubleshooting
Start with zdoctor and the dependency checker.
A command or completion is missing
Check that the repository is at ~/.config/zsh and your ~/.zshrc sources init.zsh after Oh My Zsh. Run compinit before loading the shared modules. Use zhelp --all --plain to inspect unavailable commands and their requirements.
npkg needs Nix; cgm is only defined when secret-tool is installed. Restart your shell after installing them.
Fuzzy pickers do not open
Check fzf --version. Missing, malformed, prerelease and versions below 0.68.0 block fuzzy workflows. Install a stable supported version, restart the shell, and rerun ~/.config/zsh/scripts/check-deps.sh. Pickers need an interactive terminal; plain styling does not make them noninteractive.
Secret Service is unavailable
Install secret-tool and configure an unlocked Secret Service provider in your desktop session. Run cgm check for an explicit backend health probe; it also needs gdbus. cgm status reports saved names and current-shell loaded state without retrieving values.
Icons look like boxes
Run ztheme current to preview glyphs. Nerd Font icons require a compatible terminal font and ZSH_UI_GLYPHS=nerd. Use ZSH_UI_GLYPHS=ascii for basic glyphs. Terminal styling also depends on terminal capabilities.