From c031fc7ae15d2a6d2c7c66bb7bfb963120249ca9 Mon Sep 17 00:00:00 2001 From: Ari Sosnovsky Date: Sun, 21 Jun 2026 00:11:14 -0400 Subject: [PATCH] current build --- GUIDELINES.md | 141 ++++++++++++++++++++++++++++++++ apps/ABOUTME.md | 15 ++++ bin/ABOUTME.md | 31 +++++++ configs/ABOUTME.md | 22 +++++ hosts/ABOUTME.md | 36 ++++++++ hosts/hl-fwdesk.nix | 2 +- modules/ABOUTME.md | 42 ++++++++++ openwrt-routers/ABOUTME.md | 33 ++++++++ pkgs/ABOUTME.md | 28 +++++++ secrets/ABOUTME.md | 34 ++++++++ system-special-links/ABOUTME.md | 18 ++++ 11 files changed, 401 insertions(+), 1 deletion(-) create mode 100644 GUIDELINES.md create mode 100644 apps/ABOUTME.md create mode 100644 bin/ABOUTME.md create mode 100644 configs/ABOUTME.md create mode 100644 hosts/ABOUTME.md create mode 100644 modules/ABOUTME.md create mode 100644 openwrt-routers/ABOUTME.md create mode 100644 pkgs/ABOUTME.md create mode 100644 secrets/ABOUTME.md create mode 100644 system-special-links/ABOUTME.md diff --git a/GUIDELINES.md b/GUIDELINES.md new file mode 100644 index 0000000..811093d --- /dev/null +++ b/GUIDELINES.md @@ -0,0 +1,141 @@ +# Agent Guidelines — nixos-setup + +Rules and best practices for any AI agent working in this repository. +Read this file before making any changes. + +--- + +## Hard Rules — Never Break These + +### ❌ NEVER run builds or system switches +Do NOT run any of the following, ever: + +``` +nixos-rebuild switch / test / build +nh os switch / test / build +skyg os switch / test / build +skyg remote switch / test / build +skyg hm switch / build +nix build +nix flake check +``` + +These commands take 20–40+ minutes, consume significant CPU/RAM, and can break a live +system. The user runs these themselves after reviewing changes. Your job is to make +correct edits to the source files — not to apply them. + +### ❌ NEVER edit `flake.lock` by hand +This file is managed exclusively by `nix flake update`. Editing it manually will corrupt +the lock file and break all builds. + +### ❌ NEVER edit `*.hardware-configuration.nix` files +These are generated by `nixos-generate-config` and reflect the physical hardware. Edits +will be overwritten on the next hardware scan and can render a system unbootable. + +### ❌ NEVER touch secrets +Do not read, write, or delete files in `secrets/`. Encrypted `.age` files must only be +managed with `agenix` via the `skyg secrets` commands. Do not modify `secrets.nix` unless +the user explicitly asks and explains the full context. + +### ❌ NEVER add `imports = [...]` to host files +Host files (`hosts/.nix`) do not use `imports`. All modules are composed through +the `makeNixOs` call in `flake.nix` via `modules/main.nix`. Adding imports to a host file +breaks the composition model. + +--- + +## Safe Operations + +These are always safe to perform without asking: + +- Reading any `.nix`, `.md`, or config file +- Editing host files (`hosts/.nix`) to add/remove packages or options +- Editing module files in `modules/` +- Creating or updating documentation in `docs/` or `ABOUTME.md` / `GUIDELINES.md` +- Adding new packages to `pkgs/` +- Editing configs in `configs/` + +--- + +## NixOS Conventions in This Repo + +### Option Namespace +All custom options live under `skyg.*`. Never introduce options under any other top-level +namespace. Check `modules/lib.nix` for the full `skyg.*` structure. + +```nix +# Correct +skyg.nixos.desktop.enable = true; +skyg.nixos.server.services.comfyui.enable = true; + +# Wrong — do not invent new top-level attrs +myOptions.desktop.enable = true; +``` + +### Enable/Disable Pattern +All modules follow `lib.mkIf cfg.enable { ... }`. Always gate config behind an `enable` +option. Default should be `false` unless the feature is universally required. + +### Host Files vs Shared Modules +- **Host-specific** (one machine only): goes in `hosts/.nix` +- **Shared** (multiple hosts): goes in the appropriate `modules/nixos/` or `modules/core/` submodule +- When in doubt, keep it in the host file and extract later if reuse emerges + +### Package Placement +- Packages needed on all desktops → `modules/nixos/desktop/packages.nix` +- Packages for one host only → `environment.systemPackages` in the host file +- Custom/third-party packages not in nixpkgs → `pkgs//default.nix` with an overlay in `modules/core/default.nix` + +### Home Manager +Home Manager config lives inside `home-manager.users.` blocks. Do not mix +system-level and HM-level options. The HM entry point is `modules/home/default.nix`. + +### Greeter +Both desktop hosts (`fwbook`, `hl-fwdesk`) use DankMaterialShell greeter via: +```nix +programs.dank-material-shell.greeter = { + enable = true; + compositor.name = "niri"; + configHome = "/home/"; +}; +``` +Do not configure `services.greetd` manually on these hosts — the DMS module handles it. + +--- + +## Navigation Tips + +| Question | Where to look | +|---|---| +| What hosts exist? | `hosts/` + `docs/hosts/README.md` | +| What does a `skyg.*` option do? | `modules/` — find the defining `.nix` file | +| What flake inputs are available? | Top of `flake.nix` | +| What binary caches are configured? | `modules/core/nix-substituters.nix` | +| What secrets exist? | `secrets.nix` (lists files + authorized keys) | +| What custom packages exist? | `pkgs/` | +| Full API reference | `docs/modules/README.md` | +| Host details (ports, services, hardware) | `docs/hosts/README.md` | + +--- + +## Validation Without Building + +After making changes you can verify syntax without running a build: + +```bash +# Check Nix expression syntax only (fast, safe) +nix-instantiate --parse .nix + +# Check the flake structure without building +nix flake show --no-build 2>/dev/null +``` + +Even these are optional — the user will validate by running `nh os switch` themselves. + +--- + +## Commit / Branch Policy + +- Do NOT commit changes or create branches unless the user explicitly asks +- Do NOT `git add`, `git commit`, or `git push` autonomously +- Describe what you changed in your final message so the user can review before committing diff --git a/apps/ABOUTME.md b/apps/ABOUTME.md new file mode 100644 index 0000000..b36abea --- /dev/null +++ b/apps/ABOUTME.md @@ -0,0 +1,15 @@ +# apps/ + +Standalone application binaries and AppImages that are not managed through Nix packages. + +## Contents + +| File | Description | +|---|---| +| `tabby-1.0.205-linux-arm64.AppImage` | Tabby AI coding assistant — ARM64 AppImage for manual deployment | + +## Notes + +- Files here are **not** referenced by the flake directly +- AppImages in this folder are deployed or run manually as needed +- Do not add packages here that can be expressed as proper Nix derivations — use `pkgs/` instead diff --git a/bin/ABOUTME.md b/bin/ABOUTME.md new file mode 100644 index 0000000..a77b061 --- /dev/null +++ b/bin/ABOUTME.md @@ -0,0 +1,31 @@ +# bin/ + +The `skyg` CLI — the single entry point for all system management tasks in this repo. + +## Structure + +``` +bin/ +├── skyg # Bash shim: exec nu --commands "use lib/cmds.nu *; skyg $*" +└── lib/ + ├── cmds.nu # All subcommand implementations (NuShell — source of truth) + ├── profile.nu # Profile helpers and tab-completion data + └── types.nu # Type definitions +``` + +## Key Commands + +| Command | Description | +|---|---| +| `skyg os switch` | Rebuild and switch local system | +| `skyg remote switch ` | Deploy to a remote host | +| `skyg hm switch` | Apply Home Manager config | +| `skyg update [input]` | Update flake inputs | +| `skyg build-iso` | Build bootable ISO | +| `skyg openwrt` | Deploy OpenWrt config | +| `skyg rollback` | Roll back to previous generation | + +## Agent Note + +> **Never invoke `skyg` commands that trigger builds or switches.** +> Only the user runs these. Edits to `cmds.nu` are safe if the user asks for CLI changes. diff --git a/configs/ABOUTME.md b/configs/ABOUTME.md new file mode 100644 index 0000000..11304b9 --- /dev/null +++ b/configs/ABOUTME.md @@ -0,0 +1,22 @@ +# configs/ + +Application configuration files that are symlinked into `~/.config/` via +`system.userActivationScripts` (using `skygUtils.makeHyperlinkScriptToConfigs` +from `modules/skyg-utils.nix`). + +## Contents + +| Path | Description | +|---|---| +| `niri/` | Niri Wayland compositor config | +| `hypr/` | Hyprland compositor config | +| `hyprpanel/` | HyprPanel bar/widget config | +| `extra.nu` | Extra NuShell config sourced at shell startup | +| `fwbook.knsv` | fwbook-specific Kanshi display profile | +| `libinput-gestures.conf` | Touchpad gesture bindings | + +## Notes + +- Changes here take effect on next login or when the activation script runs +- These are **not** NixOS options — they are plain config files managed as repo content +- The symlink mechanism is defined in `modules/skyg-utils.nix` diff --git a/hosts/ABOUTME.md b/hosts/ABOUTME.md new file mode 100644 index 0000000..14d4685 --- /dev/null +++ b/hosts/ABOUTME.md @@ -0,0 +1,36 @@ +# hosts/ + +One NixOS configuration file per managed machine, plus hardware configs and host-specific scripts. + +## Structure + +``` +hosts/ +├── .nix # Host configuration (packages, services, options) +├── .hardware-configuration.nix # Generated by nixos-generate-config — DO NOT EDIT +├── scripts/ +│ └── fwbook/ # fwbook-specific shell scripts +│ └── functions.sh # ZSH functions sourced at shell startup +``` + +## Managed Hosts + +| File | Host | Role | +|---|---|---| +| `fwbook.nix` | fwbook | Framework 13 AMD — personal laptop / daily driver | +| `hl-fwdesk.nix` | hl-fwdesk | Framework Desktop AI Max 300 — AI workstation | +| `hl-fws1.nix` | hl-fws1 | Framework 11th Intel — K3s server node | +| `hl-bigbox1.nix` | hl-bigbox1 | AI/compute server (NVIDIA + AMD) | +| `hl-bigbox2.nix` | hl-bigbox2 | NFS storage server | +| `hl-minipc1.nix` | hl-minipc1 | Core infra: Gitea, nix-serve, Docker registry | +| `hl-minipc2.nix` | hl-minipc2 | Container/media server | +| `hl-minipc3.nix` | hl-minipc3 | K3s worker node | +| `hl-terra1.nix` | hl-terra1 | NFS storage + Jellyfin backup | +| `iso.nix` | iso | Bootable NixOS installer image | + +## Rules + +- **Do not add `imports = [...]`** to host files — module composition happens in `flake.nix` via `modules/main.nix` +- **Do not edit `*.hardware-configuration.nix`** — these are generated and will be overwritten +- Host-specific packages and one-off settings belong here; anything reused across hosts belongs in `modules/` +- See `docs/hosts/README.md` for full per-host service/port/package reference diff --git a/hosts/hl-fwdesk.nix b/hosts/hl-fwdesk.nix index 5d9dbd9..8516c6c 100644 --- a/hosts/hl-fwdesk.nix +++ b/hosts/hl-fwdesk.nix @@ -1,4 +1,5 @@ { pkgs +, lib , ... }: let @@ -154,7 +155,6 @@ in OLLAMA_KEEP_ALIVE = "24h"; }; }; - hardware.graphics.enable = true; hardware.enableAllFirmware = true; hardware.amdgpu = { opencl.enable = true; diff --git a/modules/ABOUTME.md b/modules/ABOUTME.md new file mode 100644 index 0000000..b804724 --- /dev/null +++ b/modules/ABOUTME.md @@ -0,0 +1,42 @@ +# modules/ + +All reusable NixOS and Home Manager modules. Every host gets the full module tree via +`modules/main.nix`, which is wired up in `flake.nix` through the `makeNixOs` helper. + +## Structure + +``` +modules/ +├── lib.nix # makeNixOs / makeIso / makeHomeManagerUsers / makeDarwinModule / eachSystem +├── main.nix # Base module imported by every host: core/ + nixos/ + network-drives.nix +├── skyg-utils.nix # makeHyperlinkScriptToConfigs (symlinks configs/ → ~/.config/) +├── macos.nix # macOS / nix-darwin module +├── network-drives.nix # skyg.networkDrives — NFS automount options +├── core/ # User, binary caches, distributed builds, macOS workarounds +├── home/ # Home Manager: shell, programs, git, fonts, services +├── nixos/ +│ ├── common/ # Core system settings, networking, SSH, QEMU, fonts, hardware +│ ├── server/ # Server services: K3s, Gitea, AI stack, DNS, Dockge, ARRs... +│ └── desktop/ # Desktop: tiler (niri/hyprland), packages, theming, crypto +└── openwrt/ # OpenWrt router config generator +``` + +## Option Namespace + +All custom options live under `skyg.*`. Never introduce options outside this namespace. + +``` +skyg.user.* → core/user.nix +skyg.networkDrives.* → network-drives.nix +skyg.nixos.common.* → nixos/common/ +skyg.nixos.desktop.* → nixos/desktop/ +skyg.nixos.server.* → nixos/server/ +skyg.core.* → core/ +``` + +## Key Conventions + +- All modules gate config with `lib.mkIf cfg.enable { ... }` +- Default for every `enable` option is `false` unless universally required +- New modules go in the most specific subdirectory that matches their scope +- See `docs/modules/README.md` for full option reference and architecture diagram diff --git a/openwrt-routers/ABOUTME.md b/openwrt-routers/ABOUTME.md new file mode 100644 index 0000000..db19fda --- /dev/null +++ b/openwrt-routers/ABOUTME.md @@ -0,0 +1,33 @@ +# openwrt-routers/ + +Declarative OpenWrt router configurations, compiled to UCI (Unified Configuration Interface) +by the Rust-based generator in `modules/openwrt/generator/`. + +## Contents + +| File | Description | +|---|---| +| `glmain.nix` | Configuration for the `glmain` GL.iNet router (gateway at `10.0.0.1`) | + +## How It Works + +1. `glmain.nix` declares the router's network topology, firewall zones, DHCP, and DNS in Nix +2. `modules/openwrt/default.nix` passes it through the generator binary +3. `skyg openwrt` SSHes to the router and applies the generated UCI config + +## Deploying + +```bash +skyg openwrt +``` + +## Adding a New Router + +1. Create `openwrt-routers/.nix` modelled on `glmain.nix` +2. Add a `openwrt-` package output in `flake.nix` using the `openwrt` helper +3. Add a deploy target in `bin/lib/cmds.nu` + +## Notes + +- Router credentials are stored in `secrets/glmain.json.age` +- Do not hardcode passwords or PSKs in the `.nix` file — use agenix secrets diff --git a/pkgs/ABOUTME.md b/pkgs/ABOUTME.md new file mode 100644 index 0000000..eba85b7 --- /dev/null +++ b/pkgs/ABOUTME.md @@ -0,0 +1,28 @@ +# pkgs/ + +Custom Nix package derivations for software not available in nixpkgs (or needing local overrides). +Packages here are exposed via an overlay defined in `modules/core/default.nix`. + +## Contents + +| Package | Description | +|---|---| +| `grok-cli/` | xAI Grok CLI — prebuilt static binary, fetched per-platform. Exposed as `pkgs.grok-cli`. | + +## Adding a New Package + +1. Create `pkgs//default.nix` with a standard derivation +2. Add an entry to the overlay in `modules/core/default.nix`: + ```nix + (final: _prev: { + = final.callPackage ../../pkgs/ { }; + }) + ``` +3. Reference it as `pkgs.` anywhere in the flake +4. Optionally expose it as a flake output in `flake.nix` under `packages` + +## Notes + +- For unfree or binary packages, set `meta.license` and `meta.sourceProvenance` accurately +- Use `stdenvNoCC` for prebuilt binaries that don't need compilation +- Hash updates: use `nix hash file --type sha256 --sri ` after downloading the new binary diff --git a/secrets/ABOUTME.md b/secrets/ABOUTME.md new file mode 100644 index 0000000..6290244 --- /dev/null +++ b/secrets/ABOUTME.md @@ -0,0 +1,34 @@ +# secrets/ + +Age-encrypted secret files managed with [agenix](https://github.com/ryantm/agenix). + +## Contents + +| File | Description | +|---|---| +| `dns-addresses.conf.age` | DNS address overrides for the dnsmasq module | +| `glmain.json.age` | OpenWrt router credentials/config for `glmain` | + +## ⚠️ Agent Warning + +**Do not read, write, decrypt, or delete any `.age` file.** +These files are encrypted and can only be decrypted by authorized SSH keys. +Editing them outside of `agenix` will corrupt the secret. + +## Workflow (for humans) + +```bash +# Edit a secret (decrypts, opens editor, re-encrypts) +skyg secrets edit dns-addresses.conf.age + +# Re-key all secrets (e.g. after adding a new host key) +skyg secrets rekey +``` + +## Adding a New Secret + +1. Add the `.age` filename and authorized public keys to `secrets.nix` +2. Run `skyg secrets edit .age` to create and encrypt the file +3. Reference it in a module via `config.age.secrets..path` + +See `docs/agenix.md` for the full workflow reference. diff --git a/system-special-links/ABOUTME.md b/system-special-links/ABOUTME.md new file mode 100644 index 0000000..46a0001 --- /dev/null +++ b/system-special-links/ABOUTME.md @@ -0,0 +1,18 @@ +# system-special-links/ + +Tracked repository copies of files that live at special system paths outside the normal +Nix store — primarily Kubernetes configs and persistent service data that must be +version-controlled but can't be managed as Nix derivations. + +## Contents + +| Directory | Description | +|---|---| +| `k3s-configs/` | K3s cluster configuration files (manifests, kubeconfig templates) | +| `terra1-apps/` | Application data layouts for `hl-terra1` NFS-backed services | + +## Notes + +- Files here are **not** automatically deployed by the flake +- They are synced to target hosts manually or via the `skyg remote` workflow +- Do not store secrets here — use `secrets/` with agenix instead