pirc-extension 0.1.8v0.1.8

1 files changed, 24 insertions, 0 deletions

diff --git a/README.md b/README.md
index adf34e6..1fbf22d 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,30 @@ enrolled without the command; a relay URL without a token asks for approval.
 If the relay's certificate is self-signed or from a private CA, set
 `NODE_EXTRA_CA_CERTS` to the CA's PEM file in the environment pi starts in.
 
+## Where pi runs
+
+Clients name a session by the terminal it runs in. In tmux, that is the
+tmux session and window (found through `$TMUX_PANE`); in
+[herdr](https://herdr.dev), the workspace and tab (through its socket).
+The names are checked again whenever pi does something: a prompt, a turn
+starting or ending, a client's request. So a window renamed while pi sits
+idle shows its new name after pi's next turn.
+
+For any other terminal, or to name sessions your own way, another pi
+extension can say where pi runs:
+
+```ts
+pi.events.emit("pirc:place", { kind: "zellij", group: "work", window: "api" });
+pi.events.emit("pirc:place", { display: "deploys" }); // shown as it is
+pi.events.emit("pirc:place", {});   // show nothing
+pi.events.emit("pirc:place", null); // back to PiRC's own detection
+```
+
+Fields: `kind`, `group` (a tmux session, a workspace), `groupNumber`,
+`window` (a window, a tab), `windowNumber`, `pane` and `display`, each
+optional; names are cut to 128 bytes. A place given this way stands until
+the next one, so the extension can update it whenever it likes.
+
 ## Licence
 
 MIT; see `LICENSE`. The bundle includes third-party code, listed in