commit 85714d28e5bc0b9c146d3fff8bc0f65dc42f8a7b
from: mtmn <miro@haravara.org>
date: Sun Sep  6 20:40:56 2026 UTC

docs cleanup

commit - 9ed49f84562145a3245831fa21ecd166a6b6ad03
commit + 85714d28e5bc0b9c146d3fff8bc0f65dc42f8a7b
blob - 824323346cc9d8c5eaebfa7539ad0fd62cc8db02
blob + 9f1b9bf2991dc9e073e3fb06db4fdcfe8a3a4f03
--- README.md
+++ README.md
@@ -28,7 +28,7 @@ pisol COMMAND [ARG...]
 
 `make tui` opens the editor. Add writable directories and outbound TCP ports,
 then save with `x`. The editor shows and changes only grants from the local
-file. Grants from the global init file apply to every project; edit those in
+file. Grants from the global init file apply to every project. Edit those in
 the global file itself.
 
 The sandbox allows read, write and execute access to the current directory.
blob - 4c386355288109cd681c7e4ec6e8a592cf55a0f5
blob + ceb16173d0b428132cc397a5e66e6316a8b132a2
--- doc/pisol.1
+++ doc/pisol.1
@@ -33,11 +33,12 @@ Use
 before a command name that starts with a hyphen.
 .SH SANDBOX
 pisol grants read, write and execute access to the current directory.
-Temporary storage is writable. System runtime files are readable. Outbound TCP
+The command can write to temporary storage and read system runtime files.
+Outbound TCP
 is denied unless configuration allows a port. A configured port also grants the
 name resolution that port requires.
 .PP
-The command inherits the caller environment. pisol also sets
+The command inherits the environment of the calling shell. pisol also sets
 .B PROMPT_ENV_INDICATOR=isolated
 and
 .B ISOLATE_ENV
@@ -50,15 +51,16 @@ is set, pisol runs the command without another sandbox
 Add a writable directory.
 .TP
 .B r
-Remove a writable directory by number. Only grants from the local file can be
-removed; grants from the global init file belong to that file.
+Remove a writable directory by number. You can remove only grants from the
+local file. Grants from the global init file belong to that file.
 .TP
 .BI p " PORT"
 Allow outbound TCP to PORT.
 .TP
 .B d
-Remove an outbound TCP port. Local grants only, as for
-.BR r .
+Remove an outbound TCP port. As with
+.BR r ,
+it removes local grants only.
 .TP
 .B c
 Show the global and local configuration files.
@@ -73,9 +75,9 @@ Save and exit.
 is trusted Bash. pisol loads the optional global init file before this local
 file. Both files add grants to the Bash array
 .IR args .
-The vocabulary is the same on every platform and each backend translates it, so
-a saved configuration is portable. A grant that the selected backend cannot
-express is an error, never a silent omission.
+Both files use the same grant vocabulary on every platform. Each backend
+translates it, so a saved configuration stays portable. A grant that the
+selected backend cannot express is an error, never a silent omission.
 .PP
 For example:
 .PP
@@ -124,8 +126,8 @@ Provide runtime paths and sandbox grants.
 .BR WAYLAND_DISPLAY , " XDG_RUNTIME_DIR"
 Provide an optional Wayland socket grant.
 .SH EXIT STATUS
-The editor exits with status zero when it ends normally. Load and save
-errors exit nonzero. In
+The editor exits with status zero when it ends normally. Load and save errors
+end the editor with a nonzero status. In
 command mode, pisol returns the command status. Usage errors, untranslatable
 grants, an out-of-range port and an unrecognised
 .B PISOL_BACKEND