diff --git a/readme.md b/readme.md
index 8c19ffa..8cc664d 100644
--- a/readme.md
+++ b/readme.md
@@ -4,36 +4,86 @@ Experiment in digital autonomy
 
 Latest code is hosted on https://git.woodbine.nyc/micro/woodbine.nyc
 
-In general, everything is orchestrated by the compose files.
+If you are new to running your own websites, welcome!
 
-Sometimes, you will see a -setup service in the compose file.
-This usually runs a script that checks or generates secrets, and does initial configuration if needed.
+Note that a "service" is a fuzzy name for software that is expected to be always running.
+
+A simple web server (`python3 -m http.server`) could be a service, as could something like Gmail.
 
 ## Goals
 
-We hope this is understandable by a single individual, after learning a bit about docker compose and caddy.
+Understandable
+
+- a person should be able to adapt this to their community while learning the least amount of new concepts and technology
+- the person who set it up should not be needed to maintain the services
+
+Resiliant
+
+- services should work even when other parts of the web are not accessible
+
+Lean
+
+- we prefer lightweight software, which usually require less long-term maintenance
+
+## Decisions
+
+There are many other kinds of digital autonomy, but most people are used to the web.
+
+We hope to share our decision making here, so you can follow our thought process.
+
+### Decisions made for you
+
+These needs are required for anyone who wants to deploy **web-based** services.
+
+#### Auth
+
+We need a way for people to either register an account or sign in with an external account to use the services.
+
+After trying authelia, zitadel, authentik, and keycloak, got the furthest with zitadel.
+
+#### Web
+
+To host a webpage, you need some software that listens for http requests. We chose Caddy.
+
+If you would like to edit the webpage, either change the files in `./data/web/site/` directly, or you can connect via WebDAV and edit the file remotely via https://web.localhost.
 
-## setup
+#### Backup
+
+If you will be helping a community, its important to have backups and restore. We have two helper services, `backup-files` and `backup-database`.
+
+These use duplicity to backup to a backblaze instance, so you will need to setup that beforehand.
+
+#### Secrets
+
+We have two helper services for making sure secrets exist (`check-secrets`), or generating unique secrets for other services that need them (`generate-secrets`).
+
+---
+
+## getting started
+
+### setup
 
 Make a backblaze B2 account for backups. Add the secrets to ./secrets/backup/.
 
 Fill out env.template and make sure to pass it in the next command
 
-## running
+### running
+
+Helper scripts can be found in [the scripts directory](./scripts)
 
-We have two scripts in the `scripts/` directory - up and down
+To start 
 
     ./scripts/up
 
-To stop all the containers, you can ctrl+c, or 
+To stop, you can press ctrl+c, or in another terminal run
 
     ./scripts/down
 
-To generate secrets for all services
+To generate secrets for all services ahead-of-time
 
-    ./scripts/secrets
+    ./scripts/generate-secrets
 
-## port forwarding
+### port forwarding
 
 The caddy service expects to be able to bind to ports 80 and 443
 
@@ -42,7 +92,23 @@ One simple way is to allow unprivileged users access to these low ports
     echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee -a /etc/sysctl.conf
     sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80
 
-## alpha
+---
+
+## design
+
+All the services are defined by docker compose files.
+
+We provide `backup-files`, `backup-database`, `check-secrets`, and `generate-secrets` helper services.
+
+We have configured Caddy to import all files found in /etc/caddy.d/, so if you want to add a new service, you will need to make a small `Proxyfile` to tell caddy what subdomain to forward to what port.
+
+See [the services readme](./services/readme.md) for a guide on adding a new service.
+
+--- 
+
+## roadmap
+
+### alpha
 
 - [x] identity provider (zitadel)
 - [ ] single sign-on for webdav (one user per folder)
@@ -55,7 +121,7 @@ One simple way is to allow unprivileged users access to these low ports
 - [x] migrate from yaml to env for authelia config
 - [x] setup notifications via smtp
 
-## beta
+### beta
 
 - [ ] file restore
 - [ ] postgres restore
@@ -65,7 +131,7 @@ One simple way is to allow unprivileged users access to these low ports
 - [ ] mailing list (listmonk)
 - [ ] code forge (gitea or forgejo)
 
-## 0.1
+### 0.1
 
 - [ ] only expose 443, 587, 993
 - [ ] running on beta.woodbine.nyc