Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (52 loc) · 2.52 KB

AGENTS.md

File metadata and controls

71 lines (52 loc) · 2.52 KB

AGENTS.md

Project Intent

This repository is the source of truth for managed dotfiles. It is a personal setup first, but changes should still be made in a way that keeps chezmoi, shell startup, and machine portability predictable.

Current Stack

  • Dotfiles manager: chezmoi
  • Zsh plugin manager: Sheldon
  • Runtime manager: mise
  • Prompt: Starship or Warp-native prompt
  • Interactive management layer: Serotonin

Do not reintroduce zinit or asdf. The old cheat payload has been removed.

Key Files

  • dot_zshrc.tmpl: main rendered ~/.zshrc
  • dot_zprofile: login-shell initialization
  • dot_path: shared PATH logic
  • dot_zshrc.d/: modular zsh pieces
  • dot_gitconfig.tmpl: global git config
  • dot_config/sheldon/plugins.toml.tmpl: plugin list
  • dot_config/mise/config.toml: managed tool versions
  • scripts/serotonin/: primary CLI/TUI UX
  • scripts/dotfiles/: older helper layer

Safe Change Workflow

  1. Edit repository files, not files in $HOME, unless the task is explicitly about a live local-only file.
  2. Preview chezmoi output before broad apply.
  3. Prefer targeted apply over full apply for shell and git changes.
  4. Validate syntax after shell/install changes.
  5. Keep commits focused and small when possible.

Recommended commands:

chezmoi diff
chezmoi apply ~/.zshrc ~/.zprofile ~/.path ~/.gitconfig
zsh -n dot_zprofile scripts/serotonin/main.zsh
bash -n install.sh
sheldon lock

Secrets

  • Never commit secrets into tracked dotfiles.
  • Local machine secrets should live in ~/.config/local-shell/env.zsh.
  • If shell behavior depends on a secret, keep the hook in the repo and the secret value outside the repo.

Editing Guidelines

  • Be conservative with startup-path changes.
  • Be conservative with global aliases, especially destructive git aliases.
  • Prefer Serotonin as the user-facing layer when touching update/doctor flows.
  • When touching template files, think in terms of rendered output, not only source text.
  • Keep macOS/Linux behavior explicit when it differs.

Validation Notes

  • chezmoi execute-template may fail if unrelated garbage exists in the source tree; validate rendered snippets locally when needed.
  • For dot_gitconfig.tmpl, render a stub file and test it with git config -f <file> --list.
  • After plugin changes, regenerate lock state with sheldon lock.

Cleanup Priorities

  • Reduce legacy surface in scripts/dotfiles/.
  • Keep README and TODO aligned with actual project state.
  • Prefer removing dead config and payloads over hiding them behind ignores.