> ## 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.
# Introduction
> The context layer that lets AI agents query your data correctly.
Point canonic at your database and it builds the context an agent needs to answer data questions accurately: definitions, relationships, business meaning, and the guardrails that stop confidently-wrong answers. It keeps that context up to date as your data changes, and it never touches your warehouse beyond reading it.
Package and image names shown throughout these docs illustrate the shape of each install channel; exact names are confirmed per release.
## The problem
An AI agent connected straight to your warehouse sees **tables and columns**, not **meaning**. It doesn't know that `revenue` lives in `orders.amount` but excludes refunds, that "active customer" has a specific definition your finance team agreed on, or that summing a daily balance across a week is nonsense. So it guesses. A confidently-wrong answer is the worst kind of wrong: a confident, well-formatted, *incorrect* number that looks right.
Schema access makes an agent *fluent*. It doesn't make it *correct*.
## Why you need a context layer
**❌ Without Canonic (the guess):**
```
Agent query: SELECT SUM(amount) FROM orders;
Result: $1,450,320
The problem: The sum includes refunded orders and sales tax, making the
number wrong by 12%. The agent delivers a confident, well-formatted,
and completely incorrect metric.
```
**✅ With Canonic (the truth):**
```
Agent request: "Give me revenue"
Canonic compiles: SELECT SUM(amount) FROM orders
WHERE status = 'completed' AND type != 'tax';
Result: $1,274,500 [certified fresh, excludes refunds and tax]
The agent gets the exact right number, with the business logic and
caveats baked in—and it knows the data freshness and which guardrails
applied. Zero guessing.
```
## What canonic does
canonic sits between your data and your agents as a **context layer**: an auto-built, auto-maintained, version-controlled description of what your data *means* and how to query it *safely*. Agents ask for a metric by name; canonic resolves it to the canonical definition, compiles correct read-only SQL, runs it, and returns the answer **with the caveats that make it trustworthy**: how fresh the data is, which guardrails applied, whether the number is final or provisional.
When canonic isn't sure, it **refuses and asks** instead of guessing. A confidently-wrong answer is the one outcome it's built to never produce.
## Why canonic, not something else
| Instead of… | You get… | canonic gives you… |
| ------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Giving the agent raw schema/SQL access | Fluency without correctness; it guesses definitions and picks wrong tables | Resolved canonical definitions, enforced guardrails, never a silent wrong number |
| Hand-building a semantic layer from scratch | Months of modeling before any value | Context auto-drafted from your live schema on day one; you review, not author from zero |
| Migrating onto a new metrics platform | Lock-in and a rebuild | canonic **ingests** your dbt / BI tools / docs; it feeds your existing stack, it doesn't replace it |
| A hosted "AI analytics" SaaS | Your data and definitions leaving your environment | Local-first, fully **air-gapped-capable**: nothing has to leave your machine |
What makes it different in one line: **canonic builds the context for you, keeps it honest, and refuses to lie when it isn't sure.**
## The three layers
canonic's context lives in three committed surfaces: plain files in your git repo, reviewed like code. Each answers a different question.
| Layer | File | Answers | Owned by |
| ------------- | --------------------- | ---------------------------------------------------------------------- | --------------- |
| **Semantics** | `semantics/**/*.yaml` | "How do I query this safely?": tables, types, grains, joins, measures | auto-maintained |
| **Knowledge** | `knowledge/**/*.md` | "What does this mean to the business?": definitions, caveats, policies | auto-maintained |
| **Contracts** | `contracts/**/*.yaml` | "Which definition is canonical, and what must the answer obey?" | human-owned |
**The split rule:**
* Changes how the SQL *runs* → **semantics**.
* A human needs it to *trust* the answer → **knowledge**.
* Governs *which* definition is authoritative or *what an answer must satisfy* → **contracts**.
The key idea: a knowledge page *explains* why "amount includes refunds unless filtered." A contract *makes the SQL obey* it. Documented caveats become enforced guardrails, so the warning can't be silently ignored.
## What you can rely on
* **Read-only.** canonic never mutates your warehouse. It reads, it never writes back.
* **Propose-only.** It never silently edits your context: every change is a reviewable diff anchored to evidence.
* **Refuse-and-ask.** Ambiguous or unsafe? It returns a structured reason, not a guess.
* **No LLM in the answer path.** Queries compile deterministically: the same question always produces the same SQL. An LLM only helps *draft* context, never *compute* an answer.
* **Local-first & air-gapped-capable.** Run entirely on your machine with a local model and local embeddings; nothing has to leave your network.
* **Measurable.** A local event log tracks accuracy, freshness, and answer quality, so "trustworthy" is something you can check, not just claim.
Install the canonic CLI via npm, Homebrew, or Docker.
Get your first answer in minutes with a local SQLite or DuckDB file.