cleanup, docs

site/doc/pages/random_bytes.txt

@@ -1,11 +1,18 @@
-# random_bytes
+:sig
+String random_bytes(u64 n)
 
+:params
+n : number of bytes to generate
+return value : `n` cryptographically random bytes
 
-Returns up to `n` bytes from the host CSPRNG. Requests are capped to a bounded size.
+:content
+Returns `n` cryptographically secure random bytes, suitable for session IDs, tokens, and salts. The bytes are binary; wrap them with `base64_encode()` or `sha256_hex()` when you need printable text.
 
 :example
-String bytes = random_bytes(4);
-print(bytes.length(), " bytes\n");
+String token = base64_encode(random_bytes(16));
+print(random_bytes(16).length(), " raw bytes; as base64 token: ", token.length(), " chars\n");
 
 :see
->noise
+>sys
+base64_encode
+sha256_hex