Docs!

Author: gabriel

README.md

@@ -1,60 +1,81 @@
 ---
-title: keys.pub - Cryptographic key management, sigchains, user identities, signing, encryption
+title: keys.pub - Cryptographic key management, sigchains, user identities, signing, encryption, password manager.
 ---
 
 <img src="./logo.png" width="280"/>
 
-::: warning
-This project is in development and has not been audited. Don't use for anything important yet.
-:::
-
 ## Install
 
-[Download for macOS](https://github.com/keys-pub/app/releases/download/v0.0.31/Keys-0.0.31.dmg)
+[Download for macOS](https://github.com/keys-pub/app/releases/download/v0.0.33/Keys-0.0.33.dmg)
+
+[Download for Windows](https://github.com/keys-pub/app/releases/download/v0.0.33/Keys-0.0.33.msi)
 
-[Download for Windows](https://github.com/keys-pub/app/releases/download/v0.0.31/Keys-0.0.31.msi)
+[Download for Linux](https://github.com/keys-pub/app/releases/download/v0.0.33/Keys-0.0.33.AppImage)
 
 Or the [command line only](/docs/cli/install.md).
 
-## Introduction
+## What is it?
 
-Key management is hard.
+- Manage cryptographic [keys](/docs/specs/keys.md), [sigchains](/docs/specs/sigchain.md) and [user identities](/docs/specs/user.md).
+- [Search for keys](/docs/restapi/user.md#get-user-search), verify and import them.
+- Securely store passwords and secrets.
+- Encrypt, decrypt, sign, verify.
+- Create a secure connection ([Wormhole](/docs/specs/wormhole)) between 2 computers.
+- Most features available in both the app and on the command line.
+- 100% open source ([github.com/keys-pub](https://github.com/keys-pub)) and cross platform (macOS, Windows, Linux).
+- _Coming soon:_ Backup keys/secrets to your private self-hosted storage on S3, GCP, etc.
+- _Coming soon:_ Support for hardware keys.
+- _Coming soon:_ Mobile apps.
 
-keys.pub is an app and service that manages cryptographic keys, sigchains and user identities. It integrates with other frameworks to provide signing and encryption, such as [Saltpack](https://saltpack.org) or [Noise Protocol](https://noiseprotocol.org/).
+<img src="./app-encrypt.jpg"/>
 
-```shell
-> keys pull gabriel@github
-kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c
+<div style="margin-top: -20px; margin-bottom: 20px; font-style: italic; text-align: center">Using the desktop app to encrypt a message from gabriel@github to multiple recipients.</div>
 
-> echo "hi 🤓" | keys encrypt -recipient gabriel@github -armor -stdin -stdout
-BEGIN SALTPACK ENCRYPTED MESSAGE. kcJn5brvybfNjz6 D5ll2Nk0Z2co0as ...
-```
+::: warning
+This project is in development and has not been audited.
+:::
 
-_The above example pulls the public key for the Github user gabriel, verifies it and creates an encrypted message._
+## How does it work?
 
 The default key is a [Ed25519/X25519 key](/docs/specs/keys.md) capable of signing and encryption.
-This key can also be used to create a [sigchain](/docs/specs/sigchain.md) (an ordered sequence of signed statements).
-You can [link a key to an identity](/docs/specs/user.md) (on Github, Twitter, Reddit, etc), by publishing a signed statement to this sigchain.
+
+We can [link this key](/docs/specs/user.md) to your identity on Github, Twitter, Reddit, etc, by creating a signed statement and publishing it both there and on your sigchain. (You can revoke by removing either statement.)
+
+You can [search for keys](/docs/restapi/user.md#get-user-search) by user name and service (e.g. `gabriel@github`, `gabrlh@twitter`), or [lookup a user](/docs/restapi/user.md#get-user-kid) by a key identifier using a [REST API](/docs/restapi-index).
 
 The [Saltpack](https://saltpack.org) format is used for signing and encryption, providing authenticity, repudability and anonymity.
 
-You can [search for keys](/docs/restapi/user.md#get-user-search) by user name and service, or [lookup a user](/docs/restapi/user.md#get-user-kid) by a key identifier using a [REST API](/docs/restapi/).
+The [Noise Protocol](https://noiseprotocol.org/) is used to create a secure connection between two keys.
 
 [Key identifiers](/docs/specs/kid.md) are [Bech32 format](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki), encode the type of key and public key bytes, and include a checksum with error correction.
 
-Your keys are protected by a [keyring](/docs/specs/keyring.md) which is secured by both the OS and a user supplied password (similar to a password manager).
+Your keys and secrets are protected by a [keyring](/docs/specs/keyring.md) which is secured by both the OS and a user supplied password.
+
+The app and command line utility connect to a `keysd` daemon runs as a [gRPC service](/docs/specs/service.md) on your computer.
+
+```shell
+> keys pull gabriel@github
+kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c
+
+> echo "hi 🤓" | keys encrypt -recipient gabriel@github -armor -stdin -stdout
+BEGIN SALTPACK ENCRYPTED MESSAGE. kcJn5brvybfNjz6 D5ll2Nk0Z2co0as ...
+```
 
-The `keysd` daemon runs as a [gRPC service](/docs/specs/service.md) on your computer.
+_The above example pulls the public key for the Github user gabriel, verifies it and creates an encrypted saltpack message._
 
 - [Desktop App](/docs/desktop/install.md)
 - [Command Line](/docs/cli-index.md)
 - [REST API](/docs/restapi-index.md)
 - [Library](/docs/lib-index.md)
 - [Specs](/docs/specs-index.md)
 
-<img src="./app.png"/>
+## What else?
+
+### Go Libraries
+
+All the features in the app is available through Go libraries.
 
-_Using the desktop app to encrypt a message for the Github user gabriel._
+[See some examples](/docs/lib-index.md)
 
 ### Similarities/Differences
 

app-encrypt.jpg

@@ -1,10 +1,10 @@
 # Install
 
-[Download for macOS (0.0.31)](https://github.com/keys-pub/app/releases/download/v0.0.31/Keys-0.0.31.dmg)
+[Download for macOS (0.0.33)](https://github.com/keys-pub/app/releases/download/v0.0.33/Keys-0.0.33.dmg)
 
-[Download for Windows (0.0.31)](https://github.com/keys-pub/app/releases/download/v0.0.31/Keys-0.0.31.msi)
+[Download for Windows (0.0.33)](https://github.com/keys-pub/app/releases/download/v0.0.33/Keys-0.0.33.msi)
 
-_Linux coming soon._
+[Download for Linux (0.0.33)](https://github.com/keys-pub/app/releases/download/v0.0.33/Keys-0.0.33.AppImage)
 
 Or the [command line only](/docs/cli/install.md).
 

app-encrypt.png

@@ -40,5 +40,5 @@ curl -X PUT -d '{".sig":"RZhVfrd6IpHFdUbn3hmxKh0UQpzjdkRPBZHE3Ag8sZHOqGvDG1wfRKZ
 https://keys.pub/sigchain/kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c/1
 ```
 
-It must be a valid signed sigchain statement by the sign key. If it exists already, returns 409 error.
-The max size for the msg is 16KB.
+It must be a valid signed sigchain statement by the specified key. If it exists already, returns 409 error.
+The max size for a signed message is 16KB.

app-keys.png

@@ -9,7 +9,7 @@ The steps are:
 
 1. Generate a user signed statement (saltpack armored) with the name, service and key identifier.
 2. Place the statement on the service at an URL controlled by the account.
-3. Save a signed statement in the key's sigchain including name, service, key identifier and the url from step 2.
+3. Save a signed statement in the key's sigchain ([PUT /sigchain/:kid/:seq](/docs/restapi/sigchain.md#put-sigchain-kid-seq)) including name, service, key identifier and url from step 2.
 
 ## Statement