home-hosted 0.4.1 → 0.5.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/`,
@@ -37,9 +37,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
@@ -55,10 +68,10 @@ exists, so the first release has to be published by hand.
 - `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.
+- `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
   a first-class credential (same authority as a signed-in browser) and is verified from the secrets
@@ -74,12 +87,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
@@ -175,8 +196,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 +254,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 +272,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,40 @@ 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) — or a complex docker/k8s
+setup?
+
+|  |  |
+| --- | --- |
+| ❌ **"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
@@ -104,6 +138,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>
@@ -160,7 +198,7 @@ revokes it instantly.
 | `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 /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 +213,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 +227,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 +261,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,11 +277,14 @@ 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 (`--list` to see them) |
 | `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 the options that command takes.
+
 ```text
 -c, --config <file>   servers config (default: <state>/servers.config.json)
 -p, --port <port>     control panel port (default: 3999)
@@ -299,7 +341,7 @@ 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`.
@@ -313,14 +355,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>
@@ -355,7 +399,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 +428,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>
@@ -430,10 +474,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
@@ -445,9 +492,9 @@ types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 
 | 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 |
+| [SERVERS.md](./docs/SERVERS.md) | declaring a server: every field, placeholders, port conflicts |
+| [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md) | Telegram alerts, end to end |
+| [UI_CREATION.md](./docs/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 |