lux/AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
This repository is a Den-based NixOS flake. `flake.nix` evaluates `./modules` through `import-tree`, so normal `.nix` files under `modules/` are auto-imported.

- `modules/den.nix` imports the Den flake module and the `lux` namespace.
- `modules/defaults.nix` sets repo-wide Den defaults, enables `den._.mutual-provider`, and configures `den.ctx.hm-host`.
- `modules/schema.nix` defines the custom Den host and user schema used by this repo.
- `modules/infra.nix` defines `den.hosts.x86_64-linux.<name>`, each host entity's `users` attrset, and the host/user data attached to those entities.
- `modules/bundles.nix` defines bundle aspects that group other aspects. A bundle aspect may exist only to compose `includes`; `local-session` is an example.
- `modules/hosts/` contains host-specific composition and hardware data for `orion`, `polaris`, and `zenith`.
- `modules/features/` contains reusable aspects. In this repo, "feature" is only a directory label, not a Den primitive.
- `modules/users/` defines per-user aspects.
- `modules/secrets/` wires `sops-nix` and stores the encrypted `secrets.yaml`.
- `.agents/den/` is a local checkout of Den with source, docs, and examples.

Keep host files thin. Shared behavior belongs in `modules/features/` or `modules/bundles.nix`.
When Den behavior is unclear, read `.agents/den/modules/` and `.agents/den/nix/lib/` first. Use `.agents/den/templates/ci/` as example code. Use `.agents/den/docs/` only for design rationale, terminology, and usage guidance.
Do not infer Den behavior from surface symptoms or from where an aspect is included; reason from the actual context pipeline.

## Den Mental Model
Den is aspect-first and context-driven.

- Host, user, and home are entity kinds in Den. This repo defines host and user entities; it does not define standalone home entities under `modules/`.
- An aspect is the unit of behavior. A single aspect may define `nixos`, `homeManager`, `darwin`, `user`, or other class fragments for one concern.
- A context stage applies a resolved aspect to a context; Den then follows `into.*` and `provides.*`.
- `homeManager` is a forwarding class.

In practice:

- Including an aspect does not by itself create a forwarding path.
- Parametric matching does not by itself create a forwarding path.
- A class fragment reaches its final option path only if a context stage or forwarding class actually puts it there.
- If you cannot name the context stage and forwarding path, treat the claim as unverified.

## Den Context Stages And Forwarding Mechanisms
These are the mechanisms most relevant to the context pipeline in this repo.

- `den.ctx.host`: host context stage; applies `fixedTo { host; } host.aspect`
- `den.ctx.user`: user context stage from `den.ctx.host.into.user`; applies `fixedTo { host; user; } user.aspect`
- `den._.mutual-provider`: battery included on `den.ctx.user` in this repo; routes host-to-user and user-to-host through `provides.<name>`, host-to-all-users through `provides.to-users`, user-to-hosts through `provides.to-hosts`, and user-to-other-users on the same host through the same user context pipeline. In Den generally it also has standalone-home behavior, but this repo does not use standalone `den.homes`
- `den.ctx.hm-host` / `den.ctx.hm-user`: derived home-env context stages
- `den._.define-user`: battery included by `den.default` in this repo; defines base OS user fields and base `homeManager.home.username` / `home.homeDirectory` fields
- `homeManager`: forwarding class into `home-manager.users.<name>`
- `den._.os-user`: framework battery forwarding the `user` class into `users.users.<name>`; useful in Den generally, but not used in this repo today
- `den._.forward`: battery for custom class/path forwarding

## Den Helper Functions
These are the Den helpers that matter most in this repo.

- `den.lib.perHost`: exact `{ host }` wrapper
- `den.lib.perUser`: exact `{ host, user }` wrapper
- `den.lib.perHome`: exact `{ home }` wrapper; not used by this flake today
- `den.lib.parametric`: explicit parametric wrapper; default matching is `atLeast`
- `den.lib.parametric.exactly`: explicit exact-match wrapper

## Den Forwarding Proof Obligation
When making or reviewing any Den forwarding change, do not infer behavior from where code is declared or included.

You must identify all four of these explicitly:

1. Source: which aspect actually owns the class fragment?
2. Context stage: which `den.ctx.*` stage applies it?
3. Destination: which final evaluated option path should contain the result?
4. Mechanism: which `into.*` transition reaches the context stage, and which class application, `provides.*`, forwarding class, or `den._.forward` step places it at the destination?

If any of those answers are missing, unclear, or based on analogy, treat the claim as unverified.

Before presenting a forwarding claim as a recommendation or review finding, verify it at the evaluated destination with `nix eval`.

Minimum checks:

- host-selected `homeManager` behavior: inspect `nixosConfigurations.<host>.config.home-manager.users.<user>`
- OS user forwarding via `user` class: inspect `nixosConfigurations.<host>.config.users.users.<user>`
- mutual host/user forwarding through `provides.<name>`, `provides.to-users`, or `provides.to-hosts`: inspect the final destination option, not the declaration site
- custom forwarding through `den._.forward`: inspect the exact target path created by the forwarder

## Validation And Development Commands
Run commands from the repository root.

- `nix build --no-link --show-trace .#nixosConfigurations.<host>.config.system.build.toplevel`: baseline validation for one host without activation and without creating a `result` symlink.
- `nix build --no-link --show-trace .#nixosConfigurations.orion.config.system.build.toplevel .#nixosConfigurations.polaris.config.system.build.toplevel .#nixosConfigurations.zenith.config.system.build.toplevel`: validate all currently defined hosts in one invocation.
- `nixos-rebuild build --flake .#<host>`: use the standard rebuild path without activation when you specifically want `nixos-rebuild` semantics.
- `nix fmt`: format Nix files using the flake-provided `nixfmt` formatter.
- `nix eval .#nixosConfigurations.<host>.config.<option>`: inspect a single option while iterating.

This repo does not define a `checks` output or a first-party test suite. Treat evaluation and build-only checks as the baseline. `nix flake check` is therefore not the baseline validation command here. `nixos-rebuild dry-activate` is not a baseline validation command either: it is activation-oriented, applies to the target system being rebuilt, and its own help text says the reported change set is not guaranteed to be complete.

For Den context-stage or forwarding changes, use the destination checks above.

## Coding Style & Naming Conventions
Use two-space indentation and standard Nix attrset formatting. Prefer small `let` bindings, lowerCamelCase local names, and lowercase file names such as `sops-password.nix`. Match the surrounding module style instead of reformatting unrelated code.

Prefer Den composition through `includes`; avoid host-specific duplication when a reusable aspect or bundle aspect is clearer.
Keep the configuration aspect-first. When a class fragment must cross context boundaries, express that through an explicit forwarding mechanism instead of relying on implicit host/user propagation.

## Commit
Follow the history style: short imperative subjects, optionally with a conventional prefix, for example `refactor: restructure openssh config`. Keep each commit focused on one concern.

## Security & Configuration Tips
Never commit plaintext secrets. Add or update secrets through `modules/secrets/secrets.yaml` and reference them via `config.sops.secrets.<name>.path`. Be explicit about firewall, SSH, disk, boot, or firmware changes; those are the highest-risk edits here.