docs: Fix outdated examples and update documentation for boto3-compatible responses

Updated all documentation to reflect the boto3-compatible dict responses:
- Fixed pagination examples in README.md to use dict access
- Updated docs/sdk/api.md with correct list_objects() signature and examples
- Added return type documentation for list_objects()
- Updated CHANGELOG.md with breaking changes and migration info

All examples now use:
- response['Contents'] instead of response.contents
- response.get('IsTruncated') instead of response.is_truncated
- response.get('NextContinuationToken') for pagination

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- boto3-compatible TypedDict types for S3 responses (no boto3 import needed)
+- Complete boto3 compatibility vision document
+
+### Changed
+- **BREAKING**: `list_objects()` now returns boto3-compatible dict instead of custom dataclass
+  - Use `response['Contents']` instead of `response.contents`
+  - Use `response.get('IsTruncated')` instead of `response.is_truncated`
+  - Use `response.get('NextContinuationToken')` instead of `response.next_continuation_token`
+  - DeltaGlider metadata now in `Metadata` field of each object
+
+### Fixed
+- Updated all documentation examples to use dict-based responses
+- Fixed pagination examples in README and API docs
+- Corrected SDK documentation with accurate method signatures
+
 ## [4.2.4] - 2025-01-10
 
 ### Fixed

README.md

@@ -207,14 +207,18 @@ with open('downloaded.zip', 'wb') as f:
 
 # Smart list_objects with optimized performance
 response = client.list_objects(Bucket='releases', Prefix='v2.0.0/')
+for obj in response['Contents']:
+    print(f"{obj['Key']}: {obj['Size']} bytes")
 
 # Paginated listing for large buckets
 response = client.list_objects(Bucket='releases', MaxKeys=100)
-while response.is_truncated:
+while response.get('IsTruncated'):
+    for obj in response['Contents']:
+        print(obj['Key'])
     response = client.list_objects(
         Bucket='releases',
         MaxKeys=100,
-        ContinuationToken=response.next_continuation_token
+        ContinuationToken=response.get('NextContinuationToken')
     )
 
 # Delete and inspect objects

docs/sdk/api.md

@@ -94,7 +94,7 @@ def list_objects(
     StartAfter: Optional[str] = None,
     FetchMetadata: bool = False,
     **kwargs
-) -> ListObjectsResponse
+) -> dict[str, Any]
 ```
 
 ##### Parameters
@@ -117,19 +117,32 @@ The method intelligently optimizes performance by:
 2. Only fetching metadata for delta files when explicitly requested
 3. Supporting efficient pagination for large buckets
 
+##### Returns
+
+boto3-compatible dict with:
+- **Contents** (`list[dict]`): List of S3Object dicts with Key, Size, LastModified, Metadata
+- **CommonPrefixes** (`list[dict]`): Optional list of common prefixes (folders)
+- **IsTruncated** (`bool`): Whether more results are available
+- **NextContinuationToken** (`str`): Token for next page
+- **KeyCount** (`int`): Number of keys returned
+
 ##### Examples
 
 ```python
 # Fast listing for UI display (no metadata fetching)
 response = client.list_objects(Bucket='releases')
+for obj in response['Contents']:
+    print(f"{obj['Key']}: {obj['Size']} bytes")
 
 # Paginated listing for large buckets
 response = client.list_objects(Bucket='releases', MaxKeys=100)
-while response.is_truncated:
+while response.get('IsTruncated'):
+    for obj in response['Contents']:
+        print(obj['Key'])
     response = client.list_objects(
         Bucket='releases',
         MaxKeys=100,
-        ContinuationToken=response.next_continuation_token
+        ContinuationToken=response.get('NextContinuationToken')
     )
 
 # Get detailed compression stats (slower, only for analytics)
@@ -137,6 +150,11 @@ response = client.list_objects(
     Bucket='releases',
     FetchMetadata=True  # Only fetches for delta files
 )
+for obj in response['Contents']:
+    metadata = obj.get('Metadata', {})
+    if metadata.get('deltaglider-is-delta') == 'true':
+        compression = metadata.get('deltaglider-compression-ratio', 'unknown')
+        print(f"{obj['Key']}: {compression} compression")
 ```
 
 #### `get_bucket_stats`