From c0bb413a2e7c4bdf459ec5d8639aeee88e9ec0ad Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Mon, 2 Feb 2026 09:29:41 -0800
Subject: [PATCH] docs: update plugin docs to reflect opt-in behavior

Plugins are no longer auto-detected. Updated README and PLUGINS.md
to show explicit plugins config, document all config values, and
fix manual registration example to use brain.use() API.
---
 README.md       | 12 +++++++++++-
 docs/PLUGINS.md | 25 +++++++++++++++++++++----
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 094aba63..07d7cdee 100644
--- a/README.md
+++ b/README.md
@@ -576,12 +576,22 @@ const stats = brain.getCacheStats()  // Performance insights
 
 ### Native Acceleration (Optional)
 
-Install `@soulcraft/cortex` for Rust-powered native acceleration: SIMD distance calculations, native metadata/graph indexes, CRoaring bitmaps, and Candle ML embeddings. Auto-detected — zero configuration required.
+Install `@soulcraft/cortex` for Rust-powered native acceleration: SIMD distance calculations, native metadata/graph indexes, CRoaring bitmaps, and Candle ML embeddings.
 
 ```bash
 npm install @soulcraft/cortex
 ```
 
+```typescript
+const brain = new Brainy({
+  plugins: ['@soulcraft/cortex']
+})
+await brain.init()
+// [brainy] Plugin activated: @soulcraft/cortex
+```
+
+Plugins are opt-in — brainy never auto-imports packages unless you list them in `plugins`.
+
 ---
 
 ## Benchmarks
diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md
index 48ed1b78..944092bd 100644
--- a/docs/PLUGINS.md
+++ b/docs/PLUGINS.md
@@ -6,11 +6,28 @@ Brainy has a plugin system that allows third-party packages to replace internal
 
 Brainy's plugin system uses **named providers** — string keys mapped to implementations. During `init()`, brainy:
 
-1. Auto-detects installed plugin packages via dynamic `import()`
+1. Imports each package listed in the `plugins` config array
 2. Activates each plugin, passing a `BrainyPluginContext`
 3. The plugin calls `context.registerProvider(key, implementation)` for each subsystem it provides
 4. Brainy checks each provider key and wires the implementation into its internal pipeline
 
+Plugins are **opt-in** — brainy never auto-imports packages. You must explicitly list plugins in the config:
+
+```typescript
+const brain = new Brainy({
+  plugins: ['@soulcraft/cortex']  // explicitly load cortex
+})
+```
+
+| `plugins` value | Behavior |
+|---|---|
+| `undefined` (default) | No plugins loaded |
+| `false` | No plugins loaded |
+| `[]` | No plugins loaded |
+| `['@soulcraft/cortex']` | Load only the listed packages |
+
+Plugins registered programmatically via `brain.use(plugin)` are always activated regardless of the `plugins` config.
+
 If no plugin provides a given key, brainy uses its built-in JavaScript implementation. This means brainy works perfectly standalone — plugins only enhance performance or add capabilities.
 
 ## Creating a Plugin
@@ -50,7 +67,7 @@ export { default } from './plugin.js'
 
 ### 3. Registration
 
-**Auto-detection:** Brainy auto-detects plugins by package name. Pass your package name in the brainy config:
+**Config-based:** List your package name in the brainy config:
 
 ```typescript
 const brain = new Brainy({
@@ -59,14 +76,14 @@ const brain = new Brainy({
 await brain.init()
 ```
 
-**Manual registration:** For plugins not installed as npm packages:
+**Programmatic registration:** For plugins not installed as npm packages, use `brain.use()`:
 
 ```typescript
 import { Brainy } from '@soulcraft/brainy'
 import myPlugin from './my-plugin.js'
 
 const brain = new Brainy()
-brain.pluginRegistry.register(myPlugin)
+brain.use(myPlugin)
 await brain.init()
 ```