home-hosted 0.3.0 → 0.4.1

package/README.md

@@ -16,7 +16,7 @@ them, watches them, restarts what dies, and shows you one page of what is going
 [![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) · [🎨 BYOU](#-bring-your-own-ui-byou)
+[🚀 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>
 
@@ -34,44 +34,12 @@ shortcuts wizards), and UI directions you could build yourself —
 
 ---
 
-## 🤔 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).
-
-|  |  |
-| --- | --- |
-| ❌ **"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. |
-
-```text
-                   ┌──────────────────────────────────────┐
-   your browser ──▶│  home-hosted  ·  127.0.0.1:3999      │
-                   │  your UI + JSON API + SSE logs       │
-                   └───────────────┬──────────────────────┘
-                                   │  supervises
-        ┌──────────────────────────┼──────────────────────────┐
-        ▼                          ▼                          ▼
-   ┌─────────┐               ┌─────────┐                ┌─────────┐
-   │ gateway │               │ files   │                │ bot     │
-   │ :4000   │               │ :4010   │                │  ...    │
-   └─────────┘               └─────────┘                └─────────┘
-     health ✓                  health ✓                  restarts ↻
-```
-
-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.
-
----
-
 ## ⚡ Quick start
 
 ```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 keeps running after the terminal
@@ -89,7 +57,7 @@ npx home-hosted down       # stops the panel *and* everything it started
 <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
 ```
 
@@ -99,18 +67,18 @@ Everything it owns — config, secrets, logs, TLS, backups — lives in `$HHOSTE
 </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>
 
-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 9router serve             # the lockfile pins them, so `npm ci` reproduces
-
-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
 {
@@ -118,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 — or export
-it as one archive under **Settings → Backups**.
+<sub>Call them as `pnpm run up` — `pnpm up` is pnpm's own update, not your script.</sub>
 
 </details>
 
@@ -156,83 +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** | Upload a static build, `home-hosted ui-revert` to go back. [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. |
+| 🔐 **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.
-
-<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, and what each one resolves to:
-
-| placeholder | resolves to |
-| --- | --- |
-| `{id}` `{label}` | the entry's id, and its label (falling back to the id) |
-| `{port}` | its configured port, empty when it has none |
-| `{bind}` `{host}` `{displayHost}` | `local`/`lan`/an address; the address it binds (`127.0.0.1`, `0.0.0.0`); the address to *show* (`127.0.0.1`, the LAN IP) |
-| `{lanIp}` | this machine's LAN address, or `127.0.0.1` |
-| `{cwd}` | the entry's working directory (its `cwd`, else the project directory) |
-| `{projectDir}` | where you ran `home-hosted` (or `--project`) — `$HHOSTED_PROJECT` |
-| `{dataRoot}` | the state directory — `$HHOSTED_HOME`, default `~/.home-hosted` |
-| `{home}` | the current user's home directory |
-
-Unknown placeholders stay visible instead of silently becoming empty, and `${VAR}` reads from the
-environment (including `envFile`).
-
-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).**
 
 ---
 
@@ -245,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>
@@ -264,55 +257,81 @@ 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
+## 🔔 Notifications
 
-**Settings → Backups** archives the config, the secrets file, the TLS pair and the data
-directories your entries declare — as an ordinary `.zip`:
+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).**
 
-- 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
+---
 
-### 🚚 One archive is a whole setup
+## 💾 Backups
 
-Start a **blank** home-hosted anywhere — another machine, another user, a fresh container — upload
-the archive under **Settings → Backups** and restore. Definitions come back, data lands where *this*
-machine's config says, and `autostart` entries come up immediately.
-
-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.
+**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>
 
@@ -326,44 +345,22 @@ panel if yours breaks.
 
 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. `/openapi/ui` documents the API; [UI_CREATION.md](./UI_CREATION.md)
-has the rules and a worked example.
+the server never cares what built it.
 
 <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 about the result:
+specific:
 
-> Help me build an UI for `home-hosted`: a nostalgic game theme — servers as a party menu, health as
-> HP bars, logs in a text-box pane, keyboard navigation, and a save-state corner for backups.
-> Follow `UI_CREATION.md`.
+> Help me build a UI for `home-hosted`: nostalgic game theme, including … features.
 
-Zip the build, install it under **Settings → Interface**, and `home-hosted ui-revert` undoes it if
-you change your mind. [`docs/mockups/`](./docs/mockups) holds example directions to borrow from, or
-ignore all of them.
+[UI_CREATION.md](./UI_CREATION.md) has the endpoints, the SSE frames, the auth rules and a checklist.
 
 </details>
 
 ---
 
-## 🌐 HTTP API
-
-The panel is a client of its own API, so everything is scriptable:
-
-| | |
-| --- | --- |
-| `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 |
-| `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 |
-
----
-
 ## ❓ FAQ
 
 <details>
@@ -383,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>
 
@@ -395,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
@@ -409,19 +409,18 @@ 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>
 
@@ -429,12 +428,9 @@ the holder. The control port itself is checked before the listener is opened.
 
 ## 🗂 Working on it
 
-<details>
-<summary><b>Layout, scripts and conventions</b></summary>
-
 ```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 — any framework, static output
 bin/            the published entry point
@@ -442,8 +438,18 @@ bin/            the published entry point
 
 `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. [AGENTS.md](./AGENTS.md)
-has the architecture and the rules worth knowing before changing anything.
+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>
 

package/SERVERS.md

@@ -0,0 +1,101 @@
+# Servers
+
+Every supervised process is one entry in `$HHOSTED_HOME/servers.config.json`. Add it with **➕ Add
+server** in the panel, or write it by hand — the panel writes the same file.
+
+```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" } }
+}
+```
+
+Relative paths resolve against the directory you ran `home-hosted` from, so a project can keep its
+servers and its state together.
+
+## Field reference
+
+| 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` |
+| `onPortConflict` | `block` (default), `warn`, or `adopt` — see below |
+| `health.mode` | `port` (TCP connect) or `http` (path, expected status, expected body) |
+| `health.unhealthyThreshold`, `forceRestartAfterMs` | how many failed probes before the card warns, and when to restart anyway |
+| `restart.*` | backoff: `maxRetries`, `baseDelayMs`, `factor`, `maxDelayMs`, `resetAfterMs` |
+| `stop.*` | `signal`, `killGroup`, `graceMs`, and `killPortHolders` to sweep a leftover listener |
+| `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
+
+| placeholder | resolves to |
+| --- | --- |
+| `{id}` `{label}` | the entry's id, and its label (falling back to the id) |
+| `{port}` | its configured port, empty when it has none |
+| `{bind}` `{host}` `{displayHost}` | `local`/`lan`/an address; the address it binds (`127.0.0.1`, `0.0.0.0`); the address to *show* (`127.0.0.1`, the LAN IP) |
+| `{lanIp}` | this machine's LAN address, or `127.0.0.1` |
+| `{cwd}` | the entry's working directory (its `cwd`, else the project directory) |
+| `{projectDir}` | where you ran `home-hosted` (or `--project`) — `$HHOSTED_PROJECT` |
+| `{dataRoot}` | the state directory — `$HHOSTED_HOME`, default `~/.home-hosted` |
+| `{home}` | the current user's home directory |
+
+Unknown placeholders stay visible instead of silently becoming empty, and `${VAR}` reads from the
+environment (including `envFile`). 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.
+
+`dataEnvs` is the one that pays for itself twice: the value is exported to the process *and* the path
+is picked up by Backups, so a data directory is declared once.
+
+## A busy port
+
+Preflight runs before every start, so two servers cannot silently fight over one port.
+
+| `onPortConflict` | what happens when something already listens |
+| --- | --- |
+| `block` *(default)* | the entry goes to **conflict** with `port 4000 is already in use (pid 4242)`, and does not start |
+| `warn` | it starts anyway — useful when the listener is a leftover you are replacing |
+| `follow` | if the listener is a **detached restart of this same entry**, the panel adopts it as-is; anything else blocks, exactly like `block` |
+| `reclaim` | same detection, but it stops that successor and starts a fully supervised process of its own |
+
+### When a program restarts itself
+
+Some programs restart themselves by launching a new detached process and exiting — a plugin doing an
+update, a `re-exec` on config change. The panel used to see the successor's port as a conflict and sit
+there blocked while the service was actually up.
+
+Every process gets `HHOSTED_SERVER_ID` in its environment and a successor inherits it, so the preflight
+can tell a successor from a stranger (Linux `/proc`, macOS `ps -E`; Windows has no per-process
+environment, so there you get the conflict banner and the free-port button). Two policies act on that:
+
+| policy | what it does | trade-off |
+| --- | --- | --- |
+| `follow` | adopts the successor: pid, health probe, CPU/RSS, stop, and it starts its own process again when the successor exits | **keeps exactly what the program set up**, but its output is not captured — the pipe belongs to whoever spawned it, so that entry's log in the panel goes quiet |
+| `reclaim` | stops the successor, then starts a fully supervised process of its own | **full features** — live logs, resources, stop semantics all behave like any other entry — at the cost of one restart |
+
+Both are shown as **detached** in the panel while adopted, both can be stopped and restarted like any
+other entry, and neither will ever start a second copy on top of a **stranger**: that still blocks,
+exactly like `block`.
+
+If the holder is ours under a different policy, the conflict message says so, which is how the setting
+is discovered:
+
+```text
+port 4374 is already in use (pid 912) — pid 912 is a detached restart of this entry:
+set onPortConflict to "follow" to adopt it, or "reclaim" to replace it with a supervised process
+```
+
+## Editing fields
+
+Changes from the panel are atomic and validated before they are written. Editing an entry in the file
+by hand is picked up without a restart; a value the schema rejects is refused with the exact path, and
+the panel keeps running on the config it already had.