nix-configurations/README.md

# NixOS configurations

One flake manages three x86_64 machines. NixOS uses stable `nixos-26.05`;
`nixos-unstable` supplies only packages the older configs already selected
from unstable. `nixos-hardware` provides the Framework 11th-gen Intel profile.
All inputs are pinned in `flake.lock`.

| Flake host | Network hostname | Hardware |
| --- | --- | --- |
| `t450s` | `samwise` | ThinkPad T450s, original encrypted ext4 layout |
| `x1eg2` | `bilbo` | ThinkPad X1 Extreme Gen 2, original ZFS/NVIDIA layout |
| `framework` | `framework` | Framework 13, Intel i5-1135G7; generated hardware file required |

## Organization

Each `hosts/<host>/configuration.nix` explicitly imports its own generated
`hardware-configuration.nix` and selected shared modules:

- `common.nix`: flakes, store maintenance, locale, NetworkManager, user `clw`, zsh.
- `kde.nix`: Plasma 6, SDDM, US keyboard, PipeWire, Bluetooth, printing, Flatpak.
- `development.nix`: Emacs, VS Code, htop, general CLI/DevOps tools, Docker,
  direnv and nix-direnv on every host.
- `desktop-apps.nix`: selected shared desktop applications on every host.
- `gaming.nix`: shared Steam setup on all three hosts. The ThinkPads' different
  games, Wine variants and X1EG2 GameMode customization stay at host level.

Storage, encryption, NVIDIA/PRIME, undervolting, backup datasets, virtualization,
SSH server and firewall policy live in the host configurations. There is no
shared laptop module because the older configurations did not have common
laptop tuning. Framework enables power-profiles-daemon and touchpad support
locally, and uses the upstream Framework 11th-gen Intel hardware profile. Its
generated hardware file supplies the actual disk UUIDs and detected devices.

## Rebuild

From this checkout on the relevant machine:

```sh
sudo nixos-rebuild build --flake .#t450s
sudo nixos-rebuild switch --flake .#t450s
# Or use .#x1eg2 / .#framework
```

Flake names are independent of network hostnames. New files must be tracked
with `git add` for Git-backed flakes to include them. Review the release upgrade
before switching: the old machines were configured for Plasma 5, whereas the
current release uses Plasma 6. Keep the original `system.stateVersion` values
(`23.05` and `23.11`); changing inputs does not require changing stateVersion.

The ThinkPads retain their disabled firewall. Only T450s enables the SSH server;
Framework keeps the firewall enabled, with the gaming module's Steam port
exceptions, and does not enable the SSH server.
T450s still requires `/crypto_keyfile.bin` on that machine for its initrd. Never
put that key in this repository. Its existing ZFS support is also preserved even
though the generated root filesystem is ext4.

## Install Framework

Framework uses a GPT layout with a FAT32 EFI partition at `/boot`, ext4 at `/`,
and the remaining drive space in ZFS pool `tookland`. Dataset `tookland/home`
is mounted at `/home`; other datasets can be created later.

The NixOS configuration enables ZFS, imports the existing pool, mounts home,
and schedules scrubs. It does **not** partition disks or create pools/datasets.
Follow the [Framework installation guide](hosts/framework/README.md) to create
and mount them before generating hardware configuration and running:

```sh
sudo nixos-install --flake /mnt/etc/nixos-config#framework
```

Replace the deliberate failing `hosts/framework/hardware-configuration.nix`
placeholder with the file generated by `nixos-generate-config --root /mnt`.
No disk UUIDs are copied from another machine. Keep Framework's initial
`system.stateVersion = "26.05"` after installation.

## Add a host

1. Generate its hardware configuration on that machine or mounted installation.
2. Create `hosts/<name>/configuration.nix`, import its hardware file and the
   shared modules you need, and set hostname, bootloader and initial stateVersion.
3. Add an explicit `nixpkgs.lib.nixosSystem` entry under `nixosConfigurations`
   in `flake.nix`, pointing to the new host configuration.
4. Track the files, evaluate/build, then install or rebuild with `.#<name>`.

## Development

General workstation tools belong here. Each project should provide its own
`devShell`, container, or equivalent for languages, SDKs and dependencies:

```sh
nix develop
# For a project using direnv, review .envrc then:
direnv allow
```

An `.envrc` containing `use flake` integrates a project's devShell with direnv.
No existing development projects were changed. Docker and Compose are available
on every host, with `clw` in the Docker group. Ansible and AWS CLI are shared
DevOps tools. The module includes JSON/YAML tools (`jq`, `yq`), file/search
utilities, tmux, and network troubleshooting tools. It does not add project
language runtimes or Kubernetes/Terraform tooling. Android
Studio remains on the ThinkPads as an existing IDE/workflow choice, but its
bundled SDK is worth reviewing if moving fully to project-local tooling.

Codex CLI (`codex`) and Claude Code (`claude`) are installed on every host.
Run each command as your normal user and follow its sign-in flow.
They use official upstream binaries, with versions and SHA-256 checksums pinned
in `packages/ai-cli-versions.json`, independently of the stable NixOS release.
`packages/ai-cli.nix` packages Codex and reuses Nixpkgs' Claude Code wrapper.
Authentication stays in your home directory, outside this repo.

To update both to the latest stable upstream releases, run from this repo:

```sh
nix shell nixpkgs#python3 -c python3 scripts/update-ai-cli.py
git diff -- packages/ai-cli-versions.json
nix build .#codex .#claude-code --no-link
sudo nixos-rebuild switch --flake .#framework
codex --version
claude --version
git add packages/ai-cli-versions.json
git commit -m "chore(ai-cli): update upstream releases"
```

Use your own host name when rebuilding. The updater changes only the CLI pins;
`nix flake update` updates NixOS inputs but does not update these pins.
Updates remain explicit and reproducible; no upstream self-updaters are used.

The official ChatGPT Linux desktop preview does not formally support NixOS.
Our pinned `chatgpt` package supports macOS only, so it is not installed here.
See the [official Linux app documentation](https://learn.chatgpt.com/docs/linux/linux-app)
for supported platforms; a native NixOS package would need separate packaging.

For fast package discovery, `common.nix` installs `nix-search-cli` on every host:

```sh
nix-search --channel=26.05 blender
```

This queries the online search.nixos.org index rather than evaluating nixpkgs
locally. Results reflect the current stable channel index, which can be newer
than this repository's lock file. To search the exact pinned package set, use
`nix search --inputs-from /path/to/nixos-config nixpkgs blender` (slower).

## Migration and package review

The original repositories are left untouched. No credentials were found in the
tracked configurations or a pattern scan of their Git history. UUIDs, host IDs,
and references to local encryption keys are not the keys themselves.
Do not add passwords, Wi-Fi PSKs, private keys, tokens or API credentials to Nix
files. No secrets framework is added.

Changes required for the current release include Plasma 6 and renamed graphics,
keyboard, display-manager and package options. `programs.adb` and its old
`adbusers` group are removed: systemd now grants device access automatically,
and `android-tools` still provides ADB. Libvirt now exposes QEMU's OVMF firmware
without the removed `qemu.ovmf` settings. NVIDIA containers use the current
toolkit/CDI integration (for example, `docker run --device nvidia.com/gpu=all …`).
`ffmpeg_6` becomes current `ffmpeg`, KCalc comes from `kdePackages`, Bitwarden
becomes `bitwarden-desktop`, `du-dust` becomes `dust`, Jellyfin becomes
`jellyfin-desktop`, and Proton VPN becomes `proton-vpn`. The Adwaita, nvtop, Noto
fonts and Wine attribute names are also updated; `noto-fonts-extra` is now
covered by `noto-fonts`.

`whatsapp-for-linux` is removed because nixpkgs reports it was unmaintained
and archived upstream. No replacement is installed automatically. The obsolete insecure-package
exceptions for `mailspring-1.12.0` and `electron-24.8.6` are removed; do not restore
these old exceptions simply to force evaluation.

Removed from global packages in both old hosts: Java (`jdk`), Node 20, Flutter,
Perl and Python. Put the versions each project needs in its development shell.
Applications can still bring their own runtime dependencies.

The shared desktop app selection omits Calf, Cryptomator, Discord, gscan2pdf,
Minigalaxy, Proton VPN and Tilix. Tilix's VTE shell integration is removed too.
Brave, Signal and Rocket.Chat now use stable nixpkgs from this shared module,
instead of duplicate host entries (some previously used unstable). Emacs is
also shared across all hosts using stable nixpkgs, as is VS Code.

Review these preserved choices before your first switch:

- Android Studio, Postman and Android tools: retain only tools
  you use across projects; SDKs are better project-local.
- Mailspring, Rocket.Chat, Threema wrappers: verify which messaging
  clients you still use; availability may have changed since the old configs.
- Firefox plus Chrome plus Brave, VLC plus mpv plus Jellyfin, and
  overlapping mail clients: remove whichever you no longer use.
- Wine, Lutris and VCMI: older ThinkPad gaming choices; Framework currently
  gets Steam through the shared gaming module.
- HP/Canon printing drivers and scanner support on T450s: keep only if you still
  own the relevant devices.
- T450s ZFS support and host ID: retained despite its ext4 root; check whether
  you still attach ZFS pools.
- X1EG2's `-100` CPU undervolt, PRIME bus IDs, NVIDIA power management, root-run
  QEMU, ZFS pools and Sanoid datasets are hardware/workflow-specific and retained.
  Confirm they still describe the actual machine before activating the upgrade.

## Update inputs and check

```sh
nix flake update
# Or update one input:
nix flake update nixpkgs
nix eval --raw .#nixosConfigurations.t450s.config.system.build.toplevel.drvPath
nix eval --raw .#nixosConfigurations.x1eg2.config.system.build.toplevel.drvPath
# After replacing Framework's hardware file:
nix eval --raw .#nixosConfigurations.framework.config.system.build.toplevel.drvPath
sudo nixos-rebuild build --flake .#framework
```

Review and commit `flake.lock` after checking the hosts. `nix flake check` will
fail on the intentional Framework placeholder until its hardware file is supplied.

Validation uses a temporary Nix Docker container because Nix is not installed
on this workstation. Both ThinkPads evaluate to complete system derivations;
Framework is evaluated with an external test-only ext4/EFI hardware fixture.
The checked-in placeholder remains an intentional evaluation failure until the
installer-generated hardware file is supplied. Full system builds, activation,
and physical disk operations are not performed here.