feat: harden plugin system wiring and add developer diagnostics

Fix critical wiring bugs that prevented plugin-provided implementations
from being used at runtime. All CRUD operations, fork/checkout/clear,
batch embedding, neural APIs, and VFS path resolution now properly
dispatch through the plugin registry.

Changes:
- Wire graphIndex to storage for getVerbsBySource() fast path
- Replace instanceof checks with duck-typing (indexIsTypeAware flag)
  so plugin HNSW indexes work in add/update/delete/search
- Add createIndex() shared helper for plugin HNSW factory
- Fix fork/checkout/clear to use plugin factories for metadataIndex,
  graphIndex, and HNSW instead of hardcoding JS constructors
- Add three-tier embedBatch priority: embedBatch > embeddings > WASM
- Skip WASM warmup/eagerEmbeddings when plugin provides embeddings
- Fix PathResolver metadataIndex access (was looking on storage)
- Use global UnifiedCache in SemanticPathResolver
- Wire plugin distance function through neural APIs
- Add diagnostics() method and CLI command for provider inspection
- Add requireProviders() for production fail-fast assertions
- Add init-time provider summary log
- Add plugin developer documentation (docs/PLUGINS.md)
- Export DiagnosticsResult type

src/cli/commands/core.ts

@@ -918,5 +918,55 @@ export const coreCommands = {
       console.error(chalk.red(error.message))
       process.exit(1)
     }
+  },
+
+  /**
+   * Show plugin and provider diagnostics
+   */
+  async diagnostics(options: CoreOptions) {
+    try {
+      const brain = getBrainy()
+      await brain.init()
+
+      const diag = brain.diagnostics()
+
+      if (options.json) {
+        formatOutput(diag, options)
+        return
+      }
+
+      console.log(chalk.bold('\nBrainy Diagnostics'))
+      console.log(chalk.dim(`Version: ${diag.version}`))
+      console.log()
+
+      // Plugins
+      console.log(chalk.bold('Plugins:'))
+      if (diag.plugins.count === 0) {
+        console.log(chalk.dim('  (none active)'))
+      } else {
+        for (const name of diag.plugins.active) {
+          console.log(chalk.green(`  ✓ ${name}`))
+        }
+      }
+      console.log()
+
+      // Providers
+      console.log(chalk.bold('Providers:'))
+      for (const [key, info] of Object.entries(diag.providers)) {
+        const icon = info.source === 'plugin' ? chalk.green('✓ plugin') : chalk.dim('default')
+        console.log(`  ${key.padEnd(16)} ${icon}`)
+      }
+      console.log()
+
+      // Indexes
+      console.log(chalk.bold('Indexes:'))
+      console.log(`  HNSW:      ${diag.indexes.hnsw.type} (${diag.indexes.hnsw.size} vectors)`)
+      console.log(`  Metadata:  ${diag.indexes.metadata.type} (initialized: ${diag.indexes.metadata.initialized})`)
+      console.log(`  Graph:     ${diag.indexes.graph.type} (initialized: ${diag.indexes.graph.initialized}, wired: ${diag.indexes.graph.wiredToStorage})`)
+      console.log()
+    } catch (error: any) {
+      console.error(chalk.red('Diagnostics failed: ' + error.message))
+      process.exit(1)
+    }
   }
 }

src/cli/index.ts

@@ -174,6 +174,14 @@ program
   .option('-f, --format <format>', 'Output format (json|csv|jsonl)', 'json')
   .action(coreCommands.export)
 
+program
+  .command('diagnostics')
+  .alias('diag')
+  .description('Show plugin and provider diagnostics')
+  .option('--json', 'Output as JSON')
+  .option('--pretty', 'Pretty print JSON')
+  .action(coreCommands.diagnostics)
+
 // ===== Neural Commands =====
 
 program