# Kollabor Configuration Guide

## Configuration Directory

Kollabor uses a layered configuration approach that supports both global and project-specific configurations.

### Important: Unified Directory Structure

Kollabor uses a **single unified directory structure** - **`.kollabor-cli/`** for all application data:

- `config.json` - Application configuration
- `state.db` - Application state
- `logs/` - Application logs
- `conversations/` - Conversation history
- `conversations_raw/` - Raw conversation data
- `system_prompt/` - System prompt files
- `mcp/` - MCP server configurations

Everything is organized under `.kollabor-cli/` for consistency and simplicity.

### Directory Resolution Order

1. **Local override**: `./.kollabor-cli/` in current directory
2. **Global default**: `~/.kollabor-cli/` in home directory

### How It Works

#### Default Behavior (Global Configuration)

By default, Kollabor creates a **global** configuration directory:

```bash
~/.kollabor-cli/
├── config.json              # Global configuration
├── state.db                 # Application state
├── logs/                    # Application logs
│   └── kollabor.log
├── conversations/           # Conversation history
├── conversations_raw/       # Raw conversation data
├── mcp/                     # MCP server configurations
│   └── mcp_settings.json
└── system_prompt/           # System prompt customization
    └── default.md           # Default system prompt (can be edited)
```

This configuration is **shared across all directories** where you run `kollab`.

**Benefits:**
- Single configuration for all projects
- Centralized conversation history
- Consistent behavior everywhere
- Standard CLI tool pattern (like git, docker, npm)

#### Project-Specific Configuration (Local Override)

To use project-specific configuration, create a `.kollabor-cli/` directory in your project:

```bash
mkdir .kollabor-cli
```

Once this directory exists, Kollabor will use it **instead of** the global directory for **all data**:

```bash
/path/to/my-project/.kollabor-cli/
├── config.json              # Project-specific configuration
├── state.db                 # Project-specific state
├── logs/                    # Project-specific logs
│   └── kollabor.log
├── conversations/           # Project-specific conversations
├── conversations_raw/       # Project-specific raw data
├── mcp/                     # Project-specific MCP configurations
│   └── mcp_settings.json
└── system_prompt/           # Project-specific system prompt
    └── default.md           # Overrides global system prompt
```

**Use cases:**
- Different LLM configurations per project
- Separate conversation histories per project
- Team-shared configuration (commit `.kollabor-cli/config.json` to git)
- Isolated testing environments

### Configuration Layering

The configuration system uses a layered approach (lowest to highest priority):

1. **Base defaults** - Hardcoded in `kollabor/config/loader.py`
2. **Plugin defaults** - From each plugin's `get_default_config()`
3. **Global config** - `~/.kollabor-cli/config.json`
4. **Local config** - `./.kollabor-cli/config.json` (if exists)

### Migration from v0.1.x

**Version 0.1.x behavior:** Always created `./.kollabor-cli/` in current directory

**Version 0.2.0+ behavior:** Uses `~/.kollabor-cli/` unless `./.kollabor-cli/` exists

**No migration needed!** If you have existing `./.kollabor-cli/` directories:
- They will continue to work as project-specific configurations
- Kollabor will use them automatically when you're in that directory
- Your configuration and conversation history are preserved

### Examples

#### Example 1: Standard User (Global Config)

```bash
# First time running kollab
cd ~/projects/project1
kollab

# Creates: ~/.kollabor-cli/config.json
# All data stored in: ~/.kollabor-cli/

# Later, in a different directory
cd ~/projects/project2
kollab

# Uses same config: ~/.kollabor-cli/config.json
# Same conversation history, same settings
```

#### Example 2: Project-Specific Config

```bash
# Create project-specific config
cd ~/projects/special-project
mkdir .kollabor-cli

# Run kollab
kollab

# Creates: ./.kollabor-cli/config.json (project-specific)
# All data for this project stored in: ./.kollabor-cli/

# Edit project-specific config
vim ./.kollabor-cli/config.json

# Changes only affect this project
# Other projects still use ~/.kollabor-cli/
```

#### Example 3: Mixed Usage

```bash
# Global config for most projects
cd ~/projects/project1
kollab  # Uses ~/.kollabor-cli/

cd ~/projects/project2
kollab  # Uses ~/.kollabor-cli/

# But project3 has special needs
cd ~/projects/project3
mkdir .kollabor-cli
kollab  # Uses ./.kollabor-cli/ (project-specific)

# Back to global
cd ~/projects/project4
kollab  # Uses ~/.kollabor-cli/
```

### Configuration File

The configuration file (`config.json`) contains all settings in JSON format:

```json
{
  "core": {
    "llm": {
      "api_url": "http://localhost:1234",
      "model": "qwen/qwen3-4b",
      "temperature": 0.7,
      "max_history": 90
    }
  },
  "plugins": {
    "enhanced_input": {
      "enabled": true,
      "style": "rounded"
    }
  }
}
```

### MCP Configuration

MCP (Model Context Protocol) settings have **both** global and local options:

**Global MCP config:**
```bash
~/.kollabor-cli/mcp/mcp_settings.json
```

**Local MCP config (higher priority):**
```bash
./.kollabor-cli/mcp/mcp_settings.json
```

MCP configurations are **merged**, with local settings overriding global ones.

### System Prompt Configuration

Kollabor includes a customizable system prompt that controls how the LLM behaves.

**Global system prompt:**
```bash
~/.kollabor-cli/system_prompt/default.md
```

**Local system prompt (higher priority):**
```bash
./.kollabor-cli/system_prompt/default.md
```

On first run, Kollabor automatically copies the bundled `system_prompt/default.md` to:
1. **Global directory**: `~/.kollabor-cli/system_prompt/default.md` (if not exists)
2. **Local directory**: `./.kollabor-cli/system_prompt/default.md` (if local config dir exists and file not exists)

**Customization:**
- Edit the global file to change default behavior across all projects
- Create a local `.kollabor-cli/` directory and the system prompt will be copied there
- Edit the local file for project-specific LLM behavior
- Local system prompts override global ones

**Use cases:**
- Project-specific coding standards and conventions
- Custom tool usage instructions
- Domain-specific knowledge and terminology
- Team-shared LLM interaction patterns

### Best Practices

1. **Most users**: Use global configuration (do nothing, it's the default)
2. **Per-project LLM settings**: Create `.kollabor-cli/` in project directory
3. **Team collaboration**: Commit `.kollabor-cli/config.json` to version control
4. **Sensitive data**: Add `.kollabor-cli/conversations/` to `.gitignore`

### Troubleshooting

**Q: Where is my configuration stored?**

Run Kollabor and check the logs:
```bash
kollab
# Look for: "Using global config directory: ..." or "Using local config directory: ..."
```

Or check for directories:
```bash
ls ~/.kollabor-cli/        # Global config
ls ./.kollabor-cli/        # Local config (if exists)
```

**Q: How do I reset to defaults?**

Global reset:
```bash
rm -rf ~/.kollabor-cli/
# Next run will recreate with defaults
```

Local reset:
```bash
rm -rf ./.kollabor-cli/
# Next run will use global config
```

**Q: How do I switch from local to global?**

```bash
# Simply remove the local directory
rm -rf ./.kollabor-cli/
# Kollabor will now use ~/.kollabor-cli/
```

**Q: My conversations disappeared!**

Check if you have both local and global configs:
```bash
ls ~/.kollabor-cli/conversations/      # Global conversations
ls ./.kollabor-cli/conversations/      # Local conversations (if exists)
```

Conversations are stored in whichever config directory is active.
