bankrupt/QUICKSTART.md

# Quick Start Guide

## TL;DR

### macOS Setup (3 steps)

```bash
# 1. Configure your info
export USERNAME="your-username"
export HOSTNAME="your-hostname"

# Edit these files and replace placeholders:
# - flake.nix (line 82-94)
# - darwin/configuration.nix (lines 33, 45, 48)
# - home-manager/home.nix (line 30)

# 2. Build (first time only)
nix build .#darwinConfigurations.$HOSTNAME.system --extra-experimental-features "nix-command flakes"
./result/sw/bin/darwin-rebuild switch --flake .#$HOSTNAME

# 3. Apply (after first time)
darwin-rebuild switch --flake .
```

### Linux/NixOS Setup (2 steps)

```bash
# 1. Configure your info
# Edit flake.nix, nixos/configuration.nix, home-manager/home.nix
# Replace placeholders with your username and hostname

# 2. Apply
sudo nixos-rebuild switch --flake .#your-hostname
```

---

## What You Get

### ✅ Cross-Platform Support
- Same config works on macOS (via nix-darwin) and Linux (NixOS)
- Automatic platform detection
- Shared home-manager configuration

### ✅ Modular Home Manager
Your user environment is organized into:
- **common.nix** - Basic tools (git, ripgrep, etc.)
- **development.nix** - Dev tools (gh, lazygit, direnv)
- **shell.nix** - Shell config (bash/zsh/fish + starship prompt)
- **terminal.nix** - Terminal apps (tmux, neovim, alacritty)
- **linux.nix** - Linux-specific GUI apps
- **darwin.nix** - macOS-specific integrations

### ✅ Great Defaults
- Modern CLI tools (ripgrep, fd, bat, eza, zoxide, fzf)
- Starship prompt with git integration
- Syntax highlighting and autosuggestion
- Git aliases and better defaults
- macOS system preferences (dock, finder, keyboard)
- Automatic garbage collection
- Nix flakes enabled

### ✅ Easy Maintenance
```bash
# Update everything
make update && make darwin-switch  # or make nixos-switch

# Format code
make fmt

# Clean old generations
make clean
```

---

## File Structure Quick Reference

```
├── flake.nix              ← Define all your systems here
├── common.nix             ← Shared Nix settings
│
├── darwin/                ← macOS system config
│   └── configuration.nix  
│
├── nixos/                 ← Linux system config
│   └── configuration.nix
│
└── home-manager/          ← Your user environment (SHARED!)
    ├── home.nix           ← Main entry point
    ├── common.nix         ← Base config
    ├── development.nix    ← Dev tools
    ├── shell.nix          ← Shell setup
    ├── terminal.nix       ← Terminal apps
    ├── linux.nix          ← Linux-only
    └── darwin.nix         ← macOS-only
```

---

## Common Tasks

### Add a Package

**User package** (recommended):
```nix
# home-manager/common.nix
home.packages = with pkgs; [
  firefox
  your-package-here
];
```

**System package**:
```nix
# common.nix or darwin/configuration.nix or nixos/configuration.nix
environment.systemPackages = with pkgs; [
  your-package-here
];
```

### Enable a Program

```nix
# In any home-manager/*.nix file
programs.firefox.enable = true;
programs.vscode = {
  enable = true;
  extensions = with pkgs.vscode-extensions; [
    bbenoist.nix
  ];
};
```

### Platform-Specific Packages

```nix
# In home-manager/common.nix or development.nix
home.packages = with pkgs; [
  # Shared
  ripgrep
  fd
] ++ lib.optionals stdenv.isDarwin [
  # macOS only
] ++ lib.optionals stdenv.isLinux [
  # Linux only
];
```

### Change Shell

```nix
# In home-manager/shell.nix, set enable = true for your preferred shell:
programs.fish.enable = true;    # Fish (recommended)
programs.zsh.enable = true;     # Zsh
programs.bash.enable = true;    # Bash
```

Then on macOS, set in `darwin/configuration.nix`:
```nix
programs.fish.enable = true;  # or zsh/bash
```

On NixOS, set in `nixos/configuration.nix`:
```nix
users.users.your-username.shell = pkgs.fish;  # or zsh/bash
```

### Add SSH Keys

macOS:
```nix
# darwin/configuration.nix
users.users.your-username = {
  openssh.authorizedKeys.keys = [
    "ssh-ed25519 AAAA... your-key"
  ];
};
```

NixOS:
```nix
# nixos/configuration.nix
users.users.your-username = {
  openssh.authorizedKeys.keys = [
    "ssh-ed25519 AAAA... your-key"
  ];
};
```

### Multiple Machines

Add entries in `flake.nix`:

```nix
darwinConfigurations = {
  macbook = darwin.lib.darwinSystem { ... };
  mac-mini = darwin.lib.darwinSystem { ... };
};

nixosConfigurations = {
  desktop = nixpkgs.lib.nixosSystem { ... };
  laptop = nixpkgs.lib.nixosSystem { ... };
};
```

Then build with:
```bash
darwin-rebuild switch --flake .#macbook
# or
sudo nixos-rebuild switch --flake .#desktop
```

---

## Troubleshooting One-Liners

```bash
# Check flake is valid
nix flake check

# Show flake outputs
nix flake show

# Build without switching (test)
darwin-rebuild build --flake .         # macOS
sudo nixos-rebuild build --flake .     # Linux

# Rollback
darwin-rebuild --rollback              # macOS
sudo nixos-rebuild --rollback          # Linux

# Force rebuild
darwin-rebuild switch --flake . --recreate-lock-file

# View current generation
darwin-rebuild --list-generations      # macOS
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system  # Linux
```

---

## Next Steps

1. ⚙️  **Customize `home-manager/development.nix`** - Add your dev tools
2. 🎨 **Tweak `home-manager/shell.nix`** - Customize your prompt and aliases  
3. 🖥️  **Adjust `darwin/configuration.nix`** - Set macOS preferences
4. 📦 **Add packages** - Browse [search.nixos.org](https://search.nixos.org)
5. 🔧 **Create modules** - Extract common patterns into `modules/home-manager/`

---

## Help & Resources

- 📖 [Full README](./README.md) - Complete documentation
- 🚀 [INSTALL.md](./INSTALL.md) - Detailed installation guide
- 🔍 [NixOS Search](https://search.nixos.org) - Find packages and options
- 💬 [NixOS Discourse](https://discourse.nixos.org) - Community forum
- 🎮 [Nix Discord](https://discord.gg/RbvHtGa) - Real-time chat