nix-config/.github/copilot-instructions.md

Copilot Instructions for EmergentMind's Nix-Config

Project Overview

• This is a modular, flake-based NixOS configuration system for managing multiple hosts, users, and environments (NixOS, Darwin, Home Manager).
• The repo is structured for maximum composability: core logic is split into hosts/, home/, modules/, and overlays/ with heavy use of imports and attribute sets.
• Secrets are managed via a private nix-secrets repo and sops-nix, integrated as a flake input (see docs/secretsmgmt.md).

Key Architectural Patterns

• Host configs: Each host (machine) has its own directory under hosts/nixos/ or hosts/darwin/, with a default.nix that imports shared and host-specific modules.
• User configs: User-level Home Manager configs live in home/<user>/<host>.nix and are imported by host configs.
• Common logic: Shared modules for users and hosts are in hosts/common/ and home/exampleSecondUser/common/ etc.
• Optional features: Features like desktops, shells, and services are split into common/optional/ submodules and imported as needed.
• Installer: The nixos-installer/ flake provides a minimal environment and scripts for bootstrapping new machines.

Developer Workflows

• Build & switch: Use just commands (see justfile) for common workflows, e.g. just switch, just iso, or run nixos-rebuild switch --flake .#<hostname>.
• Testing: Tests are in tests/ and use bats for shell scripts. Run with just test.
• Secrets: To update secrets, edit the nix-secrets repo and re-pull as a flake input.
• Installer: See nixos-installer/README.md for remote install and ISO generation.

Project-Specific Conventions

• Imports: Always use relative imports and lib.flatten for lists of modules.
• pkgs: Always passed as an argument; use with pkgs; [...] for package lists.
• Shells: Shell configs (fish, zsh, nushell) are in home/panotaka/common/core/shell/ and imported as needed.
• Hyprland: Desktop config is modularized; plugins and settings are split into separate files (see home/panotaka/common/optional/desktops/hyprland/).
• Keybinds: For Hyprland, keybinds can be set in feature modules (e.g. hyprlock) using wayland.windowManager.hyprland.keybinds.
• Packages: Each feature module (e.g. hyprlock, hypridle) is responsible for adding its own package to home.packages.

Integration Points

• Secrets: sops-nix, private flake input, see docs/secretsmgmt.md.
• Disk layout: Uses disko for declarative disk partitioning, see hosts/common/disks/.
• Theming: Stylix is used for theming, imported as a flake input.
• Remote install: nixos-installer/ flake and scripts for remote/automated setup.

Examples

• To add a new desktop feature, create a module in common/optional/desktops/ and import it in the host or user config.
• To add a new shell, create a module in common/core/shell/ and import it in the user config.
• To add a new host, create a directory in hosts/nixos/ and a matching user config in home/<user>/.

Key Files & Directories

• flake.nix, flake.lock: Flake entrypoints
• hosts/, home/, modules/, overlays/: Core config structure
• nixos-installer/: Bootstrap/installer logic
• docs/secretsmgmt.md: Secrets management details
• justfile: Common developer commands

---

If you are unsure about a pattern, check for similar logic in the common/optional/ or common/core/ directories, and follow the import structure used in host/user configs.