@bahulam/code 0.1.9 → 0.1.11

package/src/plugins/state.mjs

@@ -0,0 +1,290 @@
+/**
+ * Plugin state — the Shared Blackboard.
+ *
+ * Every plugin gets its own SQLite sidecar at ~/.bahulam/data/<name>/state.db.
+ * Two built-in tables ship with every DB; plugins are free to `CREATE TABLE`
+ * additional ones via `state.query(sql)`:
+ *
+ *   kv        — small structured values (watchlists, prefs, cursors, form
+ *               state). One row per key, JSON-encoded value, last-write-wins
+ *               with an updated_at timestamp.
+ *
+ *   records   — append-only event log (backtest runs, decisions, alerts,
+ *               anything you want a history of). Named streams via the
+ *               `stream` column; plugin owns the stream namespace.
+ *
+ * The exported `makePluginState(pluginName, {emit})` returns a proxy with
+ * the methods handlers and view routes call. Every write fires `emit(evt)`
+ * synchronously AFTER commit — the SSE bus turns that into a
+ * `plugin_state_changed` event so views can re-render live. When the same
+ * key/stream is written many times in quick succession the emit hook
+ * debounces to at most one event per 50ms per (plugin, kind, target).
+ *
+ * We use Node's built-in `node:sqlite` (v22+, experimental) so plugin
+ * authors get relational storage with zero install steps. The
+ * ExperimentalWarning is silenced once at module load.
+ *
+ * A NOTE ON SAFETY: `state.query(sql, params)` is a raw SQL escape hatch
+ * intended for the plugin's OWN tools and views — never expose it to
+ * untrusted input (the plugin author owns the SQL). The higher-level
+ * get/set/patch/append/list methods parameterize everything.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+// Silence the single "SQLite is an experimental feature" warning that
+// node:sqlite emits at first import. Users would see it on every plugin
+// launch otherwise, which is noise, not signal.
+{
+  const orig = process.emit;
+  process.emit = function (name, warning, ...rest) {
+    if (name === 'warning' && warning?.name === 'ExperimentalWarning'
+        && /SQLite/i.test(String(warning.message || ''))) {
+      return false;
+    }
+    return orig.call(this, name, warning, ...rest);
+  };
+}
+
+const DATA_ROOT = () => path.join(os.homedir(), '.bahulam', 'data');
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const DEBOUNCE_MS = 50;
+
+// Open handles cached per plugin — SQLite in WAL mode is happy with one
+// handle per process, and this is a single-process dev tool. Handles live
+// for the lifetime of the CLI; explicit close() is available for tests.
+const _handles = new Map(); // pluginName -> { db, dir, path }
+
+function pluginDataDir(pluginName) {
+  if (!PLUGIN_NAME_RE.test(pluginName)) {
+    throw new Error(`invalid plugin name for state dir: ${pluginName}`);
+  }
+  const dir = path.join(DATA_ROOT(), pluginName);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function openDb(pluginName) {
+  if (_handles.has(pluginName)) return _handles.get(pluginName);
+  const dir = pluginDataDir(pluginName);
+  const dbPath = path.join(dir, 'state.db');
+  const db = new DatabaseSync(dbPath);
+  // WAL: multiple readers, one writer; robust against concurrent view+agent.
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec('PRAGMA foreign_keys = ON');
+  // Bootstrap schema — idempotent so evolving plugins never crash on start.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS kv (
+      key        TEXT PRIMARY KEY,
+      value      TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS records (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      stream     TEXT NOT NULL,
+      payload    TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS records_stream_idx
+      ON records(stream, id DESC);
+  `);
+  const handle = { db, dir, path: dbPath };
+  _handles.set(pluginName, handle);
+  return handle;
+}
+
+function now() { return new Date().toISOString(); }
+
+function deepMerge(base, patch) {
+  if (Array.isArray(base) || Array.isArray(patch)) return patch;
+  if (base == null || typeof base !== 'object') return patch;
+  if (patch == null || typeof patch !== 'object') return patch;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)
+        && out[k] && typeof out[k] === 'object' && !Array.isArray(out[k])) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a per-plugin state proxy.
+ * @param {string} pluginName  Must match /^[a-z0-9][a-z0-9._-]{0,63}$/i
+ * @param {object} [opts]
+ * @param {(evt: {plugin: string, op: string, kind: 'kv'|'records', target: string, at: string}) => void} [opts.emit]
+ *   Called (debounced) after every write commits. The workspace server
+ *   turns this into an SSE `plugin_state_changed` event for the browser.
+ * @returns proxy with { get, set, patch, append, list, query, delete, close, db, path }
+ */
+export function makePluginState(pluginName, { emit = null } = {}) {
+  const { db, path: dbPath } = openDb(pluginName);
+
+  // One debounce timer per (kind, target). Fast writes coalesce into
+  // exactly one plugin_state_changed event. Pending entry is stored so
+  // close() can flush synchronously for tests and controlled shutdown.
+  const timers = new Map();  // key -> timeout handle
+  const pending = new Map(); // key -> event payload to fire on flush
+  function fire(op, kind, target) {
+    if (typeof emit !== 'function') return;
+    const key = `${kind}:${target}`;
+    if (timers.has(key)) clearTimeout(timers.get(key));
+    pending.set(key, { plugin: pluginName, op, kind, target, at: now() });
+    timers.set(key, setTimeout(() => {
+      const evt = pending.get(key);
+      timers.delete(key);
+      pending.delete(key);
+      if (evt) {
+        try { emit(evt); }
+        catch { /* emit failure must never surface into the tool call */ }
+      }
+    }, DEBOUNCE_MS));
+  }
+  function flushPending() {
+    for (const [key, evt] of pending) {
+      clearTimeout(timers.get(key));
+      try { emit(evt); } catch { /* swallow */ }
+    }
+    timers.clear();
+    pending.clear();
+  }
+
+  // Prepared statements are cached on first use (better-sqlite3-style perf,
+  // node:sqlite exposes prepare() too).
+  const stmts = {
+    get:    db.prepare('SELECT value FROM kv WHERE key = ?'),
+    upsert: db.prepare('INSERT INTO kv(key, value, updated_at) VALUES(?, ?, ?) '
+                     + 'ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at'),
+    del:    db.prepare('DELETE FROM kv WHERE key = ?'),
+    keys:   db.prepare('SELECT key FROM kv ORDER BY key'),
+    append: db.prepare('INSERT INTO records(stream, payload, created_at) VALUES(?, ?, ?)'),
+    listAsc:  db.prepare('SELECT id, payload, created_at FROM records WHERE stream = ? ORDER BY id ASC  LIMIT ?'),
+    listDesc: db.prepare('SELECT id, payload, created_at FROM records WHERE stream = ? ORDER BY id DESC LIMIT ?'),
+  };
+
+  return {
+    /** Read one key. Returns `fallback` (default null) when the key is absent. */
+    get(key, fallback = null) {
+      const row = stmts.get.get(String(key));
+      if (!row) return fallback;
+      try { return JSON.parse(row.value); }
+      catch { return fallback; }
+    },
+
+    /** Write one key with a whole value. Fires plugin_state_changed. */
+    set(key, value) {
+      const k = String(key);
+      stmts.upsert.run(k, JSON.stringify(value), now());
+      fire('set', 'kv', k);
+      return value;
+    },
+
+    /**
+     * Deep-merge a partial into an existing object under `key`. Arrays
+     * replace; nested objects merge recursively. When the key is absent,
+     * `patch` is stored as-is. Matches the "PATCH endpoint for surgeon
+     * precision" contract.
+     */
+    patch(key, partial) {
+      const k = String(key);
+      const cur = this.get(k, null);
+      const next = deepMerge(cur, partial);
+      stmts.upsert.run(k, JSON.stringify(next), now());
+      fire('patch', 'kv', k);
+      return next;
+    },
+
+    /** Remove one key. */
+    delete(key) {
+      const k = String(key);
+      const info = stmts.del.run(k);
+      if (info.changes > 0) fire('delete', 'kv', k);
+      return info.changes > 0;
+    },
+
+    /** List every kv key currently present. */
+    keys() { return stmts.keys.all().map(r => r.key); },
+
+    /** Append one row to a named stream. Returns the new row's id. */
+    append(stream, payload) {
+      const s = String(stream);
+      const info = stmts.append.run(s, JSON.stringify(payload), now());
+      fire('append', 'records', s);
+      return Number(info.lastInsertRowid);
+    },
+
+    /**
+     * Read from a stream.
+     * @param {string} stream
+     * @param {object} [opts]  { limit?: number = 50, order?: 'asc'|'desc' = 'desc' }
+     * @returns [{ id, payload, created_at }]
+     */
+    list(stream, { limit = 50, order = 'desc' } = {}) {
+      const s = String(stream);
+      const cap = Math.max(1, Math.min(10000, Math.floor(limit)));
+      const stmt = order === 'asc' ? stmts.listAsc : stmts.listDesc;
+      return stmt.all(s, cap).map(r => ({
+        id: r.id,
+        payload: safeParse(r.payload),
+        created_at: r.created_at,
+      }));
+    },
+
+    /**
+     * Raw SQL escape hatch — for the plugin's own advanced use. Always
+     * use parameters, never string-concat user input into SQL. Returns
+     * whatever the underlying prepared statement returns; SELECTs come
+     * back as an array of rows.
+     */
+    query(sql, params = []) {
+      const stmt = db.prepare(String(sql));
+      const args = Array.isArray(params) ? params : [params];
+      // node:sqlite prepared statements expose all() for SELECT-like
+      // queries and run() for DML; iterate() is available too.
+      const first = String(sql).trim().slice(0, 6).toUpperCase();
+      if (first.startsWith('SELECT') || first.startsWith('PRAGMA')) {
+        return stmt.all(...args);
+      }
+      const info = stmt.run(...args);
+      // Any DML on kv/records is announced generically so views can
+      // refresh; more specific writes go through set/patch/append.
+      fire('query', 'kv', '*');
+      return { changes: info.changes, lastInsertRowid: Number(info.lastInsertRowid) };
+    },
+
+    /** Direct DatabaseSync handle for callers that know what they need. */
+    get db() { return db; },
+    /** Absolute path to the DB file on disk. */
+    get path() { return dbPath; },
+
+    /** Test hook — closes the underlying handle. Flushes any pending
+     * emit events synchronously so tests can observe them without a wait. */
+    close() {
+      flushPending();
+      db.close();
+      _handles.delete(pluginName);
+    },
+  };
+}
+
+function safeParse(text) {
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+/**
+ * Test helper — reset all cached handles. Called by tests between cases so
+ * a temp $HOME override actually takes effect.
+ */
+export function _resetForTests() {
+  for (const h of _handles.values()) {
+    try { h.db.close(); } catch { /* ignore */ }
+  }
+  _handles.clear();
+}

package/src/terminal/agents.mjs

@@ -163,6 +163,22 @@ export function findBuiltinAgent(agentName) {
   return BUILTIN_AGENTS.find(agent => agent.command === target || agent.name.toLowerCase() === target) || null;
 }
 
+/**
+ * Search for an agent across built-in agents, project .bahulam/agents, and plugin agents.
+ * @param {string} agentName
+ * @param {object} [agentLoader] - Instance of AgentLoader with loadFromPlugins() called
+ * @returns {object|null}
+ */
+export function findAgent(agentName, agentLoader = null) {
+  const builtin = findBuiltinAgent(agentName);
+  if (builtin) return builtin;
+  if (agentLoader) {
+    const local = agentLoader.get(agentName);
+    if (local) return local;
+  }
+  return null;
+}
+
 export function localAgentMatches(agent, target) {
   const needle = String(target || '').trim().toLowerCase();
   if (!needle) return false;
@@ -344,7 +360,8 @@ export async function runAgentDefinition(agentDefinition, instruction, ctx, sess
  * @param {Function} renderEvent - Event renderer function
  */
 export async function runAgent(agentName, instruction, ctx, session, renderEvent) {
-  const agent = findBuiltinAgent(agentName);
+  const agentLoader = ctx?.agentLoader || null;
+  const agent = findAgent(agentName, agentLoader);
   if (!agent) {
     process.stderr.write(`  ${c.red('Unknown agent: ' + agentName)}\n`);
     return;

package/src/terminal/init.mjs

@@ -28,7 +28,7 @@ Format v1. Markdown files are intentionally hand-editable.
   'config.json': JSON.stringify({
     version: 1,
     context: {
-      loadEveryTurn: ['KEPLER.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
+      loadEveryTurn: ['BAHULAM.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
       showReloadNotice: true,
     },
     planning: { owner: 'auto', onUserEditedPlan: 'prefer_user_plan' },
@@ -57,7 +57,7 @@ Format v1. Markdown files are intentionally hand-editable.
       Stop: [],
     },
   }, null, 2) + '\n',
-  'KEPLER.md': `# Project
+  'BAHULAM.md': `# Project
 
 ## Quick Facts
 - Stack:

package/src/terminal/main.mjs

@@ -23,6 +23,64 @@ import { BahulamAuth as Auth } from '../auth/bahulam-auth.mjs';
 const subcommand = process.argv[2];
 const subcommandArgs = process.argv.slice(3);
 
+const PLUGIN_MANAGEMENT_COMMANDS = new Set([
+  'install', 'validate', 'check', 'lint',
+  'list', 'ls', 'remove', 'rm', 'uninstall',
+  'enable', 'disable', 'info', 'update', 'upgrade',
+]);
+
+function parsePluginArgs(argv) {
+  const parsed = {
+    action: null,       // 'open' (default) or a management verb
+    pluginName: null,
+    targetPath: null,
+    source: null,       // install source: git url, tarball, local dir
+    port: 0,
+    open: true,
+    help: false,
+    json: false,
+    global: true,       // install target: ~/.bahulam vs project .bahulam
+    force: false,
+    ref: null,          // git branch/tag/commit
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--help':
+      case '-h': parsed.help = true; break;
+      case '--port': parsed.port = Number(argv[++i]) || 0; break;
+      case '--no-open': parsed.open = false; break;
+      case '--json': parsed.json = true; parsed.open = false; break;
+      case '--project': parsed.global = false; break;
+      case '--global': parsed.global = true; break;
+      case '--force': case '-f': parsed.force = true; break;
+      case '--ref': case '--tag': case '--branch': parsed.ref = argv[++i]; break;
+      default:
+        if (!arg.startsWith('-')) positional.push(arg);
+        break;
+    }
+  }
+  if (positional.length && PLUGIN_MANAGEMENT_COMMANDS.has(positional[0].toLowerCase())) {
+    parsed.action = positional.shift().toLowerCase();
+    if (parsed.action === 'install') parsed.source = positional.shift() || null;
+    else if (['validate', 'check', 'lint'].includes(parsed.action)) {
+      // Accepts either a directory path or an installed plugin name.
+      const arg = positional.shift() || null;
+      if (arg && (arg.includes('/') || fs.existsSync?.(arg))) parsed.source = arg;
+      else parsed.pluginName = arg;
+    }
+    else if (['info', 'remove', 'rm', 'uninstall', 'enable', 'disable', 'update', 'upgrade'].includes(parsed.action)) {
+      parsed.pluginName = positional.shift() || null;
+    }
+  } else {
+    parsed.action = 'open';
+    parsed.pluginName = positional.shift() || null;
+    parsed.targetPath = positional.shift() || null;
+  }
+  return parsed;
+}
+
 function parseKeplerSubcommandArgs(command, argv) {
   const parsed = {
     command,
@@ -221,6 +279,18 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'plugin' || subcommand === 'plugins') {
+    const args = parsePluginArgs(subcommandArgs);
+    if (args.action && args.action !== 'open') {
+      const { handlePluginManagementCommand } = await import('../commands/plugin-manage.mjs');
+      await handlePluginManagementCommand(args, { cwd: process.cwd() });
+      return;
+    }
+    const { handlePluginCommand } = await import('../commands/plugin.mjs');
+    await handlePluginCommand(args, { cwd: process.cwd() });
+    return;
+  }
+
   if (subcommand === 'version' || subcommand === '--version' || subcommand === '-v') {
     const { createRequire } = await import('node:module');
     const require = createRequire(import.meta.url);
@@ -260,6 +330,9 @@ async function main() {
     bahulam workspace list         List recent local workspace sessions
     bahulam local open [path]      Alias for workspace open
 
+  \x1b[1mPlugins:\x1b[0m
+    bahulam plugin <name> [path]   Open a workspace with a named plugin
+
   \x1b[1mAnalytics:\x1b[0m
     bahulam sessions               List recent local sessions
     bahulam stats                  Show aggregate local session stats
@@ -302,8 +375,8 @@ async function main() {
     ANTHROPIC_API_KEY       Direct Anthropic API key
     OPENROUTER_API_KEY      OpenRouter API key
     BAHULAM_CONFIG_DIR        Override config directory (default: ~/.bahulam)
-    KEPLER_CONFIG_DIR         Legacy config directory override
-    KEPLER_RECONNECT_MAX_ELAPSED_MS
+    BAHULAM_CONFIG_DIR         Legacy config directory override
+    BAHULAM_RECONNECT_MAX_ELAPSED_MS
                             Max reconnect window for dropped streams
     BAHULAM_TTY_MODE=stable Scrollback-safe transcript if fixed dock redraws leak
     BAHULAM_BLOCK_SEPARATOR Tool/content separator: space, dotted, or off

package/src/terminal/repl-explore.mjs

@@ -25,7 +25,7 @@ const EXPLORE_TOOL_CATEGORY = new Map([
 ]);
 
 export function exploreCollapseEnabled() {
-  return process.env.KEPLER_EXPLORE_COLLAPSE !== '0';
+  return process.env.BAHULAM_EXPLORE_COLLAPSE !== '0';
 }
 
 export function isExploreTool(tool) {

package/src/terminal/repl-render.mjs

@@ -211,12 +211,12 @@ function exploreRunTotal() {
 }
 
 function exploreSnapshotEvery() {
-  const n = Number.parseInt(process.env.KEPLER_EXPLORE_SNAPSHOT_EVERY || '8', 10);
+  const n = Number.parseInt(process.env.BAHULAM_EXPLORE_SNAPSHOT_EVERY || '8', 10);
   return Number.isFinite(n) ? Math.max(1, n) : 8;
 }
 
 function exploreSnapshotMs() {
-  const n = Number.parseInt(process.env.KEPLER_EXPLORE_SNAPSHOT_MS || '900', 10);
+  const n = Number.parseInt(process.env.BAHULAM_EXPLORE_SNAPSHOT_MS || '900', 10);
   return Number.isFinite(n) ? Math.max(100, n) : 900;
 }
 

package/src/terminal/repl.mjs

@@ -64,6 +64,7 @@ import { SkillInstaller } from '../skills/installer.mjs';
 import { SkillsLoader } from '../skills/loader.mjs';
 import { openSkillsPicker, formatSkillsList } from './skills-picker.mjs';
 import { createAgentFile, isVsCodeTerminal, listLocalAgents, openAgentFile, syncAgentsToBackend } from '../agents/scaffold.mjs';
+import { PluginRegistry } from '../plugins/registry.mjs';
 import { SessionManager } from '../core/session-manager.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
 import { pickModelOverridesForm } from './repl-model-form.mjs';
@@ -875,7 +876,7 @@ function handleAttachmentsCommand(rest = '', ctx) {
 }
 
 async function confirmVisionUpload(ctx, attachments, { skip = false } = {}) {
-  if (skip || process.env.KEPLER_VISION_CONFIRM === '0' || process.env.KEPLER_VISION_CONFIRM === 'false') {
+  if (skip || process.env.BAHULAM_VISION_CONFIRM === '0' || process.env.BAHULAM_VISION_CONFIRM === 'false') {
     return true;
   }
   if (!ctx?._rl || !process.stdin.isTTY) return false;
@@ -1044,6 +1045,43 @@ function printSkillsUsage() {
   process.stderr.write(`  ${c.dim('  /skills update <name> [--project]')}\n`);
 }
 
+async function handlePluginsCommand(rest = '', ctx) {
+  const argv = String(rest || '').trim().split(/\s+/).filter(Boolean);
+  const action = (argv[0] || 'list').toLowerCase();
+  const known = new Set(['install', 'validate', 'check', 'lint', 'list', 'ls', 'remove', 'rm', 'uninstall', 'enable', 'disable', 'info', 'update', 'upgrade']);
+
+  // Bare `/plugins <name>` (no action verb) is treated as info, mirroring how
+  // `/skills <name>` behaves. `/plugins` alone lists.
+  if (!known.has(action)) {
+    if (argv.length === 0) return handlePluginsCommand('list', ctx);
+    return handlePluginsCommand(`info ${argv.join(' ')}`, ctx);
+  }
+
+  const args = {
+    action, pluginName: null, source: null,
+    global: true, force: false, ref: null, json: false,
+  };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') args.global = false;
+    else if (a === '--global') args.global = true;
+    else if (a === '--force' || a === '-f') args.force = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--ref' || a === '--tag' || a === '--branch') args.ref = argv[++i];
+    else if (!a.startsWith('-')) {
+      if (action === 'install' && !args.source) args.source = a;
+      else if (['validate', 'check', 'lint'].includes(action) && !args.source && !args.pluginName) {
+        if (a.includes('/')) args.source = a; else args.pluginName = a;
+      }
+      else if (!args.pluginName) args.pluginName = a;
+    }
+  }
+  try {
+    const { handlePluginManagementCommand } = await import('../commands/plugin-manage.mjs');
+    await handlePluginManagementCommand(args, { cwd: process.cwd(), throwOnError: true });
+  } catch { /* already printed by the handler */ }
+}
+
 async function handleSkillsCommand(rest = '', ctx) {
   const parts = String(rest || '').trim().split(/\s+/).filter(Boolean);
   const hasFlag = (flag) => parts.includes(flag);
@@ -3720,6 +3758,11 @@ async function handleCommand(input, ctx) {
       await handleSkillsCommand(rest, ctx);
       return;
 
+    case '/plugin':
+    case '/plugins':
+      await handlePluginsCommand(rest, ctx);
+      return;
+
     case '/explore':
     case '/review':
     case '/architect': {
@@ -3813,6 +3856,7 @@ export async function startTerminalRepl() {
     return createToolExecutor({
       checkpoints,
       hookRunner,
+      pluginRegistry,
       interactionHandler: askUserInteraction,
       onAutoRegisterStart: shouldShowIndexStatus ? (root) => {
         const name = path.basename(root || safeCwd()) || root || 'project';
@@ -3828,6 +3872,7 @@ export async function startTerminalRepl() {
     });
   }
 
+  const pluginRegistry = new PluginRegistry().scan();
   let toolExecutor = null;
   const skipPerms = cliArgs.skipPermissions;
   let approval = new ApprovalManager({ autoApprove: skipPerms, cwd: safeCwd(), policy: effectivePolicy.policy });
@@ -4224,8 +4269,8 @@ export async function startTerminalRepl() {
     printBanner(auth);
 
     // Preflight diagnostic (PRD-055 §9). Non-blocking; opt-out via
-    // KEPLER_NO_PREFLIGHT=1 (used by tests / scripted runs).
-    if (process.env.KEPLER_NO_PREFLIGHT !== '1' && !cliArgs.skipPermissions) {
+    // BAHULAM_NO_PREFLIGHT=1 (used by tests / scripted runs).
+    if (process.env.BAHULAM_NO_PREFLIGHT !== '1' && !cliArgs.skipPermissions) {
       try { await runPreflight({ auth, cwd: safeCwd(), version: VERSION }); }
       catch { /* preflight is best-effort */ }
     }
@@ -4902,6 +4947,7 @@ export async function startTerminalRepl() {
         token: creds.token,
         toolExecutor,
         approvalManager: approval,
+        pluginRegistry,
       });
     }
     const client = streamClient;

package/src/tools/analyze-image.mjs

@@ -92,7 +92,7 @@ export const AnalyzeImageTool = {
     if (!creds.backendUrl || !creds.token) {
       return {
         success: false,
-        output: 'analyze_image requires CLI auth. Run `bahulam-code login` or set B0_TOKEN/KEPLER_TOKEN.',
+        output: 'analyze_image requires CLI auth. Run `bahulam-code login` or set B0_TOKEN.',
         _tool: 'analyze_image',
       };
     }

package/src/tools/project-overview.mjs

@@ -73,7 +73,7 @@ const PROJECT_MARKERS = [
     'pom.xml', 'build.gradle', 'build.gradle.kts', 'settings.gradle',  // Java/Kotlin
     'Makefile', 'CMakeLists.txt',  // C/C++
     'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
-    'AGENTS.md', 'CLAUDE.md', 'KEPLER.md',  // Agent config lives at root
+    'AGENTS.md', 'BAHULAM.md', 'CLAUDE.md',  // Agent config lives at root
     '.editorconfig',               // Broad but a strong "this is a repo" signal
 ];
 
@@ -350,7 +350,7 @@ function defaultScratchRoots() {
         '/private/tmp',
         os.tmpdir(),
         process.env.TMPDIR,
-        ...(process.env.KEPLER_SCRATCH_ROOTS || '')
+        ...(process.env.BAHULAM_SCRATCH_ROOTS || '')
             .split(path.delimiter)
             .map(s => s.trim())
             .filter(Boolean),
@@ -399,13 +399,13 @@ export class ProjectRegistry {
 
     // PRD-69 project context is live metadata, not index cache. Re-read it on
     // every registration attempt so repeated get_project_overview calls pick up
-    // .bahulam/KEPLER.md, goal/plan/style, skills, AGENTS.md, etc. changes.
+    // .bahulam/BAHULAM.md, goal/plan/style, skills, AGENTS.md, etc. changes.
     _attachLiveContext(resource, root) {
-        // Resolver — prefers .bahulam/, falls back to .kepler/ for legacy projects.
         const bahulamDir = projectConfigDir(root);
         resource.environment = detectEnvironment();
-        resource.project_context = _readIfExists(bahulamDir, 'KEPLER.md', 10000) ||
-            _readIfExists(root, 'KEPLER.md', 10000) ||
+        resource.project_context = _readIfExists(root, 'AGENTS.md', 10000) ||
+            _readIfExists(bahulamDir, 'BAHULAM.md', 10000) ||
+            _readIfExists(root, 'BAHULAM.md', 10000) ||
             _readIfExists(bahulamDir, 'project.md', 8000);
         resource.style = _readIfExists(bahulamDir, 'style.md', 4000);
         resource.goal = _readIfExists(bahulamDir, 'goal.md', 2000);
@@ -413,7 +413,7 @@ export class ProjectRegistry {
         resource.skills_index = _scanSkills(bahulamDir);
 
         if (!resource.project_context) {
-            for (const name of ['.bahulam.md', 'AGENTS.md', 'CLAUDE.md']) {
+            for (const name of ['.bahulam.md', 'BAHULAM.md', 'AGENTS.md', 'CLAUDE.md']) {
                 const content = _readIfExists(root, name, 8000);
                 if (content) { resource.project_context = content; break; }
             }

package/src/ui/slash-commands.mjs

@@ -47,6 +47,8 @@ export const COMMANDS = {
   '/agents':      'List available agents',
   '/subagents':   'Alias of /agents (list/create/edit/sync sub-agents)',
   '/skills':      'List / install / view / remove skills (SKILL.md bundles)',
+  '/plugins':     'List / install / info / update / remove plugins (tools + agents + views)',
+  '/plugin':      'Alias of /plugins',
   '/run':         'Run a sub-agent or synced workflow',
   '/explore':     'Code explorer agent',
   '/review':      'Code review agent',
@@ -162,6 +164,22 @@ export const HELP_GROUPS = [
       ['/skills update <name>', 'Reinstall from the recorded source'],
     ],
   },
+  {
+    key: 'plugins',
+    title: 'Plugins',
+    summary: 'community-authored tools, agents, and workspace views',
+    commands: [
+      ['/plugins', 'List installed plugins'],
+      ['/plugins install <git-url|path|name>', 'Install from git URL, local path, or awesome-bahulam-plugins name'],
+      ['/plugins install <src> --project', 'Install into .bahulam/plugins (project scope)'],
+      ['/plugins install <src> --ref <tag>', 'Pin a git ref'],
+      ['/plugins validate <path|name>', 'Preflight a plugin without installing (schema + handlers + collisions)'],
+      ['/plugins info <name>', 'Show manifest details + install origin'],
+      ['/plugins enable|disable <name>', 'Toggle without deleting'],
+      ['/plugins update <name>', 'Pull the latest for git-installed plugins'],
+      ['/plugins remove <name>', 'Uninstall a plugin'],
+    ],
+  },
   {
     key: 'workflows',
     title: 'Workflows',