> ## 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.

# core-config.yaml

> Complete schema reference for AIOX core configuration file

## Overview

`core-config.yaml` is the **legacy unified configuration file** that contains all AIOX settings in a single location. Located at `.aiox-core/core-config.yaml`, it manages project metadata, documentation paths, integrations, and operational settings.

<Note>
  This file is being **gradually migrated** to the three-tier configuration system (`framework-config.yaml`, `project-config.yaml`, `local-config.yaml`). New projects should prefer the modular approach.
</Note>

## Schema Reference

### Project Metadata

<ParamField path="markdownExploder" type="boolean" default="true">
  Enable markdown file explosion for large documents
</ParamField>

<ParamField path="project" type="object" required>
  Project installation metadata

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Project type: `EXISTING_AIOX`, `NEW_AIOX`, `GREENFIELD`
    </ResponseField>

    <ResponseField name="installedAt" type="string" required>
      ISO 8601 timestamp of installation

      Example: `2025-01-14T00:00:00Z`
    </ResponseField>

    <ResponseField name="version" type="string" required>
      AIOX framework version

      Example: `2.1.0`
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="user_profile" type="string" default="advanced">
  User experience level: `beginner`, `intermediate`, `advanced`

  Affects agent verbosity and guidance level.
</ParamField>

### Documentation Configuration

<ParamField path="qa" type="object">
  Quality assurance documentation settings

  <Expandable title="properties">
    <ResponseField name="qaLocation" type="string" default="docs/qa">
      Directory for QA reports and artifacts
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="prd" type="object">
  Product Requirements Document configuration

  <Expandable title="properties">
    <ResponseField name="prdFile" type="string" default="docs/prd.md">
      Primary PRD file path
    </ResponseField>

    <ResponseField name="prdVersion" type="string" default="v4">
      PRD template version
    </ResponseField>

    <ResponseField name="prdSharded" type="boolean" default="true">
      Enable PRD sharding for large documents
    </ResponseField>

    <ResponseField name="prdShardedLocation" type="string" default="docs/prd">
      Directory for PRD shards
    </ResponseField>

    <ResponseField name="epicFilePattern" type="string" default="epic-{n}*.md">
      Pattern for epic file naming
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="architecture" type="object">
  Architecture documentation settings

  <Expandable title="properties">
    <ResponseField name="architectureFile" type="string" default="docs/architecture.md">
      Primary architecture document
    </ResponseField>

    <ResponseField name="architectureVersion" type="string" default="v4">
      Architecture document version
    </ResponseField>

    <ResponseField name="architectureSharded" type="boolean" default="true">
      Enable architecture sharding
    </ResponseField>

    <ResponseField name="architectureShardedLocation" type="string" default="docs/architecture">
      Directory for architecture shards
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="devLoadAlwaysFiles" type="array">
  Files loaded by dev agent on every activation

  ```yaml theme={null}
  devLoadAlwaysFiles:
    - docs/framework/coding-standards.md
    - docs/framework/tech-stack.md
    - docs/framework/source-tree.md
  ```
</ParamField>

<ParamField path="devStoryLocation" type="string" default="docs/stories">
  Directory for user stories
</ParamField>

### Resource Locations

<ParamField path="toolsLocation" type="string" default=".aiox-core/tools">
  Directory for AIOX utility tools
</ParamField>

<ParamField path="scriptsLocation" type="object">
  Script directories by category

  <Expandable title="properties">
    <ResponseField name="core" type="string" default=".aiox-core/core">
      Core framework scripts
    </ResponseField>

    <ResponseField name="development" type="string" default=".aiox-core/development/scripts">
      Development scripts
    </ResponseField>

    <ResponseField name="infrastructure" type="string" default=".aiox-core/infrastructure/scripts">
      Infrastructure scripts
    </ResponseField>

    <ResponseField name="legacy" type="string" default=".aiox-core/scripts">
      Legacy scripts (deprecated)
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="dataLocation" type="string" default=".aiox-core/data">
  Directory for framework data files (registries, patterns, schemas)
</ParamField>

<ParamField path="elicitationLocation" type="string" default=".aiox-core/elicitation">
  Directory for elicitation templates and workflows
</ParamField>

### IDE Configuration

<ParamField path="ide" type="object">
  IDE integration settings

  <Expandable title="properties">
    <ResponseField name="selected" type="array">
      Active IDE integrations

      ```yaml theme={null}
      selected:
        - vscode
        - codex
        - gemini
        - cursor
        - claude-code
      ```
    </ResponseField>

    <ResponseField name="configs" type="object">
      Per-IDE feature flags

      ```yaml theme={null}
      configs:
        vscode: true
        codex: true
        cursor: true
        claude-code: true
        zed: false
      ```
    </ResponseField>
  </Expandable>
</ParamField>

### MCP Configuration

<ParamField path="mcp" type="object">
  Model Context Protocol settings

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable MCP integration
    </ResponseField>

    <ResponseField name="configLocation" type="string" default=".claude/mcp.json">
      MCP configuration file location
    </ResponseField>

    <ResponseField name="docker_mcp" type="object">
      Docker-based MCP gateway configuration

      <Expandable title="docker_mcp properties">
        <ResponseField name="enabled" type="boolean" default="true">
          Enable Docker MCP gateway
        </ResponseField>

        <ResponseField name="gateway" type="object">
          Gateway transport settings

          ```yaml theme={null}
          gateway:
            transport: http
            url: http://localhost:8080/mcp
            port: 8080
            watch: true
            service_file: .docker/mcp/gateway-service.yml
          ```
        </ResponseField>

        <ResponseField name="defaultPreset" type="string" default="minimal">
          Default server preset: `minimal` or `full`
        </ResponseField>

        <ResponseField name="defaultServers" type="array">
          MCP server definitions

          Each server includes:

          * `name` - Server identifier
          * `description` - Purpose
          * `config` - Server-specific settings
          * `required` - Whether server is mandatory
          * `api_key_required` - Whether API key needed
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

### Performance Settings

<ParamField path="lazyLoading" type="object">
  Lazy loading configuration for performance optimization

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable lazy loading
    </ResponseField>

    <ResponseField name="heavySections" type="array">
      Sections to lazy load

      ```yaml theme={null}
      heavySections:
        - pvMindContext
        - squads
        - registry
      ```
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="git" type="object">
  Git integration settings

  <Expandable title="properties">
    <ResponseField name="showConfigWarning" type="boolean" default="true">
      Show git configuration warnings
    </ResponseField>

    <ResponseField name="cacheTimeSeconds" type="number" default="300">
      Git status cache duration (seconds)
    </ResponseField>
  </Expandable>
</ParamField>

### Logging & Status

<ParamField path="decisionLogging" type="object">
  Architecture Decision Record (ADR) logging

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable decision logging
    </ResponseField>

    <ResponseField name="async" type="boolean" default="true">
      Asynchronous logging
    </ResponseField>

    <ResponseField name="location" type="string" default=".ai/">
      Decision log directory
    </ResponseField>

    <ResponseField name="indexFile" type="string" default="decision-logs-index.md">
      Index file name
    </ResponseField>

    <ResponseField name="format" type="string" default="adr">
      Log format: `adr`, `json`, `yaml`
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="projectStatus" type="object">
  Project status tracking configuration

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable project status tracking
    </ResponseField>

    <ResponseField name="autoLoadOnAgentActivation" type="boolean" default="true">
      Load status automatically when agent activates
    </ResponseField>

    <ResponseField name="showInGreeting" type="boolean" default="true">
      Display status in agent greeting
    </ResponseField>

    <ResponseField name="cacheTimeSeconds" type="number" default="60">
      Status cache duration
    </ResponseField>

    <ResponseField name="components" type="object">
      Status components to display

      ```yaml theme={null}
      components:
        gitBranch: true
        gitStatus: true
        recentWork: true
        currentEpic: true
        currentStory: true
      ```
    </ResponseField>
  </Expandable>
</ParamField>

### Integrations

<ParamField path="github" type="object">
  GitHub integration settings

  See [Project Config - GitHub](/api/project-config#github-integration) for complete schema.
</ParamField>

<ParamField path="coderabbit_integration" type="object">
  CodeRabbit AI code review integration

  See [Project Config - CodeRabbit](/api/project-config#coderabbit-integration) for complete schema.
</ParamField>

### Boundary Protection

<ParamField path="boundary" type="object">
  Framework-Project separation controls (Epic BM)

  <Expandable title="properties">
    <ResponseField name="frameworkProtection" type="boolean" default="true">
      Enable framework file protection via deny rules

      When `true`, Claude Code deny rules block Edit/Write on L1/L2 paths.
      Set to `false` for framework contributors.
    </ResponseField>

    <ResponseField name="protected" type="array">
      L1/L2 paths blocked from editing

      ```yaml theme={null}
      protected:
        - .aiox-core/core/**
        - .aiox-core/development/tasks/**
        - .aiox-core/development/templates/**
        - .aiox-core/infrastructure/**
        - bin/aiox.js
      ```
    </ResponseField>

    <ResponseField name="exceptions" type="array">
      L3 paths allowed within `.aiox-core/`

      ```yaml theme={null}
      exceptions:
        - .aiox-core/data/**
        - .aiox-core/development/agents/*/MEMORY.md
      ```
    </ResponseField>
  </Expandable>
</ParamField>

## Example Configuration

```yaml theme={null}
markdownExploder: true

project:
  type: EXISTING_AIOX
  installedAt: '2025-01-14T00:00:00Z'
  version: 2.1.0

user_profile: advanced

qa:
  qaLocation: docs/qa

prd:
  prdFile: docs/prd.md
  prdVersion: v4
  prdSharded: true
  prdShardedLocation: docs/prd

architecture:
  architectureFile: docs/architecture.md
  architectureSharded: true
  architectureShardedLocation: docs/architecture

devLoadAlwaysFiles:
  - docs/framework/coding-standards.md
  - docs/framework/tech-stack.md

lazyLoading:
  enabled: true
  heavySections:
    - pvMindContext
    - squads

git:
  showConfigWarning: true
  cacheTimeSeconds: 300

boundary:
  frameworkProtection: true
  protected:
    - .aiox-core/core/**
    - .aiox-core/infrastructure/**
```

## Migration Path

To migrate from `core-config.yaml` to the three-tier system:

1. **Framework defaults** → `framework-config.yaml`
2. **Project settings** → `project-config.yaml`
3. **Personal preferences** → `local-config.yaml`

See [Configuration Files Overview](/api/config-files) for migration guidance.

## Related Documentation

* [Configuration Files Overview](/api/config-files)
* [Project Config Schema](/api/project-config)
* [Framework Config Schema](/api/framework-config)

***

*Reference: `.aiox-core/core-config.yaml`*