docs(platform): clarify FileSystem.watch recursive option behavior (#5792)

Author: Hoishin

packages/platform-node/CHANGELOG.md

@@ -515,7 +515,7 @@
 
   Added a `recursive` option to `FileSystem.watch` that allows watching for changes in subdirectories. When set to `true`, the watcher will monitor changes in all nested directories.
 
-  Note: The recursive option is only supported on macOS and Windows. On other platforms, it will be ignored.
+  Note: The `recursive` option behavior depends on the backend implementation. When using the default Node.js `fs.watch()` backend, the `recursive` option is supported on all platforms (Node.js v20+). When using `@parcel/watcher` (via `NodeFileSystem/ParcelWatcher` layer), watching is always recursive on all platforms and this option is ignored.
 
   Example:
 

packages/platform/src/FileSystem.ts

@@ -235,8 +235,11 @@ export interface FileSystem {
    * By default, only changes to the direct children of the directory are reported.
    * Set the `recursive` option to `true` to watch for changes in subdirectories as well.
    *
-   * Note: The `recursive` option is only supported on macOS and Windows.
-   * On other platforms, it will be ignored.
+   * Note: The `recursive` option behavior depends on the backend implementation:
+   * - When using the default Node.js `fs.watch()` backend: The `recursive`
+   *   option is supported on all platforms (Node.js v20+).
+   * - When using `@parcel/watcher` (via `NodeFileSystem/ParcelWatcher` layer):
+   *   Watching is always recursive on all platforms. This option is ignored.
    */
   readonly watch: (path: string, options?: WatchOptions) => Stream<WatchEvent, PlatformError>
   /**