From a2ffa6afb56dec4c8bd93c592edd5c225cce1249 Mon Sep 17 00:00:00 2001
From: Paul Trowbridge <paul@hptrow.me>
Date: Sun, 10 May 2026 02:12:36 -0400
Subject: [PATCH] document .bashrc_paths pattern and machine-specific config
 workflow

---
 CLAUDE.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7bae4a9..7b93987 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,8 +52,10 @@ All dotfiles are symlinked, not copied. Editing `~/.<file>` directly modifies fi
 
 **Critical Files:**
 - `dotfiles/.bashrc` - Main bash configuration with extensive aliases and functions
-- `dotfiles/.bashrc_local` - Machine-specific environment variables (PG, MS connection strings)
-- `dotfiles/.bashrc_local_example` - Template for setting up machine-specific configs
+- `dotfiles/.bashrc_local` - Machine-specific secrets and credentials (PG, MS connection strings)
+- `dotfiles/.bashrc_local_example` - Template for `.bashrc_local`
+- `dotfiles/.bashrc_paths` - Machine-specific PATH additions and tool inits
+- `dotfiles/.bashrc_paths_example` - Template for `.bashrc_paths`
 - `dotfiles/.vimrc` - Vim configuration using Vundle plugin manager
 - `dotfiles/.tmux.conf` - Tmux configuration with vim-style pane navigation
 - `dotfiles/.gitconfig` - Git configuration with custom log format and vimdiff
@@ -126,10 +128,20 @@ Base packages installed by `setup_env.sh`:
 
 ## Important Conventions
 
-### Environment Variables
-Machine-specific environment variables (database connections, tokens, passwords) belong in `dotfiles/.bashrc_local`, not `.bashrc`. This file is sourced by `.bashrc` and should contain sensitive or machine-specific configuration.
+### Machine-specific configuration
 
-The `.bashrc_local` file is gitignored for security. Use `dotfiles/.bashrc_local_example` as a template when setting up a new machine. Copy it to `.bashrc_local` and fill in your actual credentials.
+There are two gitignored files for machine-specific configuration, both sourced by `.bashrc`:
+
+- **`.bashrc_local`** — secrets and credentials: database connection strings, passwords, tokens. Use `dotfiles/.bashrc_local_example` as a template.
+- **`.bashrc_paths`** — PATH additions and tool initializations: neovim, cargo, nvm, java, etc. Use `dotfiles/.bashrc_paths_example` as a template.
+
+On a new machine, copy both examples and fill them in:
+```bash
+cp dotfiles/.bashrc_local_example dotfiles/.bashrc_local
+cp dotfiles/.bashrc_paths_example dotfiles/.bashrc_paths
+```
+
+When a tool (cargo, nvm, conda, etc.) auto-appends lines to `.bashrc`, `git status` will show the modification — that's your signal to move those lines to `.bashrc_paths` instead.
 
 ### Symlink Pattern
 When modifying dotfiles, remember they are symlinked. Changes are automatically tracked by git since the actual files are in the repository's `dotfiles/` directory.