skel/AGENTS.md

Installation and Environment

This is a set of dotfiles and utilities for setting up my personal environment on POSIX-style environments. It is cloned from github and installed from the install.sh script.

It mostly relies on symlinking dotfiles and other resources into the appropriate locations, but also installs dependencies in various ways.

I primarily target Debian Linux-based (Debian, Ubuntu, and Kali Linux) systems as well as MacOS. Other platforms are lower priorities. Shell scripts ending in .sh should use only POSIX features unless there is a shebang line at the beginning suggesting a different shell will be used. In particular, those in directories with names like bash might use those shells.

zsh and fish are the key interactive shells to be configured, but bash may also be used at times.

Project Structure

• bin/: Contains executable scripts symlinked to ~/bin/. Subdirectories like macos/, restic/, and setup/ are included.
• dotfiles/: Contains configuration files (dotfiles) symlinked to the home directory.
• dotfile_overlays/: Each directory within is symlinked to the home directory, allowing for modular or git-submodule-based configurations.
• local_dotfiles/: If present, its contents are symlinked to the home directory (ignored by git).
• packages/: Contains lists of packages (one per line) for different environments or toolsets.
• keys/: Contains SSH keys (ssh/), GPG keys (gpg/), and a known_hosts file to be installed/merged.
• skeltools/: Internal utilities used by the installation scripts.
• sysctl/ and udev/: Linux system configuration files.
• Brewfile: Homebrew package list for macOS environments.
• install.sh: The primary installation script for symlinking and basic setup.

Notes on Security Issues

It is safe to have scripts and tools re-invoke themselves with sudo when they require elevated privileges, as these are my own. Do not attempt to remove these use cases.

Making Changes

IMPORTANT: Only make those changes which are explicitly requested. If you identify other issues, notify me about them, but do not suggest changes until I ask for them.

When making large changes, explain your chain of thought transparently and explain solution design.

If making changes that affects how the user installs the tools, update README.md accordingly.

Adding a new dotfile

1. Place the new dotfile in the dotfiles/ directory.
2. Alternatively, use dotfile_overlays/ if the dotfile belongs to a specific group or submodule.
3. The install.sh script will automatically symlink it to the home directory.

Adding a new script to bin/

1. Add the new script to the bin/ directory (or an appropriate subdirectory).
2. Ensure the script is executable (chmod +x).

Adding a new package

1. Identify the appropriate package list in the packages/ directory (e.g., packages/cli, packages/kali).
2. Add the new package name to the list (one per line).
3. If a new package set is required, create a new file in the packages/ directory.
4. For macOS-specific packages, also consider adding them to the Brewfile.

Platform-specific changes

When making changes that are specific to a platform (e.g., Debian vs. macOS), please check for existing conventions in the install.sh script or other files. Use conditional logic (e.g., checking uname) to apply platform-specific settings.