@dollhousemcp/mcp-server 1.9.13 → 1.9.15

package/README.md.backup

@@ -1,17 +1,323 @@
 # DollhouseMCP
 
-[![npm version](https://img.shields.io/npm/v/@dollhousemcp/mcp-server.svg)](https://www.npmjs.com/package/@dollhousemcp/mcp-server)
+## Project Status
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io)
+[![npm version](https://img.shields.io/npm/v/@dollhousemcp/mcp-server.svg)](https://www.npmjs.com/package/@dollhousemcp/mcp-server)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![GitHub Views](https://komarev.com/ghpvc/?username=DollhouseMCP&repo=mcp-server&label=Repository+Views&style=flat)](https://github.com/DollhouseMCP/mcp-server/graphs/traffic)
+
+## Build & Quality
 [![Core Build & Test](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml/badge.svg)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml)
+[![Build Artifacts](https://github.com/DollhouseMCP/mcp-server/actions/workflows/build-artifacts.yml/badge.svg)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/build-artifacts.yml)
+[![Test Coverage](https://img.shields.io/badge/Coverage-1858%2B%20Tests-green)](https://github.com/DollhouseMCP/mcp-server/tree/develop/test/__tests__)
+[![Enterprise-Grade Security](https://img.shields.io/badge/Security-Enterprise%20Grade-purple)](https://github.com/DollhouseMCP/mcp-server/blob/develop/SECURITY.md)
+
+## Platform Support
+[![Windows Build Status](https://img.shields.io/badge/Windows-✓_Tested-0078D4?logo=windows&logoColor=white)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml?query=branch:main "Windows CI Build Status")
+[![macOS Build Status](https://img.shields.io/badge/macOS-✓_Tested-000000?logo=apple&logoColor=white)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml?query=branch:main "macOS CI Build Status")
+[![Linux Build Status](https://img.shields.io/badge/Linux-✓_Tested-FCC624?logo=linux&logoColor=black)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml?query=branch:main "Linux CI Build Status")
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&logoColor=white)](https://github.com/DollhouseMCP/mcp-server/blob/main/Dockerfile)
+
+## Technology
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Extended Node Compatibility](https://github.com/DollhouseMCP/mcp-server/actions/workflows/extended-node-compatibility.yml/badge.svg)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/extended-node-compatibility.yml)
+[![Docker Testing](https://github.com/DollhouseMCP/mcp-server/actions/workflows/docker-testing.yml/badge.svg)](https://github.com/DollhouseMCP/mcp-server/actions/workflows/docker-testing.yml)
 
-A comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management with an integrated GitHub-powered collection. DollhouseMCP allows Claude and other compatible AI assistants to activate different behavioral personas while supporting community sharing and monetization.
+---
 
 **🌐 Repository**: https://github.com/DollhouseMCP/mcp-server  
 **🏪 Collection**: https://github.com/DollhouseMCP/collection  
 **📦 NPM Package**: https://www.npmjs.com/package/@dollhousemcp/mcp-server  
 **🌍 Website**: https://dollhousemcp.com
 
+---
+
+<div align="center">
+  <img src="docs/assets/dollhouse-logo.png" alt="DollhouseMCP" width="200" />
+  
+  # Open Source, Community-Powered AI Customization
+  
+  ### Create, Edit, and Share Customization Elements for Your AI Platforms
+  
+  [![Install](https://img.shields.io/badge/Install-npm%20install%20@dollhousemcp/mcp--server-blue?style=for-the-badge)](https://www.npmjs.com/package/@dollhousemcp/mcp-server)
+  [![Collection](https://img.shields.io/badge/Browse-Community%20Collection-purple?style=for-the-badge)](https://github.com/DollhouseMCP/collection)
+  [![Contribute](https://img.shields.io/badge/Share-Your%20Elements-green?style=for-the-badge)](https://github.com/DollhouseMCP/mcp-server#contributing)
+</div>
+
+---
+
+## Elements That Customize Your AI's Capabilities and Actions
+
+**DollhouseMCP** is open source, community-powered AI customization. Create your own customization elements—personas that shape behavior, skills that add capabilities, templates for consistent outputs, agents for automation, and memories for persistent context—or use and modify an ever-growing number of customization elements from the community. Every element you create can be saved to your portfolio and used again or shared back to the DollhouseMCP Collection to help others.
+
+### What Are Customization Elements?
+
+- **Personas** – Shape how your AI acts and responds in specific domains
+- **Skills** – Add specialized capabilities your AI can use
+- **Templates** – Ensure consistent, high-quality outputs
+- **Agents** – Enable autonomous task completion with smart decision-making
+- **Memory** – Persistent context storage across sessions
+
+### Core Capabilities
+
+- **🌍  Community Element Library** – A growing number of tested personas, skills, templates, agents, and memories
+- **✨  Create Custom Elements** – Create personas, skills, templates, agents, and memories from scratch using natural language
+- **🤝  Open Source** – AGPL-3.0 licensed, ensuring community contributions stay free
+- **📚  The DollhouseMCP Collection** – Install any community element with one command
+- **🛠️  41 Professional Tools** – Complete toolkit for element creation and management
+- **🛡️  Security-First Validation** – All elements validated against hundreds of attack vectors
+- **⚡  Hot-Swap Elements** – Change personas, skills, and templates without restarting as needed
+- **📦  Personal Portfolio** – Your library of custom AI configurations on your local computer or personal GitHub repo
+
+### Use Cases
+
+<table>
+<tr>
+<td width="25%" align="center">
+<h4>👨‍💻 For Developers</h4>
+<p>Use community-powered code review personas and debugging skills. Share your language-specific optimizations.</p>
+</td>
+<td width="25%" align="center">
+<h4>✍️ For Writers</h4>
+<p>Access community-crafted writing styles and templates. Contribute your genre expertise.</p>
+</td>
+<td width="25%" align="center">
+<h4>🎯 For Professionals</h4>
+<p>Leverage community-built industry elements. Share your domain knowledge.</p>
+</td>
+<td width="25%" align="center">
+<h4>🌟 For Everyone</h4>
+<p>Give your AI any personality you want. Describe it, modify it, save it to your portfolio, share it with the world.</p>
+</td>
+</tr>
+</table>
+
+### Get Started
+
+```bash
+npm install @dollhousemcp/mcp-server
+```
+See [Quick Start](#-quick-start) for complete setup instructions.
+
+---
+
+## 🎯 Element Types
+
+### ✅ Available Now
+
+<table>
+<tr>
+<td width="50%">
+
+#### 🎭 Personas
+Shape how your AI behaves and responds
+- **Creative Writer** - Imaginative storyteller for engaging narratives
+- **Business Consultant** - Strategic advisor for business decisions
+- **Debug Detective** - Systematic problem-solver for code issues
+- **Security Analyst** - Vulnerability assessment and threat analysis
+- **Technical Analyst** - Deep dive technical documentation
+- **Use**: `"Activate the creative writer persona"`
+
+</td>
+<td width="50%">
+
+#### 💡 Skills
+Add specialized capabilities your AI can use
+- **Code Review** - Analyze code quality and suggest improvements
+- **Data Analysis** - Statistical analysis and visualization
+- **Language Translation** - Multi-language communication
+- **API Integration** - Connect and interact with external services
+- **Testing Automation** - Generate and run test suites
+- **Use**: `"Enable the code review skill"`
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+#### 📝 Templates
+Ensure consistent, high-quality outputs
+- **Project Proposal** - Structured business proposals
+- **Penetration Test Report** - Security assessment documentation
+- **Meeting Notes** - Organized meeting summaries
+- **Code Review** - Systematic code evaluation format
+- **Documentation** - Technical documentation structure
+- **Use**: `"Use the project proposal template"`
+
+</td>
+<td width="50%">
+
+#### 🤖 Agents
+Enable autonomous task completion
+- **Code Reviewer** - Automated code quality assessment
+- **Task Manager** - Project organization and tracking
+- **Research Assistant** - Information gathering and synthesis
+- **Academic Researcher** - Scholarly research and citations
+- **Security Fix Specialist** - Vulnerability remediation
+- **Use**: `"Run the code reviewer agent"`
+
+</td>
+</tr>
+<tr>
+<td colspan="2">
+
+#### 🧠 Memory <span style="background-color: #4CAF50; color: white; padding: 2px 6px; border-radius: 3px; font-size: 0.8em;">NEW in v1.9.0</span>
+Persistent context across sessions with intelligent organization
+- **Text-based storage** - Currently supports text content (PDFs, images, and other media types coming soon)
+- **Date-based folders** - Automatic YYYY-MM-DD organization prevents flat directory issues
+- **YAML format** - Human-readable structured data (vs Markdown for other elements)
+- **Smart deduplication** - SHA-256 hashing prevents duplicate storage
+- **Search indexing** - Fast queries across thousands of entries
+- **Use**: `"Create a memory for this project"` or `"Remember this conversation"`
+
+**Typical file sizes**: Single memories up to ~100KB, folder structure enables unlimited collections
+
+</td>
+</tr>
+</table>
+
+### 🚀 Coming Soon
+
+<table>
+<tr>
+<td width="50%">
+
+#### 🎯 Ensembles
+Combine multiple elements as one unified entity
+- **Full-Stack Developer** - Frontend + Backend + DevOps skills
+- **Writing Suite** - Creative + Technical + Editorial capabilities
+- **Security Team** - Analyst + Auditor + Remediation skills
+- **Data Science Platform** - Analysis + Visualization + ML skills
+- **Status**: In development
+
+</td>
+<td width="50%">
+
+#### 📋 Prompts
+Reusable instruction sets
+- **Code Review Checklist** - Systematic review steps
+- **Security Audit Guide** - Vulnerability assessment process
+- **Writing Guidelines** - Style and tone instructions
+- **Debug Workflow** - Problem-solving methodology
+- **Status**: Planned
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+#### 🔧 Tools
+External function calls and commands
+- **Git Operations** - Version control management
+- **Database Queries** - Direct database interaction
+- **API Calls** - External service integration
+- **File Operations** - Advanced file manipulation
+- **Status**: Under consideration
+
+</td>
+<td width="50%">
+
+#### 📚 Memory Enhancements
+Expanding memory capabilities
+- **PDF Support** - Text extraction from PDF documents
+- **Image Analysis** - Visual content understanding
+- **Audio Transcription** - Voice and sound processing
+- **Video Understanding** - Motion and scene analysis
+- **Status**: Roadmap planned
+
+</td>
+</tr>
+</table>
+
+## 💬 Natural Language Usage Examples
+
+DollhouseMCP is designed for natural language interaction. Just describe what you want in plain English - you don't need to be overly specific, the system will figure it out.
+
+### Importing from the Community Collection
+
+**Natural Language Examples:**
+- `"Show me all the personas in the Dollhouse Collection"`
+- `"What creative writing personas are available?"`
+- `"Install the storyteller persona from the collection"`
+- `"Search for Python development skills"`
+- `"Find templates for technical documentation"`
+
+**Direct Commands (if you prefer):**
+```bash
+browse_collection type="personas"
+search_collection "creative writing"
+install_content "personas/storyteller.md"
+```
+
+### Managing Your Portfolio
+
+**Natural Language Examples:**
+- `"What's in my portfolio?"`
+- `"Show me all my custom personas"`
+- `"Sync my portfolio with GitHub"`
+- `"Create a backup of my elements"`
+- `"Search my portfolio for marketing templates"`
+
+**Direct Commands (if you prefer):**
+```bash
+portfolio_status
+list_elements type="personas"
+sync_portfolio
+search_portfolio "marketing"
+```
+
+### Working with Elements
+
+**Natural Language Examples:**
+- `"Activate the code reviewer persona"`
+- `"What's currently active?"`
+- `"Switch to creative writing mode"`
+- `"Deactivate all elements"`
+- `"Show me details about the data analyst skill"`
+- `"Create a new persona for customer support"`
+- `"Edit the email template to be more formal"`
+
+**Direct Commands (if you prefer):**
+```bash
+activate_element "code-reviewer" type="personas"
+get_active_elements
+deactivate_element type="personas"
+get_element_details "data-analyst" type="skills"
+create_element type="personas" name="customer-support"
+```
+
+### Complete Workflow Example
+
+Here's how a typical session might look:
+
+```
+You: "I need help with creative writing"
+Assistant: "I'll help you with creative writing. Let me check what personas are available..."
+
+You: "Show me creative writing personas in the collection"
+Assistant: [Shows list of available creative writing personas]
+
+You: "Install and activate the storyteller persona"
+Assistant: "I've installed and activated the Storyteller persona. I'm now ready to help craft engaging narratives..."
+
+You: "Actually, let me create my own persona for science fiction writing"
+Assistant: "I'll help you create a custom science fiction writing persona. What characteristics would you like?"
+
+You: "Make it focus on hard sci-fi with attention to scientific accuracy"
+Assistant: [Creates custom persona with specified traits]
+
+You: "Save that to my portfolio as 'Hard SciFi Writer'"
+Assistant: "I've saved 'Hard SciFi Writer' to your portfolio. You can activate it anytime."
+```
+
+### Pro Tips
+
+- **Be conversational**: `"Help me write better code"` works as well as specific commands
+- **Stack elements**: `"Activate both the code reviewer and the Python expert"`  
+- **Save your favorites**: `"Save this configuration as my default setup"`
+- **Share with others**: `"Submit my custom persona to the community collection"`
+
 ## 📦 Installation
 
 ### Choose Your Installation Method
@@ -226,73 +532,959 @@ search_collection query="python" type="skills"
 | 🛡️ **Data Protection** | Copy-on-write for default personas, comprehensive backup system |
 | 🏠 **Local-First Architecture** | Full functionality without cloud dependency |
 
-## 🎨 Portfolio Elements
+## 🎨 Portfolio System
+
+The DollhouseMCP Portfolio system provides a comprehensive framework for managing AI elements locally and in the cloud.
+
+### Portfolio Structure
+
+Your portfolio is organized by element type:
 
-DollhouseMCP supports multiple element types for customizing AI behavior:
+```
+~/.dollhouse/portfolio/
+├── personas/       # Behavioral profiles (Markdown files)
+├── skills/         # Discrete capabilities (Markdown files)
+├── templates/      # Reusable content structures (Markdown files)
+├── agents/         # Goal-oriented actors (Markdown files)
+├── memories/       # Persistent context (YAML files with date folders)
+│   ├── 2025-09-18/
+│   │   └── project-context.yaml
+│   └── 2025-09-19/
+│       ├── meeting-notes.yaml
+│       └── code-review.yaml
+└── ensembles/      # Element combinations (Markdown files)
+```
+
+**Note on File Types:**
+- **Markdown (.md)**: Used for personas, skills, templates, agents, and ensembles - human-readable with YAML frontmatter
+- **YAML (.yaml)**: Used exclusively for memories - structured data optimized for context storage
+
+**Memory Organization:**
+- Memories use automatic **YYYY-MM-DD** folder structure to prevent flat directory performance issues
+- Each memory file can grow up to ~100KB before creating a new file
+- Folder structure enables unlimited memory collections without degradation
+
+### Key Features
+
+- **Local-First Architecture**: All elements stored locally with optional cloud sync
+- **GitHub Integration**: Sync your portfolio with GitHub for backup and sharing
+- **Version Control**: Full git integration for tracking changes
+- **Smart Detection**: Automatically identifies element types from content
+- **Flexible Naming**: Use any naming convention you prefer
+
+### Portfolio Management Tools
+
+Use the comprehensive set of MCP tools to manage your portfolio:
+
+- `list_portfolio_elements` - View all elements across types
+- `sync_portfolio` - Synchronize with GitHub
+- `upload_to_portfolio` - Share elements with the community
+- `download_from_portfolio` - Get elements from GitHub
+
+For detailed portfolio documentation, see the [Portfolio Guide](docs/guides/PORTFOLIO_SETUP_GUIDE.md).
+
+## 🔒 Security
+
+DollhouseMCP implements enterprise-grade security measures to protect your data and ensure safe operation.
+
+### Security Features
+
+- **Input Sanitization**: All user inputs validated and sanitized
+- **Path Traversal Prevention**: Filesystem access strictly controlled
+- **YAML Injection Protection**: Safe parsing with validation
+- **Command Injection Prevention**: No direct shell command execution
+- **Token Encryption**: OAuth tokens encrypted at rest
+- **Rate Limiting**: API calls throttled to prevent abuse
+- **Audit Logging**: Security events tracked for analysis
+
+### Security Testing
+
+- **Automated Security Scanning**: GitHub Advanced Security enabled
+- **Dependency Scanning**: Automated vulnerability detection
+- **Code Analysis**: Static analysis with CodeQL
+- **Secret Scanning**: Prevents credential leaks
+
+### Reporting Security Issues
+
+If you discover a security vulnerability, please:
+
+1. **DO NOT** create a public GitHub issue
+2. Open a private security advisory on GitHub
+3. Include steps to reproduce if possible
+4. Allow up to 48 hours for initial response
+
+For more details, see our [Security Policy](SECURITY.md).
+
+## 🛠️ Development
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/DollhouseMCP/mcp-server.git
+cd mcp-server
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+```
+
+### Development Workflow
+
+1. **Create Feature Branch**: `git checkout -b feature/your-feature`
+2. **Make Changes**: Implement your feature or fix
+3. **Run Tests**: `npm test`
+4. **Build**: `npm run build`
+5. **Submit PR**: Create pull request to develop branch
+
+### Available Scripts
+
+- `npm run build` - Compile TypeScript
+- `npm run dev` - Development mode with watch
+- `npm test` - Run test suite
+- `npm run lint` - Check code style
+- `npm run typecheck` - TypeScript type checking
+
+### Project Structure
+
+```
+src/
+├── index.ts           # Main server entry
+├── tools/            # MCP tool implementations
+├── utils/            # Utility functions
+├── types/            # TypeScript definitions
+└── elements/         # Element system
+```
+
+For detailed development guides, see [Development Documentation](docs/development/).
+
+## 🏭 Architecture
+
+### System Overview
+
+DollhouseMCP follows a modular, extensible architecture built on the Model Context Protocol (MCP) standard.
+
+### Core Components
+
+#### MCP Server
+- **Transport**: StdioServerTransport for Claude Desktop integration
+- **Protocol**: JSON-RPC 2.0 communication
+- **Tools**: 41 MCP tools for comprehensive functionality
 
-| Element | Purpose | Status |
-|---------|---------|--------|
-| 🎭 **Personas** | Define AI personality, tone, and behavioral characteristics | ✅ Available |
-| 🛠️ **Skills** | Add specific capabilities like code review, data analysis, or creative writing | ✅ Available |
-| 📝 **Templates** | Create reusable response formats for emails, reports, documentation | ✅ Available |
-| 🤖 **Agents** | Build autonomous assistants that can pursue goals and make decisions | ✅ Available |
-| 💬 **Prompts** | Pre-configured conversation starters and structured interactions | 🔄 Coming Soon |
-| 🧠 **Memory** | Persistent context storage with retention policies and search capabilities | 🔄 Coming Soon |
-| 🎯 **Ensemble** | Orchestrate multiple elements together as one unified entity | 🔄 Coming Soon |
+#### Element System
+- **BaseElement**: Abstract base class for all elements
+- **IElement Interface**: Common contract for elements
+- **Element Types**: Personas, Skills, Templates, Agents, Memories, Ensembles
 
-Your portfolio lives in `~/.dollhouse/portfolio/` with elements organized by type.
+#### Portfolio Manager
+- **Local Storage**: File-based element storage
+- **GitHub Sync**: Git-based synchronization
+- **Version Control**: Full git integration
 
-## 🔧 Troubleshooting
+#### Security Layer
+- **Input Validation**: All inputs sanitized
+- **Path Security**: Traversal prevention
+- **Token Management**: Encrypted storage
+
+### Data Flow
+
+1. **Client Request** → MCP Server
+2. **Tool Routing** → Appropriate handler
+3. **Element Processing** → Element system
+4. **Storage** → Portfolio manager
+5. **Response** → Client
+
+For detailed architecture documentation, see [Architecture Guide](docs/ARCHITECTURE.md).
+
+## 🎯 Troubleshooting
 
 ### Common Issues
 
-| Issue | Solution |
-|-------|----------|
-| **Personas not loading** | Check `~/.dollhouse/portfolio/personas/` directory exists |
-| **Server won't start** | Ensure Node.js v20+ is installed: `node --version` |
-| **Collection not working** | Check internet connection and GitHub API access |
-| **Tools not appearing in Claude** | Restart Claude Desktop completely after config changes |
-| **"Cannot find module" errors** | Reinstall: `npm install -g @dollhousemcp/mcp-server@latest` |
-| **Rate limit errors** | Wait 60 seconds; GitHub API has hourly limits |
+#### MCP Server Not Connecting
+
+**Symptoms**: Claude Desktop doesn't show DollhouseMCP in available servers
+
+**Solutions**:
+1. Verify configuration file location:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+2. Check JSON syntax is valid
+3. Restart Claude Desktop after configuration changes
+
+#### OAuth Authentication Fails
+
+**Symptoms**: Cannot authenticate with GitHub
+
+**Solutions**:
+1. Check internet connection
+2. Verify GitHub account has proper permissions
+3. Try using Personal Access Token instead:
+   ```bash
+   export GITHUB_TOKEN=your_pat_token
+   ```
+4. Clear cached credentials and retry
+
+#### Elements Not Loading
+
+**Symptoms**: Portfolio appears empty
+
+**Solutions**:
+1. Check portfolio directory exists: `~/.dollhouse/portfolio/`
+2. Verify file permissions
+3. Run `list_portfolio_elements` tool to diagnose
+4. Check element file format (YAML frontmatter required)
+
+#### Performance Issues
+
+**Symptoms**: Slow response times
+
+**Solutions**:
+1. Check portfolio size (large portfolios may be slow)
+2. Verify adequate system resources
+3. Consider using pagination for large lists
+4. Check network latency for GitHub operations
+
+### Getting Help
+
+- **Documentation**: [Full docs](https://github.com/DollhouseMCP/mcp-server/tree/main/docs)
+- **Issues**: [GitHub Issues](https://github.com/DollhouseMCP/mcp-server/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/DollhouseMCP/mcp-server/discussions)
+
+For detailed troubleshooting, see [Troubleshooting Guide](docs/troubleshooting/).
+
+## 🤝 Contributing
+
+We welcome contributions to DollhouseMCP! Here's how you can help:
+
+### Ways to Contribute
 
-### Need Help?
+- **🐛 Report Bugs**: Open an issue with reproduction steps
+- **✨ Request Features**: Suggest new functionality
+- **📝 Improve Documentation**: Fix typos, add examples
+- **💻 Submit Code**: Fix bugs or implement features
+- **🎨 Share Elements**: Contribute personas, skills, templates
 
-- 📖 [Full Troubleshooting Guide](docs/TROUBLESHOOTING.md)
-- 💬 [GitHub Issues](https://github.com/DollhouseMCP/mcp-server/issues)
-- 💭 [GitHub Discussions](https://github.com/DollhouseMCP/mcp-server/discussions)
+### Development Process
+
+1. **Fork the Repository**
+   ```bash
+   gh repo fork DollhouseMCP/mcp-server
+   ```
+
+2. **Create Feature Branch**
+   ```bash
+   git checkout -b feature/your-feature
+   ```
+
+3. **Make Changes**
+   - Follow existing code style
+   - Add tests for new functionality
+   - Update documentation
+
+4. **Test Thoroughly**
+   ```bash
+   npm test
+   npm run lint
+   npm run typecheck
+   ```
+
+5. **Submit Pull Request**
+   - Target the `develop` branch
+   - Provide clear description
+   - Reference any related issues
+
+### Code Style
+
+- TypeScript with strict mode
+- ESLint configuration provided
+- Prettier for formatting
+- Comprehensive JSDoc comments
+
+### Commit Messages
+
+Follow conventional commits:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `test:` Testing
+- `chore:` Maintenance
+
+### Review Process
+
+1. Automated CI checks must pass
+2. Code review by maintainers
+3. Address feedback
+4. Merge when approved
+
+For detailed guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## 📚 Resources
 
 ### Documentation
-- [Roundtrip Workflow Guide](docs/guides/ROUNDTRIP_WORKFLOW_USER_GUIDE.md)
-- [Portfolio Setup Guide](docs/guides/PORTFOLIO_SETUP_GUIDE.md)
-- [Element Detection Guide](docs/guides/ELEMENT_DETECTION_GUIDE.md)
-- [PersonaTools Migration Guide](docs/PERSONATOOLS_MIGRATION_GUIDE.md)
-- [API Documentation](docs/API.md)
+
+- **[Quick Start Guide](docs/QUICK_START.md)** - Get up and running quickly
+- **[Portfolio Setup](docs/guides/PORTFOLIO_SETUP_GUIDE.md)** - Configure your portfolio
+- **[Element Development](docs/ELEMENT_DEVELOPER_GUIDE.md)** - Create custom elements
+- **[API Reference](docs/API_REFERENCE.md)** - Complete tool documentation
+- **[Architecture Guide](docs/ARCHITECTURE.md)** - System design details
+- **[Security Documentation](docs/SECURITY.md)** - Security measures and best practices
+
+### Repositories
+
+- **[Main Repository](https://github.com/DollhouseMCP/mcp-server)** - Core MCP server
+- **[Collection](https://github.com/DollhouseMCP/collection)** - Community elements
+- **[Developer Kit](https://github.com/DollhouseMCP/developer-kit)** - Development tools
 
 ### Community
-- [GitHub Repository](https://github.com/DollhouseMCP/mcp-server)
-- [NPM Package](https://www.npmjs.com/package/@dollhousemcp/mcp-server)
-- [Community Collection](https://github.com/DollhouseMCP/collection)
-- [Discord Community](https://discord.gg/dollhousemcp) (coming soon)
 
-### Development
-- [Contributing Guide](CONTRIBUTING.md)
-- [Security Policy](SECURITY.md)
-- [Full Changelog](CHANGELOG.md)
+- **[GitHub Discussions](https://github.com/DollhouseMCP/mcp-server/discussions)** - Q&A and ideas
+- **[GitHub Issues](https://github.com/DollhouseMCP/mcp-server/issues)** - Bug reports and features
+- **[Discord Server](#)** - Real-time chat (coming soon)
+
+### External Resources
+
+- **[Model Context Protocol](https://modelcontextprotocol.io)** - MCP specification
+- **[Claude Desktop](https://claude.ai/download)** - AI assistant with MCP support
+- **[Anthropic Documentation](https://docs.anthropic.com)** - Claude documentation
+
+### Learning Materials
+
+- **Tutorials** (coming soon)
+  - Building Your First Persona
+  - Creating Custom Skills
+  - Portfolio Management Best Practices
+  - GitHub Integration Setup
+
+- **Videos** (coming soon)
+  - Installation Walkthrough
+  - Feature Demonstrations
+  - Developer Tutorials
+
+### Support
+
+- **GitHub Issues**: [Report issues or request features](https://github.com/DollhouseMCP/mcp-server/issues)
+- **Security Issues**: [Private security advisories](https://github.com/DollhouseMCP/mcp-server/security/advisories)
+- **Discussions**: [Community Q&A](https://github.com/DollhouseMCP/mcp-server/discussions)
+
+## 🏷️ Version History
+
+### v1.9.15 - October 1, 2025
+
+**Security Patch**: Zero-width Unicode bypass vulnerability + SonarCloud cleanup
+
+#### 🔒 Security Fix [HIGH]
+- **Zero-width Unicode bypass vulnerability** - Restored Unicode security validation (#1228, #1229)
+  - Blocks zero-width characters (U+200B-U+200F, U+FEFF) in metadata validation
+  - Prevents steganography and homograph attacks
+  - Fixed `validateContent` bypass in DefaultElementProvider
+  - Restored security validation chain through ContentValidator and UnicodeValidator
+
+#### 🧹 Code Quality
+- **228+ SonarCloud issues resolved** across 5 issues (#1220-1224):
+  - S7773: Modernized Number parsing methods (90 issues) - `parseInt()` → `Number.parseInt()`
+  - S7781: String.replaceAll modernization (134 issues) - `.replace(/g)` → `.replaceAll()`
+  - MEDIUM severity fixes (4 issues) - Object literals, loop counters, Promise types
+  - False positives marked (11 issues) - Test-only patterns properly categorized
+- **199 security hotspots evaluated** - All marked SAFE, zero production concerns (#1219)
+  - Math.random(), MD5, PATH usage validated for non-security contexts
+  - Comprehensive documentation of safe patterns
+
+#### 📊 Impact
+- ✅ 1 HIGH severity security vulnerability fixed
+- ✅ All production security concerns resolved
+- ✅ Test coverage maintained at >96%
+
+### v1.9.14 - September 30, 2025
+
+**Bug Fixes**: ElementFormatter and portfolio search improvements
+
+#### 🔧 Fixed
+- **ElementFormatter Security Scanner False Positives** - Fixed validation option being ignored (#1211, #1212)
+  - SecureYamlParser now properly respects `validateContent: false` option
+  - ElementFormatter uses `validateContent: false` for all YAML parsing (5 locations)
+  - Local trusted files can bypass content scanning while maintaining security for untrusted sources
+
+- **Portfolio Search File Extension Display** - Fixed incorrect extension display (#1213, #1215)
+  - Portfolio search now shows correct file extensions based on element type
+  - Memories display `.yaml` extension, other elements show `.md` extension
+
+#### 📚 Documentation
+- Added SONARCLOUD_QUERY_PROCEDURE.md - Critical guide for querying SonarCloud correctly
+- Updated CLAUDE.md with naming conventions and style guide for session notes
+- Added session notes documentation for PR #1215
+
+#### 📊 Statistics
+- 2 Bug fixes merged (PR #1212, #1215)
+- 10 Code quality issues resolved
+- 2,277 tests passing with >96% coverage
+- Quality Gate: PASSING
+- Test Coverage: >96% maintained
+
+---
+
+### v1.9.13 - September 29, 2025
+
+**Memory System Critical Fixes**: Security scanner improvements and enhanced error reporting
+
+#### 🔧 Fixed
+- **Security Scanner False Positives** - Fixed memory system rejecting legitimate security documentation (#1206, #1207)
+  - Memory files with security terms (vulnerability, exploit, attack) now load correctly
+  - Local memory files are now pre-trusted (validateContent: false)
+- **Silent Error Reporting** - Added visible error reporting for failed memory loads
+  - Users now see "Failed to load X memories" with detailed error messages
+  - New getLoadStatus() diagnostic method for troubleshooting
+- **Legacy Memory Migration** - New migration tool for old .md files
+  - Migrates to .yaml format in date-organized folders
+  - Safe archiving of original files, dry-run mode by default
+
+#### ✨ Added
+- CLI Utility: migrate-legacy-memories.ts for legacy file migration
+- Diagnostic Method: getLoadStatus() for memory loading diagnostics
+- Error Tracking: failedLoads tracking in MemoryManager
+
+#### 🛠️ Code Quality
+- Fixed SonarCloud S3776: Reduced cognitive complexity in getLoadStatus()
+- Fixed SonarCloud S3358: Replaced nested ternary with if-else chain
+- Fixed SonarCloud S7785: Use top-level await instead of promise chain
+- Extracted handleLoadFailure() to eliminate code duplication
+- Use os.homedir() for cross-platform reliability
+
+#### 🔒 Security
+- Fixed DMCP-SEC-004: Added Unicode normalization to CLI input validation
+
+#### 📊 Statistics
+- 3 Critical fixes merged in PR #1207
+- 7 Code quality issues resolved
+- 1 Security issue fixed
+- Quality Gate: PASSING
+- Test Coverage: >96% maintained
+
+---
+
+### v1.9.12 - September 29, 2025
+
+**Memory System Stability**: Portfolio index and test isolation improvements
+
+#### 🔧 Fixed
+- **Memory Metadata Preservation** - Fixed PortfolioIndexManager overwriting memory metadata (#1196, #1197)
+  - Memory descriptions now properly preserved instead of "Memory element"
+- **Test Isolation** - Fixed memory portfolio index tests contaminating real user portfolio (#1194, #1195)
+  - Tests now use temporary directories
+  - Added security validation for memory YAML parsing (size limits, type checking)
+- **ElementFormatter Tool** - Added tool for cleaning malformed elements (#1190, #1193)
+
+#### 🛠️ Code Quality
+- Fixed SonarCloud S7781: Use String#replaceAll() for modern string replacement
+- Fixed SonarCloud S1135: Removed TODO comments, documented test isolation patterns
+
+#### 🔒 Security
+- Added content size validation (1MB limit) for memory YAML parsing
+- Added type safety validation for parsed memory content
+- Documented security trade-offs with audit suppressions
+
+#### 📊 Statistics
+- Memory portfolio index tests: 8/8 passing (was 3/8)
+- Closed issues: #1196, #1194, #1190, #659, #404, #919
+- Quality Gate: PASSING
+- Test Coverage: >96% maintained
+
+---
+
+### v1.9.11 - September 28, 2025
+
+**SonarCloud Quality & Security**: Major code quality improvements and security fixes
+
+#### 🔒 Security Fixes
+- Fixed command injection vulnerabilities in GitHub Actions workflows (#1149)
+- Resolved ReDoS vulnerabilities in RelationshipManager (#1144)
+- All critical and high severity issues resolved
+
+#### 🛠️ Quality Improvements
+- **82% reduction in SonarCloud reliability bugs** (from 55 to 10)
+- Fixed unsafe throw in finally blocks (S1143)
+- Fixed async constructor patterns
+- Resolved regex precedence issues
+- Fixed control character usage
+- Removed hardcoded tokens
+
+#### 📊 Statistics
+- 11 Pull Requests merged for quality fixes
+- Quality Gate: PASSING
+- Security: All critical issues resolved
+- Test Coverage: >96% maintained
+
+### v1.9.10 - September 27, 2025
+
+**Enhanced Capability Index & Security**: Complete trigger extraction system and SonarCloud integration
+
+#### ✨ Major Features
+- **Enhanced Capability Index System** - NLP scoring with Jaccard similarity and Shannon entropy
+- **Cross-Element Relationships** - GraphRAG-style relationship mapping
+- **Complete Trigger Extraction** - All element types now support trigger extraction
+- **SonarCloud Integration** - Quality gate PASSING with 0% duplication
+
+#### 🔒 Security Improvements
+- Fixed 16 SonarCloud BLOCKER issues
+- GitHub Actions command injection vulnerabilities resolved
+- Full SHA pinning for all Actions
+- PATH manipulation vulnerability fixed
+
+#### 🛠️ Improvements
+- Extended Node compatibility fixes
+- Enhanced Index stability improvements
+- Type-safe relationship parsing
+- Docker Hub rate limit mitigation
+- Test isolation and CI improvements
+
+#### 📊 Statistics
+- 34 Pull Requests merged
+- Test Coverage: 98.17%
+- Security Hotspots: 100% reviewed
+- Code Duplication: 0% on new code
+
+---
+
+### v1.9.9 - September 22, 2025
+
+**Security & Stability**: Prototype pollution protection and memory timestamp fixes
+
+#### ✨ Features
+- **Security Utilities**: New reusable security module for prototype pollution protection
+- **Memory Auto-Repair**: Corrupted memory timestamps now auto-repair during read operations
+- **Enhanced Validation**: Comprehensive timestamp validation with detailed error reporting
+
+#### 🔧 Fixed
+- **Memory Timestamps**: Fixed toISOString errors when memory entries have string timestamps (#1069)
+- **Security Badge**: Fixed broken security badge link in README pointing to wrong location
+- **Prototype Pollution**: Added belt-and-suspenders protection to satisfy code scanners (#202-#205)
+
+#### 🔒 Security
+- Added `securityUtils.ts` module with reusable security patterns
+- Implemented Object.create(null) for prototype-less objects
+- Added Object.defineProperty() for secure property setting
+- Proper CodeQL suppressions for validated false positives
+
+---
+
+### v1.9.8 - September 20, 2025
+
+**Memory System Complete**: Full CRUD operations and enhanced memory management
+
+#### ✨ Features
+- **Memory CRUD Operations**: Complete create, read, update, delete functionality for memories
+- **Memory Editing**: Full support for editing memory fields including metadata and content
+- **Memory Validation**: Comprehensive validation with detailed error reporting
+- **Enhanced Search**: Improved search across all sources with duplicate detection
+
+#### 🔧 Fixed
+- **Memory Display**: Fixed "No content stored" issue when memories have valid content
+- **Test Coverage**: Maintained >96% test coverage with comprehensive memory tests
+- **Documentation**: Updated all documentation to reflect new memory features
+
+---
+
+### v1.9.7 - September 20, 2025
+
+**NPM Package Fix**: Corrected build issue from v1.9.6
+
+#### 🔧 Fixed
+- **NPM Package Build**: Republished with correct commit including all memory display fixes
+- **Memory Display**: Memories now correctly show content instead of "No content stored"
+- Note: v1.9.6 NPM package was accidentally built from wrong commit
+
+---
+
+### v1.9.6 - September 20, 2025
+
+**🎉 First External Contribution**: Performance and security improvements from the community!
+
+#### ✨ Highlights
+- **Fixed**: Memory display bug - added content getter to Memory class (PR #1036)
+- **Fixed**: Flaky macOS tests on Node 22+ (PR #1038)
+- **Enhanced**: Optimized whitespace detection for better performance (PR #1037)
+- **Security**: Strengthened path traversal protection (PR #1037)
+- **Attribution**: Thanks to @jeetsingh008 for identifying improvements!
+
+---
+
+### v1.9.5 - September 19, 2025
+
+**Memory YAML Parsing Fix**: Resolved display issues with pure YAML memory files
+
+#### 🔧 Bug Fixes
+- **Fixed**: Memory files showing incorrect names for pure YAML format
+- **Enhanced**: Added comprehensive test coverage for memory file formats
+- **Technical**: Improved compatibility between SecureYamlParser and pure YAML
+
+---
+
+### v1.9.4 - September 19, 2025
+
+**Memory Name Display Fix**: Corrected "Unnamed Memory" display issue
+
+#### 🔧 Bug Fixes
+- **Fixed**: Memory elements showing as "Unnamed Memory" in list output
+- **Fixed**: Corrected metadata parsing path in SecureYamlParser
+- **Technical**: Added retention format parsing for various formats
+
+---
+
+### v1.9.3 - September 19, 2025
+
+**Memory Element MCP Support**: Complete MCP tool handler integration
+
+#### 🔧 Bug Fixes
+- **Fixed**: Added Memory element support to all MCP tool handlers
+- **Fixed**: Resolved "Unknown element type 'memories'" errors
+- **Technical**: Added Memory case handling to 8 critical methods
+
+---
+
+### v1.9.2 - September 19, 2025
+
+**Branch Synchronization**: Documentation and configuration alignment
+
+#### 🔧 Improvements
+- **Fixed**: Resolved divergence between main and develop branches
+- **Enhanced**: Updated documentation to reflect all features
+- **Technical**: Merged 58 commits from develop branch
+
+---
+
+### v1.9.1 - September 19, 2025
+
+**Memory Element Hotfix**: Fixed validation and tool descriptions
+
+#### 🔧 Bug Fixes
+- **Fixed**: Added 'memories' to validation arrays
+- **Fixed**: Updated collection tool descriptions
+- **Technical**: Clean hotfix for memory element support
+
+---
+
+### v1.9.0 - September 19, 2025
+
+**🎉 Memory Element Release**: Persistent context storage with enterprise-grade features
+
+#### ✨ New Features
+- **Memory Element**: Complete implementation of persistent context storage (PR #1000 - The Milestone PR!)
+- **Date-based Organization**: Automatic folder structure (YYYY-MM-DD) prevents flat directory issues
+- **Content Deduplication**: SHA-256 hashing prevents duplicate storage (Issue #994)
+- **Search Indexing**: Fast queries across thousands of entries with O(log n) performance (Issue #984)
+- **Privacy Levels**: Three-tier access control (public, private, sensitive)
+- **Retention Policies**: Automatic cleanup based on age and capacity
+
+#### 🔧 Improvements
+- **Performance Optimizations**: 60-second cache for date folder operations
+- **Collision Handling**: Automatic version suffixes for same-named files
+- **Atomic Operations**: FileLockManager prevents corruption and race conditions
+- **Sanitization Caching**: SHA-256 checksums reduce CPU usage by ~40% during deserialization
+- **Retry Logic**: Search index building with exponential backoff
+
+#### 🛡️ Security
+- **Comprehensive Input Validation**: All memory content sanitized with DOMPurify
+- **Path Traversal Protection**: Robust validation in MemoryManager
+- **Size Limits**: DoS protection with 1MB memory and 100KB entry limits
+- **Audit Logging**: Complete security event tracking
+
+#### 🧪 Testing
+- **89 Memory Tests**: Comprehensive coverage across 4 test suites
+- **Concurrent Access Tests**: Thread safety verification
+- **Security Coverage**: XSS, Unicode attacks, path traversal
+- **CI Improvements**: Fixed GitHub integration test conflicts (PR #1001)
+
+---
+
+### v1.8.1 - September 15, 2025
+
+**CI Reliability Improvements**: Fixed persistent test failures across platforms
+
+#### 🔧 Bug Fixes
+- **GitHub API 409 Conflicts**: Enhanced retry mechanism with jitter for parallel CI jobs
+- **Windows Performance Tests**: Platform-specific timing thresholds for CI environments
+- **Test Stability**: Resolved flaky tests in Extended Node Compatibility workflow
+
+---
+
+### v1.8.0 - September 15, 2025
+
+**Major Portfolio System Enhancements**: Full GitHub portfolio synchronization
+
+#### ✨ New Features
+- **Portfolio Sync**: Complete bidirectional sync with GitHub portfolios
+- **Pull Functionality**: Download elements from GitHub portfolios (3 sync modes)
+- **Configurable Repos**: Portfolio repository names now configurable
+- **Configuration Wizard**: Now manual-only (removed auto-trigger for better UX)
+
+#### 🔧 Improvements
+- **Tool Clarity**: Renamed conflicting tools for better user experience
+- **Rate Limiting**: Fixed redundant token validation causing API limits
+- **GitHub Integration**: Comprehensive repository management
+
+---
+
+### v1.7.4 - September 12, 2025
+
+**Hotfix Release**: Critical build and registration fixes
+
+#### 🔧 Bug Fixes
+- **Build Infrastructure**: Fixed missing TypeScript files in dist
+- **Tool Registration**: Resolved MCP tool availability issues
+- **Skill System**: Fixed skill registration and activation
+- **Test Framework**: Restored test infrastructure functionality
+
+---
+
+### v1.7.3 - September 9, 2025
+
+**Security & Configuration Release**: Prototype pollution protection and config management
+
+#### 🛡️ Security
+- **Prototype Pollution Protection**: Comprehensive validation against injection attacks
+- **YAML Security**: Maintained FAILSAFE_SCHEMA with security documentation
+- **Security Audit**: Achieved 0 security findings across all severity levels
+
+#### ✨ Improvements
+- **Configuration Management**: Complete overhaul with atomic operations
+- **Test Coverage**: Comprehensive security and configuration tests
+- **Input Normalization**: All inputs normalized at MCP request layer
+
+---
+
+### v1.7.2 - September 7, 2025
+
+**Security Patch Release**: Critical logging vulnerability fixes
+
+#### 🛡️ Security Fixes
+- **Clear-text Logging Prevention**: Comprehensive sanitization of sensitive data
+- **OAuth Token Protection**: Prevents exposure of tokens in console output
+- **API Key Sanitization**: Masks all credentials before logging
+
+---
+
+### v1.7.1 - September 3, 2025
+
+**Maintenance Release**: Documentation and compatibility improvements
+
+#### 🔧 Improvements
+- **Documentation**: Updated for better clarity and accuracy
+- **Compatibility**: Enhanced cross-platform support
+- **Bug Fixes**: Various minor fixes and optimizations
+
+---
+
+### v1.7.0 - August 30, 2025
+
+**Major Feature Release**: Enhanced portfolio and collection systems
+
+#### ✨ New Features
+- **Portfolio Management**: Improved local portfolio organization
+- **Collection Integration**: Better integration with community collection
+- **Security Enhancements**: Critical security fixes from code review
+
+---
+
+### v1.6.11 - August 28, 2025
+
+**Test Reliability & Collection Fixes**: Improved test suite stability and fixed collection system
+
+#### 🔧 Bug Fixes
+- **Collection Index URL**: Fixed to use GitHub Pages for better reliability
+- **E2E Test Tokens**: Improved token prioritization for CI environments
+- **Response Format**: Enhanced compatibility with various response formats
+- **Type Safety**: Improved TypeScript types throughout test suite
+
+#### ✨ Improvements
+- Added helper functions for better code organization
+- Enhanced test reliability in CI/CD pipelines
+- General code quality improvements
+
+---
+
+### v1.6.10 - August 28, 2025
+
+**Collection Submission Fix**: Critical fix for collection submission pipeline
+
+#### 🔧 Bug Fixes
+- **Collection Submission**: Fixed workflow failing due to missing element types
+- **Local Path Parameter**: Added missing localPath parameter to submission tool
+- **Duplicate Detection**: Added detection for duplicate portfolio uploads and collection issues
+
+#### ✨ Improvements
+- Added comprehensive QA tests for collection submission validation
+- Cleaned up QA documentation files
+- Updated all documentation to v1.6.10
+
+---
+
+### v1.6.9 - August 26, 2025
+
+**Critical Fixes**: Fixed OAuth helper NPM packaging and performance testing workflow
+
+#### 🔧 Bug Fixes
+- **OAuth NPM Packaging**: Fixed missing `oauth-helper.mjs` file in NPM distribution
+  - File was present in repository but not included in published package
+  - OAuth authentication now works correctly for NPM users
+- **Performance Tests**: Fixed CI workflow running all tests instead of performance tests
+  - Performance monitoring now works correctly in GitHub Actions
+
+---
+
+### v1.6.3 - August 25, 2025
+
+**OAuth Authentication Fix**: Fixed invalid OAuth client ID and improved error handling
+
+#### 🔧 Bug Fixes
+- **OAuth Client ID**: Updated from incorrect ID to correct `Ov23li9gyNZP6m9aJ2EP`
+- **Error Messages**: Improved clarity of OAuth error messages for better debugging
+- **Setup Tool**: Fixed `setup_github_auth` tool to properly handle authentication flow
+
+---
+
+### v1.6.2 - August 25, 2025
+
+**Critical Hotfix**: Fixed OAuth default client ID not being used in `setup_github_auth` tool
+
+#### 🔧 Bug Fixes
+- **OAuth Default Client**: Fixed `setup_github_auth` tool not using default client ID when none provided
+- **Authentication Flow**: Restored ability to authenticate without manual client ID entry
+
+#### 📝 Documentation
+- Added troubleshooting guide for OAuth issues
+- Updated setup instructions with clearer OAuth configuration steps
+
+---
+
+### v1.6.1 - August 25, 2025
+
+**⚠️ Breaking Changes**:
+- 🔄 **Serialization Format Change** - `BaseElement.serialize()` now returns markdown with YAML frontmatter instead of JSON
+
+#### 🔧 Bug Fixes
+- **Serialization Format**: Fixed `BaseElement.serialize()` to return markdown format
+  - Changed from JSON string to markdown with YAML frontmatter
+  - Maintains consistency with existing persona format
+  - Fixes portfolio round-trip workflow
+
+#### ✨ Improvements
+- **Code Quality**: Extracted validation methods into ValidationService
+- **Error Handling**: Improved validation error messages with specific field information
+- **Test Coverage**: Added comprehensive tests for markdown serialization
+
+---
+
+### v1.6.0 - August 25, 2025
+
+**🚀 Major Release: Portfolio System & OAuth Integration**
+
+This release introduces the complete portfolio management system with GitHub OAuth authentication, enabling secure cloud-based element synchronization and management.
+
+#### ✨ New Features
+
+##### 🔐 GitHub OAuth Authentication
+- **OAuth App Integration**: Full OAuth flow with GitHub for secure authentication
+- **Personal Access Token Support**: Alternative authentication method for CI/CD
+- **Token Management**: Secure storage and rotation of authentication tokens
+- **Multi-Account Support**: Handle multiple GitHub accounts seamlessly
+
+##### 📦 Portfolio Management System
+- **Cloud Sync**: Automatic synchronization between local and GitHub portfolios
+- **Version Control**: Full git integration for portfolio elements
+- **Conflict Resolution**: Smart merging of local and remote changes
+- **Batch Operations**: Upload/download multiple elements efficiently
+
+##### 🛠️ New MCP Tools (42 total)
+- `setup_github_auth`: Interactive GitHub OAuth setup
+- `check_github_auth`: Verify authentication status
+- `refresh_github_token`: Rotate OAuth tokens
+- `sync_portfolio`: Bidirectional portfolio synchronization
+- `upload_to_portfolio`: Upload local elements to GitHub
+- `download_from_portfolio`: Download elements from GitHub
+- `submit_to_portfolio`: Submit elements for review
+- And 30 more tools for complete portfolio management
+
+#### 🔧 Bug Fixes
+- **Element Detection**: Fixed smart detection of element types
+- **YAML Parsing**: Improved handling of complex YAML structures
+- **Path Resolution**: Fixed Windows path compatibility issues
+- **Token Security**: Enhanced token storage encryption
+
+#### 📝 Documentation
+- Comprehensive OAuth setup guide
+- Portfolio management tutorials
+- Troubleshooting guides for common issues
+- API documentation for all new tools
+
+#### 🔒 Security
+- OAuth token encryption at rest
+- Secure token transmission
+- Rate limiting for API calls
+- Audit logging for all operations
+
+---
+
+For complete release history prior to v1.6.0, see the [GitHub Releases](https://github.com/DollhouseMCP/mcp-server/releases) page.
+
+## 📜 License
+
+This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)** with Platform Stability Commitments.
+
+### What This Means
+
+#### ✅ You CAN:
+- Use the software for personal projects
+- Use the software for commercial projects
+- Modify the source code
+- Distribute the software
+- Use personas and elements you create
+
+#### ⚠️ You MUST:
+- Include the license and copyright notice
+- State changes made to the code
+- Disclose your source code when distributing
+- Use the same AGPL-3.0 license for derivatives
+- **Make network use source available** (AGPL requirement)
+
+#### ❌ You CANNOT:
+- Hold us liable for damages
+- Use our trademarks without permission
+- Claim warranty or guarantee of fitness
+- Resell commercially
+
+### Platform Stability Commitments
+
+We provide additional guarantees beyond the AGPL-3.0:
+
+- **90-day advance notice** for monetization policy changes
+- **12-month revenue sharing locks** for content creators
+- **Full data portability** - export all your content anytime
+- **180-day transition period** for platform ownership changes
+- **Community advisory input** on major policy decisions
+
+### Contributor License Agreement
+
+By contributing to DollhouseMCP, you agree that:
+
+1. You have the right to grant us license to your contribution
+2. Your contribution is licensed under AGPL-3.0
+3. You grant us additional rights to use your contribution in our commercial offerings
+4. You retain copyright to your contribution
 
-## 📄 License
+For the complete license text, see [LICENSE](LICENSE).
 
-DollhouseMCP is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
+### Questions?
 
-### What this means:
-- ✅ **Free to use** for personal and commercial purposes
-- ✅ **Modify and distribute** with the same license
-- ✅ **Network use** requires source code disclosure
-- ✅ **Platform stability** commitments protect users
+If you have questions about the license or what you can do with DollhouseMCP:
 
-See [LICENSE](LICENSE) for full terms.
+- **Documentation**: [License FAQ](docs/LICENSE_FAQ.md)
+- **GitHub Issue**: Open an issue with the `license` label
+- **Discussions**: Ask in [GitHub Discussions](https://github.com/DollhouseMCP/mcp-server/discussions)
 
 ---
 
-*Built with ❤️ by the DollhouseMCP team*
+*Copyright © 2025 DollhouseMCP. All rights reserved.*