Dotfiles and Provisioning

This repository manages a cross-platform developer environment with a strict split of responsibilities:

• Chezmoi owns user dotfiles, templates, and platform-specific file placement.
• Ansible owns package installation, downloaded binaries, source builds, and system-level setup.

That split is intentional. If a behavior change belongs in a dotfile, change the Chezmoi source tree. Do not patch managed dotfiles from Ansible.

Install

Windows

winget install twpayne.chezmoi
chezmoi init --apply --verbose RichardSlater

Linux

sudo apt update && sudo apt install --yes curl git unzip
curl -s https://ohmyposh.dev/install.sh | bash -s
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply RichardSlater

Transient environments

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --one-shot RichardSlater

Validate

chezmoi diff
cd scripts/ansible && ansible-galaxy install -r requirements.yml && ansible-playbook playbook.yml --syntax-check

For broader validation, use the repository tasks and helper scripts:

• .vscode/test-dotfiles.sh for Docker-based Chezmoi rendering and doctor checks.
• .vscode/test-ansible-idempotence.sh for a two-pass Docker Ansible apply.
• yamllint ., ansible-lint playbook.yml, and shell linting for repo scripts.

Documentation

• docs/README.md for the documentation index.
• docs/ARCHITECTURE.md for the Chezmoi and Ansible boundary, current inventory, and change guardrails.
• docs/CHEZMOI_VARIABLES.md for the built-in and repo-specific template variables used by this repo.
• docs/ANSIBLE_ROLE_TEMPLATE.md for the preferred Ansible role structure and idempotence checklist.
• scripts/ansible/README.md for play ordering, role categories, and privilege boundaries.

Shared coding-agent instructions

Edit dot_agents/AGENTS.md to update the user-wide defaults shared by all three agents. Chezmoi installs it at ~/.agents/AGENTS.md and creates relative symlinks:

Agent	Global instruction file
Pi	~/.pi/agent/AGENTS.md
Claude Code	~/.claude/CLAUDE.md
Antigravity	~/.gemini/GEMINI.md

The Claude Code and Antigravity locations follow their memory and rules documentation. Antigravity also shares this file with Gemini CLI when it uses the same global path.

Preview and apply only these files (leave unrelated dotfiles and scripts untouched):

chezmoi diff ~/.agents/AGENTS.md ~/.pi/agent/AGENTS.md ~/.claude/CLAUDE.md ~/.gemini/GEMINI.md
chezmoi apply ~/.agents/AGENTS.md ~/.pi/agent/AGENTS.md ~/.claude/CLAUDE.md ~/.gemini/GEMINI.md

Review and preserve any existing app-specific instructions before applying: existing files at these paths will be replaced by symlinks. On Windows, symlink creation requires Developer Mode or appropriate privileges. Custom agent configuration/home directories need corresponding link locations.

SSH Push URL

chezmoi cd
git remote set-url --no-push origin https://github.com/richardslater/dotfiles.git
git remote set-url --push origin git@github.com:RichardSlater/dotfiles.git