LLMS.txt

iam-dotfiles

Purpose
- Personal dotfiles managed with chezmoi.
- Main focus: fast zsh environment on macOS and Linux.
- Current stack: chezmoi + Sheldon + mise + Starship + Serotonin.

Current Decisions
- Sheldon is the zsh plugin manager.
- mise replaces asdf.
- cheat payload was removed from the repository.
- Shell config is modular and generated via chezmoi templates.

Important Paths
- dot_zshrc.tmpl: main zsh entrypoint.
- dot_zshrc.d/: modular zsh config files.
- dot_zprofile: login-shell setup, brew shellenv, mise activation.
- dot_path: PATH construction.
- dot_gitconfig.tmpl: global git config and aliases.
- dot_config/sheldon/plugins.toml.tmpl: zsh plugin definitions.
- dot_config/mise/config.toml: global runtime versions.
- scripts/serotonin/: interactive CLI/TUI layer.
- scripts/dotfiles/: legacy helper scripts and install/update flows.

How To Work Safely
- Treat this repo as the source of truth for managed dotfiles.
- Prefer editing repo files first, then apply via chezmoi.
- Preview before broad apply:
  - chezmoi diff
- Apply targeted files when possible:
  - chezmoi apply ~/.zshrc ~/.zprofile ~/.path ~/.gitconfig
- Do not put secrets in tracked files.
- Local secrets belong in:
  - ~/.config/local-shell/env.zsh

Common Commands
- chezmoi source-path
- chezmoi diff
- chezmoi apply
- sheldon lock
- mise doctor
- mise upgrade
- dotfiles doctor
- dotfiles update

Validation
- zsh -n dot_zprofile dot_zshrc.tmpl scripts/serotonin/main.zsh
- bash -n install.sh
- git config -f rendered.gitconfig --list

Known Constraints
- Some old scripts in scripts/dotfiles/ are legacy and less reliable than Serotonin.
- The repo may contain template files that should be validated after rendering, not only as raw text.
- Prefer conservative changes to shell startup and git aliases.

Good First Targets
- Docs consistency.
- Legacy script cleanup.
- Safer install/update flow.
- Small shell/module improvements with targeted chezmoi apply.