lux-old/GEMINI.md

Gemini Context & Project Guidelines

This file serves as persistent contextual memory for the Gemini CLI when working on this NixOS configuration project.

Architecture: The den Framework

This repository manages NixOS and Home Manager configurations using the den framework. The approach here drastically differs from standard NixOS setups.

Core Concepts & Rules

1. Freeform Schemas over Custom Options: Do not use legacy Nix module options (lib.mkOption, lib.mkIf) to define simple user/host properties (like email addresses, domains, or names). Instead, attach properties directly to the host or user definition objects in hosts/<name>/default.nix or users/<name>.nix. Den's freeform entity schemas will pass these through the context pipeline automatically.
2. Parametric Aspects: When a module requires access to host or user variables (like user.email or host.domain), the aspect MUST be wrapped in den.lib.parametric.
   • Example: lux.myapp = den.lib.parametric { includes = [ ({ user, ... }: { ... }) ]; };
3. Decentralized Host & User Definitions: Do not centralize host definitions in a single file. Follow the quasigod reference structure:
   • Hosts declare themselves in modules/hosts/<hostname>/default.nix (e.g., den.hosts.x86_64-linux.orion = { ... }).
   • Users bind themselves to hosts in their own user files in modules/users/<username>.nix (e.g., den.hosts.x86_64-linux.orion.users.kiri = userAccount // { ... }).
4. App Categories & Naming:
   • /modules/desktop/: GUI, Wayland, display managers, WMs.
   • /modules/dev/: Developer tools, terminal, neovim.
   • /modules/apps/: User-level software (PIM, Bitwarden, MPV, Email). Note: pim.nix stands for Personal Information Management and is an app, not a user definition.
   • /modules/services/: System-level daemons (Caddy, Gitea, Vaultwarden).
   • /modules/profiles/: Aggregations (like workstation/server).

Common Pitfalls & Lessons Learned

• home-manager vs homeManager: When defining class configurations inside a parametric function, the key for Home Manager is strictly homeManager (camelCase). Writing home-manager.programs... will cause evaluation errors because home-manager is not the class name used by the schema.
• user is an Object: In context parameters ({ user, ... }:), user is an attribute set, not a string. Do not interpolate it directly as a string ("${user}"); use ${user.name}.
• Namespace Inclusion: The project uses the lux namespace. When an aspect needs to pull in other aspects, use with lux; [ ... ] rather than writing out den.ful.lux... repeatedly.
• Abstracting Paths: Never hardcode /home/<username>. Inside homeManager modules, use config.home.homeDirectory. Inside nixos modules (like SOPS), use /home/${user.name} where user is provided by the parametric context.
• Git Status dependency: When moving, creating, or renaming files (mv, mkdir), they must be staged in Git (git add <file>) before running nix flake check, otherwise the flake evaluator will not see the changes and will throw "undefined variable" or "path does not exist" errors.