diff --git a/README.md b/README.md
index 6045fc1..2d18bee 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,87 @@
-# developer-portal
+# hightrusted Developer Portal
 
-hightrusted Developer Portal — gemeinsame Konventionen, Auth, Errors, Rate-Limits
\ No newline at end of file
+Gemeinsame Konventionen für alle hightrusted-APIs. Wer einen Endpoint von einem
+Modul nutzt, soll alle anderen Module ohne erneute Einarbeitung nutzen können.
+
+Hier dokumentieren wir, was **plattformweit** gilt — die produktspezifischen
+Endpoints stehen jeweils in der OpenAPI-Spec des Produkts (z.B.
+[`hightrusted-capture/openapi`](https://git.hightrusted.net/hightrusted-capture/openapi)).
+
+## Inhalt (geplant)
+
+- **`auth/`** — API-Key-Schema, OIDC-Anbindung, Sessions, Rotation, Widerruf
+- **`errors/`** — Einheitliche Fehler-Codes, HTTP-Status, `request_id`-Konzept
+- **`pagination/`** — Cursor-basierte Pagination, Limits, Sortierung
+- **`rate-limits/`** — `Retry-After`-Header, 429-Handling, Burst-Verhalten
+- **`webhooks/`** — Signatur-Verifikation, Retry-Policy, Idempotenz
+- **`ids/`** — Präfix-Schema (`cap_`, `sig_`, `usr_`, …), Format, Generierung
+- **`versioning/`** — Major-Versionen im Pfad, Breaking-Change-Policy, Deprecation
+- **`status/`** — Status-Page-Konventionen, Maintenance-Windows
+- **`sdk-conventions/`** — Was Klienten implementieren müssen (Retries, Timeouts, Logging)
+
+## Authentifizierung — Kurzfassung
+
+Alle hightrusted-APIs nutzen **Bearer-Token** mit API-Keys. Keys werden im jeweiligen
+Produkt-Dashboard erzeugt und sind produkt-scoped, d.h. ein CAPTURE-Key funktioniert
+nicht für SIGN.
+
+```http
+GET /api/v1/...
+Authorization: Bearer ht_live_abc123...
+```
+
+API-Key-Präfixe:
+
+- `ht_live_…` — Produktions-Key
+- `ht_test_…` — Sandbox-Key (kostenlos, ohne echte Wirkung)
+
+## Fehler-Format — Kurzfassung
+
+Einheitlich über alle APIs:
+
+```json
+{
+  "error": "invalid_argument",
+  "message": "URL is required",
+  "request_id": "req_01H...",
+  "documentation_url": "https://...errors#invalid_argument"
+}
+```
+
+Jede Antwort hat einen `X-Request-ID`-Header, den du beim Support angeben solltest.
+
+## Rate Limits — Kurzfassung
+
+Limits werden pro API-Key gemessen. Bei Überschreitung:
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 12
+```
+
+Konkrete Limits stehen in der jeweiligen Produkt-Doku.
+
+## Status der Plattform
+
+- **Live-Status:** https://status.hightrusted.net
+- **Inzident-History:** https://status.hightrusted.net/history
+- **Maintenance-Ankündigungen:** RSS-Feed auf der Status-Page
+
+## Verwandte Repositorys
+
+- [`platform`](https://git.hightrusted.net/hightrusted/platform) — Plattform-Übersicht, Architektur, Produkt-Liste
+- [`compliance`](https://git.hightrusted.net/hightrusted/compliance) — DSGVO, AGB-Templates, Whitepaper
+
+## Kontakt
+
+- **Developer-Support:** developers@hightrusted.net
+- **Sicherheit:** security@hightrusted.net
+
+## Lizenz
+
+MIT — siehe [LICENSE](./LICENSE). Konventionen dürfen frei nachgenutzt werden.
+
+---
+
+**hightrusted GmbH** — *The European Trust Infrastructure.*
+Made in Germany. DSGVO-nativ. eIDAS-konform.