update claude guideline

CLAUDE.md

@@ -1,8 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Working principles
+
 1. Don't assume. Don't hide confusion. Surface tradeoffs.
 2. Minimum code that solves the problem. Nothing speculative.
 3. Touch only what you must. Clean up only your own mess.
 4. Define success criteria. Loop until verified.
 
-This project's hbd daemon is deployed and in production on host w02 
-under user 'nagios', which you can reach via ssh nagios@w02.
- The hbc client is used on 30 hosts in multiple networks.
+## Commands
+
+```bash
+# Run tests
+pytest -q                        # all tests
+pytest tests/test_threshold.py   # single file
+pytest -k test_name              # single test
+
+# Lint and type check
+tox -e lint     # flake8 over hbd/ and tests/
+tox -e mypy     # mypy over hbd/
+
+# Install for development
+pip install -e ".[all,dev]"
+
+# Run server
+python -m hbd.server.cli serve -c .hb.yaml -f -v
+
+# Generate a password hash
+hbd passwd <username>
+```
+
+Tests live in `tests/` (pytest, imported as a package). A second directory `test/` contains only TLS fixtures (`.pem` files), not test code.
+
+Line length: 111 characters (`black`, `flake8`, both configured).
+
+## Architecture
+
+The system has two components: `hbc` (client) and `hbd` (server), both in the `hbd` Python package.
+
+```
+hbd/
+  common/    # proto.py (encode/decode), utils.py
+  client/    # hbc: plugins/, main.py, config.py, plugin.py
+  server/    # hbd: all server modules
+```
+
+### Server module map
+
+| Module | Role |
+|---|---|
+| `cli.py` | Argument parsing, entry point, daemon startup |
+| `main.py` | Asyncio runtime: starts UDP, HTTP, WebSocket; pickle save/load |
+| `hbdclass.py` | `Host` and `Connection` domain objects; DNS queue |
+| `udp.py` | UDP datagram listener; processes `HTB` and `PLG` messages; sets/resets overdue timers |
+| `http.py` | aiohttp web server; all REST API routes (`/api/0/`) and page routes |
+| `ws.py` | WebSocket broadcast to connected dashboard clients |
+| `notify.py` | Notification dispatch (Pushover, email, Mattermost, Matrix, Signal, SMS); `eventlog()` is the single choke-point for all alert events |
+| `threshold.py` | Threshold evaluation against plugin metrics; state transitions (OK/WARNING/CRITICAL/UNKNOWN) |
+| `monitor.py` | Timer cleanup on shutdown (reachability is event-driven via timers in `udp.py`, not polled) |
+| `data.py` | Shared in-memory message ring buffer |
+| `journal.py` | JSONL message journal with size-based rotation |
+| `users.py` | Session management, password hashing (PBKDF2), role checks |
+| `config.py` | Config loading and defaults |
+| `configio.py` | Config file read/write via `ruamel.yaml` (preserves comments) |
+| `settings.py` | Settings sections for the web UI settings page |
+| `dns.py` | `nsupdate` integration for dynamic DNS |
+| `oauth.py` | OAuth2 login (Gitea) |
+
+### Key data flows
+
+**Heartbeat received:** `udp.py` decodes the `HTB` datagram → updates `Connection` state in `hbdclass.py` → resets overdue asyncio timer → broadcasts via `ws.py` → `notify.py` fires connectivity alerts on state change.
+
+**Plugin data received:** `udp.py` decodes `PLG` datagram → stores on `Host` → `threshold.py` evaluates against configured thresholds → `notify.py` fires threshold alerts on state transitions.
+
+**State persistence:** `Host.hosts` dict + `data.msgs` ring + active sessions are pickled every 5 minutes and on clean shutdown. Asyncio timers are stripped before pickling (`Connection.__getstate__`).
+
+**Config reload:** SIGHUP → `configio.py` re-reads YAML → live-updates hosts, thresholds, users, notification channels. Port/cert/pickle/journal changes require a full restart.
+
+### Client plugin system
+
+Plugins in `hbd/client/plugins/` subclass `InfoPlugin` (collected once, on demand) or `MonitorPlugin` (periodic). `initialize()` returns `False` to self-disable. Data is sent as `PLG` UDP messages.
+
+`hbc_mini.py` (scripts/) and `hbc_mini.c` (scripts/c/) are standalone single-file clients with no external dependencies.
+
+### Protocol
+
+All UDP messages: `!<ID>: <zlib-compressed key=value payload>`. Encoding in `hbd/common/proto.py`. Lists/dicts encoded as JSON with `@` prefix; booleans as `1`/`0`.
+
+### Web UI
+
+Jinja2 templates in `hbd/server/templates/`. Static assets in `hbd/server/static/`. Live pages (`/live`, `/plugins`) use WebSocket connections for real-time push.
+
+### CI
+
+Gitea Actions workflow at `.gitea/workflows/release.yml`.