Cut restated "what", domain-glossary framing, cross-file consumption
narration, and against-alternative justification from in-file comments;
keep only non-obvious "why" and load-bearing pointers. Drop the
`generateCompletions` line (a no-op restatement of the upstream default)
and its comment.
Add docs/install.md, the operator runbook that turns the completed
neogaia Host into a running encrypted laptop from the NixOS live ISO:
push the flake to its remote, join wifi, clone the repo locally,
disko-install against neogaia with the chaotic substituter handed to the
install-time daemon, set the bootstrap login password by hand via
nixos-enter, and reboot.
Bring the declarative half of ~/.claude into modules/claude-code and apply
it when the Module is enabled: the global agent instructions (context =
./CLAUDE.md), the skills tree (skills = ./skills), the attention-bell hook,
and settings.json (model = opus plus the Stop/Notification/SessionStart
hook wiring).
Runtime state (projects, plugins, cache, history, sessions) and the
.credentials.json secret are left out, so login survives rebuilds and no
secret enters the repo. Verified against the built home-files that
~/.claude/{CLAUDE.md,settings.json,skills,hooks/attention-bell.sh} are
generated, the hook executable.
Install Claude Code through home-manager's native programs.claude-code
module, matching how the tmux and fish Modules use their home-manager
options rather than a raw home.packages entry. The feature Module at
modules/claude-code/claude-code.nix stays thin — just the enable option
and the delegation — and writes no settings, so login and first-run
configuration remain interactive and no auth material enters the repo.
Signing in without a browser (needed over the console or SSH) is
documented in modules/claude-code/authentication.md: the paste-code OAuth
flow, where the printed URL is opened on another device and the code
pasted back, and the ANTHROPIC_API_KEY path for non-interactive use.
The neogaia toplevel builds with claude-code-2.1.209 included.
Add an nvim Module that configures Neovim declaratively through nixvim,
wired as a flake input and consumed as its home-manager module. Options,
globals, keymaps, and plugin settings are typed Nix; the colorscheme
call and two autocmds live in modules/nvim/config.lua via extraConfigLua.
Plugins come from nixpkgs (no plugin manager, no runtime cloning); git,
ripgrep, and fd are provided from Nix; treesitter grammars are built by
Nix so no runtime compiler is needed.
Functionally matches the previous config (plugins, keymaps, options, the
nord colorscheme, markdown conceal, the Neogit blame toggle), verified
headless against the generated init.
reference/ is a read-only snapshot of the pre-migration machine, kept
locally for porting configs but not part of the flake. Stop tracking it
and ignore it so migrations don't churn the repo.
Configure tmux through home-manager's programs.tmux: the settings it exposes
as options (prefix, keyMode, mouse, baseIndex, clock24, escapeTime,
historyLimit, terminal) are set as options, and every setting it has no option
for is read verbatim from modules/tmux/extra.conf. No tmux plugin manager is
used. The generated config is behaviourally identical to the reference, verified
by parsing it with a live tmux binary.
The interactive init is small; four fragment files was over-splitting it.
Keep the mechanic (a real fish file inlined by Nix into config.fish) but
merge the fragments into a single modules/fish/config.fish read with
builtins.readFile. Rendered config is unchanged.
Break the interactive init into concern-scoped fish files under
modules/fish/config/ (bindings, env, done, path) and assemble them with
lib.concatMapStringsSep + readFile into a single interactiveShellInit, so
home-manager still writes one ~/.config/fish/config.fish. The pieces stay
editable as separate fish files; the rendered file is unchanged.
Fold the done plugin tuning back into config.fish and drop the conf.d
fragment: config.fish is read whole into interactiveShellInit, so Nix
assembles the interactive init at build time instead of fish autoloading
a separate conf.d file. functions/copy.fish stays a function file, the
idiomatic home for a lazily-autoloaded function.
Move the Module to modules/fish/fish.nix and mirror a real fish config
directory beside it: config.fish (interactive init), conf.d/done.fish
(the done plugin tuning, now a real conf.d file), and functions/copy.fish.
completions/ and themes/ are omitted as they have no content and git
cannot track empty directories.
Move the interactiveShellInit block and the copy function body into
modules/fish/*.fish and pull them in with builtins.readFile, so the
non-trivial fish lives in real fish files (highlighting, fish_indent)
instead of inline Nix strings. The Auto-loader only collects .nix, so
the new .fish files are ignored by it. Rendered config is unchanged.
Move the login-shell switch behind a new modules.fish.defaultShell
option (default false; neogaia opts in). Convert every non-eza alias to
an abbreviation, set preferAbbrs and pin generateCompletions, and switch
the command line to vi-style editing. Cap navigation at four dots and
drop psmem/psmem10/dir/vdir/please. Comment the installed packages.
Translate the CachyOS fish snapshot into a home-manager Module: the
fastfetch greeting, the bat-backed manpager, the done and bang-bang
plugins (from nixpkgs, not a plugin manager), the history/backup/copy
helper functions, and the eza and navigation aliases. Pacman-specific
aliases are dropped or replaced with NixOS equivalents (update ->
nixos-rebuild switch, cleanup -> nix-collect-garbage). Enabling the
Module also makes fish the user's default login shell.
Turn the booted laptop into a usable, remotely reachable console: enable
NetworkManager so wifi can be joined from the console and an SSH daemon so
the rest of the setup can be driven over the network. Set the base locale to
timezone America/New_York, locale en_GB.UTF-8, and console keymap us.
These live inline in the neogaia Host rather than behind enable Modules,
matching the single-Host MVI precedent; a shared locale/networking Module can
be extracted once a second Host needs the same settings. SSH keeps default
password auth on, as first-boot access relies on the hand-set bootstrap
password until key/sops-based auth lands post-install.
modules/zram.nix only wrapped the native zramSwap.enable toggle without
adding anything. Rewrite the touched comments to describe only the current
file content, and record the in-file-comment convention in CLAUDE.md.
Select the CachyOS kernel per-Host via boot.kernelPackages, enable Intel
microcode and redistributable firmware (ath10k for the QCA6174 wifi), and
move zram behind a toggle Module. Declare the chaotic binary cache in the
base Nix settings (extra-substituters/keys) so the built system fetches the
kernel from nyx-cache rather than compiling it.
Add disko as a flake input (following nixpkgs) and wire its NixOS module
into the host-builder, so any Host can declare a disk layout while the
layout itself stays a per-Host concern.
neogaia's layout (hosts/neogaia/disk.nix): one GPT NVMe disk with a
systemd-boot EFI system partition and a LUKS container holding btrfs with
@root/@home/@nix subvolumes. The initrd prompts for the passphrase on a
normal boot. Swap is RAM-backed zram, so there is no on-disk swap
partition; zramSwap is enabled directly for now. The placeholder
fileSystems are removed since disko now derives them.
In-file comments should describe only what the file currently is, not task
numbers, external tooling, or past/future states.
- hosts/neogaia: drop the "replaced by disko" / "arrive later" framing;
describe the filesystems and hardware profile as the placeholder values
they are.
- lib: drop the "no null-placeholder traversal hack" comparison to a prior
implementation.
- system: drop "no impure environment lookup" from the user.name description
and the sops/post-boot roadmap from the user comment.
26.05 is the latest stable NixOS release as of now (26.11 is still the
in-development branch that nixos-unstable reports); the previous 25.05 pin
was a release behind.
- flake.nix / flake.lock: stable overlay tracks nixos-26.05.
- neogaia system.stateVersion and the base home.stateVersion set to 26.05
(fresh install, so aligning to the current stable release).
- Refresh the "latest stable release" references in the project docs to
match.
Other inputs are rolling branches (nixos-unstable, nixpkgs-unstable,
chaotic nyxpkgs-unstable) or master (home-manager, per spec), so they carry
no version to bump.
Stand up the walking skeleton the rest of the laptop MVI extends and
re-verifies against: the whole neogaia Host evaluates and its system
toplevel builds (nix flake check green).
- flake.nix: hand-rolled flake (no flake-parts). Base nixos-unstable, plus
nixpkgs-unstable and nixos-25.05 for the per-package unstable/stable
overlays, home-manager (nixpkgs followed), and chaotic-nyx (deliberately
not following our nixpkgs, to keep its binary cache usable). checks build
each Host toplevel.
- lib/: trimmed helper lib — the Auto-loader (recursive .nix discovery, no
null-placeholder hack), the host-builder, and the script-from-file helper.
Deps inherited explicitly; no with lib.my, no nixosModules output.
- system/: shared base config — the unstable/stable overlays, the user
option (defaults to alexion, in wheel, drives system + home-manager user
in lockstep), flakes, git, and home-manager as a NixOS module.
- modules/example.nix: Auto-loader / Enable-convention reference Module,
inert until enabled.
- hosts/neogaia/: minimal laptop Host — placeholder filesystems, bootloader,
and hardware profile.
- CLAUDE.md: project agent instructions with a Gotchas section (nix on the
CachyOS dev host, the chaotic overlay/cache behaviour, the forge CLI).
Capture the design work for the NixOS migration before any implementation:
- .claude/CONTEXT.md: domain glossary (Host, Module, Skeleton, Auto-loader,
Enable convention, unstable/stable overlay)
- .claude/adr/0001-sops-nix-for-secrets.md: secrets tooling decision
- .claude/spec/laptop-mvi.md: frozen minimum-viable-install spec for neogaia
- reference/: read-only snapshot of the current CachyOS configs (secrets and
state excluded), plus ENVIRONMENT.md profiling the live environment to guide
replication
Add a PreToolUse hook that reminds the main agent not to author test
files directly, and change the implement skill to always use
test-driven-development rather than only where possible.
implement: sync main and cut task-<NNNN>-<slug> before work, with
stop-and-ask guards for a dirty tree, a diverged main, and an unmerged
blocker. Replaces the no-commit rule with one commit, a push, and a PR
carrying the review's Risk block plus any unaddressed findings.
test-driven-development: every test is written by a general-purpose
sub-agent that never reads the implementation; the main agent writes the
code and never edits a test.
Wire Stop and Notification hooks in ~/.claude/settings.json to a new
~/.claude/hooks/attention-bell.sh, which rings the terminal bell in the
session pane so tmux monitor-bell flags the background window.
The hook runs detached (no controlling tty), so it walks its process
ancestry to the claude process and writes the BEL to that pane tty.
Also replaces the dead settings.json symlink (pointed at a now-missing
~/wrk/claude path) with a real tracked file.
Adds a dot setup subcommand family (idempotent, re-runnable machine-setup
tasks) with a folders task that brings the 8 standard XDG user
directories under a fixed short-name convention (Desktop -> .desktop,
Documents -> doc, Downloads -> dwn, Music -> mus, Pictures -> pic,
Videos -> vid, Templates/Public -> .ignoreme), hardcoded rather than read
from ~/.config/user-dirs.dirs -- that file is a separate, manually
tracked dotfile whose values can drift or go stale, and the migration
must not depend on it being correct. The nested Pictures/Screenshots
folder is renamed to pic/screenshots in the same pass.
Content left behind in a legacy full-named folder by a fresh XDG-defaults
install -- empty or not -- is merged into its short-named replacement.
A same-named collision between a legacy folder and its target is never
overwritten: it is skipped, reported, and the legacy folder is left in
place rather than deleted while something in it could not be merged.
--dry-run previews what would move/skip without touching the filesystem.
xdg-user-dirs-update runs once afterward to notify running apps/portals.
dot kde save's tab-completion only ever enumerated schema-backed
identifiers; kglobalshortcutsrc identifiers never showed up as
candidates despite being a fully supported mechanism. Enumerate them
live via kglobalaccel (allMainComponents/allActionsForComponent),
printed as a separate block after the schema-backed one, degrading
silently if the D-Bus session is unavailable.
