# COMMON HOST CONFIGURATION

**Shared base configuration and abstractions for all hosts**

## OVERVIEW
Common imports, overlays, and custom patterns (extraServices, ports) used across 6 hosts.

## STRUCTURE
```
common/
├── default.nix          # Base imports, overlays, nix settings
├── ports.nix            # Centralized port registry
├── extraServices/       # Optional service modules
│   ├── default.nix
│   ├── flatpak.nix
│   ├── ollama.nix
│   ├── podman.nix
│   └── virtualisation.nix
└── users/
    ├── default.nix
    └── m3tam3re.nix     # Primary user definition
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| Add port definition | ports.nix | Use config.m3ta.ports.get |
| Enable optional service | Host config extraServices | Boolean flags |
| Modify overlays | default.nix lines 27-36 | 5 overlay sources |
| Add new user | users/ | Shared across all hosts |

## CONVENTIONS

### Port Registry Pattern
```nix
# Define in ports.nix
definitions = {
  myservice = 3099;
};

# Access in host config
config.m3ta.ports.get "myservice"  # Returns 3099
```

### extraServices Abstraction
Host configs enable via boolean:
```nix
extraServices = {
  podman.enable = true;      # Container runtime
  ollama.enable = true;      # LLM inference
  flatpak.enable = false;    # Flatpak apps
  virtualisation.enable = true;  # QEMU/KVM
};
```

### Overlay Precedence (bottom overrides top)
1. stable-packages (nixpkgs-stable)
2. locked-packages (nixpkgs-locked)
3. pinned-packages (nixpkgs-45570c2, nixpkgs-9e58ed7)
4. master-packages (nixpkgs-master)
5. m3ta-nixpkgs (local custom overlay)

## ANTI-PATTERNS

- **DON'T** add host-specific logic to common/ - belongs in hosts/<name>/
- **DON'T** bypass port registry - hardcoded ports break consistency
- **DON'T** modify user shell globally - set per-user if needed

## NOTES

- Nix GC runs weekly, keeps 30 days
- Trusted users: root, m3tam3re
- Default shell: Nushell (set line 77)
- Home-manager integrated at common level, not per-host
- TODO on line 69: ports should only return actually used ports