diff --git a/README.md b/README.md
index 402924a..8320066 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,81 @@
# curve25519-dalek [](https://crates.io/crates/curve25519-dalek) [](https://docs.rs/curve25519-dalek) [](https://travis-ci.org/dalek-cryptography/curve25519-dalek)
-**A low-level cryptographic library for point, group, field, and scalar
-operations on a curve isomorphic to the twisted Edwards curve defined by -x²+y²
-= 1 - 121665/121666 x²y² over GF(2²⁵⁵ - 19).**
+**A pure-Rust implementation of group operations on Ristretto and Curve25519.**
+
+`curve25519-dalek` is a library providing group operations on the Edwards and
+Montgomery forms of Curve25519, and on the prime-order Ristretto group.
+
+`curve25519-dalek` is not intended to provide implementations of any particular
+crypto protocol. Rather, implementations of those protocols (such as
+[`x25519-dalek`][x25519-dalek] and [`ed25519-dalek`][ed25519-dalek]) should use
+`curve25519-dalek` as a library.
+
+`curve25519-dalek` is intended to provide a clean and safe _mid-level_ API for use
+implementing a wide range of ECC-based crypto protocols, such as key agreement,
+signatures, anonymous credentials, rangeproofs, and zero-knowledge proof
+systems.
+
+## WARNING
+
+We do not yet consider this code to be production-ready. We intend to
+stabilize a production-ready version `1.0` soon.
+
+# Documentation
+
+The semver-stable, public-facing `curve25519-dalek` API is documented
+[here][docs-external]. In addition, the unstable internal implementation
+details are documented [here][docs-internal].
+
+The `curve25519-dalek` documentation requires a custom HTML header to include
+KaTeX for math support. Unfortunately `cargo doc` does not currently support
+this, but docs can be built using
+```sh
+make doc
+make doc-internal
+```
+
+# Use
+
+To import `curve25519-dalek`, add the following to the dependencies section of
+your project's `Cargo.toml`:
+```toml
+curve25519-dalek = "^0.14"
+```
+Then import the crate as:
+```rust,no_run
+extern crate curve25519_dalek;
+```
+
+# Backends and Features
+
+Curve arithmetic is implemented using one of the following backends:
+
+* a `u32` backend using `u64` products;
+* a `u64` backend using `u128` products, available using the `nightly` feature;
+* an experimental AVX2 backend, available using the `yolocrypto` feature when compiling for a target with `target_feature=+avx2`
+
+By default, the benchmarks are not compiled without the `bench`
+feature. Benchmarks can be run via:
+
+```sh
+cargo bench --features="bench" # u32 backend
+cargo bench --features="bench nightly" # u64 backend
+cargo bench --features="bench nightly yolocrypto" # u64 or avx2 if available
+```
+
+# Contributing
+
+Please see [CONTRIBUTING.md][contributing].
+
+Patches and pull requests should be make against the `develop`
+branch, **not** `master`.
+
+# About
**SPOILER ALERT:** *The Twelfth Doctor's first encounter with the Daleks is in
his second full episode, "Into the Dalek". A beleaguered ship of the "Combined
@@ -23,65 +91,16 @@ universe's beauty, but also his deep hatred of the Daleks. Rusty destroys the
other Daleks and departs the ship, determined to track down and bring an end
to the Dalek race.*
-Significant portions of this code are ported from [Adam Langley's
-Golang ed25519 library](https://github.com/agl/ed25519), which is in
+`curve25519-dalek` is authored by Isis Agora Lovecruft and Henry de Valence.
+
+Portions of this library were originally a port of [Adam Langley's
+Golang ed25519 library](https://github.com/agl/ed25519), which was in
turn a port of the reference `ref10` implementation.
-## Warning
+The fast `u32` and `u64` scalar arithmetic was implemented by Andrew Moon, and
+the addition chain for scalar inversion was provided by Brian Smith. The
+`no_std` support was contributed by Tony Arcieri.
-This code has **not** yet received sufficient peer review by other qualified
-cryptographers to be considered in any way, shape, or form, safe. Further,
-this library does **not** provide high-level routines such as encryption and
-decryption or signing and verification. Instead, it is a low-level library,
-intended for other cryptographers who would like to implement their own
-primitives using this curve. (For an example of how one would implement a
-signature scheme using this library, see
-[ed25519-dalek](https://github.com/dalek-cryptography/ed25519-dalek).)
-
-**USE AT YOUR OWN RISK**
-
-## Documentation
-
-Extensive documentation is available [here](https://docs.rs/curve25519-dalek).
-
-# Installation
-
-To install, add the following to the dependencies section of your project's
-`Cargo.toml`:
-
-```toml
-curve25519-dalek = "^0.14"
-```
-
-Then, in your library or executable source, add:
-
- extern crate curve25519_dalek;
-
-## Features
-
-On nightly Rust, using the `nightly` feature enables a radix-51 field
-arithmetic implementation using `u128`s, which is approximately twice as
-fast. It will also enable additional developer documentation when
-compiling via `make doc-internal`.
-
-By default, the benchmarks are not compiled without the `bench`
-feature. To run the benchmarks, do:
-
-```sh
-cargo bench --features="bench"
-```
-
-## TODO
-
-We intend to stabilise the following before curve25519-dalek-1.0.0:
-
-* Implement hashing to a point on the curve (Elligator).
-* Finish Ristretto documentation.
-
-## Contributing
-
-Please see
-[CONTRIBUTING.md](https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md).
-
-Patches and pull requests should be make against the `develop`
-branch, **not** `master`.
+[ed25519-dalek]: https://github.com/dalek-cryptography/ed25519-dalek
+[x25519-dalek]: https://github.com/dalek-cryptography/x25519-dalek
+[contributing]: https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md
diff --git a/src/lib.rs b/src/lib.rs
index 0baf368..c4f5d68 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -9,29 +9,21 @@
// - Henry de Valence
#![cfg_attr(not(feature = "std"), no_std)]
+
#![cfg_attr(feature = "alloc", feature(alloc))]
-#![cfg_attr(feature = "nightly", feature(i128_type))]
-#![cfg_attr(feature = "nightly", feature(cfg_target_feature))]
#![cfg_attr(feature = "bench", feature(test))]
-#![deny(missing_docs)] // refuse to compile if documentation is missing
+#![cfg_attr(feature = "nightly", feature(i128_type))]
+#![cfg_attr(feature = "nightly", feature(cfg_target_feature))]
+#![cfg_attr(feature = "nightly", feature(external_doc))]
-//! # curve25519-dalek
-//!
-//! **A high-performance, pure-Rust implementation of group operations for Ristretto and Curve25519.**
-//!
-//! **[SPOILER ALERT]** The Twelfth Doctor's first encounter with the Daleks is
-//! in his second full episode, "Into the Dalek". A beleaguered ship of the
-//! "Combined Galactic Resistance" has discovered a broken Dalek that has
-//! turned "good", desiring to kill all other Daleks. The Doctor, Clara and a
-//! team of soldiers are miniaturized and enter the Dalek, which the Doctor
-//! names Rusty. They repair the damage, but accidentally restore it to its
-//! original nature, causing it to go on the rampage and alert the Dalek fleet
-//! to the whereabouts of the rebel ship. However, the Doctor manages to
-//! return Rusty to its previous state by linking his mind with the Dalek's:
-//! Rusty shares the Doctor's view of the universe's beauty, but also his deep
-//! hatred of the Daleks. Rusty destroys the other Daleks and departs the
-//! ship, determined to track down and bring an end to the Dalek race.
+// Refuse to compile if documentation is missing, but only on nightly.
+//
+// This means that missing docs will still fail CI, but means we can use
+// README.md as the crate documentation.
+#![cfg_attr(feature = "nightly", deny(missing_docs))]
+
+#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
//------------------------------------------------------------------------
// External dependencies: