acmefs: pardes --fs serves acme's control filesystem over raw Linux FUSE

1 files changed, 38 insertions, 0 deletions

diff --git a/src/tutor.txt b/src/tutor.txt
index 7dfac0bf..f75734e4 100644
--- a/src/tutor.txt
+++ b/src/tutor.txt
@@ -1179,6 +1179,40 @@ abc
  special case.)
 
 =================================================================
+=   PART 5 — THE CONTROL FILESYSTEM (pardes --fs)               =
+=================================================================
+
+ Started as `pardes --fs`, this session serves plan9 acme's control
+ files over FUSE: a directory per pane, holding `body`, `tag`, `ctl`,
+ `addr`, `data`, `event` and the rest, plus `index`, `cons` and `new/`
+ at the top. Every pane shell gets `$PARDES_FS` (where it is mounted)
+ and `$PARDES_PANE` (which pane it is), so a script run in a pane can
+ talk to its own window with no arguments:
+
+     echo hello >> $PARDES_FS/$PARDES_PANE/body     append to this pane
+     cat $PARDES_FS/index                           one line per pane
+     echo hi > $PARDES_FS/new/body                  open a pane holding "hi"
+
+ That IS the extension mechanism: no plugin API, no interpreter, no
+ rebuild — a program that opens files. Two things about it are worth
+ knowing before you use it.
+
+ While a program holds a pane's `event` file open, MIDDLE AND RIGHT
+ CLICKS IN THAT PANE BELONG TO IT: pardes reports them and performs
+ nothing, so the words in that pane's tag can be the program's own
+ commands (examples/acmefs/life.py puts Step/Run/Clear there). The
+ keyboard is not suppressed, so the pane stays editable either way, and
+ when the program exits the clicks come back.
+
+ And writing an event record back — `origin type q0 q1` — makes pardes
+ perform the Look or Exec it names. That is arbitrary command execution
+ by design, the same door acme has always had, which is why the mount
+ lives under $XDG_RUNTIME_DIR at 0700 and why `--fs` is opt-in.
+
+ examples/README.md is the client's guide; docs/acme-fs.md compares this
+ implementation with acme's, file by file.
+
+=================================================================
 =             SUMMARY                                            =
 =================================================================
 
@@ -1198,6 +1232,10 @@ abc
                 landing its cursor where you navigated (prompt start if
                 the input is empty, mid-text otherwise)
                 Filter in its tag toggles a pane-local, theme-keyed palette
+ --fs:          acme's control files over FUSE: $PARDES_FS/<id>/{body,tag,
+                ctl,addr,data,event,...} and $PARDES_FS/{index,cons,new}
+                a script holding a pane's `event` open owns that pane's
+                    middle and right clicks; writing a record back runs it
  KEYS (helix):  h j k l  w b e  0 $ ^  gg ge  f F t T  v x X  d c y p
                 i a I A o O   u undo  U redo   Enter=look  Tab=execute
                 w b e f F t T SELECT what they cross, so `i` after one