From e507fcfe066f0a937bac380b39c28f685f5c55e6 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Tue, 14 Oct 2025 14:59:38 -0700
Subject: [PATCH] docs: fix S3 examples and improve storage path visibility

- Fix 4 S3 storage configuration examples in README
- Change from 'options: {bucket}' to 's3Storage: {bucketName}'
- Enhance FileSystemStorage logs to show resolved path
- Helps users verify their configuration is working correctly
- Prevents silent failures like v3.43.2 persistence regression
---
 README.md                     | 40 +++++++++++++++++++++++++++++++----
 src/storage/storageFactory.ts | 15 +++++++------
 2 files changed, 45 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 8cf21ee3..e8d0f84b 100644
--- a/README.md
+++ b/README.md
@@ -543,12 +543,28 @@ await brain.import('research.pdf')       // PDF with table extraction
 ```javascript
 // Single node (default)
 const brain = new Brainy({
-    storage: {type: 's3', options: {bucket: 'my-data'}}
+    storage: {
+        type: 's3',
+        s3Storage: {
+            bucketName: 'my-data',
+            region: 'us-east-1',
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+        }
+    }
 })
 
 // Distributed cluster - just add one flag!
 const brain = new Brainy({
-    storage: {type: 's3', options: {bucket: 'my-data'}},
+    storage: {
+        type: 's3',
+        s3Storage: {
+            bucketName: 'my-data',
+            region: 'us-east-1',
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+        }
+    },
     distributed: true  // That's it! Everything else is automatic
 })
 ```
@@ -568,7 +584,15 @@ import { Brainy, NounType } from '@soulcraft/brainy'
 
 // Ingestion nodes (optimized for writes)
 const ingestionNode = new Brainy({
-    storage: {type: 's3', options: {bucket: 'social-data'}},
+    storage: {
+        type: 's3',
+        s3Storage: {
+            bucketName: 'social-data',
+            region: 'us-east-1',
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+        }
+    },
     distributed: true,
     writeOnly: true  // Optimized for high-throughput writes
 })
@@ -585,7 +609,15 @@ blueskyStream.on('post', async (post) => {
 
 // Search nodes (optimized for queries)
 const searchNode = new Brainy({
-    storage: {type: 's3', options: {bucket: 'social-data'}},
+    storage: {
+        type: 's3',
+        s3Storage: {
+            bucketName: 'social-data',
+            region: 'us-east-1',
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+        }
+    },
     distributed: true,
     readOnly: true  // Optimized for fast queries
 })
diff --git a/src/storage/storageFactory.ts b/src/storage/storageFactory.ts
index 788c101e..4780303a 100644
--- a/src/storage/storageFactory.ts
+++ b/src/storage/storageFactory.ts
@@ -306,12 +306,13 @@ export async function createStorage(
       )
       return new MemoryStorage()
     }
-    console.log('Using file system storage (forced)')
+    const fsPath = getFileSystemPath(options)
+    console.log(`Using file system storage (forced): ${fsPath}`)
     try {
       const { FileSystemStorage } = await import(
         './adapters/fileSystemStorage.js'
       )
-      return new FileSystemStorage(getFileSystemPath(options))
+      return new FileSystemStorage(fsPath)
     } catch (error) {
       console.warn(
         'Failed to load FileSystemStorage, falling back to memory storage:',
@@ -359,12 +360,13 @@ export async function createStorage(
           )
           return new MemoryStorage()
         }
-        console.log('Using file system storage')
+        const fsPath = getFileSystemPath(options)
+        console.log(`Using file system storage: ${fsPath}`)
         try {
           const { FileSystemStorage } = await import(
             './adapters/fileSystemStorage.js'
           )
-          return new FileSystemStorage(getFileSystemPath(options))
+          return new FileSystemStorage(fsPath)
         } catch (error) {
           console.warn(
             'Failed to load FileSystemStorage, falling back to memory storage:',
@@ -538,12 +540,13 @@ export async function createStorage(
         process.versions &&
         process.versions.node
       ) {
-        console.log('Using file system storage (auto-detected)')
+        const fsPath = getFileSystemPath(options)
+        console.log(`Using file system storage (auto-detected): ${fsPath}`)
         try {
           const { FileSystemStorage } = await import(
             './adapters/fileSystemStorage.js'
           )
-          return new FileSystemStorage(getFileSystemPath(options))
+          return new FileSystemStorage(fsPath)
         } catch (fsError) {
           console.warn(
             'Failed to load FileSystemStorage, falling back to memory storage:',