documentation: Updating atproto-lexicon project documentation

crates/atproto-lexicon/README.md

···
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     let http_client = reqwest::Client::new();
-    let dns_resolver = HickoryDnsResolver::create_resolver(vec![]);
+    let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
 
     let resolver = DefaultLexiconResolver::new(http_client, dns_resolver);
 
···
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    // ... setup resolver as above ...
+    let http_client = reqwest::Client::new();
+    let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+    let resolver = DefaultLexiconResolver::new(http_client, dns_resolver);
 
     let config = RecursiveResolverConfig {
         max_depth: 5,  // Maximum recursion depth
···
 let parts = parse_nsid("app.bsky.feed.post#reply", None)?;
 assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
 assert_eq!(parts.fragment, Some("reply".to_string()));
+
+// Convert parsed NSID back to string using Display trait
+println!("Parsed NSID: {}", parts); // Outputs: app.bsky.feed.post#reply
 
 // Convert NSID to DNS name for resolution
 let dns_name = nsid_to_dns_name("app.bsky.feed.post")?;
···
 
 ## Module Structure
 
+- **`errors`**: Structured error types for all lexicon operations
 - **`resolve`**: Core lexicon resolution implementation following AT Protocol specification
 - **`resolve_recursive`**: Recursive resolution with dependency tracking and cycle detection
 - **`validation`**: NSID validation, parsing, and helper functions
···
 Represents a parsed NSID with its component parts and optional fragment:
 - `parts`: Vector of NSID components (e.g., `["app", "bsky", "feed", "post"]`)
 - `fragment`: Optional fragment identifier (e.g., `"reply"` for `#reply`)
+
+Implements `Display` trait for converting back to string format.
 
 ### `RecursiveResolverConfig`
 Configuration for recursive resolution:
···
 
 ## Error Handling
 
-The library uses structured error types for different failure modes:
-- `ValidationError`: NSID format validation errors
-- `ResolveError`: DNS resolution and DID resolution errors
-- Network and XRPC errors are wrapped in `anyhow::Error`
+The library uses structured error types following the project convention `error-atproto-lexicon-<domain>-<number>`:
+
+- **`LexiconResolveError`**: Resolution errors (no DIDs found, invalid DID format, PDS errors)
+- **`LexiconValidationError`**: NSID format and validation errors
+- **`LexiconSchemaError`**: Schema structure and parsing errors
+- **`LexiconRecursiveError`**: Errors specific to recursive resolution
+
+All errors implement the `Error` trait and provide detailed context about failures.
 
 ## Dependencies
 

crates/atproto-lexicon/src/lib.rs

···
 //!
 //! This library provides functionality for resolving and validating AT Protocol lexicons,
 //! which define the schema and structure of AT Protocol data.
+//!
+//! ## Overview
+//!
+//! Lexicons in AT Protocol serve as schema definitions that describe the structure
+//! and types of data that can be stored and transmitted. This library implements
+//! the full lexicon resolution chain as specified by the AT Protocol:
+//!
+//! 1. Convert NSID to DNS name with `_lexicon` prefix
+//! 2. Perform DNS TXT lookup to get the authoritative DID
+//! 3. Resolve the DID to get the DID document
+//! 4. Extract PDS endpoint from the DID document
+//! 5. Make XRPC call to fetch the lexicon schema
+//!
+//! ## Modules
+//!
+//! - [`errors`]: Structured error types for all lexicon operations
+//! - [`resolve`]: Core lexicon resolution implementation
+//! - [`resolve_recursive`]: Recursive resolution with dependency tracking
+//! - [`validation`]: NSID validation, parsing, and helper functions
+//!
+//! ## Example Usage
+//!
+//! ```no_run
+//! # use anyhow::Result;
+//! # #[tokio::main]
+//! # async fn main() -> Result<()> {
+//! use atproto_lexicon::resolve::{DefaultLexiconResolver, LexiconResolver};
+//! use atproto_identity::resolve::HickoryDnsResolver;
+//!
+//! let http_client = reqwest::Client::new();
+//! let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+//! let resolver = DefaultLexiconResolver::new(http_client, dns_resolver);
+//!
+//! // Resolve a lexicon
+//! let lexicon = resolver.resolve("app.bsky.feed.post").await?;
+//! # Ok(())
+//! # }
+//! ```
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]