docs: refresh repo README and add component guides

docs/uptime-kuma/README.md

@@ -0,0 +1,90 @@
+# Uptime Kuma Push Client
+
+`kuma-push.sh` sends heartbeat updates to your Uptime Kuma instance by iterating through a JSON inventory of checks. It is built for guests that cannot be polled directly but can reach the Kuma push endpoint.
+
+## Files
+- `kuma-push.sh` – performs the checks and submits results via HTTP GET.
+- `kuma-checks.json` – declarative list of checks the script will execute.
+
+## Requirements
+- `bash`, `jq`, `wget`, and access to `https://status.jordanwages.com` (adjust `BASE` in the script if your Kuma lives elsewhere).
+- Optional: `systemd`, `cron`, or another scheduler to run the script every minute.
+
+## Configuration (`kuma-checks.json`)
+Each object in the array represents one Kuma monitor and should contain:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | ✔ | Human-friendly label shown inside Kuma. Sent back in the push message. |
+| `type` | ✔ | One of `native`, `http`, `service`, `docker`, `mount`, or `disk`. |
+| `push` | ✔ | Kuma push token for the monitor. |
+| `target` | ◐ | Interpreted per check type (URL, systemd service name, container name, mount path, or disk device). Not used for `native`. |
+| `threshold` | ◐ | Only used for `disk` checks. Marks the percentage usage at which the disk turns unhealthy. |
+
+Example:
+```json
+{
+  "name": "web_frontend",
+  "type": "http",
+  "target": "http://localhost:8080/health",
+  "push": "xxxxxxxxxxxxxxxx"
+}
+```
+
+## Check Types
+- **native**: Always reports `up`. Useful for “is the agent alive” checks.
+- **http**: Issues a `wget` to the target URL and reports `up` when the request succeeds. Ping time is the response time in ms.
+- **service**: Calls `systemctl is-active` on the target unit.
+- **docker**: Uses `docker inspect` to confirm the container is running.
+- **mount**: Uses `mountpoint -q` to verify the target path is mounted.
+- **disk**: Finds the mount that corresponds to the device (e.g. `vda5` or `/dev/sda1`) and reports `down` when usage meets/exceeds `threshold`.
+
+## Scheduling
+A one-minute cadence keeps Kuma happy without overwhelming it. Two common options:
+
+### systemd timer
+Create `/etc/systemd/system/kuma-push.service`:
+```ini
+[Unit]
+Description=Send Uptime Kuma push heartbeats
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/kuma-push.sh
+```
+
+Create `/etc/systemd/system/kuma-push.timer`:
+```ini
+[Unit]
+Description=Run Uptime Kuma push heartbeats every minute
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=1min
+AccuracySec=5s
+
+[Install]
+WantedBy=timers.target
+```
+
+Enable both:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now kuma-push.timer
+```
+
+### cron
+Copy the script into `/usr/local/bin` and drop the following into `crontab -e`:
+```
+* * * * * /usr/local/bin/kuma-push.sh >/dev/null 2>&1
+```
+
+## Customization Tips
+- Update the `BASE` variable inside `kuma-push.sh` if your Kuma origin or token path changes.
+- When `curl` is available you can swap `wget` for `curl` calls; the current implementation favours `wget` so the template can stay minimal.
+- Add jitter with the `sleep $(( RANDOM % 5 ))` line if you scale to dozens of VMs—feel free to widen the range.
+
+## Troubleshooting
+- **Missing dependencies**: install `jq` and `wget` (`apt install jq wget`). The script exits if either is missing.
+- **No pushes arriving**: confirm the machine reaches the Kuma endpoint manually with `wget`. Kuma will mark the monitor down automatically when pushes stop.
+- **Disk check always down**: ensure the `target` resolves to a mounted device (`lsblk -f` and `findmnt` help confirm the correct name).