@soulcraft/brainy 4.2.4 → 4.3.1

package/dist/brainy.d.ts

@@ -76,6 +76,14 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Add an entity to the database
      *
      * @param params - Parameters for adding the entity
+     * @param params.data - Content to embed and store (required)
+     * @param params.type - NounType classification (required)
+     * @param params.metadata - Custom metadata object
+     * @param params.id - Custom ID (auto-generated if not provided)
+     * @param params.vector - Pre-computed embedding vector
+     * @param params.service - Service name for multi-tenancy
+     * @param params.confidence - Type classification confidence (0-1) *New in v4.3.0*
+     * @param params.weight - Entity importance/salience (0-1) *New in v4.3.0*
      * @returns Promise that resolves to the entity ID
      *
      * @example Basic entity creation
@@ -88,6 +96,17 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * console.log(`Created entity: ${id}`)
      * ```
      *
+     * @example Adding with confidence and weight (New in v4.3.0)
+     * ```typescript
+     * const id = await brain.add({
+     *   data: "Machine learning model for sentiment analysis",
+     *   type: NounType.Concept,
+     *   metadata: { accuracy: 0.95, version: "2.1" },
+     *   confidence: 0.92,  // High confidence in Concept classification
+     *   weight: 0.85       // High importance entity
+     * })
+     * ```
+     *
      * @example Adding with custom ID
      * ```typescript
      * const customId = await brain.add({
@@ -126,6 +145,11 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * @param id - The unique identifier of the entity to retrieve
      * @returns Promise that resolves to the entity if found, null if not found
      *
+     * **Entity includes (v4.3.0):**
+     * - `confidence` - Type classification confidence (0-1) if set
+     * - `weight` - Entity importance/salience (0-1) if set
+     * - All standard fields: id, type, data, metadata, vector, timestamps
+     *
      * @example
      * // Basic entity retrieval
      * const entity = await brainy.get('user-123')
@@ -137,6 +161,15 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * }
      *
      * @example
+     * // Accessing confidence and weight (New in v4.3.0)
+     * const entity = await brainy.get('concept-456')
+     * if (entity) {
+     *   console.log(`Type: ${entity.type}`)
+     *   console.log(`Confidence: ${entity.confidence ?? 'N/A'}`)
+     *   console.log(`Weight: ${entity.weight ?? 'N/A'}`)
+     * }
+     *
+     * @example
      * // Working with typed entities
      * interface User {
      *   name: string
@@ -192,6 +225,11 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * }
      */
     get(id: string): Promise<Entity<T> | null>;
+    /**
+     * Create a flattened Result object from entity
+     * Flattens commonly-used entity fields to top level for convenience
+     */
+    private createResult;
     /**
      * Convert a noun from storage to an entity
      */
@@ -353,6 +391,13 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * @param query - Natural language string or structured FindParams object
      * @returns Promise that resolves to array of search results with scores
      *
+     * **Result Structure (v4.3.0):**
+     * Each result includes flattened entity fields for convenient access:
+     * - `metadata`, `type`, `data` - Direct access (flattened from entity)
+     * - `confidence`, `weight` - Entity confidence/importance (if set)
+     * - `entity` - Full Entity object (backward compatible)
+     * - `score` - Search relevance score (0-1)
+     *
      * @example
      * // Natural language queries (most common)
      * const results = await brainy.find('users who work on AI projects')
@@ -371,11 +416,18 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      *   }
      * })
      *
-     * // Process results
+     * // NEW in v4.3.0: Access flattened fields directly
      * for (const result of results) {
-     *   console.log(`Found: ${result.entity.data} (score: ${result.score})`)
+     *   console.log(`Score: ${result.score}`)
+     *   console.log(`Type: ${result.type}`)           // Flattened!
+     *   console.log(`Metadata:`, result.metadata)     // Flattened!
+     *   console.log(`Confidence: ${result.confidence ?? 'N/A'}`)  // Flattened!
+     *   console.log(`Weight: ${result.weight ?? 'N/A'}`)          // Flattened!
      * }
      *
+     * // Backward compatible: Nested access still works
+     * console.log(result.entity.data)  // Also works
+     *
      * @example
      * // Metadata-only filtering (no vector search)
      * const activeUsers = await brainy.find({
@@ -491,7 +543,15 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Find similar entities using vector similarity
      *
      * @param params - Parameters specifying the target for similarity search
-     * @returns Promise that resolves to array of similar entities with similarity scores
+     * @param params.to - Entity ID, Entity object, or Vector to find similar to (required)
+     * @param params.limit - Maximum results (default: 10)
+     * @param params.threshold - Minimum similarity (0-1)
+     * @param params.type - Filter by NounType(s)
+     * @param params.where - Metadata filters
+     * @returns Promise that resolves to array of Result objects with similarity scores (same structure as find())
+     *
+     * **Returns (v4.3.0):**
+     * Same Result structure as find() with flattened fields for convenient access
      *
      * @example
      * // Find entities similar to a specific entity by ID
@@ -500,9 +560,12 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      *   limit: 10
      * })
      *
-     * // Process similarity results
+     * // NEW in v4.3.0: Access flattened fields
      * for (const result of similarDocs) {
-     *   console.log(`Similar entity: ${result.entity.data} (similarity: ${result.score})`)
+     *   console.log(`Similarity: ${result.score}`)
+     *   console.log(`Type: ${result.type}`)              // Flattened!
+     *   console.log(`Metadata:`, result.metadata)        // Flattened!
+     *   console.log(`Confidence: ${result.confidence ?? 'N/A'}`)  // Flattened!
      * }
      *
      * @example
@@ -799,6 +862,32 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     }): Promise<import("./import/ImportCoordinator.js").ImportResult>;
     /**
      * Virtual File System API - Knowledge Operating System
+     *
+     * Returns a cached VFS instance. You must call vfs.init() before use:
+     *
+     * @example After import
+     * ```typescript
+     * await brain.import('./data.xlsx', { vfsPath: '/imports/data' })
+     *
+     * const vfs = brain.vfs()
+     * await vfs.init()  // Required! (safe to call multiple times)
+     * const files = await vfs.readdir('/imports/data')
+     * ```
+     *
+     * @example Direct VFS usage
+     * ```typescript
+     * const vfs = brain.vfs()
+     * await vfs.init()  // Always required before first use
+     * await vfs.writeFile('/docs/readme.md', 'Hello World')
+     * const content = await vfs.readFile('/docs/readme.md')
+     * ```
+     *
+     * **Note:** brain.import() automatically initializes the VFS, so after
+     * an import you can call vfs.init() again (it's idempotent) and immediately
+     * query the imported files.
+     *
+     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs()
+     * return the same instance. This ensures import and user code share state.
      */
     vfs(): VirtualFileSystem;
     /**

package/dist/brainy.js

@@ -205,6 +205,14 @@ export class Brainy {
      * Add an entity to the database
      *
      * @param params - Parameters for adding the entity
+     * @param params.data - Content to embed and store (required)
+     * @param params.type - NounType classification (required)
+     * @param params.metadata - Custom metadata object
+     * @param params.id - Custom ID (auto-generated if not provided)
+     * @param params.vector - Pre-computed embedding vector
+     * @param params.service - Service name for multi-tenancy
+     * @param params.confidence - Type classification confidence (0-1) *New in v4.3.0*
+     * @param params.weight - Entity importance/salience (0-1) *New in v4.3.0*
      * @returns Promise that resolves to the entity ID
      *
      * @example Basic entity creation
@@ -217,6 +225,17 @@ export class Brainy {
      * console.log(`Created entity: ${id}`)
      * ```
      *
+     * @example Adding with confidence and weight (New in v4.3.0)
+     * ```typescript
+     * const id = await brain.add({
+     *   data: "Machine learning model for sentiment analysis",
+     *   type: NounType.Concept,
+     *   metadata: { accuracy: 0.95, version: "2.1" },
+     *   confidence: 0.92,  // High confidence in Concept classification
+     *   weight: 0.85       // High importance entity
+     * })
+     * ```
+     *
      * @example Adding with custom ID
      * ```typescript
      * const customId = await brain.add({
@@ -280,7 +299,10 @@ export class Brainy {
                 _data: params.data, // Store the raw data in metadata
                 noun: params.type,
                 service: params.service,
-                createdAt: Date.now()
+                createdAt: Date.now(),
+                // Preserve confidence and weight if provided
+                ...(params.confidence !== undefined && { confidence: params.confidence }),
+                ...(params.weight !== undefined && { weight: params.weight })
             };
             // v4.0.0: Save vector and metadata separately
             await this.storage.saveNoun({
@@ -301,6 +323,11 @@ export class Brainy {
      * @param id - The unique identifier of the entity to retrieve
      * @returns Promise that resolves to the entity if found, null if not found
      *
+     * **Entity includes (v4.3.0):**
+     * - `confidence` - Type classification confidence (0-1) if set
+     * - `weight` - Entity importance/salience (0-1) if set
+     * - All standard fields: id, type, data, metadata, vector, timestamps
+     *
      * @example
      * // Basic entity retrieval
      * const entity = await brainy.get('user-123')
@@ -312,6 +339,15 @@ export class Brainy {
      * }
      *
      * @example
+     * // Accessing confidence and weight (New in v4.3.0)
+     * const entity = await brainy.get('concept-456')
+     * if (entity) {
+     *   console.log(`Type: ${entity.type}`)
+     *   console.log(`Confidence: ${entity.confidence ?? 'N/A'}`)
+     *   console.log(`Weight: ${entity.weight ?? 'N/A'}`)
+     * }
+     *
+     * @example
      * // Working with typed entities
      * interface User {
      *   name: string
@@ -378,12 +414,34 @@ export class Brainy {
             return this.convertNounToEntity(noun);
         });
     }
+    /**
+     * Create a flattened Result object from entity
+     * Flattens commonly-used entity fields to top level for convenience
+     */
+    createResult(id, score, entity, explanation) {
+        return {
+            id,
+            score,
+            // Flatten common entity fields to top level
+            type: entity.type,
+            metadata: entity.metadata,
+            data: entity.data,
+            confidence: entity.confidence,
+            weight: entity.weight,
+            // Preserve full entity for backward compatibility
+            entity,
+            // Optional score explanation
+            ...(explanation && { explanation })
+        };
+    }
     /**
      * Convert a noun from storage to an entity
      */
     async convertNounToEntity(noun) {
         // Extract metadata - separate user metadata from system metadata
-        const { noun: nounType, service, createdAt, updatedAt, _data, ...userMetadata } = noun.metadata || {};
+        const { noun: nounType, service, createdAt, updatedAt, _data, confidence, // Entity confidence score (0-1)
+        weight, // Entity importance/salience (0-1)
+        ...userMetadata } = noun.metadata || {};
         const entity = {
             id: noun.id,
             vector: noun.vector,
@@ -393,10 +451,16 @@ export class Brainy {
             createdAt: createdAt || Date.now(),
             updatedAt: updatedAt
         };
-        // Only add data field if it exists
+        // Only add optional fields if they exist
         if (_data !== undefined) {
             entity.data = _data;
         }
+        if (confidence !== undefined) {
+            entity.confidence = confidence;
+        }
+        if (weight !== undefined) {
+            entity.weight = weight;
+        }
         return entity;
     }
     /**
@@ -444,7 +508,12 @@ export class Brainy {
                 noun: params.type || existing.type,
                 service: existing.service,
                 createdAt: existing.createdAt,
-                updatedAt: Date.now()
+                updatedAt: Date.now(),
+                // Update confidence and weight if provided, otherwise preserve existing
+                ...(params.confidence !== undefined && { confidence: params.confidence }),
+                ...(params.weight !== undefined && { weight: params.weight }),
+                ...(params.confidence === undefined && existing.confidence !== undefined && { confidence: existing.confidence }),
+                ...(params.weight === undefined && existing.weight !== undefined && { weight: existing.weight })
             };
             // v4.0.0: Save vector and metadata separately
             await this.storage.saveNoun({
@@ -797,6 +866,13 @@ export class Brainy {
      * @param query - Natural language string or structured FindParams object
      * @returns Promise that resolves to array of search results with scores
      *
+     * **Result Structure (v4.3.0):**
+     * Each result includes flattened entity fields for convenient access:
+     * - `metadata`, `type`, `data` - Direct access (flattened from entity)
+     * - `confidence`, `weight` - Entity confidence/importance (if set)
+     * - `entity` - Full Entity object (backward compatible)
+     * - `score` - Search relevance score (0-1)
+     *
      * @example
      * // Natural language queries (most common)
      * const results = await brainy.find('users who work on AI projects')
@@ -815,11 +891,18 @@ export class Brainy {
      *   }
      * })
      *
-     * // Process results
+     * // NEW in v4.3.0: Access flattened fields directly
      * for (const result of results) {
-     *   console.log(`Found: ${result.entity.data} (score: ${result.score})`)
+     *   console.log(`Score: ${result.score}`)
+     *   console.log(`Type: ${result.type}`)           // Flattened!
+     *   console.log(`Metadata:`, result.metadata)     // Flattened!
+     *   console.log(`Confidence: ${result.confidence ?? 'N/A'}`)  // Flattened!
+     *   console.log(`Weight: ${result.weight ?? 'N/A'}`)          // Flattened!
      * }
      *
+     * // Backward compatible: Nested access still works
+     * console.log(result.entity.data)  // Also works
+     *
      * @example
      * // Metadata-only filtering (no vector search)
      * const activeUsers = await brainy.find({
@@ -996,11 +1079,7 @@ export class Brainy {
                 for (const id of pageIds) {
                     const entity = await this.get(id);
                     if (entity) {
-                        results.push({
-                            id,
-                            score: 1.0, // All metadata-filtered results equally relevant
-                            entity
-                        });
+                        results.push(this.createResult(id, 1.0, entity));
                     }
                 }
                 return results;
@@ -1016,11 +1095,7 @@ export class Brainy {
                     const noun = storageResults.items[i];
                     if (noun) {
                         const entity = await this.convertNounToEntity(noun);
-                        results.push({
-                            id: noun.id,
-                            score: 1.0, // All results equally relevant for empty query
-                            entity
-                        });
+                        results.push(this.createResult(noun.id, 1.0, entity));
                     }
                 }
                 return results;
@@ -1114,11 +1189,7 @@ export class Brainy {
                     for (const id of pageIds) {
                         const entity = await this.get(id);
                         if (entity) {
-                            results.push({
-                                id,
-                                score: 1.0, // All metadata matches are equally relevant
-                                entity: entity
-                            });
+                            results.push(this.createResult(id, 1.0, entity));
                         }
                     }
                     // Early return for metadata-only queries with pagination applied
@@ -1151,7 +1222,15 @@ export class Brainy {
      * Find similar entities using vector similarity
      *
      * @param params - Parameters specifying the target for similarity search
-     * @returns Promise that resolves to array of similar entities with similarity scores
+     * @param params.to - Entity ID, Entity object, or Vector to find similar to (required)
+     * @param params.limit - Maximum results (default: 10)
+     * @param params.threshold - Minimum similarity (0-1)
+     * @param params.type - Filter by NounType(s)
+     * @param params.where - Metadata filters
+     * @returns Promise that resolves to array of Result objects with similarity scores (same structure as find())
+     *
+     * **Returns (v4.3.0):**
+     * Same Result structure as find() with flattened fields for convenient access
      *
      * @example
      * // Find entities similar to a specific entity by ID
@@ -1160,9 +1239,12 @@ export class Brainy {
      *   limit: 10
      * })
      *
-     * // Process similarity results
+     * // NEW in v4.3.0: Access flattened fields
      * for (const result of similarDocs) {
-     *   console.log(`Similar entity: ${result.entity.data} (similarity: ${result.score})`)
+     *   console.log(`Similarity: ${result.score}`)
+     *   console.log(`Type: ${result.type}`)              // Flattened!
+     *   console.log(`Metadata:`, result.metadata)        // Flattened!
+     *   console.log(`Confidence: ${result.confidence ?? 'N/A'}`)  // Flattened!
      * }
      *
      * @example
@@ -1688,6 +1770,32 @@ export class Brainy {
     }
     /**
      * Virtual File System API - Knowledge Operating System
+     *
+     * Returns a cached VFS instance. You must call vfs.init() before use:
+     *
+     * @example After import
+     * ```typescript
+     * await brain.import('./data.xlsx', { vfsPath: '/imports/data' })
+     *
+     * const vfs = brain.vfs()
+     * await vfs.init()  // Required! (safe to call multiple times)
+     * const files = await vfs.readdir('/imports/data')
+     * ```
+     *
+     * @example Direct VFS usage
+     * ```typescript
+     * const vfs = brain.vfs()
+     * await vfs.init()  // Always required before first use
+     * await vfs.writeFile('/docs/readme.md', 'Hello World')
+     * const content = await vfs.readFile('/docs/readme.md')
+     * ```
+     *
+     * **Note:** brain.import() automatically initializes the VFS, so after
+     * an import you can call vfs.init() again (it's idempotent) and immediately
+     * query the imported files.
+     *
+     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs()
+     * return the same instance. This ensures import and user code share state.
      */
     vfs() {
         if (!this._vfs) {
@@ -2187,7 +2295,7 @@ export class Brainy {
             const entity = await this.get(id);
             if (entity) {
                 const score = Math.max(0, Math.min(1, 1 / (1 + distance)));
-                results.push({ id, score, entity });
+                results.push(this.createResult(id, score, entity));
             }
         }
         return results;
@@ -2211,7 +2319,7 @@ export class Brainy {
             if (score >= (params.near.threshold || 0.7)) {
                 const entity = await this.get(id);
                 if (entity) {
-                    results.push({ id, score, entity });
+                    results.push(this.createResult(id, score, entity));
                 }
             }
         }
@@ -2244,11 +2352,7 @@ export class Brainy {
         for (const id of connectedIds) {
             const entity = await this.get(id);
             if (entity) {
-                results.push({
-                    id,
-                    score: 1.0,
-                    entity
-                });
+                results.push(this.createResult(id, 1.0, entity));
             }
         }
         return results;

package/dist/importers/SmartExcelImporter.d.ts

@@ -129,6 +129,24 @@ export declare class SmartExcelImporter {
      * Map type string to NounType
      */
     private mapTypeString;
+    /**
+     * Infer entity type from Excel sheet name
+     *
+     * Uses common naming patterns to suggest appropriate entity types:
+     * - "Characters", "People", "Humans" → Person
+     * - "Places", "Locations" → Location
+     * - "Terms", "Concepts", "Glossary" → Concept
+     * - etc.
+     *
+     * @param sheetName - Excel sheet name
+     * @returns Inferred NounType or null if no match
+     *
+     * @example
+     * inferTypeFromSheetName("Characters") // → NounType.Person
+     * inferTypeFromSheetName("Places") // → NounType.Location
+     * inferTypeFromSheetName("Animals") // → null (no semantic hint)
+     */
+    private inferTypeFromSheetName;
     /**
      * Infer relationship type from context using SmartRelationshipExtractor
      */

package/dist/importers/SmartExcelImporter.js

@@ -107,10 +107,16 @@ export class SmartExcelImporter {
                         ? this.brain.extractConcepts(definition, { limit: 10 }).catch(() => [])
                         : Promise.resolve([])
                 ]);
-                // Determine main entity type
+                // Determine main entity type with priority order:
+                // 1. Explicit "Type" column (highest priority - user specified)
+                // 2. Sheet name inference (NEW - semantic hint from Excel structure)
+                // 3. AI extraction from related entities
+                // 4. Default to Thing (fallback)
+                const sheetTypeHint = this.inferTypeFromSheetName(row._sheet || '');
                 const mainEntityType = type ?
                     this.mapTypeString(type) :
-                    (relatedEntities.length > 0 ? relatedEntities[0].type : NounType.Thing);
+                    sheetTypeHint ||
+                        (relatedEntities.length > 0 ? relatedEntities[0].type : NounType.Thing);
                 // Generate entity ID
                 const entityId = this.generateEntityId(term);
                 // Create main entity
@@ -297,6 +303,58 @@ export class SmartExcelImporter {
         };
         return mapping[normalized] || NounType.Thing;
     }
+    /**
+     * Infer entity type from Excel sheet name
+     *
+     * Uses common naming patterns to suggest appropriate entity types:
+     * - "Characters", "People", "Humans" → Person
+     * - "Places", "Locations" → Location
+     * - "Terms", "Concepts", "Glossary" → Concept
+     * - etc.
+     *
+     * @param sheetName - Excel sheet name
+     * @returns Inferred NounType or null if no match
+     *
+     * @example
+     * inferTypeFromSheetName("Characters") // → NounType.Person
+     * inferTypeFromSheetName("Places") // → NounType.Location
+     * inferTypeFromSheetName("Animals") // → null (no semantic hint)
+     */
+    inferTypeFromSheetName(sheetName) {
+        if (!sheetName)
+            return null;
+        const normalized = sheetName.toLowerCase();
+        // Person types: characters, people, humans, individuals
+        if (normalized.match(/character|people|person|human|individual|npc|cast/)) {
+            return NounType.Person;
+        }
+        // Location types: places, locations, areas, regions
+        if (normalized.match(/place|location|area|region|zone|geography|map|world/)) {
+            return NounType.Location;
+        }
+        // Concept types: terms, concepts, ideas, glossary
+        if (normalized.match(/term|concept|idea|definition|glossary|vocabulary|lexicon/)) {
+            return NounType.Concept;
+        }
+        // Organization types: groups, factions, companies
+        if (normalized.match(/organization|company|group|faction|tribe|guild|clan|corp/)) {
+            return NounType.Organization;
+        }
+        // Event types: events, occurrences, happenings
+        if (normalized.match(/event|occurrence|happening|battle|encounter|scene/)) {
+            return NounType.Event;
+        }
+        // Product types: items, equipment, gear
+        if (normalized.match(/item|product|equipment|gear|weapon|armor|artifact|treasure/)) {
+            return NounType.Product;
+        }
+        // Project types: quests, missions, campaigns
+        if (normalized.match(/project|quest|mission|campaign|task/)) {
+            return NounType.Project;
+        }
+        // No semantic match found - return null to continue to next type determination method
+        return null;
+    }
     /**
      * Infer relationship type from context using SmartRelationshipExtractor
      */

package/dist/importers/VFSStructureGenerator.d.ts

@@ -53,6 +53,9 @@ export declare class VFSStructureGenerator {
     constructor(brain: Brainy);
     /**
      * Initialize the generator
+     *
+     * CRITICAL: Gets brain's VFS instance and initializes it if needed.
+     * This ensures that after import, brain.vfs() returns an initialized instance.
      */
     init(): Promise<void>;
     /**

package/dist/importers/VFSStructureGenerator.js

@@ -8,7 +8,6 @@
  *
  * NO MOCKS - Production-ready implementation
  */
-import { VirtualFileSystem } from '../vfs/VirtualFileSystem.js';
 import { NounType } from '../types/graphTypes.js';
 /**
  * VFSStructureGenerator - Organizes imported data into VFS
@@ -16,19 +15,28 @@ import { NounType } from '../types/graphTypes.js';
 export class VFSStructureGenerator {
     constructor(brain) {
         this.brain = brain;
-        this.vfs = new VirtualFileSystem(brain);
+        // CRITICAL FIX: Use brain.vfs() instead of creating separate instance
+        // This ensures VFSStructureGenerator and user code share the same VFS instance
+        // Before: Created separate instance that wasn't accessible to users
+        // After: Uses brain's cached instance, making VFS queryable after import
     }
     /**
      * Initialize the generator
+     *
+     * CRITICAL: Gets brain's VFS instance and initializes it if needed.
+     * This ensures that after import, brain.vfs() returns an initialized instance.
      */
     async init() {
-        // Always ensure VFS is initialized
+        // Get brain's cached VFS instance (creates if doesn't exist)
+        this.vfs = this.brain.vfs();
+        // Initialize if not already initialized
+        // VFS.init() is idempotent (safe to call multiple times)
         try {
-            // Check if VFS is initialized by trying to access root
+            // Check if already initialized
             await this.vfs.stat('/');
         }
         catch (error) {
-            // VFS not initialized, initialize it
+            // Not initialized, initialize now
             await this.vfs.init();
         }
     }

package/dist/types/brainy.types.d.ts

@@ -18,6 +18,8 @@ export interface Entity<T = any> {
     createdAt: number;
     updatedAt?: number;
     createdBy?: string;
+    confidence?: number;
+    weight?: number;
 }
 /**
  * Relation representation (replaces GraphVerb)
@@ -50,10 +52,18 @@ export interface RelationEvidence {
 }
 /**
  * Search result with similarity score
+ *
+ * Flattens commonly-used entity fields to top level for convenience,
+ * while preserving full entity in 'entity' field for backward compatibility.
  */
 export interface Result<T = any> {
     id: string;
     score: number;
+    type?: NounType;
+    metadata?: T;
+    data?: any;
+    confidence?: number;
+    weight?: number;
     entity: Entity<T>;
     explanation?: ScoreExplanation;
 }
@@ -77,6 +87,8 @@ export interface AddParams<T = any> {
     id?: string;
     vector?: Vector;
     service?: string;
+    confidence?: number;
+    weight?: number;
 }
 /**
  * Parameters for updating entities
@@ -88,6 +100,8 @@ export interface UpdateParams<T = any> {
     metadata?: Partial<T>;
     merge?: boolean;
     vector?: Vector;
+    confidence?: number;
+    weight?: number;
 }
 /**
  * Parameters for creating relationships

package/dist/vfs/VirtualFileSystem.js

@@ -812,11 +812,17 @@ export class VirtualFileSystem {
     // ============= Helper Methods =============
     async ensureInitialized() {
         if (!this.initialized) {
-            throw new Error('VFS not initialized. You must call await vfs.init() after getting the VFS instance.\n' +
-                'Example:\n' +
-                '  const vfs = brain.vfs()  // Note: vfs() is a method, not a property\n' +
-                '  await vfs.init()         // This creates the root directory\n' +
-                'See docs: https://github.com/Brainy-Technologies/brainy/blob/main/docs/vfs/QUICK_START.md');
+            throw new VFSError(VFSErrorCode.EINVAL, 'VFS not initialized. Call await vfs.init() before using VFS operations.\n\n' +
+                '✅ After brain.import():\n' +
+                '  await brain.import(file, { vfsPath: "/imports/data" })\n' +
+                '  const vfs = brain.vfs()\n' +
+                '  await vfs.init()  // ← Required! Safe to call multiple times\n' +
+                '  const files = await vfs.readdir("/imports/data")\n\n' +
+                '✅ Direct VFS usage:\n' +
+                '  const vfs = brain.vfs()\n' +
+                '  await vfs.init()  // ← Always required before first use\n' +
+                '  await vfs.writeFile("/docs/readme.md", "Hello")\n\n' +
+                '📖 Docs: https://github.com/soulcraftlabs/brainy/blob/main/docs/vfs/QUICK_START.md', '<unknown>', 'VFS');
         }
     }
     async ensureDirectory(path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.2.4",
+  "version": "4.3.1",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",