# 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.