feat: Release v3.0.1 - XML-Enhanced Prompts & Security Fixes

Major release with structured XML prompts system and critical security fixes:

## XML-Enhanced Prompts System
- Structured XML prompt templates for consistent LLM interactions
- Built-in templates: security-audit, code-review, research, bug-analysis
- XmlPromptTemplate and PlainTextPromptTemplate classes
- XmlResponseParser with safe defusedxml parsing (prevents XXE)
- PromptContext dataclass with factory methods
- Per-workflow XML configuration via .empathy/workflows.yaml

## Security Fixes (HIGH Priority)
- Fixed command injection in VSCode extension EmpathyDashboardPanel.ts
- Fixed command injection in extension.ts runEmpathyCommand functions
- Replaced vulnerable cp.exec() with safe cp.execFile() using arrays
- Created health_scan.py helper script to eliminate inline code
- Removed insecure demo_key fallback in wizard_api.py
- Updated .gitignore for nested .env files
- Added defusedxml for secure XML parsing

## VSCode Dashboard Enhancements
- 10 integrated workflows with input history persistence
- File/folder picker integration for workflow inputs
- Cost fetching from telemetry CLI with fallback
- Error banner for improved debugging

## Documentation
- Added XML-Enhanced Prompts section to README
- Updated CHANGELOG with v3.0.0 and v3.0.1 entries
- Added security notice to test fixtures

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

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

Author: 2 people

.claude/CLAUDE.md

@@ -1,6 +1,6 @@
 # Empathy Framework - Production Security Configuration
 # Location: ./.claude/CLAUDE.md
-# Project: empathy-framework v2.2.7
+# Project: empathy-framework v3.0.1
 # Classification: INTERNAL
 
 # Import pattern library summary (auto-generated)
@@ -149,7 +149,7 @@ pytest tests/test_claude_memory.py -v
   "timestamp": "2025-11-24T03:30:00Z",
   "event_id": "evt_abc123",
   "project": "empathy-framework",
-  "version": "2.2.7",
+  "version": "3.0.1",
   "user_id": "[email protected]",
   "action": "llm_request",
 
@@ -405,5 +405,5 @@ By working on this project, I confirm:
 ---
 
 *This configuration enforces enterprise security while enabling the five-level empathy system.*
-*Last updated: 2025-12-15*
-*Empathy Framework v2.2.7*
+*Last updated: 2025-12-22*
+*Empathy Framework v3.0.1*

.gitignore

@@ -50,6 +50,10 @@ __pycache__/
 # Security
 security_scan_results.json
 .env
+**/.env
+**/tests/.env
+*.env.local
+*.env.*.local
 
 # MemDocs
 .memdocs/

CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to the Empathy Framework will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.1] - 2025-12-22
+
+### Added
+
+**XML-Enhanced Prompts System**
+- Structured XML prompt templates for consistent LLM interactions
+- Built-in templates: `security-audit`, `code-review`, `research`, `bug-analysis`
+- `XmlPromptTemplate` and `PlainTextPromptTemplate` classes for flexible rendering
+- `XmlResponseParser` with automatic XML extraction from markdown code blocks
+- `PromptContext` dataclass with factory methods for common workflows
+- Per-workflow XML configuration via `.empathy/workflows.yaml`
+- Fallback to plain text when XML parsing fails (configurable)
+
+**VSCode Dashboard Enhancements**
+- 10 integrated workflows: Research, Code Review, Debug, Refactor, Test Generation, Documentation, Security Scan, Performance, Explain Code, Morning Briefing
+- Workflow input history persistence across sessions
+- File/folder picker integration for workflow inputs
+- Cost fetching from telemetry CLI with fallback
+- Error banner for improved debugging visibility
+
+### Fixed
+
+**Security Vulnerabilities (HIGH Priority)**
+- Fixed command injection in VSCode extension `EmpathyDashboardPanel.ts`
+- Fixed command injection in `extension.ts` runEmpathyCommand functions
+- Replaced vulnerable `cp.exec()` with safe `cp.execFile()` using array arguments
+- Created `health_scan.py` helper script to eliminate inline code execution
+- Removed insecure `demo_key` fallback in `wizard_api.py`
+
+**Security Hardening**
+- Updated `.gitignore` to cover nested `.env` files (`**/.env`, `**/tests/.env`)
+- Added security notice documentation to test fixtures with intentional vulnerabilities
+
+### Changed
+
+- Workflows now show provider name in output
+- Workflows auto-load `.env` files for API key configuration
+
+---
+
+## [3.0.0] - 2025-12-22
+
+### Added
+
+**Multi-Model Provider System**
+- Provider configuration: Anthropic, OpenAI, Ollama, Hybrid
+- Auto-detection of API keys from environment and `.env` files
+- CLI commands: `python -m empathy_os.models.cli provider`
+- Single, hybrid, and custom provider modes
+
+**Smart Tier Routing (80-96% Cost Savings)**
+- Cheap tier: GPT-4o-mini/Haiku for summarization
+- Capable tier: GPT-4o/Sonnet for bug fixing, code review
+- Premium tier: o1/Opus for architecture decisions
+
+**VSCode Dashboard - Complete Overhaul**
+- 6 Quick Action commands for common tasks
+- Real-time health score, costs, and workflow monitoring
+
+### Changed
+
+- README refresh with "Become a Power User" 5-level progression
+- Comprehensive CLI reference
+- Updated comparison table
+
+---
+
 ## [2.5.0] - 2025-12-20
 
 ### Added

README.md

@@ -12,11 +12,13 @@
 pip install empathy-framework[full]
 ```
 
-## What's New in v3.0.0
+## What's New in v3.0.1
 
+- **XML-Enhanced Prompts** — Structured prompts for consistent, parseable LLM responses
 - **Multi-Model Provider System** — Choose Anthropic, OpenAI, Ollama, or Hybrid mode
 - **80-96% Cost Savings** — Smart tier routing: cheap models detect, best models decide
-- **VSCode Dashboard** — Real-time health, costs, and workflow monitoring
+- **VSCode Dashboard** — 10 integrated workflows with input history persistence
+- **Security Hardening** — Fixed command injection vulnerabilities in VSCode extension
 - **Provider Auto-Detection** — Automatically configures based on your API keys
 
 ---
@@ -108,6 +110,7 @@ Install the Empathy VSCode extension for:
 - **Real-time Dashboard** — Health score, costs, patterns
 - **One-Click Workflows** — Research, code review, debugging
 - **Visual Cost Tracking** — See savings in real-time
+    - See also: `docs/dashboard-costs-by-tier.md` for interpreting the **By tier (7 days)** cost breakdown.
 
 ### Level 5: Custom Agents
 ```python
@@ -167,6 +170,43 @@ empathy-inspect . --staged            # Only staged changes
 
 ---
 
+## XML-Enhanced Prompts
+
+Enable structured XML prompts for consistent, parseable LLM responses:
+
+```yaml
+# .empathy/workflows.yaml
+xml_prompt_defaults:
+  enabled: false  # Set true to enable globally
+
+workflow_xml_configs:
+  security-audit:
+    enabled: true
+    enforce_response_xml: true
+    template_name: "security-audit"
+  code-review:
+    enabled: true
+    template_name: "code-review"
+```
+
+Built-in templates: `security-audit`, `code-review`, `research`, `bug-analysis`
+
+```python
+from empathy_os.prompts import get_template, XmlResponseParser, PromptContext
+
+# Use a built-in template
+template = get_template("security-audit")
+context = PromptContext.for_security_audit(code="def foo(): pass")
+prompt = template.render(context)
+
+# Parse XML responses
+parser = XmlResponseParser(fallback_on_error=True)
+result = parser.parse(llm_response)
+print(result.summary, result.findings, result.checklist)
+```
+
+---
+
 ## Install Options
 
 ```bash

backend/api/wizard_api.py

@@ -94,11 +94,17 @@
 
 # Initialize shared LLM instance for domain wizards
 def get_llm_instance():
-    """Get or create EmpathyLLM instance"""
+    """Get or create EmpathyLLM instance.
+
+    Raises:
+        ValueError: If ANTHROPIC_API_KEY environment variable is not set.
+    """
     api_key = os.getenv("ANTHROPIC_API_KEY")
     if not api_key:
-        logger.warning("ANTHROPIC_API_KEY not set - domain wizards will use demo mode")
-        api_key = "demo_key"
+        raise ValueError(
+            "ANTHROPIC_API_KEY environment variable is required. "
+            "Set it in your .env file or environment before starting the API."
+        )
 
     return EmpathyLLM(
         provider="anthropic", api_key=api_key, enable_security=True, enable_audit_logging=True

docs/dashboard-costs-by-tier.md

@@ -0,0 +1,29 @@
+# Understanding By Tier (7 days) in the Empathy Dashboard
+
+The Empathy VS Code dashboard includes a **Cost Details** panel that shows how model routing is saving you money over the last 7 days.
+
+When you click **View Costs** in the Power tab, you’ll see:
+
+- **Saved** – Total dollars saved over the last 7 days compared to always using the premium model.
+- **Reduction** – Percentage reduction in cost compared to the premium-only baseline.
+- **Actual** – Actual dollars spent on API calls in the last 7 days.
+
+Below the summary, the **By tier (7 days)** section breaks those savings down by model tier:
+
+- **Cheap** – Requests routed to the cheapest tier (e.g., Haiku-level models). Best for simple tasks like short summaries.
+- **Capable** – Requests routed to the middle tier (e.g., Sonnet-level models). Used for most code and reasoning tasks.
+- **Premium** – Requests routed to the most powerful tier (e.g., Opus-level models). Reserved for the hardest or most critical tasks.
+
+For each tier, you’ll see:
+
+- **Requests** – How many API calls used this tier in the last 7 days.
+- **Cost** – Actual dollars spent on that tier.
+- **+Saved** – How many dollars you saved by using this tier instead of always using the premium model for those same requests.
+
+Use this section to answer questions like:
+
+- Are most of my requests using **cheap** or **capable** models instead of premium?
+- Which tier is responsible for the **largest share of savings**?
+- Do I have many **premium** calls that could safely be moved down to capable or cheap?
+
+If the **cheap** and **capable** tiers show healthy savings and most requests, your routing is working well. If **premium** dominates both cost and request count, consider revisiting your task-type to tier mapping in `ModelRouter` or your workflow configuration.

docs/marketing/drafts/DEVTO_ARTICLE.md

@@ -1,16 +1,16 @@
 ---
-title: Give Claude Persistent Memory in 10 Lines of Python
+title: Give Claude Persistent Memory in 10 Lines of Python (Now with 80% Cost Savings)
 published: false
-description: How to make Claude remember your preferences across sessions using the Empathy Framework
-tags: python, ai, claude, anthropic
+description: How to make Claude remember your preferences across sessions using the Empathy Framework v3.0.0
+tags: python, ai, claude, anthropic, openai
 cover_image:
 ---
 
 # Give Claude Persistent Memory in 10 Lines of Python
 
 Every conversation with Claude starts from scratch. Tell it you prefer concise code examples, and next session? It's forgotten.
 
-Here's how to fix that—plus save 80% on API costs.
+Here's how to fix that—plus save 80% on API costs with v3.0.0's multi-provider system.
 
 ## The Problem
 
@@ -28,7 +28,7 @@ Claude's API is stateless. Each request is independent. For simple Q&A, that's f
 from empathy_llm_toolkit import EmpathyLLM
 
 llm = EmpathyLLM(
-    provider="anthropic",
+    provider="anthropic",  # or "openai", "ollama", "hybrid"
     api_key="your-key",
     memory_enabled=True
 )
@@ -42,6 +42,27 @@ response = await llm.interact(
 
 That's it. Next time this user connects—even days later—Claude remembers.
 
+## New in v3.0.0: Multi-Provider Support
+
+Choose your provider—or mix them:
+
+```bash
+# Check available providers (auto-detects API keys)
+python -m empathy_os.models.cli provider status
+
+# Switch providers
+python -m empathy_os.models.cli provider set openai
+
+# Enable hybrid mode (best model from each provider)
+python -m empathy_os.models.cli provider set hybrid
+```
+
+Supported providers:
+- **Anthropic** — Claude (Haiku/Sonnet/Opus)
+- **OpenAI** — GPT (GPT-4o-mini/GPT-4o/o1)
+- **Ollama** — Local models (Llama 3.2)
+- **Hybrid** — Best of each provider per tier
+
 ## Real-World Example: Debugging Wizard
 
 Here's what persistent memory enables. I built a debugging wizard that correlates current bugs with historical patterns:
@@ -113,23 +134,25 @@ On a real codebase (364 debt items, 81 security findings):
 - **Security noise reduction**: 84% (81 → 13 findings after learning)
 - **Tech debt tracking**: Trajectory predicts 2x growth in 170 days
 
-## NEW in v2.3: Smart Model Routing (80% Cost Savings)
+## v3.0.0: Smart Model Routing (80% Cost Savings)
+
+Why pay Opus prices for simple tasks? The ModelRouter automatically picks the right model across any provider.
 
-Why pay Opus prices for simple tasks? The new ModelRouter automatically picks the right model:
+*API users save money. Subscription users (Max/Pro) preserve their premium model quota for complex tasks.*
 
 ```python
 llm = EmpathyLLM(
-    provider="anthropic",
-    enable_model_routing=True  # NEW!
+    provider="anthropic",  # or "openai", "ollama", "hybrid"
+    enable_model_routing=True
 )
 
-# Summarization → Haiku ($0.25/M tokens)
+# Summarization → Haiku/GPT-4o-mini ($0.25/M tokens)
 await llm.interact(user_id="dev", user_input="Summarize this", task_type="summarize")
 
-# Code generation → Sonnet ($3/M tokens)
+# Code generation → Sonnet/GPT-4o ($3/M tokens)
 await llm.interact(user_id="dev", user_input="Write a function", task_type="generate_code")
 
-# Architecture → Opus ($15/M tokens)
+# Architecture → Opus/o1 ($15/M tokens)
 await llm.interact(user_id="dev", user_input="Design the system", task_type="architectural_decision")
 ```
 
@@ -138,13 +161,33 @@ await llm.interact(user_id="dev", user_input="Design the system", task_type="arc
 - With routing (tiered): $0.83/complex task
 - **Savings: 80%**
 
+## v3.0.0: VSCode Dashboard
+
+The biggest addition in v3.0.0 is a complete VSCode Dashboard with **10 integrated workflows**:
+
+1. **Research Synthesis** — Deep dive research with citations
+2. **Code Review** — Comprehensive PR analysis
+3. **Debug Assistant** — Smart error diagnosis
+4. **Refactor Advisor** — Code improvement suggestions
+5. **Test Generator** — Automated test creation
+6. **Documentation Writer** — Auto-generate docs
+7. **Security Scanner** — Vulnerability detection
+8. **Performance Analyzer** — Bottleneck identification
+9. **Explain Code** — Code explanation for onboarding
+10. **Morning Briefing** — Daily project status report
+
+Plus **6 Quick Action commands** for common tasks.
+
+All with real-time cost tracking showing your savings.
+
 ## Get Started
 
 ```bash
 pip install empathy-framework
 ```
 
 **Resources:**
+- **PyPI:** 3,400+ monthly downloads
 - [GitHub](https://github.com/Smart-AI-Memory/empathy-framework)
 - [Documentation](https://www.smartaimemory.com/docs)
 - [Live Demo](https://www.smartaimemory.com/tools/debug-wizard)