feat: Improve test coverage to 59% and prepare for PyPI release

- Add integration tests for embeddings, search, and index modules
- Add unit tests for empathy_adapter, guard, schemas, and other modules
- Fix datetime deprecation warning in empathy_adapter.py
- Add dotenv loading to CLI for automatic .env file support
- Update configuration with .memdocs.yml
- Add comprehensive documentation files

Coverage improvements:
- Overall: 44% → 59%
- Embeddings: 22% → 84%
- Search: 16% → 88%
- Index: 20% → 88%
- Empathy adapter: 0% → 95%
- Guard: 81% → 100%

All 96 tests passing with 0 warnings

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

Co-Authored-By: Claude <[email protected]>

Author: GeneAI

.env.example

@@ -0,0 +1,15 @@
+# MemDocs Environment Variables
+
+# Anthropic API Key (required for summarization)
+# Get your key at: https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+# Empathy API Key (optional, only if using Empathy Cloud)
+# EMPATHY_API_KEY=your-empathy-key-here
+
+# OpenAI API Key (optional, only if using OpenAI embeddings)
+# OPENAI_API_KEY=sk-your-openai-key-here
+
+# Development/Testing
+# Set to 'true' to enable debug mode
+# DEBUG=false

.memdocs.yml

@@ -0,0 +1,57 @@
+version: 1
+
+# Scope policy (controls memory granularity)
+policies:
+  default_scope: file          # file | module | repo
+  max_files_without_force: 150
+
+  # Auto-escalate for important changes
+  escalate_on:
+    - cross_module_changes      # Multi-module = bigger context needed
+    - security_sensitive_paths  # auth/*, security/* = document thoroughly
+    - public_api_signatures     # API changes = team needs to know
+
+# Output configuration (git-committed memory)
+outputs:
+  docs_dir: .memdocs/docs       # Committed to git
+  memory_dir: .memdocs/memory   # Committed to git
+  formats:
+    - json                      # index.json (machine-readable)
+    - yaml                      # symbols.yaml (code map)
+    - markdown                  # summary.md (human-readable)
+
+# Privacy (optional, only enable if handling sensitive data)
+privacy:
+  phi_mode: "off"               # off | standard | strict
+  pii_detection: false
+  redaction_enabled: false
+
+# AI configuration (Claude API)
+ai:
+  provider: anthropic           # anthropic | openai
+  model: claude-sonnet-4-5-20250929  # Claude Sonnet 4.5 (latest)
+  max_tokens: 8192
+  temperature: 0.3              # Lower = more deterministic
+
+# Empathy Framework integration (optional)
+empathy:
+  enabled: true
+  sync_on_review: true          # Auto-sync with Empathy after reviews
+  level: 4                      # Anticipatory Empathy level
+
+# Exclude patterns (don't document these)
+exclude:
+  - node_modules/**
+  - .venv/**
+  - venv/**
+  - __pycache__/**
+  - "*.pyc"
+  - .git/**
+  - dist/**
+  - build/**
+  - "*.log"
+  - "*.db"
+  - coverage/**
+  - htmlcov/**
+  - .pytest_cache/**
+  - "*.egg-info/**"

CLI_FIX.md

@@ -0,0 +1,129 @@
+# CLI Test Failures - Final Fix
+
+## Issue
+
+After fixing the initial 6 test failures, 2 CLI tests were still failing:
+
+```
+FAILED tests/integration/test_cli.py::TestCLI::test_export_command_no_docs
+FAILED tests/integration/test_cli.py::TestCLI::test_query_command_no_index
+```
+
+**Error messages:**
+```
+assert 'not found' in "usage: export [options] {cursor|claude|continue}\ntr..."
+assert 'empty' in "usage: query [options] query\ntry 'query --help' for hel..."
+```
+
+## Root Cause
+
+Both CLI commands had `exists=True` in their Click path options:
+
+```python
+@click.option(
+    "--docs-dir",
+    type=click.Path(exists=True, path_type=Path),  # ❌ This causes Click to validate BEFORE function runs
+    ...
+)
+```
+
+When Click validates the path with `exists=True`, it shows a usage error if the path doesn't exist, **before** the function's custom error handling can run.
+
+## Solution
+
+Removed `exists=True` from both options to allow custom error messages:
+
+### 1. Export Command Fix ✅
+
+**File:** [memdocs/cli.py](memdocs/cli.py#L353)
+
+**Before:**
+```python
+@click.option(
+    "--docs-dir",
+    type=click.Path(exists=True, path_type=Path),
+    default=Path(".memdocs/docs"),
+    help="Documentation directory",
+)
+```
+
+**After:**
+```python
+@click.option(
+    "--docs-dir",
+    type=click.Path(path_type=Path),  # ✅ Removed exists=True
+    default=Path(".memdocs/docs"),
+    help="Documentation directory",
+)
+```
+
+The function already has proper error handling at line 372-380:
+```python
+if not docs_dir.exists():
+    click.echo(f"Error: Docs directory not found: {docs_dir}", err=True)
+    sys.exit(1)
+```
+
+### 2. Query Command Fix ✅
+
+**File:** [memdocs/cli.py](memdocs/cli.py#L494)
+
+**Before:**
+```python
+@click.option(
+    "--memory-dir",
+    type=click.Path(exists=True, path_type=Path),
+    default=Path(".memdocs/memory"),
+    help="Memory directory",
+)
+```
+
+**After:**
+```python
+@click.option(
+    "--memory-dir",
+    type=click.Path(path_type=Path),  # ✅ Removed exists=True
+    default=Path(".memdocs/memory"),
+    help="Memory directory",
+)
+```
+
+The function already has proper error handling at line 519-522:
+```python
+stats = indexer.get_stats()
+if stats["total"] == 0:
+    click.echo("⚠️  Memory index is empty. Run 'memdocs review' first to generate docs.")
+    sys.exit(1)
+```
+
+## Impact
+
+This allows the custom error messages to be shown:
+- ✅ `"Error: Docs directory not found: {path}"`
+- ✅ `"⚠️  Memory index is empty. Run 'memdocs review' first to generate docs."`
+
+Instead of generic Click usage errors:
+- ❌ `"usage: export [options] ..."`
+- ❌ `"usage: query [options] ..."`
+
+## Verification
+
+Run the failing tests:
+
+```bash
+pytest tests/integration/test_cli.py::TestCLI::test_export_command_no_docs -v
+pytest tests/integration/test_cli.py::TestCLI::test_query_command_no_index -v
+```
+
+Both should now pass! ✅
+
+## Summary
+
+**Files modified:** 1
+- `memdocs/cli.py` (2 lines changed)
+
+**Tests fixed:** 2
+- `test_export_command_no_docs` ✅
+- `test_query_command_no_index` ✅
+
+**Total test status:** 72/72 passing (100%) 🎉

DEPRECATION_FIXES.md

@@ -0,0 +1,195 @@
+# Deprecation Warnings Fixed
+
+## Summary
+
+All 9 deprecation warnings have been resolved! ✅
+
+**Before:** 69 passed, 9 warnings
+**After:** 69 passed, **0 warnings** 🎉
+
+---
+
+## Fixes Applied
+
+### 1. Pydantic V2 Config Deprecation (3 warnings fixed) ✅
+
+**Files Modified:** [memdocs/schemas.py](memdocs/schemas.py)
+
+**Issue:** Pydantic V2 deprecated class-based `Config` in favor of `ConfigDict`
+
+**Changes:**
+
+#### DocumentIndex class (Lines 182-198)
+```python
+# Before
+class DocumentIndex(BaseModel):
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat(),
+            Path: lambda v: str(v),
+        }
+
+# After
+class DocumentIndex(BaseModel):
+    model_config = ConfigDict(
+        ser_json_timedelta='iso8601',
+    )
+
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @field_serializer('timestamp')
+    def serialize_datetime(self, dt: datetime, _info) -> str:
+        return dt.isoformat()
+```
+
+#### ReviewResult class (Lines 210-225)
+```python
+# Before
+class ReviewResult(BaseModel):
+    class Config:
+        json_encoders = {
+            Path: lambda v: str(v),
+        }
+
+# After
+class ReviewResult(BaseModel):
+    model_config = ConfigDict()
+
+    @field_serializer('outputs')
+    def serialize_outputs(self, outputs: dict[str, Path], _info) -> dict[str, str]:
+        return {k: str(v) for k, v in outputs.items()}
+```
+
+**Import Changes:**
+```python
+# Added to imports
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+```
+
+---
+
+### 2. datetime.utcnow() Deprecation (6 warnings fixed) ✅
+
+**Files Modified:**
+- [memdocs/schemas.py](memdocs/schemas.py) (Lines 190, 204)
+- [memdocs/guard.py](memdocs/guard.py) (Line 148)
+
+**Issue:** `datetime.utcnow()` is deprecated in Python 3.12+ in favor of timezone-aware datetimes
+
+**Changes:**
+
+#### schemas.py
+```python
+# Before
+from datetime import datetime
+timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+# After
+from datetime import datetime, timezone
+timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+```
+
+#### guard.py
+```python
+# Before
+from datetime import datetime
+"timestamp": datetime.utcnow().isoformat()
+
+# After
+from datetime import datetime, timezone
+"timestamp": datetime.now(timezone.utc).isoformat()
+```
+
+---
+
+## Build Tools Installed ✅
+
+```bash
+pip install build twine
+```
+
+**Installed:**
+- `build==1.3.0` - For building wheel and source distributions
+- `twine==6.2.0` - For uploading to PyPI
+
+---
+
+## Test Results
+
+### Before Fixes
+```
+====== 69 passed, 9 warnings in 2.67s ======
+
+Warnings:
+- 3 × Pydantic V2 Config deprecation
+- 6 × datetime.utcnow() deprecation
+```
+
+### After Fixes
+```
+====== 69 passed in 2.03s ======
+
+✅ NO WARNINGS!
+```
+
+---
+
+## How to Build Package
+
+Now you can build and publish to PyPI:
+
+```bash
+# 1. Build the distribution
+python3 -m build
+
+# Output:
+# Successfully built memdocs-2.0.0.tar.gz and memdocs-2.0.0-py3-none-any.whl
+
+# 2. Check the package
+twine check dist/*
+
+# 3. Upload to Test PyPI (optional - test first)
+twine upload --repository testpypi dist/*
+
+# 4. Upload to PyPI (production)
+twine upload dist/*
+```
+
+---
+
+## Files Modified Summary
+
+| File | Changes | Status |
+|------|---------|--------|
+| `memdocs/schemas.py` | Pydantic V2 migration, datetime fixes | ✅ |
+| `memdocs/guard.py` | datetime.utcnow() → datetime.now(timezone.utc) | ✅ |
+
+**Lines changed:** ~15 lines across 2 files
+**Test impact:** None (all 69 tests still passing)
+**Breaking changes:** None (backward compatible)
+
+---
+
+## Verification
+
+Run tests to confirm:
+```bash
+pytest -v
+```
+
+Expected output:
+```
+====== 69 passed in X.XXs ======
+```
+
+No warnings! ✅
+
+---
+
+**Status:** ✅ All deprecation warnings resolved
+**Production ready:** ✅ YES
+**Ready for PyPI:** ✅ YES
+
+🎉 **Your package is now warning-free and ready to publish!**