Day-to-day workflow

Update and upgrade

~/dotfiles/bootstrap.sh update    # pull latest + refresh tools (no brew upgrade)
~/dotfiles/bootstrap.sh upgrade   # update + brew upgrade + cargo upgrade
~/dotfiles/bootstrap.sh           # full install (same as first run, idempotent)

update pulls the repo, applies chezmoi, refreshes zsh plugins, and reconciles missing tools while holding existing Homebrew and Go packages. upgrade also refreshes Homebrew, Go, Rust/Cargo, Node/npm, uv tools, Julia, TeX, and extensions, then runs the strict JSON toolchain audit.

Run the read-only audit independently with:

bash ~/dotfiles/install/audit-versions.sh | jq .

Add a package

See Package management for the priority order. Quick reference:

# Rust tool → packages/cargo.txt, then:
bash ~/dotfiles/install/rust.sh

# Homebrew formula/cask → packages/Brewfile, then:
brew bundle --file=~/dotfiles/packages/Brewfile

# Python core → packages/pip.txt; optional full tools → packages/pip-full.txt
bash ~/dotfiles/install/python.sh

Edit a dotfile

chezmoi edit ~/.zshrc          # opens in $EDITOR, applies on save
chezmoi edit ~/.zprofile       # zsh login shell
chezmoi edit ~/.bash_profile   # bash login shell
chezmoi edit ~/.gitconfig

Or edit the source directly and apply:

$EDITOR ~/dotfiles/home/dot_zshrc.tmpl
$EDITOR ~/dotfiles/home/dot_zprofile.tmpl
$EDITOR ~/dotfiles/home/dot_bash_profile.tmpl
chezmoi apply

Preview before applying: chezmoi diff

Sync dotfiles from the repo

chezmoi update                 # git pull + chezmoi apply

AeroSpace config (v2)

Window-management docs are now in AeroSpace window management.

Update AI agent instructions

Claude and Codex now diverge intentionally:

chezmoi edit ~/.claude/CLAUDE.md
chezmoi edit ~/.codex/AGENTS.md

Use ~/.claude/CLAUDE.md for Claude-specific memory and ~/.codex/AGENTS.md for Codex-specific guidance. Keep only genuinely shared preferences aligned.

Claude Code’s status line is a custom bash script at home/dot_claude/executable_statusline.sh (no npm dependency). Edit it with chezmoi edit ~/.claude/statusline.sh. The header comment documents the shape; DEBUG=1 env var dumps parsed input + intermediate values to stderr.

Codex also has global skills and rules (edit source-of-truth in the repo):

$EDITOR ~/dotfiles/home/dot_codex/create_private_config.toml
$EDITOR ~/dotfiles/home/dot_codex/rules/dotfiles.rules
chezmoi apply
~/dotfiles/install/codex.sh sync-config

Codex binary/config health commands:

~/dotfiles/install/codex.sh upgrade      # install latest binary + sync config + healthcheck
~/dotfiles/install/codex.sh sync-config  # sync managed config; preserve runtime trust sections
~/dotfiles/install/codex.sh check        # verify binary, profiles, and rules

Skills live under home/dot_claude/skills/ in the repo, apply to ~/.claude/skills/, and reach Codex/opencode/pi through the ~/.agents/skills symlink. Custom domain skills included:

• web-shipping
• simulation-lab
• compiler-workbench
• game-systems

Custom Codex themes live under home/dot_codex/themes/ and sync to ~/.codex/themes/:

• neon-noir
• sunburst-candy
• minty-terminal

Useful Codex commands after updating:

codex --profile fast
codex --profile review
codex --profile deep
codex   # default: Sol/high, unrestricted host access, no prompts
codex -c 'tui.theme="neon-noir"'
codex -c 'tui.theme="sunburst-candy"'
codex -c 'tui.theme="minty-terminal"'
codex mcp list
codex execpolicy check --pretty --rules ~/.codex/rules/dotfiles.rules -- git status
codex '$env-reconciler Map this repository and propose the first validation step.'
codex '$simulation-lab Define state variables and a minimal validation case for this model.'

Codex schema note: profiles are delta-only overlay files at ~/.codex/<name>.config.toml with top-level keys (Codex 0.134+); the old [profiles.*] tables in config.toml are ignored. Managed sources: home/dot_codex/{deep,review,fast}.config.toml.

Default Codex mode uses the built-in :danger-full-access permission profile and approval_policy = "never". MCP and connector tools are also configured for prompt-free execution. Use -p deep for extra-high reasoning, -p fast for Luna/low, or -p review for deliberately read-only work.

Add an env var or PATH entry

Edit both home/dot_zprofile.tmpl and home/dot_bash_profile.tmpl (they should stay identical). For anything arch-specific use $_LOCAL_PLAT (set at shell startup):

export MY_TOOL_HOME="$_LOCAL_PLAT/my-tool"
export PATH="$MY_TOOL_HOME/bin:$PATH"

Also add the variable to install/_lib.sh so install scripts can reference the same path.

Work on the docs

cd ~/dotfiles/docs && mdbook serve --open   # live reload at localhost:3000

Every push to main auto-deploys to dotfiles.cade.io via Cloudflare Pages.

Deploy infrastructure changes

cd ~/dotfiles/infra/cloudflare
export CLOUDFLARE_API_TOKEN=...
tofu plan     # preview
tofu apply    # apply

terraform.tfvars is gitignored — it holds account_id and stays local.

Commit and push

cd ~/dotfiles
git add -p                    # stage selectively
git commit -m "description"
git push

Natural commit points: one commit per feature, config change, or coherent set of package additions.