docs: Add warm session provisioning README

Documentation for #327 implementation.

docs/warm-session-provisioning.md

@@ -0,0 +1,139 @@
+# Warm Session Provisioning
+
+**Issue:** #327
+
+## Overview
+
+Warm session provisioning allows creating pre-contextualized agent sessions that start with established patterns and context, reducing initial errors and improving session quality.
+
+## Key Concepts
+
+### Session Seed
+A `SessionSeed` contains:
+- **System context**: Key instructions and context from previous sessions
+- **Tool examples**: Successful tool call patterns to establish conventions
+- **User patterns**: User interaction style preferences
+- **Context markers**: Important files, URLs, and references
+
+### Warm Template
+A `WarmTemplate` wraps a seed with metadata:
+- Name and description
+- Source session ID
+- Usage statistics
+- Success rate tracking
+
+## Usage
+
+### Extract Template from Session
+
+```bash
+# Create a template from a successful session
+hermes warm extract SESSION_ID --name "Code Review Template" --description "For code review tasks"
+
+# The template captures:
+# - System context and key instructions
+# - Successful tool call examples
+# - User interaction patterns
+# - Important context markers
+```
+
+### List Templates
+
+```bash
+hermes warm list
+```
+
+Output:
+```
+=== Warm Session Templates ===
+
+ID: warm_20260413_123456
+  Name: Code Review Template
+  Description: For code review tasks
+  Usage: 5 times, 80% success
+```
+
+### Test Warm Session
+
+```bash
+# Test what messages would be generated
+hermes warm test warm_20260413_123456 "Review this pull request"
+```
+
+Output shows the messages that would be sent to the agent, including:
+- System context with warm-up information
+- Tool call examples
+- The actual user message
+
+### Delete Template
+
+```bash
+hermes warm delete warm_20260413_123456
+```
+
+## How It Works
+
+### 1. Extraction Phase
+When you extract a template:
+1. System messages provide base context
+2. First 10 user messages establish patterns
+3. Successful tool calls become examples
+4. File paths and URLs become context markers
+
+### 2. Bootstrap Phase
+When creating a warm session:
+1. System context is injected as initial message
+2. Tool examples establish successful patterns
+3. User message follows the warm-up context
+4. Agent starts with established conventions
+
+## Example Workflow
+
+```bash
+# 1. Have a successful session
+# ... work with the agent on a complex task ...
+
+# 2. Extract template from that session
+hermes warm extract abc123 --name "API Integration" --description "REST API work"
+
+# 3. Later, start a new session with warm context
+# The agent will have context about:
+# - Your coding style
+# - Successful tool patterns
+# - Common file paths
+# - Previous instructions
+```
+
+## Benefits
+
+1. **Reduced Initial Errors**: Agent starts with proven patterns
+2. **Consistent Behavior**: Established conventions carry over
+3. **Faster Context**: No need to re-explain preferences
+4. **Quality Tracking**: Success rate shows template effectiveness
+
+## Implementation Details
+
+### Files
+- `tools/warm_session.py`: Core implementation
+- `~/.hermes/warm_templates/`: Template storage
+
+### Data Flow
+```
+Session -> SessionExtractor -> SessionSeed -> WarmTemplate
+                                            ↓
+WarmSessionBootstrapper -> Messages -> Agent
+```
+
+## Research Context
+
+This implementation addresses Finding #4 from the empirical audit:
+- Marathon sessions show different error patterns
+- Context establishment affects session quality
+- Pre-seeding can improve initial session reliability
+
+## Future Enhancements
+
+1. **Automatic Template Creation**: Create templates from high-performing sessions
+2. **Template Sharing**: Export/import templates between installations
+3. **A/B Testing**: Compare warm vs cold session performance
+4. **Smart Selection**: Automatically choose best template for task type