DOTS¶

Desired-state environment manager for a personal workstation operating layer — shared muscle memory across home Mac, work Mac, and headless Linux. Not a pile of identical packages everywhere; not “just dotfiles.”

Humans use ./dots. Automation uses bootstrap.sh / setup.sh. Declarative registries own desired state; helpers execute it.

Documentation site¶

Live docs: https://sempervent.github.io/dots/

Entry points¶

I want to…	Go here
Install and run the first time	Getting Started
Understand profiles / packages / components	Core Concepts
Select optional `--with` components	Components and `--with`
Pick a machine role (home / work / server / Pi)	Profiles
Use Linux or Raspberry Pi	Linux · Raspberry Pi
macOS workstation apps (Vorssaint, Raycast, …)	mactools
Agents, models, routing	Agent harness · Models
Fix something that broke	Troubleshooting
Extend the repo safely	Extending
CLI flags (generated)	CLI reference

Happy path¶

git clone https://github.com/sempervent/dots.git ~/dots
cd ~/dots
./dots                     # interactive setup
./dots setup --dry-run     # preview without mutating
./dots status              # read-only dashboard
./dots check               # health verification

Sources of truth (do not invent a second)¶

Thing	Authority
Optional components / supergroups	`configs/components.toml`
Package groups	`configs/packages/groups.toml` + `brew/groups/*.Brewfile`
Linux package names	`configs/packages/{apt,pacman,dnf,xbps}.toml`
Managed links	`configs/links.toml`
Skill packs	`configs/skills/manifest.toml`
Local models	`configs/models.toml`
Built-in profiles	`configs/bootstrap/profiles/*.toml`

See Architecture for the full map.

What DOTS is not¶

A forced identical install on every machine
An auto-cleanup tool (brew bundle cleanup is never run)
An AI consent grab — presence of a binary does not authorize configuration
A ZFS / NAS appliance (a future file-tank profile is explicitly out of scope today)

Contribute / maintain¶

Branch → PR → GitHub CI. See Contributing and the maintainer skill.