v1.7.0

update-all is now a real command that always runs its own latest fix, and Groundwork's platform support is now an explicit contract

update-all: from shell function to launcher + runner

Previously update-all was a shell function baked into ~/.zshrc, so a terminal that was already open kept running the old copy — a fix shipped for update-all itself never applied to the run that delivered it. It is now two real commands:

• ~/.local/bin/update-all — a stable launcher that pulls and applies Groundwork, then hands the same invocation to the freshly applied runner.
• ~/.local/bin/groundwork-update-run — the actual stages. Because the launcher execs the copy the sync just installed, a fix delivered by chezmoi update governs the rest of that same run. No shell reload, ever again.

Everything the old function did is preserved: the three-attempt brew update retry gate that stops before upgrading against stale metadata, brew upgrade --greedy-latest on macOS (avoids re-quarantining self-updating apps), autoremove/cleanup, relaunching always-on apps Homebrew quit, mise upgrade, the Xcode-beta reminder, and a success timestamp written only after the complete batch.

One-time step for existing users: terminals that were open before this update still have the old function in memory — run exec zsh once in those (a notice during chezmoi update explains this). Fresh installs and new terminals need nothing.

An honest platform support contract

Groundwork supports Linux directly; WSL2 is one supported way to run that Linux environment on a Windows-owned machine — and native Linux is the recommendation if you want no Microsoft dependency.

• macOS — full experience. Ubuntu LTS (native or WSL2) — the primary tested Linux path. Debian and Fedora stable — targeted next, promoted to supported as CI receipts land. WSL1 and native Windows shells (PowerShell, CMD, Git Bash) — unsupported, and they now fail closed with clear guidance instead of partially working.
• New groundwork-platform reports darwin / linux / wsl2 / wsl1 / wsl-unknown / unsupported, correctly classifying older microsoft-standard WSL2 kernels and refusing to guess on ambiguous ones. New groundwork-distro reports the distribution, with --family for bootstrap decisions.
• The update runner fails closed before touching anything on unsupported platforms, the Linux runner drops macOS-only cask policy, and Groundwork never mutates the operating system it runs inside: no apt/dnf/pacman upgrades on Linux, nothing on the Windows host from WSL2.
• new-project refuses to scaffold repositories onto Windows-mounted drives (/mnt/c/...) under WSL — keep code in the Linux filesystem (~/code) where performance and file watching actually work.
• The platforms page and command catalog document the contract and the command-ownership rule.

After chezmoi update

Run exec zsh once in already-open terminals if prompted; nothing else. Future update-all improvements take effect during the same run that fetches them.

v1.6.1

Fixed

• update-all now attempts brew update up to three total times with short backoff when the Homebrew metadata or repository refresh fails.
• Ctrl-C and termination stop immediately instead of starting another attempt.
• Package upgrades use the successfully refreshed metadata without triggering a second automatic Homebrew update.
• A failed refresh or later runtime upgrade leaves the previous successful-update timestamp unchanged.

Verification

Groundwork now tests first-, second-, and third-attempt success, persistent failure, interruption statuses, exact brew update arguments, stage ordering, and timestamp integrity through the rendered update-all function.

Get it

Run chezmoi update or update-all. Open a new shell, or run source ~/.zshrc, before using the updated function in an existing terminal.

v1.6.0

New command: groundwork-doctor

A read-only machine health report. It never installs, deletes, prunes, or changes settings — it tells you what it found and hands you the owner-scoped way to act on it.

The first module covers Docker machine health:

• Daemon reachability (with the right start command for your setup).
• Engine hygiene: warns when container logs don't rotate (log-driver not local) and when the containerd image store — which local multi-platform builds expect — is off. Work Macs get both from the managed Colima template; on Docker Desktop these are one-time settings the doctor now verifies instead of trusting.
• Disk usage (docker system df) plus a leftovers count: stopped containers, dangling images, dangling volumes — with guidance that routes cleanup to each repo's own clean commands and warns against blanket docker system prune.

Run groundwork-doctor any time disk feels tight, or after setting up a machine. groundwork-help doctor shows the catalog entry. Planned next module (see ROADMAP): competing-app detection.

After updating

Run chezmoi update, then try groundwork-doctor. If it warns about log-driver, the Platforms page has the exact Docker Desktop engine JSON to paste.

v1.5.0

Find disk space, clean it up safely

New command: largest. Run largest ~ (or any path) to see the 50 largest files and folders, followed by a cleanup guide that routes each kind of result to the tool that owns it — apps to their uninstaller, project output to its build tool, caches to brew cleanup/pnpm store prune, containers to Docker's own tools. Use --files or --folders to narrow, -n 25 to change the count, largest --help for everything. On macOS, give your terminal Full Disk Access for a complete root-drive scan.

New app on personal Macs: AppCleaner — for removing plain dragged-in apps and their leftovers. The docs teach the removal order that matters: vendor uninstaller first, brew uninstall --cask for Homebrew apps, AppCleaner for the rest (Apps).

Containers

• The headless image now includes dust, so largest works inside agent containers too.
• The Platforms page now documents the repo's devcontainer (open Groundwork straight into a container from VS Code, Cursor, or Codespaces), current agent-sandbox options (bounded docker run, Docker Sandboxes microVMs, Anthropic's firewalled devcontainer), and daemon alternatives (OrbStack, Apple's container).

After updating

Run chezmoi update, then brew bundle --file ~/.config/homebrew/Brewfile (or your usual update flow) to get dust and AppCleaner. Try largest ~ — and read the cleanup guide it prints before deleting anything.

v1.4.6

Fix: a failed repair step explains itself

If you accept a Homebrew repair and a step fails — most often a transient network error downloading Homebrew's package index — Groundwork now says which command failed and what to do: nothing is half-applied, just re-run chezmoi apply and the whole sequence retries. Previously the raw brew error collided with the app-relaunch messages and looked worse than it was.

Nothing to do after updating.

v1.4.5

New: Groundwork offers to run Homebrew's own fix

When Homebrew hits a known-broken state — like the circular libtiff/webp dependency some machines saw — it prints its own remediation commands. Groundwork now catches that during chezmoi apply and offers to run them for you:

• The exact commands are shown in full and validated against a strict whitelist (plain brew invocations only — a tampered suggestion is refused).
• Nothing runs without you answering y at the prompt. Decline, and the commands are left on screen to run yourself.
• On yes, the repair runs and the install retries once, automatically.
• Headless and CI runs never prompt: they print the commands and exit for the operator.

Nothing to do after updating — the next time Homebrew breaks itself, Groundwork will ask instead of stopping.

v1.4.4

Fix: one failed package no longer takes down the recovery steps

If a Brewfile package fails to install, the bundle script previously aborted on the spot — meaning the always-on app relaunch never ran, so an unrelated failed cask could leave Raycast or Karabiner down. Now the relaunch guard always runs, and the script still exits non-zero afterwards (so the next chezmoi apply retries what's missing) with a message that says exactly that: everything installed stays installed, only the missing pieces retry.

update-all also runs brew autoremove, clearing orphaned dependency formulae — the deprecated versioned leftovers (like an old icu4c) that otherwise warn on every upgrade forever.

Nothing to do after updating.

v1.4.3

Fix: the quiet download phase announces itself

Homebrew downloads casks in parallel, and even with verbose output the fetch phase can sit quiet for minutes on a fresh install — which looks like a hang. Now:

• Before fetching, Groundwork prints a heads-up: a fresh install downloads several gigabytes in parallel and can look quiet for stretches; it has not hung, and interrupting only delays it (downloads resume).
• Homebrew emits a heartbeat dot (at most one per minute) whenever it would otherwise be silent, via HOMEBREW_VERBOSE_USING_DOTS.

Pairs with v1.4.2's verbose streaming. Nothing to do after updating.

v1.4.2

Fix: setup survives interrupts, and long installs show progress

If you ever hit Ctrl+C during chezmoi apply/update (or lose power mid-run), Groundwork already recovered cleanly in most places — completion markers are written last, interrupted install scripts re-run, backups and resets never lose data. This release closes the remaining gaps:

• Big installs stream progress. brew bundle now runs verbose, so a multi-gigabyte fetch shows each download instead of printing one "Fetching …" line and looking hung — the exact situation that invites an unnecessary Ctrl+C.
• A half-cloned tmux plugin manager heals itself. An interrupted clone used to pass the directory check and silently break tmux plugins; it now re-clones.
• The "config file template has changed" nag self-heals. update-all runs chezmoi update --init, regenerating the config from your saved answers — no prompts re-asked, no manual chezmoi init needed.

Nothing to do after updating.

v1.4.1

Fix: always-on apps come back after updates

Homebrew quits a GUI app to replace its cask during an update and never relaunches it. Groundwork already reopened Karabiner-Elements; now the same guard covers every always-on app: Raycast (so ⌘Space keeps answering), BetterDisplay, and Anybox, alongside Karabiner.

After chezmoi update or update-all, any of these that is installed but not running is reopened automatically. The old groundwork-karabiner-start helper is retired and removed from your machine on the next apply; groundwork-apps-start replaces it. Windowed apps with their own updaters (password managers, editors, Docker) stay user-managed on purpose.

Nothing to do after updating.