Quick Reference

Tool	Directory	Config Location	Has Install Script
Neovim	`nvim/`	`~/.config/nvim`	Yes
Tmux	`tmux/`	`~/.tmux.conf`	Yes
Zsh	`zsh/`	`~/.zshrc`, `~/.zsh/`	Yes (`install.zsh`)
Git	`git/`	`~/.gitconfig`	Yes
Ghostty	`ghostty/`	`~/.config/ghostty`	No
Helix	`helix/`	`~/.config/helix`	Yes
Whisper	`whisper/`	N/A	Yes (macOS/Arch only)
OpenCode	`opencode/`	`~/.config/opencode/`	Yes
Skills	`skills/`	`~/.config/opencode/skill/`, `~/.claude/skills/`	Yes
Rust	`rust/`	N/A	Yes (rustup)
Go	`go/`	N/A	Yes (Go tools: gopls, gofumpt, etc.)
Node	`node/`	N/A	Yes (fnm + TypeScript tools)
Bin	`bin/`	`~/.local/bin`	Yes (custom scripts)
jj	`jj/`	`~/.jjconfig.toml`	Yes (Jujutsu VCS)
gh	`gh/`	`~/.local/gh`, `~/.local/bin/gh`	Yes (GitHub CLI + extensions)

Platform Support

Platform	Detection	Package Manager	Notes
GitHub Codespaces	`$CODESPACES` set	`apt`	Debian-based, read-only for push (use `dot patch`)
macOS	`uname == Darwin`	`brew`	Personal machines
Arch/Omarchy	`command -v pacman`	`pacman`/`yay`	Arch + Hyprland
Omarchy	`~/.local/share/omarchy` exists	`pacman`/`yay`	Uses default configs, skip apply()

See references/platform-detection.md for detection code snippets.

Important Constraints

Always Modify Dotfiles, Not Config Targets

Never create or edit files directly in config target directories like ~/.config/ or ~/.local/bin/. These locations contain symlinks to ~/dotfiles/, so changes made there are either not version controlled or will be overwritten by install scripts.

Always make changes in ~/dotfiles/ so they are:

Version controlled (git)
Propagated to other machines via dot pull
Not overwritten by install scripts

Common mistakes to avoid:

Creating skills in ~/.config/opencode/skill/ instead of ~/dotfiles/skills/
Editing nvim config in ~/.config/nvim/ instead of ~/dotfiles/nvim/
Adding scripts to ~/.local/bin/ instead of ~/dotfiles/bin/

After creating or modifying files in ~/dotfiles/, run the appropriate install script to create symlinks (e.g., dot install skills, dot install nvim).

Codespaces: Read-Only for Pushing

You cannot push dotfiles changes directly from GitHub Codespaces.

Why:

Codespaces use a scoped GITHUB_TOKEN that only has access to the workspace repository (e.g., github/github), not your personal luanzeba/dotfiles repo
Pushing changes would require setting up SSH keys or manually providing a PAT

Workaround - Use dot patch:

# 1. In Codespace: Create a patch from your changes
dot patch create

# 2. On local machine: Pull and apply the patch
dot patch pull

# 3. On local: Review, commit, and push
cd ~/dotfiles
git diff
git add -A && git commit -m "Fix from Codespace"
git push

# 4. In Codespace: Pull the committed changes
dot pull

This uses gh cs cp to transfer a patch file, authenticating through GitHub's Codespace infrastructure rather than requiring repo-specific credentials.

Key Principles

Always install latest versions: Install scripts should always fetch the latest stable/LTS version of tools, not pin to specific versions. Use @latest tags, --lts flags, or omit version specifiers where possible.
Idempotent scripts: Install scripts must be safe to run multiple times without side effects.
Platform-aware: Use platform detection to handle differences between Codespaces, macOS, and Arch.
Script pattern: Each tool script should have install(), configure(), and optionally apply() and update() functions.

Installation Preference Hierarchy

Direct GitHub releases - Preferred for tools with prebuilt binaries (nvim, jj, gh, helix, fnm)
Package managers - Only when no prebuilt binaries exist (tmux via brew, system tools via apt/pacman)

Homebrew is installed lazily in Phase 3 of install-local, only when needed for brew-dependent tools.

Standard Binary Locations

Purpose	Location	Example
User binaries/scripts	`~/.local/bin/`	`dotfiles`, `dot`
Tool extractions	`~/.local/<tool>/`	`~/.local/nvim/`, `~/.local/gh/`

Scripts from bin/ are symlinked individually to ~/.local/bin/.

Idempotency Guidelines

Scripts should produce the same result whether run once or many times:

Check before installing: Use command -v <tool> to skip if already installed

if command -v rustc &>/dev/null; then
    echo "Rust already installed"
    return
fi

Use -sf for symlinks: The -f flag overwrites existing symlinks safely
```
ln -sf "$SCRIPT_DIR/.config" "$HOME/.config/tool"
```

Handle existing directories: Check and backup if needed

if [[ -e "$target" && ! -L "$target" ]]; then
    mv "$target" "$target.backup"
fi

Use --noconfirm for package managers: Avoid interactive prompts

sudo pacman -S --noconfirm package
brew install package  # Already non-interactive

dotfiles CLI

The dot command (symlinked to ~/.local/bin/ from bin/dotfiles) provides easy management:

dotfiles status   # Show VCS status of dotfiles repo
dotfiles pull     # Pull latest and apply changes (skipped on Omarchy)
dotfiles edit     # Open dotfiles in $EDITOR
dotfiles update   # Update tools (brew, nvim plugins, rustup, etc.)
dotfiles doctor   # Check if everything is set up correctly

The CLI uses jj (Jujutsu) if available, falling back to git.

Common Tasks

Adding a New Tool

Create <tool>/ directory at repo root
Create <tool>/install script using the template with:
- install() - Install the tool binary/package
- configure() - Symlink configs, set up environment
- apply() (optional) - Reload config after dotfiles pull, or handle migrations
- update() (optional) - Update tool for dotfiles update
- check_installed() / check_configured() - For dot doctor health checks
Add config files to the directory
Test on each platform
Optionally integrate with install-local in the appropriate phase

See references/tool-template.md for the install script template. See references/install-patterns.md for version checking, migrations, and Codespaces patterns.

Modifying Neovim Config

See references/nvim-config.md for structure details.

Key locations:

Plugins: nvim/lua/plugins/<name>.lua
Key bindings: nvim/lua/config/mappings.lua
Core options: nvim/init.lua

Running Install Scripts

# Main install (dispatches to platform-specific script)
~/dotfiles/install

# Platform-specific scripts (called by main install)
~/dotfiles/install-codespaces   # GitHub Codespaces
~/dotfiles/install-local        # macOS and Arch

# Tool-specific installs
~/dotfiles/nvim/install
~/dotfiles/zsh/install.zsh
~/dotfiles/skills/install
~/dotfiles/node/install
~/dotfiles/rust/install
~/dotfiles/go/install
~/dotfiles/jj/install

Shared Utilities

The lib/common.sh file provides shared functions for all scripts:

source "$DOTFILES_DIR/lib/common.sh"

dotfiles_dir    # Get dotfiles path (handles Codespaces)
is_codespaces   # Check if running in Codespaces
is_macos        # Check if running on macOS
is_arch         # Check if running on Arch Linux
is_omarchy      # Check if running on Omarchy
vcs_cmd         # Run jj or git command
log_info/log_success/log_warn/log_error  # Logging helpers

dotfiles

Dotfiles Management

Repository Location

Structure