diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ce4ede1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# Family Home Lab
+
+A self-hosted "home dash" and family toolkit that runs on our own network — a
+single place to reach every app we run, plus a private AI chat, media tools,
+storage and an audio transcriber.
+
+## What it is
+
+- **Console portal** — the front door at `https://console.lab.audasmedia.com.au`.
+  Log in and you get a dashboard ("home dash") with every service in tidy,
+  colour-coded groups, with a search box. It also has an **Admin** area
+  (users, passwords, the Pi task-board sessions).
+- **DeepSeek Harness (dsh)** — a private chat assistant for each family member
+  (sam / jo / harry / finn). It remembers conversations (shown in a sidebar),
+  can summarise web pages and documents, and can understand and generate images.
+  It is hardened so it cannot run system commands.
+- **Media tools** — browser-based editing apps: Photopea (images), KdenLive
+  (video), Audacity + LMMS (audio & music).
+- **Transcriber** — turns audio into MIDI (Basic Pitch) and full sheet music
+  (MuScriptor).
+- **Garage S3** — our object storage for your files (each person has a bucket).
+
+## Where things live
+
+| Kind | Location |
+|------|----------|
+| Source code | this repo (`family_home_lab`). Also pushed to Gitea: `sam/family_home_lab` |
+| Portal + core stack (Postgres, Redis, RabbitMQ, Garage, workers) | `.13` — `/home/sam/Docker/Containers/family-home-lab` |
+| dsh chat instances | `.13` — `/home/sam/Docker/Containers/dsh` (ports 3081–3084) |
+| Media tool containers | `.13` (behind `profile: tools`) |
+| Reverse proxy / Caddy + public sites | `.35` — `/Docker/Containers/caddy/Caddyfile` |
+| Data (garage, media, dsh, pi-dashboard) | `.13` — `/mnt/data/family-home-lab/` |
+
+## How you access it
+
+- Everything is reachable from the console: `https://console.lab.audasmedia.com.au`.
+- Public sites live under `*.lab.audasmedia.com.au`; LAN-only ones under `*.home.lab`.
+- Some apps are kept private behind **Caddy basic-auth** (e.g. the media tools,
+  which have no login of their own). Apps with their **own** login (Home
+  Assistant, Nextcloud, Immich, …) sign you in themselves.
+
+## A note about logins & passwords
+
+- **Never put real passwords or API keys in code.** Secrets live only in
+  `.env` files (git-ignored) on `.13`. This repo is safe to share.
+- Change your console password via the **Password** page in the portal.
+- If you rotate passwords, also update the matching `.env` values and any
+  Caddy basic-auth hash.
+
+## How to update / deploy
+
+```bash
+# 1. edit code, then record it in Gitea
+git add -A && git commit -m "change" && git push
+
+# 2. deploy the portal/core stack to .13
+scp -r portal sam@192.168.20.13:/home/sam/Docker/Containers/family-home-lab/
+ssh sam@192.168.20.13 'cd /home/sam/Docker/Containers/family-home-lab && docker compose up -d --build portal'
+
+# 3. deploy a dsh chat instance
+scp dsh/app.py dsh/templates/chat.html sam@192.168.20.13:/home/sam/Docker/Containers/dsh/
+ssh sam@192.168.20.13 'cd /home/sam/Docker/Containers/dsh && docker compose build && docker compose up -d'
+
+# 4. Caddy changes go on .35 (always back up Caddyfile first)
+```
+
+## Also worth knowing
+
+- Console accounts: `sam` (admin) plus `jo`, `harry`, `finn`.
+- Borg backup on `.13` already includes `/mnt/data/family-home-lab`.
+- The **Pi dashboard** admin page shows live agent sessions synced from the
+  pi host (see `deploy/pi-dash-sync.sh`; run it on a cron to keep it fresh).
+- Kids' accounts get a reduced view (no AI/chat, no admin-only items).
+
+See `docs/` for the website inventory, the audio plan, and the dsh plugin plan.
\ No newline at end of file