the settings form, and the branch that never ran

the plugin could not be configured. /_config had GET, PUT, DELETE and a test
that validates without storing, and nothing rendered any of it — the
connection had to be inserted by hand.

ConnectionPanel is both the wizard and the settings page, one component, the
same choice jellyfin's ConnectionSection makes and for the same reason: a
connection edited months later goes through exactly the path that stored the
first one. HostsPanel shows it when nothing is configured and on ?config=1,
which is in the URL so it survives a refresh. test comes before save and
stores nothing, so a wrong password cannot replace a working one. the secret
field starts empty even when one is stored, and empty means keep — that is
what lets a typo in the URL be fixed without going to find the password.

and while wiring the unconfigured case, it turned out that case never fired.

both panels read `(error as { body?: Failure }).body` to decide whether a
failure was unconfigured, unauthenticated or unreachable. useClient throws
ApiError(status, message) and has no `.body` at all, so that was always
undefined: every failure fell through to the generic message, and the careful
explanation of NPM's 404-means-credential quirk was written, shipped and
unreachable. asFailure now reads the STATUS, which the router already chooses
deliberately — 409 nothing stored, 503 no answer, 502 answered and refused.

owner-only is explained rather than reported. a member hitting 403 here reads
why: it is an admin login and NPM has no read-only role.

still not installed, still no db:push.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

web/HostsPanel.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { AlertTriangle, Globe, Lock, LockOpen, Power, RefreshCw, ShieldCheck, Users } from "lucide-react";
+import { AlertTriangle, Globe, Lock, LockOpen, Power, RefreshCw, Settings, ShieldCheck, Users } from "lucide-react";
 import { useClient } from "hooks/useClient";
 import { useSearchParams } from "react-router";
+import { ConnectionPanel } from "./ConnectionPanel";
 
 /**
  * The proxy hosts, which is the thing anybody opens this plugin to see.
@@ -26,6 +27,30 @@ type ProxyHost = {
 
 type Failure = { error: string; likelyAuth?: boolean; unreachable?: boolean; unconfigured?: boolean };
 
+/**
+ * Turn a thrown `ApiError` into the shape this panel branches on.
+ *
+ * **This reads the STATUS, not the body, and that is not a shortcut.** `useClient` throws
+ * `ApiError(status, message)` — there is no `.body` on it, and there never was. This panel used to read
+ * `(error as { body?: Failure }).body`, which is always `undefined`, so `unconfigured` and `likelyAuth`
+ * were never once true and every failure fell through to the generic message. The careful explanation of
+ * NPM's 404 quirk was written, shipped, and unreachable.
+ *
+ * `api/router.ts` already encodes the distinction in the status it chooses, so it survives the trip:
+ * 409 is "no connection stored", 503 is "NPM did not answer", 502 is "NPM answered and refused". The
+ * message carries the detail, including the sentence about a 404 really meaning the credential.
+ */
+const asFailure = (error: unknown): Failure => {
+  const status = (error as { status?: number })?.status;
+  const message = error instanceof Error ? error.message : "Could not load hosts.";
+  return {
+    error: message,
+    unconfigured: status === 409,
+    unreachable: status === 503,
+    likelyAuth: status === 502,
+  };
+};
+
 export const HostsPanel = () => {
   const client = useClient();
   // useClient() rebuilds its verbs every render, so it must not sit in a dependency list.
@@ -37,14 +62,16 @@ export const HostsPanel = () => {
   const [busy, setBusy] = useState<number | null>(null);
   const [params, setParams] = useSearchParams();
   const selected = params.get("host");
+  // `?config=1` is the settings page; an unconfigured plugin shows it whether or not it was asked for.
+  // In the URL rather than in state, so it survives a refresh and can be linked to — `docs/navigation-audit.md`.
+  const configuring = params.get("config") === "1";
 
   const load = useCallback(async () => {
     try {
       setHosts(await clientRef.current.get<ProxyHost[]>("/proxy-manager/hosts"));
       setFailure(null);
     } catch (error) {
-      const body = (error as { body?: Failure })?.body;
-      setFailure(body ?? { error: error instanceof Error ? error.message : "Could not load hosts." });
+      setFailure(asFailure(error));
       setHosts(null);
     }
   }, []);
@@ -65,9 +92,12 @@ export const HostsPanel = () => {
     }
   };
 
+  // Order matters: an explicit `?config=1` wins over everything, then "there is nothing to connect to"
+  // wins over the generic failure screen. Otherwise the first thing a new install shows is an error.
+  if (configuring || failure?.unconfigured) return <ConnectionPanel />;
   if (failure) return <Failed failure={failure} onRetry={() => void load()} />;
   if (!hosts) return <Centred>Loading hosts…</Centred>;
-  if (hosts.length === 0) return <Centred>Nginx Proxy Manager has no proxy hosts.</Centred>;
+
 
   return (
     <div className="flex size-full flex-col">
@@ -75,11 +105,27 @@ export const HostsPanel = () => {
         <span className="text-sm font-medium">
           {hosts.length} host{hosts.length === 1 ? "" : "s"}
         </span>
-        <button type="button" onClick={() => void load()} className="text-muted-foreground hover:text-foreground">
-          <RefreshCw className="size-4" />
-        </button>
+        <span className="flex items-center gap-2">
+          <button type="button" onClick={() => void load()} className="text-muted-foreground hover:text-foreground">
+            <RefreshCw className="size-4" />
+          </button>
+          {/* Not a Link: this panel lives inside a workspace and the target is a parameter on the page it
+              is already on. A button that sets the parameter is the same navigation without a full route. */}
+          <button
+            type="button"
+            title="Connection settings"
+            onClick={() => setParams((p) => { p.set("config", "1"); return p; })}
+            className="text-muted-foreground hover:text-foreground"
+          >
+            <Settings className="size-4" />
+          </button>
+        </span>
       </header>
 
+      {hosts.length === 0 ? (
+        <Centred>Nginx Proxy Manager has no proxy hosts.</Centred>
+      ) : null}
+
       <ul className="flex-1 overflow-auto">
         {hosts.map((host) => {
           const offline = host.meta?.nginx_online === false;