feat: test VM build/run script with SSH diagnostics

- nixos/vm.nix: enable PasswordAuthentication for kiosk user (SSH test access)
- scripts/test-vm.sh: one-command build → start → diagnose workflow
  - macOS: builds and runs on remote Linux server, SSH through server
  - Linux: builds and runs locally
  - Commands: --build, --start, --stop, --diagnose, --shell
  - Diagnostics: NetworkManager, PipeWire, wpctl, ALSA, pactl, processes, logs
- AGENTS.md: compact agent guide for the repo

AGENTS.md

@@ -0,0 +1,58 @@
+# RadiantWave Agent Guide
+
+## What This Is
+
+Go kiosk application using SDL2, OpenGL 3.3, SQLite (via GORM), and D-Bus (NetworkManager). Nix flake is the primary build system. CI runs on Forgejo (not GitHub Actions).
+
+## Build & Run
+
+Dev shell via direnv (`use flake` in `.envrc`). Inside the nix dev shell:
+
+```sh
+# Build
+go build -o bin/rhemawave rhemawave.go
+
+# Run
+./bin/rhemawave
+
+# Nix build (CI uses this)
+nix build -L
+```
+
+CGO is required (`CGO_ENABLED=1`). The nix dev shell and `flake.nix` `preBuild` set the necessary `CGO_CFLAGS` and `CGO_LDFLAGS` for SDL2. Do not attempt a plain `go build` outside the nix shell — it will fail on missing SDL2 headers.
+
+## Tests
+
+Only one test suite exists: `internal/mixer/mixer_test.go`. Run with:
+
+```sh
+go test ./internal/mixer/
+```
+
+No lint or typecheck commands are configured in the repo. CI only runs `nix build -L`.
+
+## Branch Model
+
+`dev` → `main` via pull requests. CI workflows are in `.forgejo/workflows/`:
+- `build-dev.yml`: PRs to `dev`
+- `build-prod.yml`: PRs to `main`
+
+Both run `nix build -L` on a self-hosted runner (`neils-server-runner`).
+
+## Key Architecture
+
+- **Entry**: `rhemawave.go` → `internal/application.Run()`
+- **State machine**: `internal/application/application.go` — FIRST_RUN → NEEDS_INTERNET → NEEDS_EMAIL_ADDRESS → NEEDS_LICENSE_KEY → DOWNLOADING_ASSETS → READY
+- **Pages**: `internal/page/` — router pattern with page interface (`page.go`)
+- **DB**: SQLite at `~/.local/share/rhemawave/database.sqlite`, managed by GORM in `internal/db/`
+- **Assets**: `share/rhemawave/` (fonts, shaders, proclamations, tos) — copied into nix store at build time
+- **Audio**: `.wav` files are gitignored, downloaded at runtime from `files.radiantwavetech.com`
+- **Vendor**: Dependencies are vendored and committed. Use `go mod vendor` after adding deps.
+
+## Common Pitfalls
+
+- The `dev_scripts/reset.sh` referenced in the nix devShell hook does not exist in the repo.
+- `share/rhemawave/audio/*.wav` is gitignored — do not commit audio assets.
+- The `vendor/` directory is committed — always run `go mod vendor` after `go mod tidy`.
+- CI runs on a self-hosted Forgejo runner, not GitHub-hosted runners. Workflows source nix via `/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh`.
+- The `packaging/` directory contains a kiosk-specific updater script and is not part of the main build.