Day-to-day workflow

Use the normal bootstrap for updates; edit managed sources for configuration changes.

Task	Jump to
Refresh tools	Update and upgrade
Install something new	Add a package
Change configuration	Edit a dotfile · Agent instructions
Change this site	Work on the docs

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

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

---

Edit a dotfile

chezmoi edit ~/.zshrc          # edit the managed source
chezmoi diff ~/.zshrc          # inspect the pending change
chezmoi apply ~/.zshrc         # apply this target
exec zsh -l                    # load it in a new login shell

Find other targets in the configuration map. Plain chezmoi edit edits source only; --apply applies after editing and --watch applies on save.

---

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

Change shared guidance once; keep harness-specific behavior in its wrapper.

Change	Authoritative source / guide
Shared preferences and tone	Instruction architecture
Codex profiles, roles, rules, or themes	Codex guide · managed sources
Claude hooks and status line	Claude guide · status-line source
A skill	Skill ownership and sync

For a Codex configuration change:

"${EDITOR:-vi}" ~/dotfiles/home/dot_codex/create_private_config.toml
bash ~/dotfiles/install/codex.sh sync-config
bash ~/dotfiles/install/codex.sh check

Sync preserves runtime trust sections. Start a new session to load changed profiles or tool inventories. For the complete command and permission reference, use agent guidance.

---

Add an env var or PATH entry

Keep zsh and bash login behavior aligned. Use $_LOCAL_PLAT for architecture-specific shell state:

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
npm --prefix site ci --ignore-scripts
npx --prefix site --no-install playwright install chromium
npm --prefix site run dev
./tests/ci.sh docs

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.