105 lines
3.8 KiB
Markdown
105 lines
3.8 KiB
Markdown
# 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.
|