documentation: Updating documentation

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

crates/atproto-client/README.md

···
 
 ## Binaries
 
-- **atproto-client-auth**: OAuth authentication flow helper
-- **atproto-client-app-password**: App password management tool
-- **atproto-client-dpop**: DPoP authentication testing tool
+All CLI tools require the `clap` feature:
+
+- **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
 
 ## Usage
 
···
 
 ## Command Line Examples
 
+### Create and Manage Sessions
+
 ```bash
-# Test DPoP authentication
-cargo run --bin atproto-client-dpop \
-  --private-key did:key:zQ3sh... \
-  --access-token token \
-  --issuer did:plc:issuer \
-  --url https://pds.example.com/xrpc/... \
-  --method GET
+# Create an authentication session with username and password
+cargo run --features clap --bin atproto-client-auth -- login alice.example.com my_password
+
+# Use an existing app password for session creation
+cargo run --features clap --bin atproto-client-auth -- session alice.example.com app_password_token
+```
+
+### App Password Authentication
+
+```bash
+# Make an XRPC call using app password Bearer token
+cargo run --features clap --bin atproto-client-app-password -- \
+  did:plc:user123 \
+  your_access_token \
+  com.atproto.repo.listRecords
+```
+
+### DPoP Authentication
+
+```bash
+# Make an authenticated XRPC call using DPoP tokens
+cargo run --features clap --bin atproto-client-dpop -- \
+  did:plc:user123 \
+  did:key:zQ3sh... \
+  your_access_token \
+  com.atproto.repo.getRecord
 ```
 
 ## License

crates/atproto-client/src/lib.rs

···
-//! HTTP client for AT Protocol services with DPoP authentication and XRPC support.
+//! # AT Protocol HTTP Client Library
 //!
-//! Provides binaries:
-//! - `atproto-client-dpop`: Make authenticated XRPC calls using DPoP tokens
-//! - `atproto-client-auth`: Manage app password authentication and sessions
-//! - `atproto-client-app-password`: Make authenticated XRPC calls using Bearer tokens
+//! 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
+//!
+//! ## Architecture
+//!
+//! The library provides both raw HTTP client capabilities and AT Protocol specific abstractions:
+//!
+//! - **`client`**: Core HTTP client with authentication middleware support
+//! - **`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
+//! - **`errors`**: Structured error types for HTTP and authentication failures
+//!
+//! ## Command-Line Tools
+//!
+//! When built with the `clap` feature, provides XRPC client tools:
+//!
+//! - **`atproto-client-dpop`**: Make authenticated XRPC calls using DPoP (Demonstration of Proof-of-Possession) tokens
+//! - **`atproto-client-auth`**: Create and refresh authentication sessions with AT Protocol services
+//! - **`atproto-client-app-password`**: Make authenticated XRPC calls using application-specific Bearer tokens
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]

crates/atproto-identity/src/lib.rs

···
-//! AT Protocol identity management library for DID resolution, handle resolution, and cryptographic key operations.
+//! # 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
 //!
-//! Provides binaries:
-//! - `atproto-identity-resolve`: Resolve handles and DIDs to identity documents
-//! - `atproto-identity-key`: Generate and manage cryptographic keys
-//! - `atproto-identity-sign`: Sign data with private keys
-//! - `atproto-identity-validate`: Validate handles and DIDs
+//! ## 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
+//!
+//! ## Command-Line Tools
+//!
+//! When built with the `clap` feature, provides comprehensive CLI tools:
+//!
+//! - **`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
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]

crates/atproto-jetstream/src/lib.rs

···
-//! WebSocket-based event stream consumer for AT Protocol Jetstream with Zstandard compression.
+//! # AT Protocol Jetstream Consumer Library
 //!
-//! Provides binary:
-//! - `atproto-jetstream-consumer`: Consume and log Jetstream events from AT Protocol relays
+//! 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
+//!
+//! ## Architecture
+//!
+//! The library provides a high-level consumer interface with customizable event handlers:
+//!
+//! - **`consumer`**: Core WebSocket consumer with event handling and connection management
+//!
+//! ## Command-Line Tools
+//!
+//! When built with the `clap` feature, provides Jetstream consumer tools:
+//!
+//! - **`atproto-jetstream-consumer`**: Connect to AT Protocol Jetstream and consume real-time events with Zstandard compression
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]

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

···
 //!
 //! ## Error Categories
 //!
-//! - **`OAuthWorkflowError`** (1 to 8): OAuth workflow operations including PAR, token exchange, and session management
+//! - **`OAuthWorkflowError`** (workflow-1 to workflow-8): OAuth workflow operations including PAR, token exchange, and session management
 //!
 //! ## Error Format
 //!
-//! All errors use the standardized format: `error-atproto-oauth-aip-{number} {message}: {details}`
+//! All errors use the standardized format: `error-atproto-oauth-aip-{domain}-{number} {message}: {details}`
 
 use thiserror::Error;
 
···
 #[derive(Debug, Error)]
 pub enum OAuthWorkflowError {
     /// Failed to send PAR HTTP request.
-    #[error("error-atproto-oauth-aip-1 PAR HTTP request failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-1 PAR HTTP request failed: {0}")]
     ParRequestFailed(#[source] reqwest::Error),
 
     /// Failed to parse PAR response JSON.
-    #[error("error-atproto-oauth-aip-2 PAR HTTP request parse failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-2 PAR HTTP request parse failed: {0}")]
     ParResponseParseFailed(#[source] reqwest::Error),
 
     /// PAR response contained an error.
-    #[error("error-atproto-oauth-aip-3 PAR HTTP response invalid: {message}")]
+    #[error("error-atproto-oauth-aip-workflow-3 PAR HTTP response invalid: {message}")]
     ParResponseInvalid {
         /// Error message from the PAR response.
         message: String,
     },
 
     /// Failed to send token exchange HTTP request.
-    #[error("error-atproto-oauth-aip-4 Token request failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-4 Token request failed: {0}")]
     TokenRequestFailed(#[source] reqwest::Error),
 
     /// Failed to parse token response JSON.
-    #[error("error-atproto-oauth-aip-5 Token response json parsing failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-5 Token response json parsing failed: {0}")]
     TokenResponseParseFailed(#[source] reqwest::Error),
 
     /// Failed to send session exchange HTTP request.
-    #[error("error-atproto-oauth-aip-6 Session request failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-6 Session request failed: {0}")]
     SessionRequestFailed(#[source] reqwest::Error),
 
     /// Failed to parse session response JSON.
-    #[error("error-atproto-oauth-aip-7 Session json parsing failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-7 Session json parsing failed: {0}")]
     SessionResponseParseFailed(#[source] reqwest::Error),
 
     /// Session response contained an error.
-    #[error("error-atproto-oauth-aip-8 Session response invalid: {message}")]
+    #[error("error-atproto-oauth-aip-workflow-8 Session response invalid: {message}")]
     SessionResponseInvalid {
         /// Error message from the session response.
         message: String,

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

···
 //! use atproto_oauth_aip::workflow::{oauth_init, oauth_complete, session_exchange, OAuthClient};
 //! use atproto_oauth::resources::AuthorizationServer;
 //! use atproto_oauth::workflow::OAuthRequestState;
-//! 
+//!
 //! let http_client = reqwest::Client::new();
 //! let oauth_client = OAuthClient {
 //!     redirect_uri: "https://redirect.example.com/callback".to_string(),
 //!     client_id: "client123".to_string(),
 //!     client_secret: "secret456".to_string(),
 //! };
-//! 
+//!
 //! let authorization_server = AuthorizationServer {
 //!     issuer: "https://auth.example.com".to_string(),
 //!     authorization_endpoint: "https://auth.example.com/authorize".to_string(),
···
 //!     dpop_signing_alg_values_supported: vec!["ES256".to_string()],
 //!     client_id_metadata_document_supported: true,
 //! };
-//! 
+//!
 //! let oauth_request_state = OAuthRequestState {
 //!     state: "random-state".to_string(),
 //!     nonce: "random-nonce".to_string(),
 //!     code_challenge: "code-challenge".to_string(),
 //!     scope: "atproto transition:generic".to_string(),
 //! };
-//! 
+//!
 //! // Initialize OAuth flow with PAR
 //! let par_response = oauth_init(
 //!     &http_client,
···
 //!     &authorization_server,
 //!     &oauth_request_state
 //! ).await?;
-//! 
+//!
 //! // Complete OAuth flow with authorization code
 //! # let oauth_request = atproto_oauth::workflow::OAuthRequest {
 //! #     oauth_state: "state".to_string(),
···
 //!     "authorization_code",
 //!     &oauth_request
 //! ).await?;
-//! 
+//!
 //! // Exchange tokens for AT Protocol session
 //! # let protected_resource = atproto_oauth::resources::OAuthProtectedResource {
 //! #     resource: "https://pds.example.com".to_string(),

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

···
-//! Axum web handlers for AT Protocol OAuth 2.0 client endpoints with DPoP support.
+//! # 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
+//!
+//! ## Architecture
+//!
+//! The library provides Axum-compatible handlers and state management:
 //!
-//! Provides binary:
-//! - `atproto-oauth-tool`: OAuth client for login and token refresh operations
+//! - **`handle_init`**: OAuth authorization initiation handler
+//! - **`handle_complete`**: OAuth callback and completion handler  
+//! - **`handle_jwks`**: JWKS (JSON Web Key Set) endpoint handler
+//! - **`handler_metadata`**: OAuth authorization server metadata handler
+//! - **`state`**: Shared application state management for OAuth operations
+//! - **`errors`**: Specialized error types for web handler operations
+//!
+//! ## Command-Line Tools
+//!
+//! When built with the `clap` feature, provides OAuth management tools:
+//!
+//! - **`atproto-oauth-tool`**: Command-line OAuth login, token management, and workflow testing
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]

crates/atproto-oauth/README.md

···
 - **Request storage**: LRU cache-based OAuth request storage
 - **Structured errors**: Comprehensive error handling with detailed error codes
 
-## Binaries
-
-All CLI tools require the `clap` feature and are provided via the atproto-oauth-axum crate:
-
-- **atproto-oauth-tool**: OAuth authentication workflow management
-
-
 ## Usage
 
 ### JWT Operations

crates/atproto-xrpcs/README.md

···
 
 `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.
 
-## Binaries
-
-- **atproto-xrpcs-helloworld**: Complete example XRPC service with DID:web functionality (via atproto-xrpcs-helloworld crate)
+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.
 
 ## Features
 

crates/atproto-xrpcs/src/lib.rs

···
-//! XRPC service components for AT Protocol with JWT authorization and DID verification.
+//! # 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
+//!
+//! ## Architecture
+//!
+//! The framework provides modular components for building XRPC services:
 //!
-//! Provides binaries:
-//! - `atproto-xrpcs-helloworld`: Complete example XRPC service with DID:web functionality (via atproto-xrpcs-helloworld crate)
+//! - **`authorization`**: JWT validation and DID-based authorization middleware
+//! - **`errors`**: Specialized error types for authorization and XRPC operations
+//!
+//! ## Example Applications
+//!
+//! Complete example services demonstrating framework usage:
+//!
+//! - **`atproto-xrpcs-helloworld`**: Complete example XRPC service with DID:web functionality and authorization
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]