# KOGRAL Configuration Structure

Central configuration hub for KOGRAL knowledge base system.

## Directory Structure

```
.typedialog/kogral/
├── core/                  # Core Nickel schemas (source of truth)
│   ├── contracts.ncl      # Type contracts and validation rules
│   ├── defaults.ncl       # Base default values
│   └── helpers.ncl        # Composition utilities (merge_with_override)
│
├── modes/                 # Environment-specific overrides
│   ├── dev.ncl            # Development mode (filesystem, fastembed, manual sync)
│   ├── prod.ncl           # Production mode (SurrealDB, OpenAI, auto-sync)
│   └── test.ncl           # Test mode (in-memory, no embeddings, isolated)
│
├── forms/                 # typedialog-web UI configuration (fragment composition)
│   ├── kogral-config.toml # Main form definition (composes fragments)
│   ├── README.md          # Forms architecture documentation
│   └── fragments/         # Reusable form fragments
│       ├── graph.toml     # Knowledge graph metadata
│       ├── storage.toml   # Storage backend options
│       ├── embeddings.toml # Vector search provider
│       ├── query.toml     # Query engine tuning
│       ├── mcp.toml       # MCP server configuration
│       └── sync.toml      # Synchronization settings
│
├── templates/             # Tera templates for rendering JSON
│   └── config.json.tera   # JSON template (maps to Nickel structure)
│
└── scripts/               # Configuration generation and validation scripts
    ├── generate-configs.nu    # Generate JSON config from Nickel modes
    └── validate-config.nu     # Validate all schemas
```

## Three-Layer Configuration System

**Pattern**: Nickel Schemas → Mode Overrides → User Customization → JSON → Rust

```
┌──────────────────────────────────────────┐
│ Layer 1: Nickel Core (kogral/core/)      │ ← Type safety + validation
│ - contracts.ncl (validation rules)       │
│ - defaults.ncl (base values)             │
│ - helpers.ncl (utilities)                │
├──────────────────────────────────────────┤
│ Layer 2: Mode Overrides (kogral/modes/)  │ ← Environment-specific
│ - dev.ncl (development)                  │
│ - prod.ncl (production)                  │
│ - test.ncl (testing)                     │
├──────────────────────────────────────────┤
│ Layer 3: User Customization              │ ← Project-level
│ - .kogral-config/core/kogral.ncl         │
└──────────────────────────────────────────┘
         ↓ Generated by scripts/ ↓
┌──────────────────────────────────────────┐
│ Rendered Output (forms/ + templates/)    │ ← typedialog-web UI
│ - JSON config                            │
│ - TOML settings                          │
└──────────────────────────────────────────┘
         ↓ Loaded by Rust ↓
┌──────────────────────────────────────────┐
│ Runtime Configuration                    │ ← Deserialized + validated
│ - KbConfig struct                        │
└──────────────────────────────────────────┘
```

## Components

### 1. Core Schemas (Source of Truth)

`core/contracts.ncl` - Type contracts and validation rules:
- Defines all fields with types and documentation
- Enforced by Nickel at export time
- Example: `version | doc "Schema version" = "1.0.0"`

`core/defaults.ncl` - Base configuration values across all environments

`core/helpers.ncl` - Utility functions (merge, compose, etc.)

### 2. Mode Overrides (Environment-Specific)

Each environment has specific requirements:

- **dev.ncl** - Filesystem storage, local fastembed, manual sync
- **prod.ncl** - SurrealDB storage, OpenAI/Claude, auto-sync
- **test.ncl** - In-memory storage, no embeddings, isolated

### 3. UI Forms (typedialog-web Integration)

`forms/config.toml` - Interactive form definition:
- Defines UI fields for each configuration option
- Supports conditional visibility (visible_if)
- Enables roundtrip editing via typedialog-web

### 4. Templates (Configuration Rendering)

`templates/config.json.tera` - Tera template:
- Renders configuration to JSON format
- Supports conditional blocks for environment-specific values
- Can be extended for TOML, YAML, or other formats

### 5. Configuration Scripts

`scripts/generate-configs.nu` - Generate JSON from Nickel mode:
```bash
nu scripts/generate-configs.nu --mode dev --output .kogral
```

`scripts/validate-config.nu` - Validate all schemas:
```bash
nu scripts/validate-config.nu
```

## Form Fragment Architecture

Forms use **fragment composition pattern** for modularity:

```
kogral-config.toml (main form)
  └─ includes: fragments/graph.toml
  └─ includes: fragments/storage.toml
  └─ includes: fragments/embeddings.toml
  └─ includes: fragments/query.toml
  └─ includes: fragments/mcp.toml
  └─ includes: fragments/sync.toml
```

Each fragment defines fields with:
- **nickel_path** - Path in Nickel config (e.g., `["storage", "primary"]`)
- **type** - Input control type (text, select, boolean, number, text_array)
- **visible_if** - Conditional visibility rules
- **default** - Default value

See [FORM-TO-TEMPLATE-MAPPING.md](FORM-TO-TEMPLATE-MAPPING.md) for complete field mapping across:
- Form fragments (user input)
- Tera template (JSON rendering)
- Nickel contracts (type validation)

## Double Validation

1. **Nickel validation** - Type contracts enforced at export time
2. **Serde validation** - Rust deserialization in KbConfig struct

## Usage

### Validate Configuration

```bash
nickel export --format json schemas/kogral/defaults.ncl
```

### Generate Modes

```bash
# Development
nickel export --format json schemas/kogral/modes/dev.ncl > .kogral/config.dev.json

# Production
nickel export --format json schemas/kogral/modes/prod.ncl > .kogral/config.prod.json
```

### Run Scripts

All scripts in `scripts/` are production-ready automation:

```bash
# Sync knowledge base
nu scripts/kogral-sync.nu

# Reindex embeddings
nu scripts/kogral-reindex.nu --provider fastembed

# Import from Logseq
nu scripts/kogral-import-logseq.nu ~/Logseq/mydb

# Export to Logseq
nu scripts/kogral-export-logseq.nu ~/logseq-export

# Migrate schema
nu scripts/kogral-migrate.nu --target latest
```

## Environment Variables

Configuration system supports environment variables for resolution:

- **TOOLS_PATH** - Base directory for shared tools (used by Nickel helper functions)
- **OPENAI_API_KEY** - OpenAI API credentials (embedding provider)
- **ANTHROPIC_API_KEY** - Claude API credentials (embedding provider)

Export with custom TOOLS_PATH:

```bash
TOOLS_PATH=/opt/mytools nickel export --format json schemas/kogral/defaults.ncl
```

## Integration with Codebase

- **Core Library** (`crates/kogral-core/`) - Uses exported JSON config
- **CLI Binary** (`crates/kogral-cli/`) - Loads config from `.kogral/config.json`
- **MCP Server** (`crates/kogral-mcp/`) - Inherits config from core
- **Scripts** (`scripts/`) - May read config for behavior customization

## See Also

- [Schemas Documentation](../../schemas/)
- [Configuration Guide](../../docs/config/)
- [NuShell Scripts Reference](../../docs/cli/nushell-scripts.md)
