From 932b14bbfc37bfdc8da9fd258e078acebd2eff92 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Thu, 25 Jun 2026 14:16:17 +0300
Subject: [PATCH] doc: document shell-integration, URL, notify, and bell config

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I75b279526ba5857d3a4104e67ccaa58e6a6a6964
---
 doc/beer.1.scd      | 22 +++++++++++++++++++++-
 doc/beer.toml.5.scd | 31 ++++++++++++++++++++++++++++++-
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/doc/beer.1.scd b/doc/beer.1.scd
index 149e753..ef7f85f 100644
--- a/doc/beer.1.scd
+++ b/doc/beer.1.scd
@@ -53,17 +53,37 @@ table of _beer.toml_(5).
 :  Reset the font size
 |  F11
 :  Toggle fullscreen
+|  Ctrl+Shift+N
+:  Open a new window in the shell's current directory
+|  Ctrl+Shift+Up / Ctrl+Shift+Down
+:  Jump to the previous / next shell prompt (OSC 133)
+|  Ctrl+Shift+O
+:  Enter URL hint mode
+
+The *pipe-command-output* action (unbound by default) feeds the last command's
+output to the configured command; see *shell-integration* in _beer.toml_(5).
 
 In incremental search, type to refine the query, *Up*/*Return* jumps to the
 previous match, *Down* to the next, and *Escape* exits.
 
+In URL hint mode each visible URL is tagged with a label; type the label to open
+the URL in the configured launcher, or press *Escape* to cancel.
+
 # MOUSE
 
 Left-click and drag selects text; double-click selects a word, triple-click a
 line, and Ctrl+drag selects a rectangular block. The selection is copied to the
 primary selection on release; middle-click pastes it. The wheel scrolls
 history. Holding *Shift* forces local selection even while an application has
-requested mouse reporting.
+requested mouse reporting. Clicking an *OSC 8* hyperlink opens it; hovering one
+underlines it.
+
+# SHELL INTEGRATION
+
+With a shell configured to emit them, *beer* tracks the working directory
+(*OSC 7*, used by new windows) and prompt marks (*OSC 133*) for prompt jumping
+and piping the last command's output. Applications may raise desktop
+notifications via *OSC 9*, *OSC 777*, and *OSC 99*.
 
 # ENVIRONMENT
 
diff --git a/doc/beer.toml.5.scd b/doc/beer.toml.5.scd
index a0d449a..7888765 100644
--- a/doc/beer.toml.5.scd
+++ b/doc/beer.toml.5.scd
@@ -82,6 +82,14 @@ channel).
 *visual* = _bool_
 	Briefly flash the screen on the terminal bell. Default _false_.
 
+*command* = _[argv]_
+	Command run on the bell, e.g. _["paplay", "/usr/share/sounds/bell.oga"]_.
+	Unset runs nothing.
+
+*urgent* = _bool_
+	Request the compositor's attention (xdg-activation) when the bell rings
+	while the window is unfocused. Default _false_.
+
 # [mouse]
 
 *scroll-multiplier* = _float_
@@ -100,7 +108,8 @@ _"none"_ unbinds the chord.
 
 Recognized actions: _copy_, _paste_, _paste-primary_, _scrollback-up_,
 _scrollback-down_, _scrollback-top_, _scrollback-bottom_, _search_,
-_font-increase_, _font-decrease_, _font-reset_, _fullscreen_.
+_font-increase_, _font-decrease_, _font-reset_, _fullscreen_, _new-window_,
+_jump-prompt-up_, _jump-prompt-down_, _pipe-command-output_, _url-mode_.
 
 ```
 [key-bindings]
@@ -108,6 +117,26 @@ _font-increase_, _font-decrease_, _font-reset_, _fullscreen_.
 "Ctrl+grave" = "none"
 ```
 
+# [shell-integration]
+
+Behaviour driven by *OSC 7* (cwd) and *OSC 133* (prompt) marks.
+
+*pipe-command* = _[argv]_
+	Command the _pipe-command-output_ binding feeds the last command's output
+	to on stdin, e.g. _["less"]_. Empty (the default) disables the action.
+
+# [url]
+
+*launch* = _[argv]_
+	Launcher the URL is appended to when an _OSC 8_ hyperlink is clicked or a
+	hint-mode label is chosen. Default _["xdg-open"]_.
+
+# [notify]
+
+*command* = _[argv]_
+	Notifier for desktop notifications (_OSC 9_/_777_/_99_); the title and body
+	are appended as the final two arguments. Default _["notify-send"]_.
+
 # [text-bindings]
 
 A table of _chord_ = _text_ entries that send a literal string to the shell.