docorbit 0.1.0

package/apps/cli/src/commands/add.ts

@@ -0,0 +1,44 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { IngestionPipeline } from '../../../../packages/core/src/index.ts';
+import { formatIngestionResult } from '../formatters/terminal.ts';
+
+export interface AddCommandOptions {
+  json?: boolean;
+  dbPath?: string;
+  maxPages?: number;
+  allowLocalhost?: boolean;
+}
+
+export async function runAddCommand(targetUrl: string, options: AddCommandOptions = {}): Promise<void> {
+  if (!targetUrl) {
+    console.error('Error: Please provide a documentation target URL.');
+    console.error('Usage: docorbit add <url> [--json] [--db <path>]');
+    process.exit(1);
+  }
+
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repository = new DocOrbitRepository(db);
+
+  try {
+    const pipeline = new IngestionPipeline(repository, {
+      allowLocalhostForTesting: options.allowLocalhost,
+      crawlerConfig: {
+        maxPages: options.maxPages || 50,
+      },
+    });
+
+    const result = await pipeline.ingest(targetUrl);
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatIngestionResult(result));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Ingestion Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/api.ts

@@ -0,0 +1,38 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { resolveProjectContext } from '../../../../packages/workspace/src/index.ts';
+import type { ApiCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatApiEndpoints } from '../formatters/terminal.ts';
+
+export async function runApiCommand(query: string = '', options: ApiCommandOptions = {}): Promise<void> {
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repository = new DocOrbitRepository(db);
+
+  try {
+    let effectiveDocVersion = options.docVersion;
+
+    if (options.projectDir) {
+      const projContext = resolveProjectContext(options.projectDir, query, repository);
+      if (projContext.matchedDependency && !effectiveDocVersion) {
+        effectiveDocVersion = projContext.matchedDependency.targetDocVersion;
+      }
+    }
+
+    const endpoints = repository.searchApiEndpoints(query, {
+      method: options.method,
+      docVersion: effectiveDocVersion,
+      limit: options.limit || 20,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(endpoints, null, 2));
+    } else {
+      console.log(formatApiEndpoints(endpoints, query));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit API Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/context.ts

@@ -0,0 +1,47 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { RetrievalEngine } from '../../../../packages/retrieval/src/index.ts';
+import { formatContextPackage } from '../formatters/terminal.ts';
+
+export interface ContextCommandOptions {
+  json?: boolean;
+  dbPath?: string;
+  tokens?: number;
+  maxChunks?: number;
+  snapshotId?: string;
+  docVersion?: string;
+  projectDir?: string;
+}
+
+export async function runContextCommand(task: string, options: ContextCommandOptions = {}): Promise<void> {
+  if (!task) {
+    console.error('Error: Please provide a coding task description.');
+    console.error('Usage: docorbit context "<task>" [--tokens <n>] [--doc-version <ver>] [--project <dir>] [--json] [--db <path>]');
+    process.exit(1);
+  }
+
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repository = new DocOrbitRepository(db);
+  const engine = new RetrievalEngine(repository);
+
+  try {
+    const pkg = await engine.buildContext(task, {
+      tokenBudget: options.tokens || 3000,
+      maxChunks: options.maxChunks,
+      snapshotId: options.snapshotId,
+      docVersion: options.docVersion,
+      projectDir: options.projectDir,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(pkg, null, 2));
+    } else {
+      console.log(formatContextPackage(pkg));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Context Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/dashboard.ts

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { DashboardServer } from '../../../../packages/core/src/index.ts';
+import { c } from '../formatters/colors.ts';
+
+export interface DashboardCommandOptions {
+  port?: number;
+  host?: string;
+  projectDir?: string;
+  dbPath?: string;
+  noOpen?: boolean;
+}
+
+export async function runDashboardCommand(options: DashboardCommandOptions = {}): Promise<void> {
+  const projectDir = options.projectDir ? path.resolve(options.projectDir) : process.cwd();
+  const dbPath = options.dbPath || path.join(projectDir, '.docorbit', 'docorbit.db');
+  const port = options.port || 3737;
+  const host = options.host || '127.0.0.1';
+
+  const db = new DocOrbitDb(dbPath);
+  const repo = new DocOrbitRepository(db);
+
+  const server = new DashboardServer({
+    repo,
+    projectDir,
+    dbPath,
+  });
+
+  try {
+    const info = await server.start(port, host);
+    console.log(`\n${c.bold(c.cyan('DocOrbit Local Dashboard'))}`);
+    console.log(`${c.dim('Documentation Intelligence & Verification Layer')}\n`);
+    console.log(`  ${c.green('●')} Server running at: ${c.bold(c.underline(info.url))}`);
+    console.log(`  ${c.dim('Database:')} ${dbPath}`);
+    console.log(`  ${c.dim('Workspace:')} ${projectDir}`);
+    console.log(`  ${c.dim('Security:')} ${c.yellow('untrusted documentation boundary enforced')}\n`);
+    console.log(c.dim('Press Ctrl+C to stop.\n'));
+
+    // Keep process alive until interrupted
+    await new Promise<void>((resolve) => {
+      const shutdown = async () => {
+        console.log(`\n${c.dim('Stopping dashboard server...')}`);
+        await server.stop();
+        db.close();
+        resolve();
+      };
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+    });
+  } catch (err: any) {
+    db.close();
+    console.error(c.red(`Failed to start dashboard server: ${err.message}`));
+    process.exit(1);
+  }
+}

package/apps/cli/src/commands/diff.ts

@@ -0,0 +1,30 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { DiffService } from '../../../../packages/verification/src/index.ts';
+import type { DiffCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatDiffReport } from '../formatters/terminal.ts';
+
+export async function runDiffCommand(target: string = '', options: DiffCommandOptions = {}): Promise<void> {
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repo = new DocOrbitRepository(db);
+
+  try {
+    const service = new DiffService(repo);
+    const { result } = service.diffDocs({
+      fromVersion: options.from,
+      toVersion: options.to,
+      sourceId: options.source || (target && !target.startsWith('-') ? target : undefined),
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatDiffReport(result));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Diff Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/evaluate.ts

@@ -0,0 +1,133 @@
+import { BenchmarkRunner } from '../../../../packages/evaluation/src/index.ts';
+import type { AgentEvaluationStrategy, EvaluationSplit } from '../../../../packages/evaluation/src/index.ts';
+import { c } from '../formatters/colors.ts';
+
+export interface EvaluateCommandOptions {
+  split?: string;
+  strategy?: string;
+  task?: string;
+  output?: string;
+  json?: boolean;
+  verbose?: boolean;
+  /** Offline simulation mode — no network required, for CI regression only */
+  simulation?: boolean;
+}
+
+export async function handleEvaluateCommand(options: EvaluateCommandOptions = {}): Promise<void> {
+  const sim = options.simulation ?? false;
+  const runner = new BenchmarkRunner({ simulation: sim });
+
+  const split: EvaluationSplit | 'all' =
+    options.split === 'train'
+      ? 'train'
+      : options.split === 'eval'
+        ? 'eval'
+        : options.split === 'verification'
+          ? 'verification'
+          : 'all';
+
+  let strategies: AgentEvaluationStrategy[] | undefined;
+  if (options.strategy) {
+    const list = options.strategy.split(',').map((s) => s.trim());
+    strategies = list as AgentEvaluationStrategy[];
+  }
+
+  const tasks = options.task ? [options.task] : undefined;
+
+  if (!options.json) {
+    const modeLabel = sim
+      ? c.yellow('[SIMULATION MODE — offline CI, no network]')
+      : c.green('[REAL MODE — requires network access]');
+    console.log(c.bold(c.cyan('\n=== DocOrbit Real-World Agent Evaluation Benchmark ===')));
+    console.log(modeLabel);
+    if (!sim) {
+      console.log(c.gray('  Context7: real context7-mcp stdio subprocess (context7.com)'));
+      console.log(c.gray('  Firecrawl: real /v1/scrape API (api.firecrawl.dev)'));
+      console.log(c.gray('  Official Docs Fetch: direct HTTPS fetch to official docs URLs'));
+      console.log(c.gray('  DocOrbit: real in-process MCP server\n'));
+    }
+    console.log(`Split: ${c.yellow(split)} | Strategies: ${strategies ? strategies.join(', ') : 'all'}`);
+    console.log(`Artifacts: ${options.output || 'eval-results/'}\n`);
+  }
+
+  const report = await runner.run({
+    split,
+    strategies,
+    tasks,
+    outputDir: options.output,
+    verbose: options.verbose,
+    simulation: sim,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  const modeTag = sim ? ' [SIMULATION]' : ' [REAL]';
+  console.log(c.bold(c.green(`\nEvaluation Complete${modeTag} — ${report.totalTasks} tasks\n`)));
+
+  const sDocs = report.byStrategy.agent_official_docs_fetch || report.byStrategy.agent_web_search;
+  const sFC = report.byStrategy.agent_firecrawl;
+  const sDR = report.byStrategy.agent_docorbit;
+
+  if (sDocs && sC7 && sDR) {
+    const pct = (n: number) => `${(n * 100).toFixed(1)}%`;
+
+    if (sFC) {
+      const hr = '---------------------------------------------------------------------------------------------------------------------';
+      console.log(hr);
+      console.log(c.bold(`| ${'Metric'.padEnd(32)}| ${'Official Docs Fetch'.padEnd(21)}| ${'Firecrawl'.padEnd(14)}| ${'Context7'.padEnd(14)}| ${'DocOrbit'.padEnd(14)}|`));
+      console.log(hr);
+
+      const row = (label: string, vDocs: string, vFC: string, vC7: string, vDR: string) =>
+        `| ${label.padEnd(32)}| ${vDocs.padEnd(21)}| ${vFC.padEnd(14)}| ${vC7.padEnd(14)}| ${vDR.padEnd(14)}|`;
+
+      console.log(row('Overall Task Success Rate', pct(sDocs.overallSuccessRate), pct(sFC.overallSuccessRate), pct(sC7.overallSuccessRate), pct(sDR.overallSuccessRate)));
+      console.log(row('Held-Out Eval Success Rate', pct(sDocs.evalSuccessRate), pct(sFC.evalSuccessRate), pct(sC7.evalSuccessRate), pct(sDR.evalSuccessRate)));
+      console.log(row('Correct Version Selection', pct(sDocs.versionAccuracy), pct(sFC.versionAccuracy), pct(sC7.versionAccuracy), pct(sDR.versionAccuracy)));
+      console.log(row('Retrieval Precision@k', pct(sDocs.meanPrecision), pct(sFC.meanPrecision), pct(sC7.meanPrecision), pct(sDR.meanPrecision)));
+      console.log(row('Retrieval Recall@k', pct(sDocs.meanRecall), pct(sFC.meanRecall), pct(sC7.meanRecall), pct(sDR.meanRecall)));
+      console.log(row('Mean Token Ingestion', `~${Math.round(sDocs.meanTokens)}`, `~${Math.round(sFC.meanTokens)}`, `~${Math.round(sC7.meanTokens)}`, `~${Math.round(sDR.meanTokens)}`));
+      console.log(row('Context Prep Latency', `~${sDocs.meanLatencyMs.toFixed(0)}ms`, `~${sFC.meanLatencyMs.toFixed(0)}ms`, `~${sC7.meanLatencyMs.toFixed(0)}ms`, `~${sDR.meanLatencyMs.toFixed(0)}ms`));
+      console.log(row('Avg Tool Calls per Task', sDocs.meanToolCalls.toFixed(1), sFC.meanToolCalls.toFixed(1), sC7.meanToolCalls.toFixed(1), sDR.meanToolCalls.toFixed(1)));
+      console.log(row('AST Verification Catches', '—', '—', '—', String(sDR.totalVerificationCatches)));
+      console.log(row('Verification False Positives', '—', '—', '—', String(sDR.falsePositives)));
+      console.log(hr);
+    } else {
+      const hr = '--------------------------------------------------------------------------------------------------';
+      console.log(hr);
+      console.log(c.bold(`| ${'Metric'.padEnd(36)}| ${'Official Docs Fetch'.padEnd(21)}| ${'Context7'.padEnd(14)}| ${'DocOrbit'.padEnd(14)}|`));
+      console.log(hr);
+
+      const row = (label: string, vDocs: string, vC7: string, vDR: string) =>
+        `| ${label.padEnd(36)}| ${vDocs.padEnd(21)}| ${vC7.padEnd(14)}| ${vDR.padEnd(14)}|`;
+
+      console.log(row('Overall Task Success Rate', pct(sDocs.overallSuccessRate), pct(sC7.overallSuccessRate), pct(sDR.overallSuccessRate)));
+      console.log(row('Held-Out Eval Success Rate', pct(sDocs.evalSuccessRate), pct(sC7.evalSuccessRate), pct(sDR.evalSuccessRate)));
+      console.log(row('Correct Version Selection', pct(sDocs.versionAccuracy), pct(sC7.versionAccuracy), pct(sDR.versionAccuracy)));
+      console.log(row('Retrieval Precision@k', pct(sDocs.meanPrecision), pct(sC7.meanPrecision), pct(sDR.meanPrecision)));
+      console.log(row('Retrieval Recall@k', pct(sDocs.meanRecall), pct(sC7.meanRecall), pct(sDR.meanRecall)));
+      console.log(row('Mean Token Ingestion', `~${Math.round(sDocs.meanTokens)}`, `~${Math.round(sC7.meanTokens)}`, `~${Math.round(sDR.meanTokens)}`));
+      console.log(row('Context Prep Latency', `~${sDocs.meanLatencyMs.toFixed(0)}ms`, `~${sC7.meanLatencyMs.toFixed(0)}ms`, `~${sDR.meanLatencyMs.toFixed(0)}ms`));
+      console.log(row('Avg Tool Calls per Task', sDocs.meanToolCalls.toFixed(1), sC7.meanToolCalls.toFixed(1), sDR.meanToolCalls.toFixed(1)));
+      console.log(row('AST Verification Catches', '—', '—', String(sDR.totalVerificationCatches)));
+      console.log(row('Verification False Positives', '—', '—', String(sDR.falsePositives)));
+      console.log(hr);
+    }
+
+    if (sDR) {
+      console.log(c.bold(c.cyan('\nAST Code Verification (`check_api`) Performance:')));
+      console.log(`  Total Verification Catches: ${c.bold(String(sDR.totalVerificationCatches))}`);
+      console.log(`  False Positives on Valid Code: ${c.bold(String(sDR.falsePositives))}`);
+      console.log(`  Dynamic/Ambiguous Fallback Rate: ${c.bold(pct(sDR.insufficientEvidenceRate))}`);
+    }
+
+    if (sim) {
+      console.log(c.yellow('\n⚠  Results above are from simulated runners. Run without --simulation for real results.'));
+    }
+    console.log(c.gray('\n* Official Docs Fetch baseline directly fetches known official documentation URLs over HTTPS rather than querying a search engine.'));
+  }
+
+  console.log(`\nRaw artifacts: ${c.cyan(options.output || 'eval-results/')}\n`);
+}

package/apps/cli/src/commands/examples.ts

@@ -0,0 +1,39 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { resolveProjectContext } from '../../../../packages/workspace/src/index.ts';
+import type { ExamplesCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatIndexedExamples } from '../formatters/terminal.ts';
+
+export async function runExamplesCommand(task: string = '', options: ExamplesCommandOptions = {}): Promise<void> {
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repository = new DocOrbitRepository(db);
+
+  try {
+    let effectiveDocVersion = options.docVersion;
+
+    if (options.projectDir) {
+      const projContext = resolveProjectContext(options.projectDir, task, repository);
+      if (projContext.matchedDependency && !effectiveDocVersion) {
+        effectiveDocVersion = projContext.matchedDependency.targetDocVersion;
+      }
+    }
+
+    const examples = repository.searchIndexedExamples(task, {
+      language: options.language,
+      framework: options.framework,
+      docVersion: effectiveDocVersion,
+      limit: options.limit || 10,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(examples, null, 2));
+    } else {
+      console.log(formatIndexedExamples(examples, task));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Examples Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/export.ts

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { ExportService } from '../../../../packages/export/src/index.ts';
+import type { ExportFormat } from '../../../../packages/shared/src/index.ts';
+import { c } from '../formatters/colors.ts';
+
+export interface ExportCommandOptions {
+  format?: string;
+  output?: string;
+  stdout?: boolean;
+  projectDir?: string;
+  docVersion?: string;
+  targetSource?: string;
+  json?: boolean;
+  dbPath?: string;
+}
+
+export async function runExportCommand(
+  formatArg?: string,
+  options: ExportCommandOptions = {}
+): Promise<void> {
+  const rawFormat = (formatArg || options.format || 'agents.md').toLowerCase();
+  const validFormats: ExportFormat[] = ['agents.md', 'claude.md', 'skill.md', 'llms.txt', 'docs-map.md'];
+
+  let format: ExportFormat = 'agents.md';
+  if (validFormats.includes(rawFormat as ExportFormat)) {
+    format = rawFormat as ExportFormat;
+  } else if (rawFormat === 'agents' || rawFormat === 'agent') {
+    format = 'agents.md';
+  } else if (rawFormat === 'claude') {
+    format = 'claude.md';
+  } else if (rawFormat === 'skill') {
+    format = 'skill.md';
+  } else if (rawFormat === 'llms' || rawFormat === 'llms.txt') {
+    format = 'llms.txt';
+  } else if (rawFormat === 'map' || rawFormat === 'docs-map') {
+    format = 'docs-map.md';
+  }
+
+  const projectDir = options.projectDir ? path.resolve(options.projectDir) : process.cwd();
+  const dbPath = options.dbPath || path.join(projectDir, '.docorbit', 'docorbit.db');
+
+  const db = new DocOrbitDb(dbPath);
+  const repo = new DocOrbitRepository(db);
+  const service = new ExportService(repo);
+
+  try {
+    if (options.stdout) {
+      const result = await service.generateExport({
+        format,
+        projectDir,
+        docVersion: options.docVersion,
+        targetSource: options.targetSource,
+        stdout: true,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        process.stdout.write(result.content);
+      }
+      return;
+    }
+
+    const result = await service.writeExport({
+      format,
+      projectDir,
+      docVersion: options.docVersion,
+      targetSource: options.targetSource,
+      outputPath: options.output,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(`\n${c.bold(c.green('✓'))} Generated ${c.bold(format)} for coding agents`);
+    console.log(`  ${c.dim('Output file:')}      ${c.cyan(result.outputPath || 'stdout')}`);
+    console.log(`  ${c.dim('Doc Version:')}      ${result.metadata.docVersion || 'global/latest'}`);
+    console.log(`  ${c.dim('Estimated Tokens:')} ~${result.metadata.tokenEstimate.toLocaleString()}`);
+    console.log(`  ${c.dim('APIs Included:')}    ${result.metadata.totalApis}`);
+    console.log(`  ${c.dim('Pitfalls Included:')}${result.metadata.totalPitfalls}`);
+    console.log(`  ${c.dim('Indexed Sources:')}  ${result.metadata.sources.length}`);
+    console.log(`  ${c.dim('Security Boundary:')}${c.yellow('untrusted documentation preserved')}\n`);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/impact.ts

@@ -0,0 +1,31 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { ImpactAnalysisService } from '../../../../packages/verification/src/index.ts';
+import type { ImpactCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatImpactReport } from '../formatters/terminal.ts';
+
+export async function runImpactCommand(target: string = '', options: ImpactCommandOptions = {}): Promise<void> {
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repo = new DocOrbitRepository(db);
+
+  try {
+    const service = new ImpactAnalysisService(repo);
+    const { result } = service.analyzeImpact({
+      projectDir: options.projectDir || process.cwd(),
+      fromVersion: options.from,
+      toVersion: options.to,
+      sourceId: options.source || (target && !target.startsWith('-') ? target : undefined),
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatImpactReport(result));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Impact Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/init.ts

@@ -0,0 +1,69 @@
+import { resolve } from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import {
+  detectWorkspaceDependencies,
+  generateDocsLock,
+  readDocsLock,
+  writeDocsLock,
+} from '../../../../packages/workspace/src/index.ts';
+
+export interface InitCommandOptions {
+  json?: boolean;
+  dbPath?: string;
+}
+
+export async function runInitCommand(
+  targetDir: string = '.',
+  options: InitCommandOptions = {}
+): Promise<void> {
+  const projectDir = resolve(targetDir);
+  const dbPath = options.dbPath || '.docorbit/docorbit.db';
+  const db = new DocOrbitDb(dbPath);
+  const repository = new DocOrbitRepository(db);
+
+  try {
+    const scanResult = detectWorkspaceDependencies(projectDir);
+    const existingLock = readDocsLock(projectDir);
+    const lock = generateDocsLock(scanResult, repository, existingLock);
+
+    writeDocsLock(projectDir, lock);
+
+    if (options.json) {
+      console.log(JSON.stringify(lock, null, 2));
+      return;
+    }
+
+    console.log(`\n=== DocOrbit Project Initialization ===`);
+    console.log(`Workspace Root:  ${projectDir}`);
+    console.log(`Ecosystems:     ${scanResult.ecosystems.length > 0 ? scanResult.ecosystems.join(', ') : 'None detected'}`);
+    console.log(`Manifests:       ${scanResult.manifestsFound.join(', ') || 'None'}`);
+    console.log(`Dependencies:    ${scanResult.dependencies.length} detected`);
+
+    const lockedCount = Object.keys(lock.dependencies).length;
+    console.log(`Locked Docs:     ${lockedCount} dependencies resolved to documentation\n`);
+
+    if (lockedCount > 0) {
+      console.log('-----------------------------------------------------------------------------');
+      console.log('| Package               | Project Ver | Doc Ver  | Match       | Confidence |');
+      console.log('-----------------------------------------------------------------------------');
+      for (const [key, dep] of Object.entries(lock.dependencies)) {
+        const pkgPad = key.padEnd(21).slice(0, 21);
+        const projPad = dep.resolvedDependencyVersion.padEnd(11).slice(0, 11);
+        const docPad = dep.docVersion.padEnd(8).slice(0, 8);
+        const matchPad = dep.matchType.padEnd(11).slice(0, 11);
+        const confPad = (dep.confidence * 100).toFixed(0) + '%';
+        console.log(`| ${pkgPad} | ${projPad} | ${docPad} | ${matchPad} | ${confPad.padEnd(10)} |`);
+      }
+      console.log('-----------------------------------------------------------------------------');
+      console.log(`\nGenerated deterministic docs.lock at: ${projectDir}/docs.lock\n`);
+    } else {
+      console.log('Note: No ingested documentation matched detected dependencies.');
+      console.log('Tip: Use `docorbit add <url>` to ingest official docs for your dependencies, then re-run `docorbit init`.\n');
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Init Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

package/apps/cli/src/commands/inspect.ts

@@ -0,0 +1,30 @@
+import { inspectDocumentation } from '../../../../packages/core/src/index.ts';
+import { formatInspectionReport } from '../formatters/terminal.ts';
+
+export interface InspectCommandOptions {
+  json?: boolean;
+  allowLocalhost?: boolean;
+}
+
+export async function runInspectCommand(targetUrl: string, options: InspectCommandOptions = {}): Promise<void> {
+  if (!targetUrl) {
+    console.error('Error: Please provide a documentation target URL.');
+    console.error('Usage: docorbit inspect <url> [--json]');
+    process.exit(1);
+  }
+
+  try {
+    const report = await inspectDocumentation(targetUrl, {
+      allowLocalhostForTesting: options.allowLocalhost,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatInspectionReport(report));
+    }
+  } catch (err: unknown) {
+    console.error(`DocOrbit Inspection Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}