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

8 August 2026

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 durable thesis is now broader:

Dotfiles has evolved from reproducible personal configuration into a governed development and agent harness that makes environment state, capabilities, semantic tooling, validation and mutation boundaries inspectable.

This Project page is not a changelog. The public series v0.3 → v0.4 → v0.5 carries the evolution narrative; this page keeps the stable map.

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.

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. Docker is used where a bounded runtime improves repeatability, including selected MCP services and Playwright-based browser tooling.

The shared harness: devx

On top of that foundation, Dotfiles materialises a shared operational harness:

devx
→ agent capability discovery
→ inventory / orientation
→ project diagnostics
→ tool ownership
→ GitNexus freshness and risk
→ Serena semantic intelligence
→ Playwright facade
→ governed release operations

A core current principle: contracts belong to the consuming project. Dotfiles does not impose every language server or tool choice on every repository. It diagnoses readiness; it does not silently mutate another project’s semantic configuration.

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.

Evolution series

Recent harness lessons live in the Spanish editorial series (canonical public narrative for now):

• v0.3 — capabilities, Serena and governed releases
• v0.4 — inventory, diagnostics and evidence-aware risk
• v0.5 — project-owned semantics and frictionless localhost

These articles are published in Spanish first; this English Project page keeps the durable map without requiring parallel article translations yet.

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 — including when the operator is an agent.