kogral/schemas/kogral-config.ncl

# Knowledge Base Configuration Schema
#
# Main configuration schema for the knowledge base system.
# This schema is exported to JSON and loaded into Rust structs.
#
# Usage:
#   nickel export --format json kogral-config.ncl > config.json

let Types = import "types.ncl" in

{
  # Graph metadata configuration
  GraphConfig = {
    name
      | String
      | doc "Graph name/identifier",

    version
      | Types.Version
      | doc "Graph version (semver)"
      | default = "1.0.0",

    description
      | String
      | doc "Human-readable description"
      | default = "",
  },

  # Inheritance configuration for guidelines
  InheritanceConfig = {
    base
      | Types.Path
      | doc "Base path for shared KOGRAL (resolves $TOOLS_PATH at runtime, defaults to $HOME/Tools)"
      | default = "$TOOLS_PATH/.kogral-shared",

    guidelines
      | Array Types.Path
      | doc "Additional guideline paths to inherit"
      | default = [],

    priority
      | Types.PositiveInt
      | doc "Override priority (higher = wins)"
      | default = 100,
  },

  # Secondary storage configuration
  SecondaryStorageConfig = {
    enabled
      | Bool
      | doc "Whether secondary storage is enabled"
      | default = false,

    type
      | Types.SecondaryStorageType
      | doc "Secondary storage backend type"
      | default = 'surrealdb,

    url
      | Types.Url
      | doc "Connection URL for secondary storage"
      | default = "ws://localhost:8000",

    namespace
      | String
      | doc "Database namespace"
      | default = "kogral",

    database
      | String
      | doc "Database name"
      | default = "default",
  },

  # Storage backend configuration
  StorageConfig = {
    primary
      | Types.StorageType
      | doc "Primary storage backend type"
      | default = 'filesystem,

    secondary
      | SecondaryStorageConfig
      | doc "Optional secondary storage (for scaling/search)"
      | default = {},
  },

  # Embedding provider configuration
  EmbeddingConfig = {
    enabled
      | Bool
      | doc "Whether embeddings are enabled"
      | default = true,

    provider
      | Types.EmbeddingProvider
      | doc "Embedding provider selection"
      | default = 'fastembed,

    model
      | String
      | doc "Model name/identifier"
      | default = "BAAI/bge-small-en-v1.5",

    dimensions
      | Types.PositiveInt
      | doc "Vector dimensions"
      | default = 384,

    api_key_env
      | String
      | doc "Environment variable name for API key"
      | default = "OPENAI_API_KEY",
  },

  # Logseq blocks support configuration
  BlocksConfig = {
    enabled
      | Bool
      | doc "Enable Logseq content blocks parsing and queries"
      | default = false,

    parse_on_import
      | Bool
      | doc "Automatically parse blocks when importing Logseq pages"
      | default = true,

    serialize_on_export
      | Bool
      | doc "Serialize blocks to outliner format on export"
      | default = true,

    enable_mcp_tools
      | Bool
      | doc "Enable block-related MCP tools (kogral/find_blocks, kogral/find_todos, kogral/find_cards)"
      | default = true,
  },

  # Template mappings per node type
  TemplateMap = {
    note
      | String
      | doc "Note template filename"
      | default = "note.md.tera",

    decision
      | String
      | doc "Decision (ADR) template filename"
      | default = "decision.md.tera",

    guideline
      | String
      | doc "Guideline template filename"
      | default = "guideline.md.tera",

    pattern
      | String
      | doc "Pattern template filename"
      | default = "pattern.md.tera",

    journal
      | String
      | doc "Journal (daily notes) template filename"
      | default = "journal.md.tera",

    execution
      | String
      | doc "Execution record template filename"
      | default = "execution.md.tera",
  },

  # Export template mappings
  ExportTemplateMap = {
    logseq_page
      | String
      | doc "Logseq page export template"
      | default = "export/logseq-page.md.tera",

    logseq_journal
      | String
      | doc "Logseq journal export template"
      | default = "export/logseq-journal.md.tera",

    summary
      | String
      | doc "Summary report template"
      | default = "export/summary.md.tera",

    json
      | String
      | doc "JSON export template"
      | default = "export/graph.json.tera",
  },

  # Template engine configuration
  TemplateConfig = {
    templates_dir
      | Types.Path
      | doc "Template directory path (relative to project root)"
      | default = "templates",

    templates
      | TemplateMap
      | doc "Node type template mappings"
      | default = {},

    export
      | ExportTemplateMap
      | doc "Export template mappings"
      | default = {},

    custom
      | { _ | String }
      | doc "Custom template registry (name → path)"
      | default = {},
  },

  # Query behavior configuration
  QueryConfig = {
    similarity_threshold
      | Types.UnitFloat
      | doc "Minimum similarity threshold for matches (0.0 to 1.0)"
      | default = 0.4,

    max_results
      | Types.PositiveInt
      | doc "Maximum number of search results"
      | default = 10,

    recency_weight
      | Number
      | doc "Recency weight (higher = prefer more recent results)"
      | default = 3.0,

    cross_graph
      | Bool
      | doc "Whether cross-graph queries are enabled"
      | default = true,
  },

  # MCP server configuration
  McpServerConfig = {
    name
      | String
      | doc "MCP server name"
      | default = "kogral-mcp",

    version
      | Types.Version
      | doc "MCP server version"
      | default = "1.0.0",

    transport
      | Types.McpTransport
      | doc "Transport protocol (stdio or SSE)"
      | default = 'stdio,
  },

  # MCP tools configuration
  McpToolsConfig = {
    search
      | Bool
      | doc "Enable kogral/search tool"
      | default = true,

    add_note
      | Bool
      | doc "Enable kogral/add_note tool"
      | default = true,

    add_decision
      | Bool
      | doc "Enable kogral/add_decision tool"
      | default = true,

    link
      | Bool
      | doc "Enable kogral/link tool"
      | default = true,

    get_guidelines
      | Bool
      | doc "Enable kogral/get_guidelines tool"
      | default = true,

    export
      | Bool
      | doc "Enable kogral/export tool"
      | default = true,
  },

  # MCP resources configuration
  McpResourcesConfig = {
    expose_project
      | Bool
      | doc "Expose project resources (kogral://project/*)"
      | default = true,

    expose_shared
      | Bool
      | doc "Expose shared resources (kogral://shared/*)"
      | default = true,
  },

  # MCP configuration
  McpConfig = {
    server
      | McpServerConfig
      | doc "MCP server settings"
      | default = {},

    tools
      | McpToolsConfig
      | doc "MCP tool enablement"
      | default = {},

    resources
      | McpResourcesConfig
      | doc "MCP resource exposure"
      | default = {},
  },

  # Sync configuration
  SyncConfig = {
    auto_index
      | Bool
      | doc "Auto-sync filesystem to secondary storage"
      | default = true,

    watch_paths
      | Array String
      | doc "Paths to watch for changes"
      | default = ["notes", "decisions", "guidelines", "patterns", "journal"],

    debounce_ms
      | Types.PositiveInt
      | doc "Debounce time in milliseconds"
      | default = 500,
  },

  # Main configuration schema
  KbConfig = {
    graph
      | GraphConfig
      | doc "Graph metadata configuration",

    inheritance
      | InheritanceConfig
      | doc "Inheritance settings for guidelines"
      | default = {},

    storage
      | StorageConfig
      | doc "Storage backend configuration"
      | default = {},

    embeddings
      | EmbeddingConfig
      | doc "Embedding provider configuration"
      | default = {},

    blocks
      | BlocksConfig
      | doc "Logseq blocks support configuration"
      | default = {},

    templates
      | TemplateConfig
      | doc "Template engine configuration"
      | default = {},

    query
      | QueryConfig
      | doc "Query behavior configuration"
      | default = {},

    mcp
      | McpConfig
      | doc "MCP server configuration"
      | default = {},

    sync
      | SyncConfig
      | doc "Sync settings"
      | default = {},
  },
}