cleanup, docs

site/doc/pages/file_open.txt

@@ -1,11 +1,23 @@
-file_open
+:sig
+u64 file_open(String path, String mode)
 
-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
+path : file to open, resolved against the unit's directory
+mode : "r" read, "w" truncate+write, "a" append, "r+" read+write
+return value : opaque handle; 0 means open failed (bad path, policy denial, or lock timeout)
 
-See also: file_get_contents, file_put_contents, file_append.
+:content
+Opens a file for streaming, handle-based I/O and returns an opaque handle for `file_read()`, `file_write()`, `file_seek()`, and `file_close()`. Locks are automatic and scoped to the handle: read opens take a shared lock, write/append/read-write opens take an exclusive lock, and `file_close()` releases it. Lock waits are bounded by `UCE_FILE_LOCK_TIMEOUT_MS` (default 2000ms), so a contended open returns 0 instead of blocking forever. For whole-file access prefer `file_get_contents()` / `file_put_contents()`.
+
+:example
+u64 h = file_open("/tmp/doc-open.txt", "w");
+file_write(h, "streamed");
+file_close(h);
+print(file_get_contents("/tmp/doc-open.txt"), "\n");
 
 :see
 >sys
-
-:example
-print("file_open example\n");
+file_read
+file_write
+file_close
+file_get_contents