cleanup, docs

site/doc/pages/file_write.txt

@@ -1,11 +1,23 @@
-file_write
+:sig
+u64 file_write(u64 h, String data)
 
-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 writing
+data : bytes to write at the current offset
+return value : number of bytes written
 
-See also: file_get_contents, file_put_contents, file_append.
+:content
+Writes `data` at the handle's current offset and advances the offset. The handle must come from `file_open()` with a writable mode (`"w"`, `"a"`, or `"r+"`). Binary-safe: `data` may contain NUL and other non-text bytes.
+
+:example
+u64 h = file_open("/tmp/doc-write.txt", "w");
+u64 n = file_write(h, "hello world");
+file_close(h);
+print(n, " bytes -> ", file_get_contents("/tmp/doc-write.txt"), "\n");
 
 :see
 >sys
-
-:example
-print("file_write example\n");
+file_open
+file_pwrite
+file_read
+file_close