docs: add top-level README

Front-door for the repo. Pitches the project, surfaces known limitations
honestly (timeline not live, CTR not authenticated, no migrations), and
links into the three doc trees: home user guide, operator guide, and
architecture overview + 12 subsystem references.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,131 @@
+# Vigilar
+
+> DIY offline-first home security. Your cameras, your house, your data.
+
+Vigilar runs on a small mini PC in your home, records from your IP cameras,
+detects motion, and pushes notifications to your phone — with no cloud, no
+account, and no external service in the critical path.
+
+<!-- Screenshot placeholder: replace with a real UI grid shot when available. -->
+![Vigilar web UI grid view](docs/images/grid.png)
+
+## Why Vigilar
+
+- **Offline-first.** No cloud dependency. No external calls in the hot path.
+- **Multi-camera live view.** HLS grid for bandwidth efficiency, MJPEG single
+  view for low-latency focus.
+- **On-device motion detection.** OpenCV MOG2 with a 5-second pre-motion ring
+  buffer, so the run-up to a trigger is captured.
+- **Adaptive FPS.** Cameras idle at 2 FPS and jump to 30 FPS on motion.
+- **Event timeline and highlight reels.** Plus timelapses and visitor, pet,
+  and wildlife tracking as separate views.
+- **Phone push notifications.** PWA + VAPID web push. No Firebase, no
+  Google Cloud Messaging.
+- **Encrypted recordings at rest.** AES-256-CTR `.vge` files, key stays on
+  your box. (Confidential, not tamper-evident — see the
+  [Operator Guide](docs/operator-guide.md) for the details of the threat
+  model.)
+- **UPS aware.** NUT integration, graceful shutdown on critical battery.
+- **Runs on a cheap mini PC.** 4 GB RAM, 128 GB SSD, any modern x86_64 box.
+
+## Quick paths
+
+| I want to…                                   | Start here                                                   |
+|----------------------------------------------|--------------------------------------------------------------|
+| Set it up at home on a mini PC               | [Home User Guide](docs/home-user-guide.md)                   |
+| Run it as a self-hoster / sysadmin           | [Operator Guide](docs/operator-guide.md)                     |
+| Understand how it works internally           | [Architecture Overview](docs/architecture/overview.md)       |
+| Pick cameras that work well with it          | [Camera Hardware Guide](docs/camera-hardware-guide.md)       |
+
+## 60-second overview
+
+```
+   [IP cameras] ──RTSP──▶  [mini PC running Vigilar]  ──LAN──▶  [phone / browser]
+                                      │
+                                      └── optional nightly ──▶ [NAS]
+```
+
+- **Language:** Python 3.11+
+- **Web:** Flask + Bootstrap 5 dark + `hls.js`
+- **Storage:** SQLite (WAL) via SQLAlchemy Core
+- **Bus:** Local Mosquitto on `127.0.0.1:1883`
+- **Video:** OpenCV (capture + motion), FFmpeg subprocess (recording, HLS)
+
+## Status
+
+**Alpha.** Works on the author's hardware. Expect rough edges and breaking
+changes. Not recommended for anyone who cannot read a stack trace.
+
+Known limitations worth calling out up front:
+
+- The in-browser event timeline does not yet update live. Push
+  notifications to your phone work in real time; the timeline itself
+  needs a page refresh.
+- Recording encryption is AES-256-CTR: confidential at rest, but not
+  tamper-evident.
+- There is no automated database migration framework yet. Schema changes
+  are forward-only.
+
+See the [Operator Guide](docs/operator-guide.md) for the full list.
+
+## Installation (TL;DR)
+
+```bash
+git clone <repo URL> vigilar
+cd vigilar
+sudo ./scripts/install.sh
+sudo systemctl enable --now vigilar
+```
+
+Then open `http://<mini-pc-ip>:49735` on your LAN.
+
+For the full walkthrough (OS install, camera setup, PIN, push
+notifications, NAS backup), see the
+[Home User Guide](docs/home-user-guide.md).
+
+For configuration, CLI, secrets, backups, and upgrades, see the
+[Operator Guide](docs/operator-guide.md).
+
+## Documentation
+
+- **User guides**
+  - [Home User Guide](docs/home-user-guide.md) — mini PC to working cameras,
+    step by step.
+  - [Operator Guide](docs/operator-guide.md) — configuration, CLI, backups,
+    security, upgrades.
+  - [Camera Hardware Guide](docs/camera-hardware-guide.md) — picking and
+    wiring up cameras.
+- **Architecture**
+  - [Overview](docs/architecture/overview.md) — process model, MQTT bus,
+    data flow, storage layout.
+  - [Conventions](docs/architecture/conventions.md) — coding rules for
+    contributors.
+  - [Subsystems](docs/architecture/subsystems/) — one short reference per
+    subsystem: [camera](docs/architecture/subsystems/camera.md),
+    [detection](docs/architecture/subsystems/detection.md),
+    [events](docs/architecture/subsystems/events.md),
+    [alerts](docs/architecture/subsystems/alerts.md),
+    [sensors](docs/architecture/subsystems/sensors.md),
+    [ups](docs/architecture/subsystems/ups.md),
+    [storage](docs/architecture/subsystems/storage.md),
+    [highlights](docs/architecture/subsystems/highlights.md),
+    [presence](docs/architecture/subsystems/presence.md),
+    [pets](docs/architecture/subsystems/pets.md),
+    [health](docs/architecture/subsystems/health.md),
+    [web](docs/architecture/subsystems/web.md).
+
+## License
+
+Vigilar is distributed under the **GNU General Public License v3.0**. See
+`LICENSE` for the full text. (If the `LICENSE` file is not yet in the tree,
+it will be added in a follow-up.)
+
+## Contributing
+
+Issues and pull requests are welcome. Before sending a PR:
+
+- Read [`CLAUDE.md`](CLAUDE.md) for the project's code conventions, or the
+  human-friendly distillation at
+  [`docs/architecture/conventions.md`](docs/architecture/conventions.md).
+- Run `ruff check vigilar/` and `pytest` — both must pass.
+- Keep commits small and focused.