"""
YAML Schema Definitions - Single Source of Truth.

This directory contains YAML files that define the ideal state of the system.
Each file maps to specific Django models and is used for:

1. Database Seeding: Initial data population
2. Reconciliation: Sync database to match YAML definitions
3. Drift Detection: Compare YAML ideal vs database reality
4. Test Generation: Generate tests from specifications

Directory Structure (Decision Tree):

    definitions/
    ├── __index.yaml          # Master registry of all definitions
    │
    ├── config/               # System configuration
    │   ├── __index.yaml
    │   ├── field_options/    # All valid field option strings (split)
    │   │   ├── statuses.yaml
    │   │   ├── roles.yaml
    │   │   └── ui_options.yaml
    │   ├── django_settings.yaml
    │   └── middleware.yaml
    │
    ├── domains/              # Tenant definitions
    │   ├── __index.yaml
    │   ├── cineos.yaml
    │   ├── createos.yaml
    │   └── ...
    │
    ├── entities/             # Data model definitions
    │   ├── __index.yaml
    │   └── apps/             # App structure (split)
    │       ├── core.yaml
    │       ├── platform.yaml
    │       └── integration.yaml
    │
    ├── governance/           # Rules and policies
    │   ├── __index.yaml
    │   ├── rbac/             # RBAC definitions (split)
    │   │   ├── platform.yaml
    │   │   ├── tenant.yaml
    │   │   └── api.yaml
    │   ├── security/         # Security policies (split)
    │   └── legal/            # Legal documents (split)
    │
    ├── ui/                   # UI configuration
    │   ├── __index.yaml
    │   ├── blueprints.yaml
    │   ├── layouts.yaml
    │   ├── navigation.yaml
    │   └── pages.yaml
    │
    ├── communication/        # Messaging
    │   ├── __index.yaml
    │   ├── email.yaml
    │   ├── cli.yaml
    │   └── websockets/       # WebSocket config (split)
    │
    └── workflows/            # Unified workflow definitions
        ├── __index.yaml
        ├── __schema.yaml     # Workflow validation schema
        ├── agentic/          # Background automation
        ├── collaboration/    # Multi-agent workflows
        ├── journeys/         # User-driven flows (was user_flows/)
        ├── epics/            # Strategic initiatives
        ├── infrastructure/   # CI/CD operations
        └── compliance/       # Audit workflows

Usage:
    from lightwave.schema.loaders.base import (
        load_workflow,      # Load a workflow by path
        load_workflows,     # Load all workflows
        load_schema,        # Load any schema by name
        load_layouts,       # Load typed layouts
        load_blueprints,    # Load typed blueprints
    )

    # Load a user journey
    signup = load_workflow("journeys/auth/signup")

    # Load an agentic workflow
    enrichment = load_workflow("agentic/enrichment/task")

Backward Compatibility:
    The old user_flows/ directory is still available but deprecated.
    Use workflows/journeys/ for new code.
"""
