The .dotfiles Manual

A trusted agent workstation baseline for macOS, Linux, and WSL. Chezmoi handles templating and platform differences; the dot CLI coordinates lifecycle operations on top.

This manual is generated from the Markdown sources in docs/manual/ and published in nine formats per release. The HTML edition you are reading is the canonical online version.

Read it your way

• Web (multi-page) — browse the chapters below
• Single-page HTML, PDF, EPUB, ASCII text — attached to every GitHub Release
• CLI — dot manual opens the manual locally; dot manual pdf downloads the PDF; dot manual text pipes the ASCII edition to your pager

Contents

Introduction

The audience, scope, conventions, and where the manual is published.

Concepts

• Architecture — repository layout, chezmoi templating, the dot dispatcher
• Trust model — signing, attestation, SBOM, policy gates
• Theme engine — wallpaper-driven theming across apps
• Fleet — multi-workstation coordination and drift detection
• Self-healing — automatic remediation and rollback

Tutorials

• First install
• Add a wallpaper-driven theme
• Create an agent profile
• Encrypt a secret
• Deploy to a fleet

Reference

• dot CLI — every subcommand
• Config files — every ~/.config/dotfiles/* path
• Environment — every variable read by the framework
• Templates — every {{ .var }} reference
• Feature flags

Cookbook

• Recipes
• Troubleshooting
• FAQ

Appendices

• A — Platform matrix
• B — Security checklist
• C — Glossary
• D — Bibliography
• E — License

Indexes

• Concept index
• Command index