local-lemonade 1.0.0

package/index.ts

@@ -0,0 +1,2374 @@
+/**
+ * local-lemonade — unified pi extension for a self-hosted Lemonade server
+ *
+ * One extension, four capabilities:
+ *
+ *   1. Dynamic chat-model discovery — queries the server's model catalog and
+ *      health endpoints at every pi startup, registers one
+ *      lemonade-<instance-name> provider per configured instance
+ *      with capability metadata (reasoning / vision / context window) and
+ *      live loaded-state annotations. Chat-capable models only, by default.
+ *   2. Multimodal agent tools — transcribe_audio, generate_image, edit_image,
+ *      vary_image, upscale_image, text_to_speech, generate_audio, and
+ *      generate_3d_model, all backed by lemonade's OpenAI-compatible and
+ *      Lemonade-specific endpoints. Unloaded models auto-load on demand;
+ *      container audio formats are converted to wav via ffmpeg first.
+ *   3. /lemonade-setup — a navigable TUI menu for live status, endpoint
+ *      configuration, server discovery, model management (load, unload,
+ *      pull with live progress + cancel, delete with typed-phrase
+ *      confirmation, change-ctx, Hugging Face search & install, filter,
+ *      refresh).
+ *   4. Pulls use lemonade's server-owned download jobs (stream + subscribe:
+ *      false + GET /v1/downloads) with a live progress view, Esc to cancel —
+ *      no blocking 30-minute waits. Blocking pull is kept as a fallback.
+ *
+ * Nothing is hardcoded: every endpoint lives in ~/.pi/agent/lemonade.json,
+ * editable at runtime via /lemonade-setup (changes re-register the provider
+ * immediately; no restart or /reload needed). The config file is REQUIRED:
+ * if it is missing or unparseable at startup, the extension fails loudly
+ * and registers nothing — copy lemonade.example.json (beside this file,
+ * fully commented) to ~/.pi/agent/lemonade.json and edit it for your
+ * server. JSONC-style comments are allowed in the config file; note that
+ * /lemonade-setup rewrites strip them.
+ *
+ * Endpoints confirmed against lemonade 11.7.0 (see README for full list).
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import dgram from "node:dgram";
+import { spawn } from "node:child_process";
+import { Type } from "typebox";
+import { DynamicBorder, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+interface LemonadeConfig {
+  /** Resolved per-instance on views produced by listInstances()/instanceView()
+   *  (from servers[].baseUrl). Empty on the raw config — the only instance
+   *  store is servers[], and servers[0] is the default instance. */
+  baseUrl: string;
+  apiKey: string; // shared fallback; a server entry without apiKey inherits it
+  chatPath: string; // OpenAI-compat chat completions base
+  modelsPath: string;
+  healthPath: string;
+  loadPath: string;
+  unloadPath: string;
+  pullPath: string;
+  deletePath: string;
+  downloadsPath: string;
+  downloadsControlPath: string;
+  registrySearchPath: string;
+  pullVariantsPath: string;
+  transcriptionPath: string;
+  imageGenerationPath: string;
+  imageEditPath: string;
+  imageVariationPath: string;
+  imageUpscalePath: string;
+  speechPath: string;
+  audioGenerationPath: string;
+  mesh3dPath: string;
+  classifyPath: string;
+  beaconPort: number;
+  chatOnly: boolean;
+  defaultTranscriptionModel: string;
+  defaultImageModel: string; // "" = auto-pick first image-labeled catalog model
+  defaultUpscaleModel: string;
+  defaultClassifierModel: string; // "" = auto-pick first classification model
+  outputDir: string; // "" = process cwd
+  discoveryTimeoutMs: number;
+  beaconTimeoutMs: number;
+  loadTimeoutMs: number;
+  pullTimeoutMs: number; // blocking-pull fallback cap only
+  transcriptionTimeoutMs: number;
+  generationTimeoutMs: number; // images, speech, audio gen, 3D
+  /** ALL lemonade instances — the only instance store. REQUIRED (at least
+   *  one entry); the FIRST entry is the default instance (the one tools
+   *  target when the `server` argument is omitted). There is no separate
+   *  default: servers[0] IS the default, and reordering the array changes
+   *  which instance that is. */
+  servers: ServerEntry[];
+}
+
+export interface ServerEntry {
+  name: string; // lowercase alnum + hyphens; "default" and duplicate names are reserved
+  baseUrl: string;
+  apiKey?: string; // falls back to the top-level (shared) apiKey when omitted
+  description?: string; // free-form context for the user's own reminder's sake
+}
+
+const CONFIG_PATH = path.join(getAgentDir(), "lemonade.json");
+
+const DEFAULT_CONFIG: LemonadeConfig = {
+  baseUrl: "", // views resolve this from servers[]; empty on the raw config
+  apiKey: "lemonade",
+  chatPath: "/api/v1",
+  modelsPath: "/v1/models",
+  healthPath: "/api/v1/health",
+  loadPath: "/api/v1/load",
+  unloadPath: "/api/v1/unload",
+  pullPath: "/api/v1/pull",
+  deletePath: "/api/v1/delete",
+  downloadsPath: "/v1/downloads",
+  downloadsControlPath: "/v1/downloads/control",
+  registrySearchPath: "/v1/registry/search",
+  pullVariantsPath: "/v1/pull/variants",
+  transcriptionPath: "/v1/audio/transcriptions",
+  imageGenerationPath: "/v1/images/generations",
+  imageEditPath: "/v1/images/edits",
+  imageVariationPath: "/v1/images/variations",
+  imageUpscalePath: "/v1/images/upscale",
+  speechPath: "/v1/audio/speech",
+  audioGenerationPath: "/v1/audio/generations",
+  mesh3dPath: "/v1/3d/generations",
+  classifyPath: "/v1/classify",
+  beaconPort: 13305,
+  chatOnly: true,
+  defaultTranscriptionModel: "Whisper-Large-v3",
+  defaultImageModel: "",
+  defaultUpscaleModel: "RealESRGAN-x4plus",
+  defaultClassifierModel: "",
+  outputDir: "",
+  discoveryTimeoutMs: 5000,
+  beaconTimeoutMs: 3000,
+  loadTimeoutMs: 300_000,
+  pullTimeoutMs: 30 * 60 * 1000,
+  transcriptionTimeoutMs: 300_000,
+  generationTimeoutMs: 600_000,
+  servers: [],
+};
+
+/** Strip JSONC comments — // line comments and block comments — so the
+ *  config file can be annotated by hand. String-aware: // inside quoted
+ *  values (URLs like http://...) is preserved. */
+function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (inString) {
+      out += c;
+      if (c === "\\" && i + 1 < text.length) {
+        out += text[i + 1];
+        i += 2;
+        continue;
+      }
+      if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i + 1 < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/** Load the required config file. Missing or unparseable config is a hard
+ *  failure — never a silent fallback to defaults, which would point at a
+ *  server that may not be yours. The loud failure lives in localLemonade()
+ *  at the bottom of this file; this function just throws with a reason. */
+function loadConfig(): LemonadeConfig {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    throw new Error(
+      `${CONFIG_PATH} does not exist. Copy the fully-commented example from the extension folder ` +
+        `(lemonade.example.json) to your pi agent dir, edit "baseUrl" for your server, and restart pi.`
+    );
+  }
+  const raw = JSON.parse(stripJsonComments(fs.readFileSync(CONFIG_PATH, "utf8")));
+  if (typeof raw !== "object" || !raw || Array.isArray(raw)) {
+    throw new Error(`${CONFIG_PATH} must contain a JSON object.`);
+  }
+  // servers[] is the ONLY instance store — validate it hard, loudly, up front.
+  if (!Array.isArray(raw.servers) || raw.servers.length === 0) {
+    throw new Error(
+      `${CONFIG_PATH} must define a non-empty "servers" array — there is no default instance outside it; ` +
+        `the FIRST entry is the default. Minimal example: ` +
+        `{ "servers": [{ "name": "main", "baseUrl": "http://your-lemonade-server:13305" }] }`
+    );
+  }
+  const seen = new Set<string>();
+  for (const [i, s] of (raw.servers as Array<Record<string, unknown>>).entries()) {
+    if (!s || typeof s !== "object") throw new Error(`${CONFIG_PATH}: servers[${i}] must be an object.`);
+    if (typeof s.name !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(s.name) || s.name === "default") {
+      throw new Error(
+        `${CONFIG_PATH}: servers[${i}].name must be lowercase letters/numbers/hyphens ("default" is reserved).`
+      );
+    }
+    if (seen.has(s.name)) throw new Error(`${CONFIG_PATH}: duplicate instance name "${s.name}".`);
+    seen.add(s.name);
+    if (typeof s.baseUrl !== "string" || !/^https?:\/\//.test(s.baseUrl)) {
+      throw new Error(`${CONFIG_PATH}: servers[${i}].baseUrl must be an http(s) URL.`);
+    }
+  }
+  return { ...DEFAULT_CONFIG, ...raw };
+}
+
+function saveConfig(config: LemonadeConfig): void {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+}
+
+// ─── Multi-instance support ─────────────────────────────────────────────────
+
+/** A resolved instance: its name plus a config *view* — same shared settings,
+ *  but baseUrl/apiKey swapped for that instance. Because every existing helper
+ *  (fetchCatalog, tools, TUI actions, discovery) takes a LemonadeConfig, an
+ *  instance view flows through all of them unchanged. This is the one place
+ *  instance semantics are defined; everything else inherits it. servers[0]
+ *  is the default instance — position, not a flag, decides defaultness. */
+export interface InstanceView {
+  name: string;
+  description: string;
+  isDefault: boolean;
+  config: LemonadeConfig;
+}
+
+function listInstances(config: LemonadeConfig): InstanceView[] {
+  return config.servers.map((s, i) => ({
+    name: s.name,
+    description: s.description ?? "",
+    isDefault: i === 0,
+    config: { ...config, baseUrl: s.baseUrl, apiKey: s.apiKey || config.apiKey },
+  }));
+}
+
+/** Resolve a config view for the named instance. Returns the default view
+ *  (servers[0]) when name is omitted; returns an error string for unknown
+ *  names, so callers surface actionable text instead of dialing a wrong box. */
+function instanceView(config: LemonadeConfig, name?: string): LemonadeConfig | string {
+  // "default" stays a reserved alias for servers[0], so old muscle memory
+  // and scripts keep working.
+  const target = !name || name === "default" ? config.servers[0] : config.servers.find((s) => s.name === name);
+  if (!target) {
+    return `Unknown lemonade instance "${name}". Available instances: ${config.servers.map((s) => s.name).join(", ")}.`;
+  }
+  return { ...config, baseUrl: target.baseUrl, apiKey: target.apiKey || config.apiKey };
+}
+
+/** pi provider id for an instance — uniformly `lemonade-<name>` for EVERY
+ *  instance, without prejudice. Model addresses follow: lemonade-main/
+ *  <model>. Renaming an instance changes its id (and re-registers it); old
+ *  references (pinned sessions, --model scripts) must follow the rename. */
+function instanceProviderId(view: InstanceView): string {
+  return `lemonade-${view.name}`;
+}
+
+// ─── Lemonade API types & helpers ───────────────────────────────────────────
+
+interface LemonadeModel {
+  id: string;
+  labels?: string[];
+  recipe?: string;
+  size?: number;
+  downloaded?: boolean;
+  max_context_window?: number;
+}
+
+interface LoadedModelInfo {
+  model_name: string;
+  type: string;
+  status: string;
+  device?: string;
+  pinned?: boolean;
+  max_context_window?: number;
+}
+
+interface LemonadeHealth {
+  status?: string;
+  version?: string;
+  model_loaded?: string | null;
+  all_models_loaded?: LoadedModelInfo[];
+  websocket_port?: number;
+  max_models?: Record<string, number>;
+}
+
+interface SystemStats {
+  cpu_percent?: number | null;
+  memory_gb?: number | null;
+  gpu_percent?: number | null;
+  vram_gb?: number | null;
+  npu_percent?: number | null;
+}
+
+interface PerfStats {
+  time_to_first_token?: number;
+  tokens_per_second?: number;
+  input_tokens?: number;
+  output_tokens?: number;
+  request_count_total?: number;
+}
+
+interface DiscoveredServer {
+  hostname: string;
+  baseUrl: string;
+}
+
+/** Server-owned download job snapshot (GET /v1/downloads). */
+interface DownloadJob {
+  id: string;
+  model_name?: string;
+  status: string; // downloading | paused | cancelled | completed | error
+  running?: boolean;
+  file?: string;
+  file_index?: number;
+  total_files?: number;
+  bytes_downloaded?: number;
+  bytes_total?: number;
+  percent?: number;
+  cumulative_bytes_downloaded?: number;
+  total_download_size?: number;
+  complete?: boolean;
+  error?: string;
+}
+
+interface RegistryResult {
+  repository_id: string;
+  display_name?: string;
+  description?: string;
+  downloads?: number;
+  likes?: number;
+  tags?: string[];
+}
+
+interface PullVariants {
+  checkpoint: string;
+  recipe?: string;
+  suggested_name?: string;
+  suggested_labels?: string[];
+  mmproj_files?: string[];
+  variants: Array<{ name: string; primary_file: string; files: string[]; sharded: boolean; size_bytes: number }>;
+}
+
+function url(config: LemonadeConfig, p: string): string {
+  return `${config.baseUrl.replace(/\/+$/, "")}${p}`;
+}
+
+function authHeaders(config: LemonadeConfig): Record<string, string> {
+  return config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {};
+}
+
+async function postJson(fullUrl: string, config: LemonadeConfig, body: unknown, timeoutMs: number): Promise<Response> {
+  const res = await fetch(fullUrl, {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  }
+  return res;
+}
+
+async function fetchCatalog(config: LemonadeConfig, showAll = false): Promise<LemonadeModel[]> {
+  const res = await fetch(url(config, `${config.modelsPath}${showAll ? "?show_all=true" : ""}`), {
+    headers: authHeaders(config),
+    signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const payload = (await res.json()) as { data?: LemonadeModel[] };
+  return payload.data ?? [];
+}
+
+async function fetchJsonOrNull<T>(config: LemonadeConfig, p: string): Promise<T | null> {
+  try {
+    const res = await fetch(url(config, p), {
+      headers: authHeaders(config),
+      signal: AbortSignal.timeout(config.discoveryTimeoutMs),
+    });
+    return res.ok ? ((await res.json()) as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchHealth(config: LemonadeConfig): Promise<LemonadeHealth | null> {
+  return fetchJsonOrNull<LemonadeHealth>(config, config.healthPath);
+}
+
+async function loadModel(config: LemonadeConfig, id: string, ctxSize?: number): Promise<string> {
+  const body: Record<string, unknown> = { model_name: id };
+  if (ctxSize) {
+    body.ctx_size = ctxSize;
+    body.save_options = true;
+  }
+  await postJson(url(config, config.loadPath), config, body, config.loadTimeoutMs);
+  return ctxSize ? `Loaded ${id} with ctx_size ${ctxSize}.` : `Loaded ${id}.`;
+}
+
+async function unloadModel(config: LemonadeConfig, id: string): Promise<void> {
+  await postJson(url(config, config.unloadPath), config, { model_name: id }, config.discoveryTimeoutMs);
+}
+
+/** Start a server-owned download job; returns the initial snapshot. */
+async function startPullJob(config: LemonadeConfig, id: string, extra?: Record<string, unknown>): Promise<DownloadJob> {
+  const res = await postJson(url(config, config.pullPath), config, {
+    model_name: id,
+    stream: true,
+    subscribe: false,
+    ...(extra ?? {}),
+  }, config.discoveryTimeoutMs);
+  return (await res.json()) as DownloadJob;
+}
+
+async function listDownloads(config: LemonadeConfig): Promise<DownloadJob[] | null> {
+  return fetchJsonOrNull<DownloadJob[]>(config, config.downloadsPath);
+}
+
+async function controlDownload(config: LemonadeConfig, jobId: string, action: "pause" | "cancel" | "remove"): Promise<void> {
+  await postJson(url(config, config.downloadsControlPath), config, { id: jobId, action }, config.discoveryTimeoutMs);
+}
+
+/** Blocking fallback for servers without download-job support. */
+async function pullModelBlocking(config: LemonadeConfig, id: string): Promise<string> {
+  await postJson(url(config, config.pullPath), config, { model_name: id }, config.pullTimeoutMs);
+  return `Pulled ${id} (downloaded to disk).`;
+}
+
+async function deleteModel(config: LemonadeConfig, id: string): Promise<string> {
+  await postJson(url(config, config.deletePath), config, { model_name: id }, config.pullTimeoutMs);
+  return `Deleted ${id} from disk.`;
+}
+
+/** Change ctx for a loaded model: unload → reload with new ctx_size + save_options. */
+async function changeModelContext(config: LemonadeConfig, id: string, ctxSize: number): Promise<string> {
+  await unloadModel(config, id);
+  return loadModel(config, id, ctxSize);
+}
+
+/** Parse "32k", "1m", "262144" → number of tokens. */
+function parseCtxSize(input: string): number | null {
+  const m = input.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)(k|m)?$/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  return m[2] === "k" ? Math.round(n * 1024) : m[2] === "m" ? Math.round(n * 1024 * 1024) : Math.round(n);
+}
+
+function formatBytes(bytes?: number): string {
+  if (!bytes || bytes <= 0) return "—";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+  return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
+}
+
+// ─── Server discovery (UDP beacon + HTTP fallback) ──────────────────────────
+
+function normalizeBaseUrl(raw: string): string {
+  return raw.trim().replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+}
+
+function discoverViaBeacon(config: LemonadeConfig, timeoutMs: number): Promise<DiscoveredServer[]> {
+  return new Promise((resolve) => {
+    const found = new Map<string, DiscoveredServer>();
+    let sock: ReturnType<typeof dgram.createSocket> | null = null;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const finish = () => {
+      if (timer) clearTimeout(timer);
+      if (sock) {
+        try { sock.close(); } catch { /* ignore */ }
+        sock = null;
+      }
+      resolve([...found.values()]);
+    };
+
+    try {
+      sock = dgram.createSocket({ type: "udp4", reuseAddr: true, reusePort: true } as never);
+      sock.on("error", finish);
+      sock.on("message", (msg: Buffer, rinfo: { address: string }) => {
+        try {
+          const beacon = JSON.parse(msg.toString());
+          if (beacon?.service !== "lemonade") return;
+          const base = normalizeBaseUrl(String(beacon.url ?? ""));
+          if (!base) return;
+          if (!found.has(base)) {
+            found.set(base, { hostname: String(beacon.hostname ?? rinfo.address), baseUrl: base });
+          }
+        } catch { /* not our beacon */ }
+      });
+      sock.bind(config.beaconPort);
+    } catch {
+      finish();
+      return;
+    }
+    timer = setTimeout(finish, timeoutMs);
+  });
+}
+
+async function discoverViaHttp(config: LemonadeConfig): Promise<DiscoveredServer[]> {
+  const candidateHosts = new Set(["localhost"]);
+  // Probe every configured instance's host, not just one: the raw config has
+  // no single baseUrl anymore — servers[] is the only instance store.
+  for (const s of config.servers) {
+    try {
+      candidateHosts.add(new URL(s.baseUrl).hostname);
+    } catch { /* skip malformed */ }
+  }
+  const ports = [13305, 8000, 1234, 9000, 8080];
+
+  const probes = [...candidateHosts].flatMap((host) =>
+    ports.map(async (port) => {
+      try {
+        const res = await fetch(`http://${host}:${port}/api/v1/health`, {
+          signal: AbortSignal.timeout(1500),
+        });
+        if (!res.ok) return null;
+        const body = (await res.json()) as { status?: string; version?: string };
+        if (typeof body.status !== "string") return null;
+        return { hostname: host, baseUrl: `http://${host}:${port}` } as DiscoveredServer;
+      } catch {
+        return null;
+      }
+    })
+  );
+  const results = await Promise.all(probes);
+  const seen = new Map<string, DiscoveredServer>();
+  for (const r of results) if (r && !seen.has(r.baseUrl)) seen.set(r.baseUrl, r);
+  return [...seen.values()];
+}
+
+// ─── Provider registration ──────────────────────────────────────────────────
+
+function isChatModel(m: LemonadeModel): boolean {
+  return (
+    (m.labels ?? []).includes("chat") ||
+    m.recipe === "llamacpp" ||
+    // Omni collections bundle a chat LLM with server-side tools (image gen,
+    // TTS) and are driven through chat completions like any chat model.
+    m.recipe === "collection.omni"
+  );
+}
+
+function toProviderModel(m: LemonadeModel, loaded: Set<string>, providerId = "lemonade") {
+  const labels = m.labels ?? [];
+  const contextWindow = m.max_context_window ?? 128000;
+  return {
+    id: m.id,
+    name: loaded.has(m.id)
+      ? `${m.id} (${providerId}, loaded)`
+      : `${m.id} (${providerId}, on-demand)`,
+    reasoning: labels.includes("reasoning"),
+    input: labels.includes("vision") ? (["text", "image"] as const) : (["text"] as const),
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow,
+    maxTokens: Math.min(contextWindow, 32768),
+    compat: {
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: "max_tokens" as const,
+    },
+  };
+}
+
+async function registerInstanceProvider(pi: ExtensionAPI, view: InstanceView): Promise<number> {
+  const config = view.config;
+  const providerId = instanceProviderId(view);
+  let catalog: LemonadeModel[];
+  let loaded = new Set<string>();
+  try {
+    const [catalogRes, health] = await Promise.all([
+      fetchCatalog(config),
+      fetchHealth(config),
+    ]);
+    catalog = catalogRes;
+    loaded = new Set((health?.all_models_loaded ?? []).map((m) => m.model_name));
+  } catch {
+    // Unreachable => contribute nothing to /model. No placeholders: an
+    // unreachable model is not listable. Sessions pinned to a lemonade model
+    // will hard-fail model resolution until the box is reachable again —
+    // the accepted tradeoff of "fully automated, fully honest" listings.
+    catalog = [];
+    console.error(
+      `[local-lemonade] instance "${view.name}" unreachable at ${config.baseUrl}; registering no models`
+    );
+  }
+
+  const advertised = config.chatOnly ? catalog.filter(isChatModel) : catalog;
+
+  try {
+    pi.unregisterProvider(providerId);
+  } catch {
+    // not previously registered
+  }
+
+  pi.registerProvider(providerId, {
+    name: `Lemonade ${view.name} (self-hosted)`,
+    baseUrl: url(config, config.chatPath),
+    apiKey: config.apiKey || "lemonade",
+    authHeader: true,
+    api: "openai-completions",
+    models: advertised.map((m) => toProviderModel(m, loaded, providerId)),
+  });
+
+  return advertised.length;
+}
+
+/** Provider ids used by past versions of this extension. unregisterProvider
+ *  only works within the running pi process, and ids changed over the
+ *  extension's evolution, so a long-lived session (or /reload after an
+ *  upgrade) can accumulate ghost providers registered by old code. Each
+ *  registration pass sweeps them; anything not in this list and not a
+ *  current instance id persists until the pi process restarts. */
+const LEGACY_PROVIDER_IDS = ["lemonade", "lemonade-undefined"];
+
+/** Register (or re-register) every configured instance. Each becomes its own
+ *  pi provider under the uniform lemonade-<name> id. */
+async function registerLemonadeProvider(pi: ExtensionAPI, config: LemonadeConfig): Promise<number> {
+  for (const staleId of LEGACY_PROVIDER_IDS) {
+    try {
+      pi.unregisterProvider(staleId);
+    } catch { /* never registered; fine */ }
+  }
+  let total = 0;
+  for (const view of listInstances(config)) {
+    total += await registerInstanceProvider(pi, view);
+  }
+  return total;
+}
+
+// ─── Multimodal agent tools ──────────────────────────────────────────────────
+
+/** Formats lemonade's whisper backend can't ingest; converted via ffmpeg. */
+const CONTAINER_FORMATS = new Set([
+  ".mp4", ".m4a", ".mov", ".webm", ".mkv", ".avi", ".aac", ".ogg", ".opus", ".flac",
+]);
+
+function runFfmpeg(args: string[], timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", ...args]);
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (e) => { clearTimeout(timer); reject(e); });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      code === 0 ? resolve() : reject(new Error(`ffmpeg exited ${code}: ${stderr.slice(0, 300)}`));
+    });
+  });
+}
+
+function outputDir(config: LemonadeConfig): string {
+  return config.outputDir ? path.resolve(config.outputDir) : process.cwd();
+}
+
+function outputFilePath(config: LemonadeConfig, kind: string, ext: string): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  return path.join(outputDir(config), `lemonade-${kind}-${stamp}.${ext}`);
+}
+
+/** Find a sensible default model for a tool, by label, from the live catalog. */
+/**
+ * Returns: the picked model id, undefined if no catalog model matches, or
+ * null if the server is unreachable — callers must surface that distinctly,
+ * because "nothing matches" and "no route to the server" need different advice.
+ */
+async function pickModelByLabels(
+  config: LemonadeConfig,
+  labelCandidates: string[]
+): Promise<string | null | undefined> {
+  try {
+    const catalog = await fetchCatalog(config);
+    const matches = catalog.filter((m) =>
+      (m.labels ?? []).some((l) => labelCandidates.includes(l))
+    );
+    const downloaded = matches.find((m) => m.downloaded !== false) ?? matches[0];
+    return downloaded?.id;
+  } catch {
+    return null; // unreachable
+  }
+}
+
+/** Find the first catalog model using a given recipe (e.g. onnxruntime). */
+async function pickModelByRecipe(
+  config: LemonadeConfig,
+  recipe: string
+): Promise<string | null | undefined> {
+  try {
+    const catalog = await fetchCatalog(config);
+    const matches = catalog.filter((m) => m.recipe === recipe);
+    const downloaded = matches.find((m) => m.downloaded !== false) ?? matches[0];
+    return downloaded?.id;
+  } catch {
+    return null; // unreachable
+  }
+}
+
+function toolError(message: string): { content: Array<{ type: "text"; text: string }>; details: {} } {
+  return { content: [{ type: "text", text: `Error: ${message}` }], details: {} };
+}
+
+function unreachableMessage(config: LemonadeConfig): string {
+  return (
+    `Lemonade server at ${config.baseUrl} is unreachable from this network — ` +
+    "there is probably no route back to the lemonade LAN. Reconnect to a network " +
+    "with access, or point the extension at a reachable instance: /lemonade-setup → " +
+    "Server settings → Edit base URL (or Discover servers)."
+  );
+}
+
+/** fetch() for tool paths: converts raw network rejections (the cryptic
+ *  "fetch failed") into a descriptive, actionable error. Abort/cancel passes
+ *  through untouched. */
+async function toolFetch(config: LemonadeConfig, p: string, init: RequestInit): Promise<Response> {
+  try {
+    return await fetch(url(config, p), init);
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") throw error;
+    throw new Error(unreachableMessage(config));
+  }
+}
+
+/** POST JSON, save binary response body to a file. */
+async function postJsonSaveBinary(
+  config: LemonadeConfig,
+  p: string,
+  body: Record<string, unknown>,
+  kind: string,
+  ext: string
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const res = await toolFetch(config, p, {
+    method: "POST",
+    headers: { ...authHeaders(config), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(config.generationTimeoutMs),
+  });
+  if (!res.ok) {
+    return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const file = outputFilePath(config, kind, ext);
+  await fs.promises.writeFile(file, buf);
+  return {
+    content: [{ type: "text", text: `Saved ${file} (${formatBytes(buf.length)}).` }],
+    details: { file },
+  };
+}
+
+/** POST multipart, save JSON response's b64_json / raw binary to a file. */
+async function postFormSaveImage(
+  config: LemonadeConfig,
+  p: string,
+  form: FormData,
+  kind: string
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+  const res = await toolFetch(config, p, {
+    method: "POST",
+    headers: authHeaders(config),
+    body: form,
+    signal: AbortSignal.timeout(config.generationTimeoutMs),
+  });
+  if (!res.ok) {
+    return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+  }
+  const contentType = res.headers.get("content-type") ?? "";
+  const file = outputFilePath(config, kind, "png");
+  if (contentType.includes("application/json")) {
+    const payload = (await res.json()) as { data?: Array<{ b64_json?: string; url?: string }> };
+    const b64 = payload.data?.[0]?.b64_json;
+    if (!b64) return toolError("Server response contained no image data.");
+    await fs.promises.writeFile(file, Buffer.from(b64, "base64"));
+  } else {
+    await fs.promises.writeFile(file, Buffer.from(await res.arrayBuffer()));
+  }
+  return {
+    content: [{ type: "text", text: `Saved ${file}.` }],
+    details: { file },
+  };
+}
+
+function readRequiredFile(resolved: string): Promise<Buffer> {
+  return fs.promises.readFile(resolved);
+}
+
+async function prepareAudioForWhisper(config: LemonadeConfig, resolved: string): Promise<string> {
+  if (!CONTAINER_FORMATS.has(path.extname(resolved).toLowerCase())) return resolved;
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-whisper-"));
+  const converted = path.join(tmpDir, "converted.wav");
+  await runFfmpeg(
+    ["-i", resolved, "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", converted],
+    config.transcriptionTimeoutMs
+  );
+  return converted;
+}
+
+async function registerAgentTools(pi: ExtensionAPI, gconfig: LemonadeConfig): Promise<void> {
+  // Harness-level self-awareness: these lines are merged into the Guidelines
+  // section of every chat's system prompt, so even a virgin chat knows where
+  // its lemonade machinery lives without having to hunt for it. (pi dedupes
+  // guideline strings, so attaching once is enough.)
+  const AWARENESS = [
+    "Self-hosted Lemonade server: base URL, endpoint paths, and defaults live in ~/.pi/agent/lemonade.json; full documentation (tools, endpoints, behavior reference, official API spec) is at ~/.pi/agent/extensions/local-lemonade/README.md and docs/ beside it.",
+    "For questions about the lemonade server (loaded models, catalog, health, host resources), query its HTTP API directly with bash + curl using the config; for interactive management, tell the user to run the /lemonade-setup command.",
+    `Lemonade instances available to tools: ${listInstances(gconfig)
+      .map((v) => `${v.name}${v.isDefault ? " (default)" : ""} (${v.config.baseUrl})`)
+      .join("; ")}. Tools accept an optional server argument naming an instance; omit it for the default.`,
+  ];
+
+  const SERVER_PARAM_DESC =
+    "Instance name for multi-server setups (omit for the default instance; see guidelines for the available names).";
+
+  // Enumerate the classifiers actually present on the server, so the tool's
+  // advertisement reflects reality each session. The label universe of each
+  // classifier is baked into the model itself and is revealed at runtime by
+  // the response's labels — the description can only hint via model ids.
+  let classifierHint = "";
+  try {
+    const catalog = await fetchCatalog(gconfig);
+    const classifiers = catalog.filter((m) => m.recipe === "onnxruntime");
+    if (classifiers.length) {
+      const pulled = classifiers.filter((m) => m.downloaded !== false).map((m) => m.id);
+      classifierHint =
+        `Classifiers on this server: ${classifiers.map((m) => m.id).join(", ")}. ` +
+        (pulled.length ? `Pulled and ready: ${pulled.join(", ")}.` : "None pulled yet — pull via /lemonade-setup.");
+    }
+  } catch {
+    // server unreachable at registration time — description stays generic
+  }
+
+  // ── transcribe_audio ────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "transcribe_audio",
+    label: "Transcribe Audio",
+    description:
+      "Transcribe an audio or video file (wav, mp3, mp4, m4a, webm, flac, ...) to text " +
+      "using a Whisper model on the self-hosted lemonade server. Video/container " +
+      "formats are converted to wav with ffmpeg automatically. Returns the transcript.",
+    promptSnippet: "[lemonade] Transcribe audio or video files (wav, mp3, mp4, m4a, webm, ...) to text with Whisper",
+    promptGuidelines: AWARENESS,
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      file_path: Type.String({ description: "Path to the audio/video file to transcribe." }),
+      language: Type.Optional(
+        Type.String({ description: "Optional ISO-639-1 language hint (e.g. 'en')." })
+      ),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.file_path);
+      let data: Buffer;
+      let fileToSend: string;
+      try {
+        fileToSend = await prepareAudioForWhisper(config, resolved);
+        data = await readRequiredFile(fileToSend);
+      } catch (error) {
+        return toolError(`Could not prepare '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const form = new FormData();
+      form.append("file", new File([data], path.basename(fileToSend)));
+      form.append("model", config.defaultTranscriptionModel);
+      if (params.language) form.append("language", params.language);
+      const response = await toolFetch(config, config.transcriptionPath, {
+        method: "POST",
+        headers: authHeaders(config),
+        body: form,
+        signal,
+      });
+      if (!response.ok) {
+        return toolError(`HTTP ${response.status}: ${(await response.text()).slice(0, 400)}`);
+      }
+      const payload = (await response.json()) as { text?: string };
+      return {
+        content: [{ type: "text", text: payload.text ?? "" }],
+        details: { file: resolved, model: config.defaultTranscriptionModel },
+      };
+    },
+  });
+
+  // ── generate_image ──────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "generate_image",
+    label: "Generate Image",
+    description:
+      "Generate an image from a text prompt using an image model on the lemonade server " +
+      "(e.g. Flux, Z-Image, SD-Turbo). Saves the PNG to disk and returns its path. " +
+      "If no model is specified, the first image model in the catalog is used. " +
+      "Image generation can take a while on first use (model auto-loads).",
+    promptSnippet: "[lemonade] Generate images from text prompts with the local Flux/SD models (saves PNG to disk)",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      prompt: Type.String({ description: "Text description of the image to generate." }),
+      model: Type.Optional(Type.String({ description: "Image model id. Omit to auto-pick." })),
+      size: Type.Optional(Type.String({ description: "Output size as WIDTHxHEIGHT, e.g. 512x512." })),
+      steps: Type.Optional(Type.Number({ description: "Inference steps. Turbo models work well with 4." })),
+      cfg_scale: Type.Optional(Type.Number({ description: "Classifier-free guidance scale. Turbo ~1.0, standard ~7.5." })),
+      seed: Type.Optional(Type.Number({ description: "Random seed for reproducibility." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByLabels(config, ["image"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultImageModel || auto;
+      if (!model) return toolError("No image model found on the lemonade server. Pull one first (e.g. Z-Image-Turbo).");
+      const body: Record<string, unknown> = { model, prompt: params.prompt, response_format: "b64_json" };
+      if (params.size) body.size = params.size;
+      if (params.steps) body.steps = params.steps;
+      if (params.cfg_scale) body.cfg_scale = params.cfg_scale;
+      if (params.seed !== undefined) body.seed = params.seed;
+      const res = await toolFetch(config, config.imageGenerationPath, {
+        method: "POST",
+        headers: { ...authHeaders(config), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+      const payload = (await res.json()) as { data?: Array<{ b64_json?: string }> };
+      const b64 = payload.data?.[0]?.b64_json;
+      if (!b64) return toolError("Server response contained no image data.");
+      const file = outputFilePath(config, "image", "png");
+      await fs.promises.writeFile(file, Buffer.from(b64, "base64"));
+      return {
+        content: [{ type: "text", text: `Saved ${file} (model: ${model}).` }],
+        details: { file, model },
+      };
+    },
+  });
+
+  // ── edit_image ──────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "edit_image",
+    label: "Edit Image",
+    description:
+      "Edit an image with a text prompt (e.g. 'add a red barn, photorealistic') using an " +
+      "edit-capable image model on the lemonade server. Saves the edited PNG and returns its path.",
+    promptSnippet: "[lemonade] Edit local images with text prompts (add/remove/change things), saves result PNG",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the source image (PNG)." }),
+      prompt: Type.String({ description: "Description of the desired edit." }),
+      model: Type.Optional(Type.String({ description: "Edit-capable model id (e.g. Flux-2-Klein-9B-GGUF). Omit to auto-pick." })),
+      mask_path: Type.Optional(Type.String({ description: "Optional mask PNG: white = edit, black = preserve." })),
+      size: Type.Optional(Type.String({ description: "Output size WIDTHxHEIGHT, e.g. 512x512." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const auto = await pickModelByLabels(config, ["edit", "image"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultImageModel || auto;
+      if (!model) return toolError("No edit-capable image model found on the lemonade server.");
+      const form = new FormData();
+      form.append("model", model);
+      form.append("prompt", params.prompt);
+      form.append("response_format", "b64_json");
+      if (params.size) form.append("size", params.size);
+      form.append("image", new File([buf], path.basename(resolved), { type: "image/png" }));
+      if (params.mask_path) {
+        try {
+          const mask = await readRequiredFile(path.resolve(params.mask_path));
+          form.append("mask", new File([mask], path.basename(params.mask_path!), { type: "image/png" }));
+        } catch { /* mask is optional */ }
+      }
+      const result = await postFormSaveImage(config, config.imageEditPath, form, "image-edit");
+      return result;
+    },
+  });
+
+  // ── vary_image ──────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "vary_image",
+    label: "Vary Image",
+    description:
+      "Generate a variation of an image using the lemonade server's image models. " +
+      "Saves the variation PNG and returns its path.",
+    promptSnippet: "[lemonade] Generate variations of local images",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the source image (PNG)." }),
+      model: Type.Optional(Type.String({ description: "Image model id. Omit to auto-pick." })),
+      size: Type.Optional(Type.String({ description: "Output size WIDTHxHEIGHT." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const auto = await pickModelByLabels(config, ["edit", "image"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultImageModel || auto;
+      if (!model) return toolError("No image model found on the lemonade server.");
+      const form = new FormData();
+      form.append("model", model);
+      form.append("response_format", "b64_json");
+      if (params.size) form.append("size", params.size);
+      form.append("image", new File([buf], path.basename(resolved), { type: "image/png" }));
+      return postFormSaveImage(config, config.imageVariationPath, form, "image-variation");
+    },
+  });
+
+  // ── upscale_image ───────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "upscale_image",
+    label: "Upscale Image",
+    description:
+      "Upscale an image 4x with Real-ESRGAN on the lemonade server " +
+      "(models: RealESRGAN-x4plus, RealESRGAN-x4plus-anime). Saves the upscaled PNG and returns its path.",
+    promptSnippet: "[lemonade] Upscale images 4x with Real-ESRGAN",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the image to upscale (PNG)." }),
+      model: Type.Optional(Type.String({ description: `Upscale model id. Default: ${DEFAULT_CONFIG.defaultUpscaleModel}.` })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const model = params.model ?? config.defaultUpscaleModel;
+      const res = await toolFetch(config, config.imageUpscalePath, {
+        method: "POST",
+        headers: { ...authHeaders(config), "Content-Type": "application/json" },
+        body: JSON.stringify({ image: buf.toString("base64"), model }),
+        signal,
+      });
+      if (!res.ok) return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+      const payload = (await res.json()) as { data?: Array<{ b64_json?: string }> };
+      const b64 = payload.data?.[0]?.b64_json;
+      if (!b64) return toolError("Server response contained no image data.");
+      const file = outputFilePath(config, "image-upscaled", "png");
+      await fs.promises.writeFile(file, Buffer.from(b64, "base64"));
+      return { content: [{ type: "text", text: `Saved ${file} (model: ${model}).` }], details: { file, model } };
+    },
+  });
+
+  // ── text_to_speech ──────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "text_to_speech",
+    label: "Text to Speech",
+    description:
+      "Convert text to spoken audio using a TTS model on the lemonade server " +
+      "(e.g. OpenMOSS-TTS). Saves the audio file and returns its path.",
+    promptSnippet: "[lemonade] Convert text to spoken audio (TTS), saves mp3/wav to disk",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      text: Type.String({ description: "The text to speak." }),
+      model: Type.Optional(Type.String({ description: "TTS model id. Omit to auto-pick from catalog." })),
+      voice: Type.Optional(Type.String({ description: "Voice name (e.g. 'alloy', 'af_sky')." })),
+      speed: Type.Optional(Type.Number({ description: "Speaking speed (default 1.0)." })),
+      response_format: Type.Optional(Type.String({ description: "Output format: mp3 (default), wav, opus, pcm." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByLabels(config, ["tts"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || auto;
+      if (!model) return toolError("No TTS model found on the lemonade server. Pull one first (e.g. OpenMOSS-TTS).");
+      const fmt = params.response_format ?? "mp3";
+      const body: Record<string, unknown> = { model, input: params.text, response_format: fmt };
+      if (params.voice) body.voice = params.voice;
+      if (params.speed) body.speed = params.speed;
+      const res = await toolFetch(config, config.speechPath, {
+        method: "POST",
+        headers: { ...authHeaders(config), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+      const buf = Buffer.from(await res.arrayBuffer());
+      const file = outputFilePath(config, "speech", fmt === "pcm" ? "pcm" : fmt);
+      await fs.promises.writeFile(file, buf);
+      return { content: [{ type: "text", text: `Saved ${file} (${formatBytes(buf.length)}, model: ${model}).` }], details: { file, model } };
+    },
+  });
+
+  // ── generate_audio (music / sound effects) ─────────────────────────────
+  pi.registerTool({
+    name: "generate_audio",
+    label: "Generate Audio",
+    description:
+      "Generate music or sound effects from a text prompt using audio-generation models on " +
+      "the lemonade server (e.g. ACE-Step-Music, ThinkSound-SFX). For music with vocals, " +
+      "pass lyrics with section tags like [verse] and [chorus]. Saves a wav file and returns its path.",
+    promptSnippet: "[lemonade] Generate music or sound effects from text prompts (ACE-Step / ThinkSound), saves wav",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      prompt: Type.String({ description: "Style description: genre, mood, tempo, instruments, voice character." }),
+      model: Type.Optional(Type.String({ description: "Audio model id (e.g. ThinkSound-SFX, ACE-Step-Music). Omit to auto-pick." })),
+      duration: Type.Optional(Type.Number({ description: "Clip length in seconds." })),
+      lyrics: Type.Optional(Type.String({ description: "Lyrics to sing (music models only). Omit for instrumental." })),
+      vocal_language: Type.Optional(Type.String({ description: "BCP-47 language of lyrics, e.g. 'en' (music models only)." })),
+      seed: Type.Optional(Type.Number({ description: "Random seed for reproducibility." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByLabels(config, ["music", "sfx", "audio", "tts-audio"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || auto;
+      if (!model) return toolError("No audio-generation model found on the lemonade server. Pull one first (e.g. ThinkSound-SFX).");
+      const body: Record<string, unknown> = { model, prompt: params.prompt, response_format: "wav" };
+      if (params.duration) body.duration = params.duration;
+      if (params.lyrics) body.lyrics = params.lyrics;
+      if (params.vocal_language) body.vocal_language = params.vocal_language;
+      if (params.seed !== undefined) body.seed = params.seed;
+      const res = await toolFetch(config, config.audioGenerationPath, {
+        method: "POST",
+        headers: { ...authHeaders(config), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+      const buf = Buffer.from(await res.arrayBuffer());
+      const file = outputFilePath(config, "audio-gen", "wav");
+      await fs.promises.writeFile(file, buf);
+      return { content: [{ type: "text", text: `Saved ${file} (${formatBytes(buf.length)}, model: ${model}).` }], details: { file, model } };
+    },
+  });
+
+  // ── generate_3d_model ──────────────────────────────────────────────────
+  pi.registerTool({
+    name: "generate_3d_model",
+    label: "Generate 3D Model",
+    description:
+      "Generate a textured 3D mesh (.glb) from an image using the TRELLIS-3D model on the " +
+      "lemonade server. Saves the .glb file and returns its path. Can take minutes.",
+    promptSnippet: "[lemonade] Generate textured 3D meshes (.glb) from images with TRELLIS",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      image_path: Type.String({ description: "Path to the input image (PNG/JPEG/BMP/GIF)." }),
+      model: Type.Optional(Type.String({ description: "3D model id, e.g. TRELLIS-3D. Omit to auto-pick." })),
+      resolution: Type.Optional(Type.Number({ description: "Cascade resolution: 512 (default), 1024, or 1536." })),
+      seed: Type.Optional(Type.Number({ description: "Random seed for reproducibility." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const resolved = path.resolve(params.image_path);
+      let buf: Buffer;
+      try {
+        buf = await readRequiredFile(resolved);
+      } catch (error) {
+        return toolError(`Could not read '${resolved}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const auto = await pickModelByLabels(config, ["3d"]);
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || auto;
+      if (!model) return toolError("No 3D-generation model found on the lemonade server. Pull one first (e.g. TRELLIS-3D).");
+      const body: Record<string, unknown> = { model, image: `data:image/png;base64,${buf.toString("base64")}` };
+      if (params.resolution) body.resolution = params.resolution;
+      if (params.seed !== undefined) body.seed = params.seed;
+      return postJsonSaveBinary(config, config.mesh3dPath, body, "mesh3d", "glb");
+    },
+  });
+
+  // ── classify_text ────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "classify_text",
+    label: "Classify Text",
+    description:
+      "Classify input TEXT with an encoder-classifier model on the lemonade server " +
+      "(recipe: onnxruntime). Each classifier answers exactly one question, decided by " +
+      "its baked-in label set, and the response's labels reveal that universe — if they " +
+      "don't fit the question, retry with a different model. Text-only by architecture: " +
+      "image questions go to vision-capable chat models (read the image), audio must be " +
+      "transcribed first (transcribe_audio). " +
+      (classifierHint ||
+        "Common classifier types: phishing/PII/prompt-injection detection. Pull via /lemonade-setup.") +
+      " Returns all labels with confidence scores, ranked highest to lowest.",
+    promptSnippet:
+      "[lemonade] Classify text through safety/phishing/PII-style classifier models — ranked label confidences",
+    parameters: Type.Object({
+      server: Type.Optional(Type.String({ description: SERVER_PARAM_DESC })),
+      input: Type.String({ description: "The text to classify." }),
+      model: Type.Optional(
+        Type.String({ description: "Classifier model id (recipe onnxruntime). Omit to auto-pick." })
+      ),
+      top_k: Type.Optional(
+        Type.Number({ description: "Only return the highest-scoring k labels." })
+      ),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const instCfg = instanceView(gconfig, params.server);
+      if (typeof instCfg === "string") return toolError(instCfg);
+      const config = instCfg; // instance view — every reference below targets the selected box
+      const auto = await pickModelByRecipe(config, "onnxruntime");
+      if (auto === null) return toolError(unreachableMessage(config));
+      const model = params.model || config.defaultClassifierModel || auto;
+      if (!model) {
+        return toolError(
+          "No classifier model (onnxruntime recipe) found on the lemonade server. " +
+            "Pull one first, e.g. Bert-Phishing-ONNX or Phishing-Email-Detection-ONNX."
+        );
+      }
+      const body: Record<string, unknown> = { model, input: params.input };
+      if (params.top_k) body.top_k = params.top_k;
+      const res = await toolFetch(config, config.classifyPath, {
+        method: "POST",
+        headers: { ...authHeaders(config), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) {
+        return toolError(`HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+      }
+      const payload = (await res.json()) as Record<string, unknown> & {
+        labels?: Record<string, number>;
+        model?: string;
+      };
+      const ranked = Object.entries(payload.labels ?? {})
+        .sort((a, b) => b[1] - a[1])
+        .map(([label, score]) => `${(score * 100).toFixed(3).padStart(7)}%  ${label}`);
+      // Some classifiers (token-classification, e.g. PII span detection) return
+      // extra structure beyond the flat label map — pass it through verbatim.
+      const extras = Object.keys(payload).filter((k) => !["labels", "model", "object"].includes(k));
+      const extraText = extras.length
+        ? "\n" + JSON.stringify(Object.fromEntries(extras.map((k) => [k, payload[k]])), null, 2)
+        : "";
+      const text =
+        `Classification by ${payload.model ?? model}:\n` +
+        (ranked.length ? ranked.join("\n") : "(no labels returned)") +
+        extraText;
+      return { content: [{ type: "text", text }], details: { model } };
+    },
+  });
+}
+
+// ─── /lemonade-setup TUI ────────────────────────────────────────────────────
+
+type UiCtx = { ui: import("@earendil-works/pi-coding-agent").ExtensionContext["ui"] };
+
+/** Show a SelectList menu framed with DynamicBorder. Returns chosen value or null on Esc. */
+function menu<T extends string>(ctx: UiCtx, title: string, items: SelectItem<T>[]): Promise<T | null> {
+  return ctx.ui.custom<T | null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+    const list = new SelectList(items, Math.min(items.length, 12), {
+      selectedPrefix: (t) => theme.fg("accent", t),
+      selectedText: (t) => theme.fg("accent", t),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    });
+    list.onSelect = (item) => done(item.value);
+    list.onCancel = () => done(null);
+    container.addChild(list);
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc back"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => { list.handleInput(data); tui.requestRender(); },
+    };
+  });
+}
+
+/** Full-screen framed text view (status output); any key returns. */
+async function textView(ctx: UiCtx, title: string, lines: string[]): Promise<void> {
+  await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+    for (const line of lines) container.addChild(new Text(line, 0, 0));
+    container.addChild(new Text(theme.fg("dim", "press any key to return"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: () => { done(null); tui.requestRender(); },
+    };
+  });
+}
+
+/**
+ * Live download-progress view over a server-owned download job.
+ * Polls GET /v1/downloads once per second; Esc sends a cancel via
+ * /v1/downloads/control. Resolves when the job completes, errors,
+ * disappears (treated as completed), or the user cancels.
+ */
+async function trackDownload(
+  ctx: UiCtx,
+  config: LemonadeConfig,
+  jobId: string,
+  label: string
+): Promise<"complete" | "cancelled" | "error"> {
+  const outcome = await ctx.ui.custom<"complete" | "cancelled" | "error">((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(`Downloading ${label}`)), 1, 0));
+    const statusLine = new Text("starting…", 0, 0);
+    container.addChild(statusLine);
+    container.addChild(new Text(theme.fg("dim", "esc cancel • progress updates every second"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    let finished = false;
+    let seen = false;
+    const finish = (v: "complete" | "cancelled" | "error") => {
+      if (finished) return;
+      finished = true;
+      done(v);
+    };
+
+    void (async () => {
+      while (!finished) {
+        const jobs = await listDownloads(config);
+        const job = (jobs ?? []).find((j) => j.id === jobId);
+        if (job) {
+          seen = true;
+          const pct = typeof job.percent === "number" ? `${job.percent.toFixed(1)}%` : "?";
+          const bytes = `${formatBytes(job.cumulative_bytes_downloaded ?? job.bytes_downloaded)} / ${formatBytes(job.total_download_size ?? job.bytes_total)}`;
+          statusLine.setText(
+            `${job.status} — ${pct} (${bytes})${job.file ? ` — ${job.file}` : ""}` +
+              `${job.file_index && job.total_files ? ` [file ${job.file_index}/${job.total_files}]` : ""}` +
+              (job.error ? `\nerror: ${job.error.slice(0, 120)}` : "")
+          );
+          tui.requestRender();
+          if (job.complete || job.status === "completed") return finish("complete");
+          if (job.status === "error") return finish("error");
+          if (job.status === "cancelled") return finish("cancelled");
+        } else if (seen) {
+          // Completed jobs are removed from the list after a short delay.
+          return finish("complete");
+        } else if (jobs !== null) {
+          // Job not registered yet (server hasn't picked it up) — keep polling.
+        } else {
+          statusLine.setText("cannot reach server — press esc to cancel");
+          tui.requestRender();
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    })();
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => {
+        if (matchesKey(data, Key.escape)) {
+          statusLine.setText("cancelling…");
+          tui.requestRender();
+          void controlDownload(config, jobId, "cancel").catch(() => {});
+          finish("cancelled");
+        }
+      },
+    };
+  });
+  return outcome;
+}
+
+/** Live server log viewer: subscribes to ws://host:{wsPort}/logs/stream, shows
+ *  the snapshot backlog then live entries; Esc closes. */
+async function liveLogsView(ctx: UiCtx, config: LemonadeConfig): Promise<void> {
+  ctx.ui.setStatus("lemonade-setup", "Finding websocket port…");
+  const health = await fetchHealth(config);
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  const wsPort = health?.websocket_port;
+  if (!wsPort) {
+    ctx.ui.notify("Server unreachable, or no websocket port advertised — cannot stream logs.", "error");
+    return;
+  }
+  let host = "localhost";
+  try {
+    host = new URL(config.baseUrl).hostname;
+  } catch { /* keep localhost */ }
+  const wsUrl = `ws://${host}:${wsPort}/logs/stream`;
+
+  await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(`Live Server Logs`)), 1, 0));
+    container.addChild(new Text(theme.fg("dim", wsUrl), 0, 0));
+    const logText = new Text("connecting…", 0, 0);
+    container.addChild(logText);
+    container.addChild(new Text(theme.fg("dim", "esc to close • newest 40 lines shown"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    const lines: string[] = [];
+    let closed = false;
+    const push = (line: string) => {
+      if (closed) return;
+      lines.push(line.slice(0, 200));
+      if (lines.length > 500) lines.splice(0, lines.length - 500);
+      logText.setText(lines.slice(-40).join("\n"));
+      tui.requestRender();
+    };
+
+    let ws: { close: () => void } | null = null;
+    try {
+      const WS = (globalThis as { WebSocket?: new (url: string) => WebSocket }).WebSocket;
+      if (!WS) throw new Error("no WebSocket global in this runtime");
+      const sock = new WS(wsUrl) as WebSocket & {
+        onopen: (() => void) | null;
+        onmessage: ((ev: { data: unknown }) => void) | null;
+        onclose: (() => void) | null;
+        onerror: (() => void) | null;
+        send: (data: string) => void;
+      };
+      ws = { close: () => { try { sock.close(); } catch { /* ignore */ } } };
+      sock.onopen = () => {
+        sock.send(JSON.stringify({ type: "logs.subscribe", after_seq: null }));
+        push("— subscribed —");
+      };
+      sock.onmessage = (ev) => {
+        try {
+          const msg = JSON.parse(String(ev.data)) as {
+            type?: string;
+            entries?: Array<{ timestamp?: string; line?: string }>;
+            entry?: { timestamp?: string; line?: string };
+          };
+          if (msg.type === "logs.snapshot") {
+            for (const e of msg.entries ?? []) push(`${e.timestamp ?? ""} ${e.line ?? ""}`);
+            if (!(msg.entries ?? []).length) push("(no backlog entries)");
+          } else if (msg.type === "logs.entry") {
+            const e = msg.entry ?? {};
+            push(`${e.timestamp ?? ""} ${e.line ?? ""}`);
+          }
+        } catch { /* non-JSON frame */ }
+      };
+      sock.onclose = () => push("— connection closed —");
+      sock.onerror = () => push("— connection error —");
+    } catch (error) {
+      push(`connect failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    return {
+      render: (w) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data) => {
+        if (matchesKey(data, Key.escape)) {
+          closed = true;
+          ws?.close();
+          done(null);
+          tui.requestRender();
+        }
+      },
+    };
+  });
+}
+
+function formatHealth(config: LemonadeConfig, health: LemonadeHealth | null): string[] {
+  if (!health) {
+    return [
+      `Unreachable: ${url(config, config.healthPath)}`,
+      "",
+      "Check that the lemonade server is running, then verify the baseUrl",
+      "under Server settings (or run Discover servers).",
+    ];
+  }
+  const lines = [
+    `Status:   ${health.status ?? "?"}   Version: ${health.version ?? "?"}`,
+    `Endpoint: ${config.baseUrl}   WebSocket port: ${health.websocket_port ?? "?"}`,
+    "",
+    `Loaded models (${health.all_models_loaded?.length ?? 0}):`,
+  ];
+  for (const m of health.all_models_loaded ?? []) {
+    lines.push(
+      `  • ${m.model_name} — ${m.type}, ${m.status}, ${m.device ?? "?"}${m.pinned ? ", pinned" : ""}` +
+        `, ctx ${m.max_context_window ?? "?"}`
+    );
+  }
+  if (!health.all_models_loaded?.length) lines.push("  (none)");
+  const slots = Object.entries(health.max_models ?? {})
+    .map(([k, v]) => `${k}:${v}`)
+    .join("  ");
+  if (slots) lines.push("", `Slots: ${slots}`);
+  return lines;
+}
+
+function formatStatus(
+  config: LemonadeConfig,
+  health: LemonadeHealth | null,
+  sys: SystemStats | null,
+  perf: PerfStats | null
+): string[] {
+  const lines = formatHealth(config, health);
+  if (sys) {
+    const pct = (v?: number | null) => (typeof v === "number" ? `${v.toFixed(0)}%` : "?");
+    const gb = (v?: number | null) => (typeof v === "number" ? `${v.toFixed(1)} GB` : "?");
+    lines.push(
+      "",
+      `Host: CPU ${pct(sys.cpu_percent)}  RAM ${gb(sys.memory_gb)}  GPU ${pct(sys.gpu_percent)}  VRAM ${gb(sys.vram_gb)}` +
+        (sys.npu_percent !== undefined && sys.npu_percent !== null ? `  NPU ${pct(sys.npu_percent)}` : "")
+    );
+  }
+  if (perf && typeof perf.tokens_per_second === "number") {
+    lines.push(
+      "",
+      `Last request: ${perf.tokens_per_second.toFixed(1)} tok/s, TTFT ${
+        typeof perf.time_to_first_token === "number" ? perf.time_to_first_token.toFixed(2) : "?"
+      }s` +
+        ` (in ${perf.input_tokens ?? "?"} / out ${perf.output_tokens ?? "?"} tokens)` +
+        (typeof perf.request_count_total === "number" ? `  lifetime requests: ${perf.request_count_total}` : "")
+    );
+  }
+  return lines;
+}
+
+/** Run an async op with a status indicator; returns [ok, result]. */
+async function withStatus<T>(
+  ctx: UiCtx,
+  label: string,
+  op: () => Promise<T>
+): Promise<[boolean, T | string]> {
+  ctx.ui.setStatus("lemonade-setup", label);
+  try {
+    return [true, await op()];
+  } catch (error) {
+    return [false, error instanceof Error ? error.message : String(error)];
+  } finally {
+    ctx.ui.setStatus("lemonade-setup", undefined);
+  }
+}
+
+/**
+ * Pull a model with live progress: server-owned download job + progress view.
+ * Falls back to a blocking pull on servers without job support.
+ */
+async function pullWithProgress(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  id: string,
+  extra?: Record<string, unknown>
+): Promise<[boolean, string]> {
+  let job: DownloadJob | null = null;
+  try {
+    job = await startPullJob(config, id, extra);
+  } catch {
+    // Fallback: blocking pull (older server without download jobs)
+    return withStatus(ctx, `Pulling ${id} (blocking)…`, () => pullModelBlocking(config, id));
+  }
+  const outcome = await trackDownload(ctx, config, job.id, id);
+  if (outcome === "complete") {
+    await registerLemonadeProvider(pi, config); // model now in catalog
+    return [true, `Pulled ${id}.`];
+  }
+  if (outcome === "cancelled") {
+    return [false, `Pull of ${id} cancelled.`];
+  }
+  return [false, `Pull of ${id} failed.`];
+}
+
+/** Search Hugging Face via the lemonade server and install a model as user.* */
+async function installFromHuggingFace(ctx: UiCtx, pi: ExtensionAPI, config: LemonadeConfig): Promise<void> {
+  const query = (await ctx.ui.input("Search Hugging Face (GGUF repos):", ""))?.trim();
+  if (!query || query.length < 3) {
+    if (query) ctx.ui.notify("Search query must be at least 3 characters.", "warning");
+    return;
+  }
+
+  ctx.ui.setStatus("lemonade-setup", `Searching Hugging Face for "${query}"…`);
+  const res = await fetch(
+    url(config, `${config.registrySearchPath}?query=${encodeURIComponent(query)}&format=gguf&limit=12`),
+    { headers: authHeaders(config), signal: AbortSignal.timeout(config.discoveryTimeoutMs * 3) }
+  );
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  if (!res.ok) {
+    ctx.ui.notify(`Registry search failed (HTTP ${res.status}).`, "error");
+    return;
+  }
+  const payload = (await res.json()) as { results?: RegistryResult[] };
+  const results = payload.results ?? [];
+  if (!results.length) {
+    ctx.ui.notify("No matching repositories found.", "warning");
+    return;
+  }
+
+  const repo = await menu(
+    ctx,
+    "Search Results",
+    results.map((r) => ({
+      value: r.repository_id,
+      label: r.repository_id,
+      description: [
+        r.downloads !== undefined ? `${(r.downloads / 1000).toFixed(0)}k downloads` : undefined,
+        r.likes !== undefined ? `${r.likes} likes` : undefined,
+        (r.tags ?? []).slice(0, 3).join(", "),
+      ].filter(Boolean).join(" • "),
+    })) as SelectItem<string>[]
+  );
+  if (!repo) return;
+
+  ctx.ui.setStatus("lemonade-setup", `Inspecting ${repo}…`);
+  const varRes = await fetch(
+    url(config, `${config.pullVariantsPath}?checkpoint=${encodeURIComponent(repo)}`),
+    { headers: authHeaders(config), signal: AbortSignal.timeout(config.discoveryTimeoutMs * 4) }
+  );
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  if (!varRes.ok) {
+    ctx.ui.notify(`Could not inspect variants (HTTP ${varRes.status}).`, "error");
+    return;
+  }
+  const variants = (await varRes.json()) as PullVariants;
+  if (!variants.variants?.length) {
+    ctx.ui.notify("No installable variants found for this repository.", "warning");
+    return;
+  }
+
+  const variant = await menu(
+    ctx,
+    `Variants of ${repo}`,
+    variants.variants.map((v) => ({
+      value: v.name,
+      label: v.name,
+      description: `${formatBytes(v.size_bytes)}${v.sharded ? " • sharded" : ""}`,
+    })) as SelectItem<string>[]
+  );
+  if (!variant) return;
+  const chosen = variants.variants.find((v) => v.name === variant)!;
+
+  const modelName = `user.${variants.suggested_name ?? repo.split("/")[1]}`;
+  const vision = (variants.suggested_labels ?? []).includes("vision");
+  const ok = await ctx.ui.confirm(
+    `Install as ${modelName}?`,
+    `${repo}:${chosen.primary_file} (${formatBytes(chosen.size_bytes)})` +
+      (vision ? " • vision model (mmproj included)" : "")
+  );
+  if (!ok) return;
+
+  const extra: Record<string, unknown> = {
+    checkpoint: `${repo}:${chosen.primary_file}`,
+    recipe: variants.recipe ?? "llamacpp",
+  };
+  if (vision && variants.mmproj_files?.[0]) {
+    extra.mmproj = variants.mmproj_files[0];
+    extra.vision = true;
+  }
+
+  const [succeeded, msg] = await pullWithProgress(ctx, pi, config, modelName, extra);
+  ctx.ui.notify(msg, succeeded ? "info" : "error");
+}
+
+
+/** Interactive flow to register a new lemonade instance. Returns its name on
+ *  success, undefined otherwise. Validates the name, verifies reachability,
+ *  persists to config.servers, and registers the new provider immediately. */
+async function addInstanceFlow(
+  ctx: UiCtx,
+  pi: ExtensionAPI,
+  config: LemonadeConfig,
+  presetUrl?: string
+): Promise<string | undefined> {
+  const nameInput = (await ctx.ui.input("Instance name (lowercase letters, numbers, hyphens):", ""))?.trim();
+  if (!nameInput) return undefined;
+  if (
+    nameInput === "default" ||
+    config.servers.some((s) => s.name === nameInput) ||
+    !/^[a-z0-9][a-z0-9-]*$/.test(nameInput)
+  ) {
+    ctx.ui.notify(
+      'Invalid name — use lowercase letters/numbers/hyphens; "default" and existing instance names are reserved.',
+      "warning"
+    );
+    return undefined;
+  }
+  const urlInput = presetUrl ?? (await ctx.ui.input("Lemonade base URL:", "http://"))?.trim();
+  const base = normalizeBaseUrl(urlInput ?? "");
+  if (!/^https?:\/\/.+/.test(base)) {
+    ctx.ui.notify("Invalid URL.", "warning");
+    return undefined;
+  }
+  const description = (await ctx.ui.input("Description (optional, your own reminder):", ""))?.trim() ?? "";
+  const view: InstanceView = {
+    name: nameInput,
+    description,
+    isDefault: false,
+    config: { ...config, baseUrl: base },
+  };
+  ctx.ui.setStatus("lemonade-setup", `Verifying ${base}…`);
+  const health = await fetchHealth(view.config);
+  ctx.ui.setStatus("lemonade-setup", undefined);
+  if (!health) {
+    const ok = await ctx.ui.confirm(
+      "Server unreachable — add anyway?",
+      `${base} did not respond to a health check. The provider will register with an empty model list until it is reachable.`
+    );
+    if (!ok) return undefined;
+  }
+  config.servers.push({ name: nameInput, baseUrl: base, description: description || undefined });
+  saveConfig(config);
+  const [, msg] = await withStatus(ctx, "Registering providers…", () =>
+    registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered across all instances.`)
+  );
+  void msg;
+  return nameInput;
+}
+
+function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeConfig }): void {
+  pi.registerCommand("lemonade-setup", {
+    description: "Lemonade server: status, discovery, endpoints, models, tools, transcription",
+    handler: async (_args, ctx) => {
+      let activeInstance = configRef.current.servers[0].name; // servers[0] IS the default
+      for (;;) {
+        const config = configRef.current;
+        // Config view of the active instance — status/models/logs act on it.
+        const viewOrErr = instanceView(config, activeInstance);
+        if (typeof viewOrErr === "string") {
+          activeInstance = configRef.current.servers[0].name; // instance was removed/renamed mid-session
+          continue;
+        }
+        const iconfig = viewOrErr;
+        const choice = await menu(ctx, "🍋 Lemonade Setup", [
+          { value: "status", label: "Server status", description: `Live health + host + perf from ${iconfig.baseUrl}` },
+          { value: "server", label: "Server settings", description: "Discover, base URL, API key, instances, connection test" },
+          { value: "models", label: "Model management", description: `List, load, unload, pull (progress+cancel), delete, change-ctx, HF install, filter, refresh — active instance: ${activeInstance}` },
+          { value: "transcription", label: "Transcription settings", description: "Whisper model, paths, smoke test" },
+          { value: "logs", label: "Live server logs", description: "Stream the server's log over websocket" },
+          { value: "instance", label: "Switch instance", description: `Current: ${activeInstance} — pick which box status/models/logs act on` },
+          { value: "exit", label: "Exit", description: "Close the setup menu" },
+        ] as SelectItem<string>[]);
+        if (choice === null || choice === "exit") break;
+
+        // ── Switch instance ─────────────────────────────────────────────
+        if (choice === "instance") {
+          const picked = await menu(
+            ctx,
+            "Active Instance",
+            listInstances(config).map((v) => ({
+              value: v.name,
+              label: `${v.name}${v.isDefault ? " (default)" : ""}`,
+              description: [v.config.baseUrl, v.description].filter(Boolean).join(" — "),
+            })) as SelectItem<string>[]
+          );
+          if (picked) activeInstance = picked;
+          continue;
+        }
+
+        // ── Live logs ────────────────────────────────────────────────
+        if (choice === "logs") {
+          await liveLogsView(ctx, iconfig);
+          continue;
+        }
+
+        // ── Status ────────────────────────────────────────────────────────
+        if (choice === "status") {
+          ctx.ui.setStatus("lemonade-setup", "Contacting server…");
+          const [h, sys, perf] = await Promise.all([
+            fetchHealth(iconfig),
+            fetchJsonOrNull<SystemStats>(iconfig, "/v1/system-stats"),
+            fetchJsonOrNull<PerfStats>(iconfig, "/v1/stats"),
+          ]);
+          ctx.ui.setStatus("lemonade-setup", undefined);
+          await textView(
+            ctx,
+            `Server Status — ${activeInstance}`,
+            formatStatus(iconfig, h, sys, perf)
+          );
+          continue;
+        }
+
+        // ── Server settings ──────────────────────────────────────────────
+        if (choice === "server") {
+          for (;;) {
+            const sub = await menu(ctx, "Server Settings", [
+              { value: "discover", label: "Discover servers", description: "UDP beacon scan + HTTP fallback" },
+              { value: "instances", label: "Manage instances", description: `${config.servers.length} instance(s) — servers[0] is the default` },
+              { value: "baseurl", label: "Edit default instance base URL", description: `Current: ${config.servers[0].baseUrl}` },
+              { value: "apikey", label: "Edit shared API key", description: `Fallback for instances without their own — ${config.apiKey ? "••••• (set)" : "(none)"}` },
+              { value: "test", label: "Test connection", description: "Ping the health endpoint" },
+              { value: "back", label: "Back", description: "" },
+            ] as SelectItem<string>[]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "discover") {
+              ctx.ui.setStatus("lemonade-setup", `Scanning UDP beacons (${config.beaconTimeoutMs / 1000}s)…`);
+              let servers = await discoverViaBeacon(config, config.beaconTimeoutMs);
+              ctx.ui.setStatus("lemonade-setup", undefined);
+              if (!servers.length) {
+                ctx.ui.setStatus("lemonade-setup", "No beacons — probing known hosts/ports…");
+                servers = await discoverViaHttp(config);
+                ctx.ui.setStatus("lemonade-setup", undefined);
+              }
+              if (!servers.length) {
+                ctx.ui.notify(
+                  "No lemonade servers found. Note: UDP LAN broadcasts don't reach into WSL2 — " +
+                    "set the URL manually, or run discovery on the Windows side.",
+                  "warning"
+                );
+                continue;
+              }
+              const picked = await menu(
+                ctx,
+                "Discovered Servers",
+                servers.map((s) => ({
+                  value: s.baseUrl,
+                  label: `${s.hostname} — ${s.baseUrl}`,
+                })) as SelectItem<string>[]
+              );
+              if (picked) {
+                if (picked === config.servers[0].baseUrl) {
+                  ctx.ui.notify("That is already the default instance.", "info");
+                  continue;
+                }
+                const use = await menu(
+                  ctx,
+                  `Use ${picked}`,
+                  [
+                    { value: "default", label: "Set as default instance", description: "Replaces the current default" },
+                    { value: "instance", label: "Add as named instance", description: "Keeps the default; registers as lemonade-<name>" },
+                    { value: "back", label: "Cancel", description: "" },
+                  ] as SelectItem<string>[]
+                );
+                if (use === "default") {
+                  config.servers[0].baseUrl = picked;
+                  saveConfig(config);
+                  const [ok, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                    registerLemonadeProvider(pi, config).then((n) => `Connected — ${n} model(s) registered.`)
+                  );
+                  ctx.ui.notify(msg, ok ? "info" : "error");
+                } else if (use === "instance") {
+                  const added = await addInstanceFlow(ctx, pi, config, picked);
+                  if (added) ctx.ui.notify(`Instance "${added}" added — provider lemonade-${added} registered.`, "info");
+                }
+              }
+            } else if (sub === "instances") {
+              for (;;) {
+                const op = await menu(ctx, "Manage Instances", [
+                  { value: "list", label: "List instances", description: "Names, URLs, descriptions, live reachability" },
+                  { value: "edit", label: "Edit instance", description: "Rename, re-describe, re-point, or re-key an instance" },
+                  { value: "add", label: "Add instance", description: "Register another lemonade box as lemonade-<name>" },
+                  ...(config.servers.length > 1
+                    ? [
+                        { value: "makedefault", label: "Make default", description: "Move an instance to the front — servers[0] is the default" } as SelectItem<string>,
+                        { value: "remove", label: "Remove instance", description: "Unregister an instance (the last one cannot be removed)" } as SelectItem<string>,
+                      ]
+                    : []),
+                  { value: "back", label: "Back", description: "" },
+                ] as SelectItem<string>[]);
+                if (op === null || op === "back") break;
+
+                if (op === "list") {
+                  const lines: string[] = [];
+                  for (const v of listInstances(config)) {
+                    const h = await fetchHealth(v.config);
+                    lines.push(
+                      `${v.name}${v.isDefault ? " (default)" : ""} — ${v.config.baseUrl} — ` +
+                        (h ? `ok (v${h.version ?? "?"}, ${h.all_models_loaded?.length ?? 0} loaded)` : "unreachable")
+                    );
+                    if (v.description) lines.push(`    ${v.description}`);
+                  }
+                  await textView(ctx, "Instances", lines);
+                } else if (op === "edit") {
+                  const views = listInstances(config);
+                  const target = await menu(
+                    ctx,
+                    "Edit Instance",
+                    views.map((v) => ({
+                      value: v.name,
+                      label: `${v.name}${v.isDefault ? " (default)" : ""}`,
+                      description: [v.config.baseUrl, v.description].filter(Boolean).join(" — "),
+                    })) as SelectItem<string>[]
+                  );
+                  if (!target) continue;
+                  const view = views.find((v) => v.name === target)!;
+                  const entry = config.servers.find((x) => x.name === target)!;
+
+                  for (;;) {
+                    const field = await menu(ctx, `Edit ${target}`, [
+                      { value: "description", label: "Edit description", description: view.description ? `Current: ${view.description.slice(0, 60)}` : "(none set)" },
+                      { value: "name", label: "Edit name", description: `Current: ${view.name}` },
+                      { value: "url", label: "Edit base URL", description: `Current: ${entry.baseUrl}` },
+                      { value: "apikey", label: "Edit API key", description: entry.apiKey ? "Current: ••••• (own key)" : "Current: (inherits the shared key)" },
+                      { value: "back", label: "Back", description: "" },
+                    ] as SelectItem<string>[]);
+                    if (field === null || field === "back") break;
+
+                    if (field === "description") {
+                      const input = await ctx.ui.input(
+                        "Description (your own reminder's sake, shown in this menu):",
+                        view.description
+                      );
+                      if (input !== undefined) {
+                        entry.description = input.trim() || undefined;
+                        saveConfig(config);
+                        ctx.ui.notify("Description saved.", "info");
+                      }
+                    } else if (field === "name") {
+                      const input = (await ctx.ui.input("New name (lowercase letters, numbers, hyphens):", view.name))?.trim();
+                      if (!input || input === view.name) continue;
+                      const others = [
+                        "default",
+                        ...config.servers.filter((x) => x.name !== target).map((x) => x.name),
+                      ];
+                      if (others.includes(input) || !/^[a-z0-9][a-z0-9-]*$/.test(input)) {
+                        ctx.ui.notify("Invalid or duplicate name.", "warning");
+                        continue;
+                      }
+                      // Uniform ids: renaming changes the provider id too —
+                      // unregister the old one before re-registering.
+                      try {
+                        pi.unregisterProvider(`lemonade-${target}`);
+                      } catch { /* not registered */ }
+                      entry.name = input;
+                      if (activeInstance === target) activeInstance = input;
+                      saveConfig(config);
+                      const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                        registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                      );
+                      void msg;
+                      ctx.ui.notify(`Renamed to "${input}".`, "info");
+                      break; // menu keys changed; leave the edit loop
+                    } else if (field === "url") {
+                      const input = (await ctx.ui.input("New base URL:", entry.baseUrl))?.trim();
+                      const base = normalizeBaseUrl(input ?? "");
+                      if (!/^https?:\/\//.test(base)) {
+                        ctx.ui.notify("Invalid URL.", "warning");
+                        continue;
+                      }
+                      entry.baseUrl = base;
+                      saveConfig(config);
+                      const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                        registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                      );
+                      void msg;
+                      ctx.ui.notify("URL saved.", "info");
+                    } else if (field === "apikey") {
+                      const input = (await ctx.ui.input("Instance API key (empty = inherit the shared key):", entry.apiKey ?? ""))?.trim();
+                      if (input !== undefined) {
+                        entry.apiKey = input || undefined;
+                        saveConfig(config);
+                        const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                          registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                        );
+                        void msg;
+                        ctx.ui.notify(input ? "API key saved." : "API key cleared — instance inherits the shared key.", "info");
+                      }
+                    }
+                  }
+                } else if (op === "add") {
+                  const added = await addInstanceFlow(ctx, pi, config);
+                  if (added) ctx.ui.notify(`Instance "${added}" added — provider lemonade-${added} registered.`, "info");
+                } else if (op === "remove") {
+                  const victim = await menu(
+                    ctx,
+                    "Remove Instance",
+                    config.servers.map((s) => ({
+                      value: s.name,
+                      label: `${s.name}${s.name === config.servers[0].name ? " (default)" : ""}`,
+                      description: s.baseUrl,
+                    })) as SelectItem<string>[]
+                  );
+                  if (!victim) continue;
+                  const wasDefault = victim === config.servers[0].name;
+                  const ok = await ctx.ui.confirm(
+                    `Remove instance ${victim}?`,
+                    `Unregisters the lemonade-${victim} provider. Files on that box are untouched.` +
+                      (wasDefault ? " It is the DEFAULT — the next instance in the list becomes the default." : "")
+                  );
+                  if (!ok) continue;
+                  config.servers = config.servers.filter((x) => x.name !== victim);
+                  saveConfig(config);
+                  if (activeInstance === victim) activeInstance = config.servers[0].name;
+                  try {
+                    pi.unregisterProvider(`lemonade-${victim}`);
+                  } catch { /* not registered */ }
+                  const [rok, rmsg] = await withStatus(ctx, "Re-registering providers…", () =>
+                    registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+                  );
+                  ctx.ui.notify(rmsg, rok ? "info" : "error");
+                } else if (op === "makedefault") {
+                  const pick = await menu(
+                    ctx,
+                    "Make Default",
+                    config.servers.slice(1).map((s) => ({
+                      value: s.name,
+                      label: s.name,
+                      description: [s.baseUrl, s.description].filter(Boolean).join(" — "),
+                    })) as SelectItem<string>[]
+                  );
+                  if (!pick) continue;
+                  const idx = config.servers.findIndex((x) => x.name === pick);
+                  const [entry] = config.servers.splice(idx, 1);
+                  config.servers.unshift(entry);
+                  saveConfig(config);
+                  // Provider ids are lemonade-<name>, unchanged by reordering —
+                  // no re-registration needed; only defaultness moved.
+                  ctx.ui.notify(`"${pick}" is now the default instance (servers[0]).`, "info");
+                }
+              }
+            } else if (sub === "baseurl") {
+              const input = await ctx.ui.input("Default instance base URL:", config.servers[0].baseUrl);
+              if (input !== undefined && input.trim()) {
+                config.servers[0].baseUrl = normalizeBaseUrl(input);
+                saveConfig(config);
+                const [ok, msg] = await withStatus(ctx, "Re-registering provider…", () =>
+                  registerLemonadeProvider(pi, config).then((n) => `Saved — ${n} model(s) registered.`)
+                );
+                ctx.ui.notify(msg, ok ? "info" : "error");
+              }
+            } else if (sub === "apikey") {
+              const input = await ctx.ui.input("Shared API key (instances without their own inherit it; empty for none):", config.apiKey);
+              if (input !== undefined) {
+                config.apiKey = input.trim();
+                saveConfig(config);
+                ctx.ui.notify("API key saved.", "info");
+              }
+            } else if (sub === "test") {
+              const h = await fetchHealth(iconfig);
+              ctx.ui.notify(
+                h
+                  ? `OK — ${h.status ?? "?"} v${h.version ?? "?"}, ${h.all_models_loaded?.length ?? 0} model(s) loaded`
+                  : `Failed to reach ${iconfig.baseUrl}`,
+                h ? "info" : "error"
+              );
+            }
+          }
+          continue;
+        }
+
+        // ── Model management ──────────────────────────────────────────────
+        if (choice === "models") {
+          for (;;) {
+            const sub = await menu(ctx, "Model Management", [
+              { value: "list", label: "List catalog", description: "All advertised models + live state" },
+              { value: "load", label: "Load a model", description: "Load into memory (may take minutes)" },
+              { value: "unload", label: "Unload a model", description: "Free its slot" },
+              { value: "pull", label: "Pull (download) a model", description: "Live progress, esc to cancel" },
+              { value: "installhf", label: "Install from Hugging Face", description: "Search HF, pick a variant, install as user.*" },
+              { value: "delete", label: "Delete a model", description: "Typed-phrase confirmation required" },
+              { value: "changectx", label: "Change context size", description: "Unload → reload with new ctx (saved)" },
+              {
+                value: "chatonly",
+                label: "Toggle chat-only filter",
+                description: `Currently: ${config.chatOnly ? "chat models only" : "all models"}`,
+              },
+              { value: "refresh", label: "Refresh provider", description: "Re-discover and re-register in /model" },
+              { value: "back", label: "Back", description: "" },
+            ] as SelectItem<string>[]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "installhf") {
+              await installFromHuggingFace(ctx, pi, iconfig);
+              continue;
+            }
+
+            if (sub === "chatonly") {
+              config.chatOnly = !config.chatOnly;
+              saveConfig(config);
+              const [ok, msg] = await withStatus(ctx, "Re-registering…", () =>
+                registerLemonadeProvider(pi, config).then((n) => `Filter ${config.chatOnly ? "on" : "off"} — ${n} model(s) registered.`)
+              );
+              ctx.ui.notify(msg, ok ? "info" : "error");
+              continue;
+            }
+            if (sub === "refresh") {
+              const [ok, msg] = await withStatus(ctx, "Refreshing…", () =>
+                registerLemonadeProvider(pi, config).then((n) => `Provider refreshed — ${n} model(s) registered.`)
+              );
+              ctx.ui.notify(msg, ok ? "info" : "error");
+              continue;
+            }
+
+            // Everything else needs the live catalog. show_all=true includes
+            // not-yet-downloaded registry entries (pull candidates).
+            let catalog: LemonadeModel[];
+            let loadedIds = new Set<string>();
+            let loadedCtx = new Map<string, number>();
+            try {
+              const health = await fetchHealth(iconfig);
+              loadedIds = new Set((health?.all_models_loaded ?? []).map((m) => m.model_name));
+              for (const m of health?.all_models_loaded ?? []) {
+                if (m.max_context_window) loadedCtx.set(m.model_name, m.max_context_window);
+              }
+              catalog = await fetchCatalog(iconfig, true);
+            } catch (error) {
+              ctx.ui.notify(`Could not reach server: ${error instanceof Error ? error.message : error}`, "error");
+              continue;
+            }
+
+            if (sub === "list") {
+              const lines: string[] = [`Catalog: ${catalog.length} model(s), ${loadedIds.size} loaded`, ""];
+              for (const m of catalog) {
+                const state = loadedIds.has(m.id) ? "● loaded" : "○ on-demand";
+                lines.push(
+                  `${state}  ${m.id}` +
+                    (m.labels?.length ? `  [${m.labels.join(", ")}]` : "") +
+                    (m.downloaded === false ? "  (not downloaded)" : "") +
+                    (m.max_context_window ? `  ctx ${m.max_context_window}` : "") +
+                    (m.size ? `  ${m.size} GB` : "")
+                );
+              }
+              await textView(ctx, "Model Catalog", lines);
+              continue;
+            }
+
+            if (sub === "changectx") {
+              if (!loadedIds.size) {
+                ctx.ui.notify("Nothing is loaded — load a model first.", "warning");
+                continue;
+              }
+              const picked = await menu(ctx, "Change Context Size (pick model)", [...loadedIds].map((id) => ({
+                value: id,
+                label: id,
+              })) as SelectItem<string>[]);
+              if (!picked) continue;
+              const currentCtx =
+                loadedCtx.get(picked) ??
+                catalog.find((m) => m.id === picked)?.max_context_window ??
+                32768;
+              const input = await ctx.ui.input(
+                `New context size (current: ${currentCtx}; e.g. 32k, 1m, or raw tokens):`,
+                String(currentCtx)
+              );
+              const ctxSize = input ? parseCtxSize(input) : null;
+              if (!ctxSize) {
+                ctx.ui.notify("Invalid size — use e.g. 32k, 1m, or 262144.", "warning");
+                continue;
+              }
+              const ok = await ctx.ui.confirm(
+                "Unload and reload?",
+                `${picked} will be unloaded and reloaded with ctx ${ctxSize} (saved for future loads).`
+              );
+              if (!ok) continue;
+              const [succeeded, msg] = await withStatus(ctx, `Reloading ${picked} with ctx ${ctxSize}…`, () =>
+                changeModelContext(iconfig, picked, ctxSize)
+              );
+              ctx.ui.notify(msg, succeeded ? "info" : "error");
+              if (succeeded) await registerLemonadeProvider(pi, config);
+              continue;
+            }
+
+            if (sub === "pull" || sub === "delete") {
+              const predicate = sub === "delete"
+                ? (m: LemonadeModel) => m.downloaded !== false
+                : (m: LemonadeModel) => m.downloaded === false;
+              let candidates = catalog.filter(predicate);
+              if (sub === "delete" && candidates.some((m) => !m.downloaded)) {
+                candidates = candidates.filter((m) => m.downloaded === true || m.downloaded === undefined);
+              }
+
+              let picked: string | null = null;
+              if (candidates.length) {
+                picked = await menu(
+                  ctx,
+                  sub === "pull" ? "Pull (download)" : "Delete from disk",
+                  candidates.map((m) => ({
+                    value: m.id,
+                    label: m.id,
+                    description: [
+                      loadedIds.has(m.id) ? "loaded" : undefined,
+                      m.size ? `${m.size} GB` : undefined,
+                      m.recipe,
+                    ].filter(Boolean).join(" • "),
+                  })) as SelectItem<string>[]
+                );
+              } else {
+                const input = await ctx.ui.input(
+                  sub === "pull"
+                    ? "No undownloaded models in catalog. Enter a model id to pull:"
+                    : "Enter a model id to delete:",
+                  ""
+                );
+                picked = input?.trim() || null;
+              }
+              if (!picked) continue;
+
+              if (sub === "pull") {
+                const size = catalog.find((m) => m.id === picked)?.size;
+                const ok = await ctx.ui.confirm(
+                  `Pull ${picked}?`,
+                  size ? `Downloads ~${size} GB to the server's disk.` : "Downloads the model to the server's disk."
+                );
+                if (!ok) continue;
+                const [succeeded, msg] = await pullWithProgress(ctx, pi, iconfig, picked!);
+                ctx.ui.notify(msg, succeeded ? "info" : "error");
+                continue;
+              }
+
+              // delete: confirm + typed phrase, 3 attempts
+              const ok = await ctx.ui.confirm(
+                `Delete ${picked}?`,
+                "This permanently removes the model files from the server's disk. Load state and cache are also lost."
+              );
+              if (!ok) continue;
+              const phrase = `i want to delete ${picked.toLowerCase()}`;
+              let confirmed = false;
+              for (let attempt = 1; attempt <= 3 && !confirmed; attempt++) {
+                const chancesLeft = 4 - attempt;
+                const typed = await ctx.ui.input(
+                  `Type "${phrase}" (${chancesLeft} chance${chancesLeft === 1 ? "" : "s"} left):`,
+                  ""
+                );
+                if (typed === undefined) break; // Esc = abort immediately
+                if (typed.trim().toLowerCase().replace(/\s+/g, " ") === phrase) {
+                  confirmed = true;
+                } else if (attempt < 3) {
+                  ctx.ui.notify("Phrase did not match.", "warning");
+                }
+              }
+              if (!confirmed) {
+                ctx.ui.notify(`Deletion of ${picked} aborted.`, "warning");
+                continue;
+              }
+              const [succeeded, msg] = await withStatus(ctx, `Deleting ${picked}…`, () =>
+                deleteModel(iconfig, picked!)
+              );
+              ctx.ui.notify(msg, succeeded ? "info" : "error");
+              if (succeeded) await registerLemonadeProvider(pi, config);
+              continue;
+            }
+
+            // load / unload
+            {
+              const candidates =
+                sub === "unload"
+                  ? [...loadedIds]
+                  : catalog.map((m) => m.id).filter((id) => !loadedIds.has(id));
+              if (!candidates.length) {
+                ctx.ui.notify(sub === "unload" ? "Nothing is loaded." : "Everything is already loaded.", "warning");
+                continue;
+              }
+              const picked = await menu(
+                ctx,
+                sub === "load" ? "Load model" : "Unload model",
+                candidates.map((id) => ({
+                  value: id,
+                  label: id,
+                  description: loadedIds.has(id) ? "loaded" : "on-demand",
+                })) as SelectItem<string>[]
+              );
+              if (!picked) continue;
+              const [succeeded, msg] = await withStatus(ctx, `${sub === "load" ? "Loading" : "Unloading"} ${picked}…`, () =>
+                sub === "load" ? loadModel(iconfig, picked) : unloadModel(iconfig, picked).then(() => `Unloaded ${picked}.`)
+              );
+              ctx.ui.notify(msg, succeeded ? "info" : "error");
+              if (succeeded) await registerLemonadeProvider(pi, config);
+            }
+          }
+          continue;
+        }
+
+        // ── Transcription settings ────────────────────────────────────────
+        if (choice === "transcription") {
+          for (;;) {
+            const sub = await menu(ctx, "Transcription Settings", [
+              {
+                value: "model",
+                label: "Default transcription model",
+                description: `Current: ${config.defaultTranscriptionModel}`,
+              },
+              {
+                value: "transpath",
+                label: "Transcription endpoint path",
+                description: `Current: ${config.transcriptionPath}`,
+              },
+              { value: "test", label: "Smoke test", description: "Transcribe a file of your choosing" },
+              { value: "back", label: "Back", description: "" },
+            ] as SelectItem<string>[]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "model" || sub === "transpath") {
+              const input = await ctx.ui.input(
+                sub === "model" ? "Transcription model id:" : "Transcription endpoint path:",
+                sub === "model" ? config.defaultTranscriptionModel : config.transcriptionPath
+              );
+              if (input !== undefined && input.trim()) {
+                if (sub === "model") config.defaultTranscriptionModel = input.trim();
+                else config.transcriptionPath = input.trim();
+                saveConfig(config);
+                ctx.ui.notify("Saved.", "info");
+              }
+            } else if (sub === "test") {
+              const file = await ctx.ui.input("Path to an audio/video file:", "");
+              if (!file?.trim()) continue;
+              const resolved = path.resolve(file.trim());
+              const tool = pi.getAllTools().find((t) => t.name === "transcribe_audio");
+              if (!tool) {
+                ctx.ui.notify("transcribe_audio tool not registered.", "error");
+                continue;
+              }
+              const [succeeded, result] = await withStatus(ctx, `Transcribing ${path.basename(resolved)}…`, () =>
+                tool!.execute(`setup-${Date.now()}`, { file_path: resolved }, new AbortController().signal, () => {}, ctx as never) as Promise<{ content?: Array<{ type?: string; text?: string }> }>
+              );
+              if (typeof result === "string") {
+                ctx.ui.notify(result, "error");
+              } else {
+                const text =
+                  result?.content?.find((c) => (c as { type?: string }).type === "text")?.text ?? "(empty)";
+                await textView(ctx, "Transcription Result", [`File: ${resolved}`, "", text]);
+              }
+            }
+          }
+        }
+      }
+    },
+  });
+}
+
+// ─── Extension entry ────────────────────────────────────────────────────────
+
+export default async function localLemonade(pi: ExtensionAPI): Promise<void> {
+  // The config file is REQUIRED — nothing is hardcoded, not even a default
+  // server, because a config-less run would silently target a server that
+  // isn't yours. On failure we do two things, belt and braces: register a
+  // session_start handler that shows a red error banner in the chat window,
+  // and throw so pi logs the extension load failure. (The throw is in case
+  // pi drops handlers registered by an extension that fails during load;
+  // if it keeps them, the user sees the reason twice — loudly, both times.)
+  let config: LemonadeConfig;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    const failure = [
+      "local-lemonade did NOT load — no lemonade providers, tools, or /lemonade-setup are registered.",
+      "",
+      `Reason: ${reason}`,
+      "",
+      `Everything (base URL, endpoints, defaults) is config-driven from ${CONFIG_PATH} — nothing is hardcoded.`,
+      "To set it up, copy the fully-commented example into your pi agent dir and edit it for your server:",
+      "",
+      "  cp ~/.pi/agent/extensions/local-lemonade/lemonade.example.json ~/.pi/agent/lemonade.json",
+      "",
+      'A minimal config is enough to start:  { "servers": [{ "name": "main", "baseUrl": "http://your-lemonade-server:13305" }] }',
+    ].join("\n");
+    pi.on("session_start", async (_event, ctx) => {
+      if (ctx.hasUI) ctx.ui.notify(failure, "error");
+    });
+    throw new Error(failure);
+  }
+  const configRef = { current: config };
+  // No startup save: the config file is user-authored and may carry JSONC
+  // comments, and rewriting it here would strip them. Missing keys are
+  // merged from DEFAULT_CONFIG in memory; /lemonade-setup persists the full
+  // normalized object when the user actually changes something.
+
+  await registerLemonadeProvider(pi, configRef.current);
+  await registerAgentTools(pi, configRef.current);
+  registerSetupCommand(pi, configRef);
+}