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 <id> --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 .#<host> for affected hosts

### host deployment

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

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

### 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 <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 <id>
3. bd update <id> --claim
4. bd close <id> --reason <summary>
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-<greek-name>
- **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