syntaxis/shared/templates/documentation/configuration.md.template

# {{TOOL_NAME}} Configuration Guide

Complete documentation for {{TOOL_NAME}} configuration system.

## Quick Start

1. **Create config file**:
   ```bash
   mkdir -p .project
   cp examples/config.toml .project/{{tool_name_kebab}}.toml
   ```

2. **Edit configuration**:
   ```bash
   vi .project/{{tool_name_kebab}}.toml
   ```

3. **Tool auto-discovers config**:
   ```bash
   {{tool_name_kebab}} list  # Automatically uses configuration
   ```

## Configuration File Location

{{TOOL_NAME}} searches for configuration in this order (uses first found):

### 1. `.project/{{tool_name_kebab}}.toml` (Priority)
For projects using the Tools ecosystem.

```bash
mkdir -p .project
cp examples/config.toml .project/{{tool_name_kebab}}.toml
```

### 2. `.vapora/{{tool_name_kebab}}.toml`
For VAPORA platform projects.

```bash
mkdir -p .vapora
cp examples/config.toml .vapora/{{tool_name_kebab}}.toml
```

### 3. `.coder/{{tool_name_kebab}}.toml`
For doc tracking projects.

```bash
mkdir -p .coder
cp examples/config.toml .coder/{{tool_name_kebab}}.toml
```

### 4. `./{{tool_name_kebab}}.toml` (Current Directory)
For simple projects or testing.

```bash
cp examples/config.toml ./{{tool_name_kebab}}.toml
```

## Configuration Format

### TOML Structure

Configuration uses TOML format (Tom's Obvious, Minimal Language):

```toml
[{{tool_name_kebab}}]
# Main section - all settings go here
setting1 = "string value"
setting2 = 42
setting3 = true

[{{tool_name_kebab}}.subsection]
# Subsections for related settings
nested_setting = "value"
```

### Data Types

- **String**: `"text"` - Double quotes required
- **Integer**: `42` - Numbers without quotes
- **Boolean**: `true` or `false` - No quotes
- **Array**: `["a", "b", "c"]` - Comma-separated values
- **Table**: `[section]` - Grouped settings

## Configuration Options

### Main Section: `[{{tool_name_kebab}}]`

#### Basic Settings

**`setting1`** (string, required)
- Description: What this setting does
- Default: `"value1"`
- Example: `setting1 = "my-value"`

**`setting2`** (integer, optional)
- Description: What this setting does
- Default: `42`
- Valid Range: 1-1000
- Example: `setting2 = 100`

**`enable_feature`** (boolean, optional)
- Description: Enable or disable feature
- Default: `true`
- Example: `enable_feature = false`

### Advanced Section: `[{{tool_name_kebab}}.advanced]`

**`max_items`** (integer, optional)
- Description: Maximum number of items to process
- Default: `1000`
- Valid Range: 1-10000
- Example: `max_items = 5000`

**`timeout_seconds`** (integer, optional)
- Description: Operation timeout in seconds
- Default: `30`
- Valid Range: 1-300
- Example: `timeout_seconds = 60`

### Database Section: `[database]`

**`type`** (string, required)
- Description: Database type to use
- Valid Values: `"sqlite"`, `"postgres"`
- Default: `"sqlite"`
- Example: `type = "sqlite"`

**`path`** (string, for sqlite)
- Description: Path to SQLite database file
- Default: `".project/{{tool_name_kebab}}.db"`
- Example: `path = ".project/tool.db"`

**`url`** (string, for postgres)
- Description: PostgreSQL connection string
- Format: `postgresql://user:password@host:port/database`
- Example: `url = "postgresql://user:pass@localhost:5432/mydb"`

## Environment Variable Overrides

You can override configuration settings using environment variables:

### Format

```bash
export {{TOOL_NAME}}_SETTING_NAME=value
{{tool_name_kebab}} list
```

### Examples

```bash
# Override setting1
export {{TOOL_NAME}}_SETTING1="override-value"

# Override nested setting
export {{TOOL_NAME}}_ADVANCED_MAX_ITEMS=10000

# Override database
export {{TOOL_NAME}}_DATABASE_URL="postgresql://localhost/mydb"

# Run command (uses ENV values if set)
{{tool_name_kebab}} list
```

### Precedence Order

1. **Environment Variables** (highest priority)
2. **Command-line Arguments**
3. **Configuration File**
4. **Default Values** (lowest priority)

## Complete Configuration Examples

### Minimal Configuration (Development)

```toml
# Minimum required settings
[{{tool_name_kebab}}]
setting1 = "default"

[database]
type = "sqlite"
```

### Standard Configuration (Single User)

```toml
[{{tool_name_kebab}}]
setting1 = "my-value"
setting2 = 100
enable_feature = true

[database]
type = "sqlite"
path = ".project/{{tool_name_kebab}}.db"
```

### Production Configuration (Multi-User)

```toml
[{{tool_name_kebab}}]
setting1 = "production-value"
setting2 = 500
enable_feature = true

[{{tool_name_kebab}}.advanced]
max_items = 10000
timeout_seconds = 60

[database]
type = "postgres"
url = "postgresql://user:password@prod-db:5432/{{tool_name_kebab}}"
```

## Configuration Validation

### Validation Rules

Configuration is automatically validated on startup:

- ✅ Required fields must be present
- ✅ Values must be correct type
- ✅ Numbers must be in valid range
- ✅ Paths must exist (if required)
- ✅ URLs must be valid format

### Validation Errors

If configuration is invalid, you'll see errors like:

```
Error: Configuration validation failed
  - setting1: Cannot be empty
  - setting2: Must be between 1 and 1000
  - database.url: Invalid PostgreSQL URL format
```

### Check Configuration

You can validate without running:

```bash
{{tool_name_kebab}} validate-config
# Output: Configuration is valid ✅
```

## Configuration Search Debugging

To see which configuration file is being used:

```bash
# Enable verbose logging
{{tool_name_kebab}} -v list

# Output includes:
# DEBUG: Searching for configuration...
# DEBUG: Checking .project/{{tool_name_kebab}}.toml... found!
# INFO: Using config: .project/{{tool_name_kebab}}.toml
```

## Customizing Configuration

### Add Custom Settings

In your {{MainType}}Service:

```rust
#[derive(Debug, Deserialize)]
pub struct Config {
    pub setting1: String,
    pub setting2: u32,
    pub custom_setting: String,  // Add this
}
```

Update the TOML:

```toml
[{{tool_name_kebab}}]
setting1 = "value"
setting2 = 42
custom_setting = "custom-value"
```

### Add Validation

```rust
impl Config {
    pub fn validate(&self) -> Result<()> {
        if self.custom_setting.is_empty() {
            return Err(ConfigError::EmptyCustomSetting);
        }
        Ok(())
    }
}
```

## Database Configuration

### SQLite (Default)

Best for single-user applications.

```toml
[database]
type = "sqlite"
path = ".project/{{tool_name_kebab}}.db"
```

**Advantages**:
- No server needed
- Zero configuration
- Good for testing
- File-based

**Disadvantages**:
- Single writer at a time
- Not suitable for high concurrency

### PostgreSQL (Production)

Best for multi-user production deployments.

```toml
[database]
type = "postgres"
url = "postgresql://user:password@hostname:5432/database"
```

**Connection URL Format**:
```
postgresql://[user[:password]@][host][:port][/database]
```

**Examples**:
```
postgresql://localhost/{{tool_name_kebab}}
postgresql://user:pass@localhost:5432/{{tool_name_kebab}}
postgresql://user:pass@prod.example.com:5432/{{tool_name_kebab}}
```

**Advantages**:
- Multiple concurrent connections
- Full ACID compliance
- Advanced features
- Production-ready

**Disadvantages**:
- Requires server
- Setup complexity
- Network latency

## Configuration with Docker

### Environment-Based Configuration

```dockerfile
FROM rust:latest as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
ENV {{TOOL_NAME}}_DATABASE_URL=postgresql://db:5432/mydb
ENV {{TOOL_NAME}}_TIMEOUT_SECONDS=60
COPY --from=builder /app/target/release/{{tool_name_kebab}} /usr/bin/
ENTRYPOINT ["{{tool_name_kebab}}", "list"]
```

### Docker Compose

```yaml
version: '3.8'
services:
  {{tool_name_kebab}}:
    image: {{tool_name_kebab}}:latest
    environment:
      {{TOOL_NAME}}_DATABASE_URL: postgresql://db:5432/{{tool_name_kebab}}
      {{TOOL_NAME}}_TIMEOUT_SECONDS: 60
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: {{tool_name_kebab}}
```

## Troubleshooting Configuration

### Configuration Not Found

**Problem**: "No config found in standard locations"

**Solution**: Create config in one of the search locations:

```bash
mkdir -p .project
cp examples/config.toml .project/{{tool_name_kebab}}.toml
```

### Invalid TOML Syntax

**Problem**: "Failed to parse configuration: TOML parse error"

**Solution**: Check TOML syntax:

```toml
# ❌ Wrong
setting = value        # Missing quotes

# ✅ Correct
setting = "value"      # Strings need quotes
number = 42            # Numbers don't need quotes
```

### Configuration Not Applied

**Problem**: Changes to config aren't taking effect

**Solution**:
1. Verify you're editing the right file
2. Check file path with verbose logging: `{{tool_name_kebab}} -v list`
3. Ensure environment variables aren't overriding: `env | grep {{TOOL_NAME}}`

### Database Connection Error

**Problem**: "Failed to connect to database"

**Solution**:
- SQLite: Ensure path is writable: `chmod 755 .project/`
- PostgreSQL: Check connection string and server: `psql -c "select 1"`

### Invalid Configuration Values

**Problem**: "Configuration validation failed: setting2 must be between 1 and 1000"

**Solution**: Check valid ranges in this document and adjust values.

## Configuration Best Practices

1. **Start with example**: Copy `examples/config.toml` and customize
2. **Use .project/**: Use consistent location across Tools
3. **Don't commit sensitive data**: Use environment variables for secrets
4. **Version your config**: Track in git (without secrets)
5. **Document changes**: Add comments to custom settings
6. **Test configuration**: Use `validate-config` command
7. **Use environment variables**: For deployment-specific values

## Advanced: Configuration as Code

You can generate configuration programmatically:

```bash
# Create config from template
cat > .project/{{tool_name_kebab}}.toml << EOF
[{{tool_name_kebab}}]
setting1 = "$(hostname)"
setting2 = $(nproc)
EOF

{{tool_name_kebab}} list
```

## References

- **Example Configuration**: [examples/config.toml](../examples/config.toml)
- **README**: [README.md](README.md)
- **Quick Start**: [QUICKSTART.md](QUICKSTART.md)
- **Architecture**: [architecture.md](architecture.md)