What chezmoi is, and why you run it.

Files in the repo start with dot_ instead of a dot so they're visible and easy to work with. A .tmpl ending means the file has blanks chezmoi fills in per machine — your name, your email, whether it's a work computer. That's how one repo serves many people without hard-coding anyone.

Groundwork starts with the role derived from the bootstrap facts and on stable application channels. Environment role, release posture, and the optional Xcode beta channel are preferences you can revisit, so bootstrap does not ask for them. Run groundwork-configure later; Xcode beta appears only when Xcode is enabled, while groundwork-profile set preview is the focused release-posture shortcut. Accepting applies the selected desired state immediately, and groundwork-doctor --browser reports the stored posture and Xcode states.

Groundwork treats Docker as a way to run the environment, not as a standalone lesson. Linux and WSL2 get the shared terminal layer: shell, Git, tmux, Neovim, mise/uv, helper scripts, and agent instructions. macOS GUI apps, App Store apps, browser helpers, and macOS defaults are skipped when .chezmoi.os is not darwin; on macOS, the server/CI prompt lets a headless Mac skip the same desktop layer.

The Docker image is the non-interactive headless profile for agents, CI, and disposable shells. From the repo root, build it with docker build -t groundwork . and run docker run -it --rm groundwork. Keep that groundwork tag for the image you actually use; when you or an agent rebuild only to test a Dockerfile change, build it with groundwork-docker-build-scratch <purpose> . instead — the wrapper applies the ephemeral labels and the groundwork/scratch:<purpose> tag so groundwork-docker-tidy can remove it later — see Platforms for the contract. Personal Macs can use Docker Desktop; work Macs use Colima plus the Docker CLI, so start the daemon with colima start first. This does not try to teach Dockerfiles, Compose, or app hosting; it just gives the Groundwork terminal environment somewhere reproducible to run. See Platforms for the profile-by-profile split.

Groundwork does not install unattended Homebrew or mise upgrade jobs. Run update-all intentionally and skim its consolidated receipt. One machine-wide lock prevents terminals or agents from racing the same update. Groundwork synchronizes first, hands the invocation to the freshly applied runner, inventories every Homebrew formula and cask, and verifies matching formula and cask metadata before mutation. Ordinary outdated casks use the normal exact-token lane. Checksummed self-updating and safely verifiable latest-version casks enter separate greedy-aware lanes only when the matching outdated query selects them; bare global --greedy remains prohibited. Current privileged casks stay quiet. A cask upgrade matches Homebrew's own default of quitting and reopening an app that declares a safe quit action; update-all --no-app-quit is the explicit one-run opt-out, deferring each observed running cask individually and passing Homebrew's --no-quit guard at mutation time. Mac App Store inventory uses the reviewed mas 7.x JSON-object stream from list --json and outdated --json --inaccurate; names containing parentheses remain ordinary data, and inventory does not start or cancel downloads. Before each mutation, interactive stdin and stderr are required and sudo -v visibly establishes macOS authorization in the foreground terminal process group while a separate watchdog enforces its deadline; the exact sudo -n mas update ID then runs in one owned process group under a conservative 30-minute backstop. A timeout names the exact app on elapsed notices, closes only its tree, and lets the next exact ID continue. Redirected, CI, or cron-style runs never prompt or mutate App Store apps; they report each one action-required and continue independent safe lanes. Pins, explicitly policy-declared vendor self-updaters, deprecated or disabled tools, manual/MDM ambiguity, and other owner-review items stay visible without becoming false failures or suppressing unrelated safe updates. Actual inventory, classification, mutation, or post-update verification failures remain nonzero while independent safe lanes continue. A nonzero Homebrew command always names its exact sub-lane and tokens, even when Homebrew emits no literal error line. Package maintenance and bounded Docker scratch cleanup retain their narrower ownership contracts, and arbitrary repository dependencies remain untouched. The optional action receipt shares the maintenance invocation ID and binds its immutable maintenance receipt by filename and SHA-256.

If ChatGPT exists in /Applications but Homebrew does not own it, update-all omits the conflicting Brewfile install and completes every safe lane. After the update transaction releases its lock, an interactive run first executes groundwork-app-adopt --check chatgpt, then asks Let Homebrew manage ChatGPT.app? [y/N] only when the current observation is eligible. A literal yes invokes the separately locked groundwork-app-adopt --yes chatgpt helper, which revalidates before mutation. A redirected run prints the review command and never prompts. Adoption uses Homebrew's identical-artifact path only after codesign --verify --deep --strict succeeds and bundle identity, signing team, ownership, running state, and MDM state are exact; those checks repeat after consent. It never forces, uninstalls, deletes, reinstalls, zaps, or takes over a device-managed app.

Fresh Groundwork setup declares only the current unified ChatGPT.app. ChatGPT Classic.app is the previous supported app and remains useful for known compatibility or existing Enterprise workflows, but it is a legacy duplicate for most people. Only after current-app ownership is verified may an interactive run separately ask Remove ChatGPT Classic.app while preserving shared data? [y/N]. Enter/no keeps it; yes invokes the separately locked groundwork-app-remove chatgpt-classic. A noninteractive run prints the command and never removes anything. The deprecated Codex.app / codex-app receipt is a third identity and routes only to groundwork-app-remove codex-app; a shared bundle identifier never establishes ownership. The removal command strictly verifies the current and legacy app signatures before reading their OpenAI signing teams, verifies exact bundle identities and Homebrew artifacts again after consent, refuses running or device-managed state, and shows what remains. Manual Classic moves to Trash; Homebrew-owned targets use only their reviewed cask uninstall. It never uses --zap or removes shared Application Support, preferences, chats, credentials, or unrelated data.

On a desktop Mac, a successful update ends with a Karabiner health postflight. An unusually large Core Service footprint or a Karabiner version change prints the observed PID, uptime, RSS, footprint, and compressed memory. A terminal gets Restart Karabiner now? [y/N]; yes invokes the supported restart helper and requires a changed root PID, while Enter or no preserves the service and prints the manual command. A headless or redirected run never restarts it and prints groundwork-karabiner-restart instead. Plain chezmoi update, init, and apply remain configuration operations and do not restart an already-running keyboard service.

A maintenance failure preserves completed updates, records the failed manager, helper, or Docker scratch lane, exits nonzero, and keeps the shell reminder active until a later repair; pending pnpm repair overrides ordinary cadence. Run update-all again for the normal retry. To retry package-manager maintenance without repeating upgrades, run groundwork-cleanup --yes; it keeps the normal pnpm cadence. Retry only Docker scratch maintenance with groundwork-docker-tidy --yes; a successful direct retry clears its own pending record. If Docker was intentionally removed and the retry is impossible, groundwork-docker-tidy --yes --clear-pending acknowledges only that reminder and preserves an audit note. Use groundwork-cleanup --yes --force only for the exceptional case where you deliberately want to ignore pnpm cadence. Repository dependency installations such as node_modules are not modified. Homebrew autoremove may remove installed orphan formula dependencies, while requested formulae and casks remain. The advanced groundwork-cleanup command reports exact package-manager candidates without changing persistent state. If a package manager was intentionally removed, groundwork-cleanup --yes --clear-pending <stage> acknowledges only its unrepairable reminder and preserves an audit note. update-all --skip-maintenance exists for an exceptional fast refresh, not the normal workflow.

Existing users receive one migration notice because an old update-all() function already loaded in a terminal can shadow the new executable. Run exec zsh once in those terminals. After that transition, future command updates take effect during update-all itself without another shell reload.

AI tools are the fast-moving exception: Claude Code stays on its vendor-supported latest path, while Codex and OpenCode refresh through Homebrew in the visible update-all path.