cleanup, docs

site/doc/pages/file_seek.txt

@@ -1,11 +1,26 @@
-file_seek
+:sig
+s64 file_seek(u64 h, s64 offset, s64 whence)
 
-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()
+offset : byte offset relative to whence
+whence : 0 from start, 1 from current, 2 from end
+return value : the new absolute offset, or -1 on error
 
-See also: file_get_contents, file_put_contents, file_append.
+:content
+Moves a handle's read/write offset for random access. Combine with `file_read()` / `file_write()` to jump around a file; `file_tell()` reports the current offset.
+
+:example
+u64 w = file_open("/tmp/doc-seek.txt", "w");
+file_write(w, "hello world");
+file_close(w);
+u64 r = file_open("/tmp/doc-seek.txt", "r");
+file_seek(r, 6, 0);
+print(file_read(r, 5), "\n");
+file_close(r);
 
 :see
 >sys
-
-:example
-print("file_seek example\n");
+file_tell
+file_read
+file_open