doc: add VFS limitations and cross-references

- Add "Limitations" section to vfs.md documenting unsupported features:
  native addons, child processes, worker threads, fs.watch polling,
  and SEA code caching
- Add code caching limitations section to SEA VFS documentation
- Add VFS support section to fs.md with example and link to vfs.md

Author: mcollina

doc/api/fs.md

@@ -121,6 +121,36 @@ try {
 }
 ```
 
+## Virtual File System (VFS) support
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+The `fs` module can operate on virtual files when the [`node:vfs`][] module is
+used. When a virtual file system is mounted, `fs` operations on paths under
+the mount point are automatically routed to the VFS instead of the real file
+system.
+
+```cjs
+const vfs = require('node:vfs');
+const fs = require('node:fs');
+
+const myVfs = vfs.create();
+myVfs.writeFileSync('/data.txt', 'Hello from VFS');
+myVfs.mount('/virtual');
+
+// This reads from the virtual file system
+fs.readFileSync('/virtual/data.txt', 'utf8'); // 'Hello from VFS'
+
+myVfs.unmount();
+```
+
+Not all `fs` operations are supported with VFS. See the [`node:vfs`][]
+documentation for the complete list of supported operations and limitations.
+
 ## Promises API
 
 <!-- YAML
@@ -8773,6 +8803,7 @@ the file contents.
 [`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html
 [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 [`minimatch`]: https://github.com/isaacs/minimatch
+[`node:vfs`]: vfs.md
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [bigints]: https://tc39.github.io/proposal-bigint
 [caveats]: #caveats

doc/api/single-executable-applications.md

@@ -227,6 +227,14 @@ const utils = require('/sea/utils/helpers.js');
 The SEA's `require()` function automatically detects VFS paths (paths starting
 with `/sea/`) and loads modules from the virtual file system.
 
+#### Code caching limitations
+
+The `useCodeCache` option in the SEA configuration does not apply to modules
+loaded from the VFS. Code caching requires executing modules during the SEA
+build process to generate cached code, but VFS modules are only available at
+runtime after the SEA is built. If performance is critical, consider using
+`useCodeCache` for your main entry point and `useSnapshot` for initialization.
+
 ### Startup snapshot support
 
 The `useSnapshot` field can be used to enable startup snapshot support. In this

doc/api/vfs.md

@@ -131,6 +131,43 @@ console.log(greet('World')); // Hello, World!
 myVfs.unmount();
 ```
 
+## Limitations
+
+The VFS has the following limitations:
+
+### Native addons
+
+Native addons (`.node` files) cannot be loaded from the VFS. Native addons
+must exist on the real file system because they are loaded by the operating
+system's dynamic linker, which cannot access virtual files.
+
+### Child processes
+
+Child processes spawned via `child_process.spawn()`, `child_process.exec()`,
+or similar methods cannot directly access VFS files. The child process runs
+in a separate address space and does not inherit the parent's VFS mounts.
+To share data with child processes, write files to the real file system or
+use inter-process communication.
+
+### Worker threads
+
+Each worker thread has its own independent VFS state. A VFS mounted in the
+main thread is not automatically available in worker threads. To use VFS in
+workers, create and mount a new VFS instance within each worker.
+
+### fs.watch limitations
+
+The `fs.watch()` and `fs.watchFile()` functions work with VFS files but use
+polling internally rather than native file system notifications, since VFS
+files exist only in memory.
+
+### Code caching in SEA
+
+When using VFS with Single Executable Applications, the `useCodeCache` option
+in the SEA configuration does not apply to modules loaded from the VFS. Code
+caching requires executing modules during the SEA build process, but VFS
+modules are only available at runtime.
+
 ## `vfs.create([provider][, options])`
 
 <!-- YAML