1 files changed, 27 insertions, 0 deletions
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..fa5d6ed
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,27 @@
+# Donut Documentation
+
+Deeper documentation for Donut, the real-time Schwarzschild black-hole renderer.
+The top-level [`README.md`](../README.md) is the overview; the two documents here
+go into how it actually works.
+
+- **[physics.md](physics.md)** — the physics and maths. Tracing light through
+  curved spacetime: the Schwarzschild metric, null geodesics and the equations of
+  motion, the numerical integrator and its adaptive step, the event horizon /
+  photon sphere / ISCO, the Novikov–Thorne accretion disk, gravitational and
+  Doppler redshift with relativistic beaming, and the observable quantities the
+  renderer can measure. Tied throughout to
+  [`assets/shaders/geodesic.slang`](../assets/shaders/geodesic.slang).
+
+- **[architecture.md](architecture.md)** — how the program is built. The code's
+  layering (Application / Scene / RenderPath / UILayer), the portable RHI that lets
+  the same rendering run on OpenGL and Vulkan, the frame loop, the unified
+  scene-and-simulation world, the rendering pipeline (progressive resolution,
+  supersampling, environment lighting, tone-mapping), the tabs, the export
+  pipeline, and the build system.
+
+For each pixel, Donut casts a ray from the camera and follows it backward through
+the curved spacetime around Sagittarius A\*. Rays that fall past the horizon are
+the shadow; rays that graze the photon sphere wind around it into the bright ring;
+rays that strike the hot orbiting disk pick up its shifted glow; rays that escape
+read the background sky. That trace is one GPU shader, fed by a small portable
+graphics layer so it runs identically on both backends.