refactor: Removed issuedAt field as required signature field.

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

crates/atproto-record/README.md

···
 # atproto-record
 
-Cryptographic signature operations for AT Protocol records.
+Cryptographic signature operations and utilities for AT Protocol records.
 
 ## Overview
 
-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.
+A comprehensive Rust library for working with AT Protocol records, providing cryptographic signature creation and verification, AT-URI parsing, and datetime utilities. Built on IPLD DAG-CBOR serialization with support for P-256, P-384, and K-256 elliptic curve cryptography.
 
 ## Features
 
-- **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
+- **Record signing**: Create cryptographic signatures on AT Protocol records following community.lexicon.attestation.signature specification
+- **Signature verification**: Verify record signatures against public keys with issuer validation
+- **AT-URI parsing**: Parse and validate AT Protocol URIs (at://authority/collection/record_key) with robust error handling
+- **IPLD serialization**: DAG-CBOR serialization ensuring deterministic and verifiable record encoding
+- **Multi-curve support**: Full support for P-256, P-384, and K-256 elliptic curve signatures
+- **DateTime utilities**: RFC 3339 datetime serialization with millisecond precision for consistent timestamp handling
+- **Structured errors**: Type-safe error handling following project conventions with detailed error messages
 
 ## CLI Tools
 
 The following command-line tools are available when built with the `clap` feature:
 
-- **`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
+- **`atproto-record-sign`**: Sign AT Protocol records with private keys, supporting flexible argument ordering
+- **`atproto-record-verify`**: Verify AT Protocol record signatures by validating cryptographic signatures against issuer DIDs and public keys
 
 ## Library Usage
 
···
 use atproto_identity::key::identify_key;
 use serde_json::json;
 
+// Parse the signing key from a did:key
 let key_data = identify_key("did:key:zQ3sh...")?;
-let record = json!({"$type": "app.bsky.feed.post", "text": "Hello!"});
-let signature_object = json!({"issuer": "did:plc:issuer", "issuedAt": "2024-01-01T00:00:00Z"});
+
+// The record to sign
+let record = json!({"$type": "app.bsky.feed.post", "text": "Hello world!"});
+
+// Signature metadata (issuer is required, other fields are optional)
+let signature_object = json!({
+    "issuer": "did:plc:issuer"
+    // Optional: "issuedAt", "purpose", "expiry", etc.
+});
 
+// Create the signed record with embedded signatures array
 let signed_record = signature::create(
     &key_data,
     &record,
-    "did:plc:repo",
+    "did:plc:repository",
     "app.bsky.feed.post",
     signature_object
 ).await?;
···
 ### Verifying Signatures
 
 ```rust
+use atproto_record::signature;
+use atproto_identity::key::identify_key;
+
+// Parse the public key for verification
 let issuer_key = identify_key("did:key:zQ3sh...")?;
 
+// Verify the signature (throws error if invalid)
 signature::verify(
-    "did:plc:issuer",
-    &issuer_key,
-    signed_record,
-    "did:plc:repo",
-    "app.bsky.feed.post"
+    "did:plc:issuer",      // Expected issuer DID
+    &issuer_key,           // Public key for verification
+    signed_record,         // The signed record
+    "did:plc:repository",  // Repository context
+    "app.bsky.feed.post"   // Collection context
 ).await?;
 ```
 
···
 use atproto_record::aturi::ATURI;
 use std::str::FromStr;
 
+// Parse an AT-URI into its components
 let aturi = ATURI::from_str("at://did:plc:abc123/app.bsky.feed.post/3k2k4j5h6g")?;
-println!("Authority: {}", aturi.authority);
-println!("Collection: {}", aturi.collection);
-println!("Record Key: {}", aturi.record_key);
+
+// Access the parsed components
+println!("Authority: {}", aturi.authority);   // "did:plc:abc123"
+println!("Collection: {}", aturi.collection);  // "app.bsky.feed.post"
+println!("Record Key: {}", aturi.record_key);  // "3k2k4j5h6g"
+
+// The Display trait formats back to a valid AT-URI
+println!("Full URI: {}", aturi);  // "at://did:plc:abc123/app.bsky.feed.post/3k2k4j5h6g"
+```
+
+### DateTime Utilities
+
+```rust
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+// Use the datetime module for consistent RFC 3339 formatting
+#[derive(Serialize, Deserialize)]
+struct Record {
+    #[serde(with = "atproto_record::datetime::format")]
+    created_at: DateTime<Utc>,
+    
+    #[serde(with = "atproto_record::datetime::optional_format")]
+    updated_at: Option<DateTime<Utc>>,
+}
 ```
 
 ## Command Line Usage
···
 cargo build --features clap --bins
 
 # Sign a record
-cargo run --features clap --bin atproto-record-sign -- did:key:zQ3sh... did:plc:issuer record.json \
-  repository=did:plc:repo collection=app.bsky.feed.post
+cargo run --features clap --bin atproto-record-sign -- \
+  did:key:zQ3sh...                    # Signing key (did:key format)
+  did:plc:issuer                      # Issuer DID
+  record.json                          # Record file (or use -- for stdin)
+  repository=did:plc:repo              # Repository context
+  collection=app.bsky.feed.post        # Collection type
+
+# Sign with custom fields (e.g., issuedAt, purpose, expiry)
+cargo run --features clap --bin atproto-record-sign -- \
+  did:key:zQ3sh... did:plc:issuer record.json \
+  repository=did:plc:repo collection=app.bsky.feed.post \
+  issuedAt="2024-01-01T00:00:00.000Z" purpose="attestation"
 
 # Verify a signature
-cargo run --features clap --bin atproto-record-verify -- did:plc:issuer did:key:zQ3sh... signed.json \
+cargo run --features clap --bin atproto-record-verify -- \
+  did:plc:issuer                      # Expected issuer DID
+  did:key:zQ3sh...                    # Verification key
+  signed.json                          # Signed record file
+  repository=did:plc:repo              # Repository context (must match signing)
+  collection=app.bsky.feed.post        # Collection type (must match signing)
+
+# Read from stdin
+echo '{"text":"Hello"}' | cargo run --features clap --bin atproto-record-sign -- \
+  did:key:zQ3sh... did:plc:issuer -- \
   repository=did:plc:repo collection=app.bsky.feed.post
 ```
 

crates/atproto-record/src/aturi.rs

···
-//! AT-URI parsing and validation.
+//! AT-URI parsing and validation for AT Protocol record identification.
+//!
+//! This module provides functionality to parse and validate AT Protocol URIs (AT-URIs),
+//! which are used to uniquely identify records within the AT Protocol ecosystem.
+//! 
+//! ## AT-URI Format
 //!
-//! 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
+//! AT-URIs follow the format: `at://authority/collection/record_key`
+//!
+//! - **authority**: A DID (Decentralized Identifier) - either did:plc or did:web
+//! - **collection**: An NSID (Namespaced Identifier) specifying the record type
+//! - **record_key**: A unique identifier for the specific record within the collection
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use atproto_record::aturi::ATURI;
+//! use std::str::FromStr;
+//!
+//! let uri = "at://did:plc:abc123/app.bsky.feed.post/3k2k4j5h6g";
+//! let aturi = ATURI::from_str(uri)?;
+//!
+//! assert_eq!(aturi.authority, "did:plc:abc123");
+//! assert_eq!(aturi.collection, "app.bsky.feed.post");
+//! assert_eq!(aturi.record_key, "3k2k4j5h6g");
+//! ```
+//!
+//! ## Validation Rules
+//!
+//! - Must start with the `at://` scheme
+//! - Authority must be a valid DID (handles are not supported)
+//! - Collection and record_key must be non-empty
+//! - Trailing slashes are not permitted
 
 use std::fmt;
 use std::str::FromStr;
···
 
 /// Represents a parsed AT Protocol URI (AT-URI).
 ///
-/// AT-URIs are used to identify specific records within AT Protocol repositories.
-/// They consist of three components: authority (DID), collection (NSID), and record key.
+/// AT-URIs uniquely identify records within AT Protocol repositories by combining
+/// three essential components: authority (DID), collection (NSID), and record key.
+/// 
+/// This struct provides validated access to these components after successful parsing
+/// and implements `Display` for reconstructing the original URI format.
 #[cfg_attr(debug_assertions, derive(Debug))]
 #[derive(Clone)]
 pub struct ATURI {

crates/atproto-record/src/bin/atproto-record-sign.rs

···
-//! CLI tool for signing AT Protocol records.
+//! Command-line tool for signing AT Protocol records with cryptographic signatures.
+//!
+//! This tool creates cryptographic signatures on AT Protocol records using ECDSA
+//! signatures with IPLD DAG-CBOR serialization. It supports flexible argument
+//! ordering and customizable signature metadata.
 
 use anyhow::Result;
 use atproto_identity::{
···
 };
 use atproto_record::errors::CliError;
 use atproto_record::signature::create;
-use chrono::{SecondsFormat, Utc};
 use clap::Parser;
 use serde_json::json;
 use std::{
···
 signed record with embedded signature metadata.
 
 The tool accepts flexible argument ordering with DID keys, issuer DIDs, record
-inputs, and key=value parameters for repository and collection context.
+inputs, and key=value parameters for repository, collection, and custom metadata.
 
 REQUIRED PARAMETERS:
   repository=<DID>        Repository context for the signature
   collection=<name>       Collection type context for the signature
+
+OPTIONAL PARAMETERS:
+  Any additional key=value pairs are included in the signature metadata
+  (e.g., issuedAt=<timestamp>, purpose=<string>, expiry=<timestamp>)
 
 EXAMPLES:
   # Basic usage:
···
     repository=did:plc:4zutorghlchjxzgceklue4la \\
     collection=app.bsky.feed.post
 
+  # With custom metadata:
+  atproto-record-sign \\
+    did:key:z42tv1pb3... ./post.json did:plc:issuer... \\
+    repository=did:plc:repo... collection=app.bsky.feed.post \\
+    issuedAt=\"2024-01-01T00:00:00.000Z\" purpose=\"attestation\"
+
   # Reading from stdin:
   echo '{\"text\":\"Hello!\"}' | atproto-record-sign \\
     did:key:z42tv1pb3... -- did:plc:issuer... \\
     repository=did:plc:repo... collection=app.bsky.feed.post
 
 SIGNATURE PROCESS:
-  - Creates $sig object with repository and collection context
+  - Creates $sig object with repository, collection, and custom metadata
   - Serializes record using IPLD DAG-CBOR format
-  - Generates ECDSA signatures using P-256 or K-256 curves
-  - Embeds signatures with issuer metadata
+  - Generates ECDSA signatures using P-256, P-384, or K-256 curves
+  - Embeds signatures with issuer and any provided metadata
 "
 )]
 struct Args {
···
 
     // Write "issuer" key to signature_extras
     signature_extras.insert("issuer".to_string(), issuer);
-
-    // If signature_extras does not contain "issued_at" key, create a RFC 3339 formatted timestamp
-    if !signature_extras.contains_key("issuedAt") {
-        let timestamp = Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true);
-        signature_extras.insert("issuedAt".to_string(), timestamp);
-    }
 
     let signature_object = json!(signature_extras);
     let signed_record = create(

crates/atproto-record/src/bin/atproto-record-verify.rs

···
-//! CLI tool for verifying AT Protocol record signatures.
+//! Command-line tool for verifying cryptographic signatures on AT Protocol records.
+//!
+//! This tool validates signatures on AT Protocol records by reconstructing the
+//! signed content and verifying ECDSA signatures against public keys. It ensures
+//! that records have valid signatures from specified issuers.
 
 use anyhow::Result;
 use atproto_identity::{

crates/atproto-record/src/datetime.rs

···
 //! DateTime serialization utilities for AT Protocol records.
 //!
-//! This module provides Serde serialization and deserialization functions for DateTime<Utc>
-//! values with RFC 3339 formatting, including support for optional datetime fields.
-//! Used for consistent datetime handling across AT Protocol record structures.
+//! This module provides specialized Serde serialization and deserialization functions
+//! for `DateTime<Utc>` values, ensuring consistent RFC 3339 formatting with millisecond
+//! precision across all AT Protocol record structures.
+//!
+//! ## Usage
+//!
+//! These modules are designed to be used with Serde's `#[serde(with = "...")]` attribute:
+//!
+//! ```ignore
+//! use chrono::{DateTime, Utc};
+//! use serde::{Deserialize, Serialize};
+//!
+//! #[derive(Serialize, Deserialize)]
+//! struct Signature {
+//!     #[serde(with = "atproto_record::datetime::format")]
+//!     issued_at: DateTime<Utc>,
+//!     
+//!     #[serde(with = "atproto_record::datetime::optional_format")]
+//!     expires_at: Option<DateTime<Utc>>,
+//! }
+//! ```
 //!
 //! ## Modules
 //!
-//! - [`format`] - Required datetime field serialization in RFC 3339 format with milliseconds
-//! - [`optional_format`] - Optional datetime field serialization handling None values
+//! - [`format`] - Required datetime field serialization with RFC 3339 millisecond precision
+//! - [`optional_format`] - Optional datetime field serialization with proper None handling
 
-/// Required datetime field serialization in RFC 3339 format with milliseconds.
+/// Required datetime field serialization with RFC 3339 formatting.
 ///
-/// Provides serde serialization functions for DateTime<Utc> values
-/// using RFC 3339 formatting with millisecond precision.
+/// This module provides serde serialization/deserialization for `DateTime<Utc>` values,
+/// ensuring consistent RFC 3339 format with millisecond precision (e.g., "2024-01-01T12:00:00.000Z").
+/// Use with `#[serde(with = "atproto_record::datetime::format")]` on required datetime fields.
 pub mod format {
     use chrono::{DateTime, SecondsFormat, Utc};
     use serde::{self, Deserialize, Deserializer, Serializer};
 
-    /// Serializes a DateTime<Utc> to RFC 3339 format with milliseconds.
+    /// Serializes a `DateTime<Utc>` to RFC 3339 string with millisecond precision.
     pub fn serialize<S>(date: &DateTime<Utc>, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: Serializer,
···
         serializer.serialize_str(&s)
     }
 
-    /// Deserializes an RFC 3339 string to DateTime<Utc>.
+    /// Deserializes an RFC 3339 formatted string to `DateTime<Utc>`.
     pub fn deserialize<'de, D>(deserializer: D) -> Result<DateTime<Utc>, D::Error>
     where
         D: Deserializer<'de>,
···
     }
 }
 
-/// Optional datetime field serialization handling None values.
+/// Optional datetime field serialization with None value support.
 ///
-/// Provides serde serialization functions for Option<DateTime<Utc>> values
-/// using RFC 3339 formatting with proper None handling.
+/// This module provides serde serialization/deserialization for `Option<DateTime<Utc>>` values,
+/// handling both Some values (formatted as RFC 3339 with milliseconds) and None values gracefully.
+/// Use with `#[serde(with = "atproto_record::datetime::optional_format")]` on optional datetime fields.
 pub mod optional_format {
     use chrono::{DateTime, SecondsFormat, Utc};
     use serde::{self, Deserialize, Deserializer, Serializer};
 
-    /// Serializes an Option<DateTime<Utc>> to RFC 3339 format with milliseconds.
+    /// Serializes an `Option<DateTime<Utc>>` to RFC 3339 string or null.
     pub fn serialize<S>(date: &Option<DateTime<Utc>>, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: Serializer,
···
         serializer.serialize_str(&s)
     }
 
-    /// Deserializes an optional RFC 3339 string to Option<DateTime<Utc>>.
+    /// Deserializes an optional RFC 3339 string to `Option<DateTime<Utc>>`.
     pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<DateTime<Utc>>, D::Error>
     where
         D: Deserializer<'de>,

crates/atproto-record/src/errors.rs

···
 //! Structured error types for AT Protocol record operations.
 //!
-//! Comprehensive error handling for AT Protocol record signature verification and AT-URI parsing
-//! operations using structured error types with the `thiserror` library. All errors follow the
-//! project convention of prefixed error codes with descriptive messages.
+//! This module provides comprehensive error handling for all AT Protocol record operations
+//! using type-safe error enums powered by the `thiserror` library. All errors follow the
+//! project's standardized naming convention for consistent error reporting and debugging.
 //!
 //! ## Error Categories
 //!
-//! - **`VerificationError`** (verification-1 to verification-11): Record signature verification and creation errors
-//! - **`AturiError`** (aturi-1 to aturi-9): AT-URI parsing and validation errors
-//! - **`CliError`** (cli-1 to cli-8): Command-line interface specific errors including file I/O, DID validation, and argument parsing
+//! ### `VerificationError` (Domain: verification)
+//! Errors related to cryptographic signature creation and verification operations.
+//! Error codes: verification-1 through verification-11
+//!
+//! ### `AturiError` (Domain: aturi)
+//! Errors occurring during AT-URI parsing and validation.
+//! Error codes: aturi-1 through aturi-9
+//!
+//! ### `CliError` (Domain: cli)
+//! Command-line interface specific errors for file I/O, argument parsing, and DID validation.
+//! Error codes: cli-1 through cli-8
 //!
 //! ## Error Format
 //!
-//! All errors use the standardized format: `error-atproto-record-{domain}-{number} {message}: {details}`
+//! All errors follow the standardized format:
+//! ```text
+//! error-atproto-record-{domain}-{number} {message}: {details}
+//! ```
+//!
+//! ## Example Usage
+//!
+//! ```ignore
+//! use atproto_record::errors::VerificationError;
+//!
+//! fn verify_signature() -> Result<(), VerificationError> {
+//!     // Verification logic
+//!     Err(VerificationError::NoSignaturesField)
+//! }
+//! ```
 
 use thiserror::Error;
 
-/// Represents errors that can occur during record signature verification operations.
+/// Errors that can occur during record signature creation and verification.
 ///
-/// These errors relate to various stages of the signature verification process
-/// for AT Protocol records, from parsing to cryptographic validation.
+/// This enum covers all failure modes in the signature lifecycle, from creating
+/// signatures with missing metadata fields to verifying signatures with invalid
+/// cryptographic proofs or serialization failures.
 #[derive(Debug, Error)]
 pub enum VerificationError {
     /// Error when no signatures field is found in the record.
···
     /// Error when signature object is missing required fields.
     ///
     /// This error occurs when the signature object is missing fields that are
-    /// necessary during signature creation, such as 'issuer' or
-    /// 'issuedAt'.
+    /// necessary during signature creation, such as 'issuer'.
     #[error("error-atproto-record-verification-8 Signature object missing field: {field}")]
     SignatureObjectMissingField {
         /// The name of the missing field
···
     },
 }
 
-/// Represents errors that can occur during AT-URI parsing operations.
+/// Errors that can occur during AT-URI parsing and validation.
 ///
-/// These errors relate to various stages of parsing AT-URIs into their
-/// component parts (authority, collection, record key).
+/// This enum covers all validation failures when parsing AT-URIs, including
+/// format violations, missing components, and invalid authority types.
 #[derive(Debug, Error)]
 pub enum AturiError {
     /// Error when AT-URI does not start with the required "at://" prefix.
···
     EmptyRecordKey,
 }
 
-/// Error types that can occur in CLI tools.
+/// Errors specific to command-line interface operations.
 ///
-/// These errors represent failures specific to command-line interface operations
-/// such as file I/O, JSON parsing, DID validation, and missing required arguments.
+/// This enum covers failures in CLI argument parsing, file I/O operations,
+/// JSON processing, and DID validation that occur in the binary tools.
 #[derive(Debug, Error)]
 pub enum CliError {
     /// Occurs when DID method is not supported

crates/atproto-record/src/lib.rs

···
-//! Cryptographic signature operations for AT Protocol records.
+//! Cryptographic signature operations and utilities for 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.
+//! This library provides comprehensive functionality for working with AT Protocol records,
+//! including cryptographic signature creation and verification, AT-URI parsing, and
+//! datetime serialization utilities. Built on IPLD DAG-CBOR for deterministic encoding
+//! with support for P-256, P-384, and K-256 elliptic curve cryptography.
+//!
+//! ## Main Features
+//!
+//! - **Signature Operations**: Create and verify cryptographic signatures following the
+//!   community.lexicon.attestation.signature specification
+//! - **AT-URI Support**: Parse and validate AT Protocol URIs for record identification
+//! - **DateTime Utilities**: RFC 3339 datetime serialization with millisecond precision
+//! - **Type-Safe Errors**: Structured error types following project conventions
+//!
+//! ## Example Usage
+//!
+//! ```ignore
+//! use atproto_record::signature;
+//! use atproto_identity::key::identify_key;
+//! use serde_json::json;
+//!
+//! // Sign a record
+//! let key_data = identify_key("did:key:...")?;
+//! let record = json!({"$type": "app.bsky.feed.post", "text": "Hello!"});
+//! let sig_obj = json!({"issuer": "did:plc:..."});
+//!
+//! let signed = signature::create(&key_data, &record, "did:plc:repo", 
+//!                                "app.bsky.feed.post", sig_obj).await?;
+//!
+//! // Verify a signature
+//! signature::verify("did:plc:issuer", &key_data, signed,
+//!                   "did:plc:repo", "app.bsky.feed.post").await?;
+//! ```
 
 #![forbid(unsafe_code)]
 #![warn(missing_docs)]
 
-/// Structured error types for signature verification operations.
+/// Structured error types for record operations.
 ///
-/// This module defines comprehensive error types that can occur during
-/// AT Protocol record signature verification, following the project's
-/// error naming conventions.
+/// Comprehensive error handling for signature verification, AT-URI parsing,
+/// and CLI operations. All errors follow the project's standardized format:
+/// `error-atproto-record-{domain}-{number} {message}: {details}`
 pub mod errors;
 
-/// Core signature creation and verification functions.
+/// Core signature creation and verification.
 ///
-/// This module provides the primary functionality for creating and verifying
-/// cryptographic signatures on AT Protocol records, with proper handling of
-/// signature objects and IPLD serialization.
+/// Provides functions for creating and verifying cryptographic signatures on
+/// AT Protocol records using IPLD DAG-CBOR serialization. Supports the
+/// community.lexicon.attestation.signature specification with proper $sig
+/// object handling and multiple signature support.
 pub mod signature;
 
+/// AT-URI parsing and validation.
+///
+/// Parse and validate AT Protocol URIs (at://authority/collection/record_key)
+/// for identifying records within repositories. Supports both did:plc and
+/// did:web authority types with comprehensive validation.
 pub mod aturi;
 
+/// DateTime serialization utilities.
+///
+/// RFC 3339 datetime serialization modules for consistent timestamp handling
+/// across AT Protocol records. Includes support for both required and optional
+/// datetime fields with millisecond precision.
 pub mod datetime;

crates/atproto-record/src/signature.rs

···
-//! AT Protocol record signature operations.
+//! AT Protocol record signature creation and verification.
+//!
+//! This module provides comprehensive functionality for creating and verifying
+//! cryptographic signatures on AT Protocol records following the
+//! community.lexicon.attestation.signature specification.
+//!
+//! ## Signature Process
+//!
+//! 1. **Signing**: Records are augmented with a `$sig` object containing issuer,
+//!    timestamp, and context information, then serialized using IPLD DAG-CBOR
+//!    for deterministic encoding before signing with ECDSA.
+//!
+//! 2. **Storage**: Signatures are stored in a `signatures` array within the record,
+//!    allowing multiple signatures from different issuers.
+//!
+//! 3. **Verification**: The original signed content is reconstructed by replacing
+//!    the signatures array with the appropriate `$sig` object, then verified
+//!    using the issuer's public key.
+//!
+//! ## Supported Curves
+//!
+//! - P-256 (NIST P-256 / secp256r1)
+//! - P-384 (NIST P-384 / secp384r1)  
+//! - K-256 (secp256k1)
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use atproto_record::signature::{create, verify};
+//! use atproto_identity::key::identify_key;
+//! use serde_json::json;
+//!
+//! // Create a signature
+//! let key = identify_key("did:key:...")?;
+//! let record = json!({"text": "Hello!"});
+//! let sig_obj = json!({
+//!     "issuer": "did:plc:issuer"
+//!     // Optional: any additional fields like "issuedAt", "purpose", etc.
+//! });
 //!
-//! Sign and verify AT Protocol records using elliptic curve signatures
-//! with IPLD DAG-CBOR serialization and proper $sig object handling.
+//! let signed = create(&key, &record, "did:plc:repo",
+//!                     "app.bsky.feed.post", sig_obj).await?;
+//!
+//! // Verify the signature
+//! verify("did:plc:issuer", &key, signed,
+//!        "did:plc:repo", "app.bsky.feed.post").await?;
+//! ```
 
 use atproto_identity::key::{KeyData, sign, validate};
 use serde_json::json;
···
 
 use crate::errors::VerificationError;
 
-/// Signs an AT Protocol record.
+/// Creates a cryptographic signature for an AT Protocol record.
 ///
-/// This function generates a signature for the provided record using the specified
-/// key data and context information. The signature is embedded into the record
-/// following AT Protocol signature conventions.
+/// This function generates a signature following the community.lexicon.attestation.signature
+/// specification. The record is augmented with a `$sig` object containing context information,
+/// serialized using IPLD DAG-CBOR, signed with the provided key, and the signature is added
+/// to a `signatures` array in the returned record.
 ///
 /// # Parameters
 ///
-/// * `key_data` - The cryptographic key information wrapped in KeyData
-/// * `record` - The JSON record to be signed
-/// * `repository` - The repository DID context for the signature
-/// * `collection` - The collection name context for the signature  
-/// * `signature_object` - Optional additional fields for the signature object
+/// * `key_data` - The signing key (private key) wrapped in KeyData
+/// * `record` - The JSON record to be signed (will not be modified)
+/// * `repository` - The repository DID where this record will be stored
+/// * `collection` - The collection type (NSID) for this record
+/// * `signature_object` - Metadata for the signature, must include:
+///   - `issuer`: The DID of the entity creating the signature (required)
+///   - Additional custom fields are preserved in the signature (optional)
 ///
 /// # Returns
 ///
-/// Returns the original record with a `signatures` field containing the new signature.
+/// Returns a new record containing:
+/// - All original record fields
+/// - A `signatures` array with the new signature appended
+/// - No `$sig` field (only used during signing)
 ///
 /// # Errors
 ///
-/// Returns an error if:
-/// - IPLD serialization fails
-/// - Cryptographic signing fails
-/// - JSON manipulation fails
+/// Returns [`VerificationError`] if:
+/// - Required field `issuer` is missing from signature_object
+/// - IPLD DAG-CBOR serialization fails
+/// - Cryptographic signing operation fails
+/// - JSON structure manipulation fails
 pub async fn create(
     key_data: &KeyData,
     record: &serde_json::Value,
···
         if !record_map.contains_key("issuer") {
             return Err(VerificationError::SignatureObjectMissingField {
                 field: "issuer".to_string(),
-            });
-        }
-        if !record_map.contains_key("issuedAt") {
-            return Err(VerificationError::SignatureObjectMissingField {
-                field: "issuedAt".to_string(),
             });
         }
     } else {
···
         record_map.insert("$sig".to_string(), sig);
     }
 
-    {
-        let thing = serde_json::to_string_pretty(&signing_record).expect("yeah");
-        println!("{}", &thing);
-    }
 
     // Create a signature.
     let serialized_signing_record = serde_ipld_dagcbor::to_vec(&signing_record)?;
···
 
 /// Verifies a cryptographic signature on an AT Protocol record.
 ///
-/// This function validates that the provided record contains a valid signature
-/// from the specified issuer using the provided public key. It reconstructs
-/// the signed content and verifies the cryptographic signature.
+/// This function validates signatures by reconstructing the original signed content
+/// (record with `$sig` object) and verifying the ECDSA signature against it.
+/// It searches through all signatures in the record to find one matching the
+/// specified issuer, then verifies it with the provided public key.
 ///
 /// # Parameters
 ///
-/// * `issuer` - The DID of the expected signature issuer
-/// * `key_data` - The public key information for verification
-/// * `record` - The signed JSON record to verify
-/// * `repository` - The repository DID context for verification
-/// * `collection` - The collection name context for verification
+/// * `issuer` - The DID of the expected signature issuer to verify
+/// * `key_data` - The public key for signature verification
+/// * `record` - The signed record containing a `signatures` or `sigs` array
+/// * `repository` - The repository DID used during signing (must match)
+/// * `collection` - The collection type used during signing (must match)
 ///
 /// # Returns
 ///
-/// Returns `Ok(())` if a valid signature from the issuer is found and verified.
+/// Returns `Ok(())` if a valid signature from the specified issuer is found
+/// and successfully verified against the reconstructed signed content.
 ///
 /// # Errors
 ///
-/// Returns a [`VerificationError`] if:
-/// - No signatures field is found in the record
+/// Returns [`VerificationError`] if:
+/// - No `signatures` or `sigs` field exists in the record
 /// - No signature from the specified issuer is found
-/// - Signature decoding or parsing fails
-/// - Cryptographic verification fails
-/// - Record serialization fails
+/// - The issuer's signature is malformed or missing required fields
+/// - Base64 decoding of the signature fails
+/// - IPLD DAG-CBOR serialization of reconstructed content fails
+/// - Cryptographic verification fails (invalid signature)
+///
+/// # Note
+///
+/// This function supports both `signatures` and `sigs` field names for
+/// backward compatibility with different AT Protocol implementations.
 pub async fn verify(
     issuer: &str,
     key_data: &KeyData,