docs: signing what is sent, and which --sign-every to choose

api.md's Signed changes says what sent, all and none do, what each
costs, and which to choose: sent for nearly every swarm, all where each
change should carry its own proof, none to save signatures where only
protocol data and listed paths need them; and that signatures travel
with their changes, a message carrying none taking none. access.md no
longer says signatures come on their own within a second.

2 files changed, 31 insertions, 14 deletions

diff --git a/docs/access.md b/docs/access.md
index 4c41e3d..2df7270 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -276,9 +276,9 @@ through (they look at the path asked for, the rules at everything the change doe
 can't cut its node off.
 
 With `"signatures": "required"`, a change also needs a signature by the node it names
-([`api.md`](api.md), Signed changes): every node then signs every change it makes, and
-one no signature vouches for yet waits, with whatever builds on it, until one does
-(they come with the changes, or within a second on their own). A signature vouches for
+([`api.md`](api.md), Signed changes): every node then signs what it sends, so every
+change leaves vouched for, and one no signature vouches for yet waits, with whatever builds on it, until one does
+(they come with the changes, in the same sync messages). A signature vouches for
 its change and the node's changes it builds on, no others: a change made under another
 node's actor is forged, refused, and logged as its sender's (`A peer brought changes
 forged`). A member can then no longer write as another member; the user a change names is still its node's word.
diff --git a/docs/api.md b/docs/api.md
index 681eb60..0d96dde 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -260,17 +260,34 @@ not the node's. So not every change is signed, only those that
 * or were written with `?signed=true`.
 
 A change left unsigned, such as a metric written many times a second, is vouched for
-by the node's next signed one: with `--sign-every 1s` (the default), the node signs its
-latest change at most a second after it if nothing signed it before, so every change is vouched
-for within a second, at one signature a second at most; `--sign-every all` signs every
-change as it is made, and `--sign-every none` signs only those above. A swarm whose policy requires
-signatures ([`access.md`](access.md), Changes judged on every node) has every change
-signed as it is made, whatever `--sign-every` says.
-Signatures travel with sync messages: a node passes on, for each node's writes, the
-latest signature it checked, and checks one it receives once it holds the change (a
-signature costs about 30 µs to check, and one per node and run vouches for the rest).
-Those no sync message took, as one made after its change went, go on their own within
-a second (SIGNATURES), to each peer that wasn't sent them yet.
+by the node's next signed one. Which that is, `--sign-every` says:
+
+* `sent` (the default): the node signs its latest change, if nothing signed it yet, as
+  a sync message takes it. The signature leaves in the same message as the changes it
+  vouches for, so every change arrives vouched for. A node writing now and then signs
+  each change; one writing many a second signs once per message, however many changes
+  it carries: as many signatures as messages, not as changes.
+* `all`: every change, as it is made. Each change has its own signature, also one
+  never sent (a change made and kept while the node is cut off); the cost is a
+  signature per change, made, kept and checked on every node.
+* `none`: only those above. A change left unsigned waits for the node's next signed
+  one: until then nobody can tell it is the node's.
+
+Which to choose: `sent` for nearly every swarm, slow or fast, since it signs what
+leaves and nothing more. `all` where each change should carry its own proof, as when
+changes are read with their signatures one by one later, at a signature per change
+(about 25 µs to make, 30 µs to check on every node, 96 bytes kept). `none` where who
+wrote a change matters only for what protocol data and the listed paths hold, to save
+the signatures entirely. A swarm whose policy requires signatures
+([`access.md`](access.md), Changes judged on every node) signs what is sent with
+`none` too: every change must arrive vouched for.
+
+Signatures travel with the changes, in the sync messages that carry them, along the
+same paths: a node passes on, for each node's writes, the latest signature it checked,
+and checks one it receives once it holds the change (a signature costs about 30 µs to
+check, and one vouches for its node's changes before it). A message carrying no
+changes carries no signatures. A node that stopped with changes it never sent, nor
+signed, signs them as it starts, before anything leaves.
 The signatures a node has are kept in its document file (`--document-file`) with the
 document.