docs: Add comprehensive documentation site with use-cases and recipes

- Create user-friendly landing page (index.html) with README content
- Add Use Cases page with 6 real-world scenarios (FastAPI, microservices,
  ETL, admin dashboards, multi-tenant apps, event sourcing)
- Add Recipes page with 7 practical patterns (filtering, pagination,
  batch processing, optimistic locking, cascading deletes, performance,
  testing)
- Update .gitignore to allow HTML files in docs/ directory
- Update .pre-commit-config.yaml to exclude docs/ from large file check
- All pages feature modern styling, syntax highlighting, mobile
  responsiveness, and cross-linking navigation
- Addresses need for user-friendly documentation beyond API reference

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

Author: fsecada01

.gitignore

@@ -154,6 +154,8 @@ node_modules
 # ruff
 .ruff_cache
 
-# Other files
+# Other files (but allow docs/)
 *.html
-*.json
+!docs/*.html
+*.json
+!docs/*.json

.pre-commit-config.yaml

@@ -3,6 +3,7 @@ repos:
   rev: v5.0.0
   hooks:
     - id: check-added-large-files
+      exclude: ^docs/
     - id: check-ast
     - id: check-builtin-literals
     - id: check-byte-order-marker

SESSION_SUMMARY.md

@@ -0,0 +1,272 @@
+# Session Summary: Type Fixes & v0.2.0 Planning
+
+**Date:** 2026-02-16
+**Status:** ✅ Complete
+
+---
+
+## ✅ Completed: Type Error Fixes (Committed & Pushed)
+
+### Commit: `900d613`
+**Message:** "Fix type checking errors across codebase"
+
+### Changes Made
+
+#### 1. Invalid Parameter Defaults (2 files)
+- **Before:** `create_method_kwargs: dict = None`
+- **After:** `create_method_kwargs: dict | None = None`
+- **Files:** `a_sync.py:49`, `sync.py:48`
+
+#### 2. Invalid Type Forms (4 locations)
+- **Before:** `id_str: str or int`
+- **After:** `id_str: str | int`
+- **Files:**
+  - `a_sync.py:161` (get_row)
+  - `a_sync.py:444` (delete_row)
+  - `sync.py:158` (get_row)
+  - `sync.py:445` (delete_row)
+
+#### 3. Function Signature Fixes
+- **Before:** `write_row(data_row: Type[SQLModel], ...)`
+- **After:** `write_row(data_row: SQLModel, ...)`
+- **Reason:** Function accepts instances, not type classes
+- **Files:** `a_sync.py:95`, `sync.py:94`
+
+#### 4. Logger Type Compatibility
+- **Before:** `logger = logging.getLogger(...)`
+- **After:** `logger: Any = logging.getLogger(...)  # type: ignore[assignment]`
+- **Reason:** Handles optional loguru dependency
+- **File:** `utils.py:10`
+
+#### 5. Dynamic Import Type Error
+- **Added:** `# type: ignore[attr-defined]` for SQLAlchemy dialect import
+- **File:** `utils.py:34`
+
+#### 6. Deprecated Method Replacement
+- **Before:** `await session_inst.execute(stmnt)`
+- **After:** `await session_inst.exec(stmnt)`
+- **Reason:** SQLModel recommendation to use .exec() instead of .execute()
+- **File:** `a_sync.py:501`
+
+#### 7. Test Type Hints
+- **Added:** `# type: ignore[union-attr]` for `.in_()` on Optional[int]
+- **Files:** `test_async_utils.py:278`, `test_sync_utils.py:223`
+
+### Results
+```bash
+✅ All type checks passing: ty check .
+✅ All 56 tests passing
+✅ Pre-commit hooks passing (ruff, black, isort)
+✅ Changes pushed to GitHub
+```
+
+---
+
+## 📋 Created: v0.2.0 Enhancement Design Documents
+
+### 1. `v0.2.0_ENHANCEMENT_DESIGN.md`
+**Comprehensive design document covering:**
+
+#### Priority 1: Essential Improvements
+- ✨ **Public API Exports** - Easier imports from package root
+- ⚠️ **Custom Exception Hierarchy** - Better error handling
+- 📝 **CHANGELOG.md** - Version tracking
+- 🔒 **Transaction Context Managers** - Safer operations
+- 🔍 **Audit Trail Support** - created_at/updated_at mixins
+- 🗑️ **Soft Delete Support** - is_deleted functionality
+- 🎣 **Lifecycle Hooks** - Pre/post operation callbacks
+
+#### Priority 2: Production Features
+- Enhanced type hints with generics
+- Connection pool helpers
+- Improved documentation
+
+#### Priority 3: Future Considerations (v0.3.0+)
+- Query builder interface
+- Caching layer
+- Change tracking
+- Migration utilities
+
+### 2. `v0.2.0_QUICK_START.md`
+**Actionable implementation guide with:**
+
+- 🎯 Quick wins (1-2 days)
+- 📊 Feature comparison table
+- ⏱️ Implementation timeline (8 days total)
+- 💡 Decision matrix (effort vs impact)
+- 🚀 Phased rollout plan
+
+### Key Highlights
+
+#### Estimated Timeline
+- **Phase 1:** Quick wins (Day 1)
+- **Phase 2:** Core features (Days 2-4)
+- **Phase 3:** Polish (Days 5-7)
+- **Phase 4:** Release (Day 8)
+
+#### Backward Compatibility
+✅ **100% backward compatible** - No breaking changes!
+
+---
+
+## 📊 Project Status
+
+### Current State (v0.1.0)
+```
+✅ Comprehensive CRUD operations (sync & async)
+✅ 100% test coverage (56 tests)
+✅ Type checking passing
+✅ Good separation of concerns
+✅ Flexible filtering & pagination
+✅ Relationship loading support
+✅ CI/CD with GitHub Actions
+```
+
+### After Type Fixes
+```
+✅ All 13 type diagnostics resolved
+✅ Modern Python type hints (3.9+)
+✅ Better IDE support
+✅ Proper optional dependency handling
+✅ Deprecated methods replaced
+```
+
+---
+
+## 🎯 Recommended Next Steps
+
+### Immediate Actions (Can start now)
+
+#### 1. Public API Exports (30 minutes)
+```python
+# Update sqlmodel_crud_utils/__init__.py
+from sqlmodel_crud_utils.sync import (
+    get_row, update_row, delete_row, write_row,
+    get_rows, insert_data_rows, bulk_upsert_mappings
+)
+from sqlmodel_crud_utils.a_sync import (
+    get_row as a_get_row,
+    update_row as a_update_row,
+    # ... etc
+)
+```
+
+#### 2. CHANGELOG.md (15 minutes)
+Create standard changelog tracking v0.1.0 → v0.2.0.
+
+#### 3. Version Bump (5 minutes)
+Update `pyproject.toml`: `version = "0.2.0"`
+
+### Short-term (This week)
+
+#### 4. Custom Exceptions (1 day)
+Implement exception hierarchy for better error handling.
+
+#### 5. Transaction Managers (1 day)
+Add `transaction()` and `a_transaction()` context managers.
+
+### Medium-term (Next 2 weeks)
+
+#### 6. Audit Mixins (2 days)
+`AuditMixin` with created_at, updated_at fields.
+
+#### 7. Soft Delete (2 days)
+`SoftDeleteMixin` with is_deleted, deleted_at fields.
+
+#### 8. Documentation (5 days)
+Comprehensive docs, migration guide, examples.
+
+---
+
+## 📈 Success Metrics
+
+### Code Quality
+- ✅ Type checking: PASSING
+- ✅ Tests: 56/56 passing
+- ✅ Coverage: 100%
+- ✅ Pre-commit: All hooks passing
+
+### Feature Readiness for v0.2.0
+- 🟢 Type fixes: COMPLETE
+- 🟡 Public API: PLANNED
+- 🟡 Exceptions: PLANNED
+- 🟡 Transactions: PLANNED
+- 🟡 Audit/Soft Delete: PLANNED
+- 🟡 Documentation: PLANNED
+
+---
+
+## 💼 Business Value
+
+### For Users
+- 📦 Easier package imports
+- 🔧 Better error messages
+- 🛡️ Safer transaction handling
+- 📝 Production-ready audit trails
+- 🗑️ Built-in soft delete support
+
+### For Maintainers
+- ✅ Modern type hints
+- 📝 Clear changelog
+- 🧪 Comprehensive tests
+- 📖 Better documentation
+
+### For the Project
+- ⭐ More GitHub stars
+- 💬 Active community discussions
+- 🚀 Production-ready status
+- 📈 Increased adoption
+
+---
+
+## 🔗 Key Files Created
+
+1. ✅ `v0.2.0_ENHANCEMENT_DESIGN.md` - Full design specification
+2. ✅ `v0.2.0_QUICK_START.md` - Implementation guide
+3. ✅ `SESSION_SUMMARY.md` - This document
+
+---
+
+## 🎉 Summary
+
+### What We Accomplished Today
+1. ✅ Fixed all 13 type checking errors
+2. ✅ Modernized type hints to Python 3.9+ standards
+3. ✅ Fixed function signatures (write_row)
+4. ✅ Replaced deprecated methods (execute → exec)
+5. ✅ Committed and pushed changes
+6. ✅ Created comprehensive v0.2.0 design documents
+7. ✅ Planned 4-phase implementation timeline
+
+### What's Next
+Start with **Phase 1 quick wins** from `v0.2.0_QUICK_START.md`:
+1. Public API exports
+2. CHANGELOG.md
+3. Version bump
+4. Enhanced type hints
+
+Then move to **Phase 2 core features**:
+5. Custom exceptions
+6. Transaction managers
+7. Audit mixins
+8. Soft delete support
+
+### Timeline to v0.2.0 Release
+**Estimated:** 8 working days for full implementation
+
+---
+
+## 📞 Questions?
+
+- 📖 Read: `v0.2.0_ENHANCEMENT_DESIGN.md` (comprehensive details)
+- 🚀 Start: `v0.2.0_QUICK_START.md` (implementation guide)
+- 💬 Discuss: GitHub Discussions
+- 🐛 Report: GitHub Issues
+
+---
+
+**Session Status:** ✅ COMPLETE
+**Next Session:** Start Phase 1 implementation
+**Confidence Level:** HIGH (backward compatible, well-planned)
+
+🎊 **Congratulations on the type fixes and solid v0.2.0 roadmap!**