feat(vfs): fix VFS visibility by removing broken filtering

- Remove includeVFS parameter and broken isVFS filtering logic
- Add excludeVFS parameter for optional VFS entity filtering
- VFS entities now part of knowledge graph by default
- Enable O(1) graph adjacency optimizations for VFS operations
- Update all VFS projections and PathResolver
- Add comprehensive VFS visibility documentation

This fixes the bug where VFS operations returned empty results due to
operator object mismatch in storage adapters. VFS relationships now use
proper graph traversal without metadata filtering.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/vfs/PathResolver.ts

@@ -195,12 +195,11 @@ export class PathResolver {
       // Still need to verify it exists
     }
 
-    // Use proper graph traversal to find children
-    // Get all relationships where parentId contains other entities
+    // v4.7.0: Use proper graph traversal to find children
+    // VFS relationships are now part of the knowledge graph
     const relations = await this.brain.getRelations({
       from: parentId,
-      type: VerbType.Contains,
-      includeVFS: true  // v4.5.1: Required to see VFS relationships
+      type: VerbType.Contains
     })
 
     // Find the child with matching name
@@ -225,11 +224,11 @@ export class PathResolver {
    * Uses proper graph relationships to traverse the tree
    */
   async getChildren(dirId: string): Promise<VFSEntity[]> {
-    // Production-ready: Use graph relationships (VFS creates these in mkdir/writeFile)
+    // v4.7.0: Use O(1) graph relationships (VFS creates these in mkdir/writeFile)
+    // VFS relationships are now part of the knowledge graph (no special filtering needed)
     const relations = await this.brain.getRelations({
       from: dirId,
-      type: VerbType.Contains,
-      includeVFS: true  // v4.5.1: Required to see VFS relationships
+      type: VerbType.Contains
     })
 
     const validChildren: VFSEntity[]= []

src/vfs/VirtualFileSystem.ts

@@ -167,8 +167,7 @@ export class VirtualFileSystem implements IVirtualFileSystem {
         path: '/',           // ✅ Correct field name
         vfsType: 'directory' // ✅ Correct field name
       },
-      limit: 10,
-      includeVFS: true  // v4.4.0: CRITICAL - Must find VFS root entity!
+      limit: 10
     })
 
     if (existing.length > 0) {
@@ -961,9 +960,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
       limit: options?.limit || 10,
       offset: options?.offset,
       explain: options?.explain,
-      includeVFS: true,  // v4.4.0: VFS search must include VFS entities!
       where: {
-        vfsType: 'file'  // v4.4.0: Only search VFS files, not knowledge documents
+        vfsType: 'file'  // v4.7.0: Search VFS files
       }
     }
 
@@ -1012,9 +1010,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
       limit: options?.limit || 10,
       threshold: options?.threshold || 0.7,
       type: [NounType.File, NounType.Document, NounType.Media],
-      includeVFS: true,  // v4.4.0: VFS similarity search must include VFS entities!
       where: {
-        vfsType: 'file'  // v4.4.0: Only find similar VFS files, not knowledge documents
+        vfsType: 'file'  // v4.7.0: Find similar VFS files
       }
     })
 
@@ -2341,8 +2338,7 @@ export class VirtualFileSystem implements IVirtualFileSystem {
         ...query.where,
         vfsType: 'entity'
       },
-      limit: query.limit || 100,
-      includeVFS: true  // v4.4.0: VFS entity search must include VFS entities!
+      limit: query.limit || 100
     }
 
     if (query.type) {

src/vfs/semantic/projections/AuthorProjection.ts

@@ -31,8 +31,7 @@ export class AuthorProjection extends BaseProjectionStrategy {
         vfsType: 'file',
         owner: authorName
       },
-      limit: 1000,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit: 1000
     }
 
     // Filter by filename if subpath specified
@@ -53,14 +52,13 @@ export class AuthorProjection extends BaseProjectionStrategy {
    * Resolve author to entity IDs using REAL Brainy.find()
    */
   async resolve(brain: Brainy, vfs: VirtualFileSystem, authorName: string): Promise<string[]> {
-    // Use REAL Brainy metadata filtering
+    // v4.7.0: VFS entities are part of the knowledge graph
     const results = await brain.find({
       where: {
         vfsType: 'file',
         owner: authorName
       },
-      limit: 1000,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit: 1000
     })
 
     return this.extractIds(results)
@@ -75,10 +73,9 @@ export class AuthorProjection extends BaseProjectionStrategy {
     const results = await brain.find({
       where: {
         vfsType: 'file',
-        owner: { $exists: true }
+        owner: { exists: true }
       },
-      limit,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit
     })
 
     return results.map(r => r.entity as VFSEntity)

src/vfs/semantic/projections/TagProjection.ts

@@ -29,10 +29,9 @@ export class TagProjection extends BaseProjectionStrategy {
     const query: FindParams = {
       where: {
         vfsType: 'file',
-        tags: { contains: tagName }  // BFO operator for array contains
+        tags: { contains: tagName }  // contains operator for array search
       },
-      limit: 1000,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit: 1000
     }
 
     // Filter by filename if subpath specified
@@ -53,14 +52,13 @@ export class TagProjection extends BaseProjectionStrategy {
    * Resolve tag to entity IDs using REAL Brainy.find()
    */
   async resolve(brain: Brainy, vfs: VirtualFileSystem, tagName: string): Promise<string[]> {
-    // Use REAL Brainy metadata filtering
+    // v4.7.0: VFS entities are part of the knowledge graph
     const results = await brain.find({
       where: {
         vfsType: 'file',
-        tags: { contains: tagName }  // BFO operator
+        tags: { contains: tagName }
       },
-      limit: 1000,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit: 1000
     })
 
     return this.extractIds(results)
@@ -74,10 +72,9 @@ export class TagProjection extends BaseProjectionStrategy {
     const results = await brain.find({
       where: {
         vfsType: 'file',
-        tags: { exists: true }  // BFO operator
+        tags: { exists: true }  // exists operator
       },
-      limit,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit
     })
 
     return results.map(r => r.entity as VFSEntity)

src/vfs/semantic/projections/TemporalProjection.ts

@@ -69,17 +69,16 @@ export class TemporalProjection extends BaseProjectionStrategy {
     const endOfDay = new Date(date)
     endOfDay.setHours(23, 59, 59, 999)
 
-    // Use REAL Brainy metadata filtering with range operators
+    // v4.7.0: VFS entities are part of the knowledge graph
     const results = await brain.find({
       where: {
         vfsType: 'file',
         modified: {
-          greaterEqual: startOfDay.getTime(),  // BFO operator
-          lessEqual: endOfDay.getTime()        // BFO operator
+          greaterEqual: startOfDay.getTime(),
+          lessEqual: endOfDay.getTime()
         }
       },
-      limit: 1000,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit: 1000
     })
 
     return this.extractIds(results)
@@ -94,10 +93,9 @@ export class TemporalProjection extends BaseProjectionStrategy {
     const results = await brain.find({
       where: {
         vfsType: 'file',
-        modified: { greaterEqual: oneDayAgo }  // BFO operator
+        modified: { greaterEqual: oneDayAgo }
       },
-      limit,
-      includeVFS: true  // v4.4.0: Must include VFS entities!
+      limit
     })
 
     return results.map(r => r.entity as VFSEntity)