Repository navigation
Description
Current state
First-time setup on a new Mac creates broken links and runs scripts the repo has marked deprecated. features/setup/setup.zsh sources the zsh scripts in features/install/zsh/, eight of them from deprecated/ (lines 111, 113 to 118 and 120). One of those, deprecated/symlinks.zsh, links eight sources that no longer exist: tools/claude/config/commands, four k9s files, tools/tmux/config/battery.sh and two terminfo files. features/update/symlinks.bash is the maintained path, which sweeps broken links and then runs every link.bash (lines 16 to 34).
u also reports a failure on a fresh machine until tmux's install has run. tools/tmux/update.bash:11 calls "${TPM}/clean_plugins" with no check that tpm is there, and only tools/tmux/install.bash (lines 9 to 12) clones tpm, so the tmux update fails and u lists tmux among its failed updates.
Checked 2026-10-25
Ideal state
- One setup script, run once on a fresh Mac, replaces
features/setup/setup.zsh: it checks that it is on a Mac, keeps sudo alive, clones the dotfiles, runs each tool'sinstall.bashin an explicit priority order, and then runsu - Setup creates its links by running
features/update/symlinks.bash, so it leaves no broken links ustays the command run regularly, and can be run again at any time: each tool'supdate.bashinstalls the tool if it is missing, then updates it- On a fresh machine,
uinstalls rust, uv, node and tmux through theirupdate.bashwhen they are missing, so none of them needs aninstall.bashfor that - A tool has an
install.bashonly for a one-time side effect:tools/sshgenerates SSH keys,tools/githubregisters the key with GitHub, verifies auth and switches the dotfiles remote from HTTPS to SSH,tools/zshsets Homebrew zsh as the default shell,tools/contentclones the personal content repo, andtools/macosapplies macOS settings tools/github/holds its Brewfile, config link and shell aliases- The SSH key and GitHub auth logic worth keeping from
tools/ssh/wip/andtools/github/wip/lives in those tools'install.bash - No
wip/folder remains intools/git,tools/github,tools/obsidian,tools/ssh,tools/tmux,tools/uv,tools/zshorfeatures/setup features/setup/setup.zshandfeatures/install/zsh/no longer exist
Decisions
Constraints
- 007 — Scripts that are run, not sourced, are written in Python: everything setup runs after its first step is Python
Open
- How does a fresh Mac get uv and Python before the first script needs them, and how much of setup's first step has to be bash? (new process or runtime) Open in how-does-a-fresh-mac-get-uv-and-python-before-the-first-script-needs-them.md
- Which bash version must setup support? (runtime) Open in which-bash-version-must-this-repos-scripts-support.md, which notes that setup runs before Homebrew is installed, so whatever runs at that point gets macOS's
/bin/bash3.2.
Starting points
features/setup/setup.zsh: today's setup, and the order it runs each step infeatures/update/symlinks.bash: the maintained link step setup should callfeatures/update/tools.bash:u, which setup runs last
Activity
[-]migrate setup.zsh to setup.bash using tools/x/bootstrap.bash pattern[/-][+]migrate setup.zsh to setup.bash using tools/x/install.bash pattern[/+]ooloth commentedon Oct 18, 2026
features/install/zsh/deprecated/symlinks.zsh, whichsetup.zshstill sources, links 8 sources that no longer exist (tools/claude/config/commands, four k9s files,tools/tmux/config/battery.shand two terminfo files), so first-time setup creates broken links today.features/update/symlinks.bashis the maintained path: it runs everylink.bashand sweeps broken links, so the migration can call it instead of portingsymlinks.zsh.docs: correct claims a fresh agent would trust
docs/questions: ask which language this repo's scripts should use
[-]migrate setup.zsh to setup.bash using tools/x/install.bash pattern[/-][+]First-time setup on a new Mac leaves no broken links or deprecated steps[/+]docs: split the open python question into bootstrap and transition
ooloth commentedon Oct 26, 2026
scripts/checks/linting.bashnow runsbash -n tools/zsh/utils.zsh(a833d68). The only reasonutils.zshhas to parse as bash is thatfeatures/setup/wip/setup.bashsources it, so that step should be removed in the same change that deletesfeatures/setup/wip/, along with its line inCONTRIBUTING.mdand the "zsh utils" line in the comment at the top oflinting.bash. Under decision 007 the replacement setup script is Python, so nothing else needsutils.zshto stay parseable as bash. Before deleting the check, rungrep -rn 'zsh/utils.zsh' --include='*.bash' --include='*.sh' .to confirm nothing else sources it. Only a comment intools/homebrew/update.bashshould still mention it.agents/next-step: plan the few items a goal needs, not an essay
ooloth commentedon Oct 31, 2026
First-time setup needs a step for
private.env(#230). A fresh Mac has none, so each new shell warns that it is missing, andcheckfails in its private values step until it exists. Setup can't create the file, because its values exist only on the other Macs. So the step tells the person to copyprivate.env.exampleto~/Repos/ooloth/dotfiles/private.env, fill in the keys whose# machines:line names this Mac, andchmod 600it. On the work laptop it has to exist before uv is installed, becausetools/uv/install.bashstops withoutPRIVATE_UV_INSTALLER_URL.docs: correct stale claims a cold reader tripped on
ooloth commentedon Nov 5, 2026
Setup now has a second kind of machine-local value to restore. Tokens belong in the login Keychain, not
private.env(docs/standards/secrets.md,private.env.example), and the login Keychain does not sync between Macs. So a fresh Mac also needs asecret addstep for each stored secret, such asjira-cli(with--account) andcodefresh.docs: remove stale claims and dead fixtures around the Claude tools