diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bde62d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# Onyx
+
+**Notch-Erweiterung für macOS.** Beim Überfahren der Notch fährt ein Panel mit
+eigenen Widgets aus — Kalender, Wetter, Medien, Hardware, Netzwerk, Audio-Mixer,
+Ablage und AirDrop.
+
+Zielgerät: MacBook Pro mit Apple Silicon, macOS 26+.
+
+---
+
+## Bauen
+
+```bash
+xcodegen generate # erzeugt Onyx.xcodeproj aus project.yml
+open Onyx.xcodeproj # dann ⌘R
+```
+
+Voraussetzungen: Xcode 26, [XcodeGen](https://github.com/yonaskolb/XcodeGen),
+Signierung mit Team `PP34X97WS3`.
+
+Tests laufen ohne Xcode:
+
+```bash
+cd Packages/OnyxKit && swift test
+```
+
+---
+
+## Aufbau
+
+Die Projektdefinition liegt als `project.yml` vor, nicht als handgepflegte
+`.xcodeproj` — so ist im Diff lesbar, was sich an den Build-Einstellungen ändert.
+
+```
+Onyx/ App-Target (nicht sandboxed, Hardened Runtime)
+Packages/OnyxKit/ Alle Module als lokales Swift-Package
+ OnyxCore Einzelinstanz-Sicherung
+ OnyxDesign Farben, Maße, Bewegung — einzige Quelle
+ OnyxNotch Panel-Fenster, Geometrie, Zustandsmaschine
+ OnyxWidgetKit Widget-Protokoll, Layout-Engine, Persistenz
+ OnyxMenuBar Modul-Protokoll für Menüleisten-Elemente
+ CalendarProvider EventKit (und später Calendarr)
+ WeatherProvider WeatherKit + CoreLocation
+ MediaProvider MediaRemote-Adapter, AppleScript, Medientasten
+Vendor/ Fremdcode im Quellzustand (siehe unten)
+Spikes/ Wegwerf-Werkzeuge zur API-Verifikation
+docs/spikes/ Was dabei herauskam — auch die Sackgassen
+```
+
+---
+
+## Entscheidungen, die man sonst für Fehler hält
+
+**Keine App-Sandbox.** Sie ist mit dem privilegierten Helper, mit IOKit und mit
+dem MediaRemote-Adapter unvereinbar. Der App-Group-Container für Calendarr
+bleibt trotzdem erreichbar — auf macOS ist er von der Sandbox unabhängig.
+Nachgemessen in [docs/spikes/D-appgroup.md](docs/spikes/D-appgroup.md).
+
+**TCC-Entitlements trotz fehlender Sandbox.** Bei aktivierter Hardened Runtime
+verlangt macOS `com.apple.security.personal-information.*` auch ohne Sandbox.
+Fehlt eine davon, erscheint der Berechtigungsdialog gar nicht erst — ohne
+Fehlermeldung. Das hat einen halben Abend gekostet:
+[docs/spikes/E-tcc-hardened-runtime.md](docs/spikes/E-tcc-hardened-runtime.md).
+
+**`ENABLE_DEBUG_DYLIB = NO`.** Xcode lagert im Debug-Build den Programmcode in
+eine eigene dylib aus. TCC ordnet Berechtigungsanfragen dann dem verbleibenden
+Rumpf zu, der weder Info.plist noch Entitlements trägt.
+
+**Eigenes Einstellungsfenster.** SwiftUIs `Settings`-Szene öffnet über einen
+privaten Selektor, der bei Apps ohne Menüleiste unzuverlässig ankommt.
+
+**Der MediaRemote-Adapter wird nicht gelinkt.** Er wird von `/usr/bin/perl`
+geladen, einem berechtigten Systemprogramm — im eigenen Prozess greift Apples
+Entitlement-Prüfung und es käme nichts an.
+
+---
+
+## Fremdcode
+
+`Vendor/mediaremote-adapter` — [ungive/mediaremote-adapter](https://github.com/ungive/mediaremote-adapter),
+BSD-3-Clause. Als Quellcode eingebettet und beim Bauen kompiliert, nicht als
+fertige Binary: so ist nachvollziehbar, was läuft. Stand siehe
+`ONYX-VERSION.txt`.
+
+---
+
+© 2026 Scarriffleservices
diff --git a/bright.svg b/bright.svg
new file mode 100644
index 0000000..1e04dc1
--- /dev/null
+++ b/bright.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/outline.svg b/outline.svg
new file mode 100644
index 0000000..b18fd6b
--- /dev/null
+++ b/outline.svg
@@ -0,0 +1,36 @@
+
+