Imported from mohemohe/dotfiles (AGENTS.md). Install upstream with npx skills add mohemohe/dotfiles. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

This repository stores cross-platform shell and application dotfiles. Shell-specific configuration lives in fish/, zsh/, and the deprecated bash/ and vim/ trees. Tool configuration is grouped by application (nvim/, tmux/, starship/, chezmoi/, compton/, tint2/, and jgmenu/). Create a dedicated directory at the repository root for each newly supported application and keep its configuration there. Configuration that is implemented entirely in the shell belongs in zsh/ and fish/include/ instead of a new application directory. install/ contains one setup script per tool; _init.sh selects them, while _lib.sh provides shared fetch, clone, and loader helpers. Keep new configuration beside the tool it configures and add installation wiring only when required.

Build, Test, and Development Commands

There is no compiled build or project-wide test runner. Use focused checks:

• fish --no-execute fish/config.fish checks Fish syntax.
• zsh -n zsh/.zshrc checks Zsh syntax; repeat for changed .zsh files.
• shellcheck install.sh _init.sh _lib.sh install/*.sh lints POSIX shell installers when ShellCheck is installed.
• stylua --check nvim verifies Lua formatting using nvim/stylua.toml.
• git diff --check catches whitespace errors before review.

./_init.sh applies the checkout and may install packages or replace links under $HOME; run it only when intentionally testing the full setup, preferably in a disposable account or VM.

Coding Style & Naming Conventions

Match the surrounding shell dialect and indentation. POSIX shell files use #!/bin/sh, quoted paths, and four-space indentation; Neovim Lua uses two spaces and a 120-column limit. Name Fish load fragments with their ordering prefix, such as fish/include/50.tool.fish. Keep installers small, idempotent, and named install/<tool>.sh. Never commit credentials, host-specific secrets, or generated local state. Read API keys and similar secrets from files outside the repository, following the Homebrew token pattern, and guard every read so shell startup still succeeds when the file is absent or unreadable.

Testing Guidelines

Validate every changed file with its native parser and lint applicable shell scripts. For OS-specific changes, state which environment was exercised (macOS, Linux, or WSL). Confirm symlink targets and startup behavior in a clean shell; do not treat a successful syntax check as proof that an installer is safe.

Commit & Pull Request Guidelines

Recent history favors snapshot messages such as checkpoint: YYYY/MM/DD HH:MM:SS, plus terse entries like sync and deprecate vim. Use a concise imperative summary for focused changes and reserve checkpoint: for broad snapshots. Pull requests should describe affected shells/platforms, list validation commands, flag changes under $HOME, link relevant issues, and include terminal output or screenshots when behavior or appearance changes.

Agent-Specific Instructions

Prefix shell commands with rtk (for example, rtk git status or rtk shellcheck install.sh). Preserve unrelated working-tree changes and never run destructive setup commands merely to validate documentation.