docs: lead the usage guide with the high-level api

Make nightshade-api the first thing to reach for when building a game.
USAGE.md previously opened straight into the engine State and launch
path and barely mentioned the api facade, so the concise procedural
layer was hard to discover. Add a Start Here section covering the run
shapes, defaults, verbs, a worked game, reads, and the command form,
and point CLAUDE.md at the api for games while keeping the engine layer
as the drop-down.

Author: matthewjberger

CLAUDE.md

@@ -1,6 +1,8 @@
 # Nightshade Engine
 
-Read `docs/USAGE.md` before writing or modifying engine code.
+For games, start with the high-level `nightshade-api` facade. Read `docs/SPEC_RUST_API.md` (the full signature catalog) and the "Start Here" section of `docs/USAGE.md`. The api games `apps/coin_dash` and `apps/coin_rush` and the `template_api/` template are the working references. Reach for the engine layer only when the facade stops covering what you need.
+
+Read `docs/USAGE.md` before writing or modifying engine code (the `nightshade` crate layer).
 
 ## Architecture
 
@@ -9,7 +11,7 @@ Read `docs/USAGE.md` before writing or modifying engine code.
 - Most systems run automatically via the frame schedule (`world.resources.schedules.frame`): physics, animation, navmesh, text sync, transforms, plus a single `RETAINED_UI` entry that runs the UI sub-schedule (`world.resources.schedules.retained_ui`). Don't call these manually.
 - Camera controllers are opt-in: call `fly_camera_system(world)` or `pan_orbit_camera_system(world)` in `run_systems`. `fly_camera_system` skips if the active camera has `PAN_ORBIT_CAMERA`.
 - Scenes load from glTF. Find entities by name after spawning (`world.core.find_entity_by_name`).
-- `apps/sandbox` is the go-to reference for idiomatic 3D games. Read it before writing a new app: state shell forwarding to system functions, own `freecs::ecs!` world, screen lifecycle in `systems/lifecycle.rs`, retained UI handles stored in resources, `theme.rs` for UI constants, prototype textures, level load/save. The `template/` crate is the same architecture in skeleton form.
+- `apps/sandbox` is the go-to reference for an idiomatic engine-level 3D game (when you have dropped below the `nightshade-api` facade). Read it before writing a new engine-layer app: state shell forwarding to system functions, own `freecs::ecs!` world, screen lifecycle in `systems/lifecycle.rs`, retained UI handles stored in resources, `theme.rs` for UI constants, prototype textures, level load/save. The `template/` crate is the same architecture in skeleton form.
 
 ## Querying
 

docs/USAGE.md

@@ -2,70 +2,223 @@
 
 Comprehensive API reference for the Nightshade game engine.
 
-Most types and functions are available via `use nightshade::prelude::*`. Items that require explicit imports are noted with their full path.
+Two layers ship in this repo, and which one you start in matters:
+
+- **`nightshade-api`** is the high-level procedural facade. Free functions over the engine `World`, plain data, no trait to implement, no ECS knowledge required. **For a game, reach for this first.** It is far more concise than the engine layer and covers the whole procedural core of making things appear and behave. See [Start Here: The High-Level API](#start-here-the-high-level-api-nightshade-api) below, with the full catalog in `docs/SPEC_RUST_API.md` and the `api-*` chapters under `docs/book/src/`.
+- **`nightshade`** is the engine itself: the `State` trait, the ECS, the render graph, every subsystem. Everything after the high-level section documents this layer. You drop down to it one call at a time when the facade stops covering what you need.
+
+Every `nightshade-api` function bottoms out in an engine call and hands you the real `World`, so nothing is hidden and there is no migration cost. From an api program, reach the full engine with `use nightshade_api::nightshade::prelude::*;`.
+
+For the engine layer, most types and functions are available via `use nightshade::prelude::*`. Items that require explicit imports are noted with their full path.
 
 ---
 
 ## Table of Contents
 
-1. [Getting Started](#getting-started)
-2. [The State Trait](#the-state-trait)
-3. [ECS & Entity Management](#ecs--entity-management)
-4. [World Resources](#world-resources)
-5. [3D Meshes & Scenes](#3d-meshes--scenes)
-6. [Instanced Meshes](#instanced-meshes)
-7. [Cameras](#cameras)
-8. [Lighting](#lighting)
-9. [Materials & Textures](#materials--textures)
-10. [Shadows](#shadows)
-11. [Grass](#grass-grass-feature)
-12. [Terrain](#terrain-terrain-feature-implies-grass)
-13. [Post-Processing](#post-processing)
-14. [Custom Render Passes](#custom-render-passes)
-15. [Input Handling](#input-handling)
-16. [Physics](#physics)
-17. [Audio](#audio)
-18. [Skeletal Animation](#skeletal-animation)
-19. [Inverse Kinematics](#inverse-kinematics)
-20. [Morph Targets](#morph-targets)
-21. [Particle Systems](#particle-systems)
-22. [Cloth Simulation](#cloth-simulation)
-23. [Tweens & Shake](#tweens--shake)
-24. [Cutscenes](#cutscenes)
-25. [Text Rendering](#text-rendering)
-26. [UI: Retained Mode](#ui-retained-mode)
-27. [UI: Docking & Tiles](#ui-docking--tiles)
-28. [Scene Serialization](#scene-serialization)
-29. [Procedural Generation](#procedural-generation)
-30. [Pathfinding & Navigation](#pathfinding--navigation)
-31. [Picking & Raycasting](#picking--raycasting)
-32. [Debug Lines](#debug-lines)
-33. [Atmosphere & Skybox](#atmosphere--skybox)
-34. [Decals](#decals)
-35. [Render Layers](#render-layers)
-36. [Prefabs & GLTF Loading](#prefabs--gltf-loading)
-37. [Entity Hierarchy](#entity-hierarchy)
-38. [Entity GUIDs](#entity-guids)
-39. [Event Bus](#event-bus)
-40. [Event Stream](#event-stream)
-41. [Multi-World Rendering](#multi-world-rendering)
-42. [Steam Integration](#steam-integration)
-43. [Hot Reload](#hot-reload)
-44. [Developer Console](#developer-console-shell)
-45. [LOD (Level of Detail)](#lod-level-of-detail)
-46. [Asset Loading Queue](#asset-loading-queue)
-47. [Scripting](#scripting)
-48. [Game Development Patterns](#game-development-patterns)
-49. [Common Non-Prelude Imports](#common-non-prelude-imports)
-50. [Offscreen & Headless Rendering](#offscreen--headless-rendering)
-51. [Platform Notes](#platform-notes)
-52. [Visual Effects](#visual-effects)
+1. [Start Here: The High-Level API (nightshade-api)](#start-here-the-high-level-api-nightshade-api)
+2. [Getting Started](#getting-started)
+3. [The State Trait](#the-state-trait)
+4. [ECS & Entity Management](#ecs--entity-management)
+5. [World Resources](#world-resources)
+6. [3D Meshes & Scenes](#3d-meshes--scenes)
+7. [Instanced Meshes](#instanced-meshes)
+8. [Cameras](#cameras)
+9. [Lighting](#lighting)
+10. [Materials & Textures](#materials--textures)
+11. [Shadows](#shadows)
+12. [Grass](#grass-grass-feature)
+13. [Terrain](#terrain-terrain-feature-implies-grass)
+14. [Post-Processing](#post-processing)
+15. [Custom Render Passes](#custom-render-passes)
+16. [Input Handling](#input-handling)
+17. [Physics](#physics)
+18. [Audio](#audio)
+19. [Skeletal Animation](#skeletal-animation)
+20. [Inverse Kinematics](#inverse-kinematics)
+21. [Morph Targets](#morph-targets)
+22. [Particle Systems](#particle-systems)
+23. [Cloth Simulation](#cloth-simulation)
+24. [Tweens & Shake](#tweens--shake)
+25. [Cutscenes](#cutscenes)
+26. [Text Rendering](#text-rendering)
+27. [UI: Retained Mode](#ui-retained-mode)
+28. [UI: Docking & Tiles](#ui-docking--tiles)
+29. [Scene Serialization](#scene-serialization)
+30. [Procedural Generation](#procedural-generation)
+31. [Pathfinding & Navigation](#pathfinding--navigation)
+32. [Picking & Raycasting](#picking--raycasting)
+33. [Debug Lines](#debug-lines)
+34. [Atmosphere & Skybox](#atmosphere--skybox)
+35. [Decals](#decals)
+36. [Render Layers](#render-layers)
+37. [Prefabs & GLTF Loading](#prefabs--gltf-loading)
+38. [Entity Hierarchy](#entity-hierarchy)
+39. [Entity GUIDs](#entity-guids)
+40. [Event Bus](#event-bus)
+41. [Event Stream](#event-stream)
+42. [Multi-World Rendering](#multi-world-rendering)
+43. [Steam Integration](#steam-integration)
+44. [Hot Reload](#hot-reload)
+45. [Developer Console](#developer-console-shell)
+46. [LOD (Level of Detail)](#lod-level-of-detail)
+47. [Asset Loading Queue](#asset-loading-queue)
+48. [Scripting](#scripting)
+49. [Game Development Patterns](#game-development-patterns)
+50. [Common Non-Prelude Imports](#common-non-prelude-imports)
+51. [Offscreen & Headless Rendering](#offscreen--headless-rendering)
+52. [Platform Notes](#platform-notes)
+53. [Visual Effects](#visual-effects)
+
+---
+
+## Start Here: The High-Level API (nightshade-api)
+
+`nightshade-api` is a procedural layer over the engine. A whole scene or a small game reads as straight-line code: free functions, plain data, no trait, no callbacks, no ECS. Everything bottoms out in normal engine calls, so nothing is hidden and nothing is walled off. This is the first thing to reach for when building a game. The rest of this guide is the engine layer underneath, which you drop into when the facade stops covering what you need.
+
+The complete reference is `docs/SPEC_RUST_API.md` (the full signature catalog, written to be read once) and the `api-*` chapters under `docs/book/src/`. The serialized command form is `docs/COMMAND_API.md`.
+
+### Cargo.toml
+
+```toml
+[dependencies]
+# Inside this repo:
+nightshade-api = { path = "crates/nightshade-api" }
+# Outside the repo (versions in lockstep with the engine):
+nightshade-api = "0.46"
+```
+
+Default features: `audio`, `physics`, `gamepad`, `picking`, `navmesh` (each forwards to the engine feature of the same name). Opt-in: `scripting`, `terrain`, `grass`, `egui`, `net`. Disable defaults with `default-features = false` and an explicit list.
+
+### What you get for free
+
+`open()` and `run()` start you in a working scene, not a black screen: a sky, a sun with shadows, a reference grid, an orbit camera pointed at the origin, prototype textures (`"checkerboard"`, `"gradient"`, `"uv_test"`), physics on, and escape to exit. Building a scene is choosing what to change.
+
+### Two ways to run
+
+Own the loop (native). Setup is statements before the loop, game state is plain locals across iterations:
+
+```rust
+use nightshade_api::prelude::*;
+
+fn main() {
+    let mut app = open();
+    let cube = spawn_cube(&mut app.world, vec3(0.0, 0.5, 0.0));
+    while frame(&mut app) {
+        rotate(&mut app.world, cube, Vec3::y(), delta_time(&app.world));
+    }
+}
+```
+
+Hand the engine the loop (native and wasm). `setup` returns your state, `update` receives it back every frame:
+
+```rust
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    run(
+        |world| spawn_cube(world, vec3(0.0, 0.5, 0.0)),
+        |world, cube| rotate(world, *cube, Vec3::y(), delta_time(world)),
+    )
+}
+```
+
+`run!` takes any number of update systems sharing one state: `run!(setup, handle_input, move_player, check_collisions)`. `run_scene(setup)` is a static scene with no update. `render_image(width, height, path, setup)` renders one frame to a PNG with no window.
+
+### The verbs
+
+- `spawn_` is retained until you `despawn` it. `draw_` lasts one frame, so call it every frame you want it visible.
+- `set_` writes, `get_`/noun-named functions read. Colors are `[f32; 4]` linear RGBA, positions are `Vec3` via `vec3(...)`.
+
+```rust
+spawn_cube / spawn_sphere / spawn_cylinder / spawn_cone / spawn_torus / spawn_plane
+spawn_floor(world, half_extent)            // ground plane
+spawn_model(world, glb_bytes, position)    // animated glb
+spawn_object(world, Object { shape, position, scale, color, body })  // shape + color + physics in one
+spawn_objects / spawn_instanced            // crowds
+
+set_color / set_metallic_roughness / set_emissive / set_texture
+set_position / rotate / set_scale / set_parent
+position(world, entity) -> Vec3
+
+orbit_camera / fly_camera / first_person / third_person_camera / fixed_camera
+point_light / spot_light / directional_light / area_light / set_sun
+set_background / set_bloom / set_ssao / set_fog / set_time_of_day
+
+key_down / key_pressed / wasd / mouse_clicked / clicked_entity / delta_time
+push / set_velocity / raycast / collisions / overlap_sphere    // physics
+spawn_panel + panel_button / panel_slider / panel_label + button_clicked / slider_value  // UI
+spawn_text / set_text / spawn_label
+play_animation_named / blend_to_animation_named                // on a loaded model
+```
+
+The `Object` struct (has `Default`) is the fastest way to spawn a physical, colored shape:
+
+```rust
+spawn_object(world, Object {
+    shape: Shape::Cube,
+    position: vec3(0.0, 5.0, 0.0),
+    color: BLUE,
+    body: Body::Dynamic { mass: 1.0 },   // None, Static, or Dynamic
+    ..Object::default()
+});
+```
+
+### A small game
+
+```rust
+use nightshade_api::prelude::*;
+
+struct Game { player: Entity, score: Entity, points: u32 }
+
+fn main() { run!(setup, play).unwrap(); }
+
+fn setup(world: &mut World) -> Game {
+    set_background(world, Background::Sunset);
+    spawn_floor(world, 30.0);
+    let player = spawn_object(world, Object {
+        shape: Shape::Sphere, position: vec3(0.0, 0.5, 0.0), color: GOLD, ..Object::default()
+    });
+    for index in 0..8 {
+        let coin = spawn_torus(world, vec3((index as f32 - 4.0) * 3.0, 0.5, -6.0));
+        set_emissive(world, coin, [1.0, 0.8, 0.1], 4.0);
+        tag(world, coin, "coin");
+    }
+    let panel = spawn_panel(world, ScreenAnchor::TopLeft, 160.0, 40.0);
+    let score = panel_label(world, panel, "score: 0");
+    Game { player, score, points: 0 }
+}
+
+fn play(world: &mut World, game: &mut Game) {
+    let step = wasd(world) * 8.0 * delta_time(world);
+    set_position(world, game.player, position(world, game.player) + step);
+    let here = position(world, game.player);
+    for coin in tagged(world, "coin") {
+        if (position(world, coin) - here).norm() < 1.0 {
+            despawn(world, coin);
+            game.points += 1;
+            set_text(world, game.score, &format!("score: {}", game.points));
+        }
+    }
+}
+```
+
+Working references: the examples in `crates/nightshade-api/examples` (run with `just run-example <name>`), the api games `apps/coin_dash` and `apps/coin_rush`, and the templates `template_api/` (native) and `template_api_leptos/` (web worker plus Leptos).
+
+### Reading state back
+
+Reads are direct and typed, never round-tripped: `position`, `velocity`, `slider_value`, `get_color`, `name`, `children`, `descendants`, `roots`, `scene_tree`, `bounds`. `describe_entity(world, entity)` returns the whole editable state of one entity. Events come from `drain_events(world)` (collisions, animation, navigation).
+
+### Command form (for FFI, scripts, network, replay)
+
+Every mutating call also exists as a `Command` enum variant (300-plus), so the engine can be driven by serialized data. `submit_command(world, &cmd)` and `submit_commands(world, &batch)` dispatch them, `Ref::Result(n)` names the entity an earlier command in the same batch produced so one batch builds and wires a whole scene. Native code just calls the free functions, which are the real implementations. Details in `docs/COMMAND_API.md`.
+
+### When to drop to the engine
+
+The facade deliberately does not cover custom render passes, multi-world rendering, or user-defined ECS components. For those, read the engine-layer sections below. `apps/sandbox` is the canonical engine-level game reference. Migrate one call site at a time with `use nightshade_api::nightshade::prelude::*;`, never all at once.
 
 ---
 
 ## Getting Started
 
-Every Nightshade application implements the `State` trait and calls `launch()`.
+The engine layer (the `nightshade` crate). Every Nightshade application here implements the `State` trait and calls `launch()`. For most games, prefer the [high-level API](#start-here-the-high-level-api-nightshade-api) above and only reach for this when you need it.
 
 ### Cargo.toml