1 files changed, 21 insertions, 0 deletions
diff --git a/src/sys/README.md b/src/sys/README.md
new file mode 100644
index 0000000..22802d5
--- /dev/null
+++ b/src/sys/README.md
@@ -0,0 +1,21 @@
+# System abstraction
+
+`system.h` is the only OS-facing API used by the application and storage
+layers. Paths and process arguments are UTF-8 strings on every platform.
+
+The API owns these responsibilities:
+
+- process argument conversion and absolute/path-join operations;
+- directory creation, temporary directories, and path removal/replacement;
+- opaque file handles, locking, read/write/seek/truncate/flush operations;
+- wall-clock and monotonic milliseconds;
+- cryptographically secure random bytes.
+
+Returned strings are heap allocated and must be released with `free()`. Files
+must be initialized or opened through this API and closed with
+`tiny_sys_file_close()`.
+
+Platform selection is intentionally confined to the single conditional block
+in `system.c`. Windows uses wide Win32 calls internally; non-Windows builds use
+the POSIX implementation. No Win32 or POSIX type is exposed by `system.h`.
+