# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Architecture

This is a unified NixOS and Home Manager configuration using the **trivionomicon doctrine system** as a git subtree.

### Directory Structure

- `home/` - Home Manager user configuration
  - `modules/` - User-level feature modules (terminal, neovim, firefox, ai, etc.)
  - `platforms/` - User-specific configs per host (`fabian@t14`, `fabian@posixlycorrect`, `fabian@vps`)
- `sys/` - NixOS system configuration
  - `modules/` - System-level feature modules (audio, graphics, networking, etc.)
  - `platforms/` - Machine-specific configs (`t14`, `posixlycorrect`, `vps`)
- `pkgs/` - Custom package overlays and nixpkgs configuration
- `trivionomicon/` - Shared doctrine framework (git subtree)
  - `doctrine/` - Core library (`mkModule`, `mkSystemFlake`)
  - `modules/` - Shared modules usable by any host

### Namespace Conventions

- `config.local.*` - Home Manager modules (user level)
- `config.local.sys.*` - NixOS modules (system level)
- `config.trivium.*` - Trivionomicon shared modules

### Module Patterns

**Simple module** (single layer):
```nix
{config, lib, pkgs, ...}:
with lib; let
  cfg = config.local.programs.terminal;
in {
  options.local.programs.terminal = { enable = mkEnableOption "..."; };
  config = mkIf cfg.enable { ... };
}
```

### Platform Configuration

Each host has paired directories:
- `sys/platforms/{hostname}/` - Machine-specific NixOS config
- `home/platforms/{user}@{hostname}/` - User-specific Home Manager config

The `flake.nix` uses `trivionomicon.lib.mkSystemFlake` to auto-generate configurations from these platform directories.

## Trivionomicon System

The trivionomicon is a shared NixOS/Home Manager module framework maintained collaboratively. It lives as a git subtree at `trivionomicon/` and provides unified modules that work across both NixOS and Home Manager contexts.

### Core Functions

- **`mkDoctrine`** - Creates namespace context with the "trivium" prefix and hm/sys awareness
- **`mkModule`** - Composes hm.nix + sys.nix + options.nix into a unified module
- **`mkSystemFlake`** - Auto-generates flake outputs from platform directories

### Module Structure

```
moduleName/
├── default.nix    # Entry: calls doctrine.lib.mkModule
├── options.nix    # Options split by hm/sys keys
├── hm.nix         # Home Manager implementation (optional)
└── sys.nix        # NixOS implementation (optional)
```

### Available Modules

Modules are located at `trivionomicon/modules`.

### Git Subtree Workflow

#### Commit separation (critical):
Never create commits that include both:
- Changes inside `trivionomicon/`
- Changes outside `trivionomicon/` (home/, sys/, pkgs/, flake.nix, etc.)

The trivionomicon is a shared project. Each commit touching `trivionomicon/` must contain only trivionomicon changes so it can be cleanly pushed upstream.

#### Commit message conventions:
- If a module was modified: `trivionomicon/modules/<module name>: one line summary of changes`

Similar layout if something other than a module was modified.

#### Sync changes with the shared repository:
```bash
# Pull updates
git subtree pull --prefix=trivionomicon forgejo@git.posixlycorrect.com:deepState/trivionomicon.git master

# Push changes back
git subtree push --prefix=trivionomicon forgejo@git.posixlycorrect.com:deepState/trivionomicon.git master
```

## Key Files

- `pkgs/config/unfree.nix` - Allowlist for unfree packages (add packages here when needed)
- `pkgs/default.nix` - Package overlays and overrides
- `trivionomicon/doctrine/lib/` - Core doctrine functions for module composition

## Restrictions

Never use any `nix`, `home-manager`, `nixos-rebuild` or `nix-collect-garbage` commands.
Ask before using any `git` commands.