diff --git a/AGENTS.md b/AGENTS.md index d7d4353..707b1ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,37 +3,99 @@ ## 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/hosts/` contains host-specific composition and hardware data for `polaris` and `orion`. -- `modules/features/` contains aspects such as desktop, shell, services, and Neovim. -- `modules/profiles/` holds higher-level bundles such as `workstation.nix`. -- `modules/users/` defines user metadata and per-user behavior. +- `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.`, 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/profiles/`. -When Den behavior is unclear, read `.agents/den/docs/`, `.agents/den/modules/`, and `.agents/den/templates/ci/` before guessing. +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. -## Build, Test, and Development Commands +## 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.`, 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.` +- `den._.os-user`: framework battery forwarding the `user` class into `users.users.`; 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..config.home-manager.users.` +- OS user forwarding via `user` class: inspect `nixosConfigurations..config.users.users.` +- mutual host/user forwarding through `provides.`, `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 .#nixosConfigurations.polaris.config.system.build.toplevel --show-trace`: evaluate and build the Polaris system. -- `nix build .#nixosConfigurations.orion.config.system.build.toplevel --show-trace`: evaluate and build the Orion system. -- `nixos-rebuild build --flake .#`: use the standard rebuild path without activating it. -- `nix fmt`: format Nix files using the flake-provided formatter. +- `nix build --no-link --show-trace .#nixosConfigurations..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 .#`: 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..config.