home-hosted 0.2.0

package/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md
+
+`home-hosted` is a Node 24 / TypeScript harness for self-hosted servers: `up` starts a Hono/srvx
+panel (default `127.0.0.1:3999`) that supervises the entries in `$HHOSTED_HOME/servers.config.json`
+and serves a UI. User docs: `README.md`; UI authors: `UI_CREATION.md`.
+
+State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
+`.control-secrets.json` (0600), `.logs/`, `.tls/`, `.backups/`, `.ui/`, and `run.json` — the live
+daemon's pid/url/token, 0600. The package ships **no servers**: never commit a config, a seed
+entry, or a path that names one.
+
+## Commands
+
+```sh
+pnpm run up|down|restart|status    # detached; `down` asks /_hh/shutdown, signals are the fallback
+pnpm run start                     # up --foreground (systemd, docker, a foreground shell)
+pnpm dev                           # tsx-watch panel :3999 + the stock UI's Vite :3998 (proxies /api)
+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 quickcheck                # eslint + tsc + vue-tsc for every UI under uis/
+pnpm exec vitest run               # `pnpm test` is vitest in watch mode
+pnpm run check                     # quickcheck + vitest run --coverage
+pnpm run set-password              # non-interactive through HHOSTED_PASSWORD
+```
+
+Releases are dispatched from `.github/workflows/release.yml` with a version: changelogen writes the
+changelog, bumps, commits and tags, the GitHub release carries the UI zips, and npm publishes through
+trusted publishing.
+
+## Architecture (and why)
+
+- `src/cli.ts` — the CLI. Its only static imports are node builtins: `--home`/`--project` must set
+  `HHOSTED_HOME`/`HHOSTED_PROJECT` before any `#src` module resolves paths, so every `#src` import is
+  dynamic. `up` re-spawns itself detached as `up --foreground`.
+- `src/index.ts` — `runControlPlane()`: wiring, startup guards (exposure, free port, live run.json),
+  `run.json`, signals. Wiring belongs here and nowhere else.
+- `src/app.ts` — the Hono root, chained routes only. `/_hh` is mounted *before* the `/api/*` auth
+  guard on purpose (a local `down` uses run.json's token, not a session). `AppType` is the route type
+  that `hc<AppType>` clients and the OpenAPI document derive from.
+- `src/api/**` — one file per URL group (`$.routes.ts` = several routes), mirroring the path.
+- `src/shared/contracts.ts` — every ArkType schema (config, API and SSE DTOs), shared with the UIs;
+  the OpenAPI spec is generated from it, never hand-written.
+- `src/config/` — `schema.ts` (on-disk shape), `store.ts` (validate/merge/atomic commit, reports
+  `configError` instead of throwing on a bad file), `secrets.ts`, `seed.ts`.
+- `src/providers/` — stateless leaves: process, port, proc, health-check, host, telegram, archive.
+- `src/services/` — stateful orchestration: supervisor, control-server, state, auth + exposure,
+  dependencies, history, log-buffer/log-files, notifications, host-monitor, backups, tls, ui.
+- `src/helpers/` — paths (`dataRoot` vs `projectDir`), daemon (run.json + a loopback probe that
+  bypasses `fetch`, so TLS with a self-signed pair still answers), error, validator, atomic,
+  template, env-file, openapi, factory.
+- `uis/<name>/` — each UI is a Vite app (Vue 3 + Tailwind v4) built through `uis/vite.shared.ts`;
+  `stock` is the one shipped inside the package. Aliases: `@` → that UI's `src`, `@shared` →
+  `src/shared`, `@server` → `src` (**types only** — never import runtime server code into a UI).
+- `bin/home-hosted.mjs` — the published bin: `dist/cli.js`, or `src/cli.ts` through tsx when the
+  build is missing (a linked checkout).
+
+## Conventions
+
+- `#src/*` imports inside `src/`; UIs use `@shared/*`.
+- ArkType at every runtime boundary: routes use `validate('json'|'query'|'param', schema)` then
+  `c.req.valid(...)`; ad-hoc payloads use `parseOrThrow`. Schemas reject undeclared keys.
+- Every failure is a `DetailedError` (`@namesmt/utils`), mapped by `src/helpers/error.ts` into one
+  envelope `{ message, code, detail }`. Never hand-roll `c.json({ error })`.
+- Document routes with `describeRoute` + `jsonBody(schema)`; `jsonBody` needs a real schema.
+- Patch schemas carry no defaults; nested groups (`restart`/`health`/`stop`/`auth`/`tls`/`telegram`/
+  `http`) merge key-by-key, and an explicit `null` clears a key.
+- Two-sided bounds read inclusively (`'1 <= number.integer <= 512'`). `test/shared/contracts.test.ts`
+  pins every boundary and the patch/schema parity — update it with any schema change.
+- Conventional commits; ESLint via `@antfu/eslint-config`; sparse comments.
+
+## Rules that matter
+
+- **Server-agnostic.** No blessed ids, no `dataDir`-style globals: a server gets only its own
+  `command`/`args`/`env`/`dataEnvs`/`envFile`/`bootstrap`. A test fails if a core file learns one.
+- **Paths.** `dataRoot` is state; `projectDir` is the base for relative entry paths. `{id}{port}`
+  `{host}{bind}{cwd}{projectDir}{dataRoot}{home}` and `${ENV}` expand in config; there is no
+  package-relative state.
+- **Secrets never enter the config.** Password hash, bot token and TLS key live in the 0600 secrets
+  file; the config holds policy.
+- **Never expose beyond loopback without auth and a non-default password.** `checkExposure()` is the
+  single rule, enforced at startup, on every settings write, and in the UI.
+- **UIs are external clients.** Nothing in `src/**` may know a UI's markup or files;
+  `$HHOSTED_HOME/.ui` overrides the packaged UI at runtime.
+- **A restore writes only where a config says** — archive allowlist, `origin` matching first,
+  symlinks never recreated.
+- **Cross-platform.** Linux/macOS/Windows: `/proc` vs `ps` vs Win32_Process, process groups vs
+  `taskkill /T`, graceful fallbacks, no shell utilities assumed.
+- **Writes are atomic** (`writeFileAtomic`) and validated before commit.
+
+## Gotchas
+
+- `run.json` is the daemon's identity and `down`'s credential; keep `runtimeSchema` in sync with the
+  `Runtime` written in `src/index.ts`.
+- Moving the listener (host/port/TLS) kills the connection answering that request, so
+  `PATCH /api/settings`, the TLS routes and `/_hh/shutdown` defer with `afterResponse()`.
+- `Supervisor.start()` sets `starting` synchronously before its first await, and `stop()` sets
+  `stopping` first: overlapping calls would double-spawn or resurrect a stopped process. Tests must
+  call `supervisor.dispose()`.
+- Port preflight re-probes after 300 ms — a just-closed listener can still complete a handshake.
+- `stop.killPortHolders` frees a port only from a *listener* that is not our own process tree. Broad
+  `lsof -ti:<port>` sweeps and pid-as-text parses have killed supervisors in the field; don't add one.
+- `ServerView.config.port` is normalized to `number | null`; the hand-narrowed types in
+  `contracts.ts` are deliberate.
+- ArkType: an optional property (`'x?'`) rejects an explicit `undefined` (omit the key). Fields a UI
+  must clear are `'type | null?'`.
+- Server args are logged *before* `${VAR}` expansion, so an expanded secret never reaches the log
+  buffer, disk, SSE or Telegram.
+- Backups are zips; a password makes them WinZip AES-256/AE-2, and zero-byte entries stay
+  unencrypted on purpose (p7zip 16.02 reports a CRC failure otherwise). `list()` is sync, so
+  encryption flags are cached and refreshed in the background.
+- `vite.server.config.ts` targets `node22` while `engines` requires >= 24 — deliberate margin, leave it.
+- `pnpm test` watches; CI runs `vitest run`.
+
+## Where to extend
+
+- **Route**: `src/api/<x>.ts` (chained factory) → mount in `src/app.ts` → schemas in
+  `src/shared/contracts.ts` → `describeRoute` + `jsonBody`.
+- **Server field**: `serverSchema` + its patch in contracts, merge keys in `config/store.ts` when
+  nested, the form in `uis/stock/src/components/settings/`, and the contract tests.
+- **UI**: a new `uis/<name>/` with a `vite.config.ts` from the shared factory;
+  `node scripts/build-uis.mjs <name> --zip`. The contract is `UI_CREATION.md`.
+- **Capability**: a stateless `src/providers/*` returning plain data.
+
+## Publishing
+
+`pnpm pack` runs `prepack` (a full build) and ships `bin/`, `dist/`, `uis/stock/dist`, `README.md`,
+`UI_CREATION.md`, `AGENTS.md` and `LICENSE`. The bin falls back to tsx so `pnpm link` works before a
+build; `vue`/`vue-router` are devDependencies because the UIs are prebuilt.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NamesMT <https://github.com/namesmt>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,433 @@
+<div align="center">
+
+# 🏠 home-hosted
+
+**The control panel for everything you self-host at home.**
+
+<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.
+
+[![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)
+[![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)
+
+</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).
+
+|  |  |
+| --- | --- |
+| ❌ **"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      │
+                   │  Vue panel + 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
+```
+
+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:
+
+```bash
+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.
+
+<details>
+<summary><b>📦 Install it instead of npx-ing it</b></summary>
+
+```bash
+npm install -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.
+
+</details>
+
+<details>
+<summary><b>📁 Keep it in a project you can take anywhere (and share)</b></summary>
+
+Pin the version, install the servers next to it, and commit the whole project — it *is* the
+setup:
+
+```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
+```
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "up": "home-hosted up --home ./state",
+    "down": "home-hosted down --home ./state",
+    "status": "home-hosted status --home ./state"
+  }
+}
+```
+
+```gitignore
+state/*                 # secrets, logs, TLS keys and archives stay local…
+!state/servers.config.json   # …but the server definitions are committed
+```
+
+<sub>Call them as `npm run up` — `npm up` is npm's own update, not your script.</sub>
+
+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.
+
+</details>
+
+<details>
+<summary><b>🧰 Run it under systemd or Docker (no daemon needed)</b></summary>
+
+```bash
+home-hosted up --foreground     # stays in the foreground, logs to stderr
+```
+
+```ini
+[Unit]
+Description=home-hosted
+[Service]
+ExecStart=/usr/local/bin/home-hosted up --foreground
+Environment=HHOSTED_HOME=/srv/home-hosted
+Restart=always
+[Install]
+WantedBy=multi-user.target
+```
+
+</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. |
+| 🔗 **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. |
+| 💾 **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. |
+| 🖥 **Cross-platform** | Linux, macOS and Windows: `/proc`, `ps` or Win32_Process, process groups or `taskkill /T`, no shell dependencies. |
+
+---
+
+## 🧩 Adding a server
+
+Use **➕ Add server** in the panel, 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" } }
+}
+```
+
+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>
+
+---
+
+## 🛠 CLI
+
+| command | |
+| --- | --- |
+| `home-hosted up` | start the panel detached, and keep it alive in the background |
+| `home-hosted down` | stop it cleanly — supervised processes included |
+| `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 ui-revert` | go back to the stock panel UI after uploading your own |
+
+<details>
+<summary><b>⚙️ Flags</b></summary>
+
+```text
+-c, --config <file>   servers config (default: <state>/servers.config.json)
+-p, --port <port>     control panel port (default: 3999)
+    --host <bind>     local | lan | an ipv4 address
+    --open            open the panel in a browser once it is up
+    --no-autostart    do not start the entries marked autostart
+    --foreground      run in this process instead of detaching
+    --print-config    print the effective config and exit
+    --home <dir>      state directory         (or $HHOSTED_HOME)
+    --project <dir>   base for relative paths (or $HHOSTED_PROJECT)
+```
+
+</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.
+
+---
+
+## 💾 Backups
+
+**Settings → Backups** archives the config, the secrets file, the TLS pair and the data
+directories your entries declare — as an ordinary `.zip`:
+
+- 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
+
+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.
+
+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.
+
+<details>
+<summary><b>🗂 Declaring data directories</b></summary>
+
+```json
+{
+  "dataEnvs": { "DATA_DIR": "{home}/.myapp" },
+  "backupPaths": ["{home}/.myapp/uploads"]
+}
+```
+
+`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.
+
+</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.
+
+```bash
+home-hosted ui-revert     # if it breaks, the stock panel is one command away
+```
+
+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.
+
+---
+
+## 🌐 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/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 |
+
+---
+
+## ❓ FAQ
+
+<details>
+<summary><b>Is it a systemd replacement?</b></summary>
+
+No — it is a friendlier layer for the handful of things you run yourself. Keep systemd for the
+panel itself (`--foreground`) and for system services; use home-hosted for the rest.
+
+</details>
+
+<details>
+<summary><b>What happens to my servers when the panel stops?</b></summary>
+
+`home-hosted down` stops them — that is the point of the command. `SIGTERM`/`SIGINT` are handled
+the same way: every supervised process tree is stopped before the panel exits.
+
+</details>
+
+<details>
+<summary><b>Which ports does it use?</b></summary>
+
+Just the control panel, `3999` by default. Supervised servers use the ports you give them.
+
+</details>
+
+<details>
+<summary><b>Where is my state?</b></summary>
+
+`$HHOSTED_HOME`, default `~/.home-hosted`:
+
+```text
+servers.config.json      your servers (the UI writes it back atomically)
+servers.config.schema.json  regenerated on every start, for editor autocomplete
+.control-secrets.json    password hash + Telegram token (mode 0600)
+.logs/                   rotated per-server logs + history
+.tls/                    an uploaded PEM pair
+.backups/                zip archives
+run.json                 the running panel (pid, url, token, mode 0600)
+```
+
+`home-hosted status` prints the paths.
+
+</details>
+
+<details>
+<summary><b>Windows support, really?</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.
+
+</details>
+
+<details>
+<summary><b>Nothing starts and the port is busy</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.
+
+</details>
+
+---
+
+## 🗂 Layout
+
+```text
+src/            control plane: config, supervisor, API, providers, services
+src/cli.ts      the command line (up/down/status/restart/set-password)
+src/index.ts    the control plane itself, used by `up --foreground`
+uis/            UIs: `stock` (shipped) and alternatives, each a Vite app
+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.
+
+---
+
+<div align="center">
+
+**MIT**
+
+</div>