# AGENTS.md

## Project

C++17 / Windows desktop app using **OpenUSD + ImGui + OpenGL**. USD scene editor with layer-based overrides for lights, geometry, and materials — similar to Maya Render Layers.

---

## Build Commands

```powershell
# Configure (Visual Studio 17 2022, outputs to ./build, installs to ./install)
cmake --preset default

# Build Release
cmake --build build --config Release

# Install
cmake --install build --config Release

# Build & run tests
cmake --build build --config Release
ctest --test-dir build -C Release
```

- **Always** use `cmake --preset default` — do not invoke CMake manually with ad-hoc `-G` flags.
- Build output: `./build/` | Install prefix: `./install/`
- The installed `App.exe` lives in `install/bin/`.

---

## Key Paths

| What | Where |
|---|---|
| OpenUSD SDK | `third_party/OpenUSD_v25.05/` |
| ImGui source | `third_party/imgui-1.92.7/` |
| GLAD loader | `third_party/glad/` |
| Inter font | `third_party/Inter/Inter.ttc` |
| CMake Find modules | `cmake/modules/` (`FindOpenUSD.cmake`, `FindImgui.cmake`, `FindGlad.cmake`) |
| USD business logic | `src/core/` |
| ImGui panels | `src/ui/` |
| Utilities | `src/utils/` |
| Tests | `tests/` |
| OpenSpec specs/changes | `openspec/changes/` |

> Note: AGENTS.md previously listed `OpenUSD_v25.08` — the actual SDK on disk is `OpenUSD_v25.05`. Trust `CMakePresets.json` / `third_party/` over prose.

---

## Architecture Notes

- **Namespace**: all project code uses `namespace UsdLayerManager`.
- USD plugin registry: at runtime the app scans `<exe_dir>/usd/` for `plugInfo.json` and registers plugins via `pxr::PlugRegistry`.
- Renderer uses `UsdImagingGLEngine` into a `GlfDrawTarget` FBO; viewport picking done via engine ray-cast.
- `ViewportCamera` mirrors `usdview`'s `FreeCamera.py` (Tumble/Truck/AdjustDistance/FrameSelection); supports both Free and USD camera-prim modes.
- ImGui docking branch is used; docking enabled via `IMGUI_HAS_DOCK`.
- Python 3.12 (`python312.dll`) must be present — OpenUSD runtime requires it. CMake copies it to output via `POST_BUILD`.
- Windows-only: uses `imgui_impl_win32` + `imgui_impl_opengl3`.

---

## Critical Rules

1. **API Pre-check**: Before writing any OpenUSD API call, scan headers first:
   ```powershell
   findstr /r /s "FunctionName" third_party\OpenUSD_v25.05\include\
   ```
   Never assume an API exists — the actual SDK version may differ from docs.

2. **Build before test**: Complete `cmake --build` + `cmake --install` before running `App.exe` or CTest. Tests copy USD/Python DLLs via `POST_BUILD`; skipping the build step breaks DLL resolution.

3. **Self-healing**: If compilation fails, extract the MSBuild error log and fix the root cause. Do not retry the same approach more than once.

4. **No CI**: There are no GitHub Actions workflows. Validation is manual via CTest and running `App.exe`.

---

## Feature Workflow (OpenSpec)

Feature proposals live under `openspec/changes/<name>/` with `proposal.md`, `design.md`, `specs/`, and `tasks.md` (checkbox-tracked). Use the `openspec-*` skills (via Kilo) to propose, implement, and archive changes.