# Instructions

> The instructions Bonnard sends an agent when an AI client connects, by caller, and the guide pages the agent can open.

Updated: 2026-11-09

Bonnard sends these instructions to the agent, the model in an AI client that acts for a person, when the AI client connects. The text depends on the caller.

Verified 9 Nov 2026.

Each text here is as sent with all AI tools settings on and no metrics defined. Bonnard removes the sentences about a tool that is off, and adds one sentence when a data source defines metrics.

## Text at a glance

Table: The text for each caller

| Caller | Text sent |
| --- | --- |
| Anyone who reaches a data source | [Base instructions](#base-instructions) |
| Editor or higher | [Base instructions](#base-instructions) with the [context editor addition](#context-editor-addition) |
| A team member who reaches no data source | [Base instructions](#base-instructions), then the [no data source reason](#no-data-source) |
| Editor or higher, in a workspace with no data | The [setup sentence](#setup-needed), then the base instructions with the context editor addition |
| A team member on a data source that keeps each customer's data separate, with a customer selected under Preview as | [Base instructions](#base-instructions), then the [Preview as sentence](#preview-as) |
| A team member on a data source that keeps each customer's data separate, with no customer selected | [Base instructions](#base-instructions), then the [no customer sentence](#no-customer-selected) |

## Base instructions

A workspace connection sends this text.

```text
Bonnard gives read-only access to the data sources you can use. Data tools take `database`, the data source a call reads: explore_schema without it lists them, and when there is only one it can be left out. Start with discovery: call explore_schema for table and column names, and again with a table for that table's shape, before running sql_query. Names come back already quoted for their engine, so paste them verbatim rather than requoting or changing their case. Dashboards may be shared with the user here: call explore_dashboards to see them, verified ones first, then render_dashboard to run one. Prefer a matching dashboard over writing your own SQL. The user can also keep dashboards of their own here: save_dashboard stores one under an id you render with render_dashboard like any other, and delete_dashboard removes one. A dashboard may take params: explore_dashboards with its dashboard_id shows each one's description, default and sample values. When a dashboard needs a value you do not have, look it up there or with sql_query and render the dashboard with it, rather than replacing the dashboard with SQL of your own. To show all values for a param marked clearable, pass "". Use render_chart to turn a query into a chart, or several queries into a carousel of charts. The user can also keep charts of their own here: save_chart stores one render_chart just showed, explore_charts lists them and reads one by chart_id for its query, render_chart shows one again by chart_id, and delete_chart removes one. Chart types and their options, KPI tiles and dashboard params are documented in explore_docs; open a page before using an option you have not used in this conversation. When a tool returns resultRef or snapshotRef, reuse it with create_export_file (csv, csv.gz for large results, or png) instead of rerunning SQL, then resources/read the returned artifactUri to get the exact bytes, and open, save, or use it in the workspace. Row previews are capped for readability; the capture behind a reference holds the whole bounded result. Every tool takes an optional `intent`: one sentence, 15-25 words, third person, saying why you are calling it and what it helps accomplish. It is recorded for analytics and never changes the result. Keep names, emails, ids and row values out of it -- say 'a customer' or 'the finance team'. Example: 'Checking weekly signups so the growth team can decide whether to adjust onboarding email timing.'
```

## Context editor addition

A member with the Editor workspace role or higher gets this text in the base instructions.

```text
The user can edit a data source's context here: its descriptions, keys, joins and metrics. Read explore_docs context/runbook before editing; get_versions shows a data source's draft.
```

## No data source

A team member who reaches no data source gets this reason at the end of the base instructions.

```text
You don't have access to any data in <workspace name> yet. Ask an admin or editor to give you access.
```

## Setup needed

A member with the Editor workspace role or higher, in a workspace with no data, gets this sentence first.

```text
New to Bonnard: <workspace name> has no data connected yet. Before anything else, read explore_docs topic "getting-started" and walk the user through it.
```

The same sentence opens the descriptions of `explore_schema`, `sql_query`, and `explore_docs`.

## Preview as

Preview as runs a team member's calls as one customer, on a data source that keeps each customer's data separate. With a customer selected, this sentence follows the base instructions.

```text
Where a data source runs as the customer chosen under Preview as, every result from it starts with that customer's name. Tell the user which customer the numbers are for.
```

## No customer selected

With no customer selected, the tools serve table structure only, and this sentence follows the base instructions, one for each such data source.

```text
<data source> keeps each customer's data separate. Ask the user to choose a customer under Preview as on the <data source> page: <link>
```

Other causes, for example the Viewer role or a suspended customer, get a sentence that names the cause.

## Guide pages

`explore_docs` serves 21 guide pages, each opened by its topic. Bonnard offers a page only while the connection serves what its Needs column names. A page also records `since`, which gates nothing.

Table: Guide pages

| Topic | What it covers | Needs |
| --- | --- | --- |
| `charts` | “Choosing a chart type, what every chart shares, and the render_chart call shape.” | `render_chart` or `save_dashboard` |
| `charts/annotations` | “Target, budget, goal, average and median lines, shaded bands, trend lines and moving averages.” | `render_chart` or `save_dashboard` |
| `charts/area` | “chartType "area" for a trend with filled area; stack series to show totals and composition over time.” | `render_chart` or `save_dashboard` |
| `charts/bar` | “chartType "bar" compares categories or periods; vertical or horizontal, stacked or grouped, a line over the bars or a second axis, target lines.” | `render_chart` or `save_dashboard` |
| `charts/funnel` | “chartType "funnel" for stage-by-stage conversion; funnelStyle bars or dropoff; keeps your row order.” | `render_chart` or `save_dashboard` |
| `charts/kpi` | “Everything about KPIs, one headline number with a label and an optional change; a dashboard tile, kind "kpi".” | `save_dashboard` |
| `charts/line` | “chartType "line" for a trend over time or another ordered axis; one line per measure or per series value, a second axis, target lines.” | `render_chart` or `save_dashboard` |
| `charts/pie` | “chartType "pie" for shares of one whole; one category column and one measure, a few slices.” | `render_chart` or `save_dashboard` |
| `charts/scatter` | “chartType "scatter" plots one measure against another, one point per row; encode.size makes a bubble chart.” | `render_chart` or `save_dashboard` |
| `charts/styling` | “Series colours, dashed or dotted lines, markers, highlighting one series against grey, the legend.” | `render_chart` or `save_dashboard` |
| `charts/table` | “chartType "table" shows the rows as a sortable table, with column labels and formats from fields.” | `render_chart` or `save_dashboard` |
| `charts/waterfall` | “chartType "waterfall" for a running total built from signed changes, e.g. a bridge from opening to closing.” | `render_chart` or `save_dashboard` |
| `connect-a-database` | “A link to the add-a-data-source form, filled with the user's connection details, and checking it connected.” | `explore_schema` |
| `context/descriptions` | “Writing a table or column description with edit_draft set_description, clearing your team's description, and hiding a table with set_visible.” | `edit_draft` |
| `context/joins` | “Adding and removing joins between tables with edit_draft add_join and remove_join.” | `edit_draft` |
| `context/keys-and-time` | “Setting a table's key and its time column with edit_draft set_key and set_time_column.” | `edit_draft` |
| `context/metrics` | “Creating, updating and removing defined metrics with edit_draft create_metric, update_metric and remove_metric.” | `edit_draft` |
| `context/publishing` | “Publishing the context draft as a new version with publish_draft, and what to do when publishing from an AI client is off.” | `publish_draft` |
| `context/runbook` | “How to improve this data source's context from an AI client: find the gaps, check against the data, edit the draft, review, publish.” | `get_versions` |
| `dashboards/params` | “Dashboard params: fields, optional [[ ]] filters with All, required, latest by default, the chosen value in titles.” | `save_dashboard` |
| `getting-started` | “A first session for a new user: what Bonnard is, adding data, a first question, chart and dashboard.” | `explore_schema` |