diff --git a/README.md b/README.md
index 40c97ce..b8df043 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,11 @@
-# DidKit
+# DIDKit
 
 A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol
 
 
 ## What does it do
 
-**TODO** - not much yet :)
-
-See the [did.rb](https://github.com/mackuba/didkit/blob/master/lib/didkit/did.rb) file for now.
+Accounts on Bluesky use identifiers like [did:plc:oio4hkxaop4ao4wz2pp3f4cr](https://plc.directory/did:plc:oio4hkxaop4ao4wz2pp3f4cr) as unique IDs, and they also have assigned human-readable handles like [@mackuba.eu](https://bsky.app/profile/mackuba.eu), which are verified either through a DNS TXT entry or a `/.well-known/atproto-did` file. This library allows you to look up any account's assigned handle using a DID string or vice versa, load the account's DID JSON document that specifies the handles and the PDS server hosting user's repo, and check if the assigned handle verifies correctly.
 
 
 ## Installation
@@ -15,8 +13,54 @@ See the [did.rb](https://github.com/mackuba/didkit/blob/master/lib/didkit/did.rb
     gem install didkit
 
 
+## Usage
+
+Use the `DIDKit::Resolver` class to look up DIDs and handles.
+
+To look up a handle:
+
+```rb
+resolver = DIDKit::Resolver.new
+resolver.resolve_handle('nytimes.com')
+ # => #<DIDKit::DID:0x00000001035956b0 @did="did:plc:eclio37ymobqex2ncko63h4r", @type=:plc, @resolved_by=:dns>
+```
+
+This returns an object of `DIDKit::DID` class (aliased as just `DID`), which tells you:
+
+- the DID as a string (`#to_s` or `#did`)
+- the DID type (`#type`, `:plc` or `:web`)
+- whether the handle was resolved via a DNS entry or a `.well-known` file (`#resolved_by`, `:dns` or `:http`)
+
+To go in the other direction - to find an assigned and verified handle given a DID - use `get_validated_handle` (pass DID as a string or an object)
+
+```rb
+resolver.get_validated_handle('did:plc:ewvi7nxzyoun6zhxrhs64oiz')
+ # => "atproto.com" 
+```
+
+You can also load the DID document using `resolve_did` (or `DID#get_document`):
+
+```rb
+doc = resolver.resolve_did('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
+ # => #<DIDKit::Document:0x0000000105d751f8 @did=#<DIDKit::DID:...>, @json={...}>
+doc.handles
+ # => ["pfrazee.com"] 
+doc.pds_endpoint
+ # => "https://morel.us-east.host.bsky.network" 
+```
+
+
+### Configuration
+
+You can override the nameserver used for DNS lookups by setting the `nameserver` property in `Resolver`, e.g. to use Google's or CloudFlare's global DNS:
+
+```
+resolver.nameserver = '8.8.8.8'
+```
+
+
 ## Credits
 
-Copyright © 2023 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
+Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
 
 The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).