canonic.yaml config schema

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.
`llm`	`LLMConfig \| null`	`null`	LLM provider config, see Configuring an LLM.
`embeddings`	`EmbeddingConfig`	`model: all-MiniLM-L6-v2`	Local embedding model for knowledge vector search.
`telemetry`	`TelemetryConfig`	`enabled: false`	Opt-in telemetry, see below and Instrumentation & evaluation.
`reconcile`	`ReconcileConfig`	propose-only	Auto-apply policy for ingestion, see Ingestion & reconciliation.
`feedback`	`FeedbackConfig`	see below	Pattern-gate and trust-cap thresholds for the E11 feedback loop, see Feedback loop (E11).
`runtime`	`RuntimeConfig`	`air_gapped: false`	Air-gapped enforcement, see LLM & embeddings runtime.
`logging`	`LoggingConfig`	`level: WARNING`, `format: text`	Log level, optional file, text/json format, and size-based rotation, see below.
`instrumentation`	`InstrumentationConfig`	see below	Size and retention limits for the local event log `.canonic/events.jsonl`.
`mcp`	`McpConfig`	`auth: { tokens: [] }`	Bearer-token auth for the MCP daemon’s `http` transport, see below.

version and project are the only fields canonic actually needs to boot. Everything else configures a specific subsystem and can be left out entirely for a local, single-user setup: connections is empty until you add a data source, llm is null until you configure a provider, and the rest fall back to safe local defaults. embeddings and telemetry rarely need touching, they exist mostly for opt-in tuning and privacy control rather than day-to-day project setup.

Environment variables in values

Any value in canonic.yaml can be written as env:VAR, for example host: env:DB_HOST or port: env:DB_PORT. canonic replaces the whole value with the variable’s content when it loads the file, so one committed config can serve dev, staging and production. Only whole values are substituted, there is no ${VAR} syntax and no default value. An unset or empty variable stops the load with an error that names the exact location, such as connections[0].params.host. Keys ending in _ref (credentials_ref, api_key_ref, token_ref and so on) are not substituted at load time. They stay secret references and are resolved only when the secret is actually needed. canonic setup keeps the env:VAR spelling when it edits an existing file, so resolved values are never written back. The diagnostic bundle from canonic audit --bundle shows the resolved values, so a bug report says which environment it came from.

`connections[]`

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

Field	Type	Default	Governs
`id`	`str`	n/a (required)	Unique identifier for this connection. Referenced from `semantics/<connection-id>/`, `project.default_connection`, and the `target_connection` of a dbt or ossie connection.
`type`	`str`	n/a (required)	Connector type, e.g. `postgres`, `mysql`, `clickhouse`, `redshift`, `snowflake`, `databricks`, `sqlite`, `duckdb`, `dbt`, `ossie`. Must match a registered connector or the connection fails to load with `connection_error`.
`params`	`dict[str, Any]`	`{}`	Connector-specific settings such as `host`, `port`, `database`, or `schema`. What’s valid here depends entirely on `type`.
`credentials_ref`	`str \| null`	`null`	Where to resolve this connection’s secret from, never the secret itself. See below.
`read_only_role`	`str \| null`	`null`	The session role a `snowflake` connection connects with, which should only hold `SELECT` grants. Accepted and stored for other connectors but not consulted by them. Without it, a `snowflake` connection relies on the SQL parse guard alone and `canonic connection test` warns about that.
`rls_enforced`	`bool`	`false`	Operator attestation that this connection’s warehouse enforces row-level security independent of canonic (per-tenant credentials, or warehouse-native RLS). canonic cannot verify this claim, only trust it. Must be `true` for `run_sql` to be served on this connection once a tenancy policy is active, see the `run_sql` gate.

A connection is how canonic reaches an actual data source. id is the name every other file uses to point back at it, type picks which connector implementation handles it, and params carries whatever that connector needs to connect, host and port for a warehouse, a manifest path for dbt. credentials_ref keeps the secret itself out of canonic.yaml entirely, instead of a password you write a pointer to where the password actually lives.

credentials_ref must be a reference, one of env:, keyring:, file:, or provider:, never a literal secret. Config validation rejects a literal outright. llm.api_key_ref and the MCP auth refs accept the same schemes minus provider:, see Dynamic credentials below.
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).
mysql connections require host and user. Optional: port (default 3306), database (dbname is an alias, and without it every database the user can see is introspected), schemas/tables (narrowing introspection, as above), ssl (true verifies the server certificate against the system trust store), row_limit and statement_timeout_ms. credentials_ref resolves to the password. A MySQL schema is a database, so relations are named database.table. The driver is not installed with canonic, install it with pip install 'canonic[mysql]'.
clickhouse connections require host. Optional: port (default 8123, or 8443 when secure is set), user (default default), database (dbname is an alias), secure (true connects over HTTPS and verifies the server certificate), schemas/tables (narrowing introspection, as above), row_limit and statement_timeout_ms. credentials_ref resolves to the password. A ClickHouse schema is a database, so relations are named database.table. canonic uses the HTTP(S) interface, not the native port. The driver is not installed with canonic, install it with pip install 'canonic[clickhouse]'.
snowflake connections require account and user, and database for introspection. Optional: warehouse, schema, role (overridden by read_only_role), schemas/tables (narrowing introspection, as above), row_limit and statement_timeout_ms. credentials_ref resolves to the password. For key-pair auth set private_key_path to a PEM file, and credentials_ref then only holds the optional key passphrase. The driver is not installed with canonic, install it with pip install 'canonic[snowflake]'.
databricks connections require server_hostname and http_path, and catalog for introspection. Optional: schema, schemas/tables (narrowing introspection, as above), row_limit and statement_timeout_ms. credentials_ref resolves to the access token. read_only_role is not used, because Databricks has no role to switch to. The driver is not installed with canonic, install it with pip install 'canonic[databricks]'.
dbt connections recognize manifest_path (path to the compiled manifest.json, default manifest.json) and target_connection (the id of the physical, queryable connection whose tables this manifest describes, see Connectors). target_connection must name a connection actually declared in connections[]. An unknown id fails config validation at load time. Omitting it falls back to the dbt connection’s own id.

  - id: jaffle_dbt
    type: dbt
    params: { manifest_path: dbt/manifest.json, target_connection: warehouse_pg }

ossie connections require paths (a list of Apache Ossie model files or glob patterns, relative to the project root, a single string is accepted too) and target_connection. Unlike dbt, target_connection has no fallback. It must name a declared connection whose type is queryable (postgres, sqlite, duckdb and so on), otherwise config validation fails at load time. Supported spec versions are 0.1.x (root semantic_model array) and 0.2.0.dev0 (one flat model per file). A file with any other version fails canonic connection test, and canonic ingest ingests nothing from it. URL sources are not supported yet.

  - id: sales_ossie
    type: ossie
    params: { paths: ["models/*.ossie.yaml"], target_connection: warehouse_pg }

Dynamic credentials

env:, keyring: and file: all resolve once, to a fixed string that stays valid until someone rotates it by hand. That does not fit a credential the cloud provider issues with a built-in expiry. A Redshift IAM credential lives roughly 15 to 60 minutes, so a connection string built when the daemon starts is dead well before the daemon is. provider:<name> covers that case. The name selects a registered credential provider, which fetches a fresh credential from the issuer and reports when it expires. Canonic caches it and refetches shortly before it runs out, so a long-lived daemon keeps working without an operator touching anything.

connections:
  - id: warehouse_rs
    type: redshift
    params:
      cluster_id: analytics-cluster
      db_user: canonic_ro
      region: eu-central-1
      host: analytics-cluster.abc123.eu-central-1.redshift.amazonaws.com
      dbname: analytics
    credentials_ref: provider:aws-iam-redshift

No secret value appears in canonic.yaml. cluster_id, db_user and region are not secrets, they tell the provider how to fetch a credential, the same way a file: path is not a secret.

Provider	Fetches	Required params
`aws-iam-redshift`	Redshift IAM credentials, provisioned (`GetClusterCredentials`) or serverless (`GetCredentials`)	`cluster_id` + `db_user`, or `workgroup_name`. Optional: `region`, `dbname`, `duration_seconds` (default 3600), `auto_create`

Things worth knowing before you reach for it:

Redshift and Snowflake only, today. provider: refs are resolved on every connect, and Redshift and Snowflake are the only connectors that do that so far. The only provider that ships, aws-iam-redshift, issues Redshift credentials, so a Snowflake connection has no provider to point at yet. Pointing any other connector at a provider: ref fails with a clear error rather than silently freezing the first credential it ever saw.
Not for inbound auth. llm.api_key_ref, mcp.auth.tokens[].token_ref and mcp.auth.oauth.client_secret_ref are resolved once at startup and held. A provider credential there would go stale rather than refresh, so config validation rejects it.
aws-iam-redshift needs boto3, which canonic does not install. pip install boto3. Credentials for the AWS call itself come from the standard boto3 chain (instance role, AWS_PROFILE, environment).
Rejected under air_gapped: true. Fetching from AWS is network egress, which is what that mode exists to prevent.
Nothing is written to disk. A fetched credential lives in memory for the life of the process that fetched it. A CLI invocation and a running daemon each fetch their own.

`llm`

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

Field	Type	Default	Governs
`provider`	`str`	n/a (required)	`openai_compatible` \| `anthropic` \| `openai` \| `github_copilot`. Picks which credential rule below applies and how the call is routed.
`base_url`	`str \| null`	`null`	Endpoint to call. Required for `openai_compatible`, since there’s no default host to fall back to. Optional for the hosted providers, which otherwise reach their own default endpoint.
`model`	`str`	n/a (required)	Model identifier passed straight through to the provider, e.g. `claude-opus-4-8`.
`api_key_ref`	`str \| null`	`null`	Reference to the API key, never the key itself. Required for `openai`/`anthropic`, forbidden for `github_copilot` since that provider authenticates itself outside `canonic.yaml`.
`tasks`	`dict[str, str]`	`{}`	Per-task model overrides keyed by task name (`draft`, `reconcile`, `extract`), letting you route a cheaper or more capable model to a specific step instead of using `model` everywhere.

Each provider has a fixed credential requirement, enforced at load. openai_compatible requires base_url, openai and anthropic require api_key_ref, and github_copilot forbids one entirely since it authenticates through a device-code flow that never touches canonic.yaml. Getting this wrong fails config validation immediately rather than surfacing as a runtime error the first time canonic tries to call the model.

`reconcile`

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

Field	Type	Default	Governs
`auto_apply.enabled`	`bool`	`false`	Whether `canonic ingest` may apply a proposal automatically instead of leaving it for review. Off by default, ingestion is propose-only until you opt in.
`auto_apply.min_confidence`	`float` (0 to 1)	`0.95`	The minimum confidence score a proposal needs before it’s eligible for auto-apply. Anything below this threshold is always left for manual review, regardless of `enabled`.
`auto_apply.max_provenance`	`Provenance`	`inferred`	The highest existing provenance tier auto-apply is allowed to overwrite. Since it’s capped at `inferred`, a fact already marked `human_curated` or `board_approved` can never be silently rewritten, no matter how confident the new proposal is.
`auto_apply.never`	`list[str]`	`[grain, joins, measures]`	Field categories that always require human review, even if they’d otherwise pass the confidence and provenance checks. These are the structural fields most likely to break a query silently if an automated proposal gets them wrong.
`strict_contradictions`	`bool`	`false`	When `true`, a run that surfaces any flagged contradiction fails with exit code 14 instead of just recording it. Meant for CI, where you want ingestion to gate on data-model disagreements rather than pass through them.

reconcile only governs how eagerly canonic ingest is allowed to write changes back to semantics/. It has no effect on what evidence gets collected, only on whether a resulting proposal can be applied without a human looking at it first. See Ingestion & reconciliation for how proposals are generated in the first place.

`feedback`

feedback:
  pattern_min_count: 2        # distinct-enough wrong_definition outcomes before evidence is minted
  pattern_window_days: 90     # window the count is evaluated over
  pattern_min_markers: 1      # distinct markers (people/agents) required within that window
  trust_cap_window_days: 90   # how long a confirmed wrong_definition caps the trust tier at caution

Field	Type	Default	Governs
`pattern_min_count`	`int` (`ge=1`)	`2`	How many distinct-enough `wrong_definition` outcomes on a binding are required before `canonic ingest` mints E4 contradiction evidence.
`pattern_window_days`	`int` (`ge=1`)	`90`	The rolling window `pattern_min_count` is evaluated over.
`pattern_min_markers`	`int` (`ge=1`)	`1`	How many distinct `marked_by` roles must be represented within the window for the pattern to count (guards against one noisy marker).
`trust_cap_window_days`	`int` (`ge=1`)	`90`	How long a recent confirmed `wrong_definition` outcome caps the binding’s E14 trust tier at `caution`, independent of the evidence gate above.

See Feedback loop (E11) for how these thresholds are used.

`telemetry`

telemetry:
  enabled: false
  endpoint: null                    # e.g. https://collector.example.com/ingest
  transport_acknowledged: false
  auth_token_ref: null              # e.g. env:CANONIC_TELEMETRY_TOKEN

Field	Type	Default	Governs
`enabled`	`bool`	`false`	Opt-in flag. Forced to `false` under `runtime.air_gapped: true` (load-time rejection, not just a no-op).
`endpoint`	`str \| null`	`null`	Destination URL for `canonic audit --telemetry-send`. Must start with `http://` or `https://` when set. No default, canonic never guesses a collector.
`transport_acknowledged`	`bool`	`false`	Attestation that this project has reviewed the exact aggregate payload (`canonic audit --telemetry-preview`) before allowing a real send. canonic cannot verify that a review happened. This is a project-level policy decision recorded in `canonic.yaml`.
`auth_token_ref`	`str \| null`	`null`	Optional bearer token for `endpoint`, resolved the same way as `credentials_ref` (`env:`/`keyring:`/`file:`, never a literal).

canonic audit --telemetry-send only sends when all of enabled, endpoint, and transport_acknowledged are set, and runtime.air_gapped is false. Missing any one of them fails closed with a structured error (telemetry_not_configured). Nothing is ever sent implicitly. See Instrumentation & evaluation for the full payload shape and content-safety guarantees.

`runtime`

runtime:
  air_gapped: false
  allow_cidrs: []   # explicit private/LAN ranges for an on-prem inference host

Field	Type	Default	Governs
`air_gapped`	`bool`	`false`	Turns on the enforced privacy guarantee: every model endpoint must resolve locally or to an allowlisted range, and no context may leave the machine. This is checked at load time, not just documented behavior, so a misconfigured project refuses to start rather than silently phoning home.
`allow_cidrs`	`list[str]`	`[]`	Additional private/LAN CIDR ranges to trust under `air_gapped`, for a setup where inference runs on a separate on-prem host rather than the local machine. Only consulted when `air_gapped` is `true`. By default, air-gapped mode trusts localhost only.

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. The check runs once, at config load, so there’s no window where a project starts up in a state that could leak context off the machine. Telemetry has no allowlist path the way llm.base_url does via allow_cidrs. Under air_gapped, it is hard off regardless of telemetry.endpoint/transport_acknowledged.

`logging`

logging:
  level: WARNING
  file: null                # null logs to stderr
  format: text              # text | json
  max_bytes: 52428800       # 50 MB, 0 disables rotation
  backup_count: 5

Field	Type	Default	Governs
`level`	`str`	`WARNING`	Log level of the `canonic` logger. Override with `CANONIC_LOG_LEVEL`.
`file`	`str \| null`	`null`	Log file path. Without it, records go to stderr, never stdout, because stdio MCP carries JSON-RPC there. Override with `CANONIC_LOG_FILE`.
`format`	`text \| json`	`text`	One text line or one JSON object per record. Override with `CANONIC_LOG_FORMAT`.
`max_bytes`	`int`	`52428800`	Rotates `file` at this size. Also rotates the MCP daemon’s `.canonic/mcp.log` each time the daemon starts. `0` disables rotation.
`backup_count`	`int`	`5`	Number of rotated files kept (`canonic.log.1`, `canonic.log.2`, and so on). The oldest one is deleted.

The daemon writes .canonic/mcp.log through an inherited file descriptor, so it can only rotate on daemon start, not while the daemon runs. Set logging.file if you need rotation during a long-running daemon.

`instrumentation`

instrumentation:
  events:
    max_bytes: 52428800     # 50 MB, 0 disables rotation
    retention_days: null    # null keeps segments forever
    max_segments: null      # null keeps all segments
    compress: true

Field	Type	Default	Governs
`events.max_bytes`	`int`	`52428800`	Size at which the active `.canonic/events.jsonl` rotates. `0` disables rotation.
`events.retention_days`	`int \| null`	`null`	Deletes segments whose rotation time is older than this many days.
`events.max_segments`	`int \| null`	`null`	Keeps only this many of the newest segments.
`events.compress`	`bool`	`true`	Gzips segments (`events-<UTC>.jsonl.gz`).

Rotation moves served_answer events into a segment. Funnel, outcome, and reconcile events stay in the active file, so limits never affect onboarding state or feedback history. Retention only deletes whole segments and is evaluated when a rotation happens. See The event log. This applies equally under runtime.air_gapped: true. The log is always local, so nothing else bounds its size.

`mcp`

mcp:
  auth:
    tokens:
      - client_id: alice
        token_ref: env:CANONIC_MCP_TOKEN_ALICE
      - client_id: bob
        token_ref: env:CANONIC_MCP_TOKEN_BOB
      - client_id: merchant-4711-agent
        token_ref: env:CANONIC_MCP_TOKEN_4711
        claims: { merchant_id: '4711', roles: [merchant_viewer] }   # tenancy/RBAC only
    oauth:
      mode: proxy   # proxy | jwt
      issuer_url: https://idp.example.com
      client_id: canonic-mcp
      client_secret_ref: env:CANONIC_OAUTH_CLIENT_SECRET   # proxy mode only
      scopes: [openid, profile, email]
      base_url: https://canonic.internal.example.com       # proxy mode only, the daemon's own public URL
      verify_id_token: false                                # proxy mode only, see below
      claim_mapping:                                        # tenancy/RBAC only
        merchant_id: https://example.com/merchant_id
        roles: roles
      identity_assertion:                                   # proxy mode only, headless/agentic clients
        trusted_issuers: [https://login.acme-corp.com]
        audience: canonic-mcp
  tasks:                                                    # http transport only
    enabled: false
    backend: memory   # memory | redis
    url: null          # required (and only used) when backend is redis
  cache_ttl_seconds: 300   # 0 disables listing cache hints entirely

Field	Type	Default	Governs
`auth.tokens`	`list[McpTokenEntry]`	`[]`	Bearer tokens accepted by the MCP daemon’s `http` transport, one entry per client.
`auth.tokens[].client_id`	`str`	n/a (required)	Name attributed to that token’s caller in `.canonic/events.jsonl`, so usage can be traced per user rather than per daemon instance.
`auth.tokens[].token_ref`	`str`	n/a (required)	Reference to the token’s value, never the token itself, resolved the same way as `credentials_ref`.
`auth.tokens[].claims`	`dict[str, Any]`	`{}`	Claims carried by this static token (e.g. `{merchant_id: "4711", roles: ["merchant_viewer"]}`), keyed by the raw claim name a tenancy/role policy’s `claim` field names. Static tokens carry claims inline since there’s no IdP to ask.
`auth.oauth`	`McpOAuthConfig \| null`	`null`	OAuth 2.1 auth for the MCP daemon’s `http` transport, delegated to `fastmcp`. Independently optional from `auth.tokens`. Both configured is a supported state, not just tolerated.
`auth.oauth.mode`	`"proxy" \| "jwt"`	n/a (required)	`proxy`: presents a DCR-compliant OAuth server to MCP clients and relays the login to the upstream IdP (Authorization Code + PKCE), the mode most SSO deployments use. `jwt`: the IdP hands the client a JWT directly and the daemon only verifies its signature against the IdP’s JWKS, no proxy state.
`auth.oauth.issuer_url`	`str`	n/a (required)	The IdP’s base URL. In `proxy` mode, `mode: proxy` discovers endpoints from `issuer_url + /.well-known/openid-configuration`.
`auth.oauth.client_id`	`str \| null`	`null`	Required in `proxy` mode: the client registered with the upstream IdP. Not used in `jwt` mode.
`auth.oauth.client_secret_ref`	`str \| null`	`null`	`proxy` mode only. Reference to the upstream client’s secret, resolved the same way as `credentials_ref`. Rejected in `jwt` mode (no proxy to authenticate as).
`auth.oauth.scopes`	`list[str]`	`[]`	OAuth scopes requested from the IdP / required on incoming tokens.
`auth.oauth.base_url`	`str \| null`	`null`	Required in `proxy` mode: the daemon’s own public URL (where the IdP redirects back to). Rejected in `jwt` mode.
`auth.oauth.audience`	`str \| null`	`null`	`jwt` mode only. Expected token audience. Recommended: without it, any token the IdP issued for any resource is accepted, not just this daemon.
`auth.oauth.jwks_uri`	`str \| null`	`null`	`jwt` mode only. Skips OIDC discovery for IdPs that don’t publish `/.well-known/openid-configuration`.
`auth.oauth.verify_id_token`	`bool`	`false`	`proxy` mode only. Verifies the upstream OIDC id_token instead of the access_token. Rejected in `jwt` mode. See below.
`auth.oauth.claim_mapping`	`dict[str, str]`	`{}`	Maps a tenancy/role policy’s raw `claim` name (e.g. `merchant_id`) to the namespaced claim key the IdP actually issues (e.g. `https://example.com/merchant_id`), which most IdPs require for custom claims. A `claim` absent from this mapping is looked up under its own name unchanged.
`auth.oauth.identity_assertion`	`McpIdentityAssertionConfig \| null`	`null`	`proxy` mode only. Accepts an IdP-signed identity assertion (SEP-990 ID-JAG) in place of the interactive Authorization Code + PKCE flow, for headless/agentic clients that already hold an established identity from the IdP. Rejected in `jwt` mode.
`auth.oauth.identity_assertion.trusted_issuers`	`list[str]`	n/a (required, non-empty)	Issuer (`iss`) values the proxy accepts on an assertion. Each entry must start with `http://` or `https://`.
`auth.oauth.identity_assertion.audience`	`str \| null`	`null`	Expected `aud` value on the assertion. Defaults to this daemon’s own issuer identifier when omitted.
`tasks.enabled`	`bool`	`false`	Runs `query`, `run_sql` and `run_report` as optionally-async tools on `http` transport, so a client that declares the `io.modelcontextprotocol/tasks` capability can poll a long-running query instead of holding the request open. A client that doesn’t opt in still gets a synchronous result. Requires the `canonic[tasks]` extra installed. The daemon refuses to start otherwise. Never applies to `stdio`.
`tasks.backend`	`"memory" \| "redis"`	`"memory"`	The Docket backend running task state. `memory` is single-process, good enough for one daemon instance. `redis` coordinates tasks across multiple daemon processes/workers.
`tasks.url`	`str \| null`	`null`	Docket backend URL (e.g. `redis://localhost:6379/0`). Required when `backend` is `redis`, rejected when `backend` is `memory`.
`cache_ttl_seconds`	`int`	`300`	How long (in seconds) a client may treat a listing (`tools/list`, `resources/list`, `prompts/list`, `server/discover`) as fresh, a SEP-2549 client-side cache hint applied uniformly across all four. `0` disables the hint entirely, byte-identical to a server that never set one. Must be `>= 0`. The scope is always `private`, never shared across callers, and tool call results are unaffected, only listings.

This block only matters for canonic mcp start --transport http. The default stdio transport is a local subprocess and needs no auth, process-level trust is enough. http transport is network-reachable, though, so it refuses to start unless at least one mechanism resolves: a token here (or via the --token-ref CLI override) and/or auth.oauth. When both are configured, a request is checked against the static token map first (no network call), falling through to OAuth verification if no static token matches: the two stay independently revocable, a token entry by editing canonic.yaml, an OAuth-issued token at the IdP. canonic mcp status reports which mechanism(s) are active on a running daemon. See Connecting your agent for the full remote-deployment walkthrough, and Marketplace with Keycloak for a working proxy-mode example against a real IdP.

auth.oauth.verify_id_token matters more than its default suggests. In proxy mode, OIDCProxy verifies the upstream IdP’s access token by default, but many IdPs (Google, GitHub, some Okta setups) issue that as an opaque, non-JWT string, which fails verification outright rather than just producing a poor client identity. Setting verify_id_token: true verifies the id_token instead, which the OIDC spec guarantees is always a standard JWT carrying sub/email claims. This also controls what ends up as client_id in .canonic/events.jsonl: with it off, client_id comes from the access token’s client_id/azp/sub claim (often an opaque subject id). With it on, from the id_token’s, which is far more likely to be a meaningful identity like an email address.

Reserved directories

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

Directory	Contents	Schema reference
`semantics/`	Hand-drafted-then-reviewed relations: grain, columns, measures, dimensions, joins.	Semantic source schema
`knowledge/`	Markdown pages with YAML frontmatter carrying business meaning.	Knowledge page schema
`contracts/`	Human-owned metric bindings, guardrails, finality rules, and assertions.	Contract schema
`raw-sources/`	System-generated, committed audit trail, never hand-edited.	See below.

contracts/policies/ (tenancy.yaml / roles.yaml) is optional. Its presence is the feature switch for tenancy & access control, and a project without it behaves exactly as it did before that layer existed.

`raw-sources/<connection-id>/evidence.jsonl`

Not a hand-authored config file: it’s a deterministically-sorted, one-JSON-object-per-line snapshot of the evidence ingestion collected for a connection, written by DiskSnapshotStore so re-running ingestion against the same source yields a byte-identical file. Each line validates against EvidenceItem:

Field	Type	Governs
`source`	`str`	The connection id this evidence came from.
`kind`	`str` (open set)	`relation_schema` \| `observed_query` \| `definition` \| `doc_evidence` \| `usage_evidence` \| `answer_outcome`, or an unrecognized future kind (accepted, just not dispatched).
`acquisition_tier`	`AcquisitionTier`	Curation rank of the evidence, e.g. `live`, `modeling`, `query_history`, `declarative`, `sample`, `hand_authored`.
`payload`	`dict[str, Any]`	Shape depends on `kind`, e.g. a `RelationSchema` for `relation_schema`.
`source_fingerprint`	`str`	sha256 identifying the exact evidence content, for dedup and drift detection.
`observed_at`	`datetime`	When the evidence was collected.

This is what canonic ingest reads to draft proposals against semantics/. You’d only ever read it, not write it.

Getting Started

Concepts

CLI Reference

MCP / Agent Integration

Guides

Reference

canonic.yaml config schema

Top-level fields

Environment variables in values

`connections[]`

Dynamic credentials

`llm`

`reconcile`

`feedback`

`telemetry`

`runtime`

`logging`

`instrumentation`

`mcp`

Reserved directories

`raw-sources/<connection-id>/evidence.jsonl`

​Top-level fields

​Environment variables in values

​connections[]

​Dynamic credentials

​llm

​reconcile

​feedback

​telemetry

​runtime

​logging

​instrumentation

​mcp

​Reserved directories

​raw-sources/<connection-id>/evidence.jsonl

Top-level fields

Environment variables in values

`connections[]`

Dynamic credentials

`llm`

`reconcile`

`feedback`

`telemetry`

`runtime`

`logging`

`instrumentation`

`mcp`

Reserved directories

`raw-sources/<connection-id>/evidence.jsonl`