# Document Frontmatter Schema
#
# Schema for YAML frontmatter in knowledge base documents.
# This frontmatter is embedded in markdown files and parsed by kogral-core.
#
# Format:
# ---
# <frontmatter fields>
# ---
#
# <markdown content>

let Types = import "types.ncl" in

{
  # Frontmatter for knowledge base documents
  Frontmatter = {
    id
      | String
      | doc "Unique identifier (UUID)",

    type
      | Types.NodeType
      | doc "Node type (note, decision, guideline, etc.)",

    title
      | String
      | doc "Human-readable title",

    created
      | Types.Timestamp
      | doc "Creation timestamp (ISO 8601)",

    modified
      | Types.Timestamp
      | doc "Last modification timestamp (ISO 8601)",

    tags
      | Array String
      | doc "Tags for categorization"
      | default = [],

    status
      | Types.NodeStatus
      | doc "Current status (draft, active, etc.)"
      | default = 'draft,

    # Relationship fields (compatible with Logseq [[wikilinks]])
    relates_to
      | Array String
      | doc "Related node IDs"
      | default = [],

    depends_on
      | Array String
      | doc "Dependency node IDs (must exist/be read first)"
      | default = [],

    implements
      | Array String
      | doc "Implementation node IDs (this implements those patterns)"
      | default = [],

    extends
      | Array String
      | doc "Extension node IDs (this extends/overrides those)"
      | default = [],

    # Cross-project reference
    project
      | String
      | doc "Project identifier (for cross-project links)"
      | optional,

    # Decision-specific fields (ADR format)
    context
      | String
      | doc "Decision context (what problem are we solving?)"
      | optional,

    decision
      | String
      | doc "The decision made"
      | optional,

    consequences
      | Array String
      | doc "Consequences of the decision"
      | optional,

    # Guideline-specific fields
    language
      | String
      | doc "Programming language (rust, nushell, etc.)"
      | optional,

    category
      | String
      | doc "Category (error-handling, testing, etc.)"
      | optional,

    # Pattern-specific fields
    problem
      | String
      | doc "Problem statement"
      | optional,

    solution
      | String
      | doc "Solution description"
      | optional,

    forces
      | Array String
      | doc "Forces/constraints affecting the pattern"
      | optional,

    # Execution-specific fields (from Vapora KG)
    task_type
      | String
      | doc "Type of task executed"
      | optional,

    agent
      | String
      | doc "Agent that executed the task"
      | optional,

    outcome
      | String
      | doc "Execution outcome (success, failure, etc.)"
      | optional,

    duration_ms
      | Number
      | doc "Execution duration in milliseconds"
      | optional,
  },

  # Minimal frontmatter (required fields only)
  MinimalFrontmatter = {
    id | String,
    type | Types.NodeType,
    title | String,
    created | Types.Timestamp,
    modified | Types.Timestamp,
  },

  # Decision frontmatter (ADR)
  DecisionFrontmatter = Frontmatter & {
    type | default = 'decision,
    context | String,
    decision | String,
    consequences | Array String | default = [],
  },

  # Guideline frontmatter
  GuidelineFrontmatter = Frontmatter & {
    type | default = 'guideline,
    language | String,
    category | String | optional,
  },

  # Pattern frontmatter
  PatternFrontmatter = Frontmatter & {
    type | default = 'pattern,
    problem | String,
    solution | String,
    forces | Array String | default = [],
  },

  # Execution record frontmatter
  ExecutionFrontmatter = Frontmatter & {
    type | default = 'execution,
    task_type | String,
    agent | String | optional,
    outcome | String,
    duration_ms | Number | optional,
  },
}