cleanup, docs

site/doc/pages/file_stat.txt

@@ -1,9 +1,20 @@
+:sig
 DValue file_stat(String path)
 
-Returns `{ exists, size, mtime, ctime, mode, is_dir, is_file, is_symlink }` for a policy-gated path. Missing or denied paths return `exists=false`.
+:params
+path : path to inspect, resolved against the unit's directory
+return value : a map with exists, is_file, is_dir, is_symlink, size, mode, mtime, ctime
+
+:content
+Returns metadata about a path as a `DValue` map. Read fields with the usual accessors, e.g. `st["size"].to_u64()` and `st["is_file"].to_bool()`. When the path does not exist, `exists` is false.
+
+:example
+file_put_contents("/tmp/doc-stat.txt", "12345");
+DValue st = file_stat("/tmp/doc-stat.txt");
+print("size=", st["size"].to_u64(), " is_file=", st["is_file"].to_bool() ? "yes" : "no", "\n");
 
 :see
 >sys
-
-:example
-print("file_stat example\n");
+dir_list
+file_exists
+file_mtime