feat: add tree-aware VFS methods to prevent recursion in file explorers

Add safe tree operations that guarantee no directory appears as its own child:
- getDirectChildren() returns only immediate children
- getTreeStructure() builds safe tree with recursion protection
- getDescendants() gets all descendants efficiently
- inspect() provides comprehensive path information

Also includes VFSTreeUtils for building and validating tree structures.

This resolves the common infinite recursion issue when building file
explorers, as discovered by the Soulcraft Studio team.

Co-Authored-By: User <noreply@user.local>

docs/vfs/README.md

@@ -49,6 +49,18 @@ await vfs.addRelationship('/docs/spec.md', '/projects/my-app/', 'implements')
 
 ## Core Features
 
+### 🆕 Tree Operations (Prevents Recursion Issues)
+
+**NEW: Safe tree operations for building file explorers:**
+- **`getDirectChildren(path)`** - Returns only immediate children, never the parent
+- **`getTreeStructure(path, options)`** - Builds complete tree with recursion protection
+- **`getDescendants(path, options)`** - Gets all descendants efficiently
+- **`inspect(path)`** - Comprehensive info with parent, children, and stats
+
+See [Building File Explorers Guide](building-file-explorers.md) for complete documentation on avoiding common recursion pitfalls.
+
+## Core Features
+
 ### 📁 Full Filesystem API
 
 All the operations you expect from a filesystem: