provision/CLAUDE.MD

# CLAUDE.MD - AI Assistant Guide

## Project Overview

**System provisioning tool** for macOS and Linux desktop computers. Simple, idempotent shell scripts (~600 LOC) that automate installation of dev tools, GUI apps, and dotfiles.

**Philosophy**: "JFUI" (Just Use It) - simple, fast, idempotent, self-contained.

**Main Script**: [provision](provision) - orchestrates all installation steps

## Structure

```
provision/
├── provision              # Main entry point
├── bootstrap              # Fresh system bootstrap
├── lib/
│   ├── common.sh         # Platform detection, logging
│   └── package.sh        # Package manager abstraction
├── scripts/
│   ├── packages.sh          # CLI tools & X11 (Linux)
│   ├── apps.sh              # GUI apps
│   ├── golang.sh            # Go from tar.gz
│   ├── plan9port.sh         # Plan9 from source
│   ├── user-setup.sh        # User & SSH setup
│   ├── macos-defaults.sh    # macOS system defaults
│   ├── elementary-defaults.sh # elementary OS system defaults
│   └── update-xdm.sh        # XDM config updater (Linux)
└── config/                # Dotfiles & configs
    ├── bashrc, tmux.conf, starship.toml, gitconfig
    ├── xinitrc, xsession, Xresources  # X11 (Linux)
    └── twm/, xdm/        # TWM & XDM configs (Linux)
```

## Platforms

- **macOS**: Homebrew
- **Debian/Ubuntu**: apt (includes Pop!_OS, Linux Mint, other Debian derivatives)
- **elementary OS**: apt (X11/TWM setup skipped - uses native Pantheon desktop)
- **Arch Linux**: pacman + AUR

## What Gets Installed

**CLI Tools**: git, curl, wget, tmux, jq, starship, gh, 1Password CLI, Tailscale, Meslo Nerd Font, TPM (tmux plugins)

**Linux X11** (skipped on elementary OS): twm, slock, xsetroot, feh, xclock, xload, xdm

**GUI Apps** (skip with `--skip-apps`): VSCodium, 1Password, Obsidian, Chrome, Todoist, Claude Desktop

**Development** (skip with flags):
- Go → `/usr/local/go` (`--skip-go`)
- Plan9port → `/usr/local/plan9` (`--skip-p9`)

**Work packages** (`--work`): Slack, Zoom

**Config**: Bash, tmux, starship, git. Linux: X11/TWM with Dracula theme & 1.5x DPI

## Usage

```bash
./provision              # Full provision
./provision --skip-apps  # No GUI apps
./provision --skip-go    # No Go
./provision --skip-p9    # No Plan9
./provision --work       # Include work tools
```

Bootstrap fresh system:
```bash
curl -fsSL https://git.sdf.org/jchenry/provision/raw/branch/main/bootstrap | bash
```

## Key Implementation

**Package abstraction** ([lib/package.sh](lib/package.sh)):
```bash
install_package <name> [debian] [arch] [brew]
install_cask <name>  # macOS only
install_aur <name>   # Arch only
```

**Platform detection** ([lib/common.sh](lib/common.sh)):
- `$OS_TYPE`: "macos", "debian", "arch"
- Helpers: `is_macos`, `is_linux`, `is_debian`, `is_arch`, `is_elementary`

**Logging**: `log_info`, `log_success`, `log_warn`, `log_error`

**Idempotency**: All scripts check existing installations before proceeding

## Linux X11/TWM Setup

**Note**: X11/TWM setup is skipped on elementary OS (uses native Pantheon desktop).

Complete lightweight X11 environment for Debian/Ubuntu/Arch:
- **XDM**: Display manager with Dracula theme
- **TWM**: Window manager with custom config
- **DPI**: 1.5x default (144). Edit [config/Xresources](config/Xresources), [config/xinitrc](config/xinitrc), [config/xsession](config/xsession)
  - 96=1x, 144=1.5x, 192=2x
- **Theme**: Dracula throughout

Update XDM after changes:
```bash
./scripts/update-xdm.sh
sudo systemctl restart xdm
```

## elementary OS Setup

Custom configuration for elementary OS ([scripts/elementary-defaults.sh](scripts/elementary-defaults.sh)):

**Prerequisites** (auto-installed):
- git
- gtk2-engines-murrine
- gtk2-engines-pixbuf
- sassc
- optipng

**Themes:**
- **MacTahoe GTK Theme**: macOS-like GTK theme installed to `~/.themes`
- **MacTahoe Icon Theme**: macOS-like icons installed to `~/.icons`
- **MacTahoe Cursor Theme**: macOS-like cursors installed to `~/.icons`
- **MacTahoe Wallpapers**: Official wallpapers from MacTahoe theme repository
- **Display Manager**: LightDM/GDM configured to use MacTahoe theme and wallpaper

**System Tweaks:**
- **Dark Mode**: Enabled by default
- **Window Buttons**: macOS-like layout (close button on left)
- **Touchpad**: Natural scrolling and tap-to-click enabled
- **Hot Corners**: Disabled by default
- **Fonts**: Monospace set to Meslo LG S Nerd Font
- **Plank Dock**: Icon size 48px, window-dodge mode, bottom position
- **Animations**: Enabled for smooth UI

All themes and settings are automatically applied via `gsettings`. MacTahoe wallpapers are downloaded from the official theme repository to `~/.local/share/backgrounds/` and one is copied to `/usr/share/backgrounds/provision/` for the login screen. You can customize in System Settings > Desktop.

## Common Modifications

**Add CLI tool** - edit [scripts/packages.sh](scripts/packages.sh):
```bash
install_package newtool [debian_name] [arch_name] [brew_name]
```

**Add GUI app** - edit [scripts/apps.sh](scripts/apps.sh):
```bash
case "$OS_TYPE" in
    macos) install_cask newapp ;;
    debian) # debian install ;;
    arch) install_aur newapp ;;
esac
```

**Work tools** - use `INCLUDE_WORK` pattern:
```bash
if [ "${INCLUDE_WORK:-false}" = true ]; then
    # work-specific installs
fi
```

**Update dotfiles**:
```bash
# Edit files in config/
./config/link-dotfiles.sh  # Re-symlink
```

## Post-Install

1. `exec $SHELL` - Reload shell
2. Edit `~/.gitconfig` - Set name/email
3. Tmux: `Ctrl+a` then `I` - Install plugins
4. Linux (except elementary OS): `sudo systemctl enable --now xdm` - Enable graphical login
5. elementary OS: Theme changes should apply immediately, logout/login if needed

## Gotchas

1. **Debian fresh install**: Add user to sudo, then logout/login
2. **macOS**: Install Xcode CLI tools first
3. **Arch AUR**: Script installs AUR helper if missing
4. **XDM changes**: Run [scripts/update-xdm.sh](scripts/update-xdm.sh) + restart service (not applicable to elementary OS)
5. **DPI changes**: Logout/login to apply (not applicable to elementary OS)
6. **elementary OS**: X11/TWM setup automatically skipped - uses native Pantheon desktop

## Prerequisites

- git, curl, sudo access (or root)
- macOS: Xcode CLI Tools
- Debian: build-essential (auto-installed)
- Arch: base-devel (auto-installed)

## Design Principles

1. **Simple**: 4 main scripts, not 20+
2. **Fast**: Parallel installs where possible
3. **Idempotent**: Always safe to re-run
4. **Self-contained**: All configs included
5. **Flexible**: Skip components with flags
6. **Minimal deps**: Pure bash
7. **Transparent**: Read scripts to see what happens

## Error Handling

- All scripts: `set -euo pipefail`
- Installation failures logged but non-fatal for non-critical tools
- Bootstrap validates prerequisites

## Testing

- Test on fresh VMs for each OS
- Re-run scripts to validate idempotency
- Scripts runnable standalone for component testing