home-hosted 0.5.0 → 0.6.1

package/dist/cli.js

@@ -88,9 +88,11 @@ function applyDirFlags(flags) {
 *
 * `help`/`version` are commands here, not flags, and a help or version flag on a
 * command is answered the same way instead of being parsed as one of that
-* command's options. A first token that starts with `-` is the one-shot form
-* (`home-hosted -p 4000`), so `up` is prepended. Anything else has to name a
-* command, which keeps the old `unknown command:` text exact.
+* command's options. A help flag after a command keeps that command's name, so
+* the curated text can stay scoped to it; the bare `help` (or a top-level flag)
+* is the whole reference. A first token that starts with `-` is the one-shot
+* form (`home-hosted -p 4000`), so `up` is prepended. Anything else has to name
+* a command, which keeps the old `unknown command:` text exact.
 */
 function resolveInvocation(argv, commands) {
 	if (argv.length === 0) return {
@@ -109,7 +111,10 @@ function resolveInvocation(argv, commands) {
 		command: first
 	};
 	for (const arg of argv.slice(1)) {
-		if (HELP_FLAGS.has(arg)) return { kind: "help" };
+		if (HELP_FLAGS.has(arg)) return {
+			kind: "help",
+			command: first
+		};
 		if (VERSION_FLAGS.has(arg)) return { kind: "version" };
 	}
 	return {
@@ -242,13 +247,15 @@ async function confirm(question, fallback) {
 	if (answer.length === 0) return fallback;
 	return answer === "y" || answer === "yes";
 }
-var isTty, paint, dim, bold, green, style;
+var isTty, paint, dim, bold, cyan, green, heading, style;
 var init_io = __esmMin((() => {
 	isTty = () => process.stdout.isTTY === true;
 	paint = (code, text) => isTty() ? `\x1B[${code}m${text}\x1B[0m` : text;
 	dim = (text) => paint("2", text);
 	bold = (text) => paint("1", text);
+	cyan = (text) => paint("36", text);
 	green = (text) => paint("32", text);
+	heading = (text) => paint("1;4", text);
 	style = {
 		bold,
 		dim,
@@ -297,10 +304,12 @@ function parseBind(value) {
 	const parsed = bindSchema(value);
 	return parsed instanceof type.errors ? null : parsed;
 }
-var bindSchema, portSchema, restartSchema, httpCheckSchema, resourcesSchema, healthSchema, stopSchema, bootstrapSchema, bootstrapOrNullSchema, logBufferLinesSchema, serverSchema, authSchema, telegramSchema, notificationsSchema, logsSchema, tlsSchema, hostSchema, backupsSchema, controlSchema, defaultsSchema, restartPatchSchema, httpCheckPatchSchema, resourcesPatchSchema, healthPatchSchema, stopPatchSchema, authPatchSchema, telegramPatchSchema, notificationsPatchSchema, hostPatchSchema, backupsPatchSchema, logsPatchSchema, tlsPatchSchema, controlPatchSchema, defaultsPatchSchema, editableFields, serverPatchSchema, serverCreateSchema, settingsPatchSchema, authStatusSchema, tlsStatusSchema, telegramStatusSchema, notificationViewSchema, sessionViewSchema, loginSchema, passwordValueSchema, passwordSchema, serverStatusSchema, healthStateSchema, portStateSchema, logStreamSchema, logLineSchema, historyEventSchema, serverHistorySchema, processResourcesSchema, hostDiskSchema, hostViewSchema, backupFileSchema, backupPathSchema, backupsViewSchema, restoreItemSchema, restorePlanSchema, backupCreateSchema, restoreRequestSchema, serverViewSchema, controlViewSchema, appStateSchema, logQuerySchema, freePortResultSchema, logHistoryQuerySchema, logFileInfoSchema, logServerViewSchema, logServersViewSchema, notificationActionSchema, telegramTokenSchema, apiErrorSchema, uiMetaSchema, uiStatusSchema, tlsUploadSchema, settingsViewSchema, settingsSavedSchema;
+var bindSchema, portSchema, onPortConflictSchema, onPortConflictDefaultSchema, restartSchema, httpCheckSchema, resourcesSchema, healthSchema, stopSchema, bootstrapSchema, bootstrapOrNullSchema, logBufferLinesSchema, serverSchema, authSchema, telegramSchema, notificationsSchema, logsSchema, tlsSchema, hostSchema, backupsSchema, controlSchema, defaultsSchema, restartPatchSchema, httpCheckPatchSchema, resourcesPatchSchema, healthPatchSchema, stopPatchSchema, authPatchSchema, telegramPatchSchema, notificationsPatchSchema, hostPatchSchema, backupsPatchSchema, logsPatchSchema, tlsPatchSchema, controlPatchSchema, defaultsPatchSchema, editableFields, serverPatchSchema, serverCreateSchema, settingsPatchSchema, authStatusSchema, tlsStatusSchema, telegramStatusSchema, notificationViewSchema, sessionViewSchema, loginSchema, passwordValueSchema, passwordSchema, serverStatusSchema, healthStateSchema, portStateSchema, logStreamSchema, logLineSchema, historyEventSchema, serverHistorySchema, processResourcesSchema, hostDiskSchema, hostViewSchema, backupFileSchema, backupPathSchema, backupsViewSchema, restoreItemSchema, restorePlanSchema, backupCreateSchema, restoreRequestSchema, serverViewSchema, controlViewSchema, appStateSchema, logQuerySchema, freePortResultSchema, logHistoryQuerySchema, logFileInfoSchema, logServerViewSchema, logServersViewSchema, notificationActionSchema, telegramTokenSchema, apiErrorSchema, uiMetaSchema, uiStatusSchema, tlsUploadSchema, settingsViewSchema, settingsSavedSchema;
 var init_contracts = __esmMin((() => {
 	bindSchema = type("\"local\" | \"lan\" | /^\\d{1,3}(?:\\.\\d{1,3}){3}$/");
 	portSchema = type("1 <= number.integer <= 65535 | null");
+	onPortConflictSchema = type.enumerated("block", "warn", "follow", "reclaim", "kill");
+	onPortConflictDefaultSchema = onPortConflictSchema.default("block");
 	restartSchema = type({
 		enabled: "boolean = true",
 		maxRetries: "number.integer >= 0 = 3",
@@ -371,7 +380,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		bootstrap: bootstrapOrNullSchema.optional(),
 		port: portSchema.optional(),
 		bind: bindSchema.default(() => "local"),
-		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\" = \"block\"",
+		onPortConflict: onPortConflictDefaultSchema,
 		restart: restartSchema.default(() => ({})),
 		health: healthSchema.default(() => ({})),
 		stop: stopSchema.default(() => ({})),
@@ -452,7 +461,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		enabled: "boolean = true",
 		autostart: "boolean = false",
 		bind: bindSchema.default(() => "local"),
-		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\" = \"block\"",
+		onPortConflict: onPortConflictDefaultSchema,
 		restart: restartSchema.default(() => ({})),
 		health: healthSchema.default(() => ({})),
 		stop: stopSchema.default(() => ({})),
@@ -543,7 +552,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		enabled: "boolean?",
 		autostart: "boolean?",
 		bind: bindSchema.optional(),
-		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\"?",
+		onPortConflict: onPortConflictSchema.optional(),
 		restart: restartPatchSchema.optional(),
 		health: healthPatchSchema.optional(),
 		stop: stopPatchSchema.optional(),
@@ -561,7 +570,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		bootstrap: bootstrapOrNullSchema.optional(),
 		port: portSchema.optional(),
 		bind: bindSchema.optional(),
-		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\"?",
+		onPortConflict: onPortConflictSchema.optional(),
 		restart: restartPatchSchema.optional(),
 		health: healthPatchSchema.optional(),
 		stop: stopPatchSchema.optional(),
@@ -888,10 +897,20 @@ password: passwordValueSchema.optional() }).onUndeclaredKey("reject");
 		detail: "unknown"
 	}).onUndeclaredKey("reject");
 	uiMetaSchema = type({
-		name: "string",
-		version: "string | null",
-		uploadedAt: "number",
-		files: "number.integer >= 1"
+		"name?": "string",
+		"version?": "string | null",
+		/** Set by the panel, not by the author. */
+		"uploadedAt?": "number",
+		/** Counted by the panel, not declared. */
+		"files?": "number.integer >= 1",
+		/** `owner/name` of the UI's own repository, for `ui-update`. */
+		"repo?": "string",
+		/** The release tag this build came from, e.g. `v0.6.0`. */
+		"tag?": "string",
+		/** The release asset name, e.g. `home-hosted-ui-noc-console`. */
+		"asset?": "string",
+		/** When the UI was built, in unix epoch seconds. */
+		"unix?": "number.integer >= 0"
 	});
 	uiStatusSchema = type({
 		/** A user-supplied UI is being served instead of the stock one. */
@@ -1206,7 +1225,7 @@ var SESSION_COOKIE, MAX_SESSIONS, MAX_LOCKOUT_MS, MAX_ATTEMPT_RECORDS, ATTEMPT_R
 var init_auth$1 = __esmMin((() => {
 	init_secrets();
 	init_cookies();
-	SESSION_COOKIE = "hh2_session";
+	SESSION_COOKIE = "hh_session";
 	MAX_SESSIONS = 100;
 	MAX_LOCKOUT_MS = 9e5;
 	MAX_ATTEMPT_RECORDS = 1e4;
@@ -1294,7 +1313,7 @@ var init_auth$1 = __esmMin((() => {
 			};
 		}
 		tokenFromCookie(cookieHeader) {
-			return parseCookies(cookieHeader)["hh2_session"] ?? null;
+			return parseCookies(cookieHeader)["hh_session"] ?? null;
 		}
 		/** Sliding expiry: an active panel stays logged in, an idle one does not. */
 		validate(token) {
@@ -2307,19 +2326,19 @@ function createMetricsRoute(deps) {
 			if (samples.length === 0) return;
 			lines.push(`# HELP ${name} ${help}`, `# TYPE ${name} gauge`, ...samples);
 		};
-		metric("hh2_control_up", "Control plane is serving", ["hh2_control_up 1"]);
-		metric("hh2_servers_total", "Configured servers", [`hh2_servers_total ${state.servers.length}`]);
-		metric("hh2_server_up", "Server process is running", state.servers.map((server) => `hh2_server_up{server="${server.id}"} ${server.status === "running" ? 1 : 0}`));
-		metric("hh2_server_restarts_total", "Restarts since the control plane started", state.servers.map((server) => `hh2_server_restarts_total{server="${server.id}"} ${server.restarts}`));
-		metric("hh2_server_crashes_24h", "Crashes in the last 24 hours", state.servers.map((server) => `hh2_server_crashes_24h{server="${server.id}"} ${server.history.crashes}`));
-		metric("hh2_server_uptime_ratio_24h", "Share of the last 24 hours the server was up", state.servers.filter((server) => server.history.uptimeRatio !== null).map((server) => `hh2_server_uptime_ratio_24h{server="${server.id}"} ${server.history.uptimeRatio.toFixed(4)}`));
-		metric("hh2_server_response_ms", "Last health probe latency in milliseconds", state.servers.filter((server) => server.responseMs !== null).map((server) => `hh2_server_response_ms{server="${server.id}"} ${server.responseMs}`));
-		metric("hh2_server_rss_bytes", "RSS of the server process tree", state.servers.filter((server) => server.resources?.rssBytes != null).map((server) => `hh2_server_rss_bytes{server="${server.id}"} ${server.resources.rssBytes}`));
-		metric("hh2_server_cpu_percent", "CPU percent of the server process tree", state.servers.filter((server) => server.resources?.cpuPercent != null).map((server) => `hh2_server_cpu_percent{server="${server.id}"} ${server.resources.cpuPercent}`));
-		metric("hh2_host_disk_used_percent", "Disk usage percent per configured path", state.host.disks.map((disk) => `hh2_host_disk_used_percent{mount="${disk.path}"} ${disk.usedPercent.toFixed(2)}`));
-		metric("hh2_host_memory_used_percent", "Memory usage percent", [`hh2_host_memory_used_percent ${state.host.memoryUsedPercent.toFixed(2)}`]);
-		metric("hh2_host_swap_used_percent", "Swap usage percent", [`hh2_host_swap_used_percent ${state.host.swapUsedPercent.toFixed(2)}`]);
-		metric("hh2_host_load1_per_cpu", "1 minute load average per cpu", [`hh2_host_load1_per_cpu ${((state.host.loadAvg[0] ?? 0) / Math.max(1, state.host.cpus)).toFixed(3)}`]);
+		metric("hh_control_up", "Control plane is serving", ["hh_control_up 1"]);
+		metric("hh_servers_total", "Configured servers", [`hh_servers_total ${state.servers.length}`]);
+		metric("hh_server_up", "Server process is running", state.servers.map((server) => `hh_server_up{server="${server.id}"} ${server.status === "running" ? 1 : 0}`));
+		metric("hh_server_restarts_total", "Restarts since the control plane started", state.servers.map((server) => `hh_server_restarts_total{server="${server.id}"} ${server.restarts}`));
+		metric("hh_server_crashes_24h", "Crashes in the last 24 hours", state.servers.map((server) => `hh_server_crashes_24h{server="${server.id}"} ${server.history.crashes}`));
+		metric("hh_server_uptime_ratio_24h", "Share of the last 24 hours the server was up", state.servers.filter((server) => server.history.uptimeRatio !== null).map((server) => `hh_server_uptime_ratio_24h{server="${server.id}"} ${server.history.uptimeRatio.toFixed(4)}`));
+		metric("hh_server_response_ms", "Last health probe latency in milliseconds", state.servers.filter((server) => server.responseMs !== null).map((server) => `hh_server_response_ms{server="${server.id}"} ${server.responseMs}`));
+		metric("hh_server_rss_bytes", "RSS of the server process tree", state.servers.filter((server) => server.resources?.rssBytes != null).map((server) => `hh_server_rss_bytes{server="${server.id}"} ${server.resources.rssBytes}`));
+		metric("hh_server_cpu_percent", "CPU percent of the server process tree", state.servers.filter((server) => server.resources?.cpuPercent != null).map((server) => `hh_server_cpu_percent{server="${server.id}"} ${server.resources.cpuPercent}`));
+		metric("hh_host_disk_used_percent", "Disk usage percent per configured path", state.host.disks.map((disk) => `hh_host_disk_used_percent{mount="${disk.path}"} ${disk.usedPercent.toFixed(2)}`));
+		metric("hh_host_memory_used_percent", "Memory usage percent", [`hh_host_memory_used_percent ${state.host.memoryUsedPercent.toFixed(2)}`]);
+		metric("hh_host_swap_used_percent", "Swap usage percent", [`hh_host_swap_used_percent ${state.host.swapUsedPercent.toFixed(2)}`]);
+		metric("hh_host_load1_per_cpu", "1 minute load average per cpu", [`hh_host_load1_per_cpu ${((state.host.loadAvg[0] ?? 0) / Math.max(1, state.host.cpus)).toFixed(3)}`]);
 		return c.text(`${lines.join("\n")}\n`, 200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
 	});
 }
@@ -4093,7 +4112,7 @@ function parseNetstatListeners(output, port) {
 }
 async function listPortHolders(port) {
 	if (process.platform === "win32") try {
-		const { stdout } = await execFileAsync$3("netstat", [
+		const { stdout } = await execFileAsync$4("netstat", [
 			"-ano",
 			"-p",
 			"tcp"
@@ -4103,7 +4122,7 @@ async function listPortHolders(port) {
 		return [];
 	}
 	try {
-		const { stdout } = await execFileAsync$3("lsof", [
+		const { stdout } = await execFileAsync$4("lsof", [
 			"-ti",
 			`tcp:${port}`,
 			"-sTCP:LISTEN"
@@ -4111,7 +4130,7 @@ async function listPortHolders(port) {
 		return parsePids(stdout);
 	} catch {}
 	try {
-		const { stdout } = await execFileAsync$3("fuser", [`${port}/tcp`], { timeout: 3e3 });
+		const { stdout } = await execFileAsync$4("fuser", [`${port}/tcp`], { timeout: 3e3 });
 		return parsePids(stdout);
 	} catch {
 		return [];
@@ -4120,9 +4139,9 @@ async function listPortHolders(port) {
 function parsePids(stdout) {
 	return [...new Set(stdout.split(/\s+/).map((entry) => Number.parseInt(entry, 10)).filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid))];
 }
-var execFileAsync$3;
+var execFileAsync$4;
 var init_port = __esmMin((() => {
-	execFileAsync$3 = promisify(execFile);
+	execFileAsync$4 = promisify(execFile);
 }));
 //#endregion
 //#region src/helpers/env-file.ts
@@ -4489,7 +4508,7 @@ function parseWindowsCsv(text) {
 async function getClockTicks() {
 	if (clockTicks !== null) return clockTicks;
 	try {
-		const { stdout } = await execFileAsync$2("getconf", ["CLK_TCK"], { timeout: 2e3 });
+		const { stdout } = await execFileAsync$3("getconf", ["CLK_TCK"], { timeout: 2e3 });
 		const parsed = Number.parseInt(stdout.trim(), 10);
 		clockTicks = Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
 	} catch {
@@ -4541,7 +4560,7 @@ async function readLinux() {
 	return rows;
 }
 async function readPosix() {
-	const { stdout } = await execFileAsync$2("ps", ["-Ao", "pid=,ppid=,rss=,%cpu="], {
+	const { stdout } = await execFileAsync$3("ps", ["-Ao", "pid=,ppid=,rss=,%cpu="], {
 		timeout: 5e3,
 		maxBuffer: 16777216
 	});
@@ -4550,7 +4569,7 @@ async function readPosix() {
 async function readWindows() {
 	const script = "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,WorkingSetSize,KernelModeTime,UserModeTime | ConvertTo-Csv -NoTypeInformation";
 	try {
-		const { stdout } = await execFileAsync$2("powershell.exe", [
+		const { stdout } = await execFileAsync$3("powershell.exe", [
 			"-NoProfile",
 			"-NonInteractive",
 			"-Command",
@@ -4562,7 +4581,7 @@ async function readWindows() {
 		return parseWindowsCsv(stdout);
 	} catch {
 		try {
-			const { stdout } = await execFileAsync$2("wmic", [
+			const { stdout } = await execFileAsync$3("wmic", [
 				"process",
 				"get",
 				"ProcessId,ParentProcessId,WorkingSetSize,KernelModeTime,UserModeTime",
@@ -4614,7 +4633,7 @@ async function processCarriesServerId(pid, serverId) {
 		return false;
 	}
 	if (process.platform === "darwin") try {
-		const { stdout } = await execFileAsync$2("ps", [
+		const { stdout } = await execFileAsync$3("ps", [
 			"-p",
 			String(pid),
 			"-E",
@@ -4628,9 +4647,9 @@ async function processCarriesServerId(pid, serverId) {
 	}
 	return false;
 }
-var execFileAsync$2, clockTicks, ProcessSampler;
+var execFileAsync$3, clockTicks, ProcessSampler;
 var init_proc = __esmMin((() => {
-	execFileAsync$2 = promisify(execFile);
+	execFileAsync$3 = promisify(execFile);
 	clockTicks = null;
 	ProcessSampler = class {
 		previous = /* @__PURE__ */ new Map();
@@ -4703,6 +4722,224 @@ var init_proc = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/providers/identity.ts
+/**
+* Splits a command line into words, undoing the quoting Windows put there. `CommandLine`
+* is the raw string from the spawn call, so `"C:\a b\x.cmd" /c` is one argv entry plus
+* two words, and a quoted argument that contains spaces has to come back as one word.
+*
+* Windows also *escapes* a quote inside an argument as `\"` (Node does this for any argv
+* containing a quote), so the escape is undone here — otherwise every argument with a
+* quote in it survives as a stray backslash and never matches what the panel spawned.
+*/
+function splitCommandLine(line) {
+	const words = [];
+	let current = "";
+	let quoted = false;
+	let started = false;
+	for (const char of line.trim()) {
+		if (char === "\"") {
+			quoted = !quoted;
+			started = true;
+			continue;
+		}
+		if (!quoted && /\s/.test(char)) {
+			if (started) words.push(current);
+			current = "";
+			started = false;
+			continue;
+		}
+		current += char;
+		started = true;
+	}
+	if (started) words.push(current);
+	return words;
+}
+function comparable(target) {
+	const value = target.replace(/^"(.*)"$/, "$1").replace(/\\(?=")/g, "");
+	return process.platform === "win32" ? value.toLowerCase() : value;
+}
+/**
+* Literal comparison for an argument: the same text, modulo the case folding Windows needs
+* and the quoting a command line shuffles around.
+*
+* Deliberately *not* `sameWord`: folding an argument to its basename would let this
+* entry's `/srv/web/build/server.js` equal a stranger's `/tmp/evil/build/server.js`, and a
+* match here is what `reclaim` kills. Nor is it a plain string equality: reading an argv
+* back out of a Windows `CommandLine` cannot preserve quotes exactly — the OS escapes an
+* argument's own quote as `\"` and strips the structural ones — so quotes and backslashes
+* are dropped from both sides. That leaves the arguments' actual text, which is what the
+* match is about.
+*/
+function sameArg(a, b) {
+	const normalize = (value) => comparable(value).replace(/["\\]/g, "");
+	return normalize(a) === normalize(b);
+}
+/** The same file spelled differently (`node`, `node.exe`, a relative path) compares equal. */
+function sameWord(a, b) {
+	const left = comparable(a);
+	const right = comparable(b);
+	if (left === right || path.basename(left) === path.basename(right)) return true;
+	return path.extname(b) === "" && path.basename(left, path.extname(left)) === right;
+}
+/**
+* True when the argv a process is running is the entry's own: the image must match where
+* `spawn` would have looked it up — the image Path, or the first word of the command line
+* — and the words after it must open with the entry's args, compared literally. So
+* `spawn --port 4000` also covers `spawn -p 4000 --extra`, which is what a self-restarting
+* wrapper does, while `/tmp/evil/server.js` never covers `/srv/web/server.js`.
+*
+* `words` must already be the process's own argv. A command-line *string* is only correct
+* on Windows, where the OS hands one out; `/proc/<pid>/cmdline` quotes are literal bytes
+* of an argument, so re-joining that argv into one string corrupts it.
+*/
+function matchesSpawn(info, spawn) {
+	const { words } = info;
+	const first = words[0] ?? "";
+	if (!(sameWord(first, spawn.command) || info.imagePath != null && info.imagePath !== "" && sameWord(info.imagePath, spawn.command))) return false;
+	const offset = sameWord(first, spawn.command) ? 1 : 0;
+	if (words.length < spawn.args.length + offset) return false;
+	return spawn.args.every((arg, index) => sameArg(words[index + offset], arg));
+}
+/** The argv of a pid on the platforms whose process table can answer it; null otherwise. */
+async function processArgv(pid) {
+	if (process.platform === "win32") return null;
+	if (process.platform === "linux") try {
+		const argv = (await fs.promises.readFile(`/proc/${pid}/cmdline`)).toString("utf8").split("\0").filter((part) => part.length > 0);
+		return argv.length > 0 ? argv : null;
+	} catch {
+		return null;
+	}
+	try {
+		const { stdout } = await execFileAsync$2("ps", [
+			"-p",
+			String(pid),
+			"-ww",
+			"-o",
+			"command="
+		], { timeout: 3e3 });
+		const words = splitCommandLine(stdout.trim());
+		return words.length > 0 ? words : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The first two rows of `ConvertTo-Csv` output: the header and the first record. PowerShell
+* quotes and doubles its way around CSV, so `a,"b""c"` is three fields with the second
+* reading `b"c`.
+*/
+function parseCsvRows(output) {
+	const rows = [];
+	let row = [];
+	let field = "";
+	let quoted = false;
+	for (let index = 0; index < output.length; index++) {
+		const char = output[index];
+		if (quoted) {
+			if (char !== "\"") {
+				field += char;
+				continue;
+			}
+			if (output[index + 1] === "\"") {
+				field += "\"";
+				index++;
+				continue;
+			}
+			quoted = false;
+			continue;
+		}
+		if (char === "\"") {
+			quoted = true;
+			continue;
+		}
+		if (char === ",") {
+			row.push(field);
+			field = "";
+			continue;
+		}
+		if (char === "\n") {
+			row.push(field.replace(/\r$/, ""));
+			rows.push(row);
+			row = [];
+			field = "";
+			continue;
+		}
+		field += char;
+	}
+	if (field.length > 0 || row.length > 0) rows.push([...row, field.replace(/\r$/, "")]);
+	return [rows[0] ?? null, rows[1] ?? null];
+}
+/**
+* `Win32_Process` for one pid, or null when it cannot be read.
+*
+* The whole round trip — launching PowerShell, loading the CIM provider, serializing —
+* costs seconds on a cold runner, so the timeout is generous and the result is converted
+* to CSV rather than JSON: CSV survives a value that contains a quote or a newline, which
+* an argv legitimately can.
+*/
+async function windowsProcessInfo(pid) {
+	if (!windowsFilter.test(String(pid))) return null;
+	try {
+		const script = `Get-CimInstance Win32_Process -Filter "ProcessId=${pid}" | Select-Object CommandLine,ExecutablePath | ConvertTo-Csv -NoTypeInformation`;
+		const { stdout } = await execFileAsync$2("powershell", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			script
+		], {
+			timeout: 2e4,
+			windowsHide: true
+		});
+		const [headers, values] = parseCsvRows(stdout);
+		if (!headers || !values) return null;
+		const commandLineIndex = headers.indexOf("CommandLine");
+		const imageIndex = headers.indexOf("ExecutablePath");
+		const commandLine = commandLineIndex >= 0 ? values[commandLineIndex] : void 0;
+		if (commandLine === void 0 || commandLine.length === 0) return null;
+		const imagePath = imageIndex >= 0 ? values[imageIndex] : void 0;
+		return {
+			commandLine,
+			imagePath: imagePath && imagePath.length > 0 ? imagePath : null
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Which of these pids look like this entry's own detached successor. The environment
+* marker is authoritative where the platform can read it; otherwise the answer rests on
+* the entry's own argv, which is the only signal a detached successor is obliged to keep
+* — and the only one Windows exposes at all.
+*/
+async function identifyHolders(serverId, spawn, pids) {
+	const found = [];
+	for (const pid of pids) {
+		if (await processCarriesServerId(pid, serverId)) {
+			found.push(pid);
+			continue;
+		}
+		if (spawn.args.length === 0) continue;
+		if (process.platform === "win32") {
+			const info = await windowsProcessInfo(pid);
+			if (info && matchesSpawn({
+				words: splitCommandLine(info.commandLine),
+				imagePath: info.imagePath
+			}, spawn)) found.push(pid);
+			continue;
+		}
+		const argv = await processArgv(pid);
+		if (argv !== null && matchesSpawn({ words: argv }, spawn)) found.push(pid);
+	}
+	return found;
+}
+var execFileAsync$2, windowsFilter;
+var init_identity = __esmMin((() => {
+	init_proc();
+	execFileAsync$2 = promisify(execFile);
+	windowsFilter = /^\d+$/;
+}));
+//#endregion
 //#region src/providers/process.ts
 /**
 * Resolves a bare command through the entry's own directory and the project's
@@ -4966,6 +5203,7 @@ var init_supervisor = __esmMin((() => {
 	init_paths();
 	init_template();
 	init_health_check();
+	init_identity();
 	init_port();
 	init_proc();
 	init_process();
@@ -5110,11 +5348,8 @@ var init_supervisor = __esmMin((() => {
 				port,
 				error: `server "${id}" is busy — try again in a moment`
 			};
-			const supervised = this.supervisedPids();
-			const holders = await listPortHolders(port);
-			const ours = holders.filter((pid) => supervised.has(pid));
-			const foreign = holders.filter((pid) => !supervised.has(pid));
-			if (holders.length === 0) return {
+			const { ours, foreign } = await this.portHolders(port);
+			if ([...ours, ...foreign].length === 0) return {
 				...empty,
 				port,
 				error: `nothing is listening on port ${port} any more`
@@ -5129,7 +5364,7 @@ var init_supervisor = __esmMin((() => {
 				};
 			}
 			this.log(entry, "system", `freeing port ${port}: asking pid ${foreign.join(", ")} to stop`);
-			const { stopped, forced } = await terminatePids(foreign);
+			const { stopped, forced } = await terminatePids(foreign, { graceMs: entry.config.stop.graceMs });
 			if (forced.length > 0) this.log(entry, "system", `pid ${forced.join(", ")} ignored SIGTERM and was killed`);
 			const free = await this.waitForPortRelease(entry, port);
 			if (free) {
@@ -5154,6 +5389,20 @@ var init_supervisor = __esmMin((() => {
 				free
 			};
 		}
+		/**
+		* Splits the port's listeners into the processes this panel owns and everyone
+		* else. Only the foreign half may ever be signalled — a port held by a sibling
+		* is a config mistake, not a stray process. That also keeps a stale `(pid 1234)`
+		* in an old banner from killing a recycled pid.
+		*/
+		async portHolders(port) {
+			const supervised = this.supervisedPids();
+			const holders = await listPortHolders(port);
+			return {
+				ours: holders.filter((pid) => supervised.has(pid)),
+				foreign: holders.filter((pid) => !supervised.has(pid))
+			};
+		}
 		/** Pids of the child processes this panel owns, plus itself. */
 		supervisedPids() {
 			const pids = /* @__PURE__ */ new Set([process.pid]);
@@ -5320,7 +5569,7 @@ var init_supervisor = __esmMin((() => {
 			this.publishState();
 		}
 		isActive(entry) {
-			return entry.child !== null || entry.status === "backoff";
+			return entry.child !== null || entry.pid !== null || entry.adopted || entry.status === "backoff";
 		}
 		/** Loopback first, then the configured address, so a custom bind is still probed. */
 		probeHosts(entry) {
@@ -5343,15 +5592,24 @@ var init_supervisor = __esmMin((() => {
 			return (await Promise.all(this.occupancyHosts(entry).map((host) => probePort(host, port, timeoutMs)))).some(Boolean);
 		}
 		/**
-		* The port holders that carry this entry's own marker — a program that restarted
-		* itself leaves a detached process behind, and that process is the *same server*,
-		* not a stranger to kill. Read from the environment the supervisor gave the entry,
-		* which a successor inherits unless it scrubs it.
+		* The port holder that is this entry's own detached successor — a program that
+		* restarted itself leaves a process behind, and that process is the *same server*,
+		* not a stranger to kill.
+		*
+		* The environment marker is authoritative where the platform can read it (Linux,
+		* macOS). Failing that — Windows has no per-process environment at all — the entry's
+		* own argv answers, which a successor keeps unless it re-execs under a different
+		* image. Ambiguity is not resolved by guessing: two holders that both look like this
+		* entry means we do not know which one is ours, so we act on neither.
 		*/
-		async ownPortHolders(entry, holders) {
-			const own = [];
-			for (const pid of holders) if (await processCarriesServerId(pid, entry.config.id)) own.push(pid);
-			return own;
+		async ownPortHolder(entry, holders) {
+			const spawn = this.resolveSpawn(entry);
+			const candidates = await identifyHolders(entry.config.id, spawn, holders);
+			if (candidates.length > 1) {
+				this.log(entry, "system", `pid ${candidates.join(", ")} all look like this entry: refusing to guess which is ours, set onPortConflict to "kill" to clear the port anyway`);
+				return null;
+			}
+			return candidates[0] ?? null;
 		}
 		async preflight(entry) {
 			const port = entry.config.port;
@@ -5367,16 +5625,49 @@ var init_supervisor = __esmMin((() => {
 			}
 			entry.portState = free ? "free" : "in-use";
 			if (free) return { kind: "free" };
-			const holders = await listPortHolders(port);
-			const own = await this.ownPortHolders(entry, holders);
+			const { ours, foreign } = await this.portHolders(port);
+			const holders = [...ours, ...foreign];
+			const own = await this.ownPortHolder(entry, foreign);
 			const suffix = holders.length > 0 ? ` (pid ${holders.join(", ")})` : "";
-			if (own.length > 0 && entry.config.onPortConflict === "follow") return {
+			if (entry.config.onPortConflict === "kill") {
+				if (ours.length > 0) {
+					entry.status = "conflict";
+					entry.lastError = `port ${port} is held by pid ${ours.join(", ")}, which this panel supervises — stop that server instead`;
+					this.log(entry, "system", `${entry.lastError} — not starting (onPortConflict: kill)`);
+					this.publishServer(entry);
+					return {
+						kind: "blocked",
+						error: entry.lastError
+					};
+				}
+				if (foreign.length === 0) {
+					this.log(entry, "system", `port ${port} looks busy but no listener could be found — starting anyway`);
+					return { kind: "free" };
+				}
+				this.log(entry, "system", `port ${port} is held by pid ${foreign.join(", ")} — onPortConflict: kill, stopping the holder`);
+				const { forced } = await terminatePids(foreign, { graceMs: entry.config.stop.graceMs });
+				if (forced.length > 0) this.log(entry, "system", `pid ${forced.join(", ")} ignored SIGTERM and was killed`);
+				await delay(PORT_RELEASE_RECHECK_MS);
+				if (await freeOnAll()) {
+					entry.portState = "free";
+					return { kind: "free" };
+				}
+				entry.status = "conflict";
+				entry.lastError = `port ${port} is still in use after killing pid ${foreign.join(", ")}`;
+				this.log(entry, "system", entry.lastError);
+				this.publishServer(entry);
+				return {
+					kind: "blocked",
+					error: entry.lastError
+				};
+			}
+			if (own !== null && entry.config.onPortConflict === "follow") return {
 				kind: "adopt",
-				pid: own[0]
+				pid: own
 			};
-			if (own.length > 0 && entry.config.onPortConflict === "reclaim") {
-				this.log(entry, "system", `port ${port} is held by pid ${own.join(", ")}, a detached restart of this entry — replacing it with a supervised process`);
-				const { forced } = await terminatePids(own);
+			if (own !== null && entry.config.onPortConflict === "reclaim") {
+				this.log(entry, "system", `port ${port} is held by pid ${own}, a detached restart of this entry — replacing it with a supervised process`);
+				const { forced } = await terminatePids([own], { graceMs: entry.config.stop.graceMs });
 				if (forced.length > 0) this.log(entry, "system", `pid ${forced.join(", ")} ignored SIGTERM and was killed`);
 				await delay(PORT_RELEASE_RECHECK_MS);
 				if (await freeOnAll()) {
@@ -5384,7 +5675,7 @@ var init_supervisor = __esmMin((() => {
 					return { kind: "free" };
 				}
 				entry.status = "conflict";
-				entry.lastError = `port ${port} is still in use after replacing pid ${own.join(", ")}`;
+				entry.lastError = `port ${port} is still in use after replacing pid ${own}`;
 				this.log(entry, "system", entry.lastError);
 				this.publishServer(entry);
 				return {
@@ -5392,7 +5683,7 @@ var init_supervisor = __esmMin((() => {
 					error: entry.lastError
 				};
 			}
-			const hint = own.length > 0 ? ` — pid ${own.join(", ")} is a detached restart of this entry: set onPortConflict to "follow" to adopt it, or "reclaim" to replace it with a supervised process` : "";
+			const hint = own !== null ? ` — pid ${own} is a detached restart of this entry: set onPortConflict to "follow" to adopt it, "reclaim" to replace it with a supervised process, or "kill" to stop whatever holds the port` : "";
 			if (entry.config.onPortConflict !== "warn") {
 				entry.status = "conflict";
 				entry.lastError = `port ${port} is already in use${suffix}${hint}`;
@@ -5487,7 +5778,13 @@ var init_supervisor = __esmMin((() => {
 			if (code === 0) this.log(entry, "system", "bootstrap finished");
 			else if (code !== null) this.log(entry, "system", `bootstrap exited with code ${code} — continuing anyway`);
 		}
-		spawnEntry(entry) {
+		/**
+		* Everything `spawn` needs for an entry: the resolved image, the expanded argv, the
+		* cwd and the environment. The argv is also what the preflight recognizes the entry's
+		* own detached successor by, so spawn and identification must never resolve it twice
+		* with two different rules.
+		*/
+		resolveSpawn(entry) {
 			const vars = this.buildVars(entry);
 			const cwd = resolveCwd(entry.config.cwd);
 			const command = resolveCommand(entry.config.command, cwd, projectDir);
@@ -5503,15 +5800,26 @@ var init_supervisor = __esmMin((() => {
 				...process.env,
 				...fileEnv
 			};
-			const args = expandEnvList(resolveTemplates(entry.config.args, vars), expansionVars);
+			const dataEnvs = resolveRecord(entry.config.dataEnvs, vars);
 			const env = {
 				...expandEnvRecord(resolveRecord(entry.config.env, vars), expansionVars),
 				...fileEnv,
-				...expandEnvRecord(resolveRecord(entry.config.dataEnvs, vars), expansionVars),
+				...expandEnvRecord(dataEnvs, expansionVars),
 				HHOSTED_SERVER_ID: entry.config.id,
 				HHOSTED_CONTROL_PORT: String(this.options.control.port)
 			};
-			this.log(entry, "system", `start: ${command} ${resolveTemplates(entry.config.args, vars).join(" ")}`);
+			for (const key of Object.keys(dataEnvs)) env[key] = path.resolve(cwd, env[key]);
+			return {
+				command,
+				args: expandEnvList(resolveTemplates(entry.config.args, vars), expansionVars),
+				env,
+				cwd,
+				loggedArgs: resolveTemplates(entry.config.args, vars)
+			};
+		}
+		spawnEntry(entry) {
+			const { command, args, env, cwd, loggedArgs } = this.resolveSpawn(entry);
+			this.log(entry, "system", `start: ${command} ${loggedArgs.join(" ")}`);
 			let child;
 			try {
 				child = spawnManaged({
@@ -7515,7 +7823,11 @@ var init_ui = __esmMin((() => {
 	MAX_NAME = 120;
 	manifestSchema = type({
 		"name?": "string",
-		"version?": "string"
+		"version?": "string",
+		"repo?": "string",
+		"tag?": "string",
+		"asset?": "string",
+		"unix?": "number.integer >= 0"
 	});
 	UiService = class {
 		options;
@@ -7555,14 +7867,14 @@ var init_ui = __esmMin((() => {
 		* swapped in, so a failed upload leaves the previous UI (or the stock one)
 		* serving.
 		*/
-		async install(archivePath, fallbackName = "custom-ui") {
+		async install(archivePath, fallbackName = "custom-ui", installedTag) {
 			if (!isZipArchive(archivePath)) return {
 				ok: false,
 				error: "the upload is not a zip archive"
 			};
 			const staging = path.join(this.options.dataRoot, `.ui-staging-${Date.now()}`);
 			try {
-				return await this.stage(archivePath, staging, fallbackName);
+				return await this.stage(archivePath, staging, fallbackName, installedTag);
 			} catch (error) {
 				return {
 					ok: false,
@@ -7584,7 +7896,7 @@ var init_ui = __esmMin((() => {
 			});
 			return existed;
 		}
-		async stage(archivePath, staging, fallbackName) {
+		async stage(archivePath, staging, fallbackName, installedTag) {
 			let entries;
 			try {
 				entries = await listZip(archivePath);
@@ -7623,33 +7935,43 @@ var init_ui = __esmMin((() => {
 				name: manifest?.name ?? fallbackName,
 				version: manifest?.version ?? null,
 				uploadedAt: Date.now(),
-				files: countFiles(root)
+				files: countFiles(root),
+				...manifest?.repo === void 0 ? {} : { repo: manifest.repo },
+				...installedTag !== void 0 ? { tag: installedTag } : manifest?.tag === void 0 ? {} : { tag: manifest.tag },
+				...manifest?.asset === void 0 ? {} : { asset: manifest.asset },
+				...manifest?.unix === void 0 ? {} : { unix: manifest.unix }
 			};
-			const previous = `${this.directory}.previous`;
-			fs.rmSync(previous, {
-				recursive: true,
-				force: true
-			});
+			const previous = `${this.directory}.previous-${process.pid}-${Date.now()}`;
 			if (fs.existsSync(this.directory)) fs.renameSync(this.directory, previous);
 			try {
 				fs.renameSync(root, this.directory);
 				writeFileAtomic(path.join(this.directory, META), `${JSON.stringify(meta, null, 2)}\n`);
 			} catch (error) {
-				fs.rmSync(this.directory, {
-					recursive: true,
-					force: true
-				});
-				if (fs.existsSync(previous)) fs.renameSync(previous, this.directory);
+				try {
+					fs.rmSync(this.directory, {
+						recursive: true,
+						force: true
+					});
+					if (fs.existsSync(previous)) fs.renameSync(previous, this.directory);
+					fs.rmSync(previous, {
+						recursive: true,
+						force: true
+					});
+				} catch {
+					return {
+						ok: false,
+						error: `${error instanceof Error ? error.message : String(error)} — the previous UI is kept at ${previous}`
+					};
+				}
 				return {
 					ok: false,
 					error: error instanceof Error ? error.message : String(error)
 				};
-			} finally {
-				fs.rmSync(previous, {
-					recursive: true,
-					force: true
-				});
 			}
+			fs.rmSync(previous, {
+				recursive: true,
+				force: true
+			});
 			return {
 				ok: true,
 				meta
@@ -7658,95 +7980,488 @@ var init_ui = __esmMin((() => {
 	};
 }));
 //#endregion
-//#region src/index.ts
-var src_exports = /* @__PURE__ */ __exportAll({
-	packageRoot: () => packageRoot,
-	runControlPlane: () => runControlPlane
-});
-function packageVersion() {
-	try {
-		return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "0.0.0";
-	} catch {
-		return "0.0.0";
-	}
+//#region src/providers/ui-release.ts
+/** `owner/name`, the only slug GitHub releases are addressed by. */
+function parseRepoSlug(value) {
+	const match = /^([\w.-]+)\/([\w.-]+)$/.exec(value.trim());
+	if (match === null) return null;
+	return {
+		owner: match[1],
+		name: match[2]
+	};
 }
-/** A probe target for a `lan` bind, which is not connectable as `0.0.0.0`. */
-function probeHostFor(bindHost) {
-	return bindHost === "0.0.0.0" || bindHost === "::" ? "127.0.0.1" : bindHost;
+function repoSlug(repo) {
+	return `${repo.owner}/${repo.name}`;
+}
+/** The repo the default tag rule is about; `DEFAULT_REPO` is its only definition. */
+function isOwnRepo(repo) {
+	return repoSlug(repo).toLowerCase() === DEFAULT_REPO.toLowerCase();
 }
 /**
-* Runs the control plane in *this* process until it is stopped. `home-hosted up`
-* detaches a child that calls this; `--foreground` (systemd, docker) calls it
-* directly.
+* Our own release tag matches this CLI's version, so a UI is paired with the panel
+* it was built for. Another repo has no such pairing, so its latest release is used.
+* `null` means "latest".
 */
-async function runControlPlane(options) {
-	const existing = readRuntime();
-	if (existing !== null && existing.pid !== process.pid && isProcessAlive$1(existing.pid)) {
-		logger.error(`already running (pid ${existing.pid}) at ${existing.url} — run \`home-hosted down\` first`);
-		process.exit(1);
-	}
-	if (existing !== null) clearRuntime();
-	const configPath = options.configPath ?? defaultConfigPath;
-	const store = new ConfigStore(configPath, SEED_CONFIG);
-	store.load();
-	store.writeJsonSchema();
-	if (store.configError !== null) {
-		logger.error(`refusing to start: ${store.configError}`);
-		logger.info(`fix ${store.path}, or install the release that wrote it`);
-		process.exit(1);
-	}
-	if (store.pendingMigrations.length > 0) {
-		logger.error(`refusing to start: ${store.path} needs ${store.pendingMigrations.length} migration(s) before ${appVersion()} can use it`);
-		logger.info("run `home-hosted migrate` to see and apply them");
-		process.exit(1);
-	}
-	const secrets = new SecretsStore(defaultSecretsPath);
-	const auth = new AuthService(secrets, () => store.config.control.auth);
-	const tls = new TlsStore(defaultTlsDir);
-	const logFiles = new LogFiles(defaultLogsDir, () => store.config.logs);
-	const history = new HistoryStore(defaultHistoryPath);
-	const notifications = new NotificationService(secrets, () => store.config.notifications, () => store.config.logs);
-	const hostMonitor = new HostMonitor(() => store.config.host, (target) => resolveUserPath(resolveTemplate(target, {
-		projectDir,
-		dataRoot,
-		home: os.homedir()
-	})), notifications);
-	let onConfigRestored;
-	const backups = new BackupService({
-		dataRoot,
-		getConfig: () => store.config.backups,
-		getSources: () => ({
-			configPath: store.path,
-			secretsPath: secrets.path,
-			tlsDir: tls.directory,
-			paths: resolveBackupPaths(store.servers, store.config.backups.includePaths)
-		}),
-		onConfigRestored: () => onConfigRestored?.()
-	});
-	if (!auth.passwordSet) {
-		auth.ensureDefaultPassword("hh");
-		logger.warn(`no password was set — created the default "hh"; change it in Settings → Authentication`);
-	}
-	const configured = store.config.control;
-	const intendedHost = options.host === void 0 ? configured.host : parseBind(options.host);
-	if (intendedHost === null) {
-		logger.error(`invalid control host: ${String(options.host)} (expected local, lan or an ipv4 address)`);
-		process.exit(1);
-	}
-	const intended = {
-		host: intendedHost,
-		port: options.port ?? configured.port
-	};
-	if (!Number.isInteger(intended.port) || intended.port <= 0 || intended.port > 65535) {
-		logger.error(`invalid control port: ${String(options.port)}`);
-		process.exit(1);
-	}
-	if (options.printConfig) {
-		process.stdout.write(`${JSON.stringify(store.config, null, 2)}\n`);
-		return;
-	}
-	const exposure = checkExposure({
-		...configured,
+function defaultReleaseTag(repo, version) {
+	return isOwnRepo(repo) ? `v${version}` : null;
+}
+function releaseApiUrl(repo, tag) {
+	const base = `https://api.github.com/repos/${repo.owner}/${repo.name}/releases`;
+	if (tag === null || tag.length === 0 || tag === "latest") return `${base}/latest`;
+	return `${base}/tags/${encodeURIComponent(tag)}`;
+}
+/** Every published release, newest first, as GitHub orders them. */
+function releasesApiUrl(repo, perPage = 30) {
+	return `https://api.github.com/repos/${repo.owner}/${repo.name}/releases?per_page=${perPage}`;
+}
+/** Generous and predictable: a UI bundle is an asset whose name ends in `.zip`. */
+function isUiAsset(name) {
+	return /\.zip$/i.test(name.trim());
+}
+/**
+* Resolves a wanted asset: an exact name, a case-insensitive name, or a single
+* unambiguous substring (`--asset stock` for `home-hosted-ui-stock.zip`).
+*/
+function matchAsset(names, query) {
+	const wanted = query.trim();
+	if (wanted.length === 0) return {
+		ok: false,
+		error: "no asset name was given"
+	};
+	const exact = names.find((name) => name === wanted);
+	if (exact !== void 0) return {
+		ok: true,
+		name: exact
+	};
+	const lower = wanted.toLowerCase();
+	const insensitive = names.filter((name) => name.toLowerCase() === lower);
+	if (insensitive.length === 1) return {
+		ok: true,
+		name: insensitive[0]
+	};
+	const partial = names.filter((name) => name.toLowerCase().includes(lower));
+	if (partial.length === 0) return {
+		ok: false,
+		error: `no asset matches "${wanted}" (available: ${names.join(", ") || "none"})`
+	};
+	if (partial.length > 1) return {
+		ok: false,
+		error: `"${wanted}" matches more than one asset: ${partial.join(", ")} — use the full name`
+	};
+	return {
+		ok: true,
+		name: partial[0]
+	};
+}
+/** `^https?://` means a URL; anything else is a filesystem path with `~` expanded. */
+function parseFileSource(value) {
+	const trimmed = value.trim();
+	if (/^https?:\/\//i.test(trimmed)) return {
+		kind: "url",
+		url: trimmed
+	};
+	return {
+		kind: "path",
+		path: expandHome(trimmed)
+	};
+}
+function expandHome(value) {
+	if (value === "~") return os.homedir();
+	if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2));
+	return value;
+}
+/**
+* A token is only ever sent to GitHub: `--file <url>` may point anywhere, and a
+* credential must not leak to a host the user did not vouch for.
+*/
+function isGithubHost(url) {
+	try {
+		const host = new URL(url).hostname.toLowerCase();
+		return host === "github.com" || host.endsWith(".github.com") || host === "githubusercontent.com" || host.endsWith(".githubusercontent.com");
+	} catch {
+		return false;
+	}
+}
+function timeoutSignal(ms) {
+	return typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
+}
+function isTimeout(error) {
+	return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+/** What `UiService` names the install when the archive carries no `ui.json`. */
+function fallbackUiName(source) {
+	const stripped = path.basename(source).replace(/\.zip$/i, "").replace(/^home-hosted-ui-/i, "");
+	return stripped.length > 0 ? stripped : "custom-ui";
+}
+/** One release's assets, or a message that says what was wrong with the answer. */
+async function fetchRelease(repo, tag, context) {
+	const url = releaseApiUrl(repo, tag);
+	let response;
+	try {
+		response = await fetch(url, {
+			headers: apiHeaders(context),
+			signal: timeoutSignal(REQUEST_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new Error(isTimeout(error) ? `GitHub did not answer within ${REQUEST_TIMEOUT_MS / 1e3}s` : `could not reach GitHub: ${describeError(error)}`);
+	}
+	if (!response.ok) throw new Error(describeReleaseFailure(response.status, repo, tag));
+	const body = await response.json();
+	return {
+		tag: body.tag_name ?? tag ?? "latest",
+		assets: Array.isArray(body.assets) ? body.assets : []
+	};
+}
+/** Every published release, newest first. Drafts and unusable entries are dropped. */
+async function fetchReleases(repo, context, perPage = 30) {
+	let response;
+	try {
+		response = await fetch(releasesApiUrl(repo, perPage), {
+			headers: apiHeaders(context),
+			signal: timeoutSignal(REQUEST_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new Error(isTimeout(error) ? `GitHub did not answer within ${REQUEST_TIMEOUT_MS / 1e3}s` : `could not reach GitHub: ${describeError(error)}`);
+	}
+	if (!response.ok) throw new Error(describeReleaseFailure(response.status, repo, null));
+	const body = await response.json();
+	if (!Array.isArray(body)) return [];
+	return body.filter((release) => release.draft !== true && typeof release.tag_name === "string").map((release) => ({
+		tag: release.tag_name,
+		assets: Array.isArray(release.assets) ? release.assets : [],
+		publishedAt: typeof release.published_at === "string" ? release.published_at : null
+	}));
+}
+function assetDownloadUrl(asset) {
+	const url = asset.url ?? asset.browser_download_url;
+	if (url === void 0 || url.length === 0) throw new Error(`the release metadata for "${asset.name ?? "an asset"}" carries no download URL`);
+	return url;
+}
+/** Streams to `os.tmpdir()` so a large body is never buffered in memory. */
+async function downloadToTemp(url, headers, context) {
+	let response;
+	try {
+		response = await fetch(url, {
+			headers,
+			redirect: "follow",
+			signal: timeoutSignal(DOWNLOAD_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new Error(isTimeout(error) ? `the download stalled for ${DOWNLOAD_TIMEOUT_MS / 1e3}s: ${url}` : `could not reach ${url}: ${describeError(error)}`);
+	}
+	if (!response.ok) throw new Error(describeDownloadFailure(response.status, url));
+	const declared = Number(response.headers.get("content-length") ?? "0");
+	if (!Number.isFinite(declared) || declared < 0) throw new Error(`the download from ${url} reported an unusable size`);
+	if (declared > 536870912) throw new Error(tooLargeMessage(declared));
+	if (response.body === null) throw new Error(`the download from ${url} had no body`);
+	const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hh-ui-"));
+	const file = path.join(dir, "ui.zip");
+	const handle = await fs.promises.open(file, "w");
+	let received = 0;
+	try {
+		for await (const chunk of response.body) {
+			received += chunk.length;
+			if (received > 536870912) throw new Error(tooLargeMessage(received));
+			await handle.write(chunk);
+		}
+	} catch (error) {
+		await handle.close();
+		fs.rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		throw error instanceof Error ? error : new Error(String(error));
+	}
+	await handle.close();
+	if (context.quiet !== true) context.io.write(`${context.io.style.dim(`downloaded ${formatBytes(received)}`)}\n`);
+	return {
+		dir,
+		file
+	};
+}
+function apiHeaders(context) {
+	const headers = {
+		"accept": "application/vnd.github+json",
+		"user-agent": `home-hosted/${context.version}`,
+		"x-github-api-version": "2022-11-28"
+	};
+	if (context.token !== null && context.token.length > 0) headers.authorization = `Bearer ${context.token}`;
+	return headers;
+}
+function noAssetsMessage(where, skipped, tag) {
+	const lines = [`no usable UI assets in ${where} (expected a .zip)`];
+	lines.push(skipped.length > 0 ? `  skipped: ${skipped.join(", ")}` : "  the release has no assets at all");
+	if (tag !== null && tag !== "latest") lines.push("  installing a different version silently is worse than failing: try the newest release with --tag latest");
+	return lines.join("\n");
+}
+function describeReleaseFailure(status, repo, tag) {
+	const slug = repoSlug(repo);
+	if (status === 404) {
+		if (tag !== null && tag !== "latest") return `no release tagged "${tag}" in ${slug}\n  list what exists with: home-hosted ui-switch --repo ${slug} --tag latest --list`;
+		return `no repository or published release at ${slug}\n  check the --repo slug (owner/name), and that the repository is public`;
+	}
+	if (status === 403 || status === 429) return `GitHub refused the request (HTTP ${status}) — the unauthenticated API rate limit is per address.\n  set a token to raise it: --token <token>, or GITHUB_TOKEN / GH_TOKEN`;
+	if (status === 401) return "GitHub rejected the token (HTTP 401) — check --token, GITHUB_TOKEN or GH_TOKEN";
+	return `GitHub answered HTTP ${status} while reading the release of ${slug}`;
+}
+function describeDownloadFailure(status, url) {
+	const github = isGithubHost(url);
+	if (status === 404) return github ? `the asset is gone (HTTP 404) — ${url}\n  the release may have been rebuilt since it was listed; run the command again` : `nothing is served at that URL (HTTP 404) — ${url}`;
+	if (status === 403 || status === 429) return github ? `GitHub refused the download (HTTP ${status}) — a token raises the rate limit: --token <token>, or GITHUB_TOKEN / GH_TOKEN` : `the host refused the download (HTTP ${status}) — ${url}`;
+	if (status === 401 && github) return "GitHub rejected the token on the download (HTTP 401) — check --token, GITHUB_TOKEN or GH_TOKEN";
+	return `the download failed (HTTP ${status}) — ${url}`;
+}
+function tooLargeMessage(bytes) {
+	return `the download is ${formatBytes(bytes)}, larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB a UI may be`;
+}
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${Math.round(bytes / 1024)} KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Tag ordering: `v1.2.3` beats `v1.2.2`, a prerelease loses to its release, and anything
+* that is not a version sorts below every version that is. Enough to answer "is this
+* release newer than the one the UI came from" without a semver dependency.
+*/
+function compareTags(a, b) {
+	const left = parseTag(a);
+	const right = parseTag(b);
+	if (left === null && right === null) return a.localeCompare(b);
+	if (left === null) return -1;
+	if (right === null) return 1;
+	for (let index = 0; index < 3; index++) {
+		const difference = (left.parts[index] ?? 0) - (right.parts[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+	if (left.prerelease.length === 0) return 1;
+	if (right.prerelease.length === 0) return -1;
+	for (let index = 0; index < Math.max(left.prerelease.length, right.prerelease.length); index++) {
+		const one = left.prerelease[index];
+		const two = right.prerelease[index];
+		if (one === void 0) return -1;
+		if (two === void 0) return 1;
+		if (one === two) continue;
+		const numeric = /^\d+$/;
+		if (numeric.test(one) && numeric.test(two)) return Number(one) - Number(two);
+		if (numeric.test(one)) return -1;
+		if (numeric.test(two)) return 1;
+		return one.localeCompare(two);
+	}
+	return 0;
+}
+function parseTag(tag) {
+	const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(tag.trim());
+	if (match === null) return null;
+	return {
+		parts: [
+			Number(match[1]),
+			Number(match[2] ?? 0),
+			Number(match[3] ?? 0)
+		],
+		prerelease: match[4] === void 0 ? [] : match[4].split(".")
+	};
+}
+var DEFAULT_REPO, MAX_DOWNLOAD_BYTES, REQUEST_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS;
+var init_ui_release = __esmMin((() => {
+	DEFAULT_REPO = "NamesMT/home-hosted";
+	MAX_DOWNLOAD_BYTES = 536870912;
+	REQUEST_TIMEOUT_MS = 3e4;
+	DOWNLOAD_TIMEOUT_MS = 12e4;
+}));
+//#endregion
+//#region src/services/ui-update.ts
+/**
+* `ui.json` says which release this build came from. Anything else — an unofficial UI,
+* or one that never declared itself — is left for `home-hosted ui-update`.
+*/
+function officialTagFor(meta, runningVersion) {
+	if (meta === null || typeof meta.repo !== "string") return null;
+	const repo = parseRepoSlug(meta.repo);
+	if (repo === null || !isOwnRepo(repo)) return null;
+	return {
+		tag: `v${runningVersion}`,
+		repo: `${repo.owner}/${repo.name}`
+	};
+}
+async function syncOfficialUi(ui, runningVersion = appVersion()) {
+	if (!ui.custom) return { kind: "not-custom" };
+	const meta = ui.readMeta();
+	if (meta === null) return { kind: "no-identity" };
+	const repo = meta.repo === void 0 ? null : parseRepoSlug(meta.repo);
+	if (repo === null) return { kind: "no-identity" };
+	if (!isOwnRepo(repo)) return { kind: "foreign" };
+	const target = `v${runningVersion}`;
+	if (meta.tag === target) return {
+		kind: "current",
+		tag: target
+	};
+	const context = {
+		io: {
+			write: () => {},
+			style: {
+				bold: (t) => t,
+				dim: (t) => t,
+				green: (t) => t
+			}
+		},
+		version: runningVersion,
+		token: process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? null,
+		quiet: true
+	};
+	try {
+		const release = await fetchRelease(repo, target, context);
+		const names = release.assets.map((asset) => asset.name ?? "").filter(isUiAsset);
+		if (names.length === 0) throw new Error(`no UI asset in ${DEFAULT_REPO}@${release.tag}`);
+		const wanted = meta.asset ?? "";
+		const matched = wanted.length > 0 ? matchAsset(names, wanted) : {
+			ok: true,
+			name: names[0]
+		};
+		if (!matched.ok) throw new Error(matched.error);
+		const asset = release.assets.find((entry) => entry.name === matched.name);
+		if (asset === void 0) throw new Error(`no asset named ${matched.name} in ${release.tag}`);
+		const download = await downloadToTemp(assetDownloadUrl(asset), {
+			"accept": "application/octet-stream",
+			"user-agent": `home-hosted/${runningVersion}`
+		}, context);
+		try {
+			const result = await ui.install(download.file, matched.name.replace(/\.zip$/i, ""), release.tag);
+			if (!result.ok) throw new Error(result.error);
+		} finally {
+			(await import("node:fs")).rmSync(download.dir, {
+				recursive: true,
+				force: true
+			});
+		}
+		return {
+			kind: "updated",
+			tag: release.tag
+		};
+	} catch (error) {
+		return {
+			kind: "failed",
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/**
+* The startup hook. Never awaited by the caller and never allowed to throw: the panel
+* serves the UI it already has while this runs, and the next request picks up the new
+* one, because `UiService.resolveDir()` is read per request.
+*/
+function autoUpdateOfficialUi(ui, runningVersion = appVersion()) {
+	if (!ui.custom) return;
+	const meta = ui.readMeta();
+	const plan = officialTagFor(meta, runningVersion);
+	if (plan === null || meta?.tag === plan.tag) return;
+	logger.info(`ui:      ${meta?.name ?? "custom UI"} ${meta?.version ?? ""} came from ${meta?.tag ?? "an unknown release"}; this panel is ${plan.tag} — updating`);
+	syncOfficialUi(ui, runningVersion).then((result) => {
+		if (result.kind === "updated") logger.info(`ui:      updated to ${result.tag} — refresh the browser`);
+		else if (result.kind === "failed") logger.warn(`ui:      could not update to ${plan.tag}: ${result.error}`);
+	}).catch((error) => {
+		logger.warn(`ui:      could not update: ${error instanceof Error ? error.message : String(error)}`);
+	});
+}
+var init_ui_update$1 = __esmMin((() => {
+	init_logger();
+	init_version();
+	init_ui_release();
+}));
+//#endregion
+//#region src/index.ts
+var src_exports = /* @__PURE__ */ __exportAll({
+	packageRoot: () => packageRoot,
+	runControlPlane: () => runControlPlane
+});
+function packageVersion() {
+	try {
+		return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+/** A probe target for a `lan` bind, which is not connectable as `0.0.0.0`. */
+function probeHostFor(bindHost) {
+	return bindHost === "0.0.0.0" || bindHost === "::" ? "127.0.0.1" : bindHost;
+}
+/**
+* Runs the control plane in *this* process until it is stopped. `home-hosted up`
+* detaches a child that calls this; `--foreground` (systemd, docker) calls it
+* directly.
+*/
+async function runControlPlane(options) {
+	const existing = readRuntime();
+	if (existing !== null && existing.pid !== process.pid && isProcessAlive$1(existing.pid)) {
+		logger.error(`already running (pid ${existing.pid}) at ${existing.url} — run \`home-hosted down\` first`);
+		process.exit(1);
+	}
+	if (existing !== null) clearRuntime();
+	const configPath = options.configPath ?? defaultConfigPath;
+	const store = new ConfigStore(configPath, SEED_CONFIG);
+	store.load();
+	store.writeJsonSchema();
+	if (store.configError !== null) {
+		logger.error(`refusing to start: ${store.configError}`);
+		logger.info(`fix ${store.path}, or install the release that wrote it`);
+		process.exit(1);
+	}
+	if (store.pendingMigrations.length > 0) {
+		logger.error(`refusing to start: ${store.path} needs ${store.pendingMigrations.length} migration(s) before ${appVersion()} can use it`);
+		logger.info("run `home-hosted migrate` to see and apply them");
+		process.exit(1);
+	}
+	const secrets = new SecretsStore(defaultSecretsPath);
+	const auth = new AuthService(secrets, () => store.config.control.auth);
+	const tls = new TlsStore(defaultTlsDir);
+	const logFiles = new LogFiles(defaultLogsDir, () => store.config.logs);
+	const history = new HistoryStore(defaultHistoryPath);
+	const notifications = new NotificationService(secrets, () => store.config.notifications, () => store.config.logs);
+	const hostMonitor = new HostMonitor(() => store.config.host, (target) => resolveUserPath(resolveTemplate(target, {
+		projectDir,
+		dataRoot,
+		home: os.homedir()
+	})), notifications);
+	let onConfigRestored;
+	const backups = new BackupService({
+		dataRoot,
+		getConfig: () => store.config.backups,
+		getSources: () => ({
+			configPath: store.path,
+			secretsPath: secrets.path,
+			tlsDir: tls.directory,
+			paths: resolveBackupPaths(store.servers, store.config.backups.includePaths)
+		}),
+		onConfigRestored: () => onConfigRestored?.()
+	});
+	if (!auth.passwordSet) {
+		auth.ensureDefaultPassword("hh");
+		logger.warn(`no password was set — created the default "hh"; change it in Settings → Authentication`);
+	}
+	const configured = store.config.control;
+	const intendedHost = options.host === void 0 ? configured.host : parseBind(options.host);
+	if (intendedHost === null) {
+		logger.error(`invalid control host: ${String(options.host)} (expected local, lan or an ipv4 address)`);
+		process.exit(1);
+	}
+	const intended = {
+		host: intendedHost,
+		port: options.port ?? configured.port
+	};
+	if (!Number.isInteger(intended.port) || intended.port <= 0 || intended.port > 65535) {
+		logger.error(`invalid control port: ${String(options.port)}`);
+		process.exit(1);
+	}
+	if (options.printConfig) {
+		process.stdout.write(`${JSON.stringify(store.config, null, 2)}\n`);
+		return;
+	}
+	const exposure = checkExposure({
+		...configured,
 		host: intended.host
 	}, auth.passwordSet, auth.usingDefaultPassword);
 	if (exposure.blockedReason !== null) {
@@ -7894,6 +8609,7 @@ async function runControlPlane(options) {
 	if (ui.custom) {
 		const meta = ui.status().meta;
 		logger.warn(`custom UI in use${meta === null ? "" : ` (${meta.name}${meta.version === null ? "" : ` ${meta.version}`})`} — if it breaks, run \`home-hosted ui-revert\``);
+		autoUpdateOfficialUi(ui, runtime.version);
 	}
 	for (const warning of store.configWarnings) logger.warn(warning);
 	for (const entry of supervisor.views()) logger.info(`  ${entry.id.padEnd(12)} ${entry.config.command} ${entry.config.args.join(" ")}`.trimEnd());
@@ -7950,6 +8666,7 @@ var init_src = __esmMin((() => {
 	init_supervisor();
 	init_tls();
 	init_ui();
+	init_ui_update$1();
 	init_contracts();
 	packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 }));
@@ -8711,137 +9428,50 @@ var init_init = __esmMin((() => {
 	};
 	initCommand = defineCommand({
 		meta: {
-			name: "init",
-			description: "scaffold a project that keeps its state in the repo"
-		},
-		args: initArgs,
-		run: async ({ args }) => {
-			await runInit({
-				dir: args.dir,
-				name: args.name,
-				pm: args.pm,
-				noInstall: args.install === false,
-				yes: args.yes === true
-			});
-		}
-	});
-}));
-//#endregion
-//#region src/cli/ui-switch.ts
-var ui_switch_exports = /* @__PURE__ */ __exportAll({
-	DEFAULT_REPO: () => DEFAULT_REPO,
-	MAX_DOWNLOAD_BYTES: () => MAX_DOWNLOAD_BYTES,
-	defaultReleaseTag: () => defaultReleaseTag,
-	fallbackUiName: () => fallbackUiName,
-	isGithubHost: () => isGithubHost,
-	isOwnRepo: () => isOwnRepo,
-	isUiAsset: () => isUiAsset,
-	matchAsset: () => matchAsset,
-	parseFileSource: () => parseFileSource,
-	parseRepoSlug: () => parseRepoSlug,
-	releaseApiUrl: () => releaseApiUrl,
-	uiSwitch: () => uiSwitch,
-	uiSwitchCommand: () => uiSwitchCommand
-});
-/** `owner/name`, the only slug GitHub releases are addressed by. */
-function parseRepoSlug(value) {
-	const match = /^([\w.-]+)\/([\w.-]+)$/.exec(value.trim());
-	if (match === null) return null;
-	return {
-		owner: match[1],
-		name: match[2]
-	};
-}
-/** The repo the default tag rule is about; `DEFAULT_REPO` is its only definition. */
-function isOwnRepo(repo) {
-	return `${repo.owner}/${repo.name}`.toLowerCase() === DEFAULT_REPO.toLowerCase();
-}
-/**
-* Our own release tag matches this CLI's version, so a UI is paired with the panel
-* it was built for. Another repo has no such pairing, so its latest release is used.
-* `null` means "latest".
-*/
-function defaultReleaseTag(repo, version) {
-	return isOwnRepo(repo) ? `v${version}` : null;
-}
-function releaseApiUrl(repo, tag) {
-	const base = `https://api.github.com/repos/${repo.owner}/${repo.name}/releases`;
-	if (tag === null || tag.length === 0 || tag === "latest") return `${base}/latest`;
-	return `${base}/tags/${encodeURIComponent(tag)}`;
-}
-/** Generous and predictable: a UI bundle is an asset whose name ends in `.zip`. */
-function isUiAsset(name) {
-	return /\.zip$/i.test(name.trim());
-}
-/**
-* Resolves `--asset`: an exact name, a case-insensitive name, or a single
-* unambiguous substring (`--asset stock` for `home-hosted-ui-stock.zip`).
-*/
-function matchAsset(names, query) {
-	const wanted = query.trim();
-	if (wanted.length === 0) return {
-		ok: false,
-		error: "no asset name was given"
-	};
-	const exact = names.find((name) => name === wanted);
-	if (exact !== void 0) return {
-		ok: true,
-		name: exact
-	};
-	const lower = wanted.toLowerCase();
-	const insensitive = names.filter((name) => name.toLowerCase() === lower);
-	if (insensitive.length === 1) return {
-		ok: true,
-		name: insensitive[0]
-	};
-	const partial = names.filter((name) => name.toLowerCase().includes(lower));
-	if (partial.length === 0) return {
-		ok: false,
-		error: `no asset matches "${wanted}" (available: ${names.join(", ") || "none"})`
-	};
-	if (partial.length > 1) return {
-		ok: false,
-		error: `"${wanted}" matches more than one asset: ${partial.join(", ")} — use the full name`
-	};
-	return {
-		ok: true,
-		name: partial[0]
-	};
-}
-/** `^https?://` means a URL; anything else is a filesystem path with `~` expanded. */
-function parseFileSource(value) {
-	const trimmed = value.trim();
-	if (/^https?:\/\//i.test(trimmed)) return {
-		kind: "url",
-		url: trimmed
-	};
-	return {
-		kind: "path",
-		path: expandHome(trimmed)
-	};
-}
-function expandHome(value) {
-	if (value === "~") return os.homedir();
-	if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2));
-	return value;
-}
-/**
-* A token is only ever sent to GitHub: `--file <url>` may point anywhere, and a
-* credential must not leak to a host the user did not vouch for.
-*/
-function isGithubHost(url) {
-	try {
-		const host = new URL(url).hostname.toLowerCase();
-		return host === "github.com" || host.endsWith(".github.com") || host === "githubusercontent.com" || host.endsWith(".githubusercontent.com");
-	} catch {
-		return false;
-	}
-}
-/** What `UiService` names the install when the archive carries no `ui.json`. */
-function fallbackUiName(source) {
-	const stripped = path.basename(source).replace(/\.zip$/i, "").replace(/^home-hosted-ui-/i, "");
-	return stripped.length > 0 ? stripped : "custom-ui";
-}
+			name: "init",
+			description: "scaffold a project that keeps its state in the repo"
+		},
+		args: initArgs,
+		run: async ({ args }) => {
+			await runInit({
+				dir: args.dir,
+				name: args.name,
+				pm: args.pm,
+				noInstall: args.install === false,
+				yes: args.yes === true
+			});
+		}
+	});
+}));
+//#endregion
+//#region src/cli/ui-switch.ts
+var ui_switch_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_REPO: () => DEFAULT_REPO,
+	MAX_DOWNLOAD_BYTES: () => MAX_DOWNLOAD_BYTES,
+	apiHeaders: () => apiHeaders,
+	assetDownloadUrl: () => assetDownloadUrl,
+	compareTags: () => compareTags,
+	defaultReleaseTag: () => defaultReleaseTag,
+	describeError: () => describeError,
+	describeReleaseFailure: () => describeReleaseFailure,
+	downloadToTemp: () => downloadToTemp,
+	fallbackUiName: () => fallbackUiName,
+	fetchRelease: () => fetchRelease,
+	fetchReleases: () => fetchReleases,
+	formatBytes: () => formatBytes,
+	isGithubHost: () => isGithubHost,
+	isOwnRepo: () => isOwnRepo,
+	isUiAsset: () => isUiAsset,
+	matchAsset: () => matchAsset,
+	noAssetsMessage: () => noAssetsMessage,
+	parseFileSource: () => parseFileSource,
+	parseRepoSlug: () => parseRepoSlug,
+	releaseApiUrl: () => releaseApiUrl,
+	releasesApiUrl: () => releasesApiUrl,
+	repoSlug: () => repoSlug,
+	uiSwitch: () => uiSwitch,
+	uiSwitchCommand: () => uiSwitchCommand
+});
 async function uiSwitch(argv, io) {
 	const { values } = parseArgs({
 		args: argv,
@@ -8893,21 +9523,6 @@ async function uiSwitch(argv, io) {
 	}
 	await installFromUrl(assetDownloadUrl(chosen), fallbackUiName(chosen.name ?? ""), context);
 }
-async function fetchRelease(repo, tag, context) {
-	const url = releaseApiUrl(repo, tag);
-	let response;
-	try {
-		response = await fetch(url, { headers: apiHeaders(context) });
-	} catch (error) {
-		throw new Error(`could not reach GitHub: ${describeError(error)}`);
-	}
-	if (!response.ok) throw new Error(describeReleaseFailure(response.status, repo, tag));
-	const body = await response.json();
-	return {
-		tag: body.tag_name ?? tag ?? "latest",
-		assets: Array.isArray(body.assets) ? body.assets : []
-	};
-}
 async function chooseAsset(assets, values, context) {
 	const { io } = context;
 	if (values.asset !== void 0) {
@@ -8962,47 +9577,6 @@ async function installFromUrl(url, fallbackName, context) {
 		});
 	}
 }
-/** Streams to `os.tmpdir()` so a large body is never buffered in memory. */
-async function downloadToTemp(url, headers, context) {
-	let response;
-	try {
-		response = await fetch(url, {
-			headers,
-			redirect: "follow"
-		});
-	} catch (error) {
-		throw new Error(`could not reach ${url}: ${describeError(error)}`);
-	}
-	if (!response.ok) throw new Error(describeDownloadFailure(response.status, url));
-	const declared = Number(response.headers.get("content-length") ?? "0");
-	if (!Number.isFinite(declared) || declared < 0) throw new Error(`the download from ${url} reported an unusable size`);
-	if (declared > 536870912) throw new Error(tooLargeMessage(declared));
-	if (response.body === null) throw new Error(`the download from ${url} had no body`);
-	const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hh2-ui-"));
-	const file = path.join(dir, "ui.zip");
-	const handle = await fs.promises.open(file, "w");
-	let received = 0;
-	try {
-		for await (const chunk of response.body) {
-			received += chunk.length;
-			if (received > 536870912) throw new Error(tooLargeMessage(received));
-			await handle.write(chunk);
-		}
-	} catch (error) {
-		await handle.close();
-		fs.rmSync(dir, {
-			recursive: true,
-			force: true
-		});
-		throw error instanceof Error ? error : new Error(String(error));
-	}
-	await handle.close();
-	context.io.write(`${context.io.style.dim(`downloaded ${formatBytes(received)}`)}\n`);
-	return {
-		dir,
-		file
-	};
-}
 async function installArchive(archivePath, fallbackName, context) {
 	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
 	const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
@@ -9016,66 +9590,282 @@ async function installArchive(archivePath, fallbackName, context) {
 	context.io.write(`  ${context.io.style.dim("files")}  ${meta.files}\n`);
 	context.io.write(`refresh the browser to see it\n`);
 }
-function apiHeaders(context) {
-	const headers = {
-		"accept": "application/vnd.github+json",
-		"user-agent": `home-hosted/${context.version}`,
-		"x-github-api-version": "2022-11-28"
-	};
-	if (context.token !== null && context.token.length > 0) headers.authorization = `Bearer ${context.token}`;
-	return headers;
+var uiSwitchCommand;
+var init_ui_switch = __esmMin((() => {
+	init_io();
+	init_ui_release();
+	init_ui_release();
+	uiSwitchCommand = defineCommand({
+		meta: {
+			name: "ui-switch",
+			description: "install a UI from a release asset, a zip file or a URL"
+		},
+		run: async ({ rawArgs }) => {
+			await uiSwitch(rawArgs, {
+				write: (text) => process.stdout.write(text),
+				prompt,
+				style
+			});
+		}
+	});
+}));
+//#endregion
+//#region src/cli/ui-update.ts
+var ui_update_exports = /* @__PURE__ */ __exportAll({
+	impliedAsset: () => impliedAsset,
+	planUiUpdate: () => planUiUpdate,
+	uiUpdate: () => uiUpdate,
+	uiUpdateCommand: () => uiUpdateCommand,
+	usableCandidates: () => usableCandidates
+});
+/**
+* Which of a release list applies to what is installed. A candidate is only offered when
+* its assets carry the asset the person is actually using, so a UI is never swapped for a
+* different flavour by an update.
+*/
+function usableCandidates(releases, asset, order, currentTag) {
+	const found = [];
+	for (const release of releases) {
+		const matched = matchAsset(release.assets.map((entry) => entry.name ?? "").filter(isUiAsset), asset);
+		if (!matched.ok) continue;
+		if (currentTag !== null) {
+			const difference = compareTags(release.tag, currentTag);
+			if (order === "newer" && difference <= 0) continue;
+			if (order === "older" && difference >= 0) continue;
+		}
+		found.push({
+			tag: release.tag,
+			asset: matched.name
+		});
+	}
+	return found;
 }
-function assetDownloadUrl(asset) {
-	const url = asset.url ?? asset.browser_download_url;
-	if (url === void 0 || url.length === 0) throw new Error(`the release metadata for "${asset.name ?? "an asset"}" carries no download URL`);
-	return url;
+/** What the asset the UI is using is likely called, when it never declared one. */
+function impliedAsset(identity) {
+	if (identity.asset !== null && identity.asset.length > 0) return identity.asset;
+	if (identity.name.length > 0) return `${identity.name}.zip`;
+	return null;
 }
-function noAssetsMessage(where, skipped, tag) {
-	const lines = [`no usable UI assets in ${where} (expected a .zip)`];
-	lines.push(skipped.length > 0 ? `  skipped: ${skipped.join(", ")}` : "  the release has no assets at all");
-	if (tag !== null && tag !== "latest") lines.push("  installing a different version silently is worse than failing: try the newest release with --tag latest");
-	return lines.join("\n");
+/**
+* The decision, with no I/O in it: given what is installed and this panel's release,
+* what should `ui-update` do? `releases` is only consulted for someone else's UI.
+*/
+function planUiUpdate(installed, runningTag, releases = [], order = "newer") {
+	if (installed === null) return { kind: "stock" };
+	const repo = installed.repo === null ? null : parseRepoSlug(installed.repo);
+	if (repo === null) return {
+		kind: "unidentifiable",
+		identity: installed
+	};
+	if (isOwnRepo(repo)) return {
+		kind: "official",
+		identity: installed,
+		target: runningTag
+	};
+	const asset = impliedAsset(installed);
+	if (asset === null) return {
+		kind: "unidentifiable",
+		identity: installed
+	};
+	return {
+		kind: "choice",
+		identity: installed,
+		asset,
+		candidates: usableCandidates(releases, asset, order, installed.tag)
+	};
 }
-function describeReleaseFailure(status, repo, tag) {
-	const slug = `${repo.owner}/${repo.name}`;
-	if (status === 404) {
-		if (tag !== null && tag !== "latest") return `no release tagged "${tag}" in ${slug}\n  list what exists with: home-hosted ui-switch --repo ${slug} --tag latest --list`;
-		return `no repository or published release at ${slug}\n  check the --repo slug (owner/name), and that the repository is public`;
+/** `home-hosted ui-update` — see the module comment for the three cases. */
+async function uiUpdate(argv, io) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			tag: { type: "string" },
+			asset: { type: "string" },
+			token: { type: "string" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
+			old: { type: "boolean" },
+			check: { type: "boolean" },
+			repo: { type: "string" }
+		},
+		allowPositionals: false
+	});
+	const { appVersion } = await Promise.resolve().then(() => (init_version(), version_exports));
+	const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
+	const context = {
+		io: {
+			write: io.write,
+			style: io.style
+		},
+		ask: process.stdin.isTTY === true && values.yes !== true ? io.prompt : null,
+		version: appVersion(),
+		token: values.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? null
+	};
+	const installed = identityOf(new UiService({ dataRoot }).status().meta);
+	if (installed === null) {
+		io.write(`${io.style.dim("the stock UI is in use — it ships with the panel and is always current")}\n`);
+		return;
 	}
-	if (status === 403 || status === 429) return `GitHub refused the request (HTTP ${status}) — the unauthenticated API rate limit is per address.\n  set a token to raise it: --token <token>, or GITHUB_TOKEN / GH_TOKEN`;
-	if (status === 401) return "GitHub rejected the token (HTTP 401) — check --token, GITHUB_TOKEN or GH_TOKEN";
-	return `GitHub answered HTTP ${status} while reading the release of ${slug}`;
+	if (values.repo !== void 0) {
+		const repo = parseRepoSlug(values.repo);
+		if (repo === null) throw new Error(`invalid --repo "${values.repo}" — expected an "owner/name" slug, e.g. ${DEFAULT_REPO}`);
+		installed.repo = repoSlug(repo);
+	}
+	const order = values.old === true ? "older" : "newer";
+	const repo = installed.repo === null ? null : parseRepoSlug(installed.repo);
+	if (values.tag !== void 0 && repo === null) throw new Error(["--tag needs a repository to fetch from, and this UI does not declare one", `  pass it: home-hosted ui-update --repo ${DEFAULT_REPO} --tag ${values.tag}`].join("\n"));
+	if (values.check === true && repo !== null) {
+		if (isOwnRepo(repo)) {
+			printCheck(io, installed, values.tag ?? `v${context.version}`);
+			return;
+		}
+		const releases = await fetchReleases(repo, context);
+		const asset = impliedAsset(installed);
+		printCheck(io, installed, null, asset === null ? [] : usableCandidates(releases, asset, order, installed.tag));
+		return;
+	}
+	if (values.tag !== void 0 && repo !== null) {
+		await installTag(repo, values.asset ?? installed.asset ?? null, values.tag, context);
+		return;
+	}
+	let releases = [];
+	if (repo !== null && !isOwnRepo(repo)) releases = await fetchReleases(repo, context);
+	const plan = planUiUpdate(installed, `v${context.version}`, releases, order);
+	if (plan.kind === "unidentifiable") {
+		io.write(`${io.style.bold("this UI does not say where it came from")} — nothing to follow automatically\n`);
+		printIdentity(io, plan.identity);
+		io.write(`  ${io.style.dim("point it at a repo to make this work: home-hosted ui-update --repo owner/name")}\n`);
+		return;
+	}
+	if (plan.kind === "official") {
+		if (plan.identity.tag === plan.target) {
+			io.write(`${io.style.green("already current")} — ${io.style.bold(plan.identity.name)} is at ${plan.target}\n`);
+			return;
+		}
+		io.write(`${io.style.bold(`${plan.identity.name} ${plan.identity.version ?? ""}`.trim())} is on ${plan.identity.tag ?? "an unknown tag"}; this panel is ${plan.target} — updating\n`);
+		await installTag(repo, plan.identity.asset ?? values.asset ?? null, plan.target, context);
+		return;
+	}
+	if (plan.kind !== "choice") return;
+	io.write(`${io.style.bold(plan.identity.name)} ${plan.identity.version ?? ""} — ${repoSlug(repo)}@${plan.identity.tag ?? "unknown tag"}\n`);
+	io.write(`  ${io.style.dim(`asset: ${plan.asset}`)}\n`);
+	if (plan.candidates.length === 0) {
+		const direction = order === "newer" ? "newer" : "older";
+		io.write(`no ${direction} releases carry ${plan.asset}\n`);
+		if (order === "newer") io.write(`  ${io.style.dim("list older releases with: home-hosted ui-update --old")}\n`);
+		return;
+	}
+	const chosen = await chooseCandidate(plan.candidates, context, order);
+	if (chosen === null) {
+		io.write("cancelled — nothing was installed\n");
+		return;
+	}
+	await installTag(repo, chosen.asset, chosen.tag, context);
 }
-function describeDownloadFailure(status, url) {
-	const github = isGithubHost(url);
-	if (status === 404) return github ? `the asset is gone (HTTP 404) — ${url}\n  the release may have been rebuilt since it was listed; run the command again` : `nothing is served at that URL (HTTP 404) — ${url}`;
-	if (status === 403 || status === 429) return github ? `GitHub refused the download (HTTP ${status}) — a token raises the rate limit: --token <token>, or GITHUB_TOKEN / GH_TOKEN` : `the host refused the download (HTTP ${status}) — ${url}`;
-	if (status === 401 && github) return "GitHub rejected the token on the download (HTTP 401) — check --token, GITHUB_TOKEN or GH_TOKEN";
-	return `the download failed (HTTP ${status}) — ${url}`;
+function identityOf(meta) {
+	if (meta === null) return null;
+	return {
+		name: meta.name ?? "custom-ui",
+		version: meta.version ?? null,
+		repo: meta.repo ?? null,
+		tag: meta.tag ?? null,
+		asset: meta.asset ?? null,
+		unix: meta.unix ?? null
+	};
 }
-function tooLargeMessage(bytes) {
-	return `the download is ${formatBytes(bytes)}, larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB a UI may be`;
+function printIdentity(io, identity) {
+	io.write(`  name     ${identity.name}\n`);
+	io.write(`  version  ${identity.version ?? "unspecified"}\n`);
+	io.write(`  repo     ${identity.repo ?? "unspecified"}${identity.tag === null ? "" : ` @ ${identity.tag}`}\n`);
+	if (identity.unix !== null) io.write(`  built    ${(/* @__PURE__ */ new Date(identity.unix * 1e3)).toISOString()}\n`);
 }
-function formatBytes(bytes) {
-	if (bytes < 1024) return `${bytes} B`;
-	if (bytes < 1048576) return `${Math.round(bytes / 1024)} KB`;
-	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+function printCheck(io, identity, target, candidates = []) {
+	if (target !== null) {
+		if (identity.tag === target) {
+			io.write(`${io.style.green("up to date")} — ${identity.version ?? identity.name} at ${target}\n`);
+			return;
+		}
+		io.write(`update available: ${identity.tag ?? "unknown"} → ${target}\n`);
+		return;
+	}
+	if (candidates.length === 0) {
+		io.write(`up to date — no release carries ${identity.asset ?? identity.name}.zip\n`);
+		return;
+	}
+	io.write(`${candidates.length} release(s) available:\n`);
+	for (const candidate of candidates) io.write(`  ${candidate.tag}  ${io.style.dim(candidate.asset)}\n`);
 }
-function describeError(error) {
-	return error instanceof Error ? error.message : String(error);
+async function chooseCandidate(candidates, context, order) {
+	const headline = order === "newer" ? "Newer releases" : "Older releases";
+	const { io } = context;
+	io.write(`${io.style.bold(headline)}\n`);
+	for (const [index, candidate] of candidates.entries()) io.write(`  ${index + 1}) ${candidate.tag}\n`);
+	if (context.ask === null) {
+		if (candidates.length === 1) return candidates[0];
+		throw new Error([
+			`${candidates.length} releases are available and this session cannot ask which one:`,
+			...candidates.map((candidate) => `  ${candidate.tag}`),
+			"  run it in a terminal, or pass --tag <tag>"
+		].join("\n"));
+	}
+	for (;;) {
+		const answer = (await context.ask(`Select a release [1-${candidates.length}] (empty to cancel) `)).trim();
+		if (answer.length === 0) return null;
+		if (/^\d+$/.test(answer)) {
+			const index = Number.parseInt(answer, 10);
+			if (index >= 1 && index <= candidates.length) return candidates[index - 1];
+		}
+		const byTag = candidates.find((candidate) => candidate.tag === answer);
+		if (byTag !== void 0) return byTag;
+		io.write(`  ${io.style.dim(`no such choice — enter 1-${candidates.length} or a tag`)}\n`);
+	}
 }
-var DEFAULT_REPO, MAX_DOWNLOAD_BYTES, uiSwitchCommand;
-var init_ui_switch = __esmMin((() => {
+/** Fetches one release's asset and installs it, reporting what landed. */
+async function installTag(repo, wantedAsset, tag, context) {
+	const release = await fetchRelease(repo, tag, context);
+	const names = release.assets.map((asset) => asset.name ?? "").filter(isUiAsset);
+	let assetName;
+	if (wantedAsset !== null && wantedAsset.length > 0) {
+		const matched = matchAsset(names, wantedAsset);
+		if (!matched.ok) throw new Error(`${matched.error}\n  in ${repo.owner}/${repo.name}@${release.tag}`);
+		assetName = matched.name;
+	} else if (names.length === 1) assetName = names[0];
+	else throw new Error(`${names.length} UI assets in ${repo.owner}/${repo.name}@${release.tag} — name one with --asset`);
+	const download = await downloadToTemp(assetDownloadUrl(release.assets.find((entry) => entry.name === assetName)), {
+		"accept": "application/octet-stream",
+		"user-agent": `home-hosted/${context.version}`,
+		...context.token !== null && context.token.length > 0 ? { authorization: `Bearer ${context.token}` } : {}
+	}, context);
+	try {
+		const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
+		const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+		const result = await new UiService({ dataRoot }).install(download.file, assetName);
+		if (!result.ok) throw new Error(`nothing was installed: ${result.error}`);
+		const { meta } = result;
+		const { io } = context;
+		io.write(`${io.style.green("UI updated")} — ${meta.name} ${meta.version ?? ""} at ${release.tag}\n`);
+		io.write(`  ${io.style.dim("refresh the browser to see it")}\n`);
+	} finally {
+		fs.rmSync(download.dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+var uiUpdateCommand;
+var init_ui_update = __esmMin((() => {
 	init_io();
-	DEFAULT_REPO = "NamesMT/home-hosted";
-	MAX_DOWNLOAD_BYTES = 536870912;
-	uiSwitchCommand = defineCommand({
+	init_ui_release();
+	uiUpdateCommand = defineCommand({
 		meta: {
-			name: "ui-switch",
-			description: "install a UI from a release asset, a zip file or a URL"
+			name: "ui-update",
+			description: "update the installed UI to match this panel, or pick a release"
 		},
 		run: async ({ rawArgs }) => {
-			await uiSwitch(rawArgs, {
+			await uiUpdate(rawArgs, {
 				write: (text) => process.stdout.write(text),
 				prompt,
 				style
@@ -9132,66 +9922,201 @@ init_io();
 * module) is a dynamic import behind `subCommands`.
 */
 var CLI_ENTRY = fileURLToPath(import.meta.url);
-var USAGE = `home-hosted — a control panel for the processes on your home server
-
-Usage
-  home-hosted up [options]      start it in the background (detached)
-  home-hosted down              stop it, and everything it supervises
-  home-hosted restart [options] down, then up
-  home-hosted status [--json]   is it running, where, and how to reach it
-  home-hosted set-password      set the panel password without the API
-  home-hosted set-token         set the API token that scripts and agents use
-  home-hosted migrate           bring the config up to this release's schema
-  home-hosted init              scaffold a project that keeps its state in the repo
-  home-hosted ui-switch         install a UI from a release asset, a zip file or a URL
-  home-hosted ui-revert         go back to the stock control panel UI
-
-Options for up/restart
-  -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 (default: local)
-      --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 (systemd/docker)
-      --print-config    print the effective config and exit
-
-Options for set-token
-      --generate        create a strong token and print it once
-      --clear           remove the token, so it stops working
-
-Options for migrate
-      --dry-run         print what would change, write nothing
-  -y, --yes             apply without asking (or set HHOSTED_MIGRATE=allow)
-
-Options for init
-      --dir <dir>       where to scaffold (default: ./my-servers)
-      --name <name>     package name (default: the directory name)
-      --pm <manager>    pnpm | npm | yarn | bun (default: the first one installed)
-      --no-install      write the files, install nothing
-  -y, --yes             take every default, ask nothing
-
-Options for ui-switch
-      --repo <owner/name>   release repo (default: NamesMT/home-hosted)
-      --tag <tag>           release tag (default: this release's tag, or latest for another repo)
-      --asset <name>        asset to install (exact or unambiguous match)
-      --file <path|url>     install a zip from a local path or an http(s) URL
-      --list                list the usable assets and install nothing
-      --token <token>       GitHub token (or GITHUB_TOKEN / GH_TOKEN)
-  -y, --yes                 take the only asset instead of asking
-
-Everywhere
-      --home <dir>      state directory (default: $HHOSTED_HOME or ~/.home-hosted)
-      --project <dir>   base for relative entry paths (default: the current directory)
-  -h, --help            this text
-  -v, --version         the version
-
-Environment
-  HHOSTED_HOME          where config, secrets, logs, TLS and backups live
-  HHOSTED_PROJECT       base for relative entry paths
-  HHOSTED_PASSWORD      the password for a non-interactive set-password
-  HHOSTED_TOKEN         the token for a non-interactive set-token
-  GITHUB_TOKEN          a GitHub token for ui-switch (GH_TOKEN also works)
-`;
+/**
+* The curated prose, kept here because citty cannot generate it. One named
+* piece per command, so the full reference and a single command's help are
+* composed from the same lines and can never drift apart. Every section lays
+* its left column out at the same width, so the two views read alike.
+*/
+var HEADER = "home-hosted — a control panel for the processes on your home server";
+/** The one line the full reference lists for a command. */
+var SYNOPSIS = {
+	"up": "home-hosted up [options]",
+	"down": "home-hosted down",
+	"restart": "home-hosted restart [options]",
+	"status": "home-hosted status [--json]",
+	"set-password": "home-hosted set-password",
+	"set-token": "home-hosted set-token",
+	"migrate": "home-hosted migrate",
+	"init": "home-hosted init",
+	"ui-switch": "home-hosted ui-switch",
+	"ui-update": "home-hosted ui-update",
+	"ui-revert": "home-hosted ui-revert"
+};
+var SUMMARIES = {
+	"up": "start it in the background (detached)",
+	"down": "stop it, and everything it supervises",
+	"restart": "down, then up",
+	"status": "is it running, where, and how to reach it",
+	"set-password": "set the panel password without the API",
+	"set-token": "set the API token that scripts and agents use",
+	"migrate": "bring the config up to this release's schema",
+	"init": "scaffold a project that keeps its state in the repo",
+	"ui-switch": "install a UI from a release asset, a zip file or a URL",
+	"ui-update": "bring the installed UI up to date, or pick a release",
+	"ui-revert": "go back to the stock control panel UI"
+};
+/** Every section lays its left column out at this width, so the two views align. */
+var OPTION_WIDTH = 19;
+var UP_SECTION = {
+	heading: "Options for up/restart",
+	lines: [
+		["-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 (default: local)"],
+		["--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 (systemd/docker)"],
+		["--print-config", "print the effective config and exit"]
+	]
+};
+var STATUS_SECTION = {
+	heading: "Options for status",
+	lines: [["--json", "print machine-readable JSON"]]
+};
+var SET_PASSWORD_SECTION = {
+	heading: "Options for set-password",
+	lines: [["--clear", "remove the password, which disables authentication"]]
+};
+var SET_TOKEN_SECTION = {
+	heading: "Options for set-token",
+	lines: [["--generate", "create a strong token and print it once"], ["--clear", "remove the token, so it stops working"]]
+};
+var MIGRATE_SECTION = {
+	heading: "Options for migrate",
+	lines: [["--dry-run", "print what would change, write nothing"], ["-y, --yes", "apply without asking (or set HHOSTED_MIGRATE=allow)"]]
+};
+var INIT_SECTION = {
+	heading: "Options for init",
+	lines: [
+		["--dir <dir>", "where to scaffold (default: ./my-servers)"],
+		["--name <name>", "package name (default: the directory name)"],
+		["--pm <manager>", "pnpm | npm | yarn | bun (default: the first one installed)"],
+		["--no-install", "write the files, install nothing"],
+		["-y, --yes", "take every default, ask nothing"]
+	]
+};
+var UI_SWITCH_SECTION = {
+	heading: "Options for ui-switch",
+	lines: [
+		["--repo <owner/name>", "release repo (default: NamesMT/home-hosted)"],
+		["--tag <tag>", "release tag (default: this release's tag, or latest for another repo)"],
+		["--asset <name>", "asset to install (exact or unambiguous match)"],
+		["--file <path|url>", "install a zip from a local path or an http(s) URL"],
+		["--list", "list the usable assets and install nothing"],
+		["--token <token>", "GitHub token (or GITHUB_TOKEN / GH_TOKEN)"],
+		["-y, --yes", "take the only asset instead of asking"]
+	]
+};
+var UI_UPDATE_SECTION = {
+	heading: "Options for ui-update",
+	lines: [
+		["--check", "report whether an update is available and install nothing"],
+		["--tag <tag>", "install that release instead of asking"],
+		["--asset <name>", "asset to install (defaults to the one in use)"],
+		["--old", "list older releases instead of newer ones"],
+		["--repo <owner/name>", "for a UI that does not declare its own repo"],
+		["--token <token>", "GitHub token (or GITHUB_TOKEN / GH_TOKEN)"],
+		["-y, --yes", "take the only release instead of asking"]
+	]
+};
+var EVERYWHERE_SECTION = {
+	heading: "Everywhere",
+	lines: [
+		["--home <dir>", "state directory (default: $HHOSTED_HOME or ~/.home-hosted)"],
+		["--project <dir>", "base for relative entry paths (default: the current directory)"],
+		["-h, --help", "this text"],
+		["-v, --version", "the version"]
+	]
+};
+var ALIAS_SECTION = {
+	heading: "Alias",
+	lines: [["hh", "the same CLI, on a machine where home-hosted is installed"]]
+};
+var ENVIRONMENT_SECTION = {
+	heading: "Environment",
+	lines: [
+		["HHOSTED_HOME", "where config, secrets, logs, TLS and backups live"],
+		["HHOSTED_PROJECT", "base for relative entry paths"],
+		["HHOSTED_PASSWORD", "the password for a non-interactive set-password"],
+		["HHOSTED_TOKEN", "the token for a non-interactive set-token"],
+		["GITHUB_TOKEN", "a GitHub token for ui-switch (GH_TOKEN also works)"]
+	]
+};
+/** The command list of the full reference, aligned as it always was. */
+function renderCommandList() {
+	const width = Math.max(...Object.values(SYNOPSIS).map((synopsis) => synopsis.length));
+	return Object.keys(SYNOPSIS).map((name) => {
+		const synopsis = SYNOPSIS[name];
+		return `  ${cyan(synopsis)}${" ".repeat(width + 1 - synopsis.length)}   ${SUMMARIES[name]}`;
+	}).join("\n");
+}
+function renderSection(section) {
+	const lines = section.lines.map(([left, right]) => `  ${cyan(left)}${" ".repeat(Math.max(0, OPTION_WIDTH - left.length))}   ${right}`).join("\n");
+	return `${heading(section.heading)}\n${lines}`;
+}
+/** The trailer every command shares: the global flags, the alias and the environment. */
+var SHARED_TRAILER = [
+	renderSection(EVERYWHERE_SECTION),
+	"",
+	renderSection(ALIAS_SECTION),
+	"",
+	renderSection(ENVIRONMENT_SECTION),
+	""
+].join("\n");
+/** The full reference: every command, every option, the trailer. */
+var USAGE = [
+	dim(HEADER),
+	"",
+	heading("Usage"),
+	renderCommandList(),
+	"",
+	renderSection(UP_SECTION),
+	"",
+	renderSection(SET_PASSWORD_SECTION),
+	"",
+	renderSection(SET_TOKEN_SECTION),
+	"",
+	renderSection(MIGRATE_SECTION),
+	"",
+	renderSection(INIT_SECTION),
+	"",
+	renderSection(UI_SWITCH_SECTION),
+	"",
+	renderSection(STATUS_SECTION),
+	"",
+	SHARED_TRAILER
+].join("\n");
+var UP_COMMANDS = /* @__PURE__ */ new Set(["up", "restart"]);
+var SECTIONS = {
+	"status": STATUS_SECTION,
+	"set-password": SET_PASSWORD_SECTION,
+	"set-token": SET_TOKEN_SECTION,
+	"migrate": MIGRATE_SECTION,
+	"init": INIT_SECTION,
+	"ui-switch": UI_SWITCH_SECTION,
+	"ui-update": UI_UPDATE_SECTION
+};
+/**
+* `home-hosted <command> --help`: the usage line, that command's own options,
+* and the shared trailer. A command with no options says so instead of printing
+* an empty heading.
+*/
+function commandHelp(command) {
+	const synopsis = SYNOPSIS[command];
+	if (synopsis === void 0) return USAGE;
+	const section = UP_COMMANDS.has(command) ? UP_SECTION : SECTIONS[command];
+	const options = section === void 0 ? dim("no options") : renderSection(section);
+	return [
+		dim(HEADER),
+		"",
+		cyan(synopsis),
+		"",
+		options,
+		"",
+		SHARED_TRAILER
+	].join("\n");
+}
 function manifestVersion() {
 	try {
 		return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
@@ -9216,6 +10141,7 @@ var COMMANDS = {
 	"migrate": () => Promise.resolve().then(() => (init_migrate(), migrate_exports)).then((module) => module.migrateCommand),
 	"init": () => Promise.resolve().then(() => (init_init(), init_exports)).then((module) => module.initCommand),
 	"ui-switch": () => Promise.resolve().then(() => (init_ui_switch(), ui_switch_exports)).then((module) => module.uiSwitchCommand),
+	"ui-update": () => Promise.resolve().then(() => (init_ui_update(), ui_update_exports)).then((module) => module.uiUpdateCommand),
 	"ui-revert": () => Promise.resolve().then(() => (init_ui_revert(), ui_revert_exports)).then((module) => module.uiRevertCommand)
 };
 var rootCommand = defineCommand({
@@ -9233,7 +10159,7 @@ async function main() {
 	applyDirFlags(dirFlags);
 	const invocation = resolveInvocation(dirFlags.rest, commandNames);
 	if (invocation.kind === "help") {
-		process.stdout.write(USAGE);
+		process.stdout.write(invocation.command === void 0 ? USAGE : commandHelp(invocation.command));
 		return;
 	}
 	if (invocation.kind === "version") {
@@ -9258,6 +10184,6 @@ main().catch((error) => {
 	fail(error instanceof Error ? error.message : String(error));
 });
 //#endregion
-export {};
+export { commandHelp };
 
 //# sourceMappingURL=cli.js.map