diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2ef3cb02..b4a4ec10 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/README.md b/README.md
index 32bcfc63..31584b08 100644
--- a/README.md
+++ b/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
diff --git a/docs/specs/README.md b/docs/specs/README.md
new file mode 100644
index 00000000..1a9f7d88
--- /dev/null
+++ b/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)
diff --git a/docs/specs/_spec-template.md b/docs/specs/_spec-template.md
index a0dd6594..0f9d032e 100644
--- a/docs/specs/_spec-template.md
+++ b/docs/specs/_spec-template.md
@@ -17,6 +17,9 @@ tags: ["spec", ""]
#
+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.
diff --git a/docs/specs/audio-devices.md b/docs/specs/audio/audio-devices.md
similarity index 99%
rename from docs/specs/audio-devices.md
rename to docs/specs/audio/audio-devices.md
index 941ffa59..ff4b45db 100644
--- a/docs/specs/audio-devices.md
+++ b/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"
diff --git a/docs/specs/audio-file-loading.md b/docs/specs/audio/audio-file-loading.md
similarity index 99%
rename from docs/specs/audio-file-loading.md
rename to docs/specs/audio/audio-file-loading.md
index b7fed138..4b85b4a4 100644
--- a/docs/specs/audio-file-loading.md
+++ b/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"
diff --git a/docs/specs/depth-stencil-msaa.md b/docs/specs/rendering/depth-stencil-msaa.md
similarity index 99%
rename from docs/specs/depth-stencil-msaa.md
rename to docs/specs/rendering/depth-stencil-msaa.md
index 830c4caf..eef6095d 100644
--- a/docs/specs/depth-stencil-msaa.md
+++ b/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"
diff --git a/docs/specs/indexed-draws-and-multiple-vertex-buffers.md b/docs/specs/rendering/indexed-draws-and-multiple-vertex-buffers.md
similarity index 99%
rename from docs/specs/indexed-draws-and-multiple-vertex-buffers.md
rename to docs/specs/rendering/indexed-draws-and-multiple-vertex-buffers.md
index bbd3f28c..b93274b5 100644
--- a/docs/specs/indexed-draws-and-multiple-vertex-buffers.md
+++ b/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"
diff --git a/docs/specs/instanced-rendering.md b/docs/specs/rendering/instanced-rendering.md
similarity index 99%
rename from docs/specs/instanced-rendering.md
rename to docs/specs/rendering/instanced-rendering.md
index b62d9745..689d73a8 100644
--- a/docs/specs/instanced-rendering.md
+++ b/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"
diff --git a/docs/specs/offscreen-render-targets-and-multipass.md b/docs/specs/rendering/offscreen-render-targets-and-multipass.md
similarity index 99%
rename from docs/specs/offscreen-render-targets-and-multipass.md
rename to docs/specs/rendering/offscreen-render-targets-and-multipass.md
index 1341435c..63ee6510 100644
--- a/docs/specs/offscreen-render-targets-and-multipass.md
+++ b/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"
diff --git a/docs/specs/textures-and-samplers.md b/docs/specs/rendering/textures-and-samplers.md
similarity index 99%
rename from docs/specs/textures-and-samplers.md
rename to docs/specs/rendering/textures-and-samplers.md
index 2a42f1e6..3ec032a8 100644
--- a/docs/specs/textures-and-samplers.md
+++ b/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"
diff --git a/docs/specs/uniform-buffers-and-bind-groups.md b/docs/specs/rendering/uniform-buffers-and-bind-groups.md
similarity index 98%
rename from docs/specs/uniform-buffers-and-bind-groups.md
rename to docs/specs/rendering/uniform-buffers-and-bind-groups.md
index f61afc60..3d52e970 100644
--- a/docs/specs/uniform-buffers-and-bind-groups.md
+++ b/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
diff --git a/docs/specs/component-event-handling.md b/docs/specs/runtime/component-event-handling.md
similarity index 98%
rename from docs/specs/component-event-handling.md
rename to docs/specs/runtime/component-event-handling.md
index 08745517..f26313b0 100644
--- a/docs/specs/component-event-handling.md
+++ b/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.
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
index 00ef8016..e5d7b835 100644
--- a/docs/tutorials/README.md
+++ b/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.
diff --git a/docs/tutorials/basic-triangle.md b/docs/tutorials/rendering/basics/basic-triangle.md
similarity index 99%
rename from docs/tutorials/basic-triangle.md
rename to docs/tutorials/rendering/basics/basic-triangle.md
index e72e94dd..af38a8d7 100644
--- a/docs/tutorials/basic-triangle.md
+++ b/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"
diff --git a/docs/tutorials/immediates-multiple-triangles.md b/docs/tutorials/rendering/basics/immediates-multiple-triangles.md
similarity index 99%
rename from docs/tutorials/immediates-multiple-triangles.md
rename to docs/tutorials/rendering/basics/immediates-multiple-triangles.md
index f9442001..fff588c1 100644
--- a/docs/tutorials/immediates-multiple-triangles.md
+++ b/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"
diff --git a/docs/tutorials/textured-cube.md b/docs/tutorials/rendering/resources/textured-cube.md
similarity index 99%
rename from docs/tutorials/textured-cube.md
rename to docs/tutorials/rendering/resources/textured-cube.md
index b18c52fb..649e1eff 100644
--- a/docs/tutorials/textured-cube.md
+++ b/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"
diff --git a/docs/tutorials/textured-quad.md b/docs/tutorials/rendering/resources/textured-quad.md
similarity index 99%
rename from docs/tutorials/textured-quad.md
rename to docs/tutorials/rendering/resources/textured-quad.md
index 7207c8e8..f914ef5e 100644
--- a/docs/tutorials/textured-quad.md
+++ b/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"
diff --git a/docs/tutorials/uniform-buffers.md b/docs/tutorials/rendering/resources/uniform-buffers.md
similarity index 99%
rename from docs/tutorials/uniform-buffers.md
rename to docs/tutorials/rendering/resources/uniform-buffers.md
index e2b501e8..b28fd5ac 100644
--- a/docs/tutorials/uniform-buffers.md
+++ b/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"
diff --git a/docs/tutorials/indexed-draws-and-multiple-vertex-buffers.md b/docs/tutorials/rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md
similarity index 99%
rename from docs/tutorials/indexed-draws-and-multiple-vertex-buffers.md
rename to docs/tutorials/rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md
index 7e90591a..89383b36 100644
--- a/docs/tutorials/indexed-draws-and-multiple-vertex-buffers.md
+++ b/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"
diff --git a/docs/tutorials/instanced-quads.md b/docs/tutorials/rendering/techniques/instanced-quads.md
similarity index 99%
rename from docs/tutorials/instanced-quads.md
rename to docs/tutorials/rendering/techniques/instanced-quads.md
index 597ac882..89f0f49b 100644
--- a/docs/tutorials/instanced-quads.md
+++ b/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"
diff --git a/docs/tutorials/offscreen-post.md b/docs/tutorials/rendering/techniques/offscreen-post.md
similarity index 99%
rename from docs/tutorials/offscreen-post.md
rename to docs/tutorials/rendering/techniques/offscreen-post.md
index 6ba247c2..5ff8112f 100644
--- a/docs/tutorials/offscreen-post.md
+++ b/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"
diff --git a/docs/tutorials/reflective-room.md b/docs/tutorials/rendering/techniques/reflective-room.md
similarity index 99%
rename from docs/tutorials/reflective-room.md
rename to docs/tutorials/rendering/techniques/reflective-room.md
index f36b9580..088fcca1 100644
--- a/docs/tutorials/reflective-room.md
+++ b/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"