Add open source documentation files

Sources/Inotify/Inotify.docc/Inotify.md

@@ -0,0 +1,40 @@
+# ``Inotify``
+
+Monitor filesystem events on Linux using modern Swift concurrency.
+
+## Overview
+
+The Inotify library wraps the Linux [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) API in a Swift-native interface built around actors and async sequences. You create an ``Inotify/Inotify`` actor, add watches for the paths you care about, and iterate over the ``Inotify/Inotify/events`` property to receive ``InotifyEvent`` values as they occur.
+
+```swift
+let inotify = try Inotify()
+try inotify.addWatch(path: "/tmp/inbox", mask: [.create, .modify])
+
+for await event in await inotify.events {
+    print("\(event.mask) at \(event.path)")
+}
+```
+
+Beyond single-directory watches, the library provides two higher-level methods for monitoring entire directory trees:
+
+- ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` installs watches on every existing subdirectory at setup time.
+- ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` does the same **and** automatically watches subdirectories that are created after setup.
+
+All public types conform to `Sendable`, so they can be safely passed across concurrency boundaries.
+
+## Topics
+
+### Essentials
+
+- ``Inotify/Inotify``
+- ``InotifyEvent``
+- ``InotifyEventMask``
+
+### Errors
+
+- ``InotifyError``
+- ``DirectoryResolverError``
+
+### Low-Level Types
+
+- ``RawInotifyEvent``

Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md

@@ -0,0 +1,42 @@
+# Watching Directory Trees
+
+Monitor an entire directory hierarchy for filesystem events.
+
+## Overview
+
+The Linux inotify API watches individual directories — it does not descend into subdirectories automatically. The ``Inotify/Inotify`` actor offers two convenience methods that handle the recursion for you.
+
+### Recursive Watch
+
+Call ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` to walk the directory tree once and install a watch on every subdirectory that exists at the time of the call:
+
+```swift
+let inotify = try Inotify()
+let descriptors = try await inotify.addRecursiveWatch(
+    forDirectory: "/home/user/project",
+    mask: [.create, .modify, .delete]
+)
+```
+
+The returned array contains one watch descriptor per directory. Subdirectories created **after** this call are not covered.
+
+### Automatic Subtree Watching
+
+When you also want future subdirectories to be picked up, use ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` instead:
+
+```swift
+let descriptors = try await inotify.addWatchWithAutomaticSubtreeWatching(
+    forDirectory: "/home/user/project",
+    mask: [.create, .modify, .delete]
+)
+```
+
+Internally this listens for `CREATE` events carrying the ``InotifyEventMask/isDir`` flag and installs a new watch with the same mask whenever a subdirectory appears.
+
+### Choosing the Right Method
+
+| Method | Covers existing subdirectories | Covers new subdirectories |
+|--------|:----:|:----:|
+| ``Inotify/Inotify/addWatch(path:mask:)`` | No | No |
+| ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` | Yes | No |
+| ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` | Yes | Yes |

Sources/TaskCLI/TaskCLI.docc/TaskCLI.md

@@ -0,0 +1,46 @@
+# ``TaskCLI``
+
+The build tool for the Swift Inotify project.
+
+## Overview
+
+`TaskCLI` is a small command-line executable (exposed as `task` in `Package.swift`) that automates project-level workflows. Its primary purpose is running the integration test suite inside a Linux Docker container, so you can validate the inotify-dependent code on the correct platform even when developing on macOS.
+
+### Running the Tests
+
+```bash
+swift run task test
+```
+
+This launches a `swift:latest` Docker container with the repository mounted at `/code`, then executes two test passes:
+
+1. All tests **except** `InotifyLimitTests` — the regular integration suite.
+2. Only `InotifyLimitTests` (with `--skip-build`) — tests that manipulate system-level inotify limits and must run in isolation.
+
+The container is started with `--security-opt systempaths=unconfined` so that the limit tests can write to `/proc/sys/fs/inotify/*`.
+
+### Verbosity
+
+Pass one or more `-v` flags to increase log output:
+
+| Flag | Level |
+|------|-------|
+| *(none)* | `notice` |
+| `-v` | `info` |
+| `-vv` | `debug` |
+| `-vvv` | `trace` |
+
+### Prerequisites
+
+Docker must be installed and running on the host machine. The container uses the `linux/arm64` platform by default.
+
+## Topics
+
+### Commands
+
+- ``Command``
+- ``TestCommand``
+
+### Configuration
+
+- ``GlobalOptions``