cleanup, docs

site/doc/pages/file_pread.txt

@@ -1,11 +1,25 @@
-file_pread
+:sig
+String file_pread(u64 h, u64 offset, 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
+offset : absolute byte offset to read from
+len : maximum number of bytes to read
+return value : up to `len` bytes read at `offset`
 
-See also: file_get_contents, file_put_contents, file_append.
+:content
+Reads `len` bytes from an absolute `offset` without moving the handle's current offset. Useful for random access reads that interleave with sequential ones.
+
+:example
+u64 w = file_open("/tmp/doc-pread.txt", "w");
+file_write(w, "hello world");
+file_close(w);
+u64 r = file_open("/tmp/doc-pread.txt", "r");
+print(file_pread(r, 6, 5), "\n");
+file_close(r);
 
 :see
 >sys
-
-:example
-print("file_pread example\n");
+file_read
+file_pwrite
+file_open