From e4203698502ba2b62a31a79b41522f74093256be Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Thu, 2 Jul 2026 15:47:31 -0700
Subject: [PATCH] =?UTF-8?q?docs:=20plugins=20are=20explicit=20opt-in=20?=
 =?UTF-8?q?=E2=80=94=20correct=20the=20README=20scale=20section=20and=20pl?=
 =?UTF-8?q?ugins=20config=20comment?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A clean-room install smoke of the published GA pair caught the README telling
scale-up users the native provider is auto-detected. It is not, by design: the
loader (loadPlugins) does no auto-detection — undefined means no plugins, and
only an explicit plugins: ['@soulcraft/cor'] loads the native engine (loud
failure if it can't). The stale comment on the plugins config field in the
public types claimed auto-detection and is corrected to match the loader; one
phrase in the plugin-author guide likewise.
---
 README.md                 |  9 ++++++---
 RELEASES.md               |  8 ++++++++
 docs/PLUGINS.md           |  2 +-
 src/types/brainy.types.ts | 11 ++++++-----
 4 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 9cecf3a1..8d0516a2 100644
--- a/README.md
+++ b/README.md
@@ -181,11 +181,14 @@ npm install @soulcraft/cor
 ```
 
 ```javascript
-const brain = new Brainy({ storage: { type: 'filesystem', path: './data' } })
-await brain.init()        // Cor auto-detected — same code, native engines underneath
+const brain = new Brainy({
+  plugins: ['@soulcraft/cor'],     // explicit opt-in — brainy never auto-loads a package
+  storage: { type: 'filesystem', path: './data' }
+})
+await brain.init()                 // same code — native engines underneath
 ```
 
-[`@soulcraft/cor`](https://www.npmjs.com/package/@soulcraft/cor) (Brainy 8.x ↔ Cor 3.x, version-matched) registers Rust implementations behind every provider seam: SIMD distance kernels, memory-mapped storage, a disk-native vector index that doesn't need your dataset in RAM, durable LSM field/graph indexes that serve cold opens instantly, and native aggregation. Recall@10 measured **0.99 / 0.96 / 0.96 at 1M / 10M / 100M vectors** in Cor's release gate.
+Plugins are explicit: an engine swap is always visible in your config, and a listed plugin that fails to load fails **loud** — never a silent fallback to the JS engines. [`@soulcraft/cor`](https://www.npmjs.com/package/@soulcraft/cor) (Brainy 8.x ↔ Cor 3.x, version-matched) registers Rust implementations behind every provider seam: SIMD distance kernels, memory-mapped storage, a disk-native vector index that doesn't need your dataset in RAM, durable LSM field/graph indexes that serve cold opens instantly, and native aggregation. Recall@10 measured **0.99 / 0.96 / 0.96 at 1M / 10M / 100M vectors** in Cor's release gate.
 
 Open core, commercial accelerator: Brainy is MIT and complete on its own; Cor is licensed and funds both.
 
diff --git a/RELEASES.md b/RELEASES.md
index e5a34145..13e38dac 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -10,6 +10,14 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so
 
 ---
 
+## v8.0.8 — 2026-07-02 (docs-only patch on the GA)
+
+Corrects the README's scale-up section: the native provider is **not** auto-detected — plugins are
+**explicit opt-in** (`new Brainy({ plugins: ['@soulcraft/cor'] })`; brainy never auto-imports a
+package you didn't list, and a listed plugin that fails to load throws rather than silently falling
+back to the JS engines). Also fixes the stale `plugins` config comment in the public types and one
+phrase in the plugin-author guide. No code change.
+
 ## v8.0.7 — 2026-07-02 (GA, npm tag `latest`)
 
 > **Why 8.0.7:** npm permanently retires unpublished version numbers, and `8.0.0`–`8.0.6` were
diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md
index 28a77011..1d590c81 100644
--- a/docs/PLUGINS.md
+++ b/docs/PLUGINS.md
@@ -70,7 +70,7 @@ export default myPlugin
 
 ### 2. Package exports
 
-Your package must export the plugin as the default export so brainy's auto-detection works:
+Your package must export the plugin as the default export so brainy's plugin loader can resolve it:
 
 ```typescript
 // index.ts
diff --git a/src/types/brainy.types.ts b/src/types/brainy.types.ts
index ffb684f3..7d2c2552 100644
--- a/src/types/brainy.types.ts
+++ b/src/types/brainy.types.ts
@@ -1804,11 +1804,12 @@ export interface BrainyConfig {
   eagerEmbeddings?: boolean
 
   // Plugin configuration
-  // Controls which plugins are loaded during init()
-  // - undefined (default): Auto-detect installed plugins (@soulcraft/cor, etc.)
-  // - false: No plugins — skip auto-detection entirely
-  // - []: No plugins — skip auto-detection entirely
-  // - ['@soulcraft/cor']: Load only specified plugins, no auto-detection
+  // Controls which plugins are loaded during init(). Plugins are explicit
+  // opt-in — brainy NEVER auto-imports a package that isn't listed here.
+  // - undefined (default): no plugins loaded (same as [] / false)
+  // - false / []: no plugins loaded
+  // - ['@soulcraft/cor']: load exactly these packages; a listed plugin that
+  //   fails to load or is invalid THROWS (loud, never a silent JS fallback)
   plugins?: string[] | false
 
   // Logging configuration