amicus 1.3.0 → 1.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.3.0",
+  "version": "1.4.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" },
   "homepage": "https://bourbondog.github.io/amicus/",

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-06-28
+
+### Added
+- **Free OpenRouter council**: a new `amicus setup` option (readline wizard + Electron Models step)
+  that stands up a zero-cost council of free `:free` OpenRouter models, saved as a first-class
+  `councils` config primitive. Run it with `amicus fanout --council free` or the `amicus_fanout` MCP
+  `council` param; the second-opinion skill reads `councils.free`. Free-model picks are detected
+  live from the catalog (the `:free` suffix is authoritative), seeded under collision-safe `free-*`
+  aliases, and a delisted member degrades gracefully (dropped with a warning) instead of failing the
+  wave. Needs only an `OPENROUTER_API_KEY`; the wizard discloses the free-tier caveats (rate limits,
+  variable quality, the OpenRouter data-sharing prerequisite). `config.default` is left untouched.
+
 ## [1.3.0] - 2026-06-24
 
 Making the mature council/fan-out engine legible: live per-leg progress, cost

package/README.md

@@ -152,6 +152,16 @@ Then the council waits for your confirmation.
 
 The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**.
 
+**Free council (zero-cost).** Want the cross-examination without the model spend? `amicus setup` offers a **Free OpenRouter council** mode — readline wizard option 2, and the Electron **Models** step. It detects the free `:free` models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as `councils.free` — a first-class `councils` config primitive seeded under collision-safe `free-*` aliases. Your `config.default` is left untouched, and all you need is an `OPENROUTER_API_KEY`.
+
+Run it anywhere a council runs:
+
+```bash
+amicus fanout --council free --prompt "Review this design"
+```
+
+The `amicus_fanout` MCP tool takes the same `council` parameter, and the `second-opinion` skill reads `councils.free` automatically. A member that gets delisted is dropped with a warning — the council still runs as long as ≥2 survive. Free models are **rate-limited and quality-variable**, and some return 404 unless you enable data-sharing at [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy).
+
 ---
 
 ## The parallel window
@@ -246,7 +256,8 @@ amicus fanout --models gemini,deepseek,gpt --prompt "Review this design" --json
 
 Fanout runs one **headless wave**: every leg gets the **same** prompt (this is the shared-prompt model the council's review stages are built on). When all legs are terminal it prints **one** JSON wave document on stdout.
 
-- `--models <a,b,c>` — comma-separated aliases or `provider/model` IDs (required).
+- `--models <a,b,c>` — comma-separated aliases or `provider/model` IDs (required, unless `--council`).
+- `--council <name>` — run a saved council (e.g. `free`) instead of `--models`; mutually exclusive with `--models`.
 - `--prompt <text>` / `--prompt-file <path>` — the shared briefing. `--prompt-file` avoids the ~32 KB Windows argument cap and is mutually exclusive with `--prompt`.
 - `--wave-id <id>` — set the wave ID explicitly (leg IDs become `<id>-1..N`).
 - `--json` — emit the wave document.

package/electron/ipc-setup.js

@@ -97,7 +97,8 @@ function registerSetupHandlers(getMainWindow) {
 
   // Read-modify-write: never rewrite an alias the renderer didn't send.
   // aliasWrites values: string = set, null = delete. First run seeds live.
-  ipcMain.handle('sidecar:save-config', async (_event, defaultModel, aliasWrites) => {
+  // councilPicks (optional): when length >= 2, seeds the free council via seedFreeCouncil.
+  ipcMain.handle('sidecar:save-config', async (_event, defaultModel, aliasWrites, councilPicks) => {
     try {
       const { loadConfig, saveConfig } = require('../src/utils/config');
       let cfg = loadConfig();
@@ -119,6 +120,9 @@ function registerSetupHandlers(getMainWindow) {
         }
       }
       saveConfig(cfg);
+      if (Array.isArray(councilPicks) && councilPicks.length >= 2) {
+        require('../src/sidecar/setup').seedFreeCouncil(councilPicks);
+      }
       return { success: true };
     } catch (err) {
       logger.error('save-config handler error', { error: err.message });
@@ -192,6 +196,19 @@ function registerSetupHandlers(getMainWindow) {
       return { models: [], fetchedAt: null };
     }
   });
+
+  // Free OpenRouter council: returns all free models from the catalog,
+  // marking those in the vendor-diverse suggested set with suggested:true.
+  ipcMain.handle('sidecar:fetch-free-models', async () => {
+    try {
+      const { getCatalog } = require('../src/utils/model-catalog');
+      const { listFreeModels, suggestFreeCouncil } = require('../src/utils/free-models');
+      const catalog = await getCatalog();
+      const free = listFreeModels(catalog);
+      const suggested = new Set(suggestFreeCouncil(free, 3).map(r => r.id));
+      return free.map(r => ({ id: r.id, suggested: suggested.has(r.id) }));
+    } catch (_err) { return []; }
+  });
 }
 
 module.exports = { registerSetupHandlers };

package/electron/preload-setup.js

@@ -22,7 +22,8 @@ contextBridge.exposeInMainWorld('sidecarSetup', {
       'sidecar:get-api-keys',
       'sidecar:fetch-models',
       'sidecar:get-catalog',
-      'sidecar:refresh-catalog'
+      'sidecar:refresh-catalog',
+      'sidecar:fetch-free-models'
     ];
     if (!allowedChannels.includes(channel)) {
       throw new Error(`IPC channel not allowed: ${channel}`);

package/electron/setup-ui-council.js

@@ -0,0 +1,77 @@
+/**
+ * Setup UI — Free OpenRouter council picker (mounted on the Models step).
+ * Collapsible section: a checkbox list of free models fetched via IPC. Gated
+ * on the OpenRouter key (recomputed on Step-2 entry by the orchestrator).
+ * window.collectCouncilPicks() returns the checked ids for the save payload.
+ */
+'use strict';
+
+function buildCouncilSectionHTML() {
+  return `<div id="free-council-section" class="council-section">
+      <label class="council-toggle"><input type="checkbox" id="free-council-toggle">
+        <span>Set up a free OpenRouter council (zero-cost)</span></label>
+      <div id="free-council-body" style="display:none">
+        <div id="free-council-meta" class="search-meta"></div>
+        <div id="free-council-results" class="council-results"></div>
+        <div class="council-note">Free tier: rate-limited &amp; quality-variable; some models need
+          data-sharing enabled at openrouter.ai/settings/privacy.</div>
+      </div>
+    </div>`;
+}
+
+function buildCouncilScript() {
+  return `
+  (function() {
+    var toggle = document.getElementById('free-council-toggle');
+    var body = document.getElementById('free-council-body');
+    var results = document.getElementById('free-council-results');
+    var meta = document.getElementById('free-council-meta');
+    var loaded = false;
+
+    function hasOpenRouterKey() { return !!(window.configuredKeys && window.configuredKeys.openrouter); }
+
+    window.refreshCouncilGating = function() {
+      if (!toggle) { return; }
+      var ok = hasOpenRouterKey();
+      toggle.disabled = !ok;
+      if (meta && !ok) { meta.textContent = 'Add an OpenRouter API key (step 1) to enable a free council.'; }
+      else if (meta && !loaded) { meta.textContent = ''; }
+    };
+
+    async function loadFree() {
+      if (loaded) { return; }
+      try {
+        var rows = await window.sidecarSetup.invoke('sidecar:fetch-free-models');
+        loaded = true;
+        results.innerHTML = '';
+        (rows || []).forEach(function(r, i) {
+          var id = 'fc-' + i;
+          var row = document.createElement('label');
+          row.className = 'council-row';
+          var cb = document.createElement('input');
+          cb.type = 'checkbox'; cb.value = r.id; cb.id = id; cb.checked = !!r.suggested;
+          var span = document.createElement('span'); span.textContent = r.id;
+          row.appendChild(cb); row.appendChild(span);
+          results.appendChild(row);
+        });
+        if (meta) { meta.textContent = (rows || []).length + ' free models'; }
+      } catch (_e) { if (meta) { meta.textContent = 'Could not load free models.'; } }
+    }
+
+    if (toggle) {
+      toggle.addEventListener('change', function() {
+        body.style.display = toggle.checked ? '' : 'none';
+        if (toggle.checked) { loadFree(); }
+      });
+    }
+
+    window.collectCouncilPicks = function() {
+      if (!toggle || !toggle.checked) { return []; }
+      return Array.prototype.slice.call(results.querySelectorAll('input[type=checkbox]:checked'))
+        .map(function(cb) { return cb.value; });
+    };
+  })();
+  `;
+}
+
+module.exports = { buildCouncilSectionHTML, buildCouncilScript };

package/electron/setup-ui.js

@@ -5,6 +5,7 @@ const { buildAliasEditorHTML } = require('./setup-ui-aliases');
 const { buildWizardCSS } = require('./setup-ui-styles');
 const { buildKeysScript } = require('./setup-ui-keys-script');
 const { buildAliasScript } = require('./setup-ui-alias-script');
+const { buildCouncilSectionHTML, buildCouncilScript } = require('./setup-ui-council');
 const { getDefaultAliases } = require('../src/utils/config');
 const { getBrandName } = require('./toolbar');
 const { resolveQuickPicks } = require('../src/utils/quick-picks');
@@ -36,7 +37,7 @@ function buildSetupHTML(options = {}) {
   <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}</div>
-    <div class="wizard-step" id="wizard-step-2">${modelHtml}</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">
       <div class="step-content">
@@ -57,6 +58,7 @@ ${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultA
 function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson) {
   const keysJs = buildKeysScript();
   const aliasJs = buildAliasScript();
+  const councilJs = buildCouncilScript();
   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); };
@@ -91,6 +93,8 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
           }
         });
         if (data.hints) { keyHints = data.hints; }
+        window.configuredKeys = configuredKeys;
+        window.refreshCouncilGating && window.refreshCouncilGating();
         updateNextState();
         if (data.imported && data.imported.length > 0) {
           var notice = document.getElementById('import-notice');
@@ -171,7 +175,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     nextBtn.style.display = step < 4 ? '' : 'none';
     finishBtn.style.display = step === 4 ? '' : 'none';
     if (step === 4) { buildReview(); }
-    if (step === 2) { updateRoutingPills(); ensureCatalogLoaded(); }
+    if (step === 2) { updateRoutingPills(); ensureCatalogLoaded(); window.refreshCouncilGating && window.refreshCouncilGating(); }
     if (step === 3) {
       updateAliasRoutes();
       if (!window.availableModels) { fetchAvailableModels(); }
@@ -383,7 +387,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
           if (routeId) { aliasWrites[mc.alias] = routeId; }
         }
       }
-      await window.sidecarSetup.invoke('sidecar:save-config', dm, aliasWrites);
+      await window.sidecarSetup.invoke('sidecar:save-config', dm, aliasWrites, (window.collectCouncilPicks && window.collectCouncilPicks()) || []);
       var kc = Object.values(configuredKeys).filter(function(v) { return v; }).length;
       await window.sidecarSetup.invoke('sidecar:setup-done', dm, kc);
     } catch (_e) { finishBtn.disabled = false; finishBtn.textContent = 'Finish'; }
@@ -512,6 +516,8 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   ${aliasJs}
 
   ${keysJs}
+
+  ${councilJs}
 </script>`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.3.0",
+  "version": "1.4.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.",
   "keywords": [
     "claude",

package/skills/second-opinion/MODEL-NOTES.md

@@ -79,6 +79,12 @@ This section keeps only per-model **qualitative quirks** and **structural-confor
 - **gpt** — thorough but verbose; peers have dinged it for volume-over-judgment. Self-ranked its own review #1 in the 2026-06-04 run → the peers-only street-cred rule (now enforced by `tally`) mitigates this. Conforms cleanly. Accessible via OpenRouter.
 - **gemini** — fast, very large context; tends toward absolute severity labels ("blocker" inflation vs peers). Conforms cleanly; watch for preamble narration — instruct it to emit the JSON block verbatim after the prose.
 
+## Free-tier models (OpenRouter `:free`)
+- Heavily rate-limited (shared daily pool); a 3-leg parallel wave + cross-review can 429 mid-run.
+- Quality-variable; weaker at strict structured (findings JSON) output.
+- Some `:free` models 404 unless the account enables data-sharing at openrouter.ai/settings/privacy.
+- No reliability history — chair selection can't use `council stats`; pick the strongest free model and disclose lower confidence.
+
 ## Cost guardrail
 - The budget gate enforces this in code: a per-$/Mtok threshold (ON by default)
   refuses o3/o3-pro-class models before a wave launches. This replaces the old

package/skills/second-opinion/SKILL.md

@@ -56,6 +56,22 @@ in this run is written here. Use its absolute path in all `--prompt-file` argume
 
 **Pick the council.** Default: **3 models from different families (non-Claude)**. Recommend them ranked by fit, consulting both the reviewer-reliability data from `amicus council stats` (the authoritative quantitative source — runs, avg peers-only street-cred, confirm-rate, fact-error rate) and the qualitative quirks in `MODEL-NOTES.md`. State the estimated cost. The estimate is the budget gate's pre-flight figure (per-$/Mtok pricing from the cached catalog; direct-provider legs without catalog pricing are disclosed as "cost unknown"). State it as an estimate, not a guarantee. **Disclose the run shape up front** before asking for confirmation — e.g.:
 
+**Free council (zero-cost).** If the user asks for a "free council" / "zero-cost council",
+read `councils.free` from `~/.config/amicus/config.json` and run
+`amicus fanout --council free --prompt-file <briefing>`. Free-tier handling:
+- Cost ≈ $0 — skip the paid-run cost framing (the budget gate is a no-op at zero price).
+- No reliability history: free models have no `amicus council stats` / `MODEL-NOTES` record,
+  so don't rank on street-cred. Pick the most capable free model as chair and state lower confidence.
+- Weak structured output: small free models are less reliable at the strict findings JSON; expect
+  more `validateFindings` repair-loop hits.
+- Throttled/truncated legs: a mid-stream 429 can yield a leg marked `complete` with a truncated,
+  unparseable review. When a free-council leg is `complete` but `validateFindings` returns
+  `NO_FENCED_BLOCK`/`NOT_PARSEABLE`, treat it as suspect/throttled — don't burn the repair loop on the
+  same throttled model; disclose it and apply the ≥2-reviews-survive wave-degrade rule.
+- Prerequisite: free models require enabling data-sharing in OpenRouter privacy settings
+  (openrouter.ai/settings/privacy) or legs 404 at run time — catalog validation cannot catch this.
+  State this up front.
+
 > This run uses 3 council models across 2 fanout waves + 1 chair call (~7 model runs), ~10 min.
 
 Then **wait for confirmation**. Never launch without it. The budget gate enforces the cost guardrail in code: by default it refuses any leg whose price exceeds the per-$/Mtok threshold (the o3/o3-pro guard). To run an intentionally expensive model the user explicitly asked for by name, pass `--no-cost-gate`; to raise only the total ceiling, pass `--max-cost <$>`.

package/src/cli-handlers-run.js

@@ -108,8 +108,30 @@ async function handleFanout(args) {
   if (promptRes.error) {
     process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error }));
   }
-  if (typeof args.models !== 'string' || !args.models.trim()) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs)' }));
+  // Council preset: expand a saved council into args.models (mutually exclusive with --models).
+  const hasModels = typeof args.models === 'string' && args.models.trim();
+  const hasCouncil = args.council !== undefined && args.council !== false;
+  if (hasModels && hasCouncil) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pass exactly one of --models / --council, not both' }));
+  }
+  if (!hasModels && !hasCouncil) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs), or use --council <name>' }));
+  }
+  if (hasCouncil) {
+    if (typeof args.council !== 'string' || !args.council.trim()) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --council requires a council name (e.g. --council free)' }));
+    }
+    const { resolveCouncilMembers } = require('./utils/config');
+    const { readCache } = require('./utils/model-catalog');
+    const catalog = (readCache() || {}).models || [];
+    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
+    if (expanded.error) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }));
+    }
+    if (expanded.dropped && expanded.dropped.length && !useJson) {
+      process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
+    }
+    args.models = expanded.models.join(',');
   }
   if (args['wave-id']) {
     const check = validateTaskId(String(args['wave-id']));

package/src/cli.js

@@ -356,6 +356,7 @@ Options for 'start':
 
 Options for 'fanout':
   --models <a,b,c>             Required. Comma-separated aliases or provider/model IDs
+  --council <name>             Run a saved council instead of --models (e.g. free). Mutually exclusive with --models
   --prompt <text>              Task briefing (or use --prompt-file)
   --prompt-file <path>         Read the briefing from a UTF-8 file (avoids the
                                ~32KB Windows argument cap). Mutually exclusive

package/src/mcp-server.js

@@ -531,9 +531,38 @@ const handlers = {
   async amicus_fanout(input, project) {
     const cwd = project || getProjectDir(input.project);
     const { generateTaskId } = require('./sidecar/start');
-    const { deriveLegIds } = require('./sidecar/fanout');
+    const { deriveLegIds, DEFAULT_MAX_LEGS } = require('./sidecar/fanout');
+
+    // Resolve a single effective models list (council OR models), validated
+    // BEFORE any wave dir / metadata is written so a bad request never strands
+    // a pid-less 'running' orphan wave.
+    const inputModels = Array.isArray(input.models) ? input.models : [];
+    const hasModels = inputModels.length > 0;
+    const hasCouncil = typeof input.council === 'string' && input.council.trim();
+    if (hasModels && hasCouncil) {
+      return textResult("Pass exactly one of 'models' / 'council', not both.", true);
+    }
+    let effectiveModels;
+    if (hasCouncil) {
+      const { resolveCouncilMembers } = require('./utils/config');
+      const { readCache } = require('./utils/model-catalog');
+      const catalog = (readCache() || {}).models || [];
+      const expanded = resolveCouncilMembers(input.council.trim(), catalog);
+      if (expanded.error) { return textResult(expanded.error, true); }
+      effectiveModels = expanded.models;
+    } else if (hasModels) {
+      effectiveModels = inputModels;
+    } else {
+      return textResult("Provide 'models' or 'council'.", true);
+    }
+    const envCap = Number(process.env.AMICUS_FANOUT_MAX_LEGS);
+    const maxLegs = (Number.isInteger(envCap) && envCap > 0) ? envCap : DEFAULT_MAX_LEGS;
+    if (effectiveModels.length > maxLegs) {
+      return textResult(`Council/model list exceeds the fan-out cap of ${maxLegs} legs.`, true);
+    }
+
     const waveId = generateTaskId();
-    const legIds = deriveLegIds(waveId, input.models.length);
+    const legIds = deriveLegIds(waveId, effectiveModels.length);
     const waveDir = getSessionDir(cwd, waveId);
 
     let briefingPath;
@@ -545,14 +574,14 @@ const handlers = {
       fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
       fs.writeFileSync(path.join(waveDir, 'metadata.json'), JSON.stringify({
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
-        models: input.models, headless: true, createdAt: new Date().toISOString(),
+        models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
       }, null, 2), { mode: 0o600 });
     } catch (err) {
       return textResult(`Failed to prepare fan-out wave: ${err.message}`, true);
     }
 
     const args = [
-      'fanout', '--models', input.models.join(','),
+      'fanout', '--models', effectiveModels.join(','),
       '--prompt-file', briefingPath, '--wave-id', waveId,
       '--json', '--client', 'cowork', '--cwd', cwd,
     ];

package/src/mcp-tools.js

@@ -255,8 +255,11 @@ function getTools() {
       'document (per-leg summaries inside). Each leg is also an ordinary ' +
       'session readable by taskId.',
     inputSchema: {
-      models: z.array(safeModel).min(1).max(10).describe(
-        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed.`
+      models: z.array(safeModel).min(1).max(10).optional().describe(
+        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
+      ),
+      council: z.string().optional().describe(
+        "Run a saved council by name (e.g. 'free') instead of 'models'. Expands to the council's members. Mutually exclusive with 'models'."
       ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'

package/src/sidecar/setup.js

@@ -40,19 +40,23 @@ function addAlias(name, modelString) {
 }
 
 /**
- * Create a new config with all default aliases and the chosen default model
+ * Ensure a config exists with the chosen default model. Read-modify-write:
+ * preserves every pre-existing top-level key (aliases, councils, …) and only
+ * fills in the default + any missing default aliases. Never clobbers.
  * @param {string} defaultModel - Default model alias or full model string
- * @returns {object} The created config object
+ * @returns {object} The resulting config object
  */
 function createDefaultConfig(defaultModel) {
+  const existing = loadConfig() || {};
   const cfg = {
-    default: defaultModel,
-    aliases: getDefaultAliases()
+    ...existing,
+    default: existing.default || defaultModel,
+    aliases: { ...getDefaultAliases(), ...(existing.aliases || {}) },
   };
   saveConfig(cfg);
-  logger.info('Default config created', {
-    default: defaultModel,
-    aliasCount: Object.keys(cfg.aliases).length
+  logger.info('Default config ensured', {
+    default: cfg.default,
+    aliasCount: Object.keys(cfg.aliases).length,
   });
   return cfg;
 }
@@ -152,13 +156,70 @@ async function seedCatalog(print) {
   log('Model catalog unavailable (offline?) — it will refresh on first start.');
 }
 
+/**
+ * Free OpenRouter council branch of the readline wizard. Requires
+ * OPENROUTER_API_KEY; lists free catalog models, lets the user multi-pick
+ * (Enter = the vendor-diverse default), seeds aliases + councils.free, and
+ * never touches config.default.
+ * @param {readline.Interface} rl
+ */
+async function runFreeCouncilBranch(rl) {
+  const keys = detectApiKeys();
+  if (!keys.openrouter) {
+    console.log('');
+    console.log('A free council needs OPENROUTER_API_KEY (free models route only through OpenRouter).');
+    console.log('Set OPENROUTER_API_KEY and re-run: amicus setup. No changes made.');
+    return;
+  }
+  const { getCatalog } = require('../utils/model-catalog');
+  const { listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS } = require('../utils/free-models');
+  let catalog = [];
+  try { catalog = await getCatalog(); } catch (_e) { /* offline */ }
+  let free = listFreeModels(catalog);
+  if (free.length === 0) {
+    console.log('Live free-model list unavailable (offline?) — using a small pinned set.');
+    free = PINNED_FREE_MODELS.map(id => ({ id }));
+  }
+  const defaults = new Set(suggestFreeCouncil(free, 3).map(r => r.id));
+  console.log('');
+  console.log('Free OpenRouter models (★ = default council):');
+  free.forEach((r, i) => {
+    const star = defaults.has(r.id) ? '★' : ' ';
+    console.log(`  ${star} ${i + 1}) ${r.id}`);
+  });
+  console.log('');
+  const answer = await askQuestion(rl,
+    'Pick members (comma-separated numbers, or Enter for the ★ default): ');
+  let pickIds;
+  if (!answer) {
+    pickIds = free.filter(r => defaults.has(r.id)).map(r => r.id);
+  } else {
+    pickIds = answer.split(',').map(s => parseInt(s.trim(), 10))
+      .filter(n => n >= 1 && n <= free.length).map(n => free[n - 1].id);
+  }
+  if (pickIds.length < 2) {
+    console.log('A council needs at least 2 models. No changes made.');
+    return;
+  }
+  const { council } = seedFreeCouncil(pickIds);
+  await seedCatalog();
+  console.log('');
+  console.log(`Free council saved: councils.free = [${council.join(', ')}]`);
+  console.log('Run it:   amicus fanout --council free --prompt "..."');
+  console.log('config.default left unchanged.');
+  console.log('');
+  console.log('Heads up (free tier): rate-limited & quality-variable; some models 404');
+  console.log('unless you enable data-sharing at openrouter.ai/settings/privacy.');
+}
+
 /**
  * Run the readline-based setup wizard (headless fallback)
  *
  * Guides the user through:
  * 1. API key detection
- * 2. Default model selection from live quick-picks (read-modify-write, no clobber)
- * 3. Config file save
+ * 2. Mode selection (standard or free council)
+ * 3. Default model selection from live quick-picks (read-modify-write, no clobber)
+ * 4. Config file save
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -185,6 +246,13 @@ async function runReadlineSetup() {
     }
     console.log('');
 
+    const mode = await askQuestion(rl,
+      'Setup mode — 1) Standard (pick a default model)  2) Free OpenRouter council: ');
+    if (mode === '2') {
+      await runFreeCouncilBranch(rl);
+      return;
+    }
+
     const { getCatalog } = require('../utils/model-catalog');
     const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
     let catalog = [];
@@ -282,12 +350,64 @@ async function runInteractiveSetup() {
 
 /* eslint-enable no-console */
 
+/**
+ * Collision-safe alias name from a free model id. Strips the openrouter/
+ * prefix and trailing :free, sanitizes '/'/':' to '-', prefixes 'free-',
+ * and disambiguates against `taken` with a numeric suffix.
+ * @param {string} id e.g. openrouter/deepseek/deepseek-r1:free
+ * @param {Set<string>} taken alias names already in use
+ * @returns {string} e.g. free-deepseek-deepseek-r1
+ */
+function deriveFreeAlias(id, taken) {
+  const base = 'free-' + id
+    .replace(/^openrouter\//, '')
+    .replace(/:free$/, '')
+    .replace(/[/:]/g, '-')
+    .replace(/-+/g, '-');
+  let name = base;
+  let n = 2;
+  while (taken.has(name)) { name = `${base}-${n++}`; }
+  taken.add(name);
+  return name;
+}
+
+/**
+ * Seed free-model aliases + councils.free from chosen catalog ids.
+ * Single atomic read-modify-write. Reuses an existing alias that already
+ * maps to the same id (idempotent re-runs); never touches config.default.
+ * @param {string[]} pickIds full openrouter/.../...:free ids
+ * @returns {{added: Array<{alias:string, model:string}>, council: string[]}}
+ */
+function seedFreeCouncil(pickIds) {
+  const cfg = loadConfig() || { aliases: {} };
+  if (!cfg.aliases) { cfg.aliases = {}; }
+  const taken = new Set(Object.keys(cfg.aliases));
+  const council = [];
+  const added = [];
+  for (const id of pickIds) {
+    const existing = Object.entries(cfg.aliases).find(([, m]) => m === id);
+    if (existing) { if (!council.includes(existing[0])) { council.push(existing[0]); } continue; }
+    const alias = deriveFreeAlias(id, taken);
+    cfg.aliases[alias] = id;
+    added.push({ alias, model: id });
+    council.push(alias);
+  }
+  if (!cfg.councils) { cfg.councils = {}; }
+  cfg.councils.free = Array.from(new Set(council));
+  saveConfig(cfg);
+  logger.info('Free council seeded', { count: cfg.councils.free.length });
+  return { added, council: cfg.councils.free };
+}
+
 module.exports = {
   addAlias,
   createDefaultConfig,
+  deriveFreeAlias,
   detectApiKeys,
+  runFreeCouncilBranch,
   runInteractiveSetup,
   runReadlineSetup,
   runApiKeySetup,
   seedCatalog,
+  seedFreeCouncil,
 };

package/src/utils/config.js

@@ -273,6 +273,57 @@ function detectFallback(alias, resolvedModel) {
   return !!(val && val.startsWith('openrouter/') && !resolvedModel.startsWith('openrouter/'));
 }
 
+/** @returns {Object<string,string[]>} the councils map (empty if none) */
+function getCouncils() {
+  const config = loadConfig();
+  return (config && config.councils) || {};
+}
+
+/** @param {string} name @returns {string[]|null} council members, or null if absent */
+function getCouncil(name) {
+  return getCouncils()[name] || null;
+}
+
+/**
+ * Expand a saved council into a runnable members list, degrading gracefully.
+ * Each member is resolved to its full model id (alias → id via effective
+ * aliases; a member containing '/' is taken as-is) and that id checked against
+ * the cached catalog. Unresolvable aliases and delisted ids are dropped with a
+ * warning rather than fail-fast-aborting the whole wave. The catalog check is
+ * skipped when the catalog is empty (offline). Returns members RAW (alias or
+ * id) — leg-time validation resolves them again.
+ * @param {string} name
+ * @param {Array<{id:string}>} [catalog]
+ * @returns {{models:string[], dropped:string[]} | {error:string}}
+ */
+function resolveCouncilMembers(name, catalog = []) {
+  const members = getCouncil(name);
+  if (!members) {
+    return { error: `Unknown council '${name}'. Run 'amicus setup' to create one.` };
+  }
+  if (!Array.isArray(members) || members.length === 0) {
+    return { error: `Council '${name}' is empty. Run 'amicus setup' to populate it.` };
+  }
+  const aliases = getEffectiveAliases();
+  const known = new Set((Array.isArray(catalog) ? catalog : []).map(m => m && m.id).filter(Boolean));
+  const models = [];
+  const dropped = [];
+  for (const member of members) {
+    const id = member.includes('/') ? member : aliases[member];
+    if (!id) { dropped.push(member); continue; }                 // alias no longer resolves
+    if (known.size > 0 && !known.has(id)) { dropped.push(member); continue; } // delisted model
+    models.push(member);
+  }
+  if (models.length < 2) {
+    return {
+      error: `Council '${name}' has fewer than 2 usable members` +
+        (dropped.length ? ` (dropped: ${dropped.join(', ')})` : '') +
+        '. Run \'amicus setup\' to refresh it.',
+    };
+  }
+  return { models, dropped };
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -288,4 +339,7 @@ module.exports = {
   formatAliasNames,
   tryResolveModel,
   buildProviderModels,
+  getCouncils,
+  getCouncil,
+  resolveCouncilMembers,
 };

package/src/utils/free-models.js

@@ -0,0 +1,50 @@
+/**
+ * Free OpenRouter model detection (Unit A).
+ *
+ * A free model is an openrouter/* catalog id whose slug ends in ':free'.
+ * The ':free' suffix is OpenRouter's authoritative free-tier marker. A
+ * zero prompt/completion price is deliberately NOT used: the catalog
+ * normalizer keeps only {prompt, completion} and discards request/image
+ * pricing, so a per-request-charged model with prompt:'0' would be
+ * mislabeled. Pure + network-free.
+ */
+'use strict';
+
+/** Offline last-resort free ids (used only when the live catalog is empty). */
+const PINNED_FREE_MODELS = [
+  'openrouter/deepseek/deepseek-r1:free',
+  'openrouter/google/gemini-2.0-flash-exp:free',
+  'openrouter/qwen/qwen3-coder:free',
+];
+
+/** @param {{id?:string}} row @returns {boolean} */
+function isFreeModel(row) {
+  const id = row && typeof row.id === 'string' ? row.id : '';
+  return id.startsWith('openrouter/') && id.endsWith(':free');
+}
+
+/** @param {Array} catalog @returns {Array} free rows, sorted by vendor then id */
+function listFreeModels(catalog) {
+  const rows = (Array.isArray(catalog) ? catalog : []).filter(isFreeModel);
+  return rows.sort((a, b) => {
+    const va = a.id.split('/')[1] || '';
+    const vb = b.id.split('/')[1] || '';
+    return va === vb ? a.id.localeCompare(b.id) : va.localeCompare(vb);
+  });
+}
+
+/** @param {Array} catalog @param {number} n @returns {Array} ≤n free rows, one per vendor */
+function suggestFreeCouncil(catalog, n = 3) {
+  const out = [];
+  const seenVendors = new Set();
+  for (const row of listFreeModels(catalog)) {
+    const vendor = row.id.split('/')[1] || '';
+    if (seenVendors.has(vendor)) { continue; }
+    seenVendors.add(vendor);
+    out.push(row);
+    if (out.length >= n) { break; }
+  }
+  return out;
+}
+
+module.exports = { isFreeModel, listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS };