# 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/radiantwave radiantwave.go

# Run
./bin/radiantwave

# 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 runs `go test` then `nix build -L`.

**Every bug fix MUST include regression tests.** When fixing a bug, write tests that:
1. Reproduce the exact conditions that caused the bug (should pass with the fix, fail without it)
2. Verify the correct behavior after the fix
3. Cover edge cases related to the bug

Do not merge a bug fix without corresponding tests.

## 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/radiantwave/database.sqlite`, managed by GORM in `internal/db/`
- **Assets**: `share/radiantwave/` (fonts, shaders, proclamations, tos) — embedded into the binary and provisioned to the data dir at first run
- **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/radiantwave/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.