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

# Maintenance

> Create, update, and maintain knowledge base documents

Use `/knowledge` to create and edit documents. The agent structures content consistently, validates SQL, and adds wiki links between related documents. You can also edit documents directly in the knowledge base UI.

<Note>
  `/knowledge` requires the Developer role. Explorers can use the analytics agent but cannot modify the knowledge base.
</Note>

## Creating documents

**Document a table:**

```text theme={null}
/knowledge Document the sales.orders table.
Revenue = total_amount where status = 'completed'. Always exclude test accounts.
```

The agent creates a document at `sales/table/orders` with schema, relationships, common filters, and usage notes.

**Create a metric:**

```text theme={null}
/knowledge Create a metric for MRR.
MRR = sum of monthly subscription prices for active subscriptions.
Exclude trial and test customers.
```

The agent creates a document at `finance/metric/mrr` with the business definition, tested SQL, source tables, and filters.

**Create a business rule:**

```text theme={null}
/knowledge Document the rule for excluding test data.
Test accounts have is_test_account = TRUE or email ending in @company.com.
```

**Create a note:**

```text theme={null}
/knowledge Create an overview note for the sales namespace.
Covers order transactions, customer relationships, and revenue tracking.
```

## Providing better context

The more context you give, the better the documentation. Compare:

```text theme={null}
/knowledge Document the orders table
```

vs:

```text theme={null}
/knowledge Document the sales.orders table.
Key columns: order_id, customer_id, total_amount, status, order_date.
Revenue = total_amount where status = 'completed'.
Join to customers on customer_id. Exclude test orders where customer.is_test = true.
```

## Letting Delphina investigate

You don't have to hand the agent a complete definition — ask it to investigate. In a `/knowledge` chat the agent can query your warehouse, mine your query history for how your analysts actually compute things, read uploaded source files under `raw/`, and check documents pulled in from MCP connections, then ground the new documentation in that evidence:

```text theme={null}
/knowledge Create a new metric called revenue_by_platform.
Investigate how our Looker dashboards compute it in the query history,
and check the dashboard definitions uploaded under [[raw/other/looker/]].
```

Point it at whatever you know: the tables to look at, the users or dashboards whose SQL to trust, the uploaded files to read. The agent reports what it found — the dominant SQL pattern, conflicting definitions across dashboards, edge-case filters — for you to confirm before anything is documented, and validates the final SQL against your warehouse.

This works for updates too:

```text theme={null}
/knowledge Our finance team says the MRR number looks off. Investigate how
MRR is queried in practice — check the query history and our dbt repo from
the GitHub connection — and reconcile it with the documented metric.
```

## Automating maintenance with workflows

The same investigation can run on a schedule. Create a [workflow](/analytics-agent/workflows) in **Knowledge** mode and give it a recurring maintenance job. Two patterns work well:

**Find gaps from real usage** — periodically compare what people actually ask in chats against what the knowledge base covers:

```text theme={null}
Are there gaps in our knowledge base based on what people are actually asking?
Look at chat history for this workspace over the last 7 days and compare it
against what's documented — tables, metrics, rules, business logic.

Group the questions into themes. For each theme, is the agent answering from
documented knowledge, or guessing because nothing is there? Flag questions
that come up repeatedly and get vague or inconsistent answers.

For each real gap — one that recurs and hurts answer quality — create an
issue describing it, with a couple of example chats, unless one is already
open. Assign it to whoever owns that domain.
```

Turns the [critic agent](/analytics-agent/critic) flagged for missing context are ready-made candidates for this review — the workflow can start from them instead of scanning every chat.

**Keep documentation in sync with sources** — check whether the configured knowledge sources changed and propose updates:

```text theme={null}
Check changes to our knowledge sources within the past day and update the
knowledge base accordingly. If you hit a problem you can't resolve, create
an issue and assign it to the knowledge base owner.
```

Start with a modest cadence, e.g. weekly, and let the workflow deliver its findings as issues or a Slack summary rather than acting silently.

## Namespace structure

Documents are organized hierarchically: `{domain}/table/{name}`, `{domain}/metric/{name}`, `{domain}/rule/{name}`, `{domain}/note/{name}`. Documents reference each other with wiki links like `[[sales/table/orders]]`.

## Keeping documentation current

**Schema changes** — when tables are renamed or columns change:

```text theme={null}
/knowledge The orders table was renamed to sales_orders. Update all documents.
```

**Fix incorrect SQL:**

```text theme={null}
/knowledge The MRR metric should exclude churned subscriptions.
Update the SQL to filter where status != 'churned'.
```

**Update business definitions:**

```text theme={null}
/knowledge Enterprise is now ARR >= \$50k (changed from \$100k). Update all metrics.
```

**Validate periodically:**

```text theme={null}
/knowledge Validate all metric SQL queries and fix any errors
```

```text theme={null}
/knowledge Check all wiki links and report any broken references
```

**Add new documentation** as your data grows:

```text theme={null}
/knowledge Document the new marketing.campaigns and marketing.ad_spend tables
```

For larger additions, configure new sources at **Context Layer > Sources**, then start a knowledge update from chat:

```text theme={null}
/knowledge Plan knowledge updates
```

The agent detects what changed, proposes a plan, and builds the documentation in a guided session. See the [Onboarding guide](/knowledge-agent/onboarding).

Whichever path you take, the agent shows you what it plans to write before it writes it, and every edit is versioned so you can see what changed and roll it back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.