kogral/.typedialog/README.md

TypeDialog Configuration Hub

Central repository for all KOGRAL system configurations, schemas, and automation scripts.

Structure

.typedialog/
├── ci/                  # CI/CD configuration and pipeline setup
│   ├── config.ncl       # CI configuration (GitHub Actions, deployment)
│   ├── README.md        # CI documentation
│   └── ...
│
└── kogral/              # KOGRAL knowledge base configuration
    ├── core/            # Core Nickel schemas
    │   ├── contracts.ncl    # Type contracts and validation
    │   ├── defaults.ncl     # Base default configuration
    │   └── helpers.ncl      # Utility functions
    │
    ├── modes/           # Environment-specific overrides
    │   ├── dev.ncl          # Development mode
    │   ├── prod.ncl         # Production mode
    │   └── test.ncl         # Test mode
    │
    ├── scripts/         # NuShell automation scripts
    │   ├── kogral-sync.nu           # Bidirectional sync
    │   ├── kogral-reindex.nu        # Embeddings indexing
    │   ├── kogral-import-logseq.nu  # Logseq import
    │   ├── kogral-export-logseq.nu  # Logseq export
    │   └── kogral-migrate.nu        # Schema migration
    │
    └── README.md        # KOGRAL configuration guide

Quick Navigation

For Configuration Management

• KOGRAL Configuration - How KOGRAL schemas and modes work
• Understanding the stack: Nickel → JSON → Rust → Runtime

For CI/CD

• CI Configuration - Pipeline setup and deployment

For Automation

• NuShell Scripts - All automation scripts (5 total)
• Scripts Documentation - Detailed usage guide

Configuration Pattern

KOGRAL uses a 3-layer configuration system:

┌─────────────────────────────────────────┐
│ Layer 1: Nickel Schemas (kogral/core/)  │ ← Type safety + validation
├─────────────────────────────────────────┤
│ Layer 2: Mode Overrides (kogral/modes/) │ ← Environment-specific
├─────────────────────────────────────────┤
│ Layer 3: User Customization (.kogral/)  │ ← Project-level
└─────────────────────────────────────────┘
         ↓ Exported to JSON ↓
┌─────────────────────────────────────────┐
│ Rust Deserialization + Runtime Use      │
└─────────────────────────────────────────┘

Files by Purpose

Core Configuration Files

File	Purpose
kogral/core/contracts.ncl	Type contracts + field documentation
kogral/core/defaults.ncl	Base configuration values
kogral/core/helpers.ncl	Composition functions (merge, override)
kogral/modes/dev.ncl	Development environment overrides
kogral/modes/prod.ncl	Production environment overrides
kogral/modes/test.ncl	Test environment overrides

Automation Scripts

Script	Purpose
kogral/scripts/kogral-sync.nu	Sync filesystem ↔ SurrealDB
kogral/scripts/kogral-reindex.nu	Regenerate embeddings index
kogral/scripts/kogral-import-logseq.nu	Import from Logseq graphs
kogral/scripts/kogral-export-logseq.nu	Export to Logseq format
kogral/scripts/kogral-migrate.nu	Schema version migrations

Usage

Validate Configuration

# Validate Nickel schemas
nickel export --format json .typedialog/kogral/core/contracts.ncl

Generate Mode-Specific Config

# Development
nickel export --format json .typedialog/kogral/modes/dev.ncl > .kogral/config.dev.json

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

Run Automation Scripts

# From repository root:
nu .typedialog/kogral/scripts/kogral-sync.nu
nu .typedialog/kogral/scripts/kogral-reindex.nu
nu .typedialog/kogral/scripts/kogral-migrate.nu

Or via justfile:

just scripts::sync
just scripts::reindex
just scripts::migrate

Integration with Codebase

Documentation

• User Guide: docs/cli/nushell-scripts.md
• Configuration Guide: docs/config/
• Architecture: docs/architecture/config-driven.md

Build Process

• Core library loads JSON config via serde
• CLI respects .kogral/config.toml or Nickel-exported JSON
• Scripts are standalone executables

Environment Variables

• TOOLS_PATH - For shared configuration resolution
• OPENAI_API_KEY - For embedding providers
• ANTHROPIC_API_KEY - For Claude provider

Synchronization with /schemas/

The /schemas/kogral/ directory and .typedialog/kogral/ are synchronized:

• Source of Truth: .typedialog/kogral/ (this directory)
• /schemas/kogral/ - Symlink or copy for build compatibility
• Update Flow: Edit in .typedialog/kogral/ → sync to /schemas/kogral/

Related Directories

• schemas/ - Global schema definitions (generated from .typedialog)
• config/ - Config examples (generated from modes)
• scripts/ - Main scripts location (symlink to .typedialog/kogral/scripts)
• docs/cli/ - User-facing documentation
• crates/kogral-core/ - Rust library using config