docs: /browser-target, and why switching restarts the daemon

1 files changed, 22 insertions, 1 deletions

diff --git a/FORK.md b/FORK.md
index f574b3a..c273980 100644
--- a/FORK.md
+++ b/FORK.md
@@ -50,12 +50,33 @@ Nothing else to configure: castle is the built-in default
 
 ## Choosing a browser
 
+From inside a pi session:
+
+```
+/browser-target                 show the current target
+/browser-target local           this machine's own browser
+/browser-target default         back to castle
+/browser-target host:port       somewhere else
+```
+
+The choice persists in `~/.pi/agent/browser-target.json` and applies to every
+session on the machine, because the browser daemon is machine-wide. Switching
+replaces that daemon process — it resolves its target once at startup and holds
+the WebSocket to the old browser, so nothing short of a restart actually moves
+you.
+
+Or set it per-process:
+
 | `BU_CDP_HTTP` | behaviour |
 |---|---|
-| unset | castle, falling back to this machine's browser if unreachable |
+| unset | the stored choice, else castle, falling back to this machine's browser if unreachable |
 | `host:port` | that endpoint; **unreachable is a hard error** |
 | `local` (also `localhost`, `off`, `none`, `0`, `no`) | upstream behaviour — this machine's own browser |
 
+Precedence is `BU_CDP_HTTP` > `/browser-target` > built-in default, so a one-off
+`BU_CDP_HTTP=… pi` is never silently overridden by a choice made days ago. When
+the variable is set, `/browser-target` says so instead of pretending to obey.
+
 The asymmetry is deliberate. An explicit endpoint is an instruction, so failing
 to reach it must not quietly automate a different browser — that would drive
 your own signed-in Chrome instead of the shared one. The default is only a