[doc] Doc improvements

README.md

@@ -5,9 +5,11 @@
 
 ### Data security framework for Clojure
 
-**Tempel** is a lightweight encryption framework that wraps the JVM's native crypto facilities to provide a **high-level Clojure API** that is: idiomatic, simple, and **easy-to-use** even for non-experts.
+**Tempel** is a lightweight encryption *framework* that wraps the JVM's native crypto facilities to provide a **particularly high-level Clojure API** for easily protecting your users' data.
 
-It incorporates **best practices and reasonable defaults** to help simplify many common data security needs.
+More than a collection of crypto utils, Tempel offers a **coherent and opinionated API for secure data management** and is focused on helping you with the [toughest parts](../../wiki/1-Getting-started#challenges) of actually **using encryption in practice**.
+
+Its [tiny API](../../wiki/1-Getting-started#api-overview) and focus on **smart key chains** helps shield you from unnecessary and error-prone complexity, greatly simplifying the most common data security needs.
 
 ## Latest release/s
 
@@ -33,7 +35,7 @@ Note that Tempel is [not intended](../../wiki/3-Faq#can-i-decrypt-tempel-data-wi
 
 ## Roadmap
 
-Tempel has a fixed scope, and is **fully complete**. I'm happy with its design and implementation, and believe it meets all its objectives in its current form. I'm not anticipating significant changes.
+Tempel has a **fixed scope**, and is **fully complete**. I'm happy with its design and implementation, and believe it meets all its objectives in its current form. I'm not anticipating significant changes.
 
 Still, given the sensitivity of the problem domain, I plan to approach Tempel's official stable release as a phased rollout to allow time for feedback before locking things down:
 

wiki/1-Getting-started.md

@@ -71,10 +71,12 @@ Working with encryption can be tough. Some of the most stressful and error-prone
 
 - Understanding **what keys you'll need** (algorithms, parameters, etc.).
 - Understanding how **the various algorithms/schemes fit together** (when and how to use hybrid schemes, etc.).
-- **Managing keys** (keeping algorithms and parameters up-to-date, rotating keys, etc.).
-- Doing all the above without introducing vulnerabilities, and without being dragged into a rat's nest of complexity irrelevant to your application.
+- **Maintaining best-practices over time** (e.g. auto migrating from compromised algorithms, auto incrementing work factors, etc.).
+- **Key management** (key rotation, password resets, admin backups, etc.).
 
-Tempel was designed to try help with each of these.
+Many of these can be **tough to get right** - needing non-trivial understanding, experience, and effort. And getting even one thing wrong can mean **compromised or completely inaccessible data**.
+
+Tempel was designed to try help with each of these, letting you **focus on your application** - not on the rat's nest of becoming a security expert.
 
 ## Keychains
 
@@ -163,14 +165,45 @@ Equality works as you'd expect for `KeyChain`s:
   alice-keychain) ; => true
 ```
 
-## What next
+## API overview
+
+Tempel's API is easy to use, easy to browse, and has extensive beginner-oriented docstrings.  It includes:
+
+### Key chain basics
+
+Function | Use to
+-- | --
+[`keychain`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain) | Create a new `KeyChain`, default opts are reasonable.
+[`keychain-encrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-encrypt) | Encrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
+[`keychain-decrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-decrypt) | Decrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
+
+- `KeyChain`s are the main way you'll interact with the rest of Tempel's API.
+- Deref a `KeyChain` to see its contents.
+- The default `keychain` options will return a `KeyChain` that includes all the keys necessary to fully support Tempel's entire API.
 
-So now that we have one or more `KeyChain`s, what can we do with them?
+### Data protection
 
-See the [examples](./2-Examples) for task-oriented ideas, and/or check the extensive docstrings of Tempel's main API functions:
+Encrypt with | Decrypt with | Use to
+-- | -- | --
+[`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) | [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password) | Encrypt & decrypt data with the same password.
+[`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[].
+[`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt.
+[`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt.
+
+### Misc utils
+
+Function | Use to
+-- | --
+[`public-data`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) | Return any public (unencrypted) data associated with encrypted data.
+[`sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) | Cryptographically sign data with `KeyChain` or key pair.
+[`signed`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-signed) | Cryptographically verify data signed with `sign`.
+[`keychain-add-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-symmetric-key) | Add symmetric key/s to `KeyChain`
+[`keychain-add-asymmetric-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-asymmetric-keypair) | Add asymmetric key pair/s to `KeyChain`
+[`keychain-remove`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-remove) | Remove key/s from `KeyChain`
+[`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority) | Update priority of key/s in `KeyChain`
+
+- Manual key chain management is rarely needed in practice, but useful when you need it!
+
+## What next
 
-- [`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password)
-- [`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key)
-- [`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair)
-- [`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs)
-- [`sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign)
+See the [examples](./2-Examples) for task-oriented ideas!

wiki/2-Examples.md

@@ -226,33 +226,9 @@ Performance tip: when using this approach, make sure to use a random byte[] key
   )
 ```
 
-# Key management
-
-Tempel includes the following utils for basic key management:
-
-- [`keychain-add-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-symmetric-key)
-- [`keychain-add-asymmetric-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-asymmetric-keypair)
-- [`keychain-remove`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-remove)
-- [`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority)
-- [`keychain-normalize-priorities`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-normalize-priorities)
-
-These should cover the most common needs. More advanced key management can quickly become a complex topic and is beyond the scope of Tempel's built-in API or these docs.
-
 # Encryption
 
-Tempel's main API functions are easy to browse, easy to use, and have extensive docstrings:
-
-- Functions to encrypt data begin with `encrypt-`
-- Functions to decrypt data begin with `decrypt-`
-
-A quick overview:
-
-Encrypt with | Decrypt with | Common use
--- | -- | --
-[`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) | [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password) | Encrypt & decrypt data with the same password.
-[`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[].
-[`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt.
-[`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt.
+See [here](./3-Getting-started#data-protection) for an overview of Tempel's data protection API.
 
 ## Symmetric
 
@@ -287,6 +263,7 @@ Using [`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.
 ```
 
 ## Asymmetric
+
 ### Send secret message to user
 
 Example use case: allow users to submit a bug report, ensuring that it's viewable only by the intended recipient (e.g. engineering department).