README, keyfork-user-guide: improve docs on keyfork-shard

README.md

@@ -108,6 +108,9 @@ To follow these steps please install [git-lfs][gl] and [git-sig][gs].
 
 ## Usage
 
+Usage instructions can be found in the `keyfork-user-guide` mdBook.
+
+<!--
 ```
 keyfork generate [-c,--config=<file>]
     Generate new mnemonic optionally public keys defined by config
@@ -186,3 +189,4 @@ $ keyfork bip44 --path=bitcoin
 
 > m/44'/0'/0'/0/0: 12DefCMhYVv4sBQikyXKMciAoX2wgzhWqb
 ```
+-->

keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md

@@ -4,12 +4,10 @@ Combine `threshold` shares into a previously [`split`] secret.
 
 ## Arguments
 
-`keyfork-shard-combine-openpgp threshold key_discovery`
+`keyfork-shard-combine-openpgp [key_discovery]`
 
-* `threshold`: Minimum number of operators present to recover the secret, as
-  previously configured when creating the secret
 * `key_discovery`: A directory containing OpenPGP keys.
-  If the amount of keys found is less than `threshold`, an OpenPGP Card
+  If the number of keys found is less than `threshold`, an OpenPGP Card
   fallback will be used to decrypt the rest of the messages.
 
 ## Pinentry
@@ -27,4 +25,14 @@ OpenPGP messages from [`split`].
 
 Hex-encoded secret.
 
+## Example
+
+```sh
+# Decrypt using only smartcards
+keyfork-shard-combine-openpgp < shard.pgp
+
+# Decrypt using on-disk private keys
+keyfork-shard-combine-openpgp key_discovery.pgp < shard.pgp
+```
+
 [`split`]: ./split.md

keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md

@@ -31,3 +31,13 @@ OpenPGP ASCII armored message containing several sequential encrypted messages.
 **Note:** While it is possible to decrypt some of the messages using a tool
 like GnuPG or Sequoia, it is not recommended to handle these messages using
 tooling outside of Keyfork Shard.
+
+## Example
+
+```sh
+# Export PGP keys to key discovery file
+gpg --export 88823A75ECAA786B0FF38B148E401478A3FBEF72 F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D > key_discovery.pgp
+
+# Generate a secret and split
+keyfork-entropy | keyfork-shard-split-openpgp 1 2 key_discovery.pgp > shard.pgp
+```

keyfork-user-guide/src/bin/keyfork/shard/index.md

@@ -50,15 +50,24 @@ key.
 
 The output of the command is dependent on the format.
 
+### Example
+
+```sh
+# Export PGP keys of shard holders to key discovery file
+gpg --export 88823A75ECAA786B0FF38B148E401478A3FBEF72 F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D > key_discovery.pgp
+
+# Generate and split a secret
+keyfork-entropy | keyfork shard split --format openpgp --threshold 1 --max 2 key_discovery.pgp > shard.pgp
+```
+
 ## `keyfork shard combine`
 
 Combine `threshold` shares into a secret.
 
 ### Arguments
 
-`keyfork shard combine --threshold=threshold [key_discovery]`
+`keyfork shard combine [key_discovery]`
 
-* `threshold`: Mini mum number of operators present to recover the secret
 * `key_discovery`: Either a file or a directory containing public keys.
   If a file, load all private keys from a file.
   If a directory, for every file in the directory (non-recursively), load
@@ -74,3 +83,13 @@ same as the output from the `split` command previously used.
 ### Output
 
 Hex-encoded secret.
+
+### Example
+
+```sh
+# Decrypt using only smartcards
+keyfork shard combine --format openpgp < shard.pgp | keyfork-mnemonic-from-seed
+
+# Decrypt using on-disk private keys
+keyfork shard combine --format openpgp key_discovery.pgp < shard.pgp | keyfork-mnemonic-from-seed
+```