cleanup, docs

site/doc/pages/file_read.txt

@@ -1,11 +1,25 @@
-file_read
+:sig
+String file_read(u64 h, u64 len)
 
-Streaming/handle-based file I/O across the wasm host membrane. Handles are opaque u64 values returned by file_open(); 0 means open failed (including path policy denial or bounded lock timeout). Locks are automatic and lifetime-scoped: read opens take a shared lock, write/append/read-write opens take an exclusive lock, and file_close() releases it. Lock wait is bounded by UCE_FILE_LOCK_TIMEOUT_MS (default 2000ms).
+:params
+h : handle from file_open() opened for reading
+len : maximum number of bytes to read
+return value : up to `len` bytes from the current offset (shorter at end of file)
 
-See also: file_get_contents, file_put_contents, file_append.
+:content
+Reads up to `len` bytes starting at the handle's current offset and advances the offset. Returns fewer bytes (or `""`) at end of file. Use `file_seek()` to move the offset, or `file_pread()` to read at an absolute offset without moving it.
+
+:example
+u64 w = file_open("/tmp/doc-read.txt", "w");
+file_write(w, "hello world");
+file_close(w);
+u64 r = file_open("/tmp/doc-read.txt", "r");
+print(file_read(r, 5), "\n");
+file_close(r);
 
 :see
 >sys
-
-:example
-print("file_read example\n");
+file_open
+file_pread
+file_seek
+file_close