10 files changed, 207 insertions, 0 deletions
diff --git a/openspec/changes/archive/2026-09-18-add-gnome-desktop/.openspec.yaml b/openspec/changes/archive/2026-09-18-add-gnome-desktop/.openspec.yaml
new file mode 100644
index 0000000..d28e909
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-add-gnome-desktop/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-17
diff --git a/openspec/changes/archive/2026-09-18-add-gnome-desktop/design.md b/openspec/changes/archive/2026-09-18-add-gnome-desktop/design.md
new file mode 100644
index 0000000..09e2481
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-add-gnome-desktop/design.md
@@ -0,0 +1,33 @@
+## Context
+See proposal.md - Why. This extends `modules/nixos/common.nix` from `add-nix-flake-bootstrap` (already carrying flakes/gc/locale/user/ssh/firewall settings applied to every NixOS host) with a desktop environment. Confirmed via direct Q&A: GNOME applies unconditionally to every NixOS host, not as an opt-in per-host module — every NixOS machine this flake provisions is meant to be a desktop. Nix is still not installed on this development machine, so nothing here can be locally evaluated.
+## Goals / Non-Goals
+**Goals:**
+- A NixOS host built from this flake boots directly into a usable GNOME desktop: login, networking, audio, and printing all work without additional manual setup.
+- Keep the addition to the already-established `modules/nixos/common.nix` pattern — no new module file needed, since this applies universally like the rest of that file's contents.
+**Non-Goals:**
+- Per-user GNOME customization (dconf settings, GNOME Shell extensions via home-manager) — a system-level toggle only.
+- Any change to the user's `~/dotfiles` `herbstluftwm`/`xorg` packages or the dotfiles-stow automation (`add-dotfiles-stow-bootstrap`) — unrelated; that repo's tiling-WM configuration is untouched.
+- Fully removing Xorg/XWayland from the system. GDM defaults to a Wayland GNOME session already; XWayland (X11-app compatibility) and an optional Xorg fallback session remain present as standard NixOS/GNOME infrastructure — not something this change attempts to strip out.
+## Decisions
+**Added directly to `modules/nixos/common.nix`, not a separate opt-in module.** Per the user's explicit choice, GNOME applies to every NixOS host unconditionally — the same scope as everything else already in that file (flakes, ssh, firewall, gc policy). A separate `modules/nixos/desktop-gnome.nix` that hosts import individually was considered and rejected specifically because the user wants it universal, not per-host.
+**NetworkManager, PipeWire, and printing/Avahi are included as necessary companions, not scope creep.** A GNOME desktop without working networking, audio, or discoverable printers would only be partially functional:
+- `networking.networkmanager.enable = true` — GNOME's Settings → Network and the top-bar network menu are built against NetworkManager; without it they don't work.
+- `services.pipewire.enable` + `pulse.enable`, plus `security.rtkit.enable` — the current standard NixOS audio stack GNOME expects, including PulseAudio-compatible clients.
+- `services.printing.enable` (CUPS) + `services.avahi` (`nssmdns4`, `openFirewall`) — printing was explicitly requested; Avahi is included alongside it so network/AirPrint-style printers are actually discoverable rather than requiring manual IP-based setup. `openFirewall = true` specifically because `add-developer-environment` already enabled `networking.firewall` with only port 22 allowed — without this, printer discovery (mDNS) traffic would be silently blocked by that firewall.
+**Module option paths used reflect NixOS's current (post-migration) namespace, flagged as an implementation-time risk.** NixOS has been moving `services.xserver.displayManager.*` / `services.xserver.desktopManager.*` into standalone `services.displayManager.*` / `services.desktopManager.*`. The design uses the newer paths as pinned to `nixos-unstable`, consistent with this repo's existing pattern of flagging package/option-naming uncertainty explicitly (`yq-go` vs `yq`, `terraform`'s licensing) rather than asserting confidently what can't be verified locally. If evaluation fails once Nix is available, the fallback is the older nested paths under `services.xserver.*`.
+**Wayland is the default GNOME session; this isn't a special decision requiring extra configuration.** Confirmed directly with the user: current NixOS GDM + GNOME already defaults to a Wayland session without any extra option needed — `services.xserver.enable = true` remains required only as the underlying toggle that XWayland and the display/desktop manager modules currently build on, not as a signal that the login session itself will be Xorg-based.
+## Risks / Trade-offs
+- **Cannot verify the exact module option paths or that GNOME actually boots successfully, since Nix isn't installed and no live NixOS host exists** → Mitigation: same as every prior change in this repo — careful manual construction and review now, `nix flake check` and an actual boot test deferred until Nix/a real host are available. This remains the real acceptance gate, not any individual task checkbox.
+- **Every future NixOS host from this flake gets a full desktop stack, including any headless/server host** → Mitigation: this was an explicit, confirmed user choice (not a default I assumed) — if a headless host is ever needed, that's a follow-up change to reintroduce host-level opt-out, not a gap in this change.
+- **Firewall now allows mDNS/printer-discovery traffic (`openFirewall = true` on Avahi) in addition to SSH** → Mitigation: scoped to what Avahi's own module opens (mDNS/printer discovery ports), not a blanket firewall disable; consistent with the existing "explicit, minimal firewall allowance" pattern from `add-developer-environment`.
diff --git a/openspec/changes/archive/2026-09-18-add-gnome-desktop/proposal.md b/openspec/changes/archive/2026-09-18-add-gnome-desktop/proposal.md
new file mode 100644
index 0000000..09a2e80
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-add-gnome-desktop/proposal.md
@@ -0,0 +1,26 @@
+## Why
+NixOS hosts built from this flake currently have no desktop environment at all — just a headless system. The user wants GNOME enabled as the default desktop on every NixOS system this flake provisions.
+## What Changes
+- `modules/nixos/common.nix` gains: `services.xserver.enable`, `services.displayManager.gdm.enable`, `services.desktopManager.gnome.enable` — GNOME with GDM as the login manager, applied unconditionally to every NixOS host (not an opt-in per-host module), confirmed via direct Q&A.
+- `networking.networkmanager.enable = true` — required for GNOME's own network settings UI to function.
+- `services.pipewire` (`enable`, `pulse.enable`) + `security.rtkit.enable` — the standard NixOS audio stack GNOME expects.
+- `services.printing.enable = true` (CUPS) + `services.avahi` (`enable`, `nssmdns4`, `openFirewall`) — printing support with network/AirPrint printer discovery, added per explicit user request; `openFirewall` so the firewall enabled in the prior `add-developer-environment` change doesn't block discovery traffic.
+- Update `README.md` to document that NixOS hosts now boot into GNOME by default, with these companions.
+## Capabilities
+### New Capabilities
+- `gnome-desktop`: NixOS hosts built from this flake boot into a working GNOME desktop (login manager, networking, audio, printing) by default.
+### Modified Capabilities
+(none — this doesn't change any requirement from `nix-flake-bootstrap`, `dotfiles-management`, or `developer-environment`; it's a new, additive system capability)
+## Impact
+- Affected code: `modules/nixos/common.nix`, `README.md`.
+- Applies to every NixOS host built from this flake going forward. There is still no live NixOS host (only `hosts/template/`), so this only takes effect once a real host is scaffolded via `scripts/bootstrap-host.sh` — same situation as every prior NixOS-side change in this repo.
+- Nix is still not installed on this development machine, so the exact module option paths (`services.displayManager.*`/`services.desktopManager.*`, which NixOS has been migrating out of the older `services.xserver.displayManager.*`/`services.xserver.desktopManager.*` nesting) can only be verified by manual review here, not by actually building — flagged explicitly as an implementation-time risk, not asserted with full confidence.
+- Out of scope: per-user GNOME customization (dconf settings, Shell extensions), and any change to the user's existing `~/dotfiles` `herbstluftwm`/`xorg` packages, which this change doesn't touch.
diff --git a/openspec/changes/archive/2026-09-18-add-gnome-desktop/specs/gnome-desktop/spec.md b/openspec/changes/archive/2026-09-18-add-gnome-desktop/specs/gnome-desktop/spec.md
new file mode 100644
index 0000000..ee932c2
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-add-gnome-desktop/specs/gnome-desktop/spec.md
@@ -0,0 +1,33 @@
+## Purpose
+Provides a working GNOME desktop environment, including login, networking, audio, and printing, on every NixOS host built from this flake.
+## ADDED Requirements
+### Requirement: GNOME is the default desktop on every NixOS host
+Every NixOS host built from this flake's shared system module SHALL boot into a GNOME desktop session via a graphical login manager, without requiring per-host opt-in.
+#### Scenario: Graphical login is available after boot
+- **WHEN** a NixOS host built from this flake's shared system module finishes booting
+- **THEN** a graphical login manager is presented, and selecting the default session starts a GNOME desktop
+### Requirement: Desktop networking is functional
+The desktop environment SHALL provide working network configuration through its own UI, not require a separate manual networking setup step.
+#### Scenario: Network settings are usable from the desktop
+- **WHEN** a user opens the desktop's network configuration UI
+- **THEN** available networks can be viewed and configured without additional manual setup outside the desktop environment
+### Requirement: Desktop audio is functional
+The desktop environment SHALL provide working audio output and input, including compatibility with applications expecting a PulseAudio-compatible audio server.
+#### Scenario: Audio applications can play sound
+- **WHEN** an application on the desktop attempts to play or capture audio
+- **THEN** the audio server is running and available to handle the request
+### Requirement: Printing is supported and printers are discoverable
+The desktop environment SHALL support printing to CUPS-compatible printers, and SHALL be able to discover network printers automatically without requiring the firewall to be manually reconfigured.
+#### Scenario: A network printer is discoverable
+- **WHEN** a network printer advertises itself on the local network
+- **THEN** it can be discovered and configured for printing without the host's firewall blocking the discovery traffic
diff --git a/openspec/changes/archive/2026-09-18-add-gnome-desktop/tasks.md b/openspec/changes/archive/2026-09-18-add-gnome-desktop/tasks.md
new file mode 100644
index 0000000..b1032ea
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-add-gnome-desktop/tasks.md
@@ -0,0 +1,23 @@
+## 1. GNOME desktop and login manager
+- [x] 1.1 In `modules/nixos/common.nix`, add `services.xserver.enable = true;` — verify by reading the file
+- [x] 1.2 Add `services.displayManager.gdm.enable = true;` and `services.desktopManager.gnome.enable = true;` — verify by reading the added block, and flag the option-path uncertainty from design.md (post-migration `services.displayManager.*`/`services.desktopManager.*` vs. older `services.xserver.displayManager.*`/`services.xserver.desktopManager.*`) as a known risk to re-check once `nix flake check` can run
+## 2. Networking and audio companions
+- [x] 2.1 Add `networking.networkmanager.enable = true;` — verify by reading the added line
+- [x] 2.2 Add `services.pipewire = { enable = true; pulse.enable = true; };` and `security.rtkit.enable = true;` — verify by reading the added block
+## 3. Printing
+- [x] 3.1 Add `services.printing.enable = true;` — verify by reading the added line
+- [x] 3.2 Add `services.avahi = { enable = true; nssmdns4 = true; openFirewall = true; };` — verify by reading the added block, and confirm `openFirewall = true` is present so mDNS/printer discovery isn't blocked by the firewall enabled in `add-developer-environment`
+## 4. Documentation
+- [x] 4.1 Update `README.md` to document that NixOS hosts from this flake now boot into GNOME (GDM login) by default, with NetworkManager, PipeWire, and CUPS+Avahi printing enabled as necessary companions — verify by reading the updated section for consistency with the actual module changes
+## 5. Validation
+- [x] 5.1 Run `nix flake check` and confirm `modules/nixos/common.nix` still evaluates without error with the new services added, resolving the option-path question from task 1.2 (ran on a machine with Nix installed — passed, confirming the post-migration `services.displayManager.*`/`services.desktopManager.*` option paths are correct)
+- [x] 5.2 Manually trace through each spec scenario in `specs/gnome-desktop/spec.md` against the implemented module, confirming each is satisfied by inspection given #5.1 cannot run locally
diff --git a/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/.openspec.yaml b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/.openspec.yaml
new file mode 100644
index 0000000..f2cbbe6
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-18
diff --git a/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/design.md b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/design.md
new file mode 100644
index 0000000..60cff21
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/design.md
@@ -0,0 +1,38 @@
+## Context
+See proposal.md - Why. `modules/home/dotfiles.nix` currently loops over every non-hidden top-level directory in the cloned external dotfiles repo and stows all of them unconditionally (lines 22-28). The only existing platform-branching precedent in this codebase is the simple `if pkgs.stdenv.isDarwin then ... else ...` in `users/tom.nix:6`. Only two real `homeConfigurations` exist today (`tom@linux`, `tom@darwin` in `flake.nix:44-53`); no NixOS hosts are defined yet (`hosts/` has only `template`). The known current package inventory in the external repo includes `iterm2` (Darwin-only), and `herbstluftwm` + `xorg` (Linux-only).
+## Goals / Non-Goals
+**Goals:**
+- Skip stowing packages that are known to be irrelevant to the current platform, using a minimal, easily-extended mechanism.
+- Preserve an escape hatch so a host can exclude additional packages without further code changes if the external repo's contents change.
+- Keep all changes scoped to `modules/home/dotfiles.nix`; no changes to the external dotfiles repo, `flake.nix`, or host definitions.
+**Non-Goals:**
+- Building a full per-host "which programs/WMs does this host use" model. The current problem is fully explained by OS (Darwin vs. Linux), so no new host-level option or metadata is introduced.
+- Handling a future NixOS host that runs a desktop environment (e.g. GNOME, per `add-gnome-desktop`) but would still be Linux and thus still match the Linux exclude branch for `herbstluftwm`/`xorg` as "relevant." No such host exists yet; if it becomes a real problem later, the `excludePackages` escape hatch this change adds already covers it per-host.
+## Decisions
+**Decision: a small built-in platform-keyed exclude list, plus an `excludePackages` override option, computed with `pkgs.stdenv.isDarwin`/`isLinux`.**
+Inside `modules/home/dotfiles.nix`, add:
+```nix
+options.home.dotfiles.excludePackages = lib.mkOption {
+  type = lib.types.listOf lib.types.str;
+  default = [ ];
+  description = "Names of dotfiles stow packages to always skip, in addition to built-in platform defaults.";
+};
+```
+and a `let`-bound list combining a small built-in default (`iterm2` when not Darwin; `herbstluftwm`, `xorg` when not Linux) with `cfg.excludePackages`. Pass the combined list into the activation script via `lib.escapeShellArgs` as a bash array, and check membership in the existing `for pkg in ...` loop before calling `stow`, skipping with a warning message (mirroring the existing stow-failure warning style at line 27) instead of silently stowing.
+Alternatives considered:
+- **Marker-file convention in the external dotfiles repo** (e.g. each stow package declares its own target platform via a `.nix-platform` file that `dotfiles.nix` reads). This would keep nix-config fully generic and free of package-name knowledge, matching the original design philosophy most closely. Rejected because the dotfiles repo lives outside this git repository and is not something this change can edit or verify; it would also require the mechanism to handle a missing/malformed marker file gracefully, adding complexity for no immediate benefit over a 3-name list.
+- **Fully generic attrs-based platform-mapping option** (e.g. `home.dotfiles.packagePlatforms = { darwin = [...]; linux = [...]; }`), configured per-host. Rejected as overengineering relative to the current need (only two platforms, three known mismatched packages); the simpler list-plus-override captures the same override capability with far less surface area.
+- **Do nothing (status quo)**: the previously accepted "harmless unused symlinks" trade-off. Rejected per the user's explicit request; this change supersedes that decision.
+## Risks / Trade-offs
+- [Reintroducing external-repo package-name knowledge into nix-config, which the original design explicitly avoided] → Mitigation: kept minimal (3 names in one `let` binding) and overridable via `excludePackages`, so it degrades gracefully if the external repo's package list changes rather than silently breaking.
+- [A future Linux host that both is Linux and doesn't want `herbstluftwm`/`xorg` (e.g. a GNOME NixOS host) would still get them stowed, since the built-in default only branches on Darwin vs. Linux, not on WM in use] → Mitigation: no such host exists yet; the `excludePackages` option already provides a per-host override once one does.
diff --git a/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/proposal.md b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/proposal.md
new file mode 100644
index 0000000..6cf7af4
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/proposal.md
@@ -0,0 +1,21 @@
+## Why
+The dotfiles activation in `modules/home/dotfiles.nix` stows every top-level package directory from the external personal dotfiles repo into `$HOME` unconditionally, with no platform filtering. In practice this means macOS-only config (`iterm2`, for iTerm2) gets stowed on the Linux home-manager target, and Linux X11-only config (`herbstluftwm`, `xorg`) gets stowed on the Darwin machine — producing dead, irrelevant symlinks. This was previously an explicitly accepted trade-off (see the archived `add-dotfiles-stow-bootstrap` change's design non-goals, reaffirmed by `add-gnome-desktop`'s out-of-scope note), but the user now wants platform-irrelevant packages skipped, so this change supersedes that earlier "accept the risk" decision.
+## What Changes
+- `modules/home/dotfiles.nix` gains a new `home.dotfiles.excludePackages` option (list of package names to skip regardless of platform), as a manual per-host escape hatch.
+- The module computes a small built-in default exclude set from the current known platform mismatches, using the same `pkgs.stdenv.isDarwin`/`isLinux` pattern already used in `users/tom.nix`: `iterm2` is skipped when not on Darwin; `herbstluftwm` and `xorg` are skipped when not on Linux.
+- The stow activation loop skips any package in the combined exclude set (built-in + `excludePackages`), printing a visible "skipped — not relevant on this platform" message instead of silently stowing it. Packages not in the exclude set continue to stow exactly as before.
+## Capabilities
+### Modified Capabilities
+- `dotfiles-management`: adds a requirement that platform-irrelevant dotfiles packages (built-in defaults or explicitly configured via `excludePackages`) are skipped during stow, rather than always stowing every top-level package directory.
+## Impact
+- **Code**: `modules/home/dotfiles.nix` (new option, exclude-set computation, activation script loop).
+- **Specs**: `openspec/specs/dotfiles-management/spec.md` gains a new requirement; existing requirements (opt-in via repo URL, no re-clone, package-to-symlink mapping, per-package fault isolation) are unaffected.
+- **Prior decisions superseded**: the "no filtering, accept harmless unused symlinks" non-goal recorded in the archived `add-dotfiles-stow-bootstrap` design and reaffirmed in `add-gnome-desktop` no longer holds; this change intentionally reverses it.
+- No changes to `flake.nix`, host definitions, or the external dotfiles repo itself.
diff --git a/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/specs/dotfiles-management/spec.md b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/specs/dotfiles-management/spec.md
new file mode 100644
index 0000000..e49bac6
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/specs/dotfiles-management/spec.md
@@ -0,0 +1,16 @@
+## ADDED Requirements
+### Requirement: Platform-irrelevant packages are skipped
+The system SHALL skip stowing a dotfiles package when that package is platform-irrelevant, either because it matches a built-in platform default (based on the current OS) or because it has been explicitly listed for exclusion, rather than always stowing every top-level package directory.
+#### Scenario: A package is excluded by built-in platform default
+- **WHEN** the dotfiles repository contains a top-level package directory that is known to be relevant only to a different platform than the one currently running (for example, a macOS-only package on a Linux system, or a Linux-only package on a macOS system)
+- **THEN** that package is not symlinked, and a visible message indicates it was skipped as not relevant on this platform
+#### Scenario: A package is excluded via explicit configuration
+- **WHEN** a package name has been explicitly configured for exclusion, regardless of the built-in platform defaults
+- **THEN** that package is not symlinked, and a visible message indicates it was skipped
+#### Scenario: A non-excluded package is still stowed
+- **WHEN** a top-level package directory is neither a built-in platform-mismatched package nor explicitly excluded
+- **THEN** that package is symlinked into the home directory as described by the existing package-symlinking requirement
diff --git a/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/tasks.md b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/tasks.md
new file mode 100644
index 0000000..f2a93d7
--- /dev/null
+++ b/openspec/changes/archive/2026-09-18-filter-dotfiles-by-platform/tasks.md
@@ -0,0 +1,13 @@
+## 1. Exclude-list option and platform defaults
+- [x] 1.1 In `modules/home/dotfiles.nix`, add the `home.dotfiles.excludePackages` option (`lib.types.listOf lib.types.str`, default `[ ]`) and verify `nix flake check` still evaluates the module without errors
+- [x] 1.2 Add a `let`-bound built-in exclude list computed from `pkgs.stdenv.isDarwin`/`isLinux` (`iterm2` excluded when not Darwin; `herbstluftwm` and `xorg` excluded when not Linux), combined with `cfg.excludePackages`, and verify by inspecting the evaluated module (e.g. `nix eval` or a scratch `home-manager build`) that the combined list contains the expected names for each platform
+## 2. Skip excluded packages during stow
+- [x] 2.1 Pass the combined exclude list into the `home.activation.dotfiles` script via `lib.escapeShellArgs` and extend the `for pkg in ...` loop (currently `modules/home/dotfiles.nix:22-28`) to skip any package name present in that list, printing a message that it was skipped as not relevant on this platform, and verify by rendering the activation script (`home-manager build --flake .#tom@darwin` or `.#tom@linux`, or `nix eval .#homeConfigurations.\"tom@darwin\".activationPackage` and inspecting the generated script) that the skip branch is present
+- [x] 2.2 Verify non-excluded packages are unaffected: confirm the rendered activation script still calls `stow` for packages outside the exclude list (e.g. `git`, `neovim`, `tmux`)
+## 3. Validation
+- [x] 3.1 Run `openspec validate filter-dotfiles-by-platform --strict` and confirm it passes