home-hosted 0.8.3 → 0.9.0

package/AGENTS.md

@@ -10,8 +10,8 @@ level: `settings.json` (listener, auth, TLS policy, host vitals, backups, revers
 `.ui/`, `.logs/` (the panel console), `.proxy/` (the engine, its generated config and nanny state), and
 `run.json` (the live daemon's pid/url/token, 0600). Every workspace owns `.hh/<id>/`: `settings.json`
 (server defaults, log retention, notifications, DDNS), `servers.config.json`, `.secrets.json` (0600:
-Telegram token, plus DDNS credentials sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET` — only DDNS
-is sealed, because it is the one thing replayed to a third party), `.logs/` (per server, `<id>.log`
+Telegram bot tokens, one per destination, plus DDNS credentials sealed with AES-256-GCM under
+`HHOSTED_DDNS_SECRET` — only DDNS is sealed, because it is the one thing replayed to a third party), `.logs/` (per server, `<id>.log`
 plus `<id>.log.1` when it rotates), and `.state/` (nanny state, its 0600 spawn spec until read,
 `ddns.json`). A home still on the 0.6.x layout is **refused** by `ensureLayout()`, which names the file
 and tells the person to install the latest 0.7.x; 0.8.0 does not relocate it. **The package ships no
@@ -39,7 +39,7 @@ Where knowledge lives, and when to reach for each:
 | [`.agentDocs/COMPATIBILITY.md`](.agentDocs/COMPATIBILITY.md) | config and UI compatibility, migrations |
 | [`.agentDocs/RELEASING.md`](.agentDocs/RELEASING.md) | how a release is cut, and which version to dispatch |
 | [`docs/SERVERS.md`](docs/SERVERS.md) | entries, port conflicts, persistent entries |
-| [`docs/NOTIFICATIONS.md`](docs/NOTIFICATIONS.md) | Telegram events |
+| [`docs/NOTIFICATIONS.md`](docs/NOTIFICATIONS.md) | notification destinations: Telegram, webhooks, shared defaults |
 | [`docs/DDNS.md`](docs/DDNS.md) | dynamic-DNS providers and hostnames |
 | [`docs/REVERSE_PROXY.md`](docs/REVERSE_PROXY.md) | the Caddy engine, routes, certificates |
 | [`docs/UI_CREATION.md`](docs/UI_CREATION.md) | the contract for a new UI |
@@ -56,6 +56,8 @@ pnpm run start                     # up --foreground (systemd, docker, a foregro
 pnpm exec tsx src/cli.ts logs      # the panel's own console output (--lines, --follow, --json)
 pnpm dev                           # tsx-watch panel :6000 + the stock UI's Vite :6001, state in .dev-state/
 pnpm dev --ui noc-console          # the same, for another UI; --port/--ui-port override
+pnpm dev --home /tmp/hh-dev        # state elsewhere; HHOSTED_HOME is IGNORED here, and the real
+                                   #   ~/.home-hosted is refused. Dev password: `dev`
 pnpm run build                     # dist/cli.js + the stock UI (uis/stock/dist)
 pnpm run build:uis                 # every UI under uis/, zipped into uis/dist/ (release assets)
 pnpm run build:locales             # i18n/sheets/*.csv -> the git-ignored i18n/generated/*.json (also
@@ -69,7 +71,8 @@ pnpm run set-password              # non-interactive through HHOSTED_PASSWORD
 pnpm run set-token                 # --generate prints a new API token once
 pnpm run migrate                   # bring the config up to this release's schema
 pnpm exec tsx src/cli.ts init      # scaffold a project (interactive; --yes for defaults)
-pnpm run media                     # regenerate docs/media (mockups, both served UIs, tour.gif)
+pnpm run media                     # regenerate docs/media; needs `pnpm exec playwright install chromium`
+                                   #   once (browser only; `gif` alone does not)
 ```
 
 The published bin is `home-hosted`, with an `hh` alias: both names run the same CLI.
@@ -128,7 +131,8 @@ These prevent defects if broken. The *why* for the non-obvious ones is in
   **refuses** a commit that changed a shipped UI without raising it (a UI's `test/` and its own
   `README.md` are exempt — neither is in the built asset).
   `src/shared/**` is a UI build input, so a runtime contract needs the bump too — the hook does not
-  inspect that commit.
+  inspect that commit. **`tag` and `unix` are build provenance**, stamped into `dist/ui.json` by
+  `build-uis.mjs`; never committed to `public/ui.json`.
 - **Paths.** `dataRoot` is state, under `dataRoot/.hh`; `projectDir` is the base for relative entry
   paths. `{…}` and `${ENV}` expand in config — the full list is the table in
   [`docs/SERVERS.md`](docs/SERVERS.md), which is what to keep in step. No package-relative state.

package/README.md

@@ -277,7 +277,7 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 📈 **Resources** | CPU and RSS of the whole process tree, with an optional memory ceiling that triggers a restart. |
 | 🌡️ **Host vitals** | Load, memory, swap, disk and CPU temperature, with thresholds that notify once and again on recovery. |
 | 🤖 **Token API** | Scripts and agents drive it with `Authorization: Bearer` — no browser, no session. [↑](#-agents-scripts-and-tools) |
-| 🔔 **Notifications** | Telegram on crash, unhealthy, forced restart, recovery, host thresholds and DNS changes — [setup here](./docs/NOTIFICATIONS.md). |
+| 🔔 **Notifications** | One list of **destinations** — Telegram chats and webhooks (ntfy, Discord, Slack, your own endpoint) — on crash, unhealthy, forced restart, recovery, host thresholds and DNS changes. The event toggles and throttle are set once, and each destination may inherit them or carry its own. [Setup here](./docs/NOTIFICATIONS.md). |
 | 🌐 **Dynamic DNS** | Keep hostnames pointed at your public IP — Cloudflare, Namecheap, Spaceship, Porkbun, GoDaddy, Gandi and more. [DDNS.md](./docs/DDNS.md) |
 | 🔀 **Reverse proxy** | One engine in front of everything, with automatic HTTPS: `git.example.com` → a Gitea entry, `media.example.com` → a service on another box, `panel.example.com` → the panel. Caddy, installed and supervised by the panel. [REVERSE_PROXY.md](./docs/REVERSE_PROXY.md) |
 | 💾 **Backups** | Global settings, TLS, workspaces, and inside each one its settings, servers, secrets and declared data — plain `.zip`, or AES-256 with a password. Each secret is picked separately, and a restore can be customized. |
@@ -467,10 +467,15 @@ Everything binds `127.0.0.1` until you say otherwise.
 
 ## 🔔 Notifications
 
-Telegram, when something happens while you are not looking: a server that gave up restarting, a
+A message when something happens while you are not looking: a server that gave up restarting, a
 failing health check, a forced restart, a recovery, a host threshold (disk, memory, swap, load,
-temperature), or a dynamic DNS change. Opt-in, rate-limited per server *and* reason, and the bot token
-stays in the secrets file. **Two minutes of setup: [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md).**
+temperature), or a dynamic DNS change.
+
+Every alert goes to a list of **destinations** — a Telegram chat, a webhook, or several of each. The
+event toggles and the throttle are set **once**, and each destination either inherits them or carries
+its own. Rate-limited per destination, server *and* reason. Bot tokens and webhook credentials stay in
+the secrets file, never in a config. **Two minutes of setup:
+[NOTIFICATIONS.md](./docs/NOTIFICATIONS.md).**
 
 ---
 
@@ -495,6 +500,12 @@ ordinary `.zip`, or WinZip AES-256 with a password, restored per path. Known bui
 dependency directories (`node_modules`, `dist`, `.next`, framework caches) are skipped per entry;
 `backupIgnoreGenerated: false` captures them anyway.
 
+**Automatic backups** write one archive on a schedule you set — the page asks in hours; the config
+stores `intervalMs` — with a retention of its own (`Keep automatic`). The two counts are independent: `Keep` bounds the archives you take by hand,
+and a scheduled pass never prunes one of yours to make room for its own. Both live in the same
+directory, and an automatic archive is named `auto-…` so you can tell them apart — a name you drop
+in by hand with that prefix is treated as one, so do not use it.
+
 <details>
 <summary><b>🔑 Restoring a secret</b></summary>
 
@@ -690,7 +701,7 @@ plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 | if you want to… | read |
 | --- | --- |
 | declare a server: every field, placeholders, port conflicts | [SERVERS.md](./docs/SERVERS.md) |
-| get Telegram alerts working end to end | [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md) |
+| get Telegram or webhook alerts working end to end | [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md) |
 | expose the stack behind one hostname, with HTTPS | [REVERSE_PROXY.md](./docs/REVERSE_PROXY.md) |
 | build a UI against the API | [UI_CREATION.md](./docs/UI_CREATION.md) |
 | change the internals: architecture and the rules | [AGENTS.md](./AGENTS.md) |