docs: document local-first backend, gemma4 gotchas, and contract tests

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

README.md

@@ -58,7 +58,7 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
   - Error triggers for testing (rate_limit, context_overflow)
 
 - **Tatlock**: Real PydanticAI agent with butler personality
-  - **LLM Backend**: Ollama (mistral-nemo:latest by default)
+  - **LLM Backend**: Ollama (gemma4:e2b by default, local-first) with optional Claude fallback
   - **Personality**: Witty British butler, research-oriented
   - **Core Tools**:
     - **Calculator**: Safe mathematical expression evaluation
@@ -74,7 +74,7 @@ A privacy-first, offline-capable personal assistant system that coordinates spec
 
 - Python 3.12+ (Python 3.12.11 recommended)
 - **External Services** (must be running separately):
-  - **Ollama**: LLM inference (mistral-nemo:latest, nomic-embed-text)
+  - **Ollama**: LLM inference (gemma4:e2b, nomic-embed-text)
   - **Redis**: Caching and session memory
   - **Qdrant**: Vector storage for The Biographer's memory
   - **SearXNG**: Web search (optional)
@@ -264,7 +264,10 @@ Interactive documentation available at:
 pytest
 
 # Run unit tests only (no external services needed)
-pytest --ignore=tests/e2e --ignore=tests/integration
+pytest --ignore=tests/e2e --ignore=tests/integration --ignore=tests/contracts
+
+# Wire-level contract tests against live service boundaries
+make test-contracts
 
 # Run with coverage
 pytest --cov=src --cov-report=term-missing
@@ -303,12 +306,17 @@ Create a `.env` file for custom configuration:
 API_HOST=0.0.0.0
 API_PORT=8000
 
-# Ollama Configuration
+# Ollama Configuration (primary backend)
 OLLAMA_HOST=http://localhost:11434
-OLLAMA_DEFAULT_MODEL=mistral-nemo:latest
+OLLAMA_DEFAULT_MODEL=gemma4:e2b
 OLLAMA_EMBEDDING_MODEL=nomic-embed-text
 OLLAMA_TIMEOUT=120
 
+# Claude fallback (optional; used when Ollama is down or PREFER_CLOUD_BACKEND=true)
+# ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
+ANTHROPIC_MODEL=claude-sonnet-5
+PREFER_CLOUD_BACKEND=false
+
 # Redis Configuration
 REDIS_HOST=localhost
 REDIS_PORT=6379
@@ -427,8 +435,8 @@ For LLM agent development guidelines and architectural decisions, see [AGENTS.md
 
 ## Version
 
-Current version: **1.3.2** - Biographer tool type hints fix
+Current version: see [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
-**Note**: Tatlock is a production-ready homelab butler. All household staff use PydanticAI with Ollama for local LLM inference.
+**Note**: Tatlock is a production-ready homelab butler. All household staff use PydanticAI with local Ollama inference (gemma4), with an optional Claude cloud fallback.