home-hosted 0.2.0 → 0.4.0

package/README.md

@@ -6,52 +6,31 @@
 
 <sub>The harness for your servers.</sub>
 
-Point it at the things you run — a gateway, a media server, a bot, a database — and it
-starts them, watches them, restarts them when they die, and gives you one page to see
-what is actually going on. Or BYOU — [bring your own UI](#-bring-your-own-ui-byou), for a
-specialized panel that fits you exactly.
+Point it at the things you run — a gateway, a media server, a bot, a database — and it starts
+them, watches them, restarts what dies, and shows you one page of what is going on. Or
+[BYOU](#-bring-your-own-ui-byou), for a specialized UI that fits you exactly.
 
 [![npm](https://img.shields.io/npm/v/home-hosted.svg)](https://www.npmjs.com/package/home-hosted)
 [![Downloads](https://img.shields.io/npm/dm/home-hosted.svg)](https://www.npmjs.com/package/home-hosted)
+[![CI](https://github.com/NamesMT/home-hosted/actions/workflows/quickcheck.yml/badge.svg)](https://github.com/NamesMT/home-hosted/actions/workflows/quickcheck.yml)
 [![License](https://img.shields.io/npm/l/home-hosted.svg)](./LICENSE)
 [![Node](https://img.shields.io/node/v/home-hosted.svg)](https://nodejs.org)
 
-[🚀 Quick start](#-quick-start) · [✨ Features](#-features) · [🧩 Adding a server](#-adding-a-server) · [🛠 CLI](#-cli) · [🔐 Security](#-security) · [💾 Backups](#-backups)
+[🚀 Quick start](#-quick-start) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🧩 Servers](./SERVERS.md) · [🛠 CLI](#-cli) · [🔔 Notifications](./NOTIFICATIONS.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
 
 </div>
 
 ---
 
-## 🤔 Why?
-
-Running services on a home machine usually means one of two extremes: `tmux` sessions you
-forget about, or a hand-written systemd unit per service (times six).
+<div align="center">
 
-|  |  |
-| --- | --- |
-| ❌ **"Is it still running?"** | You check with `ps`, then `curl`, then hope. |
-| ❌ **Silent deaths** | Something crashes at 3am and you notice days later. |
-| ❌ **One terminal per service** | Logs scroll away in tabs you closed. |
-| ❌ **Fragile restarts** | The box reboots and half the stack is gone. |
-| ✅ **home-hosted** | Declare it once, watch it forever, one command to stop it all. |
+![Six views of the panel: the stock UI, the NOC-console, and UI examples](docs/media/tour.gif)
 
-```text
-                   ┌──────────────────────────────────────┐
-   your browser ──▶│  home-hosted  ·  127.0.0.1:3999      │
-                   │  Vue panel + JSON API + SSE logs     │
-                   └───────────────┬──────────────────────┘
-                                   │  supervises
-        ┌──────────────────────────┼──────────────────────────┐
-        ▼                          ▼                          ▼
-   ┌─────────┐               ┌─────────┐                ┌─────────┐
-   │ gateway │               │ files   │                │ bot     │
-   │ :4000   │               │ :4010   │                │  ...    │
-   └─────────┘               └─────────┘                └─────────┘
-     health ✓                  health ✓                  restarts ↻
-```
+<sub>The stock panel, the [NOC-console](./uis/noc-console) that ships alongside it (for TUI and
+shortcuts wizards), and UI directions you could build yourself —
+<a href="#-bring-your-own-ui-byou">BYOU</a>.</sub>
 
-It ships with **nothing**. No blessed paths, no "data directory" setting, no opinion about
-what you run — a server is a command, some arguments, and the environment you give it.
+</div>
 
 ---
 
@@ -60,10 +39,11 @@ what you run — a server is a command, some arguments, and the environment you
 ```bash
 npx home-hosted            # start it — detached, it stays running
 npx home-hosted status     # where is it, is it healthy
+# pnpm instead of npx: `pnpm dlx home-hosted …`
 ```
 
-That is it. The panel is on **<http://127.0.0.1:3999>**, and it keeps running after the
-terminal closes. Stop it whenever you like:
+That is it. The panel is on **<http://127.0.0.1:3999>** and keeps running after the terminal
+closes. <sub>Needs Node 24 or newer.</sub> Stop it whenever you like:
 
 ```bash
 npx home-hosted down       # stops the panel *and* everything it started
@@ -71,42 +51,34 @@ npx home-hosted down       # stops the panel *and* everything it started
 
 > [!NOTE]
 > The first boot writes a default password (`hh`) so the panel is never unprotected. Change
-> it under **Settings → Password** — binding beyond `127.0.0.1` stays refused until you do.
+> it under **Settings → Authentication** — binding beyond `127.0.0.1` stays refused until you do.
 
 <details>
 <summary><b>📦 Install it instead of npx-ing it</b></summary>
 
 ```bash
-npm install -g home-hosted
+npm install -g home-hosted      # or: pnpm add -g home-hosted
 home-hosted up
-
-# or keep a project with its own servers *and* its own state directory
-cd ~/my-servers
-HHOSTED_HOME=./state npx home-hosted up
 ```
 
-Before the first npm release, the same commands work from a checkout: `pnpm install && pnpm run up`
-in this repo, or `pnpm link` into a project that should depend on it.
-
-Everything home-hosted owns — config, secrets, logs, TLS, backups — lives in one directory:
-`$HHOSTED_HOME`, defaulting to `~/.home-hosted`. Delete it and nothing of yours is left behind.
+Everything it owns — config, secrets, logs, TLS, backups — lives in `$HHOSTED_HOME`, default
+`~/.home-hosted`. Delete that and nothing of yours is left behind.
 
 </details>
 
 <details>
-<summary><b>📁 Keep it in a project you can take anywhere (and share)</b></summary>
+<summary><b>📁 Keep a whole setup in a project you can take anywhere</b></summary>
 
-Pin the version, install the servers next to it, and commit the whole project — it *is* the
-setup:
+Commit the project and it *is* the setup. `init` scaffolds it:
 
 ```bash
-mkdir my-servers && cd my-servers
-npm init -y
-npm install home-hosted@0.2.0 9router serve      # pinned, so `git clone && npm ci` is enough
-
-npx home-hosted up --home ./state                 # state lives inside the project
+npx home-hosted init            # or: pnpm dlx home-hosted init
+#   project directory, package name, package manager, install, git — every step has a default
+#   `--yes` takes them all, for an agent or a CI job
 ```
 
+It writes a manifest whose scripts all pass `--home ./state`:
+
 ```jsonc
 // package.json
 {
@@ -114,19 +86,23 @@ npx home-hosted up --home ./state                 # state lives inside the proje
     "up": "home-hosted up --home ./state",
     "down": "home-hosted down --home ./state",
     "status": "home-hosted status --home ./state"
+    // …and restart, set-password, set-token, migrate
   }
 }
 ```
 
 ```gitignore
-state/*                 # secrets, logs, TLS keys and archives stay local…
-!state/servers.config.json   # …but the server definitions are committed
+node_modules/
+state/*                       # secrets, logs, TLS keys and archives stay local…
+!state/servers.config.json    # …but the server definitions are committed
+data/                         # per-server data directories, declared through dataEnvs
 ```
 
-<sub>Call them as `npm run up` — `npm up` is npm's own update, not your script.</sub>
+One clone, `pnpm install --frozen-lockfile`, `pnpm run up` — the setup is up on any machine with Node.
+Worked example, with per-server data inside the project:
+**[hhosted-9router-dsh](https://github.com/NamesMT/hhosted-9router-dsh)**.
 
-One clone, `npm ci`, `npm run up`, and the whole setup is up on any machine with Node.
-**Settings → Backups** exports the same thing as one archive for someone else to restore.
+<sub>Call them as `pnpm run up` — `pnpm up` is pnpm's own update, not your script.</sub>
 
 </details>
 
@@ -152,76 +128,101 @@ WantedBy=multi-user.target
 
 ---
 
+## 🤖 Agents, scripts and tools
+
+Everything the panel does, a script or an agent can do: the API takes a **long-lived token** in place
+of the browser cookie. One command for a credential, then plain HTTP to start, stop, inspect, restart
+and read logs.
+
+```bash
+home-hosted set-token --generate
+#   hh_9uA2…                     (printed once; only its hash is kept, mode 0600)
+
+curl -H "Authorization: Bearer hh_9uA2…" http://127.0.0.1:3999/api/state
+curl -H "Authorization: Bearer hh_9uA2…" -X POST http://127.0.0.1:3999/api/servers/9router/restart
+curl -N -H "Authorization: Bearer hh_9uA2…" 'http://127.0.0.1:3999/api/events?logs=1'   # SSE
+home-hosted status --json        # machine-readable: pid, url, health, paths
+```
+
+A token has the same authority as a signed-in browser and outlives restarts; `set-token --clear`
+revokes it instantly.
+
+<details>
+<summary><b>🌐 The endpoints worth knowing</b></summary>
+
+| | |
+| --- | --- |
+| `GET /api/state` | the full snapshot: config, live status, host vitals |
+| `GET /api/events` | SSE: the live state, plus logs (`?logs=0`, `?serverId=…`) |
+| `GET /api/servers/:id/stream` | SSE: one server's state and logs |
+| `POST /api/servers/:id/{start,stop,restart}` | lifecycle |
+| `POST /api/servers/:id/free-port` | ask whatever holds that server's port to stop |
+| `PATCH /api/servers/:id`, `PATCH /api/settings` | edit configuration |
+| `GET /api/logs`, `/api/backups`, `/api/notifications` | logs, archives, Telegram |
+| `GET /healthz` | no session needed — the one an external monitor wants (its per-server detail needs a credential) |
+| `GET /api/metrics` | Prometheus text |
+
+`GET /openapi/spec.json` describes all of it, `/openapi/ui` is the browsable version, and every error
+comes back as one envelope (`{ message, code, detail }`) with a stable `code` a tool can branch on.
+
+</details>
+
+<details>
+<summary><b>🧑‍💻 Pointing an agent at it</b></summary>
+
+Give the agent four things and it can run your home server without guessing:
+
+1. the token (`home-hosted set-token --generate`),
+2. `http://127.0.0.1:3999/openapi/spec.json` — the API it may call,
+3. `home-hosted status --json` — where things are,
+4. [SERVERS.md](./SERVERS.md) — how an entry is declared when it needs a new server.
+
+For a UI rather than the API, [UI_CREATION.md](./UI_CREATION.md) is the whole contract, and the panel
+can be told what to be: *"Help me build a UI for home-hosted: nostalgic game theme, including …"*.
+
+</details>
+
+---
+
 ## ✨ Features
 
 | | |
 | --- | --- |
 | 🚦 **Lifecycle** | Start, stop, restart from the panel or the API; `autostart` entries come up with it. |
 | ♻️ **Auto-restart** | Exponential backoff on crash, with the counter reset once a process stays up. |
-| 🩺 **Health that acts** | TCP or HTTP probes per server: warn on the card, force a restart after a timeout, and check ports before starting. |
+| 🩺 **Health that acts** | TCP or HTTP probes per server: warn on the card, force a restart after a timeout, check ports before starting — and [follow or replace](./SERVERS.md#when-a-program-restarts-itself) a program that restarts itself. |
 | 🔗 **Ordered startup** | `dependsOn` waits for a dependency to be *healthy* — not merely spawned — and stops in reverse. |
 | 📜 **Logs** | Live per-server stream, buffer plus rotated files on disk, search, download, one click to clear. |
 | 📈 **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 and host thresholds — [setup here](./NOTIFICATIONS.md). |
 | 💾 **Backups** | One click for config, secrets, TLS and your declared data directories — plain `.zip`, or AES-256 with a password, restored per path. |
-| 🚚 **Portable setup** | Restore a shared backup onto a blank instance and the whole server setup is back: definitions, data, secrets and all. |
-| 🎨 **BYOU — Bring Your Own UI** | The panel is a static site you can replace: upload your own build (or ship a whole alternative), and `home-hosted ui-revert` puts the stock one back. See [UI_CREATION.md](./UI_CREATION.md). |
-| 🔔 **Notifications** | Telegram (grammY) on crash, unhealthy, forced restart, recovery and host thresholds. |
-| 🔐 **Security** | httpOnly cookie sessions, scrypt hashes, per-IP lockout, optional TLS, and a refusal to expose itself without a password. |
-| 🧩 **Server-agnostic** | `command` + `args` + `env` + `cwd`. Nothing in the code knows what you run. |
+| 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `home-hosted ui-revert` to go back. [UI_CREATION.md](./UI_CREATION.md) |
+| 🔐 **Security** | Cookie sessions, API tokens, scrypt hashes, per-IP lockout, optional TLS, and a refusal to expose itself without a password. |
+| 🧩 **No special treatment** | A server is `command` + `args` + `env` + `cwd`; nothing is built in for any particular app. |
 | 🖥 **Cross-platform** | Linux, macOS and Windows: `/proc`, `ps` or Win32_Process, process groups or `taskkill /T`, no shell dependencies. |
 
 ---
 
-## 🧩 Adding a server
+## 🧩 Servers
 
-Use **➕ Add server** in the panel, or write it into `servers.config.json`:
+An entry is a few lines. Add one with **➕ Add server**, or write it into `servers.config.json`:
 
 ```json
 {
   "id": "myapp",
   "command": "node",
   "args": ["server.js"],
-  "cwd": "./apps/myapp",
   "port": 8080,
   "autostart": true,
-  "env": { "NODE_ENV": "production" },
-  "health": { "mode": "http", "http": { "path": "/healthz" } }
+  "dataEnvs": { "DATA_DIR": "{projectDir}/data/myapp" }
 }
 ```
 
-Relative paths resolve against the directory you ran `home-hosted` from, so a project can keep
-its servers and its state together:
-
-```bash
-cd ~/my-servers
-HHOSTED_HOME=./state npx home-hosted up
-```
-
-<details>
-<summary><b>🧾 Field reference</b></summary>
-
-| field | what it does |
-| --- | --- |
-| `command`, `args`, `cwd` | what to run, with `{placeholders}` resolved per entry |
-| `env`, `dataEnvs`, `envFile` | environment; `dataEnvs` also marks data directories for backups, `envFile` keeps secrets out of the config |
-| `port`, `bind` | enables the readiness wait, health checks and the conflict preflight; `local` keeps it on `127.0.0.1` |
-| `health.mode` | `port` (TCP connect) or `http` (path, expected status, expected body) |
-| `restart.*` | backoff: `maxRetries`, `baseDelayMs`, `factor`, `maxDelayMs`, `resetAfterMs` |
-| `stop.*` | signal, `killGroup`, grace period, and whether to sweep leftover port holders |
-| `dependsOn` | ids that must be healthy first; stopped in reverse order |
-| `resources.maxRssBytes` | restart when the process tree grows past a limit |
-| `bootstrap` | one command to run once before the first start (migrations, warmups) |
-| `backupPaths` | extra paths this entry owns, included in backups |
-
-Placeholders: `{id}` `{label}` `{port}` `{host}` `{displayHost}` `{bind}` `{lanIp}` `{cwd}`
-`{projectDir}` `{dataRoot}` `{home}`, plus `${VAR}` from the environment. Unknown placeholders
-stay visible instead of silently becoming empty.
-
-Every supervised process also gets `HHOSTED_SERVER_ID` and `HHOSTED_CONTROL_PORT`, so a
-service can tell which entry it is and how to reach the panel.
-
-</details>
+`dataEnvs` declares a data directory once: it is exported to the process *and* picked up by Backups.
+**Every field, every placeholder, the port-conflict policies (including adopting a server that
+restarts itself), and how hand-edits are validated: [SERVERS.md](./SERVERS.md).**
 
 ---
 
@@ -234,6 +235,9 @@ service can tell which entry it is and how to reach the panel.
 | `home-hosted restart` | `down`, then `up` |
 | `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
 | `home-hosted set-password` | set the panel password without opening a browser |
+| `home-hosted set-token` | set the API token scripts and agents use (`--generate`, `--clear`) |
+| `home-hosted migrate` | bring `servers.config.json` up to this release's schema (`--dry-run`, `--yes`) |
+| `home-hosted init` | scaffold a project that keeps `state/` and its data in the repo |
 | `home-hosted ui-revert` | go back to the stock panel UI after uploading your own |
 
 <details>
@@ -253,96 +257,107 @@ service can tell which entry it is and how to reach the panel.
 
 </details>
 
+<details>
+<summary><b>🧭 Upgrading, and why the panel sometimes refuses to start</b></summary>
+
+`servers.config.json` records what wrote it: `meta.writtenBy` (the release) and `meta.schema` (the
+config shape). That buys two guarantees:
+
+- **A newer home-hosted always reads an older config** — every existing key keeps its meaning.
+- **Keys a newer release added are ignored, not fatal.** The panel names them in its log, leaves them
+  in the file, and never resets the settings around them.
+
+What it will not do is run a config it cannot read. A wrong value, a duplicate id, an unreadable file
+or a config whose schema is newer than the running release stops `up` with the exact problem, rather
+than starting with defaults that quietly differ from your file. Fix the file, or install the release
+that wrote it.
+
+When a release changes the shape itself, `home-hosted migrate` applies the steps it ships:
+
+```bash
+home-hosted migrate --dry-run   # print the steps, write nothing
+home-hosted migrate             # ask, then write — keeps servers.config.json.bak
+```
+
+Unattended, consent comes from `--yes` or `HHOSTED_MIGRATE=allow`; without it the command stops.
+
+</details>
+
 ---
 
 ## 🔐 Security
 
 Everything binds `127.0.0.1` until you say otherwise.
 
-- **A password is required to expose the panel.** Replace the default, then bind to `lan` —
-  in the UI, in the config, or with `--host lan`. The same guard applies in all three places.
-- **Sessions** live in memory only; the cookie is `HttpOnly` and `SameSite=Strict`, and the
-  login route locks out repeated failures per IP.
-- **Secrets never enter the config**: the password hash, the Telegram token and the TLS key
-  live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`.
-- **Behind a proxy** turn on `trustProxy` and let `cookieSecure: auto` add `Secure` on https,
-  or upload a PEM pair and let home-hosted terminate TLS itself.
+- **A password is required to expose the panel.** Replace the default, then bind to `lan` — in the
+  UI, in the config, or with `--host lan`. The same guard applies in all three places.
+- **Sessions** live in memory only; the cookie is `HttpOnly` and `SameSite=Strict`, and the login
+  route locks out repeated failures per IP.
+- **API tokens** for scripts and agents: `home-hosted set-token --generate` prints one once, and a
+  request proves itself with `Authorization: Bearer …` — the same access as a signed-in browser,
+  stored as a SHA-256 hash, revoked with `set-token --clear`.
+- **Port conflicts** are named — `port 4010 is already in use (pid 4242)` — and can be resolved from
+  a confirmation popover on that banner or card. The process is looked up again at that moment,
+  never taken from the message, and anything the panel supervises is refused, not killed. A server
+  that [restarts itself](./SERVERS.md#when-a-program-restarts-itself) can be followed, or replaced
+  with a supervised copy.
+- **Secrets never enter the config**: the password hash, the API token hash, the Telegram bot token
+  and the TLS key live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`.
+- **Behind a proxy** turn on `trustProxy` and let `cookieSecure: auto` add `Secure` on https, or
+  upload a PEM pair and let home-hosted terminate TLS itself.
 
 ---
 
-## 💾 Backups
-
-**Settings → Backups** archives the config, the secrets file, the TLS pair and the data
-directories your entries declare — as an ordinary `.zip`:
+## 🔔 Notifications
 
-- no password → **plain zip**, openable by every operating system out of the box
-- with a password → **WinZip AES-256**, openable in 7-Zip, WinRAR, Keka, PeaZip, Ark…
-- restore is selective: check config, secrets, TLS or individual data paths, and nothing
-  else is touched
+Telegram, when something happens while you are not looking: a server that gave up restarting, a
+failing health check, a forced restart, a recovery, or a host threshold (disk, memory, swap, load,
+temperature). Opt-in, rate-limited per server *and* reason, and the bot token stays in the secrets
+file. **Two minutes of setup: [NOTIFICATIONS.md](./NOTIFICATIONS.md).**
 
-### 🚚 One archive is a whole setup
+---
 
-Start a **blank** home-hosted anywhere — another machine, another user, a fresh container —
-open **Settings → Backups**, upload the archive and restore: the server definitions come
-back, their data lands where *this* machine's config says it should, and the entries marked
-`autostart` are brought up right away. Nothing to re-declare by hand.
+## 💾 Backups
 
-That works because a backup carries its own `servers.config.json`, and paths are matched by
-the **declaration** (`9router:DATA_DIR`), not by the absolute path they had on the source
-machine — so `{home}` stays this user's home. A restore never writes anywhere a config does
-not declare: yours, or the one inside the archive you chose to restore.
+**Settings → Backups** archives the config, secrets, TLS pair and every data directory your entries
+declare — an ordinary `.zip`, or WinZip AES-256 with a password, restored per path.
 
 <details>
-<summary><b>🗂 Declaring data directories</b></summary>
+<summary><b>🚚 One archive is a whole setup</b></summary>
 
-```json
-{
-  "dataEnvs": { "DATA_DIR": "{home}/.myapp" },
-  "backupPaths": ["{home}/.myapp/uploads"]
-}
-```
+Start a **blank** home-hosted anywhere — another machine, another user, a fresh container — upload the
+archive and restore. Definitions come back, data lands where *this* machine's config says, and
+`autostart` entries come up immediately.
 
-`dataEnvs` is exported to the process *and* backed up, so a data directory is declared once.
-A path already covered by a declared parent is skipped.
+It works because an archive carries its own `servers.config.json` and paths are matched by the
+**declaration** (`9router:DATA_DIR`), not by an absolute path from the source machine. A restore never
+writes where no config declares.
 
 </details>
 
 ---
 
-Two UIs live in this repo: **stock** (the panel you get by default) and **noc-console**, an
-operations console over the same API. `pnpm run build:uis` builds and zips every one of them, and
-each release attaches them as `home-hosted-ui-<name>.zip` — install one from Settings → Interface.
-
 ## 🎨 Bring your own UI (BYOU)
 
-The panel is a static site served from `$HHOSTED_HOME/.ui` when one is installed, and from
-the package otherwise. **Settings → Interface** takes a zip; that is the whole install step,
-no restart and no fork.
+The panel is a static site: `$HHOSTED_HOME/.ui` overrides the packaged one, and **Settings →
+Interface** takes a zip. No restart, no fork — and `home-hosted ui-revert` brings back the stock
+panel if yours breaks.
 
-```bash
-home-hosted ui-revert     # if it breaks, the stock panel is one command away
-```
+Two ship in this repo: `uis/stock`, and `uis/noc-console` for TUI and shortcuts wizards; a release
+attaches both as `home-hosted-ui-<name>.zip`. Yours can be anything that compiles to static files —
+the server never cares what built it.
 
-The API is documented at `/openapi/ui` (and `/openapi/spec.json`), generated from the same
-schemas the server validates with, so a UI can be built in any framework — the stock one is
-just the first client. [UI_CREATION.md](./UI_CREATION.md) has the contract, the rules and a
-worked example.
+<details>
+<summary><b>🤖 Or have an agent build the UI you actually want</b></summary>
 
----
+The whole contract fits in one file, so a coding agent can do this. Point it at this repo and be
+specific:
 
-## 🌐 HTTP API
+> Help me build a UI for `home-hosted`: nostalgic game theme, including … features.
 
-The panel is a client of its own API, so everything is scriptable:
+[UI_CREATION.md](./UI_CREATION.md) has the endpoints, the SSE frames, the auth rules and a checklist.
 
-| | |
-| --- | --- |
-| `GET /api/state` | the full snapshot: config, live status, host vitals |
-| `GET /api/servers/:id/stream` | SSE stream of state and log lines |
-| `POST /api/servers/:id/{start,stop,restart}` | lifecycle |
-| `PATCH /api/servers/:id`, `PATCH /api/settings` | edit configuration |
-| `GET /api/logs`, `/api/backups`, `/api/notifications` | logs, archives, Telegram |
-| `GET /healthz` | no session needed — the one an external monitor wants |
-| `GET /api/metrics` | Prometheus text |
+</details>
 
 ---
 
@@ -365,9 +380,12 @@ the same way: every supervised process tree is stopped before the panel exits.
 </details>
 
 <details>
-<summary><b>Which ports does it use?</b></summary>
+<summary><b>Nothing starts and the port is busy</b></summary>
 
-Just the control panel, `3999` by default. Supervised servers use the ports you give them.
+A supervised server whose port is taken is reported rather than started over — the panel names the
+holder and offers to free it, and a program that restarts itself can be followed or reclaimed instead
+([SERVERS.md](./SERVERS.md#a-busy-port)). The control port itself is checked before the listener is
+opened.
 
 </details>
 
@@ -377,9 +395,9 @@ Just the control panel, `3999` by default. Supervised servers use the ports you
 `$HHOSTED_HOME`, default `~/.home-hosted`:
 
 ```text
-servers.config.json      your servers (the UI writes it back atomically)
+servers.config.json      your servers, plus meta: which release and schema wrote it
 servers.config.schema.json  regenerated on every start, for editor autocomplete
-.control-secrets.json    password hash + Telegram token (mode 0600)
+.control-secrets.json    password hash + API token hash + Telegram token (mode 0600)
 .logs/                   rotated per-server logs + history
 .tls/                    an uploaded PEM pair
 .backups/                zip archives
@@ -391,38 +409,49 @@ run.json                 the running panel (pid, url, token, mode 0600)
 </details>
 
 <details>
-<summary><b>Windows support, really?</b></summary>
+<summary><b>Which ports does it use?</b></summary>
 
-Yes. Process trees are sampled from Win32_Process, termination uses `taskkill /T`, and the
-shipped examples avoid POSIX-only commands. CPU temperature and swap are best-effort where the
-OS does not expose them to an unprivileged process.
+Just the control panel, `3999` by default. Supervised servers use the ports you give them.
 
 </details>
 
 <details>
-<summary><b>Nothing starts and the port is busy</b></summary>
+<summary><b>Windows support, really?</b></summary>
 
-A supervised server whose port is taken is reported rather than started over — the panel names
-the holder. The control port itself is checked before the listener is opened.
+Yes. Process trees are sampled from Win32_Process, termination uses `taskkill /T`, and the shipped
+examples avoid POSIX-only commands. CPU temperature and swap are best-effort where the OS does not
+expose them to an unprivileged process, and adopting a self-restarted process is Linux/macOS only.
 
 </details>
 
 ---
 
-## 🗂 Layout
+## 🗂 Working on it
 
 ```text
 src/            control plane: config, supervisor, API, providers, services
-src/cli.ts      the command line (up/down/status/restart/set-password)
+src/cli.ts      the command line (up/down/status/restart/set-password/set-token/migrate)
 src/index.ts    the control plane itself, used by `up --foreground`
-uis/            UIs: `stock` (shipped) and alternatives, each a Vite app
+uis/            UIs: `stock` (shipped) and alternatives — any framework, static output
 bin/            the published entry point
-vite.server.config.ts  bundles src/cli.ts into dist/cli.js
 ```
 
-Development: `pnpm dev` runs the panel with `tsx watch` plus the Vite dev server (state goes to
-`.dev-state/`), `pnpm build` produces `dist/` and `uis/stock/dist/`, `pnpm quickcheck` is lint plus
-types, and `pnpm test` is vitest.
+`pnpm dev` runs the panel with `tsx watch` plus the stock UI's dev server (state goes to
+`.dev-state/`); `pnpm build` produces `dist/` and `uis/stock/dist/`; `pnpm quickcheck` is lint plus
+types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
+
+<details>
+<summary><b>📚 The docs, and which one you want</b></summary>
+
+| file | for |
+| --- | --- |
+| [SERVERS.md](./SERVERS.md) | declaring a server: every field, placeholders, port conflicts |
+| [NOTIFICATIONS.md](./NOTIFICATIONS.md) | Telegram alerts, end to end |
+| [UI_CREATION.md](./UI_CREATION.md) | building a UI against the API |
+| [AGENTS.md](./AGENTS.md) | the architecture and the rules worth knowing before changing anything |
+| [/openapi/ui](http://127.0.0.1:3999/openapi/ui) | the live API, on your own panel |
+
+</details>
 
 ---