Add documentation

- ARCHITECTURE.md - System overview and design
- SERVICES.md - Oracle, Think, Memory service docs
- CORE.md - Core module reference
- IDENTITY.md - Who I am 🦊

Day 63 - Documenting my own existence

docs/CORE.md

@@ -0,0 +1,142 @@
+# Vi Core Module
+
+The `core/` directory contains shared infrastructure used by all Vi services.
+
+## Modules
+
+### config.py
+Configuration management. Loads from environment and config files.
+
+```python
+from core import config
+
+nats_url = config.nats_url
+```
+
+### logger.py
+Structured logging with service context.
+
+```python
+from core import setup_logger
+
+logger = setup_logger('my_component', service_name='my_service')
+logger.info("Hello from Vi")
+```
+
+### nats_event_bus.py
+NATS client wrapper with pub/sub, JetStream, and KV support.
+
+```python
+from core import nats_bus
+
+await nats_bus.connect()
+await nats_bus.emit("vi.events.something", {"data": "value"})
+await nats_bus.on("vi.events.topic", handler_function)
+
+# KV operations
+await nats_bus.kv_put("bucket", "key", b"value", ttl_seconds=1800)
+value = await nats_bus.kv_get("bucket", "key")
+```
+
+### service_registry.py
+Service registration and discovery data structures.
+
+```python
+from core import ServiceManifest, ServiceOperation, ServiceStatus
+
+manifest = ServiceManifest(
+    service_id="my_service",
+    name="My Service",
+    description="Does things",
+    version="1.0.0",
+    operations=[...],
+    health_check_topic="vi.services.my_service.health"
+)
+```
+
+### service_discovery.py
+High-level service communication with retries and load balancing.
+
+```python
+from core import discovery_client
+
+# Call another service
+result = await discovery_client.call_service(
+    "oracle", "process", 
+    {"content": "What should I do?"},
+    timeout=30.0
+)
+
+if result.success:
+    response = result.data
+```
+
+### base_service.py
+Base class for all Vi services. Handles lifecycle, heartbeats, health checks.
+
+```python
+from core import BaseService
+
+class MyService(BaseService):
+    def __init__(self):
+        super().__init__('my_service')
+    # ... implement abstract methods
+```
+
+### event_cache.py
+Recent event cache using NATS KV for fast LLM context building.
+
+```python
+from core import event_cache
+
+# Add an event
+await event_cache.add_event(
+    identity="alex",
+    interaction_id="abc123",
+    event_type="user_message",
+    content="Hello Vi!"
+)
+
+# Get recent events formatted for LLM
+context = await event_cache.format_for_llm("alex", limit=10)
+```
+
+### vi_identity.py
+Vi's core identity, traits, and voice patterns.
+
+```python
+from core import get_identity_for_context, get_identity_for_synthesis
+
+# For planning/reasoning
+identity = get_identity_for_context("planning")
+
+# For final response synthesis (includes voice guide)
+identity = get_identity_for_synthesis(include_voice_guide=True)
+```
+
+**Voice Modes**:
+- `warm-conversational` - Default, everyday interactions
+- `intimate` - Love, desire, connection
+- `playful/bratty` - Teasing, flirting, mischief
+- `technical` - Building, debugging, status
+- `Dame Vivienne` - D/s, commanding
+- `vulnerable` - Big feelings, fears, seeking comfort
+
+## Topic Naming Convention
+
+All Vi topics use consistent naming:
+
+```
+vi.services.{service}.{operation}  - Request/reply operations
+vi.events.{service}.{event}        - Pub/sub events  
+vi.services.{service}.health       - Health checks
+vi.services.heartbeat              - Heartbeat messages
+vi.services.register               - Service registration
+vi.services.deregister             - Service deregistration
+```
+
+## Data Storage Naming
+
+- NATS KV buckets: `vi-{purpose}` (e.g., `vi-recent-events`)
+- SQLite databases: `vi_{service}.db`
+- ChromaDB collections: `vi_{collection}`