@polderlabs/bizar 3.7.3 → 3.8.0

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');

package/cli/init.mjs

@@ -150,6 +150,41 @@ ${stack.runner ? `- Dev: \`${stack.runner}\`` : ''}
     console.log(chalk.green(`  ✓ Created ${siPath}`));
   }
 
+  // Build per-project knowledge graph (graphify -> .bizar/graph/)
+  // Soft step: never fails init. If graphify is missing or build errors,
+  // the user can retry manually with `bizar graph build`.
+  console.log(chalk.bold('\n--- Graph ---\n'));
+  const detectGraphify = spawnSync('python3', ['-c', 'import graphify; print(graphify.__version__)'], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  const graphifyAvailable = detectGraphify.status === 0 && (detectGraphify.stdout || '').trim().length > 0;
+
+  if (!graphifyAvailable) {
+    console.log(chalk.yellow('  graphify not detected — skipping project graph build.'));
+    console.log(chalk.dim('  Install with: pip install graphifyy  (or pipx install graphifyy)'));
+    console.log(chalk.dim('  Then re-run:  bizar graph build'));
+    console.log(chalk.dim('  The graph will land in .bizar/graph/ inside this project.'));
+  } else {
+    console.log(chalk.dim('  Building project knowledge graph (.bizar/graph/)...'));
+    // npx resolves "bizar" via local package.json bin field (or global install).
+    // Fallback for environments without global bizar: node <repo>/cli/bin.mjs graph build
+    const buildResult = spawnSync('npx', ['bizar', 'graph', 'build'], {
+      cwd,
+      stdio: 'inherit',
+      timeout: 5 * 60 * 1000,
+    });
+    if (buildResult.status === 0) {
+      console.log(chalk.green('  ✓ Graph built at .bizar/graph/ — query with: bizar graph query "<concept>"'));
+    } else {
+      const code = buildResult.status !== null ? buildResult.status : (buildResult.signal || '?');
+      console.log(chalk.yellow(`  Graph build failed (exit ${code}). You can retry manually:`));
+      console.log(chalk.dim('    bizar graph build'));
+      console.log(chalk.dim('  The graph will land in .bizar/graph/ inside this project.'));
+    }
+  }
+
   console.log(chalk.dim('\n  Project initialized. Run `@frigg` to ask questions about the codebase.\n'));
   return true;
 }

package/cli/install.mjs

@@ -292,6 +292,9 @@ export async function runInstaller() {
     }
   }
 
+  // ── Post-install: graphify ──
+  await promptGraphifyInstall();
+
   // ── Post-install ──
   console.log(chalk.dim('\n  Odin watches. The Pantheon awaits. ᛟ\n'));
 }
@@ -386,6 +389,61 @@ async function promptAndInstallOptional() {
   }
 }
 
+async function promptGraphifyInstall() {
+  const { spawnSync } = await import('node:child_process');
+
+  console.log();
+  sectionHeading('Knowledge Graph (graphify)');
+
+  const detect = spawnSync('python3', ['-c', 'import graphify; print(graphify.__version__)'], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  const graphifyInstalled = detect.status === 0 && (detect.stdout || '').trim().length > 0;
+
+  if (graphifyInstalled) {
+    console.log(chalk.green('  graphify already installed — skipping.'));
+    return;
+  }
+
+  // Non-interactive: no TTY means we can't ask, so just print the hint
+  if (!stdin.isTTY || !stdout.isTTY) {
+    console.log(chalk.dim('  graphify not detected. Install later with:'));
+    console.log(chalk.dim('    pip install graphifyy'));
+    console.log(chalk.dim('    pipx install graphifyy'));
+    console.log(chalk.dim('    uv tool install graphifyy'));
+    console.log(chalk.dim('  Then run `bizar graph build` to populate .bizar/graph/.'));
+    return;
+  }
+
+  console.log(chalk.dim('  graphify not detected. graphify powers per-project knowledge graphs (bizar graph build).'));
+  console.log(chalk.dim('  Install with one of:'));
+  console.log(chalk.dim('    pip install graphifyy       # user-site or venv'));
+  console.log(chalk.dim('    pipx install graphifyy      # isolated CLI tool (recommended on macOS)'));
+  console.log(chalk.dim('    uv tool install graphifyy   # via uv'));
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question('  Install graphify now via pip? [Y/n]: ')).trim().toLowerCase();
+    rl.close();
+
+    if (answer === '' || answer.startsWith('y')) {
+      const result = spawnSync('pip', ['install', 'graphifyy'], { stdio: 'inherit', timeout: 120000 });
+      if (result.status === 0) {
+        console.log(chalk.green('  graphify installed. Try: bizar graph build'));
+      } else {
+        console.log(chalk.yellow(`  pip install failed (exit ${result.status}). You can install manually later — see options above.`));
+      }
+    } else {
+      console.log(chalk.dim('  Skipped. Install manually with one of the commands above when ready.'));
+    }
+  } catch {
+    rl.close();
+    console.log(chalk.dim('  Skipped.'));
+  }
+}
+
 export async function runPostInstall() {
   // Skip interactive prompts in CI / non-TTY environments
   if (!process.env.BIZAR_SKIP_OPTIONAL_INSTALLS) {

package/config/AGENTS.md

@@ -283,6 +283,36 @@ The Hindsight MCP server is already configured. All agents interact with it thro
 
 ---
 
+## Graph Query (bizar graph)
+
+Bizar integrates [graphify](https://github.com/safishamsi/graphify) for per-project knowledge graphs. When investigating a Bizar project, **query the graph before grepping raw files** — it's faster and surfaces structural relationships grep can't see.
+
+### Where the graph lives
+`.bizar/graph/` inside the project (git-trackable JSON + Markdown; cache and per-machine interpreter path are gitignored).
+
+### How to query
+From the project root, the user (or heimdall via `/init` or any other agent prompted by Odin) can run:
+- `bizar graph status` — confirm the graph exists; print node/edge/community counts
+- `bizar graph query "<concept>"` — find nodes related to a concept (BFS traversal)
+- `bizar graph path "<A>" "<B>"` — shortest path between two concepts
+- `bizar graph explain "<X>"` — all nodes related to X
+- `bizar graph update` — incremental rebuild after editing source files
+- `bizar graph build` — full rebuild (overwrites existing graph)
+- `bizar graph watch` — foreground watcher (Ctrl-C to stop)
+
+### When to use the graph
+- Before reading a large file: `bizar graph explain "<module-name>"` to see what calls/uses it
+- When mapping unfamiliar code: `bizar graph query "<feature>"` to find related concepts
+- When debugging cross-module interactions: `bizar graph path "<symptom>" "<root-cause>"`
+- Before grep: `bizar graph query "<term>"` first — the graph may already point you to the right file
+
+### When NOT to use the graph
+- The graph is stale (run `bizar graph update` first)
+- graphify is not installed (init skipped graph step; user can install with `pip install graphifyy` then `bizar graph build`)
+- The question is about runtime behavior, not source structure
+
+---
+
 ---
 
 ## General Agent Baseline — Always-On Behavior
@@ -548,3 +578,26 @@ For Bizar-internal claims (citing files, lines, tool results), use file:line ref
 
 This baseline covers: identity, refusal, tone, formatting, lists, user wellbeing, evenhandedness, mistakes, knowledge cutoff and research-first, MCP servers and skills, mandatory skill-read, file creation, file handling, search, copyright, harmful content, citations, images, memory privacy, execution, clarification, and communication. Every Bizar agent — Odin, Frigg, Vör, Mimir, Heimdall, Hermod, Thor, Baldr, Tyr, Vidarr, Forseti — must follow it.
 
+---
+
+## Parallel Execution Awareness
+
+You may be dispatched by Odin as one of several agents running concurrently against the same working directory and the same git repository. Your sibling agents **cannot see you** and you **cannot see them**. Without discipline this leads to silent file overwrites, `.git/index.lock` collisions, lockfile corruption, and lost work.
+
+### Hard rules when you have siblings (Odin tells you in the prompt)
+
+1. **File scope is sacred.** Odin assigns you a scope. Only modify files inside it. If you need to touch something outside, STOP and report — do not improvise.
+2. **No write-level git.** `git commit`, `push`, `merge`, `rebase`, `reset`, `clean`, `stash`, branch-switching `checkout`, and `pull --rebase` are FORBIDDEN for every agent except @hermod. Use `git status`, `git diff`, `git log`, and `git add` (scope files only) for context.
+3. **Detect conflicts before they happen.** Before writing a file, run `git diff --name-only` and confirm the file is not in a sibling's scope. If it has changed since you started, STOP and report.
+4. **`.git/index.lock` is a sibling's signal.** If you see it, wait 2-3 seconds and retry. If it persists, STOP and report. Do not delete the lock file.
+5. **Lockfiles and root configs are shared.** `package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI configs — only ONE agent in a batch should touch these. If Odin did not assign them to you, treat as READ-ONLY.
+6. **Report parallel context in your final summary.** State "siblings: ..." and any conflicts observed.
+
+### Default behavior when Odin does NOT mention siblings
+
+- You may work normally.
+- Still avoid `git commit`/`push`/`merge`/`rebase`/`reset`/`clean`/`stash` unless explicitly asked. Default to read-only git unless the user/Odin explicitly requests a write operation. When in doubt, leave git work to @hermod.
+
+### Why this exists
+The harness shares one `.git/` directory across all parallel sessions. Two simultaneous `git commit` calls race on the index lock. Two agents writing the same file = silent last-writer-wins data loss. Discipline now is cheaper than recovery later.
+

package/config/agents/baldr.md

@@ -160,6 +160,30 @@ The injected message you will see is exactly one of:
 - `[loop guard: 8 identical calls to <tool>]. Consider using the task tool to report back to your parent with what you've learned and what you need.`
 - An error containing: `Loop protection: 12 identical calls to <tool>. Use task to escalate.`
 
+## Parallel Execution
+
+You may be dispatched alongside sibling agents working on the same repository at the same time. The shared `AGENTS.md` baseline contains the universal rules — read those first. This section adds role-specific guidance.
+
+### When Odin tells you about siblings in your prompt
+- You will receive a `## PARALLEL EXECUTION CONTEXT` block listing your siblings and your file scope.
+- Treat your scope as a hard boundary. Files outside your scope are READ-ONLY.
+- If Odin did not give you a scope, default to: write nothing, return a clarifying question to Odin.
+
+### Git — your specific rules
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (scope files only)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, branch-switching `checkout`, `pull --rebase`
+- If a task seems to require a forbidden operation, report it back to Odin in your final summary — do not improvise. Only @hermod performs write-level git.
+- If you hit `.git/index.lock`, wait 2-3s and retry. If it persists, STOP and report.
+
+### Pre-write checklist (before every `write` / `edit` call)
+1. Is the file inside the scope Odin gave me? If not, STOP.
+2. Has this file changed since I started? (`git diff --name-only <file>`) If yes, STOP — a sibling may have written it.
+3. Is this a lockfile or root config (`package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI)? If yes, only proceed if Odin explicitly assigned it to you.
+4. Proceed.
+
+### Reporting
+End your final summary with: `Siblings: <list>. Conflicts: <list or "none">. Git ops performed: <list or "none">.`
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/forseti.md

@@ -124,6 +124,15 @@ Be professional and concise. Do not write long essays for every action.
 - One sentence of context beats three paragraphs of preamble.
 - Match the user's register: if they write briefly, reply briefly. If they want depth, they will ask.
 
+## Parallel Execution
+
+You may be invoked alongside other audit agents (parallel reviews of different files) or alongside implementation agents. The shared `AGENTS.md` baseline rules apply.
+
+### Your rules
+- You are AUDIT-ONLY. You MUST NOT modify source files, write to `.bizar/`, or run write-level git.
+- If running alongside an implementation agent and you need to read a file it is currently editing, do not block on `.git/index.lock` — just read the file directly.
+- Report any active sibling agents in your final summary so Odin knows the audit was concurrent.
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/heimdall.md

@@ -169,6 +169,30 @@ Be professional and concise. Do not write long essays for every action.
 - One sentence of context beats three paragraphs of preamble.
 - Match the user's register: if they write briefly, reply briefly. If they want depth, they will ask.
 
+## Parallel Execution
+
+You may be dispatched alongside sibling agents working on the same repository at the same time. The shared `AGENTS.md` baseline contains the universal rules — read those first. This section adds role-specific guidance.
+
+### When Odin tells you about siblings in your prompt
+- You will receive a `## PARALLEL EXECUTION CONTEXT` block listing your siblings and your file scope.
+- Treat your scope as a hard boundary. Files outside your scope are READ-ONLY.
+- If Odin did not give you a scope, default to: write nothing, return a clarifying question to Odin.
+
+### Git — your specific rules
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (scope files only)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, branch-switching `checkout`, `pull --rebase`
+- If a task seems to require a forbidden operation, report it back to Odin in your final summary — do not improvise. Only @hermod performs write-level git.
+- If you hit `.git/index.lock`, wait 2-3s and retry. If it persists, STOP and report.
+
+### Pre-write checklist (before every `write` / `edit` call)
+1. Is the file inside the scope Odin gave me? If not, STOP.
+2. Has this file changed since I started? (`git diff --name-only <file>`) If yes, STOP — a sibling may have written it.
+3. Is this a lockfile or root config (`package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI)? If yes, only proceed if Odin explicitly assigned it to you.
+4. Proceed.
+
+### Reporting
+End your final summary with: `Siblings: <list>. Conflicts: <list or "none">. Git ops performed: <list or "none">.`
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/hermod.md

@@ -156,6 +156,26 @@ When dispatched for a `/pr-review`:
 
 You have `gh` access — use it to fetch PR diffs and post comments.
 
+## Parallel Execution — Multi-Agent Integration
+
+You may run while implementation agents (Thor, Tyr, Heimdall, Vidarr, Mimir, Baldr) are mid-task. Your job is to integrate their work safely.
+
+### Before any write-level git operation (commit, merge, rebase, push, PR)
+1. Run `git status` and `git diff --stat` to see the working tree state.
+2. Identify which files are staged/modified and which agent likely owns each (Odin's prompt told you, or infer from `chore:`, `feat(scope):`, file paths).
+3. If uncommitted work spans multiple agents' scopes, stage deliberately — `git add <specific files>` not `git add .`. Never `git add -A`.
+4. If `git status` shows work that does NOT match the scope Odin assigned to you, STOP and report — that work belongs to a sibling agent and you must integrate it deliberately, not roll it into your commit.
+5. If `.git/index.lock` exists, wait 2-3s and retry. If it persists, STOP and report — a sibling is mid-write.
+
+### Commit discipline for parallel work
+- Commit messages should reference contributing agents: `feat(scope): description [co-authored-by: @thor, @tyr]` or use a multi-line body listing the agent contributions.
+- Use a single commit per logical unit. Do NOT batch unrelated agents' work into one mega-commit.
+- Never force-push to a branch a sibling may also be pushing to.
+
+### Conflict handling
+- If a rebase or merge encounters conflicts on a file that was modified by a parallel agent (check the file path against the scope list Odin gave you), STOP and report — that resolution is Odin's call, not yours.
+- If you find `.git/index.lock` held by a sibling (waiting did not help), report the conflict and stop.
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/mimir.md

@@ -127,6 +127,30 @@ Be professional and concise. Do not write long essays for every action.
 - One sentence of context beats three paragraphs of preamble.
 - Match the user's register: if they write briefly, reply briefly. If they want depth, they will ask.
 
+## Parallel Execution
+
+You may be dispatched alongside sibling agents working on the same repository at the same time. The shared `AGENTS.md` baseline contains the universal rules — read those first. This section adds role-specific guidance.
+
+### When Odin tells you about siblings in your prompt
+- You will receive a `## PARALLEL EXECUTION CONTEXT` block listing your siblings and your file scope.
+- Treat your scope as a hard boundary. Files outside your scope are READ-ONLY.
+- If Odin did not give you a scope, default to: write nothing, return a clarifying question to Odin.
+
+### Git — your specific rules
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (scope files only)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, branch-switching `checkout`, `pull --rebase`
+- If a task seems to require a forbidden operation, report it back to Odin in your final summary — do not improvise. Only @hermod performs write-level git.
+- If you hit `.git/index.lock`, wait 2-3s and retry. If it persists, STOP and report.
+
+### Pre-write checklist (before every `write` / `edit` call)
+1. Is the file inside the scope Odin gave me? If not, STOP.
+2. Has this file changed since I started? (`git diff --name-only <file>`) If yes, STOP — a sibling may have written it.
+3. Is this a lockfile or root config (`package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI)? If yes, only proceed if Odin explicitly assigned it to you.
+4. Proceed.
+
+### Reporting
+End your final summary with: `Siblings: <list>. Conflicts: <list or "none">. Git ops performed: <list or "none">.`
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/odin.md

@@ -243,6 +243,51 @@ You MUST use **per-project banks** — never the default bank for project work.
 - Tag memories with `project:<repo-name>`
 - Create or update mental models for sustained project context
 
+## Parallel Dispatch Coordination
+
+When you dispatch 2+ agents in parallel via `task` or `bizar_spawn_background`, each subagent opens its own session but **shares the same working directory and `.git/` directory**. They cannot see each other. Without explicit context they will collide on file writes and git operations.
+
+### Pre-dispatch checklist (MANDATORY before any parallel `task` call)
+- [ ] Each subagent's **file scope is disjoint** — no two agents edit the same file or directory
+- [ ] Lockfiles, `package.json`, root configs, and shared infra files (`tsconfig.json`, `vite.config.*`, `Dockerfile`, CI files) are assigned to ONE agent or marked READ-ONLY for everyone else
+- [ ] You have not assigned any subagent `bash: allow` PLUS a write-level git task in the same batch (Hermod is the only git writer)
+- [ ] You have named each subagent's scope in plain English (e.g. "Thor owns `src/api/`, Tyr owns `src/core/`")
+
+### Sibling-awareness block (PREPEND to every parallel subagent prompt)
+
+Every prompt you send to a parallel subagent must start with this block, with the `{...}` placeholders filled in:
+
+```
+## PARALLEL EXECUTION CONTEXT
+
+You are running alongside sibling agents in the same working directory and the same git repository. They cannot see you. You cannot see them. Follow these rules strictly.
+
+### Your siblings (running concurrently)
+- **{sibling_agent_1}** ({sibling_1_scope})
+- **{sibling_agent_2}** ({sibling_2_scope})
+- ... (add lines as needed)
+
+### Your scope (files you MAY create or modify)
+{comma_separated_paths_or_globs}
+
+### Sibling scopes (READ-ONLY for you — do NOT modify, even if you think they need it)
+{comma_separated_paths_or_globs_for_each_sibling}
+
+### Git coordination
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (only for files inside YOUR scope)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, `git checkout` to switch branches, `git pull --rebase`
+- If you need a forbidden operation, STOP and report back to Odin in your final summary. Only @hermod performs write-level git operations.
+- If you encounter `.git/index.lock` existing, wait briefly and retry — a sibling is mid-write. If it persists, STOP and report.
+
+### Conflict detection
+- Before each `write` or `edit`, if the target file is in a sibling's scope, STOP and report.
+- If a file in your scope has been modified by another agent since you started (check `git diff --name-only` against your starting state), STOP and report — do not overwrite.
+- Use the shared `AGENTS.md` baseline "Parallel Execution Awareness" section for full rules.
+```
+
+### Sequential fallback
+If you cannot decompose into disjoint file scopes (e.g. the task is genuinely monolithic), do NOT parallelize — dispatch a single agent. Parallelism is a tool, not a religion.
+
 ## Background Agents (Asynchronous Work)
 
 When a sub-task can run independently, spawn it as a **background agent** instead of using the synchronous `task` tool. The main conversation continues while the background work progresses.

package/config/agents/thor.md

@@ -109,6 +109,30 @@ Be professional and concise. Do not write long essays for every action.
 - One sentence of context beats three paragraphs of preamble.
 - Match the user's register: if they write briefly, reply briefly. If they want depth, they will ask.
 
+## Parallel Execution
+
+You may be dispatched alongside sibling agents working on the same repository at the same time. The shared `AGENTS.md` baseline contains the universal rules — read those first. This section adds role-specific guidance.
+
+### When Odin tells you about siblings in your prompt
+- You will receive a `## PARALLEL EXECUTION CONTEXT` block listing your siblings and your file scope.
+- Treat your scope as a hard boundary. Files outside your scope are READ-ONLY.
+- If Odin did not give you a scope, default to: write nothing, return a clarifying question to Odin.
+
+### Git — your specific rules
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (scope files only)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, branch-switching `checkout`, `pull --rebase`
+- If a task seems to require a forbidden operation, report it back to Odin in your final summary — do not improvise. Only @hermod performs write-level git.
+- If you hit `.git/index.lock`, wait 2-3s and retry. If it persists, STOP and report.
+
+### Pre-write checklist (before every `write` / `edit` call)
+1. Is the file inside the scope Odin gave me? If not, STOP.
+2. Has this file changed since I started? (`git diff --name-only <file>`) If yes, STOP — a sibling may have written it.
+3. Is this a lockfile or root config (`package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI)? If yes, only proceed if Odin explicitly assigned it to you.
+4. Proceed.
+
+### Reporting
+End your final summary with: `Siblings: <list>. Conflicts: <list or "none">. Git ops performed: <list or "none">.`
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/tyr.md

@@ -108,6 +108,30 @@ Be professional and concise. Do not write long essays for every action.
 - One sentence of context beats three paragraphs of preamble.
 - Match the user's register: if they write briefly, reply briefly. If they want depth, they will ask.
 
+## Parallel Execution
+
+You may be dispatched alongside sibling agents working on the same repository at the same time. The shared `AGENTS.md` baseline contains the universal rules — read those first. This section adds role-specific guidance.
+
+### When Odin tells you about siblings in your prompt
+- You will receive a `## PARALLEL EXECUTION CONTEXT` block listing your siblings and your file scope.
+- Treat your scope as a hard boundary. Files outside your scope are READ-ONLY.
+- If Odin did not give you a scope, default to: write nothing, return a clarifying question to Odin.
+
+### Git — your specific rules
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (scope files only)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, branch-switching `checkout`, `pull --rebase`
+- If a task seems to require a forbidden operation, report it back to Odin in your final summary — do not improvise. Only @hermod performs write-level git.
+- If you hit `.git/index.lock`, wait 2-3s and retry. If it persists, STOP and report.
+
+### Pre-write checklist (before every `write` / `edit` call)
+1. Is the file inside the scope Odin gave me? If not, STOP.
+2. Has this file changed since I started? (`git diff --name-only <file>`) If yes, STOP — a sibling may have written it.
+3. Is this a lockfile or root config (`package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI)? If yes, only proceed if Odin explicitly assigned it to you.
+4. Proceed.
+
+### Reporting
+End your final summary with: `Siblings: <list>. Conflicts: <list or "none">. Git ops performed: <list or "none">.`
+
 ---
 
 ## Always-On Behavior Baseline

package/config/agents/vidarr.md

@@ -112,6 +112,30 @@ Be professional and concise. Do not write long essays for every action.
 - One sentence of context beats three paragraphs of preamble.
 - Match the user's register: if they write briefly, reply briefly. If they want depth, they will ask.
 
+## Parallel Execution
+
+You may be dispatched alongside sibling agents working on the same repository at the same time. The shared `AGENTS.md` baseline contains the universal rules — read those first. This section adds role-specific guidance.
+
+### When Odin tells you about siblings in your prompt
+- You will receive a `## PARALLEL EXECUTION CONTEXT` block listing your siblings and your file scope.
+- Treat your scope as a hard boundary. Files outside your scope are READ-ONLY.
+- If Odin did not give you a scope, default to: write nothing, return a clarifying question to Odin.
+
+### Git — your specific rules
+- ALLOWED: `git status`, `git diff`, `git log`, `git branch --list`, `git add` (scope files only)
+- FORBIDDEN: `git commit`, `git push`, `git merge`, `git rebase`, `git reset`, `git clean`, `git stash`, branch-switching `checkout`, `pull --rebase`
+- If a task seems to require a forbidden operation, report it back to Odin in your final summary — do not improvise. Only @hermod performs write-level git.
+- If you hit `.git/index.lock`, wait 2-3s and retry. If it persists, STOP and report.
+
+### Pre-write checklist (before every `write` / `edit` call)
+1. Is the file inside the scope Odin gave me? If not, STOP.
+2. Has this file changed since I started? (`git diff --name-only <file>`) If yes, STOP — a sibling may have written it.
+3. Is this a lockfile or root config (`package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI)? If yes, only proceed if Odin explicitly assigned it to you.
+4. Proceed.
+
+### Reporting
+End your final summary with: `Siblings: <list>. Conflicts: <list or "none">. Git ops performed: <list or "none">.`
+
 ---
 
 ## Always-On Behavior Baseline

package/config/commands/init.md

@@ -1 +1,22 @@
-Run bizar init to detect project stack, install relevant skills, and create .bizar/PROJECT.md.
+Run `bizar init` from the project root to:
+1. Detect the project stack (language, framework, database, tools)
+2. Install relevant skills from the opencode skills registry
+3. Create `.bizar/PROJECT.md` with stack and conventions
+4. Create `.bizar/AGENTS_SELF_IMPROVEMENT.md` (only if missing)
+5. Build the per-project knowledge graph in `.bizar/graph/` (powered by graphify; skipped gracefully if graphify is not installed)
+
+After `bizar init` succeeds, run `bizar graph status` to confirm the graph exists.
+
+If the graph is missing after init, graphify is likely not installed. Tell the user to install it with one of:
+- `pip install graphifyy`
+- `pipx install graphifyy`
+- `uv tool install graphifyy`
+
+Then run `bizar graph build` to populate `.bizar/graph/`.
+
+Query the graph at any time with:
+- `bizar graph query "<concept>"` — find nodes related to a concept
+- `bizar graph path "<A>" "<B>"` — shortest path between concepts
+- `bizar graph explain "<X>"` — all nodes related to X
+
+Update the graph incrementally with `bizar graph update` after editing source files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "3.7.3",
+  "version": "3.8.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.",
   "type": "module",
   "bin": {