Home · Quick start · Editor · charter.yaml · Sources · Agent · Guides · Evals · Audit · Policies · CLI · MCP · Workspace · Desktop · About · FAQ

Guides are the things you’d tell a new analyst on their first day: “revenue is net of refunds”, “exclude accounts with region = ‘ZZ’”, “order_date is when it was placed, created_at is a system timestamp.” Agents need exactly the same briefing — and with DataCharter, you write it once and every agent gets it.

Where guides live

Plain markdown files in your workspace’s guides/ directory:

guides/
  overview.md      # created by `datacharter init` with a commented template
  analytics.md     # yours — any *.md file here is a guide

They are ordinary files: version them with the contract, review edits in PRs, and manage them in the app’s Guides panel — create (+ New), edit, Save, and Delete — or in any editor. Per-table notes can also live in the contract itself, as a source’s context: map — those surface in describe_table, right where an agent is looking at that table.

Who reads them

Every agent surface, automatically:

• the built-in chat and Claude Code mode get guides in their system context;
• MCP clients (Claude Desktop, Cursor, Cline, …) receive them in the protocol’s initialize instructions field — no client configuration;
• comment-only or empty guide files are skipped, so the init template is inert until you write something real.

Let the guide write itself

datacharter suggest            # propose guide lines from your query history
datacharter suggest --apply    # append accepted lines to your guides

suggest mines the workspace’s local query history for habits you repeat — a filter you always apply, a join you always use — and turns each into a proposed guide line with the evidence attached. It runs offline; no model is involved. It needs some accumulated history to fire, and it skips habits your guides already cover — a quiet run means you’re covered, not broken. You review every line; nothing ships without you.

Prove the guides earn their keep

datacharter eval --compare-guides
#   100% passed  (guides off: 40%  →  lift: +60%)

Evals can run your whole suite with guides on and off and report the lift — the difference your written context makes to agent accuracy, on your data, in one number.

One caution

Guides are sent to agents, so treat them like the contract: no secrets, no real customer data in examples. datacharter scan checks guide files for literal PII and warns before it ships (add --strict to fail CI on it).

Next: Evals — measure agent accuracy →