initial commit

AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md
+
+Odin + raylib interactive 3D universe map (DESI data), with Go + Pulumi infra and Gitea Actions CI. A clean `odin build` + `go test` is the verification step.
+
+## Commands (root Makefile)
+- Run: `make run` (`odin run src`); Build: `make build` (`odin build src -collection:lib=lib/local -out:bin/desi_explorer`)
+- Web: `make build-web` (Emscripten/WASM -> build/web); Debug: `make build-debug`
+- Test: `make test` (runs `odin test` for src/ and `go test` for infra/); Clean: `make clean`
+- Setup: `make setup` (submodules + `go mod tidy` in infra/)
+- Infra: `make infra-preview`, `make infra-up`, `make infra-down`, `make infra-refresh` (Pulumi, `--cwd infra`)
+- Renovate: `make renovate-validate` (npx renovate-config-validator)
+- Format Odin with `odinfmt` (config `odinfmt.json`: tabs, width 80)
+
+## Layout
+- `src/main.odin` — entrypoint; loop is `update()` → `draw()`; resizable window with an orbital `Camera3D`; point cloud generated procedurally in `make_universe`.
+- `lib/` — third-party Odin deps (submodules / vendored libs). raylib is **not** here: it ships vendored with Odin and is imported as `vendor:raylib`. `lib/local/` is the default `-collection:lib` target and is currently empty.
+- `infra/` — Go + Pulumi (`runtime: go`) targeting the on-prem k3s cluster via the default kubeconfig, mirroring the `homelab` repo's pattern. Module name is `desi-explorer-infra`.
+- `.gitea/workflows/` — `ci.yml` (PR: install Odin, `odin test` + build, `go test`) and `release.yml` (tag `v*`: build native + WASM + publish a Gitea release).
+
+## Conventions
+- Odin code lives in `src/`; external deps go in `lib/` and are wired via `-collection:lib=lib/local` (or a git submodule imported by relative path).
+- Everything is plain `make` — no Taskfile — so CI (Gitea Actions) can call `make` directly.
+- Keep the renderer (src/) and infra (infra/) logically separated; the root Makefile is the only place that ties them together.
+
+## Gotchas
+- Odin version is pinned in `.gitea/workflows/*.yml` (`ODIN_VERSION`) and defaults in `scripts/install_odin.sh`; bump both together when tracking a new release.
+- CI installs `clang` (Odin uses it as the linker backend) and, for the WASM build, Emscripten + MinGW (Windows cross-build).
+- The WASM build uses `-define:RAYLIB_WASM_LIB=env.o` so emcc links raylib's prebuilt web lib instead of Odin.
+- Gitea Actions reuse the GitHub Actions plugin ecosystem (`actions/checkout`, `christopherHX/gitea-upload-artifact` / `gitea-download-artifact`); contexts remain `${{ github.* }}`.
+
+## Session History
+Export session information to `resources/ai/sessions` at the end of every session — for both plans and builds. (Gitignored.)
+
+## Gitignored
+`bin/`, `build/`, `*.bin`, `*.o`, `*.log`, `resources/ai/sessions`, `infra/Pulumi.*.yaml.backup`.