> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raigal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Reference for .raigal/config.yml, rule overrides, and schema validation.

Raigal reads project settings from `.raigal/config.yml` in your repository root. Configuration files use strict schema validation validated with Zod; unexpected or misspelled keys trigger validation errors.

## Complete configuration example

Here is a full `.raigal/config.yml` file matching the schema:

```yaml theme={null}
version: 1

# Supported engines
engines:
  format: true          # Biome, Ruff, Gofmt, Cargo fmt, etc.
  lint: true            # Oxlint, Ruff, Clippy, Golangci-lint, Roslynator, etc.
  code-quality: true    # Knip unused exports, dead code, complexity
  ai-slop: true         # 26+ AI anti-pattern detection rules
  architecture: false   # Dependency & boundary rules
  security: true        # Secrets, prompt injections, unsafe deserialization

# Quality and complexity limits
quality:
  maxFunctionLoc: 80
  maxFileLoc: 400
  maxNesting: 5
  maxParams: 6

# Engine-specific lint settings
lint:
  typecheck: false      # Bundled tsc compiler diagnostics (slow in CI)
  expoDoctor: false     # Expo React Native project hygiene checks
  csharp:
    projectEvaluation: false
    jb: true            # JetBrains InspectCode
    roslynator: true
    jbSeverityFloor: "WARNING"
  cpp:
    cppcheck: true
    clangTidy: true
    cppcheckEnable: "warning,performance,portability"

# CI gate configuration
ci:
  failBelow: 75         # Minimum passing score (defaults to 70 in standard config)
  format: "json"

# Score calculation tuning
scoring:
  thresholds:
    good: 75
    ok: 50
  smoothing: 5
  maxPerRule: 40

# Baseline regression protection
baseline:
  mode: strict          # "strict" (disables Stage 3 absorption) or "relaxed"

# Enterprise licensing lapse behavior
licensing:
  onLapse: "fail-closed" # "fail-closed" (exits 2 in CI) or "fail-open"

# Monorepo policy governance
workspace:
  minimumFloor: 75      # Prevents child package configs from setting failBelow < 75

# Outbound telemetry controls
telemetry:
  enabled: true         # Set to false to disable all outbound telemetry queueing

# Rule severity overrides
rules:
  ai-slop/trivial-comment: "off"
  ai-slop/unsafe-type-assertion: "error"

# Path exclusions
exclude:
  - "node_modules"
  - ".git"
  - "dist"
  - "build"
  - "coverage"
include: []
```

## File locations and precedence

Raigal resolves configuration by searching upward from the target directory until reaching the repository root:

1. `.raigal/config.yml` or `.raigal/config.yaml`
2. `.raigal/config.json`
3. Root files: `.raigal.yml`, `.raigal.yaml`, or `.raigal.json`
4. Legacy directory paths for backward compatibility (`.aislop/config.yml`)

## Options reference

### `engines`

Enables or disables individual analysis engines:

* `format` (boolean, default: `true`): whitespace, indentation, line wrapping, and import ordering.
* `lint` (boolean, default: `true`): static analysis rules via Oxlint, Ruff, Clippy, and language tools.
* `code-quality` (boolean, default: `true`): unused exports (Knip), dead code detection, and complexity limits.
* `ai-slop` (boolean, default: `true`): rules detecting AI-generated anti-patterns, trivial comments, and redundant wrappers.
* `architecture` (boolean, default: `false`): layer boundary enforcement and dependency validation.
* `security` (boolean, default: `true`): hardcoded secrets, injection vulnerabilities, and risky APIs.

### `quality`

Defines structural thresholds enforced by the `code-quality` engine:

* `maxFunctionLoc` (number, default: `80`): maximum physical lines of code per function.
* `maxFileLoc` (number, default: `400`): maximum physical lines of code per file.
* `maxNesting` (number, default: `5`): maximum depth of nested control flow blocks.
* `maxParams` (number, default: `6`): maximum parameter count per function signature.

### `lint`

Configures language-specific compiler and diagnostic tools:

* `typecheck` (boolean, default: `false`): runs TypeScript compiler diagnostics (`tsc`).
* `expoDoctor` (boolean, default: `false`): runs Expo React Native health checks.
* `csharp`: settings for C# tooling, including `roslynator` and JetBrains InspectCode (`jb`).
* `cpp`: settings for C/C++ tooling (`cppcheck`, `clangTidy`).

### `ci`

Configures automated continuous integration behavior:

* `failBelow` (number, default: `70`): minimum passing quality score. If a scan score falls below this value or encounters an `error`-level finding, `raigal ci` exits with code 1.
* `format` (`"json"`, default: `"json"`): output serialization format for CI runs.

### `baseline`

Configures incremental regression matching against `.raigal/baseline.json`:

* `mode` (`"strict"` | `"relaxed"`, default: `"relaxed"`): when set to `"strict"`, Stage 3 file-level absorption is disabled. Any finding outside the 11-line window is flagged as a blocking regression.

### `licensing`

Defines CI behavior when entitlement verification lapses:

* `onLapse` (`"fail-open"` | `"fail-closed"`, default: `"fail-open"`): when set to `"fail-closed"`, CI exits with code 2 if entitlement cannot be verified after the grace period.

### `workspace`

Enforces organizational minimum standards across monorepo packages:

* `minimumFloor` (number, default: `50`): sets a hard lower bound on `ci.failBelow` that child package configs cannot lower.

### `scoring`

Tunes scoring engine parameters:

* `thresholds`: object defining CLI status boundaries.
  * `good` (number, default: `75`): score at or above which status is labeled `Healthy`.
  * `ok` (number, default: `50`): score at or above which status is labeled `Needs Work`. Below this, status is `Critical`.
* `smoothing` (number, default: `5`): smoothing constant added to file count to avoid disproportionate penalties in small repositories.
* `maxPerRule` (number, default: `40`): maximum deduction baseline allowed for any single rule before repository scale multipliers apply.
* `weights`: custom category weights (defaults: `security: 1.5`, `ai-slop: 1.0`, `architecture: 1.0`, `code-quality: 0.8`, `lint: 0.6`, `format: 0.3`).

### `rules`

A map of rule identifiers to severity overrides:

```yaml theme={null}
rules:
  ai-slop/trivial-comment: "off"
  ai-slop/unsafe-type-assertion: "error"
```

Valid severity values are `"error"`, `"warning"`, and `"off"`.

### `exclude` and `include`

Defines filesystem scope for all engines:

* `exclude` (array of strings): paths and directories to ignore. Default: `["node_modules", ".git", "dist", "build", "coverage"]`.
* `include` (array of strings): explicit paths to scan. When empty (`[]`), all non-excluded supported files are scanned.

### `overrides`

Applies custom quality limits or rule severities to matching file patterns:

```yaml theme={null}
overrides:
  - files: ["legacy/**/*.ts"]
    quality:
      maxFileLoc: 800
    rules:
      ai-slop/trivial-comment: "off"
```

### `telemetry`

Controls telemetry delivery to Raigal Cloud:

```yaml theme={null}
telemetry:
  enabled: true
```

Set to `false` to disable outbound telemetry queueing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.