polish Hermes and Pi provider setup UX

Author: joeynyc

README.md

@@ -16,6 +16,7 @@ T3 Code is a minimal web GUI for coding agents (currently Codex, Claude, OpenCod
 
 Hermes setup notes: [docs/providers/hermes.md](./docs/providers/hermes.md)
 Pi setup notes: [docs/providers/pi.md](./docs/providers/pi.md)
+Release readiness checklist: [docs/providers/release-readiness.md](./docs/providers/release-readiness.md)
 
 ## Hermes Agent support
 

apps/web/src/components/chat/ModelPickerContent.tsx

@@ -238,6 +238,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
   const sidebarInstanceEntries = showLockedInstanceSidebar
     ? lockedInstanceEntries
     : instanceEntries.filter((entry) => visibleRailInstanceSet.has(entry.instanceId));
+  const selectedEntry =
+    selectedInstanceId === "favorites" ? null : (entryByInstanceId.get(selectedInstanceId) ?? null);
   const instanceOrder = useMemo(
     () => instanceEntries.map((entry) => entry.instanceId),
     [instanceEntries],
@@ -423,6 +425,27 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
     (): string[] => filteredModels.map((model) => `${model.instanceId}:${model.slug}`),
     [filteredModels],
   );
+  const emptyMessage = useMemo(() => {
+    if (searchQuery.trim().length > 0) {
+      return "No models match that search";
+    }
+    if (selectedInstanceId === "favorites") {
+      return "No favorite models yet";
+    }
+    if (selectedEntry && !selectedEntry.enabled) {
+      return `${selectedEntry.displayName} is disabled in Settings`;
+    }
+    if (selectedEntry && selectedEntry.status !== "ready") {
+      const detail = selectedEntry.snapshot.message?.trim();
+      return detail
+        ? `${selectedEntry.displayName} needs setup: ${detail}`
+        : `${selectedEntry.displayName} needs setup in Settings`;
+    }
+    if (selectedEntry) {
+      return `${selectedEntry.displayName} has no models yet. Finish setup, refresh provider status, then try again.`;
+    }
+    return "No models found";
+  }, [searchQuery, selectedEntry, selectedInstanceId]);
   const filteredModelByKey = useMemo(
     (): ReadonlyMap<string, ModelPickerItem> =>
       new Map(filteredModels.map((model) => [`${model.instanceId}:${model.slug}`, model] as const)),
@@ -654,7 +677,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
               </ComboboxList>
             </div>
             <ComboboxEmpty className="not-empty:py-6 empty:h-0 text-xs font-normal leading-snug">
-              No models found
+              {emptyMessage}
             </ComboboxEmpty>
           </div>
         </Combobox>

apps/web/src/components/chat/ProviderModelPicker.browser.tsx

@@ -1330,6 +1330,32 @@ describe("ProviderModelPicker", () => {
     }
   });
 
+  it("explains provider setup when the active Hermes provider has no models", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: ProviderInstanceId.make("hermes"),
+      model: "hermes-default",
+      lockedProvider: null,
+      providers: [
+        ...TEST_PROVIDERS,
+        buildHermesProvider({
+          models: [],
+        }),
+      ],
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        expect(document.body.textContent ?? "").toContain(
+          "Hermes has no models yet. Finish setup, refresh provider status, then try again.",
+        );
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
   it("accepts outline trigger styling", async () => {
     const mounted = await mountPicker({
       model: "gpt-5-codex",

apps/web/src/components/settings/ProviderInstanceCard.test.ts

@@ -1,7 +1,14 @@
 import { describe, expect, it } from "vitest";
-import type { ServerProviderModel } from "@t3tools/contracts";
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
 
-import { deriveProviderModelsForDisplay } from "./ProviderInstanceCard";
+import {
+  buildProviderSetupChecklist,
+  deriveProviderModelsForDisplay,
+} from "./ProviderInstanceCard";
 
 describe("deriveProviderModelsForDisplay", () => {
   it("uses current config custom models instead of stale live custom rows", () => {
@@ -34,3 +41,72 @@ describe("deriveProviderModelsForDisplay", () => {
     ).toEqual(["server-model", "kept-custom"]);
   });
 });
+
+describe("buildProviderSetupChecklist", () => {
+  it("treats installed Hermes with CLI-managed auth as ready for a test message", () => {
+    const checklist = buildProviderSetupChecklist({
+      displayName: "Hermes",
+      isHermesDriver: true,
+      isPiDriver: false,
+      enabled: true,
+      configuredBinaryPath: "hermes",
+      configuredPiBinaryPath: null,
+      modelCount: 1,
+      liveProvider: {
+        driver: ProviderDriverKind.make("hermes"),
+        instanceId: ProviderInstanceId.make("hermes"),
+        displayName: "Hermes",
+        enabled: true,
+        installed: true,
+        version: "0.11.0",
+        status: "ready",
+        auth: { status: "unknown" },
+        checkedAt: new Date().toISOString(),
+        models: [],
+        slashCommands: [],
+        skills: [],
+      },
+    });
+
+    expect(checklist.map((item) => [item.label, item.state])).toEqual([
+      ["Enabled", "complete"],
+      ["CLI detected", "complete"],
+      ["Authentication", "complete"],
+      ["Model visible", "complete"],
+    ]);
+  });
+
+  it("points Pi users at login and model setup when auth and models are missing", () => {
+    const checklist = buildProviderSetupChecklist({
+      displayName: "Pi",
+      isHermesDriver: false,
+      isPiDriver: true,
+      enabled: true,
+      configuredBinaryPath: "pi-acp",
+      configuredPiBinaryPath: null,
+      modelCount: 0,
+      liveProvider: {
+        driver: ProviderDriverKind.make("pi"),
+        instanceId: ProviderInstanceId.make("pi"),
+        displayName: "Pi",
+        enabled: true,
+        installed: true,
+        version: "0.73.1",
+        status: "error",
+        auth: { status: "unauthenticated" },
+        checkedAt: new Date().toISOString(),
+        models: [],
+        slashCommands: [],
+        skills: [],
+      },
+    });
+
+    expect(checklist.map((item) => [item.label, item.state])).toEqual([
+      ["Enabled", "complete"],
+      ["Adapter detected", "complete"],
+      ["Pi binary", "pending"],
+      ["Authentication", "action"],
+      ["Model visible", "action"],
+    ]);
+  });
+});