update READMEs, start a CHANGELOG

1 files changed, 82 insertions, 34 deletions

diff --git a/adenosine-cli/README.md b/adenosine-cli/README.md
index 6b526e8..c66479d 100644
--- a/adenosine-cli/README.md
+++ b/adenosine-cli/README.md
@@ -17,62 +17,110 @@ This client does not currently do any schema validation of Lexicons, either at
 compile time or runtime (eg, dynamically fetching Lexicons). The Bluesky
 Lexicon (bsky.app) is partially supported with helper commands.
 
+There is a [manpage](../extra/adenosine.1.md) with usage details and examples.
 
-## Example Commands
+Features:
 
-Generic atproto/XRPC commands:
+- [x] generic XRPC invocation (GET and POST)
+- [x] com.atproto Lexicon implementation
+- [x] repo CAR file import/export
+- [x] partial app.bsky Lexicon implementation
+- [ ] complete app.bsky Lexicon implementation
+- [ ] did:plc server interaction and chain validation
+- [ ] pretty printing of bsky records (eg, timeline) with JSON as a flag
+- [ ] test coverage
 
-    # configure host we are talking to
-    export ATP_HOST=http://localhost:2583
+Possible future features:
 
-    # register a new account
-    adenosine account register -u voltaire.test -p bogus -e voltaire@example.com
-    export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOm1qMzVmcmo3Ymd1NmMyd3N6YnRha3QzZSIsImlhdCI6MTY2NjkzNzQxMn0.908LeimAXg1txMMH4k0_IcZAVJaFw1k7pVkScGMNcmE
+- [ ] Lexicon schema validation of records/requests
+- [ ] DID resolution to repo location (independent of PDS)
+- [ ] save login/configuration in homedir dotfile
 
-    # or, login
-    unset ATP_AUTH_TOKEN
-    adenosine account login -u voltaire.test -p bogus
-    export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOm1qMzVmcmo3Ymd1NmMyd3N6YnRha3QzZSIsImlhdCI6MTY2NjkzNzcyMn0.7lXJ9xl6c-hrzUAR9YGLc4iFBn4nOJPbFX8TmYDHgdE
+## Installation
 
-    # check config and setup
-    adenosine status
+`adenosine-cli` is implemented in Rust, and in theory could be distributed in
+binary form for multiple platforms.
+
+TODO: debian packages for linux
+
+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 PDS code, which has a huge dependency tree
+and is slow to build. If you just want the CLI, enter the `adenosine-cli`
+directory before running any `cargo` commands:
+
+	cd adenosine-cli
+	cargo install
 
-    # not implemented server-side (yet?)
-    adenosine account delete
-    adenosine account logout
 
-    # create, list, delete, update some records
-    adenosine create com.example.thing a=123 b=cream
+## Quickstart
 
-    adenosine ls at://hyde.test/app.bsky.post
-    # TODO: bug in serve implementation? says "Could not find user"
+You'll need an actual PDS server to interact with. As of November 2022, this
+could be an independent implementation like `adenosine-pds`, or the more
+official official [`bluesky-social/atproto`](https://github.com/bluesky-social/atproto)
+prototype (see [local atproto dev quickstart](./../notes/atproto_quickstart.md)).
 
-    adenosine delete at://did:plc:mj35frj7bgu6c2wszbtakt3e/app.bsky.post/3jg4dqseut22a
 
-    adenosine describe
+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`:
 
-    adenosine get at://hyde.test/app.bsky.post/asdf
+	# default port for bluesky-social/atproto implementation
+	export ATP_HOST=http://localhost:2583
 
-    adenosine resolve voltaire.test
+	# default port for adenosine-pds implementation
+	export ATP_HOST=http://localhost:3030
 
-    adenosine repo root
+	# 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"
+	}
 
-    adenosine repo root did:plc:mj35frj7bgu6c2wszbtakt3e
+	export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE
 
-    adenosine repo export did:plc:mj35frj7bgu6c2wszbtakt3e > example_repo.car
+	# to clear the auth token env variable in current shell
+	unset ATP_AUTH_TOKEN
 
-    adenosine xrpc get app.bsky.getHomeFeed
+	# 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 status
 
-Example commands in bsky.app Lexicon:
+	adenosine bsky post "gruel again for breakfast"
+	{
+	  "cid": "bafyreig2aqlsg4arslck64wbo2hnhe6k2a4z3z2sjfzh3uapv3a4zjld7e",
+	  "uri": "at://did:plc:yqtuksvatmmgngd5nkkw75hn/app.bsky.post/3jg5zkr322c2a"
+	}
 
-    adenosine bsky feed
+	adenosine ls at://voltaire.test
 
-    adenosine bsky follow did:plc:mj35frj7bgu6c2wszbtakt3e
 
-    adenosine bsky profile
+## Development and Contributions
 
-    adenosine bsky profile voltaire.test
+Minimum Supported Rust Version (MSRV) is currently 1.61, using 2021 Rust
+Edition.
 
-    adenosine get at://did:plc:mj35frj7bgu6c2wszbtakt3e/app.bsky.post/3jg4dqseut22a
+Contributions, conversations, bug reports, and handwriten postcards are all
+welcome. 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).