init new repo

AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md
+
+## What this repo is
+
+NixOS flake that defines kiosk systems running the RadiantWave app. Not application code — this is the OS image and deployment configuration. The actual app lives in the `rhemawave` flake input (from Codeberg).
+
+Hosted on Codeberg: `https://codeberg.org/RhemaWave-Technologies/KioskConfig`
+
+## Key commands
+
+```bash
+# Build a system closure (any config name from flake.nix)
+nix build .#nixosConfigurations.<name>.config.system.build.toplevel
+
+# Build a bootable ISO
+nix build .#nixosConfigurations.<name>.config.system.build.isoImage
+
+# Deploy to a remote kiosk over SSH
+nixos-rebuild switch --flake .#<name> --target-host root@<host>
+
+# Push build result to Attic cache
+attic push kiosk ./result
+
+# Evaluate available config names
+nix eval .#nixosConfigurations --apply builtins.attrNames
+```
+
+## Config variants
+
+| Name | Target hardware | Disk device | Notes |
+|---|---|---|---|
+| `rhemawavekiosk` | Intel NUC 14 (NVMe) | `/dev/nvme0n1` | Production, uses `rhemawave` main |
+| `rhemawavekiosk-dev` | Intel NUC 14 (NVMe) | `/dev/nvme0n1` | Dev, uses `rhemawave-dev` ref |
+| `rhemawavekiosk-commercial` | Commercial HW (SATA) | `/dev/sda` | Production |
+| `rhemawavekiosk-commercial-dev` | Commercial HW (SATA) | `/dev/sda` | Dev |
+| `rhemawavekiosk-android` | Intel NUC 14 | `/dev/nvme0n1` | + rotated display (portrait) |
+| `rhemawavekiosk-rpi` | Raspberry Pi 5 | — | Uses `nixos-raspberrypi` |
+| `rhemawavekiosk-rpi-dev` | Raspberry Pi 5 | — | Dev, uses `rhemawave-dev` |
+
+ISOs: `usb-iso`, `commercial-usb-iso`, `android-iso`, `dev-iso` — each bakes in the corresponding system closure for zero-touch install.
+
+## Branching model
+
+Single branch (`main`). Production vs. dev split is at the **flake input** level (`rhemawave` vs `rhemawave-dev`), not at the branch level.
+
+## CI (Forgejo)
+
+`.forgejo/workflows/build-dev.yml` — triggered by `repository_dispatch` (`radiantwave-dev-built`) from the RadiantWave repo. Updates `rhemawave-dev` input, builds dev closure + ISO, commits updated `flake.lock`. Runs on `neils-server-runner`.
+
+## Important gotchas
+
+- **Disk device differs by variant**: `disk-config.nix` uses `/dev/nvme0n1`, `commercial-disk-config.nix` uses `/dev/sda`. Don't mix them up.
+- **ISO configs reference specific system closures**: `iso-config.nix` hardcodes `rhemawavekiosk`, `dev-iso.nix` hardcodes `rhemawavekiosk-dev`, `commercial-iso-config.nix` hardcodes `rhemawavekiosk-commercial`. Changing a config name in `flake.nix` requires updating the corresponding ISO config.
+- **Attic cache token**: ISO configs embed a JWT token for Attic in `/etc/nix/netrc`. If builds fail with auth errors, the token may have expired (expiry in the JWT payload).
+- **`rotated_display.nix` uses `mkForce`** on `loginShellInit` — it replaces the entire kiosk startup script from `configuration.nix`, don't edit both.
+- **SOPS**: `.sops.yaml` configures age-based encryption for `secrets.yaml`. You'll need the private key matching `age1t2wpzv...` to decrypt.
+- **Flake inputs**: `rhemawave` tracks main, `rhemawave-dev` tracks `?ref=dev`. Updating them independently is intentional.
+
+## File map
+
+- `flake.nix` — all system definitions, entry point
+- `configuration.nix` — shared NixOS config (packages, services, kiosk user, auto-upgrade, health check, VM variant)
+- `disk-config.nix` — NVMe disk layout (NUC)
+- `commercial-disk-config.nix` — SATA disk layout (commercial HW)
+- `iso-config.nix` — production ISO + zero-touch installer
+- `dev-iso.nix` — dev ISO + zero-touch installer
+- `commercial-iso-config.nix` — commercial ISO + zero-touch installer
+- `rotated_display.nix` — portrait display override for Android variant
+- `facter.json` — hardware facter report (NUC 14)
+- `14rvk.json`, `pn54.json` — additional hardware facter reports
+- `assets/` — logo and splash image
+- `plymouth-theme/` — boot splash theme
+- `commands.md` — quick-reference for build/deploy commands