trellis 2.0.8 → 2.0.13

package/src/cli/index.ts

@@ -16,6 +16,18 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve, join } from 'path';
 import { TrellisVcsEngine } from '../engine.js';
+import { TrellisKernel } from '../core/kernel/trellis-kernel.js';
+import { SqliteKernelBackend } from '../core/persist/sqlite-backend.js';
+import { QueryEngine, parseQuery, parseSimple } from '../core/query/index.js';
+import {
+  OntologyRegistry,
+  validateStore,
+  builtinOntologies,
+} from '../core/ontology/index.js';
+import { buildRAGContext } from '../embeddings/auto-embed.js';
+import { VectorStore } from '../embeddings/store.js';
+import { embed } from '../embeddings/model.js';
+import { EmbeddingManager } from '../embeddings/search.js';
 import { importFromGit } from '../git/git-importer.js';
 import { exportToGit } from '../git/git-exporter.js';
 import {
@@ -2381,6 +2393,933 @@ program
     }
   });
 
+// ---------------------------------------------------------------------------
+// Kernel helper — boots a TrellisKernel from a .trellis directory
+// ---------------------------------------------------------------------------
+
+function bootKernel(rootPath: string): TrellisKernel {
+  const dbPath = join(rootPath, '.trellis', 'kernel.db');
+  const backend = new SqliteKernelBackend(dbPath);
+  const kernel = new TrellisKernel({
+    backend,
+    agentId: `agent:${process.env.USER ?? 'unknown'}`,
+  });
+  kernel.boot();
+  return kernel;
+}
+
+// ---------------------------------------------------------------------------
+// trellis entity
+// ---------------------------------------------------------------------------
+
+const entityCmd = program
+  .command('entity')
+  .description('Manage graph entities (generic CRUD)');
+
+entityCmd
+  .command('create')
+  .description('Create a new entity in the graph')
+  .requiredOption('-i, --id <id>', 'Entity ID (e.g. "project:my-app")')
+  .requiredOption('-t, --type <type>', 'Entity type (e.g. "Project", "User")')
+  .option('-a, --attr <attrs...>', 'Attributes as key=value pairs')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const attrs: Record<string, any> = {};
+      if (opts.attr) {
+        for (const pair of opts.attr) {
+          const eq = pair.indexOf('=');
+          if (eq === -1) continue;
+          const key = pair.slice(0, eq);
+          let val: any = pair.slice(eq + 1);
+          // Auto-coerce numbers and booleans
+          if (val === 'true') val = true;
+          else if (val === 'false') val = false;
+          else if (!isNaN(Number(val)) && val !== '') val = Number(val);
+          attrs[key] = val;
+        }
+      }
+
+      const result = await kernel.createEntity(opts.id, opts.type, attrs);
+      console.log(chalk.green(`✓ Entity created: ${chalk.bold(opts.id)}`));
+      console.log(`  ${chalk.dim('Type:')}  ${opts.type}`);
+      console.log(`  ${chalk.dim('Facts:')} ${result.factsDelta.added}`);
+      console.log(`  ${chalk.dim('Op:')}    ${result.op.hash.slice(0, 32)}…`);
+    } finally {
+      kernel.close();
+    }
+  });
+
+entityCmd
+  .command('get')
+  .description('Get an entity by ID')
+  .argument('<id>', 'Entity ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('--json', 'Output as JSON')
+  .action((id: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const entity = kernel.getEntity(id);
+      if (!entity) {
+        console.error(chalk.red(`Entity not found: ${id}`));
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        const obj: Record<string, any> = { id: entity.id, type: entity.type };
+        for (const f of entity.facts) {
+          if (f.a !== 'type') obj[f.a] = f.v;
+        }
+        obj._links = entity.links.map((l) => ({
+          attribute: l.a,
+          target: l.e2,
+          source: l.e1,
+        }));
+        console.log(JSON.stringify(obj, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold(`${entity.type}: ${entity.id}\n`));
+      for (const f of entity.facts) {
+        console.log(`  ${chalk.dim(f.a.padEnd(20))} ${f.v}`);
+      }
+      if (entity.links.length > 0) {
+        console.log(`\n  ${chalk.bold('Links:')}`);
+        for (const l of entity.links) {
+          const dir = l.e1 === id ? '→' : '←';
+          const other = l.e1 === id ? l.e2 : l.e1;
+          console.log(`    ${dir} ${chalk.dim(l.a)} ${other}`);
+        }
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+entityCmd
+  .command('update')
+  .description('Update attributes on an existing entity')
+  .argument('<id>', 'Entity ID')
+  .requiredOption('-a, --attr <attrs...>', 'Attributes as key=value pairs')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const updates: Record<string, any> = {};
+      for (const pair of opts.attr) {
+        const eq = pair.indexOf('=');
+        if (eq === -1) continue;
+        const key = pair.slice(0, eq);
+        let val: any = pair.slice(eq + 1);
+        if (val === 'true') val = true;
+        else if (val === 'false') val = false;
+        else if (!isNaN(Number(val)) && val !== '') val = Number(val);
+        updates[key] = val;
+      }
+
+      await kernel.updateEntity(id, updates);
+      console.log(chalk.green(`✓ Updated ${chalk.bold(id)}`));
+      for (const [k, v] of Object.entries(updates)) {
+        console.log(`  ${chalk.dim(k)} = ${v}`);
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+entityCmd
+  .command('delete')
+  .description('Delete an entity and all its facts/links')
+  .argument('<id>', 'Entity ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const entity = kernel.getEntity(id);
+      if (!entity) {
+        console.error(chalk.red(`Entity not found: ${id}`));
+        process.exit(1);
+      }
+      await kernel.deleteEntity(id);
+      console.log(chalk.green(`✓ Deleted entity ${chalk.bold(id)}`));
+    } finally {
+      kernel.close();
+    }
+  });
+
+entityCmd
+  .command('list')
+  .description('List entities, optionally filtered by type')
+  .option('-t, --type <type>', 'Filter by entity type')
+  .option('-f, --filter <filters...>', 'Attribute filters as key=value')
+  .option('--json', 'Output as JSON')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      let filters: Record<string, any> | undefined;
+      if (opts.filter) {
+        filters = {};
+        for (const pair of opts.filter) {
+          const eq = pair.indexOf('=');
+          if (eq === -1) continue;
+          const key = pair.slice(0, eq);
+          let val: any = pair.slice(eq + 1);
+          if (val === 'true') val = true;
+          else if (val === 'false') val = false;
+          else if (!isNaN(Number(val)) && val !== '') val = Number(val);
+          filters[key] = val;
+        }
+      }
+
+      const entities = kernel.listEntities(opts.type, filters);
+
+      if (opts.json) {
+        const out = entities.map((e) => {
+          const obj: Record<string, any> = { id: e.id, type: e.type };
+          for (const f of e.facts) {
+            if (f.a !== 'type') obj[f.a] = f.v;
+          }
+          return obj;
+        });
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
+
+      if (entities.length === 0) {
+        console.log(chalk.dim('No entities found.'));
+        return;
+      }
+
+      const typeLabel = opts.type ? ` (type: ${opts.type})` : '';
+      console.log(chalk.bold(`Entities (${entities.length})${typeLabel}\n`));
+      for (const e of entities) {
+        const nameFact = e.facts.find((f) => f.a === 'name');
+        const name = nameFact ? ` ${chalk.white(String(nameFact.v))}` : '';
+        console.log(
+          `  ${chalk.cyan(e.type.padEnd(16))} ${chalk.bold(e.id)}${name}`,
+        );
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis fact
+// ---------------------------------------------------------------------------
+
+const factCmd = program
+  .command('fact')
+  .description('Add or remove individual facts on entities');
+
+factCmd
+  .command('add')
+  .description('Add a fact to an entity')
+  .argument('<entity>', 'Entity ID')
+  .argument('<attribute>', 'Attribute name')
+  .argument('<value>', 'Value')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (entity: any, attribute: any, value: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      // Auto-coerce
+      let val: any = value;
+      if (val === 'true') val = true;
+      else if (val === 'false') val = false;
+      else if (!isNaN(Number(val)) && val !== '') val = Number(val);
+
+      await kernel.addFact(entity, attribute, val);
+      console.log(
+        chalk.green(
+          `✓ Added fact: ${chalk.bold(entity)}.${attribute} = ${val}`,
+        ),
+      );
+    } finally {
+      kernel.close();
+    }
+  });
+
+factCmd
+  .command('remove')
+  .description('Remove a fact from an entity')
+  .argument('<entity>', 'Entity ID')
+  .argument('<attribute>', 'Attribute name')
+  .argument('<value>', 'Value to remove')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (entity: any, attribute: any, value: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      let val: any = value;
+      if (val === 'true') val = true;
+      else if (val === 'false') val = false;
+      else if (!isNaN(Number(val)) && val !== '') val = Number(val);
+
+      await kernel.removeFact(entity, attribute, val);
+      console.log(
+        chalk.green(
+          `✓ Removed fact: ${chalk.bold(entity)}.${attribute} = ${val}`,
+        ),
+      );
+    } finally {
+      kernel.close();
+    }
+  });
+
+factCmd
+  .command('query')
+  .description('Query facts by entity or attribute')
+  .option('-e, --entity <id>', 'Filter by entity ID')
+  .option('-a, --attribute <attr>', 'Filter by attribute')
+  .option('--json', 'Output as JSON')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const store = kernel.getStore();
+      let facts;
+
+      if (opts.entity) {
+        facts = store.getFactsByEntity(opts.entity);
+      } else if (opts.attribute) {
+        facts = store.getFactsByAttribute(opts.attribute);
+      } else {
+        facts = store.getAllFacts();
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(facts, null, 2));
+        return;
+      }
+
+      if (facts.length === 0) {
+        console.log(chalk.dim('No facts found.'));
+        return;
+      }
+
+      console.log(chalk.bold(`Facts (${facts.length})\n`));
+      for (const f of facts.slice(0, 100)) {
+        console.log(
+          `  ${chalk.cyan(f.e.padEnd(24))} ${chalk.dim(f.a.padEnd(20))} ${f.v}`,
+        );
+      }
+      if (facts.length > 100) {
+        console.log(chalk.dim(`  … +${facts.length - 100} more`));
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis link
+// ---------------------------------------------------------------------------
+
+const linkCmd = program
+  .command('link')
+  .description('Add or remove links between entities');
+
+linkCmd
+  .command('add')
+  .description('Add a link between two entities')
+  .argument('<source>', 'Source entity ID')
+  .argument('<attribute>', 'Relationship attribute')
+  .argument('<target>', 'Target entity ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (source: any, attribute: any, target: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      await kernel.addLink(source, attribute, target);
+      console.log(
+        chalk.green(
+          `✓ Link: ${chalk.bold(source)} —[${attribute}]→ ${chalk.bold(target)}`,
+        ),
+      );
+    } finally {
+      kernel.close();
+    }
+  });
+
+linkCmd
+  .command('remove')
+  .description('Remove a link between two entities')
+  .argument('<source>', 'Source entity ID')
+  .argument('<attribute>', 'Relationship attribute')
+  .argument('<target>', 'Target entity ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (source: any, attribute: any, target: any, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      await kernel.removeLink(source, attribute, target);
+      console.log(
+        chalk.green(
+          `✓ Removed: ${chalk.bold(source)} —[${attribute}]→ ${chalk.bold(target)}`,
+        ),
+      );
+    } finally {
+      kernel.close();
+    }
+  });
+
+linkCmd
+  .command('query')
+  .description('Query links for an entity')
+  .option('-e, --entity <id>', 'Entity ID')
+  .option('-a, --attribute <attr>', 'Relationship attribute')
+  .option('--json', 'Output as JSON')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const store = kernel.getStore();
+      let links;
+
+      if (opts.entity && opts.attribute) {
+        links = store.getLinksByEntityAndAttribute(opts.entity, opts.attribute);
+      } else if (opts.entity) {
+        links = store.getLinksByEntity(opts.entity);
+      } else if (opts.attribute) {
+        links = store.getLinksByAttribute(opts.attribute);
+      } else {
+        links = store.getAllLinks();
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(links, null, 2));
+        return;
+      }
+
+      if (links.length === 0) {
+        console.log(chalk.dim('No links found.'));
+        return;
+      }
+
+      console.log(chalk.bold(`Links (${links.length})\n`));
+      for (const l of links.slice(0, 100)) {
+        console.log(
+          `  ${chalk.cyan(l.e1)} —[${chalk.dim(l.a)}]→ ${chalk.cyan(l.e2)}`,
+        );
+      }
+      if (links.length > 100) {
+        console.log(chalk.dim(`  … +${links.length - 100} more`));
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis query
+// ---------------------------------------------------------------------------
+
+program
+  .command('query')
+  .description('Execute an EQL-S query against the graph')
+  .argument(
+    '<query>',
+    'EQL-S query string (or "find ?e where attr = value" shorthand)',
+  )
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('--json', 'Output as JSON')
+  .action((queryStr: string, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const store = kernel.getStore();
+      const engine = new QueryEngine(store);
+
+      let q;
+      try {
+        q = parseSimple(queryStr);
+      } catch {
+        try {
+          q = parseQuery(queryStr);
+        } catch (e: any) {
+          console.error(chalk.red(`Parse error: ${e.message}`));
+          process.exit(1);
+          return;
+        }
+      }
+
+      const result = engine.execute(q!);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result.bindings, null, 2));
+      } else {
+        if (result.count === 0) {
+          console.log(chalk.dim('No results.'));
+        } else {
+          // Determine columns
+          const cols =
+            result.bindings.length > 0 ? Object.keys(result.bindings[0]) : [];
+
+          // Print header
+          console.log(chalk.bold(cols.map((c) => `?${c}`).join('\t')));
+          console.log(chalk.dim('─'.repeat(cols.length * 20)));
+
+          // Print rows
+          for (const row of result.bindings) {
+            console.log(cols.map((c) => String(row[c] ?? '')).join('\t'));
+          }
+
+          console.log(
+            chalk.dim(
+              `\n${result.count} result(s) in ${result.executionTime.toFixed(1)}ms`,
+            ),
+          );
+        }
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis repl
+// ---------------------------------------------------------------------------
+
+program
+  .command('repl')
+  .description('Interactive EQL-S query shell')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    const store = kernel.getStore();
+    const engine = new QueryEngine(store);
+
+    console.log(chalk.cyan.bold('Trellis EQL-S REPL'));
+    console.log(
+      chalk.dim(
+        'Type EQL-S queries or "find ?e where attr = value" shorthand.',
+      ),
+    );
+    console.log(chalk.dim('Type .exit to quit, .help for help.\n'));
+
+    const readline = await import('readline');
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: chalk.green('eql> '),
+    });
+
+    rl.prompt();
+
+    rl.on('line', (line: string) => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        rl.prompt();
+        return;
+      }
+
+      if (trimmed === '.exit' || trimmed === '.quit') {
+        kernel.close();
+        rl.close();
+        return;
+      }
+
+      if (trimmed === '.help') {
+        console.log(`
+${chalk.bold('EQL-S Query Syntax:')}
+  ${chalk.cyan('SELECT')} ?var1 ?var2 ${chalk.cyan('WHERE')} { patterns } [${chalk.cyan('FILTER')} ...] [${chalk.cyan('ORDER BY')} ...] [${chalk.cyan('LIMIT')} n]
+
+${chalk.bold('Pattern types:')}
+  ${chalk.yellow('[?e "attr" "value"]')}     Fact pattern (entity, attribute, value)
+  ${chalk.yellow('(?src "rel" ?tgt)')}       Link pattern (source, relationship, target)
+  ${chalk.yellow('NOT [?e "attr" ?v]')}      Negation
+  ${chalk.yellow('OR { ... } { ... }')}      Disjunction
+
+${chalk.bold('Shorthand:')}
+  ${chalk.yellow('find ?e where type = "Project"')}
+
+${chalk.bold('Commands:')}
+  .exit / .quit   Exit the REPL
+  .stats          Show store statistics
+  .help           Show this help
+`);
+        rl.prompt();
+        return;
+      }
+
+      if (trimmed === '.stats') {
+        const facts = store.getAllFacts();
+        const links = store.getAllLinks();
+        const types = new Set(
+          facts.filter((f) => f.a === 'type').map((f) => f.v),
+        );
+        console.log(`  Facts: ${facts.length}`);
+        console.log(`  Links: ${links.length}`);
+        console.log(`  Entity types: ${[...types].join(', ') || '(none)'}`);
+        rl.prompt();
+        return;
+      }
+
+      try {
+        let q;
+        try {
+          q = parseSimple(trimmed);
+        } catch {
+          q = parseQuery(trimmed);
+        }
+
+        const result = engine.execute(q);
+
+        if (result.count === 0) {
+          console.log(chalk.dim('No results.'));
+        } else {
+          const cols = Object.keys(result.bindings[0]);
+          console.log(chalk.bold(cols.map((c) => `?${c}`).join('\t')));
+          for (const row of result.bindings) {
+            console.log(cols.map((c) => String(row[c] ?? '')).join('\t'));
+          }
+          console.log(
+            chalk.dim(
+              `${result.count} result(s) in ${result.executionTime.toFixed(1)}ms`,
+            ),
+          );
+        }
+      } catch (e: any) {
+        console.error(chalk.red(`Error: ${e.message}`));
+      }
+
+      rl.prompt();
+    });
+
+    rl.on('close', () => {
+      kernel.close();
+      console.log(chalk.dim('Goodbye.'));
+    });
+  });
+
+// ---------------------------------------------------------------------------
+// trellis ontology
+// ---------------------------------------------------------------------------
+
+const ontologyCmd = program
+  .command('ontology')
+  .description('Manage and inspect ontology schemas');
+
+ontologyCmd
+  .command('list')
+  .description('List all registered ontologies (built-in + custom)')
+  .action(() => {
+    const registry = new OntologyRegistry();
+    for (const o of builtinOntologies) registry.register(o);
+
+    const schemas = registry.list();
+    if (schemas.length === 0) {
+      console.log(chalk.dim('No ontologies registered.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Ontologies (${schemas.length})\n`));
+    for (const s of schemas) {
+      console.log(`  ${chalk.cyan(s.id)} ${chalk.dim(`v${s.version}`)}`);
+      console.log(
+        `    ${s.name}${s.description ? ` — ${chalk.dim(s.description)}` : ''}`,
+      );
+      console.log(`    Entities: ${s.entities.map((e) => e.name).join(', ')}`);
+      console.log(
+        `    Relations: ${s.relations.map((r) => r.name).join(', ')}`,
+      );
+      console.log();
+    }
+  });
+
+ontologyCmd
+  .command('inspect')
+  .description('Inspect a specific ontology or entity type')
+  .argument(
+    '<name>',
+    'Ontology ID (e.g. "trellis:project") or entity type name (e.g. "Project")',
+  )
+  .action((name: string) => {
+    const registry = new OntologyRegistry();
+    for (const o of builtinOntologies) registry.register(o);
+
+    // Try as ontology ID first
+    const schema = registry.get(name);
+    if (schema) {
+      console.log(
+        chalk.bold(
+          `${schema.name} ${chalk.dim(`(${schema.id} v${schema.version})`)}`,
+        ),
+      );
+      if (schema.description) console.log(chalk.dim(schema.description));
+      console.log();
+
+      console.log(chalk.bold('Entity Types:'));
+      for (const e of schema.entities) {
+        console.log(
+          `\n  ${chalk.cyan.bold(e.name)}${e.abstract ? chalk.dim(' (abstract)') : ''}${e.extends ? chalk.dim(` extends ${e.extends}`) : ''}`,
+        );
+        if (e.description) console.log(`  ${chalk.dim(e.description)}`);
+        for (const a of e.attributes) {
+          const flags = [
+            a.required ? chalk.red('required') : null,
+            a.enum ? `enum[${a.enum.join('|')}]` : null,
+            a.default !== undefined ? `default=${a.default}` : null,
+          ]
+            .filter(Boolean)
+            .join(', ');
+          console.log(
+            `    ${chalk.yellow(a.name)}: ${a.type}${flags ? ` (${flags})` : ''}`,
+          );
+        }
+      }
+
+      if (schema.relations.length > 0) {
+        console.log(chalk.bold('\nRelations:'));
+        for (const r of schema.relations) {
+          console.log(
+            `  ${chalk.yellow(r.name)}: ${r.sourceTypes.join('|')} → ${r.targetTypes.join('|')}${r.cardinality ? ` [${r.cardinality}]` : ''}`,
+          );
+        }
+      }
+      return;
+    }
+
+    // Try as entity type name
+    const def = registry.getEntityDef(name);
+    if (def) {
+      const ontId = registry.getEntityOntology(name);
+      console.log(chalk.bold(`${def.name}`) + chalk.dim(` (from ${ontId})`));
+      if (def.description) console.log(chalk.dim(def.description));
+      if (def.abstract)
+        console.log(chalk.dim('(abstract — cannot be instantiated)'));
+      if (def.extends) console.log(chalk.dim(`extends ${def.extends}`));
+
+      console.log(chalk.bold('\nAttributes:'));
+      for (const a of def.attributes) {
+        const flags = [
+          a.required ? chalk.red('required') : null,
+          a.enum ? `enum[${a.enum.join('|')}]` : null,
+          a.default !== undefined ? `default=${a.default}` : null,
+        ]
+          .filter(Boolean)
+          .join(', ');
+        console.log(
+          `  ${chalk.yellow(a.name)}: ${a.type}${flags ? ` (${flags})` : ''}`,
+        );
+        if (a.description) console.log(`    ${chalk.dim(a.description)}`);
+      }
+
+      const rels = registry.getRelationsForType(name);
+      if (rels.length > 0) {
+        console.log(chalk.bold('\nRelations:'));
+        for (const r of rels) {
+          const dir = r.sourceTypes.includes(name) ? '→' : '←';
+          console.log(
+            `  ${chalk.yellow(r.name)} ${dir} ${r.sourceTypes.includes(name) ? r.targetTypes.join('|') : r.sourceTypes.join('|')}`,
+          );
+        }
+      }
+      return;
+    }
+
+    console.error(chalk.red(`Unknown ontology or entity type: "${name}"`));
+    console.log(
+      chalk.dim(
+        'Available ontologies: ' +
+          registry
+            .list()
+            .map((s) => s.id)
+            .join(', '),
+      ),
+    );
+    console.log(
+      chalk.dim('Available types: ' + registry.listEntityTypes().join(', ')),
+    );
+  });
+
+ontologyCmd
+  .command('validate')
+  .description(
+    'Validate all entities in the graph against registered ontologies',
+  )
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('--strict', 'Treat unknown types as errors')
+  .action((opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const kernel = bootKernel(rootPath);
+    try {
+      const registry = new OntologyRegistry();
+      for (const o of builtinOntologies) registry.register(o);
+
+      const store = kernel.getStore();
+      const result = validateStore(store, registry);
+
+      if (result.errors.length > 0) {
+        console.log(chalk.red.bold(`✗ ${result.errors.length} error(s):\n`));
+        for (const err of result.errors) {
+          console.log(
+            `  ${chalk.red('ERROR')} ${chalk.bold(err.entityId)} (${err.entityType}) → ${err.field}: ${err.message}`,
+          );
+        }
+      }
+
+      if (result.warnings.length > 0) {
+        console.log(
+          chalk.yellow.bold(`\n⚠ ${result.warnings.length} warning(s):\n`),
+        );
+        for (const w of result.warnings) {
+          console.log(
+            `  ${chalk.yellow('WARN')}  ${chalk.bold(w.entityId)} (${w.entityType}) → ${w.field}: ${w.message}`,
+          );
+        }
+      }
+
+      if (result.valid && result.warnings.length === 0) {
+        console.log(chalk.green('✓ All entities pass ontology validation.'));
+      } else if (result.valid) {
+        console.log(chalk.green('\n✓ Valid (with warnings).'));
+      } else {
+        console.log(chalk.red('\n✗ Validation failed.'));
+      }
+    } finally {
+      kernel.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis ask
+// ---------------------------------------------------------------------------
+
+program
+  .command('ask')
+  .description('Natural language search over the graph (semantic search)')
+  .argument('<question>', 'Natural language query')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('-n, --limit <n>', 'Max results', '5')
+  .option('--json', 'Output as JSON')
+  .option('--rag', 'Output as RAG context (for LLM consumption)')
+  .action(async (question: string, opts: any) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const dbPath = join(rootPath, '.trellis', 'embeddings.db');
+    const vectorStore = new VectorStore(dbPath);
+
+    try {
+      const limit = parseInt(opts.limit, 10) || 5;
+
+      if (opts.rag) {
+        const ctx = await buildRAGContext(question, vectorStore, embed, {
+          maxChunks: limit,
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(ctx, null, 2));
+        } else {
+          console.log(chalk.bold.cyan('RAG Context'));
+          console.log(chalk.dim(`Query: ${ctx.query}`));
+          console.log(
+            chalk.dim(
+              `Chunks: ${ctx.chunks.length} | ~${ctx.estimatedTokens} tokens\n`,
+            ),
+          );
+          for (const c of ctx.chunks) {
+            console.log(
+              chalk.yellow(
+                `[${c.score.toFixed(3)}] ${c.entityId} (${c.chunkType})`,
+              ),
+            );
+            console.log(c.content);
+            console.log();
+          }
+        }
+      } else {
+        const queryVector = await embed(question);
+        const results = vectorStore.search(queryVector, { limit });
+
+        if (opts.json) {
+          console.log(
+            JSON.stringify(
+              results.map((r) => ({
+                score: r.score,
+                entityId: r.chunk.entityId,
+                chunkType: r.chunk.chunkType,
+                content: r.chunk.content,
+              })),
+              null,
+              2,
+            ),
+          );
+        } else {
+          if (results.length === 0) {
+            console.log(
+              chalk.dim(
+                'No results. Run `trellis reindex` first to build the embedding index.',
+              ),
+            );
+          } else {
+            console.log(chalk.bold(`Results for: "${question}"\n`));
+            for (const r of results) {
+              const score = chalk.dim(`[${r.score.toFixed(3)}]`);
+              const entity = chalk.cyan(r.chunk.entityId);
+              const type = chalk.dim(`(${r.chunk.chunkType})`);
+              console.log(`${score} ${entity} ${type}`);
+              const preview =
+                r.chunk.content.length > 200
+                  ? r.chunk.content.slice(0, 200) + '…'
+                  : r.chunk.content;
+              console.log(`  ${preview}\n`);
+            }
+          }
+        }
+      }
+    } catch (err: any) {
+      if (err.message?.includes('No transformers')) {
+        console.error(chalk.red('Embedding model not available.'));
+        console.error(chalk.dim('Install: bun add @huggingface/transformers'));
+      } else {
+        console.error(chalk.red(`Error: ${err.message}`));
+      }
+    } finally {
+      vectorStore.close();
+    }
+  });
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------