dotfiles

Minimal, auditable dotfiles repo for shell, proxy wrappers, and local configuration shims.

Goals

• Keep most Codex edits inside a regular git repo.
• Reduce repeated permission prompts by routing common changes through repo-owned scripts.
• Keep secrets and machine-specific values outside version control.

Layout

• Brewfile: Homebrew formulae, taps, and casks for machine rebuilds.
• install/: one-time setup helpers.
• zsh/: shell fragments linked into ~/.zshrc.d/.
• bin/: thin wrappers that can safely override binaries via ~/bin.
• scripts/: narrow operational entrypoints suited for permission rules.
• config/: tracked config templates and migration targets.

Quick Start

cd ~/work/codes/tools/macos/dotfiles
brew bundle --file Brewfile
./install/doctor.sh
./install/link.sh

install/link.sh only creates symlinks and adds a managed bootstrap block to ~/.zshrc if needed. It does not delete existing configuration.

Secrets

Do not commit secrets here.

• Put machine-local overrides in zsh/90-machine.local.zsh on disk.
• Keep API tokens in ~/.config/secrets/ or the macOS Keychain.
• Treat live Clash provider files as untracked machine state unless sanitized.

Initialize the local secrets skeleton with:

./scripts/secrets/bootstrap.sh

Tracked Recovery Assets

• Brewfile rebuilds the Homebrew toolchain baseline.
• config/homebrew/Brewfile.lock.json captures installed package versions as a lock-style recovery snapshot.
• config/recovery/private-assets.tsv tracks the non-versioned local assets that still need private backup handling.
• config/clash/config.public.yaml preserves the ClashX base port/controller settings that make the local mixed proxy port stay on 7890.
• config/clash/clashx.public.yaml is a sanitized export of the live Clash config with hostnames and passwords replaced by placeholders.
• scripts/brew/export-brewfile.sh refreshes Brewfile from the current machine state.
• scripts/brew/export-lockfile.rb refreshes the Homebrew version snapshot.
• scripts/backup/check-private-assets.sh verifies that local critical assets exist before a rebuild or migration.
• scripts/backup/create-private-backup.sh packages non-versioned private assets into a sensitive local archive.
• scripts/clash/export-public-config.rb refreshes the sanitized Clash template from the live local config.

Suggested Approval Model

• Long-lived approvals: repo-owned scripts in scripts/ and install/.
• Per-run approvals: modifying ~/.ssh, ~/.kube, ~/.docker, Keychain, launch agents, or system defaults.
• Avoid broad approvals for bash, zsh, python3, or destructive commands.