diff --git a/README.md b/README.md
index ad77eb0..a4b086b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,23 @@
 # Atuin
 
-Shell History & Executable Runbooks
\ No newline at end of file
+Self-hosted shell-history synchronization and executable runbooks, backed by
+PostgreSQL.
+
+## Deployment layout
+
+- **Compose:** `/srv/docker/atuin/docker-compose.yml`
+- **Static configuration/source:** no additional mounted configuration
+- **Non-secret environment:** host, port, and registration policy are declared in Compose; there is no project-local `.env`
+- **Secrets:** `/srv/docker/secrets/atuin/.env`
+- **NVMe application state:** `/srv/appdata/atuin/postgres`
+- **Bulk HDD data:** none
+- **Other mounts:** none
+
+Secrets are never committed to this repository. The central secret environment
+is supplied to the Atuin server and PostgreSQL services.
+
+## Dependencies and recovery
+
+- **Networks/dependencies:** `atuin-server` depends on PostgreSQL, uses the external `npm_proxy` network at `192.168.98.16`, and shares the private `atuin_internal` network with PostgreSQL
+- **Back up:** `/srv/appdata/atuin/postgres` and the separately protected Atuin secret environment
+- **Re-creatable:** the Atuin container itself; no persistent cache is declared