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](kogral/README.md)** - How KOGRAL schemas and modes work
- **Understanding the stack**: Nickel → JSON → Rust → Runtime

### For CI/CD

- **[CI Configuration](ci/README.md)** - Pipeline setup and deployment

### For Automation

- **[NuShell Scripts](kogral/scripts/)** - All automation scripts (5 total)
- **[Scripts Documentation](../docs/cli/nushell-scripts.md)** - 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

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

### Generate Mode-Specific Config

```bash
# 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

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

```bash
just scripts::sync
just scripts::reindex
just scripts::migrate
```

## Integration with Codebase

### Documentation

- **User Guide**: [docs/cli/nushell-scripts.md](../docs/cli/nushell-scripts.md)
- **Configuration Guide**: [docs/config/](../docs/config/)
- **Architecture**: [docs/architecture/config-driven.md](../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