README.md in acme-client-0.4.1 vs README.md in acme-client-0.5.0

@@ -1,19 +1,20 @@
 # Acme::Client
+
 [![Build Status](https://travis-ci.org/unixcharles/acme-client.svg?branch=master)](https://travis-ci.org/unixcharles/acme-client)
 
 `acme-client` is a client implementation of the [ACME](https://letsencrypt.github.io/acme-spec) protocol in Ruby.
 
 You can find the ACME reference implementations of the [server](https://github.com/letsencrypt/boulder) in Go and the [client](https://github.com/letsencrypt/letsencrypt) in Python.
 
-ACME is part of the [Letsencrypt](https://letsencrypt.org/) project, which goal is to provide free SSL/TLS certificates with  automation of the acquiring and renewal process.
+ACME is part of the [Letsencrypt](https://letsencrypt.org/) project, which goal is to provide free SSL/TLS certificates with automation of the acquiring and renewal process.
 
 ## Installation
 
-Via Rubygems:
+Via RubyGems:
 
-	$ gem install acme-client
+    $ gem install acme-client
 
 Or add it to a Gemfile:
 
 ```ruby
 gem 'acme-client'
@@ -52,10 +53,18 @@
 Before you are able to obtain certificates for your domain, you have to prove that you are in control of it.
 
 ```ruby
 authorization = client.authorize(domain: 'example.org')
 
+# If authorization.status returns 'valid' here you can already get a certificate
+# and _must not_ try to solve another challenge.
+authorization.status # => 'pending'
+
+# You can can store the authorization's URI to fully recover it and
+# any associated challenges via Acme::Client#fetch_authorization.
+authorization.uri # => '...'
+
 # This example is using the http-01 challenge type. Other challenges are dns-01 or tls-sni-01.
 challenge = authorization.http01
 
 # The http-01 method will require you to respond to a HTTP request.
 
@@ -88,16 +97,25 @@
 # Load a saved challenge. This is only required if you need to reuse a saved challenge as outlined above.
 challenge = client.challenge_from_hash(JSON.parse(File.read('challenge')))
 
 # Once you are ready to serve the confirmation request you can proceed.
 challenge.request_verification # => true
-challenge.verify_status # => 'pending'
+challenge.authorization.verify_status # => 'pending'
 
 # Wait a bit for the server to make the request, or just blink. It should be fast.
 sleep(1)
 
-challenge.verify_status # => 'valid'
+# Rely on authorization.verify_status more than on challenge.verify_status,
+# if the former is 'valid' you can already issue a certificate and the status of
+# the challenge is not relevant and in fact may never change from pending.
+challenge.authorization.verify_status # => 'valid'
+challenge.error # => nil
+
+# If authorization.verify_status is 'invalid', you can get at the error
+# message only through the failed challenge.
+authorization.verify_status # => 'invalid'
+authorization.http01.error # => {"type" => "...", "detail" => "..."}
 ```
 
 ### Obtain a certificate
 
 Now that your account is authorized for the domain, you should be able to obtain a certificate for it.
@@ -128,19 +146,18 @@
 ```
 
 # Not implemented
 
 - Recovery methods are not implemented.
-- proofOfPossession-01 is not implemented.
 
 # Requirements
 
 Ruby >= 2.1
 
 ## Development
 
 All the tests use VCR to mock the interaction with the server but if you
-need to record new interation against the server simply clone boulder and
+need to record new interaction against the server simply clone boulder and
 run it normally with `./start.py`.
 
 ## Pull request?
 
 Yes.