diff --git a/desktop/README.md b/desktop/README.md
new file mode 100644
index 0000000..98c519e
--- /dev/null
+++ b/desktop/README.md
@@ -0,0 +1,71 @@
+```md
+# angelhome
+
+desktop app for angelhome
+
+`main.py` opens site in a locked qtwebengine browser instead of normal browser.
+
+## compatible with
+
+- linux
+- pyside6
+- qtwebengine
+
+### does
+
+- allows only the approved https host
+- blocks external navigation
+- blocks popups
+- blocks downloads
+- denies browser permission requests
+- rejects bad tls/certificate errors
+- keeps a single app instance
+- stores login/session data beside the app, keeps between restarts
+- logs startup/runtime errors
+
+### requirements
+
+install python packages:
+
+```bash
+pip install PySide6
+```
+
+### run with python
+
+```bash
+python3 main.py
+```
+
+or:
+
+```bash
+python main.py
+```
+
+## log output
+
+```text
+angelhome_data/logs/angelhome.out.log
+```
+
+## persistent data
+
+local app data is stored beside the script or bundled binary:
+
+```text
+angelhome_data/
+  logs/
+  runtime/
+  cache/
+  storage/
+```
+
+this is used for:
+
+- session persistence
+- cache
+- logs
+- runtime lock file
+
+```
\ No newline at end of file