home-hosted 0.4.1 → 0.6.0

package/AGENTS.md

@@ -2,8 +2,8 @@
 
 `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`, `SERVERS.md` (entries and port conflicts),
-`NOTIFICATIONS.md`; UI authors: `UI_CREATION.md`.
+and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port conflicts),
+`docs/NOTIFICATIONS.md`; UI authors: `docs/UI_CREATION.md`.
 
 State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
 `.control-secrets.json` (0600: password hash, API token hash, Telegram bot token), `.logs/`, `.tls/`,
@@ -28,6 +28,8 @@ pnpm exec tsx src/cli.ts init      # scaffold a project (interactive; --yes for
 pnpm run media                     # regenerate docs/media (mockups, both served UIs, tour.gif)
 ```
 
+The published bin is `home-hosted`, with an `hh` alias: both names run the same CLI.
+
 Releases are dispatched from `.github/workflows/release.yml` with a version (and a `dry-run` switch
 that stops before pushing). It verifies the version against `package.json`, lints/types/tests,
 builds the CLI plus the stock UI and every UI zip, lets changelogen write the changelog and tag
@@ -37,9 +39,22 @@ exists, so the first release has to be published by hand.
 
 ## 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/cli.ts` — the CLI's thin root. Two things happen before [citty](https://github.com/unjs/citty)
+  is asked anything: `--home`/`--project` are peeled off and applied (`src/cli/args.ts`), and the
+  curated dispatch — `help`/`version`, `unknown command`, and the `-p 4000` shorthand for `up` — is
+  decided, because `#src/helpers/paths.ts` resolves at import time. Its static imports stay node
+  builtins, citty and those two path-free local modules; every command is a lazy
+  `() => import('#src/cli/<command>')` in citty's `subCommands`, so a command module *may* use static
+  `#src` imports (that is the whole point of the pre-pass). citty's `runMain` is deliberately not
+  used: it prints its own usage and `console.error`s before `process.exit(1)`, replacing `fail()`'s
+  one error shape; the root calls `runCommand` and catches. `src/cli/<command>.ts` is one command per
+  file — citty owns dispatch and argument parsing, with `--no-autostart`/`--no-install` declared as
+  boolean negations rather than literal arg names. The curated `--help` prose stays in `src/cli.ts`
+  because citty cannot generate it. `up` re-spawns itself detached as `up --foreground …`, with the
+  argv built from the *parsed* flags (`buildDaemonArgv`) plus this file's own URL as the entry, so it
+  works under tsx and from `dist/cli.js` alike. `src/cli/io.ts` is the one place the readline prompts
+  and colours live; commands take `prompt`/`style` through that seam (`src/cli/ui-switch.ts` keeps
+  `UiSwitchIo`).
 - `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
@@ -54,13 +69,14 @@ exists, so the first release has to be published by hand.
   `migrations.ts` (the schema constant and the ordered step registry), `secrets.ts`, `seed.ts`.
 - `src/providers/` — stateless leaves: `process` (spawn, `terminate`, `terminatePid` for a process we
   adopted), `port` (probe, holder lookup, `terminatePids`), `proc` (the sampler, plus
-  `processCarriesServerId` for ownership), 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, plus
-  `init` (the scaffold behind `home-hosted init`: a manifest, a `.gitignore`, and the prompts stay in
-  the CLI). It names no server — the scaffold must stay as neutral as the supervisor.
+  `processCarriesServerId` for the environment marker), `identity` (which port holder is this entry's
+  own successor: marker first, then resolved image + argv), health-check, host, telegram, archive.
+- `src/services/` — stateful orchestration: supervisor, control-server, config-watch, state,
+  auth + exposure, dependencies, history, log-buffer/log-files, notifications, host-monitor, backups,
+  tls, ui, plus `init` (the scaffold behind `home-hosted init`: a manifest, a `.gitignore`, and the
+  prompts stay in the CLI). It names no server — the scaffold must stay as neutral as the supervisor.
 - `src/middleware/auth.ts` — the `/api/*` guard, and `requestIdentity()`, the one place a request's
-  credentials are read: the `hh2_session` cookie or `Authorization: Bearer <api token>`. A token is
+  credentials are read: the `hh_session` cookie or `Authorization: Bearer <api token>`. A token is
   a first-class credential (same authority as a signed-in browser) and is verified from the secrets
   file on every request, so `set-token` needs no restart.
 - `src/helpers/` — paths (`dataRoot` vs `projectDir`), daemon (run.json + a loopback probe that
@@ -74,12 +90,20 @@ exists, so the first release has to be published by hand.
 - `scripts/` — `build-uis.mjs` (build one UI, optionally zip it), `typecheck-uis.mjs`,
   `capture-media.mjs` (the README's media), `check-release-version.mjs` and `release-notes.mjs`
   (used by the release workflow), `dev.mjs` (`pnpm dev`).
-- `docs/` — `mockups/*.html`, hand-written UI examples in four directions, and `media/*`: their
-  screenshots plus the README's `tour.gif`, all regenerated by `pnpm run media`.
+- `docs/` — the topic docs (`SERVERS.md`, `NOTIFICATIONS.md`, `UI_CREATION.md`), `mockups/*.html`
+  (hand-written UI examples in four directions) and `media/*`: their screenshots plus the README's
+  `tour.gif`, all regenerated by `pnpm run media`. Only the three `.md` files are published; the
+  media is a build artifact.
 
 ## Conventions
 
 - `#src/*` imports inside `src/`; UIs use `@shared/*`.
+- A single on/off setting is a `ToggleSwitch`; `CheckField` is only for picking items out of a set
+  (the restore plan). A checkbox in a `FieldGroup` grid reads as misaligned next to the inputs.
+- A create body carries only what differs from what the entry would inherit — the schema's defaults
+  with the panel's `Settings → Server defaults` on top (`inheritBaseline` + `diffFields` in both
+  UIs). A value written into `servers.config.json` stops following those defaults, so anything the
+  person did not decide stays out; the editor applies the same rule to an edit.
 - 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
@@ -145,15 +169,26 @@ either is a last resort, and never an accidental 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, API token hash, bot token and TLS key live in
-  the 0600 secrets file; the config holds policy.
-- **A port holder that carries `HHOSTED_SERVER_ID` for this entry is our own successor, not a
-  stranger.** A program that restarts itself leaves a detached process behind; with
-  `follow` the panel adopts it as-is (pid, liveness, health, resources, stop — but not its output);
-  with `reclaim` it stops that successor and starts a fully supervised child instead. Both are strictly
-  better than blocking forever on a port that is already serving, and neither ever touches a stranger.
-  Ownership is read from the environment — `/proc` on Linux, `ps -E` on macOS, impossible on Windows —
-  and `stop.killPortHolders` stays the fallback.
+- **Secrets never enter the config.** The password hash, API token hash and bot token live in the
+  0600 secrets file, and the TLS pair in `.tls/`; the config holds policy.
+- **A port holder that is this entry's own successor is not a stranger.** A program that restarts
+  itself leaves a detached process behind; with `follow` the panel adopts it as-is (pid, liveness,
+  health, resources, stop — but not its output); with `reclaim` it stops that successor and starts a
+  fully supervised child instead; with `kill` it stops whatever holds the port without asking whose it
+  is. All three beat blocking forever on a port that is already serving, and only `kill` ever touches a
+  process the panel could not identify — which is why it logs the pids it stopped.
+  Ownership is read from `HHOSTED_SERVER_ID` in the environment (`/proc` on Linux, `ps -E` on macOS),
+  falling back to the entry's own resolved image **plus its expanded argv** where that is unavailable
+  or unmatched — the fallback is what gives `follow`/`reclaim` any reach on Windows, which exposes no
+  per-process environment. That fallback is strict on purpose, because `reclaim` kills what it
+  identifies: arguments are compared **literally** (never by basename — `/srv/a/server.js` must not
+  match `/tmp/b/server.js`), an argument can never be satisfied by a word that is not in the argv, and
+  two matching holders mean the panel refuses to guess and blocks. It still cannot see through a
+  Windows `.cmd` shim (the holder is `node.exe`, whose argv never mentions the shim) or a macOS
+  argument containing a space (`ps` joins argv without quoting); those cases block, and `kill` is the
+  answer for them. `src/providers/identity.ts` owns the matching, and the argv it is given comes from
+  the supervisor's single `resolveSpawn()`, the same one the spawn itself used — keep it to one
+  resolver, because a second one that expands or filters args differently re-opens these cases.
 - **A port is only ever freed by re-listing its listeners.** `POST /api/servers/:id/free-port` never
   trusts a pid quoted in a message, and refuses any listener in `supervisedPids()` (the panel plus
   every entry's child) instead of killing it — a port held by a sibling is a config mistake.
@@ -175,8 +210,44 @@ either is a last resort, and never an accidental one.
   `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()`.
+  call `supervisor.dispose()`. `stopping` is cleared on **every** exit path of `stopEntry()`: the
+  early return for an entry with no child used to leave it set, and since `start()` refuses while it
+  is true, one Stop on an already-stopped server made that entry unstartable until a daemon restart.
+- Timers and `void`-ed promises in the supervisor carry a `.catch`: a throw in the tick or in a retry
+  is an unhandled rejection, and Node 24 ends the process on one.
+- **`Settings → Server defaults` merge into the nested groups key by key** (`mergeDefaults` in
+  `src/config/schema.ts`, used by both the config parser and `validateServer`). A shallow
+  `{ ...defaults, ...entry }` lets an entry that decides `restart.maxRetries` silently drop the
+  panel's `restart.baseDelayMs` — and the create/edit diff flow depends on inheriting exactly that.
+- The curated CLI dispatch reads only the **flag** forms (`--help`/`-h`, `--version`/`-v`) after a
+  command name, never a bare `help`/`version`: that is an option's value (`init --name help`).
 - Port preflight re-probes after 300 ms — a just-closed listener can still complete a handshake.
+- **The config is re-read whenever the file changes on disk** (`src/services/config-watch.ts` →
+  `ConfigStore.reloadFromDisk()`, wired in `src/index.ts`). The watch is on the *directory*, because
+  an editor's save is a temporary file renamed over the target — the inode changes, the name does not
+  — and a two-second poll backs it up where `fs.watch` is undependable (network mounts). The store
+  compares the bytes it last read and the bytes it wrote, so the panel's own saves never reload
+  anything, and a revision it cannot read (unparseable JSON included — that path used to fall back to
+  an *empty* config until a watcher made it reachable, which would have stopped every server) is
+  reported in the state frame while the running config is kept. A changed definition takes effect on
+  that entry's next start; only an added `autostart` entry is started, and `--no-autostart` still
+  means the panel starts nothing on its own.
+- **The shell must watch the *session*, not only the flags it derives.** With authentication off,
+  `authRequired` and `authenticated` are both `false` from the first paint to the last, so a watcher
+  on those two never ran after the session landed: the panel never opened its event stream, the
+  connection badge sat on "Connecting", and the dashboard showed one stale snapshot forever. Both
+  UIs turn it into a single `streamDecision(session)` value (`wait` | `connect` | `login`) and watch
+  that, which is also what the test pins.
+- **A form that copies live state must guard per block, never globally.** The host thresholds and the
+  backups policy arrive from `/api/settings` *after* the SSE frame, so a single "has anything
+  changed?" gate leaves them showing schema defaults forever — the backups toggle reported itself as
+  changed and flipped back to `true` on every reload. `uis/stock` compares each block against the
+  snapshot it was last filled from (`blockSnapshot`/`isBlockEdited`, `syncFromLive`) and reads the
+  file-only blocks on their own.
+- **A dialog's footer has to be a flex sibling of a scrolling body** (`uis/stock/src/components/ui/Modal.vue`):
+  the sheet is `flex flex-col` with `max-h-[88dvh]`, the body `min-h-0 flex-1 overflow-y-auto`. When
+  only the body carried a max-height, a tall form pushed its own save button below the clipped
+  edge — the add-server dialog looked like it had no save button at all.
 - Vue does not notify a computed's subscribers when its recomputed value is `Object.is`-equal to the
   old one, so anything mutated in place silently freezes every value derived from it. The log buffers
   (`uis/stock/src/composables/useControlPlane.ts`) therefore hand out a **new array per batch**, and
@@ -197,6 +268,10 @@ either is a last resort, and never an accidental one.
 - 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.
+- Generated directories are skipped by the `filter` handed to `fs.cpSync`, matched on an exact path
+  segment at any depth (`src/shared/generated.ts`): `dist/` and `app/node_modules/` go, while
+  `distributed/` and `my-node_modules/` stay. Only the paths an entry declares are filtered — a
+  global `backups.includePaths` entry is captured as it stands.
 - `vite.server.config.ts` targets `node22` while `engines` requires >= 24 — deliberate margin, leave it.
 - `pnpm test` watches; CI runs `vitest run`.
 - `pnpm run media` drives Chromium through Playwright, which needs fonts *and* the X/NSS/Mesa
@@ -211,11 +286,11 @@ either is a last resort, and never an accidental one.
 - **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`.
+  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/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`, `SERVERS.md`,
-`NOTIFICATIONS.md`, `UI_CREATION.md`, `AGENTS.md` and `LICENSE`. The bin falls back to tsx so `pnpm link` works before a
+`pnpm pack` runs `prepack` (a full build) and ships `bin/`, `dist/`, `uis/stock/dist`, `README.md`, `docs/SERVERS.md`,
+`docs/NOTIFICATIONS.md`, `docs/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/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) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🧩 Servers](./SERVERS.md) · [🛠 CLI](#-cli) · [🔔 Notifications](./NOTIFICATIONS.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
+[🚀 Quick start](#-quick-start) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🧩 Servers](./docs/SERVERS.md) · [🛠 CLI](#-cli) · [🔔 Notifications](./docs/NOTIFICATIONS.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
 
 </div>
 
@@ -34,6 +34,50 @@ shortcuts wizards), and UI directions you could build yourself —
 
 ---
 
+## 🤔 Why?
+
+You run a handful of services at home. The usual choices are extremes — 🧟 `tmux` sessions you
+forget about, 📜 a hand-written systemd unit per service (times six), or 🐳 a whole docker/k8s
+stack??? - too extreme! — plus 😩 monitoring, rebooting and changing the host machine, yuck!
+
+🙂 home-hosted, well, joins in somewhere: a panel/supervisor that starts them, watches them, restarts what dies, and
+puts the whole stack on one page, with deep backup support.
+
+```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 ↻
+```
+
+|  |  |
+| --- | --- |
+| ❌ **"Is it still running?"** | Health, CPU/mem, uptime and live logs per server — no `ps`, no `curl`, no hope |
+| ❌ **Silent deaths** | Restarted automatically, and the panel or Telegram notifies |
+| ❌ **Fragile reboots** | `autostart` brings the stack back; one `down` stops it all cleanly |
+| ❌ **"Move it to the new box"** | One archive: config **and** data, restored on a blank host |
+| ✅ **home-hosted** | Declare it once, watch it forever, one command to stop it all |
+
+It ships with **nothing**: no blessed paths, no opinion about what you run — a server is a command,
+some arguments, and the environment you give it:
+
+```json
+{ "id": "gateway", "command": "node", "args": ["server.js"], "port": 4000, "autostart": true }
+```
+
+<sub>Manage them from the panel, `home-hosted status --json`, or `GET /api/state`; `GET /healthz` is
+the same status line for your own monitor, no session needed.</sub>
+
+---
+
 ## ⚡ Quick start
 
 ```bash
@@ -58,12 +102,15 @@ npx home-hosted down       # stops the panel *and* everything it started
 
 ```bash
 npm install -g home-hosted      # or: pnpm add -g home-hosted
-home-hosted up
+home-hosted up                  # `hh up` does the same
 ```
 
 Everything it owns — config, secrets, logs, TLS, backups — lives in `$HHOSTED_HOME`, default
 `~/.home-hosted`. Delete that and nothing of yours is left behind.
 
+<sub>An installed home-hosted answers to **`hh`** too — `hh up`, `hh status`, `hh down`. Only the
+installed form gets it; npx stays `npx home-hosted …`.</sub>
+
 </details>
 
 <details>
@@ -104,6 +151,10 @@ Worked example, with per-server data inside the project:
 
 <sub>Call them as `pnpm run up` — `pnpm up` is pnpm's own update, not your script.</sub>
 
+> [!TIP]
+> Give a project its own panel port (`control.port`, e.g. `4399`) — the default `3999` is what the
+> global instance and every other project also want.
+
 </details>
 
 <details>
@@ -140,7 +191,7 @@ home-hosted set-token --generate
 
 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
+curl -N -H "Authorization: Bearer hh_9uA2…" 'http://127.0.0.1:3999/api/events?serverId=9router'   # SSE
 home-hosted status --json        # machine-readable: pid, url, health, paths
 ```
 
@@ -158,9 +209,10 @@ revokes it instantly.
 | `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 /api/logs`, `/api/backups` | history and archives |
+| `PUT`/`DELETE /api/notifications/token`, `POST /api/notifications/{test,detect-chats}` | the bot credential, a test send |
 | `GET /healthz` | no session needed — the one an external monitor wants (its per-server detail needs a credential) |
-| `GET /api/metrics` | Prometheus text |
+| `GET /api/metrics` | Prometheus text (needs a token or session, like every `/api` route) |
 
 `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.
@@ -175,9 +227,9 @@ 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.
+4. [SERVERS.md](./docs/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
+For a UI rather than the API, [UI_CREATION.md](./docs/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>
@@ -189,16 +241,17 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | | |
 | --- | --- |
 | 🚦 **Lifecycle** | Start, stop, restart from the panel or the API; `autostart` entries come up with it. |
+| 📝 **Hand edits welcome** | Change `servers.config.json` in an editor, a `git checkout` or a config tool: the panel notices within seconds, no restart. A file it cannot read is reported in the panel, and the running servers are left alone. |
 | ♻️ **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, check ports before starting — and [follow or replace](./SERVERS.md#when-a-program-restarts-itself) a program that restarts itself. |
+| 🩺 **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](./docs/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). |
+| 🔔 **Notifications** | Telegram on crash, unhealthy, forced restart, recovery and host thresholds — [setup here](./docs/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. |
-| 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `home-hosted ui-revert` to go back. [UI_CREATION.md](./UI_CREATION.md) |
+| 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `home-hosted ui-revert` to go back. [UI_CREATION.md](./docs/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. |
@@ -222,7 +275,7 @@ An entry is a few lines. Add one with **➕ Add server**, or write it into `serv
 
 `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).**
+restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.md).**
 
 ---
 
@@ -238,23 +291,32 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./SERVERS.md).*
 | `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-switch` | install a UI from a release asset, a zip file or a URL (interactive) |
 | `home-hosted ui-revert` | go back to the stock panel UI after uploading your own |
 
 <details>
 <summary><b>⚙️ Flags</b></summary>
 
+`home-hosted <command> --help` prints what that command takes.
+
 ```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)
+up, restart       -c/--config -p/--port --host --open --no-autostart --foreground --print-config
+
+down              (no flags)
+status            --json
+init              --dir --name --pm --no-install -y/--yes
+set-password      --clear
+set-token         --generate --clear
+migrate           --config --dry-run -y/--yes
+ui-switch         --repo --tag --asset --file --list --token -y/--yes
+ui-revert         (no flags)
+
+every command     --home <dir> --project <dir>       (or $HHOSTED_HOME, $HHOSTED_PROJECT)
+env vars          HHOSTED_PASSWORD, HHOSTED_MIGRATE=allow, HHOSTED_TOKEN, GITHUB_TOKEN or GH_TOKEN
 ```
 
+`up` and `restart` share the same flags: `restart` is `down`, then `up` with exactly what it was given.
+
 </details>
 
 <details>
@@ -299,10 +361,10 @@ Everything binds `127.0.0.1` until you say otherwise.
 - **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
+  that [restarts itself](./docs/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`.
+- **Secrets never enter the config**: the password hash, the API token hash and the Telegram bot
+  token live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the TLS pair in `.tls/`.
 - **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.
 
@@ -313,14 +375,16 @@ Everything binds `127.0.0.1` until you say otherwise.
 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).**
+file. **Two minutes of setup: [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md).**
 
 ---
 
 ## 💾 Backups
 
 **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.
+declare — an ordinary `.zip`, or WinZip AES-256 with a password, restored per path. Known build output
+and dependency directories (`node_modules`, `dist`, `.next`, framework caches) are skipped per entry;
+`backupIgnoreGenerated: false` captures them anyway.
 
 <details>
 <summary><b>🚚 One archive is a whole setup</b></summary>
@@ -347,6 +411,9 @@ Two ship in this repo: `uis/stock`, and `uis/noc-console` for TUI and shortcuts
 attaches both as `home-hosted-ui-<name>.zip`. Yours can be anything that compiles to static files —
 the server never cares what built it.
 
+<sub>Install a UI from the CLI: `home-hosted ui-switch` — with no flags it fetches the official asset
+built for this release.</sub>
+
 <details>
 <summary><b>🤖 Or have an agent build the UI you actually want</b></summary>
 
@@ -355,7 +422,7 @@ specific:
 
 > Help me build a UI for `home-hosted`: nostalgic game theme, including … features.
 
-[UI_CREATION.md](./UI_CREATION.md) has the endpoints, the SSE frames, the auth rules and a checklist.
+[UI_CREATION.md](./docs/UI_CREATION.md) has the endpoints, the SSE frames, the auth rules and a checklist.
 
 </details>
 
@@ -384,7 +451,7 @@ the same way: every supervised process tree is stopped before the panel exits.
 
 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
+([SERVERS.md](./docs/SERVERS.md#a-busy-port)). The control port itself is checked before the listener is
 opened.
 
 </details>
@@ -395,13 +462,13 @@ opened.
 `$HHOSTED_HOME`, default `~/.home-hosted`:
 
 ```text
-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 + API token 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)
+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 + API token 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.
@@ -430,10 +497,13 @@ expose them to an unprivileged process, and adopting a self-restarted process is
 
 ```text
 src/            control plane: config, supervisor, API, providers, services
-src/cli.ts      the command line (up/down/status/restart/set-password/set-token/migrate)
+src/cli.ts      the command line; one file per command under src/cli/
 src/index.ts    the control plane itself, used by `up --foreground`
-uis/            UIs: `stock` (shipped) and alternatives — any framework, static output
+uis/            UIs: `stock` (shipped in the package) and alternatives — any framework, static output
 bin/            the published entry point
+docs/           topic docs, UI examples and the README's media
+scripts/        builds, typechecks, media capture, release helpers
+test/           the vitest suite
 ```
 
 `pnpm dev` runs the panel with `tsx watch` plus the stock UI's dev server (state goes to
@@ -441,15 +511,15 @@ bin/            the published entry point
 types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 
 <details>
-<summary><b>📚 The docs, and which one you want</b></summary>
+<summary><b>📚 Which doc do I need?</b></summary>
 
-| file | for |
+| if you want to… | read |
 | --- | --- |
-| [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 |
+| 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) |
+| build a UI against the API | [UI_CREATION.md](./docs/UI_CREATION.md) |
+| change the internals: architecture and the rules | [AGENTS.md](./AGENTS.md) |
+| poke the live API on your own panel | [/openapi/ui](http://127.0.0.1:3999/openapi/ui) |
 
 </details>