NixOS/docs/constitution.md

AI Constitution for the NixOS Repository

Scope and Audience

• Audience: AI assistants and contributors needing an authoritative description of repository rules, structure, and workflows.
• Scope: Repo-wide conventions, module categories, host roles, secrets handling, proxy rules, documentation locations, and maintenance triggers.
• Authority: This constitution is the source of truth for AI. If human-facing docs differ, update both with the recorded resolution in specs/001-ai-docs/research.md.

Repository Overview

• Architecture: Flake-based repo using flake-parts with inputs for pkgs (stable/unstable), stylix, home-manager, sops-nix, and service overlays. Common modules are composed through parts/core.nix and parts/hosts.nix.
• Module auto-import: modules/modules.nix auto-imports .nix files under modules/apps, modules/dev, modules/scripts, modules/servers, modules/services, modules/shell, modules/websites, and modules/network, excluding librewolf.nix. Factories live in modules/factories/ (mkserver, mkscript), and shared options are in modules/nix and modules/users.
• Hosts and toggles: Host definitions live in hosts/<name>/configuration.nix with host-specific toggles in hosts/<name>/toggles.nix. The my namespace carries toggles for apps/dev/scripts/services/shell, feature flags like enableProxy and enableContainers, and per-host interfaces and ips maps.
• Main server and proxies: my.mainServer selects the host that should serve traffic by default (default vps). Reverse proxies use helpers in parts/core.nix (proxy, proxyReverse, proxyReverseFix, proxyReversePrivate) and pick IPs from my.ips plus the hostName/ip set by mkserver options. Nginx defaults to proxyReverse for any server with enableProxy = true unless useDefaultProxy = false or the server is listed in the Fix/Private proxy lists.
• Secure hosts and secrets: my.secureHost gates SOPS secrets. Secure hosts load secrets from secrets/*.yaml and wireguard definitions; non-secure hosts (e.g., hosts/emacs) skip secret-dependent services. Default SOPS file is secrets/secrets.yaml via config/base.nix. Proxy-only services that need private certificates must still define their cert secrets when enableProxy = true.

Coding Conventions

• No blank lines between code blocks; keep markdown examples tight.
• Minimize comments; prefer clear naming and shared helpers (modules/factories/mkserver.nix, modules/factories/mkscript.nix) to avoid duplication.
• Use business-level, technology-agnostic language in AI docs; reserve implementation detail for module code.
• Nix structure: flatten single-child attribute sets into their full path; keep multi-child sets nested for readability; merge siblings under a shared parent; flatten the shallowest subtree first to reduce indentation without losing clarity.

config.services.jellyfin.enable = true; # preferred single-leaf form
config.services = {
  nginx.enable = true;
  jellyfin = {
    enable = true;
    port = 1234;
  };
};

Terminology and Naming Standards

• Module: A Nix module under modules/<category>/<name>.nix auto-imported into the system.
• Factory: Shared option constructors in modules/factories/ (use mkserver for server modules, mkscript for script units).
• Options: Settings under the my namespace (e.g., my.services.<service>, my.scripts.<script>).
• Toggles: Enablement maps in hosts/<name>/toggles.nix controlling categories (apps/dev/shell/scripts/services/servers/units) and features (enableProxy, enableContainers).
• Servers: Reverse-proxied services under modules/servers/, normally created with mkserver options (including useDefaultProxy to opt out of default proxyReverse).
• Websites: Static nginx vhosts under modules/websites/ (portfolio/blog, mb-report), gated by my.websites.*.enableProxy.
• Scripts: Units defined via mkscript with enable, install, service, users, timer, and package fields.
• Playbooks: Workflow guides under docs/playbooks/ for repeatable tasks.
• Reference map: Navigation index under docs/reference/index.md for paths and responsibilities.

Secrets Map and secureHost Behavior

• Secrets files: secrets/certs.yaml, secrets/env.yaml, secrets/gallery.yaml, secrets/homepage.yaml, secrets/keys.yaml, secrets/wireguard.yaml, secrets/secrets.yaml, plus secrets/ssh/ for host keys.
• Placement rules: Keep secrets aligned to their file purpose (certificates → certs.yaml; environment/service env vars → env.yaml; media/gallery creds → gallery.yaml; homepage widgets → homepage.yaml; SSH/private keys → keys.yaml; WireGuard peers → wireguard.yaml; misc defaults → secrets.yaml).
• secureHost gating: Only hosts with my.secureHost = true load SOPS secrets and WireGuard interfaces. Hosts with secureHost = false must avoid secret-dependent services and skip SOPS entries.
• VPS enrollment flow: The vps host generates its own key on first boot, then operators enroll the public key, re-encrypt secrets, and redeploy. Follow docs/playbooks/enroll-vps.md.

Module Categories and Active Hosts

• Module categories: apps, dev, scripts, servers, services, shell, websites, network, users, nix. Factories sit in modules/factories/ and are imported explicitly; patch artifacts live at the repo root in patches/.
• Active hosts: workstation, server, miniserver, galaxy, emacs, vps. Host roles and secure status are defined in hosts/<name>/configuration.nix and toggles in hosts/<name>/toggles.nix.

Precedence and Conflict Resolution

• Precedence: This constitution is authoritative for AI. Human docs must be updated to match. If conflicts are found, align human docs to the constitution and log the resolution in specs/001-ai-docs/research.md.
• Conflict handling steps: identify the divergent rule, cite the source files, decide the authoritative rule per this constitution, update both the source file and the relevant doc, and record the decision and timestamp.

Maintenance Triggers and Update Process

• Triggers: New factory/helper, new module category, new host, new toggle set, new proxy rule, new secret category/file, change to my.mainServer or my.ips, stylix scheme changes, or new auto-import filters.
• Update flow: (1) Amend the relevant module or toggle files; (2) Update docs/constitution.md for rules/terminology changes; (3) Update playbooks under docs/playbooks/ affected by the change; (4) Update docs/reference/index.md for navigation paths; (5) Note the decision in specs/001-ai-docs/research.md and refresh quickstart.md if discoverability shifts.
• Validation: Confirm discoverability within two clicks (constitution → reference map/playbook), secrets map completeness, and alignment with success criteria SC-001–SC-004.

Quick Reference and Navigation

• Constitution: docs/constitution.md (this file)
• Reference map: docs/reference/index.md (paths, hosts, secrets, proxies, stylix)
• MCP server reference: docs/reference/mcp-server.md (tools, invocation, sync checks)
• Playbooks: docs/playbooks/*.md (add module/server/script/host toggle/secret, plus template)
• Planning artifacts: specs/001-ai-docs/ (plan, research, data-model, quickstart, contracts)