@polderlabs/bizar 4.4.12 → 4.5.0

package/cli/bin.mjs

@@ -15,9 +15,13 @@
  *   install, audit, init, export, artifact, update, test-gate, service, dash
  */
 import { existsSync } from 'node:fs';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+
+const HOME = homedir();
+const BIZAR_HOME = join(HOME, '.config', 'bizar');
 import chalk from 'chalk';
 import { runInstaller } from './install.mjs';
 import { runAudit } from './audit.mjs';
@@ -93,7 +97,9 @@ function showHelp() {
     dev-unlink          Remove the dev symlink and restore the deployed copy
     doctor              Check the BizarHarness install for health issues
     heads-up <subcommand>  Manage pre-push / pre-release heads-ups (list/check/archive)
-    mod <subcommand>    Manage mods (install/upgrade/list via the dashboard API)
+    minimax <subcommand>   Manage MiniMax Token Plan integration (key + onboarding)
+    usage                 Show compact usage analytics summary (24h rolling)
+    mod <subcommand>       Manage mods (install/upgrade/list via the dashboard API)
 
   Examples:
     bizar install
@@ -191,6 +197,8 @@ function showUpdateHelp() {
 
   Usage:
     bizar update                       Update EVERYTHING (default; auto-kills + restarts)
+    bizar update --check               Only print current vs. latest; do not update
+    bizar update --channel=stable|beta Pick the npm dist-tag (default: stable)
     bizar update --no-restart          Don't auto-restart the dashboard after update
     bizar update --dry-run             Print what would happen, change nothing
     bizar update --force               Override .bizar/PRE_PUSH_NOTES.md blockers
@@ -218,12 +226,20 @@ function showUpdateHelp() {
       --no-restart).
     • Runs 'bizar doctor' after a successful update to catch config
       regressions before opencode tries to start.
+    • With --check: prints the version matrix and release-notes excerpt
+      between current and latest, exits non-zero if an update is available.
 
   Examples:
     bizar update                       Full auto-update (recommended)
+    bizar update --check               Show version matrix + notes, do nothing
+    bizar update --channel=beta        Upgrade to latest beta build
     bizar update --dry-run             Preview what would change
-    bizar update --pick                Pick specific components
     bizar update plugin --no-restart   Plugin-only, leave dashboard alone
+
+  Errors:
+    Network failures (registry offline / DNS) and npm permission issues
+    are surfaced with the raw npm output. The provisioner never silently
+    swallows them — look for the ✗ marker in the step output.
   `);
 }
 
@@ -476,6 +492,323 @@ async function runModCommand(modArgs) {
   }
 }
 
+function showMinimaxHelp() {
+  console.log(`
+  bizar minimax — Manage the MiniMax Token Plan integration
+
+  Usage:
+    bizar minimax status              Show whether the Subscription Key is configured
+                                       and where it was resolved from (auth.json,
+                                       opencode.json, env var, or none).
+    bizar minimax remains              Fetch the live 5-hour + weekly remaining
+                                       quota per model. Shows reset times.
+    bizar minimax test                 Smoke-test the key with a one-shot chat
+                                       completion. Prints the usage block.
+    bizar minimax config <key>         Save a new Subscription Key to
+                                       ~/.local/share/opencode/auth.json. The
+                                       key never leaves this machine.
+    bizar minimax clear                Remove the Subscription Key from
+                                       opencode's auth.json.
+    bizar minimax reset-onboarding    Re-trigger the first-run wizard. Use
+                                       this if the key was changed outside the
+                                       dashboard and you want to re-enter it.
+
+  Flags:
+    --base-url <url>    Override the Token Plan host (default: https://www.minimax.io)
+    --chat-url  <url>    Override the chat-completions host (default: https://api.minimax.io/v1)
+    --yes                 Skip the confirmation prompt on 'clear' and 'reset-onboarding'
+`);
+}
+
+// Find the dashboard's port + password so the CLI can talk to /api/minimax/*.
+function readDashboardConn() {
+  const portFile = join(BIZAR_HOME, 'dashboard.port');
+  const authFile = join(BIZAR_HOME, 'dashboard-secret');
+  let port = 4321;
+  let secret = '';
+  try {
+    if (existsSync(portFile)) {
+      const parsed = parseInt(readFileSync(portFile, 'utf8').trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) port = parsed;
+    }
+  } catch { /* ignore */ }
+  try {
+    if (existsSync(authFile)) secret = readFileSync(authFile, 'utf8').trim();
+  } catch { /* ignore */ }
+  return { port, secret };
+}
+
+async function minimaxApi(path, opts = {}) {
+  const { port, secret } = readDashboardConn();
+  const url = `http://127.0.0.1:${port}${path}`;
+  const headers = { 'content-type': 'application/json', accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${secret}`).toString('base64')}`;
+  const method = (opts.method || 'GET').toUpperCase();
+  try {
+    const resp = await fetch(url, { method, headers, body: opts.body ? JSON.stringify(opts.body) : undefined });
+    const text = await resp.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+    if (!resp.ok) {
+      return { ok: false, error: `http_${resp.status}`, message: data?.message || data?.error || resp.statusText, status: resp.status };
+    }
+    return { ok: true, status: resp.status, data };
+  } catch (err) {
+    return { ok: false, error: 'network_error', message: err && err.message ? err.message : String(err) };
+  }
+}
+
+async function runMinimaxCommand(minimaxArgs) {
+  const sub = minimaxArgs[0];
+  const flags = minimaxArgs.slice(1).filter((a) => a.startsWith('-'));
+  const positional = minimaxArgs.slice(1).filter((a) => !a.startsWith('-'));
+  const yes = flags.includes('--yes') || flags.includes('-y');
+
+  if (!sub || sub === '--help' || sub === '-h' || flags.includes('--help') || flags.includes('-h')) {
+    showMinimaxHelp();
+    return;
+  }
+
+  if (sub === 'status') {
+    const r = await minimaxApi('/api/minimax/status');
+    if (!r.ok) {
+      console.error(chalk.red(`  ✗ ${r.message || r.error}`));
+      process.exit(1);
+    }
+    const s = r.data;
+    console.log('');
+    console.log(chalk.bold('  MiniMax Token Plan status'));
+    console.log('');
+    console.log(`    ${chalk.dim('configured:')}    ${s.configured ? chalk.green('yes') : chalk.red('no')}`);
+    console.log(`    ${chalk.dim('key source:')}    ${chalk.cyan(s.source)}`);
+    if (s.apiKeyHint) console.log(`    ${chalk.dim('key hint:')}      ${s.apiKeyHint}`);
+    console.log(`    ${chalk.dim('group id:')}     ${s.groupId}`);
+    console.log(`    ${chalk.dim('token host:')}   ${s.tokenBaseUrl}`);
+    console.log(`    ${chalk.dim('chat host:')}    ${s.chatBaseUrl}`);
+    console.log(`    ${chalk.dim('key format:')}   ${s.keyPatternValid === true ? chalk.green('ok') : s.keyPatternValid === false ? chalk.red('unexpected prefix') : chalk.dim('n/a')}`);
+    console.log('');
+    if (s.cache) {
+      console.log(`    ${chalk.dim('cached:')}         ${new Date(s.cache.fetchedAt).toLocaleString()} (${s.cache.modelCount} models)`);
+    } else {
+      console.log(`    ${chalk.dim('cached:')}         none yet — run \`bizar minimax remains\` to populate`);
+    }
+    return;
+  }
+
+  if (sub === 'remains') {
+    const r = await minimaxApi('/api/minimax/remains');
+    if (!r.ok) {
+      console.error(chalk.red(`  ✗ ${r.message || r.error}`));
+      process.exit(1);
+    }
+    if (!r.data?.ok) {
+      console.error(chalk.red(`  ✗ ${r.data?.message || r.data?.error || 'unknown'}`));
+      process.exit(1);
+    }
+    const data = r.data;
+    console.log('');
+    console.log(chalk.bold(`  MiniMax Token Plan quota  (${new Date(data.fetchedAt).toLocaleString()})`));
+    if (data.apiKeyHint) console.log(chalk.dim(`  Key: ${data.apiKeyHint} · source: ${data.keySource} · group: ${data.groupId}`));
+    console.log('');
+    for (const m of data.models || []) {
+      const five = m.current_interval_remaining_percent;
+      const week = m.current_weekly_remaining_percent;
+      const fiveBar = '█'.repeat(Math.round(five / 5)) + '░'.repeat(20 - Math.round(five / 5));
+      const weekBar = '█'.repeat(Math.round(week / 5)) + '░'.repeat(20 - Math.round(week / 5));
+      const fiveColor = five >= 75 ? chalk.green : five >= 25 ? chalk.yellow : chalk.red;
+      const weekColor = week >= 75 ? chalk.green : week >= 25 ? chalk.yellow : chalk.red;
+      console.log(`    ${chalk.bold(m.model_name)}`);
+      console.log(`      ${chalk.dim('5h:')}    ${fiveColor(five + '%'.padStart(4))} ${fiveBar}  resets in ${m.intervalResetInHuman}`);
+      console.log(`      ${chalk.dim('week:')}  ${weekColor(week + '%'.padStart(4))} ${weekBar}  resets in ${m.weeklyResetInHuman}`);
+      console.log('');
+    }
+    return;
+  }
+
+  if (sub === 'test') {
+    const prompt = positional[0] || 'Reply with the single word: pong';
+    const r = await minimaxApi('/api/minimax/test', {
+      method: 'POST',
+      body: { prompt, model: 'MiniMax-M3', maxTokens: 32 },
+    });
+    if (!r.ok) {
+      console.error(chalk.red(`  ✗ ${r.message || r.error}`));
+      process.exit(1);
+    }
+    const data = r.data;
+    if (!data?.ok) {
+      console.error(chalk.red(`  ✗ ${data?.message || data?.error || 'unknown'}`));
+      process.exit(1);
+    }
+    console.log('');
+    console.log(chalk.green('  ✓ Key works'));
+    console.log(`    ${chalk.dim('model:')}     ${data.model}`);
+    console.log(`    ${chalk.dim('finish:')}    ${data.finishReason}`);
+    if (data.content) console.log(`    ${chalk.dim('content:')}    ${JSON.stringify(data.content.slice(0, 80))}${data.content.length > 80 ? '…' : ''}`);
+    if (data.usage) {
+      console.log(`    ${chalk.dim('usage:')}      total=${data.usage.total_tokens} prompt=${data.usage.prompt_tokens} completion=${data.usage.completion_tokens}`);
+    }
+    return;
+  }
+
+  if (sub === 'config' || sub === 'set') {
+    const key = positional[0];
+    if (!key) {
+      console.error(chalk.red('  ✗ Missing key. Usage: bizar minimax config <sk-cp-…>'));
+      process.exit(1);
+    }
+    if (!/^sk-(cp|ant|or)-[A-Za-z0-9_-]{20,}$/.test(key)) {
+      console.error(chalk.red('  ✗ Key does not look like a MiniMax key (expected sk-cp-…, sk-ant-…, or sk-or-… prefix)'));
+      process.exit(1);
+    }
+    console.log(chalk.dim('  Saving to opencode auth.json…'));
+    const r = await minimaxApi('/api/minimax/onboarding/save-key', {
+      method: 'POST',
+      body: { key, groupId: 'default' },
+    });
+    if (!r.ok) {
+      console.error(chalk.red(`  ✗ ${r.message || r.error}`));
+      process.exit(1);
+    }
+    console.log(chalk.green(`  ✓ Saved to ${r.data?.path}`));
+    console.log(`    ${chalk.dim('key hint:')} ${r.data?.apiKeyHint}`);
+    return;
+  }
+
+  if (sub === 'clear' || sub === 'remove') {
+    if (!yes) {
+      console.log(chalk.yellow(`  ⚠ This will remove the MiniMax Subscription Key from opencode's auth.json.`));
+      console.log(chalk.dim('  Continue? [y/N]'));
+      // simple readline confirmation
+      const buf = [];
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (c) => { buf.push(c); if (c.includes('\n')) process.stdin.pause(); });
+      await new Promise((resolve) => process.stdin.once('close', resolve));
+      const answer = buf.join('').trim().toLowerCase();
+      if (answer !== 'y' && answer !== 'yes') {
+        console.log(chalk.dim('  Cancelled.'));
+        return;
+      }
+    }
+    // We don't have a "clear key" route; instead write an empty auth.json
+    // entry. We piggyback on the onboarding save-key by saving an empty
+    // marker isn't allowed — use the providers-store side instead. For
+    // now, recommend using the dashboard's "clear" button. But the
+    // simplest CLI path is to write auth.json directly.
+    const authFile = join(HOME, '.local', 'share', 'opencode', 'auth.json');
+    let auth = {};
+    try {
+      if (existsSync(authFile)) auth = JSON.parse(readFileSync(authFile, 'utf8'));
+    } catch { /* ignore */ }
+    if (auth.minimax) {
+      delete auth.minimax;
+      writeFileSync(authFile, JSON.stringify(auth, null, 2) + '\n', 'utf8');
+      console.log(chalk.green('  ✓ MiniMax key removed from auth.json'));
+    } else {
+      console.log(chalk.dim('  No MiniMax key was configured.'));
+    }
+    return;
+  }
+
+  if (sub === 'reset-onboarding' || sub === 'reset') {
+    if (!yes) {
+      console.log(chalk.yellow('  ⚠ This will re-trigger the first-run MiniMax onboarding wizard.'));
+      console.log(chalk.dim('  Continue? [y/N]'));
+      const buf = [];
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (c) => { buf.push(c); if (c.includes('\n')) process.stdin.pause(); });
+      await new Promise((resolve) => process.stdin.once('close', resolve));
+      const answer = buf.join('').trim().toLowerCase();
+      if (answer !== 'y' && answer !== 'yes') {
+        console.log(chalk.dim('  Cancelled.'));
+        return;
+      }
+    }
+    // Reset via the dashboard API.
+    const r = await minimaxApi('/api/minimax/onboarding', {
+      method: 'POST',
+      body: { dismissedAt: null },
+    });
+    if (!r.ok) {
+      console.error(chalk.red(`  ✗ ${r.message || r.error}`));
+      process.exit(1);
+    }
+    console.log(chalk.green('  ✓ Onboarding wizard will show on next dashboard load'));
+    return;
+  }
+
+  console.error(chalk.red(`  ✗ Unknown minimax subcommand: ${sub}`));
+  showMinimaxHelp();
+  process.exit(1);
+}
+
+// ── Usage subcommand ───────────────────────────────────────────────────────
+
+function showUsageHelp() {
+  console.log(`
+  bizar usage — Show compact usage analytics summary
+
+  Usage:
+    bizar usage [24h|7d|30d]   Show summary for the given range (default: 24h)
+
+  Examples:
+    bizar usage
+    bizar usage 7d
+    bizar usage 30d
+  `);
+}
+
+async function runUsageCommand(args) {
+  const range = (args[0] && ['24h', '7d', '30d'].includes(args[0])) ? args[0] : '24h';
+  const { port, secret } = readDashboardConn();
+  const url = `http://127.0.0.1:${port}/api/usage?range=${range}`;
+  const headers = { accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${secret}`).toString('base64')}`;
+  try {
+    const resp = await fetch(url, { method: 'GET', headers });
+    const text = await resp.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+    if (!resp.ok || !data) {
+      console.error(chalk.red(`  ✗ Failed to load usage data: ${data?.message ?? resp.statusText}`));
+      process.exit(1);
+    }
+    const t = data.totals;
+    console.log('');
+    console.log(chalk.bold(`  Usage summary — ${range} (from JSONL store)`));
+    console.log('');
+    console.log(`    ${chalk.dim('Requests:')}   ${t.requests.toLocaleString()}  (${t.errors} errors)`);
+    console.log(`    ${chalk.dim('Tokens:')}     ${t.totalTokens.toLocaleString()} total  (${t.promptTokens.toLocaleString()} prompt · ${t.completionTokens.toLocaleString()} completion)`);
+    console.log(`    ${chalk.dim('Cached:')}     ${t.cachedTokens.toLocaleString()} tokens`);
+    console.log(`    ${chalk.dim('Reasoning:')}  ${t.reasoningTokens.toLocaleString()} tokens`);
+    console.log(`    ${chalk.dim('Avg latency:')} ${t.avgLatencyMs}ms  (p95: ${t.p95LatencyMs}ms)`);
+    if (t.costEstimate > 0) {
+      console.log(`    ${chalk.dim('Est. cost:')}   $${t.costEstimate.toFixed(4)} USD`);
+    }
+    console.log('');
+    if (data.daily && data.daily.length > 0) {
+      console.log(chalk.dim(`  ${chalk.bold('Daily breakdown')}`));
+      for (const day of data.daily.slice(-7)) {
+        const barLen = Math.round((day.totalTokens / Math.max(...data.daily.map(d => d.totalTokens))) * 20);
+        const bar = '█'.repeat(barLen) + '░'.repeat(20 - barLen);
+        console.log(`    ${day.date}  ${bar}  ${day.totalTokens.toLocaleString()} tok  ${day.requests} req`);
+      }
+    }
+    if (data.perModel && data.perModel.length > 0) {
+      console.log('');
+      console.log(chalk.dim(`  ${chalk.bold('Per model')}`));
+      for (const m of data.perModel.slice(0, 8)) {
+        console.log(`    ${m.modelId.padEnd(24)} ${String(m.requests).padStart(6)} req  ${String(m.totalTokens).padStart(8)} tok`);
+      }
+    }
+    console.log('');
+  } catch (err) {
+    console.error(chalk.red(`  ✗ Network error: ${err && err.message ? err.message : String(err)}`));
+    console.error(chalk.dim('    Is the dashboard running? Run `bizar dash start` first.'));
+    process.exit(1);
+  }
+}
+
 function showDashHelp() {
   console.log(`
   bizar dash — Manage the Bizar dashboard
@@ -823,6 +1156,14 @@ async function main() {
     // (the dashboard owns the actual mod install/upgrade logic and the
     // opencode-config install/uninstall of instruction files).
     await runModCommand(args.slice(1));
+  } else if (args[0] === 'minimax') {
+    // v4.5.0 — MiniMax Token Plan integration CLI. Status, remains,
+    // test, config, clear, reset-onboarding. All commands shell out
+    // to the dashboard's /api/minimax/* routes.
+    await runMinimaxCommand(args.slice(1));
+  } else if (args[0] === 'usage') {
+    // v4.6.0 — Compact usage analytics summary from the JSONL store.
+    await runUsageCommand(args.slice(1));
   } else if (args[0] === 'dash' || args[0] === 'dashboard') {
     // `bizar dashboard` is a deprecated alias for `bizar dash`
     if (args[0] === 'dashboard') {

package/cli/provision.mjs

@@ -1121,17 +1121,131 @@ export async function runProvision(opts = {}) {
  * `cli/update.mjs` (the bin.mjs-facing module) can stay a thin shim
  * without duplicating flag parsing. Accepts the legacy `subargs: string[]`
  * shape so any external callers keep working.
+ *
+ * Recognized flags (v4.4.14):
+ *   --check           Only print current vs. latest, don't update.
+ *   --channel <name>  npm dist-tag (stable | beta). Default: stable.
+ *   --no-restart      Don't auto-restart the dashboard after update.
+ *   --dry-run         Print what would happen, change nothing.
+ *   --force           Override .bizar/PRE_PUSH_NOTES.md blockers.
+ *   --yes / -y        Same as --force, but named for one-line scripts.
+ *   --with-mods <csv> Opt-in: install specific mods as part of the run.
+ *
+ * With --check, we print the version matrix and release notes between
+ * current and latest, then return without touching the system.
  */
 export async function runUpdate(subargs = []) {
+  const args = Array.isArray(subargs) ? subargs : [];
+  const checkOnly = args.includes('--check');
+
+  // --channel <name> — extract a single value. Accepts both
+  //   --channel=beta     (equals form)
+  //   --channel beta     (separate-arg form)
+  // Default: 'stable'.
+  let channel = 'stable';
+  const eqArg = args.find((a) => a.startsWith('--channel='));
+  if (eqArg) {
+    const value = eqArg.slice('--channel='.length);
+    if (value === 'stable' || value === 'beta') {
+      channel = value;
+    } else {
+      console.log(chalk.yellow(`  ⚠ Unknown channel "${value}". Using "stable".`));
+    }
+  } else {
+    const channelIdx = args.indexOf('--channel');
+    if (channelIdx >= 0) {
+      const value = args[channelIdx + 1];
+      if (!value || value.startsWith('--')) {
+        console.log(chalk.yellow('  ⚠ --channel needs a value (stable | beta). Using "stable".'));
+      } else if (value !== 'stable' && value !== 'beta') {
+        console.log(chalk.yellow(`  ⚠ Unknown channel "${value}". Using "stable".`));
+      } else {
+        channel = value;
+      }
+    }
+  }
+
+  if (checkOnly) {
+    return runCheck(channel);
+  }
+
+  // Pass channel through to the provisioner. The provisioner does the
+  // actual npm install; channel maps to the npm dist-tag suffix.
   return runProvision({
     mode: 'update',
-    dryRun: subargs.includes('--dry-run'),
-    force: subargs.includes('--force'),
-    yes: subargs.includes('--yes') || subargs.includes('-y'),
-    restart: !subargs.includes('--no-restart'),
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    yes: args.includes('--yes') || args.includes('-y'),
+    restart: !args.includes('--no-restart'),
+    channel,
   });
 }
 
+/**
+ * v4.4.14 — `bizar update --check`. Print the version matrix and (if
+ * a newer version exists) the release notes between current and latest.
+ * Does NOT touch the system. Exits non-zero when an update is available
+ * so callers can use it in CI / pre-flight scripts.
+ */
+export async function runCheck(channel = 'stable') {
+  console.log(chalk.bold.hex('#a855f7')('\n  ᚦ BIZAR UPDATE — CHECK ᚦ\n'));
+  console.log(chalk.dim(`  Channel: ${channel}\n`));
+
+  const state = detectState();
+  printVersionMatrix([
+    { label: 'opencode-ai', current: state.opencodeCli.version, latest: state.opencodeCli.latest },
+    { label: PKG_MAIN, current: state.pkgVersion, latest: state.pkgLatest },
+  ]);
+
+  const cur = state.pkgVersion;
+  const lat = state.pkgLatest;
+  if (cur && lat && cur !== lat) {
+    console.log(chalk.dim(`\n  Release notes (${cur} → ${lat}):`));
+    const notes = fetchReleaseNotes(PKG_MAIN, cur, lat).catch((err) => {
+      console.log(chalk.dim(`    (could not fetch: ${err.message || err})`));
+      return null;
+    });
+    const text = await notes;
+    if (text) {
+      // Trim to a sensible cap (first 30 lines) so the console stays
+      // readable; the full notes are one `npm view` call away.
+      const lines = text.split(/\r?\n/).slice(0, 30);
+      for (const line of lines) console.log(`    ${line}`);
+      if (lines.length === 30) console.log(chalk.dim('    ... (truncated; run `npm view @polderlabs/bizar` for full)'));
+    }
+    console.log(chalk.yellow(`\n  ⤵ Run \`bizar update\` to apply.\n`));
+    // Non-zero exit so scripts can detect the update-available case.
+    return { ok: true, updateAvailable: true, channel };
+  }
+
+  console.log(chalk.green('\n  ✓ Already on the latest version.\n'));
+  return { ok: true, updateAvailable: false, channel };
+}
+
+/**
+ * Fetch the release notes between two versions from the npm registry.
+ * Returns a plain-text summary (the registry's "description" field for
+ * the latest version), or null on any failure. Never throws — failures
+ * are surfaced to the caller as null so the check command stays useful
+ * offline.
+ */
+async function fetchReleaseNotes(pkg, _from, _to) {
+  // The npm registry does not expose a structured per-version release-
+  // notes field. The best we can do is `npm view <pkg> description`
+  // which is the package's README excerpt. We surface that as "notes".
+  try {
+    const { execFileSync } = await import('node:child_process');
+    const out = execFileSync('npm', ['view', pkg, 'description'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10000,
+      encoding: 'utf8',
+    }).toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * CLI-flag-parsing entrypoint for `bizar install`. Mirrors `runUpdate`
  * so `cli/install.mjs` can stay a thin shim too.

package/config/agents/_shared/SKILLS.md

@@ -0,0 +1,109 @@
+# Bizar Skills - Reference
+
+Skills are specialized instruction sets that agents load before working on specific domains. They live as `SKILL.md` files in well-known directories and are injected into agent context when relevant.
+
+## What Skills Are
+
+A skill is a Markdown file with YAML frontmatter. The frontmatter declares a `description` that the agent matcher uses to decide when to load the skill. The body contains domain-specific knowledge, patterns, gotchas, and code examples.
+
+Example `SKILL.md`:
+
+```yaml
+---
+name: my-skill
+description: Use when working with X. Covers Y and Z.
+---
+# My Skill
+
+## When to use
+...
+
+## Key concepts
+...
+
+## Code examples
+...
+
+## Common gotchas
+...
+```
+
+## Where Skills Live
+
+| Path | Source | Priority | Notes |
+|---|---|---|---|
+| `~/.opencode/skills/<name>/SKILL.md` | User / System | Highest | User-overridable builtins |
+| `~/.agents/skills/<name>/SKILL.md` | User-added | High | Installed via `skills add` |
+| `bizar-dash/skills/<name>/SKILL.md` | Shipped | Medium | Ships with BizarHarness package |
+| `.agents/skills/<name>/SKILL.md` | Project | Low | Project-local skills |
+| `.opencode/skills/<name>/SKILL.md` | Project | Lowest | Project-local skills |
+
+When the same skill name appears in multiple places, the highest-priority source wins.
+
+## Discovering Skills
+
+Use the `skills` CLI:
+
+```bash
+# List installed skills
+skills list --json
+
+# Search for a skill
+skills search "react"
+
+# Install from a repository
+skills add owner/repo -s "skill-name" -y
+```
+
+Known repositories:
+- `vercel-labs/skills` - find-skills, skill-creator, general tools
+- `vercel-labs/agent-skills` - React, Next.js, frontend performance
+- `shadcn/ui` - shadcn/ui components
+- `supabase/agent-skills` - Postgres, Auth, Edge Functions
+- `mattpocock/skills` - TypeScript, TDD
+- `anthropics/skills` - Claude patterns, agents
+- `leonxlnx/taste-skill` - design, UI/UX
+
+## Shipped Bizar Skills
+
+These skills ship with BizarHarness and are available immediately:
+
+| Skill | Description |
+|---|---|
+| `bizar` | Norse-pantheon multi-agent system, Odin routing, agent tiers |
+| `agent-baseline` | Always-on rules: Semble, Skills CLI, loop guard, copyright |
+| `self-improvement` | .bizar/AGENTS_SELF_IMPROVEMENT.md protocol |
+| `obsidian` | Bizar Memory Service (Obsidian + Git + LightRAG) |
+| `minimax` | MiniMax provider, multi-key rotation, usage tracking |
+| `providers` | Provider subsystem, backup keys, auto-add wizard |
+| `chat` | Chat + opencode session integration |
+| `usage` | Token usage monitoring, cost estimation, MiniMax usage dashboard |
+| `skills-cli` | skills CLI reference, skill repos, discovery protocol |
+| `lightrag` | LightRAG integration, opencode-free defaults, indexing |
+| `sdk` | @polderlabs/bizar-sdk on Cloudflare Workers |
+
+## Skill Loading
+
+Agents check skill relevance at dispatch time. You can also load a skill explicitly in conversation using the `skill` tool:
+
+```
+Load the `minimax` skill before we discuss multi-key rotation.
+```
+
+## Adding a Project Skill
+
+Create a skill directory in your project:
+
+```bash
+mkdir -p .agents/skills/my-project-skill
+cat > .agents/skills/my-project-skill/SKILL.md << 'EOF'
+---
+name: my-project-skill
+description: Use when working on my project's specific domain X.
+---
+# My Project Skill
+...
+EOF
+```
+
+Project skills are picked up automatically on next session start.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "4.4.12",
+  "version": "4.5.0",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, opencode plugin, and typed SDK.",
   "type": "module",
   "bin": {