A development environment designed as a system, not a pile of files.

Dotfiles began with shell configuration, but the interesting problem was never file synchronisation alone. The real challenge was rebuilding an Ubuntu or WSL2 workstation without relying on remembered steps, hidden machine state, or a script powerful enough to damage the environment it was meant to restore. The project has grown into an operational architecture for configuration, encrypted secrets, local tooling, and agent-assisted development.

Reproducibility needs boundaries

Copying files can reproduce an output while obscuring the process that produced it. A new machine has different needs from an existing workstation, applying user configuration is not the same operation as updating installed tools, and a diagnostic command should not quietly mutate either one.

Dotfiles makes those boundaries explicit. Read-only inspection is the default for operational diagnostics. Commands that change the system require deliberate invocation. Documentation records not only the expected path but also the risks and prerequisites around it. Safety is therefore part of the interface rather than a warning added after the automation was written.

Three operational layers

The system separates three lifecycles:

• Bootstrap checks readiness and prepares dependencies for a new environment.
• Materialisation lets Chezmoi calculate and apply the intended user configuration.
• Maintenance updates the system and its tools without pretending to replace Chezmoi’s materialisation step.

SOPS and age keep secrets encrypted at rest and support the generation of local configuration during materialisation. Private machine state stays outside the portable source. Docker is used where a bounded runtime improves repeatability, including selected MCP services and Playwright-based browser tooling.

This separation makes failure easier to reason about. A dependency problem belongs to bootstrap, configuration drift belongs to materialisation, and an outdated runtime belongs to maintenance. The operator can investigate one layer without treating the whole workstation as an opaque installer.

Developer experience as an engineering surface

Make provides discoverable entry points, while development utilities compose diagnostics and common workflows. The goal is not to conceal the underlying tools. It is to give humans and agents a shared operational language: inspect before applying, distinguish validation from mutation, and run the narrowest command that proves a change.

Agent workflows follow the same model. The repository maintains instructions, skills, MCP manifests, and governance checks while keeping canonical sources distinct from generated runtime artefacts. GitNexus supports code-relationship exploration and knowledge indexing, with mutating index operations still governed explicitly rather than hidden inside routine checks.

Tests that respect the environment

The project treats validation as a first-class architectural layer. Bats suites exercise contracts around Chezmoi, commands, hooks, MCP configuration, profiles, shell behaviour, GitNexus, and system-operation guardrails. Focused Python tests cover specialised tooling. GitHub Actions runs the CI aggregate alongside MCP governance, linting, and secret checks.

Just as importantly, tests use fixtures and constrained environments instead of applying configuration to the real home directory. A dotfiles test suite would undermine its own purpose if proving correctness could alter the workstation under test.

What the project demonstrates

Dotfiles is an example of treating personal infrastructure as a maintained product: responsibilities are separated, automation is observable, secrets remain outside public content, operational knowledge is versioned, and validation effort follows risk. The outcome is not a promise that every machine becomes magically identical. It is a comprehensible process for rebuilding an environment, detecting drift, and deciding when a change is safe to apply.