Environment System

How the Shop config system layers together — symlinks, shell load order, and workspace branches.

Symlinks

Setup scripts create symlinks so tools read config from the repo instead of scattered dotfiles:

Symlink	Target	Created by
~/.zshrc	config/zsh/.zshrc	oh-my-zsh.sh
~/.config/nvim	config/nvim	lazyvim.sh
~/.claude/settings.json	config/claude/settings.json	claude.sh
~/.claude/CLAUDE.md	config/claude/CLAUDE.md	claude.sh
~/.claude/skills/	.claude/skills/	claude.sh
~/.claude/rules/	.claude/rules/	claude.sh

This means editing config in the repo immediately takes effect, and all changes are tracked in git.

Zsh load order

The shell config loads in a specific sequence. Understanding this helps when debugging or adding new config.

~/.zshrc (symlinked to config/zsh/.zshrc)
│
├─ 1. Oh My Zsh core
│     ZSH_CUSTOM points to config/zsh/.oh-my-zsh/custom
│     Theme: sjf
│     Plugins: git, zsh-syntax-highlighting
│
├─ 2. Shared config
│     config/zsh/aliases.zsh
│     config/zsh/functions.zsh
│     config/zsh/lazy.zsh
│     config/zsh/path.zsh
│
├─ 3. Environment-specific config
│     ~/.shop-env (sets SHOP_ENV)
│     config/zsh/env/$SHOP_ENV.zsh
│
└─ 4. Local overrides
      config/zsh/local.zsh (gitignored)

Later sources override earlier ones. This means:

• Shared config applies to every machine
• Environment config adds machine-specific aliases and paths
• Local overrides handle one-off tweaks that shouldn't be committed

SHOP_ENV and workspace branches

The repo uses a core + workspace branch model:

• main — shared infrastructure (agents, skills, config, tools, site scaffolding)
• Workspace branches (e.g. personal, sbg) — extend main with machine-specific config

SHOP_ENV connects a machine to its workspace branch. When you set SHOP_ENV="personal" in ~/.shop-env, the shell sources config/zsh/env/personal.zsh on startup — loading aliases, paths, and settings specific to that workspace.

The ~/.shop-env file is not tracked in the repo. Each machine creates its own.

Setup scripts reference

All scripts live in setup/ and are designed to be run independently.

Script	Purpose
all.sh	Runs the full bootstrap sequence below
brew.sh	Installs Homebrew
nvm.sh	Installs NVM and Node.js
nvmrc.sh	Writes latest LTS Node version to ~/code/.nvmrc
node.sh	Installs Node.js via Homebrew (standalone alternative to NVM)
wezterm.sh	Installs WezTerm terminal emulator
oh-my-zsh.sh	Installs Oh My Zsh, plugins, and symlinks .zshrc
omz_install.sh	Clean re-install of Oh My Zsh (removes existing)
omz_setup.sh	Clones plugins and symlinks .zshrc (no Oh My Zsh install)
postman.sh	Installs Postman
lazyvim.sh	Installs Neovim, LazyGit, ripgrep, nerd font; symlinks nvim config
claude.sh	Symlinks Claude Code config files to ~/.claude
ssh.sh	Generates an Ed25519 SSH key and copies the public key

Adding a new environment

1. Create a workspace branch off main:

   git checkout main
   git checkout -b my-workspace

2. Create the environment config file:

   touch config/zsh/env/my-workspace.zsh

3. Add your machine-specific aliases, paths, and exports to that file.

4. On the target machine, set SHOP_ENV:

   echo 'export SHOP_ENV="my-workspace"' > ~/.shop-env

5. Reload the shell to pick up the new config.