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

# The context layer (ACF)

> Why analytics agents need a curated context layer, and the open Analytics Context Format that captures it.

## The problem context solves

An agent with warehouse access can write SQL, but it can't know that "revenue" excludes refunds,
that `dim_customer` is canonical and `customers_raw` is a staging table, or that every appointment
query should filter out no-shows. Those are decisions your analyst has already made. Without them,
the agent produces answers that look right and aren't.

A **context layer** encodes those decisions in one place the agent reads before it queries:
definitions, canonical tables, standard filters, and known caveats.

## ACF: the Analytics Context Format

Nodal's context layer is **[ACF](https://github.com/nodal-data/nodal-context/blob/main/SPEC.md)** —
an open format that is just **Markdown + YAML**, organized by business domain. It is readable by a
human in a PR and by any agent at query time. ACF is Apache-2.0; the format and the interview that
builds it are yours to keep.

<Info>
  **A context layer is one idea; ACF is one shape it can take.** The Nodal eval harness reads ACF,
  dbt models and docs, or raw markdown — so you can measure the value of context you already have,
  then adopt ACF where it helps. You are never locked into the format.
</Info>

## Interview-built, not auto-generated

The defining choice in ACF is *how the context is created*. Most tools ingest your warehouse and
query logs and **auto-generate** the definitions. Teams who measured that approach found it
net-negative — it encodes the ambiguities you were trying to remove.

Nodal instead **generates a draft with the model and has a human own the definition**:

1. **Auto-extract a draft.** Your schema and dbt models/docs seed a first draft, so the analyst
   starts from something real instead of a blank page.
2. **The analyst confirms.** In the interview, the analyst corrects each definition. Their
   confirmation — not the extraction — is what Nodal trusts.
3. **Every confirmation is also an eval pair.** Each disambiguation becomes labeled ground truth,
   so context and measurement grow together.

## What's in the repo

The open-source [`nodal-context`](https://github.com/nodal-data/nodal-context) repo contains:

| Path                        | What it is                                                         |
| --------------------------- | ------------------------------------------------------------------ |
| `SPEC.md`                   | The Analytics Context Format standard                              |
| `skills/context-interview/` | The interview skill that builds your context                       |
| `schemas/`                  | JSON Schemas that make the YAML CI-checkable                       |
| `template/`                 | The empty scaffold the interview fills in                          |
| `examples/`                 | A worked example in the ACF format                                 |
| `eval_harness/`             | The OSS eval runner and its contract                               |
| `.github/workflows/`        | Validate context, detect drift, and run the eval delta on every PR |

## Next

<CardGroup cols={2}>
  <Card title="Connect a warehouse (MCP)" icon="plug" href="/open-source/self-service-mcp">
    The one prerequisite before the interview — read-only, and Nodal never sees it.
  </Card>

  <Card title="Build your context" icon="comments" href="/open-source/build-your-context">
    Run the interview and generate your first domain.
  </Card>
</CardGroup>