--- a/README.md	Tue Jul 29 16:52:32 2025 -0400
+++ b/README.md	Tue Jul 29 18:58:27 2025 -0400
@@ -1,24 +1,62 @@
 # 🍳 nonstick
 
-Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust without getting stuck in unsafe code.
+Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust safely.
+Don't worry about getting stuck on unsafe code.
+
+You can use nonstick for interacting with PAM from both sides:
+
+- PAM applications: call into PAM to authenticate users.
+- PAM modules: write a backend that PAM uses for authentication.
+
+It supports all known PAM implementations:
+
+- Linux-PAM, used on most (all?) Linux distributions.
+- OpenPAM, used on most BSDs, including Mac OS.
+- Sun's PAM, used on Solaris and derivatives like Illumos.
+
+Further documentation can be found in the crate's rustdoc.
 
 ## Status
 
-This is currently somewhat incomplete.
+- **Modules**: full support for all calls by PAM into modules.
+  You can use nonstick to implement a PAM module that performs any stage of the PAM lifecycle.
 
-It provides fairly robust functionality for developing PAM modules (i.e., backends that PAM calls to authenticate users or do something similar).
-[Linux-PAM](https://github.com/linux-pam/linux-pam) is the only _tested_ PAM implementation, but it compiles against OpenPAM.
+- **Applications**: supports only a subset of PAM features:
+  
+  - Authentication
+  - Account management
+  - Password change
+  
+  The remaining features (credential and session management) are coming in a future release.
+  (It needs work on a safe and ergonomic API.)
 
-*If you’re looking for a library to implement a PAM client* (i.e., something that authenticates using PAM), consider the [`pam` crate](https://crates.io/crates/pam) for now.
+The overall shape of the API is largely complete and its general shape should not change significantly.
+While there may still be minor source incompatibilities pre-1.0 (e.g., moving methods around), it is unlikely that the library will be radically reworked (and I will try to avoid them unless needed).
+
+## Testing
+
+Nonstick is tested against all supported PAM implementations.
+In addition to doctests and unit tests in the source itself, the (non-public) `testharness` sub-package performs end-to-end tests against the whole authentication process.
 
-APIs are likely to break before v0.1.0, but thereafter should stabilize to an eventual 1.0 release.
-After v0.1.0, the shape of the API should be mostly formed, and most of what happens will be adding new features.
+## Configuration
+
+By default, nonstick uses `libpam-sys` to detect which implementation of PAM it should build against.
+You can also select to build your library or application against a specific PAM implementation by setting the `LIBPAMSYS_IMPL` environment variable.
+See [the documentation for `libpam-sys`](https://docs.rs/libpam-sys/) for more details.
+
+## Cargo features
 
-Goals include:
+- `link` (enabled by default): Link against your system's PAM library.
+  If disabled, you can still use the PAM traits and enum types to build and test your own PAM code independent of your system PAM.
+- `basic-ext` (enabled by default): Include enum values provided by both OpenPAM and Linux-PAM.
+- `linux-pam-ext`: Include features specific to Linux-PAM, including enum values and the ability to send binary messages.
+- `openpam-ext`: Include features specific to OpenPAM (just enum values).
+- `sun-ext`: Include features specific to Sun PAM (just enum values).
 
-- Bindings for PAM clients.
-- Additional PAM features, like environment variables.
-- Way more documentation.
+When `link` is enabled, you can only use the PAM features available on the configured PAM implementation.
+For instance, when building with Linux-PAM, `link` and `openpam-ext` cannot be used together.
+
+However, when `link` is disabled, you could develop and test a crate with `sun-ext` enabled using any device.
 
 ## Credits