home-hosted 0.7.21 → 0.8.1

package/AGENTS.md

@@ -1,48 +1,57 @@
 # 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 each workspace's
-`servers.config.json` and serves a UI. User docs: `README.md` and `docs/` (SERVERS, NOTIFICATIONS,
-DDNS, REVERSE_PROXY, UI_CREATION).
+`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 each workspace's `servers.config.json` and
+serves a UI. Package manager: pnpm. User docs: `README.md` and `docs/`.
 
 State lives only in `$HHOSTED_HOME/.hh` (default `~/.home-hosted/.hh`). Global files sit at its top
 level: `settings.json` (listener, auth, TLS policy, host vitals, backups, reverse proxy),
-`workspaces.json`, `.control-secrets.json` (0600: password hash, API token hash), `.tls/`,
-`.backups/`, `.ui/`, `.logs/` (the panel console), `.proxy/` (the engine, its generated config and
-nanny state), and `run.json` (the live daemon's pid/url/token, 0600). Every workspace owns
-`.hh/<id>/`: `settings.json` (server defaults, log retention, notifications, DDNS),
-`servers.config.json`, `.secrets.json` (0600: Telegram token, plus DDNS credentials sealed with
-AES-256-GCM under `HHOSTED_DDNS_SECRET` — only DDNS is sealed, because it is the one thing replayed
-to a third party), `.logs/` (per server, `<id>.log` plus `<id>.log.1` when it rotates), and
-`.state/` (nanny state, its 0600 spawn spec until read, `ddns.json`). A pre-`.hh` instance is
-relocated automatically by `ensureLayout()`. **The package ships no servers**: never commit a config,
-a seed entry, or a path that names one.
+`workspaces.json`, `.control-secrets.json` (0600: password hash, API token hash), `.tls/`, `.backups/`,
+`.ui/`, `.logs/` (the panel console), `.proxy/` (the engine, its generated config and nanny state), and
+`run.json` (the live daemon's pid/url/token, 0600). Every workspace owns `.hh/<id>/`: `settings.json`
+(server defaults, log retention, notifications, DDNS), `servers.config.json`, `.secrets.json` (0600:
+Telegram token, plus DDNS credentials sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET` — only DDNS
+is sealed, because it is the one thing replayed to a third party), `.logs/` (per server, `<id>.log`
+plus `<id>.log.1` when it rotates), and `.state/` (nanny state, its 0600 spawn spec until read,
+`ddns.json`). A home still on the 0.6.x layout is **refused** by `ensureLayout()`, which names the file
+and tells the person to install the latest 0.7.x; 0.8.0 does not relocate it. **The package ships no
+servers**: never commit a config, a seed entry, or a path that names one.
 
 ## Docs
 
-Three tiers, so a reader loads only what the task needs: **this file** (orientation and the rules —
-read every session), **`.agentDocs/`** (depth — read on demand), and **`docs/`** (for a person using the
-package, not for an agent). The section map for every repo in this workspace is
-[`.agentDocs/AGENTS-SKELETON.md`](.agentDocs/AGENTS-SKELETON.md).
+Where knowledge lives, and when to reach for each:
+
+| tier | what it holds | when you use it |
+| --- | --- | --- |
+| `AGENTS.md` — this file | orientation and the rules that prevent defects | read every session; write when a rule is learned the hard way |
+| `.agentDocs/` | depth: module rationale, traps with their causes, compatibility | read on demand, before touching that area; write when a rule needs its reasoning kept |
+| `docs/` | how-to and reference for a person using this package | read when the task is user-facing; write in the same commit as the change |
+| `README.md` | the first read, for a person | write alongside `docs/` |
+
+- **One home per fact.** State the rule here, keep the reasoning in `.agentDocs/` and link it — never both.
+- **A dead pointer is a bug.** If the target is gone, delete the pointer rather than leave it.
+- Move depth behind a pointer once a section outgrows a screen or two; keep the rule inline.
 
 | file | what it covers |
 | --- | --- |
-| [`.agentDocs/AGENTS-SKELETON.md`](.agentDocs/AGENTS-SKELETON.md) | the canonical section names and order, and the required content |
 | [`.agentDocs/ARCHITECTURE.md`](.agentDocs/ARCHITECTURE.md) | what each module owns and why; UI versioning |
 | [`.agentDocs/GOTCHAS.md`](.agentDocs/GOTCHAS.md) | the traps this codebase already paid for, with causes |
 | [`.agentDocs/COMPATIBILITY.md`](.agentDocs/COMPATIBILITY.md) | config and UI compatibility, migrations |
-| [`docs/SERVERS.md`](docs/SERVERS.md) | entries, port conflicts, persistent entries (user-facing) |
+| [`.agentDocs/RELEASING.md`](.agentDocs/RELEASING.md) | how a release is cut, and which version to dispatch |
+| [`docs/SERVERS.md`](docs/SERVERS.md) | entries, port conflicts, persistent entries |
+| [`docs/NOTIFICATIONS.md`](docs/NOTIFICATIONS.md) | Telegram events |
+| [`docs/DDNS.md`](docs/DDNS.md) | dynamic-DNS providers and hostnames |
+| [`docs/REVERSE_PROXY.md`](docs/REVERSE_PROXY.md) | the Caddy engine, routes, certificates |
 | [`docs/UI_CREATION.md`](docs/UI_CREATION.md) | the contract for a new UI |
 
 ## Commands
 
 `pnpm-workspace.yaml` is load-bearing: dropping an `allowBuilds` entry makes `pnpm install` **exit 1**
-(`Ignored build scripts: esbuild@0.24.2` — measured, not inferred). Keep the file's own comments
-explaining why each entry is there.
+(`Ignored build scripts: …`). Keep the file's own comments explaining why each entry is there.
 
 ```sh
-pnpm run up|down|restart|status    # detached; `down` asks /_hh/shutdown, signals are the fallback
-                                   # `restart <id>` restarts one server via /_hh, panel stays up
+pnpm run up|down|restart|status    # detached; `down` asks /_hh/shutdown and signals only a pid whose
+                                   # identity it confirmed; `restart <id>` restarts one server, panel up
 pnpm run start                     # up --foreground (systemd, docker, a foreground shell)
 pnpm exec tsx src/cli.ts logs      # the panel's own console output (--lines, --follow, --json)
 pnpm dev                           # tsx-watch panel :6000 + the stock UI's Vite :6001, state in .dev-state/
@@ -51,10 +60,9 @@ 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 + the doc links — NOT the tests
 pnpm exec vitest run               # `pnpm test` is vitest in watch mode
-pnpm run check                     # ← THE GATE: quickcheck + vitest run --coverage. Run this before
-                                   #   every push — CI's `test.yml` is `pnpm test --coverage`, so an
-                                   #   area floor failing there fails the push while `quickcheck` stays
-                                   #   green. That divergence cost a day of red CI (2026-10-06).
+pnpm run check                     # ← THE GATE: quickcheck + vitest run --coverage. Run before every
+                                   #   push — CI's `test.yml` is `pnpm test --coverage`, so an area floor
+                                   #   failing there fails the push while `quickcheck` stays green.
 pnpm run set-password              # non-interactive through HHOSTED_PASSWORD
 pnpm run set-token                 # --generate prints a new API token once
 pnpm run migrate                   # bring the config up to this release's schema
@@ -66,18 +74,15 @@ The published bin is `home-hosted`, with an `hh` alias: both names run the same
 
 **Dev servers and test instances stay in the 6xxx range** — panel 6000, UI 6001, test-spawned panels
 6100+ (`--port`/`--ui-port`, or `HHOSTED_DEV_PANEL_PORT`/`HHOSTED_DEV_UI_PORT`). Never assume 3999 is
-free: an installed panel or another dev instance may hold it, and the CLI's port preflight runs
-*before* its config guard, so a busy default port turns config tests red for the wrong reason.
+free: an installed panel or another dev instance may hold it, and the port preflight runs *before* the
+workspace config guard, so a busy default port turns config tests red for the wrong reason.
 
 ## Conventions
 
-- **Server-agnostic core; UIs are clients.** `#src/*` inside `src/`; UIs use `@shared/*` (and
-  `@server` for types only).
 - **ArkType at every runtime boundary.** Routes use `validate('json'|'query'|'param', schema)` then
   `c.req.valid(...)`; ad-hoc payloads use `parseOrThrow`. **A request schema rejects undeclared keys**
-  (`.onUndeclaredKey('reject')`); **a response/view schema does not** — a newer panel may add a field
-  while an older client still reads it, so rejecting there would blank that client. 46 of the 94
-  schemas in `contracts.ts` are responses and omit it on purpose.
+  (`.onUndeclaredKey('reject')`); **a response/view schema does not** — a newer panel may add a field an
+  older client still reads, and rejecting there would blank that client.
 - **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.
@@ -85,28 +90,52 @@ free: an installed panel or another dev instance may hold it, and the CLI's port
   key. `ddns`'s `accounts`/`domains` are **replaced** — a merge cannot express removing a hostname.
 - **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.
-- **A new response *field* is optional (`'x?'`)** and read defensively: an upgrade writes a new UI
-  while an old panel keeps serving, so a required field blanks the app.
 - **A single on/off setting is a `ToggleSwitch`**; `CheckField` is only for picking items out of a set.
 - **A destructive action one click away confirms in a popover**, never by arming the same button for a
   second press — an impatient double click fires an armed button. Safe choice first in tab order.
-- **Conventional commits**; ESLint via `@antfu/eslint-config` owns formatting; sparse comments.
+- **A numeric option is a whole decimal integer, never a prefix parse** (`src/cli/up.ts`): `--port 1e3`
+  and `--port 8000x` are refused, not read as 1 and 8000. A flag the command cannot honour is refused
+  too — `restart --workspace <id>` with no server id exits 1 before anything is attempted, because the
+  panel's own restart is not per-server and `down` then `up` would restart every server
+  (`test/cli/server-action.test.ts`).
+- **A bounded read stays bounded.** `logs --lines 1e3` falls back to the default and `0x10` is not the
+  "whole log" sentinel (`src/cli/logs.ts`); `--lines N` reads a tail, never the whole file
+  (`test/cli/logs.test.ts`).
+- **Conventional commits** — changelogen derives the changelog and `scripts/check-release-version.mjs`
+  the version bump. Below 1.0 the **minor is the breaking channel**: a fix is a patch, a minor means
+  someone has to read the release notes and act — ask what the user has to do, not whether the commit
+  says `feat:`. Never hand-edit `package.json`. See [`.agentDocs/RELEASING.md`](.agentDocs/RELEASING.md).
 
 ## Rules that matter
 
-These prevent defects if broken. They stay here rather than in `.agentDocs/` for that reason — a rule
-nobody reads is worse than a long file.
+These prevent defects if broken. The *why* for the non-obvious ones is in
+[`.agentDocs/GOTCHAS.md`](.agentDocs/GOTCHAS.md).
 
-- **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.
+- **Server-agnostic core; UIs are clients.** No blessed ids, no `dataDir`-style globals: a server gets
+  only its own `command`/`args`/`env`/`dataEnvs`/`envFile`/`bootstrap`, and `#src/*` inside `src/` is
+  the only import form — UIs use `@shared/*` (and `@server` for types only). A test fails if a core
+  file learns one.
+- **UIs are external clients.** Nothing in `src/**` may know a UI's markup or files;
+  `$HHOSTED_HOME/.hh/.ui` overrides the packaged UI at runtime.
+- **`src/shared` has exactly one declaration per member** — neither a UI nor `src/**` may re-declare
+  one (`test/shared/ui-parity.test.ts`).
+- **A new response *field* is optional (`'x?'`)** and read defensively: an upgrade writes a new UI while
+  an old panel keeps serving, so a required field blanks the app.
+- **UIs move together.** A change to `uis/stock` — or to a shared contract it reads — lands in every
+  other UI under `uis/`, and each altered UI raises its `ui.json` version; `scripts/stamp-uis.mjs`
+  **refuses** a commit that changed a shipped UI without raising it (`uis/<name>/test/**` is exempt).
+  `src/shared/**` is a UI build input, so a runtime contract needs the bump too — the hook does not
+  inspect that commit.
 - **Paths.** `dataRoot` is state, under `dataRoot/.hh`; `projectDir` is the base for relative entry
-  paths. `{…}` placeholders and `${ENV}` expand in config — the full list is the table in
-  [`docs/SERVERS.md`](docs/SERVERS.md), which is what to keep in step. There is no package-relative
-  state.
+  paths. `{…}` and `${ENV}` expand in config — the full list is the table in
+  [`docs/SERVERS.md`](docs/SERVERS.md), which is what to keep in step. No package-relative state.
 - **Secrets never enter the config.** Only policy goes in a config file; every secret is 0600.
 - **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. `checkProxyExposure()` is
   the same bar for a proxy route pointing at the panel — **`tls` does not change that bar.**
+- **A credential is scoped to its origin.** A release-asset download must not carry its token across a
+  cross-origin redirect; the runtime strips `authorization` today, so that is pinned against two real
+  servers rather than a stubbed `fetch` (`test/providers/ui-release.test.ts`).
 - **The CLI drives a running panel through `/_hh`, never `/api`.** `down` and `start`/`stop` read
   run.json's token over loopback through one guard (`assertLocalCall`), so they need no session. A new
   local command must not open an unauthenticated `/api` route.
@@ -115,29 +144,24 @@ nobody reads is worse than a long file.
 - **A workspace is the ownership boundary.** Servers, secrets, logs and nanny state belong to exactly
   one; only listener, auth, TLS, host vitals, backups, UI and `run.json` are panel-wide. Reach a
   per-workspace service through `PanelService.requireWorkspace(id)`, never a module global.
-- **UIs are external clients.** Nothing in `src/**` may know a UI's markup or files;
-  `$HHOSTED_HOME/.hh/.ui` overrides the packaged UI at runtime.
 - **A restore writes only where a config says** — archive allowlist, `origin` matching first, symlinks
   never recreated.
-- **A port is only ever freed by re-listing its listeners.** `free-port` never trusts a pid quoted in
-  a message, and refuses any listener in `supervisedPids()` instead of killing it.
-- **A live pid is not the running panel.** Pids are recycled and a zombie still answers signal 0, so
-  `up`/`status`/`down` decide with `runtimeIsAlive`/`runtimeLiveness` (pid **plus** `run.json`'s own
-  `startedAt`), never `isProcessAlive` alone — otherwise `up` refuses against a dead panel, `status`
-  reports "running, but not answering", and `down` signals an unrelated process. Only `'gone'`
-  (nothing behind the pid) deletes a record; `'recycled'` blocks a **signal** but still allows the
-  token-authenticated `/_hh/shutdown`, because the birth time is wall-clock-derived.
+- **A port is only ever freed by re-listing its listeners.** `free-port` never trusts a pid quoted in a
+  message, and refuses any listener in `supervisedPids()` instead of killing it.
+- **A live pid is not the running panel.** Pids are recycled and a zombie still answers signal 0, so `up`/`status`/`down` decide
+  with `runtimeIsAlive`/`runtimeLiveness` (pid **plus** `run.json`'s own `startedAt`), never
+  `isProcessAlive` alone. Only `'gone'` deletes a record; `'unknown'` counts as alive, and `'recycled'`
+  blocks a **signal** but still allows the token-authenticated `/_hh/shutdown`, because the birth time is
+  wall-clock-derived.
 - **Only `kill` ever touches a process the panel could not identify** — which is why it logs the pids
-  it stopped. `follow` adopts this entry's own successor, `reclaim` replaces it. Ownership is the
-  entry's whole **tree**, and the panel's own tree is excluded. Full matching rules:
-  [`.agentDocs/GOTCHAS.md`](.agentDocs/GOTCHAS.md).
+  it stopped. `follow` adopts this entry's own successor, `reclaim` replaces it; ownership is the
+  entry's whole **tree**, and the panel's own tree is excluded.
 - **A persistent entry is run by its own nanny** (`src/services/nanny.ts`), which owns the pipes and
-  mirrors the exit — the only arrangement that outlives the panel *and* keeps logging. The nanny
-  never restarts anything: retries and health stay the supervisor's. Three lifetimes are pinned (it
-  exits with its child; a stop reaches the child by pid; its signal traps arm before the child
-  exists) — see [`.agentDocs/GOTCHAS.md`](.agentDocs/GOTCHAS.md).
-- **The reverse proxy's engine is a process the panel owns, not a server entry.** Its config is
-  applied through the engine's admin API (atomic, never hand-edited), it runs under the same nanny a
+  mirrors the exit — the only arrangement that outlives the panel *and* keeps logging. The nanny never
+  restarts anything: retries and health stay the supervisor's. Three lifetimes are pinned (see
+  [`.agentDocs/GOTCHAS.md`](.agentDocs/GOTCHAS.md)).
+- **The reverse proxy's engine is a process the panel owns, not a server entry.** Its config is applied
+  through the engine's admin API (atomic, never hand-edited), it runs under the same nanny a
   `persistent: true` entry uses, and its admin endpoint stays panel-side.
 - **Cross-platform is a hard requirement.** Linux/macOS/Windows: `/proc` vs `ps` vs Win32_Process,
   process groups vs `taskkill /T`, graceful fallbacks, no shell utilities assumed.
@@ -145,104 +169,51 @@ nobody reads is worse than a long file.
 
 ## How to work here
 
-- **Check who calls it before you change it.** Grep the callers and the tests that name it, and say
-  when the impact is unclear rather than guessing. One guard here looked like the one that runs and
-  was not: `declaredData` marks a path `included: false` so the copy never starts, while the check
-  inside `copyInto` is a second line that route does not reach.
-- **Never overwrite or delete a large section you have not fully understood.** Read it, or say what
-  you could not determine and ask.
-- **Report the risk, not only the change** — what could break, what you could not verify, and every
-  assumption you made. Worth checking by kind: correctness, security, operational (deploy, host,
-  scaling) and integration (dependencies, breaking changes). A confident answer that omits this is
-  worth less than a hedged one that has it.
-- **Fix the root cause, not the instance.** When the same bug keeps reappearing under different
-  names — a copied helper, a rule stated twice, a guard bypassed by a second code path — fix the
-  class: one shared implementation, one formatter, one guard. That is the work, not a follow-up to
-  ask for. Say what you changed and what it now prevents, and keep it inside the task's scope rather
-  than refactoring the world.
-- **Verify before claiming, and say what you checked.** A green test proves only what it asserts —
-  **break the thing it guards and watch it fail.** If it still passes, either the test is decoration
-  or a different guard is running; find out which. Where a stub cannot answer the question, drive the
-  real thing. Mark anything unverified as unverified.
-- **If recall of this project is missing** (a compacted or fresh session, a different machine), read
-  this file, `.agentDocs/`, and `git log` before acting, and ask 1–3 targeted questions rather than
-  reconstructing intent from guesswork.
-- **Leave the docs better than you found them.** Delete what is stale, compact what has grown, and
-  never leave a pointer to content that does not exist.
+- **Check the callers before you change anything.** Grep who uses it and which tests name it. If the
+  impact is unclear, say so — do not guess.
+- **Never overwrite or delete a large section you have not understood.** Read it, or say what you could
+  not determine and ask.
+- **Do not invent requirements.** Build what was asked; surface what else you notice and let it be
+  decided.
+- **Fix the class, not the instance.** A copied helper, a rule stated twice, a guard bypassed by a
+  second path is one problem: one implementation, one guard. That is the work, not a follow-up to ask
+  for. Stay inside the task rather than refactoring the world.
+- **Verify before claiming, and say what you checked.** A passing test is not evidence it pins
+  anything — **break the thing it guards and watch it fail.** If it still passes, either the test is
+  decoration or a different guard is running; find out which. Where a stub cannot answer the question,
+  drive the real thing.
+- **Never write an identifier from memory.** A commit hash, path, line number or version must be quoted
+  from the source; a plausible-looking invented one is worse than none.
+- **A stated blocker is a hypothesis, not a fact.** Re-test "cannot install X" / "tool unavailable"
+  before inheriting it, and never report a failure your own flag forced.
+- **Report the risk with the change** — correctness, security, operational and integration; plus what
+  you could not verify and every assumption you made. An unverified claim marked as such beats a
+  confident one that is wrong.
+- **Missing recall of this repo?** Read this file, `.agentDocs/` and `git log` before acting, then ask
+  1–3 focused questions rather than guessing at intent.
+- **One guard here looked like the one that runs and was not**: `declaredData` marks a path
+  `included: false` so the copy never starts, while the check inside `copyInto` is a second line that
+  route does not reach.
 
 ## Conciseness
 
-**Prune verbose; keep correctness.** This covers code, comments, user docs and agent docs alike.
+**Prune verbose, keep correctness** — code, comments, docs alike.
 
-- Code: say it once, name it well; a comment only for non-obvious *intent*, never to restate the line.
-- Docs: one idea per sentence, prefer a table or a line to a paragraph. Cut a sentence that would not
-  change what a reader does.
-- Delete history that `git log` already holds. Keep the *rule* that came out of it, not the story —
-  a path list of where something used to live is archaeology, not guidance.
-- Do not drop a caveat to save a line. Concise means no filler, not fewer facts.
+- Code: a comment only for non-obvious *intent*, never to restate the line, and never long. A block
+  arguing for its own change is a commit message.
+- Docs: one idea per sentence. Cut anything that would not change what a reader does.
+- Delete history `git log` already holds — keep the *rule* that came out of it, not the story.
+- **Never drop a caveat to save a line.** Concise means no filler, not fewer facts.
 
 ## User-facing docs
 
 `README.md` and the topical `docs/*.md` are for a person, not an agent:
 
-- **Concise first read**, depth behind collapsible `<details>` spoilers, and **visuals for skimmers**
-  — the media in `docs/media/` is regenerated by `pnpm run media`.
-- **Docs ship with the change.** A user-visible change updates the docs that describe it in the *same
-  commit*. A stale doc is a bug like stale code.
-- **UIs move together.** `uis/stock` is not the only client: a change to it — or to a shared contract
-  it reads — lands in every other UI under `uis/`, and each altered UI bumps its `ui.json` (see
-  [`.agentDocs/ARCHITECTURE.md`](.agentDocs/ARCHITECTURE.md)). `src/shared/**` is a UI build input, so
-  a contract a UI *calls* at runtime ships in its bundle and needs the bump — the pre-commit hook only
-  inspects `uis/` paths and stays silent on that commit.
-
-## Releasing
-
-Dispatched from `.github/workflows/release.yml` with a version (`-f dry-run=true` to rehearse). It
-verifies the version, lints/types/tests, builds the CLI and every UI zip, lets changelogen write the
-changelog and bump `package.json`, commits and tags `v<version>`, creates the GitHub release with the
-UI bundles attached, and publishes to npm through trusted publishing (OIDC, no token). npm only
-offers a trusted publisher for a package that **already exists**, so a first-ever release has to be
-published by hand.
-
-```sh
-gh workflow run release.yml -f version=0.6.3
-```
-
-Four workflows, and the split is deliberate:
-
-| workflow | runs on | what it proves |
-| --- | --- | --- |
-| `quickcheck.yml` / `test.yml` | every push and PR | lint, types, the whole suite with coverage — Linux only |
-| `cross-platform.yml` | the release gate, or by hand | the same suite on macOS and Windows |
-| `release.yml` | dispatched with a version | the platform gate, then tag, publish, release assets |
-
-The platform gate is not a per-push job on purpose: it is the expensive half, and it is what makes a
-platform-specific break fail before shipping rather than on someone's machine. Every job carries a
-`timeout-minutes`, so a wedged runner is reported instead of sitting out GitHub's 6-hour default.
-
-**Read the skip count, not just the tick.** Linux has no skips; macOS and Windows report a handful
-(Windows more), all from platform guards. What to watch is the *shape*: a new skip appearing, or a
-clean pass where a guard should have fired. **A test that returns early instead of skipping reports a
-pass**, hiding a platform that never ran the code — use `it.runIf`/`it.skipIf` with the condition
-computed at **module load**.
-
-**`npm publish` exiting 0 is the whole answer.** The registry can take up to ten minutes to show a
-package it has accepted — npm's queue, not this run's. Do not poll it, and do not hold work waiting.
-
-### Which version to dispatch
-
-Below 1.0 the **minor is the breaking channel**: a fix or non-breaking feature is a **patch**, while a
-minor means someone has to read the release notes and act. A `feat:` commit does not decide this —
-ask what the user has to do about it. Never edit `package.json` by hand; changelogen bumps inside the
-workflow. `scripts/check-release-version.mjs` refuses a patch while a breaking commit is pending.
-
-### What the package ships
-
-`pnpm pack` runs `prepack` (a full build) and ships the `files` list in `package.json`: `bin/`,
-`dist/`, `uis/stock/dist`, `README.md`, the five user-facing `docs/*.md`, `AGENTS.md` and `LICENSE`.
-`.agentDocs/` is deliberately not published — it is for agents working in this repo, not for people
-installing the package. The bin falls back to tsx so `pnpm link` works before a build;
-`vue`/`vue-router` are devDependencies because the UIs are prebuilt.
+- **Concise first read**, depth behind collapsible `<details>` spoilers, and **visuals for skimmers** —
+  the media in `docs/media/` is regenerated by `pnpm run media`.
+- **Docs ship with the change.** A
+  user-visible change updates the docs that describe it in the *same commit*. A stale doc is a bug like
+  stale code.
 
 ## Where to extend
 
@@ -250,10 +221,12 @@ installing the package. The bin falls back to tsx so `pnpm link` works before a
   `src/shared/contracts.ts` → `describeRoute` + `jsonBody`. A workspace-scoped route takes
   `?workspace=<id>` (`workspaceQuerySchema` + `requireWorkspace` in `src/helpers/workspace.ts`); an
   omitted id means the default workspace, never another one.
-- **Server field**: `serverSchema` + its patch in contracts, merge keys in `config/patch.ts` when
+- **Server field**: `serverSchema` + its patch in contracts, merge keys in `src/config/patch.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 `docs/UI_CREATION.md`.
-- **Capability**: a stateless `src/providers/*` returning plain data; a DDNS provider is one file plus
-  a registry line (`src/providers/ddns/index.ts`) — the settings form, credentials and validation
-  follow from its metadata. See `docs/DDNS.md`.
+- **Capability**: a stateless `src/providers/*` returning plain data; a DDNS provider is one file plus a
+  registry line (`src/providers/ddns/index.ts`) — the settings form, credentials and validation follow
+  from its metadata (`docs/DDNS.md`). A provider that is a **directory** also needs its own
+  `package.json#imports` entry, because `#src/*` maps to a path and Node refuses a directory import
+  (`test/helpers/imports.test.ts`).

package/README.md

@@ -278,6 +278,7 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 🌐 **Dynamic DNS** | Keep hostnames pointed at your public IP — Cloudflare, Namecheap, Spaceship, Porkbun, GoDaddy, Gandi and more. [DDNS.md](./docs/DDNS.md) |
 | 🔀 **Reverse proxy** | One engine in front of everything, with automatic HTTPS: `git.example.com` → a Gitea entry, `media.example.com` → a service on another box, `panel.example.com` → the panel. Caddy, installed and supervised by the panel. [REVERSE_PROXY.md](./docs/REVERSE_PROXY.md) |
 | 💾 **Backups** | Deep and customizable: pick global settings, global secrets, TLS, Workspaces, then the pieces inside it (workspace settings, servers, secrets, data directories) — plain `.zip`, or AES-256 with a password, customized restore is supported too! |
+| 🌍 **Nine languages** | English, Vietnamese, Chinese, Japanese, Spanish, Korean, Russian, French, German — picked on the login page or in **Global settings → Language**, kept per browser. |
 | 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `ui-update` to follow its releases, `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. |
@@ -348,7 +349,7 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted logs` | read the panel's own console output — the file `up` redirects it into (`--lines`, `--follow`, `--json`) |
 | `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` | relocate a pre-workspaces state directory and stamp every config for this release (`--dry-run`, `--yes`) |
+| `home-hosted migrate` | bring every config up to the schema this release understands (`--dry-run`, `--yes`) |
 | `home-hosted init` | scaffold a self-contained project, whose scripts keep state in the repo (`--home ./state`) |
 | `home-hosted ui-switch` | install a UI from a release asset, a zip file or a URL (interactive) |
 | `home-hosted ui-update` | bring an installed UI up to date automatically (official UI) or pick a release (`--old`, `--check`) |
@@ -413,6 +414,17 @@ or a config whose schema is newer than the running release stops `up` with the e
 than starting with defaults that quietly differ from your file. Fix the file, or install the release
 that wrote it.
 
+### Coming from 0.6.x
+
+**Install the latest 0.7.x first, and run it once.** 0.7.0 moved all state from `$HHOSTED_HOME` itself
+into `$HHOSTED_HOME/.hh`, splitting the old all-in-one `servers.config.json` into global settings, a
+`default` workspace, and that workspace's servers — and it did the move automatically on its first
+run. 0.8.0 dropped that relocation.
+
+So a home that is still on the 0.6.x layout is not read: `up` stops and names the file it found,
+rather than starting against an empty state directory beside a config it never opened. 0.7.x does
+the move on its first run; 0.8.0 then starts against the result.
+
 </details>
 
 ---
@@ -663,15 +675,12 @@ plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 
 ---
 
-<details>
-<summary><b>🔗 Interesting resources</b></summary>
+><b>🔗 Interesting resources</b>
 
 - [dsh-home-hosted](https://github.com/NamesMT/dsh-home-hosted) — home-hosted servers management with boot autostart from inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
 
 <sub><i>+ PR to add yours</i></sub>
 
-</details>
-
 ---
 
 <div align="center">