AGENTS.md

# AGENTS.md — tinygltf v3 (C)

TinyGLTF v3 C (`tiny_gltf_v3.h` + `tiny_gltf_v3.c` + `tinygltf_json_c.h`) is the
mainline. Legacy v1/v2/v3-C++ code lives under `attic/` and is not built or
tested.

## Commands

- Unit tests (C): `make -C tests all && make -C tests run`
- CMake: `cmake -B build -DTINYGLTF3_BUILD_TESTS=ON && cmake --build build && ctest --test-dir build --output-on-failure`
- Meson: `meson setup build && meson compile -C build && meson test -C build`
- WASM/web demo (requires Emscripten SDK, default `~/work/emsdk`):
  `make -C web && make -C web sample` — then open `http://localhost:8000` via `make -C web serve`
- Fuzzers: `make -C tests/v3/fuzzer` (clang + libFuzzer)

## Pre-push audit checklist

Run **before every push**. Fix or unstage anything found; the audit must pass
clean.

1. **Working tree sanity**
   - `git status --short` — no staged build artifacts, no surprise files.
   - Never `git add -A` / `git add .`: stage only intended paths. The repo
     root frequently contains untracked scratch files (`Fox.glb`,
     `benchmark/synthetic_*`, `log*`, `.cache/`, `tests/v3/fuzzer/artifacts|corpus`,
     stray `*.gltf`/`*.bin` files). Verify `git status` before staging.

2. **Secret scan**
   - `gitleaks detect --source . --no-banner -r /tmp/gitleaks.json`
   - `~/local/bin/trufflehog git file://$PWD --no-update --only-verified`
   - Both must report 0 real secrets. Known allowed finding: `B3G_LEFT_ARROW`
     generic-api-key hits in `attic/examples/common/OpenGLWindow/` are false
     positives (keyboard key constants).

3. **No build artifacts or unwanted large binaries**
   - `git ls-files -z | xargs -0 du -b | sort -rn | head -30` — review the top.
   - Rule of thumb: nothing over ~1 MB unless it is a tracked, intentional
     asset (e.g. `attic/tools/windows/premake5.exe`, `models/Cube/*.png`).
   - Watch for: compiled executables, `*.wasm`/`*.exr`/`*.log`/`*.o`/`*.obj`,
     generated `output.*`/`cloth*`/`sim*.bin`/`out_*.exr` files, and large
     `.gltf`/`.glb` files. Small test/regression fixture `.gltf` files
     (e.g. under `tests/`, `models/regression/`, `tests/v3/security/`) are OK.
   - `web/tinygltf_v3.js`, `web/tinygltf_v3.wasm`, `web/Cube.glb` are
     generated by `make -C web` and must stay gitignored (never commit them).

4. **History is lean**
   - If an unwanted file was added in an unpushed commit, rewrite it
     (`git rebase -i origin/<branch>`, `git rm` + `--amend`) so the blob never
     reaches the remote, then `git gc --prune=now` locally.
   - Push only intended branches (`git push origin <branch>` — never `--all`
     or `--force` unless explicitly asked).

5. **Final smoke check**
   - `make -C tests run` passes (all 4 testers).
   - If touched: `cmake`/`meson` builds and `make -C web` still succeed.