{
  "projectName": "nixos-config",
  "description": "A reliable, elegant, multi-system NixOS flake configuration for personal desktop, server, cloud, Home Manager, package, overlay, and secret management.",
  "goals": [
    {
      "id": "goal-reliability-1",
      "description": "Keep all managed NixOS systems reproducible, reliable, and easy to validate before deployment.",
      "category": "reliability",
      "priority": "high",
      "status": "active"
    },
    {
      "id": "goal-architecture-1",
      "description": "Maintain an elegant multi-system architecture with clear host boundaries and reusable common modules.",
      "category": "architecture",
      "priority": "high",
      "status": "active"
    },
    {
      "id": "goal-modularization-1",
      "description": "Continue breaking up the former monorepo by keeping Home Manager profiles in m3ta-home and custom packages/modules in m3ta-nixpkgs where appropriate.",
      "category": "modularization",
      "priority": "high",
      "status": "active"
    },
    {
      "id": "goal-cicd-1",
      "description": "CI/CD is not currently configured; add useful Gitea Actions validation later for formatting, linting, flake evaluation, and safe host checks.",
      "category": "automation",
      "priority": "medium",
      "status": "deferred"
    }
  ],
  "techStack": {
    "languages": [
      {
        "name": "Nix",
        "role": "primary system, module, overlay, and package configuration language"
      },
      {
        "name": "Markdown",
        "role": "project, agent, and workflow documentation"
      },
      {
        "name": "JSON/YAML",
        "role": "tool configuration and metadata"
      }
    ],
    "frameworks": [
      {
        "name": "Nix flakes",
        "category": "reproducible dependency and output model"
      },
      {
        "name": "NixOS modules",
        "category": "host and service configuration"
      },
      {
        "name": "Home Manager",
        "category": "user environment management"
      },
      {
        "name": "Agenix",
        "category": "encrypted secret management"
      },
      {
        "name": "Disko",
        "category": "server disk provisioning"
      },
      {
        "name": "NUR",
        "category": "community package access"
      },
      {
        "name": "llm-agents.nix",
        "category": "LLM agent packages overlay"
      },
      {
        "name": "m3ta-home",
        "category": "external reusable Home Manager profiles"
      },
      {
        "name": "m3ta-nixpkgs",
        "category": "external custom packages/modules/overlays"
      }
    ],
    "databases": [],
    "infrastructure": [
      {
        "name": "m3-ares",
        "category": "desktop NixOS host"
      },
      {
        "name": "m3-kratos",
        "category": "desktop NixOS host"
      },
      {
        "name": "m3-daedalus",
        "category": "portable laptop/Home Manager configuration"
      },
      {
        "name": "m3-atlas",
        "category": "primary server NixOS host"
      },
      {
        "name": "m3-helios",
        "category": "minimal server/AdGuard host"
      },
      {
        "name": "m3-hermes",
        "category": "secondary server/Hermes host"
      },
      {
        "name": "m3-aether",
        "category": "cloud VM/minimal server host"
      }
    ],
    "buildTools": [
      "nix",
      "nixos-rebuild",
      "nix build",
      "nix flake show",
      "alejandra",
      "statix",
      "deadnix"
    ],
    "packageManagers": [
      "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.",
    "modules": [
      {
        "name": "flake.nix",
        "path": "flake.nix",
        "description": "Top-level entry point defining inputs, packages, overlays, Home Manager modules, NixOS configurations, and dev shells."
      },
      {
        "name": "hosts/common",
        "path": "hosts/common",
        "description": "Shared NixOS configuration, nix settings, overlays, Home Manager setup, ports, extra services, and users."
      },
      {
        "name": "hosts",
        "path": "hosts",
        "description": "Per-host NixOS/Home Manager configurations for desktops, servers, and cloud VM."
      },
      {
        "name": "modules/nixos",
        "path": "modules/nixos",
        "description": "Reusable NixOS modules."
      },
      {
        "name": "modules/home-manager",
        "path": "modules/home-manager",
        "description": "Reusable Home Manager module exports."
      },
      {
        "name": "overlays",
        "path": "overlays",
        "description": "Nixpkgs overlays for stable, locked, pinned, master, temporary, and agent packages."
      },
      {
        "name": "pkgs",
        "path": "pkgs",
        "description": "Custom package export set."
      },
      {
        "name": "secrets",
        "path": "secrets",
        "description": "Encrypted agenix secret files and registry."
      }
    ],
    "entryPoints": [
      "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"
    ],
    "dataFlow": "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."
  },
  "team": [
    {
      "name": "m3tam3re",
      "role": "solo developer and operator",
      "responsibilities": [
        "architecture",
        "implementation",
        "host maintenance",
        "deployments",
        "review"
      ]
    },
    {
      "name": "m3ta-chiron",
      "role": "agent contributor",
      "responsibilities": [
        "semi-autonomous implementation",
        "validation",
        "documentation updates",
        "conventional commits"
      ]
    }
  ],
  "workflows": [
    {
      "name": "development",
      "description": "Default feature-branch workflow for solo development with conventional commits and validation before push.",
      "steps": [
        "review Beads issues with bd ready --json",
        "claim work with bd update <id> --claim when applicable",
        "edit Nix modules or project files",
        "run alejandra .",
        "run statix check .",
        "run targeted nix flake or host dry-run checks",
        "commit with conventional commit format",
        "pull --rebase and push"
      ],
      "triggers": [
        "new feature",
        "bug fix",
        "refactor",
        "agent task"
      ]
    },
    {
      "name": "nix validation",
      "description": "Quality gate for Nix configuration changes.",
      "steps": [
        "alejandra .",
        "statix check .",
        "deadnix check or deadnix -w when appropriate",
        "nix flake show",
        "sudo nixos-rebuild dry-run --flake .#<host> for affected hosts"
      ],
      "triggers": [
        "Nix code changes",
        "before deployment",
        "before commit"
      ]
    },
    {
      "name": "host deployment",
      "description": "Manual deployment after successful dry-run validation.",
      "steps": [
        "sudo nixos-rebuild dry-run --flake .#<host>",
        "sudo nixos-rebuild switch --flake .#<host>"
      ],
      "triggers": [
        "manual host update"
      ]
    },
    {
      "name": "dependency/input update",
      "description": "Controlled flake input updates without manually editing flake.lock.",
      "steps": [
        "use nix flake update or nixos-rebuild --update-input <input>",
        "validate affected outputs",
        "commit flake.nix/flake.lock changes"
      ],
      "triggers": [
        "planned dependency update",
        "security update"
      ]
    },
    {
      "name": "beads issue tracking",
      "description": "Persistent issue tracking and session handoff workflow.",
      "steps": [
        "bd ready --json",
        "bd show <id>",
        "bd update <id> --claim",
        "bd close <id> --reason <summary>",
        "bd dolt push"
      ],
      "triggers": [
        "start of tracked work",
        "completion of tracked work"
      ]
    }
  ],
  "processes": [
    {
      "id": "cradle/project-install",
      "name": "Babysitter project install",
      "status": "installing",
      "purpose": "Create and save a Babysitter project profile and setup recommendations."
    }
  ],
  "tools": {
    "formatting": [
      {
        "name": "alejandra",
        "purpose": "Nix formatting",
        "configPaths": [
          "flake.nix devShells.default"
        ]
      }
    ],
    "linting": [
      {
        "name": "statix",
        "purpose": "Nix anti-pattern linting",
        "configPaths": [
          "flake.nix devShells.default"
        ]
      },
      {
        "name": "deadnix",
        "purpose": "Detect unused Nix code",
        "configPaths": [
          "flake.nix devShells.default"
        ]
      }
    ],
    "testing": [
      {
        "name": "nix flake show",
        "purpose": "Evaluate flake outputs",
        "configPaths": [
          "flake.nix"
        ]
      },
      {
        "name": "nixos-rebuild dry-run",
        "purpose": "Validate host configurations without applying changes",
        "configPaths": [
          "flake.nix",
          "hosts/*"
        ]
      },
      {
        "name": "nix build",
        "purpose": "Build selected outputs such as host toplevels or ISOs",
        "configPaths": [
          "flake.nix"
        ]
      }
    ],
    "issueTracking": [
      {
        "name": "Beads",
        "command": "bd",
        "purpose": "Persistent task tracking"
      }
    ]
  },
  "services": [
    {
      "name": "code.m3ta.dev",
      "type": "git hosting",
      "url": "git+ssh://gitea@code.m3ta.dev"
    },
    {
      "name": "GitHub",
      "type": "flake input hosting",
      "url": "github:* flake inputs"
    },
    {
      "name": "Agenix",
      "type": "secret encryption",
      "url": "github:ryantm/agenix"
    },
    {
      "name": "Hermes Agent",
      "type": "NixOS module/agent service",
      "url": "github:NousResearch/hermes-agent"
    },
    {
      "name": "RustFS",
      "type": "NixOS server service flake",
      "url": "github:rustfs/rustfs-flake"
    }
  ],
  "externalIntegrations": [
    {
      "service": "Beads",
      "category": "issue tracking",
      "enabled": true
    },
    {
      "service": "Dolt",
      "category": "Beads storage/sync",
      "enabled": true
    },
    {
      "service": "Agenix",
      "category": "secrets",
      "enabled": true
    },
    {
      "service": "Home Manager",
      "category": "user environment",
      "enabled": true
    },
    {
      "service": "m3ta-home",
      "category": "external home profiles",
      "enabled": true
    },
    {
      "service": "m3ta-nixpkgs",
      "category": "external Nix modules/packages",
      "enabled": true
    },
    {
      "service": "NUR",
      "category": "Nix packages",
      "enabled": true
    },
    {
      "service": "Disko",
      "category": "disk provisioning",
      "enabled": true
    },
    {
      "service": "Hermes Agent",
      "category": "LLM/agent service",
      "enabled": true
    }
  ],
  "cicd": {
    "provider": null,
    "enabled": false,
    "configPaths": [],
    "pipelines": [],
    "notes": "CI/CD is intentionally disabled for now. If re-enabled later, prefer Gitea Actions because this repository is hosted on code.m3ta.dev.",
    "babysitterIntegration": {
      "enabled": false,
      "triggerOn": [],
      "processIds": []
    }
  },
  "painPoints": [
    {
      "id": "pp-architecture-1",
      "description": "The repository is transitioning away from a monorepo; boundaries with m3ta-home and m3ta-nixpkgs must remain clear.",
      "severity": "high",
      "category": "architecture",
      "discoveredVia": "user interview",
      "suggestedRemediation": "Keep host-specific decisions local while moving reusable Home Manager profiles and package/module abstractions to their dedicated inputs."
    },
    {
      "id": "pp-validation-1",
      "description": "A single shared Nix change can require validating several hosts to be confident.",
      "severity": "medium",
      "category": "validation",
      "discoveredVia": "repo structure and AGENTS workflow",
      "suggestedRemediation": "Use targeted affected-host validation locally for now; add a Gitea Actions validation matrix later if CI/CD is re-enabled."
    },
    {
      "id": "pp-dependency-1",
      "description": "Multiple pinned, locked, stable, master, and external SSH flake inputs increase update complexity.",
      "severity": "medium",
      "category": "dependency management",
      "discoveredVia": "flake and history analysis",
      "suggestedRemediation": "Update inputs intentionally, group related updates, and validate affected host outputs."
    },
    {
      "id": "pp-operations-1",
      "description": "Service additions often need synchronized module, secret, and network/TLS changes.",
      "severity": "medium",
      "category": "operations",
      "discoveredVia": "git history and tree structure",
      "suggestedRemediation": "Use checklist-style issue templates or Babysitter processes for service changes."
    }
  ],
  "bottlenecks": [
    {
      "id": "bn-flake-1",
      "description": "flake.nix and flake.lock are high-churn files whose changes can affect many hosts at once.",
      "impact": "High; evaluation failures can block all hosts.",
      "location": "flake.nix, flake.lock",
      "frequency": "very frequent"
    },
    {
      "id": "bn-secrets-1",
      "description": "Secret registry and host secret modules must stay aligned with encrypted .age files.",
      "impact": "Medium to high; missing or mismatched secrets break host deployment.",
      "location": "secrets.nix, hosts/*/secrets.nix, secrets/*.age",
      "frequency": "recurring"
    },
    {
      "id": "bn-services-1",
      "description": "Server service changes can span service modules, secrets, Traefik/networking, and flake inputs.",
      "impact": "High for m3-atlas and m3-hermes changes; requires host-specific dry-runs.",
      "location": "hosts/m3-atlas/services, hosts/m3-hermes/services, hosts/common",
      "frequency": "frequent"
    },
    {
      "id": "bn-home-1",
      "description": "Home Manager behavior depends on both the external m3ta-home input and local host flags.",
      "impact": "Medium; may require coordinated updates across repositories.",
      "location": "flake.nix, hosts/common/users/m3tam3re.nix, m3ta-home input",
      "frequency": "frequent after migration"
    }
  ],
  "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"
    },
    "codeStyle": {
      "formatter": "alejandra",
      "indentation": "2 spaces",
      "nixStyle": "explicit pkgs references preferred; avoid with pkgs, builtins.fetchTarball, import <nixpkgs>, builtins.getAttr/hasAttr"
    },
    "importOrder": [
      "module function arguments",
      "imports",
      "let bindings",
      "options/config"
    ],
    "errorHandling": "Nix configuration should fail explicitly during evaluation/build; avoid hiding errors or impure paths.",
    "testingConventions": "Run alejandra, statix, deadnix as appropriate, nix flake show, and host-specific nixos-rebuild dry-run before switching.",
    "additionalRules": [
      "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": [
    {
      "name": "nixos-config",
      "path": "/home/m3tam3re/p/NIX/nixos-config",
      "role": "primary multi-host NixOS configuration"
    },
    {
      "name": "m3ta-home",
      "url": "git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home",
      "role": "external Home Manager profiles"
    },
    {
      "name": "m3ta-nixpkgs",
      "url": "git+ssh://gitea@code.m3ta.dev/m3tam3re/nixpkgs",
      "role": "external custom packages/modules/overlays"
    }
  ],
  "claudeMdInstructions": [
    "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."
  ],
  "installedSkills": [
    "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"
  ],
  "installedAgents": [
    "general-purpose",
    "specializations/devops-sre-platform/agents/platform-engineer/AGENT.md",
    "specializations/devops-sre-platform/agents/cicd-specialist/AGENT.md"
  ],
  "installedProcesses": [
    "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"
  ],
  "preferences": {
    "babysitterAutonomy": "semi-autonomous",
    "breakpointTolerance": "moderate",
    "externalIntegrationsRequested": false,
    "cicdDesired": false,
    "cicdNote": "Deferred for now; Gitea Actions is the preferred provider if CI/CD is added later."
  },
  "createdAt": "2026-05-29T15:50:48.754Z",
  "updatedAt": "2026-05-29T16:07:19.245463Z",
  "version": 1
}