improve docs

9 files changed, 75 insertions, 1 deletions

diff --git a/Sources/bar/bar.docc/bar.md b/Sources/bar/bar.docc/bar.md
index 0788349..ae515a0 100644
--- a/Sources/bar/bar.docc/bar.md
+++ b/Sources/bar/bar.docc/bar.md
@@ -32,6 +32,7 @@ If you specify the interval, the block will re-run the command with such frequen
 
 ### Bar
 
+- <doc:screens>
 - <doc:hide-show>
 
 ### Blocks
diff --git a/Sources/bar/bar.docc/command.md b/Sources/bar/bar.docc/command.md
index c94862e..da1a71f 100644
--- a/Sources/bar/bar.docc/command.md
+++ b/Sources/bar/bar.docc/command.md
@@ -22,3 +22,15 @@ Each command inherits the `bar` process environment plus a `BLOCK` variable that
 > Important: Since the environment is inherited by the `bar` process, there is no guarantee that the script will always receive the same set of variables.
 For example, if you run `bar` from your shell, you'll probably have available the custom `PATH` you set.
 On the contrary, if you run `bar` from a launch agent, you'll probably not have the same custom `PATH` set.
+
+## Error handling
+
+If the command exits with a non-zero status or cannot be launched, the block displays a single cell containing the text `ERROR`.
+The command's stderr is forwarded to the `bar` process stderr, which you can inspect for the actual failure.
+
+```shell
+# Example: simulate a command failure
+some-command-that-fails && echo "&!1 success"
+```
+
+> Tip: If you see `ERROR` in the bar, run the command manually in your terminal to diagnose the issue.
diff --git a/Sources/bar/bar.docc/highlighting.md b/Sources/bar/bar.docc/highlighting.md
index 8bd737c..aa2ad0d 100644
--- a/Sources/bar/bar.docc/highlighting.md
+++ b/Sources/bar/bar.docc/highlighting.md
@@ -34,4 +34,8 @@ echo "&!2 workspace 2"    # highlighted with Config.highlights[1]
 echo "workspace 3"        # no highlight
 ```
 
+> Important: The `&!<level>` notation is stripped before rendering, so only the text after it is displayed.
+> For example, `&!1 workspace 1` renders as `workspace 1` on a highlighted background.
+
 > Important: The highlight level is a positive integer that indexes into ``Config-swift.enum/highlights`` (1-based).
+> If the level exceeds the number of defined highlights, the cell is treated as unhighlighted.
diff --git a/Sources/bar/bar.docc/how-it-works.md b/Sources/bar/bar.docc/how-it-works.md
index b6efbd8..e81e40a 100644
--- a/Sources/bar/bar.docc/how-it-works.md
+++ b/Sources/bar/bar.docc/how-it-works.md
@@ -29,7 +29,7 @@ The way to install *bar* is simply to download or clone the repository on your s
 What if you need a specific feature that is not available?
 Well, you can build it or patch it yourself.
 
-*bar* aims to stay focused and minimal, so it can be read through and understood in roughly half an hour.
+*bar* aims to stay focused and minimal, so it can be read through and understood in roughly an hour.
 You're more than encouraged to apply <doc:patches> to extend the software, write your own features, and ultimately publish them for the entire community.
 
 This approach is far more powerful than a plugin/extension ecosystem because you're not limited to what we, as the main developers, decide you can customise or change.
diff --git a/Sources/bar/bar.docc/installation.md b/Sources/bar/bar.docc/installation.md
index 272882e..6475aa1 100644
--- a/Sources/bar/bar.docc/installation.md
+++ b/Sources/bar/bar.docc/installation.md
@@ -33,6 +33,9 @@ make install
 > make install PREFIX=/usr/local/bin
 > ```
 
+> Tip: While iterating on the configuration, use `make run` instead.
+> It builds and runs the program in one step without copying the binary, which speeds up the edit-compare loop.
+
 ### Without make
 
 If you don't have `make`, build directly with the Swift Package Manager:
diff --git a/Sources/bar/bar.docc/patches.md b/Sources/bar/bar.docc/patches.md
index 1a356c9..e2646f3 100644
--- a/Sources/bar/bar.docc/patches.md
+++ b/Sources/bar/bar.docc/patches.md
@@ -88,3 +88,7 @@ To publish, upload the patch somewhere publicly accessible (e.g., the *bar* GitH
 ### Appearance
 
 - <doc:patch-font-offset>
+
+### Functionality
+
+- <doc:patch-screen-hotplug>
diff --git a/Sources/bar/bar.docc/patches/patch-font-offset.md b/Sources/bar/bar.docc/patches/patch-font-offset.md
index 9b2d841..3c1e0ad 100644
--- a/Sources/bar/bar.docc/patches/patch-font-offset.md
+++ b/Sources/bar/bar.docc/patches/patch-font-offset.md
@@ -21,6 +21,12 @@ enum Config {
 curl -sL https://raw.githubusercontent.com/paninihouse/bar/refs/heads/master/patches/bar-font_offset-20260810-11d813c.patch | patch -p1
 ```
 
+After applying, rebuild the program:
+
+```shell
+make install
+```
+
 ## Author
 
 Tommaso Negri [@tommasongr](https://github.com/tommasongr)
diff --git a/Sources/bar/bar.docc/patches/patch-screen-hotplug.md b/Sources/bar/bar.docc/patches/patch-screen-hotplug.md
new file mode 100644
index 0000000..b1aee91
--- /dev/null
+++ b/Sources/bar/bar.docc/patches/patch-screen-hotplug.md
@@ -0,0 +1,26 @@
+# Screen hot-plug
+
+Recreate bars when a display is connected or disconnected at runtime.
+
+Without this patch, *bar* only creates windows for the screens connected at launch.
+If you plug in or unplug a display while the program is running, nothing changes.
+This patch observes the system notification for display configuration changes and rebuilds the bar windows to match the new screen layout.
+
+All windows are closed and reopened, so every bar picks up the correct position and size for its screen.
+The block content is preserved during the rebuild — there is no need to re-run commands.
+
+## Installation
+
+```shell
+curl -sL https://raw.githubusercontent.com/paninihouse/bar/refs/heads/master/patches/bar-screen_hotplug-20260810-f6805c9.patch | patch -p1
+```
+
+After applying, rebuild the program:
+
+```shell
+make install
+```
+
+## Author
+
+Tommaso Negri [@tommasongr](https://github.com/tommasongr)
diff --git a/Sources/bar/bar.docc/screens.md b/Sources/bar/bar.docc/screens.md
new file mode 100644
index 0000000..99d9385
--- /dev/null
+++ b/Sources/bar/bar.docc/screens.md
@@ -0,0 +1,18 @@
+# Multi-screen
+
+How the bar behaves when more than one display is connected.
+
+At launch, *bar* creates one bar for **each screen** connected to your Mac.
+Every bar spans the full width of its own screen and is anchored at the top or bottom edge, depending on the ``Config-swift.enum/position`` setting.
+All bars display the same set of ``Block``, so each screen mirrors the others.
+
+You don't need to configure anything per-display: every bar is built from the same ``Config``, and the ``Screen`` type sizes it automatically to fit its screen's frame.
+This also means that bars on displays with different resolutions are sized to match each screen.
+
+## Adding or removing displays
+
+Bars are created when the program starts, based on the screens connected at that moment.
+If you connect or disconnect a display while the program is already running, *bar* does **not** automatically add or remove a bar for it.
+To pick up the new screen layout, restart the program.
+
+> Note: Handling display hot-plugging at runtime is not part of the core, but the screen code is small and self-contained, which makes it a good candidate for a custom <doc:patches>.
\ No newline at end of file