réorg doc

AGENTS.md

@@ -5,22 +5,24 @@ Rust workspace (2024 edition) wrapping [wgpu](https://github.com/gfx-rs/wgpu) fo
 
 ## Workspace Structure
 ```
-Cargo.toml          # workspace root — no dependencies here
-lib/Cargo.toml      # wsg-lib crate: wgpu 30.0.0, winit 0.30
-examples/Cargo.toml # depends on wsg-lib via path reference
-lib/lib.rs          # lib entry point
-lib/context.rs      # Context type (aggregates wgpu objects: Instance, Surface, Adapter, Device, Queue)
-lib/renderer.rs     # renderer implementation
-examples/src/main.rs # example binary
+Cargo.toml          # workspace root (members = ["lib"]) — no dependencies here
+lib/Cargo.toml      # wsg-lib crate: wgpu 30.0.0, winit 0.30 + explicit [[example]] entries
+lib/src/            # library source (app, core/, mesh/, pipeline/, resources/, scene/, utils/)
+lib/examples/       # examples, one subfolder per category (each folder has a README.md):
+│   ├── meshes/     #   simple, cube, pbr, import, manual
+│   ├── lights/     #   shadow, shadow_test, spot_test, emissive
+│   ├── cameras/    #   culling
+│   └── effects/    #   demo, bloom, hdr, msaa, fog, dof
 ```
 
-**Key convention**: `wsg-lib` is referenced from `examples/` via relative path (`path = "../lib"`). Do not publish this to crates.io as-is — it uses a local path dependency.
+**Key convention**: examples live in `lib/examples/<category>/` subfolders. Cargo only auto-discovers top-level `examples/*.rs`, so **every example is declared explicitly in `lib/Cargo.toml`** (`[[example]] name = … path = "examples/<cat>/….rs"`). Names are stable: `cargo run -p wsg-lib --example <name>` works as before. Do not publish this to crates.io as-is — it uses local path conventions.
 
 ## Essential Commands
 | Action | Command |
 |--------|---------|
 | Build everything | `cargo build --workspace` |
-| Run examples | `cargo run -p examples` |
+| Run an example | `cargo run -p wsg-lib --example <name>` |
+| Run a feature-gated example | `cargo run -p wsg-lib --example import --features import-obj` |
 | Test | `cargo test --workspace` |
 | Check | `cargo check --workspace` |
 | Format | `cargo fmt --all` |
@@ -41,7 +43,7 @@ WGPU doesn't have a native "Context" object — this type groups them together f
 ## Gotchas
 - Rust 2024 edition is used. Ensure your Rust toolchain supports it (`rustup update`).
 - wgpu 30.0.0 is pinned in `lib/Cargo.toml`. The comment says "check the latest version" — verify compatibility before upgrading.
-- No feature flags, no dev-dependencies, no tests yet. Adding any requires updating both `Cargo.toml` files if the dependency spans crates.
+- Cargo features gate primitives (`prim-*`, `all-prims` is default) and importers (`import-obj`, `import-gltf`); the `import` example is `required-features = ["import-obj"]`. 127 tests exist (`cargo test --workspace`).
 - The workspace has no `[workspace.dependencies]` section. Dependencies are declared per-crate rather than centrally.
 - **WGSL `select` argument order** (cost us a day): `select(reject, accept, cond)` returns the **second** arg when `cond` is true — the reverse of HLSL's `select(trueVal, falseVal, cond)`. In `shaders/gpu_driven.wgsl` the cull pass must stay `select(0u, u32(flags.z), visible)` (visible ⇒ full count, culled ⇒ 0). Swapped args silently zero the counts of every visible entity → black window. See the GOTCHA comment at the top of that shader.
 - **LOD UV blending: never fold integer-tile jumps, freeze seam twins instead** (cost us a day, 2026-09-23): a UV *seam* is two copies of the same 3-D point on integer-apart UVs (u=0/u=1 columns) — it is NOT a mesh edge, so the decimation must record the weld's refused pairs and **freeze** those twins (any edge touching one is excluded from the PQ). A co-facial edge spanning a whole tile (cone apex v=1 ↔ base v=0) is a *legit* chart span — the chart is bilinear, so the UVs **blend linearly** (fold the integer jump to zero and the apex UV smears down the cone side). And the attribute-aware weld refuses a Δ of *exactly* 0.5 (ambiguous: seam at its widest vs legit half-tile jump — the cone's u=1 column vs the cap-disc chart sits exactly there). See the comments in `geometry.rs` (`welded`, `Collapse::collapse_edge`) and the cone/seam regression tests.