diff --git a/README.md b/README.md
index af15b1c0..2817b322 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # Tx OS
 
 A bilingual (Arabic / English) internal "office OS" web platform. Single-tenant,
-self-hosted, designed to live behind a TLS-terminating reverse proxy on a
-private VPS or on-prem host.
+self-hosted, designed to run on any Linux server (cloud or on-prem) behind a
+TLS-terminating reverse proxy.
 
 The repo is a pnpm monorepo containing:
 
@@ -33,16 +33,68 @@ The repo is a pnpm monorepo containing:
 
 ---
 
-## Quick start (Docker)
+## Quick start
 
-The fastest path to a running stack on a Linux VPS with Docker installed.
+Two ready-made install scripts cover the common cases — pick the one that
+matches your machine. Both are idempotent (safe to re-run) and never delete
+existing data.
+
+### Option A — One-shot Docker install (recommended)
+
+For any Linux server with Docker + Docker Compose. Boots the full stack
+(Postgres, MinIO, API, SPA, Caddy edge) with a single command:
+
+```bash
+git clone <this-repo>
+cd tx-os
+./start.sh
+```
+
+`start.sh` will:
+
+1. Copy `.env.docker.example` → `.env` on first run (and pause so you can
+   edit secrets — at minimum `SESSION_SECRET`, `POSTGRES_PASSWORD`).
+2. Build the images, bring up the database + object storage, run migrations,
+   then start the API and web containers behind Caddy.
+3. Print the URLs you can reach the system on.
+
+After install, open the printed URL and the **first-time setup wizard** will
+let you create the admin account in the browser. (You can also pre-seed an
+admin by setting `SEED_ADMIN_PASSWORD` in `.env` before running.)
+
+### Option B — Local development with HTTPS (`mkcert`)
+
+For developers running the stack on their own laptop with trusted local
+certificates (so the SPA can talk to a real `https://tx.local`):
+
+```bash
+git clone <this-repo>
+cd tx-os
+./scripts/local-setup.sh
+```
+
+`local-setup.sh` will:
+
+1. Detect your OS / package manager and tell you how to install
+   [`mkcert`](https://github.com/FiloSottile/mkcert) if it's missing.
+2. Prompt for a local domain (default `tx.local`) and detect your LAN IP
+   (so phones / tablets on the same Wi-Fi can reach the system too).
+3. Generate a trusted local TLS certificate covering `localhost`, the
+   chosen domain, and the LAN IP.
+4. Bootstrap `.env` from `.env.example` (preserving any keys you've already
+   set), then bring the Docker stack up.
+
+### Manual Docker install (advanced)
+
+If you'd rather drive `docker compose` yourself:
 
 ```bash
 git clone <this-repo>
 cd tx-os
 cp .env.example .env
 # Edit .env — at minimum change SESSION_SECRET, POSTGRES_PASSWORD,
-# S3_SECRET_ACCESS_KEY, SEED_ADMIN_PASSWORD, SEED_USER_PASSWORD.
+# S3_SECRET_ACCESS_KEY. SEED_ADMIN_PASSWORD / SEED_USER_PASSWORD are
+# OPTIONAL — leave them blank to use the in-browser setup wizard.
 $EDITOR .env
 
 docker compose build