docs: add file watching API documentation

Add comprehensive documentation for the new file watching feature:
- New file-watching.mdx API reference page covering watch() method
- Event types, filtering, cancellation, and use cases
- Cross-links from files.mdx to file watching
- Updated API index with file watching card

Synced from cloudflare/sandbox-sdk PR #324

Author: github-actions[bot]

src/content/docs/sandbox/api/file-watching.mdx

@@ -0,0 +1,285 @@
+---
+title: File watching
+pcx_content_type: concept
+sidebar:
+  order: 4
+---
+
+import { TypeScriptExample } from "~/components";
+
+Monitor filesystem changes in real-time using native Linux inotify. Watch directories for file creation, modification, deletion, and moves.
+
+## watch()
+
+Start watching a directory for filesystem changes. Returns a `FileWatch` instance that emits events for file changes.
+
+```ts
+const watcher = await sandbox.watch(path: string, options?: WatchOptions): Promise<WatchHandle>
+```
+
+**Parameters**:
+- `path` - Absolute path to watch (for example, `/workspace/src`)
+- `options` (optional):
+  - `recursive` - Watch subdirectories recursively (default: `true`)
+  - `exclude` - Patterns to exclude (default: `['.git', 'node_modules', '.DS_Store']`)
+  - `include` - Only emit events for files matching these patterns
+  - `onEvent` - Callback for file change events
+  - `onError` - Callback for watch errors
+  - `signal` - AbortSignal for cancellation
+
+**Returns**: `Promise<WatchHandle>` with:
+- `id` - Unique watch identifier
+- `path` - Watched path
+- `stop()` - Stop watching
+
+<TypeScriptExample>
+```
+// Watch for all changes in src directory
+const watcher = await sandbox.watch('/workspace/src', {
+  recursive: true,
+  onEvent: (event) => {
+    console.log(`${event.type}: ${event.path}`);
+  },
+  onError: (error) => {
+    console.error('Watch error:', error);
+  }
+});
+
+// Stop watching when done
+await watcher.stop();
+```
+</TypeScriptExample>
+
+## Event types
+
+File change events contain:
+
+```ts
+interface WatchEvent {
+  type: 'create' | 'modify' | 'delete' | 'rename';
+  path: string;
+  isDirectory: boolean;
+  timestamp: string;
+}
+```
+
+Event types:
+- `create` - File or directory created
+- `modify` - File content changed
+- `delete` - File or directory deleted
+- `rename` - File or directory moved (generates two events: delete at old path, create at new path)
+
+<TypeScriptExample>
+```
+const watcher = await sandbox.watch('/workspace', {
+  onEvent: (event) => {
+    if (event.type === 'create' && !event.isDirectory) {
+      console.log(`New file: ${event.path}`);
+    } else if (event.type === 'modify') {
+      console.log(`File modified: ${event.path} at ${event.timestamp}`);
+    } else if (event.type === 'delete') {
+      console.log(`${event.isDirectory ? 'Directory' : 'File'} deleted: ${event.path}`);
+    }
+  }
+});
+```
+</TypeScriptExample>
+
+## Filtering events
+
+### Include patterns
+
+Use glob-style patterns to filter which files trigger events:
+
+<TypeScriptExample>
+```
+// Only watch TypeScript files
+const watcher = await sandbox.watch('/workspace/src', {
+  include: ['*.ts', '*.tsx']
+});
+
+// Watch specific file types
+const watcher = await sandbox.watch('/workspace', {
+  include: ['*.json', '*.yaml', '*.yml']
+});
+```
+</TypeScriptExample>
+
+:::note[Pattern matching]
+Include patterns match against the filename only (not the full path). Use `*.ts` to match all TypeScript files recursively.
+:::
+
+### Exclude patterns
+
+Exclude patterns prevent events for matching paths. Default excludes are `.git`, `node_modules`, and `.DS_Store`.
+
+<TypeScriptExample>
+```
+// Custom exclusions (replaces defaults)
+const watcher = await sandbox.watch('/workspace', {
+  exclude: ['.git', 'node_modules', 'dist', '.cache']
+});
+
+// Watch everything except hidden files
+const watcher = await sandbox.watch('/workspace', {
+  exclude: ['.*']
+});
+```
+</TypeScriptExample>
+
+:::caution[Exclude replaces defaults]
+When you provide `exclude` patterns, they replace the default exclusions. If you want to keep the defaults, include them explicitly: `exclude: ['.git', 'node_modules', '.DS_Store', 'your-pattern']`
+:::
+
+## Cancellation
+
+Stop watching using the `stop()` method or an AbortSignal:
+
+<TypeScriptExample>
+```
+// Stop explicitly
+const watcher = await sandbox.watch('/workspace/src');
+await watcher.stop();
+
+// Use AbortController for cancellation
+const controller = new AbortController();
+const watcher = await sandbox.watch('/workspace/src', {
+  signal: controller.signal,
+  onEvent: (event) => console.log(event)
+});
+
+// Later: cancel the watch
+controller.abort();
+```
+</TypeScriptExample>
+
+## Watch scope
+
+### Recursive watching
+
+By default, watches are recursive and monitor all subdirectories:
+
+<TypeScriptExample>
+```
+// Watch entire project (recursive by default)
+const watcher = await sandbox.watch('/workspace/myproject');
+
+// Non-recursive: only watch the specified directory
+const watcher = await sandbox.watch('/workspace/logs', {
+  recursive: false
+});
+```
+</TypeScriptExample>
+
+### Multiple watches
+
+You can create multiple watches simultaneously:
+
+<TypeScriptExample>
+```
+// Watch different directories with different handlers
+const srcWatcher = await sandbox.watch('/workspace/src', {
+  include: ['*.ts', '*.tsx'],
+  onEvent: (e) => console.log('Source change:', e.path)
+});
+
+const configWatcher = await sandbox.watch('/workspace', {
+  include: ['*.json', '*.yaml'],
+  recursive: false,
+  onEvent: (e) => console.log('Config change:', e.path)
+});
+
+// Clean up both
+await Promise.all([srcWatcher.stop(), configWatcher.stop()]);
+```
+</TypeScriptExample>
+
+## Use cases
+
+### Hot reload
+
+Restart services when code changes:
+
+<TypeScriptExample>
+```
+let serverProcess = null;
+
+const watcher = await sandbox.watch('/workspace/src', {
+  include: ['*.js', '*.ts'],
+  onEvent: async (event) => {
+    if (event.type === 'modify' || event.type === 'create') {
+      console.log('Code changed, restarting server...');
+
+      if (serverProcess) {
+        await serverProcess.kill();
+      }
+
+      serverProcess = await sandbox.execBackground('npm start');
+    }
+  }
+});
+```
+</TypeScriptExample>
+
+### Build automation
+
+Trigger builds on file changes:
+
+<TypeScriptExample>
+```
+const watcher = await sandbox.watch('/workspace/src', {
+  onEvent: async (event) => {
+    if (event.type === 'modify') {
+      console.log('Building...');
+      const result = await sandbox.exec('npm run build');
+
+      if (result.exitCode === 0) {
+        console.log('Build complete');
+      } else {
+        console.error('Build failed:', result.stderr);
+      }
+    }
+  }
+});
+```
+</TypeScriptExample>
+
+### File sync monitoring
+
+Track when files are written to a directory:
+
+<TypeScriptExample>
+```
+const files = new Set();
+
+const watcher = await sandbox.watch('/workspace/uploads', {
+  onEvent: (event) => {
+    if (event.type === 'create' && !event.isDirectory) {
+      files.add(event.path);
+      console.log(`New file uploaded: ${event.path}`);
+      console.log(`Total files: ${files.size}`);
+    }
+  }
+});
+```
+</TypeScriptExample>
+
+## Implementation details
+
+File watching uses Linux inotify under the hood:
+- Native filesystem event notifications (not polling)
+- Low overhead for monitoring large directory trees
+- Events delivered in real-time via Server-Sent Events (SSE)
+- Automatic cleanup when the watch is stopped or the sandbox sleeps
+
+## Limitations
+
+- **Linux only**: File watching requires Linux inotify (available in all sandbox containers)
+- **Path must exist**: The watched path must exist before calling `watch()`
+- **No cross-mount watching**: Cannot watch paths that span different filesystem mounts
+- **Event coalescing**: Rapid changes to the same file may be coalesced into fewer events
+
+## Related resources
+
+- [Files API](/sandbox/api/files/) - File operations reference
+- [Commands API](/sandbox/api/commands/) - Execute commands including background processes

src/content/docs/sandbox/api/files.mdx

@@ -208,4 +208,5 @@ await sandbox.gitCheckout('https://github.com/user/repo', {
 ## Related resources
 
 - [Manage files guide](/sandbox/guides/manage-files/) - Detailed guide with best practices
+- [File watching API](/sandbox/api/file-watching/) - Monitor filesystem changes in real-time
 - [Commands API](/sandbox/api/commands/) - Execute commands

src/content/docs/sandbox/api/index.mdx

@@ -35,6 +35,14 @@ The Sandbox SDK provides a comprehensive API for executing code, managing files,
 	Read, write, and manage files in the sandbox filesystem. Includes directory operations and file metadata.
 </LinkTitleCard>
 
+<LinkTitleCard
+	title="File watching"
+	href="/sandbox/api/file-watching/"
+	icon="eye-on"
+>
+	Monitor filesystem changes in real-time. Watch directories for file creation, modification, deletion, and moves.
+</LinkTitleCard>
+
 <LinkTitleCard
 	title="Code Interpreter"
 	href="/sandbox/api/interpreter/"