> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anonymous.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Set up, update, and manage Rig modules.

## Initial Setup

### 1. Clone the repository

```bash theme={null}
git clone https://github.com/anonymous-dev-org/rig.git
cd rig
```

### 2. Run the installer

```bash theme={null}
./init.sh
```

`init.sh` is interactive by default. It asks before each major step:

| Step           | What happens                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------- |
| Homebrew       | Runs `./brew/install-brew.sh` to install Homebrew and the Brewfile, including released `0x0` |
| Stow packages  | Installs `neovim`, `zsh`, `aerospace`, `kitty`, `git`, and `codex` when present              |
| macOS defaults | Applies Dock, Finder, keyboard, hot corner, and appearance settings                          |
| Swift apps     | Compiles AeroSpace picker apps when `swiftc` is available                                    |

Use `--yes` for a full non-interactive install:

```bash theme={null}
./init.sh --yes
```

<Warning>
  During stow setup, `init.sh` removes conflicting non-symlink files at the destination path.
  Back up local dotfiles before running it on a machine with existing config.
</Warning>

## Updating

```bash theme={null}
./update.sh
```

This script:

1. Pulls the latest changes from the remote.
2. Re-stows installed packages with `stow --no-folding -t ~ -R`.
3. Cleans up stale files from previous versions.
4. Recompiles AeroSpace Swift picker apps when possible.

Packages that are not installed on the current machine are skipped.

## How Stow Works

Stow creates symlinks from your home directory into the repo. Each module mirrors `$HOME`.

```
rig/zsh/.zshrc                   --> ~/.zshrc
rig/neovim/.config/nvim/init.lua --> ~/.config/nvim/init.lua
rig/kitty/.config/kitty/         --> ~/.config/kitty/
rig/codex/.codex/config.toml     --> ~/.codex/config.toml
```

Rig uses `--no-folding` so Stow creates file-level links instead of linking whole directories.

## Manual Stow Commands

| Command                                 | What it does              |
| --------------------------------------- | ------------------------- |
| `stow --restow --no-folding -t ~ <pkg>` | Install/refresh a package |
| `stow -D -t ~ <pkg>`                    | Unlink a package          |

## Ignored Files

`.stow-local-ignore` prevents these repo files from being linked into `$HOME`:

```text theme={null}
.DS_Store
.git
.gitignore
.stow-local-ignore
```

## Local Overrides

Keep machine-specific settings outside the repo:

* Zsh: create `~/.zshrc.local`; it is sourced at the end of `.zshrc`.
* Claude Code: `.claude/settings.local.json` is ignored by the global Git ignore.