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 re-runs all install scripts (which skip already-installed tools). upgrade does the same but also enables Homebrew upgrades and forces cargo-binstall to re-check for newer binaries.

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 package → packages/pip.txt, then:
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_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 profile is already danger-full-access
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 is intentionally autonomous: sandbox_mode = "danger-full-access" with granular approvals (approval_policy = { granular = { rules = true, ... } }) so the execpolicy prompt rules (rm, git reset –hard, git push) stay live. Use -p deep (workspace-write) or -p review (read-only) to opt into tighter sandboxes.

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.