@polderlabs/bizar 3.7.3 → 3.9.0

package/README.md

@@ -65,18 +65,18 @@
 ### Agents
 
 | Agent | Rune | Model | Cost | Role |
-|---|---|---|---|---|---|
-| **Odin** | ᛟ | MiniMax-M3 | $0.30/M · $1.20/M out | Primary router — never executes, only delegates |
+|---|---|---|---|---|
+| **Odin** | ᛟ | OpenRouter minimax-m3 | $0.30/M · $1.20/M out | Primary router — never executes, only delegates |
 | **Frigg** | ᚠ | DeepSeek V4 Flash | **Free** | Read-only Q&A — ask questions, get answers, never modifies |
 | **Vör** | ᛢ | DeepSeek V4 Flash | **Free** | Clarifies ambiguous requests — asks questions until task is well-defined |
 | **Mimir** | ᛗ | DeepSeek V4 Flash | **Free** | Research & codebase exploration (Semble-first) |
 | **Heimdall** | ᚹ | DeepSeek V4 Flash | **Free** | Simple tasks, quick edits, file operations |
-| **Hermod** | ᚱ | MiniMax-M2.7 | $0.30/M · $1.20/M out | Git & GitHub operations (commit, PR, merge, rebase) |
-| **Thor** | ᚦ | MiniMax-M2.7 | $0.30/M · $1.20/M out | Moderate implementation, debugging, refactoring |
-| **Baldr** | ᛒ | MiniMax-M2.7 | $0.30/M · $1.20/M out | UI/UX design system (DESIGN.md plans, visual audits) |
-| **Tyr** | ᛏ | MiniMax-M3 | $0.30/M · $1.20/M out | Complex implementation, architecture, deep debugging |
+| **Hermod** | ᚱ | OpenRouter minimax-m2.7 | $0.30/M · $1.20/M out | Git & GitHub operations (commit, PR, merge, rebase) |
+| **Thor** | ᚦ | OpenRouter minimax-m2.7 | $0.30/M · $1.20/M out | Moderate implementation, debugging, refactoring |
+| **Baldr** | ᛒ | OpenRouter minimax-m2.7 | $0.30/M · $1.20/M out | UI/UX design system (DESIGN.md plans, visual audits) |
+| **Tyr** | ᛏ | OpenRouter minimax-m3 | $0.30/M · $1.20/M out | Complex implementation, architecture, deep debugging |
 | **Vidarr** | ᛉ | GPT-5.5 | Subscription | Last resort — GPT-5.5 |
-| **Forseti** | ᚨ | MiniMax-M3 | $0.30/M · $1.20/M out | Adversarial plan reviewer (edit: deny, audit-only) |
+| **Forseti** | ᚨ | OpenRouter minimax-m3 | $0.30/M · $1.20/M out | Adversarial plan reviewer (edit: deny, audit-only) |
 
 ---
 
@@ -257,13 +257,11 @@ After installation, run `/connect` in opencode to add API keys:
 | Provider | Models | Auth |
 |---|---|---|
 | **OpenCode Zen** | `opencode/deepseek-v4-flash-free` | Free API key from [opencode.ai](https://opencode.ai) — create account, get key, no charges |
-| **minimax.io** | `minimax/MiniMax-M2.7`, `minimax/MiniMax-M3` | API key from [minimax.io](https://minimax.io) — **no `baseURL` override** |
+| **OpenRouter** | `openrouter/minimax-m2.7`, `openrouter/minimax-m3` | API key from [openrouter.ai](https://openrouter.ai) |
 | **OpenAI** | `openai/gpt-5.5` | ChatGPT subscription (OAuth) |
 
 Then run `/models` to verify connectivity.
 
-> **Note:** Do not set `baseURL` on the minimax provider. The ai-sdk minimax provider uses its own default URL internally. Setting one causes 404 errors.
-
 ---
 
 ## 🧭 Routing

package/cli/audit.mjs

@@ -78,8 +78,8 @@ export async function runAudit() {
       const model = modelMatch[1].trim();
       const validModels = [
         'opencode/deepseek-v4-flash-free',
-        'minimax/MiniMax-M2.7',
-        'minimax/MiniMax-M3',
+        'openrouter/minimax-m2.7',
+        'openrouter/minimax-m3',
         'openai/gpt-5.5',
       ];
       if (!validModels.includes(model)) {

package/cli/bin.mjs

@@ -28,6 +28,7 @@ import { runInit } from './init.mjs';
 import { runExport } from './export.mjs';
 import runPlan from './plan.mjs';
 import { runUpdate } from './update.mjs';
+import { runGraph } from './graph.mjs';
 import { ensureSetup, checkSetupStatus } from './bootstrap.mjs';
 
 const args = process.argv.slice(2);
@@ -86,6 +87,7 @@ function showHelp() {
     bizar init                  Initialize .bizar/ in current project
     bizar export [target]       Export agents/rules to another harness
     bizar plan <subcommand>     Manage visual plans
+    bizar graph                 Per-project knowledge graph (powered by graphify)
     bizar test-gate             Detect & run the project's test suite
     bizar update                Update opencode, bizar, and/or bizar-plugin
     bizar service               Manage the background service daemon
@@ -126,7 +128,29 @@ function showInitHelp() {
 
   Description:
     Detects the project stack, creates .bizar/PROJECT.md and
-    .bizar/AGENTS_SELF_IMPROVEMENT.md, and installs relevant skills.
+    .bizar/AGENTS_SELF_IMPROVEMENT.md, installs relevant skills,
+    and builds the per-project knowledge graph in .bizar/graph/
+    (requires graphify — pip install graphifyy — otherwise the
+    graph step is skipped gracefully).
+  `);
+}
+
+function showGraphHelp() {
+  console.log(`
+  bizar graph — Per-project knowledge graph (powered by graphify)
+
+  Usage:
+    bizar graph build              # full build of the project graph
+    bizar graph update             # incremental rebuild
+    bizar graph query "<text>"     # query the graph
+    bizar graph path "<A>" "<B>"   # shortest path between concepts
+    bizar graph explain "<X>"      # all nodes related to a concept
+    bizar graph watch              # watch for changes and rebuild
+    bizar graph status             # show graph path, size, node/edge/community counts
+    bizar graph install            # install graphify + drop OpenCode skill/plugin
+
+  Requires Python 3.10+ and \`graphify\` (pip install graphifyy).
+  Graph data lives in .bizar/graph/ inside this project.
   `);
 }
 
@@ -376,6 +400,9 @@ async function main() {
   } else if (args[0] === 'init') {
     if (isHelpRequest) showInitHelp();
     else await runInit(process.cwd());
+  } else if (args[0] === 'graph') {
+    if (isHelpRequest) showGraphHelp();
+    else await runGraph(args.slice(1));
   } else if (args[0] === 'export') {
     if (isHelpRequest) showExportHelp();
     else await runExport(parseFlag('--target'));

package/cli/graph.mjs

@@ -0,0 +1,337 @@
+/**
+ * cli/graph.mjs
+ *
+ * `bizar graph` — Per-project knowledge graph powered by graphify.
+ * Graph data lives in .bizar/graph/ inside the project.
+ */
+
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+export const GRAPH_DIR = '.bizar/graph';
+export const GRAPHIFY_OUT_ENV = 'GRAPHIFY_OUT';
+
+// ── Python detection ───────────────────────────────────────────────────────────
+
+/**
+ * Find a Python 3 interpreter on PATH.
+ * Returns the absolute path string, or null if none found.
+ */
+export function findPython() {
+  // Prefer python3, fall back to python
+  for (const name of ['python3', 'python']) {
+    try {
+      const result = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0 && result.stdout.includes('Python 3')) {
+        return name;
+      }
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Check whether graphify is available via `python3 -m graphify --version`.
+ * Returns true if available, false otherwise.
+ */
+function checkGraphify(python) {
+  try {
+    const result = spawnSync(python, ['-m', 'graphify', '--version'], {
+      encoding: 'utf8',
+      timeout: 10000,
+      env: { ...process.env },
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ── Graph stats parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse .bizar/graph/graph.json and return stats.
+ * Returns null if the file does not exist or cannot be parsed.
+ *
+ * Expected NetworkX node-link JSON shape:
+ * {
+ *   "directed": false,
+ *   "multigraph": false,
+ *   "graph": {},
+ *   "nodes": [{ "id": "...", "community": 0, ... }],
+ *   "links": [{ "source": "...", "target": "...", ... }]
+ * }
+ */
+export function parseGraphStats(jsonPath) {
+  if (!existsSync(jsonPath)) return null;
+  try {
+    const content = readFileSync(jsonPath, 'utf8');
+    const graph = JSON.parse(content);
+
+    const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+    const links = Array.isArray(graph.links) ? graph.links : [];
+
+    // Count unique community values among nodes
+    const communitySet = new Set();
+    for (const node of nodes) {
+      if (node.community !== undefined && node.community !== null) {
+        communitySet.add(node.community);
+      }
+    }
+
+    const stats = statSync(jsonPath);
+
+    return {
+      nodes: nodes.length,
+      edges: links.length,
+      communities: communitySet.size,
+      lastModified: stats.mtime.toISOString(),
+      sizeBytes: stats.size,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Gitignore guard ────────────────────────────────────────────────────────────
+
+const GRAPH_GITIGNORE = `cache/
+.graphify_python
+cost.json
+`;
+
+/**
+ * Ensure .bizar/graph/.gitignore exists so heavy cache artefacts are not committed.
+ * Called after a successful first build.
+ */
+function ensureGitignore(graphDir) {
+  const gitignorePath = join(graphDir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, GRAPH_GITIGNORE, 'utf8');
+  }
+}
+
+// ── Run helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Spawn a graphify command with GRAPHIFY_OUT set to GRAPH_DIR.
+ * Streams stdout/stderr to the terminal. Returns the exit code.
+ */
+function runGraphify(python, subArgs, extraEnv = {}) {
+  const env = { ...process.env, [GRAPHIFY_OUT_ENV]: GRAPH_DIR };
+  const result = spawnSync(python, ['-m', 'graphify', ...subArgs], {
+    stdio: 'inherit',
+    env,
+    timeout: 0, // no timeout — user may run long builds
+  });
+  return result.status ?? 1;
+}
+
+// ── Subcommand handlers ────────────────────────────────────────────────────────
+
+async function cmdBuild(python) {
+  console.log(chalk.dim('  Running full graphify pipeline...'));
+  const code = runGraphify(python, ['.']);
+  if (code === 0) {
+    ensureGitignore(GRAPH_DIR);
+    console.log(chalk.green(`\n  ✓ Graph built → ${GRAPH_DIR}/\n`));
+  }
+  return code;
+}
+
+async function cmdUpdate(python) {
+  console.log(chalk.dim('  Running incremental graph update...'));
+  return runGraphify(python, ['.', '--update']);
+}
+
+async function cmdQuery(python, query) {
+  if (!query) {
+    console.log(chalk.red('  Error: query text required.'));
+    console.log(chalk.dim('  Usage: bizar graph query "<search term>"\n'));
+    return 1;
+  }
+  return runGraphify(python, ['query', query]);
+}
+
+async function cmdPath(python, a, b) {
+  if (!a || !b) {
+    console.log(chalk.red('  Error: two concept names required.'));
+    console.log(chalk.dim('  Usage: bizar graph path "<A>" "<B>"\n'));
+    return 1;
+  }
+  return runGraphify(python, ['path', a, b]);
+}
+
+async function cmdExplain(python, concept) {
+  if (!concept) {
+    console.log(chalk.red('  Error: concept name required.'));
+    console.log(chalk.dim('  Usage: bizar graph explain "<X>"\n'));
+    return 1;
+  }
+  return runGraphify(python, ['explain', concept]);
+}
+
+async function cmdWatch(python) {
+  console.log(chalk.dim('  Starting graphify watch mode (Ctrl-C to stop)...'));
+  return runGraphify(python, ['.', '--watch']);
+}
+
+async function cmdStatus() {
+  const graphJsonPath = join(GRAPH_DIR, 'graph.json');
+  const stats = parseGraphStats(graphJsonPath);
+
+  console.log(chalk.bold.hex('#10b981')('\n  ᛗ BIZAR GRAPH STATUS ᛗ\n'));
+  console.log(`  Path:       ${GRAPH_DIR}/`);
+
+  if (!existsSync(GRAPH_DIR)) {
+    console.log(`  Exists:     ${chalk.yellow('no')}  (run \`bizar graph build\` first)`);
+    console.log();
+    return 0;
+  }
+
+  if (!stats) {
+    console.log(`  Exists:     ${chalk.yellow('no graph.json found')}`);
+    console.log();
+    return 0;
+  }
+
+  console.log(`  Exists:     ${chalk.green('yes')}`);
+  console.log(`  Size:       ${(stats.sizeBytes / 1024).toFixed(1)} KB`);
+  console.log(`  Last built: ${stats.lastModified}`);
+  console.log(`  Nodes:      ${stats.nodes}`);
+  console.log(`  Edges:      ${stats.edges}`);
+  console.log(`  Communities:${stats.communities}`);
+  console.log();
+  return 0;
+}
+
+async function cmdInstall() {
+  const python = findPython();
+  if (!python) {
+    console.error(chalk.red('  Error: graphify requires Python 3.10+.'));
+    console.error(chalk.dim('  Install Python from https://python.org or via your package manager, then re-run.\n'));
+    return 1;
+  }
+
+  console.log(chalk.dim('  Installing graphify via pip...\n'));
+
+  // pip install graphifyy
+  console.log(chalk.dim('  $ pip install graphifyy'));
+  let result = spawnSync('pip', ['install', 'graphifyy'], { stdio: 'inherit' });
+  if (result.status !== 0) {
+    console.log(chalk.red('  ✗ pip install graphifyy failed.\n'));
+    return 1;
+  }
+
+  // graphify install --platform opencode --project
+  console.log(chalk.dim('\n  $ graphify install --platform opencode --project'));
+  result = spawnSync('graphify', ['install', '--platform', 'opencode', '--project'], {
+    stdio: 'inherit',
+  });
+  if (result.status !== 0) {
+    console.log(chalk.red('  ✗ graphify install failed.\n'));
+    return 1;
+  }
+
+  console.log(chalk.green('\n  ✓ graphify installed and OpenCode plugin configured.\n'));
+  return 0;
+}
+
+// ── Help ──────────────────────────────────────────────────────────────────────
+
+export function showGraphHelp() {
+  console.log(`
+  ${chalk.bold.hex('#10b981')('bizar graph')} — Per-project knowledge graph (powered by graphify)
+
+  ${chalk.dim('Usage:')}
+    ${chalk.cyan('bizar graph build')}              # full build of the project graph
+    ${chalk.cyan('bizar graph update')}              # incremental rebuild
+    ${chalk.cyan('bizar graph query "<text>"')}    # query the graph
+    ${chalk.cyan('bizar graph path "<A>" "<B>"')}  # shortest path between concepts
+    ${chalk.cyan('bizar graph explain "<X>"')}     # all nodes related to a concept
+    ${chalk.cyan('bizar graph watch')}              # watch for changes and rebuild
+    ${chalk.cyan('bizar graph status')}             # show graph path, size, node/edge/community counts
+    ${chalk.cyan('bizar graph install')}            # install graphify + drop OpenCode skill/plugin
+
+  ${chalk.dim('Requires:')} Python 3.10+ and \`graphify\` (${chalk.cyan('pip install graphifyy')})
+
+  ${chalk.dim('Graph data lives in')} ${chalk.cyan('.bizar/graph/')} ${chalk.dim('inside this project.')}
+  `);
+}
+
+// ── Main entry point ───────────────────────────────────────────────────────────
+
+/**
+ * `bizar graph` entry point.
+ *
+ * @param {string[]} args — subcommand + args after 'graph'
+ */
+export async function runGraph(args) {
+  // Show help when called with no args or --help / -h
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    showGraphHelp();
+    return 0;
+  }
+
+  const sub = args[0];
+
+  // status and install are the only subcommands that don't need graphify
+  if (sub !== 'status' && sub !== 'install') {
+    // Detect Python
+    const python = findPython();
+    if (!python) {
+      console.error(chalk.red('  Error: graphify requires Python 3.10+.'));
+      console.error(chalk.dim('  Install Python from https://python.org or via your package manager, then re-run.\n'));
+      return 1;
+    }
+
+    // Detect graphify
+    if (!checkGraphify(python)) {
+      console.error(chalk.red('  Error: graphify is not installed.'));
+      console.error(chalk.dim('  Install it with:'));
+      console.error(chalk.cyan('    pip install graphifyy\n'));
+      console.error(chalk.dim('  Or run:'));
+      console.error(chalk.cyan('    bizar graph install\n'));
+      return 1;
+    }
+
+    // Ensure .bizar/ directory exists (graphify will create graph/ inside it)
+    mkdirSync(GRAPH_DIR, { recursive: true });
+
+    switch (sub) {
+      case 'build':
+        return await cmdBuild(python);
+      case 'update':
+        return await cmdUpdate(python);
+      case 'query':
+        return await cmdQuery(python, args.slice(1).join(' '));
+      case 'path':
+        return await cmdPath(python, args[1], args[2]);
+      case 'explain':
+        return await cmdExplain(python, args[1]);
+      case 'watch':
+        return await cmdWatch(python);
+      default:
+        console.error(chalk.red(`  Error: unknown subcommand '${sub}'.\n`));
+        showGraphHelp();
+        return 1;
+    }
+  }
+
+  // subcommands that don't need graphify
+  switch (sub) {
+    case 'status':
+      return await cmdStatus();
+    case 'install':
+      return await cmdInstall();
+    default:
+      // unreachable — already caught unknown subcommands above
+      return 1;
+  }
+}

package/cli/graph.test.mjs

@@ -0,0 +1,218 @@
+/**
+ * cli/graph.test.mjs
+ *
+ * Tests for the `bizar graph` subcommand.
+ * Uses Node's built-in node:test (no external test framework).
+ *
+ * Covered:
+ *   - findPython() returns a string when Python is on PATH (or null)
+ *   - parseGraphStats() returns null for nonexistent files
+ *   - parseGraphStats() returns correct {nodes, edges, communities} from a fixture
+ *   - GRAPH_DIR constant is '.bizar/graph'
+ *   - help output contains all subcommand names
+ */
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Resolve graph.mjs from this test file's location
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, '..');
+
+const {
+  findPython,
+  parseGraphStats,
+  showGraphHelp,
+  GRAPH_DIR,
+} = await import('./graph.mjs');
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+test('GRAPH_DIR equals ".bizar/graph"', () => {
+  assert.equal(GRAPH_DIR, '.bizar/graph');
+});
+
+// ── findPython ────────────────────────────────────────────────────────────────
+
+describe('findPython()', () => {
+  test('returns a string when python3 or python is on PATH', () => {
+    const result = findPython();
+    // On most dev machines Python is installed; the test documents the expected shape
+    if (result !== null) {
+      assert.equal(typeof result, 'string');
+      assert.ok(result.length > 0);
+    }
+  });
+
+  test('returns null when neither python3 nor python is found', () => {
+    // We can't easily stub PATH in this test runner without副作用,
+    // so we verify the function is deterministic and returns the same value
+    // across two calls (proving it doesn't throw or return garbage).
+    const first = findPython();
+    const second = findPython();
+    assert.equal(first, second, 'findPython should be deterministic');
+  });
+});
+
+// ── parseGraphStats ────────────────────────────────────────────────────────────
+
+describe('parseGraphStats()', () => {
+  test('returns null for a nonexistent path', () => {
+    const result = parseGraphStats('/nonexistent/path/graph.json');
+    assert.equal(result, null);
+  });
+
+  test('returns null for a file that is not valid JSON', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const badPath = join(tmpDir, 'graph.json');
+      writeFileSync(badPath, '{ not json', 'utf8');
+      const result = parseGraphStats(badPath);
+      assert.equal(result, null);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test('returns zeroed stats when graph.json has null nodes/links arrays', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test2');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const graphPath = join(tmpDir, 'graph.json');
+      writeFileSync(graphPath, JSON.stringify({ graph: {}, nodes: null, links: null }), 'utf8');
+      const result = parseGraphStats(graphPath);
+      // null arrays are treated as 0-length — parseGraphStats guards with Array.isArray
+      assert.notEqual(result, null);
+      assert.equal(result.nodes, 0);
+      assert.equal(result.edges, 0);
+      assert.equal(result.communities, 0);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test('returns correct stats from a minimal NetworkX node-link fixture', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test3');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const graphPath = join(tmpDir, 'graph.json');
+
+      // NetworkX node-link JSON with 4 nodes, 3 links, 2 communities
+      const fixture = {
+        directed: false,
+        multigraph: false,
+        graph: {},
+        nodes: [
+          { id: 'alpha', community: 0 },
+          { id: 'beta', community: 0 },
+          { id: 'gamma', community: 1 },
+          { id: 'delta', community: 1 },
+        ],
+        links: [
+          { source: 'alpha', target: 'beta' },
+          { source: 'beta', target: 'gamma' },
+          { source: 'gamma', target: 'delta' },
+        ],
+      };
+
+      writeFileSync(graphPath, JSON.stringify(fixture), 'utf8');
+
+      const stats = parseGraphStats(graphPath);
+
+      assert.notEqual(stats, null);
+      assert.equal(stats.nodes, 4, 'should count 4 nodes');
+      assert.equal(stats.edges, 3, 'should count 3 links');
+      assert.equal(stats.communities, 2, 'should detect 2 unique communities (0 and 1)');
+      assert.ok(typeof stats.lastModified === 'string', 'lastModified should be ISO string');
+      assert.ok(typeof stats.sizeBytes === 'number', 'sizeBytes should be a number');
+      assert.ok(stats.sizeBytes > 0, 'sizeBytes should be > 0 for a real file');
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test('handles nodes without a community field gracefully', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test4');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const graphPath = join(tmpDir, 'graph.json');
+      const fixture = {
+        nodes: [
+          { id: 'orphan' },   // no community field
+          { id: 'solo', community: 0 },
+          { id: 'alone', community: 1 },
+        ],
+        links: [],
+      };
+      writeFileSync(graphPath, JSON.stringify(fixture), 'utf8');
+      const stats = parseGraphStats(graphPath);
+      assert.notEqual(stats, null);
+      assert.equal(stats.communities, 2, 'should count communities 0 and 1 only');
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+});
+
+// ── Help output ───────────────────────────────────────────────────────────────
+
+describe('showGraphHelp()', () => {
+  test('outputs all subcommand names', () => {
+    // Capture stdout
+    let output = '';
+    const originalLog = console.log;
+    console.log = (msg) => { output += msg + '\n'; };
+
+    try {
+      showGraphHelp();
+    } finally {
+      console.log = originalLog;
+    }
+
+    // Assert each expected subcommand keyword appears in the help text
+    const subcommands = ['build', 'update', 'query', 'path', 'explain', 'watch', 'status', 'install'];
+    for (const cmd of subcommands) {
+      assert.ok(
+        output.includes(cmd),
+        `help output should contain subcommand "${cmd}"`
+      );
+    }
+  });
+
+  test('mentions the GRAPH_DIR path', () => {
+    let output = '';
+    const originalLog = console.log;
+    console.log = (msg) => { output += msg + '\n'; };
+
+    try {
+      showGraphHelp();
+    } finally {
+      console.log = originalLog;
+    }
+
+    assert.ok(output.includes('.bizar/graph'), 'help should mention the graph directory');
+  });
+
+  test('mentions graphify pip install command', () => {
+    let output = '';
+    const originalLog = console.log;
+    console.log = (msg) => { output += msg + '\n'; };
+
+    try {
+      showGraphHelp();
+    } finally {
+      console.log = originalLog;
+    }
+
+    assert.ok(
+      output.includes('pip install graphifyy'),
+      'help should mention pip install graphifyy'
+    );
+  });
+});
+
+console.log('  graph.mjs tests loaded — run with: node --test cli/graph.test.mjs');