amicus 4.1.1 → 4.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-07-23
+
+### Added
+
+- **Local / OpenAI-compatible providers, at $0.** `amicus provider add <id> --preset
+  ollama|lmstudio|vllm` (or `--url <baseURL>` for any other OpenAI-compatible endpoint)
+  configures Ollama, LM Studio, vLLM, or a self-hosted server as a first-class model source —
+  `provider list|test|remove` manage them (all support `--json`). Local models price at a real,
+  explicit `$0` tier (not "unpriced"), so the budget gate, `amicus spend`, and the default-model
+  picker all treat them as free. `amicus key <localId> <token>` manages a local provider's bearer
+  (stored in the `0600` `.env`, never in `config.json`); `amicus doctor` gains a
+  `local-providers` reachability check (warn, never error); the setup wizard (readline and
+  Electron) offers to add one.
+- **Local inference completes instead of hanging forever.** Local (`@ai-sdk/openai-compatible`)
+  provider blocks now carry a 5-minute engine request `timeout` and a non-empty `apiKey`
+  (`{env:VAR}` for a configured bearer, the literal `not-needed` otherwise), so `amicus
+  start`/`fanout`/`council` against Ollama/LM Studio/vLLM now complete. Local models need enough
+  context loaded to fit the ~26k-token agent prompt (**~32k** is a safe target — LM Studio's
+  ~16k default is not) and are slower than cloud to first token (30–90s prefill on a cold model
+  is normal) — see [`amicus provider`](docs/usage.md#amicus-provider).
+- **`amicus init [--claude] [--desktop] [--json]`** re-runs the same skill-install + MCP
+  registration that `npm install`'s postinstall runs, on demand — for plugin-channel /
+  `--ignore-scripts` installs (which skip the postinstall), a failed postinstall, or repairing
+  deleted `~/.claude` state.
+
+## [4.1.2] - 2026-07-22
+
+### Fixed
+
+- **Claude model aliases no longer drift between the direct API and OpenRouter.** The two
+  gateways spell the same model differently — OpenRouter serves `anthropic/claude-opus-4.8`,
+  the direct Anthropic API serves `anthropic/claude-opus-4-8` — and three places converted
+  between the two by adding or removing the `openrouter/` prefix. That is only sound when the
+  rest of the id is identical, which for Claude it is not. Two user-visible consequences: a fresh
+  `amicus setup` wrote an `opus` alias that `amicus doctor` then reported as stale (the exact
+  warning 4.1.1 shipped to remove — and it fired even with an Anthropic-only catalog, not just
+  for OpenRouter users), and the pre-registered fallback catalog handed to a long-lived shared
+  server carried two ids OpenRouter does not serve while omitting the two it does. All three
+  sites now read each gateway's authored route instead of deriving one from the other, and an
+  alias you have overridden yourself is left alone rather than inheriting a curated route.
+  Affects `opus` and `haiku`; every other alias is spelled identically on both gateways or is
+  OpenRouter-only. Default routing is direct-first and was never affected — no run selected a
+  wrong model.
+
 ## [4.1.1] - 2026-07-21
 
 ### Fixed

package/README.md

@@ -8,6 +8,8 @@
 
 Hand Claude a plan, a design, a diff, an architecture decision, a manuscript — anything — and say *council review this*: Amicus routes it through several models from different families, has them anonymously cross-review each other, and a non-Claude chair synthesizes a verdict you turn into accept/deny edits. Or skip the ceremony and **fork** a single conversation to Gemini, GPT, DeepSeek, or any other model — it works in parallel with full context, and you **fold** the result back when you're ready. Claude orchestrates throughout; you stay in your editor.
 
+**The same council — more ways to run it:** take it **headless in CI** with no Claude runtime, sharpen it with a **debate round**, or run it on **free local models** (Ollama, LM Studio, vLLM) at **$0** — private and offline.
+
 [![npm version](https://img.shields.io/npm/v/amicus?color=D97757&labelColor=1A1C29)](https://www.npmjs.com/package/amicus)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?labelColor=1A1C29)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?labelColor=1A1C29)](https://nodejs.org)
@@ -22,6 +24,7 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 ## Table of Contents
 
 - [What is Amicus](#what-is-amicus)
+- [Ways to run the council](#ways-to-run-the-council)
 - [Quick start](#quick-start)
 - [Requirements & Dependencies](#requirements--dependencies)
 - [The Council](#the-council)
@@ -55,6 +58,17 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ---
 
+## Ways to run the council
+
+The council is the hero — start with the everyday way, and reach for the more powerful ways when you need them:
+
+- **Just ask, in Claude Code.** Hand Claude a plan, diff, design, or manuscript and say *"council review this."* The `second-opinion` skill runs the whole ritual in your session — several models review independently → anonymized cross-review → a non-Claude chair verdict → tiered accept/deny edits — with no setup beyond your API keys. This is how most people use it. → [The Council](#the-council)
+- **Headless, in CI, with no Claude runtime.** `amicus council run --prompt-file plan.md --council free` runs that same pipeline in one command — reviews → cross-review → tally → chair verdict — writing `verdict.json` and `report.html`. It needs no Claude session, so it drops straight into CI. → [Headless council](./docs/council.md#amicus-council-run)
+- **With a debate round.** Add `--debate` and every Contested or Disputed finding goes back to its raiser to **defend, amend, or withdraw** while the disputing judges re-vote — exactly one rebuttal round, then the final tally. → [The Council](#the-council)
+- **On free, local, private models — at $0.** Point the council (and sidecars) at an OpenAI-compatible server already running on your machine — Ollama, LM Studio, or vLLM — with `amicus provider add`. No API key, no per-token bill, nothing leaves your machine, and it works offline. → [`amicus provider`](./docs/usage.md#amicus-provider)
+
+---
+
 ## Quick start
 
 > **Two install channels — read this first.** Amicus ships two ways, and CLI commands look different in each:
@@ -99,6 +113,8 @@ For the **npm** and **install-script** paths, a postinstall auto-configures ever
 - Registers the **MCP server** in Claude Code and in Claude Desktop / Cowork, so the Amicus tools appear natively.
 - Installs **both skills** into `~/.claude/skills/` — `second-opinion` (the council) and `sidecar` (the chat skill).
 
+> **Skipped the postinstall?** `--ignore-scripts` npm installs never run it, and the plugin channel skips it by design (Claude Code registers the plugin's MCP server and skills itself). Either way, run `amicus init` (plugin channel: `npx -y amicus@latest init`) any time to (re)register on demand — e.g. to also wire up Claude Desktop, which the plugin path doesn't touch. See [`amicus init`](./docs/usage.md#amicus-init).
+
 **Configure:**
 
 ```bash
@@ -167,6 +183,7 @@ Everything you need before your first run, and what's optional.
 **Model API keys** — at least one is required
 
 - **OpenRouter** covers the most models with one key, or use a **direct Google / OpenAI / Anthropic / DeepSeek** key. Add one with `amicus setup` or `amicus key <provider> <key>`; keys live in `~/.config/amicus/.env`. The supported env vars are `OPENROUTER_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` (the legacy `GEMINI_API_KEY` is still accepted), `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `DEEPSEEK_API_KEY`.
+- **Or skip cloud keys entirely and run local, at $0.** Point Amicus at an OpenAI-compatible server already running on your machine — LM Studio, Ollama, or vLLM — and there's no API key, no per-token bill: `amicus provider add lmstudio --preset lmstudio` (LM Studio), `--preset ollama` (Ollama), or `--preset vllm` (vLLM). See [`amicus provider`](./docs/usage.md#amicus-provider).
 - ⚠️ **OpenRouter keys need purchased credits.** A brand-new, zero-credit key *passes* setup's live validation but then fails at runtime with a **402** on the first real call. Buy a small amount of credit before you run a council.
 
 **Electron — optional (GUI only)**
@@ -300,12 +317,14 @@ amicus update
 | `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
 | `amicus spend` | Cross-run cost rollup from the spend ledger — total + per-model spend, tokens, and source mix, most-expensive first (`--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
+| `amicus provider` | Add/list/test/remove local, OpenAI-compatible providers (LM Studio, Ollama, vLLM) — configured with `--preset` or `--url`, at **$0** marginal cost (`--json` on every subcommand). |
 | `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [The Council](#the-council) for the built-in `free`/`budget`/`frontier` benches. |
 | `amicus council run` | The headless council engine: Stage-1 reviews → anonymized cross-review → deterministic tally → non-Claude chair verdict, in one command with no Claude runtime. Add `--debate` for a Stage-2.5 rebuttal round (raisers defend/amend/withdraw, disputing judges re-vote) and `--claude-review <file>` to enter Claude's own review as judged review N+1. Writes a run directory with `verdict.json` (including `overallVerdict`) and `report.html` — see [docs/council.md](./docs/council.md#amicus-council-run). |
 | `amicus abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
 | `amicus mcp` | Start the MCP server (stdio transport). |
+| `amicus init` | Re-run skill install + MCP registration on demand — `--claude`/`--desktop` to scope it, `--json` for per-step status. For plugin-channel / `--ignore-scripts` installs (which skip the npm postinstall), a failed postinstall, or repairing deleted `~/.claude` state. |
 
 The `am` alias is interchangeable with `amicus` everywhere.
 
@@ -329,7 +348,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -117,11 +117,21 @@ async function main() {
         exitCode = await handleDoctor(args);
         break;
       }
+      case 'init': {
+        const { handleInit } = require('../src/cli-handlers-init');
+        exitCode = await handleInit(args);
+        break;
+      }
       case 'spend': {
         const { handleSpend } = require('../src/cli-handlers-spend');
         exitCode = await handleSpend(args);
         break;
       }
+      case 'provider': {
+        const { handleProvider } = require('../src/cli-handlers-provider');
+        exitCode = await handleProvider(args);
+        break;
+      }
       case 'setup':
         await handleSetup(args);
         break;

package/electron/ipc-setup-local.js

@@ -0,0 +1,109 @@
+/**
+ * IPC handlers for the Electron wizard's "Local server" card (Task 13, v4.2 §4.6).
+ *
+ * Split out of ipc-setup.js purely to keep that file under the 300-line size gate
+ * (mirrors RULING D14's extraction of src/sidecar/setup-local.js out of setup.js for
+ * the identical reason). registerLocalProviderHandlers is called from
+ * registerSetupHandlers with the same (possibly test-injected) ipcMain, so these two
+ * channels are registered on exactly the instance the rest of the setup-mode IPC
+ * surface uses — this split changes no behavior, only file layout.
+ *
+ * setup:probe-local reuses Task 2's probeLocalProvider (the same reachability check
+ * `amicus provider test` and the readline wizard's handleProvider already share) and
+ * deliberately returns only a model COUNT — never the model list or the
+ * bearer/Authorization header — so nothing sensitive crosses the preload bridge
+ * beyond what the renderer asked for.
+ *
+ * setup:save-local-provider reuses the same validateProviderEntry/deriveKeyEnv
+ * (Task 1) and saveRawEnv (api-key-store.js) the CLI's `amicus provider add` uses,
+ * so a bearer always lands in the 0600 .env under its derived env-var NAME and
+ * config.json only ever carries that name (never the secret). Per B7/D4,
+ * applyProviderDefault (provider-default-picker.js) remains the SOLE writer of
+ * config.default — this handler never seeds it, even on a successful save.
+ */
+'use strict';
+
+const { logger } = require('../src/utils/logger');
+
+/**
+ * Exact-hostname loopback + scheme check (mirrors cli-handlers-provider.js's
+ * isLoopbackUrl/isPlaintextRemote pair). Duplicated locally rather than imported —
+ * leaf-module convention (see local-providers.js's RESERVED_IDS comment) — since
+ * those helpers are private to the CLI-oriented module.
+ * @param {string} baseURL
+ * @returns {boolean} true when a bearer sent here would travel in cleartext
+ */
+function isPlaintextRemoteBearer(baseURL) {
+  try {
+    const u = new URL(baseURL);
+    const loopback = ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(u.hostname);
+    return u.protocol === 'http:' && !loopback;
+  } catch { return false; }
+}
+
+/**
+ * @param {object} ipcMain - electron's ipcMain, or the test double
+ *   registerSetupHandlers was called with — same instance the rest of
+ *   ipc-setup.js's handlers are registered on.
+ */
+function registerLocalProviderHandlers(ipcMain) {
+  // Probe handler (Test connection button): gated through validateProviderEntry
+  // first so an invalid-input vs. unreachable-server distinction never depends on
+  // the network layer.
+  ipcMain.handle('setup:probe-local', async (_event, entry) => {
+    try {
+      const { validateProviderEntry } = require('../src/utils/local-providers');
+      const v = validateProviderEntry({ type: 'openai-compatible', baseURL: entry.baseURL, flavor: entry.flavor });
+      if (!v.ok) { return { ok: false, error: v.error }; }
+      const { probeLocalProvider } = require('../src/utils/local-probe');
+      const probe = await probeLocalProvider({ ...v.normalized, id: 'probe' }, { timeoutMs: 2000, bearer: entry.bearer });
+      return probe.status === 'ok' ? { ok: true, count: probe.models.length } : { ok: false, error: 'unreachable' };
+    } catch (e) { return { ok: false, error: e.message }; }
+  });
+
+  // Save handler (Save button): validate -> persist bearer to .env (if any) ->
+  // write config.providers[id]. Reserved/malformed ids are rejected here because
+  // validateProviderEntry is id-agnostic (the map key carries the id).
+  ipcMain.handle('setup:save-local-provider', async (_event, entry) => {
+    try {
+      const { validateProviderEntry, deriveKeyEnv, RESERVED_IDS, ID_RE } = require('../src/utils/local-providers');
+      const id = entry && typeof entry.id === 'string' ? entry.id.trim() : '';
+      if (!ID_RE.test(id) || RESERVED_IDS.includes(id)) {
+        return { ok: false, error: `Invalid or reserved provider id: '${id}'` };
+      }
+      const draft = { type: 'openai-compatible', baseURL: entry.baseURL, flavor: entry.flavor };
+      if (entry.pricing) { draft.pricing = entry.pricing; }
+      const v = validateProviderEntry(draft);
+      if (!v.ok) { return { ok: false, error: v.error }; }
+      const normalized = v.normalized;
+      // Bearer: value -> .env under the derived env var; config carries the NAME only.
+      if (entry.bearer) {
+        const envVar = deriveKeyEnv(id);
+        const { saveRawEnv } = require('../src/utils/api-key-store');
+        const saved = saveRawEnv(envVar, entry.bearer);
+        if (!saved.success) { return { ok: false, error: saved.error }; }
+        normalized.apiKeyEnv = envVar;
+      }
+      const { loadConfig, saveConfig } = require('../src/utils/config');
+      const config = loadConfig() || {};
+      config.providers = config.providers || {};
+      config.providers[id] = normalized; // undefined name/apiKeyEnv keys are dropped by JSON.stringify
+      // B7/D4: applyProviderDefault is the SOLE writer of config.default. A bare id with no
+      // matching config.aliases[id] is unresolvable by resolveModel() and permanently breaks
+      // every later keyless launch. Do NOT seed it here.
+      saveConfig(config);
+      const result = { ok: true, id, bearer: !!entry.bearer };
+      // Security posture parity with the CLI (cli-handlers-provider.js's doAdd):
+      // warn, never block, a bearer headed over plain http to a non-loopback host.
+      if (entry.bearer && isPlaintextRemoteBearer(entry.baseURL)) {
+        result.warning = 'Sending a bearer token over plain http:// to a non-loopback host transmits it in cleartext.';
+      }
+      return result;
+    } catch (err) {
+      logger.error('save-local-provider handler error', { error: err.message });
+      return { ok: false, error: err.message };
+    }
+  });
+}
+
+module.exports = { registerLocalProviderHandlers, isPlaintextRemoteBearer };

package/electron/ipc-setup.js

@@ -10,14 +10,21 @@
  * uncached live fetch.)
  */
 
-const { ipcMain } = require('electron');
 const { logger } = require('../src/utils/logger');
+const { registerLocalProviderHandlers } = require('./ipc-setup-local');
 
 /**
  * Register all setup-related IPC handlers
  * @param {function} getMainWindow - Returns the current main BrowserWindow
+ * @param {object} [injected] - DI overrides
+ * @param {object} [injected.ipcMain] - Electron ipcMain (or a test double exposing
+ *   .handle). Defaults to the real `require('electron').ipcMain` — production call
+ *   sites (electron/main.js) pass none. Task 13 / C9: this parameter shadows what
+ *   used to be a module-level `const { ipcMain } = require('electron');`, which is
+ *   removed rather than left dead now that every ipcMain.handle(...) call below
+ *   resolves through this local binding instead.
  */
-function registerSetupHandlers(getMainWindow) {
+function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ipcMain } = {}) {
   ipcMain.handle('sidecar:validate-key', async (_event, provider, key) => {
     try {
       const { validateApiKey } = require('../src/utils/api-key-store');
@@ -237,6 +244,11 @@ function registerSetupHandlers(getMainWindow) {
       }));
     } catch (_err) { return []; }
   });
+
+  // Task 13 (v4.2 §4.6): Electron wizard "Local server" card — probe + save.
+  // Extracted to ipc-setup-local.js to keep this file under the size gate (see its
+  // header comment); registered on the SAME (possibly injected) ipcMain as above.
+  registerLocalProviderHandlers(ipcMain);
 }
 
 module.exports = { registerSetupHandlers };

package/electron/preload-setup.js

@@ -23,7 +23,9 @@ contextBridge.exposeInMainWorld('sidecarSetup', {
       'sidecar:get-catalog',
       'sidecar:refresh-catalog',
       'sidecar:fetch-free-models',
-      'sidecar:set-provider-default'
+      'sidecar:set-provider-default',
+      'setup:probe-local',
+      'setup:save-local-provider'
     ];
     if (!allowedChannels.includes(channel)) {
       throw new Error(`IPC channel not allowed: ${channel}`);

package/electron/setup-ui-local-script.js

@@ -0,0 +1,114 @@
+/**
+ * Setup UI — Local server widget runtime script (Task 13, v4.2 §4.6).
+ *
+ * Companion to setup-ui-local.js's HTML. Preset chips fill the URL field and track
+ * a flavor (defaulting to 'generic' the moment the URL no longer matches any chip's
+ * preset value — mirrors cli-handlers-provider.js's entryFromArgs: `(preset &&
+ * preset.flavor) || 'generic'`). "Test connection" invokes setup:probe-local and
+ * renders the returned model count or error; Save invokes setup:save-local-provider
+ * and renders its result (including the plaintext-bearer warning, D-posture parity
+ * with the CLI's doAdd). Model/error strings from the response are rendered via
+ * textContent only — never innerHTML — mirroring the no-innerHTML-for-catalog-data
+ * convention setup-ui-provider-default.js documents.
+ */
+'use strict';
+
+/**
+ * Build the local-server widget JS for inline inclusion in the wizard script.
+ * @returns {string} JavaScript source (no <script> tags)
+ */
+function buildLocalScript() {
+  return `
+  // Task 13: Local server card (Ollama / LM Studio / vLLM / any OpenAI-compatible).
+  (function() {
+    var idInput = document.getElementById('local-id-input');
+    var urlInput = document.getElementById('local-url-input');
+    var bearerInput = document.getElementById('local-bearer-input');
+    var testBtn = document.getElementById('local-test-btn');
+    var saveBtn = document.getElementById('local-save-btn');
+    var statusMsg = document.getElementById('local-status-msg');
+    var chips = Array.prototype.slice.call(document.querySelectorAll('.local-chip'));
+    var selectedFlavor = 'generic';
+
+    function setStatus(text, cls) {
+      if (!statusMsg) { return; }
+      statusMsg.textContent = text || '';
+      statusMsg.className = cls || '';
+    }
+
+    chips.forEach(function(chip) {
+      chip.addEventListener('click', function() {
+        chips.forEach(function(c) { c.classList.remove('active'); });
+        chip.classList.add('active');
+        var preset = chip.getAttribute('data-preset');
+        if (urlInput) { urlInput.value = chip.getAttribute('data-url'); }
+        if (idInput && !idInput.value.trim()) { idInput.value = preset; }
+        selectedFlavor = chip.getAttribute('data-flavor');
+        setStatus('', '');
+      });
+    });
+
+    if (urlInput) {
+      urlInput.addEventListener('input', function() {
+        var matched = chips.filter(function(c) { return c.getAttribute('data-url') === urlInput.value; });
+        selectedFlavor = matched.length > 0 ? matched[0].getAttribute('data-flavor') : 'generic';
+        if (matched.length === 0) { chips.forEach(function(c) { c.classList.remove('active'); }); }
+      });
+    }
+
+    if (testBtn) {
+      testBtn.addEventListener('click', async function() {
+        var url = (urlInput && urlInput.value.trim()) || '';
+        if (!url) { setStatus('Enter a server URL first', 'status-invalid'); return; }
+        testBtn.disabled = true; testBtn.textContent = 'Testing...';
+        setStatus('', '');
+        try {
+          var res = await window.sidecarSetup.invoke('setup:probe-local', {
+            baseURL: url, flavor: selectedFlavor, bearer: (bearerInput && bearerInput.value) || undefined,
+          });
+          if (res && res.ok) {
+            setStatus(res.count + ' model' + (res.count === 1 ? '' : 's') + ' found \\u2713', 'status-valid');
+          } else {
+            setStatus((res && res.error) || 'Unreachable', 'status-invalid');
+          }
+        } catch (_e) {
+          setStatus('Connection failed', 'status-invalid');
+        }
+        testBtn.disabled = false; testBtn.textContent = 'Test connection';
+      });
+    }
+
+    if (saveBtn) {
+      saveBtn.addEventListener('click', async function() {
+        var id = (idInput && idInput.value.trim()) || '';
+        var url = (urlInput && urlInput.value.trim()) || '';
+        if (!id || !url) { setStatus('Provider ID and server URL are required', 'status-invalid'); return; }
+        saveBtn.disabled = true; saveBtn.textContent = 'Saving...';
+        try {
+          var res = await window.sidecarSetup.invoke('setup:save-local-provider', {
+            id: id, baseURL: url, flavor: selectedFlavor, bearer: (bearerInput && bearerInput.value) || undefined,
+          });
+          if (res && res.ok) {
+            // A returned warning (plaintext-bearer-to-remote-host, ipc-setup.js) is
+            // shown with the same visual weight as an error even though the save
+            // itself succeeded -- it is safety-relevant, not merely informational.
+            setStatus(res.warning || 'Saved \\u2713', res.warning ? 'status-invalid' : 'status-valid');
+            // Configuring a local provider counts toward "at least one provider
+            // ready" the same way a cloud API key does, so Step 1's Next button
+            // unlocks for a local-only setup too.
+            if (typeof configuredKeys === 'object') { configuredKeys[id] = true; }
+            if (typeof updateNextState === 'function') { updateNextState(); }
+          } else {
+            setStatus((res && res.error) || 'Save failed', 'status-invalid');
+          }
+        } catch (_e) {
+          setStatus('Save failed', 'status-invalid');
+        }
+        saveBtn.disabled = false; saveBtn.textContent = 'Save local server';
+      });
+    }
+  })();
+  `;
+}
+
+module.exports = { buildLocalScript };

package/electron/setup-ui-local.js

@@ -0,0 +1,75 @@
+/**
+ * Setup UI — "Local server" step-1 add-on widget (Task 13, v4.2 §4.6).
+ *
+ * The Electron-wizard equivalent of Task 12's readline `addLocalProviderInteractive`
+ * (src/sidecar/setup-local.js): lets the user point the wizard at a self-hosted
+ * OpenAI-compatible server (Ollama, LM Studio, vLLM, or any other) without leaving
+ * the GUI. LM Studio leads the chip order and the widget copy — a LOCKED parity
+ * constraint (the readline wizard's own preset prompt order is `ollama / lmstudio /
+ * vllm`, but this card is not required to mirror that order).
+ *
+ * RULING B12/D8: `electron/setup-ui-keys.js`'s provider cards (buildKeysStepHTML)
+ * are bare id/name/description buttons feeding ONE shared key-section — there is no
+ * per-provider card with its own fields to extend, and this widget needs two
+ * simultaneous fields (URL + bearer) plus N preset chips plus a differently-behaved
+ * Test button. So, per the convention `setup-ui-provider-default.js` and
+ * `setup-ui-council.js` already establish, this is its own `setup-ui-*.js` +
+ * `*-script.js` pair, spliced into `setup-ui.js`'s step-1 assembly, rather than
+ * grown into setup-ui-keys.js / setup-ui-keys-script.js.
+ *
+ * Consumes (at render time): `PRESETS` (src/utils/local-providers.js, Task 1) for the
+ * three built-in chip URLs/flavors — single-sourced rather than re-hardcoded here.
+ * The runtime script (setup-ui-local-script.js) additionally consumes the
+ * `setup:probe-local` / `setup:save-local-provider` IPC handlers (ipc-setup.js,
+ * Task 13) at click time.
+ */
+'use strict';
+
+const { PRESETS } = require('../src/utils/local-providers');
+
+/** LOCKED parity constraint: LM Studio leads (chip order + widget title/copy). */
+const CHIP_ORDER = [
+  { id: 'lmstudio', label: 'LM Studio' },
+  { id: 'ollama', label: 'Ollama' },
+  { id: 'vllm', label: 'vLLM' },
+];
+
+/**
+ * Build the HTML fragment for the Local server widget (spliced into wizard-step-1,
+ * beneath the key step and the per-provider default picker section).
+ * @returns {string} HTML fragment (not a full document)
+ */
+function buildLocalSectionHTML() {
+  const chips = CHIP_ORDER.map((c) => {
+    const preset = PRESETS[c.id];
+    return `<button type="button" class="local-chip" data-preset="${c.id}" ` +
+      `data-url="${preset.baseURL}" data-flavor="${preset.flavor}">${c.label}</button>`;
+  }).join('\n        ');
+
+  return `<div class="local-section" id="local-section">
+      <div class="local-divider">Local server &mdash; LM Studio &middot; Ollama &middot; vLLM</div>
+      <p class="local-subtitle">Connect a self-hosted OpenAI-compatible server. No API key required for most.</p>
+      <div class="local-chips" id="local-chips">
+        ${chips}
+      </div>
+      <label class="field-label" for="local-id-input">Provider ID</label>
+      <div class="input-row">
+        <input id="local-id-input" type="text" placeholder="lmstudio" autocomplete="off" spellcheck="false">
+      </div>
+      <label class="field-label" for="local-url-input">Server URL</label>
+      <div class="input-row">
+        <input id="local-url-input" type="text" placeholder="http://127.0.0.1:1234/v1" autocomplete="off" spellcheck="false">
+      </div>
+      <label class="field-label" for="local-bearer-input">Bearer token (optional)</label>
+      <div class="input-row">
+        <input id="local-bearer-input" type="password" placeholder="" autocomplete="off" spellcheck="false">
+        <button class="test-btn" id="local-test-btn" type="button">Test connection</button>
+      </div>
+      <div class="key-actions">
+        <span id="local-status-msg"></span>
+        <button class="nav-btn" id="local-save-btn" type="button">Save local server</button>
+      </div>
+    </div>`;
+}
+
+module.exports = { buildLocalSectionHTML, CHIP_ORDER };

package/electron/setup-ui-styles.js

@@ -427,7 +427,21 @@ function __rawWizardCSS() {
     border-radius: var(--r-6);
   }
   .provider-default-row:hover { background: var(--surface-hover); }
-  .provider-default-row input[type="radio"] { accent-color: var(--accent); flex-shrink: 0; }`;
+  .provider-default-row input[type="radio"] { accent-color: var(--accent); flex-shrink: 0; }
+
+  /* Local server card (Step 1, Task 13) -- grep -ri chip electron/ had zero hits before this */
+  .local-section { margin-top: 14px; border-top: 1px solid var(--border); padding-top: 12px; }
+  .local-divider { font-size: 12px; font-weight: 600; color: var(--text-muted); margin-bottom: 4px; }
+  .local-subtitle { color: var(--text-faint); font-size: 11px; margin-bottom: 8px; }
+  .local-chips { display: flex; gap: 6px; margin-bottom: 10px; flex-wrap: wrap; }
+  .local-chip {
+    padding: 4px 10px; font-size: 11px; font-weight: 500;
+    background: var(--surface); border: 1px solid var(--border); border-radius: var(--r-4);
+    color: var(--text-muted); cursor: pointer;
+    transition: border-color var(--dur-fast), color var(--dur-fast), background var(--dur-fast);
+  }
+  .local-chip:hover { border-color: var(--border-strong); color: var(--text); }
+  .local-chip.active { background: var(--accent); color: var(--accent-text); border-color: var(--accent); }`;
 }
 
 function buildWizardCSS() {

package/electron/setup-ui.js

@@ -7,6 +7,8 @@ const { buildKeysScript } = require('./setup-ui-keys-script');
 const { buildAliasScript } = require('./setup-ui-alias-script');
 const { buildCouncilSectionHTML, buildCouncilScript } = require('./setup-ui-council');
 const { buildProviderDefaultSectionHTML, buildProviderDefaultScript } = require('./setup-ui-provider-default');
+const { buildLocalSectionHTML } = require('./setup-ui-local');
+const { buildLocalScript } = require('./setup-ui-local-script');
 const { getDefaultAliases } = require('../src/utils/config');
 const { getBrandName } = require('./toolbar');
 const { resolveQuickPicks } = require('../src/utils/quick-picks');
@@ -41,7 +43,7 @@ function buildSetupHTML(options = {}) {
   <div class="header"><svg width="18" height="18" viewBox="0 0 32 32" fill="none"><path d="M4 8H19"/><path d="M4 11H14L19 8"/><path d="M4 14H13L19 8"/><path d="M4 17H12L19 8"/><path d="M4 20H11L19 8"/><path d="M4 23H10L19 8"/><path class="brand-main" d="M19 8H28"/></svg><span class="header-title">${brandName} Setup</span></div>
   <div class="progress-bar"><div class="progress-step active" id="step-1"><span class="progress-dot">1</span><span>API Keys</span></div><div class="progress-connector"></div><div class="progress-step" id="step-2"><span class="progress-dot">2</span><span>Models</span></div><div class="progress-connector"></div><div class="progress-step" id="step-3"><span class="progress-dot">3</span><span>Routing</span></div><div class="progress-connector"></div><div class="progress-step" id="step-4"><span class="progress-dot">4</span><span>Review</span></div></div>
   <div class="content">
-    <div class="wizard-step visible" id="wizard-step-1"><div id="import-notice"></div>${keysHtml}${buildProviderDefaultSectionHTML()}</div>
+    <div class="wizard-step visible" id="wizard-step-1"><div id="import-notice"></div>${keysHtml}${buildProviderDefaultSectionHTML()}${buildLocalSectionHTML()}</div>
     <div class="wizard-step" id="wizard-step-2">${modelHtml}${buildCouncilSectionHTML()}</div>
     <div class="wizard-step" id="wizard-step-3">${aliasHtml}</div>
     <div class="wizard-step" id="wizard-step-4">
@@ -65,6 +67,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   const aliasJs = buildAliasScript();
   const councilJs = buildCouncilScript();
   const providerDefaultJs = buildProviderDefaultScript();
+  const localJs = buildLocalScript();
   return `<script>
   window.onerror = function(msg, src, line, col, err) { console.error('WIZARD ERROR:', msg, 'at', src, line, col, err); };
   window.onunhandledrejection = function(e) { console.error('WIZARD UNHANDLED REJECTION:', e.reason); };
@@ -578,6 +581,8 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   ${councilJs}
 
   ${providerDefaultJs}
+
+  ${localJs}
 </script>`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [