nix-los/INDEX.md

# Project Index

Quick reference to all files and their purposes.

## Getting Started

Start here in this order:

1. **README.md** - Feature overview and quick start
2. **SETUP.md** - Step-by-step installation guide
3. **QUICKREF.md** - Command reference for daily use

## Documentation

- **README.md** - Overview, features, directory structure, usage patterns
- **SETUP.md** - Detailed setup from scratch, per-scenario instructions
- **QUICKREF.md** - Command reference, common tasks, one-liners
- **CUSTOMIZATION.md** - Advanced patterns, extension examples
- **ARCHITECTURE.md** - Design principles, data flow, scalability
- **INDEX.md** - This file

## Configuration Files

### Core Configuration

- **flake.nix** - Main entry point
  - Defines all inputs (nixpkgs, home-manager, sops-nix, disko)
  - Specifies all outputs (nixosConfigurations, homeConfigurations)
  - Includes development shell and installer app
  - **Requires customization**: Replace `youruser` with actual username

### Host Configurations (Per-Machine)

- **hosts/laptop/default.nix** - Laptop configuration template
  - Networking hostname
  - Disko disk partitioning
  - Development tools to enable
  - **Requires customization**: Hostname, disk device, language selection

- **hosts/server/default.nix** - Server configuration template
  - Minimal development tools
  - Same structure as laptop, customize as needed

### NixOS System Modules (Shared)

- **nixos/default.nix** - System configuration entry point
  - Imports all modules
  - System packages (git, curl, vim, htop)
  - Nix settings, garbage collection, locale
  - **Touch rarely**: Mostly imports

- **nixos/modules/system.nix** - System base configuration
  - User creation (currently `youruser` - customize)
  - Sudo configuration
  - System state version
  - **Options exposed**: `custom.system.enable`

- **nixos/modules/development.nix** - Development tools module
  - Language-specific packages (rust, python, nodejs, go, ruby)
  - Build tools (gcc, cmake, gdb, etc)
  - Container support (docker/podman)
  - **Options exposed**: `custom.development.enable`, `custom.development.languages`
  - **Example**: Set `languages = [ "rust" "python" ]` to install

- **nixos/modules/shell.nix** - Shell configuration
  - Zsh, bash, fish support
  - Starship prompt, direnv integration
  - **Options exposed**: `custom.shell.enable`, `custom.shell.defaultShell`

- **nixos/modules/secrets-example.nix** - Secrets integration example
  - Shows how to use sops-nix for encrypted secrets
  - NOT imported by default
  - Uncomment in `nixos/default.nix` to enable
  - Reference for managing SSH keys, API tokens, passwords

- **nixos/modules/example-template.nix** - Template for new modules
  - Shows the module pattern: options + config
  - Copy and customize for new features

### Home Manager User Configuration (Portable)

- **home/default.nix** - User configuration entry point
  - Imports all home modules
  - Home username, home directory, stateVersion
  - User-level packages (utilities, tools)
  - Environment variables
  - **Requires customization**: Username, email (in git.nix)

- **home/modules/shell.nix** - Shell environment
  - Zsh configuration (autosuggestion, syntax highlighting)
  - Shell aliases (ls → exa, cat → bat)
  - Starship prompt setup
  - Direnv integration for per-project shells
  - Zsh-z plugin for directory navigation

- **home/modules/editor.nix** - Editor configuration
  - Neovim as primary editor
  - LSP setup (language servers)
  - Plugins: telescope, lualine, treesitter, git integration
  - Alternative: VSCode (commented out)
  - **Note**: Basic config, customize for your needs

- **home/modules/git.nix** - Git configuration
  - Git username, email
  - Default branch, pull strategy
  - Common aliases (st, co, br, ci)
  - **Requires customization**: Your name and email

- **home/modules/dev-tools.nix** - Development utilities
  - Debuggers (lldb, gdb)
  - Version managers (fnm, pyenv)
  - Build tools (cmake, ninja, meson)
  - System utilities (tmux, htop, iotop)
  - Container tools (podman, podman-compose)
  - Tmux configuration with mouse support and vi keybindings

- **home/modules/example-template.nix** - Template for new user modules
  - Shows home-manager module pattern
  - Copy and customize for new user features

### Secrets Management

- **secrets/.sops.yaml** - SOPS encryption configuration
  - Specifies which keys can decrypt secrets
  - Points to your age public key
  - **Requires**: Replace placeholder with your actual age public key

- **secrets/secrets.yaml** - Encrypted secrets file
  - SSH keys, API tokens, passwords
  - Encrypted with sops (safe to commit)
  - **Usage**: Edit with `sops secrets/secrets.yaml`
  - **Never**: Commit unencrypted version

## Build & Deployment

No separate deployment files needed - everything flows through flake.nix:

```
flake.nix
  ├─ nixosConfigurations.laptop → Deploy with: sudo nixos-rebuild switch --flake .#laptop
  ├─ homeConfigurations.youruser@linux → Deploy with: home-manager switch --flake .#youruser@linux
  ├─ devShells.default → Enter with: nix develop
  └─ apps.installer → Run with: nix run .#installer -- laptop
```

## Support Files

- **.gitignore** - Prevents committing secrets, temp files, nix artifacts
- **flake.lock** - COMMIT THIS: Pins all dependencies for reproducibility

## Quick Navigation

### "I want to..."

| Task | File | Line | Command |
|------|------|------|---------|
| **Change my hostname** | hosts/laptop/default.nix | 8 | `sed -i 's/laptop/myname/' ...` |
| **Change my username** | flake.nix | ~40, 70 | Global replace: `"youruser"` |
| **Add a programming language** | hosts/laptop/default.nix | 35 | Add to `languages = [...]` |
| **Install new system package** | nixos/default.nix | 14 | Add to `systemPackages` |
| **Install new user package** | home/default.nix | 16 | Add to `home.packages` |
| **Change default shell** | nixos/modules/shell.nix | 11 | Change `defaultShell = "fish"` |
| **Add SSH key to secrets** | secrets/secrets.yaml | 8 | `sops secrets/secrets.yaml` |
| **Use unstable package** | home/modules/dev-tools.nix | varies | Use `pkgs-unstable.package` |
| **Create a new module** | nixos/modules/example-template.nix | — | Copy template, customize |
| **Add a new machine** | hosts/ | — | `mkdir newhost && cp laptop/* newhost/` |

## File Customization Checklist

On first setup, customize these:

- [ ] **flake.nix** - Replace all `youruser` (3 locations)
- [ ] **hosts/laptop/default.nix** - Set `networking.hostName`, verify `/dev/sda` disk
- [ ] **home/default.nix** - Set `home.username`
- [ ] **home/modules/git.nix** - Set `userName` and `userEmail`
- [ ] **secrets/.sops.yaml** - Add your age public key
- [ ] **secrets/secrets.yaml** - Add actual SSH keys and API tokens

## File Statistics

- **Documentation**: 6 files (README, SETUP, QUICKREF, CUSTOMIZATION, ARCHITECTURE, INDEX)
- **Configuration**: 1 core file (flake.nix)
- **System modules**: 5 files (default, system, development, shell, secrets-example)
- **Home modules**: 6 files (default, shell, editor, git, dev-tools, example-template)
- **Hosts**: 2 example files (laptop, server)
- **Secrets**: 2 files (.sops.yaml, secrets.yaml)
- **Support**: 2 files (.gitignore, flake.lock)

Total: ~24 files, all under 500 lines each

## Update Schedule

### When to update inputs

```bash
# Monthly (security patches)
nix flake update nixpkgs
sudo nixos-rebuild switch --flake .#laptop

# Less frequently (minor version bumps)
nix flake update

# Test before committing
nix flake check
sudo nixos-rebuild test --flake .#laptop
```

### When to add modules

Add modules when:
- Feature can be enabled/disabled independently
- Reused across multiple machines
- Follows the options + config pattern

## Related Resources

- NixOS Manual: https://nixos.org/manual/nixos/stable
- Home Manager: https://nix-community.github.io/home-manager
- Nix Flakes: https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake
- sops-nix: https://github.com/mic92/sops-nix
- Disko: https://github.com/nix-community/disko

---

**Next Step**: Read README.md for a feature overview, then SETUP.md for installation instructions.