docs: append S9-S11, add README and TROUBLESHOOTING

docs/01-rainbow-triangle.md

@@ -1255,3 +1255,96 @@ succession. `surface.configure()` is fast enough to handle this — each call
 discards old buffers and allocates new ones. The GPU continues processing
 in-flight frames with the old buffer dimensions; there is no visual glitch
 because the swapchain handles the transition seamlessly.
+
+## S9: Where All the Code Goes
+
+The full source is the codeblocks in sections S2–S8, assembled in order into
+`src/main.rs` and `src/shader.wgsl`.
+
+### File Structure
+
+```
+src/
+├── main.rs          # Sections S2, S3, S5 (structs), S7 (render), S8 (resize)
+├── shader.wgsl      # Section S4 (the complete WGSL shader)
+```
+
+- `main.rs` combines the winit event loop (S2), the init chain and `State`
+  struct (S3), the `Vertex` type and `VERTICES` constant (S5), the `render`
+  method (S7), and the `resize` method (S8).
+- `shader.wgsl` is the single file from S4: vertex shader, fragment shader,
+  and the `VertexOutput` struct.
+
+Refer to [concepts/GLOSSARY.md](concepts/GLOSSARY.md) for term definitions used
+throughout these sections. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for
+common issues and their fixes.
+
+## S10: Running It
+
+Run the project:
+
+```bash
+cargo run
+```
+
+**Expected console output:** wgpu adapter info (GPU model, driver name), shader
+module compilation log, pipeline creation messages, and the `simple_logger`
+debug lines from surface status and device polling.
+
+**Expected visual:** A dark gray background (from `LoadOp::Clear`) with a
+rainbow triangle spanning most of the window. Red at the bottom-left corner,
+blue at the bottom-right corner, green at the top vertex. Colors blend smoothly
+across the triangle surface via hardware interpolation.
+
+**Expected CPU usage:** 100% on one core due to `ControlFlow::Poll` driving a
+continuous redraw loop. This is normal for a demo that redraws every vsync.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues.
+
+## S11: What You've Learned and What's Next
+
+### Summary
+
+You have built a complete GPU-rendered application from scratch. Here is what
+each piece does:
+
+- **The 5-layer wgpu [init chain](concepts/GLOSSARY.md#instance):**
+  [Instance](concepts/GLOSSARY.md#instance) →
+  [Surface](concepts/GLOSSARY.md#surface) →
+  [Adapter](concepts/GLOSSARY.md#adapter) →
+  [Device](concepts/GLOSSARY.md#device) + [Queue](concepts/GLOSSARY.md#queue) →
+  [SurfaceConfiguration](concepts/GLOSSARY.md#surface-configuration).
+  Each layer adds a capability: driver connection, window binding, GPU selection,
+  resource management, and swapchain allocation.
+
+- **The [render pipeline](concepts/GLOSSARY.md#pipeline-render):** Shaders,
+  topology, and vertex layout compiled into a GPU configuration. Created once,
+  reused every frame. Expensive to create, cheap to execute.
+
+- **The [command buffer](concepts/GLOSSARY.md#command-buffer) model:** Record
+  instructions on the CPU, submit atomically to the queue, GPU executes
+  asynchronously. No `.await` on a draw call.
+
+- **The [swapchain](concepts/GLOSSARY.md#swapchain) and
+  [framebuffer](concepts/GLOSSARY.md#framebuffer):** Double-buffered rendering
+  through [PresentMode::Mailbox](concepts/GLOSSARY.md#present-mode). Acquire a
+  back buffer, render into it, present it to the display.
+
+- **GPU [interpolation](concepts/GLOSSARY.md#interpolation):** Vertex attributes
+  automatically blended across triangle surfaces. You supply values at three
+  points; the rasterizer computes every value in between.
+
+### What's Next
+
+With the render loop and pipeline foundation in place, the next steps are:
+
+- **Textures and [bind groups](concepts/GLOSSARY.md#bind-group)** — loading
+  images onto the GPU and sampling them in fragment shaders
+- **Uniforms and 3D transforms** — projection, view, and model matrices for
+  positioning geometry in 3D space
+- **Lighting and material models** — diffuse, specular, and PBR shading
+- **Depth buffering and z-fighting** — per-pixel depth testing for correct
+  overlap ordering
+- **[Compute shaders](concepts/GLOSSARY.md#compute-shader) and GPU compute
+  pipelines** — general-purpose GPU computation outside the graphics pipeline
+
+Keep [concepts/GLOSSARY.md](concepts/GLOSSARY.md) handy as you move forward.