# Knowledge sources

> Confluence, Figma, Notion and Google Drive as context for answers: read tools, requests on a page and on a mock-up, scope, parameters instead of pictures.

A tracker gives the bot the **task**, a repository gives the **code**, and a knowledge source gives what is in
neither: **the team’s written and visual context**. Requirements, architectural
decisions, policies, runbooks — and mock-ups: how a screen should look, which tokens it is
built from, how its auto layout behaves. A person does not retell this in a question — they
assume you already know.

The catalogue has five such sources (Notion, Google Drive and files on disk have their own pages:
[Notion](/en/docs/connector/notion), [Google Drive](/en/docs/connector/google-drive),
[Files on disk](/en/docs/connector/files) — because their events, scope and sign-in
work differently):

| Source | What it gives the model | Where it takes questions |
|---|---|---|
| [Confluence](/en/marketplace/confluence) | pages of the spaces in the connection’s scope — as text | page comments |
| [Figma](/en/marketplace/figma) | the structure, parameters and tokens of mock-ups in the connection’s scope; the picture — only to a model that can see | mock-up comments |
| [Notion](/en/marketplace/notion) | pages as markdown and database records — as text; the research result — as a child page | page comments |
| [Google Drive](/en/marketplace/google-drive) | documents as markdown, spreadsheets — by sheet, presentations — as text; the research result — as a new document in the folder | comments on a document, spreadsheet or presentation |
| [Files on disk](/en/marketplace/files) | folders on a server and SMB network folders: Word, Excel, PowerPoint (2007+ and 97–2003), PDF and text files — with the glob, grep and read tools | nowhere: a folder has no comments, questions are asked in Buff |

One more source is what the team does not have: [the web](/en/docs/connector/web). It has its own
page, because there the model names the addresses and the administrator sets the boundaries.

## How it works

The model **decides itself** when to look into a source, and does it with tools. Nothing is
copied to us in advance or indexed: only what was needed for a
particular answer is read. This is a decision, not a limitation — the knowledge base and mock-ups stay in your
perimeter, and you are billed for what was actually read.

Addressing the bot from a page or a mock-up is optional. As soon as the connection’s “Development project” field
holds the name of your project (or [space](/en/docs/quickstart/space)), the model
sees its tools in every “Ask” question and every deep research of that
project — including those asked from the app, next to the code. The development stages of tasks
do not get the connection’s tools.

### Confluence

| Tool | What it does |
|---|---|
| `search_pages` | searches the spaces in the connection’s scope — titles, excerpts, addresses |
| `get_page` | reads a whole page, together with its discussion |
| `get_page_children` | lists the child pages of a section |

**A page arrives as text, not markup.** Confluence stores it as markup with
macros, tables and embeds; the integration turns it into readable text, keeping
headings, lists, tables, code and link addresses. Nothing is truncated along the way:
a truncated policy is a silently lost requirement.

_Illustration: A question whose answer is written down only in the wiki: the model went to the page with a tool and answered from it._

### Figma

| Tool | What it does |
|---|---|
| `list_files` | lists the connected mock-ups — key, name, project; if the lists are empty — only those where the bot was mentioned since the connector’s last start (the webhook reported them), and another file is opened from a link to it |
| `get_file` | the file structure: pages, frames, sizes, styles and components — down to a given depth |
| `get_node` | a node with its subtree and parameters: position and size, auto layout, fills and strokes in hex, corner radii, effects, typography and text, styles and variables **by name**, an instance’s component and its properties |
| `get_styles` | design tokens: published styles with values, the file’s styles, variables by mode — where the Figma plan allows reading them |
| `search_nodes` | searching nodes by words in the layer name or in the text |
| `get_comments` | the mock-up’s discussions: threads, which node they are pinned to, whether they are resolved |
| `render_node` | render a node to PNG — **only for a model that reads images** |

**A mock-up arrives as parameters, like the inspector panel.** A node in Figma refers to styles and
variables by identifiers — the integration turns them into names (“Button/Malachite”,
“Colour/Accent”), because the name is in the design system documentation and nobody reads the identifier.
Colours come in hex, paddings and gaps as numbers, fonts as family, style,
size and line height. Nothing is truncated: a frame with forty layers has forty layers in the answer.

<Callout type="warn">
**Not every model can see pictures.** Most models Buff runs on read
only text. So the integration is built around parameters: everything listed above, except
`render_node`, works with any model. The only tool with a picture is marked in
the catalogue with an “image” label, and the platform offers it only to a model that reads
images — based on the model’s description (at the provider or on the dedicated machine), without manual setup. A text model does not
see it at all, so a model that cannot look will never get
an image it would “read” at random. At the moment only “Ask” gets the picture;
deep research works from the mock-up’s parameters.
</Callout>

_Illustration: A question about a button style: the model found the node, read its parameters and named the style — without a single picture._

## Requests on a page and on a mock-up

Everything described in [“Tracker integrations”](/en/docs/connector/trackers) works
here too: a mention of the bot or a slash command in a comment is a question, a research or
a task draft, and the answer arrives as a comment in the same discussion. There is one difference: a page
and a mock-up have no code branch, so the answer is computed at the level of the development project — or
[space](/en/docs/quickstart/space) — the connection is bound to.

In Figma **the thread is the root comment** pinned to a spot on the mock-up. A question in a reply to
it continues the same conversation, and the bot’s answer arrives in the same thread.

## Visibility scope

The connection has a list of where the bot works. If the list is set, it works both
ways: outside it the bot reads neither pages and mock-ups nor requests, and writes no answers. What an empty list means is below.

| Source | What goes in the list | Where to find it |
|---|---|---|
| Confluence | space keys (`DOC`, `OPS`) | in the page address: `/spaces/DOC/pages/…` |
| Figma | file keys and/or project numbers | the key — in the file address `figma.com/design/KEY/…`; the project number — in the project address `figma.com/files/project/NUMBER/…` |

<Callout type="warn">
An empty list for Confluence and Figma means **“everything open to the bot’s account”** — as
for [Notion](/en/docs/connector/notion#scope) and [Google Drive](/en/docs/connector/google-drive#scope):
the permissions in the system itself have already drawn the boundary. An empty list means “nowhere” only for
[trackers](/en/docs/connector/trackers). The bot account’s permissions in the external system are the outer
boundary, the list is the inner one; it is sensible to have both.

Figma without a list has caveats: its API cannot list all of an account’s files.
If you ask in the app, attach a link to the mock-up: the bot cannot find a file by its name
by itself. The bot learns about a question in a comment only from the `FILE_COMMENT` webhook and only in the
files the webhook is set up for (see [“Events”](#events)). For this the connector’s event receiver
must be reachable from the internet. Without the webhook, questions in mock-up comments
do not reach the bot.
</Callout>

## Setup

### Confluence

| Field | Value |
|---|---|
| Address | `https://wiki.corp.local` for Data Center and Server, `https://your-company.atlassian.net/wiki` for Cloud — **including `/wiki`**, otherwise the integration knocks on the wrong door |
| Credentials | the bot account’s token; for Cloud — **email and API token** (the account is entered next to the secret) |
| Spaces | `DOC, OPS` — keys, not names; empty — all spaces open to the bot’s account |
| Alias | a short name for the bot, for example `buff`. In Cloud accounts have no login, so it is especially handy there |

The connectivity check answers not with “ok” but with the Confluence version, the account it
signed in with, and **how many of the selected spaces are actually available**. If the list is empty,
the check says so: the scope is all spaces open to the account.

### Figma

| Field | Value |
|---|---|
| API address | prefilled: `https://api.figma.com` — no need to change it |
| Image delivery address | prefilled: the storage Figma serves rendered images from — no need to change it |
| Credentials | the bot account’s personal access token (Figma accepts it in its own header) |
| Files, projects | file keys and/or project numbers — one of the lists or both. Both empty — any file open to the bot’s account, but questions from comments then arrive only via the webhook (see “Events”) |
| Alias | a short name for the bot, for example `buff` |

The connectivity check says who signed in, how many files are in scope and how many of them are available
(without lists — that the scope is all of the account’s files), and
**whether variables can be read on this Figma plan**: the API returns variables (Variables) only to
Enterprise plans; for the others the integration takes tokens from published styles and node
bindings — and says so plainly, rather than with an empty list.

From the command line: `connector install figma`, then
`connector instance add figma --config projects=4815162342` — the API address is filled in by itself.

## Events

**Polling always works**: the integration reads the comments of the selected spaces or
files — every 20 seconds by default; the interval is changed in the connection settings.
No ports need to be opened — except for Figma without a list of files and projects, see below.
For Confluence without a list, polling reads all spaces open to the account.

The Confluence webhook **is not parsed for content; it simply wakes up polling**: we have not checked
the payload against a live server. This takes nothing away from its usefulness: the answer comes right away rather than
on the next pass.

The Figma webhook **is delivered to the integration**: the file and the comment number are taken from the `FILE_COMMENT` event,
and the comment itself and its thread are read through the API — the event does not say which
thread the reply was written in. With a list of files or projects the webhook speeds up the answer, and polling
picks up lost calls. **Without a list the webhook is mandatory**: only it tells which
file the bot was mentioned in, and the connector’s event receiver must then be reachable from the
internet — Figma calls it from its cloud. The bot answers mentions only in
files the webhook is set up for. Polling then rereads the files where the bot was mentioned since
the connector’s last start. A Figma
webhook is created through its API (`POST /v2/webhooks`, the `FILE_COMMENT` event) for a team,
a project or a file and points to the link issued by the connector; a webhook for a team covers
all of its files.

## What the integrations do not do

- **They do not create or edit** pages and mock-ups. Publishing a result means writing into
  your system, and that needs to be limited separately; the result comes back as a comment and
  a link.
- **They do not touch labels, permissions, libraries or attachments** — except for the research document,
  which is attached to the Confluence page if research is exactly what was asked for.
  A file cannot be attached to a Figma comment — it is available via a link, and the answer says so.
- **They do not go beyond the connection’s scope** — the selected spaces, files and projects, and without
  a list — what is open to the bot’s account.
- **They do not show a picture to a text model** — see above.