documentation: updates in advance of release

Signed-off-by: Nick Gerakines <[e-mail]>

README.md

···
-# atproto-identity-rs
+# AT Protocol Identity Rust Components
 
-A comprehensive collection of Rust crates for building AT Protocol applications. This workspace provides identity management, record operations, OAuth 2.0 flows, HTTP client operations, XRPC services, and event streaming capabilities.
+A comprehensive collection of Rust components for creating AT Protocol applications. This workspace provides essential building blocks for identity management, record operations, OAuth 2.0 authentication flows, HTTP client operations, XRPC services, and real-time event streaming.
 
-**Note**: This project contains components extracted from the open-source [smokesignal.events](https://tangled.sh/@smokesignal.events/smokesignal) project, an AT Protocol event and RSVP management application. This library is released under the MIT license.
+**Origin**: Parts of this project were extracted from the open-source [smokesignal.events](https://tangled.sh/@smokesignal.events/smokesignal) project, an AT Protocol event and RSVP management application. This library is released under the MIT license to enable broader AT Protocol ecosystem development.
 
 ## Components
 
-### Core Libraries
+This workspace contains 9 specialized crates that work together to provide complete AT Protocol application development capabilities:
 
-- **[`atproto-identity`](crates/atproto-identity/)** - Identity management with DID resolution and cryptographic operations. Includes 4 CLI tools for identity resolution, key management, signing, and validation.
-- **[`atproto-record`](crates/atproto-record/)** - AT Protocol record signature operations. Includes 2 CLI tools for signing and verifying records.
-- **[`atproto-oauth`](crates/atproto-oauth/)** - OAuth 2.0 implementation with AT Protocol security extensions including PKCE, DPoP, and JWT operations.
-- **[`atproto-oauth-aip`](crates/atproto-oauth-aip/)** - AT Protocol Identity Provider (AIP) OAuth workflow implementation for client applications.
-- **[`atproto-client`](crates/atproto-client/)** - HTTP client with DPoP authentication and repository operations. Includes 3 CLI tools for client authentication testing.
+### Identity & Cryptography
+
+- **[`atproto-identity`](crates/atproto-identity/)** - Core identity management with multi-method DID resolution (plc, web, key), DNS/HTTP handle resolution, and P-256/P-384/K-256 cryptographic operations. *Includes 4 CLI tools.*
+- **[`atproto-record`](crates/atproto-record/)** - Cryptographic signature operations for AT Protocol records using IPLD DAG-CBOR serialization with AT-URI parsing support. *Includes 2 CLI tools.*
+
+### Authentication & Authorization  
+
+- **[`atproto-oauth`](crates/atproto-oauth/)** - Complete OAuth 2.0 implementation with AT Protocol security extensions including DPoP (RFC 9449), PKCE (RFC 7636), JWT operations, and secure storage abstractions.
+- **[`atproto-oauth-aip`](crates/atproto-oauth-aip/)** - OAuth AIP (Identity Provider) implementation providing complete authorization code flow with PAR, token exchange, and AT Protocol session management.
+- **[`atproto-oauth-axum`](crates/atproto-oauth-axum/)** - Production-ready Axum web handlers for OAuth endpoints including authorization callbacks, JWKS endpoints, and client metadata. *Includes 1 CLI tool.*
 
-### Web Framework Integration
+### Client & Service Development
 
-- **[`atproto-oauth-axum`](crates/atproto-oauth-axum/)** - Axum web handlers for OAuth endpoints. Includes 1 CLI tool for OAuth client testing.
-- **[`atproto-xrpcs`](crates/atproto-xrpcs/)** - XRPC service components with JWT authorization extractors.
-- **[`atproto-xrpcs-helloworld`](crates/atproto-xrpcs-helloworld/)** - Example XRPC service implementation with DID web support.
+- **[`atproto-client`](crates/atproto-client/)** - HTTP client library supporting multiple authentication methods (DPoP, Bearer tokens, sessions) with native XRPC protocol operations and repository management. *Includes 3 CLI tools.*
+- **[`atproto-xrpcs`](crates/atproto-xrpcs/)** - XRPC service framework providing JWT authorization extractors, DID resolution integration, and Axum middleware for building AT Protocol services.
+- **[`atproto-xrpcs-helloworld`](crates/atproto-xrpcs-helloworld/)** - Complete example XRPC service demonstrating DID:web identity, service document generation, and JWT authentication patterns. *Includes 1 service binary.*
 
-### Event Streaming
+### Real-time Event Processing
 
-- **[`atproto-jetstream`](crates/atproto-jetstream/)** - WebSocket event stream consumer with compression support. Includes 1 CLI tool for event consumption.
+- **[`atproto-jetstream`](crates/atproto-jetstream/)** - WebSocket consumer for AT Protocol Jetstream events with Zstandard compression, automatic reconnection, and configurable event filtering. *Includes 1 CLI tool.*
 
 ## Quick Start
 
···
 
 ## Command Line Tools
 
-The workspace includes 12 command-line tools across the crates. All CLI tools require the `clap` feature:
+The workspace includes 11 command-line tools across multiple crates, providing ready-to-use utilities for AT Protocol development and testing. All CLI tools require the `clap` feature:
 
 ```bash
 # Build with CLI support
···
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
+## Architecture
+
+These components are designed to work together as building blocks for AT Protocol applications:
+
+- **Identity Layer**: `atproto-identity` provides the foundation for DID resolution and cryptographic operations
+- **Authentication Layer**: `atproto-oauth*` crates handle complete OAuth 2.0 flows with AT Protocol security extensions
+- **Application Layer**: `atproto-client` and `atproto-xrpcs*` enable client applications and service development
+- **Data Layer**: `atproto-record` handles record signing and verification with proper IPLD serialization
+- **Event Layer**: `atproto-jetstream` provides real-time event processing capabilities
+
+## Use Cases
+
+This workspace enables development of:
+
+- **AT Protocol Identity Providers (AIPs)** - Complete OAuth servers with DID-based authentication
+- **Personal Data Servers (PDS)** - XRPC services with JWT authorization and repository management
+- **AT Protocol Clients** - Applications that authenticate and interact with AT Protocol services
+- **Event Processing Systems** - Real-time processors for AT Protocol repository events
+- **Development Tools** - CLI utilities for testing, debugging, and managing AT Protocol identities
+
+## Contributing
+
+Contributions are welcome! This project follows standard Rust development practices:
+
+1. Fork this repository
+2. Create a feature branch
+3. Run tests: `cargo test`
+4. Run linting: `cargo fmt && cargo clippy`
+5. Submit a pull request
+
 ## Acknowledgments
 
-This library was extracted from the [smokesignal.events](https://tangled.sh/@smokesignal.events/smokesignal) project, an open-source AT Protocol event and RSVP management application.
+Parts of this project were extracted from the [smokesignal.events](https://tangled.sh/@smokesignal.events/smokesignal) project, an open-source AT Protocol event and RSVP management application. This extraction enables broader community use and contribution to AT Protocol tooling in Rust.

crates/atproto-client/README.md

···
 # atproto-client
 
-HTTP client library for AT Protocol services with DPoP authentication support.
+AT Protocol HTTP client with authentication support.
 
 ## Overview
 
-`atproto-client` provides HTTP client functionality specifically designed for interacting with AT Protocol endpoints. This library handles both basic HTTP operations and DPoP-authenticated requests required for secure AT Protocol communication.
+HTTP client for AT Protocol services supporting DPoP, bearer tokens, and sessions with native XRPC protocol operations and repository management.
 
-## Binaries
+## Features
 
-All CLI tools require the `clap` feature:
+- **Multiple authentication methods**: DPoP, Bearer tokens, and session-based authentication
+- **XRPC protocol support**: Native support for AT Protocol's XRPC communication protocol
+- **Repository operations**: Complete client for AT Protocol repository CRUD operations
+- **Session management**: Authentication session creation, refresh, and validation
+- **URL utilities**: Helper functions for AT Protocol URL construction and validation
 
-- **atproto-client-auth**: Create and refresh authentication sessions with AT Protocol services using identifier and password
-- **atproto-client-app-password**: Make authenticated XRPC calls using application-specific Bearer tokens and app passwords  
-- **atproto-client-dpop**: Make authenticated XRPC calls using DPoP (Demonstration of Proof-of-Possession) tokens for enhanced security
+## CLI Tools
+
+The following command-line tools are available when built with the `clap` feature:
+
+- **`atproto-client-auth`**: Create and refresh authentication sessions using identifier and password
+- **`atproto-client-app-password`**: Make authenticated XRPC calls using app password Bearer tokens
+- **`atproto-client-dpop`**: Make authenticated XRPC calls using DPoP (Demonstration of Proof-of-Possession) tokens
 
 ## Usage
 

crates/atproto-client/src/client.rs

···
 //! HTTP client operations with DPoP authentication support.
 //!
-//! Provides authenticated and unauthenticated HTTP request functions for JSON APIs,
-//! with support for DPoP (Demonstration of Proof-of-Possession) authentication.
+//! Authenticated and unauthenticated HTTP requests for JSON APIs
+//! with DPoP (Demonstration of Proof-of-Possession) support.
 
 use crate::errors::{ClientError, DPoPError};
 use anyhow::Result;

crates/atproto-client/src/com_atproto_repo.rs

···
-//! AT Protocol repository operations for record management.
-//!
-//! This module provides client functions for interacting with AT Protocol repository endpoints,
-//! including CRUD operations for records with DPoP authentication. Supports the `com.atproto.repo`
-//! XRPC methods for managing user data in AT Protocol repositories.
-//!
-//! ## Operations
+//! AT Protocol repository operations.
 //!
-//! - **`get_record()`**: Retrieve a specific record by repository, collection, and key
-//! - **`list_records()`**: List records in a collection with pagination support
+//! Client functions for com.atproto.repo XRPC methods including
+//! record CRUD operations with DPoP authentication support.
 //! - **`create_record()`**: Create a new record in a repository
 //! - **`put_record()`**: Update or create a record with a specific key
 //! - **`delete_record()`**: Delete a record from a repository

crates/atproto-client/src/com_atproto_server.rs

···
-//! AT Protocol server operations for session management.
-//!
-//! This module provides client functions for interacting with AT Protocol server endpoints,
-//! including session creation and refresh operations using app passwords. Supports the
-//! `com.atproto.server` XRPC methods for authentication and session management.
-//!
-//! ## Operations
+//! AT Protocol server authentication operations.
 //!
-//! - **`create_session()`**: Create a new authentication session with app password
-//! - **`refresh_session()`**: Refresh an existing authentication session
+//! Client functions for com.atproto.server XRPC methods including
+//! session creation and refresh with app password authentication.
 //! - **`create_app_password()`**: Create a new app password for authenticated account
 //!
 //! ## Request/Response Types

crates/atproto-client/src/lib.rs

···
-//! # AT Protocol HTTP Client Library
-//!
-//! Comprehensive HTTP client library for AT Protocol services with support for multiple
-//! authentication methods and XRPC protocol operations. Provides both low-level HTTP
-//! client functionality and high-level AT Protocol specific operations.
-//!
-//! ## Key Features
-//!
-//! - **Multiple Authentication Methods**: DPoP, Bearer tokens, and session-based authentication
-//! - **XRPC Protocol Support**: Native support for AT Protocol's XRPC communication protocol
-//! - **Repository Operations**: Complete client for AT Protocol repository operations
-//! - **Session Management**: Authentication session creation, refresh, and validation
-//! - **Error Handling**: Structured error types with detailed context for debugging
-//! - **URL Utilities**: Helper functions for AT Protocol URL construction and validation
+//! AT Protocol HTTP client with authentication support.
 //!
-//! ## Architecture
-//!
-//! The library provides both raw HTTP client capabilities and AT Protocol specific abstractions:
-//!
-//! - **`client`**: Core HTTP client with authentication middleware support
+//! HTTP client for AT Protocol services supporting DPoP, bearer tokens, and sessions
+//! with native XRPC protocol operations and repository management.
 //! - **`url`**: URL construction and validation utilities for AT Protocol endpoints
 //! - **`com::atproto::repo`**: Repository operations for record management
 //! - **`com::atproto::server`**: Server operations for authentication and session management

crates/atproto-client/src/url.rs

···
-//! URL construction utilities for building HTTP endpoints.
+//! URL construction utilities for HTTP endpoints.
 //!
-//! Provides flexible URL building with parameter encoding and query string generation
-//! for constructing well-formed HTTP request URLs.
+//! Build well-formed HTTP request URLs with parameter encoding
+//! and query string generation.
 
 /// A single query parameter as a key-value pair.
 pub type QueryParam<'a> = (&'a str, &'a str);

crates/atproto-identity/README.md

···
 # atproto-identity
 
-Comprehensive Rust library for AT Protocol identity management with DID resolution, handle resolution, and cryptographic key operations.
+AT Protocol identity management for DID resolution, handle resolution, and cryptographic operations.
 
 ## Overview
 
-`atproto-identity` provides full functionality for DID resolution, handle resolution, and identity document management across multiple DID methods. This library supports complete AT Protocol identity workflows including DNS/HTTP resolution, DID document caching, cryptographic operations, and structured error handling.
+Core identity functionality for AT Protocol applications including multi-method DID resolution (plc, web, key), DNS/HTTP handle resolution, and P-256/P-384/K-256 key operations.
 
 ## Features
 
-- **Multi-method DID resolution**: Support for `did:plc` and `did:web` methods
-- **Handle resolution**: DNS TXT record and HTTP `.well-known` endpoint resolution
-- **Cryptographic operations**: P-256, P-384, and K-256 elliptic curve support
-- **Identity validation**: Input validation for handles and DIDs
-- **Document storage**: LRU cache-based DID document storage
-- **Configuration management**: Environment variable and DNS configuration
-- **CLI tools**: Command-line utilities for identity operations (requires `clap` feature)
+- **Multi-method DID resolution**: Support for `did:plc`, `did:web`, and `did:key` methods
+- **Handle resolution**: DNS TXT record and HTTP `.well-known` endpoint resolution with conflict detection
+- **Cryptographic operations**: P-256, P-384, and K-256 elliptic curve key generation, signing, and validation
+- **Identity validation**: Input validation for handles and DIDs following AT Protocol specifications
+- **Document storage**: LRU cache-based DID document storage with pluggable backends
+- **Configuration management**: Environment variable handling and DNS nameserver configuration
 
-## Binaries
+## CLI Tools
 
-All CLI tools require the `clap` feature and use consistent command-line argument processing:
+The following command-line tools are available when built with the `clap` and `hickory-dns` features:
 
-- **atproto-identity-resolve**: Resolve AT Protocol handles and DIDs to canonical identifiers
-- **atproto-identity-key**: Generate and manage cryptographic keys (P-256, P-384, K-256)
-- **atproto-identity-sign**: Create cryptographic signatures of JSON data
-- **atproto-identity-validate**: Validate cryptographic signatures
+- **`atproto-identity-resolve`**: Resolve AT Protocol handles and DIDs to canonical identifiers with optional DID document output
+- **`atproto-identity-key`**: Generate cryptographic keys for P-256, P-384, and K-256 curves
+- **`atproto-identity-sign`**: Create cryptographic signatures of JSON data using private keys
+- **`atproto-identity-validate`**: Validate cryptographic signatures against public keys
 
 ## Library Usage
 
···
 
 ```bash
 # Build with CLI support
-cargo build --features clap --bins
+cargo build --features clap,hickory-dns --bins
 
 # Resolve a handle to DID
-cargo run --features clap --bin atproto-identity-resolve -- alice.bsky.social
+cargo run --features clap,hickory-dns --bin atproto-identity-resolve -- alice.bsky.social
 
 # Generate a new P-256 key
 cargo run --features clap --bin atproto-identity-key -- generate p256

crates/atproto-identity/src/config.rs

···
 //! Configuration management for AT Protocol identity operations.
 //!
-//! Provides utilities for reading environment variables, parsing configuration values,
-//! and managing DNS nameservers and TLS certificate bundles. Supports fallback defaults
-//! and structured error handling for missing or invalid configuration.
+//! Environment variable utilities, DNS nameserver configuration, and TLS certificate
+//! bundle management with structured error handling.
 
 use crate::errors::ConfigError;
 use anyhow::Result;

crates/atproto-identity/src/key.rs

···
-//! Cryptographic key operations for AT Protocol identity management.
-//!
-//! This module provides utilities for working with elliptic curve cryptographic keys
-//! used in AT Protocol DID documents and identity verification. Supports P-256
-//! (secp256r1), P-384 (secp384r1), and K-256 (secp256k1) curves with operations for key identification,
-//! signature validation, and content signing.
-//!
-//! # Supported Key Types
+//! Cryptographic key operations for AT Protocol identity.
 //!
-//! - **P-256** (secp256r1/ES256): NIST standard curve, commonly used in web standards
+//! Elliptic curve cryptography for P-256, P-384, and K-256 curves including
+//! key identification, signature validation, and content signing.
 //! - **P-384** (secp384r1/ES384): NIST standard curve, providing higher security than P-256
 //! - **K-256** (secp256k1/ES256K): Bitcoin curve, widely used in blockchain applications
 //!

crates/atproto-identity/src/lib.rs

···
-//! # AT Protocol Identity Management Library
-//!
-//! Comprehensive Rust library for AT Protocol identity operations including DID resolution,
-//! handle resolution, and cryptographic key management. This is the core identity management
-//! library for building AT Protocol applications and services.
-//!
-//! ## Key Features
-//!
-//! - **Multi-Method DID Resolution**: Support for `did:plc`, `did:web`, and `did:key` methods
-//! - **Handle Resolution**: DNS and HTTP-based handle-to-DID resolution with conflict detection
-//! - **Cryptographic Key Operations**: P-256, P-384, and K-256 key generation, signing, and validation
-//! - **DID Document Management**: Parsing, validation, and caching of DID documents
-//! - **Storage Abstraction**: Pluggable storage with LRU cache implementation
-//! - **Configuration Management**: Environment-based configuration with validation
-//! - **Error Handling**: Structured error types with descriptive messages
-//!
-//! ## Architecture
-//!
-//! The library is organized into focused modules that can be used independently or together:
-//!
-//! - **`resolve`**: Core identity resolution logic for handles and DIDs
-//! - **`plc`**: PLC directory client for `did:plc` resolution
-//! - **`web`**: Web DID client for `did:web` resolution and URL conversion
-//! - **`key`**: Cryptographic operations including signature validation and key identification
-//! - **`model`**: Data structures for DID documents and AT Protocol entities
-//! - **`validation`**: Input validation for handles and DIDs
-//! - **`storage`**: Storage abstraction for DID document caching
-//! - **`config`**: Configuration management and environment variable handling
+//! AT Protocol identity management for DID resolution, handle resolution, and cryptographic operations.
 //!
-//! ## Command-Line Tools
+//! This crate provides core identity functionality for AT Protocol applications including multi-method
+//! DID resolution (plc, web, key), DNS/HTTP handle resolution, and P-256/P-384/K-256 key operations.
 //!
 //! When built with the `clap` feature, provides comprehensive CLI tools:
 //!

crates/atproto-identity/src/model.rs

···
 //! Data structures for DID documents and AT Protocol entities.
 //!
-//! Defines the core data models used throughout the AT Protocol identity system
-//! including DID documents, services, and verification methods. All structures
-//! support JSON serialization/deserialization for working with AT Protocol APIs.
+//! Core data models for AT Protocol identity including DID documents, services,
+//! and verification methods with full JSON serialization support.
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;

crates/atproto-identity/src/plc.rs

···
-//! # PLC Directory Client
-//!
-//! Simple HTTP client for querying PLC (Public Ledger of Credentials) directories to retrieve
-//! DID documents for `did:plc` identifiers. The PLC system serves as a centralized registry
-//! for AT Protocol DIDs.
-//!
-//! ## Usage
+//! PLC directory client for did:plc resolution.
 //!
-//! The primary function `query()` fetches complete DID documents from PLC directory servers
-//! using HTTPS requests to the standard PLC API endpoint format.
+//! Fetches DID documents from PLC directory servers using HTTPS requests
+//! to resolve did:plc identifiers in the AT Protocol ecosystem.
 
 use tracing::{Instrument, instrument};
 

crates/atproto-identity/src/resolve.rs

···
-//! # Core Resolution Logic
-//!
-//! Provides comprehensive resolution capabilities for AT Protocol identities including handle-to-DID
-//! resolution via DNS TXT records and HTTPS well-known endpoints, input parsing for multiple
-//! identifier formats, and DNS resolver configuration.
-//!
-//! ## Key Features
+//! AT Protocol identity resolution for handles and DIDs.
 //!
-//! - **Multi-method resolution**: Uses both DNS and HTTP methods for handle resolution
-//! - **Input parsing**: Automatically detects and parses handles, `did:plc`, and `did:web` identifiers
+//! Resolves AT Protocol identities via DNS TXT records and HTTPS well-known endpoints,
+//! with automatic input detection for handles, did:plc, and did:web identifiers.
 //! - **Validation**: Ensures DNS and HTTP resolution methods agree on the resolved DID
 //! - **Custom DNS**: Supports custom DNS nameservers for resolution
 //!

crates/atproto-identity/src/storage.rs

···
-//! DID document storage abstraction for AT Protocol identity management.
+//! DID document storage abstraction.
 //!
-//! This module provides the `DidDocumentStorage` trait for implementing DID document CRUD operations
-//! across different storage backends (database, file system, in-memory, etc.).
-//!
-//! The trait enables flexible storage implementations while maintaining a consistent
-//! interface for DID document operations throughout the AT Protocol ecosystem.
+//! Storage trait for DID document CRUD operations supporting multiple
+//! backends (database, file system, memory) with consistent interface.
 
 use anyhow::Result;
 

crates/atproto-identity/src/storage_lru.rs

···
-//! LRU-based implementation of the `DidDocumentStorage` trait.
-//!
-//! This module provides an in-memory implementation of DID document storage using an LRU (Least Recently Used)
-//! cache. This is useful for scenarios where you want to cache DID documents with automatic
-//! eviction of least recently used entries when the cache reaches its capacity limit.
+//! LRU cache implementation for DID document storage.
 //!
-//! The implementation is thread-safe and can be used in concurrent environments where multiple
-//! async tasks need to access the document storage simultaneously.
+//! Thread-safe in-memory storage with automatic eviction of least recently used
+//! DID documents when capacity is reached.
 
 use std::num::NonZeroUsize;
 use std::sync::{Arc, Mutex};

crates/atproto-identity/src/validation.rs

···
 //! Input validation for AT Protocol handles and DIDs.
 //!
-//! This module provides comprehensive validation functions for various identifier formats
-//! used in the AT Protocol ecosystem. All validation follows established standards including
-//! RFC 1035 for hostnames and AT Protocol specifications for handle and DID formats.
-//!
-//! # Main Functions
-//!
-//! ## Handle Validation
-//! - [`is_valid_handle`] - Validates and normalizes AT Protocol handles
+//! Validates AT Protocol identifiers including handles, DIDs, and TLDs
+//! following RFC 1035 and AT Protocol specifications.
 //! - [`strip_handle_prefixes`] - Removes common handle prefixes (`@`, `at://`)
 //!
 //! ## DID Validation  

crates/atproto-identity/src/web.rs

···
-//! # Web DID Client
-//!
-//! HTTP client for resolving `did:web` identifiers by converting DID formats to HTTPS URLs
-//! and fetching DID documents from well-known locations. Supports both standard did:web
-//! resolution and direct hostname-based document retrieval.
-//!
-//! ## Key Functions
+//! Web DID client for did:web resolution.
 //!
-//! - **`did_web_to_url()`**: Converts `did:web:example.com` format to HTTPS well-known URLs
-//! - **`query()`**: Fetches DID documents for did:web identifiers
+//! Resolves did:web identifiers by converting them to HTTPS URLs and fetching
+//! DID documents from well-known locations on web servers.
 //! - **`query_hostname()`**: Direct document retrieval from hostname well-known endpoints
 //!
 //! ## URL Conversion

crates/atproto-jetstream/README.md

···
 # atproto-jetstream
 
-WebSocket event stream consumer library for AT Protocol Jetstream.
+WebSocket consumer for AT Protocol Jetstream events.
 
 ## Overview
 
-`atproto-jetstream` provides a comprehensive async stream consumer for AT Protocol Jetstream events. This library enables real-time consumption of AT Protocol repository events, identity changes, and account updates through WebSocket connections with support for filtering, compression, and graceful shutdown patterns.
+Real-time event streaming with Zstandard compression, automatic reconnection, and configurable event filtering for AT Protocol repository changes.
 
-## Binaries
+## Features
 
-- **atproto-jetstream-consumer**: Real-time event stream consumer with filtering and compression support
+- **WebSocket streaming**: High-performance event consumption with automatic reconnection handling
+- **Event filtering**: Configurable filtering by collections and DIDs for targeted event processing
+- **Zstandard compression**: Built-in support for compressed event streams with custom dictionaries
+- **Event handlers**: Flexible handler system supporting multiple custom event processors
+- **Background processing**: Asynchronous event processing with graceful shutdown via cancellation tokens
+- **Structured errors**: Comprehensive error handling with detailed error codes
 
-## Features
+## CLI Tools
 
-- High-performance WebSocket streaming with automatic reconnection
-- Flexible event handler system with multiple custom handlers
-- Zstandard compression support with custom dictionaries
-- Event filtering by collections and DIDs
-- Graceful shutdown with cancellation token support
-- Structured error handling with detailed error codes
+The following command-line tool is available when built with the `clap` feature:
+
+- **`atproto-jetstream-consumer`**: Real-time event stream consumer with filtering, compression, and background processing support
 
 ## Usage
 

crates/atproto-jetstream/src/consumer.rs

···
-//! Async stream consumer for AT Protocol Jetstream events
+//! Async stream consumer for Jetstream events.
 //!
-//! This module provides structures for consuming events from an async stream
-//! and dispatching them to registered event handlers.
+//! WebSocket event consumption with background processing and
+//! customizable event handler dispatch.
 
 use anyhow::Result;
 use async_trait::async_trait;

crates/atproto-jetstream/src/lib.rs

···
-//! # AT Protocol Jetstream Consumer Library
-//!
-//! Real-time WebSocket consumer library for AT Protocol Jetstream events with high-performance
-//! streaming and compression support. Enables applications to receive live AT Protocol events
-//! such as posts, likes, follows, and other repository changes.
-//!
-//! ## Key Features
-//!
-//! - **WebSocket Streaming**: Real-time event consumption via WebSocket connections
-//! - **Zstandard Compression**: Built-in support for Zstandard (zstd) compressed event streams
-//! - **Background Processing**: Asynchronous event processing with configurable concurrency
-//! - **Resilient Connections**: Automatic reconnection handling for production reliability
-//! - **Event Filtering**: Configurable filtering for specific event types and collections
-//! - **Performance Optimized**: Low-latency event processing with minimal overhead
+//! WebSocket consumer for AT Protocol Jetstream events.
 //!
-//! ## Architecture
-//!
-//! The library provides a high-level consumer interface with customizable event handlers:
-//!
-//! - **`consumer`**: Core WebSocket consumer with event handling and connection management
+//! Real-time event streaming with Zstandard compression, automatic reconnection,
+//! and configurable event filtering for AT Protocol repository changes.
 //!
 //! ## Command-Line Tools
 //!

crates/atproto-oauth-aip/README.md

···
 # atproto-oauth-aip
 
-AT Protocol OAuth implementation for AT Protocol Identity Provider (AIP) integration. This crate provides high-level OAuth workflow functions for client applications that need to authenticate with AT Protocol services.
+OAuth AIP (Identity Provider) implementation for AT Protocol.
 
 ## Overview
 
-`atproto-oauth-aip` builds on top of the foundational `atproto-oauth` crate to provide a complete OAuth authentication workflow specifically tailored for AT Protocol. It handles the full OAuth flow including:
-
-- OAuth metadata discovery
-- Pushed Authorization Request (PAR) initiation
-- Authorization code exchange
-- AT Protocol session establishment
+Complete OAuth 2.0 authorization code flow with PAR, PKCE, token exchange, and AT Protocol session management for identity providers.
 
 ## Features
 
-- **PAR Support**: Enhanced security through Pushed Authorization Requests
-- **AT Protocol Session Exchange**: Convert OAuth tokens to rich AT Protocol sessions
-- **DPoP Integration**: Support for Demonstration of Proof-of-Possession tokens
-- **Comprehensive Error Handling**: Typed errors for each OAuth operation
-- **Async/Await**: Fully asynchronous implementation using Tokio
+- **OAuth 2.0 authorization code flow**: Complete implementation with PKCE support for secure authentication
+- **Pushed Authorization Requests (PAR)**: Enhanced security through server-side request storage
+- **Token exchange**: Secure OAuth token issuance and refresh capabilities
+- **AT Protocol session management**: Convert OAuth tokens to AT Protocol sessions with DID resolution
+- **Resource validation**: OAuth protected resource and authorization server configuration validation
+- **Structured error handling**: Comprehensive error types following AT Protocol conventions
+
+## CLI Tools
+
+This crate does not provide standalone CLI tools. It serves as a library for OAuth AIP implementations.
 
 ## Installation
 

crates/atproto-oauth-aip/src/lib.rs

···
-//! # AT Protocol OAuth AIP (Identity Provider) Implementation
-//!
-//! This crate provides a comprehensive OAuth 2.0 workflow implementation for AT Protocol
-//! Identity Providers (AIPs). It handles the complete OAuth flow including Pushed
-//! Authorization Requests (PAR), token exchange, and session management according to
-//! AT Protocol specifications.
-//!
-//! ## Key Features
-//!
-//! - **OAuth 2.0 Authorization Code Flow**: Complete implementation with PKCE support
-//! - **Pushed Authorization Requests (PAR)**: Enhanced security through server-side request storage
-//! - **Token Exchange**: Secure token issuance and refresh capabilities
-//! - **Session Management**: AT Protocol session establishment and validation
-//! - **Resource Validation**: OAuth protected resource and authorization server validation
+//! OAuth AIP (Identity Provider) implementation for AT Protocol.
 //!
-//! ## Usage
-//!
-//! The primary entry point is the workflow module which provides functions for each
-//! stage of the OAuth flow:
-//!
+//! Complete OAuth 2.0 authorization code flow with PAR, PKCE, token exchange,
+//! and AT Protocol session management for identity providers.
 //! ```rust,no_run
 //! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
 //! use atproto_oauth_aip::workflow::{oauth_init, oauth_complete, session_exchange, OAuthClient};

crates/atproto-oauth-aip/src/resources.rs

···
+//! OAuth resource discovery for AT Protocol identity providers.
+
 use atproto_oauth::{
     errors::OAuthClientError,
     resources::{AuthorizationServer, OAuthProtectedResource},
 };
 
-/// Fetches OAuth protected resource metadata from an AIP server.
-///
-/// This function retrieves the OAuth protected resource configuration from
-/// the well-known endpoint of an AT Protocol Identity Provider (AIP) server.
-/// The metadata includes information about the protected resource endpoints
+/// Fetch OAuth protected resource metadata from an AIP server.
 /// and capabilities.
 ///
 /// # Arguments

crates/atproto-oauth-aip/src/workflow.rs

···
-//! # OAuth 2.0 Workflow Implementation for AT Protocol Identity Providers
-//!
-//! This module provides a complete OAuth 2.0 authorization code flow implementation
-//! specifically designed for AT Protocol Identity Providers (AIPs). It handles the
-//! three main phases of OAuth authentication: initialization, completion, and session exchange.
-//!
-//! ## Workflow Overview
-//!
-//! The OAuth workflow consists of three main functions that handle different phases:
+//! OAuth 2.0 workflow for AT Protocol identity providers.
 //!
+//! Complete authorization code flow implementation with PAR initialization,
+//! code exchange, and AT Protocol session establishment.
 //! 1. **Initialization (`oauth_init`)**: Creates a Pushed Authorization Request (PAR)
 //!    and returns the authorization URL for user consent
 //! 2. **Completion (`oauth_complete`)**: Exchanges the authorization code for access tokens

crates/atproto-oauth-axum/README.md

···
 # atproto-oauth-axum
 
-Axum web handlers for AT Protocol OAuth 2.0 authorization server endpoints.
+Axum web framework integration for AT Protocol OAuth.
 
 ## Overview
 
-`atproto-oauth-axum` provides ready-to-use Axum web handlers that implement the complete AT Protocol OAuth 2.0 authorization server specification. This library handles OAuth client metadata discovery, JWKS endpoints, authorization callback processing, and includes a command-line OAuth login tool.
+Production-ready OAuth handlers for authorization flows, callbacks, JWKS endpoints, and metadata with secure state management.
 
-## Binaries
+## Features
 
-- **atproto-oauth-tool**: Complete OAuth login CLI tool for AT Protocol services
+- **OAuth endpoint handlers**: Complete Axum handlers for authorization flows, callbacks, and metadata endpoints
+- **JWKS endpoint**: JSON Web Key Set endpoint for public key distribution to authorization servers
+- **Client metadata**: RFC 7591 compliant OAuth client metadata endpoint for dynamic registration
+- **Callback processing**: OAuth authorization callback handler with state validation and token exchange
+- **State management**: Secure OAuth state and request management with Axum extractors
+- **Error handling**: Comprehensive error handling with proper HTTP status codes
 
-## Features
+## CLI Tools
 
-- Complete OAuth server handlers for Axum web applications
-- Client metadata endpoint with RFC 7591 compliance
-- JWKS endpoint for JSON Web Key Set serving
-- Authorization callback handler with token exchange
-- Native Axum state management and request extractors
-- AT Protocol compliance validation
+The following command-line tool is available when built with the `clap` feature:
+
+- **`atproto-oauth-tool`**: Complete OAuth login workflow tool for AT Protocol services with local callback server
 
 ## Usage
 

crates/atproto-oauth-axum/src/handle_complete.rs

···
 //! OAuth authorization callback handler.
 //!
-//! Handles the OAuth authorization callback by exchanging authorization codes for tokens,
-//! validating OAuth state, and completing the OAuth flow with proper error handling.
+//! Exchange authorization codes for tokens with state validation
+//! and comprehensive error handling for OAuth completion.
 
 use std::sync::Arc;
 

crates/atproto-oauth-axum/src/handle_jwks.rs

···
-//! OAuth JSON Web Key Set (JWKS) endpoint handler.
+//! JSON Web Key Set (JWKS) endpoint handler.
 //!
-//! Serves the JWKS endpoint for OAuth client public keys, enabling authorization servers
-//! to verify JWT signatures from the OAuth client during authentication flows.
+//! Serve OAuth client public keys for JWT signature verification
+//! by authorization servers.
 
 use atproto_oauth::jwk::{WrappedJsonWebKey, generate};
 use axum::{Json, response::IntoResponse};

crates/atproto-oauth-axum/src/handler_metadata.rs

···
 //! OAuth client metadata endpoint handler.
 //!
-//! Serves OAuth 2.0 client metadata according to RFC 7591, providing client configuration
-//! information required for dynamic client registration and authorization server discovery.
+//! RFC 7591 compliant client metadata for dynamic registration
+//! and authorization server discovery.
 
 use atproto_identity::key::to_public;
 use axum::{Json, response::IntoResponse};

crates/atproto-oauth-axum/src/lib.rs

···
-//! # AT Protocol OAuth Axum Integration Library
-//!
-//! Axum web framework integration for AT Protocol OAuth workflows with comprehensive
-//! handler implementations for OAuth endpoints. Provides production-ready web handlers
-//! for OAuth authorization, callback processing, and JWKS endpoint management.
-//!
-//! ## Key Features
-//!
-//! - **Axum Integration**: Native Axum web framework handlers for OAuth endpoints
-//! - **OAuth Workflow Handlers**: Complete OAuth authorization and callback processing
-//! - **JWKS Endpoint**: JSON Web Key Set endpoint for public key distribution
-//! - **Metadata Endpoints**: OAuth authorization server metadata endpoint implementation
-//! - **State Management**: Secure OAuth state and request management with storage abstraction
-//! - **Error Handling**: Comprehensive error handling with proper HTTP status codes
+//! Axum web framework integration for AT Protocol OAuth.
 //!
-//! ## Architecture
-//!
-//! The library provides Axum-compatible handlers and state management:
-//!
-//! - **`handle_init`**: OAuth authorization initiation handler
+//! Production-ready OAuth handlers for authorization flows, callbacks,
+//! JWKS endpoints, and metadata with secure state management.
 //! - **`handle_complete`**: OAuth callback and completion handler  
 //! - **`handle_jwks`**: JWKS (JSON Web Key Set) endpoint handler
 //! - **`handler_metadata`**: OAuth authorization server metadata handler

crates/atproto-oauth-axum/src/state.rs

···
-//! Axum state management for OAuth client configuration.
+//! Axum state management for OAuth configuration.
 //!
-//! Provides request extractors and HTTP client wrappers for injecting OAuth client
-//! configuration and HTTP clients into Axum request handlers.
+//! Request extractors and HTTP client wrappers for OAuth
+//! client configuration injection in handlers.
 
 use atproto_identity::key::KeyData;
 use axum::extract::{FromRef, FromRequestParts};

crates/atproto-oauth/README.md

···
 # atproto-oauth
 
-OAuth 2.0 implementation for AT Protocol with DPoP support, PKCE, and JWT operations.
+OAuth 2.0 implementation for AT Protocol.
 
 ## Overview
 
-`atproto-oauth` provides comprehensive OAuth 2.0 functionality specifically designed for the AT Protocol ecosystem. This library implements DPoP (Demonstration of Proof-of-Possession), PKCE (Proof Key for Code Exchange), JWT operations, JWK management, and AT Protocol-specific OAuth validation.
+Comprehensive OAuth support with DPoP, PKCE, JWT operations, and secure storage abstractions for AT Protocol authentication.
 
 ## Features
 
-- **JWT operations**: Minting, verification, and validation with ES256/ES256K/ES384 support
-- **JWK management**: Generation and conversion for P-256, P-384, and K-256 curves
-- **PKCE implementation**: Secure OAuth flows with Proof Key for Code Exchange
-- **DPoP support**: Demonstration of Proof-of-Possession with automatic retry middleware
-- **OAuth discovery**: Resource discovery and AT Protocol validation
-- **Request storage**: LRU cache-based OAuth request storage
-- **Structured errors**: Comprehensive error handling with detailed error codes
+- **JWT operations**: Token minting, verification, and validation with ES256/ES384/ES256K support
+- **JWK management**: JSON Web Key generation and conversion for P-256, P-384, and K-256 curves
+- **PKCE implementation**: RFC 7636 compliant Proof Key for Code Exchange for secure authorization flows
+- **DPoP support**: RFC 9449 compliant Demonstration of Proof-of-Possession with automatic retry middleware
+- **OAuth discovery**: Resource discovery and validation using RFC 8414 well-known endpoints
+- **Storage abstractions**: Pluggable storage with LRU cache implementation for OAuth requests
+- **Base64 encoding**: URL-safe base64 encoding/decoding utilities for JWT operations
+
+## CLI Tools
+
+This crate does not provide standalone CLI tools. OAuth workflow tools are available through the `atproto-oauth-axum` crate when built with the `clap` feature.
 
 ## Usage
 

crates/atproto-oauth/src/dpop.rs

···
-//! DPoP (Demonstration of Proof-of-Possession) implementation for AT Protocol OAuth.
-//!
-//! This module provides functionality for creating and managing DPoP tokens as specified
-//! in RFC 9449. DPoP is a security extension to OAuth 2.0 that allows clients to prove
-//! possession of cryptographic keys by including a DPoP proof in HTTP requests.
+//! DPoP (Demonstration of Proof-of-Possession) implementation.
 //!
-//! Key features:
-//! - DPoP token generation for authorization and resource requests
-//! - Automatic retry middleware for handling DPoP nonce challenges
-//! - Support for ES256 signature algorithm with elliptic curve keys
+//! RFC 9449 compliant DPoP token generation with automatic retry middleware
+//! for nonce challenges and ES256 signature support.
 
 use crate::errors::{JWKError, JWTError};
 use anyhow::Result;

crates/atproto-oauth/src/encoding.rs

···
-//! Base64 encoding and decoding utilities for AT Protocol OAuth.
+//! Base64 encoding utilities for OAuth operations.
 //!
-//! Provides traits and implementations for converting JSON serializable types to and from
-//! base64url-encoded format, commonly used in JWT headers and claims. Uses URL-safe base64
-//! encoding without padding as specified by RFC 7515 for JSON Web Signature operations.
+//! URL-safe base64 encoding/decoding for JWT headers and claims
+//! following RFC 7515 specifications.
 
 use anyhow::{Context, Result};
 use base64::{Engine as _, engine::general_purpose};

crates/atproto-oauth/src/jwk.rs

···
-//! JSON Web Key (JWK) generation and management for AT Protocol OAuth.
+//! JSON Web Key (JWK) generation and management.
 //!
-//! Provides functionality for creating and managing JSON Web Keys with AT Protocol-specific
-//! algorithm mappings. Supports bidirectional conversion between `atproto-identity` key data
-//! and JWK format with proper algorithm identifiers for P-256 (ES256), P-384 (ES384), and
-//! K-256 (ES256K) elliptic curves.
+//! Convert between AT Protocol key data and JWK format with support
+//! for P-256 (ES256), P-384 (ES384), and K-256 (ES256K) curves.
 
 use anyhow::Result;
 use atproto_identity::key::{KeyData, KeyType, to_public};

crates/atproto-oauth/src/jwt.rs

···
-//! JSON Web Token (JWT) minting and verification for AT Protocol OAuth.
+//! JSON Web Token (JWT) minting and verification.
 //!
-//! Provides functionality for creating and verifying JWT tokens with JOSE standard claims and
-//! custom extensions for AT Protocol OAuth flows. Supports ES256, ES384, and ES256K elliptic curve
-//! signature algorithms with comprehensive timestamp validation and structured error handling.
+//! Create and verify JWTs with JOSE standard claims supporting
+//! ES256, ES384, and ES256K signature algorithms.
 
 use anyhow::Result;
 use atproto_identity::key::{KeyData, KeyType, sign, to_public, validate};

crates/atproto-oauth/src/lib.rs

···
-//! OAuth 2.0 implementation for AT Protocol with DPoP support, PKCE, and JWT operations.
+//! OAuth 2.0 implementation for AT Protocol.
 //!
-//! Provides binaries:
-//! - `atproto-oauth-tool`: OAuth authentication workflow management (via atproto-oauth-axum crate)
+//! Comprehensive OAuth support with DPoP, PKCE, JWT operations,
+//! and secure storage abstractions for AT Protocol authentication.
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]

crates/atproto-oauth/src/pkce.rs

···
-//! PKCE (Proof Key for Code Exchange) implementation for OAuth 2.0.
-//!
-//! This module implements the PKCE security extension defined in RFC 7636, which protects
-//! OAuth 2.0 authorization code flows from interception attacks. PKCE is particularly
-//! important for public clients such as mobile applications and single-page applications
-//! that cannot securely store client secrets.
-//!
-//! ## PKCE Flow
+//! PKCE (Proof Key for Code Exchange) implementation.
 //!
-//! 1. **Generate**: Create a cryptographically random code verifier and its SHA256 challenge
+//! RFC 7636 compliant PKCE for OAuth 2.0 authorization code flow
+//! security with SHA256 challenge generation.
 //! 2. **Authorize**: Send the code challenge with the authorization request
 //! 3. **Exchange**: Send the original code verifier when exchanging the authorization code for tokens
 //!

crates/atproto-oauth/src/resources.rs

···
-//! OAuth resource discovery and validation for AT Protocol Personal Data Servers.
+//! OAuth resource discovery and validation.
 //!
-//! This module provides functionality to discover and validate OAuth 2.0 configuration
-//! from AT Protocol Personal Data Servers (PDS) using RFC 8414 well-known endpoints
-//! with AT Protocol specific requirements and validations.
+//! Discover and validate OAuth 2.0 configuration from AT Protocol
+//! PDS servers using RFC 8414 well-known endpoints.
 
 use serde::Deserialize;
 

crates/atproto-oauth/src/storage.rs

···
-//! OAuth request storage abstraction for AT Protocol OAuth operations.
-//!
-//! This module provides the `OAuthRequestStorage` trait for implementing OAuth request CRUD operations
-//! across different storage backends (database, file system, in-memory, etc.).
+//! OAuth request storage abstraction.
 //!
-//! The trait enables flexible storage implementations while maintaining a consistent interface
-//! for OAuth request management operations throughout the AT Protocol OAuth ecosystem, including
-//! state tracking, expiration handling, and cleanup operations.
+//! Storage trait for OAuth request CRUD operations supporting multiple
+//! backends with state tracking and expiration handling.
 
 use anyhow::Result;
 

crates/atproto-oauth/src/storage_lru.rs

···
-//! LRU-based implementation of the `OAuthRequestStorage` trait.
-//!
-//! This module provides an in-memory implementation of OAuth request storage using an LRU (Least Recently Used)
-//! cache. This is useful for scenarios where you want to cache OAuth requests with automatic
-//! eviction of least recently used entries when the cache reaches its capacity limit.
+//! LRU cache implementation for OAuth request storage.
 //!
-//! The implementation is thread-safe and can be used in concurrent environments where multiple
-//! async tasks need to access the OAuth request storage simultaneously.
+//! Thread-safe in-memory storage with automatic eviction of least recently used
+//! OAuth requests when capacity is reached.
 
 use std::num::NonZeroUsize;
 use std::sync::{Arc, Mutex};

crates/atproto-oauth/src/workflow.rs

···
-//! OAuth workflow implementation for AT Protocol authorization flows.
-//!
-//! This module provides a complete OAuth 2.0 authorization code flow implementation specifically
-//! designed for AT Protocol, including Pushed Authorization Requests (PAR), DPoP security, PKCE
-//! protection, and client assertion handling.
-//!
-//! ## OAuth Flow Components
+//! OAuth workflow for AT Protocol authorization.
 //!
-//! - **`oauth_init()`**: Initiates OAuth flow with PAR request to authorization server
-//! - **`oauth_complete()`**: Completes OAuth flow by exchanging authorization code for tokens
+//! Complete OAuth 2.0 authorization code flow with PAR, DPoP, PKCE,
+//! and client assertion support for AT Protocol authentication.
 //! - **`OAuthClient`**: Client configuration with credentials and signing keys
 //! - **`OAuthRequest`**: Tracking structure for ongoing authorization requests
 //! - **`OAuthRequestState`**: Security parameters including state, nonce, and PKCE challenge

crates/atproto-record/README.md

···
 # atproto-record
 
-Cryptographic signature operations for AT Protocol records with IPLD DAG-CBOR serialization and AT-URI parsing.
+Cryptographic signature operations for AT Protocol records.
 
 ## Overview
 
-`atproto-record` provides comprehensive signature operations for AT Protocol records, including cryptographic signing, verification, AT-URI parsing, and proper IPLD DAG-CBOR serialization. This library implements the AT Protocol signature format with proper `$sig` object handling for secure record attestation.
+Sign and verify AT Protocol records using IPLD DAG-CBOR serialization with support for P-256, P-384, and K-256 cryptographic signatures. Includes AT-URI parsing for record identification.
 
 ## Features
 
-- **Record signing**: Create cryptographic signatures on AT Protocol records
-- **Signature verification**: Verify signatures against public keys and issuers
-- **AT-URI parsing**: Parse and validate AT Protocol URIs into component parts
-- **IPLD serialization**: Proper DAG-CBOR serialization for signature consistency
-- **Multi-curve support**: Support for P-256, P-384, and K-256 elliptic curves
+- **Record signing**: Create cryptographic signatures on AT Protocol records with proper $sig object handling
+- **Signature verification**: Verify record signatures against public keys and issuer DIDs
+- **AT-URI parsing**: Parse and validate AT Protocol URIs (at://authority/collection/record_key)
+- **IPLD serialization**: DAG-CBOR serialization for signature consistency and integrity
+- **Multi-curve support**: Support for P-256, P-384, and K-256 elliptic curve signatures
 - **Structured errors**: Comprehensive error handling with detailed error types
-- **CLI tools**: Command-line utilities for record operations (requires `clap` feature)
 
-## Binaries
+## CLI Tools
 
-All CLI tools require the `clap` feature and use consistent command-line argument processing:
+The following command-line tools are available when built with the `clap` feature:
 
-- **atproto-record-sign**: Sign AT Protocol records with cryptographic signatures
-- **atproto-record-verify**: Verify AT Protocol record signatures
+- **`atproto-record-sign`**: Sign AT Protocol records with private keys and create signature objects
+- **`atproto-record-verify`**: Verify AT Protocol record signatures against public keys and issuers
 
 ## Library Usage
 

crates/atproto-record/src/aturi.rs

···
-//! # AT-URI Parsing
-//!
-//! Provides parsing and validation functionality for AT Protocol URIs (AT-URIs).
-//! AT-URIs are used to identify records within AT Protocol repositories.
-//!
-//! ## Format
+//! AT-URI parsing and validation.
 //!
-//! AT-URIs follow the format: `at://{authority}/{collection}/{record_key}`
-//! where:
-//! - `authority` is a DID (not a handle)
+//! Parse AT Protocol URIs (at://authority/collection/record_key) for
+//! identifying records within AT Protocol repositories.
 //! - `collection` is an NSID identifying the record type
 //! - `record_key` is the unique identifier for the specific record
 

crates/atproto-record/src/lib.rs

···
-//! Cryptographic signature operations for AT Protocol records with IPLD DAG-CBOR serialization.
+//! Cryptographic signature operations for AT Protocol records.
 //!
-//! Provides binaries:
-//! - `atproto-record-sign`: Sign AT Protocol records with private keys
-//! - `atproto-record-verify`: Verify signatures on AT Protocol records
+//! Sign and verify AT Protocol records using IPLD DAG-CBOR serialization
+//! with support for P-256, P-384, and K-256 cryptographic signatures.
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]

crates/atproto-record/src/signature.rs

···
 //! AT Protocol record signature operations.
 //!
-//! Provides cryptographic signing and verification capabilities for AT Protocol records using
-//! elliptic curve digital signatures. Implements the AT Protocol signature format with proper
-//! `$sig` object handling and IPLD DAG-CBOR serialization for secure record attestation.
+//! Sign and verify AT Protocol records using elliptic curve signatures
+//! with IPLD DAG-CBOR serialization and proper $sig object handling.
 
 use atproto_identity::key::{KeyData, sign, validate};
 use serde_json::json;

crates/atproto-xrpcs-helloworld/README.md

···
 # atproto-xrpcs-helloworld
 
-Example XRPC service implementation demonstrating AT Protocol service patterns.
+Example XRPC service with DID:web identity and JWT authentication.
 
 ## Overview
 
-`atproto-xrpcs-helloworld` provides a complete AT Protocol XRPC service that demonstrates DID web identity, service document generation, well-known endpoint handling, and JWT-based authentication using the `atproto-xrpcs` library.
+Complete AT Protocol XRPC service demonstrating DID:web identity, service document generation, well-known endpoints, and JWT-based authentication patterns.
 
-## Binaries
+## Features
 
-- **atproto-xrpcs-helloworld**: Complete XRPC service with DID web identity and authentication
+- **Complete XRPC service**: Production-ready service implementation with authentication
+- **DID:web identity**: Automatic service document generation with well-known endpoint support
+- **JWT authorization**: Optional JWT-based authentication with DID document verification
+- **Discovery endpoints**: Standard AT Protocol discovery endpoints for service metadata
+- **Example patterns**: Reference implementation for building AT Protocol services
 
-## Features
+## CLI Tools
 
-- Complete XRPC service implementation with authentication
-- DID web identity with automatic service document generation
-- Well-known endpoints for AT Protocol discovery
-- Example authenticated and unauthenticated XRPC endpoint
-- JWT authorization with DID document verification
+The following service binary is available:
+
+- **`atproto-xrpcs-helloworld`**: Complete XRPC service demonstrating AT Protocol patterns with DID:web identity and optional JWT authentication
 
 ## Usage
 

crates/atproto-xrpcs-helloworld/src/main.rs

···
-//! Demonstration XRPC service for AT Protocol with DID:web identity and optional JWT authentication.
+//! Example XRPC service with DID:web identity and JWT authentication.
 
 use anyhow::Result;
 use async_trait::async_trait;

crates/atproto-xrpcs/README.md

···
 # atproto-xrpcs
 
-XRPC service components library for AT Protocol with JWT authorization.
+XRPC service framework for AT Protocol applications.
 
 ## Overview
 
-`atproto-xrpcs` provides foundational components for building AT Protocol XRPC services. This library offers JWT-based authorization extractors that integrate with Axum web handlers, enabling secure XRPC endpoints with automatic DID document verification.
-
-This is a library-only crate that provides reusable components for XRPC service development. For a complete example service implementation, see the `atproto-xrpcs-helloworld` crate.
+Build AT Protocol services with JWT authorization, DID resolution, and cryptographic identity verification middleware.
 
 ## Features
 
-- JWT authorization extractors for Axum web handlers
-- Automatic DID document verification for caller identities
-- Structured error handling with detailed error codes
-- Native Axum integration for HTTP handlers
-- Identity resolution support for AT Protocol
+- **JWT authorization**: Comprehensive JWT token validation with DID-based issuer verification
+- **DID resolution integration**: Automatic DID document resolution and key verification for authorization
+- **Identity verification**: Cryptographic verification of JWT signatures using DID documents
+- **Axum extractors**: Ready-to-use authorization extractors for Axum web handlers
+- **Structured errors**: Specialized error types for authorization and XRPC operations
+
+## CLI Tools
+
+This crate does not provide standalone CLI tools. It serves as a foundational library for building XRPC services. See `atproto-xrpcs-helloworld` for a complete example service implementation.
 
 ## Usage
 

crates/atproto-xrpcs/src/authorization.rs

···
-//! # JWT Authorization Extractors for XRPC Services
+//! JWT authorization extractors for XRPC services.
 //!
-//! Provides Axum extractors for validating JWT tokens against DID documents in AT Protocol
-//! XRPC services. Supports both cached and resolving authorization modes for flexible
-//! identity verification workflows.
+//! Axum extractors for JWT validation against DID documents with
+//! cached and resolving authorization modes.
 
 use anyhow::Result;
 use atproto_identity::key::identify_key;

crates/atproto-xrpcs/src/lib.rs

···
-//! # AT Protocol XRPC Service Framework
-//!
-//! Service framework for building AT Protocol XRPC applications with built-in JWT authorization,
-//! DID resolution, and identity verification. Provides the foundational components needed to
-//! create production AT Protocol services and applications.
-//!
-//! ## Key Features
-//!
-//! - **JWT Authorization**: Comprehensive JWT token validation with DID-based issuer verification
-//! - **XRPC Protocol Support**: Native implementation of AT Protocol's XRPC communication standard
-//! - **DID Resolution Integration**: Automatic DID document resolution and key verification
-//! - **Identity Verification**: Cryptographic verification of JWT signatures using DID documents
-//! - **Authorization Middleware**: Reusable authorization components for Axum and other frameworks
-//! - **Error Handling**: Structured error types for authorization and service operations
+//! XRPC service framework for AT Protocol applications.
 //!
-//! ## Architecture
-//!
-//! The framework provides modular components for building XRPC services:
-//!
-//! - **`authorization`**: JWT validation and DID-based authorization middleware
+//! Build AT Protocol services with JWT authorization, DID resolution,
+//! and cryptographic identity verification middleware.
 //! - **`errors`**: Specialized error types for authorization and XRPC operations
 //!
 //! ## Example Applications