From 48c6488220cc7e459d30f18ed4fb6153ef031191 Mon Sep 17 00:00:00 2001
From: "engine-labs-app[bot]"
 <140088366+engine-labs-app[bot]@users.noreply.github.com>
Date: Sun, 2 Nov 2025 18:16:29 +0000
Subject: [PATCH] docs: add comprehensive documentation suite for setup,
 features, architecture, and deployment

This commit introduces a full documentation suite for Project-Aura
covering setup, architecture, beginner/expert guides, API reference,
integrations, troubleshooting, deployment, plugin details, changelog,
and contributing guidelines. The README is expanded and links to all
major documents. Guides now include feature toggles, backup/restore
workflows, integrations (Azure, Composio, MCP), diagrams/screenshots
(placeholders), and detailed deployment instructions for Railway,
Render, Fly.io, and more. Ensures docs are in sync with type schemas
and adds a changelog template for future releases.

No breaking changes. All major and minor features are now well
documented for developers and end users alike.
---
 CHANGELOG.md                |  252 +++++++++
 CONTRIBUTING.md             |  484 +++++++++++++++++
 README.md                   |  192 ++++++-
 docs/API_REFERENCE.md       | 1003 ++++++++++++++++++++++++++++++++++
 docs/ARCHITECTURE.md        |  615 +++++++++++++++++++++
 docs/DEPLOYMENT.md          |  905 +++++++++++++++++++++++++++++++
 docs/DOCUMENTATION_INDEX.md |  181 +++++++
 docs/FEATURES_BEGINNER.md   |  359 +++++++++++++
 docs/FEATURES_EXPERT.md     |  811 ++++++++++++++++++++++++++++
 docs/INTEGRATIONS.md        | 1005 +++++++++++++++++++++++++++++++++++
 docs/SETUP.md               |  429 +++++++++++++++
 docs/TROUBLESHOOTING.md     |  843 +++++++++++++++++++++++++++++
 docs/images/README.md       |  136 +++++
 13 files changed, 7214 insertions(+), 1 deletion(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 docs/API_REFERENCE.md
 create mode 100644 docs/ARCHITECTURE.md
 create mode 100644 docs/DEPLOYMENT.md
 create mode 100644 docs/DOCUMENTATION_INDEX.md
 create mode 100644 docs/FEATURES_BEGINNER.md
 create mode 100644 docs/FEATURES_EXPERT.md
 create mode 100644 docs/INTEGRATIONS.md
 create mode 100644 docs/SETUP.md
 create mode 100644 docs/TROUBLESHOOTING.md
 create mode 100644 docs/images/README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..43b013a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,252 @@
+# Changelog
+
+All notable changes to Project-Aura 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).
+
+## [Unreleased]
+
+### Added
+- Comprehensive documentation suite
+  - Expanded README with feature overview
+  - Detailed setup guide
+  - Architecture documentation
+  - Beginner and expert feature guides
+  - Complete API reference
+  - Deployment guide for multiple platforms
+  - Integrations guide (Azure, Composio, MCP)
+  - Troubleshooting guide
+
+### Changed
+- README updated with links to documentation
+- Project structure documented
+
+### Deprecated
+- None
+
+### Removed
+- None
+
+### Fixed
+- None
+
+### Security
+- None
+
+## [1.0.0] - 2024-XX-XX
+
+### Added
+- Initial release
+- Multi-provider LLM support
+  - Google Gemini (2.0 Flash, 1.5 Pro, 1.5 Flash)
+  - OpenAI (GPT-4o, GPT-4o Mini, GPT-4 Turbo, GPT-3.5 Turbo)
+  - Anthropic Claude (3.5 Sonnet, 3.5 Haiku, 3 Opus)
+  - Mistral AI (Large, Medium, Small)
+- Agent Mode with function calling
+- Plugin system for extensibility
+- Core plugins:
+  - System Plugin (system info, calculations, notifications)
+  - File Manager Plugin (file operations)
+  - Web Browser Plugin (web automation)
+  - Process Management Plugin (process control)
+  - Network Plugin (network operations)
+  - Code Execution Plugin (sandboxed code execution)
+  - Email Plugin (email integration)
+  - Calendar Plugin (calendar management)
+- Chat management
+  - Multiple concurrent chats
+  - Persistent history
+  - Auto-generated titles
+  - Chat deletion
+- Streaming responses
+- Model selection and switching
+- Secure API key storage
+- Local-first data storage
+- Modern React + TypeScript UI
+- Electron desktop application framework
+- Webpack build system
+
+### Changed
+- N/A (initial release)
+
+### Deprecated
+- N/A (initial release)
+
+### Removed
+- N/A (initial release)
+
+### Fixed
+- N/A (initial release)
+
+### Security
+- Encrypted API key storage
+- Sandboxed plugin execution
+- Input validation and sanitization
+- No telemetry or data collection
+
+---
+
+## Release Guidelines
+
+### Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+- **MAJOR** version: Incompatible API changes
+- **MINOR** version: New functionality (backwards compatible)
+- **PATCH** version: Bug fixes (backwards compatible)
+
+### Change Categories
+
+- **Added**: New features
+- **Changed**: Changes to existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Security improvements/fixes
+
+### Example Entry Format
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New feature description (#issue-number)
+- Another feature (@contributor-name)
+
+### Changed
+- Changed behavior description (#pr-number)
+
+### Fixed
+- Bug fix description (fixes #issue-number)
+
+### Security
+- Security improvement description
+```
+
+### Release Process
+
+1. **Update CHANGELOG.md**
+   - Move items from `[Unreleased]` to new version section
+   - Add release date
+   - Update links at bottom of file
+
+2. **Update version in package.json**
+   ```bash
+   npm version [major|minor|patch]
+   ```
+
+3. **Create Git tag**
+   ```bash
+   git tag -a v1.0.0 -m "Release version 1.0.0"
+   git push origin v1.0.0
+   ```
+
+4. **Build release artifacts**
+   ```bash
+   npm run build
+   npm run package
+   ```
+
+5. **Create GitHub Release**
+   - Go to GitHub Releases
+   - Create new release from tag
+   - Copy changelog entry as release notes
+   - Attach build artifacts
+
+6. **Announce release**
+   - GitHub Discussions
+   - Discord (if applicable)
+   - Social media
+   - Update documentation
+
+### Pre-release Versions
+
+For alpha, beta, and release candidates:
+
+- **Alpha**: `1.0.0-alpha.1`
+- **Beta**: `1.0.0-beta.1`
+- **Release Candidate**: `1.0.0-rc.1`
+
+Example:
+```markdown
+## [1.1.0-beta.1] - 2024-XX-XX
+
+### Added
+- Experimental Docker support
+- Beta testing for new plugin system
+
+### Known Issues
+- Performance optimization needed
+- Documentation incomplete
+```
+
+### Migration Guides
+
+For breaking changes, include migration instructions:
+
+```markdown
+## [2.0.0] - YYYY-MM-DD
+
+### Changed
+- **BREAKING**: Plugin API restructured
+
+#### Migration Guide
+
+**Before (v1.x)**:
+```typescript
+export const manifest = {
+  id: 'my-plugin',
+  functions: ['func1']
+};
+```
+
+**After (v2.x)**:
+```typescript
+export const manifest: PluginManifest = {
+  id: 'my-plugin',
+  version: '2.0.0',
+  functions: ['func1'],
+  metadata: {
+    author: 'Author Name'
+  }
+};
+```
+
+Update your plugins accordingly.
+```
+
+### Deprecation Warnings
+
+When deprecating features:
+
+```markdown
+## [1.5.0] - YYYY-MM-DD
+
+### Deprecated
+- `oldFunction()` is deprecated and will be removed in v2.0.0
+  - Use `newFunction()` instead
+  - Migration guide: [link to docs]
+  
+### Added
+- `newFunction()` as replacement for `oldFunction()`
+```
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/afkutrotzdemda/Project-Aura)
+- [Documentation](docs/)
+- [Issue Tracker](https://github.com/afkutrotzdemda/Project-Aura/issues)
+- [Releases](https://github.com/afkutrotzdemda/Project-Aura/releases)
+
+## Contributors
+
+Thank you to all contributors who have helped make Project-Aura better!
+
+See the [Contributors Graph](https://github.com/afkutrotzdemda/Project-Aura/graphs/contributors) for the full list.
+
+---
+
+**Questions about a release?** Open a [discussion](https://github.com/afkutrotzdemda/Project-Aura/discussions) or [issue](https://github.com/afkutrotzdemda/Project-Aura/issues).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..2486818
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,484 @@
+# Contributing to Project-Aura
+
+Thank you for your interest in contributing to Project-Aura! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Process](#development-process)
+- [Coding Standards](#coding-standards)
+- [Submitting Changes](#submitting-changes)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+
+## Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inclusive experience for everyone. We expect all contributors to:
+
+- Be respectful and considerate
+- Welcome newcomers and help them get started
+- Accept constructive criticism gracefully
+- Focus on what is best for the community
+- Show empathy towards other community members
+
+### Unacceptable Behavior
+
+- Harassment, discrimination, or intimidation
+- Trolling or insulting comments
+- Publishing others' private information
+- Other unprofessional conduct
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ and npm
+- Git
+- Code editor (VS Code recommended)
+- Basic knowledge of TypeScript and React
+
+### Setup Development Environment
+
+1. **Fork the repository**
+   ```bash
+   # Click "Fork" on GitHub
+   ```
+
+2. **Clone your fork**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/Project-Aura.git
+   cd Project-Aura
+   ```
+
+3. **Add upstream remote**
+   ```bash
+   git remote add upstream https://github.com/afkutrotzdemda/Project-Aura.git
+   ```
+
+4. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+5. **Create a branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/issue-description
+   ```
+
+6. **Start development server**
+   ```bash
+   npm run dev
+   ```
+
+## Development Process
+
+### Branch Naming
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation updates
+- `refactor/` - Code refactoring
+- `test/` - Test additions/fixes
+- `chore/` - Maintenance tasks
+
+Examples:
+- `feature/add-docker-support`
+- `fix/api-key-validation`
+- `docs/update-setup-guide`
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, no logic change)
+- `refactor`: Code restructuring
+- `perf`: Performance improvement
+- `test`: Adding tests
+- `chore`: Maintenance
+
+**Examples**:
+```bash
+feat(llm): add support for Mistral AI models
+
+Implements integration with Mistral AI API including:
+- API client setup
+- Model configuration
+- Streaming support
+
+Closes #123
+
+---
+
+fix(plugins): resolve file manager permission issue
+
+Fixed bug where file manager plugin couldn't access
+user Documents folder due to incorrect permission check.
+
+Fixes #456
+
+---
+
+docs(readme): update installation instructions
+
+Added troubleshooting section and clarified
+Node.js version requirements.
+```
+
+### Keeping Your Fork Updated
+
+```bash
+# Fetch upstream changes
+git fetch upstream
+
+# Merge upstream main into your branch
+git checkout main
+git merge upstream/main
+
+# Push to your fork
+git push origin main
+```
+
+## Coding Standards
+
+### TypeScript
+
+- Use TypeScript for all new code
+- Enable strict mode
+- Avoid `any` type - use proper types
+- Document complex types with comments
+
+```typescript
+// Good
+interface UserConfig {
+  apiKey: string;
+  model: string;
+  agentMode: boolean;
+}
+
+function saveConfig(config: UserConfig): void {
+  // Implementation
+}
+
+// Avoid
+function saveConfig(config: any): void {
+  // Implementation
+}
+```
+
+### React Components
+
+- Use functional components with hooks
+- Keep components focused and single-purpose
+- Props should have defined interfaces
+- Use meaningful component names
+
+```typescript
+// Good
+interface ChatMessageProps {
+  message: Message;
+  isStreaming?: boolean;
+}
+
+const ChatMessage: React.FC<ChatMessageProps> = ({ message, isStreaming }) => {
+  // Component logic
+  return <div>{message.content}</div>;
+};
+
+export default ChatMessage;
+```
+
+### File Organization
+
+```
+src/
+├── renderer/
+│   ├── components/          # React components
+│   │   ├── ChatMessage.tsx
+│   │   ├── Sidebar.tsx
+│   │   └── ...
+│   ├── services/            # Core services
+│   │   ├── llmService.ts
+│   │   ├── pluginService.ts
+│   │   └── ...
+│   ├── plugins/             # Plugin implementations
+│   │   ├── systemPlugin.ts
+│   │   └── ...
+│   ├── utils/               # Utility functions
+│   │   ├── storage.ts
+│   │   └── ...
+│   └── App.tsx              # Main app component
+```
+
+### Naming Conventions
+
+- **Files**: camelCase for utilities, PascalCase for components
+  - `llmService.ts`, `ChatMessage.tsx`
+- **Variables/Functions**: camelCase
+  - `const userName = "..."`, `function sendMessage() {}`
+- **Classes/Interfaces**: PascalCase
+  - `class LLMService`, `interface UserConfig`
+- **Constants**: UPPER_SNAKE_CASE
+  - `const MAX_RETRIES = 3`
+
+### Code Style
+
+- Use 2 spaces for indentation
+- Use single quotes for strings
+- Add semicolons
+- Use ES6+ features (arrow functions, destructuring, etc.)
+- Keep lines under 100 characters when possible
+
+```typescript
+// Good
+const sendMessage = async (content: string): Promise<void> => {
+  const result = await llmService.sendMessage(content);
+  console.log('Message sent:', result);
+};
+
+// Less ideal
+function sendMessage(content) {
+  return llmService.sendMessage(content).then(result => {
+    console.log("Message sent:", result)
+  })
+}
+```
+
+### Documentation
+
+- Add JSDoc comments for public APIs
+- Explain "why" not just "what"
+- Document complex algorithms
+- Update documentation when changing functionality
+
+```typescript
+/**
+ * Sends a message to the LLM and handles streaming responses.
+ * 
+ * @param message - The message content to send
+ * @param onStream - Optional callback for streaming chunks
+ * @param enableFunctions - Whether to enable function calling
+ * @returns Promise resolving to the complete response
+ * @throws {Error} If API key is invalid or request fails
+ */
+async sendMessage(
+  message: string,
+  onStream?: (response: StreamingResponse) => void,
+  enableFunctions?: boolean
+): Promise<string> {
+  // Implementation
+}
+```
+
+## Submitting Changes
+
+### Before Submitting
+
+1. **Test your changes**
+   ```bash
+   npm run build
+   npm test
+   ```
+
+2. **Lint your code**
+   ```bash
+   npm run lint
+   ```
+
+3. **Update documentation**
+   - Update README if needed
+   - Add/update JSDoc comments
+   - Update relevant docs in `docs/`
+
+4. **Add tests** (if applicable)
+   - Unit tests for utilities
+   - Integration tests for features
+   - Manual testing for UI changes
+
+### Creating a Pull Request
+
+1. **Push your branch**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+2. **Open Pull Request**
+   - Go to GitHub repository
+   - Click "New Pull Request"
+   - Select your branch
+   - Fill out PR template
+
+3. **PR Title Format**
+   ```
+   feat: Add Docker deployment support
+   fix: Resolve API key validation issue
+   docs: Update setup guide
+   ```
+
+4. **PR Description**
+   - What changes were made
+   - Why these changes are needed
+   - Any breaking changes
+   - Screenshots (for UI changes)
+   - Related issues
+
+   Example:
+   ```markdown
+   ## Description
+   Adds support for deploying Project-Aura using Docker containers.
+
+   ## Changes
+   - Added Dockerfile and docker-compose.yml
+   - Updated deployment documentation
+   - Added Docker-specific environment variables
+
+   ## Testing
+   - [x] Built Docker image successfully
+   - [x] Container runs and serves application
+   - [x] Tested with different configurations
+
+   ## Screenshots
+   ![Docker deployment](screenshots/docker.png)
+
+   ## Related Issues
+   Closes #123
+   ```
+
+### PR Review Process
+
+1. **Automated checks** must pass
+   - Build succeeds
+   - Tests pass
+   - Linting passes
+
+2. **Code review** by maintainers
+   - May request changes
+   - May ask questions
+   - May suggest improvements
+
+3. **Address feedback**
+   - Make requested changes
+   - Push updates to same branch
+   - Respond to comments
+
+4. **Merge**
+   - Maintainer will merge when approved
+   - Your branch will be deleted
+   - Changes included in next release
+
+## Reporting Bugs
+
+### Before Reporting
+
+1. **Search existing issues** - May already be reported
+2. **Test on latest version** - May already be fixed
+3. **Check documentation** - May be expected behavior
+
+### Creating a Bug Report
+
+Use the bug report template and include:
+
+- **Clear title**: "API key validation fails for Claude"
+- **Environment**:
+  - OS and version
+  - Node.js version
+  - Project-Aura version
+- **Steps to reproduce**:
+  1. Do this
+  2. Then this
+  3. Observe the error
+- **Expected behavior**: What should happen
+- **Actual behavior**: What actually happens
+- **Logs/Errors**: Error messages, console output
+- **Screenshots**: If applicable
+
+## Suggesting Features
+
+### Before Suggesting
+
+1. **Check existing issues** - May already be planned
+2. **Read documentation** - May already exist
+3. **Consider scope** - Should it be a plugin instead?
+
+### Creating a Feature Request
+
+Use the feature request template and include:
+
+- **Clear title**: "Add support for local LLM models"
+- **Problem**: What problem does this solve?
+- **Proposed solution**: How should it work?
+- **Alternatives**: Other ways to solve this
+- **Use cases**: When would you use this?
+- **Additional context**: Examples, mockups, etc.
+
+## Development Tips
+
+### Debugging
+
+```bash
+# Run with debug output
+DEBUG=* npm run dev
+
+# Open DevTools in Electron
+Ctrl+Shift+I (Windows/Linux)
+Cmd+Option+I (macOS)
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test
+npm test -- llmService.test.ts
+
+# Run with coverage
+npm run test:coverage
+
+# Watch mode
+npm test -- --watch
+```
+
+### Building
+
+```bash
+# Development build
+npm run build
+
+# Production build
+NODE_ENV=production npm run build
+
+# Package application
+npm run package
+```
+
+## Questions?
+
+- **General questions**: [GitHub Discussions](https://github.com/afkutrotzdemda/Project-Aura/discussions)
+- **Bug reports**: [GitHub Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+- **Security issues**: Email security@project-aura.dev (placeholder)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project (MIT License).
+
+---
+
+**Thank you for contributing to Project-Aura! 🎉**
diff --git a/README.md b/README.md
index f387386..8d5414f 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,191 @@
-# Project-Aura
\ No newline at end of file
+# Project-Aura
+
+**AI-Powered Desktop Chat Application with Advanced Agent Capabilities**
+
+Project-Aura is a powerful, cross-platform desktop application that brings advanced AI capabilities to your fingertips. Built with Electron, React, and TypeScript, it supports multiple LLM providers and features an intelligent agent mode with function calling capabilities for system integration.
+
+![Project Aura Banner](docs/images/banner-placeholder.png)
+
+## ✨ Features
+
+### 🤖 Multi-Provider LLM Support
+- **Google Gemini** (2.0 Flash, 1.5 Pro, 1.5 Flash)
+- **OpenAI** (GPT-4o, GPT-4o Mini, GPT-4 Turbo, GPT-3.5 Turbo)
+- **Anthropic Claude** (3.5 Sonnet, 3.5 Haiku, 3 Opus)
+- **Mistral AI** (Large, Medium, Small)
+
+### 🎯 Agent Mode
+Enable advanced AI capabilities with function calling:
+- **System Information** - Get real-time system metrics and information
+- **File Management** - Read, write, and manage files
+- **Web Browser** - Automated web browsing and data extraction
+- **Process Management** - Monitor and control system processes
+- **Network Operations** - Network diagnostics and monitoring
+- **Code Execution** - Execute code snippets safely
+- **Email Integration** - Send and manage emails
+- **Calendar Management** - Schedule and manage events
+
+### 💬 Chat Management
+- Multiple concurrent chat sessions
+- Persistent chat history
+- Chat title auto-generation
+- Export/import conversations
+- Streaming responses for real-time interaction
+
+### 🎨 User Interface
+- Clean, modern interface
+- Dark mode optimized
+- Responsive design
+- Keyboard shortcuts
+- Beginner and Expert modes
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Node.js 18+ and npm
+- API key from at least one supported LLM provider
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/afkutrotzdemda/Project-Aura.git
+cd Project-Aura
+
+# Install dependencies
+npm install
+
+# Start the development server
+npm run dev
+```
+
+### First Run Setup
+
+1. Launch the application
+2. Click the settings icon in the chat header
+3. Select your preferred LLM model
+4. Enter your API key for the selected provider
+5. (Optional) Enable Agent Mode for advanced capabilities
+6. Start chatting!
+
+## 📚 Documentation
+
+Comprehensive documentation is available in the `docs/` directory:
+
+- **[Setup Guide](docs/SETUP.md)** - Detailed installation and configuration instructions
+- **[Architecture](docs/ARCHITECTURE.md)** - System design and technical architecture
+- **[Feature Guide - Beginner](docs/FEATURES_BEGINNER.md)** - Getting started with basic features
+- **[Feature Guide - Expert](docs/FEATURES_EXPERT.md)** - Advanced features and customization
+- **[API Reference](docs/API_REFERENCE.md)** - Plugin and service API documentation
+- **[Deployment Guide](docs/DEPLOYMENT.md)** - Self-hosted and cloud deployment options
+- **[Integrations](docs/INTEGRATIONS.md)** - Azure, Composio, MCP, and other integrations
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[Changelog](CHANGELOG.md)** - Version history and updates
+
+## 🛠️ Development
+
+### Project Structure
+
+```
+Project-Aura/
+├── src/
+│   └── renderer/          # Frontend React application
+│       ├── components/    # UI components
+│       ├── services/      # Core services (LLM, plugins, functions)
+│       ├── plugins/       # Agent mode plugins
+│       └── utils/         # Utility functions
+├── docs/                  # Documentation
+├── dist/                  # Build output
+└── webpack.config.js      # Webpack configuration
+```
+
+### Building from Source
+
+```bash
+# Development build with hot reload
+npm run dev
+
+# Production build
+npm run build
+
+# Package for distribution
+npm run package
+```
+
+### Running Tests
+
+```bash
+# Run unit tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run with coverage
+npm run test:coverage
+```
+
+## 🔒 Security & Privacy
+
+- **Local-First**: All data stored locally on your machine
+- **API Keys**: Encrypted storage of provider API keys
+- **Sandboxed Execution**: Code execution in isolated environments
+- **No Telemetry**: We don't collect or transmit usage data
+
+## 🌐 Deployment Options
+
+Project-Aura can be deployed in multiple ways:
+
+- **Desktop Application**: Package as native app for Windows, macOS, Linux
+- **Self-Hosted Web**: Deploy as web application on your infrastructure
+- **Cloud Platforms**: Railway, Render, Fly.io ready configurations
+- **Docker**: Containerized deployment (coming soon)
+
+See the [Deployment Guide](docs/DEPLOYMENT.md) for detailed instructions.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📋 Roadmap
+
+- [ ] Docker containerization
+- [ ] Plugin marketplace
+- [ ] Voice input/output
+- [ ] Multi-modal support (images, documents)
+- [ ] Team collaboration features
+- [ ] Mobile companion app
+- [ ] Self-hosted model support (Ollama, LM Studio)
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [Electron](https://www.electronjs.org/)
+- UI powered by [React](https://react.dev/)
+- LLM integrations via official SDKs
+- Icons from [Heroicons](https://heroicons.com/)
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/afkutrotzdemda/Project-Aura/discussions)
+- **Email**: support@project-aura.dev (placeholder)
+
+## ⭐ Star History
+
+If you find Project-Aura useful, please consider giving it a star on GitHub!
+
+---
+
+**Made with ❤️ by the Project-Aura Team**
diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md
new file mode 100644
index 0000000..a35bb79
--- /dev/null
+++ b/docs/API_REFERENCE.md
@@ -0,0 +1,1003 @@
+# API Reference
+
+Complete API documentation for Project-Aura services, plugins, and interfaces.
+
+## Table of Contents
+
+- [Core Services](#core-services)
+  - [LLMService](#llmservice)
+  - [PluginService](#pluginservice)
+  - [FunctionService](#functionservice)
+  - [StorageService](#storageservice)
+- [Plugin APIs](#plugin-apis)
+- [Type Definitions](#type-definitions)
+- [Hooks and Extensions](#hooks-and-extensions)
+
+## Core Services
+
+### LLMService
+
+Central service for managing LLM provider integrations.
+
+#### Initialization
+
+```typescript
+async initialize(config: LLMConfig): Promise<void>
+```
+
+Initialize an LLM provider with configuration.
+
+**Parameters**:
+- `config.provider`: `'gemini' | 'openai' | 'claude' | 'mistral'`
+- `config.apiKey`: string - Provider API key
+- `config.model`: string - Model identifier
+
+**Example**:
+```typescript
+await llmService.initialize({
+  provider: 'gemini',
+  apiKey: 'AIza...',
+  model: 'gemini-2.0-flash-exp'
+});
+```
+
+**Throws**: Error if provider is unsupported or API key is invalid
+
+---
+
+#### Send Message
+
+```typescript
+async sendMessage(
+  message: string,
+  onStream?: (response: StreamingResponse) => void,
+  enableFunctions?: boolean
+): Promise<string>
+```
+
+Send a message to the current LLM model.
+
+**Parameters**:
+- `message`: string - User message content
+- `onStream` (optional): Callback for streaming responses
+  - `response.content`: string - Accumulated response content
+  - `response.isComplete`: boolean - Whether generation is complete
+- `enableFunctions` (optional): boolean - Enable function calling (Agent Mode)
+
+**Returns**: Promise<string> - Complete response text
+
+**Example**:
+```typescript
+// Without streaming
+const response = await llmService.sendMessage('Hello, AI!');
+
+// With streaming
+await llmService.sendMessage(
+  'Explain quantum computing',
+  (stream) => {
+    console.log('Received:', stream.content);
+    if (stream.isComplete) {
+      console.log('Done!');
+    }
+  }
+);
+
+// With function calling
+await llmService.sendMessage(
+  'What is my disk usage?',
+  undefined,
+  true  // Enable functions
+);
+```
+
+---
+
+#### Model Management
+
+```typescript
+getAvailableModels(): LLMModel[]
+```
+
+Get list of all available models.
+
+**Returns**: Array of LLMModel objects
+
+**Example**:
+```typescript
+const models = llmService.getAvailableModels();
+models.forEach(model => {
+  console.log(`${model.name} (${model.provider})`);
+});
+```
+
+---
+
+```typescript
+getModelsByProvider(provider: LLMProvider): LLMModel[]
+```
+
+Get models for a specific provider.
+
+**Parameters**:
+- `provider`: LLMProvider - Provider name
+
+**Returns**: Array of models for that provider
+
+---
+
+```typescript
+getModelInfo(modelId: string): LLMModel | undefined
+```
+
+Get detailed information about a specific model.
+
+**Parameters**:
+- `modelId`: string - Model identifier (e.g., 'gemini-2.0-flash-exp')
+
+**Returns**: LLMModel object or undefined if not found
+
+**Example**:
+```typescript
+const info = llmService.getModelInfo('gpt-4o');
+console.log(`Max tokens: ${info?.maxTokens}`);
+console.log(`Supports functions: ${info?.supportsFunctions}`);
+```
+
+---
+
+#### API Key Management
+
+```typescript
+setApiKey(provider: LLMProvider, apiKey: string): void
+```
+
+Set API key for a provider.
+
+**Parameters**:
+- `provider`: LLMProvider
+- `apiKey`: string
+
+---
+
+```typescript
+hasApiKey(provider: LLMProvider): boolean
+```
+
+Check if API key exists for provider.
+
+**Returns**: boolean
+
+---
+
+```typescript
+getCurrentProvider(): LLMProvider | null
+```
+
+Get currently active provider.
+
+**Returns**: Provider name or null
+
+---
+
+```typescript
+getCurrentModel(): string | null
+```
+
+Get currently active model ID.
+
+**Returns**: Model ID or null
+
+---
+
+### PluginService
+
+Manages plugin lifecycle and registration.
+
+#### Load Plugin
+
+```typescript
+loadPlugin(manifest: PluginManifest, implementation: any): void
+```
+
+Load and register a plugin.
+
+**Parameters**:
+- `manifest`: PluginManifest - Plugin metadata
+- `implementation`: any - Plugin implementation object
+
+**Example**:
+```typescript
+import { myPluginManifest } from './myPlugin';
+import * as myPlugin from './myPlugin';
+
+pluginService.loadPlugin(myPluginManifest, myPlugin);
+```
+
+---
+
+#### Enable/Disable Plugins
+
+```typescript
+enablePlugin(pluginId: string): void
+```
+
+Enable a loaded plugin.
+
+**Parameters**:
+- `pluginId`: string - Plugin identifier
+
+**Throws**: Error if plugin not found
+
+---
+
+```typescript
+disablePlugin(pluginId: string): void
+```
+
+Disable an active plugin.
+
+**Parameters**:
+- `pluginId`: string - Plugin identifier
+
+---
+
+#### Query Plugins
+
+```typescript
+isPluginEnabled(pluginId: string): boolean
+```
+
+Check if plugin is enabled.
+
+**Returns**: boolean
+
+---
+
+```typescript
+getEnabledPlugins(): Plugin[]
+```
+
+Get all enabled plugins.
+
+**Returns**: Array of Plugin objects
+
+---
+
+```typescript
+getAvailableFunctions(): FunctionRegistration[]
+```
+
+Get all functions from enabled plugins.
+
+**Returns**: Array of function registrations
+
+**Example**:
+```typescript
+const functions = pluginService.getAvailableFunctions();
+console.log(`${functions.length} functions available`);
+```
+
+---
+
+### FunctionService
+
+Handles function calling and execution for Agent Mode.
+
+#### Register Function
+
+```typescript
+registerFunction(
+  declaration: FunctionDeclaration,
+  implementation: Function
+): void
+```
+
+Register a function with its declaration and implementation.
+
+**Parameters**:
+- `declaration`: FunctionDeclaration - Function schema for LLM
+- `implementation`: Function - Actual function to execute
+
+**Example**:
+```typescript
+const declaration = {
+  name: 'getCurrentWeather',
+  description: 'Get weather for a location',
+  parameters: {
+    type: "object",
+    properties: {
+      location: {
+        type: "string",
+        description: "City name"
+      },
+      units: {
+        type: "string",
+        enum: ["celsius", "fahrenheit"],
+        description: "Temperature units"
+      }
+    },
+    required: ["location"]
+  }
+};
+
+async function getCurrentWeather(args) {
+  // Implementation
+  return { temperature: 72, conditions: 'sunny' };
+}
+
+functionService.registerFunction(declaration, getCurrentWeather);
+```
+
+---
+
+#### Execute Functions
+
+```typescript
+async executeFunctions(calls: FunctionCall[]): Promise<FunctionResult[]>
+```
+
+Execute multiple function calls from LLM.
+
+**Parameters**:
+- `calls`: FunctionCall[] - Array of function calls from LLM
+
+**Returns**: Promise<FunctionResult[]> - Results from each function
+
+**Example**:
+```typescript
+const calls = [
+  { name: 'getSystemInfo', args: {} },
+  { name: 'calculate', args: { expression: '2 + 2' } }
+];
+
+const results = await functionService.executeFunctions(calls);
+results.forEach(result => {
+  if (result.error) {
+    console.error(`${result.name} failed:`, result.error);
+  } else {
+    console.log(`${result.name} result:`, result.result);
+  }
+});
+```
+
+---
+
+#### Query Functions
+
+```typescript
+getFunctionDeclarations(): FunctionDeclaration[]
+```
+
+Get all registered function declarations.
+
+**Returns**: Array of FunctionDeclaration objects
+
+---
+
+```typescript
+clearFunctions(): void
+```
+
+Clear all registered functions.
+
+---
+
+### StorageService
+
+Manages local data persistence.
+
+#### Chat Management
+
+```typescript
+saveChat(chat: StoredChat): void
+```
+
+Save or update a chat.
+
+**Parameters**:
+- `chat`: StoredChat - Chat object with messages
+
+**Example**:
+```typescript
+storage.saveChat({
+  id: '1234567890',
+  title: 'Coding Help',
+  timestamp: new Date(),
+  messages: [
+    {
+      id: '1',
+      role: 'user',
+      content: 'How do I reverse a string?',
+      timestamp: new Date()
+    },
+    {
+      id: '2',
+      role: 'assistant',
+      content: 'Here are several ways...',
+      timestamp: new Date()
+    }
+  ]
+});
+```
+
+---
+
+```typescript
+getChat(chatId: string): StoredChat | null
+```
+
+Retrieve a specific chat.
+
+**Parameters**:
+- `chatId`: string
+
+**Returns**: StoredChat or null
+
+---
+
+```typescript
+getChats(): StoredChat[]
+```
+
+Get all chats, sorted by timestamp (newest first).
+
+**Returns**: Array of StoredChat objects
+
+---
+
+```typescript
+deleteChat(chatId: string): void
+```
+
+Delete a chat permanently.
+
+**Parameters**:
+- `chatId`: string
+
+---
+
+#### Settings Management
+
+```typescript
+saveSettings(settings: Settings): void
+```
+
+Save application settings.
+
+**Parameters**:
+- `settings`: Settings object
+
+---
+
+```typescript
+getSettings(): Settings
+```
+
+Load application settings.
+
+**Returns**: Settings object (with defaults if not found)
+
+---
+
+#### API Key Storage
+
+```typescript
+saveApiKey(provider: LLMProvider, key: string): void
+```
+
+Save API key securely (encrypted).
+
+**Parameters**:
+- `provider`: LLMProvider
+- `key`: string
+
+---
+
+```typescript
+getApiKey(provider: LLMProvider): string
+```
+
+Retrieve API key for provider.
+
+**Parameters**:
+- `provider`: LLMProvider
+
+**Returns**: Decrypted API key or empty string
+
+---
+
+#### Utility
+
+```typescript
+generateChatTitle(firstMessage: string): string
+```
+
+Generate a chat title from the first message.
+
+**Parameters**:
+- `firstMessage`: string
+
+**Returns**: Generated title (max 50 characters)
+
+**Example**:
+```typescript
+const title = storage.generateChatTitle(
+  'Can you help me debug this Python function?'
+);
+// Returns: "Help debug Python function"
+```
+
+---
+
+## Plugin APIs
+
+### Plugin Manifest
+
+Every plugin must export a manifest:
+
+```typescript
+interface PluginManifest {
+  id: string;                    // Unique identifier (kebab-case)
+  name: string;                  // Display name
+  description: string;           // Purpose and capabilities
+  version: string;               // Semantic version (e.g., "1.0.0")
+  author: string;                // Author name
+  main: string;                  // Entry point filename
+  functions: string[];           // Exported function names
+}
+```
+
+**Example**:
+```typescript
+export const myPluginManifest: PluginManifest = {
+  id: 'my-awesome-plugin',
+  name: 'My Awesome Plugin',
+  description: 'Does awesome things',
+  version: '1.0.0',
+  author: 'Your Name',
+  main: 'myAwesomePlugin.ts',
+  functions: ['awesomeFunction', 'anotherFunction']
+};
+```
+
+---
+
+### Function Declaration
+
+Functions must be declared with a schema:
+
+```typescript
+interface FunctionDeclaration {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: {
+      [paramName: string]: {
+        type: "string" | "number" | "boolean" | "array" | "object";
+        description: string;
+        enum?: any[];
+        items?: any;          // For arrays
+        properties?: any;     // For nested objects
+      };
+    };
+    required: string[];
+  };
+}
+```
+
+**Example**:
+```typescript
+export const searchFilesDeclaration = {
+  name: 'searchFiles',
+  description: 'Search for files matching criteria',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      directory: {
+        type: "string",
+        description: "Directory to search in"
+      },
+      pattern: {
+        type: "string",
+        description: "File pattern (glob)"
+      },
+      recursive: {
+        type: "boolean",
+        description: "Search subdirectories"
+      },
+      fileTypes: {
+        type: "array",
+        description: "File extensions to include",
+        items: {
+          type: "string"
+        }
+      }
+    },
+    required: ["directory", "pattern"]
+  }
+};
+```
+
+---
+
+### Function Implementation
+
+Implement the actual function logic:
+
+```typescript
+type FunctionImplementation = (args: any) => Promise<any> | any;
+```
+
+**Guidelines**:
+- Accept single `args` object parameter
+- Return serializable data (JSON-compatible)
+- Handle errors gracefully
+- Validate inputs
+- Log important actions
+
+**Example**:
+```typescript
+export async function searchFiles(args: {
+  directory: string;
+  pattern: string;
+  recursive?: boolean;
+  fileTypes?: string[];
+}): Promise<{ files: string[] }> {
+  try {
+    // Validate
+    if (!args.directory || !args.pattern) {
+      throw new Error('directory and pattern are required');
+    }
+
+    // Check permissions
+    if (!isAllowedDirectory(args.directory)) {
+      throw new Error('Access denied to directory');
+    }
+
+    // Execute
+    const files = await performSearch(
+      args.directory,
+      args.pattern,
+      args.recursive ?? false,
+      args.fileTypes
+    );
+
+    // Return results
+    return { files };
+  } catch (error) {
+    console.error('[searchFiles] Error:', error);
+    throw error;
+  }
+}
+```
+
+---
+
+### Plugin Exports
+
+Plugin files must export:
+
+1. **Manifest** (required)
+2. **Function Declarations** (required for each function)
+3. **Function Implementations** (required for each function)
+
+**Complete Example**:
+```typescript
+// weatherPlugin.ts
+import { PluginManifest } from '../services/pluginService';
+
+// 1. Manifest
+export const weatherPluginManifest: PluginManifest = {
+  id: 'weather-plugin',
+  name: 'Weather Plugin',
+  description: 'Get weather information',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'weatherPlugin.ts',
+  functions: ['getWeather']
+};
+
+// 2. Function Declaration
+export const getWeatherDeclaration = {
+  name: 'getWeather',
+  description: 'Get current weather for a location',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      location: {
+        type: "string",
+        description: "City name or coordinates"
+      },
+      units: {
+        type: "string",
+        description: "Temperature units",
+        enum: ["celsius", "fahrenheit", "kelvin"]
+      }
+    },
+    required: ["location"]
+  }
+};
+
+// 3. Function Implementation
+export async function getWeather(args: {
+  location: string;
+  units?: string;
+}): Promise<any> {
+  const units = args.units || 'celsius';
+  
+  // Call weather API
+  const response = await fetch(
+    `https://api.weather.com/v1/current?location=${args.location}&units=${units}`
+  );
+  
+  const data = await response.json();
+  
+  return {
+    location: args.location,
+    temperature: data.temperature,
+    conditions: data.conditions,
+    humidity: data.humidity,
+    units: units
+  };
+}
+```
+
+---
+
+## Type Definitions
+
+### Core Types
+
+```typescript
+// LLM Configuration
+interface LLMConfig {
+  provider: LLMProvider;
+  apiKey: string;
+  model: string;
+}
+
+type LLMProvider = 'gemini' | 'openai' | 'claude' | 'mistral';
+
+// Model Information
+interface LLMModel {
+  id: string;
+  name: string;
+  provider: LLMProvider;
+  description: string;
+  maxTokens: number;
+  supportsFunctions: boolean;
+}
+
+// Streaming Response
+interface StreamingResponse {
+  content: string;
+  isComplete: boolean;
+}
+
+// Message
+interface Message {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: Date;
+  isStreaming?: boolean;
+}
+
+// Stored Chat
+interface StoredChat {
+  id: string;
+  title: string;
+  timestamp: Date;
+  messages: Message[];
+}
+
+// Settings
+interface Settings {
+  selectedModel: string;
+  agentMode: boolean;
+  theme?: 'light' | 'dark';
+  autoSave?: boolean;
+  maxChatHistory?: number;
+}
+```
+
+---
+
+### Plugin Types
+
+```typescript
+// Plugin Manifest
+interface PluginManifest {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  author: string;
+  main: string;
+  functions: string[];
+}
+
+// Plugin
+interface Plugin {
+  manifest: PluginManifest;
+  functions: FunctionRegistration[];
+  enabled: boolean;
+}
+
+// Function Declaration
+interface FunctionDeclaration {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: Record<string, PropertySchema>;
+    required: string[];
+  };
+}
+
+// Property Schema
+interface PropertySchema {
+  type: "string" | "number" | "boolean" | "array" | "object";
+  description: string;
+  enum?: any[];
+  items?: any;
+  properties?: Record<string, PropertySchema>;
+}
+
+// Function Registration
+interface FunctionRegistration {
+  declaration: FunctionDeclaration;
+  implementation: Function;
+  pluginId: string;
+}
+
+// Function Call (from LLM)
+interface FunctionCall {
+  name: string;
+  args: Record<string, any>;
+}
+
+// Function Result
+interface FunctionResult {
+  name: string;
+  result?: any;
+  error?: string;
+}
+```
+
+---
+
+## Hooks and Extensions
+
+### React Component Integration
+
+**Using LLMService in Components**:
+```typescript
+import { llmService } from './services/llmService';
+
+function MyComponent() {
+  const [response, setResponse] = useState('');
+
+  const handleSend = async (message: string) => {
+    const result = await llmService.sendMessage(
+      message,
+      (stream) => setResponse(stream.content)
+    );
+  };
+
+  return <div>{response}</div>;
+}
+```
+
+---
+
+### Custom Service Integration
+
+**Extending Services**:
+```typescript
+// customLLMService.ts
+import { LLMService } from './services/llmService';
+
+class CustomLLMService extends LLMService {
+  async sendMessageWithContext(
+    message: string,
+    context: any
+  ): Promise<string> {
+    // Custom logic
+    const enhancedMessage = `${context}\n\n${message}`;
+    return this.sendMessage(enhancedMessage);
+  }
+}
+
+export const customLLMService = new CustomLLMService();
+```
+
+---
+
+### Event Hooks (Future)
+
+```typescript
+// Event system for plugins
+pluginService.on('plugin.enabled', (pluginId) => {
+  console.log(`Plugin enabled: ${pluginId}`);
+});
+
+pluginService.on('function.called', (functionName, args) => {
+  console.log(`Function called: ${functionName}`, args);
+});
+
+pluginService.on('function.completed', (functionName, result) => {
+  console.log(`Function completed: ${functionName}`, result);
+});
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+```typescript
+// API Key Error
+try {
+  await llmService.initialize(config);
+} catch (error) {
+  if (error.message.includes('API_KEY_INVALID')) {
+    // Handle invalid key
+  }
+}
+
+// Quota Error
+try {
+  await llmService.sendMessage(message);
+} catch (error) {
+  if (error.message.includes('QUOTA_EXCEEDED')) {
+    // Handle quota exceeded
+  }
+}
+
+// Plugin Error
+try {
+  pluginService.enablePlugin('my-plugin');
+} catch (error) {
+  if (error.message.includes('not found')) {
+    // Handle plugin not found
+  }
+}
+
+// Function Error
+const results = await functionService.executeFunctions(calls);
+results.forEach(result => {
+  if (result.error) {
+    console.error(`Function ${result.name} failed:`, result.error);
+  }
+});
+```
+
+---
+
+## Best Practices
+
+1. **Always validate inputs** in plugin functions
+2. **Use TypeScript types** for better development experience
+3. **Handle errors gracefully** and provide meaningful messages
+4. **Log important events** for debugging
+5. **Test functions independently** before integration
+6. **Document function parameters** clearly
+7. **Keep functions focused** - single responsibility
+8. **Version your plugins** using semantic versioning
+
+---
+
+## See Also
+
+- [Architecture Documentation](ARCHITECTURE.md) - System design details
+- [Plugin Development Guide](PLUGIN_DEVELOPMENT.md) - Creating custom plugins
+- [Expert Feature Guide](FEATURES_EXPERT.md) - Advanced usage patterns
+- [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions
+
+---
+
+**API Version**: 1.0.0  
+**Last Updated**: 2024
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..02207fe
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,615 @@
+# Architecture Documentation
+
+Technical architecture and design overview of Project-Aura.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [System Architecture](#system-architecture)
+- [Core Components](#core-components)
+- [Data Flow](#data-flow)
+- [Plugin System](#plugin-system)
+- [Service Layer](#service-layer)
+- [Storage Architecture](#storage-architecture)
+- [Security Model](#security-model)
+- [Performance Considerations](#performance-considerations)
+
+## Overview
+
+Project-Aura is built as an Electron-based desktop application using a modern React + TypeScript stack. The architecture follows a modular, service-oriented design with a plugin system for extensibility.
+
+### Technology Stack
+
+- **Frontend**: React 18+ with TypeScript
+- **Desktop Framework**: Electron (Renderer Process)
+- **Build Tool**: Webpack 5
+- **State Management**: React Hooks (useState, useEffect)
+- **Styling**: CSS with CSS Modules
+- **LLM Integration**: Provider-specific SDKs (Google AI, OpenAI, Anthropic, Mistral)
+
+### Design Principles
+
+1. **Modularity**: Loosely coupled components and services
+2. **Extensibility**: Plugin-based architecture for new features
+3. **Security**: Local-first with encrypted storage
+4. **Performance**: Streaming responses and lazy loading
+5. **User Privacy**: No telemetry, local data storage
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Electron App                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                    UI Layer (React)                       │  │
+│  ├──────────────────────────────────────────────────────────┤  │
+│  │  ├─ App.tsx (Main Container)                             │  │
+│  │  ├─ ChatHeader (Model Selection, Settings)               │  │
+│  │  ├─ ChatMessages (Message Display)                       │  │
+│  │  ├─ ChatInput (User Input)                               │  │
+│  │  └─ Sidebar (Chat History)                               │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                             │                                    │
+│                             ▼                                    │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                   Service Layer                           │  │
+│  ├──────────────────────────────────────────────────────────┤  │
+│  │  ├─ LLMService (Multi-provider LLM integration)          │  │
+│  │  ├─ PluginService (Plugin lifecycle management)          │  │
+│  │  ├─ FunctionService (Function calling & execution)       │  │
+│  │  └─ StorageService (Local data persistence)              │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                             │                                    │
+│                             ▼                                    │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                    Plugin System                          │  │
+│  ├──────────────────────────────────────────────────────────┤  │
+│  │  ├─ SystemPlugin (System information)                    │  │
+│  │  ├─ FileManagerPlugin (File operations)                  │  │
+│  │  ├─ WebBrowserPlugin (Web automation)                    │  │
+│  │  ├─ ProcessManagementPlugin (Process control)            │  │
+│  │  ├─ NetworkPlugin (Network operations)                   │  │
+│  │  ├─ CodeExecutionPlugin (Code execution)                 │  │
+│  │  ├─ EmailPlugin (Email integration)                      │  │
+│  │  └─ CalendarPlugin (Calendar management)                 │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                             │                                    │
+└─────────────────────────────┼────────────────────────────────────┘
+                              │
+                              ▼
+              ┌───────────────────────────────┐
+              │    External Services          │
+              ├───────────────────────────────┤
+              │  ├─ Google Gemini API        │
+              │  ├─ OpenAI API               │
+              │  ├─ Anthropic Claude API     │
+              │  ├─ Mistral AI API           │
+              │  └─ Other Integrations       │
+              └───────────────────────────────┘
+```
+
+## Core Components
+
+### App.tsx - Main Application Container
+
+The root component that orchestrates the entire application.
+
+**Responsibilities**:
+- State management for chat sessions, messages, and settings
+- Lifecycle management for services and plugins
+- Event handling and user interactions
+- Persistence of chat history and settings
+
+**Key State**:
+```typescript
+interface AppState {
+  currentChatId: string;
+  selectedModel: string;
+  agentMode: boolean;
+  apiKey: string;
+  messages: Message[];
+  isLoading: boolean;
+  chats: StoredChat[];
+}
+```
+
+### ChatHeader Component
+
+Manages model selection, agent mode toggle, and API key input.
+
+**Features**:
+- Model dropdown with provider grouping
+- Agent mode toggle switch
+- API key input with secure handling
+- Settings modal
+
+### ChatMessages Component
+
+Displays conversation history with streaming support.
+
+**Features**:
+- Message rendering (user/assistant)
+- Streaming indicator
+- Markdown support
+- Code syntax highlighting
+- Auto-scroll to latest message
+
+### ChatInput Component
+
+Handles user input and message submission.
+
+**Features**:
+- Multi-line text input
+- Send on Enter (Shift+Enter for new line)
+- Loading state handling
+- Character count indicator
+- Input validation
+
+### Sidebar Component
+
+Manages chat history and session navigation.
+
+**Features**:
+- Chat list with titles and timestamps
+- New chat button
+- Chat selection and switching
+- Chat deletion with confirmation
+- Search/filter capabilities
+
+## Data Flow
+
+### Message Sending Flow
+
+```
+User Input → ChatInput Component
+     │
+     ▼
+App.handleSendMessage()
+     │
+     ├─ Create user message
+     ├─ Update local state
+     ├─ Save to storage
+     │
+     ▼
+LLMService.sendMessage()
+     │
+     ├─ Initialize provider (if needed)
+     ├─ Build request with context
+     │
+     ▼
+[Agent Mode?]
+     │
+     ├─ No → Direct LLM call
+     │
+     └─ Yes → With function declarations
+          │
+          ▼
+     FunctionService.getFunctionDeclarations()
+          │
+          ▼
+     LLM API Call (streaming)
+          │
+          ├─ Text response → Stream to UI
+          │
+          └─ Function calls detected
+               │
+               ▼
+          FunctionService.executeFunctions()
+               │
+               ├─ Route to appropriate plugin
+               ├─ Execute function
+               └─ Return results
+                    │
+                    ▼
+               Append results to response
+                    │
+                    ▼
+               Update UI with complete response
+```
+
+### Plugin Loading Flow
+
+```
+Application Startup
+     │
+     ▼
+App.useEffect() (mount)
+     │
+     ├─ Load settings from storage
+     ├─ Restore API keys
+     │
+     ▼
+PluginService.loadPlugin() × N
+     │
+     ├─ Validate plugin manifest
+     ├─ Register plugin functions
+     └─ Initialize plugin state
+          │
+          ▼
+[Agent Mode Enabled?]
+     │
+     └─ Yes → Enable plugins
+          │
+          ▼
+     FunctionService.registerFunction() × N
+          │
+          └─ Build function declarations for LLM
+```
+
+## Plugin System
+
+### Plugin Architecture
+
+Plugins are self-contained modules that extend the AI agent's capabilities.
+
+**Plugin Structure**:
+```typescript
+interface PluginManifest {
+  id: string;                    // Unique plugin identifier
+  name: string;                  // Display name
+  description: string;           // Plugin purpose
+  version: string;               // Semantic version
+  author: string;                // Plugin author
+  main: string;                  // Entry point file
+  functions: string[];           // Exported function names
+}
+
+interface Plugin {
+  manifest: PluginManifest;
+  functions: FunctionRegistration[];
+  enabled: boolean;
+}
+```
+
+### Plugin Lifecycle
+
+1. **Registration**: Plugin manifest and functions registered with PluginService
+2. **Initialization**: Plugin state initialized, resources allocated
+3. **Activation**: Plugin enabled and functions exposed to FunctionService
+4. **Execution**: Functions called by AI agent based on context
+5. **Deactivation**: Plugin disabled, cleanup performed
+6. **Unload**: Plugin removed from memory (future)
+
+### Function Declaration Format
+
+Functions must follow the schema format expected by LLM providers:
+
+```typescript
+interface FunctionDeclaration {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: {
+      [key: string]: {
+        type: string;
+        description: string;
+        enum?: string[];
+      };
+    };
+    required: string[];
+  };
+}
+```
+
+### Creating a Custom Plugin
+
+Example plugin structure:
+
+```typescript
+// myPlugin.ts
+import { PluginManifest } from '../services/pluginService';
+
+export const myPluginManifest: PluginManifest = {
+  id: 'my-plugin',
+  name: 'My Custom Plugin',
+  description: 'Does something useful',
+  version: '1.0.0',
+  author: 'Your Name',
+  main: 'myPlugin.ts',
+  functions: ['myFunction']
+};
+
+export const myFunctionDeclaration = {
+  name: 'myFunction',
+  description: 'Performs a custom operation',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      input: {
+        type: "string",
+        description: "Input parameter"
+      }
+    },
+    required: ["input"]
+  }
+};
+
+export async function myFunction(args: { input: string }) {
+  // Implementation
+  return { result: `Processed: ${args.input}` };
+}
+```
+
+## Service Layer
+
+### LLMService
+
+Central service for all LLM provider integrations.
+
+**Key Methods**:
+```typescript
+class LLMService {
+  // Initialize a provider with API key
+  async initialize(config: LLMConfig): Promise<void>
+  
+  // Send message with optional streaming and functions
+  async sendMessage(
+    message: string,
+    onStream?: (response: StreamingResponse) => void,
+    enableFunctions?: boolean
+  ): Promise<string>
+  
+  // Provider-specific implementations
+  private async sendMessageGemini(...): Promise<string>
+  private async sendMessageOpenAI(...): Promise<string>
+  private async sendMessageClaude(...): Promise<string>
+  private async sendMessageMistral(...): Promise<string>
+  
+  // Utility methods
+  getAvailableModels(): LLMModel[]
+  getModelInfo(modelId: string): LLMModel | undefined
+  hasApiKey(provider: LLMProvider): boolean
+  setApiKey(provider: LLMProvider, apiKey: string): void
+}
+```
+
+**Provider Abstraction**:
+The service abstracts provider-specific details, allowing seamless switching between different LLMs.
+
+### PluginService
+
+Manages plugin lifecycle and registration.
+
+**Key Methods**:
+```typescript
+class PluginService {
+  // Load and register a plugin
+  loadPlugin(manifest: PluginManifest, implementation: any): void
+  
+  // Enable/disable plugins
+  enablePlugin(pluginId: string): void
+  disablePlugin(pluginId: string): void
+  
+  // Query plugin state
+  isPluginEnabled(pluginId: string): boolean
+  getEnabledPlugins(): Plugin[]
+  getAvailableFunctions(): FunctionRegistration[]
+}
+```
+
+### FunctionService
+
+Handles function calling and execution.
+
+**Key Methods**:
+```typescript
+class FunctionService {
+  // Register a function with its implementation
+  registerFunction(
+    declaration: FunctionDeclaration,
+    implementation: Function
+  ): void
+  
+  // Execute functions called by LLM
+  async executeFunctions(
+    calls: FunctionCall[]
+  ): Promise<FunctionResult[]>
+  
+  // Query available functions
+  getFunctionDeclarations(): FunctionDeclaration[]
+  
+  // Clear all registrations
+  clearFunctions(): void
+}
+```
+
+### StorageService
+
+Handles local data persistence.
+
+**Key Methods**:
+```typescript
+class StorageService {
+  // Chat management
+  saveChat(chat: StoredChat): void
+  getChat(chatId: string): StoredChat | null
+  getChats(): StoredChat[]
+  deleteChat(chatId: string): void
+  
+  // Settings management
+  saveSettings(settings: Settings): void
+  getSettings(): Settings
+  
+  // Secure API key storage
+  saveApiKey(provider: LLMProvider, key: string): void
+  getApiKey(provider: LLMProvider): string
+  
+  // Utility
+  generateChatTitle(firstMessage: string): string
+}
+```
+
+## Storage Architecture
+
+### Local Storage Structure
+
+```
+~/.config/Project-Aura/ (Linux/macOS) or %APPDATA%\Project-Aura\ (Windows)
+├── config.json              # Application settings
+├── chats/
+│   ├── {chatId1}.json      # Individual chat history
+│   ├── {chatId2}.json
+│   └── ...
+├── secure-storage.encrypted # Encrypted API keys
+├── plugins/
+│   └── plugin-config.json  # Plugin settings
+└── logs/
+    └── app.log             # Application logs
+```
+
+### Data Models
+
+**Chat Storage**:
+```typescript
+interface StoredChat {
+  id: string;
+  title: string;
+  timestamp: Date;
+  messages: Message[];
+}
+
+interface Message {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: Date;
+  isStreaming?: boolean;
+}
+```
+
+**Settings Storage**:
+```typescript
+interface Settings {
+  selectedModel: string;
+  agentMode: boolean;
+  theme?: 'light' | 'dark';
+  autoSave?: boolean;
+  maxChatHistory?: number;
+}
+```
+
+### Encryption
+
+API keys are encrypted using:
+- **Windows**: DPAPI (Data Protection API)
+- **macOS**: Keychain Services
+- **Linux**: libsecret with system keyring
+
+## Security Model
+
+### Threat Model
+
+**Protected Assets**:
+1. User API keys
+2. Chat history and conversations
+3. System access (via plugins)
+4. User data accessed by plugins
+
+**Threat Actors**:
+1. Malicious plugins
+2. Network attackers (MITM)
+3. Local system compromise
+4. Malicious LLM responses
+
+### Security Measures
+
+**API Key Protection**:
+- Encrypted at rest using OS keychain
+- Never logged or displayed in full
+- Transmitted only over HTTPS to official provider APIs
+
+**Plugin Sandboxing**:
+- Explicit permission system for plugins
+- Function-level access control
+- Input validation and sanitization
+- Timeout limits for function execution
+
+**Network Security**:
+- All LLM API calls over HTTPS
+- Certificate validation enforced
+- No telemetry or tracking
+
+**Code Execution Safety**:
+- Sandboxed execution environment
+- Resource limits (CPU, memory, time)
+- Filesystem access restrictions
+- Network access controls
+
+## Performance Considerations
+
+### Optimization Strategies
+
+**Streaming Responses**:
+- Chunked transfer for real-time feedback
+- Reduced perceived latency
+- Progressive rendering of messages
+
+**Lazy Loading**:
+- Components loaded on demand
+- Plugin initialization deferred until needed
+- Chat history pagination
+
+**Caching**:
+- Model metadata cached locally
+- Plugin manifests cached
+- API response caching (future)
+
+**Memory Management**:
+- Message history limited by configuration
+- Old chat data compressed or archived
+- Plugin cleanup on disable
+
+### Performance Metrics
+
+Target performance characteristics:
+- **Initial Load**: < 2 seconds
+- **Message Send**: < 100ms to first token
+- **Plugin Execution**: < 5 seconds timeout
+- **Memory Usage**: < 500MB typical, < 1GB peak
+- **Chat History Load**: < 500ms for 100 messages
+
+## Extension Points
+
+### Adding New LLM Providers
+
+1. Add provider to `LLMProvider` type
+2. Implement provider-specific initialization
+3. Implement provider-specific message sending
+4. Add models to `AVAILABLE_MODELS`
+5. Update UI for provider selection
+
+### Adding New Plugins
+
+1. Create plugin manifest
+2. Define function declarations
+3. Implement function handlers
+4. Register with PluginService
+5. Add to App initialization
+
+### Custom Storage Backends
+
+1. Implement `StorageProvider` interface
+2. Register with StorageService
+3. Configure via settings
+
+## Future Architecture Considerations
+
+### Planned Enhancements
+
+1. **Main Process Integration**: Move heavy operations to Electron main process
+2. **IPC Communication**: Structured communication between renderer and main
+3. **Worker Threads**: Background processing for expensive operations
+4. **Database Integration**: SQLite for improved chat history management
+5. **Plugin Marketplace**: Discovery and installation of community plugins
+6. **Multi-Window Support**: Separate chat windows
+7. **Offline Mode**: Local model support (Ollama, LM Studio)
+
+---
+
+For implementation details, see:
+- [API Reference](API_REFERENCE.md)
+- [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
+- [Contributing Guidelines](../CONTRIBUTING.md)
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..e5c1dd2
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,905 @@
+# Deployment Guide
+
+Comprehensive guide for deploying Project-Aura across different platforms and environments.
+
+## Table of Contents
+
+- [Deployment Options Overview](#deployment-options-overview)
+- [Desktop Application](#desktop-application)
+- [Self-Hosted Web Application](#self-hosted-web-application)
+- [Cloud Platform Deployments](#cloud-platform-deployments)
+  - [Railway](#railway)
+  - [Render](#render)
+  - [Fly.io](#flyio)
+- [Docker Deployment](#docker-deployment)
+- [Environment Configuration](#environment-configuration)
+- [Production Considerations](#production-considerations)
+
+## Deployment Options Overview
+
+Project-Aura can be deployed in multiple configurations:
+
+| Method | Best For | Difficulty | Cost |
+|--------|----------|------------|------|
+| Desktop App | Individual users | Easy | Free |
+| Self-Hosted | Privacy, Control | Medium | Server costs |
+| Railway | Quick cloud deploy | Easy | Pay-as-you-go |
+| Render | Managed hosting | Easy | Free tier available |
+| Fly.io | Global distribution | Medium | Free tier available |
+| Docker | Containerized deploy | Medium | Infrastructure costs |
+
+## Desktop Application
+
+### Building for Distribution
+
+#### Prerequisites
+```bash
+npm install electron-builder --save-dev
+```
+
+#### Configuration
+
+Add to `package.json`:
+```json
+{
+  "name": "project-aura",
+  "version": "1.0.0",
+  "main": "main.js",
+  "scripts": {
+    "start": "electron .",
+    "build": "webpack --mode production",
+    "package": "electron-builder"
+  },
+  "build": {
+    "appId": "com.projectaura.app",
+    "productName": "Project Aura",
+    "directories": {
+      "output": "dist-electron"
+    },
+    "files": [
+      "dist/**/*",
+      "main.js",
+      "package.json"
+    ],
+    "mac": {
+      "category": "public.app-category.productivity",
+      "icon": "build/icon.icns",
+      "target": ["dmg", "zip"]
+    },
+    "win": {
+      "icon": "build/icon.ico",
+      "target": ["nsis", "portable"]
+    },
+    "linux": {
+      "icon": "build/icon.png",
+      "target": ["AppImage", "deb", "rpm"],
+      "category": "Utility"
+    }
+  }
+}
+```
+
+#### Build Commands
+
+**macOS**:
+```bash
+# Build for current platform
+npm run build
+npm run package
+
+# Build for distribution
+npm run package -- --mac
+
+# Output: dist-electron/Project-Aura-1.0.0.dmg
+```
+
+**Windows**:
+```bash
+# Build installer
+npm run package -- --win
+
+# Output: dist-electron/Project-Aura-Setup-1.0.0.exe
+```
+
+**Linux**:
+```bash
+# Build AppImage
+npm run package -- --linux
+
+# Output: dist-electron/Project-Aura-1.0.0.AppImage
+```
+
+#### Code Signing (Optional but Recommended)
+
+**macOS**:
+```bash
+# Get Developer ID certificate from Apple
+# Configure in package.json:
+"mac": {
+  "identity": "Developer ID Application: Your Name (TEAM_ID)"
+}
+```
+
+**Windows**:
+```bash
+# Get code signing certificate
+# Configure in package.json:
+"win": {
+  "certificateFile": "path/to/cert.pfx",
+  "certificatePassword": "password"
+}
+```
+
+#### Auto-Update Configuration
+
+```json
+{
+  "build": {
+    "publish": {
+      "provider": "github",
+      "owner": "afkutrotzdemda",
+      "repo": "Project-Aura"
+    }
+  }
+}
+```
+
+```typescript
+// In main.js
+const { autoUpdater } = require('electron-updater');
+
+autoUpdater.checkForUpdatesAndNotify();
+```
+
+## Self-Hosted Web Application
+
+### Server Requirements
+
+- **OS**: Linux (Ubuntu 20.04+ recommended)
+- **Node.js**: 18.x or higher
+- **RAM**: 2GB minimum, 4GB recommended
+- **Storage**: 10GB
+- **Network**: HTTPS required for production
+
+### Installation Steps
+
+#### 1. Prepare Server
+
+```bash
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install Node.js
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Install build tools
+sudo apt install -y build-essential git
+```
+
+#### 2. Deploy Application
+
+```bash
+# Clone repository
+git clone https://github.com/afkutrotzdemda/Project-Aura.git
+cd Project-Aura
+
+# Install dependencies
+npm ci --production
+
+# Build application
+npm run build
+
+# Create production config
+cp .env.example .env
+nano .env
+```
+
+#### 3. Configure Environment
+
+```bash
+# .env
+NODE_ENV=production
+PORT=3000
+HOST=0.0.0.0
+
+# Security
+SESSION_SECRET=your-random-secret-here
+ALLOWED_ORIGINS=https://yourdomain.com
+
+# Optional: Default API keys (use cautiously)
+# GEMINI_API_KEY=your-key
+# OPENAI_API_KEY=your-key
+```
+
+#### 4. Set Up Process Manager
+
+**Using PM2**:
+```bash
+# Install PM2
+sudo npm install -g pm2
+
+# Start application
+pm2 start npm --name "project-aura" -- start
+
+# Configure auto-start
+pm2 startup
+pm2 save
+
+# Monitor
+pm2 status
+pm2 logs project-aura
+```
+
+#### 5. Configure Reverse Proxy (Nginx)
+
+```bash
+# Install Nginx
+sudo apt install -y nginx
+
+# Create configuration
+sudo nano /etc/nginx/sites-available/project-aura
+```
+
+```nginx
+server {
+    listen 80;
+    server_name yourdomain.com;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+```bash
+# Enable site
+sudo ln -s /etc/nginx/sites-available/project-aura /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl restart nginx
+```
+
+#### 6. Set Up SSL (Let's Encrypt)
+
+```bash
+# Install Certbot
+sudo apt install -y certbot python3-certbot-nginx
+
+# Get certificate
+sudo certbot --nginx -d yourdomain.com
+
+# Auto-renewal is configured automatically
+```
+
+## Cloud Platform Deployments
+
+### Railway
+
+Railway provides simple, automated deployments from Git.
+
+#### Setup Steps
+
+1. **Create Account**: Visit [railway.app](https://railway.app) and sign up
+
+2. **Create New Project**:
+   - Click "New Project"
+   - Select "Deploy from GitHub repo"
+   - Connect your GitHub account
+   - Select the Project-Aura repository
+
+3. **Configure Build**:
+
+Create `railway.toml` in project root:
+```toml
+[build]
+builder = "NIXPACKS"
+buildCommand = "npm install && npm run build"
+
+[deploy]
+startCommand = "npm start"
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 10
+```
+
+4. **Environment Variables**:
+   - Go to Variables tab
+   - Add required variables:
+     ```
+     NODE_ENV=production
+     PORT=3000
+     ```
+
+5. **Deploy**:
+   - Railway automatically deploys on push to main branch
+   - Monitor deployment in dashboard
+
+#### Custom Domain
+
+```bash
+# In Railway dashboard:
+# Settings → Domains → Add Custom Domain
+# Add your domain and configure DNS:
+
+CNAME record:
+yourdomain.com → your-app.up.railway.app
+```
+
+#### Estimated Costs
+
+- Starter: $5/month (500 hours)
+- Developer: $10/month (1000 hours)
+- Team: $20/month (2000 hours)
+
+### Render
+
+Render offers managed cloud hosting with generous free tier.
+
+#### Setup Steps
+
+1. **Create Account**: Visit [render.com](https://render.com)
+
+2. **Create Web Service**:
+   - Click "New +" → "Web Service"
+   - Connect GitHub repository
+   - Configure:
+     - **Name**: project-aura
+     - **Environment**: Node
+     - **Build Command**: `npm install && npm run build`
+     - **Start Command**: `npm start`
+     - **Plan**: Free (or paid for better performance)
+
+3. **Environment Variables**:
+```
+NODE_ENV=production
+PORT=10000
+```
+
+4. **Create `render.yaml`** (optional, for Infrastructure as Code):
+
+```yaml
+services:
+  - type: web
+    name: project-aura
+    env: node
+    plan: free
+    buildCommand: npm install && npm run build
+    startCommand: npm start
+    envVars:
+      - key: NODE_ENV
+        value: production
+    healthCheckPath: /health
+```
+
+5. **Deploy**:
+   - Automatic deployment on push
+   - Access at: `https://project-aura.onrender.com`
+
+#### Custom Domain
+
+```bash
+# In Render dashboard:
+# Settings → Custom Domains
+# Add domain and configure DNS:
+
+CNAME record:
+yourdomain.com → project-aura.onrender.com
+```
+
+#### Free Tier Limitations
+
+- Spins down after 15 minutes of inactivity
+- 750 hours/month free
+- Shared CPU/memory
+- Use paid plan for production
+
+### Fly.io
+
+Fly.io provides global edge deployment with excellent performance.
+
+#### Setup Steps
+
+1. **Install Fly CLI**:
+```bash
+# macOS/Linux
+curl -L https://fly.io/install.sh | sh
+
+# Windows (PowerShell)
+iwr https://fly.io/install.ps1 -useb | iex
+```
+
+2. **Login**:
+```bash
+fly auth login
+```
+
+3. **Initialize App**:
+```bash
+cd Project-Aura
+fly launch
+```
+
+Answer prompts:
+- App name: project-aura (or your choice)
+- Region: Choose closest to your users
+- Postgres database: No (unless needed)
+- Redis: No (unless needed)
+
+4. **Configure `fly.toml`**:
+
+```toml
+app = "project-aura"
+primary_region = "sjc"
+
+[env]
+  NODE_ENV = "production"
+  PORT = "8080"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+  min_machines_running = 0
+
+[[services]]
+  protocol = "tcp"
+  internal_port = 8080
+  
+  [[services.ports]]
+    port = 80
+    handlers = ["http"]
+  
+  [[services.ports]]
+    port = 443
+    handlers = ["tls", "http"]
+
+[build]
+  builder = "heroku/buildpacks:20"
+
+[[build.buildpacks]]
+  id = "heroku/nodejs"
+```
+
+5. **Deploy**:
+```bash
+fly deploy
+```
+
+6. **Custom Domain**:
+```bash
+# Add certificate
+fly certs create yourdomain.com
+
+# Configure DNS:
+# A record: @ → [IP from fly certs show]
+# AAAA record: @ → [IPv6 from fly certs show]
+```
+
+#### Scaling
+
+```bash
+# Scale up
+fly scale count 2
+
+# Scale VM size
+fly scale vm shared-cpu-2x
+
+# Set regions
+fly regions add lax
+fly regions add fra
+```
+
+#### Estimated Costs
+
+- Free tier: 3 shared CPUs, 256MB RAM
+- Paid: ~$5-20/month depending on scale
+
+## Docker Deployment
+
+### Dockerfile
+
+Create `Dockerfile` in project root:
+
+```dockerfile
+# Build stage
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy source code
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Production stage
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S projectaura -u 1001
+
+# Copy from builder
+COPY --from=builder --chown=projectaura:nodejs /app/dist ./dist
+COPY --from=builder --chown=projectaura:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=projectaura:nodejs /app/package*.json ./
+
+# Switch to non-root user
+USER projectaura
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
+  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
+
+# Start application
+CMD ["node", "dist/server.js"]
+```
+
+### Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  project-aura:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: project-aura
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+    volumes:
+      - ./data:/app/data
+      - ./logs:/app/logs
+    networks:
+      - app-network
+
+  # Optional: Nginx reverse proxy
+  nginx:
+    image: nginx:alpine
+    container_name: nginx
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./ssl:/etc/nginx/ssl:ro
+    depends_on:
+      - project-aura
+    networks:
+      - app-network
+
+networks:
+  app-network:
+    driver: bridge
+
+volumes:
+  data:
+  logs:
+```
+
+### Build and Run
+
+```bash
+# Build image
+docker build -t project-aura:latest .
+
+# Run container
+docker run -d \
+  --name project-aura \
+  -p 3000:3000 \
+  -v $(pwd)/data:/app/data \
+  project-aura:latest
+
+# Using Docker Compose
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop
+docker-compose down
+```
+
+### Kubernetes Deployment (Advanced)
+
+Create `k8s/deployment.yaml`:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: project-aura
+  labels:
+    app: project-aura
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: project-aura
+  template:
+    metadata:
+      labels:
+        app: project-aura
+    spec:
+      containers:
+      - name: project-aura
+        image: project-aura:latest
+        ports:
+        - containerPort: 3000
+        env:
+        - name: NODE_ENV
+          value: "production"
+        resources:
+          requests:
+            memory: "256Mi"
+            cpu: "250m"
+          limits:
+            memory: "512Mi"
+            cpu: "500m"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 5
+          periodSeconds: 5
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: project-aura-service
+spec:
+  selector:
+    app: project-aura
+  ports:
+  - protocol: TCP
+    port: 80
+    targetPort: 3000
+  type: LoadBalancer
+```
+
+```bash
+kubectl apply -f k8s/deployment.yaml
+```
+
+## Environment Configuration
+
+### Environment Variables
+
+**Required**:
+```bash
+NODE_ENV=production
+PORT=3000
+```
+
+**Optional**:
+```bash
+# LLM API Keys (if providing defaults)
+GEMINI_API_KEY=your-key
+OPENAI_API_KEY=your-key
+CLAUDE_API_KEY=your-key
+MISTRAL_API_KEY=your-key
+
+# Security
+SESSION_SECRET=random-secret-here
+ALLOWED_ORIGINS=https://yourdomain.com
+
+# Features
+ENABLE_AGENT_MODE=true
+ENABLE_EXPERIMENTAL_FEATURES=false
+
+# Logging
+LOG_LEVEL=info
+LOG_FILE=/var/log/project-aura/app.log
+
+# Performance
+MAX_CHAT_HISTORY=100
+MESSAGE_RETENTION_DAYS=30
+```
+
+### Configuration Management
+
+**Production config template**:
+```json
+{
+  "production": {
+    "settings": {
+      "agentMode": false,
+      "maxChatHistory": 50,
+      "autoSave": true
+    },
+    "security": {
+      "rateLimiting": true,
+      "maxRequestsPerHour": 100
+    },
+    "logging": {
+      "level": "info",
+      "file": "/var/log/project-aura/app.log"
+    }
+  }
+}
+```
+
+## Production Considerations
+
+### Security Checklist
+
+- [ ] Enable HTTPS/TLS
+- [ ] Configure CORS properly
+- [ ] Rate limiting implemented
+- [ ] API keys stored securely
+- [ ] Regular security updates
+- [ ] Firewall configured
+- [ ] Access logging enabled
+- [ ] Backup strategy in place
+
+### Performance Optimization
+
+**Caching**:
+```nginx
+# Nginx caching
+proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m;
+
+location /static {
+    proxy_cache my_cache;
+    proxy_cache_valid 200 1d;
+}
+```
+
+**Compression**:
+```nginx
+# Enable gzip
+gzip on;
+gzip_types text/plain text/css application/json application/javascript;
+gzip_min_length 1000;
+```
+
+**Load Balancing**:
+```nginx
+upstream project_aura {
+    server localhost:3000;
+    server localhost:3001;
+    server localhost:3002;
+}
+```
+
+### Monitoring
+
+**Health Check Endpoint**:
+```typescript
+// server.ts
+app.get('/health', (req, res) => {
+  res.status(200).json({
+    status: 'healthy',
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString()
+  });
+});
+```
+
+**Logging**:
+```bash
+# Structured logging
+npm install winston
+
+# Configure
+const winston = require('winston');
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+```
+
+### Backup Strategy
+
+```bash
+#!/bin/bash
+# backup.sh
+
+DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR="/backups/project-aura"
+
+# Backup user data
+tar -czf $BACKUP_DIR/data-$DATE.tar.gz /app/data
+
+# Backup configuration
+cp /app/config.json $BACKUP_DIR/config-$DATE.json
+
+# Retain last 30 days
+find $BACKUP_DIR -mtime +30 -delete
+
+# Upload to cloud (optional)
+# aws s3 cp $BACKUP_DIR/data-$DATE.tar.gz s3://bucket/
+```
+
+### Updates and Maintenance
+
+```bash
+# Zero-downtime updates with PM2
+pm2 reload project-aura
+
+# With Docker
+docker-compose pull
+docker-compose up -d
+
+# Database migrations (if applicable)
+npm run migrate
+```
+
+## Troubleshooting Deployment
+
+### Common Issues
+
+**Port already in use**:
+```bash
+# Find process
+sudo lsof -i :3000
+
+# Kill process
+sudo kill -9 [PID]
+```
+
+**Permission denied**:
+```bash
+# Fix ownership
+sudo chown -R $USER:$USER /app
+
+# Fix permissions
+chmod +x /app/start.sh
+```
+
+**Out of memory**:
+```bash
+# Increase Node memory
+NODE_OPTIONS="--max-old-space-size=4096" npm start
+
+# Or in Docker
+ENV NODE_OPTIONS="--max-old-space-size=4096"
+```
+
+## See Also
+
+- [Setup Guide](SETUP.md) - Initial configuration
+- [Architecture](ARCHITECTURE.md) - System design
+- [Troubleshooting](TROUBLESHOOTING.md) - Problem solving
+- [Security Best Practices](SECURITY.md)
+
+---
+
+**Questions?** Open an issue on [GitHub](https://github.com/afkutrotzdemda/Project-Aura/issues)
diff --git a/docs/DOCUMENTATION_INDEX.md b/docs/DOCUMENTATION_INDEX.md
new file mode 100644
index 0000000..4321c58
--- /dev/null
+++ b/docs/DOCUMENTATION_INDEX.md
@@ -0,0 +1,181 @@
+# Documentation Index
+
+Complete guide to Project-Aura documentation.
+
+## 📚 Documentation Overview
+
+### Getting Started
+1. **[README](../README.md)** - Start here! Overview and quick start
+2. **[Setup Guide](SETUP.md)** - Detailed installation and configuration
+3. **[Beginner Feature Guide](FEATURES_BEGINNER.md)** - Your first steps
+
+### Core Documentation
+- **[Architecture](ARCHITECTURE.md)** - System design and technical details
+- **[API Reference](API_REFERENCE.md)** - Complete API documentation
+- **[Expert Feature Guide](FEATURES_EXPERT.md)** - Advanced features and customization
+
+### Deployment & Integration
+- **[Deployment Guide](DEPLOYMENT.md)** - Deploy on desktop, cloud, or self-hosted
+- **[Integrations](INTEGRATIONS.md)** - Azure, Composio, MCP, and more
+- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions
+
+### Development
+- **[Contributing](../CONTRIBUTING.md)** - How to contribute
+- **[Changelog](../CHANGELOG.md)** - Version history
+
+## 🎯 Documentation by Role
+
+### End Users
+1. [README](../README.md) - Overview
+2. [Setup Guide](SETUP.md) - Installation
+3. [Beginner Guide](FEATURES_BEGINNER.md) - Basic usage
+4. [Troubleshooting](TROUBLESHOOTING.md) - Help with issues
+
+### Power Users
+1. [Expert Guide](FEATURES_EXPERT.md) - Advanced features
+2. [Integrations](INTEGRATIONS.md) - Connect external services
+3. [Deployment Guide](DEPLOYMENT.md) - Self-hosting options
+
+### Developers
+1. [Architecture](ARCHITECTURE.md) - System design
+2. [API Reference](API_REFERENCE.md) - API docs
+3. [Contributing](../CONTRIBUTING.md) - Development guidelines
+4. [Integrations](INTEGRATIONS.md) - Building integrations
+
+### DevOps/SysAdmins
+1. [Deployment Guide](DEPLOYMENT.md) - Deployment options
+2. [Setup Guide](SETUP.md) - Configuration
+3. [Troubleshooting](TROUBLESHOOTING.md) - Problem solving
+
+## 📖 Documentation by Topic
+
+### Installation & Setup
+- [Setup Guide](SETUP.md)
+  - System requirements
+  - Installation methods
+  - API key setup
+  - Plugin configuration
+  - First-time setup
+
+### Usage Guides
+- [Beginner Guide](FEATURES_BEGINNER.md)
+  - Your first conversation
+  - Choosing AI models
+  - Managing chats
+  - Basic settings
+- [Expert Guide](FEATURES_EXPERT.md)
+  - Agent Mode
+  - Plugin system
+  - Advanced configuration
+  - Custom workflows
+  - Backup/restore
+
+### Technical Documentation
+- [Architecture](ARCHITECTURE.md)
+  - System overview
+  - Component structure
+  - Data flow
+  - Plugin system
+  - Security model
+- [API Reference](API_REFERENCE.md)
+  - Core services
+  - Plugin APIs
+  - Type definitions
+  - Examples
+
+### Deployment
+- [Deployment Guide](DEPLOYMENT.md)
+  - Desktop application
+  - Self-hosted web
+  - Railway deployment
+  - Render deployment
+  - Fly.io deployment
+  - Docker containers
+
+### Integrations
+- [Integrations Guide](INTEGRATIONS.md)
+  - Azure OpenAI
+  - Azure Cognitive Services
+  - Composio platform
+  - Model Context Protocol (MCP)
+  - Third-party services (Notion, Slack, GitHub, etc.)
+  - Custom integrations
+
+### Help & Support
+- [Troubleshooting](TROUBLESHOOTING.md)
+  - Installation issues
+  - API key problems
+  - Connection issues
+  - Plugin issues
+  - Performance problems
+  - Platform-specific issues
+
+## 🔍 Quick Links
+
+### Common Tasks
+- **Install Project-Aura**: [Setup Guide - Installation Methods](SETUP.md#installation-methods)
+- **Get API Key**: [Setup Guide - API Key Setup](SETUP.md#api-key-setup)
+- **First Chat**: [Beginner Guide - Your First Conversation](FEATURES_BEGINNER.md#your-first-conversation)
+- **Enable Agent Mode**: [Expert Guide - Agent Mode](FEATURES_EXPERT.md#agent-mode)
+- **Deploy to Cloud**: [Deployment - Cloud Platforms](DEPLOYMENT.md#cloud-platform-deployments)
+- **Fix Issues**: [Troubleshooting](TROUBLESHOOTING.md)
+
+### Developer Resources
+- **Create Plugin**: [API Reference - Plugin APIs](API_REFERENCE.md#plugin-apis)
+- **Contribute Code**: [Contributing](../CONTRIBUTING.md)
+- **Report Bug**: [GitHub Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+- **API Documentation**: [API Reference](API_REFERENCE.md)
+
+## 📋 Checklist for New Users
+
+- [ ] Read README overview
+- [ ] Follow Setup Guide to install
+- [ ] Configure at least one API key
+- [ ] Complete first conversation (Beginner Guide)
+- [ ] Try different AI models
+- [ ] Create multiple chats
+- [ ] (Optional) Enable Agent Mode
+- [ ] (Optional) Configure plugins
+
+## 🎓 Learning Path
+
+### Week 1: Basics
+- Day 1-2: Installation and setup
+- Day 3-4: Basic conversations with different models
+- Day 5-7: Chat management and settings
+
+### Week 2: Intermediate
+- Day 1-3: Explore Agent Mode (start with System Plugin)
+- Day 4-5: Try File Manager Plugin
+- Day 6-7: Experiment with prompting techniques
+
+### Week 3: Advanced
+- Day 1-3: Configure additional plugins
+- Day 4-5: Set up integrations (if needed)
+- Day 6-7: Customize configuration
+
+### Week 4: Expert
+- Day 1-2: Create custom plugin
+- Day 3-4: Deploy self-hosted instance
+- Day 5-7: Contribute to project
+
+## 🤝 Contributing to Documentation
+
+Found an error or want to improve the docs?
+
+1. Check [Contributing Guidelines](../CONTRIBUTING.md)
+2. Documentation lives in `docs/` directory
+3. Use Markdown format
+4. Follow existing structure
+5. Submit Pull Request
+
+## 📞 Get Help
+
+- **Questions**: [GitHub Discussions](https://github.com/afkutrotzdemda/Project-Aura/discussions)
+- **Issues**: [GitHub Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+- **Discord**: [Project-Aura Discord](https://discord.gg/project-aura) (placeholder)
+
+---
+
+**Last Updated**: 2024  
+**Documentation Version**: 1.0.0
diff --git a/docs/FEATURES_BEGINNER.md b/docs/FEATURES_BEGINNER.md
new file mode 100644
index 0000000..5c302b0
--- /dev/null
+++ b/docs/FEATURES_BEGINNER.md
@@ -0,0 +1,359 @@
+# Feature Guide - Beginner
+
+A beginner-friendly guide to using Project-Aura's core features.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Your First Conversation](#your-first-conversation)
+- [Choosing an AI Model](#choosing-an-ai-model)
+- [Managing Chats](#managing-chats)
+- [Basic Settings](#basic-settings)
+- [Understanding Responses](#understanding-responses)
+- [Tips for Better Results](#tips-for-better-results)
+
+## Getting Started
+
+Welcome to Project-Aura! This guide will help you get started with the basics.
+
+### What is Project-Aura?
+
+Project-Aura is a desktop application that lets you chat with advanced AI models from different providers (Google, OpenAI, Anthropic, and Mistral). Think of it as a ChatGPT-like experience, but with more flexibility and privacy.
+
+### The Interface
+
+![Main Interface](images/main-interface-placeholder.png)
+
+When you open Project-Aura, you'll see:
+
+1. **Sidebar (Left)**: Your chat history
+2. **Chat Area (Center)**: Your conversation
+3. **Header (Top)**: Settings and controls
+4. **Input Box (Bottom)**: Where you type messages
+
+## Your First Conversation
+
+### Step 1: Enter Your API Key
+
+Before you can chat, you need to add an API key:
+
+1. Click the **settings icon** (gear) in the top-right corner
+2. Select a model from the dropdown (e.g., "Gemini 2.0 Flash")
+3. Paste your API key in the "API Key" field
+4. The key is automatically saved and encrypted
+
+**Where to get API keys**: See the [Setup Guide](SETUP.md#api-key-setup) for instructions.
+
+### Step 2: Send Your First Message
+
+1. Type your message in the input box at the bottom
+2. Press **Enter** to send (or click the send button)
+3. Watch as the AI responds in real-time!
+
+**Example first messages**:
+- "Hello! What can you help me with?"
+- "Explain quantum computing in simple terms"
+- "Write a short poem about coffee"
+
+### Step 3: Continue the Conversation
+
+The AI remembers your conversation context, so you can:
+- Ask follow-up questions
+- Request changes to previous responses
+- Build on earlier topics
+
+**Example conversation**:
+```
+You: What's the capital of France?
+AI: The capital of France is Paris.
+
+You: Tell me three interesting facts about it.
+AI: Here are three interesting facts about Paris:
+1. The Eiffel Tower was only meant to stand for 20 years...
+2. Paris has 20 districts called "arrondissements"...
+3. The city has over 400 parks and gardens...
+```
+
+## Choosing an AI Model
+
+Different AI models have different strengths. Here's a simple guide:
+
+### For Most Tasks: Gemini 2.0 Flash (Recommended)
+- **Best for**: General conversations, questions, explanations
+- **Speed**: Very fast
+- **Cost**: Free tier available
+- **Strengths**: Great balance of quality and speed
+
+### For Complex Tasks: GPT-4o or Claude 3.5 Sonnet
+- **Best for**: Detailed analysis, creative writing, complex reasoning
+- **Speed**: Moderate
+- **Cost**: Pay-per-use
+- **Strengths**: Highest quality responses
+
+### For Quick Tasks: GPT-3.5 Turbo or Mistral Small
+- **Best for**: Simple questions, quick responses
+- **Speed**: Very fast
+- **Cost**: Lower cost
+- **Strengths**: Fast and economical
+
+### How to Switch Models
+
+1. Click the **model dropdown** in the header
+2. Select your preferred model
+3. Enter the API key for that provider (if different)
+4. Continue chatting - the new model is active immediately
+
+## Managing Chats
+
+### Creating a New Chat
+
+Click the **"New Chat"** button in the sidebar to start fresh:
+- Previous conversation context is cleared
+- A new chat session begins
+- Old chat is automatically saved
+
+### Switching Between Chats
+
+Click any chat in the sidebar to switch to it:
+- Your conversation history is restored
+- You can continue where you left off
+- Each chat is independent
+
+### Chat Titles
+
+Chat titles are automatically generated from your first message:
+- Titles update when you start a new conversation
+- You can identify chats at a glance
+- Example: "Help with Python code" or "Recipe for lasagna"
+
+### Deleting Chats
+
+To delete a chat:
+1. Hover over the chat in the sidebar
+2. Click the **trash/delete icon**
+3. Confirm the deletion
+
+**Warning**: Deleted chats cannot be recovered!
+
+## Basic Settings
+
+### Model Selection
+- **Location**: Header dropdown
+- **What it does**: Choose which AI model to use
+- **Tip**: Start with Gemini 2.0 Flash for best free experience
+
+### API Key Management
+- **Location**: Settings panel (gear icon)
+- **What it does**: Store your provider API keys
+- **Tip**: Keys are encrypted and stored securely on your computer
+
+### Agent Mode (Advanced)
+- **Location**: Toggle in header
+- **What it is**: Allows AI to perform actions (file access, web browsing, etc.)
+- **Beginner tip**: Leave this OFF for now - see [Expert Guide](FEATURES_EXPERT.md)
+
+## Understanding Responses
+
+### Streaming Responses
+
+As the AI generates its response, you'll see it appear word-by-word:
+- **Loading indicator**: Shows the AI is thinking
+- **Streaming text**: Appears in real-time
+- **Complete indicator**: Blinking cursor stops when done
+
+### Response Quality
+
+Factors affecting response quality:
+1. **Model choice**: Better models = better responses
+2. **Question clarity**: Clear questions get better answers
+3. **Context**: AI remembers previous messages in the conversation
+4. **Token limits**: Very long conversations may lose early context
+
+### Response Formatting
+
+The AI can format responses with:
+- **Paragraphs**: For readability
+- **Lists**: Numbered or bulleted
+- **Code blocks**: For programming code
+- **Bold/Italic**: For emphasis
+
+Example formatted response:
+```markdown
+Here's how to make coffee:
+
+1. **Grind beans** - Use medium grind
+2. **Heat water** - 195-205°F is ideal
+3. **Brew** - 4-5 minutes for best flavor
+
+*Tip*: Fresh beans make a huge difference!
+```
+
+## Tips for Better Results
+
+### 1. Be Specific
+
+❌ Poor: "Tell me about dogs"
+✅ Good: "What are the best dog breeds for apartment living?"
+
+### 2. Provide Context
+
+❌ Poor: "How do I fix it?"
+✅ Good: "My Python program shows 'IndexError'. How do I fix this?"
+
+### 3. Break Down Complex Questions
+
+❌ Poor: "Explain quantum computing, how it works, who invented it, and what it's used for"
+✅ Good: Ask one question at a time:
+- "What is quantum computing?"
+- "Who invented it?"
+- "What are its practical applications?"
+
+### 4. Ask for Clarification
+
+If the AI's response isn't clear:
+- "Can you explain that in simpler terms?"
+- "Can you give me an example?"
+- "What do you mean by [specific term]?"
+
+### 5. Request Different Formats
+
+You can ask the AI to format information differently:
+- "Can you summarize that in bullet points?"
+- "Can you explain this like I'm 10 years old?"
+- "Can you give me a step-by-step guide?"
+
+### 6. Iterate and Refine
+
+Don't hesitate to refine the AI's responses:
+- "That's good, but can you make it shorter?"
+- "Can you add more details about the second point?"
+- "Can you rewrite this in a more professional tone?"
+
+## Common Use Cases
+
+### Learning and Education
+
+**Example prompts**:
+- "Explain photosynthesis in simple terms"
+- "What's the difference between affect and effect?"
+- "Help me understand the French Revolution"
+
+### Writing Assistance
+
+**Example prompts**:
+- "Help me write a professional email to my boss"
+- "Check this paragraph for grammar mistakes: [paste text]"
+- "Give me 5 creative names for a pet cat"
+
+### Problem Solving
+
+**Example prompts**:
+- "I need to organize a birthday party for 20 people. Help me plan."
+- "What's the best way to learn guitar as a beginner?"
+- "How can I be more productive while working from home?"
+
+### Information Lookup
+
+**Example prompts**:
+- "What's the weather like in Tokyo right now?" (Note: Requires Agent Mode)
+- "Summarize the plot of 'The Great Gatsby'"
+- "What are the health benefits of green tea?"
+
+### Creative Tasks
+
+**Example prompts**:
+- "Write a short story about a robot learning to paint"
+- "Give me recipe ideas using chicken and broccoli"
+- "Help me brainstorm business name ideas for a bakery"
+
+## Keyboard Shortcuts
+
+Speed up your workflow with these shortcuts:
+
+- **Send message**: `Enter`
+- **New line in message**: `Shift + Enter`
+- **New chat**: `Ctrl/Cmd + N` (coming soon)
+- **Clear input**: `Escape` (when focused)
+
+## Safety and Privacy
+
+### Your Data is Local
+
+- All chats are stored on your computer
+- Nothing is sent to Project-Aura servers (we don't have any!)
+- Only you and the AI provider see your conversations
+
+### API Key Security
+
+- Keys are encrypted on your computer
+- Never share your API keys with others
+- Revoke and regenerate keys if you suspect compromise
+
+### Content Safety
+
+- AI models have built-in safety filters
+- Inappropriate requests may be blocked
+- Responses should be helpful, harmless, and honest
+
+## Troubleshooting
+
+### AI Not Responding
+
+1. Check that you've entered a valid API key
+2. Verify you have internet connection
+3. Try switching to a different model
+4. Check if your API key has credits/quota remaining
+
+### Slow Responses
+
+- Some models are slower than others
+- Complex questions take longer to process
+- Your internet speed affects streaming
+- Try switching to a faster model (e.g., Gemini Flash)
+
+### Error Messages
+
+Common errors and solutions:
+
+**"Invalid API Key"**
+- Double-check your key is copied correctly
+- Ensure no extra spaces
+- Verify the key hasn't been revoked
+
+**"Quota Exceeded"**
+- You've hit your provider's usage limit
+- Check your provider dashboard
+- Wait for quota reset or add billing
+
+**"Model Not Available"**
+- Some models require special access
+- Try a different model
+- Check provider's model availability
+
+## Next Steps
+
+Once you're comfortable with the basics:
+
+1. **Explore different models** - Try various AI providers to see what works best
+2. **Experiment with prompts** - Learn how to craft better questions
+3. **Try Agent Mode** - Enable advanced capabilities (see [Expert Guide](FEATURES_EXPERT.md))
+4. **Customize settings** - Explore additional configuration options
+
+### Additional Resources
+
+- [Expert Feature Guide](FEATURES_EXPERT.md) - Advanced features and techniques
+- [API Reference](API_REFERENCE.md) - Technical documentation
+- [Troubleshooting](TROUBLESHOOTING.md) - Detailed problem-solving
+- [FAQ](FAQ.md) - Frequently asked questions
+
+## Getting Help
+
+Need assistance?
+
+- Check the [Troubleshooting Guide](TROUBLESHOOTING.md)
+- Visit [GitHub Discussions](https://github.com/afkutrotzdemda/Project-Aura/discussions)
+- Open an [Issue](https://github.com/afkutrotzdemda/Project-Aura/issues)
+
+---
+
+**Happy chatting! 🎉**
diff --git a/docs/FEATURES_EXPERT.md b/docs/FEATURES_EXPERT.md
new file mode 100644
index 0000000..0d29f51
--- /dev/null
+++ b/docs/FEATURES_EXPERT.md
@@ -0,0 +1,811 @@
+# Feature Guide - Expert
+
+Advanced features, customization, and power-user techniques for Project-Aura.
+
+## Table of Contents
+
+- [Agent Mode](#agent-mode)
+- [Plugin System](#plugin-system)
+- [Advanced Configuration](#advanced-configuration)
+- [Custom Workflows](#custom-workflows)
+- [Performance Optimization](#performance-optimization)
+- [Development Mode](#development-mode)
+- [Advanced Prompting](#advanced-prompting)
+- [Backup and Migration](#backup-and-migration)
+
+## Agent Mode
+
+Agent Mode transforms the AI from a conversational assistant into an autonomous agent capable of performing actions on your behalf.
+
+### Overview
+
+When Agent Mode is enabled:
+- AI can call functions to interact with your system
+- Plugins extend the AI's capabilities
+- Responses include both text and action results
+- AI decides which functions to call based on context
+
+### Enabling Agent Mode
+
+**Via UI**:
+1. Toggle "Agent Mode" switch in the header
+2. Confirm any security warnings
+3. Select which plugins to enable
+
+**Via Configuration**:
+```json
+{
+  "settings": {
+    "agentMode": true
+  },
+  "plugins": {
+    "system-plugin": true,
+    "file-manager-plugin": true
+  }
+}
+```
+
+### How It Works
+
+```
+User: "What's my current disk usage and create a report file?"
+
+Agent Process:
+1. Parse intent → needs disk info + file creation
+2. Call getSystemInfo() from System Plugin
+3. Format results into report content
+4. Call writeFile() from File Manager Plugin
+5. Return success message to user
+```
+
+### Agent Mode Best Practices
+
+**Do**:
+✅ Start with minimal plugin permissions
+✅ Review plugin capabilities before enabling
+✅ Use specific instructions for actions
+✅ Monitor what the agent is doing
+✅ Keep plugins updated
+
+**Don't**:
+❌ Enable all plugins without understanding them
+❌ Use Agent Mode with untrusted plugin code
+❌ Give overly vague instructions
+❌ Enable Code Execution Plugin without sandboxing
+
+## Plugin System
+
+### Available Plugins
+
+#### 1. System Plugin (Safe - Always Enabled)
+
+**Capabilities**:
+- Get system information (OS, CPU, memory, disk)
+- Perform calculations
+- Show desktop notifications
+
+**Example usage**:
+```
+"What are my system specs?"
+"Calculate the compound interest on $1000 at 5% for 10 years"
+"Remind me to take a break in 25 minutes"
+```
+
+**Functions**:
+- `getSystemInfo()` - Returns system metrics
+- `calculate(expression)` - Evaluates math expressions
+- `showNotification(title, message)` - Displays notification
+
+#### 2. File Manager Plugin (⚠️ Use with caution)
+
+**Capabilities**:
+- Read file contents
+- Write files
+- List directory contents
+- File operations (copy, move, delete)
+
+**Security considerations**:
+- Configure allowed directories
+- Set file size limits
+- Restrict file types
+
+**Configuration**:
+```json
+{
+  "fileManagerPlugin": {
+    "allowedDirectories": [
+      "~/Documents/AIWorkspace",
+      "~/Downloads"
+    ],
+    "maxFileSize": "10MB",
+    "allowedExtensions": [".txt", ".md", ".json", ".csv"]
+  }
+}
+```
+
+**Example usage**:
+```
+"Read the contents of ~/Documents/notes.txt"
+"Create a CSV file with this data: [provide data]"
+"List all markdown files in my Documents folder"
+```
+
+#### 3. Web Browser Plugin (⚠️ Network access)
+
+**Capabilities**:
+- Fetch web page content
+- Extract data from websites
+- Check website status
+- Follow redirects
+
+**Configuration**:
+```json
+{
+  "webBrowserPlugin": {
+    "userAgent": "Project-Aura/1.0",
+    "timeout": 30000,
+    "maxRedirects": 5,
+    "followMetaRefresh": false
+  }
+}
+```
+
+**Example usage**:
+```
+"What's the current price of Bitcoin on CoinMarketCap?"
+"Fetch the latest blog post from example.com/blog"
+"Check if website.com is online"
+```
+
+**Limitations**:
+- JavaScript-rendered content may not be available
+- Some sites block automated access
+- Rate limiting may apply
+
+#### 4. Process Management Plugin (⚠️⚠️ High risk)
+
+**Capabilities**:
+- List running processes
+- Get process information
+- Monitor process resources
+- Terminate processes (with confirmation)
+
+**Security**: Recommend read-only mode:
+```json
+{
+  "processManagementPlugin": {
+    "readOnly": true,
+    "allowKill": false
+  }
+}
+```
+
+**Example usage**:
+```
+"What processes are using the most CPU?"
+"Is Chrome running?"
+"Show me all Node.js processes"
+```
+
+#### 5. Network Plugin
+
+**Capabilities**:
+- Ping hosts
+- DNS lookups
+- Port scanning (local only)
+- Network interface info
+
+**Example usage**:
+```
+"Ping google.com"
+"What's the IP address of github.com?"
+"Show my network interfaces"
+```
+
+#### 6. Code Execution Plugin (⚠️⚠️⚠️ Extreme risk)
+
+**Capabilities**:
+- Execute Python code
+- Execute JavaScript code
+- Run shell commands (if enabled)
+
+**SECURITY WARNING**: Only enable in sandboxed environment!
+
+**Sandboxed Configuration**:
+```json
+{
+  "codeExecutionPlugin": {
+    "enabled": false,
+    "sandboxed": true,
+    "allowedLanguages": ["python", "javascript"],
+    "timeout": 10000,
+    "maxMemory": "512MB",
+    "networkAccess": false,
+    "filesystemAccess": false
+  }
+}
+```
+
+**Example usage**:
+```
+"Run this Python code to analyze the data: [code]"
+"Execute this JavaScript to parse the JSON: [code]"
+```
+
+#### 7. Email Plugin
+
+**Capabilities**:
+- Send emails
+- Draft emails
+- Email templates
+
+**Configuration** (Gmail example):
+```json
+{
+  "emailPlugin": {
+    "provider": "smtp",
+    "smtp": {
+      "host": "smtp.gmail.com",
+      "port": 587,
+      "secure": false,
+      "auth": {
+        "user": "your-email@gmail.com",
+        "pass": "your-app-password"
+      }
+    },
+    "from": {
+      "name": "Your Name",
+      "email": "your-email@gmail.com"
+    }
+  }
+}
+```
+
+**Example usage**:
+```
+"Send an email to john@example.com with subject 'Meeting Tomorrow'"
+"Draft an email to my team about the project update"
+```
+
+#### 8. Calendar Plugin
+
+**Capabilities**:
+- Create events
+- List upcoming events
+- Check availability
+- Set reminders
+
+**Configuration** (Google Calendar):
+```json
+{
+  "calendarPlugin": {
+    "provider": "google",
+    "credentials": {
+      "clientId": "your-client-id",
+      "clientSecret": "your-client-secret",
+      "refreshToken": "your-refresh-token"
+    },
+    "calendarId": "primary",
+    "timezone": "America/New_York"
+  }
+}
+```
+
+**Example usage**:
+```
+"Add a meeting with Alice tomorrow at 2pm"
+"What's on my calendar this week?"
+"Am I free on Friday afternoon?"
+```
+
+### Plugin Development
+
+Create custom plugins to extend functionality:
+
+```typescript
+// customPlugin.ts
+import { PluginManifest } from '../services/pluginService';
+
+export const customPluginManifest: PluginManifest = {
+  id: 'custom-plugin',
+  name: 'Custom Plugin',
+  description: 'Your custom functionality',
+  version: '1.0.0',
+  author: 'Your Name',
+  main: 'customPlugin.ts',
+  functions: ['customFunction']
+};
+
+export const customFunctionDeclaration = {
+  name: 'customFunction',
+  description: 'Does something useful',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      param1: {
+        type: "string",
+        description: "First parameter"
+      },
+      param2: {
+        type: "number",
+        description: "Second parameter"
+      }
+    },
+    required: ["param1"]
+  }
+};
+
+export async function customFunction(args: { 
+  param1: string; 
+  param2?: number 
+}): Promise<any> {
+  // Your implementation here
+  console.log(`Called with: ${args.param1}, ${args.param2}`);
+  
+  return {
+    success: true,
+    result: `Processed ${args.param1}`
+  };
+}
+```
+
+**Register the plugin**:
+```typescript
+// In App.tsx
+import { customPluginManifest } from './plugins/customPlugin';
+import * as customPlugin from './plugins/customPlugin';
+
+// In useEffect
+pluginService.loadPlugin(customPluginManifest, customPlugin);
+pluginService.enablePlugin('custom-plugin');
+```
+
+## Advanced Configuration
+
+### Configuration File Location
+
+- **Linux**: `~/.config/Project-Aura/config.json`
+- **macOS**: `~/Library/Application Support/Project-Aura/config.json`
+- **Windows**: `%APPDATA%\Project-Aura\config.json`
+
+### Complete Configuration Schema
+
+```json
+{
+  "version": "1.0.0",
+  "settings": {
+    "theme": "dark",
+    "defaultProvider": "gemini",
+    "defaultModel": "gemini-2.0-flash-exp",
+    "agentMode": false,
+    "streamingEnabled": true,
+    "autoSave": true,
+    "maxChatHistory": 100,
+    "messageRetention": 30,
+    "showTimestamps": true,
+    "enableSounds": false,
+    "fontSize": "medium",
+    "codeSyntaxHighlighting": true
+  },
+  "plugins": {
+    "system-plugin": true,
+    "file-manager-plugin": false,
+    "web-browser-plugin": false,
+    "process-management-plugin": false,
+    "network-plugin": false,
+    "code-execution-plugin": false,
+    "email-plugin": false,
+    "calendar-plugin": false
+  },
+  "advanced": {
+    "maxTokens": 4096,
+    "temperature": 0.7,
+    "topP": 0.9,
+    "requestTimeout": 60000,
+    "maxRetries": 3,
+    "logLevel": "info",
+    "enableDebug": false
+  },
+  "shortcuts": {
+    "newChat": "Ctrl+N",
+    "send": "Enter",
+    "multiline": "Shift+Enter",
+    "focusInput": "Ctrl+L"
+  }
+}
+```
+
+### Environment Variables
+
+Override configuration with environment variables:
+
+```bash
+# API Keys (alternative to UI)
+export GEMINI_API_KEY="your-key"
+export OPENAI_API_KEY="your-key"
+export CLAUDE_API_KEY="your-key"
+export MISTRAL_API_KEY="your-key"
+
+# Feature Flags
+export ENABLE_AGENT_MODE=true
+export ENABLE_EXPERIMENTAL_FEATURES=true
+
+# Debugging
+export DEBUG=project-aura:*
+export LOG_LEVEL=debug
+```
+
+### Model-Specific Parameters
+
+Fine-tune model behavior:
+
+```typescript
+// Via LLMService configuration
+llmService.initialize({
+  provider: 'gemini',
+  model: 'gemini-2.0-flash-exp',
+  apiKey: 'your-key',
+  parameters: {
+    temperature: 0.7,      // Creativity (0-1)
+    topP: 0.9,            // Nucleus sampling
+    topK: 40,             // Token sampling
+    maxOutputTokens: 2048, // Response length
+    stopSequences: ['\n\n\n'] // Stop generation
+  }
+});
+```
+
+**Temperature Guide**:
+- `0.0-0.3`: Focused, deterministic, factual
+- `0.4-0.7`: Balanced creativity and accuracy
+- `0.8-1.0`: Creative, varied, exploratory
+
+## Custom Workflows
+
+### Workflow Automation with Prompts
+
+Create reusable prompt templates:
+
+```typescript
+// promptTemplates.ts
+export const templates = {
+  codeReview: `Review this code for:
+- Best practices
+- Performance issues
+- Security vulnerabilities
+- Potential bugs
+
+Code:
+{code}`,
+
+  documentSummarizer: `Summarize this document in {format}:
+- Main points
+- Key takeaways
+- Action items
+
+Document:
+{document}`,
+
+  dataAnalysis: `Analyze this data and provide:
+- Statistical summary
+- Trends and patterns
+- Visualize recommendations
+
+Data:
+{data}`
+};
+
+// Usage
+const prompt = templates.codeReview.replace('{code}', myCode);
+```
+
+### Chaining Operations
+
+Execute multi-step workflows:
+
+**Example: Research and Report**
+```
+Step 1: "Search for recent news about quantum computing"
+[AI fetches and summarizes]
+
+Step 2: "Create a detailed report with the following sections: 
+        Overview, Recent Advances, Key Players, Future Outlook"
+[AI structures information]
+
+Step 3: "Save this report as quantum-computing-report.md 
+        in my Documents folder"
+[AI uses File Manager Plugin]
+```
+
+### Batch Processing
+
+Process multiple items efficiently:
+
+```
+"For each file in ~/Documents/data/*.csv:
+1. Read the file
+2. Calculate summary statistics
+3. Create a report
+4. Save to ~/Documents/reports/[filename]-report.txt"
+```
+
+## Performance Optimization
+
+### Reducing Latency
+
+**1. Model Selection**:
+- Use Flash models for quick responses
+- Reserve Pro models for complex tasks
+
+**2. Streaming**:
+- Enable streaming for real-time feedback
+- Perception of speed improves user experience
+
+**3. Caching** (future):
+- Cache common queries
+- Reuse similar context
+
+### Managing Token Usage
+
+**Monitor token consumption**:
+```typescript
+// Estimate tokens (rough)
+const tokenCount = Math.ceil(text.length / 4);
+
+// Truncate context when needed
+const maxContextTokens = 4000;
+if (tokenCount > maxContextTokens) {
+  // Trim older messages
+}
+```
+
+**Strategies**:
+- Keep conversations focused
+- Start new chats for different topics
+- Summarize long contexts periodically
+
+### Memory Management
+
+**Chat History Limits**:
+```json
+{
+  "settings": {
+    "maxChatHistory": 50,
+    "messageRetention": 30,
+    "autoArchive": true
+  }
+}
+```
+
+**Manual Cleanup**:
+```bash
+# Archive old chats
+find ~/.config/Project-Aura/chats -mtime +30 -exec gzip {} \;
+
+# Clean up logs
+rm ~/.config/Project-Aura/logs/*.log
+```
+
+## Development Mode
+
+### Enabling Debug Mode
+
+**Via Configuration**:
+```json
+{
+  "advanced": {
+    "enableDebug": true,
+    "logLevel": "debug",
+    "showDevTools": true
+  }
+}
+```
+
+**Via Environment**:
+```bash
+export DEBUG=project-aura:*
+export NODE_ENV=development
+npm run dev
+```
+
+### Developer Tools
+
+**Electron DevTools**:
+- `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (macOS)
+- Console, Network, Performance tabs available
+
+**Logging**:
+```typescript
+// In code
+console.log('[LLMService]', 'Message sent:', message);
+console.error('[Plugin]', 'Error:', error);
+
+// View logs
+tail -f ~/.config/Project-Aura/logs/app.log
+```
+
+### Testing Plugins
+
+**Unit Testing**:
+```typescript
+// pluginName.test.ts
+import { myFunction, myFunctionDeclaration } from './myPlugin';
+
+describe('MyPlugin', () => {
+  test('function executes correctly', async () => {
+    const result = await myFunction({ param: 'test' });
+    expect(result.success).toBe(true);
+  });
+
+  test('declaration is valid', () => {
+    expect(myFunctionDeclaration.name).toBe('myFunction');
+    expect(myFunctionDeclaration.parameters).toBeDefined();
+  });
+});
+```
+
+## Advanced Prompting
+
+### Prompt Engineering Techniques
+
+**1. Few-Shot Learning**:
+```
+"Convert these examples to JSON:
+
+Example 1:
+Input: John Doe, 30, Engineer
+Output: {"name": "John Doe", "age": 30, "role": "Engineer"}
+
+Example 2:
+Input: Jane Smith, 25, Designer
+Output: {"name": "Jane Smith", "age": 25, "role": "Designer"}
+
+Now convert: Alice Johnson, 28, Manager"
+```
+
+**2. Chain-of-Thought**:
+```
+"Solve this step by step:
+What's 15% of 240?
+
+Think through:
+1. Convert percentage to decimal
+2. Multiply by the number
+3. Show the result"
+```
+
+**3. Role-Based Prompting**:
+```
+"Act as a senior software architect. Review this system design 
+and provide feedback on scalability, security, and maintainability."
+```
+
+**4. Constrained Output**:
+```
+"Summarize in exactly 3 bullet points, each under 20 words."
+```
+
+### System Prompts (Coming Soon)
+
+Define default behavior for all interactions:
+
+```json
+{
+  "systemPrompt": "You are a helpful AI assistant focused on providing 
+                   accurate, concise responses. When uncertain, say so. 
+                   Always explain your reasoning."
+}
+```
+
+## Backup and Migration
+
+### Exporting Data
+
+**Export All Chats**:
+```bash
+# Create backup
+cd ~/.config/Project-Aura
+tar -czf backup-$(date +%Y%m%d).tar.gz chats/ config.json
+
+# Store securely
+mv backup-*.tar.gz ~/Backups/
+```
+
+**Export Single Chat**:
+```bash
+# Copy specific chat
+cp ~/.config/Project-Aura/chats/1234567890.json ~/backup-chat.json
+```
+
+**Export Configuration**:
+```bash
+# Backup settings (without API keys)
+jq 'del(.apiKeys)' ~/.config/Project-Aura/config.json > config-backup.json
+```
+
+### Importing Data
+
+**Restore from Backup**:
+```bash
+# Extract backup
+tar -xzf backup-20240101.tar.gz -C ~/.config/Project-Aura/
+
+# Restart application
+```
+
+**Import Single Chat**:
+```bash
+# Copy to chats directory
+cp backup-chat.json ~/.config/Project-Aura/chats/
+
+# Will appear in sidebar on next launch
+```
+
+### Migration Between Machines
+
+**1. Export from old machine**:
+```bash
+cd ~/.config/Project-Aura
+tar -czf project-aura-export.tar.gz chats/ config.json plugins/
+```
+
+**2. Transfer** (via USB, cloud, network)
+
+**3. Import on new machine**:
+```bash
+mkdir -p ~/.config/Project-Aura
+tar -xzf project-aura-export.tar.gz -C ~/.config/Project-Aura/
+```
+
+**4. Re-enter API keys** (security - not exported)
+
+### Sync Across Devices (Manual)
+
+```bash
+# Use rsync for periodic sync
+rsync -avz ~/.config/Project-Aura/chats/ \
+      user@other-machine:~/.config/Project-Aura/chats/
+
+# Or use cloud storage
+ln -s ~/Dropbox/Project-Aura-Sync ~/.config/Project-Aura/chats
+```
+
+## Pro Tips
+
+### 1. Context Management
+- Start new chats for different topics
+- Summarize long discussions periodically
+- Reference earlier messages explicitly
+
+### 2. Efficient Model Switching
+- Use fast models for drafting
+- Switch to powerful models for refinement
+- Test responses across multiple models
+
+### 3. Plugin Combinations
+- Combine File Manager + Web Browser for research automation
+- Use System + Email for monitoring alerts
+- Chain Calendar + Email for meeting management
+
+### 4. Security Practices
+- Regular API key rotation
+- Minimal plugin permissions
+- Review plugin actions in logs
+- Sandbox untrusted code execution
+
+### 5. Productivity Hacks
+- Create custom keyboard shortcuts
+- Use prompt templates for common tasks
+- Set up system notifications for long operations
+- Organize chats with descriptive names
+
+## See Also
+
+- [API Reference](API_REFERENCE.md) - Technical API documentation
+- [Plugin Development Guide](PLUGIN_DEVELOPMENT.md) - Create custom plugins
+- [Architecture](ARCHITECTURE.md) - System internals
+- [Troubleshooting](TROUBLESHOOTING.md) - Advanced problem solving
+
+---
+
+**Ready to build something amazing? 🚀**
diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md
new file mode 100644
index 0000000..eaeea9b
--- /dev/null
+++ b/docs/INTEGRATIONS.md
@@ -0,0 +1,1005 @@
+# Integrations Guide
+
+Comprehensive guide for integrating Project-Aura with external services and platforms.
+
+## Table of Contents
+
+- [Azure Integration](#azure-integration)
+- [Composio Integration](#composio-integration)
+- [Model Context Protocol (MCP)](#model-context-protocol-mcp)
+- [Third-Party Services](#third-party-services)
+- [API Integrations](#api-integrations)
+- [Webhook Support](#webhook-support)
+- [Custom Integrations](#custom-integrations)
+
+## Azure Integration
+
+### Azure OpenAI Service
+
+Use Azure-hosted OpenAI models for enhanced security and compliance.
+
+#### Prerequisites
+
+1. Azure subscription
+2. Azure OpenAI resource deployed
+3. API key and endpoint from Azure Portal
+
+#### Configuration
+
+**Method 1: Environment Variables**
+
+```bash
+# .env
+AZURE_OPENAI_API_KEY=your-azure-api-key
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+AZURE_OPENAI_DEPLOYMENT=your-deployment-name
+AZURE_OPENAI_API_VERSION=2024-02-15-preview
+```
+
+**Method 2: Code Configuration**
+
+```typescript
+// azureOpenAIConfig.ts
+export const azureOpenAIConfig = {
+  provider: 'azure-openai',
+  apiKey: process.env.AZURE_OPENAI_API_KEY,
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+  deploymentName: process.env.AZURE_OPENAI_DEPLOYMENT,
+  apiVersion: process.env.AZURE_OPENAI_API_VERSION || '2024-02-15-preview'
+};
+```
+
+#### Implementation
+
+```typescript
+// services/azureOpenAIService.ts
+import { OpenAIClient, AzureKeyCredential } from '@azure/openai';
+
+class AzureOpenAIService {
+  private client: OpenAIClient;
+  private deploymentName: string;
+
+  async initialize(config: AzureOpenAIConfig): Promise<void> {
+    this.client = new OpenAIClient(
+      config.endpoint,
+      new AzureKeyCredential(config.apiKey)
+    );
+    this.deploymentName = config.deploymentName;
+  }
+
+  async sendMessage(message: string): Promise<string> {
+    const response = await this.client.getChatCompletions(
+      this.deploymentName,
+      [{ role: 'user', content: message }]
+    );
+    
+    return response.choices[0]?.message?.content || '';
+  }
+
+  async streamMessage(
+    message: string,
+    onChunk: (chunk: string) => void
+  ): Promise<void> {
+    const stream = await this.client.streamChatCompletions(
+      this.deploymentName,
+      [{ role: 'user', content: message }]
+    );
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        onChunk(content);
+      }
+    }
+  }
+}
+
+export const azureOpenAIService = new AzureOpenAIService();
+```
+
+#### Register with LLMService
+
+```typescript
+// Extend LLMService to support Azure
+async initializeAzureOpenAI(
+  apiKey: string,
+  endpoint: string,
+  deploymentName: string
+): Promise<void> {
+  this.currentModel = {
+    provider: 'azure-openai',
+    apiKey,
+    endpoint,
+    deploymentName,
+    baseURL: endpoint
+  };
+  this.currentProvider = 'azure-openai' as LLMProvider;
+}
+```
+
+### Azure Cognitive Services
+
+#### Speech-to-Text Integration
+
+```typescript
+// plugins/azureSpeechPlugin.ts
+import * as sdk from 'microsoft-cognitiveservices-speech-sdk';
+
+export const azureSpeechPluginManifest = {
+  id: 'azure-speech-plugin',
+  name: 'Azure Speech Plugin',
+  description: 'Speech-to-text and text-to-speech using Azure',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'azureSpeechPlugin.ts',
+  functions: ['speechToText', 'textToSpeech']
+};
+
+export const speechToTextDeclaration = {
+  name: 'speechToText',
+  description: 'Convert speech to text',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      audioFile: {
+        type: "string",
+        description: "Path to audio file"
+      },
+      language: {
+        type: "string",
+        description: "Language code (e.g., en-US)",
+        enum: ["en-US", "es-ES", "fr-FR", "de-DE"]
+      }
+    },
+    required: ["audioFile"]
+  }
+};
+
+export async function speechToText(args: {
+  audioFile: string;
+  language?: string;
+}): Promise<{ text: string }> {
+  const speechConfig = sdk.SpeechConfig.fromSubscription(
+    process.env.AZURE_SPEECH_KEY!,
+    process.env.AZURE_SPEECH_REGION!
+  );
+  
+  speechConfig.speechRecognitionLanguage = args.language || 'en-US';
+  
+  const audioConfig = sdk.AudioConfig.fromWavFileInput(
+    fs.readFileSync(args.audioFile)
+  );
+  
+  const recognizer = new sdk.SpeechRecognizer(speechConfig, audioConfig);
+  
+  return new Promise((resolve, reject) => {
+    recognizer.recognizeOnceAsync(
+      result => {
+        if (result.reason === sdk.ResultReason.RecognizedSpeech) {
+          resolve({ text: result.text });
+        } else {
+          reject(new Error('Speech recognition failed'));
+        }
+        recognizer.close();
+      },
+      error => {
+        recognizer.close();
+        reject(error);
+      }
+    );
+  });
+}
+```
+
+#### Configuration
+
+```json
+{
+  "azureServices": {
+    "openai": {
+      "endpoint": "https://your-resource.openai.azure.com/",
+      "deployments": {
+        "gpt4": "your-gpt4-deployment",
+        "gpt35": "your-gpt35-deployment"
+      }
+    },
+    "speech": {
+      "key": "your-speech-key",
+      "region": "eastus"
+    },
+    "translator": {
+      "key": "your-translator-key",
+      "endpoint": "https://api.cognitive.microsofttranslator.com/"
+    }
+  }
+}
+```
+
+## Composio Integration
+
+Composio provides managed integrations for 100+ tools and services.
+
+### Setup
+
+```bash
+# Install Composio SDK
+npm install composio-core
+```
+
+### Configuration
+
+```typescript
+// services/composioService.ts
+import { Composio } from 'composio-core';
+
+class ComposioService {
+  private client: Composio;
+
+  async initialize(apiKey: string): Promise<void> {
+    this.client = new Composio({
+      apiKey: apiKey
+    });
+  }
+
+  async getConnections(): Promise<any[]> {
+    return await this.client.connections.list();
+  }
+
+  async executeAction(
+    connection: string,
+    action: string,
+    params: any
+  ): Promise<any> {
+    return await this.client.actions.execute({
+      connectionId: connection,
+      actionName: action,
+      input: params
+    });
+  }
+}
+
+export const composioService = new ComposioService();
+```
+
+### Available Integrations
+
+#### GitHub Integration
+
+```typescript
+export const githubPluginManifest = {
+  id: 'github-plugin',
+  name: 'GitHub Plugin',
+  description: 'Interact with GitHub repositories',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'githubPlugin.ts',
+  functions: ['createIssue', 'listRepositories', 'createPR']
+};
+
+export const createIssueDeclaration = {
+  name: 'createIssue',
+  description: 'Create a GitHub issue',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      repo: {
+        type: "string",
+        description: "Repository name (owner/repo)"
+      },
+      title: {
+        type: "string",
+        description: "Issue title"
+      },
+      body: {
+        type: "string",
+        description: "Issue description"
+      },
+      labels: {
+        type: "array",
+        description: "Labels to add",
+        items: { type: "string" }
+      }
+    },
+    required: ["repo", "title", "body"]
+  }
+};
+
+export async function createIssue(args: {
+  repo: string;
+  title: string;
+  body: string;
+  labels?: string[];
+}): Promise<any> {
+  return await composioService.executeAction(
+    'github',
+    'CREATE_ISSUE',
+    {
+      repository: args.repo,
+      title: args.title,
+      body: args.body,
+      labels: args.labels || []
+    }
+  );
+}
+```
+
+#### Slack Integration
+
+```typescript
+export const slackPluginManifest = {
+  id: 'slack-plugin',
+  name: 'Slack Plugin',
+  description: 'Send messages and interact with Slack',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'slackPlugin.ts',
+  functions: ['sendMessage', 'listChannels']
+};
+
+export const sendMessageDeclaration = {
+  name: 'sendSlackMessage',
+  description: 'Send a message to Slack',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      channel: {
+        type: "string",
+        description: "Channel name or ID"
+      },
+      text: {
+        type: "string",
+        description: "Message text"
+      },
+      threadTs: {
+        type: "string",
+        description: "Thread timestamp (for replies)"
+      }
+    },
+    required: ["channel", "text"]
+  }
+};
+
+export async function sendSlackMessage(args: {
+  channel: string;
+  text: string;
+  threadTs?: string;
+}): Promise<any> {
+  return await composioService.executeAction(
+    'slack',
+    'SEND_MESSAGE',
+    {
+      channel: args.channel,
+      text: args.text,
+      thread_ts: args.threadTs
+    }
+  );
+}
+```
+
+#### Google Drive Integration
+
+```typescript
+export const googleDrivePluginManifest = {
+  id: 'google-drive-plugin',
+  name: 'Google Drive Plugin',
+  description: 'Access and manage Google Drive files',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'googleDrivePlugin.ts',
+  functions: ['uploadFile', 'listFiles', 'downloadFile']
+};
+
+export const uploadFileDeclaration = {
+  name: 'uploadToGoogleDrive',
+  description: 'Upload a file to Google Drive',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      filePath: {
+        type: "string",
+        description: "Local file path"
+      },
+      fileName: {
+        type: "string",
+        description: "Name for the file in Drive"
+      },
+      folderId: {
+        type: "string",
+        description: "Destination folder ID"
+      }
+    },
+    required: ["filePath", "fileName"]
+  }
+};
+
+export async function uploadToGoogleDrive(args: {
+  filePath: string;
+  fileName: string;
+  folderId?: string;
+}): Promise<any> {
+  const fileContent = fs.readFileSync(args.filePath);
+  
+  return await composioService.executeAction(
+    'google-drive',
+    'UPLOAD_FILE',
+    {
+      name: args.fileName,
+      content: fileContent.toString('base64'),
+      folderId: args.folderId
+    }
+  );
+}
+```
+
+## Model Context Protocol (MCP)
+
+MCP provides standardized context sharing between AI applications.
+
+### Overview
+
+The Model Context Protocol enables:
+- **Context Sharing**: Share conversation context across applications
+- **Tool Discovery**: Discover and use tools from other MCP servers
+- **Resource Access**: Access external resources through standardized interface
+
+### MCP Server Implementation
+
+```typescript
+// services/mcpServer.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+class MCPServer {
+  private server: Server;
+
+  async start(): Promise<void> {
+    this.server = new Server({
+      name: 'project-aura-mcp',
+      version: '1.0.0'
+    }, {
+      capabilities: {
+        tools: {}
+      }
+    });
+
+    // Register tools
+    this.server.setRequestHandler('tools/list', async () => {
+      return {
+        tools: [
+          {
+            name: 'get_system_info',
+            description: 'Get system information',
+            inputSchema: {
+              type: 'object',
+              properties: {}
+            }
+          },
+          {
+            name: 'read_file',
+            description: 'Read file contents',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: {
+                  type: 'string',
+                  description: 'File path'
+                }
+              },
+              required: ['path']
+            }
+          }
+        ]
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler('tools/call', async (request) => {
+      const { name, arguments: args } = request.params;
+
+      switch (name) {
+        case 'get_system_info':
+          return await this.getSystemInfo();
+        case 'read_file':
+          return await this.readFile(args.path);
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+    });
+
+    // Start server
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+
+  private async getSystemInfo(): Promise<any> {
+    return {
+      platform: process.platform,
+      arch: process.arch,
+      nodeVersion: process.version,
+      memory: process.memoryUsage()
+    };
+  }
+
+  private async readFile(path: string): Promise<any> {
+    const content = await fs.promises.readFile(path, 'utf-8');
+    return { content };
+  }
+}
+
+export const mcpServer = new MCPServer();
+```
+
+### MCP Client Implementation
+
+```typescript
+// services/mcpClient.ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+class MCPClient {
+  private client: Client;
+
+  async connect(serverPath: string): Promise<void> {
+    const transport = new StdioClientTransport({
+      command: serverPath
+    });
+
+    this.client = new Client({
+      name: 'project-aura-client',
+      version: '1.0.0'
+    }, {
+      capabilities: {}
+    });
+
+    await this.client.connect(transport);
+  }
+
+  async listTools(): Promise<any[]> {
+    const response = await this.client.request({
+      method: 'tools/list'
+    });
+    return response.tools;
+  }
+
+  async callTool(name: string, args: any): Promise<any> {
+    return await this.client.request({
+      method: 'tools/call',
+      params: {
+        name,
+        arguments: args
+      }
+    });
+  }
+}
+
+export const mcpClient = new MCPClient();
+```
+
+### Using MCP Tools in Plugin
+
+```typescript
+// plugins/mcpPlugin.ts
+export const mcpPluginManifest = {
+  id: 'mcp-plugin',
+  name: 'MCP Plugin',
+  description: 'Access tools from MCP servers',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'mcpPlugin.ts',
+  functions: ['callMCPTool', 'listMCPTools']
+};
+
+export const callMCPToolDeclaration = {
+  name: 'callMCPTool',
+  description: 'Call a tool from connected MCP server',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      server: {
+        type: "string",
+        description: "MCP server name"
+      },
+      tool: {
+        type: "string",
+        description: "Tool name"
+      },
+      arguments: {
+        type: "object",
+        description: "Tool arguments"
+      }
+    },
+    required: ["server", "tool", "arguments"]
+  }
+};
+
+export async function callMCPTool(args: {
+  server: string;
+  tool: string;
+  arguments: any;
+}): Promise<any> {
+  await mcpClient.connect(args.server);
+  return await mcpClient.callTool(args.tool, args.arguments);
+}
+```
+
+## Third-Party Services
+
+### Notion Integration
+
+```typescript
+// plugins/notionPlugin.ts
+import { Client } from '@notionhq/client';
+
+const notion = new Client({
+  auth: process.env.NOTION_API_KEY
+});
+
+export const notionPluginManifest = {
+  id: 'notion-plugin',
+  name: 'Notion Plugin',
+  description: 'Interact with Notion databases and pages',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'notionPlugin.ts',
+  functions: ['createPage', 'queryDatabase', 'updatePage']
+};
+
+export const createPageDeclaration = {
+  name: 'createNotionPage',
+  description: 'Create a new page in Notion',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      parentId: {
+        type: "string",
+        description: "Parent page or database ID"
+      },
+      title: {
+        type: "string",
+        description: "Page title"
+      },
+      content: {
+        type: "string",
+        description: "Page content (markdown)"
+      }
+    },
+    required: ["parentId", "title", "content"]
+  }
+};
+
+export async function createNotionPage(args: {
+  parentId: string;
+  title: string;
+  content: string;
+}): Promise<any> {
+  const response = await notion.pages.create({
+    parent: { page_id: args.parentId },
+    properties: {
+      title: {
+        title: [
+          {
+            text: { content: args.title }
+          }
+        ]
+      }
+    },
+    children: [
+      {
+        object: 'block',
+        type: 'paragraph',
+        paragraph: {
+          rich_text: [
+            {
+              type: 'text',
+              text: { content: args.content }
+            }
+          ]
+        }
+      }
+    ]
+  });
+
+  return {
+    id: response.id,
+    url: response.url
+  };
+}
+```
+
+### Airtable Integration
+
+```typescript
+// plugins/airtablePlugin.ts
+import Airtable from 'airtable';
+
+Airtable.configure({
+  apiKey: process.env.AIRTABLE_API_KEY
+});
+
+export const airtablePluginManifest = {
+  id: 'airtable-plugin',
+  name: 'Airtable Plugin',
+  description: 'Manage Airtable records',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'airtablePlugin.ts',
+  functions: ['createRecord', 'listRecords', 'updateRecord']
+};
+
+export const createRecordDeclaration = {
+  name: 'createAirtableRecord',
+  description: 'Create a new record in Airtable',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      baseId: {
+        type: "string",
+        description: "Airtable base ID"
+      },
+      tableName: {
+        type: "string",
+        description: "Table name"
+      },
+      fields: {
+        type: "object",
+        description: "Record fields"
+      }
+    },
+    required: ["baseId", "tableName", "fields"]
+  }
+};
+
+export async function createAirtableRecord(args: {
+  baseId: string;
+  tableName: string;
+  fields: Record<string, any>;
+}): Promise<any> {
+  const base = Airtable.base(args.baseId);
+  
+  const record = await base(args.tableName).create(args.fields);
+  
+  return {
+    id: record.id,
+    fields: record.fields
+  };
+}
+```
+
+## API Integrations
+
+### REST API Client Plugin
+
+```typescript
+// plugins/apiClientPlugin.ts
+import axios from 'axios';
+
+export const apiClientPluginManifest = {
+  id: 'api-client-plugin',
+  name: 'API Client Plugin',
+  description: 'Make HTTP requests to REST APIs',
+  version: '1.0.0',
+  author: 'Project-Aura',
+  main: 'apiClientPlugin.ts',
+  functions: ['makeRequest']
+};
+
+export const makeRequestDeclaration = {
+  name: 'makeAPIRequest',
+  description: 'Make an HTTP request to an API',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      method: {
+        type: "string",
+        description: "HTTP method",
+        enum: ["GET", "POST", "PUT", "DELETE", "PATCH"]
+      },
+      url: {
+        type: "string",
+        description: "API endpoint URL"
+      },
+      headers: {
+        type: "object",
+        description: "Request headers"
+      },
+      body: {
+        type: "object",
+        description: "Request body"
+      }
+    },
+    required: ["method", "url"]
+  }
+};
+
+export async function makeAPIRequest(args: {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: any;
+}): Promise<any> {
+  try {
+    const response = await axios({
+      method: args.method,
+      url: args.url,
+      headers: args.headers || {},
+      data: args.body
+    });
+
+    return {
+      status: response.status,
+      headers: response.headers,
+      data: response.data
+    };
+  } catch (error) {
+    throw new Error(`API request failed: ${error.message}`);
+  }
+}
+```
+
+## Webhook Support
+
+### Incoming Webhooks
+
+```typescript
+// services/webhookService.ts
+import express from 'express';
+import crypto from 'crypto';
+
+class WebhookService {
+  private app: express.Application;
+  private handlers: Map<string, Function>;
+
+  constructor() {
+    this.app = express();
+    this.handlers = new Map();
+    this.setupRoutes();
+  }
+
+  private setupRoutes(): void {
+    this.app.post('/webhook/:id', async (req, res) => {
+      const { id } = req.params;
+      const handler = this.handlers.get(id);
+
+      if (!handler) {
+        return res.status(404).json({ error: 'Webhook not found' });
+      }
+
+      // Verify signature (if configured)
+      if (req.headers['x-webhook-signature']) {
+        const isValid = this.verifySignature(
+          req.body,
+          req.headers['x-webhook-signature'] as string
+        );
+        if (!isValid) {
+          return res.status(401).json({ error: 'Invalid signature' });
+        }
+      }
+
+      try {
+        await handler(req.body);
+        res.status(200).json({ received: true });
+      } catch (error) {
+        console.error('Webhook handler error:', error);
+        res.status(500).json({ error: 'Handler failed' });
+      }
+    });
+  }
+
+  registerHandler(id: string, handler: Function): void {
+    this.handlers.set(id, handler);
+  }
+
+  private verifySignature(body: any, signature: string): boolean {
+    const secret = process.env.WEBHOOK_SECRET || '';
+    const computed = crypto
+      .createHmac('sha256', secret)
+      .update(JSON.stringify(body))
+      .digest('hex');
+    return computed === signature;
+  }
+
+  start(port: number = 3001): void {
+    this.app.listen(port, () => {
+      console.log(`Webhook server listening on port ${port}`);
+    });
+  }
+}
+
+export const webhookService = new WebhookService();
+```
+
+## Custom Integrations
+
+### Creating Custom Integration Plugin
+
+```typescript
+// plugins/customIntegrationPlugin.ts
+
+// 1. Define manifest
+export const customIntegrationManifest = {
+  id: 'custom-integration',
+  name: 'Custom Integration',
+  description: 'Integration with custom service',
+  version: '1.0.0',
+  author: 'Your Name',
+  main: 'customIntegrationPlugin.ts',
+  functions: ['customAction']
+};
+
+// 2. Define function declaration
+export const customActionDeclaration = {
+  name: 'customAction',
+  description: 'Perform custom action',
+  parameters: {
+    type: "object" as const,
+    properties: {
+      param1: {
+        type: "string",
+        description: "First parameter"
+      }
+    },
+    required: ["param1"]
+  }
+};
+
+// 3. Implement function
+export async function customAction(args: {
+  param1: string;
+}): Promise<any> {
+  // Your integration logic here
+  const result = await yourServiceAPI.call(args.param1);
+  return result;
+}
+```
+
+## Integration Configuration File
+
+```json
+{
+  "integrations": {
+    "azure": {
+      "enabled": true,
+      "openai": {
+        "endpoint": "https://your-resource.openai.azure.com/",
+        "deployments": ["gpt-4", "gpt-35-turbo"]
+      },
+      "speech": {
+        "region": "eastus"
+      }
+    },
+    "composio": {
+      "enabled": true,
+      "connections": ["github", "slack", "google-drive"]
+    },
+    "mcp": {
+      "enabled": true,
+      "servers": [
+        {
+          "name": "filesystem",
+          "path": "/usr/local/bin/mcp-server-filesystem"
+        },
+        {
+          "name": "git",
+          "path": "/usr/local/bin/mcp-server-git"
+        }
+      ]
+    },
+    "webhooks": {
+      "enabled": true,
+      "port": 3001,
+      "secret": "your-webhook-secret"
+    }
+  }
+}
+```
+
+## See Also
+
+- [API Reference](API_REFERENCE.md) - Core API documentation
+- [Expert Feature Guide](FEATURES_EXPERT.md) - Advanced features
+- [Plugin Development](PLUGIN_DEVELOPMENT.md) - Create custom plugins
+- [Deployment Guide](DEPLOYMENT.md) - Deployment options
+
+---
+
+**Questions?** Open an issue on [GitHub](https://github.com/afkutrotzdemda/Project-Aura/issues)
diff --git a/docs/SETUP.md b/docs/SETUP.md
new file mode 100644
index 0000000..a00c15c
--- /dev/null
+++ b/docs/SETUP.md
@@ -0,0 +1,429 @@
+# Setup Guide
+
+Complete installation and configuration guide for Project-Aura.
+
+## Table of Contents
+
+- [System Requirements](#system-requirements)
+- [Installation Methods](#installation-methods)
+- [Configuration](#configuration)
+- [API Key Setup](#api-key-setup)
+- [Plugin Configuration](#plugin-configuration)
+- [Troubleshooting Setup](#troubleshooting-setup)
+
+## System Requirements
+
+### Minimum Requirements
+- **OS**: Windows 10/11, macOS 10.15+, or Linux (Ubuntu 20.04+)
+- **RAM**: 4GB
+- **Storage**: 500MB free space
+- **Node.js**: 18.x or higher (for development)
+- **Internet**: Required for LLM API calls
+
+### Recommended Requirements
+- **RAM**: 8GB or more
+- **Storage**: 2GB free space (for chat history and caching)
+- **Display**: 1920x1080 or higher resolution
+
+## Installation Methods
+
+### Method 1: Pre-built Binaries (Recommended for End Users)
+
+**Coming Soon**: Download pre-built binaries from the [Releases](https://github.com/afkutrotzdemda/Project-Aura/releases) page.
+
+1. Download the appropriate installer for your platform:
+   - Windows: `Project-Aura-Setup-x.x.x.exe`
+   - macOS: `Project-Aura-x.x.x.dmg`
+   - Linux: `Project-Aura-x.x.x.AppImage`
+
+2. Run the installer and follow the on-screen instructions
+
+3. Launch Project-Aura from your applications menu
+
+### Method 2: From Source (For Developers)
+
+#### Step 1: Install Prerequisites
+
+**Node.js and npm**:
+```bash
+# Check if Node.js is installed
+node --version  # Should be 18.x or higher
+npm --version
+
+# If not installed, download from https://nodejs.org/
+```
+
+**Git**:
+```bash
+# Check if Git is installed
+git --version
+
+# If not installed, download from https://git-scm.com/
+```
+
+#### Step 2: Clone the Repository
+
+```bash
+# Clone the repository
+git clone https://github.com/afkutrotzdemda/Project-Aura.git
+
+# Navigate to the project directory
+cd Project-Aura
+```
+
+#### Step 3: Install Dependencies
+
+```bash
+# Install npm packages
+npm install
+
+# This will install:
+# - React and related packages
+# - Electron framework
+# - TypeScript and build tools
+# - LLM provider SDKs
+# - All other dependencies
+```
+
+#### Step 4: Set Up Environment (Optional)
+
+Create a `.env` file in the root directory for default configuration:
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit with your preferred settings
+nano .env  # or use your preferred editor
+```
+
+Example `.env` file:
+```env
+# Default LLM Provider (optional)
+DEFAULT_PROVIDER=gemini
+DEFAULT_MODEL=gemini-2.0-flash-exp
+
+# Development Settings
+NODE_ENV=development
+ELECTRON_DEV_MODE=true
+
+# Feature Flags (optional)
+ENABLE_AGENT_MODE=true
+ENABLE_EXPERIMENTAL_FEATURES=false
+```
+
+#### Step 5: Start Development Server
+
+```bash
+# Start the webpack dev server
+npm run dev
+
+# The application will launch automatically
+# Hot reload is enabled for development
+```
+
+### Method 3: Docker (Coming Soon)
+
+```bash
+# Pull the Docker image
+docker pull projectaura/project-aura:latest
+
+# Run the container
+docker run -p 3000:3000 -v ~/.project-aura:/data projectaura/project-aura:latest
+```
+
+## Configuration
+
+### First-Time Setup Wizard
+
+When you first launch Project-Aura, you'll be guided through initial setup:
+
+1. **Welcome Screen**: Overview of features
+2. **Provider Selection**: Choose your preferred LLM provider
+3. **API Key Entry**: Enter your API key(s)
+4. **Agent Mode**: Choose to enable advanced capabilities
+5. **Plugin Selection**: Select which plugins to enable
+6. **Privacy Settings**: Configure data storage preferences
+
+### Manual Configuration
+
+#### Application Settings
+
+Settings are stored in:
+- **Windows**: `%APPDATA%\Project-Aura\config.json`
+- **macOS**: `~/Library/Application Support/Project-Aura/config.json`
+- **Linux**: `~/.config/Project-Aura/config.json`
+
+Example `config.json`:
+```json
+{
+  "version": "1.0.0",
+  "settings": {
+    "theme": "dark",
+    "defaultProvider": "gemini",
+    "defaultModel": "gemini-2.0-flash-exp",
+    "agentMode": false,
+    "streamingEnabled": true,
+    "autoSave": true,
+    "maxChatHistory": 100
+  },
+  "plugins": {
+    "system-plugin": true,
+    "file-manager-plugin": false,
+    "web-browser-plugin": false,
+    "process-management-plugin": false,
+    "network-plugin": false,
+    "code-execution-plugin": false,
+    "email-plugin": false,
+    "calendar-plugin": false
+  }
+}
+```
+
+## API Key Setup
+
+### Obtaining API Keys
+
+#### Google Gemini
+1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
+2. Sign in with your Google account
+3. Click "Create API Key"
+4. Copy the API key (starts with `AIza...`)
+5. **Pricing**: Free tier available with generous limits
+
+#### OpenAI
+1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
+2. Sign in or create an account
+3. Navigate to "API Keys" section
+4. Click "Create new secret key"
+5. Copy the key (starts with `sk-...`)
+6. **Pricing**: Pay-as-you-go, credit card required
+
+#### Anthropic Claude
+1. Visit [Anthropic Console](https://console.anthropic.com/)
+2. Sign in or create an account
+3. Navigate to "API Keys"
+4. Click "Create Key"
+5. Copy the key (starts with `sk-ant-...`)
+6. **Pricing**: Pay-as-you-go with free trial credits
+
+#### Mistral AI
+1. Visit [Mistral Platform](https://console.mistral.ai/)
+2. Sign in or create an account
+3. Go to "API Keys" section
+4. Generate a new key
+5. Copy the API key
+6. **Pricing**: Various tiers available
+
+### Adding API Keys to Project-Aura
+
+#### Method 1: Through UI (Recommended)
+1. Launch Project-Aura
+2. Click the settings/gear icon in the header
+3. Select your LLM provider from the dropdown
+4. Paste your API key in the "API Key" field
+5. The key is automatically encrypted and stored locally
+
+#### Method 2: Configuration File
+Edit the secure storage file directly (advanced users):
+
+**Location**:
+- **Windows**: `%APPDATA%\Project-Aura\secure-storage.encrypted`
+- **macOS**: `~/Library/Application Support/Project-Aura/secure-storage.encrypted`
+- **Linux**: `~/.config/Project-Aura/secure-storage.encrypted`
+
+**Note**: API keys are encrypted at rest using system keychain integration.
+
+### API Key Security
+
+- Keys are encrypted using OS-level security features
+- Never shared or transmitted (except to official provider APIs)
+- Can be revoked/rotated at any time through provider console
+- Recommend using environment-specific keys for development
+
+## Plugin Configuration
+
+### Enabling/Disabling Plugins
+
+#### Through UI
+1. Open Settings → Plugins
+2. Toggle individual plugins on/off
+3. Some plugins may require additional permissions
+4. Restart may be required for changes to take effect
+
+#### Through Configuration File
+
+Edit `config.json` and modify the `plugins` section:
+
+```json
+{
+  "plugins": {
+    "system-plugin": true,        // Basic system info - always enabled
+    "file-manager-plugin": true,   // File operations - requires filesystem access
+    "web-browser-plugin": false,   // Web automation - requires network access
+    "code-execution-plugin": false // Code execution - SECURITY RISK
+  }
+}
+```
+
+### Plugin-Specific Configuration
+
+#### File Manager Plugin
+```json
+{
+  "fileManagerPlugin": {
+    "allowedDirectories": [
+      "~/Documents",
+      "~/Downloads"
+    ],
+    "maxFileSize": "10MB",
+    "allowedExtensions": [".txt", ".md", ".json"]
+  }
+}
+```
+
+#### Web Browser Plugin
+```json
+{
+  "webBrowserPlugin": {
+    "userAgent": "Project-Aura/1.0",
+    "timeout": 30000,
+    "enableJavaScript": true,
+    "maxRedirects": 5
+  }
+}
+```
+
+#### Code Execution Plugin
+```json
+{
+  "codeExecutionPlugin": {
+    "enabled": false,
+    "sandboxed": true,
+    "allowedLanguages": ["python", "javascript"],
+    "timeout": 10000,
+    "maxMemory": "512MB"
+  }
+}
+```
+
+#### Email Plugin
+```json
+{
+  "emailPlugin": {
+    "provider": "smtp",
+    "smtp": {
+      "host": "smtp.gmail.com",
+      "port": 587,
+      "secure": false,
+      "auth": {
+        "user": "your-email@gmail.com",
+        "pass": "your-app-password"
+      }
+    }
+  }
+}
+```
+
+#### Calendar Plugin
+```json
+{
+  "calendarPlugin": {
+    "provider": "google",
+    "calendarId": "primary",
+    "timezone": "America/New_York"
+  }
+}
+```
+
+## Troubleshooting Setup
+
+### Common Installation Issues
+
+#### Issue: `npm install` fails with permission errors
+
+**Solution (Linux/macOS)**:
+```bash
+# Use npx to avoid global installation issues
+npx npm install
+
+# Or fix npm permissions
+sudo chown -R $(whoami) ~/.npm
+```
+
+**Solution (Windows)**:
+```bash
+# Run as Administrator or use:
+npm install --no-optional
+```
+
+#### Issue: Application won't start
+
+**Check Node.js version**:
+```bash
+node --version  # Must be 18.x or higher
+```
+
+**Clear cache and reinstall**:
+```bash
+rm -rf node_modules package-lock.json
+npm cache clean --force
+npm install
+```
+
+#### Issue: API key not working
+
+**Verify key format**:
+- Gemini: Should start with `AIza`
+- OpenAI: Should start with `sk-`
+- Claude: Should start with `sk-ant-`
+- Mistral: Check provider documentation
+
+**Check API key permissions**:
+- Ensure key has appropriate permissions in provider console
+- Verify no IP restrictions or rate limits
+
+**Test API key manually**:
+```bash
+# For Gemini
+curl -H "Content-Type: application/json" \
+     -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' \
+     "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=YOUR_API_KEY"
+```
+
+#### Issue: Plugins not loading
+
+**Check plugin requirements**:
+- Ensure Agent Mode is enabled
+- Verify plugin permissions in OS settings
+- Check console for error messages
+
+**Reset plugin configuration**:
+```bash
+# Delete plugin config
+rm ~/.config/Project-Aura/plugins.json
+
+# Restart application
+```
+
+### Getting Help
+
+If you continue to experience issues:
+
+1. Check the [Troubleshooting Guide](TROUBLESHOOTING.md)
+2. Search [GitHub Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+3. Join our [Discord Community](https://discord.gg/project-aura)
+4. Create a new issue with detailed information
+
+## Next Steps
+
+Now that you have Project-Aura installed and configured:
+
+1. Read the [Beginner's Feature Guide](FEATURES_BEGINNER.md) to get started
+2. Explore [Architecture Documentation](ARCHITECTURE.md) to understand the system
+3. Check out [Deployment Options](DEPLOYMENT.md) for production use
+4. Review [Security Best Practices](SECURITY.md)
+
+---
+
+**Need help?** Visit our [Support Page](https://github.com/afkutrotzdemda/Project-Aura/discussions) or open an issue.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 0000000..3b218f3
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,843 @@
+# Troubleshooting Guide
+
+Solutions to common issues and problems with Project-Aura.
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [API Key Problems](#api-key-problems)
+- [Connection Issues](#connection-issues)
+- [Plugin Issues](#plugin-issues)
+- [Performance Problems](#performance-problems)
+- [Error Messages](#error-messages)
+- [Data and Storage](#data-and-storage)
+- [Platform-Specific Issues](#platform-specific-issues)
+- [Getting Help](#getting-help)
+
+## Installation Issues
+
+### npm install fails
+
+**Symptom**: Errors during `npm install`
+
+**Solutions**:
+
+1. **Clear npm cache**:
+```bash
+npm cache clean --force
+rm -rf node_modules package-lock.json
+npm install
+```
+
+2. **Check Node.js version**:
+```bash
+node --version  # Should be 18.x or higher
+```
+
+If outdated:
+```bash
+# Using nvm
+nvm install 18
+nvm use 18
+
+# Or download from https://nodejs.org/
+```
+
+3. **Permission errors (Linux/Mac)**:
+```bash
+sudo chown -R $(whoami) ~/.npm
+sudo chown -R $(whoami) node_modules
+```
+
+4. **Python dependency errors**:
+```bash
+# Install Python build tools
+# Ubuntu/Debian
+sudo apt-get install python3 build-essential
+
+# macOS
+xcode-select --install
+
+# Windows
+npm install --global windows-build-tools
+```
+
+### Application won't start
+
+**Symptom**: Application crashes on launch or shows blank screen
+
+**Solutions**:
+
+1. **Check console for errors**:
+```bash
+# Run with debug output
+DEBUG=* npm start
+```
+
+2. **Verify build completed**:
+```bash
+npm run build
+ls -la dist/  # Should contain built files
+```
+
+3. **Reset configuration**:
+```bash
+# Backup first
+cp ~/.config/Project-Aura/config.json ~/config-backup.json
+
+# Remove config
+rm -rf ~/.config/Project-Aura/
+
+# Restart application
+```
+
+4. **Clear Electron cache**:
+```bash
+# macOS
+rm -rf ~/Library/Application\ Support/Project-Aura/
+
+# Linux
+rm -rf ~/.config/Project-Aura/
+
+# Windows
+rd /s /q %APPDATA%\Project-Aura
+```
+
+### Webpack build errors
+
+**Symptom**: Build fails with webpack errors
+
+**Solutions**:
+
+1. **Update dependencies**:
+```bash
+npm update
+```
+
+2. **Check TypeScript errors**:
+```bash
+npx tsc --noEmit
+```
+
+3. **Verify webpack config**:
+```bash
+npx webpack --config webpack.config.js
+```
+
+4. **Clear webpack cache**:
+```bash
+rm -rf node_modules/.cache
+```
+
+## API Key Problems
+
+### "Invalid API Key" error
+
+**Symptom**: Error message when sending first message
+
+**Solutions**:
+
+1. **Verify key format**:
+   - **Gemini**: Should start with `AIza`
+   - **OpenAI**: Should start with `sk-`
+   - **Claude**: Should start with `sk-ant-`
+   - **Mistral**: Check provider documentation
+
+2. **Check for extra spaces**:
+```javascript
+// In browser console
+const key = "your-api-key";
+console.log(key.length);  // Should match expected length
+console.log(key.trim() === key);  // Should be true
+```
+
+3. **Verify key is active**:
+   - Visit provider console
+   - Check API key status
+   - Regenerate if necessary
+
+4. **Test key manually**:
+
+**Gemini**:
+```bash
+curl -H "Content-Type: application/json" \
+     -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' \
+     "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=YOUR_KEY"
+```
+
+**OpenAI**:
+```bash
+curl https://api.openai.com/v1/models \
+     -H "Authorization: Bearer YOUR_KEY"
+```
+
+**Claude**:
+```bash
+curl https://api.anthropic.com/v1/messages \
+     -H "x-api-key: YOUR_KEY" \
+     -H "anthropic-version: 2023-06-01" \
+     -H "content-type: application/json" \
+     -d '{"model":"claude-3-opus-20240229","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+### API key not persisting
+
+**Symptom**: Need to re-enter API key after restart
+
+**Solutions**:
+
+1. **Check storage permissions**:
+```bash
+# Verify config directory exists
+ls -la ~/.config/Project-Aura/
+
+# Fix permissions
+chmod 700 ~/.config/Project-Aura/
+chmod 600 ~/.config/Project-Aura/secure-storage.encrypted
+```
+
+2. **Verify storage service**:
+```javascript
+// In console
+localStorage.setItem('test', 'value');
+console.log(localStorage.getItem('test'));  // Should output 'value'
+```
+
+3. **Check for errors in console**:
+   - Open DevTools (Ctrl+Shift+I / Cmd+Option+I)
+   - Look for storage-related errors
+   - Check Application → Local Storage
+
+### "Quota Exceeded" error
+
+**Symptom**: Error after several requests
+
+**Solutions**:
+
+1. **Check usage in provider console**:
+   - Review current usage
+   - Check quota limits
+   - Add billing information if needed
+
+2. **Wait for quota reset**:
+   - Free tiers often have daily/monthly limits
+   - Check provider documentation for reset times
+
+3. **Switch to different model**:
+   - Use a model with higher quota
+   - Or switch to a different provider
+
+4. **Optimize requests**:
+   - Use shorter messages
+   - Disable streaming if not needed
+   - Clear conversation history more frequently
+
+## Connection Issues
+
+### "Failed to connect to API" error
+
+**Symptom**: Network connection errors
+
+**Solutions**:
+
+1. **Check internet connection**:
+```bash
+ping google.com
+ping api.openai.com
+```
+
+2. **Verify firewall settings**:
+   - Allow outbound HTTPS (port 443)
+   - Check corporate proxy settings
+
+3. **Test API endpoints**:
+```bash
+# Gemini
+curl https://generativelanguage.googleapis.com
+
+# OpenAI
+curl https://api.openai.com
+
+# Claude
+curl https://api.anthropic.com
+```
+
+4. **Configure proxy (if needed)**:
+```bash
+# Set environment variables
+export HTTP_PROXY=http://proxy.example.com:8080
+export HTTPS_PROXY=http://proxy.example.com:8080
+
+# Or in code
+npm config set proxy http://proxy.example.com:8080
+npm config set https-proxy http://proxy.example.com:8080
+```
+
+### Slow response times
+
+**Symptom**: Very slow AI responses
+
+**Solutions**:
+
+1. **Switch to faster model**:
+   - Gemini 2.0 Flash
+   - GPT-3.5 Turbo
+   - Mistral Small
+
+2. **Enable streaming**:
+   - Already enabled by default
+   - Check that it's working in settings
+
+3. **Check network speed**:
+```bash
+# Test connection speed
+speedtest-cli
+# or visit https://fast.com
+```
+
+4. **Reduce message length**:
+   - Shorter prompts = faster responses
+   - Clear old conversation context
+
+### Timeout errors
+
+**Symptom**: "Request timeout" errors
+
+**Solutions**:
+
+1. **Increase timeout in config**:
+```json
+{
+  "advanced": {
+    "requestTimeout": 120000  // 2 minutes
+  }
+}
+```
+
+2. **Check for large context**:
+   - Long conversation histories cause slow responses
+   - Start new chat to clear context
+
+3. **Provider-specific issues**:
+   - Check provider status page
+   - Try different provider temporarily
+
+## Plugin Issues
+
+### Plugins not loading
+
+**Symptom**: Agent mode enabled but functions not available
+
+**Solutions**:
+
+1. **Verify Agent Mode is enabled**:
+   - Check toggle in header
+   - Confirm in settings
+
+2. **Check plugin configuration**:
+```json
+{
+  "plugins": {
+    "system-plugin": true,  // Should be true
+    "file-manager-plugin": false
+  }
+}
+```
+
+3. **Restart application**:
+   - Some plugins require restart to activate
+
+4. **Check console for errors**:
+```bash
+# Look for plugin loading errors
+grep -i "plugin" ~/.config/Project-Aura/logs/app.log
+```
+
+5. **Verify plugin files exist**:
+```bash
+ls -la src/renderer/plugins/
+# Should see all plugin files
+```
+
+### Function calls failing
+
+**Symptom**: Plugin functions called but return errors
+
+**Solutions**:
+
+1. **Check function permissions**:
+   - File Manager needs filesystem access
+   - Process Manager needs elevated permissions
+
+2. **Verify function parameters**:
+```javascript
+// Example debugging
+console.log('Function called:', functionName);
+console.log('Arguments:', JSON.stringify(args));
+```
+
+3. **Check plugin-specific configuration**:
+```json
+{
+  "fileManagerPlugin": {
+    "allowedDirectories": [
+      "~/Documents"  // Add your directories
+    ]
+  }
+}
+```
+
+4. **Enable debug logging**:
+```json
+{
+  "advanced": {
+    "enableDebug": true,
+    "logLevel": "debug"
+  }
+}
+```
+
+### Code Execution Plugin unsafe
+
+**Symptom**: Security warnings about code execution
+
+**Solution**: This is expected behavior
+
+**Recommendations**:
+1. Keep plugin disabled unless absolutely needed
+2. Only enable in sandboxed environment
+3. Never execute untrusted code
+4. Use Docker container for isolation
+
+```json
+{
+  "codeExecutionPlugin": {
+    "enabled": false,  // Keep disabled
+    "sandboxed": true,  // If you must enable
+    "allowedLanguages": ["python"],  // Restrict languages
+    "networkAccess": false,
+    "filesystemAccess": false
+  }
+}
+```
+
+## Performance Problems
+
+### High memory usage
+
+**Symptom**: Application using excessive RAM
+
+**Solutions**:
+
+1. **Limit chat history**:
+```json
+{
+  "settings": {
+    "maxChatHistory": 50,  // Reduce from 100
+    "messageRetention": 7   // Keep only 7 days
+  }
+}
+```
+
+2. **Clear old chats**:
+```bash
+# Archive old chats
+find ~/.config/Project-Aura/chats -mtime +30 -exec gzip {} \;
+
+# Or delete
+find ~/.config/Project-Aura/chats -mtime +30 -delete
+```
+
+3. **Restart application regularly**:
+   - Memory leaks may accumulate
+   - Restart daily if using heavily
+
+4. **Check for memory leaks**:
+```bash
+# Monitor memory
+# macOS/Linux
+top -pid $(pgrep -f "Project-Aura")
+
+# Or use Activity Monitor / System Monitor
+```
+
+### Slow UI/Laggy interface
+
+**Symptom**: Interface sluggish or unresponsive
+
+**Solutions**:
+
+1. **Reduce animations**:
+```css
+/* In user CSS */
+* {
+  animation: none !important;
+  transition: none !important;
+}
+```
+
+2. **Clear rendering cache**:
+```bash
+rm -rf ~/.config/Project-Aura/Cache/
+```
+
+3. **Disable hardware acceleration** (if issues persist):
+   - Add to electron launch flags
+   - `--disable-gpu`
+
+4. **Check CPU usage**:
+   - Close other applications
+   - Disable unnecessary plugins
+
+### Database/storage issues
+
+**Symptom**: Slow loading, corrupted data
+
+**Solutions**:
+
+1. **Check storage space**:
+```bash
+df -h
+# Ensure adequate free space
+```
+
+2. **Repair storage**:
+```bash
+# Backup first
+cp -r ~/.config/Project-Aura ~/Project-Aura-backup
+
+# Remove corrupted files
+find ~/.config/Project-Aura -size 0 -delete
+```
+
+3. **Rebuild chat index**:
+```bash
+# Delete index cache
+rm ~/.config/Project-Aura/chat-index.json
+
+# Restart application to rebuild
+```
+
+## Error Messages
+
+### "Safety filters blocked response"
+
+**Symptom**: AI refuses to respond to certain prompts
+
+**Solutions**:
+
+1. **Rephrase your question**:
+   - Use more neutral language
+   - Break down into smaller questions
+
+2. **Switch providers**:
+   - Different providers have different safety policies
+   - Try alternative model
+
+3. **Check content policy**:
+   - Review provider's content policy
+   - Ensure request is compliant
+
+### "Context length exceeded"
+
+**Symptom**: Error about too much context
+
+**Solutions**:
+
+1. **Start new chat**:
+   - Clear conversation history
+   - Reduces context size
+
+2. **Summarize conversation**:
+   - Ask AI to summarize discussion so far
+   - Copy summary and start new chat
+
+3. **Use models with larger context**:
+   - Gemini 1.5 Pro: 2M tokens
+   - Claude 3: 200K tokens
+   - GPT-4 Turbo: 128K tokens
+
+### "Rate limit exceeded"
+
+**Symptom**: Too many requests error
+
+**Solutions**:
+
+1. **Wait before retrying**:
+   - Rate limits typically reset within minutes
+   - Check provider documentation
+
+2. **Reduce request frequency**:
+   - Don't spam send button
+   - Wait for responses to complete
+
+3. **Upgrade API plan**:
+   - Free tiers have strict limits
+   - Paid plans offer higher limits
+
+4. **Use different API key**:
+   - Rotate between multiple keys
+   - Or switch provider temporarily
+
+## Data and Storage
+
+### Chat history disappeared
+
+**Symptom**: Previous conversations missing
+
+**Solutions**:
+
+1. **Check data location**:
+```bash
+# List all chats
+ls -la ~/.config/Project-Aura/chats/
+
+# Check if recently accessed
+ls -ltu ~/.config/Project-Aura/chats/
+```
+
+2. **Restore from backup**:
+```bash
+# If you have backups
+cp ~/backup/Project-Aura/chats/* ~/.config/Project-Aura/chats/
+```
+
+3. **Check for corruption**:
+```bash
+# Verify JSON files
+for file in ~/.config/Project-Aura/chats/*.json; do
+  echo "Checking $file"
+  jq empty "$file" || echo "CORRUPT: $file"
+done
+```
+
+4. **Recovery tools**:
+```bash
+# macOS Time Machine
+tmutil listbackups
+
+# Linux
+extundelete /dev/sdX --restore-all
+```
+
+### Export/Import not working
+
+**Symptom**: Cannot export or import chats
+
+**Solutions**:
+
+1. **Manual export**:
+```bash
+# Create backup
+tar -czf chats-backup.tar.gz ~/.config/Project-Aura/chats/
+
+# Or copy individual chat
+cp ~/.config/Project-Aura/chats/1234567890.json ~/Desktop/
+```
+
+2. **Manual import**:
+```bash
+# Extract backup
+tar -xzf chats-backup.tar.gz -C ~/.config/Project-Aura/
+
+# Or copy chat file
+cp ~/Desktop/chat.json ~/.config/Project-Aura/chats/
+
+# Restart application
+```
+
+3. **Fix permissions**:
+```bash
+chmod 644 ~/.config/Project-Aura/chats/*.json
+```
+
+### Settings not saving
+
+**Symptom**: Configuration changes don't persist
+
+**Solutions**:
+
+1. **Check config file**:
+```bash
+# Verify it exists and is writable
+ls -la ~/.config/Project-Aura/config.json
+
+# Fix permissions
+chmod 644 ~/.config/Project-Aura/config.json
+```
+
+2. **Verify JSON is valid**:
+```bash
+jq empty ~/.config/Project-Aura/config.json
+# No output = valid JSON
+# Error = fix syntax
+```
+
+3. **Reset to defaults**:
+```bash
+mv ~/.config/Project-Aura/config.json ~/.config/Project-Aura/config.json.bak
+# Restart application to generate new config
+```
+
+## Platform-Specific Issues
+
+### macOS Issues
+
+**App won't open - "Damaged or incomplete"**:
+```bash
+# Remove quarantine attribute
+xattr -dr com.apple.quarantine /Applications/Project-Aura.app
+```
+
+**Permission prompts repeatedly**:
+```bash
+# Reset permissions
+tccutil reset All com.projectaura.app
+```
+
+### Linux Issues
+
+**Missing dependencies**:
+```bash
+# Ubuntu/Debian
+sudo apt install libgtk-3-0 libnotify4 libnss3 libxss1 \
+                 libxtst6 xdg-utils libatspi2.0-0 libuuid1 \
+                 libsecret-1-0
+
+# Fedora
+sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst \
+                 xdg-utils at-spi2-core libuuid libsecret
+```
+
+**AppImage won't run**:
+```bash
+# Make executable
+chmod +x Project-Aura*.AppImage
+
+# Run with --no-sandbox if needed
+./Project-Aura*.AppImage --no-sandbox
+```
+
+### Windows Issues
+
+**SmartScreen warning**:
+- Click "More info"
+- Click "Run anyway"
+- Or sign application with code signing certificate
+
+**Antivirus blocking**:
+- Add exception for Project-Aura
+- Or temporarily disable to test
+
+**Electron app slow on Windows**:
+```bash
+# Disable Windows Defender real-time scanning for app folder
+# Or add exclusion in Windows Security
+```
+
+## Getting Help
+
+### Before Asking for Help
+
+1. **Check existing issues**:
+   - [GitHub Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+   - Search for similar problems
+
+2. **Gather information**:
+```bash
+# System info
+node --version
+npm --version
+cat /etc/os-release  # Linux
+sw_vers  # macOS
+systeminfo  # Windows
+
+# Application version
+grep version package.json
+
+# Recent logs
+tail -n 100 ~/.config/Project-Aura/logs/app.log
+```
+
+3. **Try minimal reproduction**:
+   - Disable all plugins
+   - Clear configuration
+   - Test with fresh install
+
+### Reporting Issues
+
+**Include in bug reports**:
+1. Operating system and version
+2. Node.js and npm versions
+3. Project-Aura version
+4. Steps to reproduce
+5. Expected vs actual behavior
+6. Error messages and logs
+7. Screenshots if applicable
+
+**Template**:
+```markdown
+**Environment**:
+- OS: Ubuntu 22.04
+- Node: 18.16.0
+- Project-Aura: 1.0.0
+
+**Steps to reproduce**:
+1. Enable Agent Mode
+2. Load File Manager Plugin
+3. Try to read file
+
+**Expected**: File contents displayed
+**Actual**: Error "Permission denied"
+
+**Logs**:
+```
+[Error logs here]
+```
+
+**Screenshots**: [attached]
+```
+
+### Getting Support
+
+- **GitHub Issues**: [Project-Aura Issues](https://github.com/afkutrotzdemda/Project-Aura/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/afkutrotzdemda/Project-Aura/discussions)
+- **Discord**: [Project-Aura Discord](https://discord.gg/project-aura) (placeholder)
+- **Email**: support@project-aura.dev (placeholder)
+
+### Useful Diagnostic Commands
+
+```bash
+# Check process
+ps aux | grep -i "project-aura"
+
+# Network connectivity
+netstat -an | grep ESTABLISHED
+
+# Disk usage
+du -sh ~/.config/Project-Aura
+
+# File permissions
+ls -laR ~/.config/Project-Aura
+
+# Check logs in real-time
+tail -f ~/.config/Project-Aura/logs/app.log
+
+# Test API connectivity
+curl -I https://api.openai.com
+curl -I https://generativelanguage.googleapis.com
+
+# System resources
+top -bn1 | grep project-aura
+```
+
+## See Also
+
+- [Setup Guide](SETUP.md) - Installation and configuration
+- [FAQ](FAQ.md) - Frequently asked questions
+- [API Reference](API_REFERENCE.md) - Technical documentation
+- [Expert Guide](FEATURES_EXPERT.md) - Advanced features
+
+---
+
+**Still having issues?** Open an issue on [GitHub](https://github.com/afkutrotzdemda/Project-Aura/issues) with details.
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..55fb0b6
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1,136 @@
+# Documentation Images
+
+This directory contains images and diagrams for the Project-Aura documentation.
+
+## Placeholders
+
+The following images are currently placeholders and should be replaced with actual screenshots and diagrams:
+
+### Main Documentation
+- `banner-placeholder.png` - Main project banner for README
+- `main-interface-placeholder.png` - Screenshot of main application interface
+- `chat-interface-placeholder.png` - Chat interface screenshot
+- `settings-panel-placeholder.png` - Settings panel screenshot
+- `agent-mode-placeholder.png` - Agent mode in action
+
+### Setup Guide
+- `api-key-setup-placeholder.png` - API key configuration screenshot
+- `first-run-placeholder.png` - First run setup wizard
+- `model-selection-placeholder.png` - Model selection dropdown
+
+### Architecture
+- `architecture-diagram-placeholder.svg` - System architecture diagram
+- `plugin-flow-placeholder.svg` - Plugin execution flow diagram
+- `data-flow-placeholder.svg` - Data flow diagram
+- `component-hierarchy-placeholder.svg` - React component hierarchy
+
+### Feature Guides
+- `chat-management-placeholder.png` - Chat sidebar and management
+- `streaming-response-placeholder.png` - Streaming response in action
+- `plugin-configuration-placeholder.png` - Plugin settings panel
+
+### Deployment
+- `railway-deploy-placeholder.png` - Railway deployment dashboard
+- `render-config-placeholder.png` - Render configuration
+- `docker-deployment-placeholder.png` - Docker container running
+
+## Creating Images
+
+### Screenshots
+
+**For Desktop App**:
+1. Launch Project-Aura
+2. Use built-in screenshot tool or:
+   - macOS: `Cmd + Shift + 4`
+   - Windows: `Win + Shift + S`
+   - Linux: `gnome-screenshot` or similar
+3. Crop and optimize
+4. Save as PNG in this directory
+
+**Recommended Dimensions**:
+- Full interface: 1920x1080
+- Panel/component: 800x600
+- Icon/small: 256x256
+
+### Diagrams
+
+**Tools**:
+- [diagrams.net](https://app.diagrams.net/) (free, web-based)
+- [Excalidraw](https://excalidraw.com/) (hand-drawn style)
+- [Mermaid](https://mermaid.js.org/) (text-to-diagram)
+- [PlantUML](https://plantuml.com/) (UML diagrams)
+
+**Example Mermaid Diagram** (can be embedded in Markdown):
+
+```mermaid
+graph TD
+    A[User Input] --> B[App Component]
+    B --> C[LLM Service]
+    C --> D{Agent Mode?}
+    D -->|Yes| E[Function Service]
+    D -->|No| F[Direct API Call]
+    E --> G[Plugin Execution]
+    G --> H[Return Result]
+    F --> H
+    H --> I[Display Response]
+```
+
+**Export as**:
+- SVG (preferred for diagrams - scalable)
+- PNG (for screenshots - use high DPI)
+
+### Image Optimization
+
+**Before committing**:
+```bash
+# Install optimization tools
+npm install -g imageoptim-cli
+
+# Optimize PNGs
+imageoptim --quality 80-100 *.png
+
+# Or use online tools
+# - TinyPNG (https://tinypng.com/)
+# - Squoosh (https://squoosh.app/)
+```
+
+### File Naming Convention
+
+- Use lowercase with hyphens
+- Be descriptive: `plugin-architecture-diagram.svg`
+- Include size suffix if multiple versions: `banner-1920x400.png`
+- Use appropriate extension:
+  - `.png` for screenshots, photos
+  - `.svg` for diagrams, icons
+  - `.jpg` for photos (if appropriate)
+  - `.gif` for animations (use sparingly)
+
+## Attribution
+
+If using third-party images:
+1. Ensure proper licensing (Creative Commons, etc.)
+2. Add attribution in this file
+3. Include license information
+
+Example:
+```markdown
+### Third-Party Assets
+- `icon-source.svg` - [Source Name](https://example.com) - CC BY 4.0
+```
+
+## Accessibility
+
+When adding images to documentation:
+1. Always include alt text
+2. Describe what the image shows
+3. Consider color-blind users in diagrams
+4. Use high contrast
+
+Example:
+```markdown
+![Main Interface showing chat window with message history and input field](images/main-interface.png)
+```
+
+---
+
+**Need help?** Open an issue or discussion on GitHub.