.dotfiles

Declarative dotfiles for macOS, Linux, WSL, and Windows-native PowerShell 7.5+. Multi-shell by default. Sub-100ms dot cold-start. Wallpaper-driven themes. Signed and attested releases. Fleet apply over SSH.

Contents

Getting started

• Install — one-line installer, verified installer, release archive, Homebrew, Scoop, AUR, npm, Nix, chezmoi, source
• Requirements — toolchain floor, platforms, shells
• Quick Start — install, verify, switch a theme, apply in six commands

The dotfiles family (framework + five in-repo satellites)

• The dotfiles family — dot, dot-ui, dot-ai-tui, dot mcp, dot-mcp, dot-sys, the module registry at a glance

Framework reference

• One-minute migration from another dotfiles manager — yadm, GNU Stow, a bare repository, plain chezmoi
• Why this approach? — design rationale
• Capabilities at a glance — the current surface by theme
• Five shells, one alias hub — parity tiers from ADR-007
• Comparison — short matrix against chezmoi, holman, nikitabobko
• Benchmarks — startup budgets and the measurement method
• Features — what is included, by area

What it does

• Wallpaper-driven themes — K-Means in CIELAB, WCAG AAA, 228 generated themes
• Agent governance (ask / plan / apply / audit) — bounded profiles, MCP policy, attestation
• Self-healing and rollback — dot doctor, dot doctor fix, dot doctor rollback
• Fleet apply — every host in fleet.toml over SSH
• The dot CLI — the command surface, grouped by intent
• Configuration — .chezmoidata.toml, profiles, session flags
• Examples — runnable example index

Operational

• When not to use .dotfiles — limitations
• Development — make targets, fuzzing, hardening gates, CI
• Security — reporting, posture, supply chain
• Documentation — all reference docs
• Acknowledgements
• Stability guarantees — SemVer axis, output stability, toolchain discipline
• License

Install

Verified release installer

The default installation path is pinned to a release and fails before execution if the installer bytes do not match the reviewed SHA256. Never pipe the moving main branch directly into a shell. The per-release hash and its release process are documented in docs/security/INSTALL_VERIFICATION.md.

curl -fsSL -o /tmp/dotfiles-install.sh \
  https://github.com/sebastienrousseau/dotfiles/releases/download/v0.2.541/dotfiles-install-0.2.541.sh
if command -v sha256sum >/dev/null 2>&1; then
  echo "1ad4bba73b8357b8abd6128af9fd5f957763f16832716db141a92c9415b02ae5  /tmp/dotfiles-install.sh" | sha256sum -c -
else
  echo "1ad4bba73b8357b8abd6128af9fd5f957763f16832716db141a92c9415b02ae5  /tmp/dotfiles-install.sh" | shasum -a 256 -c -
fi
bash /tmp/dotfiles-install.sh

The script needs git, curl, and sha256sum or shasum. It downloads a checksum-verified chezmoi binary, clones the pinned release to ~/.dotfiles, applies it, and puts dot on PATH. The installer is idempotent across macOS, Ubuntu, Debian, Arch, WSL2, and GitHub Codespaces.

Pre-built release archive (dot CLI only)

Every tag publishes dot-<version>.tar.gz and .zip with the dispatcher, lib/dot, the bundled plugins and runtime scripts, the man page, zsh / bash / fish completions, and a Makefile honouring the usual install prefix and staging directory. The archive carries SLSA build provenance (keyless, via Fulcio + Rekor):

gh release download v0.2.541 --repo sebastienrousseau/dotfiles --pattern 'dot-*.tar.gz'
gh attestation verify dot-0.2.541.tar.gz --repo sebastienrousseau/dotfiles
tar -xzf dot-0.2.541.tar.gz
make -C dot-0.2.541 install PREFIX=/usr/local

release-install-smoke.yml repeats exactly this sequence on a clean Ubuntu and macOS runner after every release: verify provenance, make install into an empty staging directory, run dot version, make uninstall, assert nothing is left behind.

Package managers

The Homebrew formula and Scoop manifest are regenerated per tag by release-distribute-homebrew.yml and release-distribute-scoop.yml from the templates under pkg/; the AUR package is pushed by release-distribute-aur.yml. The per-channel templates and the maintainer runbook are in pkg/README.md; the end-to-end pipeline is docs/operations/RELEASE_PIPELINE.md.

With chezmoi directly

The repository is a chezmoi source tree (.chezmoiroot points at defaults/), so chezmoi's own bootstrap works:

chezmoi init --apply sebastienrousseau

install.sh does the equivalent after its preflight checks: it clones the pinned release tag to ~/.dotfiles, points chezmoi's sourceDir at it, and applies. Going direct, you give up the verified chezmoi download, the pinned tag, and the git / curl checks.

Build from source

git clone https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh                  # full install from the local checkout
make install PREFIX=~/.local  # or: stage only the dot CLI

./install.sh --minimal selects the minimal profile (written to this host's chezmoi config) and skips --provision. dot config export ~/Downloads builds an offline .tar.zst for an air-gapped host; unpack it and run ./install.sh --force.

# After downloading and verifying /tmp/dotfiles-install.sh as shown above:
DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
  bash /tmp/dotfiles-install.sh --force

docker run --rm -e DOTFILES_NONINTERACTIVE=1 ubuntu:24.04 bash -c \
  'apt-get update -qq && apt-get install -y -qq git curl sudo >/dev/null 2>&1 \
  && git clone --depth 1 https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles \
  && bash ~/.dotfiles/install.sh \
  && export PATH="$HOME/.local/bin:$PATH" \
  && dot doctor'

Profiles and session flags

Everything heavy is off, deferred, or cached by default. Pick a profile per machine and flip session flags when you need less.

Requirements

• Bash 5.0 or newer, zsh 5.8 or newer. These are the Tier-1 shells and the floor the test suite runs on: Ubuntu and macOS (Apple Silicon) runners on every push, Windows when shell code changes, and an Intel macOS runner in the weekly extended run (nightly.yml). install.sh and lib/dot avoid bash-4-only constructs where macOS's stock /bin/bash 3.2 has to run them (the notes are in lib/dot/ui.sh), but 3.2 is not a supported interactive shell.

• chezmoi 2.73.3 or newer, git 2.34 or newer, curl. CI pins chezmoi 2.73.3 and installs it through a checksum-verified fetch; install.sh does the same on your machine.

• A supported platform. macOS 15+ (Apple Silicon and Intel), Ubuntu 22.04+, Debian 12+, WSL2, NixOS 23.11+ are CI-tested or supported; Fedora and Arch are community-supported. The full table, with per-tool floors, is docs/MINIMUM-TOOLCHAIN.md.

• Windows. PowerShell 7.5+ runs the native dot.ps1 for the daily workflow (apply, status, doctor, mise inventory, agent checks, fleet status); the Test / Windows job exercises the cmdlets on windows-latest whenever shell or Windows code changes.

Minimum-toolchain policy. The floor is the version CI exercises, not the oldest version that happens to work. It is raised only in a release whose CHANGELOG.md entry names the new floor and the reason, never silently. The version axis on which it may move, and the table mapping every supported platform and tool to its floor live in docs/MINIMUM-TOOLCHAIN.md; this README makes no distro-compatibility claim that table does not back.

Quick Start

# First download and verify /tmp/dotfiles-install.sh as shown in Install.
bash /tmp/dotfiles-install.sh
dot doctor            # audit tools, paths, portability, security
dot help tour         # interactive tour of shells, secrets, themes, performance
dot theme rebuild     # generate themes from the wallpapers on this machine
dot theme toggle      # swap dark and light within the current family
dot sync              # apply the source tree; the next shell hydrates its caches

First 5 Minutes

1. Check — dot doctor validates tools, paths, and security.
2. Explore — dot help tour walks through shells, secrets, themes, and performance.
3. Customize — edit ~/.config/chezmoi/chezmoi.toml for per-machine settings (Profiles).
4. Toggle features — flip flags in .chezmoidata.toml (Feature Flags).
5. Apply — dot sync applies the config, and the next interactive shell hydrates its caches through _cached_eval.

Upgrades between versions are covered in docs/operations/MIGRATION.md.

The dotfiles family

One repository, one release train: the dot framework plus five satellites that ship inside it and version with it. The version number in defaults/.chezmoidata.toml is the compatibility contract: CI's Generators / version-consistency job checks it against every human-visible version surface (among them package.json, bin/dot, the man page, the bento banner, this README's badge, CLAUDE.md and AGENTS.md) on every push to main.

Install the pieces

# The framework (everything, chezmoi-managed)
bash /tmp/dotfiles-install.sh  # after the verified download above

# Only the dot CLI, from the attested release archive
gh release download v0.2.541 --repo sebastienrousseau/dotfiles --pattern 'dot-*.tar.gz'

# The Go satellites are (re)built on apply by
#   defaults/run_onchange_24-build-dot-ui.sh.tmpl
#   defaults/run_onchange_25-build-dot-ai-tui.sh.tmpl
#   defaults/run_onchange_26-build-dot-mcp.sh.tmpl

# A registry module
dot cli list --available && dot cli install <module> --yes

Per-host quick links

How good is this, really?

The rating is a set of programs, and each one prints the command next to the number.

dot doctor score             # system health and security scorecard
dot security score show -j   # workstation security posture, JSON
dot doctor --score           # tools, paths, portability, AI analysis
make test                    # the reliability audit CI runs

What the repository can show today:

• OpenSSF Scorecard 8.3 / 10 at the last recorded snapshot (2026-10-29), written into docs/security/SCORECARD.md with the per-check breakdown by scripts/qa/scorecard-snapshot.sh, run by hand. scorecard.yml runs the analysis weekly, and the badge above is live.
• OpenSSF Best Practices: passing (100%), project 12840.
• Unit, integration, and regression suites, a golden-snapshot suite for dot --help / version / doctor / perf / health, and an install.sh fuzz harness — see tests/README.md.
• Bash line coverage floor 98% (96% for behavioural tests alone) measured by pure xtrace, no kcov, ratcheted up slice by slice with the history recorded in coverage.yml.
• Every third-party action SHA-pinned, and Harden Runner in every workflow except branch-drift-guard.yml.

The gaps, so nobody has to find them:

• Scorecard's Code-Review check scores 0: one maintainer, merges gated by CI rather than by a second reviewer.
• OSS-Fuzz onboarding is prepared under fuzz/oss-fuzz/ but not yet submitted; ClusterFuzzLite runs in the meantime.
• Repology tracks one packaging (AUR dot-cli-git); Homebrew and Scoop go through this project's own tap and bucket.
• Nushell sits at Tier 3 with under 5% feature parity (ADR-011).

Each number above names the command or the file that produced it. The Scorecard breakdown is docs/security/SCORECARD.md, the coverage history is in coverage.yml, and docs/STRUCTURE.md maps every top-level path to the component that owns it. The rest of this README covers the framework surface.

One-minute migration from another dotfiles manager

The one-minute version is dot config init. It clones any GitHub user's dotfiles repository through this harness, refuses to clobber an existing chezmoi source without --force, insists on HTTPS, and previews with --dry-run:

dot config init alice --dry-run     # preview: what github.com/alice/dotfiles would do
dot config init alice               # clone + apply through the dot harness
dot config init https://... --no-apply

Coming from a specific tool? The headline mapping is below, and dot config init <user> --dry-run shows the repository URL and target directory it would use before anything is written.

Upgrades between versions of this project are a different document: docs/operations/MIGRATION.md.

Why this approach?

Most dotfiles repositories are personal collections. This one is built as workstation infrastructure: chezmoi is the templating engine (ADR-005), dot is the lifecycle CLI on top (ADR-004), and every claim on this page has a test, a workflow, or a document behind it.

Three choices you will not find in mathiasbynens/, holman/, or paulirish/:

1. Wallpaper-driven terminal themes. K-Means clustering in CIELAB extracts a palette from any wallpaper; the engine enforces WCAG AAA (7:1) contrast and writes themes.toml itself. 228 generated themes ship today (ADR-009).
2. First-class agent governance. Bounded profiles (ask / plan / apply / audit), MCP policy enforcement, A2A discovery, and signed attestation logs for every agent session (docs/security/MCP_POLICY.md, docs/interop/A2A.md).
3. Verified multi-shell parity. One alias and function hub feeds zsh, bash, fish, nushell, and PowerShell; a parity contract runs the canonical command surface in every available shell on every PR (ADR-007).

Two architectural choices make the rest cheap:

• Lazy hydration. The prompt paints first from static escape codes; tool initialisations (mise, atuin, zoxide, starship) run through _cached_eval, which sources cached init output and invalidates on the binary's mtime and realpath. Heavy binaries resolve asynchronously after the first prompt (ADR-002).
• Idempotent, verifiable apply. dot sync is chezmoi apply plus drift detection; dot doctor fix repairs tools, symlinks, and missing files; dot doctor rollback returns to a known-good state; a chaos test (scripts/ops/chaos.sh) breaks things on purpose to prove the loop closes.

The default install is signed (SSH ed25519 commits enforced on main), attested (SLSA provenance and Cosign-signed SBOM per release), multi-platform (macOS, Linux, WSL2, Apple Silicon CI runners, Windows PowerShell), and schema-checked (.chezmoidata.toml against config/chezmoidata.schema.json via taplo on every PR).

Capabilities at a glance

Five shells, one alias hub

The dotfiles expose one command surface over five shells through a hub-and-spoke bridge (ADR-007):

• Hub — canonical aliases and functions live once, in Bash/POSIX, under defaults/.chezmoitemplates/aliases/ and defaults/.chezmoitemplates/functions/. Adding one propagates to every shell.
• Tier 1 (full): zsh, bash — direct inclusion, lazy loading, _cached_eval, staged rc.d modules.
• Tier 2 (bridged): fish — a runtime bash bridge with a cached abbr table (878 entries source in 34 ms, down from 170 ms when they were alias functions), plus native dot completions.
• Tier 3 (compatible): nushell — simple aliases extracted and cached to ~/.cache/nushell/bash-aliases.nu; functions delegate to bash at roughly 5 ms per call (ADR-011 explains why it stays).
• PowerShell — a managed profile, the native dot.ps1 for the daily workflow, and a parity contract that runs on every PR (docs/reference/POWERSHELL_PARITY.md).

tests/integration/test_shell_parity.sh verifies the canonical command surface and a runtime smoke in every shell present on the runner; the Reliability Gate workflow adds WSL and PowerShell contract jobs.

dot cli completion show zsh      # completions are generated from the command registry,
dot cli completion show fish     # never hand-maintained — bash, zsh, fish, and nu
dot shell alias status --tiers   # which alias tiers and ecosystems are enabled here
dot shell alias show gco         # provenance and deprecation status of one alias

Comparison

.dotfiles is the only dotfiles distribution in this comparison that ships wallpaper-derived WCAG-AAA themes, agent governance, cryptographic attestation, a self-healing CLI, and fleet apply on top of a stock chezmoi source tree.

chezmoi is the underlying templating engine. This repo is the opinionated reference implementation on top of it, and plain chezmoi users can adopt it without moving their source tree.

Benchmarks

Two budgets are enforced in CI, and both state their method.

dot cold start — tools/ci/dot-cli-startup-bench.sh runs dot version eleven times under a clean env -i shell and takes the median. dot-cli-bench.yml fails the build above the budget on every push and PR touching bin/dot or scripts/dot/; a median more than 15% over the previous baseline is a warning.

Interactive shell startup — dot doctor perf show (backed by scripts/diagnostics/perf.sh, hyperfine-style warm-up plus three runs, mean) measures every installed shell against a per-shell target, compares with a recorded baseline in ~/.cache/dotfiles/perf-baseline.json, and flags any shell more than 10% slower. perf-baseline.yml records the reference weekly on Ubuntu and measures every push to a feat/** branch that touches shell code.

Measured deltas that shipped with their method in CHANGELOG.md: fish startup 217 ms → 119 ms by emitting the alias bridge as abbr instead of alias (#963); ~140 ms saved per fish start by shadowing Homebrew's eager direnv / mise vendor_conf.d hooks; 20–50 ms saved per tool by _cached_eval (docs/ARCHITECTURE.md). The original threshold and the hyperfine --warmup 3 --runs 10 "zsh -i -c exit" recipe are in ADR-002.

Numbers on your own machine:

dot doctor perf show              # every installed shell vs its target
dot doctor perf show --baseline   # record this machine's known-good point
dot doctor perf measure           # per-component startup profile
dot doctor perf --ready           # time to heavy-layer readiness

Budgets, baseline lifecycle, and the regression-issue pipeline are documented in docs/operations/PERFORMANCE.md; the harnesses are tools/ci/dot-cli-startup-bench.sh and benches/.

Features

Wallpaper-driven themes

Drop a wallpaper. Get a theme.

dot theme rebuild discovers system wallpapers and your custom ones. On macOS it looks in /System/Library/Desktop Pictures/. On Linux it looks in /usr/share/backgrounds/. Custom wallpapers live in ~/Pictures/Wallpapers/ (DOTFILES_WALLPAPER_DIR overrides). K-Means clustering in CIELAB colour space extracts the dominant colours; the engine generates a 16-colour terminal palette, enforces WCAG AAA contrast (7:1 for fg/bg, accent text on accent, and c15 on bg), and assembles defaults/.theme-manifest/themes.toml on its own. Extraction runs four jobs in parallel, results are cached in ~/.cache/dotfiles/themes/, and only changed wallpapers are regenerated.

dot theme              # interactive picker (paired themes only)
dot theme set maui     # select a family and follow OS appearance
dot theme plan maui --mode auto --json # inspect the pure transaction plan
dot theme tahoe-dark   # switch directly
dot theme toggle       # swap dark and light within the current family
dot theme mode light   # pin a manual appearance
dot theme mode auto    # resume following the OS appearance
dot theme family       # cycle between theme families
dot theme sync         # enable auto mode and sync immediately
dot theme rebuild      # regenerate from current wallpapers

Maui is the default family. Its dynamic HEIC supplies both wallpaper appearances, while the resolved maui-light or maui-dark palette keeps terminals and applications aligned. On macOS, a LaunchAgent watches the system appearance preference and reruns the sync automatically. Runtime selection is machine-local in ~/.config/chezmoi/chezmoi.toml, so using the picker does not modify the dotfiles checkout.

On theme switch, every managed surface updates. Terminals: Ghostty, Alacritty, Kitty, WezTerm, Warp, iTerm2, tmux. Editors: Neovim and VS Code. The theme also sets GTK and icon themes, the macOS accent colour and dark-mode toggle (with a forced UI refresh), the browser colour mode, and the wallpaper. On Linux the engine converts HEIC to PNG through magick or heif-convert.

Full guide: docs/guides/THEMING.md. Rationale: ADR-009.

Agent governance (ask / plan / apply / audit)

Agents run under a named profile that bounds what they may do, and every run leaves evidence:

dot agent mode list                  # ask / plan / apply / audit
dot agent mode set plan              # switch the active profile
dot agent mode run plan git status   # run one command under a profile, with a checkpoint
dot agent check                      # validate agent-profiles.json and the default
dot agent log                        # tail the session audit log
dot agent checkpoint list            # saved run checkpoints (save / list / show / replay)
dot fleet policy set strict          # advisory → strict RBAC for agent profiles

The MCP side is policy-first: dot mcp check audits configured Model Context Protocol servers against defaults/dot_config/dotfiles/mcp-policy.json (allowlist, supply chain, config), and dot mcp list shows the configured servers. dot attest export writes the workstation's version, platform, signing settings, active profile, and policy hash as tracked JSON (docs/operations/ATTESTATION.md). The A2A agent card and conformance suite are in docs/interop/A2A.md; the trust model that ties signing, secrets, profiles, and attestation together is docs/manual/01-concepts/02-trust-model.md.

Self-healing and rollback

The CLI is idempotent, and it checks its own work.

dot doctor                # deep audit: tools, paths, portability, AI analysis
dot doctor fix            # auto-fix tools, chezmoi drift, broken symlinks, missing files
dot doctor rollback       # return to a previous known-good state
dot doctor snapshot new   # capture a baseline to compare against later

Tool recovery is checksum-verified: Nushell, Pueue, Wasmtime, SOPS, Yazi, and Zellij are restored from exact mise / aqua pins, never from a mutable release URL. dot doctor status renders the cache and tool state as a live dashboard (-j for JSON); its output, like doctor, perf, version, and --help, is pinned by golden snapshots in tests/snapshots/.

Fleet apply

# ~/.config/dotfiles/fleet.toml  (DOTFILES_FLEET_HOSTS overrides the path)
[hosts.laptop]
ssh     = "[email protected]"
profile = "workstation"

dot fleet                     # this node: id, namespace, version, OS, drift, last apply
dot fleet drift               # configuration drift across managed files
dot fleet apply               # every host runs: dot sync && dot doctor --quiet
dot fleet apply --cmd uptime  # or an arbitrary command — this is the trust boundary
dot fleet namespace list      # the active namespace (multi-tenant isolation)
dot fleet log show            # recent fleet events from the local log

Hostnames are validated against [A-Za-z0-9._@:+/-]+ before any SSH fan-out; first connections use StrictHostKeyChecking=accept-new, so pre-populate ~/.ssh/known_hosts if your threat model allows no TOFU window. dot fleet push brings a fresh machine up over SSH before it joins the fleet. The concept chapter is docs/manual/01-concepts/04-fleet.md.

The dot CLI

Commands are spelled dot <domain> [object] <verb> (ADR-020), with the shortcuts dot apply, sync, diff, status, edit, cd and update for the daily loop; the tables below group them by intent. dot help shows the overview, dot help all the full reference, dot help <keyword> filters it. The command index is generated from the plugin manifests (through the command table) and checked in CI.

Start here

Daily use

Inspect and repair

AI and agents

Configuration commands

Fleet and performance

Full reference: docs/reference/UTILS.md · manual chapter: docs/manual/03-reference/01-dot-cli.md · man dot after install.

graph TD
    A[User Shell] --> B{dot CLI}
    B --> C[Lifecycle: config sync / config apply / doctor rollback / doctor fix]
    B --> D[Diagnostics: doctor / doctor drift / doctor perf / doctor score]
    B --> E[AI & Agents: ai / mcp / agent / agent mode]
    B --> F[Themes: theme / theme rebuild]
    B --> G[Fleet & Attest: fleet / attest]

    C --> H[Chezmoi Source]
    F --> I[Wallpaper Discovery<br/>System + Custom]
    I --> J[K-Means CIELAB Engine]
    J --> K[themes.toml<br/>WCAG AAA enforced]
    K --> H

    H --> L[Zsh / Fish / Bash / Nushell / PowerShell]
    H --> M[Mise / Nix Toolchains]
    H --> N[MCP Policy / Agent Profiles]
    L --> O[~/.cache/shell Fast Init]

    G --> P[Signed Attestation Logs]

Configuration

# defaults/.chezmoidata.toml — repo-wide defaults, schema-checked in CI
dotfiles_version = "0.2.541"

[features]
alias_wrapper = false   # confirm destructive aliases
dms = true              # Dank Material Shell accents (niri borders, GTK) via dot-theme-sync
ai_theme_sync = true    # wallpaper-aware AI CLI appearance
zellij = false
linux_desktop = false   # mako, environment.d and systemd user units

[tools]
node_manager = "mise"   # mise | fnm | nvm

[data]
profile = "laptop"        # laptop | minimal | server
machine = "work-macbook"
default_shell = "zsh"

[data.features]
linux_desktop = false

Examples

Run all examples (each one is bounded by a 60 s timeout and executed in CI by the Examples Contract job):

make examples

When not to use .dotfiles

A few cases where another tool fits better, listed because the short answer is "we don't do that" rather than because of a disagreement on priorities.

• You want a dependency-free shell config. The full setup (install.sh --provision) brings chezmoi, mise, starship, zoxide, atuin, fzf, and a Go toolchain for the TUI satellites. Leaving out --provision (or passing --minimal) and DOTFILES_ULTRA_FAST=1 cut that down, but the framework assumes it may install things. A single .zshrc is lighter.

• You need full parity on nushell. Nushell is Tier 3: simple aliases plus bash-delegated functions, under 5% of the zsh feature set, kept deliberately as a reference target (ADR-011).

• You need Windows without WSL to be first-class. The native dot.ps1 covers the daily workflow (apply, status, doctor, mise, agents, fleet status); themes, dot doctor fix, and most diagnostics still need bash. Windows CI verifies the PowerShell surface, not the whole CLI.

• You are on Fedora or Arch and need CI-backed support. Both are community-supported: the code is expected to work, but the matrix runs Ubuntu, macOS (Apple Silicon on every push, Intel in the weekly extended run), and Windows (docs/reference/SUPPORT_MATRIX.md).

• You do not want apply to run scripts. chezmoi apply runs the run_onchange_* hooks under defaults/ (the Go satellite builds, terminal profiles, fonts, completion caches) when their source changes. They are idempotent and previewable with dot sync --check, but they are scripts running as you. Package and toolchain provisioning under install/provision/ runs only with install.sh --provision.

• You need a second reviewer on every merge. This is a single-maintainer project gated by CI, DCO, and signed commits, not by code review; the Scorecard Code-Review check says so.

If you hit a case that should be on this list, please open an issue; that is how it gets fixed or moved into the supported set.

Development

make                    # reliability audit: syntax, unit, module coverage, examples, docs + traceability coverage
make test-quick         # the same, quick mode
make test-unit          # unit only
make test-integration   # with integration suites
make examples           # run every example under a timeout
make install            # stage the dot CLI under $(DESTDIR)$(PREFIX) (default /usr/local)
make uninstall

./tests/framework/test_runner.sh --jobs auto   # unit suite, parallel
bash tests/snapshots/test_snapshots.sh         # golden CLI output
bash fuzz/install/fuzz_install.sh                # install.sh under adversarial input
bash tools/docs/generate-command-index.sh --check
bash scripts/verify-release-versions

Toolchain setup, the task map, and how to reproduce every CI gate locally are in DEVELOPMENT.md and docs/operations/TESTING.md. Commit signing, the DCO trailer, branch names, and the regression-test convention are in CONTRIBUTING.md. A devcontainer boots to a working make for Codespaces.

Fuzzing

Native Go fuzz harnesses ship under fuzz/ for the user-input surfaces that were ported out of the shell so they could be fuzzed at all, among them FuzzValidateName (the name validator behind lib/dot/utils.sh) and FuzzInitURLResolver (the URL resolver behind dot config init); the three Go satellites carry their own in-module harnesses. A shell harness, fuzz/install/fuzz_install.sh, drives install.sh itself with unknown flags, garbage positionals, symlink loops in $HOME, an empty PATH, 4 KB arguments, and NUL bytes in the environment, and asserts every case exits cleanly or fails fast but never hangs. It has already found two real bugs (a missing -h alias; unknown positionals triggering a 30 s network fetch).

• fuzz.yml runs each Go harness for 60 s on every push to main and on every PR touching the parsing surfaces. Go replays the committed seed corpus under testdata/fuzz/ before exploring, so a fixed crash cannot silently return.
• cflite_pr.yml builds the ClusterFuzzLite fuzzers (AddressSanitizer) on PRs touching the harnesses or .clusterfuzzlite/, so the build OSS-Fuzz runs cannot break unseen; the fuzzing itself runs in fuzz.yml.
• install-fuzz.yml runs the install.sh harness weekly on Ubuntu and macOS, and on every PR touching install.sh; a scheduled failure opens a tracking issue.
• OSS-Fuzz: the project definition is ready in fuzz/oss-fuzz/ (libFuzzer, ASan + UBSan, x86_64); the upstream submission to google/oss-fuzz has not been filed yet.

cd fuzz
go test -run TestNothing -fuzz='^FuzzValidateName$' -fuzztime=60s ./...
go test -run TestNothing -fuzz='^FuzzInitURLResolver$' -fuzztime=60s ./...

The harness layout and the OSS-Fuzz submission steps are in docs/security/FUZZING.md; the shared corpus lives beside the harnesses under fuzz/testdata/.

Hardening gates in place of Miri

• ShellCheck at severity error is a hard gate on every push (reusable-shell-lint.yml, fail_on_shellcheck: true), with shfmt formatting checked alongside; the same hooks run in pre-commit. Fish and Nushell configs have their own lint jobs.
• Coverage by xtrace, not kcov. tools/ci/run-coverage.sh turns on set -x through BASH_ENV in every bash process the suite spawns and aggregates the lines that executed. The floor is 98% (96% for behavioural tests alone); the measured history is in the workflow file. A separate 100% module-mapping floor (tests/framework/module_coverage.sh) fails the build when an executable module has no test file at all.
• Reliability Gate runs the audit on ubuntu-latest, macos-latest, and macos-15 (both Apple Silicon), then the examples contract, the WSL contract, and the PowerShell contract (docs/operations/RELIABILITY.md).
• Cross-platform portability scan rejects GNU-only sed, grep, and date idioms and runs the critical scripts on each OS (cross-platform-test.yml).
• Generators cannot drift: the command index is regenerated from the plugin manifests (through the command table) and diffed; every version surface (among them package.json, bin/dot, the man page, lib/dot/bento.sh, this README's badge, CLAUDE.md and AGENTS.md) is checked against .chezmoidata.toml; .chezmoidata.toml itself is validated against its JSON Schema. dot agent context check does the same for the AI-harness stubs locally.
• Golden snapshots pin the user-facing text of dot --help, dot version, dot doctor, dot doctor perf show, and dot doctor status after scrubbing paths, timings, and colours.

CI

The cadence and the composite actions are documented in docs/operations/CI_CADENCE.md and docs/operations/CI_COMPOSITES.md.

Security

Reporting: never open a public issue for a vulnerability — use GitHub Security Advisories or [email protected]; see SECURITY.md for the response SLA (Critical: 24 h initial response, 48 h target; High: 72 h / 7 days; Medium: 5 / 30 business days; Low: 10 / 90), the supported-version table, and the GPG key for encrypted reports (docs/security/DISCLOSURE.md, docs/security/KEY_ROTATION.md).

A dotfiles framework is code that runs as you, on every login, on every machine you own. The posture below closes the vectors that matter for that shape — remote script execution, secrets at rest, agents with shell access, and the pipeline that ships it — at the architectural level, not behind opt-in flags. The full analysis is docs/security/THREAT_MODEL.md.

Installer and remote-execution controls

• No unverified download runs. Where chezmoi is missing, install.sh installs it with Homebrew when brew is present; otherwise it fetches the release tarball through tools/ci/install-chezmoi-verified.sh, or, when that helper is not beside it, an embedded verifier that checks the tarball against a pinned SHA-256 (and the upstream checksum file when it can fetch it). Either refuses on mismatch and never falls back to a remote script.
• Every third-party installer the framework can execute is allowlisted by SHA-256 in security/remote-installers.sha256 (Claude, Kimi, Goose, Antigravity, xAI, and the rest). CI rejects any curl | sh that bypasses the verifier.
• Size and structure limits. lib/dot/verified-download.sh caps scripts at 512 KiB and archives at 100 MiB by default, caps checksum manifests at 2 MiB, and fails closed on empty files; registry archives are rejected when they contain path traversal or link entries. Fonts, distro signing keys, and binary archives go through the same path.
• dot config init is HTTPS-only, refuses to overwrite an existing source directory without --force, and prints the source URL it is about to run scripts from.
• Self-healing never fetches mutable URLs. Tool recovery uses exact mise / aqua pins with checksums.

Secrets

• dot secret selects a provider by policy — macOS Keychain, pass, or an age-encrypted local store — and loads buckets into the environment on demand (eval "$(dot secret export ai)"), so keys are never in plaintext files or shell history.
• age and SOPS encrypt chezmoi-managed secret files at rest; dot secret init bootstraps the key, dot secret key new encrypts an SSH key locally, dot secret cert manages short-lived certificates.
• dot secret check audits hygiene and leakage surface on the workstation; gitleaks, detect-secrets, and TruffleHog run on every push and in pre-commit; the history-filtering procedure is written down in docs/security/HISTORY_FILTERING.md.

Agents and MCP

• Every agent runs under a bounded profile (ask / plan / apply / audit) with checkpoints and a session audit log; dot fleet policy set strict turns the profile RBAC from advisory into enforced.
• MCP servers must appear in mcp-policy.json and pass dot mcp check (policy, supply chain, config) before use.
• dot attest records the workstation state with the policy hash so an audit can check what an agent was allowed to do when it ran.

Supply chain

• Every third-party GitHub Action is pinned to a commit SHA, and the pins are linted (Lint / Reusable Workflow Pins). The one tag reference is the SLSA generator reusable workflow, which its maintainers require to be referenced by release tag (docs/security/CI_PINNING.md).
• Harden Runner in every workflow except branch-drift-guard.yml, with the jobs proven local-only in egress-block mode and an explicit endpoint list (docs/security/CI_EGRESS_ALLOWLIST.md).
• Releases carry provenance: SLSA L3 build attestation on the dot archive (gh attestation verify), an SPDX SBOM signed with Cosign keyless (Fulcio + Rekor), and one signed ALL_SHA256SUMS manifest covering every asset; the verification recipe is docs/security/VERIFY_RELEASE.md.
• Signed everything: SSH ed25519 commit signatures enforced on main, signed annotated tags verified by workflow, DCO and PR signature checks required, GPG key published over WKD and checked weekly (verify-gpg-wkd.yml).
• npm via OIDC trusted publishing with provenance attached, no long-lived token.
• Scans on every push: dependency review (fail-on-severity: high), CodeQL, Checkov, Grype against the SBOM, Dependabot with grouped updates; OpenSSF Scorecard weekly, with the snapshot in docs/security/SCORECARD.md refreshed by hand (scripts/qa/scorecard-snapshot.sh).
• SPDX headers on source files, checked by the copyright lint job.

Notes

• Template injection is a real surface for a chezmoi tree: .tmpl files render with chezmoi data before deployment, so .chezmoidata.toml is schema-validated and the trust boundary is documented per surface in the threat model.
• _cached_eval output files under ~/.cache/shell/ are sourced on startup; the cache key includes the tool binary's mtime and realpath so a swapped binary invalidates its cache.

Documentation

The four entry points, identical across every repo in the family:

• User Manual — the rendered book: concepts, tutorials, reference, cookbook, appendices; also dot help --manual, dot help --manual pdf, dot help --manual text | less, and dot help --manual --offline from the bundled snapshot
• Command reference — every dot subcommand, generated from the plugin manifests; man dot after install
• Developer docs — toolchain, task map, reproducing every CI gate locally
• Family map — what lives in-repo, the component that owns it, and where to make which change

The manual is published in nine formats (single- and multi-page HTML, PDF, EPUB, ASCII text, compressed variants, Markdown source) and rebuilds on every change from docs/manual/.

Acknowledgements

This framework stands on tools whose maintainers did the hard part: chezmoi for the source-tree model that makes every apply reproducible, mise and Nix for toolchains that survive a reinstall, age and SOPS for secrets that stay encrypted, and the Charmbracelet libraries behind the Go satellites. The security posture leans on Sigstore, SLSA, OpenSSF Scorecard, and StepSecurity Harden Runner.

Bug reports with a reproduction and a failing test are the most useful contribution this project receives; the regression-test convention in CONTRIBUTING.md exists so that every one of them stays fixed.

Stability guarantees

• Versioning. SemVer with defaults/.chezmoidata.toml as the source of truth, mirrored to the non-template version surfaces by scripts/version-sync.sh and checked in CI. During the 0.2.x series every release is a patch bump; a change that breaks an existing machine (a renamed command, a moved managed path, a changed flag default) is called out in its CHANGELOG.md entry and, where relevant, in docs/operations/MIGRATION.md with a migration or rollback script under install/migrate/ (GOVERNANCE.md).

• Output stability. For a tool that generates files, output is API. Machine-readable outputs carry a schema version — dot tool export conforms to docs/schema/dot-env-v1.json, the registry index to docs/schema/dot-registry-v1.json — and a change to their shape is a new schema version, not an edit to v1. Generated artefacts that other tools consume (themes.toml, shell completions, AGENTS.md and the harness stubs, the command index) are produced by generators whose output is diffed in CI; a behavioural change to what a generator emits is treated as breaking and recorded in the changelog even when no command-line flag moves. The human-facing text of dot --help, version, doctor, perf, and health is pinned by golden snapshots and changes only with a deliberate snapshot update in the same commit.

• Minimum toolchain. Raised only with the reason recorded in the CHANGELOG.md entry, never silently — policy, version axis, and history in docs/MINIMUM-TOOLCHAIN.md.

• Deprecations are announced before removal with the removal release named up front: docs/reference/ALIASES_DEPRECATIONS.md records each deprecated alias, its replacement, and its Remove In version, and dot shell alias show <alias> reports the same from the CLI. The deprecation window is the span between the release that adds the row and the release named in Remove In.

License

Dual-licensed under Apache 2.0 or MIT, at your option. See LICENSE-APACHE and LICENSE-MIT.

See CHANGELOG.md for release history.

THE ARCHITECT ᛫ Sebastien Rousseau THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

Back to Top