@michelabboud/visual-forge-mcp 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,814 @@
+# Changelog
+
+All notable changes to Visual Forge MCP 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).
+
+## [0.6.0] - 2026-01-14
+
+### Added ✨ Automatic Image Optimization
+
+#### Feature: Web-Optimized Images with Original Preservation
+
+Visual Forge now automatically optimizes generated images for web use while preserving originals for high-quality print or archival purposes.
+
+**What's New:**
+- **Automatic optimization** of all generated images for web delivery
+- **Works with ALL providers** - OpenAI, Gemini, Stability, Replicate, Leonardo, XAI, HuggingFace
+- **Provider-agnostic** - optimization happens at workflow level, not in individual providers
+- **Preserves originals** in `original/` subdirectory (never touched)
+- **WebP format** by default for ~70% file size reduction
+- **Configurable** via environment variables
+- **Graceful fallback** when Sharp library unavailable
+- **No crashes** - always works, even if optimization fails
+
+**Default Behavior:**
+- Originals saved: `generated-images/gemini/original/image.png` (4.2 MB)
+- Web version used: `generated-images/gemini/image.webp` (1.2 MB)
+- Quality: 85% (excellent, nearly imperceptible loss)
+- Format: WebP (modern, best compression)
+- Dimensions: Max 1920px (standard web)
+
+**Configuration Options:**
+```bash
+# Enable/disable (default: true)
+IMAGE_OPTIMIZATION_ENABLED=true
+
+# Quality 1-100 (default: 85)
+IMAGE_OPTIMIZATION_QUALITY=85
+
+# Format: webp|jpeg|png (default: webp)
+IMAGE_OPTIMIZATION_FORMAT=webp
+
+# Max dimensions (default: 1920)
+IMAGE_OPTIMIZATION_MAX_WIDTH=1920
+IMAGE_OPTIMIZATION_MAX_HEIGHT=1920
+
+# Keep originals (default: true)
+IMAGE_OPTIMIZATION_KEEP_ORIGINAL=true
+```
+
+**Use Cases:**
+1. **Web docs** (default): Q85 WebP, ~70% reduction, excellent quality
+2. **Print-ready**: Disable optimization, use originals
+3. **Premium quality**: Q95 WebP, ~40% reduction, virtually no loss
+4. **Diagrams with text**: Q95 PNG, lossless, perfect clarity
+
+**Files Added:**
+- `src/utils/image-optimizer.ts` - Core optimization logic with Sharp
+- `docs/guides/image-optimization.md` - Comprehensive configuration guide
+
+**Files Modified:**
+- `src/workflow/workflow-orchestrator.ts` - Added optimization after image generation (provider-agnostic)
+- `src/types/generation.ts` - Added optimization metadata to `GeneratedImageMetadata`
+- `src/utils/index.ts` - Export optimizer utilities
+- `package.json` - Added `bin` field for global npm installation
+
+**Safety Features:**
+- Originals always preserved in `original/` subdirectory
+- Graceful fallback if Sharp unavailable
+- Error handling with automatic fallback to originals
+- No workflow disruption on optimization failure
+
+**Documentation:**
+- See [docs/guides/image-optimization.md](docs/guides/image-optimization.md) for full guide
+- Includes examples, troubleshooting, and best practices
+
+## [0.5.6] - 2026-01-14
+
+### Fixed 🔧 CRITICAL: Image Generation Failure
+
+#### Problem: No Images Actually Generated
+- **Issue:** vf_generate_session claimed success but NO images were actually generated
+- **Symptom:** All images stuck at "placeholder_added" status, never progressed to "generated"
+- **Root Cause:** Parsed image specifications were never added to StateManager
+  - `handleProcessFiles()` parsed specs and added them to session tracking
+  - But specs were NOT added to StateManager via `stateManager.addImages()`
+  - When `handleGenerateSession()` tried to retrieve specs from StateManager, found nothing
+  - Empty `imageSpecs` array passed to orchestrator → no generation occurred
+- **Impact:** Complete workflow failure - no images generated despite "success" message
+
+#### The Fix ✅
+- **Location:** `WorkflowTools.handleProcessFiles()` (lines 218-224)
+- **Solution:** Added StateManager initialization and `addImages()` call after parsing
+- **Code Added:**
+  ```typescript
+  // ✅ CRITICAL: Add specs to StateManager so they can be retrieved for generation
+  const stateManager = new StateManager();
+  await stateManager.initialize();
+  stateManager.addImages(allSpecs);
+  await stateManager.save();
+  ```
+
+#### Verification
+- ✅ User confirmed: "the images were generated beautifully"
+- ✅ Images now properly generated by all providers
+- ✅ Placeholders correctly replaced with image links
+- ✅ Session tracking works end-to-end
+
+### Impact
+- ✅ Image generation now works as designed
+- ✅ Complete workflow from placeholders → generation → replacement
+- ✅ StateManager properly tracks all specs for orchestrator
+- ✅ No more "phantom success" with zero images
+
+## [0.5.5] - 2026-01-14
+
+### Fixed 🔧 CRITICAL: Backup Issues
+
+#### Problem 1: No Backup When Adding Placeholders
+- **Issue:** Original markdown files were modified WITHOUT backup when adding placeholders
+- **Risk:** Users could lose original file content if placeholder addition went wrong
+- **Fix:** ✅ Now creates backup BEFORE adding placeholders to markdown files
+- **Location:** `PlaceholderManager.addPlaceholders()` (line 93-105)
+
+#### Problem 2: Unnecessary Image Backups
+- **Issue:** Newly generated images were being backed up unnecessarily
+- **Why Bad:** Wastes disk space and confuses backup purpose (images are NEW files, not modifications)
+- **Fix:** ✅ Removed image files from backup when replacing placeholders
+- **Location:** `WorkflowTools.handleGenerateSession()` (line 541-543)
+
+### Changes
+
+**PlaceholderManager:**
+- ✅ Added `BackupManager` instance
+- ✅ Creates backup before `fs.writeFile()` when adding placeholders
+- ✅ Logs backup creation status
+- ✅ Proceeds with warning if backup fails (doesn't block operation)
+
+**WorkflowTools:**
+- ✅ Changed backup call to only backup markdown files: `createBackup(session.files, [])`
+- ✅ Added comment explaining why images aren't backed up
+- ✅ Clearer log message: "Creating backups before replacing placeholders in markdown files"
+
+### Impact
+- ✅ Original markdown files are now protected when placeholders are added
+- ✅ Backup system only backs up what matters (files being modified)
+- ✅ Reduced disk space usage (no unnecessary image backups)
+- ✅ Clearer backup intent and purpose
+
+## [0.5.4] - 2026-01-14
+
+### Added 🆕 Session Management Tools
+
+#### Easy Session Clearing/Reset
+- **New MCP Tools for Session Management**
+  - ✅ `vf_clear_session` - Clear/delete a specific session by ID
+  - ✅ `vf_clear_all_sessions` - Clear ALL sessions (with warning)
+  - ✅ `vf_clear_incomplete_sessions` - Clear only incomplete sessions
+  - ✅ `vf_reset_state` - Nuclear option: reset entire Visual Forge state
+
+- **Session Manager Enhancements**
+  - ✅ `clearAllSessions()` - Delete all session data
+  - ✅ `clearIncompleteSessions()` - Delete only incomplete sessions
+  - Returns count of deleted sessions
+
+- **State Manager Enhancements**
+  - ✅ `reset()` - Async method to reset state to initial
+  - ✅ Deletes state.json file
+  - ✅ Creates fresh initial state
+  - ✅ Renames old `reset()` to `resetMemory()` for clarity
+
+- **Benefits**
+  - ✅ Easy cleanup of old session data
+  - ✅ Quick way to start fresh
+  - ✅ Clears memory/cache issues
+  - ✅ Maintains generated images on disk
+  - ✅ Clear warnings for destructive operations
+
+## [0.5.3] - 2026-01-14
+
+### Fixed 🔧 CRITICAL BUG FIX
+
+#### Global Context Null Handling
+- **Fixed "Cannot read properties of undefined (reading 'style')" Error**
+  - ✅ All 7 providers now handle missing/undefined `globalContext` gracefully
+  - ✅ Added null checks before accessing `context.style` properties
+  - ✅ Providers provide sensible defaults when context is missing
+  - ✅ Removed non-null assertion operators (`!`) from all providers
+  - ✅ Updated `BaseProvider` abstract method signature to make context optional
+
+- **Provider-Specific Fixes**
+  - ✅ Gemini: Default to "professional style" when context missing
+  - ✅ OpenAI: Default to clean, modern technical documentation style
+  - ✅ Stability: Default positive/negative prompts without context
+  - ✅ Replicate: Default FLUX prompt enhancements
+  - ✅ xAI Grok: Default to professional, clean, modern style
+  - ✅ Leonardo: Default to professional, high quality, detailed
+  - ✅ HuggingFace: Default inference parameters and prompts
+
+- **Impact**
+  - ✅ Images can now be generated even without detailed global context
+  - ✅ Workflow no longer crashes when context is undefined
+  - ✅ All providers work in "quick generation" mode
+  - ✅ Backward compatible with existing workflows
+
+## [0.5.2] - 2026-01-14
+
+### Added 🎯 RED LINE #6: API Testing & Output Verification
+
+#### Real-Time Progress Bar 📊
+- **Visual Progress Indicators**
+  - ✅ Text-based progress bar: `[████████░░░░░░░░] 8/32 (25%)`
+  - ✅ Real-time progress tracking during generation
+  - ✅ Current image name and provider display
+  - ✅ Elapsed time, average time per image, ETA
+  - ✅ Recently completed/failed image tracking (last 5)
+
+- **Enhanced Progress Reporting**
+  - ✅ Progress logged after each image completes
+  - ✅ Works in all modes: interactive, batch, bulk
+  - ✅ Includes detailed timing information
+  - ✅ Shows queue status: pending, in-progress, completed, failed
+
+#### API Connectivity Testing ⚡
+- **All 7 Providers Implement `testConnection()`**
+  - ✅ Gemini: Tests `/v1beta/models` endpoint
+  - ✅ OpenAI: Tests `/v1/models` endpoint
+  - ✅ Stability: Tests `/v1/user/account` endpoint
+  - ✅ Replicate: Tests `/v1/models` endpoint
+  - ✅ xAI: Tests `/v1/models` endpoint (OpenAI-compatible)
+  - ✅ Leonardo: Tests `/api/rest/v1/me` endpoint
+  - ✅ HuggingFace: Tests model info endpoint
+  - Returns: `{success: boolean, message: string, latency?: number}`
+
+- **Workflow Integration - Tests BEFORE Generation**
+  - ✅ Tests API connectivity before starting generation
+  - ✅ BLOCKS generation if API test fails
+  - ✅ Returns clear error with latency information
+  - ✅ Logs all connection attempts
+
+#### Image Output Verification 🔍
+- **File Verification After Generation**
+  - ✅ Verifies each generated image file exists on disk
+  - ✅ Checks file size (must be > 1KB for valid image)
+  - ✅ Separates verified images from failed images
+  - ✅ Only updates status for VERIFIED images
+
+- **Accurate Generation Counts**
+  - ✅ Returns `imagesGenerated` (actual verified count)
+  - ✅ Returns `imagesFailed` (failed count)
+  - ✅ Returns `verification` object with detailed breakdown
+  - ✅ Returns `failedImages` array with reasons
+
+- **Generation Blocking**
+  - ✅ Returns error if ZERO images verified
+  - ✅ Provides clear error messages
+  - ✅ Suggests actions to fix issues
+  - ✅ Never claims success with zero output
+
+#### Session Auto-Resume 🔄
+- **New MCP Tools**
+  - ✅ `vf_check_incomplete_sessions`: Find incomplete sessions
+  - ✅ `vf_resume_session`: Resume a specific session
+  - Auto-detects most recent incomplete session
+  - Returns recommended next steps based on status
+
+- **Smart Resumption**
+  - Filters out completed/generation_complete sessions
+  - Sorts by timestamp (most recent first)
+  - Provides context-aware next steps
+  - Loads full session state for continuation
+
+### Fixed
+- **Type Definitions**
+  - Added `testConnection()` to `IImageProvider` interface
+  - Fixed TypeScript compilation errors
+  - Removed unused variables
+
+### Changed
+- **Workflow Return Values**
+  - `imagesGenerated` now returns VERIFIED count (not claimed count)
+  - Added `imagesFailed` to return object
+  - Added `verification` object with detailed breakdown
+  - `success` now depends on verified images count
+
+### Documentation
+- **V0.5.2_IMPLEMENTATION_PLAN.md**: Complete implementation plan
+- **API_TESTING_IMPLEMENTATION.md**: API testing approach and solution
+
+### User Impact ⭐
+**Before (v0.5.1)**
+- ❌ Says "42 images generated" but none exist
+- ❌ No API test before generation
+- ❌ Placeholders remain in files
+- ❌ User confused why nothing happened
+
+**After (v0.5.2)**
+- ✅ Tests API before starting
+- ✅ Verifies each image file exists
+- ✅ Returns accurate counts
+- ✅ Clear error if API fails
+- ✅ Only updates status for verified images
+- ✅ User knows exactly what happened
+- ✅ Can auto-resume incomplete sessions
+
+## [0.5.1] - 2026-01-13
+
+### Added
+
+#### Workflow Enforcement Rules 🚨 (Phase 1)
+- **RED LINE #1: Mandatory File Analysis** - Enforced in `placeholder-manager.ts`
+  - ✅ Reads ENTIRE file with line count logging
+  - ✅ Validates file is not empty (throws error)
+  - ✅ Parses ALL sections with count logging
+  - ✅ Validates sections were found (throws error if none)
+  - ✅ Analyzes content for image opportunities with logging
+  - ✅ Cannot skip analysis or guess sections
+
+- **RED LINE #2: Detailed Context REQUIRED** - Enforced in `workflow-tools.ts`
+  - ✅ Checks for detailed context before generation
+  - ✅ BLOCKS generation if no context exists
+  - ✅ WARNS if context is too short (<100 chars)
+  - ✅ STRONGLY RECOMMENDS detailed context over simple
+  - ✅ Logs all context validation
+
+- **RED LINE #3: Explicit Tool Descriptions** - Updated in `mcp-server.ts`
+  - ✅ `vf_process_files` description now uses MUST/REQUIRED language
+  - ✅ `vf_generate_session` description details enforcement
+  - ✅ Clear sections: REQUIRED BEFORE, WHAT THIS DOES, WHAT IT DOES NOT DO
+  - ✅ AI models understand exact requirements
+
+- **RED LINE #4: No Silent Failures** - Enforced throughout
+  - ✅ Comprehensive logging in all operations
+  - ✅ Explicit error throwing (not silent failures)
+  - ✅ Structured log data for debugging
+  - ✅ Every operation is transparent
+
+- **RED LINE #5: Context Prepending Validation** - Enforced in `placeholder-manager.ts`
+  - ✅ Validates context exists before prepending
+  - ✅ Logs context usage (length, section)
+  - ✅ Prepends context with separator
+  - ✅ Validates final prompt length
+  - ✅ Warns if prompt is too short
+
+#### Documentation
+- **ENFORCEMENT_IMPLEMENTATION_SUMMARY.md**: Complete implementation summary
+  - What was implemented for each RED LINE
+  - Code examples showing enforcement
+  - Testing results (build ✅, startup ✅)
+  - Impact comparison (before/after)
+- **WORKFLOW_ENFORCEMENT_RULES.md**: Rule definitions (created in v0.5.0)
+- **REAL_FILE_ANALYSIS.md**: Example of proper file analysis (created in v0.5.0)
+
+### Changed
+- **Placeholder Manager**: Now enforces file analysis (cannot skip)
+- **Workflow Tools**: Now validates context requirements (blocks without context)
+- **MCP Server**: Tool descriptions now explicit with requirements
+- **Logging**: Comprehensive logging added throughout workflow
+
+### Fixed
+- AI models can no longer skip file analysis
+- AI models can no longer use vague or missing context
+- AI models can no longer bypass workflow requirements
+- All operations now logged (no silent failures)
+
+### Technical Details
+
+#### Files Modified
+1. `src/placeholders/placeholder-manager.ts` - RED LINES #1, #5
+2. `src/workflow/workflow-tools.ts` - RED LINE #2
+3. `src/server/mcp-server.ts` - RED LINE #3
+4. `package.json` - Version bump to 0.5.1
+
+#### Code Changes
+- ~150 lines of enforcement code
+- ~50 lines of logging
+- ~80 lines of validation
+- ~40 lines of documentation comments
+
+---
+
+## [0.5.0] - 2026-01-13
+
+### Added
+
+#### Detailed Global Context System 🎨
+- **New MCP Tool**: `vf_set_detailed_context` for comprehensive image styling
+- **DetailedGlobalContext Type**: Structured context with 7 major categories:
+  - Visual Style & Approach (illustration style, abstraction level, complexity)
+  - Color Palette (hex codes, usage descriptions for primary/secondary/accent/background/text)
+  - Typography & Labels (font family, sizes, alignment)
+  - Layout & Composition (grid system, spacing, padding, whitespace)
+  - Technical Elements (icon style, line weights, shadows, borders, corner radius)
+  - Audience Context (technical level, professional context, prior knowledge, purpose)
+  - Content Approach (document type, tone, detail level, diagram philosophy)
+- **Context Helpers**:
+  - `contextToPrompt()`: Convert structured context to comprehensive prompt string
+  - `createSimpleContext()`: Create default context from simple text
+- **Session Integration**:
+  - Sessions now store both `detailedContext` (structured) and `globalContext` (text)
+  - Automatic conversion to prompt text for image generation
+  - Persistent storage in `detailed-context.json` per session
+
+#### Documentation Updates
+- **CLAUDE.md**: Added comprehensive "Detailed Global Context System" section
+  - Why detailed context matters (dramatically better results)
+  - What detailed context includes (7 categories explained)
+  - How to use the `vf_set_detailed_context` tool (with examples)
+  - Multi-file context inheritance guidance
+- **README.md**: Added new feature to features list with ✨ NEW badge
+
+### Changed
+- **Session Manager**: Extended to support detailed context save/load
+- **Session Types**: Added `detailedContext` field to `Session` and `SessionOptions`
+- **Workflow Tools**: New `handleSetDetailedContext()` method for context management
+- **Type System**: New `src/types/context.ts` module with comprehensive types
+
+### Technical Details
+
+#### New Files
+- `src/types/context.ts`: Detailed context type definitions and helpers
+- Per-session `detailed-context.json`: Structured context storage
+
+#### Updated Files
+- `src/session/types.ts`: Added `DetailedGlobalContext` import and session fields
+- `src/session/session-manager.ts`: Added detailed context save/load methods
+- `src/workflow/workflow-tools.ts`: Added `handleSetDetailedContext()` handler
+- `src/server/mcp-server.ts`: Added `vf_set_detailed_context` tool definition
+- `src/types/index.ts`: Export context types
+
+#### Workflow Enhancement
+```
+vf_start_session → vf_set_detailed_context → vf_process_files → vf_generate_session
+```
+
+The detailed context is automatically prepended to every image prompt, ensuring:
+- **Visual Consistency**: All images follow the same design system
+- **Better Quality**: AI models receive specific, actionable guidance
+- **Professional Results**: Hex codes, typography, and layout rules produce polished images
+
+### Backward Compatibility
+- ✅ Fully backward compatible
+- ✅ Simple `globalContext` (text) still works
+- ✅ Detailed context is optional enhancement
+- ✅ Sessions without detailed context use text-based context
+
+---
+
+## [0.4.1] - 2026-01-13
+
+### Added
+
+#### Pricing Configuration System 💰
+- **config/pricing.json**: Externalized pricing configuration with multi-model support
+- **config/pricing-schema.json**: JSON schema validation for pricing configuration
+- **scripts/update-pricing.js**: Interactive CLI tool for managing provider pricing
+- **src/utils/pricing-checker.ts**: Automatic 24-hour pricing staleness checking
+- **npm scripts**: pricing:show, pricing:check, pricing:update, pricing:set
+
+#### Pricing Features
+- **Multi-Model Support**: Each provider can have multiple models with different pricing
+- **Auto-Staleness Check**: Warns users when pricing >24 hours old
+- **Interactive Updates**: Easy-to-use CLI with colorized output
+- **Pricing URLs**: Direct links to provider pricing pages
+- **Timestamp Tracking**: lastUpdated and lastChecked timestamps
+
+### Changed
+
+#### Documentation Reorganization 📚
+- **Root Cleanup**: Reduced root markdown files from 15 to 3 (80% reduction)
+- **New Structure**: Organized documentation into logical directories
+  - docs/guides/ - User-facing documentation (8 files)
+  - docs/integrations/ - Third-party integrations (5 files)
+  - docs/development/ - Internal development docs (6 files)
+  - docs/releases/ - Release notes archive (2 files)
+  - docs/archive/ - Historical documentation (10 files)
+- **README Files**: Added README.md in each docs subdirectory
+- **CLAUDE.md**: Added documentation structure reference section
+
+#### Provider Improvements
+- **Graceful Degradation**: MCP server now starts successfully without API keys
+- **Better Error Messages**: Enhanced guidance to configure_provider tool
+- **Provider Checking**: Only validates providers when actually needed
+
+#### Wording Updates
+- Removed "free" marketing language throughout codebase
+- Changed to "$0.00" or "no-cost" terminology
+- Kept "Nano Banana" branding as requested
+- Updated Gemini provider display text and comments
+
+### Fixed
+- MCP server no longer crashes on startup when no API keys configured
+- Clear error messages guide users to proper configuration steps
+
+## [0.4.0] - 2026-01-13
+
+### Added
+
+#### Visual Forge Workflow Session Management 🔄
+- **vf_start_session**: Initialize new workflow sessions with git branch integration
+- **vf_process_files**: Automated placeholder addition and image spec parsing
+- **vf_generate_session**: Complete session image generation with auto-document updates
+- **vf_regenerate_image**: Regenerate specific images with new prompts/providers
+- **vf_finalize_session**: Commit changes and create PRs via GitHub CLI
+- **vf_get_session**: Retrieve session information and status
+- **vf_list_sessions**: List all workflow sessions with filtering
+
+#### Session Management Features
+- **Session Persistence**: Full session state tracking across restarts
+- **Global Context**: Theme/style context prepended to all image prompts
+- **Git Integration**: Automatic branch creation and PR management
+- **Multi-File Workflows**: Process multiple files in a single session
+- **Session Recovery**: Resume interrupted sessions from saved state
+
+#### Backup Management Tools 🛡️
+- **approve_changes**: Approve modifications and delete backup files
+- **restore_from_backups**: Restore all files from backups
+- **list_backups**: Display current backup status and details
+
+#### Documentation
+- **VF_WORKFLOW.md**: Complete workflow guide
+- **WORKFLOW_IMPLEMENTATION_PLAN.md**: Technical implementation details
+- **WORKFLOW_IMPLEMENTATION_COMPLETE.md**: Implementation summary
+- **N8N_INTEGRATION_COMPLETE.md**: N8N integration documentation
+- **docs/N8N_INTEGRATION.md**: N8N setup and usage guide
+- **docs/N8N_QUICK_START.md**: Quick start guide for N8N
+- **docs/CONTINUE_SETUP.md**: Continue.dev integration guide
+- **docs/CURSOR_SETUP.md**: Cursor IDE setup guide
+
+#### Infrastructure
+- **src/session/**: Session management module
+- **src/git/**: Git operations integration
+- **src/placeholders/**: Placeholder injection system
+- **HTTP Server**: Optional HTTP API server (src/http-server.ts)
+- **OpenAPI Spec**: Complete API documentation (docs/openapi.yaml)
+
+#### Testing & Development
+- **test/helpers/**: Test utilities and mocks
+- **test/providers/**: Provider system tests
+- **DEVELOPER_TESTING_GUIDE.md**: Comprehensive testing guide
+- **MANUAL_TESTING_GUIDE.md**: Manual testing procedures
+
+#### Third-Party Integration
+- **n8n-nodes-visual-forge/**: Custom N8N nodes for Visual Forge
+- **n8n-workflows/**: Pre-built N8N workflow templates
+- **scripts/npm-manager.js**: NPM package management utilities
+
+### Changed
+- **StateManager**: Enhanced with session tracking and recovery
+- **MCP Server**: Added 10 new workflow and backup management tools
+- **WorkflowTools**: Complete workflow orchestration system
+- **Documentation Structure**: Reorganized and expanded
+
+### Fixed
+- **TESTING-GUIDE.md**: Replaced with DEVELOPER_TESTING_GUIDE.md
+
+### Technical Details
+
+#### New MCP Tools (10 total)
+| Tool | Purpose |
+|------|---------|
+| vf_start_session | Start workflow session |
+| vf_process_files | Add placeholders & parse |
+| vf_generate_session | Generate all images |
+| vf_regenerate_image | Regenerate specific image |
+| vf_finalize_session | Commit & create PR |
+| vf_get_session | Get session info |
+| vf_list_sessions | List sessions |
+| approve_changes | Approve file changes |
+| restore_from_backups | Restore from backups |
+| list_backups | List backup status |
+
+#### Session Architecture
+```
+Session Manager
+├── Session State (persistent)
+├── Git Integration (branches, commits, PRs)
+├── Placeholder Injection
+├── Image Generation Queue
+├── Document Update System
+└── Backup Integration
+```
+
+### Backward Compatibility
+- ✅ Fully backward compatible
+- ✅ Existing workflows unchanged
+- ✅ No breaking changes
+- ✅ New features optional
+
+---
+
+## [0.3.0] - 2026-01-13
+
+### Added
+
+#### HTML File Support 🌐
+- **Multi-Format Parser**: New `DocumentParser` class supporting multiple file formats
+- **HTML Handler**: Complete HTML file parsing and manipulation
+  - Parse image specifications from HTML comments (`<!-- VF_IMAGE: {...} -->`)
+  - Parse from `data-vf-*` attributes on `<img>` tags
+  - Automatic image insertion with clean HTML output
+  - Support for `.html` and `.htm` files
+- **File Handler Architecture**: Extensible architecture for future formats (.docx, .pptx)
+- **Mixed Format Projects**: Parse HTML and Markdown files in the same workflow
+
+#### Backup System Integration ✅
+- **Automatic Backups**: Files backed up before modification during workflow
+- **Workflow Integration**: BackupManager integrated into WorkflowTools
+- **Reminder System**: 24-hour reminder checks on session start
+- **Workflow Messages**: Backup status included in generation responses
+- **Complete Documentation**: Comprehensive guides for backup workflow
+
+#### Testing
+- **HTML Handler Tests**: 18 comprehensive tests covering parsing and insertion
+- **Workflow Integration Tests**: 14 tests for backup workflow lifecycle
+- **Total Test Coverage**: 77 tests (all passing)
+
+### Changed
+- **DocumentParser**: Replaced MarkdownParser in workflow tools for multi-format support
+- **README**: Updated features to highlight HTML support and backup system
+- **Description**: Updated package description to include HTML support
+
+### Dependencies
+- **Added**: `cheerio@^1.0.0` for HTML parsing (~180KB)
+
+### Documentation
+- **docs/HTML_SUPPORT.md**: Complete HTML support guide with examples
+- **docs/WORKFLOW_WITH_BACKUPS.md**: Workflow integration guide
+- **docs/BACKUP_SYSTEM.md**: Complete backup system reference
+- **RELEASE_NOTES_v0.3.0.md**: Detailed release notes
+
+### Security
+- ✅ **Snyk Scan**: Zero vulnerabilities found (198 dependencies scanned)
+- ✅ **License Compliance**: All licenses verified
+
+### Technical Details
+
+#### Architecture Changes
+```
+FileHandler (interface)
+├── MarkdownHandler (.md, .markdown)
+├── HTMLHandler (.html, .htm)
+└── DocumentParser (orchestrator)
+```
+
+#### Test Coverage
+| Component | Tests | Status |
+|-----------|-------|--------|
+| Provider System | 21 | ✅ Pass |
+| Backup Manager | 24 | ✅ Pass |
+| HTML Handler | 18 | ✅ Pass |
+| Workflow Integration | 14 | ✅ Pass |
+| **Total** | **77** | **✅ All Pass** |
+
+### Backward Compatibility
+- ✅ Fully backward compatible
+- ✅ Existing Markdown workflows unchanged
+- ✅ No breaking changes
+
+---
+
+## [0.1.0] - 2026-01-13
+
+### Added
+
+#### Core Features
+- **Multi-Provider Architecture**: Support for 7 AI image generation providers
+  - OpenAI GPT Image 1 ($0.04-0.12/image)
+  - Google Gemini 2.5 Flash Image ($0.039/image)
+  - Stability AI SDXL 1.0 ($0.04/image)
+  - Replicate FLUX Schnell ($0.003/image)
+  - Leonardo Phoenix ($0.02/image)
+  - HuggingFace Inference (FREE)
+  - xAI Grok 2 Image ($0.07/image)
+- **Provider Factory Pattern**: Easy provider initialization and management
+- **Base Provider Abstract Class**: Consistent interface across all providers
+- **Rate Limiting**: Token bucket algorithm per provider to prevent API bans
+- **Cost Tracking**: Real-time cost monitoring and estimation per provider
+- **Quality Inspection Module**: Automated image quality analysis
+  - Sharpness detection (Laplacian variance)
+  - Brightness analysis (0-255 scale)
+  - File size validation
+  - Dimension verification
+  - Format checking
+
+#### Provider Implementations
+
+**Google Gemini Provider**
+- Full API integration with Gemini 2.5 Flash Image (Nano Banana)
+- Correct endpoint: `/v1beta/models/gemini-2.5-flash-image:generateContent`
+- Custom authentication header: `x-goog-api-key`
+- SynthID watermarking support
+- Multilingual prompt support
+- 100% success rate in testing
+
+**OpenAI GPT Image Provider**
+- Support for GPT Image 1 model
+- Quality modes: standard ($0.04) and HD ($0.08-0.12)
+- Removed unsupported parameters (style, response_format) for GPT Image models
+- PNG output format
+
+**Stability AI Provider**
+- SDXL 1.0 engine support
+- Custom dimension mapping for SDXL-compatible sizes
+- Multi-image generation support (samples parameter)
+- Credit-based cost tracking
+
+**Replicate Provider**
+- FLUX Schnell model support (fast, cost-effective)
+- Async prediction API with polling
+- Most cost-effective option at $0.003/image
+
+**Leonardo Provider**
+- Phoenix model support
+- Credit-based pricing
+
+**HuggingFace Provider**
+- Router endpoint: `https://router.huggingface.co`
+- Free model support
+
+**xAI Grok Provider**
+- Grok 2 Image model support
+- Automatic prompt revision by chat model
+- JPG output format (not PNG)
+- OpenAI-compatible API format
+
+#### Generation Scripts
+- `check-providers.ts`: Provider status and configuration checker
+- `generate-with-gemini.ts`: Gemini-specific generation
+- `generate-with-xai.ts`: xAI Grok-specific generation
+- `generate-all-providers.ts`: Multi-provider comparison tool
+- `generate-solo-theme-test.ts`: Versioning test with unified theme
+
+#### Documentation
+- Comprehensive README.md with installation instructions
+- Detailed provider comparison table
+- Cost analysis for 151-image project
+- MCP client configuration examples for 5+ clients
+- Troubleshooting guide
+- API key setup documentation
+
+#### Developer Tools
+- TypeScript strict mode enabled
+- ES2022 target
+- Type definitions for all interfaces
+- Logger utility with structured logging
+- HTTP client wrapper with axios-retry
+- Rate limiter with configurable limits
+
+### Fixed
+- **Gemini API Integration**: Fixed 404 errors by correcting endpoint, authentication, and request format
+- **OpenAI GPT Image**: Removed unsupported 'style' and 'response_format' parameters
+- **Stability AI SDXL**: Fixed dimension validation with SDXL-compatible size mapping
+- **Abstract Property Access**: Created `init()` method pattern to avoid accessing abstract properties in constructor
+
+### Changed
+- Updated provider factory to use Gemini as default (high success rate, good pricing)
+- Changed HuggingFace endpoint to `https://router.huggingface.co`
+- Improved error messages with actionable solutions
+
+### Technical Details
+
+#### Dependencies
+- `@modelcontextprotocol/sdk`: ^1.25.2
+- `zod`: ^3.25.0 (validation)
+- `axios`: ^1.7.0 (HTTP client)
+- `axios-retry`: ^4.5.0 (retry logic)
+- `sharp`: ^0.33.0 (image processing)
+- `dotenv`: ^16.4.0 (env management)
+
+#### File Structure
+```
+src/
+├── providers/       # 7 provider implementations
+├── quality/         # Quality inspection module
+├── state/           # State management (future)
+├── types/           # TypeScript definitions
+└── utils/           # Logger, rate limiter, HTTP client
+```
+
+#### Testing Results
+- **Gemini**: 6/6 images (100% success rate)
+- **Stability AI**: 3/6 images (ran out of credits)
+- **xAI Grok**: 2/6 images (intermittent access)
+- **Total generated**: 23 test images across providers
+- **Total cost**: ~$0.494
+
+### Known Issues
+- HuggingFace provider needs additional fixes (404 errors)
+- OpenAI GPT Image needs rerun with fixed build
+- xAI Grok has intermittent API access
+- Text in AI-generated diagrams is often illegible (known AI limitation)
+
+### Coming Soon (v0.2.0)
+- Full MCP server implementation
+- Markdown parser for visual guides
+- Interactive, batch, and bulk workflow modes
+- State persistence and session resumption
+- Additional provider support
+- REST API mode
+
+---
+
+## Versioning Notes
+
+This project follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for new functionality in a backwards compatible manner
+- **PATCH** version for backwards compatible bug fixes
+
+---
+
+[0.1.0]: https://github.com/yourusername/visual-forge-mcp/releases/tag/v0.1.0