nixos-config/.a5c/project-profile.md

Project Profile: nixos-config

A reliable, elegant, multi-system NixOS flake configuration for personal desktop, server, cloud, Home Manager, package, overlay, and secret management.

Last updated: 2026-05-29T16:02:11.092188Z | Version: 1

Goals

• reliability [high]: Keep all managed NixOS systems reproducible, reliable, and easy to validate before deployment. (active)
• architecture [high]: Maintain an elegant multi-system architecture with clear host boundaries and reusable common modules. (active)
• modularization [high]: Continue breaking up the former monorepo by keeping Home Manager profiles in m3ta-home and custom packages/modules in m3ta-nixpkgs where appropriate. (active)
• automation [medium]: CI/CD is not currently configured; add useful Gitea Actions validation later for formatting, linting, flake evaluation, and safe host checks. (deferred)

Tech Stack

Languages

• Nix (primary system, module, overlay, and package configuration language)
• Markdown (project, agent, and workflow documentation)
• JSON/YAML (tool configuration and metadata)

Frameworks

• Nix flakes [reproducible dependency and output model]
• NixOS modules [host and service configuration]
• Home Manager [user environment management]
• Agenix [encrypted secret management]
• Disko [server disk provisioning]
• NUR [community package access]
• llm-agents.nix [LLM agent packages overlay]
• m3ta-home [external reusable Home Manager profiles]
• m3ta-nixpkgs [external custom packages/modules/overlays]

Infrastructure

• m3-ares [desktop NixOS host]
• m3-kratos [desktop NixOS host]
• m3-daedalus [portable laptop/Home Manager configuration]
• m3-atlas [primary server NixOS host]
• m3-helios [minimal server/AdGuard host]
• m3-hermes [secondary server/Hermes host]
• m3-aether [cloud VM/minimal server host]

Build tools: nix, nixos-rebuild, nix build, nix flake show, alejandra, statix, deadnix

Package managers: nix flakes

Architecture

Pattern: Pure Nix flake-based NixOS configuration repository with host-specific modules, common shared modules, overlays, custom packages, agenix secrets, and externalized Home Manager/package inputs. Data flow: flake.nix wires inputs, overlays, packages, NixOS modules, and Home Manager. Host modules import common configuration and host-specific hardware/programs/services/secrets. Host profile flags in hosts/common/users/m3tam3re.nix feed the external m3ta-home mkHome integration. Secrets flow through agenix registry and host secret modules.

Modules

Module	Path	Description
flake.nix	flake.nix	Top-level entry point defining inputs, packages, overlays, Home Manager modules, NixOS configurations, and dev shells.
hosts/common	hosts/common	Shared NixOS configuration, nix settings, overlays, Home Manager setup, ports, extra services, and users.
hosts	hosts	Per-host NixOS/Home Manager configurations for desktops, servers, and cloud VM.
modules/nixos	modules/nixos	Reusable NixOS modules.
modules/home-manager	modules/home-manager	Reusable Home Manager module exports.
overlays	overlays	Nixpkgs overlays for stable, locked, pinned, master, temporary, and agent packages.
pkgs	pkgs	Custom package export set.
secrets	secrets	Encrypted agenix secret files and registry.

Entry points: flake.nix, hosts/<host>/default.nix, hosts/<host>/configuration.nix, hosts/common/default.nix, hosts/common/users/m3tam3re.nix, overlays/default.nix, pkgs/default.nix, secrets.nix

Team

• m3tam3re (solo developer and operator): architecture, implementation, host maintenance, deployments, review
• m3ta-chiron (agent contributor): semi-autonomous implementation, validation, documentation updates, conventional commits

Workflows

development

Default feature-branch workflow for solo development with conventional commits and validation before push. Triggers: new feature, bug fix, refactor, agent task

1. review Beads issues with bd ready --json
2. claim work with bd update --claim when applicable
3. edit Nix modules or project files
4. run alejandra .
5. run statix check .
6. run targeted nix flake or host dry-run checks
7. commit with conventional commit format
8. pull --rebase and push

nix validation

Quality gate for Nix configuration changes. Triggers: Nix code changes, before deployment, before commit

1. alejandra .
2. statix check .
3. deadnix check or deadnix -w when appropriate
4. nix flake show
5. sudo nixos-rebuild dry-run --flake .# for affected hosts

host deployment

Manual deployment after successful dry-run validation. Triggers: manual host update

1. sudo nixos-rebuild dry-run --flake .#
2. sudo nixos-rebuild switch --flake .#

dependency/input update

Controlled flake input updates without manually editing flake.lock. Triggers: planned dependency update, security update

1. use nix flake update or nixos-rebuild --update-input
2. validate affected outputs
3. commit flake.nix/flake.lock changes

beads issue tracking

Persistent issue tracking and session handoff workflow. Triggers: start of tracked work, completion of tracked work

1. bd ready --json
2. bd show
3. bd update --claim
4. bd close --reason
5. bd dolt push

Processes

• Babysitter project install (cradle/project-install, undefined)

Tools

Linting

• statix
• deadnix

Testing

• nix flake show
• nixos-rebuild dry-run
• nix build

Formatting

• alejandra

Services

• code.m3ta.dev (git hosting) - git+ssh://gitea@code.m3ta.dev
• GitHub (flake input hosting) - github:* flake inputs
• Agenix (secret encryption) - github:ryantm/agenix
• Hermes Agent (NixOS module/agent service) - github:NousResearch/hermes-agent
• RustFS (NixOS server service flake) - github:rustfs/rustfs-flake

CI/CD

Status: Not configured/enabled for now.

No Babysitter CI/CD workflow is currently installed. If CI/CD is added later, prefer Gitea Actions because this repository is hosted on code.m3ta.dev.

Pain Points

• high [architecture]: The repository is transitioning away from a monorepo; boundaries with m3ta-home and m3ta-nixpkgs must remain clear.
  • Remediation: Keep host-specific decisions local while moving reusable Home Manager profiles and package/module abstractions to their dedicated inputs.
• medium [validation]: A single shared Nix change can require validating several hosts to be confident.
  • Remediation: Use targeted affected-host validation locally for now; add a Gitea Actions validation matrix later if CI/CD is re-enabled.
• medium [dependency management]: Multiple pinned, locked, stable, master, and external SSH flake inputs increase update complexity.
  • Remediation: Update inputs intentionally, group related updates, and validate affected host outputs.
• medium [operations]: Service additions often need synchronized module, secret, and network/TLS changes.
  • Remediation: Use checklist-style issue templates or Babysitter processes for service changes.

Bottlenecks

• flake.nix and flake.lock are high-churn files whose changes can affect many hosts at once. at flake.nix, flake.lock (very frequent) Impact: High; evaluation failures can block all hosts.
• Secret registry and host secret modules must stay aligned with encrypted .age files. at secrets.nix, hosts//secrets.nix, secrets/.age (recurring) Impact: Medium to high; missing or mismatched secrets break host deployment.
• Server service changes can span service modules, secrets, Traefik/networking, and flake inputs. at hosts/m3-atlas/services, hosts/m3-hermes/services, hosts/common (frequent) Impact: High for m3-atlas and m3-hermes changes; requires host-specific dry-runs.
• Home Manager behavior depends on both the external m3ta-home input and local host flags. at flake.nix, hosts/common/users/m3tam3re.nix, m3ta-home input (frequent after migration) Impact: Medium; may require coordinated updates across repositories.

Conventions

Naming

• files: hyphen-case for Nix/docs where practical; host directories use m3-* names
• hosts: m3-
• modules: one module per file/directory where possible
• nixVariables: camelCase

Git

• branchStrategy: default feature branches for non-trivial work; master as integration branch
• commits: conventional commits for agent work
• reviews: optional for solo development
• releaseCadence: continuous/manual as needed
• remote: code.m3ta.dev over SSH for private inputs and repo access

Import order: module function arguments > imports > let bindings > options/config

Error handling: Nix configuration should fail explicitly during evaluation/build; avoid hiding errors or impure paths.

Testing: Run alejandra, statix, deadnix as appropriate, nix flake show, and host-specific nixos-rebuild dry-run before switching.

Additional Rules

• Use Beads for persistent task tracking.
• Use non-interactive flags for shell file operations.
• Do not modify flake.lock directly; use nix flake update.
• Do not commit plaintext secrets.
• Use SSH URLs for code.m3ta.dev flake inputs.
• Operate Babysitter semi-autonomously with breakpoints for destructive, deployment, or architecture-changing decisions.

Repositories

• nixos-config [/home/m3tam3re/p/NIX/nixos-config]
• m3ta-home - git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home
• m3ta-nixpkgs - git+ssh://gitea@code.m3ta.dev/m3tam3re/nixpkgs

CLAUDE.md Instructions

• Respect AGENTS.md as the source of project workflow rules.
• Resolve the active Babysitter process library before using library processes.
• Use cradle/project-install for project setup or profile refresh.
• Use evolutionary GSD: map affected Nix modules/hosts, make focused changes, verify, and iterate.
• Prefer alejandra, statix, deadnix, nix flake show, and targeted host dry-runs for Nix changes.
• Preserve boundaries between nixos-config, m3ta-home, and m3ta-nixpkgs.
• Use breakpoints for destructive operations, deployments, architecture changes, and secret-handling decisions.
• Babysitter CI/CD is not currently enabled; if re-added later, use Gitea Actions rather than GitHub Actions.

Installed Extensions

• Skills: project-install, babysit, specializations/devops-sre-platform/skills/cicd-pipelines/SKILL.md, specializations/devops-sre-platform/skills/gitops/SKILL.md, specializations/devops-sre-platform/skills/secrets-management/SKILL.md
• Agents: general-purpose, specializations/devops-sre-platform/agents/platform-engineer/AGENT.md, specializations/devops-sre-platform/agents/cicd-specialist/AGENT.md
• Processes: cradle/project-install, methodologies/gsd/quick.js, methodologies/gsd/verify-work.js, methodologies/gsd/iterative-convergence.js, methodologies/evolutionary.js, specializations/devops-sre-platform/iac-testing.js