constitution ammendment

docs/constitution.md

@@ -21,6 +21,7 @@
 - Minimize comments; prefer clear naming and shared helpers (`modules/factories/mkserver.nix`, `modules/factories/mkscript.nix`) to avoid duplication.
 - Use business-level, technology-agnostic language in AI docs; reserve implementation detail for module code.
 - Nix structure: flatten single-child attribute sets into their full path; keep multi-child sets nested for readability; merge siblings under a shared parent; flatten the shallowest subtree first to reduce indentation without losing clarity.
+- Nix attribute ordering: prefer `options` before `config` in module bodies; inside attribute sets keep `inherit` statements first, then boolean leaf assignments, then other leaf assignments, then nested attribute sets; when simple leaves and nested children share a parent, place the simple leaves first.
 ```nix
 config.services.jellyfin.enable = true; # preferred single-leaf form
 config.services = {
@@ -31,6 +32,20 @@ config.services = {
   };
 };
 ```
+```nix
+{
+  options.my.example.enable = lib.mkEnableOption "example";
+  config = lib.mkIf config.my.example.enable {
+    services.example = {
+      enable = true;
+      port = 1234;
+      nested = {
+        value = "x";
+      };
+    };
+  };
+}
+```
 
 ## Terminology and Naming Standards
 - Module: Prefer a feature directory under `modules/<category>/<name>/` with `nixos.nix` for system concerns and `home.nix` for Home Manager concerns. Legacy flat modules at `modules/<category>/<name>.nix` remain valid during migration.

specs/001-ai-docs/research.md

@@ -49,3 +49,8 @@
 - **Decision**: Add a standalone `homeConfigurations.mac` target backed by `hosts/mac/home.nix` and `hosts/mac/toggles.nix`, reusing workstation-style dev and shell modules while excluding Linux GUI app modules.
 - **Rationale**: Lets the repo model an upcoming macOS machine without forcing NixOS host semantics onto a Home Manager-only system.
 - **Alternatives considered**: (a) Wait for the physical Mac and keep no target in the flake (rejected: delays validation and reuse work); (b) model the Mac as a fake NixOS host (rejected: does not match the intended deployment model).
+
+## Decision 11 (2026-03-23): Canonical Nix nesting and ordering style
+- **Decision**: Standardize Nix structure so single-child attribute sets are flattened into dotted attrpaths, siblings that share a parent are merged into one nested attribute set, simple leaf assignments appear before nested attribute sets, `inherit` statements appear first within a set, boolean leaves appear before other leaves, and module bodies place `options` before `config`.
+- **Rationale**: This keeps modules scan-friendly, reduces unnecessary indentation, and makes the high-signal contract (`options`) appear before implementation (`config`) consistently across the repo.
+- **Alternatives considered**: (a) Leave structure to formatter defaults only (rejected: formatters do not enforce these semantic grouping rules); (b) prefer fully flattened attrpaths everywhere (rejected: harms readability once a parent has multiple children); (c) keep `config` before `options` when it was written first (rejected: makes module interfaces harder to scan).