From a0ecd9fd2bd5ee725d998c4db51d96f0cf7fc061 Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Sun, 16 Aug 2026 09:14:37 +0800
Subject: [PATCH] docs(cli): server restart ends sessions, and its sibling
 already said so
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`stop` is described as "Stop the server; sessions end". `restart` was
"Stop, then start" — the same destruction, undisclosed, on the verb
people reach for casually when something seems stuck.

Measured rather than assumed: two panes before, zero after, workspaces
still there. So the layout survives, because the tree is on disk, and
what those shells were running does not.

The long form also separates this from the thing it will be confused
with. The server can hand panes to a new build of itself with their pids
and ptys kept — that is a real wire request (`ClientMsg::Handoff`, into
`hand_over` and `handoff::take_over`), and it is how an update keeps
sessions. `restart` is not that path, and someone who has read about one
should not assume the other.
---
 crates/tty7-cli/src/cli.rs | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/crates/tty7-cli/src/cli.rs b/crates/tty7-cli/src/cli.rs
index fe9a5039..b6df05eb 100644
--- a/crates/tty7-cli/src/cli.rs
+++ b/crates/tty7-cli/src/cli.rs
@@ -572,7 +572,18 @@ pub enum ServerCmd {
     #[command(about = "Stop the server; sessions end")]
     Stop,
 
-    #[command(about = "Stop, then start")]
+    #[command(
+        about = "Stop, then start; sessions end",
+        long_about = "Stop, then start.\n\n\
+                      Sessions end, exactly as `stop` says of itself: every pane the \
+                      server is running is a child of it, and this kills the server. The \
+                      workspaces survive — the tree is on disk — so the layout is still \
+                      there afterwards with dead leaves the GUI revives into fresh \
+                      shells. What does not survive is what those shells were running.\n\n\
+                      The server can hand panes to a new build of itself with their pids \
+                      and ptys intact, which is how an update keeps your sessions, but \
+                      that path is not this one: this stops and starts."
+    )]
     Restart,
 
     #[command(about = "Version, uptime, panes, links")]