From 9df7bfd825809ffc3c93878c1eaa8698a2b196aa Mon Sep 17 00:00:00 2001 From: Jelle Spreeuwenberg Date: Fri, 12 Jun 2026 15:46:06 +0200 Subject: [PATCH] chore: remove outdated AGENTS.md --- AGENTS.md | 78 ------------------------------------------------------- 1 file changed, 78 deletions(-) delete mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 3a90cde..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,78 +0,0 @@ -# AGENTS.md - -## Purpose - -This repo uses the Dendritic Pattern with `flake-parts`. - -Design and change the configuration as a composition of **features**, not as a host-first tree. - -For deeper design rationale and pattern descriptions, refer to `.agents/dendritic-design-with-flake-parts.wiki`. - -## Core Terms - -- **Feature**: a flake-parts module under `modules/` that defines one coherent concern. -- **Aspect**: a reusable module published at `flake.modules..`. -- **Module class**: the configuration context of an aspect. This repo primarily uses `nixos` and `homeManager`. -- **Feature module**: the flake-parts module that defines aspects, flake outputs, options, or shared helpers. - -In this repo, `flake.nix` imports `./modules` recursively via `inputs.import-tree`. Any non-private `.nix` file under `modules/` is therefore treated as a feature module. - -## Design Principles - -- Work bottom-up. Define features first; assemble hosts from features. -- Keep semantic ownership local. A feature should contain the configuration for that concern across all relevant module classes. -- Name aspects semantically. The aspect name should usually match the file or directory name that defines it. -- Prefer small, composable aspects. Build larger configurations with `imports`. -- Import aspects unconditionally and only within the same module class. -- Put conditions inside module content with `lib.mkIf` or `lib.mkMerge`, never around `imports`. -- Avoid importing the same aspect multiple times along one import path. -- Keep private helper files next to the feature that uses them and prefix them with `_` so `import-tree` does not import them as feature modules. -- Put shared schemas and constructors in dedicated shared modules, not ad hoc host files. - -## Repo Structure - -- `modules/capabilities/`: reusable leaf capability features and most aspect definitions. -- `modules/capabilities/services/`: reusable service capabilities, especially hosted daemons and network services. -- `modules/profiles/`: bundle features that assemble capabilities into larger profiles such as `host-base` and `workstation-base`. -- `modules/hosts//default.nix`: host features that assemble NixOS aspects into `flake.modules.nixos.`. -- `modules/secrets/`: secret-related features shared by hosts. -- `modules/flake-parts.nix`: flake-parts entrypoint; defines systems, formatter, and `flake.nixosConfigurations`. -- `modules/lib/`: shared schemas, constructors, and helpers exposed through `repo.helpers`, especially `mkHost` and `mkCaddyReverseProxy`. -- `modules/data.nix`: canonical shared repo data, including the single `repo.account`, machine inventory, desktop preferences, services, and theme data. -- `modules/lib/schema.nix`: shared metadata schema for `repo.*` and NixOS `meta.machine`. - -## How Features Are Applied Here - -- Reusable NixOS concerns are published as `flake.modules.nixos.`. -- Reusable Home Manager concerns are published as `flake.modules.homeManager.`. -- Hosts are aspects too. `orion`, `polaris`, and `zenith` are `nixos` aspects assembled from smaller aspects. -- `flake.nixosConfigurations` instantiates every entry in `repo.machines` with `config.repo.helpers.mkHost`. -- Hosts define machine data under `repo.machines.` and host-specific NixOS composition under `flake.modules.nixos.`. -- `mkHost` wires the single `repo.account` into `users.users.` and `home-manager.users.`. -- NixOS modules may read `config.meta.machine`; Home Manager modules should read host facts through `osConfig.meta.machine` and user facts through `config.home` or `repo.account`. - -## Preferred Aspect Patterns - -- **Simple Aspect**: use for one self-contained concern in one or more module classes. -- **Multi Context Aspect**: use when one concern must configure both `nixos` and `homeManager`. -- **Inheritance Aspect**: use by importing a parent aspect and extending it. -- **Conditional Aspect**: use `lib.mkMerge` plus `lib.mkIf` for conditional content. - -Use **Collector Aspect** only when composition through imports or shared library helpers is insufficient. - -## Change Rules - -- When adding a reusable leaf feature, add or extend aspects under `modules/capabilities/` and let profiles or hosts opt into them explicitly. -- When adding a hosted service or network daemon feature, prefer `modules/capabilities/services/`. -- When adding a bundle of existing capabilities, put it under `modules/profiles/`. -- When adding a host, create `modules/hosts//default.nix` and keep host-local generated files private as `_hardware.nix`, `_disk.nix`, or similar. -- When a feature needs local data or helper code, keep it inside that feature directory and prefix non-feature files with `_` when they live under `modules/`. -- Do not place arbitrary non-feature `.nix` files under `modules/` unless they are intentionally private and excluded from recursive import. -- If a concern is shared across hosts, it belongs in a reusable feature, not inline in one host unless it is truly host-specific. - -## Practical Heuristics - -- If you are about to edit a host because of a reusable concern, that concern probably wants its own feature. -- If a Home Manager module needs host facts, prefer `osConfig.meta.machine`; for user facts, prefer `config.home` or `repo.account` instead of duplicating literals. -- If a concern spans system and user space, keep both aspects in one feature so the behavior stays coherent. -- If imports would need to be conditional, redesign the aspect boundary instead.