diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml
deleted file mode 100644
index e7a3158..0000000
--- a/.github/workflows/linter.yml
+++ /dev/null
@@ -1,33 +0,0 @@
----
-#################################
-## Super Linter GitHub Actions ##
-#################################
-
-# Documentation:
-# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
-
-name: Lint Code Base
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    name: Lint Code Base
-    runs-on: ubuntu-latest
-
-    steps:
-      # Checkout the code base
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          # Full git history is needed to get a proper list of changed files
-          fetch-depth: 0
-
-      # Run Linter against code base
-      - name: Lint Code Base
-        uses: github/super-linter/slim@v4
-        env:
-          VALIDATE_ALL_CODEBASE: false
-          DEFAULT_BRANCH: master
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          LINTER_RULES_PATH: /
diff --git a/.gitignore b/.gitignore
index b428592..0645844 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,4 +2,5 @@
 .homedir_last_update
 .homedir_no_update
 .vim/.netrwhist
+.zshrc.local
 Brewfile.lock.json
diff --git a/.macos b/.macos
new file mode 100755
index 0000000..112550c
--- /dev/null
+++ b/.macos
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+
+# macOS System Preferences
+# Run this script to configure macOS defaults after a fresh install.
+# Safe to run multiple times (idempotent).
+#
+# Inspired by https://github.com/mathiasbynens/dotfiles/blob/main/.macos
+
+# Close any open System Preferences/Settings panes to prevent them from overriding settings
+# macOS Ventura (13.0+) renamed "System Preferences" to "System Settings"
+osascript -e 'tell application "System Preferences" to quit' 2>/dev/null
+osascript -e 'tell application "System Settings" to quit' 2>/dev/null
+
+# Ask for the administrator password upfront
+sudo -v
+
+# Keep-alive: update existing `sudo` time stamp until script has finished
+while true; do sudo -n true; sleep 60; kill -0 "$$" || exit; done 2>/dev/null &
+
+###############################################################################
+# Screenshots                                                                  #
+###############################################################################
+
+# Create screenshots folder on Desktop
+mkdir -p ~/Desktop/ScreenShots
+
+# Save screenshots to the ScreenShots folder
+defaults write com.apple.screencapture location ~/Desktop/ScreenShots
+
+###############################################################################
+# Keyboard - Vim Key Repeat                                                   #
+###############################################################################
+
+# Enable key repeat for VS Code (so j/k work properly in vim mode)
+defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false
+
+# Enable key repeat for Cursor (so j/k work properly in vim mode)
+# Older versions use todesktop bundle ID, newer versions use com.getcursor.Cursor
+defaults write com.todesktop.230313mzl4w4u92 ApplePressAndHoldEnabled -bool false 2>/dev/null
+defaults write com.getcursor.Cursor ApplePressAndHoldEnabled -bool false 2>/dev/null
+
+###############################################################################
+# Kill affected applications                                                  #
+###############################################################################
+
+echo "Done. Some changes require a logout/restart to take effect."
+echo "Restart affected apps (VS Code, Cursor) for key repeat changes."
diff --git a/.my_mac_zshrc b/.my_mac_zshrc
index d89ce61..26d08fc 100644
--- a/.my_mac_zshrc
+++ b/.my_mac_zshrc
@@ -253,3 +253,6 @@ clone-cryptoai() {
 
   echo "✨ Ready to work in $target_dir"
 }
+
+# Source local overrides (machine-specific, not in git)
+[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 43d8099..44bd7fc 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -17,6 +17,14 @@ repos:
         files: \.gitignore
       - id: trailing-whitespace
 
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+        args: [--severity=warning]
+        # Exclude zsh files - shellcheck only supports sh/bash/dash/ksh
+        exclude: (\.zsh|\.zshrc|\.zshenv|daily_update_mac\.sh|interpreter\.sh)$
+
   - repo: https://github.com/Lucas-C/pre-commit-hooks
     rev: v1.5.5
     hooks:
@@ -29,7 +37,7 @@ repos:
 
   # Ruff replaces flake8, pylint, isort and more
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.8
+    rev: v0.14.10
     hooks:
       # Run the linter with auto-fix
       - id: ruff
diff --git a/Brewfile b/Brewfile
index 041259d..6dcf2c3 100644
--- a/Brewfile
+++ b/Brewfile
@@ -12,8 +12,11 @@ cask "zoom"
 
 # Command line
 brew "bat"
+brew "btop"                 # Modern process viewer
+brew "delta"                # Beautiful git diffs
+brew "fzf"                  # Fuzzy finder for everything
 brew "pkg-config"
-brew "the_silver_searcher" # ag
+brew "the_silver_searcher"  # ag
 brew "pwgen"
 brew "watch"
 brew "wget"
diff --git a/README.md b/README.md
index 1afe4d0..8bb5000 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,148 @@
-# Overview
+# homedir
 
-These are for common files in my home directory.
+My macOS dotfiles. Simple, symlink-based configuration for a productive development environment.
 
 ## Install
 
 ```bash
-    cd ~
-    git clone https://github.com/TechNickAI/homedir.git
-    cd homedir
+cd ~
+git clone https://github.com/TechNickAI/homedir.git
+cd homedir
+git submodule init
+git submodule update
+bash setup.sh
+```
+
+Or as a one-liner:
+
+```bash
+curl "https://raw.githubusercontent.com/TechNickAI/homedir/master/install.sh" | bash
+```
+
+After installing, run the macOS defaults script:
+
+```bash
+~/.macos
+```
+
+## What's Included
+
+### Shell Configuration
+
+- **`.my_mac_zshrc`** - macOS-specific zsh config with Homebrew, virtualenv aliases, and utilities
+- **`.my_zshrc`** - Cross-platform zsh base config
+- **`.zshenv`** - Universal environment setup (virtualenvwrapper, Python paths)
+- **`.profile`** - Bash config with history management and git aliases
+- **`.bash_prompt`** - Colorized prompt with git status
+
+### Vim
+
+- **`.vimrc`** - Vim configuration with Pathogen plugin manager
+- Plugins: Syntastic, CtrlP, indent guides, rainbow parentheses
+- 160-char line width with visual guide
+
+### Git
+
+- **`.gitconfig`** - Safe defaults: `pull.ff=only`, rebase on pull, autocorrect
+- **`.gitignore`** - Global ignore patterns
+
+### Code Quality
+
+- **`.pre-commit-config.yaml`** - Pre-commit hooks with Ruff for Python
+- **`.prettierrc`** - Prettier config (88-char width, consistent with Python)
+- **`.jshintrc`** - JavaScript linting
+
+### Command-Line Tools (via Brewfile)
+
+```bash
+brew bundle --file=~/homedir/Brewfile
+```
+
+| Tool | Purpose |
+|------|---------|
+| `bat` | Better `cat` with syntax highlighting |
+| `btop` | Modern process viewer |
+| `delta` | Beautiful git diffs |
+| `fzf` | Fuzzy finder for everything |
+| `ag` | Fast code search (silver searcher) |
+| `ncdu` | Disk usage analyzer |
+
+### macOS Defaults (`.macos`)
+
+Run `~/.macos` to configure:
+
+- Screenshots saved to `~/Desktop/ScreenShots/`
+- Key repeat enabled for VS Code (vim j/k navigation)
+- Key repeat enabled for Cursor (vim j/k navigation)
+
+### Automation
+
+**Daily Updates** (`daily_update_mac.sh`)
+
+Scheduled via cron to run at 10am:
+- Updates Homebrew packages
+- Updates npm/pnpm globals
+- Skips when on battery
+
+```bash
+# Add to crontab
+0 10 * * * $HOME/homedir/daily_update_mac.sh >> $HOME/daily_update.log 2>&1
+```
+
+**Environment Loading**
+
+Automatically sources `.env` files from:
+- `~/dot_env_shared` (team-shared)
+- `~/dot_env_local` (local secrets)
+- `~/env`, `~/src/env`, `~/.env`
+
+Use `browse_env_vars` to see loaded variables.
+
+### Smart Git Functions
+
+**`commit_link`** - Copy GitHub URL of latest commit to clipboard
+
+**`_smart_git_update`** - Intelligent branch management:
+- Detects uncommitted changes (stays on branch)
+- Checks for unpushed commits (warns before switching)
+- Auto-switches to main if current branch is merged
+
+**`clone-carmenta [name]`** / **`clone-cryptoai [name]`** - Clone project with environment setup
+
+## Customization
+
+### Local Overrides
+
+Create `~/.zshrc.local` for machine-specific settings. This file is gitignored and sourced at the end of `.my_mac_zshrc`:
+
+```bash
+# ~/.zshrc.local example
+export WORK_API_KEY="secret"
+alias deploy="./scripts/deploy-prod.sh"
+```
+
+### Adding macOS Defaults
 
-    # Update the submodules (vim plugins)
-    git submodule init
-    git submodule update
+Edit `.macos` to add your preferred system settings. Check [mathiasbynens/dotfiles](https://github.com/mathiasbynens/dotfiles/blob/main/.macos) for inspiration.
 
-    # Makes all the symlinks to homedir
-    bash setup.sh
+## Structure
 
+```text
+homedir/
+├── .macos              # macOS system preferences
+├── .my_mac_zshrc       # macOS shell config
+├── .my_zshrc           # Cross-platform shell config
+├── .vimrc              # Vim configuration
+├── .vim/               # Vim plugins (Pathogen)
+├── .gitconfig          # Git configuration
+├── .pre-commit-config.yaml
+├── .prettierrc
+├── Brewfile            # Homebrew packages
+├── setup.sh            # Creates symlinks
+├── daily_update_mac.sh # Automated updates
+└── install.sh          # One-liner installer
 ```
 
-or as a one-liner:
+## License
 
-`curl "https://raw.githubusercontent.com/TechNickAI/homedir/master/install.sh" | bash`
+MIT
diff --git a/install.sh b/install.sh
index ef9d78a..f96a2fa 100644
--- a/install.sh
+++ b/install.sh
@@ -1,6 +1,9 @@
-cd ~
+#!/usr/bin/env bash
+set -e
+
+cd ~ || exit
 git clone https://github.com/TechNickAI/homedir.git
-cd homedir
+cd homedir || exit
 
 echo
 echo "Updating the submodules (vim plugins)"