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

# canonic.yaml config schema

> Every top-level field in the project config file, and what it governs.

`canonic.yaml` is validated against `CanonicConfig` at load time. Unknown top-level fields are ignored rather than rejected. Only `version` and `project` are required: everything else defaults.

## Top-level fields

| Field         | Type                | Default                          | Governs                                                                                                                            |
| ------------- | ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `version`     | `int`               | n/a (required)                   | Config schema version; currently only `1` is recognized.                                                                           |
| `project`     | `ProjectConfig`     | n/a (required)                   | Project `name` and optional `default_connection`.                                                                                  |
| `connections` | `list[Connection]`  | `[]`                             | Configured data sources; see [Connectors](/concepts/connectors).                                                                   |
| `llm`         | `LLMConfig \| null` | `null`                           | LLM provider config; see [Configuring an LLM](/configuring-an-llm).                                                                |
| `embeddings`  | `EmbeddingConfig`   | `model: all-MiniLM-L6-v2`        | Local embedding model for knowledge vector search.                                                                                 |
| `telemetry`   | `TelemetryConfig`   | `enabled: false`                 | Opt-in telemetry flag; see [Instrumentation & evaluation](/concepts/instrumentation-and-eval#opt-in-telemetry).                    |
| `reconcile`   | `ReconcileConfig`   | propose-only                     | Auto-apply policy for ingestion; see [Ingestion & reconciliation](/concepts/ingestion-and-reconciliation#propose-only-by-default). |
| `runtime`     | `RuntimeConfig`     | `air_gapped: false`              | Air-gapped enforcement; see [LLM & embeddings runtime](/concepts/llm-runtime#air-gapped-mode--enforced-not-advisory).              |
| `logging`     | `LoggingConfig`     | `level: WARNING`, `format: text` | Log level, optional file, and text/json format.                                                                                    |

## `connections[]`

```yaml theme={null}
connections:
  - id: warehouse_pg
    type: postgres
    params: { host: localhost, port: 5432, database: analytics, schema: analytics }
    credentials_ref: env:CANONIC_PG_PASSWORD
    read_only_role: null
```

* `credentials_ref` (and `llm.api_key_ref`) must be a reference, one of `env:`, `keyring:`, or `file:`, never a literal secret; config validation rejects a literal outright.
* Postgres/Redshift connections additionally recognize `schema`/`schemas` (search path) and `tables` (glob patterns narrowing introspection), plus `fetch_column_stats: true` to merge zero-scan cardinality/null-ratio stats into the returned schema (a no-op on SQLite/DuckDB).

## `llm`

```yaml theme={null}
llm:
  provider: anthropic       # openai_compatible | anthropic | openai | github_copilot
  base_url: null            # required only for openai_compatible
  model: claude-opus-4-8
  api_key_ref: env:ANTHROPIC_API_KEY
  tasks: { reconcile: claude-opus-4-8 }   # per-task overrides: draft, reconcile, extract
```

Each provider has a fixed credential requirement, enforced at load: `openai_compatible` requires `base_url`; `openai`/`anthropic` require `api_key_ref`; `github_copilot` forbids one (device-code auth, outside `canonic.yaml`).

## `reconcile`

```yaml theme={null}
reconcile:
  auto_apply:
    enabled: false             # default: propose-only
    min_confidence: 0.95
    max_provenance: inferred   # never auto-apply over human_curated+
    never: [grain, joins, measures]
  strict_contradictions: false
```

## `runtime`

```yaml theme={null}
runtime:
  air_gapped: false
  allow_cidrs: []   # explicit private/LAN ranges for an on-prem inference host
```

When `air_gapped: true`, load-time validation additionally rejects: a public `llm.base_url`, `telemetry.enabled: true`, and any `credentials_ref`/`api_key_ref` using a non-local scheme.

## Reserved directories

Independent of `canonic.yaml` fields, every project scaffolds four committed context directories (`semantics/`, `knowledge/`, `contracts/`, `raw-sources/`) plus a git-ignored `.canonic/` local-state directory (created with `0o700` permissions).