diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..df25914
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,10 @@
+# Agent Notes
+
+This project is expected to run locally using split systemd user services:
+
+- `pi-web-sessiond.service` runs `npm run start:sessiond` in non-autoreload, non-auto-restart mode.
+- `pi-web-ui-dev.service` runs the web/API and Vite UI in dev autoreload mode with `npm run dev:web` and `npm run dev:client`.
+
+When working on this project, assume the session runtime owner is long-lived and separate from the autoreloading UI/API process. Browser disconnects and UI/API restarts should not stop active Pi sessions.
+
+If you make changes that affect `src/server/sessiond.ts`, session runtime ownership, the session daemon protocol, or any code path only loaded by the session daemon, inform the user that `pi-web-sessiond.service` must be manually restarted. Changes to the web/API/UI side generally only require the `pi-web-ui-dev.service` autoreload/restart path.
diff --git a/README.md b/README.md
index 61a9f78..b944464 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,64 @@ npm run dev:client
 
 Then restart `dev:web` or `dev:client` freely; active Pi sessions continue in `dev:sessiond`.
 
+### systemd user services for local development
+
+This repository is commonly run as two systemd user services:
+
+- `pi-web-sessiond.service`: runs `npm run start:sessiond` without autoreload or automatic restart.
+- `pi-web-ui-dev.service`: runs `npm run dev:web` and `npm run dev:client` together, giving backend autoreload via `tsx watch` and Vite UI HMR.
+
+Example units live in `~/.config/systemd/user/` on the development host:
+
+```ini
+# ~/.config/systemd/user/pi-web-sessiond.service
+[Unit]
+Description=Pi Web session daemon
+
+[Service]
+Type=simple
+WorkingDirectory=/srv/dev/pi-web
+ExecStart=/bin/bash -lc 'exec npm run start:sessiond'
+Restart=no
+
+[Install]
+WantedBy=default.target
+```
+
+```ini
+# ~/.config/systemd/user/pi-web-ui-dev.service
+[Unit]
+Description=Pi Web UI dev server
+After=pi-web-sessiond.service
+Wants=pi-web-sessiond.service
+
+[Service]
+Type=simple
+WorkingDirectory=/srv/dev/pi-web
+ExecStart=/bin/bash -lc 'trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait'
+Restart=no
+
+[Install]
+WantedBy=default.target
+```
+
+After creating or changing units:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now pi-web-sessiond.service
+systemctl --user enable --now pi-web-ui-dev.service
+```
+
+Useful logs:
+
+```bash
+journalctl --user -u pi-web-sessiond.service -f
+journalctl --user -u pi-web-ui-dev.service -f
+```
+
+Because `sessiond` is intentionally not watched or restarted automatically, code changes that affect `src/server/sessiond.ts` or session runtime ownership require manually restarting `pi-web-sessiond.service`. Restarting only the UI dev service is enough for changes in the web/API/UI processes.
+
 For deployment:
 
 ```bash