1 files changed, 112 insertions, 13 deletions
diff --git a/man/meshbay-node.1 b/man/meshbay-node.1
index 1e1173b..92067a2 100644
--- a/man/meshbay-node.1
+++ b/man/meshbay-node.1
@@ -68,12 +68,18 @@ List all hosted groups with their roots, key status, file count, and
 connected peers.
 .
 .TP
-\fBgroup add\fR \fIname\fR \fB\-\-dir\fR \fIpath\fR [\fB\-\-upload\-dir\fR \fIpath\fR]
+\fBgroup add\fR \fIname\fR \fB\-\-dir\fR \fIpath\fR
 Attach a hub\-side group to this node by writing a
 .B [[groups]]
 entry to
 .IR node.toml .
 The group must already exist on the hub.
+The directory becomes the group's first root, and is
+.B read\-write
+so that a new group can receive an upload without further configuration;
+pass
+.B \-\-no\-writable
+for a group that only publishes.
 Run
 .B meshbay\-node reload
 afterwards, then
@@ -88,6 +94,54 @@ Asks for confirmation unless
 .B \-\-yes
 is given.
 .
+.SS Root management
+A group has one or more named roots: directories on this machine that its
+members see. Each is read\-only or read\-write, independently; a group whose
+roots are all read\-only is valid and accepts no uploads at all.
+.
+.TP
+.B root list
+List this group's roots with their flags and current availability.
+.
+.TP
+\fBroot add\fR \fIpath\fR [\fB\-\-name\fR \fIname\fR] [\fB\-\-writable\fR] [\fB\-\-removable\fR]
+Add a directory to the group. The name defaults to the directory's
+basename; two roots in a group cannot share a name, compared without
+regard to case, and no root may sit inside another.
+Run
+.B meshbay\-node reload
+afterwards to start indexing it.
+.
+.TP
+\fBroot remove\fR \fIname\fR
+Remove a root from the group. Files on disk are untouched; only
+.I node.toml
+changes. The last remaining root cannot be removed.
+Asks for confirmation unless
+.B \-\-yes
+is given.
+.
+.TP
+\fBroot set\fR \fIname\fR [\fB\-\-writable\fR|\fB\-\-no\-writable\fR] [\fB\-\-removable\fR|\fB\-\-no\-removable\fR]
+Change a root's flags without removing it. Takes effect immediately; no
+reload is needed.
+.
+.TP
+\fBroot eject\fR \fIname\fR
+Mark a removable root as ejected before physically disconnecting the
+device. Its files are hidden from members and its index entries are
+frozen \(em nothing is deleted \(em and the directory watcher stops, so
+the unplug produces no deletions to propagate. The device can then be
+removed safely. Refused on a root that is not marked
+.BR removable .
+.
+.TP
+\fBroot plug\fR \fIname\fR
+Re\-enable an ejected root once the device is back. Refused if the
+directory is not readable, since clearing the flag while the device is
+still absent would hand the next scan an empty directory. The root is
+rescanned, so anything that changed while it was away is picked up.
+.
 .SS Member management
 .TP
 .B member list
@@ -196,11 +250,33 @@ Shared directory, used with
 .BR "group add" .
 .
 .TP
-\fB\-\-upload\-dir\fR \fIpath\fR
-Separate upload directory, used with
-.BR "group add" .
-Files land directly in this directory (not in a subdirectory) and it
-appears as its own root in the index.
+.BR \-\-writable ", " \-\-no\-writable
+Whether a root accepts uploads from group members, used with
+.BR "root add" ", " "root set" " and " "group add" .
+Uploads land in an
+.I uploads
+subdirectory of the root; existing files are never replaced.
+A new root is read\-only unless
+.B \-\-writable
+is given; the directory passed to
+.B "group add"
+is the exception and is writable by default.
+.
+.TP
+.BR \-\-removable ", " \-\-no\-removable
+Whether a root lives on a device that gets disconnected, used with
+.BR "root add" " and " "root set" .
+Enables
+.BR "root eject" " and " "root plug" ,
+and makes the node treat the directory suddenly disappearing as an
+unannounced eject rather than as a deletion.
+.
+.TP
+\fB\-\-name\fR \fIname\fR
+Explicit name for a root, used with
+.BR "root add" .
+Default: the directory's basename. Required for a drive or filesystem
+root, which has no basename to derive one from.
 .
 .TP
 .B \-\-yes
@@ -343,15 +419,18 @@ Human\-readable group name.
 .
 .TP
 .B shared_dir
-Single\-directory shorthand: equivalent to declaring one root named after
-the directory's basename, which receives uploads. Cannot be combined with
+Single\-directory shorthand: equivalent to declaring one read\-write root
+named after the directory's basename. Cannot be combined with
 .BR [[groups.roots]] .
 .
 .TP
 .B upload_dir
-A separate filesystem path for uploads. Files land directly in it (not in
-a subdirectory) and it appears as its own root in the index. When set,
-no other root receives uploads.
+Deprecated. A separate filesystem path for uploads, from before roots
+carried their own read\-write flag. A configuration still using it is
+read as a second, writable root and every other root is forced
+read\-only. Use
+.B writable
+on the intended root instead.
 .
 .TP
 .B visibility
@@ -399,10 +478,30 @@ A view hint: one of
 Currently unused.
 .
 .TP
-.B upload
-Boolean. Exactly one root per group must receive uploads. Default:
+.B writable
+Boolean. Whether members may upload into this root. Uploads land in an
+.I uploads
+subdirectory; an existing file is never replaced. Any number of roots in
+a group may be writable, including none. Default:
+.BR false .
+.
+.TP
+.B removable
+Boolean. Whether this root lives on a device that gets disconnected.
+Enables
+.BR "meshbay\-node root eject" ,
+and makes the directory suddenly disappearing freeze the root rather
+than look like a deletion of everything in it. Default:
 .BR false .
 .
+.TP
+.B upload
+Deprecated spelling of
+.BR writable ,
+read for configurations written before the two were separated.
+.B writable
+wins where both appear.
+.
 .SS [keystore]
 .TP
 .B path