kogral/.typedialog/kogral/README.md

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:

nu scripts/generate-configs.nu --mode dev --output .kogral

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

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 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

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

Generate Modes

# 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:

# 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:

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
• Configuration Guide
• NuShell Scripts Reference