update top-level README

1 files changed, 91 insertions, 3 deletions

diff --git a/README.md b/README.md
index 8e881d9..f7bfea3 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,98 @@
 </a>
 </div>
 
-`adenosine`: hobby implementation of atproto.com in Rust
-========================================================
+`adenosine`: enthusiast-grade implementation of atproto.com in Rust
+===================================================================
 
-It doesn't work yet.
+**Status:** it doesn't even work yet and will eat your data
+
+This is a hobby project to implement components of the proposed Bluesky AT
+Protocol ([atproto.com](https://atproto.com)) for federated social media, as
+initially announced in Fall 2022. This might be interesting for other folks to
+take a spin with, but isn't intended to host real content from real people. The
+goal is to think through how the protocol might work by implementing it.
+
+
+## Quickstart (CLI)
+
+To work with an actual PDS server, you will need to get the
+[`bluesky-social/atproto`](https://github.com/bluesky-social/atproto) prototype
+PDS up and running locally. There is a separate
+[quickstart](./notes/atproto_quickstart.md) on how to get that going.
+
+If you run a Debian-base Linux distribution, you might be able to install an
+existing package (TODO: link). Otherwise, you'll need to build the CLI tool
+from source. Install a recent version of the Rust programming language
+toolchain (eg, using [`rustup`](https://rustup.rs/)
+
+The top level workplace includes the GUI and PDS code, which include huge
+dependency trees and are very slow to build. If you just want the CLI, enter
+the `adenosine-cli` directory before running any `cargo` commands.
+
+To build, test, and locally install just the CLI (using `cargo`):
+
+	cd adenosine-cli
+	cargo install
+
+To start interacting with a PDS, set the `ATP_HOST` environment variable. Then
+either register a test account, or create a new session for an existing
+account, and save the JWT token to the `ATP_AUTH_TOKEN`:
+
+	# default port for bluesky-social/atproto implementation
+	export ATP_HOST=http://localhost:2583
+
+	# register a new account
+	adenosine account register -u voltaire.test -p bogus -e voltaire@example.com
+	{
+	  "did": "did:plc:yqtuksvatmmgngd5nkkw75hn",
+	  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE",
+	  "username": "voltaire.test"
+	}
+
+	export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE
+
+	# to clear the auth token env variable
+	unset ATP_AUTH_TOKEN
+
+	# create a new session (login) for existing account
+	adenosine account login -u voltaire.test -p bogus
+	{
+	  "did": "did:plc:yqtuksvatmmgngd5nkkw75hn",
+	  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjQxNX0.j2wcF1g9NxT_1AvYRiplNf_jtK6S81y3L38AkcBwOqY",
+	  "name": "voltaire.test"
+	}
+
+	export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjQxNX0.j2wcF1g9NxT_1AvYRiplNf_jtK6S81y3L38AkcBwOqY
+
+You could save the `ATP_HOST` and `ATP_AUTH_TOKEN` values in `~/.bashrc` so you
+don't need to enter them every time.
+
+Now you can start posting and poking around:
+
+	adenosine bsky post "gruel again for breakfast"
+	{
+	  "cid": "bafyreig2aqlsg4arslck64wbo2hnhe6k2a4z3z2sjfzh3uapv3a4zjld7e",
+	  "uri": "at://did:plc:yqtuksvatmmgngd5nkkw75hn/app.bsky.post/3jg5zkr322c2a"
+	}
+
+
+	adenosine ls at://voltaire.test
+	app.bsky.post
+
+There is a [manpage](./extra/adenosine.1.md) and [CLI-specific
+README](./adenosine-cli/README.md) with more details and examples.
+
+
+## Development
 
 Mininum Supported Rust Version (MSRV) is currently 1.61, using 2021 Rust
 Edition.
+
+Contributions, conversations, bug reports, and handwriten postcards are all
+welcome. As mentioned above this is a low-effort hobby project so high-touch
+support, feature requests, growth strategies, etc, probably will not be
+fielded.
+
+The source code license is AGPLv3. Please acknowledge this in any initial
+contributions, and also indicate whether and how you would like to be
+acknowledged as a contributor (eg, a name and optionally a URL).