chore: Claude/agent guidance and workspace files

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

INTEGRATION_NOTES.md

@@ -0,0 +1,130 @@
+# nixos-dev-setup integration notes
+
+Status: wired in, evaluates cleanly, ready to build once a pre-existing
+unrelated bug is fixed.
+
+## What was integrated
+
+From `~/Work/tries/2026-04-06-nixos-dev-setup` (tagged `v0.1.0`):
+
+- `lib/mksystem.nix` — uniform host constructor
+- `lib/overlays.nix` — nixpkgs-unstable pinning for fast-moving pkgs
+- `modules/cache.nix` — substituters + trusted-public-keys
+- `modules/dev-env/` — full dev environment module (options, config,
+  lib, bash helpers, aiolabs preset, git hooks, runbooks)
+- `Makefile` — `switch`/`test`/`build`/`cache`/`check`/`clean`/`fmt`
+- `hosts/omni/default.nix` — host-specific dev-env settings
+- `users/user/home-manager.nix` — shim forwarder for home.nix
+
+## What changed in existing omni files
+
+- `flake.nix`
+  - Added `nixpkgs-unstable` and `deploy-flake` inputs.
+  - Outputs rewritten to use `mkSystem` for the `omni` host.
+  - `omni-iso` left as a direct `nixosSystem` call (variant, not host).
+  - Overlays (lib/overlays.nix + nur + neovim-nightly) now applied to
+    nixosConfigurations as well as devShells/packages/apps.
+
+- Nothing else was edited in place. `configuration.nix` and `home.nix`
+  are still at the top level, reached via shim files in `hosts/omni/`
+  and `users/user/`.
+
+## Integration commit sequence
+
+```
+2f875a9 enable dev-env + aiolabs preset; fix options.nix interpolation escapes (phase E)
+81ecc6c wire flake.nix outputs through mkSystem (phase D)
+103fe0e extend mksystem with extraHmArgs for host-specific HM extras
+dc9d70b add mksystem shims for hosts/ and users/ (phase C)
+2fe2ba0 add nixpkgs-unstable + deploy-flake inputs (phase B)
+c9b7db5 import nixos-dev-setup module (phase A: additive copy)
+f18d2c0 fix: VM boot support and documentation update  ← pre-dev-env-integration tag
+```
+
+Rollback: `git reset --hard pre-dev-env-integration`
+
+## Verification
+
+Last successful eval sequence on current master:
+
+```bash
+# Top-level host name — verifies module tree assembles
+nix eval .#nixosConfigurations.omni.config.system.name
+  # → "omni"
+
+# Project list from aiolabs preset — verifies dev-env schema loads
+nix eval --json \
+  .#nixosConfigurations.omni.config.dev-env.projects \
+  --apply 'builtins.attrNames'
+  # → 18 projects incl. lightning-pub, lnbits, webapp, etc.
+
+# Nested worktree paths — verifies submodule wiring
+nix eval --json \
+  .#nixosConfigurations.omni.config.dev-env.projects.lightning-pub.worktrees
+  # → 7 worktree entries with computed path/branch/remote
+
+# Runtime config file rendering — verifies config.nix
+nix build --no-link --print-out-paths \
+  '.#nixosConfigurations.omni.config.environment.etc."dev-env/config.sh".source'
+  # → /nix/store/.../dev-env-config.sh with DEV_ROOT, FORGEJO_*, etc.
+
+# Project manifest rendering — verifies dev-env-bootstrap input
+nix build --no-link --print-out-paths \
+  '.#nixosConfigurations.omni.config.environment.etc."dev-env/projects.json".source'
+  # → /nix/store/.../dev-env-projects.json — full project tree with
+  #   bare paths, remotes, and worktree paths resolved
+```
+
+All the above work end-to-end. The dev-env pipeline (options → config
+rendering → runtime files) is validated.
+
+## Known pre-existing issue: blocks final build
+
+`modules/desktop/hyprland.nix:112` references `thunar` as an unqualified
+package name inside a `with pkgs;` scope. `thunar` is not a top-level
+attribute — it lives at `pkgs.xfce.thunar` — so evaluation of
+`config.system.build.toplevel` fails with:
+
+    error: undefined variable 'thunar'
+
+This bug exists at the `pre-dev-env-integration` tag too. It is
+**not caused by this integration**. Verified by:
+
+```bash
+git stash -u
+git checkout pre-dev-env-integration -- .
+nix eval .#nixosConfigurations.omni.config.system.build.toplevel.drvPath
+  # → same 'undefined variable thunar' error
+git checkout master -- .
+git stash pop
+```
+
+To move past it, fix that line (change `thunar` to `xfce.thunar` or
+remove it if unused). That is out of scope for the dev-env integration.
+
+## After the thunar fix
+
+Once the pre-existing issue is resolved, run:
+
+```bash
+make test HOST=omni      # nixos-rebuild test, no boot entry change
+make switch HOST=omni    # actual switch
+dev-env-bootstrap --dry-run
+dev-env-bootstrap
+lb dev                     # navigate to ~/user/dev/lnbits/dev (won't exist until bootstrap runs)
+```
+
+## Open follow-ups (not blocking)
+
+- [ ] Fix `thunar` → `xfce.thunar` in `modules/desktop/hyprland.nix`
+- [ ] Rename `users/user/` → `users/<real-username>/` once `settings.user`
+      is set to something other than `"user"`
+- [ ] Inline the shim content (move `configuration.nix` body into
+      `hosts/omni/default.nix`, `home.nix` body into
+      `users/<user>/home-manager.nix`) — cosmetic cleanup
+- [ ] Push `optimize-deploys/unified` to forgejo so `deploy-flake.url`
+      can move from `git+file://` to `git+ssh://forgejo@.../deploy-unified`
+- [ ] Set up the `aiolabs-nix` cachix cache and uncomment the
+      substituter + trusted-public-key lines in `modules/cache.nix`
+- [ ] Add a smoke-test flake to the staging repo so options.nix
+      interpolation bugs (or similar) don't escape again