> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Files Overview

> Complete reference for AIOX configuration file structure and hierarchy

## Overview

AIOX uses a three-level configuration hierarchy to manage framework, project, and local settings. This architecture ensures framework stability while allowing project-specific customization.

## Configuration Hierarchy

AIOX implements a three-tier configuration system:

<ParamField path="Level 1" type="Framework">
  **Framework Configuration** - Read-only settings shipped with the AIOX npm package

  * **File:** `framework-config.yaml`
  * **Location:** `.aiox-core/`
  * **Mutability:** Read-only (framework source)
  * **Git Status:** Committed to framework
  * **Reference:** ADR-PRO-002 — Configuration Hierarchy
</ParamField>

<ParamField path="Level 2" type="Project">
  **Project Configuration** - Team-shared settings committed to repository

  * **File:** `project-config.yaml`
  * **Location:** `.aiox-core/`
  * **Mutability:** Editable by project maintainers
  * **Git Status:** Committed to project repository
  * **Purpose:** Project-specific customizations shared across team
</ParamField>

<ParamField path="Level 3" type="Local">
  **Local Configuration** - Developer-specific settings (not committed)

  * **File:** `local-config.yaml`
  * **Location:** `.aiox-core/`
  * **Mutability:** Fully editable
  * **Git Status:** Ignored (`.gitignore`)
  * **Purpose:** Personal developer preferences and secrets
</ParamField>

## Configuration Resolution

Settings are resolved using a **merge strategy** with precedence:

```text theme={null}
local-config.yaml (highest priority)
    ↓ overrides
project-config.yaml
    ↓ overrides
framework-config.yaml (lowest priority)
```

<Expandable title="Resolution Example">
  ```yaml theme={null}
  # framework-config.yaml (L1)
  performance_defaults:
    git:
      cache_time_seconds: 300

  # project-config.yaml (L2)
  # (no override - inherits from L1)

  # local-config.yaml (L3)
  performance_defaults:
    git:
      cache_time_seconds: 60  # ← Final value: 60
  ```
</Expandable>

## Core Configuration File

The `core-config.yaml` file is the **legacy single-file configuration** that predates the three-tier system. It contains all configuration in one place.

<ParamField path="core-config.yaml" type="object">
  **Location:** `.aiox-core/core-config.yaml`

  This file is being **gradually migrated** to the three-tier system. New projects should use `framework-config.yaml` and `project-config.yaml` instead.

  See [Core Config Reference](/api/core-config) for complete schema.
</ParamField>

## File Locations

<ResponseField name="Configuration Directory" type="string" required>
  `.aiox-core/` - Root directory for all configuration files
</ResponseField>

<ResponseField name="Available Files" type="array">
  * `core-config.yaml` - Legacy unified configuration
  * `framework-config.yaml` - Level 1 (Framework)
  * `project-config.yaml` - Level 2 (Project)
  * `local-config.yaml` - Level 3 (Local, git-ignored)
  * `local-config.yaml.template` - Template for local configuration
</ResponseField>

## Configuration Loading

AIOX loads configuration in the following order:

1. **Framework defaults** from `framework-config.yaml`
2. **Project overrides** from `project-config.yaml`
3. **Local overrides** from `local-config.yaml` (if exists)
4. **Runtime environment variables** (highest priority)

## Best Practices

<AccordionGroup>
  <Accordion title="Framework Contributors">
    * Only modify `framework-config.yaml` for framework-wide changes
    * Document all changes in ADRs
    * Ensure backward compatibility
    * Use semantic versioning for breaking changes
  </Accordion>

  <Accordion title="Project Teams">
    * Customize via `project-config.yaml` for team settings
    * Never commit `local-config.yaml`
    * Document project-specific configurations
    * Use `local-config.yaml.template` for team onboarding
  </Accordion>

  <Accordion title="Individual Developers">
    * Use `local-config.yaml` for personal preferences
    * Copy from `local-config.yaml.template` to start
    * Never commit secrets or API keys
    * Keep local overrides minimal
  </Accordion>
</AccordionGroup>

## Migration from Core Config

If your project uses `core-config.yaml`, you can migrate to the three-tier system:

```bash theme={null}
# Run migration script (when available)
aiox config migrate

# Manual migration:
# 1. Review core-config.yaml
# 2. Split framework defaults → framework-config.yaml
# 3. Move project settings → project-config.yaml
# 4. Move personal settings → local-config.yaml
```

## Related Documentation

* [Core Config Schema](/api/core-config)
* [Project Config Schema](/api/project-config)
* [Framework Config Schema](/api/framework-config)
* [Configuration Best Practices](/guides/configuration)

***

*Reference: ADR-PRO-002 — Configuration Hierarchy*