Dotfiles

Appearance

Host lanes ​

The repo supports four lanes with different responsibilities.

WSL ​

WSL is the default lane for active repos, Codex and Claude work, Linux shell workflows, and development state. Keep active project paths under the Linux filesystem, for example /home/alvaro/code/project.

Ubuntu WSL uses apt with repo-owned upstream sources where the base distro lags the workstation policy. Fish comes from the official Fish 4 PPA so shell validation matches the managed Fish 4 configuration.

Mise owns agent CLIs and portable development tools on this lane.

CachyOS ​

CachyOS is the native Linux desktop lane. It shares the Unix-like shell and tool policy with WSL, but desktop integrations should stay explicit and small.

Mise owns agent CLIs and portable development tools on this lane.

Droplet ​

Droplet is the headless Ubuntu/Linux Codex host lane. Select it explicitly with machine = "droplet" before rendering or applying dotfiles on that host.

Droplet keeps the shared Unix CLI, Bash, Fish, tmux, Git, Codex, Claude, and agent wrapper files, but omits GUI editor, VS Code Server, Windows AppData, PowerShell, WSL bridge, Ghostty, Konsole, KDE/fontconfig/MIME/autostart, CachyOS theme, and native Linux Zed bridge files. Its default shell and terminal editors are Bash and Micro.

Normal droplet rendering and smoke validation must not run broad mise installs, package-manager commands, or GUI setup. Package/bootstrap work belongs behind a separate explicit droplet bootstrap command:

bash
just droplet-bootstrap-preview
just droplet-bootstrap-core
scripts/install-prereqs-droplet.sh --dry-run --codex-tools
scripts/install-prereqs-droplet.sh --codex-tools

The core mode configures official GitHub CLI, mise, and Ubuntu Fish 4 apt sources, installs platform prerequisites, loads the Ubuntu 24.04 bubblewrap AppArmor profile when present, and leaves the login shell unchanged. --codex-tools is intentionally separate: it installs the default droplet agent/SSH toolset with flock, timeout, one-tool-at-a-time mise calls, and before/after process summaries.

Native Windows ​

Native Windows owns PowerShell, Scoop and winget bootstrap, GUI app setup, and Windows-specific path behavior. PowerShell is a peer shell, not a Bash clone. The native lane uses windows/tools.json as the tool-first inventory for Scoop, winget, mise, and direct-download exceptions. PowerShell profile stubs belong to the Scoop-owned pwsh profile paths rather than OneDrive-backed CurrentUser profile files. The accepted Windows mise policy is bounded normal PowerShell activation: the profile sources cached mise activate -q pwsh output, the cache refresh path strips generation-time PATH assignments and wraps mise hook-env with a timeout, and the profile does not use --shims activation or manual shim PATH priority.

The Scoop inventory bootstraps mise; the shared mise config then owns Codex, Claude, and other portable developer tools on native Windows, matching WSL and CachyOS.

Desktop and default-app management starts from status/export commands. Apply paths must be idempotent, backed by state exports, and explicit about admin-only or SetUserFTA-only operations.

Cross-lane policy ​

Chezmoi templates should express host differences directly. Avoid duplicate full files when a narrow template or host gate will keep the policy clear.

Node and pnpm remain managed for docs, npm-distributed CLIs, and ordinary JavaScript/TypeScript projects that declare them.