diff --git a/DESIGN.md b/DESIGN.md
index 221c954..f1e636d 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -164,6 +164,14 @@ Brand: **Kontra** (centered masthead). Home section heading: **Topics** (not "By
 
 Reference implementation: `prototype/` (index.html, article.html, assets/kontra.css).
 
+## Media (implementation note)
+
+- Images are **git files beside their article**: `content/subjects/<s>/<slug>/<file>`.
+  Reference via `{{media:<slug>/<file>}}` (front-matter `image:` MUST be quoted —
+  `image: "{{media:slug/file.jpg}}"`). The app serves `/media/<path>` by searching
+  article folders (safe-path guarded). No S3/object store (Garage dropped 2026-09-10).
+- Hero image: grayscale plate per §Hero plate; leave `image: ""` for text-only pieces.
+
 ## Token wiring (for the theme)
 
 - Implement as CSS custom properties on `:root` (the design-token layer).