soma-core 2.0.0

# Installation

SOMA-CORE is distributed as a Rust crate and can be installed in several ways depending on your needs.

## 📦 Requirements

- **Rust**: Version 1.70 or higher
- **Operating System**: Linux, macOS, or Windows
- **Memory**: Minimum 2GB RAM (4GB recommended for cognitive operations)
- **Storage**: 500MB for full installation with examples

## 🚀 Quick Installation

### As a Library (Recommended)

Add SOMA-CORE to your Rust project:

```bash
cargo add soma-core
```

Or manually add to your `Cargo.toml`:

```toml
[dependencies]
soma-core = "2.0"
```

### Global Installation

Install the CLI tool globally:

```bash
cargo install soma-core
```

### From Source

For development or the latest features:

```bash
git clone https://github.com/soma-core/soma-core.git
cd soma-core
cargo build --release
```

## 🔧 Configuration

SOMA-CORE can be configured through environment variables or configuration files.

### Environment Variables

Create a `.env` file in your project root:

```env
# Optional: Enable detailed logging
SOMA_LOG_LEVEL=info

# Optional: Configure cognitive load limits
SOMA_MAX_COGNITIVE_LOAD=0.8

# Optional: Set custom agent personalities
SOMA_DEFAULT_AGENT_STYLE=balanced
```

### Configuration File

Create `soma.toml` in your project root:

```toml
[cognitive]
max_load = 0.8
enable_meta_reflection = true
agent_memory_size = 1024

[performance]
response_timeout = 5000  # milliseconds
parallel_operations = 4

[security]
enable_file_protection = true
audit_logging = true
```

## ✅ Verification

Verify your installation:

```bash
# Check version
soma-core --version

# Run system diagnostics
soma-core --check

# Quick demo
soma-core --demo introspect
```

Expected output:
```
SOMA-CORE v2.0.0
✅ Cognitive operators: 15 loaded
✅ Meta-reflection: enabled
✅ Multi-agent: ready
✅ Performance: optimal
```

## 🎯 IDE Integration

### VS Code

Install the SOMA-CORE extension:

```bash
code --install-extension soma-core.vscode-soma
```

### IntelliJ/CLion

Download the plugin from the JetBrains marketplace or build from source:

```bash
git clone https://github.com/soma-core/intellij-plugin.git
```

## 🚨 Troubleshooting

### Common Issues

**Compilation Error: "missing cognitive operators"**
```bash
# Ensure you have the complete installation
cargo install soma-core --features "full"
```

**Runtime Error: "insufficient cognitive capacity"**
```bash
# Increase memory allocation
export SOMA_MEMORY_LIMIT=4G
```

**Permission Error: "cannot access cognitive state"**
```bash
# Check file permissions for configuration
chmod 644 soma.toml
```

### Platform-Specific Notes

#### macOS
```bash
# May need to allow binary execution
sudo spctl --add /usr/local/bin/soma-core
```

#### Windows
```powershell
# Enable developer mode for full functionality
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

#### Linux
```bash
# Install additional dependencies for visual reasoning
sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev
```

## 🔄 Updates

Keep SOMA-CORE updated:

```bash
# Update library dependency
cargo update soma-core

# Update global installation
cargo install --force soma-core

# Check for updates
soma-core --check-updates
```

## 📚 Next Steps

Once installed, continue with:

- **[Quick Start](./quick-start.md)** - Get running in 5 minutes
- **[First Steps](./first-steps.md)** - Basic cognitive operations
- **[Examples](./examples.md)** - Working code samples

## 🆘 Need Help?

- **[FAQ](../community/faq.md)** - Common questions and answers
- **[Support](../community/support.md)** - Get help from the community
- **[Issues](https://github.com/soma-core/soma-core/issues)** - Report bugs or request features