frabarz.cl / nix-config
nix config for my personal machines
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

nix-config / AGENTS.md
at main 2.8 kB view raw view code
frabarz.cl replaces kde with sway on baxi
1511dcbc

Project Conventions & Operational Standards#

1. Architectural Principles#

  • Beginner Friendly: All instructions should be targeted to users that are unfamiliar to the nix language. Be explicit about where and under which environment the commands should be run. Don't go into much detail either; give references to manuals or other resources.
  • Declarative over Imperative: All configurations must be defined in Nix files. Scripts (.sh) are only for bootstrapping or deploying to non-Nix targets (e.g., OpenWRT, Android APKs).
  • Module-Based Reuse: Shared logic (shell aliases, SSH keys, common packages) must reside in modules/ and be imported by devices.
  • Secret Management: Secrets must NEVER be committed in plain text. Use sops-nix with age encryption.
  • Flake-First: The flake.nix is the single source of truth for all system definitions.

2. Directory Structure#

.
├── .design/             # Architectural specs and phase documents
├── devices/             # Device-specific configurations
│   ├── baxi/            # NixOS Desktop
│   ├── eggu/            # NixOS Server
│   ├── thor/            # macOS
│   ├── vera/            # OpenWRT Router
│   ├── fink/            # Dashboard (postmarketOS/Android)
│   └── gelt/            # Android Phone
├── modules/             # Shared Nix modules
│   ├── core/            # Base system settings (nix settings, shells)
│   ├── home/            # Home Manager modules (dotfiles)
│   └── services/        # Service definitions (HA, Jellyfin, etc.)
├── lib/                 # Pure Nix helper functions
├── pkgs/                # Custom packages/overlays
├── secrets/             # Encrypted secrets (sops)
└── flake.nix            # Entry point

Each folder in the first and second level of depth should contain a README.md file describing the purpose of the files inside it.

Important: When adding or removing files from one of these folders, update this directory structure and the respective README file.

3. Naming Conventions#

  • Files: kebab-case.nix (e.g., hardware-configuration.nix, home-assistant.nix).
  • Variables: camelCase (e.g., hostName, networking).
  • Devices: Always lowercase, single word names (e.g., baxi, thor).

4. Error Handling#

  • Validation: Use lib.asserts or throw in Nix expressions to catch invalid configurations early (e.g., duplicate IPs).
  • Scripts: All shell scripts must use set -euo pipefail.

5. Git Workflow#

  • Commits: Conventional Commits (e.g., feat(baxi): add steam, fix(vera): update firewall rules).
  • Main Branch: Always deployable.