Dotfiles

Appearance

Tool manifest ​

This manifest is hand-maintained. It records ownership policy, not every installed binary on every host. The ownership matrix gives the detailed lane, install, upgrade, apply, and validation boundaries.

mise ​

Mise owns versioned developer tools and portable CLIs. Project-local versions still win when a project declares them.

On the droplet lane, mise has a narrower default role. Normal upgrade does not run the broad shared mise inventory; the default droplet agent/SSH toolset is installed only through scripts/install-prereqs-droplet.sh --codex-tools, after the dry-run preview, using the apt-managed /usr/bin/mise path.

Examples:

  • Node, pnpm, Python, uv, Ruff, Rust, and npm-managed CLIs.
  • Codex, Claude Code, and validation tools such as just, shfmt, shellcheck, taplo, actionlint, typos, markdownlint-cli2, cspell, gitleaks, lychee, zizmor, and Linux-only bats-core.
  • codex-acp, the Zed Agent Client Protocol adapter used by managed Zed external-agent profiles. Claude remains a terminal-task integration until a verified Claude ACP adapter is adopted.
  • Workstation CLIs such as rg, fd, bat, delta, lazygit, yazi, chezmoi, starship, atuin, direnv, zoxide, fzf, navi, carapace, hurl for repeatable HTTP/API request files, jless for JSON inspection, ouch for archive operations, vivid for themed LS_COLORS, tealdeer for the tldr command, and experiment-only Neovim.
  • Writing CLIs such as typst, tinymist, typstyle, pandoc, glow, tectonic, Mermaid CLI, and presenterm.

OS package managers ​

Use apt on WSL and droplet, and pacman on CachyOS, for platform packages, system libraries, desktop integrations, and tools that are better owned by the OS.

Examples:

  • WSL prerequisites such as GitHub CLI apt setup and distro packages.
  • Droplet prerequisites such as GitHub CLI, mise, Fish 4, AppArmor/bubblewrap, tmux, micro, and other headless Codex host packages.
  • CachyOS desktop and editor prerequisites.
  • Linux system packages such as btop where the distro is the better owner.
  • micro, the terminal editor fallback installed early enough for emergency edits before higher-level editor tooling is ready.
  • Zed on CachyOS through the Arch/CachyOS zed package; the repo manages settings but not Zed extensions outside Zed's own extension mechanism.

Windows managers ​

Native Windows uses the tool-first inventory in windows/tools.json to assign winget, Scoop, mise, direct-download, and manual ownership. Git for Windows is platform infrastructure.

Examples:

  • PowerShell, mise bootstrap, Scoop buckets and apps, GUI editors, fonts, and Windows-only utilities.
  • micro, owned by the core Scoop bootstrap as the terminal editor fallback.
  • Zed, owned by the official winget package ZedIndustries.Zed during GUI bootstrap because the repo should not depend on an unofficial Scoop manifest for this editor.

PowerShell Gallery owns PowerShell modules that are not portable mise tools. PSScriptAnalyzer is optional and used only by the explicit just windows-lint target when installed.

Fish plugins ​

Fish plugins are intentionally small and pinned in the managed fish_plugins file. Starship owns the prompt; Fisher is only the lightweight plugin manager.

Current plugin candidates and managed entries should support the Fish-first interactive shell without adding a large framework.

Editor managers ​

Editor extension managers own editor-specific packages:

  • Zed extensions installed by Zed itself through auto_install_extensions; the repo manages first-class Zed settings, keymaps, tasks, and Codex ACP agent entries.
  • VS Code extension manifests under editors/vscode/.

Neovim has no editor-manager layer in this repo yet. Mise keeps the nvim binary available for manual trials, but chezmoi must not render Neovim config, plugin, keybinding, LSP, or default editor wiring.

Theme assets and desktop apply commands ​

Theme assets are not ordinary developer tools. Existing Catppuccin terminal, editor, shell, and CLI theme settings stay owned by home/.chezmoidata/theme.toml and the relevant editor managers.

CachyOS desktop theme work must keep package or asset installation separate from user-visible desktop mutation:

  • Theme engine dependencies belong to the CachyOS or Arch package manager after current package-name verification.
  • MacTahoe and WhiteSur assets belong to a user-local upstream install or a verified AUR package after current source verification.
  • Plasma, KWin, Kvantum, GTK, icon, cursor, wallpaper, panel, Flatpak override, and SDDM/login config writes belong only behind explicit dotfiles-cachyos-theme apply-*, rollback, or restore commands.
  • chezmoi apply, just upgrade, and package refresh paths must not apply or re-apply desktop themes or panel layouts.

Optional lanes ​

Optional tools belong in optional manifests or workflow-specific docs until a workflow actually uses them. Current optional workstation tools are hexyl for binary inspection, numbat for unit-aware calculations, and Linux-only zellij for terminal workspace evaluation. Do not add tools only because they look useful.