diff --git a/.gitignore b/.gitignore
index 8c2b884..ce8417c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,5 @@
 # Built Visual Studio Code Extensions
 *.vsix
 
+*.swp
+.DS_Store
diff --git a/README.md b/README.md
index 0663813..8ddae55 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,31 @@
-# homepage
+# Homepage
 
+Homepage provides a customizable homelab dashboard with service links, status widgets, and infrastructure
+integrations.
+
+## Deployment layout
+
+- **Compose:** `/srv/docker/homepage/docker-compose.yml`
+- **Static configuration/source:** `/srv/docker/homepage/config` for sanitized YAML, CSS, and JavaScript; `/
+srv/docker/homepage/images` for static dashboard images
+- **Non-secret environment:** allowed host `heimdall.lan` and IPv6 proxy disabling are declared inline in
+Compose
+- **Secrets:** `/srv/docker/secrets/homepage/.env`
+- **NVMe application state:** `/srv/appdata/homepage/logs` and `/srv/appdata/homepage/report`
+- **Bulk HDD data:** none
+- **Other mounts:** `/var/run/docker.sock` read-only for Docker integration and `/data/Data1` read-only for
+shared storage visibility
+
+Secrets are never committed to this repository. The central secret environment
+is supplied to the Homepage service; sanitized YAML configuration references
+its widget and integration credentials through `HOMEPAGE_VAR_*` placeholders.
+
+## Dependencies and recovery
+
+- **Networks/dependencies:** Homepage uses the external `npm_proxy` network at `192.168.96.11`; Docker
+integration depends on the read-only Docker socket, storage reporting can use the read-only `/data/Data1`
+mount, and configured widgets depend on their respective external services
+- **Back up:** `/srv/docker/homepage/config`, `/srv/docker/homepage/images`, and the separately protected
+Homepage secret environment
+- **Re-creatable:** the Homepage container image and `/srv/appdata/homepage/logs` and `/srv/appdata/homepage/
+report`