Improve docs

README.md

@@ -3,18 +3,21 @@
 [![CI](https://github.com/wiktor-k/age-plugin-openpgp-card/actions/workflows/rust.yml/badge.svg)](https://github.com/wiktor-k/age-plugin-openpgp-card/actions/workflows/rust.yml)
 [![Crates.io](https://img.shields.io/crates/v/age-plugin-openpgp-card)](https://crates.io/crates/age-plugin-openpgp-card)
 
-This age plugin allows you to reuse your OpenPGP Card devices (such as Yubikeys or Nitrokeys) for [age decryption](https://age-encryption.org/).
+This age plugin lets you reuse your OpenPGP Card devices (such as [Yubikeys](https://www.yubico.com/products/yubikey-5-overview/) or [Nitrokeys](https://www.nitrokey.com/products/nitrokeys)) for [age decryption](https://age-encryption.org/).
 
-Why? [OpenPGP Card](https://en.wikipedia.org/wiki/OpenPGP_card), contrary to its name, is just a generic cryptographic device but most importantly the spec and the real-world devices (e.g. Yubikeys) in the wild [support ed25519](https://docs.yubico.com/hardware/yubikey/yk-tech-manual/yk5-apps.html#elliptic-curve-cryptographic-ecc-algorithms).
+Why? [OpenPGP Card](https://en.wikipedia.org/wiki/OpenPGP_card), contrary to its name, is just a generic cryptographic device standard.
+Most importantly the specification and the real-world devices (e.g. [Yubikeys](https://docs.yubico.com/hardware/yubikey/yk-tech-manual/yk5-apps.html#elliptic-curve-cryptographic-ecc-algorithms) and [Nitrokeys](https://docs.nitrokey.com/nitrokey3/faq#which-algorithms-and-maximum-key-length-are-supported)) support ed25519.
 
-If you don't need ed25519 [`age-plugin-yubikey`](https://github.com/str4d/age-plugin-yubikey) provides a more polished experience.
+This application is a no-moving-parts solution which requires only [`pcsc-lite`](https://github.com/LudovicRousseau/PCSC) on Linux and reuses built-in smartcard services on Windows and MacOS. No GnuPG needed, no other OpenPGP software is used or accessed.
+
+If you don't need ed25519 and are using Yubikeys then the [`age-plugin-yubikey`](https://github.com/str4d/age-plugin-yubikey) provides a more polished experience.
 
 This plugin assumes that you have already provisioned the card.
 [`oct admin generate`](https://codeberg.org/openpgp-card/openpgp-card-tools/#generate-keys-on-the-card) may be used to provision the card with a new ed25519 key.
 
 ## Usage
 
-Running the tool directly outputs public keys and identity stubs for all connected cards:
+Running the tool directly outputs the public keys and the identity stubs for all connected cards:
 
 ```sh
 $ age-plugin-openpgp-card | tee identity.txt
@@ -25,21 +28,22 @@ AGE-PLUGIN-OPENPGP-CARD-1XQCRQD36XY6NGV3JXSMRWAN88PC
 
 Note that the public key looks like a regular age ed25519 key.
 The stub encodes the card identifier and is mostly irrelevant.
+If the stub is lost it may be regenerated - if the key on the card is the same the decryption will succeed.
 
 Any age-compatible tool can be used for encryption:
 
 ```sh
-$ echo I like strawberries | rage -r age1dkfzfyk58yvkf07n32nygkyuqxtnq2am427sy79gjkh6krf96frsucn0me -a > encrypted.age
+$ echo I like strawberries | age -r age1dkfzfyk58yvkf07n32nygkyuqxtnq2am427sy79gjkh6krf96frsucn0me -a > encrypted.age
 ```
 
 And the identity stubs are required for decryption:
 
 ```sh
-$ rage -d -i identity.txt < encrypted.age
+$ age -d -i identity.txt < encrypted.age
 I like strawberries
 ```
 
-The plugin will ask you for the PIN using built-in plugin protocol (this would usually show a pin-entry prompt).
+The plugin will ask you for the PIN using built-in plugin protocol (e.g. [`rage`](https://github.com/str4d/rage) would show a pin-entry prompt).
 
 ## License
 
@@ -52,7 +56,4 @@ at your option.
 
 ### Contribution
 
-Unless you explicitly state otherwise, any contribution intentionally
-submitted for inclusion in this crate by you, as defined in the
-Apache-2.0 license, shall be dual licensed as above, without any
-additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.