From d4355932d97fe177f26cbe7b035f1edbfe53ca8e Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Fri, 24 Oct 2025 13:05:17 -0700
Subject: [PATCH] docs: add VFS filtering examples to brain.find() JSDoc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added 3 comprehensive examples showing:
- Default VFS exclusion for clean knowledge queries
- Opt-in includeVFS for mixed searches
- VFS-only queries with includeVFS + where filters

All inline code comments verified in place:
✅ VFS filtering logic documented (3 query paths)
✅ Critical bug fixes explained inline
✅ includeVFS behavior clear at all usage sites
---
 src/brainy.ts | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/brainy.ts b/src/brainy.ts
index c43cfcce..aa101335 100644
--- a/src/brainy.ts
+++ b/src/brainy.ts
@@ -1185,6 +1185,27 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    *   console.error('Search failed:', error)
    *   return []
    * }
+   *
+   * @example
+   * // VFS Filtering (v4.4.0): Exclude VFS entities by default
+   * // Knowledge graph queries stay clean - no VFS files in results
+   * const knowledge = await brainy.find({ query: 'AI concepts' })
+   * // Returns only knowledge entities, VFS files excluded
+   *
+   * @example
+   * // Include VFS entities when needed
+   * const everything = await brainy.find({
+   *   query: 'documentation',
+   *   includeVFS: true  // Opt-in to include VFS files
+   * })
+   * // Returns both knowledge entities AND VFS files
+   *
+   * @example
+   * // Search only VFS files
+   * const files = await brainy.find({
+   *   where: { vfsType: 'file', extension: '.md' },
+   *   includeVFS: true  // Required to find VFS entities
+   * })
    */
   async find(query: string | FindParams<T>): Promise<Result<T>[]> {
     await this.ensureInitialized()