# OKF Bundle Configuration
# This file configures tooling behavior for the pi Agent Documentation Bundle.
# It is not part of the OKF v0.1 spec — it is an extension for automation.

bundle:
  name: "pi Agent Documentation Bundle"
  version: "0.1"
  author: "pi agent system"
  description: "Cached documentation for tools, configurations, and systems used during pi agent sessions."
  root: "~/.omp/omp-docs"

generator:
  # Index generation settings
  index:
    auto_generate: true          # Regenerate index.md when files change
    exclude:                     # Filenames to never include in auto-generated indexes
      - log.md
      - config.yaml
    description_format: "{title} — {description}"   # Format for index entries
    sort: alphabetical           # Sort order: alphabetical | size | modified
    max_depth: 1                 # Only list immediate children (not recursive)

  # Frontmatter template for new files
  frontmatter_template: |
    ---
    type: {type}
    title: {title}
    description: {description}
    tags: []
    timestamp: {timestamp}
    ---

validator:
  # Validation rules — which checks to run
  checks:
    - name: "missing_type"
      severity: "error"
      description: "Every concept must have a `type` field in frontmatter"
      run: "grep -L '^type:' {file}"

    - name: "missing_description"
      severity: "warning"
      description: "Every concept should have a `description` field"
      run: "grep -L '^description:' {file}"

    - name: "missing_timestamp"
      severity: "info"
      description: "Consider adding a `timestamp` for staleness detection"
      run: "grep -L '^timestamp:' {file}"

    - name: "oversized_file"
      severity: "warning"
      description: "Files over 500 lines should be split into separate concepts"
      threshold: 500               # lines
      run: "wc -l {file} | awk '$1 > 500'"

    - name: "empty_frontmatter"
      severity: "error"
      description: "Frontmatter block exists but contains no parseable YAML"
      run: "head -n 4 {file} | grep -c '^---'"

    - name: "index_mismatch"
      severity: "warning"
      description: "index.md does not list all non-reserved .md files in directory"
      run: "compare-index {directory}"

  # Staleness detection
  staleness:
    warning_days: 90             # Flag files older than 90 days
    error_days: 180              # Flag files older than 180 days as stale
    timestamp_field: "timestamp"

  # Cross-link validation
  linking:
    check_absolute_links: true   # Validate absolute (bundle-relative) links resolve
    check_relative_links: true   # Validate relative links resolve
    tolerate_broken: true        # OKF spec says consumers must tolerate broken links,
                                 # but this validator can flag them for cleanup

fields:
  # Custom field definitions beyond the OKF v0.1 spec
  required:
    - type                       # Non-negotiable — defines concept kind

  recommended:
    - title                      # Human-readable display name
    - description                # One-line summary for previews and index listings
    - timestamp                  # Last meaningful change for staleness detection
    - tags                       # Cross-cutting categorization

  optional:
    - resource                   # URI identifying the underlying asset
    - status                     # Draft | Current | Deprecated | Archived
    - version                    # Version string for versioned concepts
    - see_also                   # Explicit list of related concept paths
    - related_concepts           # Tags or paths to related concepts

  # Predefined type values recognized by this bundle
  types:
    - concept           # A single concept or idea
    - reference         # Reference material, specifications, tables
    - guide             # How-to, walkthrough, procedural
    - configuration     # Config file reference or setup instructions
    - changelog         # Update history
    - specification     # Formal spec or standard
    - tutorial          # Step-by-step learning content
    - tool              # Tool documentation, setup, and usage