chore(docs): Update documentation structure

CONTRIBUTING.md

@@ -72,6 +72,8 @@ When adding or modifying features:
 - Update rustdoc comments for public APIs.
 - Add or update examples in `crates/lambda-rs/examples/`.
 - Create or update specifications in `docs/specs/` for significant changes.
+  - Add new specs to `docs/specs/README.md` and group them by feature area.
+  - Place new specs under a matching subdirectory (for example, `docs/specs/rendering/`).
 - Follow the documentation tone and style guidelines in `AGENTS.md`.
 
 ## Questions and Discussions

README.md

@@ -130,7 +130,7 @@ Coming soon.
 Start with the tutorials to build features step by step:
 
 * Tutorials index: [docs/tutorials/](./docs/tutorials/)
-* Uniform Buffers: Build a Spinning Triangle: [docs/tutorials/uniform-buffers.md](./docs/tutorials/uniform-buffers.md)
+* Uniform Buffers: Build a Spinning Triangle: [docs/tutorials/rendering/resources/uniform-buffers.md](./docs/tutorials/rendering/resources/uniform-buffers.md)
 
 ## Examples <a name="examples"></a>
 

docs/specs/README.md

@@ -0,0 +1,33 @@
+---
+title: "Specifications Index"
+document_id: "specs-index-2026-02-07"
+status: "living"
+created: "2026-02-07T00:00:00Z"
+last_updated: "2026-02-07T00:00:00Z"
+version: "0.1.0"
+owners: ["lambda-sh"]
+reviewers: ["engine"]
+tags: ["index", "specs", "docs"]
+---
+
+## Rendering
+
+- Uniform Buffers and Bind Groups — [rendering/uniform-buffers-and-bind-groups.md](rendering/uniform-buffers-and-bind-groups.md)
+- Textures and Samplers — [rendering/textures-and-samplers.md](rendering/textures-and-samplers.md)
+- Instanced Rendering — [rendering/instanced-rendering.md](rendering/instanced-rendering.md)
+- Indexed Draws and Multiple Vertex Buffers — [rendering/indexed-draws-and-multiple-vertex-buffers.md](rendering/indexed-draws-and-multiple-vertex-buffers.md)
+- Depth, Stencil, and MSAA — [rendering/depth-stencil-msaa.md](rendering/depth-stencil-msaa.md)
+- Offscreen Render Targets and Multipass — [rendering/offscreen-render-targets-and-multipass.md](rendering/offscreen-render-targets-and-multipass.md)
+
+## Audio
+
+- Audio Devices — [audio/audio-devices.md](audio/audio-devices.md)
+- Audio File Loading — [audio/audio-file-loading.md](audio/audio-file-loading.md)
+
+## Runtime / Events
+
+- Component Event Handling — [runtime/component-event-handling.md](runtime/component-event-handling.md)
+
+## Templates
+
+- Specification template — [_spec-template.md](_spec-template.md)

docs/specs/_spec-template.md

@@ -17,6 +17,9 @@ tags: ["spec", "<area>"]
 
 # <Specification Title>
 
+Note: Place specifications under the appropriate area folder (for example,
+`docs/specs/rendering/`) and add them to `docs/specs/README.md`.
+
 Summary
 - State the problem and the desired outcome in one paragraph.
 - Include a concise rationale for introducing or changing behavior.

docs/specs/audio-devices.md → docs/specs/audio/audio-devices.md

@@ -3,7 +3,7 @@ title: "Audio Device Abstraction"
 document_id: "audio-device-abstraction-2026-01-28"
 status: "draft"
 created: "2026-01-28T22:59:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.1.18"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/audio-file-loading.md → docs/specs/audio/audio-file-loading.md

@@ -3,7 +3,7 @@ title: "Audio File Loading (SoundBuffer)"
 document_id: "audio-file-loading-2026-01-31"
 status: "draft"
 created: "2026-01-31T22:07:49Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.3"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/depth-stencil-msaa.md → docs/specs/rendering/depth-stencil-msaa.md

@@ -3,7 +3,7 @@ title: "Depth/Stencil and Multi-Sample Rendering"
 document_id: "depth-stencil-msaa-2025-11-11"
 status: "draft"
 created: "2025-11-11T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.5.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/indexed-draws-and-multiple-vertex-buffers.md → docs/specs/rendering/indexed-draws-and-multiple-vertex-buffers.md

@@ -3,7 +3,7 @@ title: "Indexed Draws and Multiple Vertex Buffers"
 document_id: "indexed-draws-multiple-vertex-buffers-2025-11-22"
 status: "draft"
 created: "2025-11-22T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/instanced-rendering.md → docs/specs/rendering/instanced-rendering.md

@@ -3,7 +3,7 @@ title: "Instanced Rendering"
 document_id: "instanced-rendering-2025-11-23"
 status: "draft"
 created: "2025-11-23T00:00:00Z"
-last_updated: "2025-11-25T02:20:00Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.1.5"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/offscreen-render-targets-and-multipass.md → docs/specs/rendering/offscreen-render-targets-and-multipass.md

@@ -3,7 +3,7 @@ title: "Offscreen Render Targets and Multipass Rendering"
 document_id: "offscreen-render-targets-2025-11-25"
 status: "draft"
 created: "2025-11-25T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.6"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/textures-and-samplers.md → docs/specs/rendering/textures-and-samplers.md

@@ -3,7 +3,7 @@ title: "Textures and Samplers"
 document_id: "texture-sampler-spec-2025-10-30"
 status: "draft"
 created: "2025-10-30T00:00:00Z"
-last_updated: "2025-12-15T00:00:00Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.4.0"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/specs/uniform-buffers-and-bind-groups.md → docs/specs/rendering/uniform-buffers-and-bind-groups.md

@@ -3,7 +3,7 @@ title: "Uniform Buffers and Bind Groups"
 document_id: "ubo-spec-2025-10-11"
 status: "living"
 created: "2025-10-11T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.5.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
@@ -275,7 +275,7 @@ RC::SetBindGroup { set: 0, group: dyn_group_id, dynamic_offsets: offsets };
   - [x] Dynamic offset alignment/count checks — crates/lambda-rs/src/render/validation.rs
 - Performance
   - [x] Recommendations documented (this section)
-  - [x] Dynamic offsets example provided — docs/specs/uniform-buffers-and-bind-groups.md
+  - [x] Dynamic offsets example provided — docs/specs/rendering/uniform-buffers-and-bind-groups.md
 - Documentation and Examples
   - [x] Spec updated (this document)
   - [x] Example added — demos/render/src/bin/uniform_buffer_triangle.rs

docs/specs/component-event-handling.md → docs/specs/runtime/component-event-handling.md

@@ -3,7 +3,7 @@ title: "Component Event Handling"
 document_id: "component-event-handling-2026-01-10"
 status: "draft"
 created: "2026-01-10T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.1.2"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
@@ -214,10 +214,10 @@ winit event loop
   - [x] `Component` trait documentation updated (Ref:
     `docs/rendering.md`)
   - [x] Backwards compatibility assessed and migration documented (Ref:
-    `docs/specs/component-event-handling.md`)
+    `docs/specs/runtime/component-event-handling.md`)
 - Validation and Errors
   - [x] Error behavior specified for handler failures (Ref:
-    `docs/specs/component-event-handling.md`)
+    `docs/specs/runtime/component-event-handling.md`)
   - [x] Runtime publishes `RuntimeEvent::ComponentPanic` on handler errors
     (Ref: `crates/lambda-rs/src/runtimes/application.rs`)
 - Performance
@@ -231,7 +231,7 @@ winit event loop
   - [x] `docs/features.md` checked for relevance (no new features expected)
     (Ref: `docs/features.md`)
   - [x] Migration notes added to component documentation (Ref:
-    `docs/specs/component-event-handling.md`)
+    `docs/specs/runtime/component-event-handling.md`)
 
 For each checked item, include a reference to a commit, pull request, or file
 path that demonstrates the implementation.

docs/tutorials/README.md

@@ -3,8 +3,8 @@ title: "Tutorials Index"
 document_id: "tutorials-index-2025-10-17"
 status: "living"
 created: "2025-10-17T00:20:00Z"
-last_updated: "2026-01-05T00:00:00Z"
-version: "0.7.0"
+last_updated: "2026-02-07T00:00:00Z"
+version: "0.7.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"
 shader_backend_default: "naga"
@@ -17,19 +17,31 @@ tags: ["index", "tutorials", "docs"]
 
 This index lists tutorials that teach specific `lambda-rs` tasks through complete, incremental builds.
 
-- Basic Triangle: Vertex‑Only Draw — [basic-triangle.md](basic-triangle.md)
-- Immediates: Draw Multiple 2D Triangles — [immediates-multiple-triangles.md](immediates-multiple-triangles.md)
-- Uniform Buffers: Build a Spinning Triangle — [uniform-buffers.md](uniform-buffers.md)
-- Textured Quad: Sample a 2D Texture — [textured-quad.md](textured-quad.md)
-- Textured Cube: 3D Immediates + 2D Sampling — [textured-cube.md](textured-cube.md)
-- Offscreen Post: Render to a Texture and Sample to the Surface — [offscreen-post.md](offscreen-post.md)
-- Reflective Room: Stencil Masked Reflections with MSAA — [reflective-room.md](reflective-room.md)
-- Instanced Rendering: Grid of Colored Quads — [instanced-quads.md](instanced-quads.md)
+## Rendering
 
-Browse all tutorials in this directory.
+### Basics
+
+- Basic Triangle: Vertex‑Only Draw — [rendering/basics/basic-triangle.md](rendering/basics/basic-triangle.md)
+- Immediates: Draw Multiple 2D Triangles — [rendering/basics/immediates-multiple-triangles.md](rendering/basics/immediates-multiple-triangles.md)
+
+### GPU Resources
+
+- Uniform Buffers: Build a Spinning Triangle — [rendering/resources/uniform-buffers.md](rendering/resources/uniform-buffers.md)
+- Textured Quad: Sample a 2D Texture — [rendering/resources/textured-quad.md](rendering/resources/textured-quad.md)
+- Textured Cube: 3D Immediates + 2D Sampling — [rendering/resources/textured-cube.md](rendering/resources/textured-cube.md)
+
+### Techniques
+
+- Indexed Draws and Multiple Vertex Buffers — [rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md](rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md)
+- Instanced Rendering: Grid of Colored Quads — [rendering/techniques/instanced-quads.md](rendering/techniques/instanced-quads.md)
+- Offscreen Post: Render to a Texture and Sample to the Surface — [rendering/techniques/offscreen-post.md](rendering/techniques/offscreen-post.md)
+- Reflective Room: Stencil Masked Reflections with MSAA — [rendering/techniques/reflective-room.md](rendering/techniques/reflective-room.md)
+
+Browse all tutorials under `rendering/`.
 
 Changelog
 
+- 0.7.1 (2026-02-07): Group tutorials by feature area in the index.
 - 0.7.0 (2026-01-05): Rename push constants tutorial to immediates for wgpu v28; update metadata.
 - 0.6.0 (2025-12-29): Add offscreen post tutorial; update metadata and commit.
 - 0.5.0 (2025-12-16): Add basic triangle and multi-triangle push constants tutorials; update metadata and commit.

docs/tutorials/basic-triangle.md → docs/tutorials/rendering/basics/basic-triangle.md

@@ -3,7 +3,7 @@ title: "Basic Triangle: Vertex‑Only Draw"
 document_id: "basic-triangle-tutorial-2025-12-16"
 status: "draft"
 created: "2025-12-16T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"

docs/tutorials/immediates-multiple-triangles.md → docs/tutorials/rendering/basics/immediates-multiple-triangles.md

@@ -3,7 +3,7 @@ title: "Immediates: Draw Multiple 2D Triangles"
 document_id: "immediates-multiple-triangles-tutorial-2025-12-16"
 status: "draft"
 created: "2025-12-16T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"

docs/tutorials/textured-cube.md → docs/tutorials/rendering/resources/textured-cube.md

@@ -3,7 +3,7 @@ title: "Textured Cube: 3D Immediates + 2D Sampling"
 document_id: "textured-cube-tutorial-2025-11-10"
 status: "draft"
 created: "2025-11-10T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.3.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"

docs/tutorials/textured-quad.md → docs/tutorials/rendering/resources/textured-quad.md

@@ -3,7 +3,7 @@ title: "Textured Quad: Sample a 2D Texture"
 document_id: "textured-quad-tutorial-2025-11-01"
 status: "draft"
 created: "2025-11-01T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.4.2"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/tutorials/uniform-buffers.md → docs/tutorials/rendering/resources/uniform-buffers.md

@@ -3,7 +3,7 @@ title: "Uniform Buffers: Build a Spinning Triangle"
 document_id: "uniform-buffers-tutorial-2025-10-17"
 status: "draft"
 created: "2025-10-17T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.5.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/tutorials/indexed-draws-and-multiple-vertex-buffers.md → docs/tutorials/rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md

@@ -3,7 +3,7 @@ title: "Indexed Draws and Multiple Vertex Buffers"
 document_id: "indexed-draws-multiple-vertex-buffers-tutorial-2025-11-22"
 status: "draft"
 created: "2025-11-22T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.3.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/tutorials/instanced-quads.md → docs/tutorials/rendering/techniques/instanced-quads.md

@@ -3,7 +3,7 @@ title: "Instanced Rendering: Grid of Colored Quads"
 document_id: "instanced-quads-tutorial-2025-11-25"
 status: "draft"
 created: "2025-11-25T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/tutorials/offscreen-post.md → docs/tutorials/rendering/techniques/offscreen-post.md

@@ -3,7 +3,7 @@ title: "Offscreen Post: Render to a Texture and Sample to the Surface"
 document_id: "offscreen-post-tutorial-2025-12-29"
 status: "draft"
 created: "2025-12-29T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.2"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"

docs/tutorials/reflective-room.md → docs/tutorials/rendering/techniques/reflective-room.md

@@ -3,7 +3,7 @@ title: "Reflective Floor: Stencil‑Masked Planar Reflections"
 document_id: "reflective-room-tutorial-2025-11-17"
 status: "draft"
 created: "2025-11-17T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.4.5"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"