feat(system): add NixOS support and nix package manager integration

docs/platforms.md

@@ -10,6 +10,7 @@
 | Linux (Ubuntu/Debian) | apt | Supported |
 | Linux (Arch) | pacman | Supported |
 | Linux (Fedora/RHEL family) | dnf | Supported |
+| Linux (NixOS) | nix | Supported |
 | Windows 10/11 | Scoop | Supported |
 
 Derivatives are detected via `ID_LIKE` in `/etc/os-release` (Linux Mint, Pop!_OS, Manjaro, EndeavourOS, CentOS Stream, Rocky Linux, AlmaLinux, etc.).

internal/cli/run.go

@@ -793,15 +793,26 @@ func (s componentApplyStep) Run() error {
 			engramCommand = binaryPath
 		} else if installedPath, err := cmdLookPath("engram"); err != nil {
 			// Engram not on PATH — install it.
-			if s.profile.PackageManager == "brew" {
-				// macOS (or Linux with Homebrew): use brew tap + brew install.
+			if s.profile.PackageManager == "brew" || s.profile.PackageManager == "nix" {
+				// macOS/Brew or NixOS: use component resolver. NixOS installs from source via go install.
 				commands, err := engram.InstallCommand(s.profile)
 				if err != nil {
 					return fmt.Errorf("resolve install command for component %q: %w", s.component, err)
 				}
 				if err := runCommandSequence(commands); err != nil {
 					return err
 				}
+				if s.profile.PackageManager == "nix" {
+					// Prepends GOBIN/GOPATH bin to path so subsequent commands find the new binary.
+					if binDir, err := goInstallBinDirFromGoEnv(); err == nil && binDir != "" {
+						_ = prependToPath(binDir)
+						binaryName := "engram"
+						if runtime.GOOS == "windows" {
+							binaryName += ".exe"
+						}
+						engramCommand = filepath.Join(binDir, binaryName)
+					}
+				}
 			} else {
 				// Linux / Windows: download the pre-built binary from GitHub Releases.
 				// No Go required — engram ships pre-built binaries.

internal/cli/run_engram_download_test.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -501,7 +502,11 @@ func TestRunInstallMacOSEngramStillUsesBrew(t *testing.T) {
 func TestRunInstallBetaEngramUsesMainGoInstallAndInstalledBinary(t *testing.T) {
 	home := t.TempDir()
 	gobin := filepath.Join(home, "go-bin")
-	betaEngram := filepath.Join(gobin, "engram")
+	betaEngramName := "engram"
+	if runtime.GOOS == "windows" {
+		betaEngramName += ".exe"
+	}
+	betaEngram := filepath.Join(gobin, betaEngramName)
 
 	restoreCommand := runCommand
 	restoreLookPath := cmdLookPath
@@ -554,5 +559,61 @@ func TestRunInstallBetaEngramUsesMainGoInstallAndInstalledBinary(t *testing.T) {
 	}
 }
 
+// TestRunInstallNixOSEngramUsesGoInstall verifies NixOS uses go install.
+func TestRunInstallNixOSEngramUsesGoInstall(t *testing.T) {
+	home := t.TempDir()
+	restoreHome := osUserHomeDir
+	restoreCommand := runCommand
+	restoreLookPath := cmdLookPath
+	restoreGoEnv := goEnv
+	t.Cleanup(func() {
+		osUserHomeDir = restoreHome
+		runCommand = restoreCommand
+		cmdLookPath = restoreLookPath
+		goEnv = restoreGoEnv
+	})
+
+	osUserHomeDir = func() (string, error) { return home, nil }
+	cmdLookPath = missingBinaryLookPath
+	gobin := filepath.Join(home, "go-bin")
+	goEnv = func(keys ...string) (map[string]string, error) {
+		return map[string]string{"GOBIN": gobin, "GOPATH": filepath.Join(home, "go")}, nil
+	}
+	recorder := &commandRecorder{}
+	runCommand = recorder.record
+
+	// DownloadFn should NOT be called for NixOS (go install handles it).
+	origDownloadFn := engramDownloadFn
+	engramDownloadFn = func(profile system.PlatformProfile) (string, error) {
+		t.Error("DownloadLatestBinary should NOT be called on NixOS (go install handles it)")
+		return "", nil
+	}
+	t.Cleanup(func() { engramDownloadFn = origDownloadFn })
+
+	detection := linuxDetectionResult(system.LinuxDistroNixOS, "nix")
+	result, err := RunInstall(
+		[]string{"--agent", "opencode", "--component", "engram"},
+		detection,
+	)
+	if err != nil {
+		t.Fatalf("RunInstall() error = %v", err)
+	}
+	if !result.Verify.Ready {
+		t.Fatalf("verification ready = false")
+	}
+
+	// Must use go install.
+	commands := recorder.get()
+	foundGoInstall := false
+	for _, cmd := range commands {
+		if strings.Contains(cmd, "go install github.com/Gentleman-Programming/engram/cmd/engram@latest") {
+			foundGoInstall = true
+		}
+	}
+	if !foundGoInstall {
+		t.Fatalf("expected go install on NixOS, got commands: %v", commands)
+	}
+}
+
 // Make sure the engram package's DownloadLatestBinary is accessible.
 var _ = engram.DownloadLatestBinary

internal/components/gga/config_test.go

@@ -3,6 +3,7 @@ package gga
 import (
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -119,6 +120,10 @@ func TestBuildConfigDifferentProviders(t *testing.T) {
 func TestInjectWritesConfigAndAgents(t *testing.T) {
 	home := t.TempDir()
 
+	if runtime.GOOS == "windows" {
+		t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+	}
+
 	result, err := Inject(home, []model.AgentID{model.AgentClaudeCode})
 	if err != nil {
 		t.Fatalf("Inject() error = %v", err)
@@ -163,6 +168,10 @@ func TestInjectWritesConfigAndAgents(t *testing.T) {
 func TestInjectIsIdempotent(t *testing.T) {
 	home := t.TempDir()
 
+	if runtime.GOOS == "windows" {
+		t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+	}
+
 	first, err := Inject(home, []model.AgentID{model.AgentOpenCode})
 	if err != nil {
 		t.Fatalf("Inject() first error = %v", err)

internal/components/gga/install_test.go

@@ -99,6 +99,15 @@ func TestInstallCommandByProfile(t *testing.T) {
 				{"bash", "/tmp/gentleman-guardian-angel/install.sh"},
 			},
 		},
+		{
+			name:    "nixos uses git clone and install.sh",
+			profile: system.PlatformProfile{OS: "linux", LinuxDistro: system.LinuxDistroNixOS, PackageManager: "nix"},
+			want: [][]string{
+				{"rm", "-rf", "/tmp/gentleman-guardian-angel"},
+				{"git", "clone", "https://github.com/Gentleman-Programming/gentleman-guardian-angel.git", "/tmp/gentleman-guardian-angel"},
+				{"bash", "/tmp/gentleman-guardian-angel/install.sh"},
+			},
+		},
 		{
 			name: "unsupported package manager returns error",
 			profile: system.PlatformProfile{

internal/installcmd/resolver.go

@@ -260,7 +260,7 @@ func resolveGGAInstall(profile system.PlatformProfile) (CommandSequence, error)
 			{"brew", "tap", "Gentleman-Programming/homebrew-tap"},
 			{"brew", "reinstall", "gga"},
 		}, nil
-	case "apt", "pacman", "dnf":
+	case "apt", "pacman", "dnf", "nix":
 		const tmpDir = "/tmp/gentleman-guardian-angel"
 		return CommandSequence{
 			{"rm", "-rf", tmpDir},
@@ -402,6 +402,12 @@ func resolveEngramInstall(profile system.PlatformProfile) (CommandSequence, erro
 			{"brew", "tap", "Gentleman-Programming/homebrew-tap"},
 			{"brew", "install", "engram"},
 		}, nil
+	case "nix":
+		// NixOS requires installing from source via go install because pre-built release
+		// binaries fail to run natively due to hardcoded dynamic linker paths.
+		return CommandSequence{
+			{"go", "install", "github.com/Gentleman-Programming/engram/cmd/engram@latest"},
+		}, nil
 	default:
 		return nil, fmt.Errorf(
 			"engram on %q/%q uses direct binary download — use engram.DownloadLatestBinary() instead of CommandSequence",

internal/installcmd/resolver_test.go

@@ -611,6 +611,12 @@ func TestResolveComponentInstall(t *testing.T) {
 			component: model.ComponentEngram,
 			wantErr:   true,
 		},
+		{
+			name:      "engram on nixos uses go install",
+			profile:   system.PlatformProfile{OS: "linux", LinuxDistro: system.LinuxDistroNixOS, PackageManager: "nix"},
+			component: model.ComponentEngram,
+			want:      CommandSequence{{"go", "install", "github.com/Gentleman-Programming/engram/cmd/engram@latest"}},
+		},
 		{
 			name:      "gga on darwin uses brew tap and reinstall",
 			profile:   system.PlatformProfile{OS: "darwin", PackageManager: "brew"},
@@ -647,6 +653,16 @@ func TestResolveComponentInstall(t *testing.T) {
 				{"bash", "/tmp/gentleman-guardian-angel/install.sh"},
 			},
 		},
+		{
+			name:      "gga on nixos uses git clone and install.sh",
+			profile:   system.PlatformProfile{OS: "linux", LinuxDistro: system.LinuxDistroNixOS, PackageManager: "nix"},
+			component: model.ComponentGGA,
+			want: CommandSequence{
+				{"rm", "-rf", "/tmp/gentleman-guardian-angel"},
+				{"git", "clone", "https://github.com/Gentleman-Programming/gentleman-guardian-angel.git", "/tmp/gentleman-guardian-angel"},
+				{"bash", "/tmp/gentleman-guardian-angel/install.sh"},
+			},
+		},
 		{
 			name:      "engram on windows returns error (uses DownloadLatestBinary instead)",
 			profile:   system.PlatformProfile{OS: "windows", PackageManager: "winget"},

internal/system/detect.go

@@ -31,6 +31,7 @@ const (
 	LinuxDistroDebian  = "debian"
 	LinuxDistroArch    = "arch"
 	LinuxDistroFedora  = "fedora"
+	LinuxDistroNixOS   = "nixos"
 )
 
 type DetectionResult struct {
@@ -50,7 +51,7 @@ func Detect(ctx context.Context) (DetectionResult, error) {
 		return DetectionResult{}, err
 	}
 
-	tools := DetectTools(ctx, []string{"git", "curl", "brew", "node", "go"})
+	tools := DetectTools(ctx, []string{"git", "curl", "brew", "node", "go", "nix"})
 	configs := ScanConfigs(homeDir)
 	osReleaseContent, _ := osReleaseContent(runtime.GOOS)
 
@@ -131,6 +132,13 @@ func resolvePlatformProfile(goos, linuxOSRelease string, tools map[string]ToolSt
 		distro := detectLinuxDistro(linuxOSRelease)
 		profile.LinuxDistro = distro
 
+		// NixOS should always resolve to nix, even if Homebrew is also installed.
+		if distro == LinuxDistroNixOS {
+			profile.PackageManager = "nix"
+			profile.Supported = true
+			return profile
+		}
+
 		// Check if brew is available on Linux
 		if brew, ok := tools["brew"]; ok && brew.Installed {
 			profile.PackageManager = "brew"
@@ -148,9 +156,17 @@ func resolvePlatformProfile(goos, linuxOSRelease string, tools map[string]ToolSt
 		case LinuxDistroFedora:
 			profile.PackageManager = "dnf"
 			profile.Supported = true
+		case LinuxDistroNixOS:
+			profile.PackageManager = "nix"
+			profile.Supported = true
 		default:
-			profile.PackageManager = ""
-			profile.Supported = false
+			if nix, ok := tools["nix"]; ok && nix.Installed {
+				profile.PackageManager = "nix"
+				profile.Supported = true
+			} else {
+				profile.PackageManager = ""
+				profile.Supported = false
+			}
 		}
 
 		return profile
@@ -204,6 +220,10 @@ func detectLinuxDistro(linuxOSRelease string) string {
 		return LinuxDistroFedora
 	}
 
+	if isNixOSLike(id, idLike) {
+		return LinuxDistroNixOS
+	}
+
 	return LinuxDistroUnknown
 }
 
@@ -248,3 +268,17 @@ func isFedoraLike(id, idLike string) bool {
 
 	return false
 }
+
+func isNixOSLike(id, idLike string) bool {
+	if id == LinuxDistroNixOS {
+		return true
+	}
+
+	for _, token := range strings.Fields(idLike) {
+		if token == LinuxDistroNixOS {
+			return true
+		}
+	}
+
+	return false
+}

internal/system/detect_test.go

@@ -90,6 +90,81 @@ func TestDetectFromInputsMarksArchSupported(t *testing.T) {
 	}
 }
 
+func TestDetectFromInputsMarksNixOSSupported(t *testing.T) {
+	osRelease := "ID=nixos\n"
+	result := detectFromInputs("linux", "amd64", "/bin/bash", osRelease, nil, nil)
+
+	if !result.System.Supported {
+		t.Fatalf("expected nixos linux to be supported")
+	}
+
+	if result.System.Profile.LinuxDistro != LinuxDistroNixOS {
+		t.Fatalf("expected nixos distro, got %q", result.System.Profile.LinuxDistro)
+	}
+
+	if result.System.Profile.PackageManager != "nix" {
+		t.Fatalf("expected nix package manager, got %q", result.System.Profile.PackageManager)
+	}
+}
+
+func TestDetectFromInputsMarksNixOSLikeSupported(t *testing.T) {
+	osRelease := "ID=custom-distro\nID_LIKE=nixos\n"
+	result := detectFromInputs("linux", "amd64", "/bin/bash", osRelease, nil, nil)
+
+	if !result.System.Supported {
+		t.Fatalf("expected nixos-like linux to be supported")
+	}
+
+	if result.System.Profile.LinuxDistro != LinuxDistroNixOS {
+		t.Fatalf("expected nixos distro for ID_LIKE=nixos, got %q", result.System.Profile.LinuxDistro)
+	}
+}
+
+func TestDetectFromInputsPrefersBrewOverNixOnUbuntu(t *testing.T) {
+	tools := map[string]ToolStatus{
+		"nix":  {Name: "nix", Installed: true, Path: "/nix/var/nix/profiles/default/bin/nix"},
+		"brew": {Name: "brew", Installed: true, Path: "/home/linuxbrew/.linuxbrew/bin/brew"},
+	}
+	result := detectFromInputs("linux", "amd64", "/bin/bash", "ID=ubuntu\n", tools, nil)
+
+	if result.System.Profile.PackageManager != "brew" {
+		t.Fatalf("expected brew package manager when both nix and brew installed on Ubuntu, got %q", result.System.Profile.PackageManager)
+	}
+}
+
+func TestDetectFromInputsPrefersAptOverNixOnUbuntu(t *testing.T) {
+	tools := map[string]ToolStatus{
+		"nix": {Name: "nix", Installed: true, Path: "/nix/var/nix/profiles/default/bin/nix"},
+	}
+	result := detectFromInputs("linux", "amd64", "/bin/bash", "ID=ubuntu\n", tools, nil)
+
+	if result.System.Profile.PackageManager != "apt" {
+		t.Fatalf("expected apt package manager when only nix is installed on Ubuntu, got %q", result.System.Profile.PackageManager)
+	}
+}
+
+func TestDetectFromInputsFallsBackToNixOnUnsupportedLinux(t *testing.T) {
+	tools := map[string]ToolStatus{
+		"nix": {Name: "nix", Installed: true, Path: "/nix/var/nix/profiles/default/bin/nix"},
+	}
+	result := detectFromInputs("linux", "amd64", "/bin/bash", "ID=alpine\n", tools, nil)
+
+	if result.System.Profile.PackageManager != "nix" {
+		t.Fatalf("expected nix package manager fallback on unsupported Linux with nix installed, got %q", result.System.Profile.PackageManager)
+	}
+}
+
+func TestDetectFromInputsNixOSPrefersNixOverBrew(t *testing.T) {
+	tools := map[string]ToolStatus{
+		"brew": {Name: "brew", Installed: true, Path: "/home/linuxbrew/.linuxbrew/bin/brew"},
+	}
+	result := detectFromInputs("linux", "amd64", "/bin/bash", "ID=nixos\n", tools, nil)
+
+	if result.System.Profile.PackageManager != "nix" {
+		t.Fatalf("expected nix package manager for NixOS even when brew is installed, got %q", result.System.Profile.PackageManager)
+	}
+}
+
 // --- Batch E: Comprehensive platform detection matrix ---
 
 func TestDetectLinuxDistroMatrix(t *testing.T) {
@@ -98,6 +173,11 @@ func TestDetectLinuxDistroMatrix(t *testing.T) {
 		osRelease  string
 		wantDistro string
 	}{
+		{
+			name:       "nixos",
+			osRelease:  "ID=nixos\n",
+			wantDistro: LinuxDistroNixOS,
+		},
 		{
 			name:       "ubuntu 22.04",
 			osRelease:  "ID=ubuntu\nID_LIKE=debian\nVERSION_ID=\"22.04\"\n",