# 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.