From a0789edb6ec87ee2756b96c9d3f4a1b4da4aa41b Mon Sep 17 00:00:00 2001
From: Fabian Montero <fabian@posixlycorrect.com>
Date: Mon, 2 Mar 2026 20:35:36 -0600
Subject: [PATCH] yeah i use some ai lol, sorry

---
 CLAUDE.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4d171d4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,105 @@
+# 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.