diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..f6a79b4
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,48 @@
+# hiveops-guide — Design (approved 2026-06-30)
+
+One knowledge base that (a) teaches customers how each module works and (b) is the
+source-of-truth for module behavior (for admins + Claude). Markdown-authored, served by the
+backend API, read in a tabbed slide-out.
+
+## Decisions (Johannes, 2026-06-30)
+1. Content = **markdown files in git**, still served via **backend API calls** (not bundled in
+   the frontend).
+2. **Start over** — greenfield. No backward-compat with the old `content_json` guides or the
+   `/api/v1/guides/{pageKey}` contract; the Fleet "Guide" buttons get re-wired to the new API.
+3. **Retire the Guide Admin CRUD app.** The guide keeps **internal docs** (technical guides for
+   admins/Claude, `audience: internal`).
+
+## Content model — markdown in the repo
+`content/<app>/<module>/*.md` — folder per module, **one file per tab**. Frontmatter:
+```yaml
+---
+module: devices.sw-deploy
+title: Software Deployment
+tab: The Data          # the tab label in the slide-out
+order: 20              # tab order
+audience: customer     # or "internal" (hidden from customers)
+---
+<markdown body>
+```
+Cross-cutting technical guides: `content/technical/*.md` (e.g. fleet→Kafka→devices, service map).
+
+## Backend (Spring Boot service kept; model replaced)
+- Scans `content/**/*.md` at startup (cached), parses frontmatter + body.
+- API (JWT-gated):
+  - `GET /api/v1/guide/nav?audience=`            → apps → modules → tabs tree
+  - `GET /api/v1/guide/modules/{module}?audience=` → module + its tabs (markdown bodies)
+- Remove the DB `content_json` model + admin CRUD endpoints. `audience` gates customer vs internal.
+
+## Frontend
+- New **tabbed slide-out reader** (markdown rendered with `marked`); nav + tabs from the API.
+- Retire the Guide Admin CRUD app.
+
+## Consumers
+- Re-wire the Fleet "Guide" buttons (and future in-app guide entry points) to the new API.
+
+## Phases
+1. **Backend** — markdown content model + `nav`/`modules` API; retire DB/CRUD.
+2. **Frontend** — tabbed slide-out reader.
+3. **Content** — author `devices.sw-deploy` + `fleet.tasks` as the pattern (Overview / Data /
+   How-to + an internal Technical tab), then fan out to all modules.
+4. **Technical guides** (internal) — fleet→Kafka→devices, service map, etc.