update docs

book/src/frost.md

@@ -83,11 +83,34 @@ is still free to start the process with only 2 participants if they wish.
 Signature verification is carried out as normal with single-party signatures,
 along with the signed message and the group verifying key as inputs.
 
+## Repairing
+
+Repairing shares allow participants to help another participant recover their
+share if they have lost it, or also issue a new share to a new participant
+(while keeping the same threshold).
+
+The repair share functionality requires a threshold of participants to work.
+For example, in a 2-of-3 scenario, two participants can help the third recover
+their share, or they could issue a new share to move to a 2-of-4 group.
+
+The functionality works in such a way that each participant running the repair
+share function is not able to obtain the share that is being recovered or
+issued.
+
 ## Refreshing
 
-Refreshing shares starts with a Trusted Dealer who calculated a zero key to
-send to each participant who can then refresh their shares and create a new
-key package.
+Refreshing shares allow participants (or a subset of them) to update their
+shares in a way that maintains the same group public key. Some applications are:
+
+- Make it harder for attackers to compromise the shares. For example, in a
+  2-of-3 threshold scenario, if an attacker steals one participant's device and
+  all participants refresh their shares, the attacker will need to start over
+  and steal two shares instead of just one more.
+- Remove a participant from the group. For example, in a 2-of-3 threshold
+  scenario, if two participants decide to remove the third they can both refresh
+  their shares and the third participant would no longer be able to participate
+  in signing sessions with the others. (They can also then use the repair share
+  functionality to issue a new share and move from 2-of-2 back to 2-of-3.)
 
 ```admonish note
 This is also possible via Distributed Key Generation but this has not yet been

book/src/tutorial/refreshing-shares.md

@@ -6,23 +6,29 @@ channel](https://frost.zfnd.org/terminology.html#peer-to-peer-channel).
 
 <!-- ![Diagram of Refreshing shares, illustrating what is explained in the text](refreshing.png) -->
 
-The Trusted Dealer needs to first run `compute_refreshing_shares` where the new SecretShares are generated and then verified.
-This is done with
-[`KeyPackage::try_from()`](https://docs.rs/frost-core/latest/frost_core/frost/keys/struct.KeyPackage.html#method.try_from):
-`compute_refreshing_shares` returns a new SecretShare and PublicKeyPackage
-Each new `SecretShare` and `PublicKeyPackage` must then be sent via an [**authenticated** and
-**confidential** channel
+The Trusted Dealer needs to first run `compute_refreshing_shares()` which
+returns SecretShares (the "refreshing shares") and a PublicKeyPackage. Each
+`SecretShare` must then be sent along with the `PublicKeyPackage` via an
+[**authenticated** and **confidential** channel
 ](https://frost.zfnd.org/terminology.html#peer-to-peer-channel) for each
-participant, who must verify the package to obtain a `KeyPackage` which contains
-their signing share, verifying share and group verifying key. 
+participant.
 
-Each Participant then runs `refresh_share` to generate a new `KeyPackage`.
+Each Participant then runs `refresh_share()` to generate a new `KeyPackage`
+which will replace their old `KeyPackage`; they must also replace their old
+`PublicKeyPackage` with the one sent by the Trusted Dealer.
 
 ```admonish danger
-The refreshed `KeyPackage` contents must be stored securely and the original 
+The refreshed `KeyPackage` contents must be stored securely and the original
 `KeyPackage` should be deleted. For example:
 
 - Make sure other users in the system can't read it;
 - If possible, use the OS secure storage such that the package
   contents can only be opened with the user's password or biometrics.
 ```
+
+```admonish danger
+Applications should first ensure that all participants who refreshed their
+`KeyPackages` were actually able to do so successfully, before deleting their old
+`KeyPackages`. How this is done is up to the application; it might require
+sucessfully generating a signature with all of those participants.
+```