cleanup, docs

site/doc/pages/path_is_within.txt

@@ -3,15 +3,20 @@ bool path_is_within(String path, String root)
 
 :params
 path : path to test
-root : containing directory
-return value : true when both paths canonicalize and `path` is equal to or inside `root`
+root : directory that should contain it
+return value : true if `path` is inside `root`
+
+:content
+Reports whether `path` lies inside `root`. It resolves both paths to their canonical form (like `path_real()`), so they must exist and `..` traversal is collapsed first. Use it to reject path-traversal attempts before opening user-supplied paths.
+
+:example
+mkdir("/tmp/doc-within");
+file_put_contents("/tmp/doc-within/app.txt", "x");
+print(path_is_within("/tmp/doc-within/app.txt", "/tmp/doc-within") ? "inside" : "outside", " / ");
+print(path_is_within("/tmp/doc-within/../doc-within/app.txt", "/tmp/doc-within") ? "inside" : "outside", "\n");
+dir_remove("/tmp/doc-within", true);
 
 :see
 >sys
->path_real
-
-:content
-Performs canonical containment on the host. It resolves `..`, symlinks, and trailing slash differences before comparing, so `/foo/bar2` is not considered inside `/foo/bar`.
-
-:example
-print("path_is_within example\n");
+path_real
+expand_path