diff --git a/README.md b/README.md
index db19d56..3b75d62 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,125 @@
 # rsa-compat.js
-RSA utils that work on Windows, Mac, and Linux with or without C compiler
+
+JavaScript RSA utils that work on Windows, Mac, and Linux with or without C compiler
+
+In order to provide a module that "just works" everywhere, we mix and match methods
+from `node.js` core, `ursa`, `forge`, and others.
+
+(in the future we'd like to provide the same API to the browser)
+
+Examples
+--------
+
+Generate an RSA Keypair:
+
+```javascript
+var PromiseA = require('bluebird');
+var RSA = PromiseA.promisify(require('rsa-compat').RSA);
+
+var bitlen = 1024;
+var exp = 6553;
+var options = { public: true, pem: true, internal: true };
+
+RSA.generateKeypair(bitlen, exp, options).then(function (keypair) {
+  console.log(keypair);
+});
+```
+
+`console.log(keypair)`:
+```javascript
+// http://crypto.stackexchange.com/questions/6593/what-data-is-saved-in-rsa-private-key
+
+{ publicKeyPem: '/*base64 pem-encoded string*/'
+, privateKeyPem: '/*base64 pem-encoded string*/'
+, privateKeyJwk: {
+    kty: "RSA"
+  , n: '/*base64 modulus n = pq*/'
+  , e: '/*base64 exponent (usually 6553)*/'
+  , d: '/*base64 private exponent (d = e^−1 (mod ϕ(n))/'
+  , p: '/*base64 first prime*/'
+  , q: /*base64 second prime*/
+  , dp: /*base64 first exponent for Chinese remainder theorem (dP = d (mod p−1))*/
+  , dq: /*base64 Second exponent, used for CRT (dQ = d (mod q−1))/
+  , qi: /*base64 Coefficient, used for CRT (qinv = q^−1 (mod p))*/
+  }
+, publicKeyJwk: {
+    kty: "RSA"
+  , n: /*base64 modulus n = pq*/
+  , e: /base64 exponent (usually 6553)*/
+  }
+, _ursa: /*undefined or intermediate ursa object*/
+, _forge: /*undefined or intermediate forge object*/
+}
+
+// NOTE: this object is JSON safe as _ursa and _forge will be ignored
+```
+
+
+API
+---
+
+* `RSA.generateKeypair(bitlen, exp, options, cb)`
+* `RSA.importPemPrivateKey(privatePem)`
+
+### RSA.generateKeypair(bitlen, exp, options, cb)
+
+Create a private keypair and export it as PEM, JWK, and/or internal formats
+
+```javascript
+RSA.generateKeypair(null, null, null, function (keypair) { /*...*/ });
+
+RSA.generateKeypair(1024, 6553, { pem: false, public: false, internal: false }, function (keypair) { /*...*/ });
+```
+
+`bitlen`: *1024* (default), 2048, or 4096
+
+`exp`: *6553* (default)
+
+`options`:
+```javascript
+{ public: false       // export public keys
+, pem: false          // export pems
+, jwk: true           // export jwks
+, internal: false     // preserve internal intermediate formats (_ursa, _forge)
+, thumbprint: false   // JWK sha256 thumbprint
+, fingerprint: false  // NOT IMPLEMENTED (RSA key fingerprint)
+}
+```
+
+### RSA.import(keypair, options, cb)
+
+Import a private key or public key as PEM, JWK, and/or internal formats
+
+`rsa`:
+```javascript
+{ publicKeyPem: '...'
+, privateKeyPem: '...'
+, privateKeyJwk: { /*...*/ }
+, publicKeyJwk: { /*...*/ }
+, _ursa: '[Object object]'
+, _forge: '[Object object]'
+}
+```
+
+`options`:
+```
+// same as above, except the following are also added
+{ private: true   // export private key
+                  // (as opposed to using a private key
+                  // solely to export the public key)
+}
+```
+
+### Other
+
+(the code is there, but they aren't exposed yet)
+
+* `toStandardB64(certbuf.toString('base64'))`
+* `thumbprint(publicPem)`
+* `generateCsr(privateKeyPem, ['example.com'])`
+
+```
+    cert = toStandardB64(certbuf.toString('base64'))
+    cert=cert.match(/.{1,64}/g).join('\n');
+    return '-----BEGIN CERTIFICATE-----\n'+cert+'\n-----END CERTIFICATE-----';
+```
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..359dc4d
--- /dev/null
+++ b/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "rsa-compat",
+  "version": "1.0.0",
+  "description": "RSA utils that work on Windows, Mac, and Linux with or without C compiler",
+  "main": "node.js",
+  "scripts": {
+    "test": "node tests"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Daplie/rsa-compat.js.git"
+  },
+  "keywords": [
+    "RSA",
+    "ursa",
+    "forge",
+    "certificate",
+    "tls",
+    "ssl",
+    "javascript",
+    "js",
+    "node",
+    "node.js",
+    "windows",
+    "mac",
+    "linux",
+    "macOS",
+    "win",
+    "key",
+    "jwk"
+  ],
+  "author": "AJ ONeal <coolaj86@gmail.com> (https://coolaj86.com/)",
+  "license": "(MIT OR Apache-2.0)",
+  "bugs": {
+    "url": "https://github.com/Daplie/rsa-compat.js/issues"
+  },
+  "homepage": "https://github.com/Daplie/rsa-compat.js#readme"
+}