diff --git a/README.md b/README.md
index 017a236..192bd79 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,53 @@
-get my home assistant token by 
+# home-assistant
 
-ha_token=$(pass show home-assistant/192.168.128.3/jm/api) # it asks me to touch the yubikey.
-server: 192.168.128.3
+Source of truth for the Home Assistant automations on the HA server at
+`192.168.128.3:8123`. The automations live in [`automations/`](automations/) as
+YAML and are deployed to HA over its REST config API with
+[`deploy.py`](deploy.py). HA is only a deploy target — it never reads these files
+directly. See [`AUTOMATIONS.md`](AUTOMATIONS.md) for the full spec (identity
+model, per-rule behavior, failure modes, changelog).
 
-I want you to add an automation to set the AC thermostat to 85 at 17:58, 90 at 17:59, 85 at 18:00, 90 at 18:01 and so on until 18:20
\ No newline at end of file
+## Access
+
+The HA API token is read from the shell environment:
+
+```bash
+source ~/.bashrc        # exports HA_API_KEY
+```
+
+The `README`'s original `pass show home-assistant/192.168.128.3/jm/api` route
+works interactively but requires a YubiKey touch and times out in
+non-interactive shells, so `HA_API_KEY` in `~/.bashrc` is the practical source.
+
+## Deploy
+
+```bash
+source ~/.bashrc
+python3 deploy.py --check     # parse only
+python3 deploy.py             # deploy all automations/*.yaml in place (by id)
+```
+
+## Remotes
+
+| Name | URL | Role |
+|---|---|---|
+| `origin` | `ssh://forgejo@forgejo.jmopines.com:2222/jm/home-assistant.git` | **primary** (fetch + push) |
+| `backup` | `git@github.com:jmtremblay2/home-assistant.git` | GitHub backup mirror (push only) |
+
+**`origin` is configured with two push URLs**, so a plain `git push` mirrors to
+**both** Forgejo and GitHub in one command — the GitHub backup stays current
+automatically. Fetches still come only from Forgejo.
+
+```bash
+git push                  # -> Forgejo AND GitHub (backup) together
+```
+
+The separate `backup` remote is kept for explicit/manual use (e.g.
+`git fetch backup`). To inspect the push targets: `git remote -v`. This
+auto-mirror is a local git config (`remote.origin.pushurl`), not stored in the
+repo, so it must be re-added after a fresh clone:
+
+```bash
+git remote set-url --add --push origin ssh://forgejo@forgejo.jmopines.com:2222/jm/home-assistant.git
+git remote set-url --add --push origin git@github.com:jmtremblay2/home-assistant.git
+```